@matter/general 0.16.1 → 0.16.2-alpha.0-20260114-b38c6b796

package/src/util/Observable.ts

@@ -54,6 +54,16 @@ export interface Observable<T extends any[] = any[], R = void> extends AsyncIter
      */
     on(observer: Observer<T, R>): void;
 
+    /**
+     * Add an observer that may be released via disposal.
+     */
+    use(observer: Observer<T, R>): Disposable;
+
+    /**
+     * Add a "once" observer that may be released via disposal.
+     */
+    useOnce(observer: Observer<T, R>): Disposable;
+
     /**
      * Remove an observer.
      */
@@ -148,7 +158,13 @@ export interface Observable<T extends any[] = any[], R = void> extends AsyncIter
  */
 export interface ObservableValue<T extends [any, ...any[]] = [boolean], R extends MaybePromise<void> = void>
     extends Observable<T, R>, Promise<T[0]> {
+    /**
+     * The current value.
+     *
+     * Setting the value will resolve the promise interface but you must use {@link emit} to also emit an event.
+     */
     value: T[0] | undefined;
+
     error?: Error;
 
     /**
@@ -166,6 +182,12 @@ export interface ObservableValue<T extends [any, ...any[]] = [boolean], R extend
     catch<TResult = never>(
         onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null,
     ): Promise<T[0] | TResult>;
+
+    onError(handler: (cause: Error) => void): void;
+
+    offError(handler: (cause: Error) => void): void;
+
+    useError(handler: (cause: Error) => void): Disposable;
 }
 
 /**
@@ -344,7 +366,7 @@ export class BasicObservable<T extends any[] = any[], R = void> implements Obser
             };
         }
 
-        // Initially emit using a synchronous loop.  When we hit the first promies we convert to an async function
+        // Initially emit using a synchronous loop.  When we hit the first promise we convert to an async function
         for (; nextObserver < observers.length; nextObserver++) {
             let result: ReturnType<Observer<T, R>>;
 
@@ -410,8 +432,27 @@ export class BasicObservable<T extends any[] = any[], R = void> implements Obser
         this.#observers.add(observer);
     }
 
+    use(observer: Observer<T, R>) {
+        this.on(observer);
+        return {
+            [Symbol.dispose]: () => {
+                this.off(observer);
+            },
+        };
+    }
+
+    useOnce(observer: Observer<T, R>) {
+        this.once(observer);
+        return {
+            [Symbol.dispose]: () => {
+                this.off(observer);
+            },
+        };
+    }
+
     off(observer: Observer<T, R>) {
         this.#observers?.delete(observer);
+        this.#once?.delete(observer);
     }
 
     once(observer: Observer<T, R>) {
@@ -552,9 +593,9 @@ function event<E, N extends string>(emitter: E, name: N) {
 /**
  * A concrete {@link ObservableValue} implementation.
  */
-export class BasicObservableValue<T extends [any, ...any[]] = [boolean]>
-    extends BasicObservable<T, void>
-    implements ObservableValue<T>
+export class BasicObservableValue<T extends [any, ...any[]] = [boolean], R extends MaybePromise<void> = void>
+    extends BasicObservable<T, R>
+    implements ObservableValue<T, R>
 {
     #value: T | undefined;
     #error?: Error;
@@ -566,14 +607,12 @@ export class BasicObservableValue<T extends [any, ...any[]] = [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>);
+
+        const maybeResolve = this.#maybeResolve.bind(this) as unknown as Observer<T, R>;
+        Object.defineProperty(maybeResolve, observant, { value: false });
+        this.on(maybeResolve);
     }
 
-    /**
-     * 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;
     }
@@ -639,6 +678,27 @@ export class BasicObservableValue<T extends [any, ...any[]] = [boolean]>
         return this.then(undefined, onrejected);
     }
 
+    onError(handler: (cause: Error) => void) {
+        if (!this.#awaiters) {
+            this.#awaiters = [];
+        }
+        this.#awaiters?.push({ resolve: undefined, reject: handler });
+    }
+
+    offError(handler: (cause: Error) => void) {
+        this.#awaiters = this.#awaiters?.filter(awaiter => awaiter.resolve === undefined && awaiter.reject === handler);
+    }
+
+    useError(handler: (cause: Error) => void) {
+        this.onError(handler);
+
+        return {
+            [Symbol.dispose]: () => {
+                this.offError(handler);
+            },
+        };
+    }
+
     finally(onfinally?: (() => void) | null): Promise<T> {
         return Promise.resolve(this).finally(onfinally);
     }
@@ -924,6 +984,10 @@ export class ObserverGroup {
         this.#observers.clear();
         this.#boundObservers.clear();
     }
+
+    [Symbol.dispose]() {
+        this.close();
+    }
 }
 
 /**

package/src/util/Promises.ts

@@ -10,6 +10,13 @@ import { Duration } from "#time/Duration.js";
 import { asError } from "#util/Error.js";
 import { InternalError, TimeoutError } from "../MatterError.js";
 import { Time } from "../time/Time.js";
+import type {
+    AsyncObservable,
+    AsyncObservableValue,
+    AsyncObserver,
+    Observable,
+    ObservableValue,
+} from "./Observable.js";
 
 /**
  * Obtain a promise with functions to resolve and reject.
@@ -413,10 +420,14 @@ export namespace SafePromise {
      *     https://github.com/nodejs/node/issues/17469#issuecomment-685216777
      *
      * ...although this isn't an issue specific to Node.
+     *
+     * We specialize support for {@link Observable} and {@link ObservableValue}.  Those contracts are awaitable like a
+     * {@link Promise} but we instead register listeners directly so we can unregister using {@link Observable#off}.
      */
     export function race<T>(values: Iterable<T>): Promise<Awaited<T>> {
         let listener!: SettlementListener;
         let registered: undefined | Set<SettlementListener>[];
+        let disposables: undefined | Disposable[];
 
         let race = new Promise<Awaited<T>>((resolve, reject) => {
             listener = { resolve, reject };
@@ -428,6 +439,44 @@ export namespace SafePromise {
                     continue;
                 }
 
+                // If this is an Observable, use on/off so we can reliably unregister listeners
+                if (
+                    "use" in value &&
+                    "off" in value &&
+                    typeof value.use === "function" &&
+                    typeof value.off === "function"
+                ) {
+                    // Further specialize for ObservableValue contract, which behaves as resolved when a truthy value is
+                    // present
+                    if ("value" in value && value.value) {
+                        Promise.resolve(value.value as Awaited<T>).then(resolve, reject);
+                        continue;
+                    }
+
+                    if (!disposables) {
+                        disposables = [];
+                    }
+
+                    let observer: AsyncObserver<[Awaited<T>]>;
+                    if ("value" in value) {
+                        // For observable value, only resolve if value is truthy
+                        observer = value => {
+                            if (value) {
+                                resolve(value);
+                            }
+                        };
+
+                        // And handle errors
+                        disposables.push((value as unknown as AsyncObservableValue).useError(reject));
+                    } else {
+                        // Normal observables "resolve" on any emit and do not have an error channel
+                        observer = resolve;
+                    }
+                    disposables.push((value as unknown as AsyncObservable<[Awaited<T>]>).use(observer));
+
+                    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) {
@@ -447,11 +496,19 @@ export namespace SafePromise {
             }
         });
 
-        // If there were any unsettled promises, unregister our listener when settled
-        if (registered) {
+        // Ensure we unregister listeners when settled
+        if (registered || disposables) {
             race = race.finally(() => {
-                for (const listeners of registered!) {
-                    listeners.delete(listener);
+                if (registered) {
+                    for (const listeners of registered) {
+                        listeners.delete(listener);
+                    }
+                }
+
+                if (disposables) {
+                    for (const disposable of disposables) {
+                        disposable[Symbol.dispose]();
+                    }
                 }
             });
         }

package/src/util/Scheduler.ts

@@ -0,0 +1,185 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger } from "#log/Logger.js";
+import { ImplementationError } from "#MatterError.js";
+import { Time } from "#time/Time.js";
+import { Timestamp } from "#time/Timestamp.js";
+import { Abort } from "./Abort.js";
+import { asError } from "./Error.js";
+import { Heap } from "./Heap.js";
+import { Lifetime } from "./Lifetime.js";
+import { BasicMultiplex } from "./Multiplex.js";
+import { MaybePromise } from "./Promises.js";
+import { Semaphore } from "./Semaphore.js";
+
+const logger = Logger.get("Scheduler");
+
+/**
+ * Task scheduler.
+ *
+ * Runs workers at a designated time.
+ */
+export class Scheduler<T> {
+    #name: string;
+    #lifetime: Lifetime;
+    #timeOf: Scheduler.Configuration<T>["timeOf"];
+    #run: Scheduler.Configuration<T>["run"];
+    #queue: Heap<T>;
+    #abort = new Abort();
+    #workers = new BasicMultiplex();
+    #semaphore?: Semaphore;
+
+    constructor({
+        name = "scheduler",
+        lifetime = Lifetime.process,
+        timeOf,
+        run,
+        semaphore,
+    }: Scheduler.Configuration<T>) {
+        this.#name = name;
+        this.#lifetime = lifetime.join(this.#name);
+        this.#timeOf = timeOf;
+        this.#run = run;
+        this.#semaphore = semaphore;
+
+        this.#queue = new Heap(comparatorFor(timeOf));
+        this.#workers.add(this.#schedule());
+    }
+
+    /**
+     * Schedule a worker.
+     */
+    add(worker: T) {
+        if (this.#lifetime.isClosing) {
+            throw new ImplementationError(`Cannot schedule new work because ${this.#name} is closed`);
+        }
+        this.#queue.add(worker);
+    }
+
+    /**
+     * Unschedule a worker.
+     */
+    delete(worker: T) {
+        this.#queue.delete(worker);
+    }
+
+    /**
+     * Update a worker's scheduled run time.
+     */
+    reschedule(worker: T) {
+        this.#queue.delete(worker);
+        this.#queue.add(worker);
+    }
+
+    /**
+     * Close.
+     *
+     * Stops accepting workers.  Returns when all workers are complete.
+     */
+    async close() {
+        using _closing = this.#lifetime.closing();
+        this.#abort();
+        await this.#workers;
+    }
+
+    /**
+     * Performs actual scheduling of workers.
+     */
+    async #schedule() {
+        while (!this.#abort.aborted) {
+            // Activate workers that have no more delay
+            const now = Time.nowMs;
+            let first = this.#queue.first;
+            let nextAt = first ? this.#timeOf(first) : undefined;
+            while (nextAt !== undefined && nextAt <= now) {
+                if (this.#abort.aborted) {
+                    return;
+                }
+
+                let slot: undefined | Disposable;
+                if (this.#semaphore) {
+                    slot = await this.#semaphore.obtainSlot(this.#abort);
+                    if (this.#abort.aborted) {
+                        return;
+                    }
+                }
+
+                try {
+                    this.#queue.shift();
+                    const promise = this.#run(first!, this.#abort.signal);
+                    if (promise) {
+                        let p = Promise.resolve(promise).catch(this.#unhandled.bind(this));
+                        if (slot) {
+                            p = p.finally(() => slot[Symbol.dispose]());
+                        }
+                        this.#workers.add(p);
+                    } else {
+                        slot?.[Symbol.dispose]();
+                    }
+                } catch (e) {
+                    slot?.[Symbol.dispose]();
+                    this.#unhandled(e);
+                }
+
+                first = this.#queue.first;
+                nextAt = first ? this.#timeOf(first) : undefined;
+            }
+
+            // Wait for delay for next worker, abort or change in head of queue
+            using abort = new Abort({
+                abort: this.#abort,
+                timeout: nextAt === undefined ? undefined : Timestamp.delta(now, nextAt),
+            });
+            using _abortOnChange = this.#queue.firstChanged.use(newFirst => abort.if(newFirst !== first));
+            await abort;
+        }
+    }
+
+    #unhandled(e: unknown) {
+        logger.error(`Unhandled error in ${this.#name} worker:`, asError(e));
+    }
+}
+
+export namespace Scheduler {
+    export interface Configuration<T> {
+        /**
+         * Name used for diagnostics.
+         *
+         * Defaults to "scheduler".
+         */
+        name?: string;
+
+        /**
+         * Owner lifetime.
+         *
+         * Defaults to process.
+         */
+        lifetime?: Lifetime.Owner;
+
+        /**
+         * Identify the scheduled time for a specific worker.
+         */
+        timeOf(worker: T): Timestamp;
+
+        /**
+         * Execute a worker.
+         */
+        run(worker: T, abort: AbortSignal): MaybePromise<void>;
+
+        /**
+         * If present, controls worker concurrency.
+         *
+         * Providing the semaphore here rather than using it within the worker prevents the worker from starting when no
+         * queue slot is available.
+         */
+        semaphore?: Semaphore;
+    }
+}
+
+function comparatorFor<T>(timeOf: Scheduler.Configuration<T>["timeOf"]) {
+    return (a: T, b: T) => timeOf(a) - timeOf(b);
+}

package/src/util/Semaphore.ts

@@ -23,11 +23,6 @@ export interface WorkSlot extends Disposable {
      * This is called automatically when using `using` syntax.
      */
     close(): void;
-
-    /**
-     * Release the slot automatically when the object is garbage collected.
-     */
-    [Symbol.dispose](): void;
 }
 
 /**

package/src/util/Set.ts

@@ -61,7 +61,7 @@ export interface IndexedSet<T> {
  * Unused features have minimal performance impact.
  */
 export class BasicSet<T, AddT = T> implements ImmutableSet<T>, MutableSet<T, AddT>, ObservableSet<T>, IndexedSet<T> {
-    #entries = new Set<T>();
+    #entries?: Set<T>;
     #added?: Observable<[T]>;
     #deleted?: Observable<[T]>;
     #empty?: ObservableValue;
@@ -79,11 +79,11 @@ export class BasicSet<T, AddT = T> implements ImmutableSet<T>, MutableSet<T, Add
     }
 
     [Symbol.iterator]() {
-        return this.#entries[Symbol.iterator]();
+        return this.#definedEntries[Symbol.iterator]();
     }
 
     get size() {
-        return this.#entries.size;
+        return this.#entries?.size ?? 0;
     }
 
     map<R>(mapper: (item: T) => R) {
@@ -109,17 +109,17 @@ export class BasicSet<T, AddT = T> implements ImmutableSet<T>, MutableSet<T, Add
     }
 
     has(item: T) {
-        return this.#entries.has(item);
+        return this.#entries?.has(item) ?? false;
     }
 
     add(item: AddT) {
         const created = this.create(item);
 
-        if (this.#entries.has(item as any)) {
+        if (this.#definedEntries.has(item as any)) {
             return;
         }
 
-        this.#entries.add(item as any);
+        this.#definedEntries.add(item as any);
 
         if (this.#indices) {
             for (const field in this.#indices) {
@@ -148,6 +148,13 @@ export class BasicSet<T, AddT = T> implements ImmutableSet<T>, MutableSet<T, Add
         return this.#indexOf(field).get(value);
     }
 
+    get #definedEntries() {
+        if (this.#entries === undefined) {
+            this.#entries = new Set();
+        }
+        return this.#entries;
+    }
+
     #indexOf<F extends keyof T>(field: F) {
         if (!this.#indices) {
             this.#indices = {};
@@ -197,7 +204,7 @@ export class BasicSet<T, AddT = T> implements ImmutableSet<T>, MutableSet<T, Add
             }
         }
 
-        if (!this.#entries.delete(item)) {
+        if (!this.#entries?.delete(item)) {
             return false;
         }
 
@@ -246,7 +253,7 @@ export class BasicSet<T, AddT = T> implements ImmutableSet<T>, MutableSet<T, Add
 
     get empty() {
         if (this.#empty === undefined) {
-            this.#empty = ObservableValue(!this.#entries.size);
+            this.#empty = ObservableValue(!this.#entries?.size);
         }
         return this.#empty;
     }

package/src/util/index.ts

@@ -23,6 +23,7 @@ export * from "./FormattedText.js";
 export * from "./Function.js";
 export * from "./GeneratedClass.js";
 export * from "./Github.js";
+export * from "./Heap.js";
 export * from "./identifier-case.js";
 export * from "./Ip.js";
 export * from "./Lifecycle.js";
@@ -35,6 +36,7 @@ export * from "./NamedHandler.js";
 export * from "./Number.js";
 export * from "./Observable.js";
 export * from "./Promises.js";
+export * from "./Scheduler.js";
 export * from "./Semaphore.js";
 export * from "./serialize.js";
 export * from "./Set.js";