setUnix

Signature

setUnix(value: number, fields: Omit<Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset">, options?: { epochUnit?: "seconds" | "milliseconds"; timeZone?: string; overflow?: Overflow; disambiguation?: Disambiguation; offset?: Offset; }): number

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

Return a Unix epoch value with the given fields set on value, interpreted in timeZone.

• Converts to ZonedDateTime, wraps Temporal.ZonedDateTime.prototype.with() (resolving every supplied field in a single atomic overflow pass), then converts back to epoch. This is the safe alternative to composing addUnix() calls field-by-field — see setZoned’s doc for why order-independent field resolution matters, and why disambiguation/offset require .with() rather than arithmetic.
• fields may set any of year, month, monthCode, day, hour, minute, second, millisecond, microsecond, nanosecond, era, and/or eraYear; omitted fields keep their current value. An empty object is a no-op.
• overflow (“constrain” (default) | “reject”) controls out-of-range results, e.g. setting month: 2 on a value whose day is 31: “constrain” clamps to Feb 29/28, “reject” throws (resulting in null).
• Returns null for invalid input.

Parameters

Parameter	Type	Description
value	number	Unix timestamp (number)
fields	Omit&lt;Temporal.ZonedDateTimeLike, "calendar" | "timeZone" | "offset"&gt;	Partial<Temporal.ZonedDateTimeLike> object (excluding calendar/timeZone/offset) specifying fields to set

Options

options

Option	Type	Default
epochUnit?	"seconds" | "milliseconds"	—
timeZone?	string	—
overflow?	Overflow	—
disambiguation?	Disambiguation	—
offset?	Offset	—

Returns

Unix epoch number with fields set, or null on invalid input

Related types

• Disambiguation
• Offset
• Overflow

Examples

setUnix(1710072000000, { hour: 9 }, { timeZone: "UTC" }) // 1710061200000 (2024-03-10T09:00:00Z)
setUnix(1706659200000, { year: 2025 }, { timeZone: "UTC" }) // 1738281600000 (2025-01-31T00:00:00Z)
setUnix(1706659200000, {}, { timeZone: "UTC" }) // 1706659200000 (empty fields object is a no-op)
setUnix(NaN, { hour: 9 }) // null

Source

unix/calculate/setUnix.ts