@matter/general 0.16.0-alpha.0-20251205-dfb1e1556 → 0.16.0-alpha.0-20251207-37e501b18

package/src/util/Abort.ts

@@ -268,7 +268,7 @@ export namespace Abort {
     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);
+            timer = Time.getTimer(description, duration, () => resolve());
         });
         return race(abort, rested).finally(timer.stop.bind(timer));
     }

package/src/util/Construction.ts

@@ -4,10 +4,14 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { DiagnosticPresentation } from "#log/DiagnosticPresentation.js";
+import { LogFormat } from "#log/LogFormat.js";
 import { Logger } from "../log/Logger.js";
 import { ImplementationError } from "../MatterError.js";
 import { asError, errorOf } from "./Error.js";
+import { decamelize } from "./identifier-case.js";
 import { CrashedDependenciesError, CrashedDependencyError, Lifecycle } from "./Lifecycle.js";
+import { Lifetime } from "./Lifetime.js";
 import { Observable } from "./Observable.js";
 import { MaybePromise } from "./Promises.js";
 
@@ -88,7 +92,7 @@ export namespace Constructable {
 /**
  * The promise implementing by an {@link Constructable#construction}.
  */
-export interface Construction<T> extends Promise<T> {
+export interface Construction<T> extends Promise<T>, Lifetime.Owner {
     /**
      * If construction ends with an error, the error is saved here.
      */
@@ -237,9 +241,12 @@ export function Construction<const T extends Constructable>(
     let error: undefined | Error;
     let errorForDependencies: undefined | CrashedDependencyError;
     let primaryCauseHandled = false;
-    let status = Lifecycle.Status.Inactive;
     let change: Observable<[status: Lifecycle.Status, subject: T]> | undefined;
 
+    // Lifecycle information that exists
+    let status = Lifecycle.Status.Inactive;
+    let lifetime: Lifetime | undefined;
+
     const self: Construction<any> = {
         [Symbol.toStringTag]: "Construction",
 
@@ -262,6 +269,10 @@ export function Construction<const T extends Constructable>(
             return primaryCauseHandled;
         },
 
+        join(...name: unknown[]) {
+            return activeLifetime().join(...name);
+        },
+
         start<const T, const A extends [], const This extends Construction<Constructable.Deferred<T, A>>>(
             this: This,
             ...args: A
@@ -272,7 +283,7 @@ export function Construction<const T extends Constructable>(
 
             assertDeferred(subject);
 
-            status = Lifecycle.Status.Initializing;
+            setStatus(Lifecycle.Status.Initializing);
 
             try {
                 const initializeDeferred = () => subject[Construction.construct](...args);
@@ -284,7 +295,7 @@ export function Construction<const T extends Constructable>(
         },
 
         assert(description?: string, dependency?: any) {
-            Lifecycle.assertActive(status, description ?? subject.constructor.name);
+            Lifecycle.assertActive(status, description ?? nameOf(subject));
 
             if (arguments.length < 2) {
                 return;
@@ -582,7 +593,7 @@ export function Construction<const T extends Constructable>(
 
     // Begin initialization.  May throw synchronously or asynchronously
     function invokeInitializer(initializer: () => MaybePromise<void>) {
-        status = Lifecycle.Status.Initializing;
+        setStatus(Lifecycle.Status.Initializing);
 
         initializerPromise = initializer();
 
@@ -609,14 +620,7 @@ export function Construction<const T extends Constructable>(
             return errorForDependencies;
         }
 
-        let what;
-        if (subject.toString === Object.prototype.toString) {
-            what = subject.constructor.name;
-        } else {
-            what = subject.toString();
-        }
-
-        errorForDependencies = new CrashedDependencyError(what, "unavailable due to initialization error");
+        errorForDependencies = new CrashedDependencyError(nameOf(subject), "unavailable due to initialization error");
         errorForDependencies.subject = subject;
         errorForDependencies.cause = error;
         return errorForDependencies;
@@ -629,6 +633,28 @@ export function Construction<const T extends Constructable>(
 
         status = newStatus;
 
+        switch (status) {
+            case Lifecycle.Status.Initializing:
+            case Lifecycle.Status.Active:
+            case Lifecycle.Status.Destroying:
+                if (!lifetime) {
+                    lifetime = joinOwner();
+                }
+
+                if (status === Lifecycle.Status.Destroying) {
+                    lifetime.closing();
+                }
+                break;
+
+            default:
+                if (lifetime) {
+                    lifetime.closing()[Symbol.dispose]();
+                    lifetime[Symbol.dispose]();
+                    lifetime = undefined;
+                }
+                break;
+        }
+
         if (change) {
             change.emit(status, subject);
         }
@@ -677,13 +703,30 @@ export function Construction<const T extends Constructable>(
 
     function createErrorHandler(name: string) {
         return (e: any) => {
-            let what = subject.toString();
-            if (what === "[object Object]") {
-                what = subject.constructor.name;
-            }
-            unhandledError(`Unhandled error in ${what} ${name}:`, e);
+            unhandledError(`Unhandled error in ${nameOf(subject)} ${name}:`, e);
         };
     }
+
+    function activeLifetime() {
+        if (lifetime) {
+            if (status === Lifecycle.Status.Destroying) {
+                return lifetime.closing();
+            }
+
+            return lifetime;
+        }
+
+        // We are not in fact alive so create a zombie lifetime.  Generally this is a bug but if it happens this allows
+        // us to handle without crashing and properly track lifetime spans
+        const zombie = joinOwner();
+        zombie[Symbol.dispose]();
+        return zombie;
+    }
+
+    function joinOwner() {
+        const lifetime = Lifetime.of(subject);
+        return lifetime.join(decamelize(nameOf(subject), " "));
+    }
 }
 
 export namespace Construction {
@@ -739,3 +782,18 @@ function assertDeferred<T>(subject: Constructable<T>): asserts subject is Constr
         throw new ImplementationError(`No initializer defined for ${subject}`);
     }
 }
+
+function nameOf(subject: {}) {
+    if (DiagnosticPresentation.name in subject) {
+        const name = subject[DiagnosticPresentation.name];
+        if (name !== undefined) {
+            return LogFormat("plain")(name);
+        }
+    }
+
+    if (subject.toString === Object.prototype.toString) {
+        return subject.constructor.name;
+    }
+
+    return subject.toString();
+}

package/src/util/DataReadQueue.ts

@@ -10,6 +10,7 @@ import { Duration } from "#time/Duration.js";
 import { Minutes } from "#time/TimeUnit.js";
 import { MatterFlowError } from "../MatterError.js";
 import { Time, Timer } from "../time/Time.js";
+import { asError } from "./Error.js";
 import { createPromise } from "./Promises.js";
 import { EndOfStreamError, NoResponseTimeoutError } from "./Streams.js";
 
@@ -37,21 +38,18 @@ export class DataReadQueue<T> {
                 ),
             ).start(),
         };
-        return promise;
-    }
-
-    async write(data: T) {
-        this.push(data);
-    }
 
-    get size() {
-        return this.#queue.length;
+        try {
+            return await promise;
+        } catch (e) {
+            // The stack trace where we created the error is useless (either a timer or close()) so replace here
+            const error = asError(e);
+            error.stack = new Error().stack;
+            throw error;
+        }
     }
 
-    /**
-     * Same as write but doesn't require the await required to satisfy {@link Stream#write}.
-     */
-    push(data: T) {
+    write(data: T) {
         if (this.#closed) throw new EndOfStreamError();
         if (this.#pendingRead !== undefined) {
             this.#pendingRead.timeoutTimer?.stop();
@@ -63,6 +61,10 @@ export class DataReadQueue<T> {
         this.#queue.push(data);
     }
 
+    get size() {
+        return this.#queue.length;
+    }
+
     close() {
         if (this.#closed) return;
         this.#closed = true;

package/src/util/FormattedText.ts

@@ -6,7 +6,7 @@
 
 const INDENT = "  ";
 
-export { camelize, describeList, serialize } from "./String.js";
+export { describeList } from "./String.js";
 
 /**
  * Performs word wrap.  Input is assumed to be a series of paragraphs separated by a newline.  Output is an array of

package/src/util/Lifetime.ts

@@ -0,0 +1,284 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Diagnostic } from "#log/Diagnostic.js";
+import { DiagnosticPresentation } from "#log/DiagnosticPresentation.js";
+import { DiagnosticSource } from "#log/DiagnosticSource.js";
+import { InternalError } from "#MatterError.js";
+import { Duration } from "#time/Duration.js";
+import "#time/StandardTime.js";
+import { Time } from "#time/Time.js";
+import { Timestamp } from "#time/Timestamp.js";
+
+/**
+ * A "lifetime" represents the existence of an entity or ongoing task.
+ *
+ * This serves as a mechanism for tracking granular information about process state for diagnostic purposes.  A lifetime
+ * is present in diagnostic reports until disposed.
+ *
+ * Lifetimes are hierarchical.  Create sublifetimes using join().
+ */
+export interface Lifetime extends Disposable, Diagnostic, Lifetime.Owner {
+    /**
+     * The name of the lifetime used for diagnostic presentation.
+     *
+     * Any diagnostic (so, any value) may serve as a name.
+     */
+    name: unknown;
+
+    /**
+     * The time at which the lifetime began.
+     */
+    readonly startedAt: Timestamp;
+
+    /**
+     * A "span" is a sub-lifetime created via {@link join}.
+     */
+    readonly spans: Set<Lifetime>;
+
+    /**
+     * Arbitrary details presented as a dictionary with {@link name}.
+     */
+    readonly details: Record<string, unknown>;
+
+    /**
+     * The inverse of {@link isClosing}.
+     */
+    readonly isOpen: boolean;
+
+    /**
+     * Set when the lifetime begins closing (via {@link closing}) or {@link isClosed} is true.
+     */
+    readonly isClosing: boolean;
+
+    /**
+     * Set when the lifetime has exited.
+     */
+    readonly isClosed: boolean;
+
+    /**
+     * The lifetime enclosing this lifetime.
+     *
+     * Only the process lifetime should have no owner.  This field is writable so you can move ownership of a lifetime.
+     */
+    owner?: Lifetime;
+
+    /**
+     * Mark this lifetime as closing.
+     *
+     * Creates a sublifetime specifically for closing this lifetime.  This supports the common pattern of tracking the
+     * close process associated with an active lifetime.
+     *
+     * Calling repeatedly returns the same sublifetime.  Disposing the returned lifetime disposes this lifetime.
+     */
+    closing(): Lifetime;
+}
+
+export function Lifetime(...name: unknown[]) {
+    return Lifetime.process.join(...name);
+}
+
+class LifetimeImplementation implements Lifetime, Lifetime.Owner {
+    #name: unknown;
+    #owner?: Lifetime;
+    #startedAt: Timestamp;
+    #details?: Record<string, unknown>;
+    #spans?: Set<Lifetime>;
+    #closing?: Lifetime;
+    #isClosed = false;
+
+    declare [Diagnostic.presentation]: unknown;
+
+    constructor(name: unknown[], owner?: Lifetime) {
+        this.#name = name.length > 1 ? name : name[0];
+        this.#startedAt = Time.nowMs;
+        this.#owner = owner;
+
+        if (owner) {
+            owner.spans.add(this);
+        }
+    }
+
+    get spans() {
+        if (!this.#spans) {
+            this.#spans = new Set();
+        }
+        return this.#spans;
+    }
+
+    get name() {
+        return this.#name;
+    }
+
+    set name(name: unknown) {
+        this.#name = name;
+    }
+
+    get startedAt() {
+        return this.#startedAt;
+    }
+
+    get details() {
+        return this.#details ?? {};
+    }
+
+    get owner() {
+        return this.#owner;
+    }
+
+    set owner(owner: Lifetime | undefined) {
+        if (!this.#owner) {
+            throw new InternalError("Cannot move ownership of root lifetime");
+        }
+
+        if (this.#owner === owner) {
+            return;
+        }
+
+        removeSpan(this.owner, this);
+
+        this.#owner = owner;
+
+        this.#owner?.spans.add(this);
+    }
+
+    join(...name: unknown[]): Lifetime {
+        return new LifetimeImplementation(name, this);
+    }
+
+    closing(): Lifetime {
+        if (!this.#closing) {
+            this.#closing = this.join("closing");
+
+            const disposeClosing = this.#closing[Symbol.dispose].bind(this.#closing);
+
+            this.#closing[Symbol.dispose] = () => {
+                disposeClosing();
+
+                this[Symbol.dispose]();
+            };
+        }
+
+        return this.#closing;
+    }
+
+    get isOpen() {
+        return this.#closing === undefined && !this.#isClosed;
+    }
+
+    get isClosing() {
+        return this.#closing !== undefined || this.#isClosed;
+    }
+
+    get isClosed() {
+        return this.#isClosed;
+    }
+
+    get [DiagnosticPresentation.value]() {
+        // Special case for process lifetime
+        if (!this.#owner) {
+            return Diagnostic.node("🛠", "Lifetimes", {
+                children: this.spans,
+            });
+        }
+
+        const header: unknown[] = [this.#name];
+
+        if (this.isClosed) {
+            header.push(Diagnostic.weak("(zombie)"));
+        }
+
+        const details: Record<string, unknown> = {
+            up: Duration.format(Timestamp.delta(this.startedAt, Time.nowMs)),
+            ...this.#details,
+        };
+
+        header.push(Diagnostic.dict(details));
+
+        const result: unknown[] = [header];
+
+        if (this.#spans?.size) {
+            result.push(Diagnostic.list(this.spans));
+        }
+
+        return result;
+    }
+
+    [Symbol.dispose]() {
+        if (!this.#owner) {
+            // Can't dispose of process lifetime
+            return;
+        }
+
+        this.#isClosed = true;
+
+        // If we are disposed with active sublifetimess we become a zombie
+        if (this.#spans?.size) {
+            return;
+        }
+
+        removeSpan(this.#owner, this);
+    }
+}
+
+function removeSpan(owner: Lifetime | undefined, span: Lifetime) {
+    if (!owner) {
+        return;
+    }
+
+    owner.spans.delete(span);
+    if (owner.isClosed && !owner.spans?.size) {
+        owner[Symbol.dispose]();
+    }
+}
+
+export namespace Lifetime {
+    /**
+     * The lifetime of the system process.
+     *
+     * This is effectively a "global" lifetime.  It parents all other lifetimes.
+     */
+    export const process: Lifetime.Owner = new LifetimeImplementation(["process"]);
+
+    /**
+     * Obtain a lifetime not attached to {@link process} for testing purposes.
+     */
+    export declare const mock: Lifetime;
+
+    /**
+     * An object associated with a lifetime.
+     */
+    export interface Owner {
+        /**
+         * Create or move a sublifetime.
+         */
+        join(...name: unknown[]): Lifetime;
+    }
+
+    /**
+     * A lifetime subject that exists for a portion of a larger timespan.
+     */
+    export interface Contributor {
+        [owner]: Owner;
+    }
+
+    /**
+     * Determine the lifetime of the owner of a component.
+     */
+    export function of(subject?: {}) {
+        return (subject as Partial<Contributor> | undefined)?.[owner] ?? process;
+    }
+
+    export const owner = Symbol("owner");
+}
+
+Object.defineProperty(Lifetime, "mock", {
+    get() {
+        return new LifetimeImplementation(["mock"]);
+    },
+});
+
+DiagnosticSource.add(Lifetime.process as Lifetime);

package/src/util/Multiplex.ts

@@ -39,9 +39,9 @@ export class BasicMultiplex implements PromiseLike<void> {
         const entry = {
             done: Promise.resolve(worker)
                 .catch(e => {
-                    let message = "Unhandled error";
+                    let message = "Error";
                     if (description) {
-                        message = `${message} in ${description}`;
+                        message = `${message} ${description}`;
                     }
                     logger.error(`${message}:`, e);
                 })