@matter/general 0.16.0-alpha.0-20251023-bb23617e5 → 0.16.0-alpha.0-20251029-bd92894d4

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@matter/general",
-    "version": "0.16.0-alpha.0-20251023-bb23617e5",
+    "version": "0.16.0-alpha.0-20251029-bd92894d4",
     "description": "Non-Matter support for Matter.js",
     "keywords": [
         "iot",
@@ -36,7 +36,7 @@
         "@noble/curves": "^2.0.1"
     },
     "devDependencies": {
-        "@matter/testing": "0.16.0-alpha.0-20251023-bb23617e5"
+        "@matter/testing": "0.16.0-alpha.0-20251029-bd92894d4"
     },
     "files": [
         "dist/**/*",

package/src/crypto/Crypto.ts

@@ -12,6 +12,7 @@ import { MaybePromise } from "#util/Promises.js";
 import * as mod from "@noble/curves/abstract/modular.js";
 import { p256 } from "@noble/curves/nist.js";
 import * as utils from "@noble/curves/utils.js";
+import { Entropy } from "../util/Entropy.js";
 import type { PrivateKey, PublicKey } from "./Key.js";
 
 export const ec = {
@@ -41,7 +42,7 @@ const logger = Logger.get("Crypto");
  *
  * WARNING: The standard implementation is unaudited.  See relevant warnings in StandardCrypto.ts.
  */
-export abstract class Crypto {
+export abstract class Crypto extends Entropy {
     /**
      * The name used in log messages.
      */
@@ -57,11 +58,6 @@ export abstract class Crypto {
      */
     abstract decrypt(key: Bytes, data: Bytes, nonce: Bytes, aad?: Bytes): Bytes;
 
-    /**
-     * Create a random buffer from the most cryptographically-appropriate source available.
-     */
-    abstract randomBytes(length: number): Bytes;
-
     /**
      * Compute the SHA-256 hash of a buffer.
      */
@@ -113,33 +109,6 @@ export abstract class Crypto {
      */
     abstract generateDhSecret(key: PrivateKey, peerKey: PublicKey): MaybePromise<Bytes>;
 
-    get randomUint8() {
-        return Bytes.of(this.randomBytes(1))[0];
-    }
-
-    get randomUint16() {
-        return Bytes.dataViewOf(this.randomBytes(2)).getUint16(0);
-    }
-
-    get randomUint32() {
-        return Bytes.dataViewOf(this.randomBytes(4)).getUint32(0);
-    }
-
-    get randomBigUint64() {
-        return Bytes.dataViewOf(this.randomBytes(8)).getBigUint64(0);
-    }
-
-    randomBigInt(size: number, maxValue?: bigint) {
-        if (maxValue === undefined) {
-            return Bytes.asBigInt(this.randomBytes(size));
-        }
-
-        while (true) {
-            const random = Bytes.asBigInt(this.randomBytes(size));
-            if (random < maxValue) return random;
-        }
-    }
-
     reportUsage(component?: string) {
         const message = ["Using", Diagnostic.strong(this.implementationName), "crypto implementation"];
         if (component) {

package/src/crypto/StandardCrypto.ts

@@ -9,6 +9,7 @@ import { DerBigUint, DerCodec, DerError } from "#codec/DerCodec.js";
 import { Environment } from "#environment/Environment.js";
 import { ImplementationError, NotImplementedError } from "#MatterError.js";
 import { Bytes } from "#util/Bytes.js";
+import { Entropy } from "#util/Entropy.js";
 import { MaybePromise } from "#util/Promises.js";
 import { describeList } from "#util/String.js";
 import { Ccm } from "./aes/Ccm.js";
@@ -305,5 +306,7 @@ function assertInterface<T extends {}>(name: string, object: T, requiredMethods:
 // If available, unconditionally add to Environment as it has not been exported yet so there can be no other
 // implementation present
 if ("crypto" in globalThis && globalThis.crypto?.subtle) {
-    Environment.default.set(Crypto, new StandardCrypto());
+    const crypto = new StandardCrypto();
+    Environment.default.set(Entropy, crypto);
+    Environment.default.set(Crypto, crypto);
 }

package/src/net/RetrySchedule.ts

@@ -4,19 +4,19 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Crypto } from "#crypto/Crypto.js";
 import { Duration } from "#time/Duration.js";
 import { Instant, Millis, Seconds } from "#time/TimeUnit.js";
+import { Entropy } from "#util/Entropy.js";
 
 /**
  * An iterable of retry values based on a scheduling configuration.
  */
 export class RetrySchedule {
-    #crypto: Crypto;
+    #entropy: Entropy;
     readonly config: RetrySchedule.Configuration;
 
-    constructor(crypto: Crypto, config: RetrySchedule.Configuration) {
-        this.#crypto = crypto;
+    constructor(entropy: Entropy, config: RetrySchedule.Configuration) {
+        this.#entropy = entropy;
         this.config = config;
     }
 
@@ -42,7 +42,7 @@ export class RetrySchedule {
         while ((timeout === undefined || timeSoFar < timeout) && (maximumCount === undefined || maximumCount > count)) {
             count++;
             const maxJitter = jitterFactor * baseInterval;
-            const jitter = Millis.floor(Millis((maxJitter * this.#crypto.randomUint32) / Math.pow(2, 32)));
+            const jitter = Millis.floor(Millis((maxJitter * this.#entropy.randomUint32) / Math.pow(2, 32)));
             let interval = Millis(baseInterval + jitter);
 
             if (timeout !== undefined && timeSoFar + interval > timeout) {

package/src/util/Abort.ts

@@ -7,6 +7,7 @@
 import { TimeoutError } from "#MatterError.js";
 import { Duration } from "#time/Duration.js";
 import { Time, Timer } from "#time/Time.js";
+import { SafePromise } from "./Promises.js";
 
 /**
  * Utilities for implementing abort logic.
@@ -61,14 +62,14 @@ export namespace Abort {
                 off = () => (signal as AbortSignal).removeEventListener("abort", onabort);
             });
 
-            return Promise.race([aborted, ...promises]).finally(off!);
+            return SafePromise.race([aborted, ...promises]).finally(off!);
         }
 
         if (promises.length === 1) {
             return Promise.resolve(promises[0]);
         }
 
-        return Promise.race(promises);
+        return SafePromise.race(promises);
     }
 
     /**

package/src/util/Entropy.ts

@@ -0,0 +1,44 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes } from "#util/Bytes.js";
+
+/**
+ * A source of entropy.
+ */
+export abstract class Entropy {
+    /**
+     * Create a random buffer from the most cryptographically-appropriate source available.
+     */
+    abstract randomBytes(length: number): Bytes;
+
+    get randomUint8() {
+        return Bytes.of(this.randomBytes(1))[0];
+    }
+
+    get randomUint16() {
+        return Bytes.dataViewOf(this.randomBytes(2)).getUint16(0);
+    }
+
+    get randomUint32() {
+        return Bytes.dataViewOf(this.randomBytes(4)).getUint32(0);
+    }
+
+    get randomBigUint64() {
+        return Bytes.dataViewOf(this.randomBytes(8)).getBigUint64(0);
+    }
+
+    randomBigInt(size: number, maxValue?: bigint) {
+        if (maxValue === undefined) {
+            return Bytes.asBigInt(this.randomBytes(size));
+        }
+
+        while (true) {
+            const random = Bytes.asBigInt(this.randomBytes(size));
+            if (random < maxValue) return random;
+        }
+    }
+}

package/src/util/Observable.ts

@@ -105,6 +105,14 @@ export interface Observable<T extends any[] = any[], R = void> extends AsyncIter
      */
     handlePromise: ObserverPromiseHandler | boolean;
 
+    /**
+     * Creates a promise that resolves when next emitted.
+     */
+    then<TResult1 = T, TResult2 = never>(
+        onfulfilled?: ((value: T[0]) => TResult1 | PromiseLike<TResult1>) | null,
+        onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null,
+    ): Promise<TResult1 | TResult2>;
+
     /**
      * Observable supports standard "for await (const value of observable").
      *
@@ -119,6 +127,38 @@ export interface Observable<T extends any[] = any[], R = void> extends AsyncIter
     [Symbol.dispose](): void;
 }
 
+/**
+ * An observable value.
+ *
+ * This is a stateful observable that remembers its last emitted value and maps to standard Promise semantics.
+ *
+ * Unlike a normal {@link Observable}, awaiting an {@link ObservableValue} will result in immediate resolution if the
+ * value is truthy, and immediately upon updating to a truthy value otherwise.
+ *
+ * Also unlike a normal {@link Observable}, an {@link ObservableValue} may be placed into an error state which will
+ * result in rejection if awaited.
+ */
+export interface ObservableValue<T extends [any, ...any[]] = [boolean]> extends Observable<T, void>, Promise<T[0]> {
+    value: T[0] | undefined;
+    error?: Error;
+
+    /**
+     * Place the observable into an error state.
+     *
+     * The error is cleared on next emit.
+     */
+    reject(cause: unknown): void;
+
+    then<TResult1 = T, TResult2 = never>(
+        onfulfilled?: ((value: T[0]) => TResult1 | PromiseLike<TResult1>) | null,
+        onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null,
+    ): Promise<TResult1 | TResult2>;
+
+    catch<TResult = never>(
+        onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null,
+    ): Promise<T[0] | TResult>;
+}
+
 /**
  * An observer may designate itself as "not observant" for the purposes of {@link Observable.isObserved} by returning
  * false from this field.
@@ -315,12 +355,12 @@ export class BasicObservable<T extends any[] = any[], R = void> implements Obser
     }
 
     then<TResult1 = T, TResult2 = never>(
-        onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null,
+        onfulfilled?: ((value: T[0]) => TResult1 | PromiseLike<TResult1>) | null,
         onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null,
-    ): PromiseLike<TResult1 | TResult2> {
+    ): Promise<TResult1 | TResult2> {
         return new Promise<T>(resolve => {
             this.once((...payload): undefined => {
-                resolve(payload);
+                resolve(payload[0]);
             });
         }).then(onfulfilled, onrejected);
     }
@@ -417,6 +457,115 @@ function event<E, N extends string>(emitter: E, name: N) {
     return observer as Observable;
 }
 
+/**
+ * A concrete {@link ObservableValue} implementation.
+ */
+export class BasicObservableValue<T extends [any, ...any[]] = [boolean]>
+    extends BasicObservable<T, void>
+    implements ObservableValue<T>
+{
+    #value: T | undefined;
+    #error?: Error;
+    #awaiters?: {
+        resolve?: ((value: T[0]) => void) | null;
+        reject?: ((reason: any) => void) | null;
+    }[];
+
+    constructor(value?: T, handleError?: ObserverErrorHandler, asyncConfig?: ObserverPromiseHandler | boolean) {
+        super(handleError, asyncConfig);
+        this.#value = value;
+        this.on(this.#maybeResolve.bind(this) as unknown as Observer<T, void>);
+    }
+
+    /**
+     * The current value.
+     *
+     * This will resolve the promise interface but you must use {@link emit} to also emit an event..
+     */
+    get value(): T[0] | undefined {
+        return this.#value;
+    }
+
+    set value(value: T[0] | undefined) {
+        this.#maybeResolve([value]);
+    }
+
+    get error() {
+        return this.#error;
+    }
+
+    reject(cause: unknown) {
+        cause = asError(cause);
+        this.#value = undefined;
+        this.#error = cause as Error;
+        const awaiters = this.#awaiters;
+        if (awaiters) {
+            this.#awaiters = undefined;
+            for (const awaiter of awaiters) {
+                awaiter.reject?.(cause as Error);
+            }
+        }
+    }
+
+    #maybeResolve(value: T[0] | undefined) {
+        this.#value = value;
+        if (!this.#value) {
+            return;
+        }
+
+        const awaiters = this.#awaiters;
+        if (awaiters) {
+            this.#awaiters = undefined;
+            for (const awaiter of awaiters) {
+                awaiter.resolve?.(this.#value);
+            }
+        }
+    }
+
+    override then<TResult1 = T, TResult2 = never>(
+        onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | null,
+        onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null,
+    ): Promise<TResult1 | TResult2> {
+        if (this.#error) {
+            return Promise.reject(this.#error).then(onfulfilled, onrejected);
+        }
+        if (this.#value) {
+            return Promise.resolve(this.#value).then(onfulfilled, onrejected);
+        }
+
+        return new Promise<T>((resolve, reject) => {
+            if (!this.#awaiters) {
+                this.#awaiters = [];
+            }
+            this.#awaiters.push({ resolve, reject });
+        }).then(onfulfilled, onrejected);
+    }
+
+    catch<TResult = never>(
+        onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null,
+    ): Promise<T | TResult> {
+        return this.then(undefined, onrejected);
+    }
+
+    finally(onfinally?: (() => void) | null): Promise<T> {
+        return Promise.resolve(this).finally(onfinally);
+    }
+
+    [Symbol.toStringTag] = "Promise";
+}
+
+/**
+ * Create an {@link ObservableValue}.
+ */
+export const ObservableValue = constructObservableValue as unknown as {
+    new <T extends [any, ...any[]]>(value?: T, errorHandler?: ObserverErrorHandler): ObservableValue<T>;
+    <T extends [any, ...any[]]>(value?: T, errorHandler?: ObserverErrorHandler): ObservableValue<T>;
+};
+
+function constructObservableValue(value?: [unknown, ...unknown[]], handleError?: ObserverErrorHandler) {
+    return new ObservableValue(value, handleError);
+}
+
 /**
  * A set of observables.  You can bind events using individual observables or the methods emulating a subset Node's
  * EventEmitter.

package/src/util/Promises.ts

@@ -400,3 +400,112 @@ export class Gate<T = void> implements Promise<T> {
 }
 
 MaybePromise.toString = () => "MaybePromise";
+
+/**
+ * Replacements for standard promise functionality that avoid spec pitfalls.
+ */
+export namespace SafePromise {
+    /**
+     * A version of {@link Promise.race} that won't leak memory with long-lived promises.
+     *
+     * See:
+     *
+     *     https://github.com/nodejs/node/issues/17469#issuecomment-685216777
+     *
+     * ...although this isn't an issue specific to Node.
+     */
+    export function race<T>(values: Iterable<T>): Promise<Awaited<T>> {
+        let listener!: SettlementListener;
+        let registered: undefined | Set<SettlementListener>[];
+
+        let race = new Promise<Awaited<T>>((resolve, reject) => {
+            listener = { resolve, reject };
+
+            for (const value of values) {
+                // If this is not a promise we can safely use Promise#resolve
+                if (!MaybePromise.is<any>(value)) {
+                    Promise.resolve(value).then(resolve, reject);
+                    continue;
+                }
+
+                // We only use Promise#then once per promise and dispatch to a set of listeners from there
+                const settlement = settlementOf(value);
+                if (settlement.isSettled) {
+                    value.then(resolve, reject);
+                    continue;
+                }
+
+                // Register our listener
+                settlement.listeners.add(listener);
+
+                // Save the listener set so we can unregister our listener
+                if (registered) {
+                    registered.push(settlement.listeners);
+                } else {
+                    registered = [settlement.listeners];
+                }
+            }
+        });
+
+        // If there were any unsettled promises, unregister our listener when settled
+        if (registered) {
+            race = race.finally(() => {
+                for (const listeners of registered!) {
+                    listeners.delete(listener);
+                }
+            });
+        }
+
+        return race;
+    }
+
+    interface SettlementListener {
+        resolve?: (result: any) => any;
+        reject?: (cause: any) => any;
+    }
+
+    interface Settlement {
+        isSettled: boolean;
+        listeners: Set<SettlementListener>;
+    }
+
+    const settlements = new WeakMap<PromiseLike<any>, Settlement>();
+
+    /**
+     * Component of {@link race}.
+     *
+     * Creates a {@link Settlement} that dispatches settlement to {@link SettlementListener}s for each raced promise.
+     */
+    function settlementOf(promise: PromiseLike<any>) {
+        const existing = settlements.get(promise);
+        if (existing) {
+            return existing;
+        }
+
+        const settlement: Settlement = { isSettled: false, listeners: new Set() };
+        settlements.set(promise, settlement);
+
+        promise.then(
+            value => {
+                settlement.isSettled = true;
+
+                for (const listener of settlement.listeners) {
+                    listener.resolve?.(value);
+                }
+
+                settlement.listeners.clear();
+            },
+            cause => {
+                settlement.isSettled = true;
+
+                for (const listener of settlement.listeners) {
+                    listener.reject?.(cause);
+                }
+
+                settlement.listeners.clear();
+            },
+        );
+
+        return settlement;
+    }
+}

package/src/util/Set.ts

@@ -5,7 +5,7 @@
  */
 
 import { ImplementationError } from "#MatterError.js";
-import { Observable } from "./Observable.js";
+import { Observable, ObservableValue } from "./Observable.js";
 
 /**
  * A read-only set.
@@ -34,6 +34,7 @@ export interface MutableSet<T, AddT = T> {
 export interface ObservableSet<T> {
     get added(): Observable<[T]>;
     get deleted(): Observable<[T]>;
+    get empty(): ObservableValue;
 }
 
 /**
@@ -63,6 +64,7 @@ export class BasicSet<T, AddT = T> implements ImmutableSet<T>, MutableSet<T, Add
     #entries = new Set<T>();
     #added?: Observable<[T]>;
     #deleted?: Observable<[T]>;
+    #empty?: ObservableValue;
     #indices?: {
         [field in keyof T]?: Map<T[field], T>;
     };
@@ -211,6 +213,10 @@ export class BasicSet<T, AddT = T> implements ImmutableSet<T>, MutableSet<T, Add
 
         this.#deleted?.emit(item);
 
+        if (this.#empty && !this.size) {
+            this.#empty.emit(true);
+        }
+
         return true;
     }
 
@@ -234,6 +240,13 @@ export class BasicSet<T, AddT = T> implements ImmutableSet<T>, MutableSet<T, Add
         return this.#deleted;
     }
 
+    get empty() {
+        if (this.#empty === undefined) {
+            this.#empty = ObservableValue();
+        }
+        return this.#empty;
+    }
+
     protected create(definition: AddT) {
         return definition as unknown as T;
     }

package/src/util/index.ts

@@ -17,6 +17,7 @@ export * from "./DataWriter.js";
 export * from "./Decorator.js";
 export * from "./DeepCopy.js";
 export * from "./DeepEqual.js";
+export * from "./Entropy.js";
 export * from "./Error.js";
 export * from "./FormattedText.js";
 export * from "./GeneratedClass.js";