@rhombus-toolkit/collections 2.0.2 → 3.0.0

package/dist/bundle/index.d.ts

@@ -1,3 +1,24 @@
+import { Func } from '@rhombus-toolkit/types';
+
+/**
+ * A stack whose entries leave when their scope does.
+ *
+ * @remarks
+ * Iterates outermost first.
+ */
+declare class AutoStack<T> implements Iterable<T> {
+    #private;
+    /** How many entries the stack holds. */
+    get length(): number;
+    /** Adds `item`; disposing the return truncates back to the pre-push depth, so an outer scope's dispose also drops what an inner one left. */
+    push(item: T): Disposable;
+    /** Whether `item` sits anywhere in the stack, not only at the top. */
+    has(item: T): boolean;
+    /** The innermost entry, absent where the stack holds nothing. */
+    peek(): T | undefined;
+    [Symbol.iterator](): ArrayIterator<T>;
+}
+
 /**
  * A persistent singly-linked list — extending shares everything already there.
  *
@@ -28,22 +49,58 @@ 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;
-    /** An existing key keeps its place in iteration order, as with `Map`. */
-    set(key: K, value: V): this;
-    delete(key: K): boolean;
+    /** 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;
-    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. */
-    get size(): number;
-    entries(): MapIterator<[K, V]>;
-    keys(): MapIterator<K>;
-    values(): MapIterator<V>;
-    [Symbol.iterator](): MapIterator<[K, V]>;
-    readonly [Symbol.toStringTag]: "KindaWeakMap";
+    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;
 }
 
-export { ImmutableLinkedList, KindaWeakMap };
+export { AutoStack, ImmutableLinkedList, KindaWeakMap, MultiKeyWeakMap };

package/dist/bundle/index.js

@@ -1,3 +1,26 @@
+// src/AutoStack.ts
+class AutoStack {
+  #items = [];
+  get length() {
+    return this.#items.length;
+  }
+  push(item) {
+    const pos = this.#items.length;
+    this.#items.push(item);
+    return { [Symbol.dispose]: () => {
+      this.#items.length = pos;
+    } };
+  }
+  has(item) {
+    return this.#items.includes(item);
+  }
+  peek() {
+    return this.#items.at(-1);
+  }
+  [Symbol.iterator]() {
+    return this.#items.values();
+  }
+}
 // src/ImmutableLinkedList.ts
 class ImmutableLinkedList {
   static #nothing = new ImmutableLinkedList(undefined, undefined, 0);
@@ -58,66 +81,146 @@ 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 {
-  #map = new Map;
-  #registry = new FinalizationRegistry(({ key, ref }) => {
-    if (this.#map.get(key) === ref) {
-      this.#map.delete(key);
-    }
+  #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) {
-    const held = this.#map.get(key);
-    if (held) {
-      this.#registry.unregister(held);
+    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);
     }
-    const ref = new WeakRef(value);
-    this.#registry.register(value, { key, ref }, ref);
-    this.#map.set(key, ref);
     return this;
   }
   delete(key) {
-    const held = this.#map.get(key);
-    if (!held) {
-      return false;
+    if (isWeaklyHoldable(key)) {
+      if (!this.#weak.delete(key)) {
+        return false;
+      }
+      this.#weakSize--;
+      this.#collected.unregister(key);
+      return true;
     }
-    this.#map.delete(key);
-    this.#registry.unregister(held);
-    return held.deref() !== undefined;
+    return this.#strong?.delete(key) ?? false;
   }
-  get(key) {
-    return this.#map.get(key)?.deref();
+  getOrInsert(key, value) {
+    const existing = this.get(key);
+    if (existing !== undefined || this.has(key)) {
+      return existing;
+    }
+    this.set(key, value);
+    return value;
   }
-  has(key) {
-    return this.get(key) !== undefined;
+  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;
   }
-  clear() {
-    this.#map.forEach((ref) => this.#registry.unregister(ref));
-    this.#map.clear();
+}
+// src/MultiKeyWeakMap.ts
+class Node {
+  next = new KindaWeakMap;
+  entry;
+}
+
+class MultiKeyWeakMap {
+  _root = new Node;
+  get [Symbol.toStringTag]() {
+    return "MultiKeyWeakMap";
   }
-  forEach(callbackfn, thisArg) {
-    for (const [key, value] of this) {
-      callbackfn.call(thisArg, value, key, this);
-    }
+  #findNodeAt(keys) {
+    return keys.reduce((node, key) => node?.next.get(key), this._root);
   }
-  get size() {
-    return this.entries().reduce((count) => count + 1, 0);
+  #ensureNodeAt(keys) {
+    return keys.reduce((node, key) => node.next.getOrInsertComputed(key, () => new Node), this._root);
   }
-  entries() {
-    const held = this.#map.entries().map(([key, ref]) => [key, ref.deref()]);
-    return held.filter((entry) => entry[1] !== undefined);
+  get(keys) {
+    return this.#findNodeAt(keys)?.entry?.value;
   }
-  keys() {
-    return this.entries().map(([key]) => key);
+  has(keys) {
+    return this.#findNodeAt(keys)?.entry !== undefined;
   }
-  values() {
-    return this.entries().map(([, value]) => value);
+  set(keys, value) {
+    this.#ensureNodeAt(keys).entry = { value };
+    return this;
   }
-  [Symbol.iterator]() {
-    return this.entries();
+  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;
   }
-  [Symbol.toStringTag] = "KindaWeakMap";
 }
 export {
+  AutoStack,
   ImmutableLinkedList,
-  KindaWeakMap
+  KindaWeakMap,
+  MultiKeyWeakMap
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@rhombus-toolkit/collections",
-  "version": "2.0.2",
-  "description": "Collection data structures: ImmutableLinkedList (persistent, both ends known), KindaWeakMap (strong keys, weak values).",
+  "version": "3.0.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).",
   "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