subtractUtc

Signature

subtractUtc(value: string, units: Partial<Record<DateTimeDurationUnit, number>>, options?: { overflow?: Overflow; }): string

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

Subtract a temporal amount from a UTC datetime string and return a new UTC Instant string.

• Uses Temporal.Instant.from to parse, subtracts duration, returns new Instant.
• Validates duration units and values.
• Returns “” for invalid input. overflow (“constrain” (default) | “reject”) controls out-of-range results, e.g. subtracting 1 month from Mar 31: “constrain” clamps to Feb 29/28, “reject” throws (resulting in “”).

Parameters

Parameter	Type	Description
value	string	ISO UTC datetime string (e.g. “2024-03-10T12:00:00Z”)
units	Partial&lt;Record&lt;DateTimeDurationUnit, number&gt;&gt;	Partial<Record<DateTimeDurationUnit, number>> object specifying units to subtract

Options

options

Option	Type	Default
overflow?	Overflow	—

Returns

UTC Instant string after subtraction, or “” on invalid input

Related types

• DurationUnit
• DateTimeDurationUnit
• Overflow
• TimeDurationUnit

Examples

subtractUtc("2024-03-15T12:00:00Z", { days: 5 }) // "2024-03-10T12:00:00Z"
subtractUtc("2024-03-15T12:00:00Z", { months: 1, years: 1 }) // "2023-02-15T12:00:00Z"
subtractUtc("invalid", { days: 5 }) // ""

Source

utc/calculate/subtractUtc.ts