@matter/general 0.14.0 → 0.14.1-alpha.0-20250605-9fc134af0

package/dist/cjs/util/Set.d.ts

@@ -3,6 +3,7 @@
  * Copyright 2022-2025 Matter.js Authors
  * SPDX-License-Identifier: Apache-2.0
  */
+import { ImplementationError } from "#MatterError.js";
 import { Observable } from "./Observable.js";
 /**
  * A read-only set.
@@ -31,9 +32,19 @@ 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>;
 }
 /**
  * A generic set implementation supporting all interfaces in this module.
@@ -51,10 +62,50 @@ export declare class BasicSet<T, AddT = T> implements ImmutableSet<T>, MutableSe
     has(item: T): boolean;
     add(item: AddT): void;
     get<F extends keyof T>(field: F, value: T[F]): T | undefined;
+    /**
+     * 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>;
     delete(item: T): boolean;
     clear(): void;
     get added(): Observable<[T], void>;
     get deleted(): Observable<[T], void>;
     protected create(definition: AddT): 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 declare class MapOfIndexedSet<T, S extends ImmutableSet<T> & MutableSet<T> & IndexedSet<T>, K extends keyof T> implements Map<T[K], T> {
+    #private;
+    /**
+     * 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>);
+    clear(): void;
+    delete(key: T[K]): boolean;
+    forEach(callbackfn: (value: T, key: T[K], map: Map<T[K], T>) => void, thisArg?: any): void;
+    get(key: T[K]): T | undefined;
+    has(key: T[K]): boolean;
+    set(key: T[K], value: T): this;
+    get size(): number;
+    entries(): MapIterator<[T[K], T]>;
+    keys(): MapIterator<T[K]>;
+    values(): MapIterator<T>;
+    [Symbol.iterator](): MapIterator<[T[K], T]>;
+    [Symbol.toStringTag]: string;
+}
+export declare namespace MapOfIndexedSet {
+    class KeyValueMismatchError extends ImplementationError {
+    }
+}
 //# sourceMappingURL=Set.d.ts.map

package/dist/cjs/util/Set.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Set.d.ts","sourceRoot":"","sources":["../../../src/util/Set.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC3B,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,MAAM,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IAChD,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC;IACtB,IAAI,IAAI,IAAI,MAAM,CAAC;IACnB,IAAI,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAAG,SAAS,GAAG,CAAC,GAAG,SAAS,CAAC;IACjE,MAAM,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAAG,SAAS,GAAG,CAAC,EAAE,CAAC;CAC5D;AAED;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,EAAE,IAAI,GAAG,CAAC;IACnC,GAAG,CAAC,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IAC5B,MAAM,CAAC,UAAU,EAAE,CAAC,GAAG,OAAO,CAAC;IAC/B,KAAK,IAAI,IAAI,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC5B,IAAI,KAAK,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7B,IAAI,OAAO,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IACzB,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;CAChE;AAED;;;;GAIG;AACH,qBAAa,QAAQ,CAAC,CAAC,EAAE,IAAI,GAAG,CAAC,CAAE,YAAW,YAAY,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;;gBAQnG,GAAG,YAAY,EAAE,IAAI,EAAE;IAMnC,CAAC,MAAM,CAAC,QAAQ,CAAC;IAIjB,IAAI,IAAI,WAEP;IAED,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;IAI7B,IAAI,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAAG,SAAS;IAQhD,MAAM,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAAG,SAAS;IAUlD,GAAG,CAAC,IAAI,EAAE,CAAC;IAIX,GAAG,CAAC,IAAI,EAAE,IAAI;IA4Bd,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IAmB5C,MAAM,CAAC,IAAI,EAAE,CAAC;IAwBd,KAAK;IAIL,IAAI,KAAK,0BAKR;IAED,IAAI,OAAO,0BAKV;IAED,SAAS,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,GACG,CAAC;CAExC"}
+{"version":3,"file":"Set.d.ts","sourceRoot":"","sources":["../../../src/util/Set.ts"],"names":[],"mappings":"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"}

package/dist/cjs/util/Set.js

@@ -18,9 +18,11 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var Set_exports = {};
 __export(Set_exports, {
-  BasicSet: () => BasicSet
+  BasicSet: () => BasicSet,
+  MapOfIndexedSet: () => MapOfIndexedSet
 });
 module.exports = __toCommonJS(Set_exports);
+var import_MatterError = require("#MatterError.js");
 var import_Observable = require("./Observable.js");
 /**
  * @license
@@ -32,6 +34,7 @@ class BasicSet {
   #added;
   #deleted;
   #indices;
+  #maps;
   constructor(...initialItems) {
     for (const item of initialItems) {
       this.add(item);
@@ -87,6 +90,9 @@ class BasicSet {
     this.#added?.emit(created);
   }
   get(field, value) {
+    return this.#indexOf(field).get(value);
+  }
+  #indexOf(field) {
     if (!this.#indices) {
       this.#indices = {};
     }
@@ -94,15 +100,31 @@ class BasicSet {
     if (index === void 0) {
       index = /* @__PURE__ */ new Map();
       for (const item of this) {
-        const value2 = item[field];
-        if (value2 === void 0 || index.has(value2)) {
+        const value = item[field];
+        if (value === void 0 || index.has(value)) {
           continue;
         }
-        index.set(value2, item);
+        index.set(value, item);
       }
       this.#indices[field] = index;
     }
-    return index?.get(value);
+    return index;
+  }
+  /**
+   * 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(field) {
+    if (!this.#maps) {
+      this.#maps = {};
+    }
+    let map = this.#maps[field];
+    if (map === void 0) {
+      map = new MapOfIndexedSet(this, field, this.#indexOf(field));
+      this.#maps[field] = map;
+    }
+    return map;
   }
   delete(item) {
     if (!this.#entries.delete(item)) {
@@ -142,4 +164,99 @@ class BasicSet {
     return definition;
   }
 }
+class MapOfIndexedSet {
+  #set;
+  #key;
+  // This is an optimization for lookup
+  #index;
+  /**
+   * 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, key, index) {
+    this.#set = set;
+    this.#key = key;
+    this.#index = index;
+  }
+  clear() {
+    this.#set.clear();
+  }
+  delete(key) {
+    const item = this.get(key);
+    if (item) {
+      return this.#set.delete(item);
+    }
+    return false;
+  }
+  forEach(callbackfn, thisArg) {
+    if (thisArg) {
+      callbackfn = callbackfn.bind(thisArg);
+    }
+    for (const [k, v] of this) {
+      callbackfn(v, k, this);
+    }
+  }
+  get(key) {
+    if (this.#index) {
+      return this.#index.get(key);
+    }
+    return this.#set.get(this.#key, key);
+  }
+  has(key) {
+    return this.#index ? this.#index.has(key) : this.#set.get(this.#key, key) !== void 0;
+  }
+  set(key, value) {
+    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));
+    }
+    this.#set.add(value);
+    return this;
+  }
+  get size() {
+    return this.#set.size;
+  }
+  entries() {
+    return this[Symbol.iterator]();
+  }
+  keys() {
+    if (this.#index) {
+      return this.#index.keys();
+    }
+    const keys = [...this.#set].map((item) => item[this.#key]).filter((key) => key !== void 0);
+    return keys[Symbol.iterator]();
+  }
+  values() {
+    if (this.#index) {
+      return this.#index.values();
+    }
+    const values = [...this.#set].map((item) => item);
+    return values[Symbol.iterator]();
+  }
+  *[Symbol.iterator]() {
+    for (const item of this.#set) {
+      const k = item[this.#key];
+      if (k === void 0) {
+        continue;
+      }
+      yield [k, item];
+    }
+  }
+  [Symbol.toStringTag] = "Map";
+}
+((MapOfIndexedSet2) => {
+  class KeyValueMismatchError extends import_MatterError.ImplementationError {
+  }
+  MapOfIndexedSet2.KeyValueMismatchError = KeyValueMismatchError;
+})(MapOfIndexedSet || (MapOfIndexedSet = {}));
 //# sourceMappingURL=Set.js.map

package/dist/cjs/util/Set.js.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../../../src/util/Set.ts"],
-  "mappings": "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",
-  "names": ["value"]
+  "mappings": "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",
+  "names": ["MapOfIndexedSet"]
 }

package/dist/esm/util/Set.d.ts

@@ -3,6 +3,7 @@
  * Copyright 2022-2025 Matter.js Authors
  * SPDX-License-Identifier: Apache-2.0
  */
+import { ImplementationError } from "#MatterError.js";
 import { Observable } from "./Observable.js";
 /**
  * A read-only set.
@@ -31,9 +32,19 @@ 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>;
 }
 /**
  * A generic set implementation supporting all interfaces in this module.
@@ -51,10 +62,50 @@ export declare class BasicSet<T, AddT = T> implements ImmutableSet<T>, MutableSe
     has(item: T): boolean;
     add(item: AddT): void;
     get<F extends keyof T>(field: F, value: T[F]): T | undefined;
+    /**
+     * 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>;
     delete(item: T): boolean;
     clear(): void;
     get added(): Observable<[T], void>;
     get deleted(): Observable<[T], void>;
     protected create(definition: AddT): 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 declare class MapOfIndexedSet<T, S extends ImmutableSet<T> & MutableSet<T> & IndexedSet<T>, K extends keyof T> implements Map<T[K], T> {
+    #private;
+    /**
+     * 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>);
+    clear(): void;
+    delete(key: T[K]): boolean;
+    forEach(callbackfn: (value: T, key: T[K], map: Map<T[K], T>) => void, thisArg?: any): void;
+    get(key: T[K]): T | undefined;
+    has(key: T[K]): boolean;
+    set(key: T[K], value: T): this;
+    get size(): number;
+    entries(): MapIterator<[T[K], T]>;
+    keys(): MapIterator<T[K]>;
+    values(): MapIterator<T>;
+    [Symbol.iterator](): MapIterator<[T[K], T]>;
+    [Symbol.toStringTag]: string;
+}
+export declare namespace MapOfIndexedSet {
+    class KeyValueMismatchError extends ImplementationError {
+    }
+}
 //# sourceMappingURL=Set.d.ts.map

package/dist/esm/util/Set.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Set.d.ts","sourceRoot":"","sources":["../../../src/util/Set.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,YAAY,CAAC,CAAC;IAC3B,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,MAAM,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;IAChD,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC;IACtB,IAAI,IAAI,IAAI,MAAM,CAAC;IACnB,IAAI,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAAG,SAAS,GAAG,CAAC,GAAG,SAAS,CAAC;IACjE,MAAM,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAAG,SAAS,GAAG,CAAC,EAAE,CAAC;CAC5D;AAED;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,EAAE,IAAI,GAAG,CAAC;IACnC,GAAG,CAAC,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IAC5B,MAAM,CAAC,UAAU,EAAE,CAAC,GAAG,OAAO,CAAC;IAC/B,KAAK,IAAI,IAAI,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC;IAC5B,IAAI,KAAK,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7B,IAAI,OAAO,IAAI,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IACzB,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;CAChE;AAED;;;;GAIG;AACH,qBAAa,QAAQ,CAAC,CAAC,EAAE,IAAI,GAAG,CAAC,CAAE,YAAW,YAAY,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,CAAC;;gBAQnG,GAAG,YAAY,EAAE,IAAI,EAAE;IAMnC,CAAC,MAAM,CAAC,QAAQ,CAAC;IAIjB,IAAI,IAAI,WAEP;IAED,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;IAI7B,IAAI,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAAG,SAAS;IAQhD,MAAM,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAAG,SAAS;IAUlD,GAAG,CAAC,IAAI,EAAE,CAAC;IAIX,GAAG,CAAC,IAAI,EAAE,IAAI;IA4Bd,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;IAmB5C,MAAM,CAAC,IAAI,EAAE,CAAC;IAwBd,KAAK;IAIL,IAAI,KAAK,0BAKR;IAED,IAAI,OAAO,0BAKV;IAED,SAAS,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,GACG,CAAC;CAExC"}
+{"version":3,"file":"Set.d.ts","sourceRoot":"","sources":["../../../src/util/Set.ts"],"names":[],"mappings":"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"}

package/dist/esm/util/Set.js

@@ -3,12 +3,14 @@
  * Copyright 2022-2025 Matter.js Authors
  * SPDX-License-Identifier: Apache-2.0
  */
+import { ImplementationError } from "#MatterError.js";
 import { Observable } from "./Observable.js";
 class BasicSet {
   #entries = /* @__PURE__ */ new Set();
   #added;
   #deleted;
   #indices;
+  #maps;
   constructor(...initialItems) {
     for (const item of initialItems) {
       this.add(item);
@@ -64,6 +66,9 @@ class BasicSet {
     this.#added?.emit(created);
   }
   get(field, value) {
+    return this.#indexOf(field).get(value);
+  }
+  #indexOf(field) {
     if (!this.#indices) {
       this.#indices = {};
     }
@@ -71,15 +76,31 @@ class BasicSet {
     if (index === void 0) {
       index = /* @__PURE__ */ new Map();
       for (const item of this) {
-        const value2 = item[field];
-        if (value2 === void 0 || index.has(value2)) {
+        const value = item[field];
+        if (value === void 0 || index.has(value)) {
           continue;
         }
-        index.set(value2, item);
+        index.set(value, item);
       }
       this.#indices[field] = index;
     }
-    return index?.get(value);
+    return index;
+  }
+  /**
+   * 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(field) {
+    if (!this.#maps) {
+      this.#maps = {};
+    }
+    let map = this.#maps[field];
+    if (map === void 0) {
+      map = new MapOfIndexedSet(this, field, this.#indexOf(field));
+      this.#maps[field] = map;
+    }
+    return map;
   }
   delete(item) {
     if (!this.#entries.delete(item)) {
@@ -119,7 +140,103 @@ class BasicSet {
     return definition;
   }
 }
+class MapOfIndexedSet {
+  #set;
+  #key;
+  // This is an optimization for lookup
+  #index;
+  /**
+   * 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, key, index) {
+    this.#set = set;
+    this.#key = key;
+    this.#index = index;
+  }
+  clear() {
+    this.#set.clear();
+  }
+  delete(key) {
+    const item = this.get(key);
+    if (item) {
+      return this.#set.delete(item);
+    }
+    return false;
+  }
+  forEach(callbackfn, thisArg) {
+    if (thisArg) {
+      callbackfn = callbackfn.bind(thisArg);
+    }
+    for (const [k, v] of this) {
+      callbackfn(v, k, this);
+    }
+  }
+  get(key) {
+    if (this.#index) {
+      return this.#index.get(key);
+    }
+    return this.#set.get(this.#key, key);
+  }
+  has(key) {
+    return this.#index ? this.#index.has(key) : this.#set.get(this.#key, key) !== void 0;
+  }
+  set(key, value) {
+    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));
+    }
+    this.#set.add(value);
+    return this;
+  }
+  get size() {
+    return this.#set.size;
+  }
+  entries() {
+    return this[Symbol.iterator]();
+  }
+  keys() {
+    if (this.#index) {
+      return this.#index.keys();
+    }
+    const keys = [...this.#set].map((item) => item[this.#key]).filter((key) => key !== void 0);
+    return keys[Symbol.iterator]();
+  }
+  values() {
+    if (this.#index) {
+      return this.#index.values();
+    }
+    const values = [...this.#set].map((item) => item);
+    return values[Symbol.iterator]();
+  }
+  *[Symbol.iterator]() {
+    for (const item of this.#set) {
+      const k = item[this.#key];
+      if (k === void 0) {
+        continue;
+      }
+      yield [k, item];
+    }
+  }
+  [Symbol.toStringTag] = "Map";
+}
+((MapOfIndexedSet2) => {
+  class KeyValueMismatchError extends ImplementationError {
+  }
+  MapOfIndexedSet2.KeyValueMismatchError = KeyValueMismatchError;
+})(MapOfIndexedSet || (MapOfIndexedSet = {}));
 export {
-  BasicSet
+  BasicSet,
+  MapOfIndexedSet
 };
 //# sourceMappingURL=Set.js.map

package/dist/esm/util/Set.js.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../../../src/util/Set.ts"],
-  "mappings": "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",
-  "names": ["value"]
+  "mappings": "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",
+  "names": ["MapOfIndexedSet"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@matter/general",
-    "version": "0.14.0",
+    "version": "0.14.1-alpha.0-20250605-9fc134af0",
     "description": "Non-Matter support for Matter.js",
     "keywords": [
         "iot",
@@ -36,7 +36,7 @@
         "@noble/curves": "^1.9.1"
     },
     "devDependencies": {
-        "@matter/testing": "0.14.0"
+        "@matter/testing": "0.14.1-alpha.0-20250605-9fc134af0"
     },
     "files": [
         "dist/**/*",

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,7 +157,24 @@ 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
+    }
+
+    /**
+     * 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) {
@@ -187,3 +223,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 {}
+}