setZoned

Signature

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

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

Return a zoned ISO 8601 datetime string with the given fields set on value.

• Wraps Temporal.ZonedDateTime.prototype.with(), which resolves every supplied field in a single atomic overflow pass. This is the safe alternative to composing addZoned() calls field-by-field, and it is the only construction path that can reproduce startOfZoned’s disambiguation-plus-offset handling — addZoned() has no offset control equivalent to .with()’s, because Temporal’s ZonedDateTime.prototype.add() doesn’t accept disambiguation/offset at all.
• 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. calendar, timeZone, and offset are deliberately excluded from fields — this function only sets date/time components, never the zone or calendar identity, and offset is controlled separately via options.offset.
• 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 “”).
• Returns “” for invalid input.

Parameters

Parameter	Type	Description
value	string	zoned ISO 8601 datetime string
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
overflow?	Overflow	—
disambiguation?	Disambiguation	—
offset?	Offset	—

Returns

zoned ISO 8601 string with fields set, or “” on invalid input

Related types

• Disambiguation
• Offset
• Overflow

Examples

setZoned("2024-03-10T12:00:00-04:00[America/New_York]", { hour: 9 }) // "2024-03-10T09:00:00-04:00[America/New_York]"
setZoned("2024-01-31T12:00:00-05:00[America/New_York]", { month: 2 }) // "2024-02-29T12:00:00-05:00[America/New_York]" (constrain clamps to the last valid day)
setZoned("2024-01-31T12:00:00-05:00[America/New_York]", { month: 2 }, { overflow: "reject" }) // ""
setZoned("2024-03-10T12:00:00-04:00[America/New_York]", {}) // "2024-03-10T12:00:00-04:00[America/New_York]" (empty fields object is a no-op)
setZoned("2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject" }) // "" (offset defaults to "ignore", so disambiguation actually fires and "reject" throws on this fall-back overlap)
setZoned("2024-11-03T01:45:00-05:00[America/New_York]", { minute: 0 }, { disambiguation: "reject", offset: "prefer" }) // "2024-11-03T01:00:00-05:00[America/New_York]" (offset:"prefer" makes disambiguation inert here — the source's -05:00 offset is still valid, so it's kept and "reject" never fires)
setZoned("invalid", { hour: 9 }) // ""

Source

zoned/calculate/setZoned.ts