@aglyn/shared-util-timestamp 1.0.0-beta.143

package/src/lib/timestamp.d.ts

@@ -0,0 +1,242 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Scientific notation values for decimal precision of time equivalents for
+ * conversions when calculating time. Small to big uses a positive exponent and
+ * big to small uses a negative exponent.
+ * @example
+ * `MILLI_TO_SEC` - 1e3 equals 1,000 i.e., 1,000 milliseconds in a second
+ * `SEC_TO_MILLI` - 1e-3 equals 0.001 i.e., 1/1,000 of a second is a millisecond
+ */
+export declare enum TimeExchange {
+    NANO_TO_MICRO = 1000,
+    NANO_TO_MILLI = 1000000,
+    NANO_TO_SEC = 1000000000,
+    MICRO_TO_NANO = 0.001,
+    MICRO_TO_MILLI = 1000,
+    MICRO_TO_SEC = 1000000,
+    MILLI_TO_NANO = 0.000001,
+    MILLI_TO_MICRO = 0.001,
+    MILLI_TO_SEC = 1000,
+    SEC_TO_NANO = 1e-9,
+    SEC_TO_MICRO = 0.000001,
+    SEC_TO_MILLI = 0.001,
+    SEC_TO_MIN = 60,
+    SEC_TO_HR = 3600,
+    SEC_TO_DY = 86400,
+    SEC_TO_WK = 604800,
+    SEC_TO_MO = 2628000,
+    SEC_TO_YR = 31540000,
+    MIN_TO_SEC = 0.016667,
+    HR_TO_SEC = 0.00027778,
+    DY_TO_SEC = 0.000011574,
+    WK_TO_SEC = 0.0000016534,
+    MO_TO_SEC = 3.8052e-7,
+    YR_TO_SEC = 3.171e-8
+}
+/**
+ * The timestamp shape, declared structurally (AGL-1207).
+ *
+ * It used to be `extends FirestoreTimestamp`, which dragged the Firestore
+ * client in through TYPE space as well as value space. Everything that
+ * consumes an `ITimestamp` wants these five members; nothing wanted the SDK
+ * class's identity.
+ */
+export interface ITimestamp {
+    readonly seconds: number;
+    readonly nanoseconds: number;
+    toDate(): Date;
+    toMillis(): number;
+    isEqual(other: ITimestamp): boolean;
+}
+/**
+ * A `Timestamp` represents a point in time independent of any time zone or
+ * calendar, represented as seconds and fractions of seconds at nanosecond
+ * resolution in UTC Epoch time.
+ *
+ * It is encoded using the Proleptic Gregorian Calendar which extends the
+ * Gregorian calendar backwards to year one. It is encoded assuming all minutes
+ * are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second
+ * table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to
+ * 9999-12-31T23:59:59.999999999Z.
+ *
+ * Model and logical flow inspired by `@firebase/firestore/lite/timestamp`
+ *
+ * ## Why it extends `Date` (AGL-1207)
+ *
+ * It used to extend the Firestore SDK's `Timestamp`. A class `extends` is a
+ * hard runtime dependency — not type-only, not tree-shakeable — so every
+ * module graph reaching this file loaded the whole Firestore client, and any
+ * spec that partially mocked `firebase/firestore` failed at IMPORT time.
+ *
+ * `Date` is a JS builtin, so extending it costs nothing. Crucially it also
+ * keeps every existing write working untouched: Firestore's client validates
+ * field values with `instanceof Date` and serialises them from the internal
+ * time slot via `getTime()`, so an instance of this class is still written as
+ * a real timestamp — not as a map. That was verified against the emulator
+ * before this change, including with `valueOf()` overridden below to return a
+ * string, which does NOT interfere: the SDK never consults it.
+ *
+ * A plain custom class would have been rejected outright with
+ * `invalid-argument: Unsupported field value`, which is why `Date` and not a
+ * bare object is the base.
+ */
+/**
+ * `Date` at runtime, with two members hidden from its TYPE.
+ *
+ * `valueOf()` here returns a zero-padded ordering string, `toJSON()` returns
+ * `{seconds, nanoseconds, type}`, and `toString()` returns the
+ * `Timestamp(seconds=…, nanoseconds=…)` form — all three deliberate, all three
+ * predating this change, and all incompatible with `Date`'s own signatures.
+ * TypeScript is right to reject the override; the runtime is perfectly happy.
+ *
+ * Omitting them from the base type keeps every existing behaviour byte-for-byte
+ * rather than quietly changing what `JSON.stringify(timestamp)` or a `<`
+ * comparison produces — this change is about removing a dependency, not about
+ * altering semantics. `Timestamp` is still `Date` at runtime, so `instanceof
+ * Date` holds and Firestore serialises it as a timestamp.
+ */
+declare const TimestampBase: {
+    new (milliseconds: number): Omit<Date, "valueOf" | "toJSON" | "toString">;
+};
+export declare class Timestamp extends TimestampBase implements ITimestamp {
+    /**
+     * The earliest date supported by Google Firestore timestamps
+     * (0001-01-01T00:00:00Z).
+     */
+    static MIN_SECONDS: number;
+    /**
+     * The latest date supported by Google Firestore timestamps
+     * (9999-12-31T23:59:59Z).
+     */
+    static MAX_SECONDS: number;
+    /**
+     * Creates a new {@link Timestamp}.
+     *
+     * @param seconds - The number of seconds of UTC time since Unix epoch
+     *     1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to
+     *     9999-12-31T23:59:59Z inclusive.
+     * @param nanoseconds - The non-negative fractions of a second at nanosecond
+     *     resolution. Negative second values with fractions must still have
+     *     non-negative nanoseconds values that count forward in time. Must be
+     *     from 0 to 999,999,999 inclusive.
+     */
+    /**
+     * The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z.
+     */
+    readonly seconds: number;
+    /**
+     * The fractions of a second at nanosecond resolution.
+     *
+     * Held as its own field rather than derived from `Date`, which is only
+     * millisecond-resolution. Reads coming back from Firestore carry real
+     * nanoseconds and are the SDK's own class, not this one; nothing in the repo
+     * constructs a sub-millisecond value (`new Timestamp(` has no call sites,
+     * and `now()`/`fromMillis()`/`fromDate()` are all millisecond-sourced), so
+     * the internal slot losing sub-millisecond precision is not reachable today.
+     * The field keeps the public shape exact regardless.
+     */
+    readonly nanoseconds: number;
+    constructor(seconds: number, nanoseconds: number);
+    /**
+     * Primitive comparator
+     * @param left - left operand
+     * @param right - right operand
+     * @returns -1 if smaller, 0 if equal, 1 if greater
+     */
+    static comparator<T>(left: T, right: T): number;
+    /**
+     * Creates a new {@link Timestamp} with the current date, with millisecond
+     * precision.
+     *
+     * @returns a new {@link Timestamp} representing the current date.
+     */
+    static now(): Timestamp;
+    /**
+     * Creates a new timestamp from the given date.
+     *
+     * @param date - The date to convert to a {@link Timestamp} instance
+     * @returns {@link Timestamp} equivalent as the provided {@link Date}
+     */
+    static fromDate(date: Date): ITimestamp;
+    /**
+     * Creates a new timestamp from the given number of milliseconds, since Unix
+     * epoch 1970-01-01T00:00:00Z
+     *
+     * @param milliseconds - Number of milliseconds
+     * @returns New {@link Timestamp} instance from the provided milliseconds
+     */
+    static fromMillis(milliseconds: number): Timestamp;
+    /**
+     * Converts a {@link Timestamp} to a JavaScript {@link Date} object. This
+     * conversion causes a loss of precision since `Date` objects only support
+     * millisecond precision.
+     *
+     * @returns JavaScript {@link Date} object representing the same point in time
+     *     as this {@link Timestamp}, with millisecond precision.
+     */
+    toDate(): Date;
+    /**
+     * Converts a {@link Timestamp} to a numeric timestamp (in milliseconds since
+     * epoch). This operation causes a loss of precision.
+     *
+     * @returns The time corresponding to this {@link Timestamp}, represented as
+     *     the number of milliseconds since Unix epoch 1970-01-01T00:00:00Z.
+     */
+    toMillis(): number;
+    /**
+     * Returns true if this {@link Timestamp} is equal to the provided one.
+     *
+     * @param other - The {@link Timestamp} to compare against.
+     * @returns true if this {@link Timestamp} is equal to the provided one.
+     */
+    isEqual(other: ITimestamp): boolean;
+    /**
+     * Returns a textual representation of this Timestamp.
+     */
+    toString(): string;
+    /**
+     * Converts this object to a primitive string, which allows Timestamp objects
+     * to be compared using the `>`, `<=`, `>=` and `>` operators.
+     *
+     * This method returns a string of the form <seconds>.<nanoseconds> where
+     * <seconds> is translated to have a non-negative value and both <seconds>
+     * and <nanoseconds> are left-padded with zeroes to be a consistent length.
+     * Strings with this format then have a lexicographical ordering that matches
+     * the expected ordering. The <seconds> translation is done to avoid having
+     * a leading negative sign (i.e. a leading '-' character) in its string
+     * representation, which would affect its lexicographical ordering.
+     */
+    valueOf(): string;
+    /**
+     * Returns a JSON-serializable representation of this Timestamp.
+     */
+    toJSON(): {
+        seconds: number;
+        nanoseconds: number;
+        type: string;
+    };
+    /**
+     * Returns the difference of `a` to `b` in seconds unless they are equal, in
+     * which case it will compare the difference in nanoseconds
+     * @param a - an instance of {@link Timestamp} to compare with {@link b}
+     * @param b - an instance of {@link Timestamp} to compare against {@link a}
+     */
+    static difference(a: Timestamp, b: Timestamp): number;
+    _compareTo(other: ITimestamp): number;
+}
+export default Timestamp;

package/src/lib/timestamp.js

@@ -0,0 +1,241 @@
+/**
+ * @license
+ * Copyright 2022 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * Scientific notation values for decimal precision of time equivalents for
+ * conversions when calculating time. Small to big uses a positive exponent and
+ * big to small uses a negative exponent.
+ * @example
+ * `MILLI_TO_SEC` - 1e3 equals 1,000 i.e., 1,000 milliseconds in a second
+ * `SEC_TO_MILLI` - 1e-3 equals 0.001 i.e., 1/1,000 of a second is a millisecond
+ */ // Multiple members intentionally share the same value: base-1000 metric
+// prefix conversions (nano/micro/milli/sec) recur at the same magnitude.
+/* eslint-disable @typescript-eslint/no-duplicate-enum-values */ export var TimeExchange = /*#__PURE__*/ function(TimeExchange) {
+    TimeExchange[TimeExchange["NANO_TO_MICRO"] = 1e3] = "NANO_TO_MICRO";
+    TimeExchange[TimeExchange["NANO_TO_MILLI"] = 1e6] = "NANO_TO_MILLI";
+    TimeExchange[TimeExchange["NANO_TO_SEC"] = 1e9] = "NANO_TO_SEC";
+    TimeExchange[TimeExchange["MICRO_TO_NANO"] = 1e-3] = "MICRO_TO_NANO";
+    TimeExchange[TimeExchange["MICRO_TO_MILLI"] = 1e3] = "MICRO_TO_MILLI";
+    TimeExchange[TimeExchange["MICRO_TO_SEC"] = 1e6] = "MICRO_TO_SEC";
+    TimeExchange[TimeExchange["MILLI_TO_NANO"] = 1e-6] = "MILLI_TO_NANO";
+    TimeExchange[TimeExchange["MILLI_TO_MICRO"] = 1e-3] = "MILLI_TO_MICRO";
+    TimeExchange[TimeExchange["MILLI_TO_SEC"] = 1e3] = "MILLI_TO_SEC";
+    TimeExchange[TimeExchange["SEC_TO_NANO"] = 1e-9] = "SEC_TO_NANO";
+    TimeExchange[TimeExchange["SEC_TO_MICRO"] = 1e-6] = "SEC_TO_MICRO";
+    TimeExchange[TimeExchange["SEC_TO_MILLI"] = 1e-3] = "SEC_TO_MILLI";
+    TimeExchange[TimeExchange["SEC_TO_MIN"] = 6e1] = "SEC_TO_MIN";
+    TimeExchange[TimeExchange["SEC_TO_HR"] = 3.6e3] = "SEC_TO_HR";
+    TimeExchange[TimeExchange["SEC_TO_DY"] = 8.64e4] = "SEC_TO_DY";
+    TimeExchange[TimeExchange["SEC_TO_WK"] = 6.048e5] = "SEC_TO_WK";
+    TimeExchange[TimeExchange["SEC_TO_MO"] = 2.628e6] = "SEC_TO_MO";
+    TimeExchange[TimeExchange["SEC_TO_YR"] = 3.154e7] = "SEC_TO_YR";
+    TimeExchange[TimeExchange["MIN_TO_SEC"] = 1.6667e-2] = "MIN_TO_SEC";
+    TimeExchange[TimeExchange["HR_TO_SEC"] = 2.7778e-4] = "HR_TO_SEC";
+    TimeExchange[TimeExchange["DY_TO_SEC"] = 1.1574e-5] = "DY_TO_SEC";
+    TimeExchange[TimeExchange["WK_TO_SEC"] = 1.6534e-6] = "WK_TO_SEC";
+    TimeExchange[TimeExchange["MO_TO_SEC"] = 3.8052e-7] = "MO_TO_SEC";
+    TimeExchange[TimeExchange["YR_TO_SEC"] = 3.1710e-8] = "YR_TO_SEC";
+    return TimeExchange;
+}({});
+/**
+ * A `Timestamp` represents a point in time independent of any time zone or
+ * calendar, represented as seconds and fractions of seconds at nanosecond
+ * resolution in UTC Epoch time.
+ *
+ * It is encoded using the Proleptic Gregorian Calendar which extends the
+ * Gregorian calendar backwards to year one. It is encoded assuming all minutes
+ * are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second
+ * table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to
+ * 9999-12-31T23:59:59.999999999Z.
+ *
+ * Model and logical flow inspired by `@firebase/firestore/lite/timestamp`
+ *
+ * ## Why it extends `Date` (AGL-1207)
+ *
+ * It used to extend the Firestore SDK's `Timestamp`. A class `extends` is a
+ * hard runtime dependency — not type-only, not tree-shakeable — so every
+ * module graph reaching this file loaded the whole Firestore client, and any
+ * spec that partially mocked `firebase/firestore` failed at IMPORT time.
+ *
+ * `Date` is a JS builtin, so extending it costs nothing. Crucially it also
+ * keeps every existing write working untouched: Firestore's client validates
+ * field values with `instanceof Date` and serialises them from the internal
+ * time slot via `getTime()`, so an instance of this class is still written as
+ * a real timestamp — not as a map. That was verified against the emulator
+ * before this change, including with `valueOf()` overridden below to return a
+ * string, which does NOT interfere: the SDK never consults it.
+ *
+ * A plain custom class would have been rejected outright with
+ * `invalid-argument: Unsupported field value`, which is why `Date` and not a
+ * bare object is the base.
+ */ /**
+ * `Date` at runtime, with two members hidden from its TYPE.
+ *
+ * `valueOf()` here returns a zero-padded ordering string, `toJSON()` returns
+ * `{seconds, nanoseconds, type}`, and `toString()` returns the
+ * `Timestamp(seconds=…, nanoseconds=…)` form — all three deliberate, all three
+ * predating this change, and all incompatible with `Date`'s own signatures.
+ * TypeScript is right to reject the override; the runtime is perfectly happy.
+ *
+ * Omitting them from the base type keeps every existing behaviour byte-for-byte
+ * rather than quietly changing what `JSON.stringify(timestamp)` or a `<`
+ * comparison produces — this change is about removing a dependency, not about
+ * altering semantics. `Timestamp` is still `Date` at runtime, so `instanceof
+ * Date` holds and Firestore serialises it as a timestamp.
+ */ const TimestampBase = Date;
+export class Timestamp extends TimestampBase {
+    /**
+   * Primitive comparator
+   * @param left - left operand
+   * @param right - right operand
+   * @returns -1 if smaller, 0 if equal, 1 if greater
+   */ static comparator(left, right) {
+        return left < right ? -1 : left > right ? 1 : 0;
+    }
+    /**
+   * Creates a new {@link Timestamp} with the current date, with millisecond
+   * precision.
+   *
+   * @returns a new {@link Timestamp} representing the current date.
+   */ static now() {
+        return this.fromMillis(Date.now());
+    }
+    /**
+   * Creates a new timestamp from the given date.
+   *
+   * @param date - The date to convert to a {@link Timestamp} instance
+   * @returns {@link Timestamp} equivalent as the provided {@link Date}
+   */ static fromDate(date) {
+        return this.fromMillis(date.getTime());
+    }
+    /**
+   * Creates a new timestamp from the given number of milliseconds, since Unix
+   * epoch 1970-01-01T00:00:00Z
+   *
+   * @param milliseconds - Number of milliseconds
+   * @returns New {@link Timestamp} instance from the provided milliseconds
+   */ static fromMillis(milliseconds) {
+        const seconds = Math.floor(milliseconds / 1e3);
+        const nanoseconds = Math.floor((milliseconds - seconds * 1e3) * 1e6);
+        return new this(seconds, nanoseconds);
+    }
+    /**
+   * Converts a {@link Timestamp} to a JavaScript {@link Date} object. This
+   * conversion causes a loss of precision since `Date` objects only support
+   * millisecond precision.
+   *
+   * @returns JavaScript {@link Date} object representing the same point in time
+   *     as this {@link Timestamp}, with millisecond precision.
+   */ toDate() {
+        return new Date(this.toMillis());
+    }
+    /**
+   * Converts a {@link Timestamp} to a numeric timestamp (in milliseconds since
+   * epoch). This operation causes a loss of precision.
+   *
+   * @returns The time corresponding to this {@link Timestamp}, represented as
+   *     the number of milliseconds since Unix epoch 1970-01-01T00:00:00Z.
+   */ toMillis() {
+        return this.seconds * 1e3 + this.nanoseconds / 1e6;
+    }
+    /**
+   * Returns true if this {@link Timestamp} is equal to the provided one.
+   *
+   * @param other - The {@link Timestamp} to compare against.
+   * @returns true if this {@link Timestamp} is equal to the provided one.
+   */ isEqual(other) {
+        return other.seconds === this.seconds && other.nanoseconds === this.nanoseconds;
+    }
+    /**
+   * Returns a textual representation of this Timestamp.
+   */ toString() {
+        return `Timestamp(seconds=${this.seconds}, nanoseconds=${this.nanoseconds})`;
+    }
+    /**
+   * Converts this object to a primitive string, which allows Timestamp objects
+   * to be compared using the `>`, `<=`, `>=` and `>` operators.
+   *
+   * This method returns a string of the form <seconds>.<nanoseconds> where
+   * <seconds> is translated to have a non-negative value and both <seconds>
+   * and <nanoseconds> are left-padded with zeroes to be a consistent length.
+   * Strings with this format then have a lexicographical ordering that matches
+   * the expected ordering. The <seconds> translation is done to avoid having
+   * a leading negative sign (i.e. a leading '-' character) in its string
+   * representation, which would affect its lexicographical ordering.
+   */ valueOf() {
+        const adjustedSeconds = this.seconds - Timestamp.MIN_SECONDS;
+        // Note: Up to 12 decimal digits are required to represent all valid
+        // 'seconds' values.
+        const formattedSeconds = String(adjustedSeconds).padStart(12, '0');
+        const formattedNanoseconds = String(this.nanoseconds).padStart(9, '0');
+        return formattedSeconds + '.' + formattedNanoseconds;
+    }
+    /**
+   * Returns a JSON-serializable representation of this Timestamp.
+   */ toJSON() {
+        return {
+            seconds: this.seconds,
+            nanoseconds: this.nanoseconds,
+            type: 'firestore/timestamp/1.0'
+        };
+    }
+    /**
+   * Returns the difference of `a` to `b` in seconds unless they are equal, in
+   * which case it will compare the difference in nanoseconds
+   * @param a - an instance of {@link Timestamp} to compare with {@link b}
+   * @param b - an instance of {@link Timestamp} to compare against {@link a}
+   */ static difference(a, b) {
+        return a._compareTo(b);
+    }
+    _compareTo(other) {
+        if (this.seconds === other.seconds) {
+            return Timestamp.comparator(this.nanoseconds, other.nanoseconds);
+        }
+        return Timestamp.comparator(this.seconds, other.seconds);
+    }
+    constructor(seconds, nanoseconds){
+        // Validation runs BEFORE `super()`, which is legal because it reads only
+        // the parameters and never `this`. Order matters: seeding Date with an
+        // out-of-range value would otherwise produce an Invalid Date before the
+        // error that explains why.
+        if (nanoseconds < 0) {
+            throw new Error('invalid-argument: timestamp nanoseconds out of range: ' + nanoseconds);
+        }
+        if (nanoseconds >= 1e9) {
+            throw new Error('invalid-argument: timestamp nanoseconds out of range: ' + nanoseconds);
+        }
+        if (seconds < Timestamp.MIN_SECONDS) {
+            throw new Error('invalid-argument: timestamp seconds out of range: ' + seconds);
+        }
+        // This will break in the year 10,000.
+        if (seconds > Timestamp.MAX_SECONDS) {
+            throw new Error('invalid-argument: timestamp seconds out of range: ' + seconds);
+        }
+        super(seconds * 1e3 + nanoseconds / 1e6);
+        this.seconds = seconds;
+        this.nanoseconds = nanoseconds;
+    }
+}
+/**
+   * The earliest date supported by Google Firestore timestamps
+   * (0001-01-01T00:00:00Z).
+   */ Timestamp.MIN_SECONDS = -62135596800;
+/**
+   * The latest date supported by Google Firestore timestamps
+   * (9999-12-31T23:59:59Z).
+   */ Timestamp.MAX_SECONDS = 253402322399;
+export default Timestamp;
+
+//# sourceMappingURL=timestamp.js.map

package/src/lib/timestamp.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/shared/util/timestamp/src/lib/timestamp.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2022 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n\n/**\n * Scientific notation values for decimal precision of time equivalents for\n * conversions when calculating time. Small to big uses a positive exponent and\n * big to small uses a negative exponent.\n * @example\n * `MILLI_TO_SEC` - 1e3 equals 1,000 i.e., 1,000 milliseconds in a second\n * `SEC_TO_MILLI` - 1e-3 equals 0.001 i.e., 1/1,000 of a second is a millisecond\n */\n// Multiple members intentionally share the same value: base-1000 metric\n// prefix conversions (nano/micro/milli/sec) recur at the same magnitude.\n/* eslint-disable @typescript-eslint/no-duplicate-enum-values */\nexport enum TimeExchange {\n  NANO_TO_MICRO = 1e3,\n  NANO_TO_MILLI = 1e6,\n  NANO_TO_SEC = 1e9,\n  MICRO_TO_NANO = 1e-3,\n  MICRO_TO_MILLI = 1e3,\n  MICRO_TO_SEC = 1e6,\n  MILLI_TO_NANO = 1e-6,\n  MILLI_TO_MICRO = 1e-3,\n  MILLI_TO_SEC = 1e3,\n  SEC_TO_NANO = 1e-9,\n  SEC_TO_MICRO = 1e-6,\n  SEC_TO_MILLI = 1e-3,\n  SEC_TO_MIN = 6e1,\n  SEC_TO_HR = 3.6e3,\n  SEC_TO_DY = 8.64e4,\n  SEC_TO_WK = 6.048e5,\n  SEC_TO_MO = 2.628e6,\n  SEC_TO_YR = 3.154e7,\n  MIN_TO_SEC = 1.6667e-2,\n  HR_TO_SEC = 2.7778e-4,\n  DY_TO_SEC = 1.1574e-5,\n  WK_TO_SEC = 1.6534e-6,\n  MO_TO_SEC = 3.8052e-7,\n  YR_TO_SEC = 3.1710e-8,\n}\n/* eslint-enable @typescript-eslint/no-duplicate-enum-values */\n\n/**\n * The timestamp shape, declared structurally (AGL-1207).\n *\n * It used to be `extends FirestoreTimestamp`, which dragged the Firestore\n * client in through TYPE space as well as value space. Everything that\n * consumes an `ITimestamp` wants these five members; nothing wanted the SDK\n * class's identity.\n */\nexport interface ITimestamp {\n  readonly seconds: number\n  readonly nanoseconds: number\n  toDate(): Date\n  toMillis(): number\n  isEqual(other: ITimestamp): boolean\n}\n\n/**\n * A `Timestamp` represents a point in time independent of any time zone or\n * calendar, represented as seconds and fractions of seconds at nanosecond\n * resolution in UTC Epoch time.\n *\n * It is encoded using the Proleptic Gregorian Calendar which extends the\n * Gregorian calendar backwards to year one. It is encoded assuming all minutes\n * are 60 seconds long, i.e. leap seconds are \"smeared\" so that no leap second\n * table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to\n * 9999-12-31T23:59:59.999999999Z.\n *\n * Model and logical flow inspired by `@firebase/firestore/lite/timestamp`\n *\n * ## Why it extends `Date` (AGL-1207)\n *\n * It used to extend the Firestore SDK's `Timestamp`. A class `extends` is a\n * hard runtime dependency — not type-only, not tree-shakeable — so every\n * module graph reaching this file loaded the whole Firestore client, and any\n * spec that partially mocked `firebase/firestore` failed at IMPORT time.\n *\n * `Date` is a JS builtin, so extending it costs nothing. Crucially it also\n * keeps every existing write working untouched: Firestore's client validates\n * field values with `instanceof Date` and serialises them from the internal\n * time slot via `getTime()`, so an instance of this class is still written as\n * a real timestamp — not as a map. That was verified against the emulator\n * before this change, including with `valueOf()` overridden below to return a\n * string, which does NOT interfere: the SDK never consults it.\n *\n * A plain custom class would have been rejected outright with\n * `invalid-argument: Unsupported field value`, which is why `Date` and not a\n * bare object is the base.\n */\n/**\n * `Date` at runtime, with two members hidden from its TYPE.\n *\n * `valueOf()` here returns a zero-padded ordering string, `toJSON()` returns\n * `{seconds, nanoseconds, type}`, and `toString()` returns the\n * `Timestamp(seconds=…, nanoseconds=…)` form — all three deliberate, all three\n * predating this change, and all incompatible with `Date`'s own signatures.\n * TypeScript is right to reject the override; the runtime is perfectly happy.\n *\n * Omitting them from the base type keeps every existing behaviour byte-for-byte\n * rather than quietly changing what `JSON.stringify(timestamp)` or a `<`\n * comparison produces — this change is about removing a dependency, not about\n * altering semantics. `Timestamp` is still `Date` at runtime, so `instanceof\n * Date` holds and Firestore serialises it as a timestamp.\n */\nconst TimestampBase = Date as unknown as {\n  new (milliseconds: number): Omit<Date, 'valueOf' | 'toJSON' | 'toString'>\n}\n\nexport class Timestamp extends TimestampBase implements ITimestamp {\n  /**\n   * The earliest date supported by Google Firestore timestamps\n   * (0001-01-01T00:00:00Z).\n   */\n  public static MIN_SECONDS = -62135596800\n\n  /**\n   * The latest date supported by Google Firestore timestamps\n   * (9999-12-31T23:59:59Z).\n   */\n  public static MAX_SECONDS = 253402322399\n\n  /**\n   * Creates a new {@link Timestamp}.\n   *\n   * @param seconds - The number of seconds of UTC time since Unix epoch\n   *     1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to\n   *     9999-12-31T23:59:59Z inclusive.\n   * @param nanoseconds - The non-negative fractions of a second at nanosecond\n   *     resolution. Negative second values with fractions must still have\n   *     non-negative nanoseconds values that count forward in time. Must be\n   *     from 0 to 999,999,999 inclusive.\n   */\n  /**\n   * The number of seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z.\n   */\n  readonly seconds: number\n  /**\n   * The fractions of a second at nanosecond resolution.\n   *\n   * Held as its own field rather than derived from `Date`, which is only\n   * millisecond-resolution. Reads coming back from Firestore carry real\n   * nanoseconds and are the SDK's own class, not this one; nothing in the repo\n   * constructs a sub-millisecond value (`new Timestamp(` has no call sites,\n   * and `now()`/`fromMillis()`/`fromDate()` are all millisecond-sourced), so\n   * the internal slot losing sub-millisecond precision is not reachable today.\n   * The field keeps the public shape exact regardless.\n   */\n  readonly nanoseconds: number\n\n  constructor(seconds: number, nanoseconds: number) {\n    // Validation runs BEFORE `super()`, which is legal because it reads only\n    // the parameters and never `this`. Order matters: seeding Date with an\n    // out-of-range value would otherwise produce an Invalid Date before the\n    // error that explains why.\n    if (nanoseconds < 0) {\n      throw new Error(\n        'invalid-argument: timestamp nanoseconds out of range: ' + nanoseconds,\n      )\n    }\n    if (nanoseconds >= 1e9) {\n      throw new Error(\n        'invalid-argument: timestamp nanoseconds out of range: ' + nanoseconds,\n      )\n    }\n    if (seconds < Timestamp.MIN_SECONDS) {\n      throw new Error(\n        'invalid-argument: timestamp seconds out of range: ' + seconds,\n      )\n    }\n    // This will break in the year 10,000.\n    if (seconds > Timestamp.MAX_SECONDS) {\n      throw new Error(\n        'invalid-argument: timestamp seconds out of range: ' + seconds,\n      )\n    }\n    super(seconds * TimeExchange.MILLI_TO_SEC + nanoseconds / TimeExchange.NANO_TO_MILLI)\n    this.seconds = seconds\n    this.nanoseconds = nanoseconds\n  }\n\n  /**\n   * Primitive comparator\n   * @param left - left operand\n   * @param right - right operand\n   * @returns -1 if smaller, 0 if equal, 1 if greater\n   */\n  public static comparator<T>(left: T, right: T): number {\n    return left < right ? -1 : left > right ? 1 : 0\n  }\n\n  /**\n   * Creates a new {@link Timestamp} with the current date, with millisecond\n   * precision.\n   *\n   * @returns a new {@link Timestamp} representing the current date.\n   */\n  public static now(): Timestamp {\n    return this.fromMillis(Date.now())\n  }\n\n  /**\n   * Creates a new timestamp from the given date.\n   *\n   * @param date - The date to convert to a {@link Timestamp} instance\n   * @returns {@link Timestamp} equivalent as the provided {@link Date}\n   */\n  public static fromDate(date: Date): ITimestamp {\n    return this.fromMillis(date.getTime())\n  }\n\n  /**\n   * Creates a new timestamp from the given number of milliseconds, since Unix\n   * epoch 1970-01-01T00:00:00Z\n   *\n   * @param milliseconds - Number of milliseconds\n   * @returns New {@link Timestamp} instance from the provided milliseconds\n   */\n  public static fromMillis(milliseconds: number): Timestamp {\n    const seconds = Math.floor(milliseconds / TimeExchange.MILLI_TO_SEC)\n    const nanoseconds = Math.floor(\n      (milliseconds - seconds * TimeExchange.MILLI_TO_SEC) *\n        TimeExchange.NANO_TO_MILLI,\n    )\n    return new this(seconds, nanoseconds)\n  }\n\n  /**\n   * Converts a {@link Timestamp} to a JavaScript {@link Date} object. This\n   * conversion causes a loss of precision since `Date` objects only support\n   * millisecond precision.\n   *\n   * @returns JavaScript {@link Date} object representing the same point in time\n   *     as this {@link Timestamp}, with millisecond precision.\n   */\n  public toDate(): Date {\n    return new Date(this.toMillis())\n  }\n\n  /**\n   * Converts a {@link Timestamp} to a numeric timestamp (in milliseconds since\n   * epoch). This operation causes a loss of precision.\n   *\n   * @returns The time corresponding to this {@link Timestamp}, represented as\n   *     the number of milliseconds since Unix epoch 1970-01-01T00:00:00Z.\n   */\n  public toMillis(): number {\n    return (\n      this.seconds * TimeExchange.MILLI_TO_SEC +\n      this.nanoseconds / TimeExchange.NANO_TO_MILLI\n    )\n  }\n\n  /**\n   * Returns true if this {@link Timestamp} is equal to the provided one.\n   *\n   * @param other - The {@link Timestamp} to compare against.\n   * @returns true if this {@link Timestamp} is equal to the provided one.\n   */\n  public isEqual(other: ITimestamp): boolean {\n    return (\n      other.seconds === this.seconds && other.nanoseconds === this.nanoseconds\n    )\n  }\n\n  /**\n   * Returns a textual representation of this Timestamp.\n   */\n  public toString(): string {\n    return `Timestamp(seconds=${this.seconds}, nanoseconds=${this.nanoseconds})`\n  }\n\n  /**\n   * Converts this object to a primitive string, which allows Timestamp objects\n   * to be compared using the `>`, `<=`, `>=` and `>` operators.\n   *\n   * This method returns a string of the form <seconds>.<nanoseconds> where\n   * <seconds> is translated to have a non-negative value and both <seconds>\n   * and <nanoseconds> are left-padded with zeroes to be a consistent length.\n   * Strings with this format then have a lexicographical ordering that matches\n   * the expected ordering. The <seconds> translation is done to avoid having\n   * a leading negative sign (i.e. a leading '-' character) in its string\n   * representation, which would affect its lexicographical ordering.\n   */\n  public valueOf(): string {\n    const adjustedSeconds = this.seconds - Timestamp.MIN_SECONDS\n    // Note: Up to 12 decimal digits are required to represent all valid\n    // 'seconds' values.\n    const formattedSeconds = String(adjustedSeconds).padStart(12, '0')\n    const formattedNanoseconds = String(this.nanoseconds).padStart(9, '0')\n    return formattedSeconds + '.' + formattedNanoseconds\n  }\n\n  /**\n   * Returns a JSON-serializable representation of this Timestamp.\n   */\n  public toJSON(): { seconds: number; nanoseconds: number; type: string } {\n    return {\n      seconds: this.seconds,\n      nanoseconds: this.nanoseconds,\n      type: 'firestore/timestamp/1.0',\n    }\n  }\n\n  /**\n   * Returns the difference of `a` to `b` in seconds unless they are equal, in\n   * which case it will compare the difference in nanoseconds\n   * @param a - an instance of {@link Timestamp} to compare with {@link b}\n   * @param b - an instance of {@link Timestamp} to compare against {@link a}\n   */\n  public static difference(a: Timestamp, b: Timestamp): number {\n    return a._compareTo(b)\n  }\n\n  public _compareTo(other: ITimestamp): number {\n    if (this.seconds === other.seconds) {\n      return Timestamp.comparator(this.nanoseconds, other.nanoseconds)\n    }\n    return Timestamp.comparator(this.seconds, other.seconds)\n  }\n}\n\nexport default Timestamp\n"],"names":["TimeExchange","TimestampBase","Date","Timestamp","comparator","left","right","now","fromMillis","fromDate","date","getTime","milliseconds","seconds","Math","floor","nanoseconds","toDate","toMillis","isEqual","other","toString","valueOf","adjustedSeconds","MIN_SECONDS","formattedSeconds","String","padStart","formattedNanoseconds","toJSON","type","difference","a","b","_compareTo","Error","MAX_SECONDS"],"mappings":"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"}

package/src/lib/zoned-time.d.ts

@@ -0,0 +1,133 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/** Minutes in a day: the exclusive end of a window that runs to midnight. */
+export declare const MINUTES_PER_DAY: number;
+/** Monday through Friday, in `Date#getUTCDay` numbering. */
+export declare const MONDAY_TO_FRIDAY: readonly number[];
+/** The calendar fields a wall clock in a zone shows for one instant. */
+export interface ZonedDateTime {
+    year: number;
+    /** 1 January through 12 December. */
+    month: number;
+    /** 1 through 31. */
+    day: number;
+    /** 0 through 23. */
+    hour: number;
+    minute: number;
+    second: number;
+    /** 0 Sunday through 6 Saturday. */
+    weekday: number;
+}
+/**
+ * A wall time to find the instant of. Fields overflow the way `Date.UTC`
+ * lets them — day 32 of a month is the first of the next — so a caller can
+ * step a calendar by adding to `day`.
+ */
+export interface ZonedWallTime {
+    year: number;
+    /** 1 January through 12 December; overflow rolls into the next year. */
+    month: number;
+    day: number;
+    hour?: number;
+    minute?: number;
+    second?: number;
+}
+/** Whether `Intl` knows the zone, so a stored name can be checked before use. */
+export declare function isValidTimeZone(value: unknown): value is string;
+/**
+ * The wall clock in `timeZone` at `atMs`.
+ *
+ * @throws RangeError for a zone `Intl` does not know, or an instant that is
+ *         not a finite number.
+ */
+export declare function zonedDateTime(atMs: number, timeZone: string): ZonedDateTime;
+/** `YYYY-MM-DD` of the calendar day `atMs` falls in, in `timeZone`. */
+export declare function zonedDayKey(atMs: number, timeZone: string): string;
+/** The wall clock's minute of the day, `hour * 60 + minute`, 0 through 1439. */
+export declare function zonedMinuteOfDay(atMs: number, timeZone: string): number;
+/** The zone's offset from UTC at `atMs`, in milliseconds, positive east. */
+export declare function zoneOffsetMs(atMs: number, timeZone: string): number;
+/**
+ * The instant a wall time happens in `timeZone` — see the module note for
+ * the two days a year it is ambiguous. Seconds are whole: a millisecond part
+ * of `second` is dropped.
+ */
+export declare function zonedWallTimeToInstant(wall: ZonedWallTime, timeZone: string): number;
+/** Midnight at the start of the calendar day `atMs` falls in, in `timeZone`. */
+export declare function startOfZonedDay(atMs: number, timeZone: string): number;
+/**
+ * Midnight at the start of the NEXT calendar day in `timeZone` — built from
+ * the calendar rather than by adding 24 hours, because a day a clock change
+ * falls in is 23 or 25 hours long.
+ */
+export declare function startOfNextZonedDay(atMs: number, timeZone: string): number;
+/**
+ * How many calendar days separate the day `fromMs` falls in from the day
+ * `toMs` falls in, in `timeZone`: `0` for the same day, negative when `toMs`
+ * is on an earlier one. Counted on the calendar, so a 23-hour day is a day.
+ */
+export declare function zonedCalendarDaysBetween(fromMs: number, toMs: number, timeZone: string): number;
+/**
+ * `count` business days after `atMs`, at the same wall-clock time, in
+ * `timeZone`.
+ *
+ * The calendar is walked a day at a time from the day after `atMs`, and each
+ * day whose weekday is in `businessDays` counts one. The time of day is the
+ * wall time `atMs` showed, so a 10:00 send is followed at 10:00 after a clock
+ * change as well; a wall time the destination day skips moves forward with
+ * the clock. `0` is `atMs` itself, whatever day that is.
+ *
+ * No holidays: a calendar that knew some countries' holidays would quietly
+ * shorten the wait in every country it did not know.
+ *
+ * @throws RangeError for a count that is not a whole number of days, or a
+ *         `businessDays` list with no weekday in it.
+ */
+export declare function addZonedBusinessDays(atMs: number, count: number, timeZone: string, businessDays?: readonly number[]): number;
+/**
+ * One open stretch of a day, in minutes after local midnight: `start`
+ * inclusive, `end` exclusive, `0 <= start < end <= 1440`.
+ */
+export interface WeeklyInterval {
+    start: number;
+    end: number;
+}
+/**
+ * Open stretches by weekday (`0` Sunday through `6` Saturday), read in one
+ * zone. A weekday with no entry is closed.
+ */
+export type WeeklySchedule = Readonly<Partial<Record<number, readonly WeeklyInterval[]>>>;
+/** A stretch of a schedule as instants: `startMs` inclusive, `endMs` exclusive. */
+export interface ZonedInterval {
+    startMs: number;
+    endMs: number;
+}
+/**
+ * The stretch of `schedule` that contains `atMs`, or else the next one to
+ * open after it — `startMs <= atMs` tells the two apart — or `null` when the
+ * schedule never opens.
+ *
+ * Each end of a stretch is placed on the calendar by
+ * {@link zonedWallTimeToInstant}, so the day a clock changes is measured as
+ * it is lived: 09:00–17:00 is eight hours of wall clock either way, a time
+ * the spring gap skips is read the way that function reads it, and a stretch
+ * that comes out empty — it starts inside the gap and ends as the gap ends —
+ * does not open that day.
+ */
+export declare function nextWeeklyOpening(atMs: number, schedule: WeeklySchedule, timeZone: string): ZonedInterval | null;
+/** Whether `atMs` falls inside an open stretch of `schedule`. */
+export declare function isWithinWeeklySchedule(atMs: number, schedule: WeeklySchedule, timeZone: string): boolean;