@matter/general 0.16.0-alpha.0-20251030-e9ca79f93 → 0.16.0-alpha.0-20251031-0f308af69

package/src/util/Abort.ts

@@ -4,26 +4,216 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { TimeoutError } from "#MatterError.js";
+import { AbortedError, TimeoutError } from "#MatterError.js";
 import { Duration } from "#time/Duration.js";
 import { Time, Timer } from "#time/Time.js";
+import { asError } from "./Error.js";
+import { Callable } from "./Function.js";
 import { SafePromise } from "./Promises.js";
 
+/**
+ * Convenience abort implementation.
+ *
+ * Acts as both an {@link AbortController} and {@link AbortSignal}.
+ *
+ * May be awaited like a promise, although it returns the {@link reason} rather than throwing.
+ *
+ * May be invoked as a function to perform abort.
+ *
+ * Optionally will register for abort with an outer {@link AbortController} and/or add a timeout.  You must abort or
+ * invoke {@link close} if you use either of these options.
+ */
+export class Abort extends Callable<[reason?: Error]> implements AbortController, AbortSignal, PromiseLike<Error> {
+    // The native controller implementation
+    #controller: AbortController;
+
+    // Optional abort chaining
+    #dependents?: AbortSignal[];
+    #listener?: (reason: any) => void;
+
+    // Optional PromiseLike behavior
+    #aborted?: Promise<Error>;
+    #resolve?: (reason: Error) => void;
+
+    // Optional timeout
+    #timeout?: Timer;
+
+    constructor({ abort, timeout, handler }: Abort.Options = {}) {
+        super(() => this.abort());
+
+        this.#controller = new AbortController();
+
+        const self = (reason?: any) => {
+            this.abort(reason);
+        };
+        Object.setPrototypeOf(self, Object.getPrototypeOf(this));
+
+        if (abort && !Array.isArray(abort)) {
+            abort = [abort];
+        }
+
+        if (abort?.length) {
+            const dependents = abort.map(abort => ("signal" in abort ? abort.signal : abort));
+            this.#dependents = dependents;
+
+            this.#listener = (reason: any) => this.abort(reason);
+            for (const dependent of dependents) {
+                dependent.addEventListener("abort", this.#listener);
+            }
+        }
+
+        if (timeout) {
+            this.#timeout = Time.getPeriodicTimer("subtask timeout", timeout, () => {
+                if (this.aborted) {
+                    return;
+                }
+
+                this.abort(new TimeoutError());
+            });
+
+            this.#timeout.start();
+        }
+
+        if (handler) {
+            this.addEventListener("abort", () => handler(this.reason));
+        }
+    }
+
+    abort(reason?: any) {
+        this.#controller.abort(reason ?? new AbortedError());
+    }
+
+    get signal() {
+        return this.#controller.signal;
+    }
+
+    /**
+     * Race one or more promises with my abort signal.
+     *
+     * If aborted returns undefined.
+     */
+    async race<T>(...promises: Array<T | PromiseLike<T>>): Promise<Awaited<T> | void> {
+        return Abort.race(this, ...promises);
+    }
+
+    /**
+     * Free resources.
+     *
+     * You must abort or invoke {@link close} when finished if you construct with {@link Abort.Options#abort} or
+     * {@link Abort.Options#timeout}.
+     */
+    close() {
+        this.#timeout?.stop();
+        if (this.#listener && this.#dependents) {
+            for (const dependent of this.#dependents) {
+                dependent.removeEventListener("abort", this.#listener);
+            }
+        }
+    }
+
+    [Symbol.dispose]() {
+        this.close();
+    }
+
+    get aborted() {
+        return this.signal.aborted;
+    }
+
+    set onabort(onabort: ((this: AbortSignal, ev: Event) => any) | null) {
+        this.signal.onabort = onabort;
+    }
+
+    get onabort() {
+        return this.signal.onabort;
+    }
+
+    get reason() {
+        return asError(this.signal.reason);
+    }
+
+    throwIfAborted() {
+        this.signal.throwIfAborted();
+    }
+
+    then<TResult1 = void, TResult2 = never>(
+        onfulfilled?: ((value: Error) => TResult1 | PromiseLike<TResult1>) | null,
+        onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null,
+    ): PromiseLike<TResult1 | TResult2> {
+        if (!this.#aborted) {
+            this.#aborted = new Promise(resolve => (this.#resolve = resolve));
+            this.addEventListener("abort", () => this.#resolve!(asError(this.reason)));
+        }
+        return this.#aborted.then(onfulfilled, onrejected);
+    }
+
+    addEventListener<K extends keyof AbortSignalEventMap>(
+        type: K,
+        listener: (this: AbortSignal, ev: AbortSignalEventMap[K]) => any,
+        options?: boolean | AddEventListenerOptions,
+    ): void;
+    addEventListener(
+        type: string,
+        listener: EventListenerOrEventListenerObject,
+        options?: boolean | AddEventListenerOptions,
+    ): void;
+    addEventListener(type: any, listener: any, options?: any) {
+        this.signal.addEventListener(type, listener, options);
+    }
+
+    removeEventListener<K extends keyof AbortSignalEventMap>(
+        type: K,
+        listener: (this: AbortSignal, ev: AbortSignalEventMap[K]) => any,
+        options?: boolean | EventListenerOptions,
+    ): void;
+    removeEventListener(
+        type: string,
+        listener: EventListenerOrEventListenerObject,
+        options?: boolean | EventListenerOptions,
+    ): void;
+    removeEventListener(type: any, listener: any, options?: any) {
+        this.signal.addEventListener(type, listener, options);
+    }
+
+    dispatchEvent(event: Event) {
+        return this.signal.dispatchEvent(event);
+    }
+}
+
 /**
  * Utilities for implementing abort logic.
  */
 export namespace Abort {
     /**
-     * An entity that may be used to signal abort of an operation.
+     * Optional configuration for {@link Abort}.
      */
-    export type Signal = AbortController | AbortSignal;
+    export interface Options {
+        /**
+         * One or more parent abort signals.
+         *
+         * If a parent aborts, this {@link Abort} will abort as well.  However the inverse is not true, so this task is
+         * independently abortable.
+         *
+         * This functions similarly to {@link AbortSignal.any} but has additional protection against memory leaks.
+         */
+        abort?: Signal | Signal[];
+
+        /**
+         * An abort timeout.
+         *
+         * If you specify a timeout, you must either abort or close the {@link Abort}.
+         */
+        timeout?: Duration;
+
+        /**
+         * Adds a default abort handler.
+         */
+        handler?: (reason?: Error) => void;
+    }
 
     /**
-     * An abort controller that can be closed.
+     * An entity that may be used to signal abort of an operation.
      */
-    export interface DisposableController extends AbortController {
-        [Symbol.dispose](): void;
-    }
+    export type Signal = AbortController | AbortSignal;
 
     /**
      * Determine whether a {@link Signal} is aborted.
@@ -72,6 +262,17 @@ export namespace Abort {
         return SafePromise.race(promises);
     }
 
+    /**
+     * Perform abortable sleep.
+     */
+    export function sleep(description: string, abort: Signal | undefined, duration: Duration) {
+        let timer!: Timer;
+        const rested = new Promise<void>(resolve => {
+            timer = Time.getTimer(description, duration, resolve);
+        });
+        return race(abort, rested).finally(timer.stop.bind(timer));
+    }
+
     /**
      * Create independently abortable subtask with a new {@link AbortController} that is aborted if another controller
      * aborts.
@@ -80,39 +281,39 @@ export namespace Abort {
      *
      * {@link timeout} is a convenience for adding a timeout.
      */
-    export function subtask(signal: Signal | undefined, timeout?: Duration): DisposableController {
-        let timer: Timer | undefined;
-
-        if (signal && "signal" in signal) {
-            signal = signal.signal;
-        }
+    export function subtask(signal: Signal | undefined, timeout?: Duration): Abort {
+        return new Abort({ abort: signal, timeout });
+    }
 
-        const controller = new AbortController() as DisposableController;
+    /**
+     * Like {@link AbortSignal.any} but does not leak memory so long as the returned {@link Abort} is aborted or closed.
+     */
+    export function any(...signals: (Signal | undefined)[]) {
+        return new Abort({ abort: [...(signals.filter(signal => signal) as Signal[])] });
+    }
 
-        if (timeout) {
-            timer = Time.getPeriodicTimer("subtask timeout", timeout, () => {
-                if (controller.signal.aborted) {
-                    return;
-                }
+    /**
+     * Generate a function that will throw if aborted.
+     */
+    export function checkerFor(signal?: Signal | { abort?: Signal }) {
+        if (!signal) {
+            return () => {};
+        }
 
-                controller.abort(new TimeoutError());
-            });
-            timer.start();
+        if ("abort" in signal && typeof signal.abort === "object") {
+            signal = signal.abort;
+        }
+        if (!signal) {
+            return () => {};
         }
 
-        if (signal) {
-            const outerHandler = () => controller.abort(signal.reason);
-            signal.addEventListener("abort", outerHandler);
-            controller[Symbol.dispose] = () => {
-                signal.removeEventListener("abort", outerHandler);
-                timer?.stop();
-            };
-        } else {
-            controller[Symbol.dispose] = () => {
-                timer?.stop();
-            };
+        if ("signal" in signal) {
+            signal = signal.signal;
+        }
+        if (!signal) {
+            return () => {};
         }
 
-        return controller;
+        return (signal as AbortSignal).throwIfAborted.bind(signal);
     }
 }

package/src/util/Error.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { AbortedError } from "#MatterError.js";
 import type { Constructable } from "./Construction.js";
 import { ClassExtends } from "./Type.js";
 
@@ -14,6 +15,14 @@ function considerAsError(error: unknown): error is Error {
 
 export function asError(e: any): Error {
     if (considerAsError(e)) {
+        // AbortController defaults to a DOMException which isn't ideal; translate here
+        if (e instanceof DOMException && e.name === "AbortError") {
+            const aborted = new AbortedError(e.message);
+            aborted.stack = e.stack;
+            aborted.cause = e.cause;
+            return aborted;
+        }
+
         return e;
     }
     return new Error(e?.toString() ?? "Unknown error");

package/src/util/Function.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * A base for classes that are also functions.
+ */
+export interface Callable<A extends unknown[], R = void> {
+    (...args: A): R;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unsafe-declaration-merging
+export class Callable<A extends unknown[], R> {
+    /**
+     * Create a new invocable
+     */
+    constructor(invoke: Callable<A, R>) {
+        Object.setPrototypeOf(invoke, new.target.prototype);
+        return invoke;
+    }
+}

package/src/util/Observable.ts

@@ -138,7 +138,9 @@ export interface Observable<T extends any[] = any[], R = void> extends AsyncIter
  * 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]> {
+export interface ObservableValue<T extends [any, ...any[]] = [boolean], R extends MaybePromise<void> = void>
+    extends Observable<T, R>,
+        Promise<T[0]> {
     value: T[0] | undefined;
     error?: Error;
 
@@ -170,6 +172,11 @@ export const observant = Symbol("consider-observed");
  */
 export interface AsyncObservable<T extends any[] = any[], R = void> extends Observable<T, MaybePromise<R>> {}
 
+/**
+ * An {@link ObservableValue} that explicitly supports asynchronous observers.
+ */
+export interface AsyncObservableValue<T extends [any, ...any[]] = [boolean]> extends ObservableValue<T, MaybePromise> {}
+
 function defaultErrorHandler(error: Error) {
     throw error;
 }
@@ -425,10 +432,6 @@ export class BasicObservable<T extends any[] = any[], R = void> implements Obser
 
 type Next<T> = undefined | { value: T; promise: Promise<Next<T>> };
 
-function constructObservable(handleError?: ObserverErrorHandler) {
-    return new BasicObservable(handleError);
-}
-
 /**
  * Create an {@link Observable}.
  */
@@ -437,8 +440,8 @@ export const Observable = constructObservable as unknown as {
     <T extends any[], R = void>(errorHandler?: ObserverErrorHandler): Observable<T, R>;
 };
 
-function constructAsyncObservable(handleError?: ObserverErrorHandler) {
-    return new BasicObservable(handleError, true);
+function constructObservable(handleError?: ObserverErrorHandler) {
+    return new BasicObservable(handleError);
 }
 
 /**
@@ -449,6 +452,10 @@ export const AsyncObservable = constructAsyncObservable as unknown as {
     <T extends any[], R = void>(handleError?: ObserverErrorHandler): AsyncObservable<T, R>;
 };
 
+function constructAsyncObservable(handleError?: ObserverErrorHandler) {
+    return new BasicObservable(handleError, true);
+}
+
 function event<E, N extends string>(emitter: E, name: N) {
     const observer = (emitter as any)[name];
     if (typeof !observer?.on !== "function") {
@@ -471,7 +478,7 @@ export class BasicObservableValue<T extends [any, ...any[]] = [boolean]>
         reject?: ((reason: any) => void) | null;
     }[];
 
-    constructor(value?: T, handleError?: ObserverErrorHandler, asyncConfig?: ObserverPromiseHandler | boolean) {
+    constructor(value?: T[0], handleError?: ObserverErrorHandler, asyncConfig?: ObserverPromiseHandler | boolean) {
         super(handleError, asyncConfig);
         this.#value = value;
         this.on(this.#maybeResolve.bind(this) as unknown as Observer<T, void>);
@@ -558,12 +565,24 @@ export class BasicObservableValue<T extends [any, ...any[]] = [boolean]>
  * 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>;
+    new <T extends [any, ...any[]]>(value?: T[0], errorHandler?: ObserverErrorHandler): ObservableValue<T>;
+    <T extends [any, ...any[]]>(value?: T[0], errorHandler?: ObserverErrorHandler): ObservableValue<T>;
+};
+
+function constructObservableValue(value?: unknown, handleError?: ObserverErrorHandler) {
+    return new BasicObservableValue<any>(value, handleError);
+}
+
+/**
+ * Create an {@link AsyncObservableValue}.
+ */
+export const AsyncObservableValue = constructAsyncObservableValue as unknown as {
+    new <T extends [any, ...any[]]>(value?: T[0], errorHandler?: ObserverErrorHandler): AsyncObservableValue<T>;
+    <T extends [any, ...any[]]>(value?: T[0], errorHandler?: ObserverErrorHandler): AsyncObservableValue<T>;
 };
 
-function constructObservableValue(value?: [unknown, ...unknown[]], handleError?: ObserverErrorHandler) {
-    return new ObservableValue(value, handleError);
+function constructAsyncObservableValue(value?: unknown, handleError?: ObserverErrorHandler) {
+    return new BasicObservableValue<any>(value, handleError, true);
 }
 
 /**

package/src/util/Set.ts

@@ -138,6 +138,10 @@ export class BasicSet<T, AddT = T> implements ImmutableSet<T>, MutableSet<T, Add
         }
 
         this.#added?.emit(created);
+
+        if (this.#empty && this.#empty.value) {
+            this.#empty.emit(false);
+        }
     }
 
     get<F extends keyof T>(field: F, value: T[F]) {
@@ -242,7 +246,7 @@ export class BasicSet<T, AddT = T> implements ImmutableSet<T>, MutableSet<T, Add
 
     get empty() {
         if (this.#empty === undefined) {
-            this.#empty = ObservableValue();
+            this.#empty = ObservableValue(!this.#entries.size);
         }
         return this.#empty;
     }

package/src/util/index.ts

@@ -20,6 +20,7 @@ export * from "./DeepEqual.js";
 export * from "./Entropy.js";
 export * from "./Error.js";
 export * from "./FormattedText.js";
+export * from "./Function.js";
 export * from "./GeneratedClass.js";
 export * from "./Ip.js";
 export * from "./Lifecycle.js";