@matter/general 0.14.1-alpha.0-20250607-a93593303 → 0.15.0-alpha.0-20250612-ddd428561

package/src/time/Time.ts

@@ -101,10 +101,6 @@ if (!performance || typeof performance.now !== "function" || typeof performance.
     Time.prototype.nowUs = () => Time.nowMs() * 1000; // Fallback is a bit less accurate
 }
 
-const time = new Time();
-
-Time.startup.systemMs = Time.startup.processMs = time.nowMs();
-
 export interface Timer {
     /** Name (diagnostics) */
     name: string;
@@ -221,6 +217,10 @@ DiagnosticSource.add({
 });
 
 Boot.init(() => {
+    const time = new Time();
+
+    Time.startup.systemMs = Time.startup.processMs = time.nowMs();
+
     Time.get = () => time;
 
     // Hook for testing frameworks

package/src/util/Bytes.ts

@@ -11,6 +11,25 @@ export enum Endian {
     Big,
 }
 
+/**
+ * A string tag for hex literals.
+ *
+ * Example: b$`01020304` creates a four-byte Uint8Array.
+ */
+export function b$(strings: TemplateStringsArray, ...values: unknown[]) {
+    if (strings.length === 1 && values.length === 0) {
+        return Bytes.fromHex(strings[0]);
+    }
+    const parts = Array<string>();
+    for (let i = 0; i < strings.length; i++) {
+        parts.push(strings[i]);
+        if (i < values.length) {
+            parts.push(`${values[i]}`);
+        }
+    }
+    return Bytes.fromHex(parts.join(""));
+}
+
 /**
  * Utility functions for manipulating Uint8Array.
  */

package/src/util/DataWriter.ts

@@ -5,7 +5,7 @@
  */
 
 import { Endian } from "./Bytes.js";
-import { toBigInt, toNumber } from "./Number.js";
+import { 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.
@@ -39,7 +39,7 @@ export class DataWriter<E extends Endian = Endian.Big> {
 
     writeUInt64(value: number | bigint) {
         const chunk = new Uint8Array(8);
-        new DataView(chunk.buffer, 0, 8).setBigUint64(0, toBigInt(value), this.littleEndian);
+        new DataView(chunk.buffer, 0, 8).setBigUint64(0, BigInt(value), this.littleEndian);
         this.chunks.push(chunk);
         this.length += 8;
     }
@@ -67,7 +67,7 @@ export class DataWriter<E extends Endian = Endian.Big> {
 
     writeInt64(value: number | bigint) {
         const chunk = new Uint8Array(8);
-        new DataView(chunk.buffer, 0, 8).setBigInt64(0, toBigInt(value), this.littleEndian);
+        new DataView(chunk.buffer, 0, 8).setBigInt64(0, BigInt(value), this.littleEndian);
         this.chunks.push(chunk);
         this.length += 8;
     }

package/src/util/DeepCopy.ts

@@ -26,8 +26,8 @@ export function deepCopy<T>(value: T): T {
             if (Array.isArray(value)) {
                 clone = value.map(copy);
             } else if (ArrayBuffer.isView(value)) {
-                const ViewType = value.constructor as new (buffer: ArrayBuffer | SharedArrayBuffer) => unknown;
-                clone = new ViewType(value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength));
+                const ViewType = value.constructor as unknown as { from(v: typeof value): typeof value };
+                clone = ViewType.from(value);
             } else {
                 clone = Object.fromEntries(Object.entries(value).map(([k, v]) => [k, copy(v)]));
             }

package/src/util/GeneratedClass.ts

@@ -4,48 +4,29 @@
  * 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;
+    const { base, name, beforeSuper, mixins: extraMixins } = options;
 
     // Options + any additional mixins defines complete functionality
-    const allMixins = mixins ? [...mixins, options] : [options];
+    const mixins = extraMixins ? [...extraMixins, options] : [options];
 
     // Create the constructor function
-    const type = createConstructor({
+    const klass = createConstructor({
         name: name ?? (base ? `${base.name}$` : "GeneratedClass"),
         base,
-        args,
-        mixins: allMixins,
+        beforeSuper,
+        mixins,
     });
 
-    // Install properties
-    for (const mixin of allMixins) {
-        applyMixin(type, mixin);
-    }
+    // Configure inheritance and other class aspects not handled by the constructor
+    configureClass(klass, base, mixins);
 
-    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);
-    }
+    return klass;
 }
 
 export namespace GeneratedClass {
@@ -98,107 +79,185 @@ export namespace GeneratedClass {
          * A preprocessor for arguments.  Derivatives may use this to transform arguments prior to call to super() and
          * initialize().
          */
-        args?: (...args: any[]) => any[];
+        beforeSuper?: (...args: any[]) => any[];
 
         /**
-         * Options is a default mixin but you can provide others here.
+         * Other {@link Mixin} objects in addition to this one.
          */
         mixins?: Mixin[];
     }
 }
 
-interface ConstructorOptions {
-    name: string;
-    mixins: GeneratedClass.Mixin[];
-    base?: new (...args: any[]) => any;
-    args?: (...args: any[]) => any[];
-}
+function createConstructor({ name, base, beforeSuper, mixins }: ConstructorOptions) {
+    // We generate this function to execute construction logic based on input options; invoked by the actual constructor
+    let construct: ConstructFn;
 
-function createConstructor({ name, base, args, mixins }: ConstructorOptions) {
-    // CJS Transpilation renames this symbol so bring it local to access
-    // @ts-expect-error this is used by generated code that TS knows nothing of
-    const _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;
+    // Base constructor
     if (base) {
-        ext = `extends base `;
+        construct = function (self, args) {
+            return reflectConstruct(base, args, self.constructor as new (...args: unknown[]) => unknown);
+        };
     } else {
-        ext = "";
+        construct = function (self) {
+            return self;
+        };
     }
 
-    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) {
+    // Next apply mixins in order.  We create a specialized function depending on whether the mixin has an initialize
+    // function and/or includes instance properties
+    if (mixins) {
+        for (const { initialize, instanceProperties } of mixins) {
+            const before: ConstructFn = construct;
             if (initialize) {
-                const baseInitialize = initialize;
-                initialize = function (this: any, ...args) {
-                    baseInitialize.call(this, ...args);
-                    mixinInitialize.call(this, ...args);
+                if (instanceProperties) {
+                    // Has initialize + instanceProperties
+                    construct = function (self: {}, args: unknown[]) {
+                        self = before(self, args);
+                        for (const k in instanceProperties) {
+                            (self as Record<any, any>)[k] = (instanceProperties as any)[k];
+                        }
+                        initialize.apply(self, args);
+                        return self;
+                    };
+                } else {
+                    // Has initialize
+                    construct = function (self: {}, args: unknown[]) {
+                        self = before(self, args);
+                        initialize.apply(self, args);
+                        return self;
+                    };
+                }
+            } else if (instanceProperties) {
+                // Has instanceProperties
+                construct = function (self: {}, args: unknown[]) {
+                    self = before(self, args) as Record<any, any>;
+                    for (const k in instanceProperties) {
+                        (self as Record<any, any>)[k] = (instanceProperties as any)[k];
+                    }
+                    return self;
                 };
-            } else {
-                initialize = mixinInitialize;
             }
         }
+    }
 
-        // Add instance properties
-        if (mixin.instanceProperties) {
-            if (instanceProperties) {
-                instanceProperties = {
-                    ...instanceProperties,
-                    ...mixin.instanceProperties,
-                };
-            } else {
-                instanceProperties = mixin.instanceProperties;
-            }
-        }
+    // This is the actual constructor.
+    //
+    // We install the function into a named property of a temporary object because the VM will then assign it a name.
+    // Otherwise it would be anonymous which is confusing in diagnostics and the debugger
+    //
+    // The "beforeSuper" function contains logic that would appear before the "super" call in a normal ES6 class.  We
+    // generate a different function if present to avoid an extra conditional on every instantiation
+    let klass: (...args: unknown[]) => unknown;
+    if (beforeSuper) {
+        // "beforeSuper" is present; generate a constructor that invokes it before proceeding
+        ({ [name]: klass } = {
+            [name]: function (...args: unknown[]) {
+                // This is mandated for ES6 classes; try to behave the same
+                if (!(this instanceof klass)) {
+                    throw new TypeError(`Class constructor ${klass.name} cannot be invoked without 'new'`);
+                }
+
+                // Apply pre-construction logic
+                args = beforeSuper(...args);
+
+                // Actual construction logic
+                return construct(this, args);
+            },
+        });
+    } else {
+        // Delegate to "construct" function
+        ({ [name]: klass } = {
+            [name]: function (...args: unknown[]) {
+                // See the comment above
+                if (!(this instanceof klass)) {
+                    throw new TypeError(`Class constructor ${klass.name} cannot be invoked without 'new'`);
+                }
+
+                // Actual construction logic
+                return construct(this, args);
+            },
+        });
     }
 
-    // If we need a constructor, add it
-    if (args || initialize || instanceProperties) {
-        code.push("constructor() {");
+    // Cast to constructor type
+    return klass as unknown as new (...args: unknown[]) => {};
+}
 
-        let argsName;
-        if (args) {
-            argsName = "a";
-            code.push(`const a = args(...arguments)`);
-        } else {
-            argsName = "arguments";
-        }
+function configureClass(
+    klass: new (...args: unknown[]) => unknown,
+    base: undefined | (new (...args: any[]) => any),
+    mixins: GeneratedClass.Mixin[],
+) {
+    // Configure inheritance for derived classes
+    if (base) {
+        // Enable static inheritance
+        Object.setPrototypeOf(klass, base);
 
-        if (base) {
-            code.push(`super(...${argsName})`);
-        }
+        // Enable instance inheritance
+        klass.prototype = Reflect.construct(base, []);
+    }
+
+    // Expose the correct constructor for instances via the prototype
+    Object.defineProperty(klass.prototype, "constructor", { value: klass });
 
-        if (instanceProperties) {
-            // Do not use Object.assign because we want to support accessors
-            code.push(`for (const k in instanceProperties) this[k] = instanceProperties[k]`);
+    // Install properties.  "Own instance" properties we install in the constructor but this handles static properties
+    // and those installed on the prototype
+    if (mixins) {
+        for (const { staticProperties, staticDescriptors, instanceDescriptors } of mixins) {
+            if (staticProperties) {
+                Object.assign(klass, staticProperties);
+            }
+            if (staticDescriptors) {
+                Object.defineProperties(klass, staticDescriptors);
+            }
+            if (instanceDescriptors) {
+                Object.defineProperties(klass.prototype, instanceDescriptors);
+            }
         }
+    }
+}
 
-        if (initialize) {
-            code.push(`initialize.apply(this, ${argsName})`);
+/**
+ * {@link Reflect.construct} equivalent.
+ *
+ * On modern VMs this is just {@link Reflect.construct} but we fall back to an ES5 version if necessary.
+ */
+let reflectConstruct: (
+    target: new (...args: unknown[]) => unknown,
+    args: unknown[],
+    newTarget?: new (...args: unknown[]) => unknown,
+) => {};
+
+if (typeof globalThis.Reflect?.construct === "function") {
+    reflectConstruct = Reflect.construct;
+} else {
+    reflectConstruct = (
+        target: new (...args: unknown[]) => unknown,
+        args: unknown[],
+        newTarget?: new (...args: unknown[]) => unknown,
+    ) => {
+        if (typeof newTarget === "undefined") {
+            newTarget = target;
         }
 
-        code.push("}");
-    }
+        const initialThis = Object.create(newTarget.prototype);
+        const constructorResult = target.apply(initialThis, args);
+        if (
+            (typeof constructorResult === "object" && constructorResult !== null) ||
+            typeof constructorResult === "function"
+        ) {
+            return constructorResult;
+        }
 
-    code.push("}", name);
+        return initialThis;
+    };
+}
 
-    return eval(code.join("\n")) as new (...args: any) => any;
+interface ConstructorOptions {
+    name: string;
+    base?: new (...args: any[]) => any;
+    beforeSuper?: (...args: any[]) => any[];
+    mixins: GeneratedClass.Mixin[];
 }
+
+type ConstructFn = (self: {}, args: unknown[]) => {};

package/src/util/Number.ts

@@ -26,10 +26,6 @@ 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;