@northguild/gmt 1.18.0 → 1.19.0

package/dist/internal/readDurationUnits.js

@@ -0,0 +1,78 @@
+import { isObject } from "./isObject.js";
+import { isValidAmount } from "./isValidAmount.js";
+/**
+ * The ten fields TC39 Temporal reads from a duration-like object, in the order it reads them:
+ * ToTemporalPartialDurationRecord (7.5.18) gets them in alphabetical order.
+ */
+const DURATION_UNIT_NAMES = [
+    "days",
+    "hours",
+    "microseconds",
+    "milliseconds",
+    "minutes",
+    "months",
+    "nanoseconds",
+    "seconds",
+    "weeks",
+    "years",
+];
+/**
+ * Read a `units` argument, such as `{ minutes: 15 }`, the way Temporal reads a duration-like
+ * object, and return the amounts as a fresh plain object that holds only the caller's units.
+ *
+ * The check and the read are one pass, so nothing reaches Temporal that was not checked:
+ *
+ * - `units` must be an Object (`isObject`), a function included.
+ * - An own enumerable string key that `isAllowed` refuses returns `null`, whatever its value.
+ *   This is the guard against a misspelt key, which Temporal on its own ignores. A symbol key and
+ *   a non-enumerable key that is no unit name are not entries and are ignored.
+ * - Each of the ten unit names is read once with an ordinary property get, in the order Temporal's
+ *   ToTemporalPartialDurationRecord reads them, so an inherited or non-enumerable unit applies.
+ *   `undefined` means the unit is absent. Any other value must be a finite number; nothing is
+ *   converted to one.
+ * - A unit `isAllowed` refuses returns `null` when its amount is not zero. Zero is no amount:
+ *   Temporal too tells a calendar duration from an exact one by its nonzero fields.
+ * - No allowed unit present returns `null`.
+ *
+ * Whole numbers, one sign and the range are left to Temporal, which throws for each. A getter
+ * that throws is not caught here; the calling function's own catch returns its sentinel.
+ *
+ * @param units the caller's `units` argument
+ * @param isAllowed type guard for the units the calling function takes
+ * @returns a new plain object of the allowed units that were present, or null on invalid input
+ *
+ * @example readDurationUnits({ minutes: 15 }, isValidTimeDurationUnit) // { minutes: 15 }
+ * @example readDurationUnits({ minutes: 15, hours: undefined }, isValidTimeDurationUnit) // { minutes: 15 }
+ * @example readDurationUnits({ minutes: 15, hour: 1 }, isValidTimeDurationUnit) // null (unknown key)
+ * @example readDurationUnits(Object.create({ minutes: "15" }), isValidTimeDurationUnit) // null (not a number)
+ * @example readDurationUnits(Object.create({ days: 1 }), isValidTimeDurationUnit) // null (a unit outside the set)
+ * @example readDurationUnits({}, isValidTimeDurationUnit) // null
+ */
+export function readDurationUnits(units, isAllowed) {
+    if (!isObject(units)) {
+        return null;
+    }
+    if (!Object.keys(units).every((key) => isAllowed(key))) {
+        return null;
+    }
+    const record = units;
+    const read = {};
+    let present = false;
+    for (const name of DURATION_UNIT_NAMES) {
+        const amount = record[name];
+        if (amount === undefined) {
+            continue;
+        }
+        if (!isValidAmount(amount)) {
+            return null;
+        }
+        if (isAllowed(name)) {
+            read[name] = amount;
+            present = true;
+        }
+        else if (amount !== 0) {
+            return null;
+        }
+    }
+    return present ? read : null;
+}

package/dist/internal/readSetFields.d.ts

@@ -0,0 +1,50 @@
+/** The date fields `setDate` takes. */
+export declare const DATE_FIELDS: readonly ["year", "month", "monthCode", "day"];
+/** The time fields `setTime` takes. */
+export declare const TIME_FIELDS: readonly ["hour", "minute", "second", "millisecond", "microsecond", "nanosecond"];
+/** The fields `setDateTime`, `setUtc`, `setUnix` and `setZoned` take. */
+export declare const DATE_TIME_FIELDS: readonly ["year", "month", "monthCode", "day", "hour", "minute", "second", "millisecond", "microsecond", "nanosecond"];
+/** The one field whose value is a string; every other field a `set*` function takes is a number. */
+declare const STRING_FIELD = "monthCode";
+/** A field a `set*` function may take. */
+type SetField = (typeof DATE_TIME_FIELDS)[number];
+/** The checked values of the fields in `Field`: `monthCode` a string, every other an integer. */
+export type SetFields<Field extends SetField> = {
+    [Name in Field]?: Name extends typeof STRING_FIELD ? string : number;
+};
+/**
+ * Read the `fields` argument of a `set*` function the way Temporal's `with` reads it, and return
+ * the values as a fresh plain object that holds only the fields the function takes.
+ *
+ * The check and the read are one pass, so nothing reaches Temporal that was not checked:
+ *
+ * - `fields` must be an Object (`isObject`), a function included, and not a Temporal object that
+ *   holds a date or a time (TC39 IsPartialTemporalObject).
+ * - An own enumerable string key outside `allowedFields` returns `null`, whatever its value: the guard
+ *   against a misspelt key. A symbol key is ignored.
+ * - Each property `with` reads is read once with an ordinary property get, in the order `with`
+ *   reads them, so an inherited, non-enumerable or getter field applies. `undefined` means absent.
+ *   A defined property outside `allowedFields` (another type's field, an era, an offset, a
+ *   `calendar` or a `timeZone`) returns `null`.
+ * - A value is not converted: `monthCode` must be a string, and every other field a number that is
+ *   an integer. `null`, a numeric string, a boolean and a fraction return `null`, where Temporal
+ *   would convert or truncate them. A bigint, `NaN` and an infinity return `null` too; Temporal
+ *   throws for them (ToIntegerWithTruncation).
+ *
+ * Range and overflow are left to Temporal. An empty result means nothing is set: the function
+ * returns its value unchanged, where Temporal's `with` would throw. A getter that throws is not
+ * caught here, nor is a Proxy's `getPrototypeOf` trap that throws; the calling function's own catch
+ * returns its sentinel.
+ *
+ * @param fields the caller's `fields` argument
+ * @param allowedFields the fields the calling function takes
+ * @returns a new plain object of the fields set, empty when none is, or null on invalid input
+ *
+ * @example readSetFields({ year: 2025 }, DATE_FIELDS) // { year: 2025 }
+ * @example readSetFields({}, DATE_FIELDS) // {} (nothing set)
+ * @example readSetFields({ year: "2025" }, DATE_FIELDS) // null (not converted)
+ * @example readSetFields({ year: 2025, yaer: 1 }, DATE_FIELDS) // null (misspelt key)
+ * @example readSetFields({ year: 2025, hour: 5 }, DATE_FIELDS) // null (a field setDate does not take)
+ */
+export declare function readSetFields<Field extends SetField>(fields: unknown, allowedFields: readonly Field[]): SetFields<Field> | null;
+export {};

package/dist/internal/readSetFields.js

@@ -0,0 +1,179 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isObject } from "./isObject.js";
+/** The date fields `setDate` takes. */
+export const DATE_FIELDS = ["year", "month", "monthCode", "day"];
+/** The time fields `setTime` takes. */
+export const TIME_FIELDS = [
+    "hour",
+    "minute",
+    "second",
+    "millisecond",
+    "microsecond",
+    "nanosecond",
+];
+/** The fields `setDateTime`, `setUtc`, `setUnix` and `setZoned` take. */
+export const DATE_TIME_FIELDS = [...DATE_FIELDS, ...TIME_FIELDS];
+/**
+ * Every property TC39 Temporal's `with` methods read from their argument, in the order they read
+ * them: `calendar` and `timeZone` first, which IsPartialTemporalObject (13.24) refuses, then the
+ * date and time fields and the `offset` that `ZonedDateTime.prototype.with` reads, in code-unit
+ * order. PrepareCalendarFields (12.3.3) sorts them so for every `with` that takes a date, and
+ * ToTemporalTimeRecord (4.5.12), which `PlainTime.prototype.with` uses, reads its six fields in
+ * the same order. The list adds the era fields,
+ * which `with` never reads for the ISO 8601 calendar (CalendarExtraFields returns none) and which
+ * GMT reads only to refuse them.
+ */
+const WITH_PROPERTY_NAMES = [
+    "calendar",
+    "timeZone",
+    "day",
+    "era",
+    "eraYear",
+    "hour",
+    "microsecond",
+    "millisecond",
+    "minute",
+    "month",
+    "monthCode",
+    "nanosecond",
+    "offset",
+    "second",
+    "year",
+];
+/** The one field whose value is a string; every other field a `set*` function takes is a number. */
+const STRING_FIELD = "monthCode";
+/**
+ * For each Temporal class whose objects hold a date or a time (the internal slots TC39
+ * IsPartialTemporalObject tests), a getter that throws for any receiver without that slot.
+ */
+const BRANDED_GETTERS = [
+    ["PlainDate", "calendarId"],
+    ["PlainDateTime", "calendarId"],
+    ["PlainMonthDay", "calendarId"],
+    ["PlainYearMonth", "calendarId"],
+    ["ZonedDateTime", "calendarId"],
+    ["PlainTime", "hour"],
+];
+/** Whether `value` holds the internal slot of one class of `namespace`. */
+function isObjectOf(namespace, value) {
+    return BRANDED_GETTERS.some(([name, key]) => {
+        const prototype = namespace[name]?.prototype;
+        const getter = isObject(prototype)
+            ? Object.getOwnPropertyDescriptor(prototype, key)?.get
+            : undefined;
+        if (typeof getter !== "function") {
+            return false;
+        }
+        try {
+            getter.call(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/**
+ * Whether `value` is an object of the Temporal the host provides on `globalThis`, if any. A
+ * malformed host Temporal recognises nothing, so it never changes the result for a field object.
+ */
+function isHostTemporalObject(value) {
+    try {
+        const host = globalThis.Temporal;
+        return (isObject(host) &&
+            host !== Temporal &&
+            isObjectOf(host, value));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether `value` is a Temporal object that holds a date or a time, from the polyfill GMT uses or
+ * from a Temporal the host provides. The test is the one a class's own getter makes: it reads the
+ * internal slot, so neither the prototype chain nor any property of `value` decides it.
+ *
+ * The check calls up to six getters, twelve with a host Temporal, and a throwing getter is slow, so
+ * it is skipped when the prototype is `Object.prototype`, `null` or `Function.prototype`: a plain
+ * object, an `Object.create(null)` object or a function, which no Temporal class makes.
+ *
+ * Limits:
+ * - An object from a second copy of the polyfill that is not on `globalThis` is not detected and
+ *   is read as a field bag, which is also what TC39 IsPartialTemporalObject (13.24) does with an
+ *   object that lacks this polyfill's internal slots.
+ * - A Temporal object whose prototype was swapped to one of the three above is not detected
+ *   either. Its getters are then out of reach, so it reads as setting nothing and the function
+ *   returns its value unchanged (accepted by owner decision for the speed of the plain case).
+ */
+function isTemporalDateOrTimeObject(value) {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype === Object.prototype ||
+        prototype === null ||
+        prototype === Function.prototype) {
+        return false;
+    }
+    return (isObjectOf(Temporal, value) ||
+        isHostTemporalObject(value));
+}
+/** Whether `value` is one Temporal reads for `name` without converting it. */
+function isFieldValue(name, value) {
+    return name === STRING_FIELD
+        ? typeof value === "string"
+        : typeof value === "number" && Number.isInteger(value);
+}
+/**
+ * Read the `fields` argument of a `set*` function the way Temporal's `with` reads it, and return
+ * the values as a fresh plain object that holds only the fields the function takes.
+ *
+ * The check and the read are one pass, so nothing reaches Temporal that was not checked:
+ *
+ * - `fields` must be an Object (`isObject`), a function included, and not a Temporal object that
+ *   holds a date or a time (TC39 IsPartialTemporalObject).
+ * - An own enumerable string key outside `allowedFields` returns `null`, whatever its value: the guard
+ *   against a misspelt key. A symbol key is ignored.
+ * - Each property `with` reads is read once with an ordinary property get, in the order `with`
+ *   reads them, so an inherited, non-enumerable or getter field applies. `undefined` means absent.
+ *   A defined property outside `allowedFields` (another type's field, an era, an offset, a
+ *   `calendar` or a `timeZone`) returns `null`.
+ * - A value is not converted: `monthCode` must be a string, and every other field a number that is
+ *   an integer. `null`, a numeric string, a boolean and a fraction return `null`, where Temporal
+ *   would convert or truncate them. A bigint, `NaN` and an infinity return `null` too; Temporal
+ *   throws for them (ToIntegerWithTruncation).
+ *
+ * Range and overflow are left to Temporal. An empty result means nothing is set: the function
+ * returns its value unchanged, where Temporal's `with` would throw. A getter that throws is not
+ * caught here, nor is a Proxy's `getPrototypeOf` trap that throws; the calling function's own catch
+ * returns its sentinel.
+ *
+ * @param fields the caller's `fields` argument
+ * @param allowedFields the fields the calling function takes
+ * @returns a new plain object of the fields set, empty when none is, or null on invalid input
+ *
+ * @example readSetFields({ year: 2025 }, DATE_FIELDS) // { year: 2025 }
+ * @example readSetFields({}, DATE_FIELDS) // {} (nothing set)
+ * @example readSetFields({ year: "2025" }, DATE_FIELDS) // null (not converted)
+ * @example readSetFields({ year: 2025, yaer: 1 }, DATE_FIELDS) // null (misspelt key)
+ * @example readSetFields({ year: 2025, hour: 5 }, DATE_FIELDS) // null (a field setDate does not take)
+ */
+export function readSetFields(fields, allowedFields) {
+    const allowed = allowedFields;
+    if (!isObject(fields) || isTemporalDateOrTimeObject(fields)) {
+        return null;
+    }
+    if (!Object.keys(fields).every((key) => allowed.includes(key))) {
+        return null;
+    }
+    const record = fields;
+    const read = {};
+    for (const name of WITH_PROPERTY_NAMES) {
+        const value = record[name];
+        if (value === undefined) {
+            continue;
+        }
+        if (!allowed.includes(name) || !isFieldValue(name, value)) {
+            return null;
+        }
+        read[name] = value;
+    }
+    return read;
+}

package/dist/internal/resolveRelativeUnit.d.ts

@@ -14,7 +14,7 @@ import type { RelativeUnit } from "../types/index.js";
  *   stricter than Temporal: GetOption converts any value with ToString, so Temporal accepts
  *   `["day"]` and an object whose `toString` returns `"day"` (test262
  *   `largestunit-wrong-type.js`). GMT takes string inputs, and its other unit readers
- *   (`roundDate`, `roundDateTime`, `roundUtc`, `roundZoned`, `startOfDate`, `durationAs`,
+ *   (`roundDate`, `roundDateTime`, `roundUtc`, `roundZoned`, `startOfDate`, `totalDuration`,
  *   `areDatesEqualBy`) reject a non-string the same way, so this one does not convert either.
  *
  * @param largestUnit the option as read from the caller's object, `undefined` when absent

package/dist/internal/resolveRelativeUnit.js

@@ -13,7 +13,7 @@
  *   stricter than Temporal: GetOption converts any value with ToString, so Temporal accepts
  *   `["day"]` and an object whose `toString` returns `"day"` (test262
  *   `largestunit-wrong-type.js`). GMT takes string inputs, and its other unit readers
- *   (`roundDate`, `roundDateTime`, `roundUtc`, `roundZoned`, `startOfDate`, `durationAs`,
+ *   (`roundDate`, `roundDateTime`, `roundUtc`, `roundZoned`, `startOfDate`, `totalDuration`,
  *   `areDatesEqualBy`) reject a non-string the same way, so this one does not convert either.
  *
  * @param largestUnit the option as read from the caller's object, `undefined` when absent

package/dist/internal/resolveUnixIntervalPair.d.ts

@@ -1,10 +1,13 @@
 import type { Temporal } from "@js-temporal/polyfill";
 import { type UnixEpochUnit } from "./unixEpochValue.js";
+import { type ZoneFrame } from "./zoneFrame.js";
 export interface ResolvedUnixInterval {
     startVal: Temporal.ZonedDateTime;
     endVal: Temporal.ZonedDateTime;
     resolvedUnit: Temporal.DateTimeUnit;
     epochUnit: UnixEpochUnit;
+    /** The frame both ends were placed on; `frameInstant` turns a result back into an instant. */
+    frame: ZoneFrame;
 }
 /**
  * Resolve the shared arguments of `intervalLengthUnix`, `intervalCountUnix` and
@@ -13,13 +16,16 @@ export interface ResolvedUnixInterval {
  *
  * - Epochs follow the one `unix/` grammar (`parseUnixEpochValue`) and must name Temporal instants.
  * - `epochUnit` defaults to `"milliseconds"`; `timeZone` defaults to `"UTC"` (`"local"` is the
- *   system zone, an unknown zone is invalid).
+ *   system zone; a time zone identifier or a stored UTC offset `±HH:MM[:SS]` is read as written;
+ *   anything else is invalid).
+ * - The ends are placed with `frameZoned`: for a seconds offset they sit in the offset's
+ *   whole-minute zone, moved by its seconds, to compute with and never to write.
  *
  * @param start interval start epoch
  * @param end interval end epoch
  * @param unit unit name, singular or plural
  * @param options optional `{ epochUnit, timeZone }`
- * @returns the zoned ends, singular unit and epoch unit, or null on invalid input
+ * @returns the zoned ends, singular unit, epoch unit and frame, or null on invalid input
  *
  * @example resolveUnixIntervalPair(0, 86400, "days", { epochUnit: "seconds" })?.resolvedUnit // "day"
  * @example resolveUnixIntervalPair(10, 0, "day") // null (reversed)

package/dist/internal/resolveUnixIntervalPair.js

@@ -1,7 +1,7 @@
-import { normalizeTimeZone } from "./normalizeTimeZone.js";
 import { resolveDateTimeUnit } from "./resolveDateTimeUnit.js";
 import { parseUnixEpochInterval, resolveUnixEpochUnit, unixEpochToInstant, } from "./unixEpochValue.js";
 import { isValidDateTimeUnit } from "../plain/validate/index.js";
+import { frameZoned, normalizeZoneFrame } from "./zoneFrame.js";
 /**
  * Resolve the shared arguments of `intervalLengthUnix`, `intervalCountUnix` and
  * `splitIntervalByUnitUnix`: a non-reversed epoch pair in `epochUnit`, a singular-or-plural
@@ -9,13 +9,16 @@ import { isValidDateTimeUnit } from "../plain/validate/index.js";
  *
  * - Epochs follow the one `unix/` grammar (`parseUnixEpochValue`) and must name Temporal instants.
  * - `epochUnit` defaults to `"milliseconds"`; `timeZone` defaults to `"UTC"` (`"local"` is the
- *   system zone, an unknown zone is invalid).
+ *   system zone; a time zone identifier or a stored UTC offset `±HH:MM[:SS]` is read as written;
+ *   anything else is invalid).
+ * - The ends are placed with `frameZoned`: for a seconds offset they sit in the offset's
+ *   whole-minute zone, moved by its seconds, to compute with and never to write.
  *
  * @param start interval start epoch
  * @param end interval end epoch
  * @param unit unit name, singular or plural
  * @param options optional `{ epochUnit, timeZone }`
- * @returns the zoned ends, singular unit and epoch unit, or null on invalid input
+ * @returns the zoned ends, singular unit, epoch unit and frame, or null on invalid input
  *
  * @example resolveUnixIntervalPair(0, 86400, "days", { epochUnit: "seconds" })?.resolvedUnit // "day"
  * @example resolveUnixIntervalPair(10, 0, "day") // null (reversed)
@@ -23,10 +26,10 @@ import { isValidDateTimeUnit } from "../plain/validate/index.js";
 export function resolveUnixIntervalPair(start, end, unit, options) {
     const interval = parseUnixEpochInterval(start, end);
     const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
-    const timeZone = normalizeTimeZone(options?.timeZone);
+    const frame = normalizeZoneFrame(options?.timeZone);
     if (interval === null ||
         epochUnit === null ||
-        !timeZone ||
+        frame === null ||
         typeof unit !== "string") {
         return null;
     }
@@ -41,10 +44,11 @@ export function resolveUnixIntervalPair(start, end, unit, options) {
     }
     try {
         return {
-            startVal: startInstant.toZonedDateTimeISO(timeZone),
-            endVal: endInstant.toZonedDateTimeISO(timeZone),
+            startVal: frameZoned(startInstant, frame),
+            endVal: frameZoned(endInstant, frame),
             resolvedUnit,
             epochUnit,
+            frame,
         };
     }
     catch {

package/dist/internal/startOrEndOfUnix.d.ts

@@ -8,7 +8,8 @@ import type { Temporal } from "@js-temporal/polyfill";
  *   or `"quarter"` from `startOfQuarterForUnix` / `endOfQuarterForUnix` only.
  * - `value` follows the one epoch grammar (`parseUnixEpochValue`); `epochUnit` accepts singular
  *   and plural names and defaults to `"milliseconds"`.
- * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; an unknown zone returns null.
+ * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; a time zone identifier or a
+ *   stored UTC offset (`±HH:MM[:SS]`) is read as written; anything else returns null.
  * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
  * - The boundary is always the real local bucket from `internal/zonedBucket.ts` — a start never
  *   after `value`, an end never before it.

package/dist/internal/startOrEndOfUnix.js

@@ -1,7 +1,7 @@
-import { normalizeTimeZone } from "./normalizeTimeZone.js";
 import { resolveWeekStartsOn } from "./resolveWeekStartsOn.js";
 import { resolveUnixEpochUnit, toUnixEpoch, unixEpochToInstant, } from "./unixEpochValue.js";
 import { zonedUnitEnd, zonedUnitStart } from "./zonedBucket.js";
+import { frameInstant, frameZoned, normalizeZoneFrame } from "./zoneFrame.js";
 /**
  * Internal shared implementation for `startOfUnix` / `endOfUnix` and the quarter functions.
  *
@@ -11,7 +11,8 @@ import { zonedUnitEnd, zonedUnitStart } from "./zonedBucket.js";
  *   or `"quarter"` from `startOfQuarterForUnix` / `endOfQuarterForUnix` only.
  * - `value` follows the one epoch grammar (`parseUnixEpochValue`); `epochUnit` accepts singular
  *   and plural names and defaults to `"milliseconds"`.
- * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; an unknown zone returns null.
+ * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; a time zone identifier or a
+ *   stored UTC offset (`±HH:MM[:SS]`) is read as written; anything else returns null.
  * - `weekStartsOn` other than `"monday"` or `"sunday"` returns null.
  * - The boundary is always the real local bucket from `internal/zonedBucket.ts` — a start never
  *   after `value`, an end never before it.
@@ -24,9 +25,9 @@ import { zonedUnitEnd, zonedUnitStart } from "./zonedBucket.js";
  */
 export function startOrEndOfUnix(value, unit, options, isEnd) {
     const epochUnit = resolveUnixEpochUnit(options.epochUnit);
-    const timeZone = normalizeTimeZone(options.timeZone);
+    const frame = normalizeZoneFrame(options.timeZone);
     const weekStartsOn = resolveWeekStartsOn(options.weekStartsOn);
-    if (!timeZone || epochUnit === null || weekStartsOn === null) {
+    if (frame === null || epochUnit === null || weekStartsOn === null) {
         return null;
     }
     const instant = unixEpochToInstant(value, epochUnit);
@@ -35,11 +36,13 @@ export function startOrEndOfUnix(value, unit, options, isEnd) {
     }
     const weekStartDay = weekStartsOn === "monday" ? 1 : 7;
     try {
-        const source = instant.toZonedDateTimeISO(timeZone);
+        const source = frameZoned(instant, frame);
         const boundary = isEnd
             ? zonedUnitEnd(source, unit, weekStartDay)
             : zonedUnitStart(source, unit, weekStartDay);
-        return boundary ? toUnixEpoch(boundary, epochUnit) : null;
+        return boundary
+            ? toUnixEpoch(frameInstant(boundary, frame), epochUnit)
+            : null;
     }
     catch {
         return null;

package/dist/internal/twoDigitYear.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Resolve a two-digit year inside a caller-chosen hundred-year window: the one year in
+ * `[windowStart, windowStart + 99]` whose last two digits are `yy`.
+ *
+ * Pure arithmetic: the function holds no window of its own and reads no clock. The window comes
+ * from the caller's `TwoDigitYearOptions.yearWindow`, resolved by `readYearWindowStart`
+ * (`internal/yearWindowStart.ts`); no standard says which century a two-digit year belongs to,
+ * so the library never supplies one.
+ *
+ * @param yy the two-digit year, 0–99, as the grammar read it
+ * @param windowStart the first year of the hundred-year window
+ * @returns the four-digit year in the window ending in `yy`
+ *
+ * @example twoDigitYear(24, 2000) // 2024
+ * @example twoDigitYear(99, 1950) // 1999
+ * @example twoDigitYear(49, 1950) // 2049
+ * @example twoDigitYear(0, 1976) // 2000
+ */
+export declare function twoDigitYear(yy: number, windowStart: number): number;

package/dist/internal/twoDigitYear.js

@@ -0,0 +1,22 @@
+/**
+ * Resolve a two-digit year inside a caller-chosen hundred-year window: the one year in
+ * `[windowStart, windowStart + 99]` whose last two digits are `yy`.
+ *
+ * Pure arithmetic: the function holds no window of its own and reads no clock. The window comes
+ * from the caller's `TwoDigitYearOptions.yearWindow`, resolved by `readYearWindowStart`
+ * (`internal/yearWindowStart.ts`); no standard says which century a two-digit year belongs to,
+ * so the library never supplies one.
+ *
+ * @param yy the two-digit year, 0–99, as the grammar read it
+ * @param windowStart the first year of the hundred-year window
+ * @returns the four-digit year in the window ending in `yy`
+ *
+ * @example twoDigitYear(24, 2000) // 2024
+ * @example twoDigitYear(99, 1950) // 1999
+ * @example twoDigitYear(49, 1950) // 2049
+ * @example twoDigitYear(0, 1976) // 2000
+ */
+export function twoDigitYear(yy, windowStart) {
+    const candidate = Math.floor(windowStart / 100) * 100 + yy;
+    return candidate < windowStart ? candidate + 100 : candidate;
+}

package/dist/internal/unixEpochValue.js

@@ -1,5 +1,6 @@
 import { Temporal } from "@js-temporal/polyfill";
 import { MAX_EPOCH_NANOSECONDS } from "./epochNanoseconds.js";
+import { isObject } from "./isObject.js";
 // TC39 Temporal IsValidEpochNanoseconds bound (nsMaxInstant = 10^8 days) in milliseconds: 8.64e15.
 const MAX_EPOCH_MILLISECONDS = Number(MAX_EPOCH_NANOSECONDS / 1000000n);
 // An optionally negative run of ASCII digits and nothing else. `\d` without the `u` flag is
@@ -91,7 +92,7 @@ export function resolveUnixEpochUnitOptions(options) {
     if (options === undefined) {
         return "milliseconds";
     }
-    if (options === null || typeof options !== "object") {
+    if (!isObject(options)) {
         return null;
     }
     return resolveUnixEpochUnit(options.epochUnit);
@@ -231,7 +232,7 @@ export function parseUnixEpochIntervalList(intervals) {
     }
     const parsed = [];
     for (const interval of intervals) {
-        if (!interval || typeof interval !== "object") {
+        if (!isObject(interval)) {
             return null;
         }
         const { start, end } = interval;

package/dist/internal/unixWallClock.d.ts

@@ -0,0 +1,24 @@
+import type { Temporal } from "@js-temporal/polyfill";
+/**
+ * Read a Unix epoch argument on the local wall clock of the shared `unix/` options, or null when
+ * anything is invalid. For the `parse*FromUnix` accessors, which only read fields.
+ *
+ * - `value` follows the one epoch grammar (`parseUnixEpochValue`).
+ * - `epochUnit` accepts singular or plural names and defaults to `"milliseconds"`.
+ * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; a time zone identifier or a
+ *   stored UTC offset (`±HH:MM[:SS]`) is read as written; anything else is invalid (see
+ *   `normalizeZoneFrame`).
+ *
+ * @param value Unix epoch number or digit string
+ * @param options optional `{ epochUnit, timeZone }`
+ * @returns the local wall clock, or null
+ *
+ * @example unixWallClock(0)?.toString() // "1970-01-01T00:00:00"
+ * @example unixWallClock("86400", { epochUnit: "second", timeZone: "Asia/Tokyo" })?.hour // 9
+ * @example unixWallClock(45870000, { timeZone: "-00:44:30" })?.toString() // "1970-01-01T12:00:00"
+ * @example unixWallClock(0, { timeZone: "Asia/Tokio" }) // null
+ */
+export declare function unixWallClock(value: unknown, options?: {
+    epochUnit?: unknown;
+    timeZone?: unknown;
+}): Temporal.PlainDateTime | null;

package/dist/internal/unixWallClock.js

@@ -0,0 +1,35 @@
+import { resolveUnixEpochUnit, unixEpochToInstant } from "./unixEpochValue.js";
+import { frameWallClock, normalizeZoneFrame } from "./zoneFrame.js";
+/**
+ * Read a Unix epoch argument on the local wall clock of the shared `unix/` options, or null when
+ * anything is invalid. For the `parse*FromUnix` accessors, which only read fields.
+ *
+ * - `value` follows the one epoch grammar (`parseUnixEpochValue`).
+ * - `epochUnit` accepts singular or plural names and defaults to `"milliseconds"`.
+ * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; a time zone identifier or a
+ *   stored UTC offset (`±HH:MM[:SS]`) is read as written; anything else is invalid (see
+ *   `normalizeZoneFrame`).
+ *
+ * @param value Unix epoch number or digit string
+ * @param options optional `{ epochUnit, timeZone }`
+ * @returns the local wall clock, or null
+ *
+ * @example unixWallClock(0)?.toString() // "1970-01-01T00:00:00"
+ * @example unixWallClock("86400", { epochUnit: "second", timeZone: "Asia/Tokyo" })?.hour // 9
+ * @example unixWallClock(45870000, { timeZone: "-00:44:30" })?.toString() // "1970-01-01T12:00:00"
+ * @example unixWallClock(0, { timeZone: "Asia/Tokio" }) // null
+ */
+export function unixWallClock(value, options) {
+    const epochUnit = resolveUnixEpochUnit(options?.epochUnit);
+    const frame = normalizeZoneFrame(options?.timeZone);
+    if (epochUnit === null || frame === null) {
+        return null;
+    }
+    try {
+        const instant = unixEpochToInstant(value, epochUnit);
+        return instant === null ? null : frameWallClock(instant, frame);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/internal/utcWallClock.d.ts

@@ -0,0 +1,20 @@
+import { Temporal } from "@js-temporal/polyfill";
+/**
+ * Read a UTC ISO string on a local wall clock for the `parse*FromUtc` accessors: the instant it
+ * names, on the wall clock of `options.timeZone`. The utc twin of `unixWallClock`.
+ *
+ * - `timeZone` defaults to `"UTC"`; `"local"` is the system zone; a time zone identifier or a
+ *   stored UTC offset (`±HH:MM[:SS]`) is read as written; anything else is invalid (see
+ *   `normalizeZoneFrame`).
+ *
+ * @param value UTC ISO 8601 datetime string
+ * @param options optional `{ timeZone }`
+ * @returns the local wall clock, or null when the value or the zone is invalid
+ * @example utcWallClock("2024-03-15T14:30:00Z", { timeZone: "Asia/Tokyo" })?.toString() // "2024-03-15T23:30:00"
+ * @example utcWallClock("1970-01-01T12:44:30Z", { timeZone: "-00:44:30" })?.toString() // "1970-01-01T12:00:00"
+ * @example utcWallClock("2024-03-15T14:30:00Z", { timeZone: "Invalid/Zone" }) // null
+ * @example utcWallClock("2024-03-15T14:30:00") // null (no Z)
+ */
+export declare function utcWallClock(value: string, options?: {
+    timeZone?: string;
+}): Temporal.PlainDateTime | null;