@matter/general 0.16.0-alpha.0-20250817-1b000357c → 0.16.0-alpha.0-20250820-24939dd26

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

package/src/time/Timestamp.ts

@@ -0,0 +1,94 @@
+/**
+ * @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 { Time } from "./Time.js";
+
+/**
+ * A UNIX epoch timestamp in milliseconds.
+ *
+ * Note that the precision of the timestamp may be greater than milliseconds but is limited to floating point precision.
+ */
+export type Timestamp = Branded<number, "Timestamp"> | 0;
+
+/**
+ * Create a timestamp.
+ *
+ * Input may be a UNIX epoch value in milliseconds, a parseable date string, or a {@link Date}.
+ */
+export function Timestamp<T extends undefined | Timestamp.Definition>(
+    source: T,
+): T extends undefined ? undefined | Timestamp : Timestamp {
+    if (source === undefined) {
+        return Time.nowMs;
+    }
+
+    if (typeof source === "string") {
+        const date = Date.parse(source);
+        if (Number.isNaN(date.valueOf())) {
+            throw new TimestampFormatError("Invalid timestamp format");
+        }
+    } else if (typeof source === "object" && source !== null && source instanceof Date) {
+        if (Number.isNaN(source.valueOf())) {
+            throw new TimestampFormatError("Cannot convert date to timestamp because it is invalid");
+        }
+        source = source.getTime() as T;
+    } else if (typeof source === "bigint") {
+        source = Number(source) as T;
+    }
+
+    if (typeof source === "number") {
+        if (Number.isNaN(source)) {
+            throw new TimestampFormatError("A timestamp may not be NaN");
+        }
+    } else {
+        throw new TimestampFormatError(`Timestamp is not a number (received ${typeof source})`);
+    }
+
+    return source as Timestamp;
+}
+
+/**
+ * Thrown when a textual timestamp cannot be parsed.
+ */
+export class TimestampFormatError extends UnexpectedDataError {}
+
+export namespace Timestamp {
+    /**
+     * Values that may be used to initialize a timestamp.
+     */
+    export type Definition = number | bigint | string | Date;
+
+    /**
+     * Create a low-resolution timestamp from a seconds value.
+     */
+    export function fromSeconds(source: number) {
+        return Math.floor(source * 1000);
+    }
+
+    /**
+     * Create a high-resolution timestamp from a microsecond value.
+     */
+    export function fromMicroseconds(source: number | bigint) {
+        if (typeof source === "bigint") {
+            source = Number(source);
+        }
+        return Timestamp(source / 1000);
+    }
+
+    /**
+     * The UNIX epoch.
+     */
+    export const zero = Timestamp(0);
+
+    /**
+     * Obtain a {@link Date} for a {@link Timestamp}.
+     */
+    export function dateOf(timestamp: Timestamp) {
+        return new Date(timestamp);
+    }
+}

package/src/time/index.ts

@@ -4,4 +4,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+export * from "./Duration.js";
 export * from "./Time.js";
+export * from "./Timespan.js";
+export * from "./Timestamp.js";
+export * from "./TimeUnit.js";

package/src/transaction/Status.ts

@@ -5,6 +5,7 @@
  */
 
 import { LogLevel } from "#log/LogLevel.js";
+import { Millis } from "#time/TimeUnit.js";
 import { TransactionFlowError } from "./errors.js";
 import type { Transaction } from "./Transaction.js";
 
@@ -74,7 +75,7 @@ export namespace Status {
      * A value of 0 forces lock reports for all async transactions; a negative value disables reporting.
      */
     // eslint-disable-next-line prefer-const
-    export let slowTransactionMs = 200;
+    export let slowTransactionTime = Millis(200);
 
     /**
      * The log level for slow transaction reporting.

package/src/transaction/Tx.ts

@@ -8,6 +8,8 @@ import { Diagnostic } from "#log/Diagnostic.js";
 import { Logger } from "#log/Logger.js";
 import { ImplementationError, ReadOnlyError } from "#MatterError.js";
 import { Time, Timer } from "#time/Time.js";
+import { Timestamp } from "#time/Timestamp.js";
+import { Millis } from "#time/TimeUnit.js";
 import { asError } from "#util/Error.js";
 import { Observable } from "#util/Observable.js";
 import { MaybePromise } from "#util/Promises.js";
@@ -810,11 +812,11 @@ function throwIfErrored(errored: undefined | Array<Participant>, when: string) {
  * "Slow" async transaction monitoring implementation.
  */
 const Monitor = (function () {
-    const monitored = new Map<Tx, number>();
+    const monitored = new Map<Tx, Timestamp>();
     let monitor: Timer | undefined;
 
     function check() {
-        const now = Time.nowMs();
+        const now = Time.nowMs;
         for (const [tx, slowAt] of monitored) {
             if (now > slowAt) {
                 tx.treatAsSlow();
@@ -824,12 +826,12 @@ const Monitor = (function () {
 
     return {
         add(tx: Tx) {
-            const { slowTransactionMs } = Status;
-            if (slowTransactionMs < 0) {
+            const { slowTransactionTime } = Status;
+            if (slowTransactionTime < 0) {
                 return;
             }
 
-            if (!slowTransactionMs) {
+            if (!slowTransactionTime) {
                 tx.treatAsSlow();
                 return;
             }
@@ -838,9 +840,9 @@ const Monitor = (function () {
                 return;
             }
 
-            monitored.set(tx, Time.nowMs() + slowTransactionMs);
+            monitored.set(tx, Timestamp(Time.nowMs + slowTransactionTime));
             if (monitor === undefined) {
-                monitor = Time.getPeriodicTimer("tx-lock-monitor", slowTransactionMs / 10, check);
+                monitor = Time.getPeriodicTimer("tx-lock-monitor", Millis(slowTransactionTime / 10), check);
                 monitor.start();
             }
         },

package/src/util/Cache.ts

@@ -6,6 +6,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { Duration } from "#time/Duration.js";
 import { Diagnostic } from "../log/Diagnostic.js";
 import { Time, Timer } from "../time/Time.js";
 
@@ -17,12 +18,12 @@ class GenericCache<T> {
 
     constructor(
         name: string,
-        private readonly expirationMs: number,
+        private readonly expiration: Duration,
         private readonly expireCallback?: (key: string, value: T) => Promise<void>,
     ) {
         this.periodicTimer = Time.getPeriodicTimer(
             Diagnostic.upgrade(`${name} cache expiration`, [Diagnostic.strong(name), "cache expiration"]),
-            expirationMs,
+            expiration,
             () => this.expire(),
         ).start();
         this.periodicTimer.utility = true;
@@ -56,9 +57,9 @@ class GenericCache<T> {
     }
 
     private async expire() {
-        const now = Time.nowMs();
+        const now = Time.nowMs;
         for (const [key, timestamp] of this.timestamps.entries()) {
-            if (now - timestamp < this.expirationMs) continue;
+            if (now - timestamp < this.expiration) continue;
             await this.delete(key);
         }
     }
@@ -68,10 +69,10 @@ export class Cache<T> extends GenericCache<T> {
     constructor(
         name: string,
         private readonly generator: (...params: any[]) => T,
-        expirationMs: number,
+        expiration: Duration,
         expireCallback?: (key: string, value: T) => Promise<void>,
     ) {
-        super(name, expirationMs, expireCallback);
+        super(name, expiration, expireCallback);
     }
 
     get(...params: any[]) {
@@ -82,7 +83,7 @@ export class Cache<T> extends GenericCache<T> {
             this.values.set(key, value);
             this.knownKeys.add(key);
         }
-        this.timestamps.set(key, Time.nowMs());
+        this.timestamps.set(key, Time.nowMs);
         return value;
     }
 }
@@ -91,10 +92,10 @@ export class AsyncCache<T> extends GenericCache<T> {
     constructor(
         name: string,
         private readonly generator: (...params: any[]) => Promise<T>,
-        expirationMs: number,
+        expiration: Duration,
         expireCallback?: (key: string, value: T) => Promise<void>,
     ) {
-        super(name, expirationMs, expireCallback);
+        super(name, expiration, expireCallback);
     }
 
     async get(...params: any[]) {
@@ -105,7 +106,7 @@ export class AsyncCache<T> extends GenericCache<T> {
             this.values.set(key, value);
             this.knownKeys.add(key);
         }
-        this.timestamps.set(key, Time.nowMs());
+        this.timestamps.set(key, Time.nowMs);
         return value;
     }
 }

package/src/util/DataReadQueue.ts

@@ -6,6 +6,8 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { Duration } from "#time/Duration.js";
+import { Minutes } from "#time/TimeUnit.js";
 import { MatterFlowError } from "../MatterError.js";
 import { Time, Timer } from "../time/Time.js";
 import { createPromise } from "./Promises.js";
@@ -16,7 +18,7 @@ export class DataReadQueue<T> implements Stream<T> {
     #pendingRead?: { resolver: (data: T) => void; rejecter: (reason: any) => void; timeoutTimer?: Timer };
     #closed = false;
 
-    async read(timeoutMs = 60_000): Promise<T> {
+    async read(timeout = Minutes.one): Promise<T> {
         const { promise, resolver, rejecter } = createPromise<T>();
         if (this.#closed) throw new EndOfStreamError();
         const data = this.#queue.shift();
@@ -27,8 +29,12 @@ export class DataReadQueue<T> implements Stream<T> {
         this.#pendingRead = {
             resolver,
             rejecter,
-            timeoutTimer: Time.getTimer("Queue timeout", timeoutMs, () =>
-                rejecter(new NoResponseTimeoutError(`Expected response data missing within timeout of ${timeoutMs}ms`)),
+            timeoutTimer: Time.getTimer("Queue timeout", timeout, () =>
+                rejecter(
+                    new NoResponseTimeoutError(
+                        `Expected response data missing within timeout of ${Duration.format(timeout)}`,
+                    ),
+                ),
             ).start(),
         };
         return promise;

package/src/util/DeepEqual.ts

@@ -4,19 +4,41 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/**
+ * An object that supports custom deep equality.
+ */
+export interface DeepComparable {
+    /**
+     * Deep-compare this object to another.
+     */
+    [DeepComparable.equals](other: unknown): boolean;
+}
+
+export namespace DeepComparable {
+    export const equals = Symbol("deepEquals");
+}
+
 // TODO - implement more efficient specialization for Array and ArrayBuffer
 // TODO - currently will hang on self-referential data structures
-export function isDeepEqual(a: any, b: any, ignoreUndefinedProperties = false): boolean {
-    if (
-        a === null ||
-        a === undefined ||
-        b === null ||
-        b === undefined ||
-        typeof a !== typeof b ||
-        (typeof a !== "object" && typeof b !== "object")
-    ) {
+export function isDeepEqual(a: unknown, b: unknown, ignoreUndefinedProperties = false): boolean {
+    const aIsObject = typeof a === "object" && a !== null;
+    if (aIsObject) {
+        if (DeepComparable.equals in a) {
+            return (a as DeepComparable)[DeepComparable.equals](b);
+        }
+    }
+
+    const bIsObject = typeof b === "object" && b !== null;
+    if (bIsObject) {
+        if (DeepComparable.equals in b) {
+            return (b as DeepComparable)[DeepComparable.equals](a);
+        }
+    }
+
+    if (!aIsObject || !bIsObject) {
         return a === b;
     }
+
     // Create arrays of property names
     const aProps = Object.getOwnPropertyNames(a);
     const bProps = Object.getOwnPropertyNames(b);
@@ -29,16 +51,19 @@ export function isDeepEqual(a: any, b: any, ignoreUndefinedProperties = false):
     for (let i = 0; i < aProps.length; i++) {
         const propName = aProps[i];
 
-        if (typeof a[propName] !== typeof b[propName]) {
+        const aprop = (a as Record<string, unknown>)[propName];
+        const bprop = (b as Record<string, unknown>)[propName];
+
+        if (typeof aprop !== typeof bprop) {
             return false;
         }
-        if (typeof a[propName] === "object") {
-            if (!isDeepEqual(a[propName], b[propName])) {
+        if (typeof aprop === "object") {
+            if (!isDeepEqual(aprop, bprop)) {
                 return false;
             }
         } else {
             // If values of same property are not equal, objects are not equivalent
-            if (a[propName] !== b[propName]) {
+            if (aprop !== bprop) {
                 return false;
             }
         }

package/src/util/Observable.ts

@@ -4,7 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { Duration } from "#time/Duration.js";
 import { Time, Timer } from "#time/Time.js";
+import { Instant, Millis, Seconds } from "#time/TimeUnit.js";
 import { ImplementationError } from "../MatterError.js";
 import { Logger } from "../log/Logger.js";
 import "../polyfills/disposable.js";
@@ -654,7 +656,7 @@ export namespace ObserverGroup {
 export class QuietObservable<T extends any[] = any[]> extends BasicObservable<T> implements QuietObservable.State<T> {
     #emitAutomatically = QuietObservable.defaults.emitAutomatically;
     #suppressionEnabled = QuietObservable.defaults.suppressionEnabled;
-    #minimumEmitIntervalMs = QuietObservable.defaults.minimumEmitIntervalMs;
+    #minimumEmitInterval = QuietObservable.defaults.minimumEmitInterval;
     #shouldEmit?: QuietObservable.EmitPredicate<T>;
     #source?: Observable<T>;
     #sink?: Observable<T>;
@@ -676,15 +678,15 @@ export class QuietObservable<T extends any[] = any[]> extends BasicObservable<T>
     }
 
     set config(config: QuietObservable.Configuration<T>) {
-        const { suppressionEnabled, minimumEmitIntervalMs, emitAutomatically } = config;
+        const { suppressionEnabled, minimumEmitInterval, emitAutomatically } = config;
         if (emitAutomatically !== undefined) {
             this.emitAutomatically = emitAutomatically;
         }
         if (suppressionEnabled !== undefined) {
             this.suppressionEnabled = suppressionEnabled;
         }
-        if (minimumEmitIntervalMs !== undefined) {
-            this.minimumEmitIntervalMs = minimumEmitIntervalMs;
+        if (minimumEmitInterval !== undefined) {
+            this.minimumEmitInterval = minimumEmitInterval;
         }
         if ("shouldEmit" in config) {
             this.shouldEmit = config.shouldEmit;
@@ -726,19 +728,19 @@ export class QuietObservable<T extends any[] = any[]> extends BasicObservable<T>
         this.#suppressionEnabled = value;
     }
 
-    get minimumEmitIntervalMs() {
-        return this.#minimumEmitIntervalMs;
+    get minimumEmitInterval() {
+        return this.#minimumEmitInterval;
     }
 
-    set minimumEmitIntervalMs(value: number) {
-        if (this.#minimumEmitIntervalMs === value) {
+    set minimumEmitInterval(value: Duration) {
+        if (this.#minimumEmitInterval === value) {
             return;
         }
         const needStart = this.#emitTimer !== undefined;
         if (needStart) {
             this.#stop();
         }
-        this.#minimumEmitIntervalMs = value;
+        this.#minimumEmitInterval = value;
         if (needStart) {
             this.#start();
         }
@@ -812,12 +814,12 @@ export class QuietObservable<T extends any[] = any[]> extends BasicObservable<T>
             this.#deferredPayload = payload;
             return;
         }
-        const now = Time.nowMs();
+        const now = Time.nowMs;
         if (
             immediate ||
             !this.#suppressionEnabled ||
             this.#lastEmitAt === undefined ||
-            this.#lastEmitAt + this.#minimumEmitIntervalMs < now
+            this.#lastEmitAt + this.#minimumEmitInterval < now
         ) {
             return this.#emit(payload, now);
         }
@@ -851,7 +853,7 @@ export class QuietObservable<T extends any[] = any[]> extends BasicObservable<T>
 
     #emit(payload: T, now?: number) {
         this.#deferredPayload = undefined;
-        this.#lastEmitAt = now ?? Time.nowMs();
+        this.#lastEmitAt = now ?? Time.nowMs;
         this.#stop();
         super.emit(...payload);
     }
@@ -861,11 +863,11 @@ export class QuietObservable<T extends any[] = any[]> extends BasicObservable<T>
             return;
         }
 
-        let timeout;
+        let timeout: Duration;
         if (this.#lastEmitAt === undefined) {
-            timeout = 0;
+            timeout = Instant;
         } else {
-            timeout = this.#minimumEmitIntervalMs - ((now ?? Time.nowMs()) - this.#lastEmitAt);
+            timeout = Millis(this.#minimumEmitInterval - ((now ?? Time.nowMs) - this.#lastEmitAt));
         }
 
         if (timeout <= 0) {
@@ -900,7 +902,7 @@ export namespace QuietObservable {
         /**
          * The minimum time between emits in milliseconds.
          */
-        minimumEmitIntervalMs: number;
+        minimumEmitInterval: Duration;
 
         /**
          * An input observable this observable will automatically observe to produce events.
@@ -956,6 +958,6 @@ export namespace QuietObservable {
     export const defaults: State = {
         emitAutomatically: true,
         suppressionEnabled: true,
-        minimumEmitIntervalMs: 1000,
+        minimumEmitInterval: Seconds.one,
     };
 }

package/src/util/PromiseQueue.ts

@@ -4,7 +4,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { Duration } from "#time/Duration.js";
 import { Time } from "#time/Time.js";
+import { Instant } from "#time/TimeUnit.js";
 import { Logger } from "../log/Logger.js";
 import { createPromise } from "./Promises.js";
 
@@ -14,12 +16,12 @@ const logger = Logger.get("PromiseQueue");
  * A queue that processes promises with a given concurrency and delays after each promise if desired.
  */
 export class PromiseQueue {
-    readonly #delay: number;
+    readonly #delay: Duration;
     readonly #queue = new Array<{ func: () => Promise<any>; rejecter: (reason?: any) => void }>();
     readonly #concurrency: number;
     #runningCount = 0;
 
-    constructor(concurrency = 1, delay = 0) {
+    constructor(concurrency = 1, delay = Instant) {
         this.#concurrency = concurrency;
         this.#delay = delay;
     }

package/src/util/Promises.ts

@@ -6,6 +6,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { Duration } from "#time/Duration.js";
 import { asError } from "#util/Error.js";
 import { InternalError, TimeoutError } from "../MatterError.js";
 import { Time } from "../time/Time.js";
@@ -74,12 +75,12 @@ export class PromiseTimeoutError extends TimeoutError {}
  *
  * By default, rejects with {@link PromiseTimeoutError} on timeout but you can override by supplying {@link cancel}.
  *
- * @param timeoutMs the timeout in milliseconds
+ * @param timeout the timeout in milliseconds
  * @param promise a promise that resolves or rejects when the timed task completes
  * @param cancel invoked on timeout (default implementation throws {@link PromiseTimeoutError})
  */
 export async function withTimeout<T>(
-    timeoutMs: number,
+    timeout: Duration,
     promise: Promise<T>,
     cancel?: AbortController | (() => void),
 ): Promise<T> {
@@ -97,8 +98,8 @@ export async function withTimeout<T>(
     let cancelTimer: undefined | (() => void);
 
     // Sub-promise 1, the timer
-    const timeout = new Promise<void>((resolve, reject) => {
-        const timer = Time.getTimer("promise-timeout", timeoutMs, () => {
+    const timedOut = new Promise<void>((resolve, reject) => {
+        const timer = Time.getTimer("promise-timeout", timeout, () => {
             try {
                 cancelFn();
             } catch (e) {
@@ -130,7 +131,7 @@ export async function withTimeout<T>(
     );
 
     // Output promise, resolves like input promise unless timed out
-    await Promise.all([timeout, producer]);
+    await Promise.all([timedOut, producer]);
 
     return result as T;
 }