@northguild/gmt 1.14.2 → 1.16.0

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);
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Convert PostgreSQL's internal `timestamptz` value back to an ISO 8601 instant string.
+ *
+ * - `value` is a signed count of microseconds since 2000-01-01T00:00:00Z, the number
+ *   PostgreSQL stores and the binary wire format carries. It is not a Unix timestamp.
+ * - Accepted range is the narrower of PostgreSQL's and `Temporal.Instant`'s, one binding at
+ *   each end: `-211813488000000000n` (`MIN_TIMESTAMP`, `-004713-11-24T00:00:00Z` — the
+ *   manual's "4713 BC", counted in the Julian calendar) up to `8639053315200000000n`
+ *   (`+275760-09-13`, where `Temporal` stops, well before PostgreSQL's 294276 AD).
+ *   Anything outside returns "".
+ * - Exact in this direction — a microsecond is coarser than the nanoseconds an ISO string
+ *   carries, so nothing is rounded. The loss, if any, happened in `toPgMicroseconds`.
+ * - Returns "" on invalid input.
+ *
+ * @param value microseconds since 2000-01-01 (bigint)
+ * @returns ISO 8601 instant string (UTC), or "" on invalid input
+ *
+ * @example fromPgMicroseconds(0n) // "2000-01-01T00:00:00Z" — the PostgreSQL epoch
+ * @example fromPgMicroseconds(-946684800000000n) // "1970-01-01T00:00:00Z"
+ * @example fromPgMicroseconds(763389296789000n) // "2024-03-10T12:34:56.789Z"
+ * @example fromPgMicroseconds(763387200123456n) // "2024-03-10T12:00:00.123456Z"
+ * @example fromPgMicroseconds(-211813488000000001n) // "" — one microsecond before PostgreSQL's minimum
+ * @example fromPgMicroseconds(9223372036854775807n) // "" — int64 maximum, still past Temporal's range
+ * @example fromPgMicroseconds(763387200123456) // "" — number, not bigint
+ */
+export declare function fromPgMicroseconds(value: bigint): string;

package/dist/precision/convert/fromPgMicroseconds.js

@@ -0,0 +1,33 @@
+import { MIN_PG_MICROSECONDS, NANOSECONDS_PER_MICROSECOND, PG_EPOCH_OFFSET_MICROSECONDS, } from "../../internal/index.js";
+import { fromNanoseconds } from "./fromNanoseconds.js";
+/**
+ * Convert PostgreSQL's internal `timestamptz` value back to an ISO 8601 instant string.
+ *
+ * - `value` is a signed count of microseconds since 2000-01-01T00:00:00Z, the number
+ *   PostgreSQL stores and the binary wire format carries. It is not a Unix timestamp.
+ * - Accepted range is the narrower of PostgreSQL's and `Temporal.Instant`'s, one binding at
+ *   each end: `-211813488000000000n` (`MIN_TIMESTAMP`, `-004713-11-24T00:00:00Z` — the
+ *   manual's "4713 BC", counted in the Julian calendar) up to `8639053315200000000n`
+ *   (`+275760-09-13`, where `Temporal` stops, well before PostgreSQL's 294276 AD).
+ *   Anything outside returns "".
+ * - Exact in this direction — a microsecond is coarser than the nanoseconds an ISO string
+ *   carries, so nothing is rounded. The loss, if any, happened in `toPgMicroseconds`.
+ * - Returns "" on invalid input.
+ *
+ * @param value microseconds since 2000-01-01 (bigint)
+ * @returns ISO 8601 instant string (UTC), or "" on invalid input
+ *
+ * @example fromPgMicroseconds(0n) // "2000-01-01T00:00:00Z" — the PostgreSQL epoch
+ * @example fromPgMicroseconds(-946684800000000n) // "1970-01-01T00:00:00Z"
+ * @example fromPgMicroseconds(763389296789000n) // "2024-03-10T12:34:56.789Z"
+ * @example fromPgMicroseconds(763387200123456n) // "2024-03-10T12:00:00.123456Z"
+ * @example fromPgMicroseconds(-211813488000000001n) // "" — one microsecond before PostgreSQL's minimum
+ * @example fromPgMicroseconds(9223372036854775807n) // "" — int64 maximum, still past Temporal's range
+ * @example fromPgMicroseconds(763387200123456) // "" — number, not bigint
+ */
+export function fromPgMicroseconds(value) {
+    if (typeof value !== "bigint" || value < MIN_PG_MICROSECONDS) {
+        return "";
+    }
+    return fromNanoseconds((value + PG_EPOCH_OFFSET_MICROSECONDS) * NANOSECONDS_PER_MICROSECOND);
+}

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

@@ -0,0 +1,12 @@
+export * from "./fromDotNetTicks.js";
+export * from "./fromExcelSerial.js";
+export * from "./fromFileTime.js";
+export * from "./fromNanoseconds.js";
+export * from "./fromNtpTimestamp.js";
+export * from "./fromPgMicroseconds.js";
+export * from "./toDotNetTicks.js";
+export * from "./toExcelSerial.js";
+export * from "./toFileTime.js";
+export * from "./toNanoseconds.js";
+export * from "./toNtpTimestamp.js";
+export * from "./toPgMicroseconds.js";

package/dist/precision/convert/index.js

@@ -0,0 +1,12 @@
+export * from "./fromDotNetTicks.js";
+export * from "./fromExcelSerial.js";
+export * from "./fromFileTime.js";
+export * from "./fromNanoseconds.js";
+export * from "./fromNtpTimestamp.js";
+export * from "./fromPgMicroseconds.js";
+export * from "./toDotNetTicks.js";
+export * from "./toExcelSerial.js";
+export * from "./toFileTime.js";
+export * from "./toNanoseconds.js";
+export * from "./toNtpTimestamp.js";
+export * from "./toPgMicroseconds.js";

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

@@ -0,0 +1,29 @@
+/**
+ * Convert an ISO 8601 instant string to .NET `DateTime.Ticks`.
+ *
+ * - Ticks count 100-nanosecond intervals since 0001-01-01T00:00:00 in the proleptic
+ *   Gregorian calendar — the same unit as `FILETIME`, a different origin. The two differ by
+ *   `504911232000000000n`, the tick count at 1601-01-01.
+ * - Sub-100 ns digits floor away, toward negative infinity, so the tick grid stays uniform
+ *   either side of the epoch. Reach for `truncateNanoseconds` first if the caller needs to
+ *   see the loss.
+ * - **The range is `DateTime`'s own, and instants outside it are invalid input, not a
+ *   negative tick count:** `DateTime.MinValue` (`0n`, 0001-01-01) to `DateTime.MaxValue`
+ *   (`3155378975999999999n`, 9999-12-31T23:59:59.9999999).
+ * - The result is a bare tick count, with no `DateTimeKind`. .NET stores the kind in the top
+ *   two bits of `DateTime`'s backing field, not in `Ticks`; treat the value as UTC.
+ * - Returns `0n` on invalid input. `0n` is also `DateTime.MinValue` itself (0001-01-01) —
+ *   validate the string first with `isValidInstant` when the two must be told apart.
+ *
+ * @param isoString ISO 8601 instant string (e.g. "2024-03-10T12:00:00Z")
+ * @returns 100-nanosecond intervals since 0001-01-01 as a bigint, or 0n on invalid input
+ *
+ * @example toDotNetTicks("0001-01-01T00:00:00Z") // 0n — DateTime.MinValue
+ * @example toDotNetTicks("1970-01-01T00:00:00Z") // 621355968000000000n
+ * @example toDotNetTicks("2024-03-10T12:34:56.789Z") // 638456708967890000n
+ * @example toDotNetTicks("2024-03-10T12:00:00.123456789Z") // 638456688001234567n — floors to 100 ns
+ * @example toDotNetTicks("9999-12-31T23:59:59.9999999Z") // 3155378975999999999n — DateTime.MaxValue
+ * @example toDotNetTicks("+010000-01-01T00:00:00Z") // 0n — past DateTime.MaxValue
+ * @example toDotNetTicks("invalid") // 0n
+ */
+export declare function toDotNetTicks(isoString: string): bigint;

package/dist/precision/convert/toDotNetTicks.js

@@ -0,0 +1,40 @@
+import { DOT_NET_TICKS_EPOCH_OFFSET, floorDivide, MAX_DOT_NET_TICKS, MIN_DOT_NET_TICKS, NANOSECONDS_PER_TICK, parseInstantNanoseconds, } from "../../internal/index.js";
+/**
+ * Convert an ISO 8601 instant string to .NET `DateTime.Ticks`.
+ *
+ * - Ticks count 100-nanosecond intervals since 0001-01-01T00:00:00 in the proleptic
+ *   Gregorian calendar — the same unit as `FILETIME`, a different origin. The two differ by
+ *   `504911232000000000n`, the tick count at 1601-01-01.
+ * - Sub-100 ns digits floor away, toward negative infinity, so the tick grid stays uniform
+ *   either side of the epoch. Reach for `truncateNanoseconds` first if the caller needs to
+ *   see the loss.
+ * - **The range is `DateTime`'s own, and instants outside it are invalid input, not a
+ *   negative tick count:** `DateTime.MinValue` (`0n`, 0001-01-01) to `DateTime.MaxValue`
+ *   (`3155378975999999999n`, 9999-12-31T23:59:59.9999999).
+ * - The result is a bare tick count, with no `DateTimeKind`. .NET stores the kind in the top
+ *   two bits of `DateTime`'s backing field, not in `Ticks`; treat the value as UTC.
+ * - Returns `0n` on invalid input. `0n` is also `DateTime.MinValue` itself (0001-01-01) —
+ *   validate the string first with `isValidInstant` when the two must be told apart.
+ *
+ * @param isoString ISO 8601 instant string (e.g. "2024-03-10T12:00:00Z")
+ * @returns 100-nanosecond intervals since 0001-01-01 as a bigint, or 0n on invalid input
+ *
+ * @example toDotNetTicks("0001-01-01T00:00:00Z") // 0n — DateTime.MinValue
+ * @example toDotNetTicks("1970-01-01T00:00:00Z") // 621355968000000000n
+ * @example toDotNetTicks("2024-03-10T12:34:56.789Z") // 638456708967890000n
+ * @example toDotNetTicks("2024-03-10T12:00:00.123456789Z") // 638456688001234567n — floors to 100 ns
+ * @example toDotNetTicks("9999-12-31T23:59:59.9999999Z") // 3155378975999999999n — DateTime.MaxValue
+ * @example toDotNetTicks("+010000-01-01T00:00:00Z") // 0n — past DateTime.MaxValue
+ * @example toDotNetTicks("invalid") // 0n
+ */
+export function toDotNetTicks(isoString) {
+    const nanoseconds = parseInstantNanoseconds(isoString);
+    if (nanoseconds === null) {
+        return 0n;
+    }
+    const ticks = floorDivide(nanoseconds, NANOSECONDS_PER_TICK) + DOT_NET_TICKS_EPOCH_OFFSET;
+    if (ticks < MIN_DOT_NET_TICKS || ticks > MAX_DOT_NET_TICKS) {
+        return 0n;
+    }
+    return ticks;
+}

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

@@ -0,0 +1,56 @@
+/**
+ * Which Excel date system a serial belongs to.
+ *
+ * @remarks Members:
+ *
+ * | Member | Description |
+ * | --- | --- |
+ * | `"1900"` | The default, on every platform since Excel 2011 for Mac. Serial 1 is 1900-01-01, and serial 60 is the phantom 1900-02-29. |
+ * | `"1904"` | The legacy Mac system, still found in workbooks authored on Excel 2008 for Mac and earlier. Serial 0 is 1904-01-01, and there is no phantom day. |
+ */
+export type ExcelDateSystem = "1900" | "1904";
+/**
+ * Convert an ISO 8601 instant string to an Excel day serial.
+ *
+ * - The serial is days, with the time of day as the fraction: 45361.5 is midday on
+ *   2024-03-10. The date is the UTC wall clock — a zoned input is converted to UTC first,
+ *   so `"2024-03-10T12:00:00-05:00"` is serial 45361.708…, the 17:00 UTC it names.
+ * - **The 1900 system's serial 60 is the phantom 29 February 1900**, a date that never
+ *   existed — 1900 was not a leap year. Lotus 1-2-3 got it wrong and Excel keeps the bug for
+ *   compatibility. No instant maps to serial 60: 1900-02-28 is 59 and 1900-03-01 is 61.
+ *   Silently "fixing" this would put GMT one day out from Excel for every date before March
+ *   1900.
+ * - `{ system: "1904" }` selects the legacy Mac system, whose serial 0 is 1904-01-01. The
+ *   same instant is exactly 1462 lower there than in the 1900 system.
+ * - **Instants outside Excel's own serial range are invalid input**, not an out-of-range
+ *   number: the 1900 system runs from serial 1 (1900-01-01) to 2958465 (9999-12-31), the
+ *   1904 system from serial 0 (1904-01-01) to 2957003. Serial 0 in the 1900 system is
+ *   Excel's "January 0, 1900" placeholder, not a date, so it is rejected too.
+ * - The serial is a `double`, as it is in a workbook. The whole-day part is exact; the
+ *   intra-day fraction is not, so precision below roughly a microsecond is not
+ *   representable, and it degrades toward year 9999. Round-tripping through
+ *   `fromExcelSerial` is exact to the millisecond, which is as fine as Excel itself goes.
+ * - **The last ~20 µs of 9999-12-31 returns null**, from
+ *   `"9999-12-31T23:59:59.999979884Z"` on. A `double` near serial 2958465 resolves to about
+ *   40 µs, so those instants round to exactly 2958466 — one past Excel's last serial. The
+ *   range check is deliberately made on the rounded serial rather than the exact instant, so
+ *   a returned number is always one Excel accepts; the alternative is handing back a 2958466
+ *   that Excel rejects on the way in.
+ *
+ * @param isoString ISO 8601 instant string (e.g. "2024-03-10T12:00:00Z")
+ * @param options optional: system ("1900" (default) | "1904")
+ * @returns Excel day serial as a number, or null on invalid input
+ *
+ * @example toExcelSerial("1900-01-01T00:00:00Z") // 1 — Excel's first serial
+ * @example toExcelSerial("1970-01-01T00:00:00Z") // 25569
+ * @example toExcelSerial("2024-03-10T12:00:00Z") // 45361.5
+ * @example toExcelSerial("1900-02-28T00:00:00Z") // 59 — the next day is 61, not 60
+ * @example toExcelSerial("1900-03-01T00:00:00Z") // 61 — serial 60 is the phantom 1900-02-29
+ * @example toExcelSerial("2024-03-10T12:00:00Z", { system: "1904" }) // 43899.5 — exactly 1462 lower
+ * @example toExcelSerial("1899-12-31T00:00:00Z") // null — Excel's "January 0", not a date
+ * @example toExcelSerial("9999-12-31T23:59:59.99998Z") // null — rounds to 2958466, one past Excel's last serial
+ * @example toExcelSerial("invalid") // null
+ */
+export declare function toExcelSerial(isoString: string, options?: {
+    system?: ExcelDateSystem;
+}): number | null;

package/dist/precision/convert/toExcelSerial.js

@@ -0,0 +1,85 @@
+import { EXCEL_1900_EPOCH_NANOSECONDS, EXCEL_1900_PHANTOM_END_NANOSECONDS, EXCEL_1900_PRE_PHANTOM_EPOCH_NANOSECONDS, EXCEL_1904_EPOCH_NANOSECONDS, floorDivide, MAX_EXCEL_1900_SERIAL_EXCLUSIVE, MAX_EXCEL_1904_SERIAL_EXCLUSIVE, MIN_EXCEL_1900_SERIAL, MIN_EXCEL_1904_SERIAL, NANOSECONDS_PER_DAY, NANOSECONDS_PER_DAY_NUMBER, parseInstantNanoseconds, } from "../../internal/index.js";
+import { isOptionsArgument } from "../../internal/isObject.js";
+/**
+ * Convert an ISO 8601 instant string to an Excel day serial.
+ *
+ * - The serial is days, with the time of day as the fraction: 45361.5 is midday on
+ *   2024-03-10. The date is the UTC wall clock — a zoned input is converted to UTC first,
+ *   so `"2024-03-10T12:00:00-05:00"` is serial 45361.708…, the 17:00 UTC it names.
+ * - **The 1900 system's serial 60 is the phantom 29 February 1900**, a date that never
+ *   existed — 1900 was not a leap year. Lotus 1-2-3 got it wrong and Excel keeps the bug for
+ *   compatibility. No instant maps to serial 60: 1900-02-28 is 59 and 1900-03-01 is 61.
+ *   Silently "fixing" this would put GMT one day out from Excel for every date before March
+ *   1900.
+ * - `{ system: "1904" }` selects the legacy Mac system, whose serial 0 is 1904-01-01. The
+ *   same instant is exactly 1462 lower there than in the 1900 system.
+ * - **Instants outside Excel's own serial range are invalid input**, not an out-of-range
+ *   number: the 1900 system runs from serial 1 (1900-01-01) to 2958465 (9999-12-31), the
+ *   1904 system from serial 0 (1904-01-01) to 2957003. Serial 0 in the 1900 system is
+ *   Excel's "January 0, 1900" placeholder, not a date, so it is rejected too.
+ * - The serial is a `double`, as it is in a workbook. The whole-day part is exact; the
+ *   intra-day fraction is not, so precision below roughly a microsecond is not
+ *   representable, and it degrades toward year 9999. Round-tripping through
+ *   `fromExcelSerial` is exact to the millisecond, which is as fine as Excel itself goes.
+ * - **The last ~20 µs of 9999-12-31 returns null**, from
+ *   `"9999-12-31T23:59:59.999979884Z"` on. A `double` near serial 2958465 resolves to about
+ *   40 µs, so those instants round to exactly 2958466 — one past Excel's last serial. The
+ *   range check is deliberately made on the rounded serial rather than the exact instant, so
+ *   a returned number is always one Excel accepts; the alternative is handing back a 2958466
+ *   that Excel rejects on the way in.
+ *
+ * @param isoString ISO 8601 instant string (e.g. "2024-03-10T12:00:00Z")
+ * @param options optional: system ("1900" (default) | "1904")
+ * @returns Excel day serial as a number, or null on invalid input
+ *
+ * @example toExcelSerial("1900-01-01T00:00:00Z") // 1 — Excel's first serial
+ * @example toExcelSerial("1970-01-01T00:00:00Z") // 25569
+ * @example toExcelSerial("2024-03-10T12:00:00Z") // 45361.5
+ * @example toExcelSerial("1900-02-28T00:00:00Z") // 59 — the next day is 61, not 60
+ * @example toExcelSerial("1900-03-01T00:00:00Z") // 61 — serial 60 is the phantom 1900-02-29
+ * @example toExcelSerial("2024-03-10T12:00:00Z", { system: "1904" }) // 43899.5 — exactly 1462 lower
+ * @example toExcelSerial("1899-12-31T00:00:00Z") // null — Excel's "January 0", not a date
+ * @example toExcelSerial("9999-12-31T23:59:59.99998Z") // null — rounds to 2958466, one past Excel's last serial
+ * @example toExcelSerial("invalid") // null
+ */
+export function toExcelSerial(isoString, options) {
+    try {
+        if (!isOptionsArgument(options)) {
+            return null;
+        }
+        const system = options?.system === undefined ? "1900" : options.system;
+        if (system !== "1900" && system !== "1904") {
+            return null;
+        }
+        const nanoseconds = parseInstantNanoseconds(isoString);
+        if (nanoseconds === null) {
+            return null;
+        }
+        const epochNanoseconds = system === "1904"
+            ? EXCEL_1904_EPOCH_NANOSECONDS
+            : nanoseconds >= EXCEL_1900_PHANTOM_END_NANOSECONDS
+                ? EXCEL_1900_EPOCH_NANOSECONDS
+                : EXCEL_1900_PRE_PHANTOM_EPOCH_NANOSECONDS;
+        // Split the day count from the intra-day remainder so the whole-day part stays exact:
+        // a single `Number(...) / 86400e9` would round the day count through the same double as
+        // the fraction, and the serials Excel actually stores are mostly whole days.
+        const sinceEpoch = nanoseconds - epochNanoseconds;
+        const days = floorDivide(sinceEpoch, NANOSECONDS_PER_DAY);
+        const serial = Number(days) +
+            Number(sinceEpoch - days * NANOSECONDS_PER_DAY) /
+                NANOSECONDS_PER_DAY_NUMBER;
+        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 (serial < minimum || serial >= maximumExclusive) {
+            return null;
+        }
+        return serial;
+    }
+    catch {
+        // Never throws (Core Rule 3): a hostile
+        // argument is invalid input, not an exception.
+        return null;
+    }
+}

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

@@ -0,0 +1,31 @@
+/**
+ * Convert an ISO 8601 instant string to a Windows `FILETIME`.
+ *
+ * - A `FILETIME` counts 100-nanosecond intervals since 1601-01-01T00:00:00Z. The Unix delta
+ *   is 11 644 473 600 seconds, i.e. `116444736000000000n` ticks.
+ * - Sub-100 ns digits floor away, toward negative infinity, so the tick grid stays uniform
+ *   either side of the epoch. Reach for `truncateNanoseconds` first if the caller needs to
+ *   see the loss.
+ * - **The range is the format's own, and instants outside it are invalid input, not a
+ *   negative tick count.** The range is `0n` to `2^63 − 1` — 1601-01-01 to
+ *   `+030828-09-14T02:48:05.4775807Z`. The struct's two `DWORD`s could hold more, but
+ *   Microsoft's `FileTimeToSystemTime` requires a value "less than 0x8000000000000000", and
+ *   `SetFileTime` reserves `2^64 − 1` as a "do not modify" marker. Consumers commonly narrow
+ *   this further: .NET's `DateTime.FromFileTimeUtc` stops at 9999-12-31.
+ * - Returns `0n` on invalid input. `0n` is also the FILETIME epoch itself (1601-01-01) —
+ *   validate the string first with `isValidInstant` when the two must be told apart.
+ *
+ * @param isoString ISO 8601 instant string (e.g. "2024-03-10T12:00:00Z")
+ * @returns 100-nanosecond intervals since 1601-01-01 as a bigint, or 0n on invalid input
+ *
+ * @example toFileTime("1601-01-01T00:00:00Z") // 0n — the FILETIME epoch
+ * @example toFileTime("1970-01-01T00:00:00Z") // 116444736000000000n
+ * @example toFileTime("2024-03-10T12:34:56.789Z") // 133545476967890000n
+ * @example toFileTime("2024-03-10T12:00:00.123456789Z") // 133545456001234567n — floors to 100 ns
+ * @example toFileTime("1600-12-31T23:59:59Z") // 0n — before the FILETIME epoch
+ * @example toFileTime("+030828-09-14T02:48:05.4775807Z") // 9223372036854775807n — 2^63 − 1, the largest FILETIME
+ * @example toFileTime("+030828-09-14T02:48:05.4775808Z") // 0n — 2^63, which FileTimeToSystemTime rejects
+ * @example toFileTime("2024-03-10T12:00:00") // 0n — no offset designator
+ * @example toFileTime("invalid") // 0n
+ */
+export declare function toFileTime(isoString: string): bigint;

package/dist/precision/convert/toFileTime.js

@@ -0,0 +1,43 @@
+import { FILE_TIME_EPOCH_OFFSET_TICKS, floorDivide, MAX_FILE_TIME, MIN_FILE_TIME, NANOSECONDS_PER_TICK, parseInstantNanoseconds, } from "../../internal/index.js";
+/**
+ * Convert an ISO 8601 instant string to a Windows `FILETIME`.
+ *
+ * - A `FILETIME` counts 100-nanosecond intervals since 1601-01-01T00:00:00Z. The Unix delta
+ *   is 11 644 473 600 seconds, i.e. `116444736000000000n` ticks.
+ * - Sub-100 ns digits floor away, toward negative infinity, so the tick grid stays uniform
+ *   either side of the epoch. Reach for `truncateNanoseconds` first if the caller needs to
+ *   see the loss.
+ * - **The range is the format's own, and instants outside it are invalid input, not a
+ *   negative tick count.** The range is `0n` to `2^63 − 1` — 1601-01-01 to
+ *   `+030828-09-14T02:48:05.4775807Z`. The struct's two `DWORD`s could hold more, but
+ *   Microsoft's `FileTimeToSystemTime` requires a value "less than 0x8000000000000000", and
+ *   `SetFileTime` reserves `2^64 − 1` as a "do not modify" marker. Consumers commonly narrow
+ *   this further: .NET's `DateTime.FromFileTimeUtc` stops at 9999-12-31.
+ * - Returns `0n` on invalid input. `0n` is also the FILETIME epoch itself (1601-01-01) —
+ *   validate the string first with `isValidInstant` when the two must be told apart.
+ *
+ * @param isoString ISO 8601 instant string (e.g. "2024-03-10T12:00:00Z")
+ * @returns 100-nanosecond intervals since 1601-01-01 as a bigint, or 0n on invalid input
+ *
+ * @example toFileTime("1601-01-01T00:00:00Z") // 0n — the FILETIME epoch
+ * @example toFileTime("1970-01-01T00:00:00Z") // 116444736000000000n
+ * @example toFileTime("2024-03-10T12:34:56.789Z") // 133545476967890000n
+ * @example toFileTime("2024-03-10T12:00:00.123456789Z") // 133545456001234567n — floors to 100 ns
+ * @example toFileTime("1600-12-31T23:59:59Z") // 0n — before the FILETIME epoch
+ * @example toFileTime("+030828-09-14T02:48:05.4775807Z") // 9223372036854775807n — 2^63 − 1, the largest FILETIME
+ * @example toFileTime("+030828-09-14T02:48:05.4775808Z") // 0n — 2^63, which FileTimeToSystemTime rejects
+ * @example toFileTime("2024-03-10T12:00:00") // 0n — no offset designator
+ * @example toFileTime("invalid") // 0n
+ */
+export function toFileTime(isoString) {
+    const nanoseconds = parseInstantNanoseconds(isoString);
+    if (nanoseconds === null) {
+        return 0n;
+    }
+    const ticks = floorDivide(nanoseconds, NANOSECONDS_PER_TICK) +
+        FILE_TIME_EPOCH_OFFSET_TICKS;
+    if (ticks < MIN_FILE_TIME || ticks > MAX_FILE_TIME) {
+        return 0n;
+    }
+    return ticks;
+}

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

@@ -0,0 +1,37 @@
+/**
+ * Convert an ISO 8601 instant string to nanoseconds since the Unix epoch.
+ *
+ * - Requires an offset designator (`Z`, `±HH:MM`), as `Temporal.Instant` does — date-only
+ *   and offset-less strings are rejected.
+ * - Accepts a bracketed IANA time zone annotation and a `[u-ca=...]` calendar annotation, both
+ *   ignored as `Temporal.Instant.from` ignores them (an instant has no calendar).
+ * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
+ *   ignored: the offset alone fixes the instant, and a zone that does not exist or disagrees
+ *   with the offset is not checked.
+ * - ISO 8601 extended format before any annotation: `<date>T<time>`, then
+ *   `Z` or `±HH:MM[:SS[.fraction]]`. Basic format, a space or lower-case `t` separator, a
+ *   lower-case `z` and an hour-only time or offset return `0n`, although
+ *   `Temporal.Instant.from` reads them. The offsets make this wider than `isValidUtc`, which
+ *   requires `Z`.
+ * - Rejects leap seconds (`"2016-12-31T23:59:60Z"`), which Temporal would silently clamp —
+ *   in every separator and format variant it accepts, `"20161231 235960Z"` included.
+ * - Returns `bigint`, not `number`: nanoseconds since the epoch passed
+ *   `Number.MAX_SAFE_INTEGER` in April 1970, so a `number` cannot hold them.
+ * - Returns `0n` on invalid input. `0n` is also the epoch itself — use `isValidInstant`,
+ *   which accepts exactly this grammar, when the two must be told apart. **Not
+ *   `isValidUtc`**: it gates on GMT's stricter `<date>T<time>Z` shape and returns `false`
+ *   for the offsets and bracketed zones this function accepts, so validating with it discards valid input.
+ *
+ * @param isoString ISO 8601 instant string (e.g. "2024-03-10T12:00:00.123456789Z")
+ * @returns nanoseconds since the Unix epoch as a bigint, or 0n on invalid input
+ *
+ * @example toNanoseconds("1970-01-01T00:00:00Z") // 0n
+ * @example toNanoseconds("2024-03-10T12:00:00.123456789Z") // 1710072000123456789n
+ * @example toNanoseconds("1969-12-31T23:59:59Z") // -1000000000n
+ * @example toNanoseconds("2024-03-10T12:00:00-05:00[America/New_York]") // 1710090000000000000n
+ * @example toNanoseconds("2024-03-10T12:00:00+05:00[America/New_York]") // 1710054000000000000n — the offset decides, the zone is ignored
+ * @example toNanoseconds("2024-03-10T12:00:00") // 0n — no offset designator
+ * @example toNanoseconds("20240310T120000Z") // 0n — basic format
+ * @example toNanoseconds("invalid") // 0n
+ */
+export declare function toNanoseconds(isoString: string): bigint;

package/dist/precision/convert/toNanoseconds.js

@@ -0,0 +1,40 @@
+import { parseInstantNanoseconds } from "../../internal/index.js";
+/**
+ * Convert an ISO 8601 instant string to nanoseconds since the Unix epoch.
+ *
+ * - Requires an offset designator (`Z`, `±HH:MM`), as `Temporal.Instant` does — date-only
+ *   and offset-less strings are rejected.
+ * - Accepts a bracketed IANA time zone annotation and a `[u-ca=...]` calendar annotation, both
+ *   ignored as `Temporal.Instant.from` ignores them (an instant has no calendar).
+ * - **A bracketed zone annotation is syntactic only.** As in `Temporal.Instant.from`, it is
+ *   ignored: the offset alone fixes the instant, and a zone that does not exist or disagrees
+ *   with the offset is not checked.
+ * - ISO 8601 extended format before any annotation: `<date>T<time>`, then
+ *   `Z` or `±HH:MM[:SS[.fraction]]`. Basic format, a space or lower-case `t` separator, a
+ *   lower-case `z` and an hour-only time or offset return `0n`, although
+ *   `Temporal.Instant.from` reads them. The offsets make this wider than `isValidUtc`, which
+ *   requires `Z`.
+ * - Rejects leap seconds (`"2016-12-31T23:59:60Z"`), which Temporal would silently clamp —
+ *   in every separator and format variant it accepts, `"20161231 235960Z"` included.
+ * - Returns `bigint`, not `number`: nanoseconds since the epoch passed
+ *   `Number.MAX_SAFE_INTEGER` in April 1970, so a `number` cannot hold them.
+ * - Returns `0n` on invalid input. `0n` is also the epoch itself — use `isValidInstant`,
+ *   which accepts exactly this grammar, when the two must be told apart. **Not
+ *   `isValidUtc`**: it gates on GMT's stricter `<date>T<time>Z` shape and returns `false`
+ *   for the offsets and bracketed zones this function accepts, so validating with it discards valid input.
+ *
+ * @param isoString ISO 8601 instant string (e.g. "2024-03-10T12:00:00.123456789Z")
+ * @returns nanoseconds since the Unix epoch as a bigint, or 0n on invalid input
+ *
+ * @example toNanoseconds("1970-01-01T00:00:00Z") // 0n
+ * @example toNanoseconds("2024-03-10T12:00:00.123456789Z") // 1710072000123456789n
+ * @example toNanoseconds("1969-12-31T23:59:59Z") // -1000000000n
+ * @example toNanoseconds("2024-03-10T12:00:00-05:00[America/New_York]") // 1710090000000000000n
+ * @example toNanoseconds("2024-03-10T12:00:00+05:00[America/New_York]") // 1710054000000000000n — the offset decides, the zone is ignored
+ * @example toNanoseconds("2024-03-10T12:00:00") // 0n — no offset designator
+ * @example toNanoseconds("20240310T120000Z") // 0n — basic format
+ * @example toNanoseconds("invalid") // 0n
+ */
+export function toNanoseconds(isoString) {
+    return parseInstantNanoseconds(isoString) ?? 0n;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Convert an ISO 8601 instant string to a 64-bit NTP timestamp (RFC 5905).
+ *
+ * - The result packs an unsigned 32-bit count of seconds since 1900-01-01 in the high bits
+ *   and a 32-bit fraction in the low bits, where one fractional unit is 2^-32 s (~233 ps).
+ * - **The seconds field wraps.** It is unsigned 32-bit, so the timestamp rolls into a new
+ *   era every 2^32 seconds (~136.19 years). Era 0 runs from 1900-01-01 to
+ *   2036-02-07T06:28:15Z; the next second is `0n` again. The era is not part of the value
+ *   and is not recoverable from it — `fromNtpTimestamp` takes it as an explicit argument.
+ *   This is the wire format's own ambiguity, not a GMT limitation, so instants outside era 0
+ *   wrap here rather than being rejected.
+ * - Sub-nanosecond precision is not invented: nanoseconds floor onto the 2^-32 s grid, so a
+ *   round trip through `fromNtpTimestamp` is exact for any nanosecond-precision instant.
+ * - Returns `0n` on invalid input. `0n` is also the NTP epoch itself (1900-01-01, era 0) and
+ *   every era boundary after it — validate the string first with `isValidInstant` when the two
+ *   must be told apart. RFC 5905 §6 also makes a zero timestamp "a special case representing
+ *   unknown or unsynchronized time", so the sentinel reads as unsynchronized to an NTP peer.
+ *
+ * @param isoString ISO 8601 instant string (e.g. "2024-03-10T12:00:00Z")
+ * @returns 64-bit NTP timestamp as a bigint, or 0n on invalid input
+ *
+ * @example toNtpTimestamp("1900-01-01T00:00:00Z") // 0n — the NTP epoch
+ * @example toNtpTimestamp("1970-01-01T00:00:00Z") // 9487534653230284800n
+ * @example toNtpTimestamp("2024-03-10T12:00:00Z") // 16832237967035596800n
+ * @example toNtpTimestamp("2036-02-07T06:28:15Z") // 18446744069414584320n — the last second of era 0
+ * @example toNtpTimestamp("2036-02-07T06:28:16Z") // 0n — era 1 begins, and the seconds field wraps
+ * @example toNtpTimestamp("2024-03-10T12:00:00") // 0n — no offset designator
+ * @example toNtpTimestamp("invalid") // 0n
+ */
+export declare function toNtpTimestamp(isoString: string): bigint;

package/dist/precision/convert/toNtpTimestamp.js

@@ -0,0 +1,38 @@
+import { floorDivide, NANOSECONDS_PER_SECOND, NTP_EPOCH_OFFSET_NANOSECONDS, NTP_ERA_UNITS, NTP_UNITS_PER_SECOND, parseInstantNanoseconds, } from "../../internal/index.js";
+/**
+ * Convert an ISO 8601 instant string to a 64-bit NTP timestamp (RFC 5905).
+ *
+ * - The result packs an unsigned 32-bit count of seconds since 1900-01-01 in the high bits
+ *   and a 32-bit fraction in the low bits, where one fractional unit is 2^-32 s (~233 ps).
+ * - **The seconds field wraps.** It is unsigned 32-bit, so the timestamp rolls into a new
+ *   era every 2^32 seconds (~136.19 years). Era 0 runs from 1900-01-01 to
+ *   2036-02-07T06:28:15Z; the next second is `0n` again. The era is not part of the value
+ *   and is not recoverable from it — `fromNtpTimestamp` takes it as an explicit argument.
+ *   This is the wire format's own ambiguity, not a GMT limitation, so instants outside era 0
+ *   wrap here rather than being rejected.
+ * - Sub-nanosecond precision is not invented: nanoseconds floor onto the 2^-32 s grid, so a
+ *   round trip through `fromNtpTimestamp` is exact for any nanosecond-precision instant.
+ * - Returns `0n` on invalid input. `0n` is also the NTP epoch itself (1900-01-01, era 0) and
+ *   every era boundary after it — validate the string first with `isValidInstant` when the two
+ *   must be told apart. RFC 5905 §6 also makes a zero timestamp "a special case representing
+ *   unknown or unsynchronized time", so the sentinel reads as unsynchronized to an NTP peer.
+ *
+ * @param isoString ISO 8601 instant string (e.g. "2024-03-10T12:00:00Z")
+ * @returns 64-bit NTP timestamp as a bigint, or 0n on invalid input
+ *
+ * @example toNtpTimestamp("1900-01-01T00:00:00Z") // 0n — the NTP epoch
+ * @example toNtpTimestamp("1970-01-01T00:00:00Z") // 9487534653230284800n
+ * @example toNtpTimestamp("2024-03-10T12:00:00Z") // 16832237967035596800n
+ * @example toNtpTimestamp("2036-02-07T06:28:15Z") // 18446744069414584320n — the last second of era 0
+ * @example toNtpTimestamp("2036-02-07T06:28:16Z") // 0n — era 1 begins, and the seconds field wraps
+ * @example toNtpTimestamp("2024-03-10T12:00:00") // 0n — no offset designator
+ * @example toNtpTimestamp("invalid") // 0n
+ */
+export function toNtpTimestamp(isoString) {
+    const nanoseconds = parseInstantNanoseconds(isoString);
+    if (nanoseconds === null) {
+        return 0n;
+    }
+    const units = floorDivide((nanoseconds + NTP_EPOCH_OFFSET_NANOSECONDS) * NTP_UNITS_PER_SECOND, NANOSECONDS_PER_SECOND);
+    return ((units % NTP_ERA_UNITS) + NTP_ERA_UNITS) % NTP_ERA_UNITS;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * Convert an ISO 8601 instant string to PostgreSQL's internal `timestamptz` value.
+ *
+ * - PostgreSQL stores a `timestamp`/`timestamptz` as a signed 64-bit count of microseconds
+ *   since 2000-01-01T00:00:00Z — not since the Unix epoch. The wire protocol's binary format
+ *   carries this same value; only the text format and the client libraries convert to 1970.
+ * - Sub-microsecond digits floor away, via `truncateNanoseconds(..., "us")`, so the grid stays
+ *   uniform either side of the epoch. `timestamptz` has no finer resolution to write them to.
+ * - **Instants outside PostgreSQL's own timestamp range are invalid input.** It starts at
+ *   `-004713-11-24T00:00:00Z` (Julian Day 0 — the manual's "4713 BC", counted in the Julian
+ *   calendar), which is 40× later than the earliest instant `Temporal` can represent, so an
+ *   in-range `Temporal` instant is not automatically an in-range PostgreSQL one. The upper
+ *   end is the other way round: PostgreSQL stops at 294276 AD, past what `Temporal` holds,
+ *   so the instant range binds there first.
+ * - Returns `0n` on invalid input. `0n` is also the PostgreSQL epoch itself (2000-01-01) —
+ *   validate the string first with `isValidInstant` when the two must be told apart.
+ *
+ * @param isoString ISO 8601 instant string (e.g. "2024-03-10T12:00:00Z")
+ * @returns microseconds since 2000-01-01 as a bigint, or 0n on invalid input
+ *
+ * @example toPgMicroseconds("2000-01-01T00:00:00Z") // 0n — the PostgreSQL epoch
+ * @example toPgMicroseconds("1970-01-01T00:00:00Z") // -946684800000000n
+ * @example toPgMicroseconds("2024-03-10T12:34:56.789Z") // 763389296789000n
+ * @example toPgMicroseconds("2024-03-10T12:00:00.123456789Z") // 763387200123456n — floors to microseconds
+ * @example toPgMicroseconds("-005000-01-01T00:00:00Z") // 0n — before PostgreSQL's 4713 BC minimum
+ * @example toPgMicroseconds("2024-03-10T12:00:00") // 0n — no offset designator
+ * @example toPgMicroseconds("invalid") // 0n
+ */
+export declare function toPgMicroseconds(isoString: string): bigint;