@matter/general 0.14.0 → 0.14.1-alpha.0-20250606-a9bcd03f9

package/src/util/Set.ts

@@ -4,6 +4,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import { ImplementationError } from "#MatterError.js";
 import { Observable } from "./Observable.js";
 
 /**
@@ -36,9 +37,20 @@ export interface ObservableSet<T> {
 
 /**
  * An interface for index set lookup.
+ *
+ * Note that this interface only supports a single item for each key.  If multiple items associate with a key only the
+ * first is returned.
  */
 export interface IndexedSet<T> {
+    /**
+     * Retrieve an item with the named {@link field} set to {@link value}.
+     */
     get<F extends keyof T>(field: F, value: T[F]): T | undefined;
+
+    /**
+     * Obtain a {@link Map} of values in {@link field} to the associated item in the set.
+     */
+    mapOf<F extends keyof T>(field: F): Map<T[F], T>;
 }
 
 /**
@@ -51,7 +63,10 @@ export class BasicSet<T, AddT = T> implements ImmutableSet<T>, MutableSet<T, Add
     #added?: Observable<[T]>;
     #deleted?: Observable<[T]>;
     #indices?: {
-        [field in keyof T]?: Map<any, T>;
+        [field in keyof T]?: Map<T[field], T>;
+    };
+    #maps?: {
+        [field in keyof T]?: Map<T[field], T>;
     };
 
     constructor(...initialItems: AddT[]) {
@@ -123,6 +138,10 @@ export class BasicSet<T, AddT = T> implements ImmutableSet<T>, MutableSet<T, Add
     }
 
     get<F extends keyof T>(field: F, value: T[F]) {
+        return this.#indexOf(field).get(value);
+    }
+
+    #indexOf<F extends keyof T>(field: F) {
         if (!this.#indices) {
             this.#indices = {};
         }
@@ -138,10 +157,39 @@ export class BasicSet<T, AddT = T> implements ImmutableSet<T>, MutableSet<T, Add
             }
             this.#indices[field] = index;
         }
-        return index?.get(value);
+        return index!; // Need "!" due to (apparent) TS bug
     }
 
-    delete(item: T) {
+    /**
+     * Obtain key/value map using specific field as key.
+     *
+     * Note we use {@link This} to constrain usage to sets where {@link T} === {@link AddT} as required by {@link Map}.
+     */
+    mapOf<This extends BasicSet<T, T>, F extends keyof T>(this: This, field: F): Map<T[F], T> {
+        if (!this.#maps) {
+            this.#maps = {};
+        }
+        let map = this.#maps[field];
+        if (map === undefined) {
+            map = new MapOfIndexedSet(this, field, this.#indexOf(field));
+            this.#maps[field] = map;
+        }
+        return map;
+    }
+
+    delete(item: T): boolean;
+    delete<F extends keyof T>(field: keyof T, value: T[F]): boolean;
+    delete<F extends keyof T>(itemOrField: T | F, value?: T[F]): boolean {
+        let item: T | undefined;
+        if (value === undefined) {
+            item = itemOrField as T;
+        } else {
+            item = this.get(itemOrField as F, value);
+            if (item === undefined) {
+                return false; // Item not found
+            }
+        }
+
         if (!this.#entries.delete(item)) {
             return false;
         }
@@ -187,3 +235,121 @@ export class BasicSet<T, AddT = T> implements ImmutableSet<T>, MutableSet<T, Add
         return definition as unknown as T;
     }
 }
+
+/**
+ * A {@link Map} backed by an {@link IndexedSet}.
+ *
+ * This supports the common case where sets must be looked up by key.  Implementations like {@link BasicSet} offer
+ * efficient lookup by key using {@link IndexedSet#get}, but usage like a {@link Map} is still cumbersome.  This class
+ * works as an adapter to make key/value access patterns more natural.
+ */
+export class MapOfIndexedSet<T, S extends ImmutableSet<T> & MutableSet<T> & IndexedSet<T>, K extends keyof T>
+    implements Map<T[K], T>
+{
+    #set: S;
+    #key: K;
+
+    // This is an optimization for lookup
+    #index?: Map<T[K], T>;
+
+    /**
+     * Create a new map.
+     *
+     * @param set the backing data
+     * @param key a property of {@link T} used as the key
+     * @param index optional index that optimizes lookup by bypassing {@link IndexedSet#get}
+     */
+    constructor(set: S, key: K, index?: Map<T[K], T>) {
+        this.#set = set;
+        this.#key = key;
+        this.#index = index;
+    }
+
+    clear(): void {
+        this.#set.clear();
+    }
+
+    delete(key: T[K]): boolean {
+        const item = this.get(key);
+        if (item) {
+            return this.#set.delete(item);
+        }
+        return false;
+    }
+
+    forEach(callbackfn: (value: T, key: T[K], map: Map<T[K], T>) => void, thisArg?: any): void {
+        if (thisArg) {
+            callbackfn = callbackfn.bind(thisArg);
+        }
+        for (const [k, v] of this) {
+            callbackfn(v, k, this);
+        }
+    }
+
+    get(key: T[K]): T | undefined {
+        if (this.#index) {
+            return this.#index.get(key);
+        }
+        return this.#set.get(this.#key, key);
+    }
+
+    has(key: T[K]): boolean {
+        return this.#index ? this.#index.has(key) : this.#set.get(this.#key, key) !== undefined;
+    }
+
+    set(key: T[K], value: T): this {
+        if (value[this.#key] !== key) {
+            throw new MapOfIndexedSet.KeyValueMismatchError(
+                `Cannot set key "${key}" because value property ${String(this.#key)} is "${value[this.#key]}"`,
+            );
+        }
+        if (this.has(key)) {
+            if (this.get(key) === value) {
+                return this;
+            }
+            this.#set.delete((this.#index ? this.#index.get(key) : this.#set.get(this.#key, key)) as T);
+        }
+        this.#set.add(value);
+        return this;
+    }
+
+    get size() {
+        return this.#set.size;
+    }
+
+    entries(): MapIterator<[T[K], T]> {
+        return this[Symbol.iterator]();
+    }
+
+    keys(): MapIterator<T[K]> {
+        if (this.#index) {
+            return this.#index.keys();
+        }
+        const keys = [...this.#set].map(item => item[this.#key]).filter(key => key !== undefined);
+        return keys[Symbol.iterator]();
+    }
+
+    values(): MapIterator<T> {
+        if (this.#index) {
+            return this.#index.values();
+        }
+        const values = [...this.#set].map(item => item);
+        return values[Symbol.iterator]();
+    }
+
+    *[Symbol.iterator](): MapIterator<[T[K], T]> {
+        for (const item of this.#set) {
+            const k = item[this.#key];
+            if (k === undefined) {
+                continue;
+            }
+            yield [k, item];
+        }
+    }
+
+    [Symbol.toStringTag] = "Map";
+}
+
+export namespace MapOfIndexedSet {
+    export class KeyValueMismatchError extends ImplementationError {}
+}

package/src/util/index.ts

@@ -20,6 +20,7 @@ export * from "./FormattedText.js";
 export * from "./GeneratedClass.js";
 export * from "./Ip.js";
 export * from "./Lifecycle.js";
+export * from "./Map.js";
 export * from "./Mutex.js";
 export * from "./NamedHandler.js";
 export * from "./Number.js";