startOfUtc
Signature
Section titled “Signature”startOfUtc(value: string, unit: SmallestUnit<DateTimeUnit>, options?: { weekStartsOn?: "monday" | "sunday"; fractionalSecondDigits?: FractionalDigit; }): stringReturn the start of the specified date-time unit for a given UTC datetime string.
- Converts to ZonedDateTime, sets to start 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. - Returns "" for invalid input.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
value | string | ISO UTC datetime string |
unit | SmallestUnit<DateTimeUnit> | date or time unit, singular or plural, to specify the start |
Options
Section titled “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) | The digits unit names: 3 for "millisecond", 6 for "microsecond", 9 for "nanosecond" and 0 for any coarser unit. | The number of fractional-second digits the result is written with, 0 to 9, or "auto" to drop trailing zeros. Fewer digits than unit names truncate, as Temporal’s toString does. |
Returns
Section titled “Returns”UTC Instant string representing the start of the unit, or "" on invalid input
Related types
Section titled “Related types”Examples
Section titled “Examples”import { startOfUtc } from "@northguild/gmt/utc/calculate";
startOfUtc("2024-03-15T14:30:45Z", "year") // "2024-01-01T00:00:00Z"