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

package/src/util/String.ts

@@ -0,0 +1,248 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export function capitalize<T extends string>(text: T) {
+    return (text[0].toUpperCase() + text.slice(1)) as Capitalize<T>;
+}
+
+/**
+ * Converts identifiers of the form "foo-bar", "foo_bar", "foo bar", "foo*bar",
+ * "fooBar" or "FOOBar" into "fooBar" or "FooBar".
+ */
+export function camelize(name: string, upperFirst = false) {
+    const pieces = new Array<string>();
+    let pieceStart = 0,
+        sawUpper = false,
+        sawLower = false,
+        i = 0;
+
+    function addPiece(to: number) {
+        if (pieceStart < to) pieces.push(name.slice(pieceStart, to));
+        sawLower = sawUpper = false;
+    }
+
+    for (; i < name.length; i++) {
+        if (name[i] >= "A" && name[i] <= "Z") {
+            if (sawLower) {
+                addPiece(i);
+                pieceStart = i;
+            }
+            sawUpper = true;
+            continue;
+        }
+
+        if (name[i] >= "a" && name[i] <= "z") {
+            if (!sawLower) {
+                if (sawUpper) {
+                    addPiece(i - 1);
+                    pieceStart = i - 1;
+                }
+            }
+            sawLower = true;
+            continue;
+        }
+
+        addPiece(i);
+
+        if ((name[i] >= "0" && name[i] <= "9") || name[i] === "$") {
+            pieces.push(name[i]);
+        }
+
+        pieceStart = i + 1;
+        continue;
+    }
+    addPiece(i);
+
+    let didFirst = false;
+    let result = pieces
+        .map(piece => {
+            let firstChar = piece[0];
+            if (upperFirst || didFirst) {
+                firstChar = firstChar.toUpperCase();
+            } else {
+                firstChar = firstChar.toLowerCase();
+                didFirst = true;
+            }
+            return `${firstChar}${piece.slice(1).toLowerCase()}`;
+        })
+        .join("");
+
+    // Special case so "100ths" doesn't become "100Ths" which is formally correct but goofy
+    result = result.replace(/(\d+)Ths/i, "$1ths");
+
+    return result;
+}
+
+/**
+ * Converts an identifier from CamelCase to snake_case.
+ */
+export function decamelize(name: string, separator = "-") {
+    const result = Array<string>();
+    let needSeparator = false;
+    for (const c of name) {
+        if (c >= "A" && c <= "Z") {
+            if (needSeparator) {
+                result.push(separator);
+                needSeparator = false;
+            }
+            result.push(c.toLowerCase());
+        } else {
+            result.push(c);
+            needSeparator = true;
+        }
+    }
+    return result.join("");
+}
+
+/**
+ * Like JSON.stringify but targets well-formed JS and is slightly more readable.
+ */
+export function serialize(value: any) {
+    const visited = new Set();
+
+    function asValidKey(key: string) {
+        if (key.match(/[a-z_$][a-z_$0-9]*/i)) {
+            return key;
+        }
+        return JSON.stringify(key);
+    }
+
+    function serializeOne(value: any): string | undefined {
+        if (value === undefined) {
+            return;
+        }
+        if (value === null) {
+            return "null";
+        }
+        if (value[serialize.SERIALIZE]) {
+            return value[serialize.SERIALIZE]();
+        }
+        if (typeof value === "function") {
+            return;
+        }
+        if (typeof value === "bigint" || value instanceof BigInt) {
+            return value.toString();
+        }
+        if (typeof value === "number" || value instanceof Number) {
+            return value.toString();
+        }
+        if (typeof value === "string" || value instanceof String) {
+            return JSON.stringify(value);
+        }
+        if (typeof value === "boolean") {
+            return value ? "true" : "false";
+        }
+        if (ArrayBuffer.isView(value)) {
+            const dv = new DataView(value.buffer, value.byteOffset, value.byteLength);
+            const bytes = Array<string>();
+            for (let i = 0; i < dv.byteLength; i++) {
+                bytes.push(dv.getUint8(i).toString(16).padStart(2, "0"));
+            }
+            return bytes.join("");
+        }
+
+        // Composite objects after this
+        if (visited.has(value)) {
+            return;
+        }
+        if (value.toJSON) {
+            value = JSON.parse(JSON.stringify(value));
+        }
+
+        try {
+            visited.add(value);
+
+            if (Array.isArray(value)) {
+                if (value.length) {
+                    return `[ ${value.map(serializeOne).join(", ")} ]`;
+                }
+                return "[]";
+            }
+
+            const entries = Object.entries(value)
+                .map(([k, v]) => [k, serializeOne(v)])
+                .filter(([_k, v]) => v !== undefined)
+                .map(([k, v]) => `${asValidKey(k ?? "")}: ${v}`);
+
+            if (!entries.length) {
+                return "{}";
+            }
+
+            return `{ ${entries.join(", ")} }`;
+        } finally {
+            visited.delete(value);
+        }
+    }
+
+    return serializeOne(value);
+}
+
+export namespace serialize {
+    /**
+     * Custom serialization function key.
+     */
+    export const SERIALIZE = Symbol("SERIALIZE");
+
+    /**
+     * Mark a value as serialized so the serializer just uses its string
+     * representation.
+     */
+    export function asIs(value: any) {
+        if (typeof value === "string") {
+            value = new String(value);
+        }
+        if (value !== undefined && value !== null) {
+            value[SERIALIZE] = function () {
+                return this.toString();
+            };
+        }
+        return value;
+    }
+
+    /**
+     * Test whether a value serializes as a structure or a primitive.
+     */
+    export function isPrimitive(value: any) {
+        if (
+            value === undefined ||
+            value === null ||
+            value instanceof Date ||
+            ArrayBuffer.isView(value) ||
+            value[SERIALIZE]
+        ) {
+            return true;
+        }
+
+        if (Array.isArray(value)) {
+            return false;
+        }
+
+        return typeof value !== "object";
+    }
+}
+
+/**
+ * Create a human readable version of a list of items.
+ */
+export function describeList(setType: "and" | "or", ...entries: string[]) {
+    const text = Array<string>();
+
+    if (entries.length === 1) {
+        return entries[0];
+    }
+
+    for (let i = 0; i < entries.length; i++) {
+        if (i === entries.length - 1) {
+            text.push(setType, entries[i]);
+        } else if (i === entries.length - 2) {
+            text.push(entries[i]);
+        } else {
+            text.push(`${entries[i]},`);
+        }
+    }
+
+    return text.join(" ");
+}

package/src/util/Type.ts

@@ -0,0 +1,145 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export type Properties = { [key: string]: any };
+
+/** Merges two types into one. */
+export type Merge<A extends Properties, B extends Properties> = {
+    [K in keyof A as K extends keyof B ? never : K]: A[K];
+} & B;
+
+export function Merge<A extends Properties, B extends Properties>(a: A, b: B): Merge<A, B> {
+    return { ...a, ...b };
+}
+
+/** Type that represents a class constructor of a defined type or extend of it */
+export type ClassExtends<C> = { new (...args: any[]): C };
+
+/** Merge an array of objects into one.  Currently assumes unique elements */
+export type MergeAll<T> = T extends [infer O extends Properties | undefined, ...infer R]
+    ? O extends undefined
+        ? MergeAll<R>
+        : O & MergeAll<R>
+    : T extends []
+      ? {}
+      : never;
+
+export function MergeAll<T extends (Properties | undefined)[]>(...objects: readonly [...T]): MergeAll<T> {
+    return Object.assign({}, ...objects);
+}
+
+/** Pluck an item from an array of objects if present */
+export type Pluck<K, T extends readonly [...any]> = T extends [infer O, ...infer R]
+    ? K extends keyof O
+        ? [O[K], ...Pluck<K, R>]
+        : Pluck<K, R>
+    : T extends []
+      ? T
+      : never;
+
+export function Pluck<T extends Properties[], K extends keyof T[number]>(
+    key: K,
+    ...objects: readonly [...T]
+): Pluck<K, T> {
+    return objects.map(o => (o as any)[key]).filter(o => o !== undefined) as any;
+}
+
+/** Same as "a == undefined" but keeps the kids happy */
+export function isNullish(a: any) {
+    return a === undefined || a === null;
+}
+
+export type MakeMandatory<T> = Exclude<T, undefined>;
+
+/** Create a branded type */
+declare const __brand: unique symbol;
+// Don't think it should be necessary to export Brand<B> but it will cause
+// the following error under some circumstances:
+//
+//   Exported variable 'XXX' has or is using name '__brand' from external
+//   module "../src/util/Type" but cannot be named.ts(4023)
+//
+// Specifically this occurs with the reference to Cluster.id in the "complete"
+// cluster definitions
+export type Brand<B> = { [__brand]: B };
+export type Branded<T, B> = T & Brand<B>;
+
+/**
+ * Make a type immutable.
+ *
+ * TODO - might need to extend depending type (e.g. doesn't handle Maps, Sets or Promises yet)
+ *
+ * Good reference implementation here:
+ *
+ *     https://github.com/ts-essentials/ts-essentials/blob/master/lib/deep-readonly/index.ts
+ */
+export type Immutable<T> = T extends (...args: any[]) => any
+    ? T
+    : T extends number // Necessary for our "branded" IDs
+      ? T
+      : T extends bigint
+        ? T
+        : T extends object
+          ? { readonly [K in keyof T]: Immutable<T[K]> }
+          : T;
+
+export type Mutable<T> = T extends (...args: any[]) => any
+    ? T
+    : T extends number // Necessary for our "branded" IDs
+      ? T
+      : T extends bigint
+        ? T
+        : T extends object
+          ? { -readonly [K in keyof T]: Mutable<T[K]> }
+          : T;
+
+export function Mutable<T>(value: Immutable<T>): Mutable<T> {
+    return value as Mutable<T>;
+}
+
+/**
+ * Convert a union to an interface.
+ *
+ * @see {@link https://stackoverflow.com/questions/50374908}
+ */
+export type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+
+/**
+ * An identity type.
+ *
+ * You can't do:
+ *
+ *     interface Foo extends typeof Bar {}
+ *
+ * But you can do:
+ *
+ *     interface Foo extends Identity<typeof Bar> {}
+ *
+ * Without this type you'd have to do:
+ *
+ *     interface FooType = typeof Bar;
+ *     interface Foo extends FooType {};
+ *
+ * We have to do this a lot because we generate complex objects with detailed
+ * type information.  When exported, TS (as of 5.2) inlines the type of these
+ * objects in declarations which makes our declarations massive.  To avoid this
+ * we create an interface from the type then cast to the interface for export.
+ */
+export type Identity<T> = T;
+
+/**
+ * Tests whether the given variable is a real object and not an Array
+ * @param it The variable to test
+ * @returns true if it is Record<string, any>
+ */
+export function isObject(it: unknown): it is Record<string, unknown> {
+    // This is necessary because:
+    // typeof null === 'object'
+    // typeof [] === 'object'
+    // [] instanceof Object === true
+    return Object.prototype.toString.call(it) === "[object Object]"; // this code is 25% faster than below one
+    // return it && typeof it === 'object' && !(it instanceof Array);
+}

package/src/util/index.ts

@@ -0,0 +1,30 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./Array.js";
+export * from "./Bytes.js";
+export * from "./Cache.js";
+export * from "./Construction.js";
+export * from "./DataReader.js";
+export * from "./DataReadQueue.js";
+export * from "./DataWriter.js";
+export * from "./DeepCopy.js";
+export * from "./DeepEqual.js";
+export * from "./Error.js";
+export * from "./GeneratedClass.js";
+export * from "./Ip.js";
+export * from "./Lifecycle.js";
+export * from "./Mutex.js";
+export * from "./NamedHandler.js";
+export * from "./Number.js";
+export * from "./Observable.js";
+export * from "./PromiseQueue.js";
+export * from "./Promises.js";
+export * from "./Set.js";
+export * from "./Singleton.js";
+export * from "./Stream.js";
+export * from "./String.js";
+export * from "./Type.js";