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

package/src/storage/StorageBackendMemory.ts

@@ -0,0 +1,131 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { StorageError, SyncStorage } from "./Storage.js";
+import { SupportedStorageTypes } from "./StringifyTools.js";
+
+export class StorageBackendMemory extends SyncStorage {
+    protected isInitialized = false;
+
+    constructor(protected store: any = {}) {
+        super();
+    }
+
+    get initialized() {
+        return this.isInitialized;
+    }
+
+    static async create(store: any = {}) {
+        const storage = new StorageBackendMemory(store);
+        storage.initialize();
+        return storage;
+    }
+
+    private createContextKey(contexts: string[]) {
+        const key = contexts.join(".");
+        if (!key.length || key.includes("..") || key.startsWith(".") || key.endsWith("."))
+            throw new StorageError("Context must not be an empty string.");
+        return key;
+    }
+
+    initialize() {
+        if (this.initialized) throw new StorageError("Storage already initialized!");
+        this.isInitialized = true;
+        // nothing else to do
+    }
+
+    close() {
+        this.isInitialized = false;
+        // nothing to do
+    }
+
+    clear() {
+        this.store = {};
+    }
+
+    get<T extends SupportedStorageTypes>(contexts: string[], key: string): T | undefined {
+        if (!this.initialized) throw new StorageError("Storage is not initialized");
+        if (!contexts.length || !key.length) throw new StorageError("Context and key must not be empty.");
+        return this.store[this.createContextKey(contexts)]?.[key];
+    }
+
+    #setKey(contexts: string[], key: string, value: SupportedStorageTypes) {
+        if (!contexts.length || !key.length) throw new StorageError("Context and key must not be empty.");
+        const contextKey = this.createContextKey(contexts);
+        if (this.store[contextKey] === undefined) {
+            this.store[contextKey] = {};
+        }
+        this.store[contextKey][key] = value;
+    }
+
+    set(
+        contexts: string[],
+        keyOrValues: string | Record<string, SupportedStorageTypes>,
+        value?: SupportedStorageTypes,
+    ) {
+        if (!this.initialized) throw new StorageError("Storage is not initialized");
+        if (typeof keyOrValues === "string") {
+            this.#setKey(contexts, keyOrValues, value);
+        } else {
+            Object.entries(keyOrValues).forEach(([key, value]) => {
+                this.#setKey(contexts, key, value);
+            });
+        }
+    }
+
+    delete(contexts: string[], key: string) {
+        if (!this.initialized) throw new StorageError("Storage is not initialized");
+        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");
+        if (!contexts.length) throw new StorageError("Context must not be empty!");
+        return Object.keys(this.store[this.createContextKey(contexts)] ?? {});
+    }
+
+    values(contexts: string[]) {
+        // Initialize and context checks are done by keys method
+        const values = {} as Record<string, SupportedStorageTypes>;
+        for (const key of this.keys(contexts)) {
+            values[key] = this.get(contexts, key);
+        }
+        return values;
+    }
+
+    contexts(contexts: string[]) {
+        if (!this.initialized) throw new StorageError("Storage is not initialized");
+        const contextKey = contexts.length ? this.createContextKey(contexts) : "";
+        const startContextKey = contextKey.length ? `${contextKey}.` : "";
+        const foundContexts = new Array<string>();
+        Object.keys(this.store).forEach(key => {
+            if (key.startsWith(startContextKey)) {
+                const subKeys = key.substring(startContextKey.length).split(".");
+                if (subKeys.length < 1) return; // should never happen
+                const context = subKeys[0];
+                if (!foundContexts.includes(context)) {
+                    foundContexts.push(context);
+                }
+            }
+        });
+        return foundContexts;
+    }
+
+    clearAll(contexts: string[]) {
+        if (!this.initialized) throw new StorageError("Storage is not initialized");
+        const contextKey = this.createContextKey(contexts);
+        if (contextKey.length) {
+            delete this.store[contextKey];
+        }
+        const startContextKey = contextKey.length ? `${contextKey}.` : "";
+        Object.keys(this.store).forEach(key => {
+            if (key.startsWith(startContextKey)) {
+                delete this.store[key];
+            }
+        });
+    }
+}

package/src/storage/StorageContext.ts

@@ -0,0 +1,111 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { MaybePromise } from "../util/Promises.js";
+import { Storage, StorageError, StorageOperationResult } from "./Storage.js";
+import { SupportedStorageTypes } from "./StringifyTools.js";
+
+export class StorageContext<S extends Storage = any> {
+    constructor(
+        private readonly storage: S,
+        readonly thisContexts: string[],
+    ) {}
+
+    get<T extends SupportedStorageTypes>(key: string, defaultValue?: T): StorageOperationResult<S, T> {
+        const value = this.storage.get(this.thisContexts, key);
+        if (value !== undefined) {
+            if (MaybePromise.is(value)) {
+                return value.then(v => {
+                    if (v !== undefined) return v;
+                    if (defaultValue === undefined) {
+                        throw new StorageError(
+                            `No value found for key ${key} in context ${this.thisContexts} and no default value specified!`,
+                        );
+                    }
+                    return defaultValue;
+                }) as StorageOperationResult<S, T>;
+            }
+            return value as StorageOperationResult<S, T>;
+        }
+        if (defaultValue === undefined) {
+            throw new StorageError(
+                `No value found for key ${key} in context ${this.thisContexts} and no default value specified!`,
+            );
+        }
+        return defaultValue as StorageOperationResult<S, T>;
+    }
+
+    has(key: string) {
+        const value = this.storage.get(this.thisContexts, key);
+        if (value !== undefined) {
+            if (MaybePromise.is(value)) {
+                return value.then(v => v !== undefined) as StorageOperationResult<S, boolean>;
+            }
+            return true as StorageOperationResult<S, boolean>;
+        }
+        return false as StorageOperationResult<S, boolean>;
+    }
+
+    set(key: string, value: SupportedStorageTypes): StorageOperationResult<S>;
+    set(values: Record<string, SupportedStorageTypes>): StorageOperationResult<S>;
+    set(keyOrValues: string | Record<string, SupportedStorageTypes>, value?: SupportedStorageTypes) {
+        if (typeof keyOrValues === "string") {
+            return this.storage.set(this.thisContexts, keyOrValues, value) as StorageOperationResult<S>;
+        }
+        return this.storage.set(this.thisContexts, keyOrValues) as StorageOperationResult<S>;
+    }
+
+    delete(key: string) {
+        return this.storage.delete(this.thisContexts, key) as StorageOperationResult<S>;
+    }
+
+    createContext(context: string): StorageContext<S> {
+        if (context.length === 0) throw new StorageError("Context must not be an empty string");
+        if (context.includes(".")) throw new StorageError("Context must not contain dots!");
+        return new StorageContext(this.storage, [...this.thisContexts, context]);
+    }
+
+    keys() {
+        return this.storage.keys(this.thisContexts) as StorageOperationResult<S, string[]>;
+    }
+
+    values() {
+        return this.storage.values(this.thisContexts) as StorageOperationResult<
+            S,
+            Record<string, SupportedStorageTypes>
+        >;
+    }
+
+    contexts() {
+        return this.storage.contexts(this.thisContexts) as StorageOperationResult<S, string[]>;
+    }
+
+    /** Clears all keys in this context */
+    clear() {
+        const keys = this.keys();
+        if (MaybePromise.is(keys)) {
+            return keys.then(keys => {
+                return Promise.all(keys.map(key => this.delete(key))).then(() => Promise.resolve());
+            }) as StorageOperationResult<S>;
+        }
+        const promises = new Array<PromiseLike<void>>();
+        keys.forEach(key => {
+            const promise = this.delete(key);
+            if (promise !== undefined && MaybePromise.is(promise)) {
+                promises.push(promise);
+            }
+        });
+        if (promises.length > 0) {
+            return Promise.all(promises).then(() => Promise.resolve()) as StorageOperationResult<S>;
+        }
+        return undefined as StorageOperationResult<S>;
+    }
+
+    /** Clears all keys in this context and all created sub-contexts. */
+    clearAll() {
+        return this.storage.clearAll(this.thisContexts) as StorageOperationResult<S>;
+    }
+}

package/src/storage/StorageManager.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { MaybePromise } from "../util/Promises.js";
+import { Storage, StorageError } from "./Storage.js";
+import { StorageContext } from "./StorageContext.js";
+
+export class StorageManager<S extends Storage = any> {
+    private initialized = false;
+
+    constructor(private storage: S) {}
+
+    initialize(): MaybePromise<void> {
+        if (!this.storage.initialized) {
+            const init = this.storage.initialize();
+            if (MaybePromise.is(init)) {
+                return init.then(() => {
+                    this.initialized = true;
+                });
+            }
+        }
+        this.initialized = true;
+    }
+
+    close() {
+        this.initialized = false;
+        return this.storage.close();
+    }
+
+    createContext(context: string): StorageContext<S> {
+        if (!this.initialized) throw new StorageError("The storage needs to be initialized first!");
+        if (!context.length) throw new StorageError("Context must not be an empty string!");
+        if (context.includes(".")) throw new StorageError("Context must not contain dots!");
+        return new StorageContext(this.storage, [context]);
+    }
+}

package/src/storage/StorageService.ts

@@ -0,0 +1,73 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { NoProviderError } from "../MatterError.js";
+import { Environment } from "../environment/Environment.js";
+import { Environmental } from "../environment/Environmental.js";
+import { Diagnostic } from "../log/Diagnostic.js";
+import { Storage } from "./Storage.js";
+import { StorageManager } from "./StorageManager.js";
+
+/**
+ * Service adapter for the Matter.js storage API.
+ */
+export class StorageService {
+    #factory?: (namespace: string) => Storage;
+    #location?: string;
+
+    constructor(environment: Environment, factory?: (namespace: string) => Storage) {
+        environment.set(StorageService, this);
+        this.#factory = factory;
+    }
+
+    static [Environmental.create](environment: Environment) {
+        return new this(environment);
+    }
+
+    /**
+     * Open storage.  The storage is initialized but the caller must take ownership.
+     *
+     * @param namespace a unique namespace identifier such as a root node ID
+     */
+    async open(namespace: string) {
+        if (this.#factory === undefined) {
+            throw new NoProviderError("Storage is unavailable because no platform implementation is installed");
+        }
+
+        const storage = this.#factory(namespace);
+        const manager = new StorageManager(storage);
+        await manager.initialize();
+        return manager;
+    }
+
+    /**
+     * Install a factory for opening storage.  Without such a factory storage is unavailable.
+     */
+    set factory(factory: (namespace: string) => Storage) {
+        this.#factory = factory;
+    }
+
+    /**
+     * The storage location.  Only used for diagnostic purposes.
+     */
+    get location() {
+        return this.#location;
+    }
+
+    set location(location: string | undefined) {
+        this.#location = location;
+    }
+
+    [Diagnostic.value]() {
+        return [
+            "Persistence",
+            Diagnostic.dict({
+                location: location ?? "(unknown)",
+                available: !!this.#factory,
+            }),
+        ];
+    }
+}

package/src/storage/StringifyTools.ts

@@ -0,0 +1,107 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { UnexpectedDataError } from "../MatterError.js";
+import { Bytes } from "../util/Bytes.js";
+import { isObject } from "../util/Type.js";
+
+/** Supported base types to stringify the data for the storage that can be used as keys and also values. */
+type SupportedStorageBaseTypes = string | number | boolean | bigint | Uint8Array;
+
+/** Supported combined types to stringify the data for the storage that can be used as values. */
+type SupportedComplexStorageTypes =
+    | Array<SupportedStorageBaseTypes | SupportedComplexStorageTypes> // Arrays
+    | { [key: string]: SupportedStorageBaseTypes | SupportedComplexStorageTypes | null | undefined } // Objects
+    | Array<[SupportedStorageBaseTypes, SupportedStorageBaseTypes | SupportedComplexStorageTypes | null | undefined]> // Map style arrays
+    | Map<SupportedStorageBaseTypes, SupportedStorageBaseTypes | SupportedComplexStorageTypes>
+    | null
+    | undefined; // Maps
+
+export type SupportedStorageTypes = SupportedStorageBaseTypes | SupportedComplexStorageTypes;
+
+/** Special Magic key to identify special object types with custom encoding in JSON. */
+const JSON_SPECIAL_KEY_TYPE = "__object__";
+
+/** Special Magic key to identify the value of the custom encoded objects in JSON. */
+const JSON_SPECIAL_KEY_VALUE = "__value__";
+
+export function toJson(object: SupportedStorageTypes, spaces?: number): string {
+    return JSON.stringify(
+        object,
+        (_key, value) => {
+            if (value === undefined) {
+                return `{"${JSON_SPECIAL_KEY_TYPE}":"Undefined"}`;
+            }
+            if (typeof value === "bigint") {
+                return `{"${JSON_SPECIAL_KEY_TYPE}":"BigInt","${JSON_SPECIAL_KEY_VALUE}":"${value.toString()}"}`;
+            }
+            if (value instanceof Uint8Array) {
+                return `{"${JSON_SPECIAL_KEY_TYPE}":"Uint8Array","${JSON_SPECIAL_KEY_VALUE}":"${Bytes.toHex(value)}"}`;
+            }
+            //Node.js can sometimes pass in a native Buffer object in place of a Uint8Array, of which it is a subclass of, the Buffer class implements its own toJSON method which breaks our serialization.
+            if (isObject(value) && value.type === "Buffer" && Array.isArray(value.data)) {
+                return `{"${JSON_SPECIAL_KEY_TYPE}":"Uint8Array","${JSON_SPECIAL_KEY_VALUE}":"${Bytes.toHex(
+                    Uint8Array.from(value.data),
+                )}"}`;
+            }
+            if (value instanceof Map) {
+                return `{"${JSON_SPECIAL_KEY_TYPE}":"Map","${JSON_SPECIAL_KEY_VALUE}":${JSON.stringify(
+                    toJson(Array.from(value.entries())),
+                )}}`;
+            }
+            return value;
+        },
+        spaces,
+    );
+}
+
+export function fromJson(json: string): SupportedStorageTypes {
+    return JSON.parse(json, (_key, value) => {
+        if (typeof value === "string" && value.startsWith(`{"${JSON_SPECIAL_KEY_TYPE}":"`) && value.endsWith("}")) {
+            const data = JSON.parse(value);
+            const object = data[JSON_SPECIAL_KEY_TYPE];
+            switch (object) {
+                case "Undefined":
+                    return undefined;
+                case "BigInt":
+                    return BigInt(data[JSON_SPECIAL_KEY_VALUE]);
+                case "Uint8Array":
+                    return Bytes.fromHex(data[JSON_SPECIAL_KEY_VALUE]);
+                case "Map":
+                    return new Map(
+                        fromJson(data[JSON_SPECIAL_KEY_VALUE]) as [
+                            SupportedStorageBaseTypes,
+                            SupportedStorageBaseTypes,
+                        ][],
+                    );
+
+                // TODO Remove in the future, leave here for now for backward compatibility?
+                case "AttributeId":
+                case "CaseAuthenticatedTag":
+                case "ClusterId":
+                case "CommandId":
+                case "DataVersion":
+                case "DeviceTypeId":
+                case "EndpointNumber":
+                case "EntryIndex":
+                case "EventId":
+                case "FabricIndex":
+                case "FieldId":
+                case "GroupId":
+                case "VendorId":
+                    return data[JSON_SPECIAL_KEY_VALUE];
+                case "EventNumber":
+                case "FabricId":
+                case "NodeId":
+                    return BigInt(data[JSON_SPECIAL_KEY_VALUE]);
+
+                default:
+                    throw new UnexpectedDataError(`Unknown object type: ${object}`);
+            }
+        }
+        return value;
+    });
+}

package/src/storage/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./Storage.js";
+export * from "./StorageBackendMemory.js";
+export * from "./StorageContext.js";
+export * from "./StorageManager.js";
+export * from "./StorageService.js";
+export * from "./StringifyTools.js";

package/src/time/Time.ts

@@ -0,0 +1,179 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ImplementationError } from "../MatterError.js";
+import { Diagnostic } from "../log/Diagnostic.js";
+import { DiagnosticSource } from "../log/DiagnosticSource.js";
+
+const registry = new Set<Timer>();
+
+/**
+ * Timer and date/time management interface.
+ *
+ * You may replace this platform abstraction but we provide an implementation compatible with any standard JS
+ * environment.
+ */
+export class Time {
+    static get = () => time;
+
+    now() {
+        return new Date();
+    }
+    static readonly now = (): Date => Time.get().now();
+
+    nowMs() {
+        return this.now().getTime();
+    }
+    static readonly nowMs = (): number => Time.get().nowMs();
+
+    /** Returns a timer that will call callback after durationMs has passed. */
+    getTimer(name: string, durationMs: number, callback: Timer.Callback): Timer {
+        return new StandardTimer(name, durationMs, callback, false);
+    }
+    static readonly getTimer = (name: string, durationMs: number, callback: Timer.Callback): Timer =>
+        Time.get().getTimer(name, durationMs, callback);
+
+    /** Returns a timer that will periodically call callback at intervalMs intervals. */
+    getPeriodicTimer(name: string, intervalMs: number, callback: Timer.Callback): Timer {
+        return new StandardTimer(name, intervalMs, callback, true);
+    }
+    static readonly getPeriodicTimer = (name: string, intervalMs: number, callback: Timer.Callback): Timer =>
+        Time.get().getPeriodicTimer(name, intervalMs, callback);
+
+    static readonly sleep = async (name: string, durationMs: number): Promise<void> =>
+        new Promise(resolve => Time.get().getTimer(name, durationMs, resolve).start());
+
+    static register(timer: Timer) {
+        timer.elapsed = Diagnostic.elapsed();
+        registry.add(timer);
+    }
+
+    static unregister(timer: Timer) {
+        registry.delete(timer);
+    }
+}
+
+const time = new Time();
+
+export interface Timer {
+    /** Name (diagnostics) */
+    name: string;
+
+    /** Set to true to indicate the timer should not prevent program exit */
+    utility: boolean;
+
+    /** System ID (diagnostics) */
+    systemId: unknown;
+
+    /** Interval (diagnostics) */
+    intervalMs: number;
+
+    /** Is the timer periodic? (diagnostics) */
+    isPeriodic: boolean;
+
+    /** Amount of time interval has been active (diagnostics) */
+    elapsed?: Diagnostic.Elapsed;
+
+    /** Is true if this timer is running. */
+    isRunning: boolean;
+
+    /** Starts this timer, chainable. */
+    start(): Timer;
+
+    /** Stops this timer, chainable. */
+    stop(): Timer;
+}
+
+export namespace Timer {
+    export type Callback = () => any;
+}
+
+export class StandardTimer implements Timer {
+    #timerId: unknown;
+    #utility = false;
+    isRunning = false;
+
+    get systemId() {
+        return Number(this.#timerId);
+    }
+
+    constructor(
+        readonly name: string,
+        readonly intervalMs: number,
+        private readonly callback: Timer.Callback,
+        readonly isPeriodic: boolean,
+    ) {
+        if (intervalMs < 0 || intervalMs > 2147483647) {
+            throw new ImplementationError(
+                `Invalid intervalMs: ${intervalMs}. The value must be between 0 and 32-bit maximum value (2147483647)`,
+            );
+        }
+    }
+
+    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.intervalMs);
+        return this;
+    }
+
+    stop() {
+        (this.isPeriodic ? clearInterval : clearTimeout)(this.#timerId as ReturnType<typeof setTimeout>);
+        Time.unregister(this);
+        this.isRunning = false;
+        return this;
+    }
+}
+
+// Hook for testing frameworks
+if (typeof MatterHooks !== "undefined") {
+    MatterHooks.timeSetup?.(Time);
+}
+
+DiagnosticSource.add({
+    get [Diagnostic.value]() {
+        return Diagnostic.node("⏱", "Timers", {
+            children: [...registry].map(timer => [
+                timer.name,
+                Diagnostic.dict({
+                    periodic: timer.isPeriodic,
+                    interval: Diagnostic.interval(timer.intervalMs),
+                    system: timer.systemId,
+                    elapsed: timer.elapsed,
+                }),
+            ]),
+        });
+    },
+});

package/src/time/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./Time.js";

package/src/tsconfig.json

@@ -0,0 +1,10 @@
+{
+    "extends": "../../tools/tsc/tsconfig.lib.json",
+    "compilerOptions": {
+        "types": [
+            "@matter/tools",
+            "globals"
+        ]
+    },
+    "references": []
+}

package/src/util/Array.ts

@@ -0,0 +1,15 @@
+/**
+ * Array types
+ *
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export type AtLeastOne<T> = ArrayMinLength<T, 1>;
+
+type BuildArrayMinLength<T, N extends number, Current extends T[]> = Current["length"] extends N
+    ? [...Current, ...T[]]
+    : BuildArrayMinLength<T, N, [...Current, T]>;
+
+export type ArrayMinLength<T, N extends number> = BuildArrayMinLength<T, N, []>;