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

package/src/util/Construction.ts

@@ -0,0 +1,717 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger } from "../log/Logger.js";
+import { ImplementationError } from "../MatterError.js";
+import { errorOf } from "./Error.js";
+import { CrashedDependenciesError, CrashedDependencyError, Lifecycle } from "./Lifecycle.js";
+import { Observable } from "./Observable.js";
+import { MaybePromise } from "./Promises.js";
+
+/**
+ * Create an instance of a class implementing the {@link Constructable} pattern.
+ */
+export async function asyncNew<const A extends any[], const C extends new (...args: A) => Constructable<any>>(
+    constructor: C,
+    ...args: A
+): Promise<InstanceType<C>> {
+    const subject = new constructor(...args);
+
+    // If construction of the subject is not initiated you cannot use asyncNew because something needs to invoke
+    // Construction#start.
+    if (subject.construction.status === Lifecycle.Status.Inactive) {
+        throw new ImplementationError(
+            `You cannot use asyncNew on ${constructor.name} because its construction is controlled by another component`,
+        );
+    }
+
+    await subject.construction.ready;
+
+    return subject as InstanceType<C>;
+}
+
+/**
+ * A pattern for asynchronous object initialization and cleanup of a target object, called the "subject".
+ *
+ * Construction happens in the initializer parameter of {@link Construction} or via {@link Construction.construct} on
+ * the subject.  You invoke in your constructor and place in a property called "construction".
+ *
+ * Destruciton is optional and happens in the destructor parameter of {@link Construction#close} or via
+ * {@link Construction.destruct} on the subject.  Typically you invoke in a "close" method of the subject.
+ *
+ * If construction or destruction is not asynchronous (does not return a Promise) then they complete synchronously,
+ * including throwing exceptions.
+ *
+ * To ensure an instance is initialized prior to use you may await construction, so e.g. `await new
+ * MyConstructable().construction`. {@link asyncNew} is shorthand for this.  The creation code path can instead await
+ * {@link Construction.ready} to ensure handling of the root cause.
+ *
+ * Public APIs should provide a static async create() that performs an asyncNew().  The class will then adhere to
+ * Matter.js conventions and library users can ignore the complexities associated with async creation.
+ */
+export interface Constructable<T = object> {
+    readonly construction: Construction<T>;
+}
+
+export module Constructable {
+    /**
+     * An {@link Constructable} that supports deferred construction.
+     *
+     * This supports use cases where initialization initiates separately from construction and/or reinitialization is
+     * possible.
+     */
+    export interface Deferred<T, A extends unknown[]> extends Constructable<T> {
+        /**
+         * Perform deferred construction.
+         */
+        [Construction.construct](...args: A): MaybePromise<void>;
+    }
+
+    /**
+     * An object that supports destruction.
+     */
+    export interface Destructable {
+        /**
+         * Perform destruction. This is used invoked by {@link Constructable#close} after transitioning to
+         * {@link Lifecycle.Status.Destroying} but before transitioning to {@link Lifecycle.Status.Destroyed}.
+         *
+         * This is separate from {@link Symbol.dispose}/{@link Symbol.asyncDispose} so those can invoke
+         * {@link Constructable#close}.
+         */
+        [Construction.destruct](): MaybePromise<void>;
+    }
+}
+
+/**
+ * The promise implementing by an {@link Constructable#construction}.
+ */
+export interface Construction<T> extends Promise<T> {
+    /**
+     * If construction ends with an error, the error is saved here.
+     */
+    readonly error?: Error;
+
+    /**
+     * Status of the constructed object.
+     */
+    readonly status: Lifecycle.Status;
+
+    /**
+     * Notifications of state change.  Normally you just await construction but this offers more granular events and
+     * repeating events.
+     */
+    readonly change: Observable<[status: Lifecycle.Status, subject: T]>;
+
+    /**
+     * True iff the primary error has been or will be reported.
+     */
+    readonly isErrorHandled: boolean;
+
+    /**
+     * Resolves when construction completes; rejects if construction crashes.
+     *
+     * Behaves identically to {@link Construction} but always throws the primary cause rather than
+     * {@link CrashedDependencyError}.
+     *
+     * Handling errors on this promise will prevent other handlers from seeing the primary cause.
+     */
+    readonly ready: Promise<T>;
+
+    /**
+     * Resolves when destruction completes; rejects if the component crashes.
+     *
+     * Handling errors on this promise will prevent other handlers from seeing the primary cause.
+     */
+    readonly closed: Promise<T>;
+
+    /**
+     * If you omit the initializer parameter to {@link Construction} execution is deferred until you invoke this
+     * method to initiate construction via the {@link Constructable.Deferred} interface.
+     *
+     * Unlike the initializer, errors are always reported via the PromiseLike interface even if the constructable throws
+     * an error synchronously.
+     */
+    start<const T, const A extends unknown[], const This extends Construction<Constructable.Deferred<T, A>>>(
+        this: This,
+        ...args: A
+    ): void;
+
+    /**
+     * Invoke destruction logic then move to destroyed status.
+     *
+     * Typically you invoke this in the subject's "close" method.
+     *
+     * Use of this function is optional.  It provides these benefits:
+     *
+     *   - Ensures the subject is fully initialized before closing.
+     *
+     *   - Handles and logs errors, ensuring close() always completes successfully.
+     *
+     *   - Makes destruction observable via {@link change} and {@link closed}.
+     */
+    close(destructor?: () => MaybePromise): MaybePromise;
+
+    /**
+     * Throws an error if construction is ongoing or incomplete.
+     */
+    assert(description?: string): void;
+
+    /**
+     * Asserts construction is complete and that an object is defined.
+     */
+    assert<T>(description: string, dependency: T | undefined): T;
+
+    /**
+     * Manually force a specific {@link status}.
+     *
+     * This offers flexibility in component lifecycle management including resetting component to inactive state and
+     * broadcasting lifecycle changes.  On reset listeners are also reset and must be reinstalled.
+     *
+     * This method fails if initialization is ongoing; await completion first.
+     */
+    setStatus(status: Lifecycle.Status): void;
+
+    /**
+     * Move subject to "crashed" state, optionally setting the cause.
+     *
+     * This happens automatically if there is an error during construction.  It is also useful for post-construction
+     * errors to convey crashed state to components such as the environmental runtime service.
+     */
+    crash(cause?: any): void;
+
+    /**
+     * Invoke a method after construction completes successfully.
+     *
+     * Errors thrown by this callback are logged but otherwise ignored.
+     */
+    onSuccess(actor: () => MaybePromise<void>): void;
+
+    /**
+     * Invoke a method after construction completes unsuccessfully.
+     *
+     * If you register an onError handler then the default error handler will not log the error.
+     *
+     * Errors thrown by this callback are logged but otherwise ignored.
+     */
+    onError(actor: (error: Error) => MaybePromise<void>): void;
+
+    /**
+     * Invoke a method after construction completes successfully or onsuccessfully.
+     *
+     * Errors thrown by this callback are logged but otherwise ignored.
+     */
+    onCompletion(actor: () => void): void;
+
+    toString(): string;
+}
+
+/**
+ * Create an {@link Constructable} and optionally begin async construction.
+ */
+export function Construction<const T extends Constructable>(
+    subject: T,
+    initializer?: () => MaybePromise,
+): Construction<T> {
+    if (!initializer) {
+        assertDeferred(subject);
+    }
+
+    // The promise returned by the initializer if initialization is async
+    let initializerPromise: MaybePromise<void>;
+
+    // The promise we use to implement Construction.then() and Construction.ready
+    let awaiterPromise: undefined | Promise<T>;
+    let awaiterResolve: undefined | ((subject: T) => void);
+    let awaiterReject: undefined | ((error: any) => void);
+
+    // The promise we use to implement Constructable.close
+    let closedPromise: undefined | Promise<void>;
+    let closedResolve: undefined | (() => void);
+    let closedReject: undefined | ((error: any) => void);
+
+    let error: undefined | Error;
+    let primaryCauseHandled = false;
+    let status = Lifecycle.Status.Inactive;
+    let change: Observable<[status: Lifecycle.Status, subject: T]> | undefined;
+
+    const self: Construction<any> = {
+        [Symbol.toStringTag]: "AsyncConstruction",
+
+        get error() {
+            return error;
+        },
+
+        get status() {
+            return status;
+        },
+
+        get change() {
+            if (change === undefined) {
+                change = Observable();
+            }
+            return change;
+        },
+
+        get isErrorHandled() {
+            return primaryCauseHandled;
+        },
+
+        start<const T, const A extends [], const This extends Construction<Constructable.Deferred<T, A>>>(
+            this: This,
+            ...args: A
+        ) {
+            if (status !== Lifecycle.Status.Inactive) {
+                throw new ImplementationError(`Cannot initialize ${subject} because it is already active`);
+            }
+
+            assertDeferred(subject);
+
+            status = Lifecycle.Status.Initializing;
+
+            try {
+                const initializeDeferred = () => subject[Construction.construct](...args);
+                invokeInitializer(initializeDeferred);
+            } catch (e) {
+                rejected(e);
+                return;
+            }
+        },
+
+        assert(description?: string, dependency?: any) {
+            Lifecycle.assertActive(status, description ?? subject.constructor.name);
+
+            if (arguments.length < 2) {
+                return;
+            }
+
+            try {
+                if (dependency === undefined) {
+                    throw new ImplementationError(`Property is undefined`);
+                }
+            } catch (e) {
+                let error;
+                if (e instanceof Error) {
+                    error = e;
+                } else {
+                    error = new ImplementationError(e?.toString() ?? "(unknown error)");
+                }
+                error.message = `Cannot access ${description}: ${error.message}`;
+                throw error;
+            }
+            return dependency;
+        },
+
+        then<TResult1 = T, TResult2 = never>(
+            onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null,
+            onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null,
+        ): Promise<TResult1 | TResult2> {
+            const handleRejection = onrejected ? () => onrejected?.(crashedError()) as TResult2 : undefined;
+            if (status === Lifecycle.Status.Inactive || status === Lifecycle.Status.Initializing) {
+                if (!awaiterPromise) {
+                    awaiterPromise = new Promise<T>((resolve, reject) => {
+                        awaiterResolve = resolve;
+                        awaiterReject = reject;
+                    });
+                }
+
+                return awaiterPromise.then(onfulfilled, handleRejection);
+            }
+
+            const promise = error ? Promise.reject(crashedError()) : Promise.resolve(subject);
+            return promise.then(onfulfilled, handleRejection);
+        },
+
+        catch<TResult = never>(
+            onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null,
+        ): Promise<T | TResult> {
+            return this.then(undefined, onrejected);
+        },
+
+        onSuccess(actor: () => MaybePromise<void>) {
+            const onSuccess = () => {
+                const errorHandler = createErrorHandler("onSuccess");
+
+                try {
+                    const result = actor();
+                    if (MaybePromise.is(result)) {
+                        return Promise.resolve(result).catch(errorHandler);
+                    }
+                } catch (e) {
+                    errorHandler(e);
+                }
+            };
+
+            this.then(onSuccess).catch(e => {
+                // Failure should result in a CrashedDependencyError which simply means initialization failed.  The
+                // actual error is logged so we can safely ignore.  If the error was not a CrashedDependencyError then
+                // it is unexpected.  We rethrow which will result in the process exiting with an unexpected error
+                CrashedDependencyError.accept(e);
+            });
+        },
+
+        onError(actor: (error: Error) => MaybePromise<void>) {
+            const onError = (error: unknown) => {
+                const errorHandler = createErrorHandler("onError");
+
+                try {
+                    const result = actor(errorOf(error));
+                    if (MaybePromise.is(result)) {
+                        return result.then(undefined, errorHandler);
+                    }
+                } catch (e) {
+                    errorHandler(e);
+                }
+            };
+
+            this.ready.catch(onError);
+        },
+
+        onCompletion(actor: () => void) {
+            const onCompletion = () => {
+                const errorHandler = createErrorHandler("onCompletion");
+
+                try {
+                    actor();
+                } catch (e) {
+                    errorHandler(e);
+                }
+            };
+
+            // Do not use finally() because eslint rule doesn't like it
+            this.then(onCompletion, onCompletion);
+        },
+
+        close(destructor): MaybePromise {
+            const destructorError = createErrorHandler("destructor");
+
+            // Destruction phase 4 - move to destroyed state
+            function destroyed() {
+                setStatus(Lifecycle.Status.Destroyed);
+                if (closedResolve) {
+                    closedResolve();
+                    closedResolve = closedReject = undefined;
+                }
+            }
+
+            // Destruction phase 3 - invoke AsyncDestructable.destruct if present
+            const destruct = (subject as Partial<Constructable.Destructable>)[Construction.destruct];
+            const invokeDestruct = destruct
+                ? function invokeDestruct() {
+                      try {
+                          const promise = destruct.bind(subject)();
+                          if (promise) {
+                              return promise.then(undefined, destructorError).then(destroyed);
+                          }
+                      } catch (e) {
+                          destructorError(e);
+                      }
+                      destroyed();
+                  }
+                : destroyed;
+
+            // Destruction phase 2 - invoke destructor function if present
+            const invokeDestructor = destructor
+                ? function invokeDestructor() {
+                      try {
+                          const promise = destructor();
+                          if (promise) {
+                              return promise.then(undefined, destructorError).then(invokeDestruct);
+                          }
+                      } catch (e) {
+                          destructorError(e);
+                      }
+                      invokeDestruct();
+                  }
+                : invokeDestruct;
+
+            // Destruction phase 1 - move to destroyed state
+            function beginDestruction() {
+                if (status === Lifecycle.Status.Destroying || status === Lifecycle.Status.Destroyed) {
+                    return self.closed;
+                }
+                setStatus(Lifecycle.Status.Destroying);
+                return invokeDestructor();
+            }
+
+            if (status === Lifecycle.Status.Initializing) {
+                return this.then(beginDestruction, beginDestruction);
+            }
+
+            return beginDestruction();
+        },
+
+        finally(onfinally: () => void): Promise<T> {
+            return Promise.prototype.finally.call(this, onfinally);
+        },
+
+        setStatus(newStatus: Lifecycle.Status) {
+            if (this.status === newStatus) {
+                return;
+            }
+
+            switch (status) {
+                case newStatus:
+                    return;
+
+                case Lifecycle.Status.Destroying:
+                    if (newStatus !== Lifecycle.Status.Destroyed) {
+                        throw new ImplementationError("Cannog change status because destruction is ongoing");
+                    }
+                    break;
+
+                case Lifecycle.Status.Destroyed:
+                    throw new ImplementationError("Cannot change status because destruction is final");
+
+                case Lifecycle.Status.Initializing:
+                    throw new ImplementationError("Cannot change status because initialization is ongoing");
+            }
+
+            switch (newStatus) {
+                case Lifecycle.Status.Inactive:
+                    awaiterPromise = closedPromise = undefined;
+                    primaryCauseHandled = false;
+                    error = undefined;
+                    break;
+
+                case Lifecycle.Status.Active:
+                    awaiterPromise = closedPromise = undefined;
+                    error = undefined;
+                    break;
+
+                default:
+                    break;
+            }
+
+            setStatus(newStatus);
+        },
+
+        crash(newError?: Error) {
+            error = newError;
+            setStatus(Lifecycle.Status.Crashed);
+        },
+
+        get ready() {
+            return {
+                [Symbol.toStringTag]: "AsyncConstruction#primary",
+
+                then<TResult1 = T, TResult2 = never>(
+                    onfulfilled?: ((value: T) => TResult1 | PromiseLike<TResult1>) | undefined | null,
+                    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null,
+                ): Promise<TResult1 | TResult2> {
+                    let rejectionHandler: undefined | typeof onrejected;
+                    if (onrejected) {
+                        primaryCauseHandled = true;
+                        rejectionHandler = () => onrejected(errorOf(error));
+                    }
+
+                    return self.then(onfulfilled, rejectionHandler);
+                },
+
+                catch<TResult = never>(
+                    onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null,
+                ): Promise<T | TResult> {
+                    return this.then(undefined, onrejected);
+                },
+
+                finally(onfinally: () => void): Promise<T> {
+                    return Promise.prototype.finally.call(this, onfinally);
+                },
+            };
+        },
+
+        get closed() {
+            if (closedPromise === undefined) {
+                closedPromise = new Promise((resolve, reject) => {
+                    closedResolve = resolve;
+                    closedReject = reject;
+                });
+            }
+
+            return {
+                [Symbol.toStringTag]: "AsyncConstruction#primary",
+
+                then<TResult1 = void, TResult2 = never>(
+                    onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | undefined | null,
+                    onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null,
+                ): Promise<TResult1 | TResult2> {
+                    let rejectionHandler: undefined | typeof onrejected;
+                    if (onrejected) {
+                        primaryCauseHandled = true;
+                        rejectionHandler = () => onrejected(errorOf(error));
+                    }
+
+                    return (closedPromise as Promise<void>).then(onfulfilled, rejectionHandler);
+                },
+
+                catch<TResult = never>(
+                    onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null,
+                ): Promise<T | TResult> {
+                    return this.then(undefined, onrejected);
+                },
+
+                finally(onfinally: () => void): Promise<T> {
+                    return Promise.prototype.finally.call(this, onfinally);
+                },
+            };
+        },
+    };
+
+    if (initializer) {
+        invokeInitializer(initializer);
+    }
+
+    return self;
+
+    // Begin initialization.  May throw synchronously or asynchronously
+    function invokeInitializer(initializer: () => MaybePromise<void>) {
+        status = Lifecycle.Status.Initializing;
+
+        initializerPromise = initializer();
+
+        if (MaybePromise.is(initializerPromise)) {
+            initializerPromise.then(resolved, rejected);
+        } else {
+            resolved();
+        }
+    }
+
+    // We return the original error for the first rejection.  The stack trace will point to the source of the error.
+    // This means that the owner of the object should register error handling first.
+    //
+    // For subsequent rejections we throw a new CrashedDependencyError for each listener.  This prevents the logs from
+    // filling with redundant stack traces and ensures the stack trace details the listener's stack rather than the
+    // original error's stack.
+    function crashedError() {
+        if (!primaryCauseHandled && error) {
+            primaryCauseHandled = true;
+            return error;
+        }
+
+        let what;
+        if (subject.toString === Object.prototype.toString) {
+            what = subject.constructor.name;
+        } else {
+            what = subject.toString();
+        }
+
+        const crashError = new CrashedDependencyError(what, "unavailable due to initialization error");
+        crashError.subject = subject;
+        return crashError;
+    }
+
+    function setStatus(newStatus: Lifecycle.Status) {
+        if (status === newStatus) {
+            return;
+        }
+
+        status = newStatus;
+
+        if (change) {
+            change.emit(status, subject);
+        }
+    }
+
+    function resolved() {
+        if (status === Lifecycle.Status.Initializing) {
+            setStatus(Lifecycle.Status.Active);
+        }
+
+        if (awaiterResolve) {
+            const resolve = awaiterResolve;
+            awaiterResolve = awaiterReject = undefined;
+            resolve(subject);
+        }
+    }
+
+    function rejected(cause: any) {
+        if (status !== Lifecycle.Status.Destroying && status !== Lifecycle.Status.Destroyed) {
+            error = cause;
+            setStatus(Lifecycle.Status.Crashed);
+        }
+
+        if (awaiterReject) {
+            const reject = awaiterReject;
+            awaiterResolve = awaiterReject = undefined;
+            reject(crashedError());
+        }
+
+        if (closedReject) {
+            primaryCauseHandled = true;
+            const reject = closedReject;
+            closedResolve = closedReject = undefined;
+            reject(cause);
+        }
+
+        if (!primaryCauseHandled) {
+            unhandledError(cause);
+        }
+    }
+
+    function unhandledError(...args: any[]) {
+        const logger = Logger.get(subject.constructor.name);
+        logger.error(...args);
+    }
+
+    function createErrorHandler(name: string) {
+        return (e: any) => {
+            unhandledError(`Unhandled error in ${self} ${name}:`, e);
+        };
+    }
+}
+
+export namespace Construction {
+    /**
+     * Ensure a pool of {@link Constructable}s are initialized.  Returns a promise if any constructables are still
+     * initializing or there is an error.
+     *
+     * @param subjects the constructables to monitor; may mutate whilst construction is ongoing
+     * @param onError error handler; if returns error it is thrown; if omitted throws CrashedDependenciesError
+     */
+    export function all<T extends Constructable>(
+        subjects: Iterable<T>,
+        onError?: (errored: Iterable<T>) => void | Error,
+    ): MaybePromise {
+        if (onError === undefined) {
+            onError = errors => new CrashedDependenciesError(errors);
+        }
+
+        const subjectArray = [...subjects];
+
+        const uninitialized = subjectArray.filter(
+            subject => subject.construction.status === Lifecycle.Status.Initializing,
+        );
+        if (uninitialized.length) {
+            return Promise.allSettled(uninitialized.map(backing => backing.construction)).then(() =>
+                // Recurse to ensure subjects added subsequent to initial "all" settle
+                all(subjects, onError),
+            );
+        }
+
+        const crashed = Object.values(subjectArray).filter(
+            backing => backing.construction.status === Lifecycle.Status.Crashed,
+        );
+        if (crashed.length) {
+            let error;
+            try {
+                error = onError(crashed);
+            } catch (e) {
+                error = e;
+            }
+            if (error) {
+                return Promise.reject(error);
+            }
+        }
+    }
+
+    export const construct = Symbol("construct");
+    export const destruct = Symbol("destruct");
+}
+
+function assertDeferred<T>(subject: Constructable<T>): asserts subject is Constructable.Deferred<T, any> {
+    if (typeof (subject as Constructable.Deferred<any, any>)?.[Construction.construct] !== "function") {
+        throw new ImplementationError(`No initializer defined for ${subject}`);
+    }
+}