@rhombus-toolkit/collections 2.1.0 → 3.1.0

package/dist/bundle/index.d.ts

@@ -1,3 +1,5 @@
+import { Func } from '@rhombus-toolkit/types';
+
 /**
  * A stack whose entries leave when their scope does.
  *
@@ -47,22 +49,84 @@ declare class ImmutableLinkedList<T> implements Iterable<T> {
     tailToHead(): readonly T[];
 }
 
-declare class KindaWeakMap<K, V extends WeakKey> {
+/**
+ * A map that holds each key weakly when it can: objects, functions, and unregistered symbols go
+ * in a `WeakMap`; everything else goes in a `Map`.
+ *
+ * @remarks
+ * An entry under a weakly held key goes when the key is collected; one under any other key lives
+ * as long as the map.
+ */
+declare class KindaWeakMap<in out K = unknown, in out V = unknown> {
+    #private;
+    /** Entries held right now; a collected key still counts until its cleanup has run, so this can read high, never low. */
+    get size(): number;
+    get [Symbol.toStringTag](): string;
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    set(key: K, value: V): this;
+    delete(key: K): boolean;
+    /** The entry under `key`, storing `value` there first when there is none. */
+    getOrInsert(key: K, value: V): V;
+    /** The entry under `key`, storing what `compute` answers there first when there is none. A throw stores nothing. */
+    getOrInsertComputed(key: K, compute: Func<[K], V>): V;
+}
+
+/** Where a tuple ends: the entry stored there, and the node each further key leads to. */
+declare class Node<Value> {
+    readonly next: KindaWeakMap<unknown, Node<Value>>;
+    /** Boxed, so a stored `undefined` is an entry rather than an absence. */
+    entry: {
+        value: Value;
+    } | undefined;
+}
+/**
+ * A `KindaWeakMap` keyed by a tuple, matched key by key rather than by the tuple's identity.
+ *
+ * @remarks
+ * Tuples of every length share one map, the empty tuple included. An entry goes when any weakly
+ * held key in its tuple is collected; a tuple of primitives lives as long as the map.
+ */
+declare class MultiKeyWeakMap<in out Keys extends readonly unknown[] = unknown[], in out Value = unknown> implements WeakMap<Keys, Value> {
+    #private;
+    /** @internal The spec reads it to see pruning. */
+    readonly _root: Node<Value>;
+    get [Symbol.toStringTag](): string;
+    get(keys: Keys): Value | undefined;
+    has(keys: Keys): boolean;
+    set(keys: Keys, value: Value): this;
+    /** Longer tuples through `keys` keep their entries; a prefix left holding nothing is released. */
+    delete(keys: Keys): boolean;
+    /** The entry at `keys`, storing `value` there first when there is none. */
+    getOrInsert(keys: Keys, value: Value): Value;
+    /** The entry at `keys`, storing what `compute` answers there first when there is none. A throw stores nothing. */
+    getOrInsertComputed(keys: Keys, compute: Func<[Keys], Value>): Value;
+}
+
+/**
+ * A `Map` whose values are held weakly, so an entry is removed once nothing else holds its value.
+ *
+ * @remarks
+ * Not a `Map` by `instanceof`.
+ */
+declare class WeakValuedMap<K, V extends WeakKey> implements Map<K, V> {
     #private;
-    /** An existing key keeps its place in iteration order, as with `Map`. */
+    constructor();
+    constructor(entries: Iterable<readonly [K, V]> | null);
+    /** Re-setting an existing key leaves its place in iteration order unchanged, as with `Map`. */
     set(key: K, value: V): this;
     delete(key: K): boolean;
     get(key: K): V | undefined;
     has(key: K): boolean;
     clear(): void;
     forEach(callbackfn: (value: V, key: K, map: this) => void, thisArg?: any): void;
-    /** Counts only entries whose value is still alive, so it walks every ref. */
+    /** Computed by walking every entry and counting those whose value is still alive. */
     get size(): number;
     entries(): MapIterator<[K, V]>;
     keys(): MapIterator<K>;
     values(): MapIterator<V>;
     [Symbol.iterator](): MapIterator<[K, V]>;
-    readonly [Symbol.toStringTag]: "KindaWeakMap";
+    readonly [Symbol.toStringTag]: "WeakValuedMap";
 }
 
-export { AutoStack, ImmutableLinkedList, KindaWeakMap };
+export { AutoStack, ImmutableLinkedList, KindaWeakMap, MultiKeyWeakMap, WeakValuedMap };

package/dist/bundle/index.js

@@ -81,13 +81,156 @@ function tailOf(link) {
   return tail;
 }
 // src/KindaWeakMap.ts
+function isWeaklyHoldable(key) {
+  const type = typeof key;
+  if (type === "object") {
+    return key !== null;
+  }
+  if (type === "function") {
+    return true;
+  }
+  if (type === "symbol") {
+    return Symbol.keyFor(key) === undefined;
+  }
+  return false;
+}
+
 class KindaWeakMap {
+  #weak = new WeakMap;
+  #weakSize = 0;
+  #collected = new FinalizationRegistry(() => {
+    this.#weakSize--;
+  });
+  #strong;
+  get size() {
+    return (this.#strong?.size ?? 0) + this.#weakSize;
+  }
+  get [Symbol.toStringTag]() {
+    return "KindaWeakMap";
+  }
+  get(key) {
+    if (isWeaklyHoldable(key)) {
+      return this.#weak.get(key);
+    }
+    return this.#strong?.get(key);
+  }
+  has(key) {
+    if (isWeaklyHoldable(key)) {
+      return this.#weak.has(key);
+    }
+    return this.#strong?.has(key) ?? false;
+  }
+  set(key, value) {
+    if (isWeaklyHoldable(key)) {
+      if (!this.#weak.has(key)) {
+        this.#weakSize++;
+        this.#collected.register(key, undefined, key);
+      }
+      this.#weak.set(key, value);
+    } else {
+      (this.#strong ??= new Map).set(key, value);
+    }
+    return this;
+  }
+  delete(key) {
+    if (isWeaklyHoldable(key)) {
+      if (!this.#weak.delete(key)) {
+        return false;
+      }
+      this.#weakSize--;
+      this.#collected.unregister(key);
+      return true;
+    }
+    return this.#strong?.delete(key) ?? false;
+  }
+  getOrInsert(key, value) {
+    const existing = this.get(key);
+    if (existing !== undefined || this.has(key)) {
+      return existing;
+    }
+    this.set(key, value);
+    return value;
+  }
+  getOrInsertComputed(key, compute) {
+    const existing = this.get(key);
+    if (existing !== undefined || this.has(key)) {
+      return existing;
+    }
+    const value = compute(key);
+    this.set(key, value);
+    return value;
+  }
+}
+// src/MultiKeyWeakMap.ts
+class Node {
+  next = new KindaWeakMap;
+  entry;
+}
+
+class MultiKeyWeakMap {
+  _root = new Node;
+  get [Symbol.toStringTag]() {
+    return "MultiKeyWeakMap";
+  }
+  #findNodeAt(keys) {
+    return keys.reduce((node, key) => node?.next.get(key), this._root);
+  }
+  #ensureNodeAt(keys) {
+    return keys.reduce((node, key) => node.next.getOrInsertComputed(key, () => new Node), this._root);
+  }
+  get(keys) {
+    return this.#findNodeAt(keys)?.entry?.value;
+  }
+  has(keys) {
+    return this.#findNodeAt(keys)?.entry !== undefined;
+  }
+  set(keys, value) {
+    this.#ensureNodeAt(keys).entry = { value };
+    return this;
+  }
+  delete(keys) {
+    const path = [this._root];
+    for (const key of keys) {
+      const next = path[path.length - 1].next.get(key);
+      if (!next) {
+        return false;
+      }
+      path.push(next);
+    }
+    const leaf = path[path.length - 1];
+    if (leaf.entry === undefined) {
+      return false;
+    }
+    leaf.entry = undefined;
+    for (let depth = keys.length;depth > 0; depth--) {
+      const node = path[depth];
+      if (node.entry !== undefined || node.next.size) {
+        break;
+      }
+      path[depth - 1].next.delete(keys[depth - 1]);
+    }
+    return true;
+  }
+  getOrInsert(keys, value) {
+    return (this.#ensureNodeAt(keys).entry ??= { value }).value;
+  }
+  getOrInsertComputed(keys, compute) {
+    return (this.#ensureNodeAt(keys).entry ??= { value: compute(keys) }).value;
+  }
+}
+// src/WeakValuedMap.ts
+class WeakValuedMap {
   #map = new Map;
   #registry = new FinalizationRegistry(({ key, ref }) => {
     if (this.#map.get(key) === ref) {
       this.#map.delete(key);
     }
   });
+  constructor(entries) {
+    for (const [key, value] of entries ?? []) {
+      this.set(key, value);
+    }
+  }
   set(key, value) {
     const held = this.#map.get(key);
     if (held) {
@@ -138,10 +281,12 @@ class KindaWeakMap {
   [Symbol.iterator]() {
     return this.entries();
   }
-  [Symbol.toStringTag] = "KindaWeakMap";
+  [Symbol.toStringTag] = "WeakValuedMap";
 }
 export {
   AutoStack,
   ImmutableLinkedList,
-  KindaWeakMap
+  KindaWeakMap,
+  MultiKeyWeakMap,
+  WeakValuedMap
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rhombus-toolkit/collections",
-  "version": "2.1.0",
-  "description": "Collection data structures: AutoStack (entries leave with their scope), ImmutableLinkedList (persistent, both ends known), KindaWeakMap (strong keys, weak values).",
+  "version": "3.1.0",
+  "description": "Collection data structures: AutoStack (entries leave with their scope), ImmutableLinkedList (persistent, both ends known), KindaWeakMap (weak where it can, strong otherwise), MultiKeyWeakMap (a KindaWeakMap keyed by a tuple), WeakValuedMap (values held weakly).",
   "repository": {
     "type": "git",
     "url": "https://github.com/rhombus-toolkit/ts.git",
@@ -23,6 +23,9 @@
   ],
   "keywords": [],
   "author": "Thomas Butler",
+  "dependencies": {
+    "@rhombus-toolkit/types": "4.0.1"
+  },
   "publishConfig": {
     "access": "public",
     "provenance": true