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

package/src/net/udp/UdpMulticastServer.ts

@@ -7,6 +7,7 @@
 import { MatterAggregateError } from "#MatterError.js";
 import { Minutes } from "#time/TimeUnit.js";
 import { Bytes } from "#util/Bytes.js";
+import { Lifetime } from "#util/Lifetime.js";
 import { Logger } from "../../log/Logger.js";
 import { Cache } from "../../util/Cache.js";
 import { asError } from "../../util/Error.js";
@@ -22,41 +23,67 @@ export interface UdpMulticastServerOptions {
     broadcastAddressIpv6: string;
     broadcastAddressIpv4?: string;
     netInterface?: string;
+    lifetime?: Lifetime.Owner;
 }
 
 export class UdpMulticastServer {
+    #lifetime: Lifetime;
+    readonly network: Network;
+    readonly netInterface: string | undefined;
+    readonly #broadcastAddressIpv4: string | undefined;
+    readonly #broadcastAddressIpv6: string;
+    readonly #broadcastPort: number;
+    readonly #serverIpv4: UdpChannel | undefined;
+    readonly #serverIpv6: UdpChannel;
+
     static async create({
         netInterface,
         broadcastAddressIpv4,
         broadcastAddressIpv6,
         listeningPort,
         network,
+        lifetime: lifetimeOwner,
     }: UdpMulticastServerOptions) {
-        let ipv4UdpChannel: UdpChannel | undefined = undefined;
-        if (broadcastAddressIpv4 !== undefined) {
+        const lifetime = (lifetimeOwner || Lifetime.process)?.join("multicast server");
+
+        try {
+            let ipv4UdpChannel: UdpChannel | undefined = undefined;
+            if (broadcastAddressIpv4 !== undefined) {
+                try {
+                    ipv4UdpChannel = await network.createUdpChannel({
+                        lifetime,
+                        type: "udp4",
+                        netInterface,
+                        listeningPort,
+                        reuseAddress: true,
+                    });
+                    await ipv4UdpChannel.addMembership(broadcastAddressIpv4);
+                } catch (error) {
+                    NoAddressAvailableError.accept(error);
+                    logger.info(
+                        `IPv4 UDP channel not created because IPv4 is not available: ${asError(error).message}`,
+                    );
+                }
+            }
+
+            let ipv6UdpChannel;
             try {
-                ipv4UdpChannel = await network.createUdpChannel({
-                    type: "udp4",
+                ipv6UdpChannel = await network.createUdpChannel({
+                    lifetime,
+                    type: "udp6",
                     netInterface,
                     listeningPort,
                     reuseAddress: true,
                 });
-                await ipv4UdpChannel.addMembership(broadcastAddressIpv4);
+                await ipv6UdpChannel.addMembership(broadcastAddressIpv6);
             } catch (error) {
                 NoAddressAvailableError.accept(error);
-                logger.info(`IPv4 UDP channel not created because IPv4 is not available: ${asError(error).message}`);
+                logger.info(`IPv6 UDP interface not created because IPv6 is not available, but required my Matter`);
+                throw error;
             }
-        }
 
-        try {
-            const ipv6UdpChannel = await network.createUdpChannel({
-                type: "udp6",
-                netInterface,
-                listeningPort,
-                reuseAddress: true,
-            });
-            await ipv6UdpChannel.addMembership(broadcastAddressIpv6);
             return new UdpMulticastServer(
+                lifetime,
                 network,
                 broadcastAddressIpv4,
                 broadcastAddressIpv6,
@@ -66,8 +93,7 @@ export class UdpMulticastServer {
                 netInterface,
             );
         } catch (error) {
-            NoAddressAvailableError.accept(error);
-            logger.info(`IPv6 UDP interface not created because IPv6 is not available, but required my Matter.`);
+            lifetime[Symbol.dispose]();
             throw error;
         }
     }
@@ -80,28 +106,38 @@ export class UdpMulticastServer {
     );
 
     private constructor(
-        readonly network: Network,
-        private readonly broadcastAddressIpv4: string | undefined,
-        private readonly broadcastAddressIpv6: string,
-        private readonly broadcastPort: number,
-        private readonly serverIpv4: UdpChannel | undefined,
-        private readonly serverIpv6: UdpChannel,
-        readonly netInterface: string | undefined,
-    ) {}
+        lifetime: Lifetime,
+        network: Network,
+        broadcastAddressIpv4: string | undefined,
+        broadcastAddressIpv6: string,
+        broadcastPort: number,
+        serverIpv4: UdpChannel | undefined,
+        serverIpv6: UdpChannel,
+        netInterface: string | undefined,
+    ) {
+        this.#lifetime = lifetime;
+        this.network = network;
+        this.#broadcastAddressIpv4 = broadcastAddressIpv4;
+        this.#broadcastAddressIpv6 = broadcastAddressIpv6;
+        this.#broadcastPort = broadcastPort;
+        this.#serverIpv4 = serverIpv4;
+        this.#serverIpv6 = serverIpv6;
+        this.netInterface = netInterface;
+    }
 
     get supportsIpv4() {
-        return this.serverIpv4 !== undefined;
+        return this.#serverIpv4 !== undefined;
     }
 
     onMessage(listener: (message: Bytes, peerAddress: string, netInterface: string) => void) {
-        this.serverIpv4?.onData((netInterface, peerAddress, _port, message) => {
+        this.#serverIpv4?.onData((netInterface, peerAddress, _port, message) => {
             if (netInterface === undefined) {
                 // Ignore Network packages not coming over any known interface
                 return;
             }
             listener(message, peerAddress, netInterface);
         });
-        this.serverIpv6.onData((netInterface, peerAddress, _port, message) => {
+        this.#serverIpv6.onData((netInterface, peerAddress, _port, message) => {
             if (netInterface === undefined) {
                 // Ignore Network packages not coming over any known interface
                 return;
@@ -118,7 +154,7 @@ export class UdpMulticastServer {
             try {
                 await (
                     await this.broadcastChannels.get(netInterface, isIPv4(uniCastTarget))
-                ).send(uniCastTarget, this.broadcastPort, message);
+                ).send(uniCastTarget, this.#broadcastPort, message);
             } catch (error) {
                 logger.info(`${netInterface} ${uniCastTarget}: ${asError(error).message}`);
             }
@@ -136,7 +172,7 @@ export class UdpMulticastServer {
                     await MatterAggregateError.allSettled(
                         ips.map(async ip => {
                             const iPv4 = ipV4.includes(ip);
-                            const broadcastTarget = iPv4 ? this.broadcastAddressIpv4 : this.broadcastAddressIpv6;
+                            const broadcastTarget = iPv4 ? this.#broadcastAddressIpv4 : this.#broadcastAddressIpv6;
                             if (broadcastTarget === undefined) {
                                 // IPv4 but disabled, so just resolve
                                 return;
@@ -144,7 +180,7 @@ export class UdpMulticastServer {
                             try {
                                 await (
                                     await this.broadcastChannels.get(netInterface, iPv4)
-                                ).send(broadcastTarget, this.broadcastPort, message);
+                                ).send(broadcastTarget, this.#broadcastPort, message);
                             } catch (error) {
                                 logger.info(`${netInterface}: ${asError(error).message}`);
                             }
@@ -159,16 +195,18 @@ export class UdpMulticastServer {
 
     private async createBroadcastChannel(netInterface: string, iPv4: string): Promise<UdpChannel> {
         return await this.network.createUdpChannel({
+            lifetime: this.#lifetime,
             type: iPv4 ? "udp4" : "udp6",
-            listeningPort: this.broadcastPort,
+            listeningPort: this.#broadcastPort,
             netInterface,
             reuseAddress: true,
         });
     }
 
     async close() {
-        await this.serverIpv4?.close();
-        await this.serverIpv6.close();
+        using _closing = this.#lifetime.closing();
+        await this.#serverIpv4?.close();
+        await this.#serverIpv6.close();
         await this.broadcastChannels.close();
     }
 }

package/src/time/StandardTime.ts

@@ -0,0 +1,122 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ImplementationError } from "#MatterError.js";
+import { Boot } from "#util/Boot.js";
+import { decamelize } from "#util/identifier-case.js";
+import { Lifetime } from "#util/Lifetime.js";
+import { Duration } from "./Duration.js";
+import { Time, Timer } from "./Time.js";
+import { Instant } from "./TimeUnit.js";
+
+/**
+ * A {@link Timer} implementation that uses standard JavaScript timers.
+ */
+export class StandardTime extends Time {
+    override getTimer(name: string, duration: Duration, callback: Timer.Callback) {
+        return new StandardTimer(name, duration, callback, false);
+    }
+
+    override getPeriodicTimer(name: string, duration: Duration, callback: Timer.Callback) {
+        return new StandardTimer(name, duration, callback, true);
+    }
+}
+
+/**
+ * A {@link Timer} implementation that uses standard JavaScript functions.
+ */
+export class StandardTimer implements Timer {
+    #timerId: unknown;
+    #utility = false;
+    #interval = Instant; // Real value installed in constructor
+    isRunning = false;
+
+    get systemId() {
+        return Number(this.#timerId);
+    }
+
+    constructor(
+        readonly name: string,
+        duration: Duration,
+        private readonly callback: Timer.Callback,
+        readonly isPeriodic: boolean,
+    ) {
+        this.interval = duration;
+    }
+
+    /**
+     * The timer's interval.
+     *
+     * You can change this value but changes have no effect until the timer restarts.
+     */
+    set interval(interval: Duration) {
+        if (interval < 0 || interval > 2147483647) {
+            throw new ImplementationError(
+                `Invalid intervalMs: ${interval}. The value must be between 0 and 32-bit maximum value (2147483647)`,
+            );
+        }
+        this.#interval = interval;
+    }
+
+    get interval() {
+        return this.#interval;
+    }
+
+    get utility() {
+        return this.#utility;
+    }
+
+    set utility(utility: boolean) {
+        if (utility === this.#utility) {
+            return;
+        }
+
+        // Support node.js-style environments to control whether the timer blocks process exit
+        if (this.#timerId !== undefined) {
+            const timerId = this.#timerId as { ref?: () => void; unref?: () => void };
+            if (utility) {
+                timerId.unref?.();
+            } else {
+                timerId.ref?.();
+            }
+        }
+
+        this.#utility = utility;
+    }
+
+    start() {
+        if (this.isRunning) this.stop();
+        Time.register(this);
+        this.isRunning = true;
+        this.#timerId = (this.isPeriodic ? setInterval : setTimeout)(() => {
+            using lifetime = Lifetime(decamelize(this.name, " "));
+            if (!this.isPeriodic) {
+                Time.unregister(this);
+                this.isRunning = false;
+            }
+            this.callback(lifetime);
+        }, this.interval);
+        return this;
+    }
+
+    stop() {
+        (this.isPeriodic ? clearInterval : clearTimeout)(this.#timerId as ReturnType<typeof setTimeout>);
+        Time.unregister(this);
+        this.isRunning = false;
+        return this;
+    }
+}
+
+Boot.init(() => {
+    Time.default = new StandardTime();
+
+    Time.startup.systemMs = Time.startup.processMs = Time.nowMs;
+
+    // Hook for testing frameworks
+    if (typeof MatterHooks !== "undefined") {
+        MatterHooks?.timeSetup?.(Time);
+    }
+});

package/src/time/Time.ts

@@ -4,13 +4,13 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Boot } from "#util/Boot.js";
+import { DiagnosticPresentation } from "#log/DiagnosticPresentation.js";
+import { NoProviderError } from "#MatterError.js";
 import { CancelablePromise } from "#util/Cancelable.js";
-import { ImplementationError } from "../MatterError.js";
+import type { Lifetime } from "#util/Lifetime.js";
 import { Diagnostic } from "../log/Diagnostic.js";
 import { DiagnosticSource } from "../log/DiagnosticSource.js";
 import { Duration } from "./Duration.js";
-import { Instant } from "./TimeUnit.js";
 import type { Timestamp } from "./Timestamp.js";
 
 const registry = new Set<Timer>();
@@ -53,8 +53,8 @@ export class Time {
     /**
      * Create a timer that will call callback after durationMs has passed.
      */
-    getTimer(name: string, duration: Duration, callback: Timer.Callback): Timer {
-        return new StandardTimer(name, duration, callback, false);
+    getTimer(_name: string, _duration: Duration, _callback: Timer.Callback): Timer {
+        throw new NoProviderError();
     }
     static readonly getTimer = (name: string, duration: Duration, callback: Timer.Callback): Timer =>
         Time.default.getTimer(name, duration, callback);
@@ -62,8 +62,8 @@ export class Time {
     /**
      * Create a timer that will periodically call callback at intervalMs intervals.
      */
-    getPeriodicTimer(name: string, duration: Duration, callback: Timer.Callback): Timer {
-        return new StandardTimer(name, duration, callback, true);
+    getPeriodicTimer(_name: string, _duration: Duration, _callback: Timer.Callback): Timer {
+        throw new NoProviderError();
     }
     static readonly getPeriodicTimer = (name: string, duration: Duration, callback: Timer.Callback): Timer =>
         Time.default.getPeriodicTimer(name, duration, callback);
@@ -77,7 +77,7 @@ export class Time {
         return new CancelablePromise(
             resolve => {
                 resolver = resolve;
-                timer = Time.getTimer(name, duration, resolve);
+                timer = Time.getTimer(name, duration, () => resolve());
                 timer.start();
             },
 
@@ -144,113 +144,21 @@ export interface Timer {
 }
 
 export namespace Timer {
-    export type Callback = () => any;
-}
-
-export class StandardTimer implements Timer {
-    #timerId: unknown;
-    #utility = false;
-    #interval = Instant; // Real value installed in constructor
-    isRunning = false;
-
-    get systemId() {
-        return Number(this.#timerId);
-    }
-
-    constructor(
-        readonly name: string,
-        duration: Duration,
-        private readonly callback: Timer.Callback,
-        readonly isPeriodic: boolean,
-    ) {
-        this.interval = duration;
-    }
-
-    /**
-     * The timer's interval.
-     *
-     * You can change this value but changes have no effect until the timer restarts.
-     */
-    set interval(interval: Duration) {
-        if (interval < 0 || interval > 2147483647) {
-            throw new ImplementationError(
-                `Invalid intervalMs: ${interval}. The value must be between 0 and 32-bit maximum value (2147483647)`,
-            );
-        }
-        this.#interval = interval;
-    }
-
-    get interval() {
-        return this.#interval;
-    }
-
-    get utility() {
-        return this.#utility;
-    }
-
-    set utility(utility: boolean) {
-        if (utility === this.#utility) {
-            return;
-        }
-
-        // Support node.js-style environments to control whether the timer blocks process exit
-        if (this.#timerId !== undefined) {
-            const timerId = this.#timerId as { ref?: () => void; unref?: () => void };
-            if (utility) {
-                timerId.unref?.();
-            } else {
-                timerId.ref?.();
-            }
-        }
-
-        this.#utility = utility;
-    }
-
-    start() {
-        if (this.isRunning) this.stop();
-        Time.register(this);
-        this.isRunning = true;
-        this.#timerId = (this.isPeriodic ? setInterval : setTimeout)(() => {
-            if (!this.isPeriodic) {
-                Time.unregister(this);
-                this.isRunning = false;
-            }
-            this.callback();
-        }, this.interval);
-        return this;
-    }
-
-    stop() {
-        (this.isPeriodic ? clearInterval : clearTimeout)(this.#timerId as ReturnType<typeof setTimeout>);
-        Time.unregister(this);
-        this.isRunning = false;
-        return this;
-    }
+    export type Callback = (lifetime: Lifetime) => any;
 }
 
 DiagnosticSource.add({
-    get [Diagnostic.value]() {
+    get [DiagnosticPresentation.value]() {
         return Diagnostic.node("⏱", "Timers", {
             children: [...registry].map(timer => [
                 timer.name,
                 Diagnostic.dict({
                     periodic: timer.isPeriodic,
-                    interval: timer.interval,
-                    system: timer.systemId,
-                    elapsed: timer.elapsed,
+                    up: timer.elapsed,
+                    interval: Duration.format(timer.interval),
+                    "system#": timer.systemId,
                 }),
             ]),
         });
     },
 });
-
-Boot.init(() => {
-    Time.default = new Time();
-
-    Time.startup.systemMs = Time.startup.processMs = Time.nowMs;
-
-    // Hook for testing frameworks
-    if (typeof MatterHooks !== "undefined") {
-        MatterHooks?.timeSetup?.(Time);
-    }
-});

package/src/time/Timestamp.ts

@@ -6,6 +6,7 @@
 
 import { UnexpectedDataError } from "#MatterError.js";
 import { Branded } from "#util/Type.js";
+import type { Duration } from "./Duration.js";
 import { Time } from "./Time.js";
 
 /**
@@ -91,4 +92,11 @@ export namespace Timestamp {
     export function dateOf(timestamp: Timestamp) {
         return new Date(timestamp);
     }
+
+    /**
+     * Compute the duration between two timestamps.
+     */
+    export function delta(from: Timestamp, to: Timestamp) {
+        return (to - from) as Duration;
+    }
 }

package/src/time/index.ts

@@ -5,6 +5,7 @@
  */
 
 export * from "./Duration.js";
+export * from "./StandardTime.js";
 export * from "./Time.js";
 export * from "./Timespan.js";
 export * from "./Timestamp.js";

package/src/transaction/Transaction.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { Lifetime } from "#util/Lifetime.js";
 import { MaybePromise } from "#util/Promises.js";
 import { Participant } from "./Participant.js";
 import { Resource } from "./Resource.js";
@@ -27,7 +28,7 @@ import { open } from "./Tx.js";
  *
  * TODO - does prevent deadlock but we should probably add a timeout for resource locking
  */
-export interface Transaction {
+export interface Transaction extends Lifetime.Owner {
     /**
      * Diagnostic description of the transaction's source.
      */
@@ -144,6 +145,14 @@ export interface Transaction {
      */
     rollback(): MaybePromise;
 
+    /**
+     * Destroy the transaction without proper commit or rollback.
+     *
+     * This guarantees a synchronous resolution but will result in an error if {@link Transaction#status} is not shared,
+     * read-only or destroyed.
+     */
+    [Symbol.dispose](): void;
+
     /**
      * Wait for a set of transactions to complete.
      *
@@ -168,8 +177,12 @@ export const Transaction = {
      * The transaction is destroyed when {@link act} returns.  You will receive an error if you access it after it is
      * destroyed.
      */
-    act<T>(via: string, actor: (transaction: Transaction) => MaybePromise<T>): MaybePromise<T> {
-        const tx = open(via);
+    act<T>(
+        via: string,
+        lifetime: Lifetime.Owner,
+        actor: (transaction: Transaction) => MaybePromise<T>,
+    ): MaybePromise<T> {
+        const tx = open(via, lifetime);
 
         let result;
         try {
@@ -188,9 +201,9 @@ export const Transaction = {
      *
      * When closed the transaction commits automatically if exclusive.
      */
-    open(via: string, isolation: Transaction.IsolationLevel = "rw") {
+    open(via: string, lifetime: Lifetime.Owner, isolation: Transaction.IsolationLevel = "rw") {
         // This function is replaced below so do not edit
-        return open(via, isolation);
+        return open(via, lifetime, isolation);
     },
 
     Status,
@@ -218,7 +231,7 @@ export namespace Transaction {
 
     export interface Finalization {
         /**
-         * Finish the transaction.  If {@link result} is a promise this may result on commit or rollback.
+         * Finish the transaction.  If {@link result} is a promise this may result in commit or rollback.
          */
         resolve<T>(result: T): MaybePromise<Awaited<T>>;
 

package/src/transaction/Tx.ts

@@ -11,6 +11,7 @@ import { Time, Timer } from "#time/Time.js";
 import { Timestamp } from "#time/Timestamp.js";
 import { Millis } from "#time/TimeUnit.js";
 import { asError } from "#util/Error.js";
+import { Lifetime } from "#util/Lifetime.js";
 import { Observable } from "#util/Observable.js";
 import { MaybePromise } from "#util/Promises.js";
 import { describeList } from "#util/String.js";
@@ -34,9 +35,10 @@ const MAX_CHAINED_COMMITS = 5;
  */
 export function open(
     via: string,
+    lifetime: Lifetime.Owner,
     isolation: Transaction.IsolationLevel = "rw",
 ): Transaction & Transaction.Finalization {
-    return new Tx(via, isolation);
+    return new Tx(via, lifetime, isolation);
 }
 
 /**
@@ -50,14 +52,35 @@ class Tx implements Transaction, Transaction.Finalization {
     #status;
     #waitingOn?: Iterable<Transaction>;
     #via: string;
+    #lifetime: Lifetime;
     #shared?: Observable<[]>;
     #closed?: Observable<[]>;
     #isAsync = false;
     #reportingLocks = false;
 
-    constructor(via: string, isolation: Transaction.IsolationLevel) {
+    constructor(via: string, lifetime: Lifetime.Owner, isolation: Transaction.IsolationLevel) {
         this.#via = Diagnostic.via(via);
+
+        this.#lifetime = lifetime.join("tx", via);
+        Object.defineProperties(this.#lifetime.details, {
+            status: {
+                get: () => this.#status,
+                enumerable: true,
+            },
+
+            resources: {
+                get: () => {
+                    if (!this.#resources.size) {
+                        return;
+                    }
+
+                    return [...this.#resources].join("+");
+                },
+            },
+        });
+
         this.#isolation = isolation;
+
         if (isolation === "rw") {
             this.#status = Status.Shared;
         } else {
@@ -66,6 +89,18 @@ class Tx implements Transaction, Transaction.Finalization {
     }
 
     [Symbol.dispose]() {
+        switch (this.status) {
+            case Status.ReadOnly:
+            case Status.Shared:
+            case Status.Destroyed:
+                break;
+
+            default:
+                logger.error(this.via, "Disposed", this.via, "while", this.status);
+                break;
+        }
+
+        using _closing = this.#lifetime.closing();
         this.#reset("dropped");
         this.#status = Status.Destroyed;
         this.#closed?.emit();
@@ -253,6 +288,8 @@ class Tx implements Transaction, Transaction.Finalization {
     }
 
     resolve<T>(result: T): MaybePromise<Awaited<T>> {
+        this.#lifetime.closing();
+
         // If result is a promise, we wait for resolution and then commit (success) or roll back (error)
         if (MaybePromise.is(result)) {
             this.isAsync = true;
@@ -292,6 +329,8 @@ class Tx implements Transaction, Transaction.Finalization {
     }
 
     reject(cause: unknown): MaybePromise<never> {
+        this.#lifetime.closing();
+
         if (this.#status === Status.Shared) {
             try {
                 this.#reset("released");
@@ -331,6 +370,14 @@ class Tx implements Transaction, Transaction.Finalization {
         throw cause;
     }
 
+    join(...name: unknown[]) {
+        if (this.#isolation === "ro") {
+            throw new ReadOnlyError();
+        }
+
+        return this.#lifetime.join(...name);
+    }
+
     /**
      * Execute commit logic for a single commit cycle.
      *