endOfUtc

Signature

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

Return the end of the specified date-time unit for a given UTC datetime string.

• Converts to ZonedDateTime, sets to end of unit, converts back to Instant.
• Supports: “year”, “month”, “week”, “day”, “hour”, “minute”, “second”, “millisecond”, “microsecond”, “nanosecond”, each also in its plural form ("days"), as Temporal accepts.
• The end is the last nanosecond of the unit, one nanosecond before the next unit starts.
• 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	ISO UTC datetime string
unit	SmallestUnit<DateTimeUnit>	date or time unit, singular or plural, to specify the end

Options

options

Where a week starts, and the precision of the result

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

UTC Instant string representing the end of the unit, or "" on invalid input

Related types

• FractionalDigit

Examples

import { endOfUtc } from "@northguild/gmt/utc/calculate";

endOfUtc("2024-03-15T14:30:45Z", "year") // "2024-12-31T23:59:59.999999999Z"

value

output

 

Source

utc/calculate/endOfUtc.ts