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

package/src/util/DataReadQueue.ts

@@ -0,0 +1,55 @@
+/**
+ * Promise-based blocking queue.
+ *
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { MatterFlowError } from "../MatterError.js";
+import { Time, Timer } from "../time/Time.js";
+import { createPromise } from "./Promises.js";
+import { EndOfStreamError, NoResponseTimeoutError, Stream } from "./Stream.js";
+
+export class DataReadQueue<T> implements Stream<T> {
+    private readonly queue = new Array<T>();
+    private pendingRead?: { resolver: (data: T) => void; rejecter: (reason: any) => void; timeoutTimer?: Timer };
+    private closed = false;
+
+    async read(timeoutMs = 60_000): Promise<T> {
+        const { promise, resolver, rejecter } = createPromise<T>();
+        if (this.closed) throw new EndOfStreamError();
+        const data = this.queue.shift();
+        if (data !== undefined) {
+            return data;
+        }
+        if (this.pendingRead !== undefined) throw new MatterFlowError("Only one pending read is supported");
+        this.pendingRead = {
+            resolver,
+            rejecter,
+            timeoutTimer: Time.getTimer("Queue timeout", timeoutMs, () =>
+                rejecter(new NoResponseTimeoutError()),
+            ).start(),
+        };
+        return promise;
+    }
+
+    async write(data: T) {
+        if (this.closed) throw new EndOfStreamError();
+        if (this.pendingRead !== undefined) {
+            this.pendingRead.timeoutTimer?.stop();
+            this.pendingRead.resolver(data);
+            this.pendingRead = undefined;
+            return;
+        }
+        this.queue.push(data);
+    }
+
+    close() {
+        if (this.closed) return;
+        this.closed = true;
+        if (this.pendingRead === undefined) return;
+        this.pendingRead.timeoutTimer?.stop();
+        this.pendingRead.rejecter(new EndOfStreamError());
+    }
+}

package/src/util/DataReader.ts

@@ -0,0 +1,100 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes, Endian } from "./Bytes.js";
+
+/** Reader that auto-increments its offset after each read. */
+export class DataReader<E extends Endian> {
+    private readonly littleEndian: boolean;
+    private readonly dataView: DataView;
+    private offset = 0;
+
+    constructor(
+        private readonly buffer: Uint8Array,
+        endian: E,
+    ) {
+        this.dataView = Bytes.dataViewOf(buffer);
+        this.littleEndian = endian === Endian.Little;
+    }
+
+    readUInt8() {
+        return this.dataView.getUint8(this.getOffsetAndAdvance(1));
+    }
+
+    readUInt16() {
+        return this.dataView.getUint16(this.getOffsetAndAdvance(2), this.littleEndian);
+    }
+
+    readUInt32() {
+        return this.dataView.getUint32(this.getOffsetAndAdvance(4), this.littleEndian);
+    }
+
+    readUInt64() {
+        return this.dataView.getBigUint64(this.getOffsetAndAdvance(8), this.littleEndian);
+    }
+
+    readInt8() {
+        return this.dataView.getInt8(this.getOffsetAndAdvance(1));
+    }
+
+    readInt16() {
+        return this.dataView.getInt16(this.getOffsetAndAdvance(2), this.littleEndian);
+    }
+
+    readInt32() {
+        return this.dataView.getInt32(this.getOffsetAndAdvance(4), this.littleEndian);
+    }
+
+    readInt64() {
+        return this.dataView.getBigInt64(this.getOffsetAndAdvance(8), this.littleEndian);
+    }
+
+    readFloat() {
+        return this.dataView.getFloat32(this.getOffsetAndAdvance(4), this.littleEndian);
+    }
+
+    readDouble() {
+        return this.dataView.getFloat64(this.getOffsetAndAdvance(8), this.littleEndian);
+    }
+
+    readUtf8String(length: number) {
+        const offset = this.getOffsetAndAdvance(length);
+        return new TextDecoder().decode(this.buffer.subarray(offset, offset + length));
+    }
+
+    readByteArray(length: number) {
+        const offset = this.getOffsetAndAdvance(length);
+        return this.buffer.subarray(offset, offset + length);
+    }
+
+    getRemainingBytesCount() {
+        return this.dataView.byteLength - this.offset;
+    }
+
+    getRemainingBytes() {
+        return this.buffer.subarray(this.offset);
+    }
+
+    getLength() {
+        return this.dataView.byteLength;
+    }
+
+    setOffset(offset: number) {
+        if (offset > this.dataView.byteLength) {
+            throw new Error(`Offset ${offset} is out of bounds.`);
+        }
+        this.offset = offset;
+    }
+
+    private getOffsetAndAdvance(size: number) {
+        const result = this.offset;
+        this.offset += size;
+        if (this.offset > this.dataView.byteLength) {
+            this.offset = this.dataView.byteLength;
+        }
+        return result;
+    }
+}

package/src/util/DataWriter.ts

@@ -0,0 +1,109 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Endian } from "./Bytes.js";
+import { toBigInt, toNumber } from "./Number.js";
+
+/** Writer that auto-increments its offset after each write. */
+// TODO: some research should be done to make sure this is most performant implementation.
+export class DataWriter<E extends Endian> {
+    private readonly littleEndian: boolean;
+    private length = 0;
+    private readonly chunks = new Array<Uint8Array>();
+
+    constructor(endian: E) {
+        this.littleEndian = endian === Endian.Little;
+    }
+
+    writeUInt8(value: number | bigint) {
+        this.chunks.push(new Uint8Array([toNumber(value)]));
+        this.length += 1;
+    }
+
+    writeUInt16(value: number | bigint) {
+        const chunk = new Uint8Array(2);
+        new DataView(chunk.buffer, 0, 2).setUint16(0, toNumber(value), this.littleEndian);
+        this.chunks.push(chunk);
+        this.length += 2;
+    }
+
+    writeUInt32(value: number | bigint) {
+        const chunk = new Uint8Array(4);
+        new DataView(chunk.buffer, 0, 4).setUint32(0, toNumber(value), this.littleEndian);
+        this.chunks.push(chunk);
+        this.length += 4;
+    }
+
+    writeUInt64(value: number | bigint) {
+        const chunk = new Uint8Array(8);
+        new DataView(chunk.buffer, 0, 8).setBigUint64(0, toBigInt(value), this.littleEndian);
+        this.chunks.push(chunk);
+        this.length += 8;
+    }
+
+    writeInt8(value: number | bigint) {
+        const chunk = new Uint8Array(1);
+        new DataView(chunk.buffer, 0, 1).setInt8(0, toNumber(value));
+        this.chunks.push(chunk);
+        this.length += 1;
+    }
+
+    writeInt16(value: number | bigint) {
+        const chunk = new Uint8Array(2);
+        new DataView(chunk.buffer, 0, 2).setInt16(0, toNumber(value), this.littleEndian);
+        this.chunks.push(chunk);
+        this.length += 2;
+    }
+
+    writeInt32(value: number | bigint) {
+        const chunk = new Uint8Array(4);
+        new DataView(chunk.buffer, 0, 4).setInt32(0, toNumber(value), this.littleEndian);
+        this.chunks.push(chunk);
+        this.length += 4;
+    }
+
+    writeInt64(value: number | bigint) {
+        const chunk = new Uint8Array(8);
+        new DataView(chunk.buffer, 0, 8).setBigInt64(0, toBigInt(value), this.littleEndian);
+        this.chunks.push(chunk);
+        this.length += 8;
+    }
+
+    writeFloat(value: number) {
+        const chunk = new Uint8Array(4);
+        new DataView(chunk.buffer, 0, 4).setFloat32(0, value, this.littleEndian);
+        this.chunks.push(chunk);
+        this.length += 4;
+    }
+
+    writeDouble(value: number) {
+        const chunk = new Uint8Array(8);
+        new DataView(chunk.buffer, 0, 8).setFloat64(0, value, this.littleEndian);
+        this.chunks.push(chunk);
+        this.length += 8;
+    }
+
+    writeByteArray(value: Uint8Array) {
+        this.chunks.push(value);
+        this.length += value.byteLength;
+    }
+
+    toByteArray() {
+        if (this.chunks.length === 0) return new Uint8Array(0);
+        if (this.chunks.length === 1) return this.chunks[0];
+
+        const result = new Uint8Array(this.length);
+        let offset = 0;
+        this.chunks.forEach(chunk => {
+            result.set(chunk, offset);
+            offset += chunk.byteLength;
+        });
+        this.chunks.length = 0;
+        this.chunks.push(result);
+
+        return result;
+    }
+}

package/src/util/DeepCopy.ts

@@ -0,0 +1,47 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Create a deep copy of a data structure.
+ *
+ * Only copies enumerable properties.  Handles typed arrays and graphs.
+ */
+export function deepCopy<T>(value: T): T {
+    let clones: undefined | Map<unknown, unknown>;
+
+    function copy(value: unknown) {
+        if (typeof value === "object") {
+            if (value === null) {
+                return null;
+            }
+
+            let clone = clones?.get(value);
+            if (clone) {
+                return clone;
+            }
+
+            if (Array.isArray(value)) {
+                clone = value.map(copy);
+            } else if (ArrayBuffer.isView(value)) {
+                const ViewType = value.constructor as new (buffer: ArrayBuffer) => unknown;
+                clone = new ViewType(value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength));
+            } else {
+                clone = Object.fromEntries(Object.entries(value).map(([k, v]) => [k, copy(v)]));
+            }
+
+            if (!clones) {
+                clones = new Map();
+            }
+            clones.set(value, clone);
+
+            return clone;
+        }
+
+        return value;
+    }
+
+    return copy(value) as T;
+}

package/src/util/DeepEqual.ts

@@ -0,0 +1,49 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// TODO - implement more efficient specialization for Array and ArrayBuffer
+// TODO - currently will hang on self-referential data structures
+export function isDeepEqual(a: any, b: any) {
+    if (
+        a === null ||
+        a === undefined ||
+        b === null ||
+        b === undefined ||
+        typeof a !== typeof b ||
+        (typeof a !== "object" && typeof b !== "object")
+    ) {
+        return a === b;
+    }
+    // Create arrays of property names
+    const aProps = Object.getOwnPropertyNames(a);
+    const bProps = Object.getOwnPropertyNames(b);
+
+    // If number of properties is different, objects are not equivalent
+    if (aProps.length !== bProps.length) {
+        return false;
+    }
+
+    for (let i = 0; i < aProps.length; i++) {
+        const propName = aProps[i];
+
+        if (typeof a[propName] !== typeof b[propName]) {
+            return false;
+        }
+        if (typeof a[propName] === "object") {
+            if (!isDeepEqual(a[propName], b[propName])) {
+                return false;
+            }
+        } else {
+            // If values of same property are not equal, objects are not equivalent
+            if (a[propName] !== b[propName]) {
+                return false;
+            }
+        }
+    }
+
+    // If we made it this far, objects are considered equal
+    return true;
+}

package/src/util/Error.ts

@@ -0,0 +1,32 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import type { Constructable } from "./Construction.js";
+
+/**
+ * Ensure that a cause is an error object.
+ *
+ * We consider anything with a "message" property to be a reasonable error object.
+ */
+export function errorOf(cause: unknown): Error {
+    // If the cause is an Constructable, use its construction error
+    if ((cause as Constructable)?.construction?.error) {
+        cause = (cause as Constructable)?.construction.error;
+    }
+
+    // If the cause is indeterminate we fall back to the helpful "Unknown error"
+    if (cause === undefined || cause === null) {
+        return Error("Unknown error");
+    }
+
+    // If the cause has a "message" field, treat as an Error
+    if ((cause as Error).message !== undefined) {
+        return cause as Error;
+    }
+
+    // Otherwise create a new error using the original cause as the message
+    return new Error(cause.toString());
+}

package/src/util/GeneratedClass.ts

@@ -0,0 +1,204 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { InternalError } from "../MatterError.js";
+
+/**
+ * Helper function for class generation.
+ *
+ * This factory does not offer TypeScript types for the resulting class.  You must cast separately.
+ */
+export function GeneratedClass(options: GeneratedClass.Options) {
+    const { base, name, args, mixins } = options;
+
+    // Options + any additional mixins defines complete functionality
+    const allMixins = mixins ? [...mixins, options] : [options];
+
+    // Create the constructor function
+    const type = createConstructor({
+        name: name ?? (base ? `${base.name}$` : "GeneratedClass"),
+        base,
+        args,
+        mixins: allMixins,
+    });
+
+    // Install properties
+    for (const mixin of allMixins) {
+        applyMixin(type, mixin);
+    }
+
+    return type;
+}
+
+function applyMixin(
+    constructor: new (...args: any) => any,
+    { staticProperties, staticDescriptors, instanceDescriptors }: GeneratedClass.Mixin,
+) {
+    if (staticProperties) {
+        Object.assign(constructor, staticProperties);
+    }
+    if (staticDescriptors) {
+        Object.defineProperties(constructor, staticDescriptors);
+    }
+    if (instanceDescriptors) {
+        Object.defineProperties(constructor.prototype, instanceDescriptors);
+    }
+}
+
+export namespace GeneratedClass {
+    /**
+     * These fields control class behavior.
+     */
+    export interface Mixin {
+        /**
+         * A function that performs initialization after instantiation.  "this" will be the object and arguments are the
+         * arguments to the constructor.
+         */
+        initialize?: (...args: any[]) => void;
+
+        /**
+         * Instance properties.
+         */
+        instanceProperties?: object;
+
+        /**
+         * Instance properties defined using descriptors.
+         */
+        instanceDescriptors?: PropertyDescriptorMap;
+
+        /**
+         * Static properties.
+         */
+        staticProperties?: object;
+
+        /**
+         * Static properties defined using descriptors.
+         */
+        staticDescriptors?: PropertyDescriptorMap;
+    }
+
+    /**
+     * Input to {@link GeneratedClass}.
+     */
+    export interface Options extends Mixin {
+        /**
+         * The name of the class.
+         */
+        name?: string;
+
+        /**
+         * The base class, if any.
+         */
+        base?: new (...args: any) => any;
+
+        /**
+         * A preprocessor for arguments.  Derivatives may use this to transform arguments prior to call to super() and
+         * initialize().
+         */
+        args?: (...args: any[]) => any[];
+
+        /**
+         * Options is a default mixin but you can provide others here.
+         */
+        mixins?: Mixin[];
+    }
+}
+
+interface ConstructorOptions {
+    name: string;
+    mixins: GeneratedClass.Mixin[];
+    base?: new (...args: any[]) => any;
+    args?: (...args: any[]) => any[];
+}
+
+function createConstructor({ name, base, args, mixins }: ConstructorOptions) {
+    // CJS Transpilation renames this symbol so bring it local to access
+    const _InternalError = InternalError;
+    _InternalError;
+
+    // Have to use eval if we don't want every class to be called "GeneratedClass" in the debugger but we can ensure
+    // this won't be abused.
+    //
+    // "name" is the only input to this function that appears textually in the eval.  We limit it to letters, numbers,
+    // "$" and "_".
+    if (!name.match(/^(?:\p{L}|[0-9$_])+$/u)) {
+        throw new InternalError("Refusing to generate class with untrustworthy name");
+    }
+
+    let ext;
+    if (base) {
+        ext = `extends base `;
+    } else {
+        ext = "";
+    }
+
+    const code = [`class ${name} ${ext}{`];
+
+    // Consolidate mixins to a single initialize and instanceProperties
+    let initialize: undefined | GeneratedClass.Options["initialize"];
+    let instanceProperties: undefined | GeneratedClass.Options["instanceProperties"];
+
+    for (const mixin of mixins) {
+        const mixinInitialize = mixin.initialize;
+
+        // Add initializer
+        if (mixinInitialize) {
+            if (initialize) {
+                const baseInitialize = initialize;
+                initialize = function (this: any, ...args) {
+                    baseInitialize.call(this, ...args);
+                    mixinInitialize.call(this, ...args);
+                };
+            } else {
+                initialize = mixinInitialize;
+            }
+        }
+
+        // Add instance properties
+        if (mixin.instanceProperties) {
+            if (instanceProperties) {
+                instanceProperties = {
+                    ...instanceProperties,
+                    ...mixin.instanceProperties,
+                };
+            } else {
+                instanceProperties = mixin.instanceProperties;
+            }
+        }
+    }
+
+    // If we need a constructor, add it
+    if (args || initialize || instanceProperties) {
+        code.push("constructor() {");
+
+        let argsName;
+        if (args) {
+            argsName = "a";
+            code.push(`const a = args(...arguments)`);
+        } else {
+            argsName = "arguments";
+        }
+
+        if (base) {
+            code.push(`super(...${argsName})`);
+        }
+
+        if (instanceProperties) {
+            // Do not use Object.assign because we want to support accessors
+            code.push(`for (const k in instanceProperties) this[k] = instanceProperties[k]`);
+        }
+
+        if (initialize) {
+            code.push(`initialize.apply(this, ${argsName})`);
+        }
+
+        code.push("}");
+    }
+
+    code.push("}", name);
+
+    return eval(code.join("\n")) as new (...args: any) => any;
+}

package/src/util/Introspection.ts

@@ -0,0 +1,93 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Utilities for object introspection.
+ */
+export namespace Introspection {
+    /**
+     * Obtain a {@link PropertyDescriptor} from any level in {@link subject}'s
+     * prototype chain.
+     */
+    export function propertyDescriptorOf(subject: object, name: string): PropertyDescriptor | undefined {
+        const descriptor = Reflect.getOwnPropertyDescriptor(subject, name);
+        if (descriptor) {
+            return descriptor;
+        }
+        const prototype = Reflect.getPrototypeOf(subject);
+        if (prototype !== null) {
+            return Introspection.propertyDescriptorOf(prototype, name);
+        }
+    }
+
+    /**
+     * Obtain {@link PropertyDescriptor}s from properties in any level of
+     * {@link subject}'s prototype chain.
+     */
+    export function propertyDescriptorsOf(subject: object) {
+        const descriptors = {} as Record<string, PropertyDescriptor>;
+
+        function addDescriptors(subject: object) {
+            const localDescriptors = Object.getOwnPropertyDescriptors(subject);
+
+            for (const name in localDescriptors) {
+                if (descriptors[name] === undefined) {
+                    descriptors[name] = localDescriptors[name];
+                }
+            }
+
+            const prototype = Reflect.getPrototypeOf(subject);
+            if (prototype !== null) {
+                addDescriptors(prototype);
+            }
+        }
+
+        addDescriptors(subject);
+
+        return descriptors;
+    }
+
+    /**
+     * Determine whether a single property of {@link subject} is readable
+     * and/or writable.
+     */
+    export function propertyAccessibilityOf(subject: object, name: string) {
+        const pd = propertyDescriptorOf(subject, name);
+        if (pd) {
+            return propertyDescriptorToAccessibility(pd);
+        }
+        return { readable: true, writable: true };
+    }
+
+    /**
+     * Obtain properties from {@link subject} and whether they're readable
+     * and/or writable.
+     */
+    export function objectAccessibilityOf(subject: object) {
+        const accessibilty = {} as ObjectAccessibilty;
+
+        const propertyDescriptors = Introspection.propertyDescriptorsOf(subject);
+        for (const name in propertyDescriptors) {
+            accessibilty[name] = propertyDescriptorToAccessibility(propertyDescriptors[name]);
+        }
+
+        return accessibilty;
+    }
+
+    export function propertyDescriptorToAccessibility(pd: PropertyDescriptor): PropertyAccessibility {
+        return {
+            readable: !!(pd.set && !pd.get),
+            writable: !!(pd.set || pd.writable),
+        };
+    }
+
+    export interface PropertyAccessibility {
+        readable: boolean;
+        writable: boolean;
+    }
+
+    export interface ObjectAccessibilty extends Record<string, PropertyAccessibility> {}
+}