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

package/src/util/Heap.ts

@@ -0,0 +1,332 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError } from "#MatterError.js";
+import { Abort } from "./Abort.js";
+import { Observable } from "./Observable.js";
+
+/**
+ * A heap, useful as a priority queue.
+ *
+ * Features:
+ *
+ * * Configurable as min-heap or max-heap using comparator
+ *
+ * * O(1) lookup of first item
+ *
+ * * O(log(n)) enqueue and dequeue
+ *
+ * * O(1) deletion of arbitrary position, but will add expense of maintaining index of positions
+ *
+ * * {@link added}, {@link deleted} and {@link firstChanged} events
+ */
+export class Heap<T> {
+    // We encode the heap as an array for efficiency.  See #leftChildOf and #rightChildOf for how to navigate the tree
+    // when encoded this way
+    readonly #buffer = Array<T>();
+
+    readonly #compare: (a: T, b: T) => number;
+    readonly #normalize?: (a: T) => T;
+    #firstChanged?: Observable<[T | undefined]>;
+    #deleted?: Observable<[T]>;
+    #added?: Observable<[T]>;
+    #positions?: Map<T, number>;
+
+    /**
+     * Create new heap.
+     *
+     * @param comparator performs ordering of items in the heap
+     * @param normalizer optionally converts items to normal form on insert
+     */
+    constructor(comparator: (a: T, b: T) => number, normalizer?: (entry: T) => T) {
+        this.#compare = comparator;
+        this.#normalize = normalizer;
+    }
+
+    /**
+     * Return lowest-ranked item.
+     */
+    shift() {
+        if (!this.#buffer?.length) {
+            return undefined;
+        }
+        const result = this.first;
+
+        this.#deleteAt(0);
+
+        return result;
+    }
+
+    /**
+     * The lowest-ranked item.
+     */
+    get first(): T | undefined {
+        return this.#buffer?.[0];
+    }
+
+    /**
+     * The queue length.
+     */
+    get size() {
+        return this.#buffer.length;
+    }
+
+    /**
+     * Is the heap empty?
+     */
+    get isEmpty() {
+        return !!this.#buffer.length;
+    }
+
+    /**
+     * Emits when the head of the queue changes.
+     */
+    get firstChanged() {
+        if (!this.#firstChanged) {
+            this.#firstChanged = new Observable();
+        }
+        return this.#firstChanged;
+    }
+
+    /**
+     * Emits when an item is added to the heap.
+     */
+    get added() {
+        if (!this.#added) {
+            this.#added = new Observable();
+        }
+        return this.#added;
+    }
+
+    /**
+     * Emits when an item is deleted.
+     */
+    get deleted() {
+        if (!this.#deleted) {
+            this.#deleted = new Observable();
+        }
+        return this.#deleted;
+    }
+
+    /**
+     * Add an item.
+     */
+    add(...items: T[]) {
+        for (let item of items) {
+            if (this.#normalize) {
+                item = this.#normalize(item);
+            }
+
+            this.#buffer.push(item);
+            this.#bubbleUp(this.#buffer.length - 1);
+
+            this.#added?.emit(item);
+        }
+    }
+
+    /**
+     * Delete an item.
+     *
+     * The first delete is O(n); subsequent deletes are O(1) but insertions and deletions will have additional cost
+     * associated.
+     */
+    delete(item: T) {
+        if (this.#buffer === undefined) {
+            return false;
+        }
+
+        if (!this.#positions) {
+            this.#positions = new Map();
+            for (let i = 0; i < this.#buffer.length; i++) {
+                this.#positions.set(this.#buffer[i], i);
+            }
+        }
+
+        if (this.#normalize) {
+            item = this.#normalize(item);
+        }
+
+        const pos = this.#positions.get(item);
+        if (pos === undefined) {
+            return false;
+        }
+
+        this.#deleteAt(pos);
+        return true;
+    }
+
+    /**
+     * Remove all entries.
+     */
+    clear() {
+        if (this.#buffer.length) this.#buffer.length = 0;
+    }
+
+    /**
+     * Stream the first value from the heap until aborted.
+     */
+    async *stream(abort?: Abort.Signal) {
+        if (Abort.is(abort)) {
+            return;
+        }
+
+        while (true) {
+            // Yield values currently available
+            while (this.size) {
+                yield this.shift()!;
+
+                if (Abort.is(abort)) {
+                    return;
+                }
+            }
+
+            // Create promise to resolve when a new value is ready
+            let resolve!: () => void;
+            const ready = new Promise<void>(r => (resolve = r));
+
+            // Wait for new value
+            try {
+                this.added.once(resolve);
+
+                await Abort.race(abort, ready);
+
+                if (Abort.is(abort)) {
+                    return;
+                }
+            } finally {
+                this.added.off(resolve);
+            }
+        }
+    }
+
+    /**
+     * Perform internal validation of queue order.
+     */
+    validate() {
+        for (let i = 0; i < this.#buffer.length; i++) {
+            const leftChild = this.#leftChildOf(i);
+            if (leftChild < this.#buffer.length) {
+                if (this.#compare(this.#buffer[i], this.#buffer[leftChild]) > 0) {
+                    throw new InternalError(
+                        `Heap error: buffer #${i} (${this.#buffer[i]}) is greater than left child #${leftChild} (${this.#buffer[leftChild]})`,
+                    );
+                }
+
+                const rightChild = this.#rightChildOf(i);
+                if (rightChild < this.#buffer.length) {
+                    if (this.#compare(this.#buffer[i], this.#buffer[rightChild]) > 0) {
+                        throw new InternalError(
+                            `Heap error: buffer #${i} (${this.#buffer[i]}) is greater than right child #${rightChild} (${this.#buffer[rightChild]})`,
+                        );
+                    }
+
+                    if (this.#compare(this.#buffer[leftChild], this.#buffer[rightChild]) > 0) {
+                        throw new InternalError(
+                            `Heap error: buffer #${leftChild} (${this.#buffer[leftChild]}) is greater than right sibling #${rightChild} (${this.#buffer[rightChild]})`,
+                        );
+                    }
+                }
+            }
+        }
+    }
+
+    #deleteAt(index: number) {
+        if (index >= this.#buffer.length) {
+            return;
+        }
+
+        const item = this.#buffer[index];
+        if (this.#buffer.length === 1) {
+            this.#buffer.length = 0;
+        } else {
+            const lastIndex = this.#buffer.length - 1;
+            this.#buffer[index] = this.#buffer[lastIndex];
+            this.#positions?.set(this.#buffer[index], index);
+            this.#buffer.length = lastIndex;
+            if (index < this.#buffer.length) {
+                if (index) {
+                    index = this.#bubbleUp(index);
+                }
+                this.#sinkDown(index);
+            }
+        }
+
+        this.#positions?.delete(item);
+
+        this.#deleted?.emit(item);
+        if (!index) {
+            this.#firstChanged?.emit(this.first);
+        }
+    }
+
+    #sinkDown(index: number) {
+        while (true) {
+            let moveTo: number | undefined;
+
+            const leftChild = this.#leftChildOf(index);
+
+            if (leftChild < this.#buffer.length) {
+                if (this.#compare(this.#buffer[index], this.#buffer[leftChild]) > 0) {
+                    moveTo = leftChild;
+                }
+
+                const rightChild = this.#rightChildOf(index);
+
+                if (rightChild < this.#buffer.length) {
+                    if (this.#compare(this.#buffer[moveTo ?? index], this.#buffer[rightChild]) > 0) {
+                        moveTo = rightChild;
+                    }
+                }
+            }
+
+            if (moveTo === undefined) {
+                break;
+            }
+
+            this.#swap(index, moveTo);
+            index = moveTo;
+        }
+    }
+
+    #bubbleUp(index: number) {
+        while (index) {
+            const parent = this.#parentOf(index);
+
+            if (this.#compare(this.#buffer[parent], this.#buffer[index]) <= 0) {
+                break;
+            }
+
+            this.#swap(index, parent);
+            index = parent;
+        }
+
+        if (!index) {
+            this.#firstChanged?.emit(this.first);
+        }
+
+        return index;
+    }
+
+    #swap(index1: number, index2: number) {
+        [this.#buffer[index1], this.#buffer[index2]] = [this.#buffer[index2], this.#buffer[index1]];
+        if (this.#positions) {
+            this.#positions.set(this.#buffer[index1], index1);
+            this.#positions.set(this.#buffer[index2], index2);
+        }
+    }
+
+    #leftChildOf(index: number) {
+        return 2 * index + 1;
+    }
+
+    #rightChildOf(index: number) {
+        return 2 * index + 2;
+    }
+
+    #parentOf(index: number) {
+        return Math.floor((index - 1) / 2);
+    }
+}

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/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";