@matter/general 0.16.0-alpha.0-20251203-aaf94bca8 → 0.16.0-alpha.0-20251207-37e501b18

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@matter/general",
-    "version": "0.16.0-alpha.0-20251203-aaf94bca8",
+    "version": "0.16.0-alpha.0-20251207-37e501b18",
     "description": "Non-Matter support for Matter.js",
     "keywords": [
         "iot",
@@ -36,7 +36,7 @@
         "@noble/curves": "^2.0.1"
     },
     "devDependencies": {
-        "@matter/testing": "0.16.0-alpha.0-20251203-aaf94bca8"
+        "@matter/testing": "0.16.0-alpha.0-20251207-37e501b18"
     },
     "files": [
         "dist/**/*",

package/src/MatterError.ts

@@ -6,7 +6,7 @@
 
 import { NodeJsStyleInspectable } from "#log/NodeJsStyleInspectable.js";
 import type { MaybePromise } from "#util/Promises.js";
-import { decamelize } from "#util/String.js";
+import { decamelize } from "#util/identifier-case.js";
 import { errorOf } from "./util/Error.js";
 
 const codes = new WeakMap<{}, string>();

package/src/codec/DerTypes.ts

@@ -6,6 +6,7 @@
 
 import { InternalError } from "#MatterError.js";
 import { Bytes } from "#util/Bytes.js";
+import { hex } from "#util/String.js";
 import {
     ContextTagged,
     ContextTaggedBytes,
@@ -112,7 +113,7 @@ export namespace X520 {
      * Also registers the OID in the reverse lookup map immediately.
      */
     const GenericString_X520 = (id: number, fieldName: string) => {
-        const oidHex = `5504${id.toString(16).padStart(2, "0")}`;
+        const oidHex = `5504${hex.byte(id)}`;
         // Register in reverse lookup map immediately at function creation time
         if (OID_TO_FIELD_MAP[oidHex] !== undefined && OID_TO_FIELD_MAP[oidHex] !== fieldName) {
             throw new InternalError(

package/src/environment/Environment.ts

@@ -7,8 +7,10 @@
 import { ServiceProvider } from "#environment/ServiceProvider.js";
 import { SharedEnvironmentServices } from "#environment/SharedEnvironmentServices.js";
 import { SharedServicesManager } from "#environment/SharedServicesManager.js";
+import { Diagnostic } from "#log/Diagnostic.js";
 import { InternalError } from "#MatterError.js";
 import { Instant } from "#time/TimeUnit.js";
+import { Lifetime } from "#util/Lifetime.js";
 import { MaybePromise } from "#util/Promises.js";
 import { DiagnosticSource } from "../log/DiagnosticSource.js";
 import { Logger } from "../log/Logger.js";
@@ -48,10 +50,11 @@ const logger = Logger.get("Environment");
  *
  * TODO - could remove global singletons by moving here
  */
-export class Environment implements ServiceProvider {
+export class Environment implements ServiceProvider, Lifetime.Owner {
     #services?: Map<Environmental.ServiceType, Environmental.Service | null>;
     #name: string;
     #parent?: Environment;
+    #lifetime: Lifetime;
     #added = Observable<[type: Environmental.ServiceType, instance: {}]>();
     #deleted = Observable<[type: Environmental.ServiceType, instance: {}]>();
     #serviceEvents = new Map<Environmental.ServiceType, Environmental.ServiceEvents<any>>();
@@ -59,6 +62,11 @@ export class Environment implements ServiceProvider {
     constructor(name: string, parent?: Environment) {
         this.#name = name;
         this.#parent = parent;
+        this.#lifetime = (parent ?? Lifetime.process).join(Diagnostic.strong(name), "environment");
+    }
+
+    join(...name: unknown[]) {
+        return this.#lifetime?.join(...name);
     }
 
     /**
@@ -295,11 +303,21 @@ export class Environment implements ServiceProvider {
                 added(this, existing);
             }
 
-            events.added.on(service => this.runtime.add(() => added(this, service)));
+            events.added.on(service =>
+                this.runtime.add(async () => {
+                    using _adding = this.join(`adding ${type.name}`);
+                    await added(this, service);
+                }),
+            );
         }
 
         if (deleted) {
-            events.deleted.on(service => this.runtime.add(() => deleted(this, service)));
+            events.deleted.on(service =>
+                this.runtime.add(async () => {
+                    using _deleting = this.join(`adding ${type.name}`);
+                    await deleted(this, service);
+                }),
+            );
         }
     }
 
@@ -316,6 +334,8 @@ export class Environment implements ServiceProvider {
      * Set the default environment.
      */
     static set default(env: Environment) {
+        global[Symbol.dispose]();
+
         global = env;
 
         env.vars.use(() => {
@@ -347,7 +367,7 @@ export class Environment implements ServiceProvider {
      * Display tasks that supply diagnostics.
      */
     diagnose() {
-        Time.getTimer("Diagnostics", Instant, () => {
+        Time.getTimer("diagnostics", Instant, () => {
             try {
                 logger.notice("Diagnostics follow", DiagnosticSource);
             } catch (e) {
@@ -359,6 +379,11 @@ export class Environment implements ServiceProvider {
     protected loadVariables(): Record<string, any> {
         return {};
     }
+
+    [Symbol.dispose]() {
+        // Currently this is just a method for terminating our lifetime
+        this.#lifetime[Symbol.dispose]();
+    }
 }
 
 let global = new Environment("default");

package/src/environment/RuntimeService.ts

@@ -4,26 +4,29 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { DiagnosticPresentation } from "#log/DiagnosticPresentation.js";
 import { asError } from "#util/Error.js";
+import { Lifetime } from "#util/Lifetime.js";
 import { Diagnostic } from "../log/Diagnostic.js";
 import { DiagnosticSource } from "../log/DiagnosticSource.js";
 import { Logger } from "../log/Logger.js";
-import { Construction, type Constructable } from "../util/Construction.js";
-import { Cancellable, Destructable, Lifecycle } from "../util/Lifecycle.js";
-import { Multiplex } from "../util/Multiplex.js";
+import { type Constructable } from "../util/Construction.js";
+import { type Destructable, Lifecycle } from "../util/Lifecycle.js";
 import { Observable } from "../util/Observable.js";
 import type { Environment } from "./Environment.js";
 import { Environmental } from "./Environmental.js";
+import type { Worker } from "./Worker.js";
 
 const logger = Logger.get("Runtime");
 
 /**
  * Handles lifecycle management of other components.
  */
-export class RuntimeService implements Multiplex {
+export class RuntimeService {
     #env: Environment;
-    #workers = new Set<RuntimeService.Worker>();
-    #cancelled = new Set<RuntimeService.Worker>();
+    #lifetime: Lifetime;
+    #workers = new Set<Worker>();
+    #cancelled = new Set<Worker>();
     #workerDeleted = Observable<[]>();
     #canceled = false;
     #started = Observable<[]>();
@@ -32,6 +35,7 @@ export class RuntimeService implements Multiplex {
 
     constructor(environment: Environment) {
         this.#env = environment;
+        this.#lifetime = this.#env.join("runtime");
         environment.set(RuntimeService, this);
         DiagnosticSource.add(this);
     }
@@ -74,7 +78,9 @@ export class RuntimeService implements Multiplex {
         if (worker.then) {
             Promise.resolve(worker)
                 .catch(error => this.#crash(error))
-                .finally(() => this.delete(worker));
+                .finally(() => {
+                    this.delete(worker);
+                });
             return;
         }
 
@@ -97,7 +103,7 @@ export class RuntimeService implements Multiplex {
     /**
      * Remove a worker.
      */
-    delete(worker: RuntimeService.Worker) {
+    delete(worker: Worker) {
         if (!this.#workers.has(worker)) {
             return;
         }
@@ -197,6 +203,8 @@ export class RuntimeService implements Multiplex {
     }
 
     async close() {
+        using _closing = this.#lifetime.closing();
+
         this.cancel();
         await this.inactive;
         this.#env.delete(RuntimeService, this);
@@ -208,9 +216,9 @@ export class RuntimeService implements Multiplex {
     }
 
     get [Diagnostic.value]() {
-        return Diagnostic.node("🛠", "Workers", {
+        return Diagnostic.node("⚙️", "Workers", {
             children: [...this.#workers].map(worker => {
-                let diagnostic: unknown = worker[RuntimeService.label];
+                let diagnostic: unknown = worker[DiagnosticPresentation.name];
 
                 if (diagnostic === undefined) {
                     diagnostic = Diagnostic.valueOf(worker);
@@ -225,7 +233,7 @@ export class RuntimeService implements Multiplex {
         });
     }
 
-    #cancelWorker(worker: RuntimeService.Worker) {
+    #cancelWorker(worker: Worker) {
         if (this.#cancelled.has(worker)) {
             return;
         }
@@ -281,50 +289,6 @@ export class RuntimeService implements Multiplex {
 }
 
 export namespace RuntimeService {
-    export const label = Symbol("label");
-
-    /**
-     * The runtime tracks individual discrete tasks as "workers".
-     *
-     * The state of the runtime is dependent on installed workers.  Any JS object may be a worker but the runtime's
-     * interaction with workers varies as documented here.
-     *
-     * If a worker is a {@link PromiseLike} the runtime will delete and/or destroy it on completion.
-     */
-    export interface Worker extends Partial<PromiseLike<any>>, Partial<Cancellable>, Partial<Destructable> {
-        /**
-         * If the worker supports {@link Construction}, the runtime will monitor the worker's lifecycle:
-         *
-         *   - If the worker crashed (e.g. experiences an error during initialization) the runtime will cancel all
-         *     workers and exit
-         *
-         *   - If the worker is destroyed the runtime deletes it from the set of known workers
-         */
-        construction?: Construction<any>;
-
-        /**
-         * If the worker supports {@link Symbol.asyncDispose} the runtime will invoke when the worker is no longer
-         * needed.  This happens if:
-         *
-         *   - The worker is a {@link PromiseLike} that resolves
-         *
-         *   - The worker's {@link construction} status changed as noted above
-         *
-         *   - The runtime is canceled via {@link RuntimeService.cancel}
-         */
-        [Symbol.asyncDispose]?: () => void | Promise<void>;
-
-        /**
-         * Workers may implement {@link Symbol.dispose} to handle disposal.  Works the same as the async equivalent.
-         */
-        [Symbol.dispose]?: () => void;
-
-        /**
-         * If label is present, it will be presented in diagnostics.  This takes precedence over [Diagnostic.value].
-         */
-        [label]?: unknown;
-    }
-
     /**
      * A function that initiates work.
      */

package/src/environment/Worker.ts

@@ -0,0 +1,75 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { DiagnosticPresentation } from "#log/DiagnosticPresentation.js";
+import { Construction } from "#util/Construction.js";
+import { Cancellable, Destructable } from "#util/Lifecycle.js";
+import { Lifetime } from "#util/Lifetime.js";
+import { MaybePromise } from "#util/Promises.js";
+
+/**
+ * An self-describing object that adheres to matter.js conventions for lifecycle and diagnostics.
+ *
+ * It's best to track workers as part of other components, but workers with no other home may be installed into
+ * {@link RuntimeService}.  The state of the runtime is dependent on installed workers.  Any JS object may be a worker
+ * but the runtime's interaction with workers varies as documented here.
+ */
+export interface Worker extends Partial<PromiseLike<any>>, Partial<Cancellable>, Partial<Destructable> {
+    /**
+     * If the worker supports {@link Construction}, the runtime will monitor the worker's lifecycle:
+     *
+     *   - If the worker crashed (e.g. experiences an error during initialization) the runtime will cancel all
+     *     workers and exit
+     *
+     *   - If the worker is destroyed the runtime deletes it from the set of known workers
+     */
+    construction?: Construction<any>;
+
+    /**
+     * If the worker supports {@link Symbol.asyncDispose} the runtime will invoke when the worker is no longer
+     * needed.  This happens if:
+     *
+     *   - The worker is a {@link PromiseLike} that resolves
+     *
+     *   - The worker's {@link construction} status changed as noted above
+     *
+     *   - The runtime is canceled via {@link RuntimeService.cancel}
+     */
+    [Symbol.asyncDispose]?: () => void | Promise<void>;
+
+    /**
+     * Workers may implement {@link Symbol.dispose} to handle disposal.  Works the same as the async equivalent.
+     */
+    [Symbol.dispose]?: () => void;
+
+    /**
+     * If label is present, it will be presented in diagnostics.  This takes precedence over [Diagnostic.value].
+     */
+    [DiagnosticPresentation.name]?: unknown;
+}
+
+/**
+ * Create a {@link Worker} with {@link name} and lifetime that ends when {@link done} resolves.
+ */
+export function Worker({
+    name,
+    done,
+    lifetime,
+}: {
+    name: string;
+    done?: MaybePromise<void>;
+    lifetime?: Lifetime.Owner;
+}): Worker | undefined {
+    if (!done) {
+        return;
+    }
+
+    const ongoing = (lifetime ?? Lifetime.process).join(name);
+    const worker = Promise.resolve(done).finally(() => ongoing[Symbol.dispose]()) as Worker;
+    worker[DiagnosticPresentation.name] = name;
+
+    return worker;
+}

package/src/environment/index.ts

@@ -10,3 +10,4 @@ export * from "./RuntimeService.js";
 export * from "./ServiceBundle.js";
 export * from "./SharedEnvironmentServices.js";
 export * from "./VariableService.js";
+export * from "./Worker.js";

package/src/log/Diagnostic.ts

@@ -165,6 +165,16 @@ export namespace Diagnostic {
 
     /**
      * Create a value identifying the source of a diagnostic event.
+     *
+     * Conventions for via:
+     *
+     *   - Use padded hex for random(ish) fixed-width numbers
+     *
+     *   - If there is an ID associated with a name, associate using "name#id"
+     *
+     *   - If there are subcomponents, associate with ":" (e.g. "sessionId:exchangeId:messageId")
+     *
+     *   - Use "/" as a separator if there are distinct subcomponents commonly delineated with ":"
      */
     export function via(value: string) {
         if (Diagnostic.presentationOf(value)) {
@@ -193,7 +203,7 @@ export namespace Diagnostic {
      * A node in a diagnostic tree.  Top-level diagnostic sources registered with DiagnosticSource should present as
      * nodes.
      */
-    export function node(icon: string, label: unknown, detail: { self?: unknown; children?: unknown[] }) {
+    export function node(icon: string, label: unknown, detail: { self?: unknown; children?: Iterable<unknown> }) {
         const result = [icon, Diagnostic.strong(label)] as unknown[];
         if (detail?.self !== undefined) {
             result.push(detail.self);
@@ -302,6 +312,10 @@ export namespace Diagnostic {
             toString() {
                 return Duration.format(this.time);
             },
+
+            get [Diagnostic.value]() {
+                return this.toString();
+            },
         };
     }
 

package/src/log/DiagnosticPresentation.ts

@@ -68,10 +68,15 @@ export namespace DiagnosticPresentation {
     /**
      * Property name allowing objects to indicate their preferred presentation.
      */
-    export const presentation: unique symbol = Symbol("presentation");
+    export const presentation: unique symbol = Symbol.for("matter.diagnostic.presentation");
 
     /**
      * Property name that redirects diagnostic presentation.
      */
-    export const value: unique symbol = Symbol.for("value");
+    export const value: unique symbol = Symbol.for("matter.diagnostic.value");
+
+    /**
+     * Property name that assigns a diagnostic segment as the name of an object.
+     */
+    export const name: unique symbol = Symbol.for("matter.diagnostic.name");
 }

package/src/log/DiagnosticSource.ts

@@ -27,6 +27,10 @@ export const DiagnosticSource = {
     },
 
     get [DiagnosticPresentation.value]() {
-        return sources;
+        const diagnostic = [];
+        for (const source of sources) {
+            diagnostic.push("", source);
+        }
+        return diagnostic;
     },
 };

package/src/log/LogFormat.ts

@@ -4,10 +4,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { serialize } from "#util/serialize.js";
 import { ImplementationError, InternalError, MatterError } from "../MatterError.js";
 import { Bytes } from "../util/Bytes.js";
 import { Lifecycle } from "../util/Lifecycle.js";
-import { serialize } from "../util/String.js";
 import { isObject } from "../util/Type.js";
 import { Diagnostic } from "./Diagnostic.js";
 import { LogLevel } from "./LogLevel.js";

package/src/net/Channel.ts

@@ -38,6 +38,6 @@ export interface IpNetworkChannel<T> extends Channel<T> {
     networkAddress: ServerAddressUdp;
 }
 
-export function isIpNetworkChannel<T>(channel: Channel<T>): channel is IpNetworkChannel<T> {
-    return isObject((channel as IpNetworkChannel<T>).networkAddress);
+export function isIpNetworkChannel<T>(channel?: Channel<T>): channel is IpNetworkChannel<T> {
+    return isObject((channel as IpNetworkChannel<T> | undefined)?.networkAddress);
 }

package/src/net/mock/MockUdpChannel.ts

@@ -8,7 +8,7 @@ import { ChannelType } from "#net/Channel.js";
 import { Bytes } from "#util/Bytes.js";
 import { NetworkError } from "../Network.js";
 import { MAX_UDP_MESSAGE_SIZE, UdpChannel, UdpChannelOptions } from "../udp/UdpChannel.js";
-import { MockNetwork } from "./MockNetwork.js";
+import type { MockNetwork } from "./MockNetwork.js";
 import { MockRouter } from "./MockRouter.js";
 
 export class MockUdpChannel implements UdpChannel {

package/src/net/mock/NetworkSimulator.ts

@@ -5,6 +5,7 @@
  */
 
 import { Bytes } from "#util/Bytes.js";
+import { hex } from "#util/String.js";
 import { MockNetwork } from "./MockNetwork.js";
 import { MockRouter } from "./MockRouter.js";
 
@@ -12,7 +13,7 @@ export class NetworkSimulator {
     readonly router = MockRouter();
 
     addHost(lastIdentifierByte: number) {
-        const byte = lastIdentifierByte.toString(16).padStart(2, "0");
+        const byte = hex.byte(lastIdentifierByte);
         return new MockNetwork(this, `00:11:22:33:44:${byte}`, [
             `1111:2222:3333:4444:5555:6666:7777:88${byte}`,
             `10.10.10.${lastIdentifierByte}`,

package/src/net/udp/UdpChannel.ts

@@ -4,7 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Bytes, MaybePromise } from "#util/index.js";
+import { Bytes, Lifetime, MaybePromise } from "#util/index.js";
 import { ChannelType } from "../Channel.js";
 import { ConnectionlessTransport } from "../ConnectionlessTransport.js";
 
@@ -46,6 +46,11 @@ export interface UdpChannelOptions {
      */
     netInterface?: string;
 
+    /**
+     * Owning lifetime of the channel.
+     */
+    lifetime?: Lifetime;
+
     /**
      * Address+port pairs are normally may normally only be opened by a single socket.  This allows shared access to a
      * port.