setZoned

Signature

setZoned(value: string, fields: Omit<ZonedDateTimeLike, "calendar" | "era" | "eraYear" | "offset" | "timeZone">, options?: { overflow?: "reject" | "constrain" | undefined; disambiguation?: "compatible" | "earlier" | "later" | "reject" | undefined; offset?: "reject" | "use" | "prefer" | "ignore" | undefined; }): string

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 and/or nanosecond; omitted fields keep their current value. An object with no field set, such as {} or { year: undefined }, is a no-op.
• Values are not converted: monthCode must be a string and every other field an integer number. null, a numeric string, a boolean or a fraction returns "", where Temporal would convert or truncate it. A bigint, NaN or an infinity returns "" too. A number too large for its field follows overflow. A month or day below 1, or a date outside Temporal’s range, returns "".
• An own key that is not one of these fields, such as a misspelt yaer, returns "". So does an era, an offset, or a calendar or timeZone property, whether own, inherited or a getter. A field is read with a property get, as Temporal reads it, so an inherited or getter field is set.
• A Temporal date or time object returns "", as Temporal’s with refuses one. One whose prototype has been replaced with Object.prototype, null or Function.prototype sets nothing instead.
• 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.
• Compatibility: before 1.16.0 offset defaulted to "ignore". Pass { offset: "ignore" } to keep that resolution.
• Returns "" for invalid input.

Parameters

Parameter	Type	Description
value	string	zoned ISO 8601 datetime string
fields	Omit<ZonedDateTimeLike, "calendar" | "era" | "eraYear" | "offset" | "timeZone">	Partial<Temporal.ZonedDateTimeLike> object (excluding calendar/timeZone/offset) specifying fields to set

Options

options

optional settings for resolving an out-of-range date and the new wall-clock time

Option	Type	Default	Description
overflow?	"reject" | "constrain" (Overflow)	"constrain", Temporal’s default.	What happens when the result names a day its month does not have, such as setting month: 2 on 31 January. "constrain" clamps to the last valid day; "reject" returns "".
disambiguation?	"compatible" | "earlier" | "later" | "reject" (Disambiguation)	"compatible", Temporal’s default.	How the new wall-clock time resolves when it falls in a DST gap or overlap and offset does not settle it. In a fall-back overlap "compatible" and "earlier" take the earlier instant and "later" the later one; in a spring-forward gap "compatible" and "later" move the wall clock forward by the gap length and "earlier" back by it. "reject" returns "" for both.
offset?	"reject" | "use" | "prefer" | "ignore" (Offset)	"prefer", Temporal’s default.	How the source’s UTC offset is treated at the new wall-clock time, as in Temporal’s ZonedDateTime#with. "prefer" keeps it while it is still valid there (a repeated fall-back hour) and otherwise resolves through disambiguation; "ignore" always resolves through disambiguation. "use" keeps the offset even when that moves the wall clock, and "reject" returns "" when the offset is not valid for the new wall time.

Returns

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

Related types

• Overflow
• Disambiguation
• Offset

Examples

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

setZoned("2024-03-10T12:00:00-04:00[America/New_York]", { hour: 9 }) // "2024-03-10T09:00:00-04:00[America/New_York]"

value

output

 

Source

zoned/calculate/setZoned.ts