startOfUnix

Signature

startOfUnix(value: string | number, unit: DateTimeUnit | PluralUnit<DateTimeUnit>, options?: { epochUnit?: UnixUnit; timeZone?: string; weekStartsOn?: "monday" | "sunday"; }): number | null

Return the start of the specified unit for a Unix timestamp.

• Converts to ZonedDateTime, finds the start of the unit, converts back to epoch.
• Supports: “year”, “month”, “week”, “day”, “hour”, “minute”, “second”, “millisecond”, “microsecond”, “nanosecond”, singular or plural. For quarters use startOfQuarterForUnix / endOfQuarterForUnix; "quarter" returns null.
• Returns the real start of the local unit containing value in timeZone — the same bucket floorToZone uses — so the result is never after value: the second pass of a repeated fall-back hour starts at its own 1am, and Pacific/Chatham’s 15-minute spring-forward hour starts at 03:45.
• 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.
• Returns null for invalid input.
• value is a safe integer or a digit string ("1706659200000"); anything else returns null.
• Limit at an offset with seconds. The instant is placed in the offset’s whole-minute zone, moved by its seconds, and the moved instant must be inside Temporal’s range. So within the offset’s seconds (under a minute) of the last instant Temporal supports (+275760-09-13T00:00:00Z) for an offset east of UTC, or of the first (-271821-04-20T00:00:00Z) for one west, this returns null. An offset to the minute has no such limit.

Parameters

Parameter	Type	Description
value	string | number	Unix epoch: a safe integer, or a string of optionally negative ASCII digits
unit	DateTimeUnit | PluralUnit<DateTimeUnit>	Temporal.DateUnit | Temporal.TimeUnit to specify the start

Options

options

optional: how value is read, the zone the unit is found in and the first day of the week

Option	Type	Default	Description
epochUnit?	"seconds" | "milliseconds" | "second" | "millisecond" (UnixUnit)	"milliseconds"	The unit the epoch values are counted in: "seconds" or "milliseconds", singular or plural. Any other value returns null. The result is in the same unit.
timeZone?	string	"UTC"	The time zone the unit boundaries are found in: an IANA name, a UTC offset (a time zone identifier such as +05:30, +0530 or -08, or a stored offset ±HH:MM[:SS], what getTimeZoneOffset returns), or "local" for the system time zone. An unknown zone returns null.
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 null, whatever the unit.

Returns

Unix epoch number representing the start of the unit, or null on invalid input

Related types

• UnixUnit

Examples

import { startOfUnix } from "@northguild/gmt/unix/calculate";

startOfUnix(1706659200000, "year", { timeZone: "UTC" }) // 1704067200000

value

output

 

Source

unix/calculate/startOfUnix.ts