endOfZoned

Signature

endOfZoned(value: string, unit: SmallestUnit<DateTimeUnit>, optionsArg?: { weekStartsOn?: "monday" | "sunday"; fractionalSecondDigits?: FractionalDigit; }): string

Return the end of the specified date-time unit for a given zoned ISO 8601 datetime string.

• Supports: “year”, “month”, “week”, “day”, “hour”, “minute”, “second”, “millisecond”, “microsecond”, “nanosecond”, each also in its plural form ("days"), as Temporal accepts.
• Returns the last instant of the real local unit containing value in its own zone — one nanosecond before the next bucket floorToZone would return — so the result is never before value. The second pass of New York’s repeated fall-back hour ends at 01:59:59.999999999 −05:00, and Australia/Lord_Howe’s 90-minute fall-back hour ends in its new offset.
• A transition that reopens the previous local date makes that stretch its own bucket: America/Goose_Bay’s 00:01 fall-back on 7 November 2010 re-entered 6 November for 59 minutes, so the day holding 2010-11-06T23:30:00-04:00 ends at 23:59:59.999999999 −04:00.
• A midnight repeated on the same date stays one day: America/Havana’s 25-hour 2024-11-03 ends at 23:59:59.999999999 −05:00 from either pass of its repeated first hour.
• Takes no disambiguation or offset: a boundary is always a real instant, as TC39’s startOfDay() takes neither. Those ignored options were removed in 1.16.0.
• The end is written at nanosecond precision by default, so the string names the end itself.
• Returns "" for invalid input.
• Compatibility: before 1.16.0 the default printed only the digits the unit names — none for second and coarser, 3 for millisecond, 6 for microsecond — which wrote a moment earlier than the end. Pass that fractionalSecondDigits to keep the previous string.

Parameters

Parameter	Type	Description
value	string	zoned ISO 8601 datetime string
unit	SmallestUnit<DateTimeUnit>	date or time unit, singular or plural, to specify the unit for the end

Options

optionsArg

optional settings for the week’s first day and the precision of the output string

Option	Type	Default	Description
weekStartsOn?	"monday" | "sunday"	"monday"	The first day of the week, which sets where a "week" unit starts. "monday" is the ISO 8601 week, Monday to Sunday; "sunday" runs Sunday to Saturday. Any other value returns "", whatever the unit.
fractionalSecondDigits?	0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | "auto" | 8 | 9 (FractionalDigit)	9	The number of fractional-second digits the result is written with, 0 to 9, or "auto" to drop trailing zeros. Fewer than 9 digits truncate the string, as Temporal’s toString does, so it names a moment before the end.

Returns

zoned ISO 8601 string representing the end of the specified unit, or "" on invalid input

Related types

• DateTimeUnit
• FractionalDigit

Examples

import { endOfZoned } from "@northguild/gmt/zoned/calculate";

endOfZoned("2024-02-29T12:34:56+00:00[UTC]", "month") // "2024-02-29T23:59:59.999999999+00:00[UTC]"

value

output

 

Source

zoned/calculate/endOfZoned.ts