@matter/general 0.16.0-alpha.0-20250816-d22ad240d → 0.16.0-alpha.0-20250819-0a388db8b

package/src/storage/StringifyTools.ts

@@ -4,6 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { Duration } from "#time/Duration.js";
+import { Millis } from "#time/TimeUnit.js";
 import { UnexpectedDataError } from "../MatterError.js";
 import { Bytes } from "../util/Bytes.js";
 import { isObject } from "../util/Type.js";
@@ -17,6 +19,7 @@ type SupportedComplexStorageTypes =
     | { [key: string]: SupportedStorageBaseTypes | SupportedComplexStorageTypes | null | undefined } // Objects
     | Array<[SupportedStorageBaseTypes, SupportedStorageBaseTypes | SupportedComplexStorageTypes | null | undefined]> // Map style arrays
     | Map<SupportedStorageBaseTypes, SupportedStorageBaseTypes | SupportedComplexStorageTypes>
+    | Duration
     | null
     | undefined; // Maps
 
@@ -77,6 +80,8 @@ export function fromJson(json: string): SupportedStorageTypes {
                             SupportedStorageBaseTypes,
                         ][],
                     );
+                case "Interval":
+                    return Millis(data);
 
                 // TODO Remove in the future, leave here for now for backward compatibility?
                 case "AttributeId":

package/src/time/Duration.ts

@@ -0,0 +1,181 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { UnexpectedDataError } from "#MatterError.js";
+import { Branded } from "#util/Type.js";
+import type { Millis, Seconds, TimeUnit } from "./TimeUnit.js";
+
+/**
+ * A time interval.
+ *
+ * You can create an interval using a {@link TimeUnit} factory such as {@link Seconds}.
+ *
+ * Regardless of the input unit, intervals are stored as milliseconds.  You can use {@link TimeUnit#of} to convert an
+ * interval to the correct unit.
+ *
+ * Math operators always result in millisecond values and can thus be converted back to an interval using
+ * {@link Millis}.  For example, `Millisecs(Hours(1) + Minutes(30))` would produce a 90 minute {@link Duration}.
+ */
+export type Duration = Branded<number, "Interval"> | 0;
+
+/**
+ * Create an interval from a number or string.
+ */
+export function Duration<T extends Duration | string>(source: T): Duration {
+    if (typeof source === "string") {
+        return Duration.parse(source);
+    }
+
+    if (typeof source === "number") {
+        if (Number.isNaN(source)) {
+            throw new DurationFormatError(`A duration may not be NaN`);
+        }
+        return source;
+    }
+
+    throw new DurationFormatError(`Interval value is not a number (received ${typeof source})`);
+}
+
+/**
+ * Thrown when a textual duration cannot be parsed.
+ */
+export class DurationFormatError extends UnexpectedDataError {}
+
+export namespace Duration {
+    /**
+     * Determine the greater of two intervals.
+     */
+    export function max(a: Duration, b: Duration) {
+        if (b > a) {
+            return b;
+        }
+        return a;
+    }
+
+    /**
+     * Determine the lesser of two intervals.
+     */
+    export function min(a: Duration, b: Duration) {
+        if (b < a) {
+            return b;
+        }
+        return a;
+    }
+
+    /**
+     * Convert an interval to a compact human readable string.
+     */
+    export function format<T extends Duration | undefined>(
+        duration: T,
+    ): T extends undefined ? string | undefined : string {
+        let ms = duration as number;
+
+        if (typeof ms !== "number" || Number.isNaN(ms)) {
+            return "invalid";
+        }
+
+        switch (ms) {
+            case 0:
+                return "0";
+
+            case Infinity:
+                return "forever";
+
+            case -Infinity:
+                return "until now"; // Umm...  I guess?
+        }
+
+        if (ms < 0) {
+            return `${toPrecision(ms * 1000, 3)}μs`;
+        } else if (ms < 1000) {
+            return `${toPrecision(ms, 3)}ms`;
+        } else if (ms < 60000) {
+            return `${toPrecision(ms / 1000, 3)}s`;
+        }
+
+        const parts = Array<string>();
+
+        if (ms > 86_400_000) {
+            parts.push(`${Math.floor(ms / 86_400_000)}d`);
+            ms %= 86_400_000;
+        }
+
+        const hours = Math.floor(ms / 3_600_000);
+        if (hours) {
+            parts.push(`${hours}h`);
+        }
+        ms %= 3_600_000;
+
+        const minutes = Math.floor(ms / 60_000);
+        if (minutes) {
+            parts.push(`${minutes}m`);
+        }
+        ms %= 60_000;
+
+        const seconds = Math.floor(ms / 1_000);
+        if (seconds) {
+            parts.push(`${seconds}s`);
+        }
+
+        return parts.join(" ");
+    }
+
+    /**
+     * Parse a string into an interval.
+     */
+    export function parse(text: string) {
+        const parts = text.split(/\s+/).filter(part => part !== "");
+
+        let interval = 0;
+        for (const part of parts) {
+            const suffix = text.match(/[a-zμ]+/i)?.[1];
+            if (suffix === undefined) {
+                throw new DurationFormatError(`Interval component "${part}" is missing an time suffix`);
+            }
+
+            const value = Number(text.slice(text.length - suffix.length));
+            if (Number.isNaN(value)) {
+                throw new DurationFormatError(`Interval component "${part}" contains no numeric component`);
+            }
+
+            switch (suffix.toLowerCase()) {
+                case "μs":
+                case "us":
+                    interval += value / 1000;
+                    break;
+
+                case "ms":
+                    interval += value;
+                    break;
+
+                case "s":
+                    interval += value * 1000;
+                    break;
+
+                case "m":
+                    interval += value * 60_000;
+                    break;
+
+                case "h":
+                    interval += value * 3_600_000;
+                    break;
+
+                case "d":
+                    interval += value * 86_400_000;
+                    break;
+
+                default:
+                    throw new DurationFormatError(`Interval component ${part} contains an unsupported unit suffix`);
+            }
+        }
+
+        return interval as Duration;
+    }
+}
+
+function toPrecision(number: number, precision: number) {
+    return number.toPrecision(precision).replace(/\.?0+/, "");
+}

package/src/time/Time.ts

@@ -9,6 +9,9 @@ import { CancelablePromise } from "#util/Cancelable.js";
 import { ImplementationError } from "../MatterError.js";
 import { Diagnostic } from "../log/Diagnostic.js";
 import { DiagnosticSource } from "../log/DiagnosticSource.js";
+import { Duration } from "./Duration.js";
+import { Instant } from "./TimeUnit.js";
+import type { Timestamp } from "./Timestamp.js";
 
 const registry = new Set<Timer>();
 
@@ -19,56 +22,62 @@ const registry = new Set<Timer>();
  * environment.
  */
 export class Time {
-    static get: () => Time;
+    static default: Time;
 
     static startup = {
-        systemMs: 0,
-        processMs: 0,
+        systemMs: 0 as Timestamp,
+        processMs: 0 as Timestamp,
     };
 
-    now() {
+    get now() {
         return new Date();
     }
-    static readonly now = (): Date => Time.get().now();
+    static get now() {
+        return Time.default.now;
+    }
 
-    nowMs() {
+    get nowMs() {
         return Date.now();
     }
-    static readonly nowMs = (): number => Time.get().nowMs();
+    static get nowMs() {
+        return Time.default.nowMs as Timestamp;
+    }
 
-    nowUs() {
-        return Math.floor(performance.now() + performance.timeOrigin) * 1000;
+    get nowUs() {
+        return Math.floor(performance.now() + performance.timeOrigin) as Timestamp;
+    }
+    static get nowUs() {
+        return Time.default.nowUs;
     }
-    static readonly nowUs = (): number => Time.get().nowUs();
 
     /**
      * Create a timer that will call callback after durationMs has passed.
      */
-    getTimer(name: string, durationMs: number, callback: Timer.Callback): Timer {
-        return new StandardTimer(name, durationMs, callback, false);
+    getTimer(name: string, duration: Duration, callback: Timer.Callback): Timer {
+        return new StandardTimer(name, duration, callback, false);
     }
-    static readonly getTimer = (name: string, durationMs: number, callback: Timer.Callback): Timer =>
-        Time.get().getTimer(name, durationMs, callback);
+    static readonly getTimer = (name: string, duration: Duration, callback: Timer.Callback): Timer =>
+        Time.default.getTimer(name, duration, callback);
 
     /**
      * Create a timer that will periodically call callback at intervalMs intervals.
      */
-    getPeriodicTimer(name: string, intervalMs: number, callback: Timer.Callback): Timer {
-        return new StandardTimer(name, intervalMs, callback, true);
+    getPeriodicTimer(name: string, duration: Duration, callback: Timer.Callback): Timer {
+        return new StandardTimer(name, duration, callback, true);
     }
-    static readonly getPeriodicTimer = (name: string, intervalMs: number, callback: Timer.Callback): Timer =>
-        Time.get().getPeriodicTimer(name, intervalMs, callback);
+    static readonly getPeriodicTimer = (name: string, duration: Duration, callback: Timer.Callback): Timer =>
+        Time.default.getPeriodicTimer(name, duration, callback);
 
     /**
      * Create a promise that resolves after a specific interval or when canceled, whichever comes first.
      */
-    sleep(name: string, durationMs: number): CancelablePromise {
+    sleep(name: string, duration: Duration): CancelablePromise {
         let timer: Timer;
         let resolver: () => void;
         return new CancelablePromise(
             resolve => {
                 resolver = resolve;
-                timer = Time.getTimer(name, durationMs, resolve);
+                timer = Time.getTimer(name, duration, resolve);
                 timer.start();
             },
 
@@ -78,8 +87,8 @@ export class Time {
             },
         );
     }
-    static sleep(name: string, durationMs: number) {
-        return Time.get().sleep(name, durationMs);
+    static sleep(name: string, duration: Duration) {
+        return Time.default.sleep(name, duration);
     }
 
     static register(timer: Timer) {
@@ -98,7 +107,11 @@ export class Time {
 
 // Check if performance API is available and has the required methods. Use lower accuracy fallback if not.
 if (!performance || typeof performance.now !== "function" || typeof performance.timeOrigin !== "number") {
-    Time.prototype.nowUs = () => Time.nowMs() * 1000; // Fallback is a bit less accurate
+    Object.defineProperty(Time.prototype.nowUs, "nowUs", {
+        get() {
+            return Time.nowMs; // Fallback is a bit less accurate
+        },
+    });
 }
 
 export interface Timer {
@@ -112,7 +125,7 @@ export interface Timer {
     systemId: unknown;
 
     /** Interval (diagnostics) */
-    intervalMs: number;
+    interval: Duration;
 
     /** Is the timer periodic? (diagnostics) */
     isPeriodic: boolean;
@@ -137,7 +150,7 @@ export namespace Timer {
 export class StandardTimer implements Timer {
     #timerId: unknown;
     #utility = false;
-    #intervalMs = -1;
+    #interval = Instant; // Real value installed in constructor
     isRunning = false;
 
     get systemId() {
@@ -146,11 +159,11 @@ export class StandardTimer implements Timer {
 
     constructor(
         readonly name: string,
-        intervalMs: number,
+        duration: Duration,
         private readonly callback: Timer.Callback,
         readonly isPeriodic: boolean,
     ) {
-        this.intervalMs = intervalMs;
+        this.interval = duration;
     }
 
     /**
@@ -158,17 +171,17 @@ export class StandardTimer implements Timer {
      *
      * You can change this value but changes have no effect until the timer restarts.
      */
-    set intervalMs(intervalMs: number) {
-        if (intervalMs < 0 || intervalMs > 2147483647) {
+    set interval(interval: Duration) {
+        if (interval < 0 || interval > 2147483647) {
             throw new ImplementationError(
-                `Invalid intervalMs: ${intervalMs}. The value must be between 0 and 32-bit maximum value (2147483647)`,
+                `Invalid intervalMs: ${interval}. The value must be between 0 and 32-bit maximum value (2147483647)`,
             );
         }
-        this.#intervalMs = intervalMs;
+        this.#interval = interval;
     }
 
-    get intervalMs() {
-        return this.#intervalMs;
+    get interval() {
+        return this.#interval;
     }
 
     get utility() {
@@ -203,7 +216,7 @@ export class StandardTimer implements Timer {
                 this.isRunning = false;
             }
             this.callback();
-        }, this.intervalMs);
+        }, this.interval);
         return this;
     }
 
@@ -222,7 +235,7 @@ DiagnosticSource.add({
                 timer.name,
                 Diagnostic.dict({
                     periodic: timer.isPeriodic,
-                    interval: Diagnostic.interval(timer.intervalMs),
+                    interval: timer.interval,
                     system: timer.systemId,
                     elapsed: timer.elapsed,
                 }),
@@ -232,11 +245,9 @@ DiagnosticSource.add({
 });
 
 Boot.init(() => {
-    const time = new Time();
-
-    Time.startup.systemMs = Time.startup.processMs = time.nowMs();
+    Time.default = new Time();
 
-    Time.get = () => time;
+    Time.startup.systemMs = Time.startup.processMs = Time.nowMs;
 
     // Hook for testing frameworks
     if (typeof MatterHooks !== "undefined") {

package/src/time/TimeUnit.ts

@@ -0,0 +1,159 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Duration } from "./Duration.js";
+
+/**
+ * Details of a specific unit of time.
+ */
+export interface TimeUnit {
+    (scale: number | bigint): Duration;
+    (scale: undefined | number | bigint): undefined | Duration;
+
+    /**
+     * Long name of the unit.
+     */
+    readonly kind: TimeUnit.Kind;
+
+    /**
+     * Abbreviated name of the unit.
+     */
+    readonly abbrev: string;
+
+    /**
+     * An interval representing a single unit.
+     */
+    readonly one: Duration;
+
+    /**
+     * Convert an interval to an integer of this unit.
+     *
+     * Produces an even integer result.  Use {@link fractionalOf} to retain any fractional component.
+     */
+    of<T extends Duration | undefined>(interval: T): T extends undefined ? number | undefined : number;
+
+    /**
+     * Convert an interval to this unit, retaining fractional component.
+     */
+    fractionalOf<T extends Duration | undefined>(interval: T): T extends undefined ? number | undefined : number;
+
+    /**
+     * Compute the ceiling of an interval in this unit.
+     */
+    ceil(duration: Duration): Duration;
+
+    /**
+     * Compute the floor of an interval in this unit.
+     */
+    floor(duration: Duration): Duration;
+
+    /**
+     * Round an interval to this unit.
+     */
+    round(duration: Duration): Duration;
+
+    length: never;
+}
+
+export namespace TimeUnit {
+    /**
+     * Standard time units.
+     */
+    export type Kind = "microsecond" | "millisecond" | "second" | "minute" | "hour" | "day";
+}
+
+/**
+ * Implement a {@link TimeUnit}.
+ */
+export function TimeUnit<T = {}>(kind: TimeUnit.Kind, abbrev: string, one: number, props = {} as T): TimeUnit & T {
+    const unit = {
+        [kind]: (scale: undefined | number | bigint) => {
+            if (scale === undefined) {
+                return undefined;
+            }
+            if (typeof scale === "bigint") {
+                scale = Number(scale);
+            }
+            return (scale * one) as Duration;
+        },
+    }[kind] as TimeUnit & T;
+
+    // Add properties to the function
+    Object.assign(unit, {
+        ...props,
+        kind,
+        abbrev,
+        one,
+        of,
+        fractionalOf,
+        ceil,
+        floor,
+        round,
+        toString: kindOf,
+        [Symbol.for("nodejs.util.inspect.custom")]: kindOf,
+    });
+
+    return unit;
+}
+
+function of(this: TimeUnit, duration: Duration) {
+    return Math.floor(duration / this.one);
+}
+
+function fractionalOf(this: TimeUnit, duration: Duration) {
+    return duration / this.one;
+}
+
+function ceil(this: TimeUnit, duration: Duration) {
+    return Math.ceil(duration / this.one) * this.one;
+}
+
+function floor(this: TimeUnit, duration: Duration) {
+    return Math.floor(duration / this.one) * this.one;
+}
+
+function round(this: TimeUnit, duration: Duration) {
+    return Math.round(duration / this.one) * this.one;
+}
+
+function kindOf(this: TimeUnit) {
+    return this.kind;
+}
+
+/**
+ * Create an interval in microseconds.
+ */
+export const Microseconds = TimeUnit("microsecond", "μs", 0.001);
+
+/**
+ * Create an interval in milliseconds.
+ */
+export const Millis = TimeUnit("millisecond", "ms", 1);
+
+/**
+ * Create an interval in seconds.
+ */
+export const Seconds = TimeUnit("second", "s", 1_000);
+
+/**
+ * Create an interval in minutes.
+ */
+export const Minutes = TimeUnit("minute", "m", 60_000);
+
+/**
+ * Create an interval in hours.
+ */
+export const Hours = TimeUnit("hour", "h", 3_600_000);
+
+/**
+ * Create an interval in days.
+ */
+export const Days = TimeUnit("day", "d", 86_400_000);
+
+/**
+ * A zero-length interval.
+ */
+export const Instant = Millis(0);

package/src/time/Timespan.ts

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Duration } from "./Duration.js";
+import { Timestamp } from "./Timestamp.js";
+
+/**
+ * A period between two {@link Timestamp}s.
+ */
+export interface Timespan {
+    start: Timestamp;
+    stop: Timestamp;
+    duration: Duration;
+
+    from(newStart: Timestamp.Definition): Timespan;
+    to(newStart: Timestamp.Definition): Timespan;
+    valueOf(): { start: Timestamp; stop: Timestamp };
+}
+
+/**
+ * Create a new timespan representing time between {@link start} and {@link stop}.
+ */
+export function Timespan(start: Timestamp.Definition, stop: Timestamp.Definition) {
+    return Object.create(prototype, {
+        start: { value: Timestamp(start), enumerable: true },
+        stop: { value: Timestamp(stop), enumerable: true },
+    }) as Timespan;
+}
+
+const prototype: Timespan = {
+    start: 0 as Timestamp,
+    stop: 0 as Timestamp,
+
+    get duration() {
+        return (this.stop - this.start) as Duration;
+    },
+
+    from(this: Timespan, newStart) {
+        return Timespan(newStart, this.stop);
+    },
+
+    to(this: Timespan, newStop) {
+        return Timespan(this.start, newStop);
+    },
+
+    valueOf(this: Timespan) {
+        return { start: this.start, stop: this.stop };
+    },
+};