@matter/general 0.16.0-alpha.0-20251203-aaf94bca8 → 0.16.0-alpha.0-20251207-37e501b18

package/src/util/Observable.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { Diagnostic } from "#log/Diagnostic.js";
 import { Duration } from "#time/Duration.js";
 import { Time, Timer } from "#time/Time.js";
 import { Instant, Millis, Seconds } from "#time/TimeUnit.js";
@@ -30,10 +31,12 @@ const logger = Logger.get("Observable");
  * @param payload a list of arguments to be emitted
  */
 export interface Observer<T extends any[] = any[], R = void> {
-    (...payload: T): MaybePromise<R | undefined>;
+    (...payload: T): R | undefined;
     [observant]?: boolean;
 }
 
+export interface AsyncObserver<T extends any[] = any[], R = void> extends Observer<T, MaybePromise<R>> {}
+
 /**
  * A discrete event that may be monitored via callback.  Could call it "event" but that could be confused with Matter
  * cluster events and/or DOM events.
@@ -113,6 +116,11 @@ export interface Observable<T extends any[] = any[], R = void> extends AsyncIter
         onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null,
     ): Promise<TResult1 | TResult2>;
 
+    /**
+     * A diagnostic aid; set this to produce detailed logs of emission.
+     */
+    traceAs: string | undefined;
+
     /**
      * Observable supports standard "for await (const value of observable").
      *
@@ -193,6 +201,7 @@ export class BasicObservable<T extends any[] = any[], R = void> implements Obser
     #handlePromise!: ObserverPromiseHandler;
     #observers?: Set<Observer<T, R>>;
     #once?: Set<Observer<T, R>>;
+    #instrumentAs?: string;
 
     #joinIteration?: () => Promise<Next<T>>;
     #removeIterator?: () => void;
@@ -207,6 +216,10 @@ export class BasicObservable<T extends any[] = any[], R = void> implements Obser
         }
     }
 
+    set traceAs(name: string | undefined) {
+        this.#instrumentAs = name;
+    }
+
     [Symbol.dispose]() {
         this.#observers = this.#once = undefined;
 
@@ -227,7 +240,8 @@ export class BasicObservable<T extends any[] = any[], R = void> implements Obser
             // Promises handled by emitter
             this.#handlePromise = promise => promise;
         } else {
-            // We log promise errors but do not otherwise track
+            // We log promise errors but do not otherwise track.  This generally should not be invoked because types
+            // should align with this.#isAsync, so observers should not be returning promises
             this.#handlePromise = (promise, observer) => {
                 promise.catch(error => {
                     let identity: string;
@@ -290,55 +304,103 @@ export class BasicObservable<T extends any[] = any[], R = void> implements Obser
         }
 
         // Iterate over a clone of observers so we do not trigger new observers added during observation
-        const iterator = [...this.#observers][Symbol.iterator]();
+        const observers = [...this.#observers];
+
+        let nextObserver = 0;
+
+        const next = () => {
+            const observer = observers[nextObserver];
+
+            if (this.#once?.has(observer)) {
+                this.#once.delete(observer);
+                this.#observers?.delete(observer);
+            }
 
-        const emitNext = (previousEmitResult?: R): R | undefined => {
-            if (previousEmitResult !== undefined) {
-                return previousEmitResult;
+            if (this.#instrumentAs) {
+                logger.debug(
+                    Diagnostic.strong(this.#instrumentAs),
+                    `invoking #${nextObserver++}`,
+                    Diagnostic.strong(observer.name || "(anon)"),
+                );
             }
 
-            for (let iteration = iterator.next(); !iteration.done; iteration = iterator.next()) {
-                let result;
+            return observer;
+        };
 
-                const observer = iteration.value;
+        let log: undefined | ((observer: Observer<any, any>) => void), done: undefined | (() => void);
+        if (this.#instrumentAs) {
+            logger.debug(Diagnostic.strong(this.#instrumentAs), "emitting");
 
-                try {
-                    result = observer(...payload);
-                } catch (e) {
-                    this.#handleError(asError(e), observer);
-                }
+            log = (observer: Observer<any, any>) => {
+                logger.debug(
+                    Diagnostic.strong(this.#instrumentAs),
+                    `invoking #${nextObserver++}`,
+                    Diagnostic.strong(observer.name || "(anon)"),
+                );
+            };
 
-                if (this.#once?.has(observer)) {
-                    this.#once.delete(observer);
-                    this.#observers?.delete(observer);
-                }
+            done = () => {
+                logger.debug(Diagnostic.strong(this.#instrumentAs), "emission complete");
+            };
+        }
 
-                if (result === undefined) {
-                    continue;
-                }
+        // Initially emit using a synchronous loop.  When we hit the first promies we convert to an async function
+        for (; nextObserver < observers.length; nextObserver++) {
+            let result: ReturnType<Observer<T, R>>;
+
+            let observer = next();
 
-                if (MaybePromise.is(result)) {
-                    result = this.#handlePromise(Promise.resolve(result), observer as Observer) as R | undefined;
+            try {
+                log?.(observer);
+                result = observer(...payload);
+            } catch (e) {
+                this.#handleError(asError(e), observer);
+            }
+
+            if (result === undefined) {
+                continue;
+            }
 
-                    if (MaybePromise.is(result)) {
-                        return result.then(result => {
-                            if (result === undefined) {
-                                return emitNext();
+            // If observer was async (which we can only conclude after invocation), switch to async emission
+            if (MaybePromise.is(result)) {
+                const emitAsync = async () => {
+                    while (true) {
+                        if (MaybePromise.is(result)) {
+                            try {
+                                result = await result;
+                            } catch (e) {
+                                this.#handleError(asError(e), observer);
                             }
+                        }
+
+                        if (result !== undefined) {
                             return result;
-                        }) as R;
-                    }
+                        }
 
-                    if (result === undefined) {
-                        continue;
+                        nextObserver++;
+                        if (nextObserver >= observers.length) {
+                            break;
+                        }
+
+                        observer = next();
+
+                        try {
+                            result = observer(...payload);
+                        } catch (e) {
+                            this.#handleError(asError(e), observer);
+                        }
                     }
-                }
 
-                return result;
+                    done?.();
+                };
+
+                return emitAsync() as R | undefined;
             }
-        };
 
-        return emitNext();
+            done?.();
+
+            return result;
+        }
     }
 
     on(observer: Observer<T, R>) {
@@ -592,7 +654,7 @@ function constructAsyncObservableValue(value?: unknown, handleError?: ObserverEr
  */
 export class EventEmitter {
     // True private screws up TS types
-    private events?: Record<string, Observable | undefined>;
+    private events?: Record<string, AsyncObservable | undefined>;
 
     emit<This, N extends EventEmitter.NamesOf<This>>(this: This, name: N, ...payload: EventEmitter.PayloadOf<This, N>) {
         event(this, name).emit(...payload);
@@ -614,7 +676,7 @@ export class EventEmitter {
         event(this, name).off(handler as any);
     }
 
-    addEvent(name: string, event?: Observable) {
+    addEvent(name: string, event?: AsyncObservable) {
         if (!this.events) {
             this.events = {};
         }
@@ -735,6 +797,18 @@ export class ObserverGroup {
         this.#defaultTarget = target;
     }
 
+    on<T extends any[], R>(
+        observable: Observable<T, R>,
+        observer: Observer<ObserverGroup.VarArgs<NoInfer<T>>, NoInfer<R>>,
+        target?: {},
+    ): void;
+
+    on<T extends any[], R>(
+        observable: AsyncObservable<T, R>,
+        observer: AsyncObserver<ObserverGroup.VarArgs<NoInfer<T>>, NoInfer<R>>,
+        target?: {},
+    ): void;
+
     /**
      * Add an observer.
      *
@@ -820,20 +894,23 @@ export namespace ObserverGroup {
 /**
  * An {@link Observable} that emits an algorithmically-reduced number of events.
  */
-export class QuietObservable<T extends any[] = any[]> extends BasicObservable<T> implements QuietObservable.State<T> {
+export class QuietObservable<T extends any[] = any[], R extends MaybePromise<void> = void>
+    extends BasicObservable<T, R>
+    implements QuietObservable.State<T, R>
+{
     #emitAutomatically = QuietObservable.defaults.emitAutomatically;
     #suppressionEnabled = QuietObservable.defaults.suppressionEnabled;
     #minimumEmitInterval = QuietObservable.defaults.minimumEmitInterval;
     #shouldEmit?: QuietObservable.EmitPredicate<T>;
-    #source?: Observable<T>;
-    #sink?: Observable<T>;
-    #sourceObserver?: Observer<T>;
-    #sinkObserver?: Observer<T>;
+    #source?: Observable<T, R>;
+    #sink?: Observable<T, R>;
+    #sourceObserver?: Observer<T, R>;
+    #sinkObserver?: Observer<T, R>;
     #deferredPayload?: T;
     #lastEmitAt?: number;
     #emitTimer?: Timer;
 
-    constructor(config?: QuietObservable.Configuration<T>) {
+    constructor(config?: QuietObservable.Configuration<T, R>) {
         super();
         if (config) {
             this.config = config;
@@ -844,7 +921,7 @@ export class QuietObservable<T extends any[] = any[]> extends BasicObservable<T>
         return this;
     }
 
-    set config(config: QuietObservable.Configuration<T>) {
+    set config(config: QuietObservable.Configuration<T, R>) {
         const { suppressionEnabled, minimumEmitInterval, emitAutomatically } = config;
         if (emitAutomatically !== undefined) {
             this.emitAutomatically = emitAutomatically;
@@ -917,7 +994,7 @@ export class QuietObservable<T extends any[] = any[]> extends BasicObservable<T>
         return this.#source;
     }
 
-    set source(source: Observable<T> | undefined) {
+    set source(source: Observable<T, R> | undefined) {
         if (this.#source === source) {
             return;
         }
@@ -936,7 +1013,7 @@ export class QuietObservable<T extends any[] = any[]> extends BasicObservable<T>
         return this.#sink;
     }
 
-    set sink(sink: Observable<T> | undefined) {
+    set sink(sink: Observable<T, R> | undefined) {
         if (this.#sink === sink) {
             return;
         }
@@ -967,11 +1044,11 @@ export class QuietObservable<T extends any[] = any[]> extends BasicObservable<T>
         return super.isObserved || this.#sink?.isObserved || false;
     }
 
-    override isObservedBy(observer: Observer<T>): boolean {
+    override isObservedBy(observer: Observer<T, R>): boolean {
         return this.#sink?.isObservedBy(observer) || this.isObservedBy(observer) || false;
     }
 
-    override emit(...payload: T) {
+    override emit(...payload: T): R | undefined {
         const shouldEmit = this.#shouldEmit?.(...payload);
         if (shouldEmit === false) {
             return;
@@ -1022,7 +1099,7 @@ export class QuietObservable<T extends any[] = any[]> extends BasicObservable<T>
         this.#deferredPayload = undefined;
         this.#lastEmitAt = now ?? Time.nowMs;
         this.#stop();
-        super.emit(...payload);
+        return super.emit(...payload);
     }
 
     #start(now?: number) {
@@ -1054,7 +1131,7 @@ export class QuietObservable<T extends any[] = any[]> extends BasicObservable<T>
 }
 
 export namespace QuietObservable {
-    export interface State<T extends any[] = any[]> {
+    export interface State<T extends any[] = any[], R extends MaybePromise<void> = void> {
         /**
          * If true this observable will emit within the suppression constraints.  If false it will only emit after calls
          * to {@link emitSoon} or {@link emitNow}.
@@ -1074,12 +1151,12 @@ export namespace QuietObservable {
         /**
          * An input observable this observable will automatically observe to produce events.
          */
-        source?: Observable<T>;
+        source?: Observable<T, R>;
 
         /**
          * An output observable this observable will automatically emit to whenever it emits.
          */
-        sink?: Observable<T>;
+        sink?: Observable<T, R>;
 
         /**
          * A predicate that determine whether a payload should emit.
@@ -1120,7 +1197,9 @@ export namespace QuietObservable {
         (...payload: T): EmitDirective;
     }
 
-    export interface Configuration<T extends any[] = any[]> extends Partial<State<T>> {}
+    export interface Configuration<T extends any[] = any[], R extends MaybePromise<void> = void> extends Partial<
+        State<T, R>
+    > {}
 
     export const defaults: State = {
         emitAutomatically: true,

package/src/util/String.ts

@@ -8,177 +8,6 @@ import { ImplementationError } from "#MatterError.js";
 import { Bytes } from "./Bytes.js";
 import { isObject } from "./Type.js";
 
-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: unknown) {
-    const visited = new Set();
-
-    function asValidKey(key: string) {
-        if (key.match(/[a-z_$][\w$]*/i)) {
-            return key;
-        }
-        return JSON.stringify(key);
-    }
-
-    function serializeOne(value: unknown): string | undefined {
-        if (value === undefined) {
-            return;
-        }
-        if (value === null) {
-            return "null";
-        }
-        if ((value as { [serialize.SERIALIZE](): string })[serialize.SERIALIZE]) {
-            return (value as { [serialize.SERIALIZE](): string })[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 (Bytes.isBytes(value)) {
-            return Bytes.toHex(value);
-        }
-
-        // Composite objects after this
-        if (visited.has(value)) {
-            return;
-        }
-        if ((value as { toJSON(): string }).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 as {})
-                .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);
-}
-
 /**
  * Like {@link JSON.stringify} but with support for additional standard objects.
  */
@@ -198,50 +27,6 @@ export function asJson(value: unknown, space?: number) {
     );
 }
 
-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.
  */
@@ -326,3 +111,17 @@ export function serializeToJs(value: unknown) {
     parts.push("}");
     return parts.join("");
 }
+
+export namespace hex {
+    export function fixed(value: number | bigint, width: number) {
+        return value.toString(16).padStart(width, "0");
+    }
+
+    export function byte(value: number | bigint) {
+        return fixed(value, 2);
+    }
+
+    export function word(value: number | bigint) {
+        return fixed(value, 4);
+    }
+}

package/src/util/identifier-case.ts

@@ -0,0 +1,101 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Make first character uppercase.
+ */
+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("");
+}