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

package/src/util/Ip.ts

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Bytes } from "./Bytes.js";
+
+export function isIPv4(ip: string) {
+    return ip.includes(".");
+}
+
+export function isIPv6(ip: string) {
+    return ip.includes(":");
+}
+
+export function ipv4ToNumber(ip: string) {
+    const dataView = Bytes.dataViewOf(ipv4ToBytes(ip));
+    return dataView.getUint32(0);
+}
+
+export function ipv4ToBytes(ip: string) {
+    const array = new Uint8Array(4);
+    const ipParts = ip.split(".");
+    for (let i = 0; i < 4; i++) {
+        array[i] = parseInt(ipParts[i]);
+    }
+    return array;
+}
+
+export function ipv6ToArray(ip: string) {
+    const array = new Uint16Array(8);
+    let ipParts = ip.split(":");
+    const valueCount = ipParts.filter(value => value !== "").length;
+    if (valueCount !== 8) {
+        ipParts = ip.replace("::", ":".padEnd((8 - valueCount) * 2 + 1, "0:")).split(":");
+    }
+    let index = 0;
+    ipParts.forEach(part => {
+        if (part === "") return;
+        array[index++] = parseInt(part, 16);
+    });
+    return array;
+}
+
+export function ipv6ToBytes(ip: string) {
+    return Uint8Array.from(Array.from(ipv6ToArray(ip)).flatMap(value => [value >> 8, value & 0xff]));
+}
+
+export function onSameNetwork(ip1: string, ip2: string, mask: string) {
+    if (isIPv4(ip1)) {
+        // IPv4 addresses
+        if (!isIPv4(ip2) || !isIPv4(mask)) return false;
+        const ip1Number = ipv4ToNumber(ip1);
+        const ip2Number = ipv4ToNumber(ip2);
+        const maskNumber = ipv4ToNumber(mask);
+
+        return (ip1Number & maskNumber) === (ip2Number & maskNumber);
+    } else {
+        // IPv6 addresses
+        if (isIPv4(ip2) || isIPv4(mask)) return false;
+        const ip1Array = ipv6ToArray(ip1);
+        const ip2Array = ipv6ToArray(ip2);
+        const maskArray = ipv6ToArray(mask);
+
+        for (let i = 0; i < 16; i++) {
+            const mask = maskArray[i];
+            if (mask === 0) return true;
+            if ((ip1Array[i] & mask) !== (ip2Array[i] & mask)) return false;
+        }
+    }
+}

package/src/util/Lifecycle.ts

@@ -0,0 +1,135 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ImplementationError, MatterAggregateError } from "../MatterError.js";
+import { MaybePromise } from "../util/Promises.js";
+
+export namespace Lifecycle {
+    /**
+     * Standard statuses in an object's lifecycle.
+     */
+    export enum Status {
+        Unknown = "unknown",
+        Inactive = "inactive",
+        Initializing = "initializing",
+        Active = "active",
+        Crashed = "crashed",
+        Destroying = "destroying",
+        Destroyed = "destroyed",
+    }
+
+    /**
+     * Lifecycle status for multiple items.
+     */
+    export type Map<T extends keyof any> = Record<T, Status>;
+
+    /**
+     * Assert subject is active.
+     */
+    export function assertActive(status: Status, description?: string) {
+        if (!description) {
+            description = "dependency";
+        }
+
+        switch (status) {
+            case Status.Active:
+                return;
+
+            case Status.Inactive:
+                throw new UninitializedDependencyError(description, "is not initialized");
+
+            case Status.Initializing:
+                throw new UninitializedDependencyError(description, "is still initializing");
+
+            case Status.Crashed:
+                throw new CrashedDependencyError(description, "initialization failed");
+
+            case Status.Destroying:
+                throw new DestroyedDependencyError(description, "is closing");
+
+            case Status.Destroyed:
+                throw new DestroyedDependencyError(description, "is closed");
+        }
+
+        throw new DependencyLifecycleError(description, `status "${status}" is unknown`);
+    }
+}
+
+/**
+ * Base class for errors related to the lifecycle of a dependency.
+ */
+export class DependencyLifecycleError extends ImplementationError {
+    constructor(what: string, why: string) {
+        super(`${what} ${why}`);
+    }
+}
+
+/**
+ * Standard interface for objects that have a primary task that may initiate after construction.
+ */
+export interface Startable {
+    /**
+     * Commence with the object's primary activity.
+     *
+     * Start should have no effect if the object is already started.
+     */
+    start(): void;
+}
+
+/**
+ * Standard interface for objects supporting a task that may be aborted or stopped prior to destruction.
+ */
+export interface Cancellable {
+    /**
+     * Stop the object's primary activity.  This should result in termination as quickly as possible.
+     *
+     * Cancellation have no effect if the object is cancelled or otherwise in a state where cancellation is irrelevant.
+     */
+    cancel(): void;
+}
+
+/**
+ * Standard interface for disposing of object resources.
+ */
+export interface Destructable {
+    close(): void | Promise<void>;
+
+    [Symbol.dispose]?: () => void;
+
+    [Symbol.asyncDispose]?: () => MaybePromise<void>;
+}
+
+/**
+ * Thrown when a dependency is in an unsupported state.
+ */
+export class UnsupportedDependencyStatusError extends DependencyLifecycleError {}
+
+/**
+ * Thrown for actions that cannot be performed until further initialization occurs.
+ */
+export class UninitializedDependencyError extends DependencyLifecycleError {}
+
+/**
+ * Thrown for actions that cannot be performed because dependency crashed.
+ */
+export class CrashedDependencyError extends DependencyLifecycleError {
+    subject?: object;
+}
+
+/**
+ * Thrown for actions that cannot be performed because a dependency has been destroyed.
+ */
+export class DestroyedDependencyError extends DependencyLifecycleError {}
+
+/**
+ * Thrown for actions that cannot be performed because a dependency is not supported.
+ */
+export class UnsupportedDependencyError extends DependencyLifecycleError {}
+
+/**
+ * Thrown if multiple dependencies crash.
+ */
+export class CrashedDependenciesError extends MatterAggregateError {}

package/src/util/Multiplex.ts

@@ -0,0 +1,14 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * A "multiplex" tracks an extensible set of promises.
+ */
+export interface Multiplex {
+    add(worker: Promise<unknown>): void;
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}

package/src/util/Mutex.ts

@@ -0,0 +1,100 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger } from "../log/Logger.js";
+
+const logger = Logger.get("Mutex");
+
+/**
+ * A mutex is a task queue where at most one task is active at a time.
+ */
+export class Mutex implements PromiseLike<unknown> {
+    #owner: {};
+    #cancel?: () => void;
+    #canceled = false;
+    #promise?: Promise<unknown>;
+
+    constructor(owner: {}, initial?: PromiseLike<unknown>) {
+        this.#owner = owner;
+        if (initial) {
+            this.run(() => initial);
+        }
+    }
+
+    /**
+     * As a PromiseLike, you can await the Mutex.  This promise resolves when current activity completes but the mutex
+     * may engage in another activity immediately thereafter.  So the mutex is not guaranteed to be available after an
+     * await.
+     */
+    then<TResult1 = void, TResult2 = never>(
+        onfulfilled?: ((value: unknown) => TResult1 | PromiseLike<TResult1>) | undefined | null,
+        onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | undefined | null,
+    ): PromiseLike<TResult1 | TResult2> {
+        return (this.#promise || Promise.resolve()).then(onfulfilled, onrejected);
+    }
+
+    /**
+     * Enqueue additional work.
+     *
+     * If {@link task} is a function it runs when current activity completes.  If it is a promise then the mutex will
+     * not clear until {@link task} resolves.
+     */
+    run(task: PromiseLike<unknown> | (() => PromiseLike<unknown>), cancel?: () => void) {
+        if (this.#canceled) {
+            cancel?.();
+            return;
+        }
+
+        if (!this.#promise) {
+            this.#promise = this.initiateTask(task);
+        } else {
+            this.#promise = this.#promise.then(() => {
+                if (this.#canceled) {
+                    cancel?.();
+                    return;
+                }
+
+                this.#cancel = cancel;
+                return this.initiateTask(task).finally(() => {
+                    this.#cancel = undefined;
+                });
+            });
+        }
+    }
+
+    /**
+     * Cancel remaining work and perform one last task with the Mutex held.
+     */
+    terminate(cleanup?: () => PromiseLike<void>) {
+        if (this.#canceled) {
+            return;
+        }
+
+        this.#canceled = true;
+
+        if (this.#cancel) {
+            this.#cancel();
+        }
+
+        if (cleanup) {
+            if (!this.#promise) {
+                this.#promise = this.initiateTask(cleanup);
+            } else {
+                this.#promise = this.#promise.then(() => this.initiateTask(cleanup));
+            }
+        }
+    }
+
+    /**
+     * Execute a task immediately if it is a function.
+     */
+    protected async initiateTask(task: PromiseLike<unknown> | (() => PromiseLike<unknown>)) {
+        if (typeof task === "function") {
+            task = task();
+        }
+        return Promise.resolve(task).catch(cause => logger.error(`Error initializing ${this.#owner} worker:`, cause));
+    }
+}

package/src/util/NamedHandler.ts

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export type HandlerFunction = (...args: any[]) => any;
+
+export class NamedHandler<H extends Record<keyof H, HandlerFunction>> {
+    private handler: { action: keyof H; handler: H[keyof H] }[] = [];
+
+    hasHandler<K extends keyof H>(action: K) {
+        return this.handler.some(({ action: a }) => a === action);
+    }
+
+    addHandler<K extends keyof H>(action: K, handler: H[K]) {
+        this.handler.push({ action, handler });
+    }
+
+    async executeHandler<K extends keyof H>(action: K, ...args: Parameters<H[K]>) {
+        for (const { action: a, handler } of this.handler) {
+            if (a === action) {
+                return await handler(...args);
+            }
+        }
+    }
+
+    removeHandler<K extends keyof H>(action: K, handler: H[K]) {
+        this.handler = this.handler.filter(({ action: a, handler: h }) => {
+            return a !== action && h !== handler;
+        });
+    }
+}
+
+type ExtendPublicHandlerMethods<
+    ParentClass extends new (...args: any[]) => any,
+    H extends Record<keyof H, HandlerFunction>,
+> = ParentClass extends new (...args: infer TArgs) => infer T
+    ? new (...args: TArgs) => T & {
+          addCommandHandler<K extends keyof H>(action: K, handler: H[K]): void;
+          removeCommandHandler<K extends keyof H>(action: K, handler: H[K]): void;
+          _executeHandler<K extends keyof H>(action: K, ...args: Parameters<H[K]>): Promise<void>;
+      }
+    : never;
+
+export function extendPublicHandlerMethods<
+    ParentClass extends new (...args: any[]) => any,
+    H extends Record<keyof H, HandlerFunction>,
+>(parentClass: ParentClass): ExtendPublicHandlerMethods<ParentClass, H> {
+    // This is a type-level cheat
+    return parentClass as any;
+}

package/src/util/Number.ts

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export const UINT8_MAX = 0xff;
+export const UINT16_MAX = 0xffff;
+export const UINT24_MAX = 0xffffff;
+export const UINT32_MAX = 0xffffffff;
+export const UINT64_MAX = BigInt("18446744073709551615");
+
+export const INT8_MIN = -128;
+export const INT16_MIN = -32768;
+export const INT32_MIN = -2147483648;
+export const INT64_MIN = BigInt("-9223372036854775808");
+export const INT8_MAX = 127;
+export const INT16_MAX = 32767;
+export const INT32_MAX = 2147483647;
+export const INT64_MAX = BigInt("9223372036854775807");
+
+export const FLOAT32_MIN = -340282346638528859811704183484516925440.0;
+export const FLOAT32_MAX = 340282346638528859811704183484516925440.0;
+
+export function toNumber(value: bigint | number): number {
+    return typeof value === "bigint" ? Number(value) : value;
+}
+
+export function toBigInt(value: bigint | number): bigint {
+    return typeof value === "number" ? BigInt(value) : value;
+}
+
+export function minValue<T extends bigint | number>(a: T | undefined, b: T | undefined) {
+    if (a === undefined) return b;
+    if (b === undefined) return a;
+    return a < b ? a : b;
+}
+
+export function maxValue<T extends bigint | number>(a: T | undefined, b: T | undefined) {
+    if (a === undefined) return b;
+    if (b === undefined) return a;
+    return a > b ? a : b;
+}
+
+/**
+ * Convert a number or bigint to a hex string of a valid "even" hex length
+ */
+export function toHex(value: number | bigint) {
+    const hex = value.toString(16);
+    return hex.length % 2 === 0 ? hex : `0${hex}`;
+}
+
+/**
+ * Makes sure a value is within min and max. It sets the value to min or max in case it is below or above the range.
+ */
+export function cropValueRange(value: number, min: number, max: number): number {
+    return Math.min(Math.max(value, min), max);
+}
+
+/**
+ * Adds a value to another value and wraps around on the min and max values.
+ */
+export function addValueWithOverflow(value: number, add: number, min: number, max: number): number {
+    const newValue = value + add;
+    if (newValue < min) {
+        return newValue + max + 1;
+    } else if (newValue > max) {
+        return newValue - max - 1;
+    }
+    return newValue;
+}