@matter/general 0.15.1 → 0.15.2-alpha.0-20250703-2e16aba2b

package/src/storage/StorageBackendMemory.ts

@@ -58,7 +58,7 @@ export class StorageBackendMemory extends SyncStorage implements CloneableStorag
     }
 
     get<T extends SupportedStorageTypes>(contexts: string[], key: string): T | undefined {
-        if (!this.initialized) throw new StorageError("Storage is not initialized");
+        this.#assertInitialized();
         if (!contexts.length || !key.length) throw new StorageError("Context and key must not be empty.");
         return this.store[this.createContextKey(contexts)]?.[key];
     }
@@ -77,7 +77,7 @@ export class StorageBackendMemory extends SyncStorage implements CloneableStorag
         keyOrValues: string | Record<string, SupportedStorageTypes>,
         value?: SupportedStorageTypes,
     ) {
-        if (!this.initialized) throw new StorageError("Storage is not initialized");
+        this.#assertInitialized();
         if (typeof keyOrValues === "string") {
             this.#setKey(contexts, keyOrValues, value);
         } else {
@@ -88,13 +88,13 @@ export class StorageBackendMemory extends SyncStorage implements CloneableStorag
     }
 
     delete(contexts: string[], key: string) {
-        if (!this.initialized) throw new StorageError("Storage is not initialized");
+        this.#assertInitialized();
         if (!contexts.length || !key.length) throw new StorageError("Context and key must not be empty.");
         delete this.store[this.createContextKey(contexts)]?.[key];
     }
 
     keys(contexts: string[]) {
-        if (!this.initialized) throw new StorageError("Storage is not initialized");
+        this.#assertInitialized();
         if (!contexts.length) throw new StorageError("Context must not be empty!");
         return Object.keys(this.store[this.createContextKey(contexts)] ?? {});
     }
@@ -109,7 +109,7 @@ export class StorageBackendMemory extends SyncStorage implements CloneableStorag
     }
 
     contexts(contexts: string[]) {
-        if (!this.initialized) throw new StorageError("Storage is not initialized");
+        this.#assertInitialized();
         const contextKey = contexts.length ? this.createContextKey(contexts) : "";
         const startContextKey = contextKey.length ? `${contextKey}.` : "";
         const foundContexts = new Array<string>();
@@ -127,7 +127,7 @@ export class StorageBackendMemory extends SyncStorage implements CloneableStorag
     }
 
     clearAll(contexts: string[]) {
-        if (!this.initialized) throw new StorageError("Storage is not initialized");
+        this.#assertInitialized();
         const contextKey = this.createContextKey(contexts);
         if (contextKey.length) {
             delete this.store[contextKey];
@@ -139,4 +139,12 @@ export class StorageBackendMemory extends SyncStorage implements CloneableStorag
             }
         });
     }
+
+    #assertInitialized() {
+        if (this.initialized) {
+            return;
+        }
+
+        throw new StorageError("Storage is not initialized");
+    }
 }

package/src/time/Time.ts

@@ -83,8 +83,8 @@ export class Time {
     }
 
     static register(timer: Timer) {
-        timer.elapsed = Diagnostic.elapsed();
         registry.add(timer);
+        timer.elapsed = Diagnostic.elapsed();
     }
 
     static unregister(timer: Timer) {
@@ -137,6 +137,7 @@ export namespace Timer {
 export class StandardTimer implements Timer {
     #timerId: unknown;
     #utility = false;
+    #intervalMs = -1;
     isRunning = false;
 
     get systemId() {
@@ -145,15 +146,29 @@ export class StandardTimer implements Timer {
 
     constructor(
         readonly name: string,
-        readonly intervalMs: number,
+        intervalMs: number,
         private readonly callback: Timer.Callback,
         readonly isPeriodic: boolean,
     ) {
+        this.intervalMs = intervalMs;
+    }
+
+    /**
+     * The timer's interval.
+     *
+     * You can change this value but changes have no effect until the timer restarts.
+     */
+    set intervalMs(intervalMs: number) {
         if (intervalMs < 0 || intervalMs > 2147483647) {
             throw new ImplementationError(
                 `Invalid intervalMs: ${intervalMs}. The value must be between 0 and 32-bit maximum value (2147483647)`,
             );
         }
+        this.#intervalMs = intervalMs;
+    }
+
+    get intervalMs() {
+        return this.#intervalMs;
     }
 
     get utility() {

package/src/util/Cancelable.ts

@@ -6,7 +6,7 @@
 
 import type { Logger } from "#log/Logger.js";
 import { CanceledError } from "#MatterError.js";
-import { errorOf } from "./Error.js";
+import { asError, errorOf } from "./Error.js";
 import { createPromise, MaybePromise } from "./Promises.js";
 
 /**
@@ -81,13 +81,13 @@ export class CancelablePromise<T = void> implements Promise<T>, Cancelable {
     /**
      * Cancel the operation.
      */
-    cancel(reason: any = new CanceledError()) {
+    cancel(reason: unknown = new CanceledError()) {
         if (this.#isSettled) {
             return;
         }
 
         try {
-            this.onCancel(reason);
+            this.onCancel(asError(reason));
         } catch (e) {
             this.#reject(e);
         }

package/src/util/Construction.ts

@@ -148,6 +148,8 @@ export interface Construction<T> extends Promise<T> {
      *
      *   - Ensures the subject is fully initialized before closing.
      *
+     *   - Guards against closing multiple times; tertiary closes will wait for destruction.
+     *
      *   - Handles and logs errors, ensuring close() always completes successfully.
      *
      *   - Makes destruction observable via {@link change} and {@link closed}.
@@ -437,11 +439,23 @@ export function Construction<const T extends Constructable>(
                 return invokeDestructor();
             }
 
-            if (status === Lifecycle.Status.Initializing) {
-                return this.then(beginDestruction, beginDestruction);
-            }
+            switch (status) {
+                case Lifecycle.Status.Initializing:
+                    // Wait for initialization to complete, then close
+                    return this.then(beginDestruction, beginDestruction);
+
+                case Lifecycle.Status.Destroying:
+                    // Wait for previously initiated destruction to complete
+                    return this.closed;
 
-            return beginDestruction();
+                case Lifecycle.Status.Destroyed:
+                    // Already destroyed
+                    return;
+
+                default:
+                    // Begin destruction
+                    return beginDestruction();
+            }
         },
 
         finally(onfinally: () => void): Promise<T> {

package/src/util/Promises.ts

@@ -7,7 +7,7 @@
  */
 
 import { asError } from "#util/Error.js";
-import { InternalError, MatterError } from "../MatterError.js";
+import { InternalError, TimeoutError } from "../MatterError.js";
 import { Time } from "../time/Time.js";
 
 /**
@@ -67,11 +67,7 @@ export function anyPromise<T>(promises: ((() => Promise<T>) | Promise<T>)[]): Pr
 /**
  * Thrown when a timed promise times out.
  */
-export class PromiseTimeoutError extends MatterError {
-    constructor(message = "Operation timed out") {
-        super(message);
-    }
-}
+export class PromiseTimeoutError extends TimeoutError {}
 
 /**
  * Create a promise with a timeout.
@@ -109,7 +105,6 @@ export async function withTimeout<T>(
                 reject(asError(e));
                 return;
             }
-            reject(new Error("Timer canceled promise, but no error was thrown"));
         });
 
         cancelTimer = () => {

package/src/util/String.ts

@@ -4,6 +4,10 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { ImplementationError } from "#MatterError.js";
+import { Bytes } from "./Bytes.js";
+import { isObject } from "./Type.js";
+
 export function capitalize<T extends string>(text: T) {
     return (text[0].toUpperCase() + text.slice(1)) as Capitalize<T>;
 }
@@ -246,3 +250,65 @@ export function describeList(setType: "and" | "or", ...entries: string[]) {
 
     return text.join(" ");
 }
+
+/**
+ * Serialize a structure to JS code that will recreate it.  Supports a limited number of JS types.  Makes no effort at
+ * pretty printing.
+ */
+export function serializeToJs(value: unknown) {
+    switch (typeof value) {
+        case "bigint":
+            return `0x${value.toString(16)}n`;
+
+        case "boolean":
+            return `${value}`;
+
+        case "number":
+            if (Number.isSafeInteger(value) && value > 10) {
+                return `0x${value.toString(16)}`;
+            }
+            return `${value}`;
+
+        case "string":
+            return JSON.stringify(value);
+
+        case "undefined":
+            return "undefined";
+
+        case "function":
+        case "symbol":
+            throw new ImplementationError(`Cannot serialize a ${typeof value}`);
+    }
+
+    if (value instanceof Date) {
+        return `new Date(${JSON.stringify(value.toISOString)})`;
+    }
+
+    if (value instanceof Uint8Array) {
+        return `b$\`${Bytes.toHex(value)}\``;
+    }
+
+    if (value === null) {
+        return "null";
+    }
+
+    if (Array.isArray(value)) {
+        const parts = ["["];
+        for (const item of value) {
+            parts.push(serializeToJs(item), ",");
+        }
+        parts.push("]");
+        return parts.join("");
+    }
+
+    if (!isObject(value)) {
+        throw new ImplementationError(`Cannot serialize a ${(value as any).constructor.name}`);
+    }
+
+    const parts = ["{"];
+    for (const key in value) {
+        parts.push(key, ":", serializeToJs(value[key]), ",");
+    }
+    parts.push("}");
+    return parts.join("");
+}