@matter/general 0.11.0-alpha.0-20241005-e3e4e4a7a

package/src/util/Promises.ts

@@ -0,0 +1,278 @@
+/**
+ * Utils for promises.
+ *
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError, MatterError } from "../MatterError.js";
+import { Time } from "../time/Time.js";
+
+/**
+ * Obtain a promise with functions to resolve and reject.
+ */
+export function createPromise<T>(): {
+    promise: Promise<T>;
+    resolver: (value: T) => void;
+    rejecter: (reason?: any) => void;
+} {
+    let resolver, rejecter;
+    const promise = new Promise<T>((resolve, reject) => {
+        resolver = resolve;
+        rejecter = reject;
+    });
+
+    if (!resolver || !rejecter) {
+        // This doesn't happen but asserts that resolver and rejecter are defined.
+        throw new InternalError("Failed to extract resolve/reject from Promise context");
+    }
+
+    return {
+        promise,
+        resolver,
+        rejecter,
+    };
+}
+
+/**
+ * Use all promises or promise returning methods and return the first resolved promise or reject when all promises
+ * rejected
+ */
+export function anyPromise<T>(promises: ((() => Promise<T>) | Promise<T>)[]): Promise<T> {
+    return new Promise((resolve, reject) => {
+        let numberRejected = 0;
+        let wasResolved = false;
+        for (const entry of promises) {
+            const promise = typeof entry === "function" ? entry() : entry;
+            promise
+                .then(value => {
+                    if (!wasResolved) {
+                        wasResolved = true;
+                        resolve(value);
+                    }
+                })
+                .catch(reason => {
+                    numberRejected++;
+                    if (!wasResolved && numberRejected === promises.length) {
+                        reject(reason);
+                    }
+                });
+        }
+    });
+}
+
+/**
+ * Thrown when a timed promise times out.
+ */
+export class PromiseTimeoutError extends MatterError {
+    constructor(message = "Operation timed out") {
+        super(message);
+    }
+}
+
+/**
+ * Create a promise with a timeout.
+ *
+ * By default rejects with {@link PromiseTimeoutError} on timeout but you can override by supplying {@link cancel}.
+ *
+ * @param timeoutMs 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,
+    promise: Promise<T>,
+    cancel?: AbortController | (() => void),
+): Promise<T> {
+    let cancelFn;
+    if (typeof cancel === "function") {
+        cancelFn = cancel;
+    } else if (typeof cancel?.abort === "function") {
+        cancelFn = () => cancel.abort();
+    } else {
+        cancelFn = () => {
+            throw new PromiseTimeoutError();
+        };
+    }
+
+    let cancelTimer: undefined | (() => void);
+
+    // Sub-promise 1, the timer
+    const timeout = new Promise<void>((resolve, reject) => {
+        const timer = Time.getTimer("promise-timeout", timeoutMs, () => reject(cancelFn));
+
+        cancelTimer = () => {
+            timer.stop();
+            resolve();
+        };
+
+        timer.start();
+    });
+
+    let result: undefined | T;
+
+    // Sub-promise 2, captures result and cancels timer
+    const producer = promise.then(
+        r => {
+            cancelTimer?.();
+            result = r;
+        },
+        e => {
+            cancelTimer?.();
+            throw e;
+        },
+    );
+
+    // Output promise, resolves like input promise unless timed out
+    await Promise.all([timeout, producer]);
+
+    return result as T;
+}
+
+/**
+ * Return type for functions that are optionally asynchronous.
+ *
+ * TODO - as currently defined MaybePromise of a Promise incorrectly wraps as a Promise of a Promise
+ */
+export type MaybePromise<T = void> = T | PromiseLike<T>;
+
+/**
+ * Promise-like version of above.
+ */
+export type MaybePromiseLike<T = void> = T | PromiseLike<T>;
+
+export const MaybePromise = {
+    /**
+     * Determine whether a {@link MaybePromiseLike} is a {@link Promise}.
+     */
+    is<T>(value: MaybePromise<T>): value is PromiseLike<T> {
+        // We cannot use isObject because this could collide with valid values here
+        return typeof value === "object" && value !== null && typeof (value as { then?: unknown }).then === "function";
+    },
+
+    /**
+     * Chained MaybePromise.  Invokes the resolve function immediately if the {@link MaybePromise} is not a
+     * {@link Promise}, otherwise the same as a normal {@link Promise.then}.
+     */
+    then<I, O1 = never, O2 = never>(
+        producer: MaybePromise<I> | (() => MaybePromise<I>),
+        resolve?: ((input: I) => MaybePromise<O1>) | null,
+        reject?: ((error: any) => MaybePromise<O2>) | null,
+    ): MaybePromise<O1 | O2> {
+        let rejected = false;
+
+        try {
+            let value;
+            if (producer instanceof Function) {
+                value = producer();
+            } else {
+                value = producer;
+            }
+            if (MaybePromise.is(value)) {
+                return value.then(
+                    resolve,
+                    reject
+                        ? error => {
+                              // If reject() is not async then we will catch rejection errors below but should not
+                              // reject again
+                              rejected = true;
+
+                              return reject?.(error);
+                          }
+                        : undefined,
+                );
+            }
+            if (resolve) {
+                return resolve(value);
+            }
+        } catch (e) {
+            if (reject && !rejected) {
+                return reject(e);
+            }
+            throw e;
+        }
+
+        // Make TypeScript happy
+        return undefined as MaybePromise<O1 | O2>;
+    },
+
+    /**
+     * Equivalent of {@link Promise.catch}.
+     */
+    catch<T, TResult = never>(
+        producer: MaybePromise<T> | (() => MaybePromise<T>),
+        onrejected?: ((reason: any) => MaybePromise<TResult>) | undefined | null,
+    ) {
+        return this.then(producer, undefined, onrejected);
+    },
+
+    /**
+     * Equivalent of {@link Promise.finally}.
+     */
+    finally<T>(
+        producer: MaybePromise<T> | (() => MaybePromise<T>),
+        onfinally?: (() => MaybePromise<void>) | undefined | null,
+    ): MaybePromise<T> {
+        let result: MaybePromise<T> | undefined;
+        try {
+            if (typeof producer === "function") {
+                result = (producer as () => MaybePromise<T>)();
+            } else {
+                result = producer;
+            }
+        } finally {
+            if (MaybePromise.is(result)) {
+                // Use native finally or fake via then
+                if (typeof (result as Promise<any>).finally === "function") {
+                    // TypeScript's types are wrong for finally, they specify the callback as () => void rather than
+                    // accepting a promise return.  TS itself somehow doesn't mind this because a function returning
+                    // something can be assigned to a promise returning void.
+                    //
+                    // The TS folks rationalize this here:
+                    //
+                    //      https://github.com/microsoft/TypeScript/issues/44980
+                    //
+                    // Eslint used to work around this sometimes (was never sure when or whether it was intentional) but
+                    // something broke when we updated typescript-eslint to 7.1.1.
+                    //
+                    // The eslint folks blow this off here.  Includes a comment referencing a TS playground that
+                    // demonstrates eslint behavior is incorrect:
+                    //
+                    //      https://github.com/typescript-eslint/typescript-eslint/issues/7276
+                    //
+                    // eslint-disable-next-line @typescript-eslint/no-misused-promises
+                    result = (result as Promise<T>).finally(onfinally);
+                } else {
+                    result = result.then(
+                        value =>
+                            MaybePromise.then(
+                                () => onfinally?.(),
+                                () => value,
+                            ),
+                        error =>
+                            MaybePromise.then(
+                                () => onfinally?.(),
+                                () => {
+                                    throw error;
+                                },
+                            ),
+                    );
+                }
+            } else {
+                // The only return value from onfinally that should affect results is a rejected promise, so if we
+                // receive a return value chain such that it either throws or we return the actual result
+                const finallyResult = onfinally?.();
+                if (MaybePromise.is(finallyResult)) {
+                    const actualResult = result as T;
+                    result = finallyResult.then(() => actualResult);
+                }
+            }
+        }
+        return result;
+    },
+
+    [Symbol.toStringTag]: "MaybePromise",
+};
+
+MaybePromise.toString = () => "MaybePromise";

package/src/util/Set.ts

@@ -0,0 +1,189 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Observable } from "./Observable.js";
+
+/**
+ * A read-only set.
+ */
+export interface ImmutableSet<T> {
+    [Symbol.iterator]: () => Iterator<T, undefined>;
+    has(item: T): boolean;
+    get size(): number;
+    find(predicate: (item: T) => boolean | undefined): T | undefined;
+    filter(predicate: (item: T) => boolean | undefined): T[];
+}
+
+/**
+ * A write-only set.
+ */
+export interface MutableSet<T, AddT = T> {
+    add(definition: AddT): void;
+    delete(definition: T): boolean;
+    clear(): void;
+}
+
+/**
+ * Set change events.
+ */
+export interface ObservableSet<T> {
+    get added(): Observable<[T]>;
+    get deleted(): Observable<[T]>;
+}
+
+/**
+ * An interface for index set lookup.
+ */
+export interface IndexedSet<T> {
+    get<F extends keyof T>(field: F, value: T[F]): T | undefined;
+}
+
+/**
+ * A generic set implementation supporting all interfaces in this module.
+ *
+ * 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>();
+    #added?: Observable<[T]>;
+    #deleted?: Observable<[T]>;
+    #indices?: {
+        [field in keyof T]?: Map<any, T>;
+    };
+
+    constructor(...initialItems: AddT[]) {
+        for (const item of initialItems) {
+            this.add(item);
+        }
+    }
+
+    [Symbol.iterator]() {
+        return this.#entries[Symbol.iterator]();
+    }
+
+    get size() {
+        return this.#entries.size;
+    }
+
+    map<R>(mapper: (item: T) => R) {
+        return [...this].map(mapper);
+    }
+
+    find(predicate: (item: T) => boolean | undefined) {
+        for (const item of this) {
+            if (predicate(item)) {
+                return item;
+            }
+        }
+    }
+
+    filter(predicate: (item: T) => boolean | undefined) {
+        const result = new Array<T>();
+        for (const item of this) {
+            if (predicate(item)) {
+                result.push(item);
+            }
+        }
+        return result;
+    }
+
+    has(item: T) {
+        return this.#entries.has(item);
+    }
+
+    add(item: AddT) {
+        const created = this.create(item);
+
+        if (this.#entries.has(item as any)) {
+            return;
+        }
+
+        this.#entries.add(item as any);
+
+        if (this.#indices) {
+            for (const field in this.#indices) {
+                const value = created[field];
+                if (value === undefined) {
+                    continue;
+                }
+
+                const index = this.#indices[field];
+                if (index === undefined || index.has(value)) {
+                    continue;
+                }
+
+                index.set(value, created);
+            }
+        }
+
+        this.#added?.emit(created);
+    }
+
+    get<F extends keyof T>(field: F, value: T[F]) {
+        if (!this.#indices) {
+            this.#indices = {};
+        }
+        let index = this.#indices[field];
+        if (index === undefined) {
+            index = new Map<any, T>();
+            for (const item of this) {
+                const value = item[field];
+                if (value === undefined || index.has(value)) {
+                    continue;
+                }
+                index.set(value, item);
+            }
+            this.#indices[field] = index;
+        }
+        return index?.get(value);
+    }
+
+    delete(item: T) {
+        if (!this.#entries.delete(item)) {
+            return false;
+        }
+
+        if (this.#indices) {
+            for (const field in this.#indices) {
+                const value = item[field];
+                if (value === undefined) {
+                    continue;
+                }
+
+                const index = this.#indices[field];
+                if (index !== undefined && index.get(value) === item) {
+                    index.delete(value);
+                }
+            }
+        }
+
+        this.#deleted?.emit(item);
+
+        return true;
+    }
+
+    clear() {
+        this.#entries.clear();
+    }
+
+    get added() {
+        if (this.#added === undefined) {
+            this.#added = Observable();
+        }
+        return this.#added;
+    }
+
+    get deleted() {
+        if (this.#deleted === undefined) {
+            this.#deleted = Observable();
+        }
+        return this.#deleted;
+    }
+
+    protected create(definition: AddT) {
+        return definition as unknown as T;
+    }
+}

package/src/util/Singleton.ts

@@ -0,0 +1,13 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export function singleton<T>(create: () => T) {
+    let instance: T | undefined;
+    return () => {
+        if (instance === undefined) instance = create();
+        return instance;
+    };
+}

package/src/util/Stream.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { MatterError } from "../MatterError.js";
+
+export class EndOfStreamError extends MatterError {
+    constructor(message = "Unexpected end of stream") {
+        super(message);
+    }
+}
+
+export class NoResponseTimeoutError extends MatterError {}
+
+export interface Stream<T> {
+    read(): Promise<T>;
+    write(data: T): Promise<void>;
+}