@northguild/gmt 1.15.0 → 1.17.0

package/dist/plain/validate/isValidTimeRange.js

@@ -1,10 +1,14 @@
+// fallow-ignore-file code-duplication -- cross-family Temporal type clone, by design (rule 5)
 import { Temporal } from "@js-temporal/polyfill";
-import { plainTime } from "../../regex/index.js";
+import { isValidTime } from "./isValidTime.js";
+import { isObject, isOptionsArgument } from "../../internal/isObject.js";
 /**
  * Return true if `value1` and `value2` form a valid time range — both parseable as
  * ISO PlainTime strings and `value1 <= value2`.
  *
- * - Both inputs must be ISO 8601 time strings (e.g. `"14:30:00"`).
+ * - Both inputs must be ISO 8601 time strings (e.g. `"14:30:00"`), as `isValidTime` accepts,
+ *   annotations included.
+ * - Ordered by `Temporal.PlainTime.compare`, to the nanosecond.
  * - Equal `value1 === value2` is valid when `options.allowEqual` is true.
  * - Invalid input, malformed strings, or leap-second strings return `false`.
  *
@@ -17,35 +21,35 @@ import { plainTime } from "../../regex/index.js";
  * @example isValidTimeRange({ value1: "17:00:00", value2: "09:00:00" }) // false
  * @example isValidTimeRange({ value1: "12:00:00", value2: "12:00:00", options: { allowEqual: true } }) // true
  */
-export function isValidTimeRange({ value1, value2, options, }) {
-    if (typeof value1 !== "string" || typeof value2 !== "string") {
-        return false;
-    }
-    if (!plainTime.test(value1) || !plainTime.test(value2)) {
-        return false;
-    }
+export function isValidTimeRange(props) {
     try {
-        const time1 = Temporal.PlainTime.from(value1);
-        const time2 = Temporal.PlainTime.from(value2);
-        const isLessThan = time1.hour < time2.hour ||
-            (time1.hour === time2.hour && time1.minute < time2.minute) ||
-            (time1.hour === time2.hour &&
-                time1.minute === time2.minute &&
-                time1.second < time2.second) ||
-            (time1.hour === time2.hour &&
-                time1.minute === time2.minute &&
-                time1.second === time2.second &&
-                time1.millisecond < time2.millisecond);
-        const isEqual = time1.hour === time2.hour &&
-            time1.minute === time2.minute &&
-            time1.second === time2.second &&
-            time1.millisecond === time2.millisecond;
-        if (options?.allowEqual) {
-            return isLessThan || isEqual;
+        if (!isObject(props))
+            return false;
+        const { value1, value2, options } = props;
+        if (!isOptionsArgument(options))
+            return false;
+        if (typeof value1 !== "string" || typeof value2 !== "string") {
+            return false;
+        }
+        if (!isValidTime(value1) || !isValidTime(value2)) {
+            return false;
+        }
+        try {
+            const time1 = Temporal.PlainTime.from(value1);
+            const time2 = Temporal.PlainTime.from(value2);
+            const cmp = Temporal.PlainTime.compare(time1, time2);
+            if (options?.allowEqual) {
+                return cmp <= 0;
+            }
+            return cmp < 0;
+        }
+        catch {
+            return false;
         }
-        return isLessThan;
     }
     catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
         return false;
     }
 }

package/dist/precision/calculate/index.d.ts

@@ -0,0 +1 @@
+export * from "./truncateNanoseconds.js";

package/dist/precision/calculate/index.js

@@ -0,0 +1 @@
+export * from "./truncateNanoseconds.js";

package/dist/precision/calculate/truncateNanoseconds.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Storage precision a nanosecond value can be truncated to.
+ *
+ * @remarks Members:
+ *
+ * | Member | Description |
+ * | --- | --- |
+ * | `ms` | Milliseconds — the precision of `Date`, JSON APIs, and most message brokers. |
+ * | `us` | Microseconds — the precision of PostgreSQL `timestamptz` and MySQL `DATETIME(6)`. |
+ */
+export type NanosecondTruncationUnit = "ms" | "us";
+/**
+ * Truncate nanoseconds since the Unix epoch to the precision a store can actually hold.
+ *
+ * - Floors toward negative infinity, so pre-1970 values truncate the same way post-1970 ones
+ *   do: `truncateNanoseconds(-1500n, "us")` is `-2000n`, not `-1000n`. Rounding toward zero
+ *   would make the result jump direction either side of the epoch.
+ * - Call this before writing to a store that cannot hold nanoseconds — PostgreSQL
+ *   `timestamptz` and MySQL `DATETIME(6)` hold microseconds, `Date`-based APIs hold
+ *   milliseconds — so the value read back equals the value written.
+ * - Idempotent: truncating an already-truncated value returns it unchanged.
+ * - Returns `0n` on invalid input, including nanoseconds outside the range
+ *   `Temporal.Instant` can represent. `0n` is also the epoch itself — validate first when
+ *   the two must be told apart.
+ *
+ * @param nanoseconds nanoseconds since the Unix epoch (bigint)
+ * @param unit target storage precision, "ms" (milliseconds) or "us" (microseconds)
+ * @returns truncated nanoseconds as a bigint, or 0n on invalid input
+ *
+ * @example truncateNanoseconds(1710072000123456789n, "us") // 1710072000123456000n
+ * @example truncateNanoseconds(1710072000123456789n, "ms") // 1710072000123000000n
+ * @example truncateNanoseconds(-1500n, "us") // -2000n
+ * @example truncateNanoseconds(0n, "ms") // 0n
+ * @example truncateNanoseconds(1710072000123456789n, "ns") // 0n
+ * @example truncateNanoseconds(1710072000123456789, "us") // 0n — number, not bigint
+ */
+export declare function truncateNanoseconds(nanoseconds: bigint, unit: NanosecondTruncationUnit): bigint;

package/dist/precision/calculate/truncateNanoseconds.js

@@ -0,0 +1,41 @@
+import { isValidEpochNanoseconds } from "../../internal/index.js";
+const NANOSECONDS_PER_UNIT = {
+    ms: 1000000n,
+    us: 1000n,
+};
+/**
+ * Truncate nanoseconds since the Unix epoch to the precision a store can actually hold.
+ *
+ * - Floors toward negative infinity, so pre-1970 values truncate the same way post-1970 ones
+ *   do: `truncateNanoseconds(-1500n, "us")` is `-2000n`, not `-1000n`. Rounding toward zero
+ *   would make the result jump direction either side of the epoch.
+ * - Call this before writing to a store that cannot hold nanoseconds — PostgreSQL
+ *   `timestamptz` and MySQL `DATETIME(6)` hold microseconds, `Date`-based APIs hold
+ *   milliseconds — so the value read back equals the value written.
+ * - Idempotent: truncating an already-truncated value returns it unchanged.
+ * - Returns `0n` on invalid input, including nanoseconds outside the range
+ *   `Temporal.Instant` can represent. `0n` is also the epoch itself — validate first when
+ *   the two must be told apart.
+ *
+ * @param nanoseconds nanoseconds since the Unix epoch (bigint)
+ * @param unit target storage precision, "ms" (milliseconds) or "us" (microseconds)
+ * @returns truncated nanoseconds as a bigint, or 0n on invalid input
+ *
+ * @example truncateNanoseconds(1710072000123456789n, "us") // 1710072000123456000n
+ * @example truncateNanoseconds(1710072000123456789n, "ms") // 1710072000123000000n
+ * @example truncateNanoseconds(-1500n, "us") // -2000n
+ * @example truncateNanoseconds(0n, "ms") // 0n
+ * @example truncateNanoseconds(1710072000123456789n, "ns") // 0n
+ * @example truncateNanoseconds(1710072000123456789, "us") // 0n — number, not bigint
+ */
+export function truncateNanoseconds(nanoseconds, unit) {
+    if (!isValidEpochNanoseconds(nanoseconds)) {
+        return 0n;
+    }
+    if (unit !== "ms" && unit !== "us") {
+        return 0n;
+    }
+    const divisor = NANOSECONDS_PER_UNIT[unit];
+    const remainder = ((nanoseconds % divisor) + divisor) % divisor;
+    return nanoseconds - remainder;
+}

package/dist/precision/convert/fromDotNetTicks.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Convert .NET `DateTime.Ticks` back to an ISO 8601 instant string.
+ *
+ * - `value` counts 100-nanosecond intervals since 0001-01-01T00:00:00 in the proleptic
+ *   Gregorian calendar.
+ * - **Only UTC ticks name an instant.** .NET counts `Ticks` in the zone of the `DateTime`'s
+ *   `Kind`: a `Local` or `Unspecified` value counts local wall-clock time, and this function
+ *   reads every value as UTC. Pass `DateTime.UtcNow.Ticks` or `ToUniversalTime().Ticks`;
+ *   `DateTime.Now.Ticks` on a UTC−5 host decodes five hours early.
+ * - Accepts `DateTime.MinValue` (`0n`) to `DateTime.MaxValue` (`3155378975999999999n`,
+ *   9999-12-31T23:59:59.9999999). A tick count outside that is not a `DateTime`, and a
+ *   negative value in particular is rejected rather than read as a pre-year-1 instant.
+ * - Pass `Ticks`, not the raw backing field: .NET packs `DateTimeKind` into its top two
+ *   bits, and a `Kind`-tagged value would decode as an instant thousands of years out.
+ * - Exact in this direction — 100 ns is coarser than the nanoseconds an ISO string carries,
+ *   so nothing is rounded. The loss, if any, happened in `toDotNetTicks`.
+ * - Returns "" on invalid input.
+ *
+ * @param value 100-nanosecond intervals since 0001-01-01 (bigint, 0n to 3155378975999999999n)
+ * @returns ISO 8601 instant string (UTC), or "" on invalid input
+ *
+ * @example fromDotNetTicks(0n) // "0001-01-01T00:00:00Z" — DateTime.MinValue
+ * @example fromDotNetTicks(621355968000000000n) // "1970-01-01T00:00:00Z"
+ * @example fromDotNetTicks(638456708967890000n) // "2024-03-10T12:34:56.789Z"
+ * @example fromDotNetTicks(3155378975999999999n) // "9999-12-31T23:59:59.9999999Z" — DateTime.MaxValue
+ * @example fromDotNetTicks(-1n) // "" — before DateTime.MinValue
+ * @example fromDotNetTicks(3155378976000000000n) // "" — past DateTime.MaxValue
+ * @example fromDotNetTicks(621355968000000000) // "" — number, not bigint
+ */
+export declare function fromDotNetTicks(value: bigint): string;

package/dist/precision/convert/fromDotNetTicks.js

@@ -0,0 +1,39 @@
+import { DOT_NET_TICKS_EPOCH_OFFSET, MAX_DOT_NET_TICKS, MIN_DOT_NET_TICKS, NANOSECONDS_PER_TICK, } from "../../internal/index.js";
+import { fromNanoseconds } from "./fromNanoseconds.js";
+/**
+ * Convert .NET `DateTime.Ticks` back to an ISO 8601 instant string.
+ *
+ * - `value` counts 100-nanosecond intervals since 0001-01-01T00:00:00 in the proleptic
+ *   Gregorian calendar.
+ * - **Only UTC ticks name an instant.** .NET counts `Ticks` in the zone of the `DateTime`'s
+ *   `Kind`: a `Local` or `Unspecified` value counts local wall-clock time, and this function
+ *   reads every value as UTC. Pass `DateTime.UtcNow.Ticks` or `ToUniversalTime().Ticks`;
+ *   `DateTime.Now.Ticks` on a UTC−5 host decodes five hours early.
+ * - Accepts `DateTime.MinValue` (`0n`) to `DateTime.MaxValue` (`3155378975999999999n`,
+ *   9999-12-31T23:59:59.9999999). A tick count outside that is not a `DateTime`, and a
+ *   negative value in particular is rejected rather than read as a pre-year-1 instant.
+ * - Pass `Ticks`, not the raw backing field: .NET packs `DateTimeKind` into its top two
+ *   bits, and a `Kind`-tagged value would decode as an instant thousands of years out.
+ * - Exact in this direction — 100 ns is coarser than the nanoseconds an ISO string carries,
+ *   so nothing is rounded. The loss, if any, happened in `toDotNetTicks`.
+ * - Returns "" on invalid input.
+ *
+ * @param value 100-nanosecond intervals since 0001-01-01 (bigint, 0n to 3155378975999999999n)
+ * @returns ISO 8601 instant string (UTC), or "" on invalid input
+ *
+ * @example fromDotNetTicks(0n) // "0001-01-01T00:00:00Z" — DateTime.MinValue
+ * @example fromDotNetTicks(621355968000000000n) // "1970-01-01T00:00:00Z"
+ * @example fromDotNetTicks(638456708967890000n) // "2024-03-10T12:34:56.789Z"
+ * @example fromDotNetTicks(3155378975999999999n) // "9999-12-31T23:59:59.9999999Z" — DateTime.MaxValue
+ * @example fromDotNetTicks(-1n) // "" — before DateTime.MinValue
+ * @example fromDotNetTicks(3155378976000000000n) // "" — past DateTime.MaxValue
+ * @example fromDotNetTicks(621355968000000000) // "" — number, not bigint
+ */
+export function fromDotNetTicks(value) {
+    if (typeof value !== "bigint" ||
+        value < MIN_DOT_NET_TICKS ||
+        value > MAX_DOT_NET_TICKS) {
+        return "";
+    }
+    return fromNanoseconds((value - DOT_NET_TICKS_EPOCH_OFFSET) * NANOSECONDS_PER_TICK);
+}

package/dist/precision/convert/fromExcelSerial.d.ts

@@ -0,0 +1,38 @@
+import type { ExcelDateSystem } from "./toExcelSerial.js";
+/**
+ * Convert an Excel day serial back to an ISO 8601 instant string.
+ *
+ * - The serial is days with the time of day as the fraction, read as a UTC wall clock.
+ * - **Serial 60 in the 1900 system returns ""** — it is the phantom 29 February 1900, a date
+ *   that never existed. Lotus 1-2-3 treated 1900 as a leap year and Excel keeps the bug for
+ *   compatibility, so the whole serial day `[60, 61)` is a hole: 59 is 1900-02-28 and 61 is
+ *   1900-03-01. Mapping 60 to either neighbour would put every earlier date one day out.
+ * - `{ system: "1904" }` selects the legacy Mac system, whose serial 0 is 1904-01-01 and
+ *   which has no phantom day — serial 60 there is a real 1904-03-01. A 1904 serial resolves
+ *   to the same instant as the 1900 serial exactly 1462 higher.
+ * - Accepted range is Excel's own: serial 1 (1900-01-01) to just under 2958466 (the end of
+ *   9999-12-31) in the 1900 system, serial 0 to just under 2957004 in the 1904 system.
+ *   Serial 0 in the 1900 system is Excel's "January 0, 1900" placeholder, not a date.
+ * - Rounds to the nearest millisecond. A serial is a `double`, whose resolution is about a
+ *   microsecond near 2024 and about 40 µs near 9999 — finer than a millisecond nowhere in
+ *   the range, so rounding there is what makes the round trip through `toExcelSerial` exact.
+ * - Returns "" on invalid input.
+ *
+ * @param value Excel day serial (number, may carry a fractional time of day)
+ * @param options optional: system ("1900" (default) | "1904")
+ * @returns ISO 8601 instant string (UTC), or "" on invalid input
+ *
+ * @example fromExcelSerial(1) // "1900-01-01T00:00:00Z" — Excel's first serial
+ * @example fromExcelSerial(25569) // "1970-01-01T00:00:00Z"
+ * @example fromExcelSerial(45361.5) // "2024-03-10T12:00:00Z"
+ * @example fromExcelSerial(59) // "1900-02-28T00:00:00Z"
+ * @example fromExcelSerial(60) // "" — the phantom 1900-02-29, a date that never existed
+ * @example fromExcelSerial(61) // "1900-03-01T00:00:00Z"
+ * @example fromExcelSerial(60, { system: "1904" }) // "1904-03-01T00:00:00Z" — no phantom day here
+ * @example fromExcelSerial(43899.5, { system: "1904" }) // "2024-03-10T12:00:00Z"
+ * @example fromExcelSerial(0) // "" — Excel's "January 0, 1900", not a date
+ * @example fromExcelSerial(-1) // ""
+ */
+export declare function fromExcelSerial(value: number, options?: {
+    system?: ExcelDateSystem;
+}): string;

package/dist/precision/convert/fromExcelSerial.js

@@ -0,0 +1,81 @@
+import { EXCEL_1900_EPOCH_NANOSECONDS, EXCEL_1900_PRE_PHANTOM_EPOCH_NANOSECONDS, EXCEL_1904_EPOCH_NANOSECONDS, EXCEL_PHANTOM_SERIAL, MAX_EXCEL_1900_SERIAL_EXCLUSIVE, MAX_EXCEL_1904_SERIAL_EXCLUSIVE, MILLISECONDS_PER_DAY, MIN_EXCEL_1900_SERIAL, MIN_EXCEL_1904_SERIAL, NANOSECONDS_PER_MILLISECOND, } from "../../internal/index.js";
+import { fromNanoseconds } from "./fromNanoseconds.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
+/**
+ * Convert an Excel day serial back to an ISO 8601 instant string.
+ *
+ * - The serial is days with the time of day as the fraction, read as a UTC wall clock.
+ * - **Serial 60 in the 1900 system returns ""** — it is the phantom 29 February 1900, a date
+ *   that never existed. Lotus 1-2-3 treated 1900 as a leap year and Excel keeps the bug for
+ *   compatibility, so the whole serial day `[60, 61)` is a hole: 59 is 1900-02-28 and 61 is
+ *   1900-03-01. Mapping 60 to either neighbour would put every earlier date one day out.
+ * - `{ system: "1904" }` selects the legacy Mac system, whose serial 0 is 1904-01-01 and
+ *   which has no phantom day — serial 60 there is a real 1904-03-01. A 1904 serial resolves
+ *   to the same instant as the 1900 serial exactly 1462 higher.
+ * - Accepted range is Excel's own: serial 1 (1900-01-01) to just under 2958466 (the end of
+ *   9999-12-31) in the 1900 system, serial 0 to just under 2957004 in the 1904 system.
+ *   Serial 0 in the 1900 system is Excel's "January 0, 1900" placeholder, not a date.
+ * - Rounds to the nearest millisecond. A serial is a `double`, whose resolution is about a
+ *   microsecond near 2024 and about 40 µs near 9999 — finer than a millisecond nowhere in
+ *   the range, so rounding there is what makes the round trip through `toExcelSerial` exact.
+ * - Returns "" on invalid input.
+ *
+ * @param value Excel day serial (number, may carry a fractional time of day)
+ * @param options optional: system ("1900" (default) | "1904")
+ * @returns ISO 8601 instant string (UTC), or "" on invalid input
+ *
+ * @example fromExcelSerial(1) // "1900-01-01T00:00:00Z" — Excel's first serial
+ * @example fromExcelSerial(25569) // "1970-01-01T00:00:00Z"
+ * @example fromExcelSerial(45361.5) // "2024-03-10T12:00:00Z"
+ * @example fromExcelSerial(59) // "1900-02-28T00:00:00Z"
+ * @example fromExcelSerial(60) // "" — the phantom 1900-02-29, a date that never existed
+ * @example fromExcelSerial(61) // "1900-03-01T00:00:00Z"
+ * @example fromExcelSerial(60, { system: "1904" }) // "1904-03-01T00:00:00Z" — no phantom day here
+ * @example fromExcelSerial(43899.5, { system: "1904" }) // "2024-03-10T12:00:00Z"
+ * @example fromExcelSerial(0) // "" — Excel's "January 0, 1900", not a date
+ * @example fromExcelSerial(-1) // ""
+ */
+export function fromExcelSerial(value, options) {
+    try {
+        if (!isOptionsArgument(options)) {
+            return "";
+        }
+        const system = options?.system === undefined ? "1900" : options.system;
+        if (system !== "1900" && system !== "1904") {
+            return "";
+        }
+        if (!Number.isFinite(value)) {
+            return "";
+        }
+        // Snap to the millisecond grid before deciding anything: the range and phantom-day
+        // comparisons must be made against the value actually built, not against a serial that
+        // rounds across a boundary on the way there.
+        const dayMilliseconds = Math.round(value * MILLISECONDS_PER_DAY);
+        const minimum = system === "1904" ? MIN_EXCEL_1904_SERIAL : MIN_EXCEL_1900_SERIAL;
+        const maximumExclusive = system === "1904"
+            ? MAX_EXCEL_1904_SERIAL_EXCLUSIVE
+            : MAX_EXCEL_1900_SERIAL_EXCLUSIVE;
+        if (dayMilliseconds < minimum * MILLISECONDS_PER_DAY ||
+            dayMilliseconds >= maximumExclusive * MILLISECONDS_PER_DAY) {
+            return "";
+        }
+        if (system === "1904") {
+            return fromNanoseconds(BigInt(dayMilliseconds) * NANOSECONDS_PER_MILLISECOND +
+                EXCEL_1904_EPOCH_NANOSECONDS);
+        }
+        const phantomStart = EXCEL_PHANTOM_SERIAL * MILLISECONDS_PER_DAY;
+        const phantomEnd = (EXCEL_PHANTOM_SERIAL + 1) * MILLISECONDS_PER_DAY;
+        if (dayMilliseconds >= phantomStart && dayMilliseconds < phantomEnd) {
+            return "";
+        }
+        return fromNanoseconds(BigInt(dayMilliseconds) * NANOSECONDS_PER_MILLISECOND +
+            (dayMilliseconds >= phantomEnd
+                ? EXCEL_1900_EPOCH_NANOSECONDS
+                : EXCEL_1900_PRE_PHANTOM_EPOCH_NANOSECONDS));
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return "";
+    }
+}

package/dist/precision/convert/fromFileTime.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Convert a Windows `FILETIME` back to an ISO 8601 instant string.
+ *
+ * - `value` counts 100-nanosecond intervals since 1601-01-01T00:00:00Z.
+ * - The accepted range is `0n` to `2^63 − 1`, 1601-01-01 to
+ *   `+030828-09-14T02:48:05.4775807Z`. `FILETIME` is a pair of `DWORD`s, so a negative value is
+ *   rejected rather than read as a pre-1601 instant. Values from `2^63` up are rejected too:
+ *   Microsoft's `FileTimeToSystemTime` requires a value "less than 0x8000000000000000", and
+ *   `SetFileTime` uses `0xFFFFFFFFFFFFFFFF` (`2^64 − 1`) as its "do not modify" marker.
+ * - To decode the raw unsigned count anyway, for example to inspect a marker, compute
+ *   `fromNanoseconds((value - 116444736000000000n) * 100n)`.
+ * - Exact in this direction — 100 ns is coarser than the nanoseconds an ISO string carries,
+ *   so nothing is rounded. The loss, if any, happened in `toFileTime`.
+ * - Returns "" on invalid input.
+ *
+ * @param value 100-nanosecond intervals since 1601-01-01 (bigint, 0n to 2^63 − 1)
+ * @returns ISO 8601 instant string (UTC), or "" on invalid input
+ *
+ * @example fromFileTime(0n) // "1601-01-01T00:00:00Z" — the FILETIME epoch
+ * @example fromFileTime(116444736000000000n) // "1970-01-01T00:00:00Z"
+ * @example fromFileTime(133545476967890000n) // "2024-03-10T12:34:56.789Z"
+ * @example fromFileTime(2650467743999999999n) // "9999-12-31T23:59:59.9999999Z" — .NET's DateTime maximum
+ * @example fromFileTime(9223372036854775807n) // "+030828-09-14T02:48:05.4775807Z" — 2^63 − 1, the largest accepted
+ * @example fromFileTime(9223372036854775808n) // "" — 2^63, which FileTimeToSystemTime rejects
+ * @example fromFileTime(18446744073709551615n) // "" — SetFileTime's do-not-modify marker
+ * @example fromNanoseconds((18446744073709551615n - 116444736000000000n) * 100n) // "+060056-05-28T05:36:10.9551615Z" — raw unsigned decode
+ * @example fromFileTime(-1n) // "" — FILETIME is unsigned
+ * @example fromFileTime(116444736000000000) // "" — number, not bigint
+ */
+export declare function fromFileTime(value: bigint): string;

package/dist/precision/convert/fromFileTime.js

@@ -0,0 +1,39 @@
+import { FILE_TIME_EPOCH_OFFSET_TICKS, MAX_FILE_TIME, MIN_FILE_TIME, NANOSECONDS_PER_TICK, } from "../../internal/index.js";
+import { fromNanoseconds } from "./fromNanoseconds.js";
+/**
+ * Convert a Windows `FILETIME` back to an ISO 8601 instant string.
+ *
+ * - `value` counts 100-nanosecond intervals since 1601-01-01T00:00:00Z.
+ * - The accepted range is `0n` to `2^63 − 1`, 1601-01-01 to
+ *   `+030828-09-14T02:48:05.4775807Z`. `FILETIME` is a pair of `DWORD`s, so a negative value is
+ *   rejected rather than read as a pre-1601 instant. Values from `2^63` up are rejected too:
+ *   Microsoft's `FileTimeToSystemTime` requires a value "less than 0x8000000000000000", and
+ *   `SetFileTime` uses `0xFFFFFFFFFFFFFFFF` (`2^64 − 1`) as its "do not modify" marker.
+ * - To decode the raw unsigned count anyway, for example to inspect a marker, compute
+ *   `fromNanoseconds((value - 116444736000000000n) * 100n)`.
+ * - Exact in this direction — 100 ns is coarser than the nanoseconds an ISO string carries,
+ *   so nothing is rounded. The loss, if any, happened in `toFileTime`.
+ * - Returns "" on invalid input.
+ *
+ * @param value 100-nanosecond intervals since 1601-01-01 (bigint, 0n to 2^63 − 1)
+ * @returns ISO 8601 instant string (UTC), or "" on invalid input
+ *
+ * @example fromFileTime(0n) // "1601-01-01T00:00:00Z" — the FILETIME epoch
+ * @example fromFileTime(116444736000000000n) // "1970-01-01T00:00:00Z"
+ * @example fromFileTime(133545476967890000n) // "2024-03-10T12:34:56.789Z"
+ * @example fromFileTime(2650467743999999999n) // "9999-12-31T23:59:59.9999999Z" — .NET's DateTime maximum
+ * @example fromFileTime(9223372036854775807n) // "+030828-09-14T02:48:05.4775807Z" — 2^63 − 1, the largest accepted
+ * @example fromFileTime(9223372036854775808n) // "" — 2^63, which FileTimeToSystemTime rejects
+ * @example fromFileTime(18446744073709551615n) // "" — SetFileTime's do-not-modify marker
+ * @example fromNanoseconds((18446744073709551615n - 116444736000000000n) * 100n) // "+060056-05-28T05:36:10.9551615Z" — raw unsigned decode
+ * @example fromFileTime(-1n) // "" — FILETIME is unsigned
+ * @example fromFileTime(116444736000000000) // "" — number, not bigint
+ */
+export function fromFileTime(value) {
+    if (typeof value !== "bigint" ||
+        value < MIN_FILE_TIME ||
+        value > MAX_FILE_TIME) {
+        return "";
+    }
+    return fromNanoseconds((value - FILE_TIME_EPOCH_OFFSET_TICKS) * NANOSECONDS_PER_TICK);
+}

package/dist/precision/convert/fromNanoseconds.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Convert nanoseconds since the Unix epoch back to an ISO 8601 string.
+ *
+ * - Returns a UTC instant string when no time zone is given, and a zoned string
+ *   (`"...[America/New_York]"`) when one is.
+ * - No disambiguation policy applies: an instant maps to exactly one wall time in a zone,
+ *   so DST gaps and overlaps cannot arise on this direction of the conversion.
+ * - A time zone, when given, must be a valid IANA identifier. `undefined` is the same as omitting
+ *   it (UTC), as TC39 treats an undefined argument as absent.
+ * - Rejects values outside the range `Temporal.Instant` can represent
+ *   (±8_640_000_000_000_000_000_000n, i.e. ±10^8 days from the epoch).
+ * - **Storage round-trip:** most engines cannot hold nanoseconds — PostgreSQL `timestamptz`
+ *   stores microseconds — so writing this value and reading it back breaks equality unless
+ *   the caller applies `truncateNanoseconds` to the target precision first.
+ * - Returns "" on invalid input.
+ *
+ * @param nanoseconds nanoseconds since the Unix epoch (bigint)
+ * @param timeZone optional IANA timeZone identifier; omitted or `undefined` is UTC
+ * @returns ISO 8601 instant string (UTC), zoned ISO 8601 string when a timeZone is given, or "" on invalid input
+ *
+ * @example fromNanoseconds(0n) // "1970-01-01T00:00:00Z"
+ * @example fromNanoseconds(1710072000123456789n) // "2024-03-10T12:00:00.123456789Z"
+ * @example fromNanoseconds(1710072000123456789n, "America/New_York") // "2024-03-10T08:00:00.123456789-04:00[America/New_York]"
+ * @example fromNanoseconds(-1000000000n) // "1969-12-31T23:59:59Z"
+ * @example fromNanoseconds(0n, "Not/AZone") // ""
+ * @example fromNanoseconds(0n, undefined) // "1970-01-01T00:00:00Z" — undefined is the same as omitted
+ * @example fromNanoseconds(1710072000123456789) // "" — number, not bigint
+ */
+export declare function fromNanoseconds(nanoseconds: bigint, timeZone?: string): string;

package/dist/precision/convert/fromNanoseconds.js

@@ -0,0 +1,50 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { isValidEpochNanoseconds } from "../../internal/index.js";
+import { isValidTimeZone } from "../../zoned/validate/index.js";
+/**
+ * Convert nanoseconds since the Unix epoch back to an ISO 8601 string.
+ *
+ * - Returns a UTC instant string when no time zone is given, and a zoned string
+ *   (`"...[America/New_York]"`) when one is.
+ * - No disambiguation policy applies: an instant maps to exactly one wall time in a zone,
+ *   so DST gaps and overlaps cannot arise on this direction of the conversion.
+ * - A time zone, when given, must be a valid IANA identifier. `undefined` is the same as omitting
+ *   it (UTC), as TC39 treats an undefined argument as absent.
+ * - Rejects values outside the range `Temporal.Instant` can represent
+ *   (±8_640_000_000_000_000_000_000n, i.e. ±10^8 days from the epoch).
+ * - **Storage round-trip:** most engines cannot hold nanoseconds — PostgreSQL `timestamptz`
+ *   stores microseconds — so writing this value and reading it back breaks equality unless
+ *   the caller applies `truncateNanoseconds` to the target precision first.
+ * - Returns "" on invalid input.
+ *
+ * @param nanoseconds nanoseconds since the Unix epoch (bigint)
+ * @param timeZone optional IANA timeZone identifier; omitted or `undefined` is UTC
+ * @returns ISO 8601 instant string (UTC), zoned ISO 8601 string when a timeZone is given, or "" on invalid input
+ *
+ * @example fromNanoseconds(0n) // "1970-01-01T00:00:00Z"
+ * @example fromNanoseconds(1710072000123456789n) // "2024-03-10T12:00:00.123456789Z"
+ * @example fromNanoseconds(1710072000123456789n, "America/New_York") // "2024-03-10T08:00:00.123456789-04:00[America/New_York]"
+ * @example fromNanoseconds(-1000000000n) // "1969-12-31T23:59:59Z"
+ * @example fromNanoseconds(0n, "Not/AZone") // ""
+ * @example fromNanoseconds(0n, undefined) // "1970-01-01T00:00:00Z" — undefined is the same as omitted
+ * @example fromNanoseconds(1710072000123456789) // "" — number, not bigint
+ */
+export function fromNanoseconds(nanoseconds, timeZone) {
+    if (!isValidEpochNanoseconds(nanoseconds)) {
+        return "";
+    }
+    // An explicit `undefined` is the same as omitting the argument (TC39 optional parameters).
+    if (timeZone !== undefined &&
+        (typeof timeZone !== "string" || !isValidTimeZone(timeZone))) {
+        return "";
+    }
+    try {
+        const instant = Temporal.Instant.fromEpochNanoseconds(nanoseconds);
+        return typeof timeZone === "string"
+            ? instant.toZonedDateTimeISO(timeZone).toString()
+            : instant.toString();
+    }
+    catch {
+        return "";
+    }
+}

package/dist/precision/convert/fromNtpTimestamp.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Convert a 64-bit NTP timestamp (RFC 5905) back to an ISO 8601 instant string.
+ *
+ * - `value` is unsigned: the whole 64-bit timestamp, seconds since 1900-01-01 in the high
+ *   32 bits and 2^-32 s units in the low 32. Values outside `0n`–`2^64 − 1` are rejected.
+ * - **`era` is required information the value does not carry.** The seconds field wraps
+ *   every 2^32 seconds (~136.19 years), so one timestamp names one instant per era: era 0
+ *   is 1900-01-01 to 2036-02-07T06:28:15Z, era 1 starts at 2036-02-07T06:28:16Z, era -1
+ *   starts at 1763-11-24T17:31:44Z. It defaults to 0; `undefined` is the same as
+ *   omitting it, as TC39 treats an undefined argument as absent.
+ * - Rounds to the nearest nanosecond. One NTP unit is ~233 ps, finer than an ISO string can
+ *   express, so rounding — not truncation — is what makes `fromNtpTimestamp(toNtpTimestamp(iso))`
+ *   return `iso` exactly rather than one nanosecond early.
+ * - **The top two values of an era round onto the next era's first instant.** `2^64 − 1` and
+ *   `2^64 − 2` in era 0 both render as `"2036-02-07T06:28:16Z"`, which is where era 1 starts:
+ *   the last 0.47 ns of an era has no nanosecond of its own, and the nearest one is the era
+ *   boundary. `toNtpTimestamp` cannot produce either value from a nanosecond-precision
+ *   instant — its largest era-0 output is `18446744073709551611n` — so this does not affect
+ *   the round trip.
+ * - **`0n` is two things on the wire.** RFC 5905 §6 defines the prime epoch as the instant
+ *   "when all bits are zero", and also says "a value of zero is a special case representing
+ *   unknown or unsynchronized time" — for example a reference timestamp sent before the first
+ *   sync. This function decodes `0n` as the era's first instant; a caller reading packet
+ *   fields should test for `0n` first when "unsynchronized" must not become a 1900 date.
+ * - Returns "" when the resulting instant is outside the range `Temporal.Instant` can
+ *   represent, which a large `era` will reach.
+ * - Returns "" on invalid input.
+ *
+ * @param value 64-bit NTP timestamp (bigint, 0n to 2^64 − 1)
+ * @param eraArg optional 136-year era selector; omitted or `undefined` is era 0
+ * @returns ISO 8601 instant string (UTC), or "" on invalid input
+ *
+ * @example fromNtpTimestamp(0n) // "1900-01-01T00:00:00Z" — the NTP epoch, and also RFC 5905's unknown or unsynchronized marker
+ * @example fromNtpTimestamp(9487534653230284800n) // "1970-01-01T00:00:00Z"
+ * @example fromNtpTimestamp(16832246972675778412n) // "2024-03-10T12:34:56.789Z"
+ * @example fromNtpTimestamp(18446744069414584320n) // "2036-02-07T06:28:15Z" — the last second of era 0
+ * @example fromNtpTimestamp(0n, 1) // "2036-02-07T06:28:16Z" — the same value, one era on
+ * @example fromNtpTimestamp(0n, -1) // "1763-11-24T17:31:44Z"
+ * @example fromNtpTimestamp(-1n) // "" — the timestamp is unsigned
+ * @example fromNtpTimestamp(0n, undefined) // "1900-01-01T00:00:00Z" — undefined is era 0, as omitted
+ * @example fromNtpTimestamp(0n, 1.5) // "" — an era must be a safe integer
+ */
+export declare function fromNtpTimestamp(value: bigint, eraArg?: number): string;

package/dist/precision/convert/fromNtpTimestamp.js

@@ -0,0 +1,57 @@
+import { floorDivide, NANOSECONDS_PER_SECOND, NTP_EPOCH_OFFSET_NANOSECONDS, NTP_ERA_UNITS, NTP_UNITS_PER_SECOND, } from "../../internal/index.js";
+import { fromNanoseconds } from "./fromNanoseconds.js";
+/**
+ * Convert a 64-bit NTP timestamp (RFC 5905) back to an ISO 8601 instant string.
+ *
+ * - `value` is unsigned: the whole 64-bit timestamp, seconds since 1900-01-01 in the high
+ *   32 bits and 2^-32 s units in the low 32. Values outside `0n`–`2^64 − 1` are rejected.
+ * - **`era` is required information the value does not carry.** The seconds field wraps
+ *   every 2^32 seconds (~136.19 years), so one timestamp names one instant per era: era 0
+ *   is 1900-01-01 to 2036-02-07T06:28:15Z, era 1 starts at 2036-02-07T06:28:16Z, era -1
+ *   starts at 1763-11-24T17:31:44Z. It defaults to 0; `undefined` is the same as
+ *   omitting it, as TC39 treats an undefined argument as absent.
+ * - Rounds to the nearest nanosecond. One NTP unit is ~233 ps, finer than an ISO string can
+ *   express, so rounding — not truncation — is what makes `fromNtpTimestamp(toNtpTimestamp(iso))`
+ *   return `iso` exactly rather than one nanosecond early.
+ * - **The top two values of an era round onto the next era's first instant.** `2^64 − 1` and
+ *   `2^64 − 2` in era 0 both render as `"2036-02-07T06:28:16Z"`, which is where era 1 starts:
+ *   the last 0.47 ns of an era has no nanosecond of its own, and the nearest one is the era
+ *   boundary. `toNtpTimestamp` cannot produce either value from a nanosecond-precision
+ *   instant — its largest era-0 output is `18446744073709551611n` — so this does not affect
+ *   the round trip.
+ * - **`0n` is two things on the wire.** RFC 5905 §6 defines the prime epoch as the instant
+ *   "when all bits are zero", and also says "a value of zero is a special case representing
+ *   unknown or unsynchronized time" — for example a reference timestamp sent before the first
+ *   sync. This function decodes `0n` as the era's first instant; a caller reading packet
+ *   fields should test for `0n` first when "unsynchronized" must not become a 1900 date.
+ * - Returns "" when the resulting instant is outside the range `Temporal.Instant` can
+ *   represent, which a large `era` will reach.
+ * - Returns "" on invalid input.
+ *
+ * @param value 64-bit NTP timestamp (bigint, 0n to 2^64 − 1)
+ * @param eraArg optional 136-year era selector; omitted or `undefined` is era 0
+ * @returns ISO 8601 instant string (UTC), or "" on invalid input
+ *
+ * @example fromNtpTimestamp(0n) // "1900-01-01T00:00:00Z" — the NTP epoch, and also RFC 5905's unknown or unsynchronized marker
+ * @example fromNtpTimestamp(9487534653230284800n) // "1970-01-01T00:00:00Z"
+ * @example fromNtpTimestamp(16832246972675778412n) // "2024-03-10T12:34:56.789Z"
+ * @example fromNtpTimestamp(18446744069414584320n) // "2036-02-07T06:28:15Z" — the last second of era 0
+ * @example fromNtpTimestamp(0n, 1) // "2036-02-07T06:28:16Z" — the same value, one era on
+ * @example fromNtpTimestamp(0n, -1) // "1763-11-24T17:31:44Z"
+ * @example fromNtpTimestamp(-1n) // "" — the timestamp is unsigned
+ * @example fromNtpTimestamp(0n, undefined) // "1900-01-01T00:00:00Z" — undefined is era 0, as omitted
+ * @example fromNtpTimestamp(0n, 1.5) // "" — an era must be a safe integer
+ */
+export function fromNtpTimestamp(value, eraArg) {
+    if (typeof value !== "bigint" || value < 0n || value >= NTP_ERA_UNITS) {
+        return "";
+    }
+    // An explicit `undefined` is the same as omitting the argument (TC39 optional parameters).
+    const era = eraArg === undefined ? 0 : eraArg;
+    if (typeof era !== "number" || !Number.isSafeInteger(era)) {
+        return "";
+    }
+    const units = value + BigInt(era) * NTP_ERA_UNITS;
+    const nanoseconds = floorDivide(units * NANOSECONDS_PER_SECOND + NTP_UNITS_PER_SECOND / 2n, NTP_UNITS_PER_SECOND) - NTP_EPOCH_OFFSET_NANOSECONDS;
+    return fromNanoseconds(nanoseconds);
+}