setUtc

Signature

setUtc(value: string, fields: Omit<ZonedDateTimeLike, "calendar" | "era" | "eraYear" | "offset" | "timeZone">, options?: { overflow?: "reject" | "constrain" | undefined; }): string

Return a UTC Instant string with the given fields set on value.

• Converts to ZonedDateTime (fixed timeZone “UTC”), wraps Temporal.ZonedDateTime.prototype.with() (resolving every supplied field in a single atomic overflow pass), then converts back to an Instant. This is the safe alternative to composing addUtc() calls field-by-field — see setDate’s doc for why order-independent field resolution matters.
• 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.
• There are no disambiguation or offset options (removed in 1.16.0): a UTC instant’s wall clock is never ambiguous and its offset is always +00:00, so neither had anything to act on.
• Returns "" for invalid input.

Parameters

Parameter	Type	Description
value	string	ISO UTC datetime string (e.g. “2024-03-10T12:00:00Z”)
fields	Omit<ZonedDateTimeLike, "calendar" | "era" | "eraYear" | "offset" | "timeZone">	Partial<Temporal.ZonedDateTimeLike> object (excluding calendar/timeZone/offset) specifying fields to set

Options

options

How an out-of-range result is handled

Option	Type	Default	Description
overflow?	"reject" | "constrain" (Overflow)	"constrain", Temporal’s default.	What to do when the result is not a real date. "constrain" clamps it to the last valid day, so month: 2 on Jan 31 is Feb 29/28 (TC39 Temporal); "reject" returns "".

Returns

UTC Instant string with fields set, or "" on invalid input

Related types

• Overflow

Examples

import { setUtc } from "@northguild/gmt/utc/calculate";

setUtc("2024-03-10T12:00:00Z", { hour: 9 }) // "2024-03-10T09:00:00Z"

value

output

 

Source

utc/calculate/setUtc.ts