subtractUtc
Signature
Section titled “Signature”subtractUtc(value: string, units: Partial<Record<keyof DurationLike, number>>, options?: { overflow?: "reject" | "constrain" | undefined; }): stringSubtract 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.
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
value | string | ISO UTC datetime string (e.g. “2024-03-10T12:00:00Z”) |
units | Partial<Record<keyof DurationLike, number>> | Partial<Record<DateTimeDurationUnit, number>> object specifying units to subtract |
Options
Section titled “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 Mar 31 − 1 month is Feb 29/28 (TC39 Temporal); "reject" returns "". |
Returns
Section titled “Returns”UTC Instant string after subtraction, or "" on invalid input
Related types
Section titled “Related types”Examples
Section titled “Examples”import { subtractUtc } from "@northguild/gmt/utc/calculate";
subtractUtc("2024-03-15T12:00:00Z", { days: 5 }) // "2024-03-10T12:00:00Z"