@thi.ng/trie 1.1.28 → 2.0.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-08-04T08:45:04Z
+- **Last updated**: 2025-08-11T16:41:24Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,27 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+# [2.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/trie@2.0.0) (2025-08-11)
+
+#### 🛑 Breaking changes
+
+- major update `TrieMap` & `MultiTrie` ([d7f4a12](https://github.com/thi-ng/umbrella/commit/d7f4a12))
+- BREAKING CHANGE: major update `TrieMap` & `MultiTrie`
+  - update `MultiTrie` to only support array-based keys
+    - switch internals to using Map for storing branches
+    - update arg types in all methods
+    - add `.toJSON()` method to support serialization
+  - rename `MultiTrieOpts.vals` => `.values`
+  - add/update/dedupe iterators in both impls
+  - replace `.suffixes()` iterator in both impls w/ extra args passed to `.keys()`
+  - add `defTrieMapFromJSON()` and `defMultiTrieFromJSON()`
+  - add/update tests
+
+#### ♻️ Refactoring
+
+- update internals ([065cc27](https://github.com/thi-ng/umbrella/commit/065cc27))
+  - remove obsolete size/count in MultiTrie
+
 ### [1.1.10](https://github.com/thi-ng/umbrella/tree/@thi.ng/trie@1.1.10) (2025-01-14)
 
 #### ♻️ Refactoring

package/README.md

@@ -27,7 +27,7 @@
 
 ## About
 
-Trie-based map data structure with prefix search/query support.
+Trie-based ES6-like Map data structures with prefix search/query support.
 
 This package contains functionality which was previously part of and has been
 extracted from the [@thi.ng/associative](https://thi.ng/associative) package.
@@ -42,9 +42,10 @@ prefix, longest matching prefix queries etc.
 The implementations here too feature ES6 Map-like API, similar to other types in
 this package, with some further trie-specific additions.
 
-```ts
-import { defTrieMap } from "@thi.ng/associative";
+```ts tangle:export/readme-1.ts
+import { defTrieMap } from "@thi.ng/trie";
 
+// construct trie from given key-value pairs (optional)
 const trie = defTrieMap([
   ["hey", "en"],
   ["hello", "en"],
@@ -55,42 +56,55 @@ const trie = defTrieMap([
   ["hej", "se"],
 ]);
 
-trie.knownPrefix("hole")
+// find longest known prefix given key
+console.log(trie.knownPrefix("hole"));
 // "hol"
 
-[...trie.suffixes("he")]
-// [ "j", "llo", "y" ]
+// all known keys
+console.log([...trie.keys()])
+// [ "hold", "hola", "hallo", "hej", "hello", "hey" ]
 
-// w/ prefix included
-[...trie.suffixes("he", true)]
+// all keys starting with given prefix
+console.log([...trie.keys("he")])
 // [ "hej", "hello", "hey" ]
+
+// suffixes of given key only
+console.log([...trie.keys("he", false)])
+// [ "j", "llo", "y" ]
+
+// values of keys starting with prefix
+console.log([...trie.values("hol")]);
+// [ "en", "es" ]
 ```
 
 ### MultiTrie
 
-The `MultiTrie` is similar to `TrieMap`, but supports array-like keys and
+The `MultiTrie` is similar to `TrieMap`, but uses array-like keys and supports
 multiple values per key. Values are stored in sets whose implementation can be
-configured via ctor options.
+configured via ctor options (e.g. using custom ES6-like Sets with value-based
+equality semantics from the [thi.ng/associative](https://thi.ng/associative)
+package).
 
-```ts
-import { defMultiTrie } from "@thi.ng/associative";
+```ts tangle:export/readme-2.ts
+import { defMultiTrie } from "@thi.ng/trie";
+import { ArraySet } from "@thi.ng/associative";
 
-// init w/ custom value set type (here only for illustration)
-const t = defMultiTrie<string[], string>(null, { vals: () => new ArraySet() });
+// init w/ custom value set type (here purely for illustration)
+const t = defMultiTrie<string, string>(null, { values: () => new ArraySet() });
 
 t.add("to be or not to be".split(" "), 1);
 t.add("to be or not to be".split(" "), 2);
 t.add("to be and to live".split(" "), 3);
 
-t.get("to be or not to be".split(" "))
+console.log(t.get("to be or not to be".split(" ")))
 // Set(2) { 1, 2 }
 
-t.knownPrefix(["to", "be", "not"]);
+console.log(t.knownPrefix(["to", "be", "not"]));
 // [ "to", "be" ]
 
-// auto-complete w/ custom separator between words
-[...t.suffixes(["to", "be"], false, "/")]
-// [ "and/to/live", "or/not/to/be" ]
+// suffixes for given prefix
+console.log([...t.keys(["to", "be"], false)]);
+// [["and", "to", "live"], ["or", "not", "to", "be"]]
 ```
 
 ## Status
@@ -129,7 +143,7 @@ For Node.js REPL:
 const trie = await import("@thi.ng/trie");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.01 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.14 KB
 
 ## Dependencies
 

package/multi-trie.d.ts

@@ -1,39 +1,54 @@
-import type { Fn0, IObjectOf, Maybe, Nullable, Pair } from "@thi.ng/api";
+import type { Fn0, Fn2, Maybe, Nullable, Pair } from "@thi.ng/api";
 export interface MultiTrieOpts<V> {
     /**
-     * Custom value set factory (e.g. for using `Set` implementations from the
+     * Custom value set factory (e.g. `Set` implementations from the
      * [thi.ng/associative](https://thi.ng/associative) package). Uses native
      * ES6 Set by default.
      */
-    vals: Fn0<Set<V>>;
+    values: Fn0<Set<V>>;
 }
-export declare class MultiTrie<K extends ArrayLike<any>, V> {
+/**
+ * Multi-Map-like trie implementation for array-based keys and supporting
+ * multiple unique values per key.
+ */
+export declare class MultiTrie<K, V> {
     protected opts?: Partial<MultiTrieOpts<V>> | undefined;
-    protected next: IObjectOf<MultiTrie<K, V>>;
-    protected vals?: Set<V>;
-    protected n: number;
-    constructor(pairs?: Nullable<Iterable<Pair<K, V>>>, opts?: Partial<MultiTrieOpts<V>> | undefined);
-    [Symbol.iterator](): Generator<(string | V)[], void, unknown>;
-    keys(sep?: string, prefix?: string): Generator<string, void, unknown>;
-    values(): Generator<V, void, unknown>;
-    suffixes(prefix: K, withPrefix?: boolean, sep?: string): Generator<string, void, unknown>;
+    next: Map<K, MultiTrie<K, V>>;
+    vals?: Set<V>;
+    constructor(pairs?: Nullable<Iterable<Pair<K[], V>>>, opts?: Partial<MultiTrieOpts<V>> | undefined);
+    [Symbol.iterator](): Generator<Pair<K, V>, void, any>;
+    keys(prefix?: K[], includePrefix?: boolean): Generator<K[], void, any>;
+    values(prefix?: K[]): Generator<V, void, any>;
+    entries(prefix?: K[], includePrefix?: boolean): Generator<Pair<K, V>, void, any>;
     clear(): void;
-    has(key: K): boolean;
-    hasPrefix(prefix: K): boolean;
-    get(key: K): Maybe<Set<V>>;
-    find(key: K): MultiTrie<K, V> | undefined;
+    has(key: K[]): boolean;
+    hasPrefix(prefix: K[]): boolean;
+    get(key: K[]): Maybe<Set<V>>;
+    find(key: K[]): MultiTrie<K, V> | undefined;
     /**
      * Returns longest known prefix for `key` as array. If array is
      * empty, the given key has no partial matches.
      *
      * @param key -
      */
-    knownPrefix(key: K): K[];
-    hasKnownPrefix(key: K): boolean;
-    add(key: K, val: V): void;
-    into(pairs: Iterable<[K, V]>): void;
-    delete(prefix: K, val?: V): boolean;
-    protected queueChildren(queue: [string, MultiTrie<any, any>][], prefix: string, sep?: string): void;
+    knownPrefix(key: K[]): K[];
+    hasKnownPrefix(key: K[]): boolean;
+    add(key: K[], val: V): void;
+    into(pairs: Iterable<[K[], V]>): void;
+    delete(prefix: K[], val?: V): boolean;
+    toJSON(): SerializedMultiTrie<V>;
+    protected iterate<T>(fn: Fn2<K[], MultiTrie<K, V>, Iterable<T>>, prefix?: K[], includePrefix?: boolean): Generator<T, void, any>;
 }
-export declare const defMultiTrie: <K extends ArrayLike<any>, V>(pairs?: Iterable<Pair<K, V>>, opts?: Partial<MultiTrieOpts<V>>) => MultiTrie<K, V>;
+export declare const defMultiTrie: <K, V>(pairs?: Nullable<Iterable<Pair<K[], V>>>, opts?: Partial<MultiTrieOpts<V>>) => MultiTrie<K, V>;
+export type SerializedMultiTrie<V> = {
+    next: Record<string, SerializedMultiTrie<V>>;
+    vals?: any[];
+};
+/**
+ * Reconstruct a {@link MultiTrie} from serialized JSON.
+ *
+ * @param src
+ * @param opts
+ */
+export declare const defMultiTrieFromJSON: <V>(src: SerializedMultiTrie<V>, opts?: Partial<MultiTrieOpts<V>>) => MultiTrie<string, V>;
 //# sourceMappingURL=multi-trie.d.ts.map

package/multi-trie.js

@@ -3,54 +3,28 @@ class MultiTrie {
     this.opts = opts;
     pairs && this.into(pairs);
   }
-  next = {};
+  next = /* @__PURE__ */ new Map();
   vals;
-  n = 0;
-  *[Symbol.iterator]() {
-    const queue = [["", this]];
-    while (queue.length) {
-      const [prefix, node] = queue.pop();
-      if (node.vals) {
-        for (let v of node.vals) yield [prefix, v];
-      } else {
-        node.queueChildren(queue, prefix);
-      }
-    }
+  [Symbol.iterator]() {
+    return this.iterate(
+      (key, node) => [...node.vals].map((v) => [key, v])
+    );
   }
-  *keys(sep = "", prefix = "") {
-    const queue = [[prefix, this]];
-    while (queue.length) {
-      const [key, node] = queue.pop();
-      if (node.vals) {
-        yield key;
-      } else {
-        node.queueChildren(queue, key, sep);
-      }
-    }
+  keys(prefix = [], includePrefix = true) {
+    return this.iterate((key) => [key], prefix, includePrefix);
   }
-  *values() {
-    const queue = [this];
-    while (queue.length) {
-      const node = queue.pop();
-      if (node.vals) {
-        yield* node.vals;
-      } else {
-        queue.push(...Object.values(node.next));
-      }
-    }
+  values(prefix) {
+    return this.iterate((_, node) => node.vals, prefix);
   }
-  *suffixes(prefix, withPrefix = false, sep = "") {
-    const node = this.find(prefix);
-    if (node) {
-      yield* node.keys(
-        sep,
-        withPrefix ? Array.isArray(prefix) ? prefix.join(sep) : prefix.toString() : ""
-      );
-    }
+  entries(prefix, includePrefix = true) {
+    return this.iterate(
+      (key, node) => [...node.vals].map((v) => [key, v]),
+      prefix,
+      includePrefix
+    );
   }
   clear() {
-    this.next = {};
-    this.n = 0;
+    this.next.clear();
     this.vals = void 0;
   }
   has(key) {
@@ -66,7 +40,7 @@ class MultiTrie {
   find(key) {
     let node = this;
     for (let i = 0, n = key.length; i < n; i++) {
-      node = node.next[key[i].toString()];
+      node = node.next.get(key[i]);
       if (!node) return;
     }
     return node;
@@ -81,8 +55,8 @@ class MultiTrie {
     let node = this;
     const prefix = [];
     for (let i = 0, n = key.length; i < n; i++) {
-      const k = key[i].toString();
-      const next = node.next[k];
+      const k = key[i];
+      const next = node.next.get(k);
       if (!next) break;
       prefix.push(k);
       node = next;
@@ -95,13 +69,18 @@ class MultiTrie {
   add(key, val) {
     let node = this;
     for (let i = 0, n = key.length; i < n; i++) {
-      const k = key[i].toString();
-      const next = node.next[k];
-      node = !next ? (node.n++, node.next[k] = new MultiTrie(null, this.opts)) : next;
+      const k = key[i];
+      const next = node.next.get(k);
+      if (!next) {
+        const newNode = new MultiTrie(null, this.opts);
+        node.next.set(k, newNode);
+        node = newNode;
+      } else {
+        node = next;
+      }
     }
     if (!node.vals) {
-      const ctor = this.opts?.vals;
-      node.vals = ctor ? ctor() : /* @__PURE__ */ new Set();
+      node.vals = this.opts?.values?.() ?? /* @__PURE__ */ new Set();
     }
     node.vals.add(val);
   }
@@ -118,10 +97,10 @@ class MultiTrie {
     let i = 0;
     let node = this;
     for (; i < n; i++) {
-      const k = prefix[i].toString();
+      const k = prefix[i];
       key.push(k);
       path.push(node);
-      node = node.next[k];
+      node = node.next.get(k);
       if (!node) return false;
     }
     if (val !== void 0) {
@@ -134,22 +113,54 @@ class MultiTrie {
       }
     }
     while (node = path[--i]) {
-      delete node.next[key[i]];
-      if (--node.n) break;
+      node.next.delete(key[i]);
+      if (node.next.size) break;
     }
     return true;
   }
-  queueChildren(queue, prefix, sep = "") {
-    prefix = prefix.length ? prefix + sep : prefix;
-    queue.push(
-      ...Object.keys(this.next).map(
-        (k) => [prefix + k, this.next[k]]
-      )
-    );
+  toJSON() {
+    return {
+      next: [...this.next].reduce(
+        (acc, [k, v]) => (acc[k] = v.toJSON(), acc),
+        {}
+      ),
+      vals: this.vals ? [...this.vals] : void 0
+    };
+  }
+  *iterate(fn, prefix = [], includePrefix = true) {
+    const root = this.find(prefix);
+    if (!root) return;
+    const queue = [
+      [includePrefix ? prefix : [], root]
+    ];
+    while (queue.length) {
+      const [key, node] = queue.pop();
+      if (node.vals) yield* fn(key, node);
+      queue.push(
+        ...[...node.next].map(
+          ([k, v]) => [key.concat(k), v]
+        )
+      );
+    }
   }
 }
 const defMultiTrie = (pairs, opts) => new MultiTrie(pairs, opts);
+const defMultiTrieFromJSON = (src, opts) => {
+  const res = defMultiTrie(null, opts);
+  const queue = [[[], src]];
+  while (queue.length) {
+    const [key, node] = queue.pop();
+    if (node.vals) {
+      for (let v of node.vals) res.add(key, v);
+    }
+    for (let [k, child] of Object.entries(node.next)) {
+      queue.push([[...key, k], child]);
+    }
+  }
+  return res;
+};
 export {
   MultiTrie,
-  defMultiTrie
+  defMultiTrie,
+  defMultiTrieFromJSON
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@thi.ng/trie",
-  "version": "1.1.28",
-  "description": "Trie-based map data structure with prefix search/query support",
+  "version": "2.0.0",
+  "description": "Trie-based ES6-like Map data structures with prefix search/query support",
   "type": "module",
   "module": "./index.js",
   "typings": "./index.d.ts",
@@ -39,7 +39,7 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.12.0"
+    "@thi.ng/api": "^8.12.1"
   },
   "devDependencies": {
     "esbuild": "^0.25.8",
@@ -47,13 +47,18 @@
     "typescript": "^5.9.2"
   },
   "keywords": [
+    "associative",
     "datastructure",
-    "equality",
     "iterator",
     "keys",
     "map",
     "prefix",
     "query",
+    "search",
+    "set",
+    "string",
+    "text",
+    "tree",
     "trie",
     "typescript"
   ],
@@ -88,5 +93,5 @@
     ],
     "year": 2020
   },
-  "gitHead": "d4e2e72dcdadf26da3400900f04f9eb0ebeb0a5b\n"
+  "gitHead": "f6ebc1302dc9211d588293aa0897173c6e54f4e5\n"
 }

package/trie-map.d.ts

@@ -1,13 +1,13 @@
-import type { IObjectOf, Maybe, Pair } from "@thi.ng/api";
+import type { Fn2, IObjectOf, Maybe, Pair } from "@thi.ng/api";
 export declare class TrieMap<T> {
-    protected next: IObjectOf<TrieMap<T>>;
-    protected val?: T;
+    next: IObjectOf<TrieMap<T>>;
+    val?: T;
     protected n: number;
     constructor(pairs?: Iterable<Pair<string, T>>);
-    [Symbol.iterator](): Generator<(string | (T & ({} | null)))[], void, unknown>;
-    keys(prefix?: string): Generator<string, void, unknown>;
-    values(): Generator<T & ({} | null), void, unknown>;
-    suffixes(prefix: string, withPrefix?: boolean): Generator<string, void, unknown>;
+    [Symbol.iterator](): Generator<Pair<string, T>, void, unknown>;
+    keys(prefix?: string, includePrefix?: boolean): Generator<string, void, unknown>;
+    values(prefix?: string): Generator<NonNullable<T>, void, unknown>;
+    entries(prefix?: string, includePrefix?: boolean): Generator<Pair<string, T>, void, unknown>;
     clear(): void;
     has(key: string): boolean;
     hasPrefix(prefix: string): boolean;
@@ -24,7 +24,18 @@ export declare class TrieMap<T> {
     set(key: string, val: T): void;
     into(pairs: Iterable<Pair<string, T>>): void;
     delete(prefix: string): boolean;
-    protected queueChildren(queue: [string, TrieMap<T>][], prefix: string): void;
+    protected iterate<V>(fn: Fn2<string, TrieMap<T>, V>, prefix?: string, includePrefix?: boolean): Generator<V, void, unknown>;
 }
 export declare const defTrieMap: <T>(pairs?: Iterable<Pair<string, T>>) => TrieMap<T>;
+export type SerializedTrieMap<T> = {
+    next: IObjectOf<SerializedTrieMap<T>>;
+    val?: T;
+};
+/**
+ * Reconstruct a {@link MultiTrie} from serialized JSON.
+ *
+ * @param src
+ * @param opts
+ */
+export declare const defTrieMapFromJSON: <V>(src: SerializedTrieMap<V>) => TrieMap<V>;
 //# sourceMappingURL=trie-map.d.ts.map

package/trie-map.js

@@ -5,44 +5,21 @@ class TrieMap {
   constructor(pairs) {
     pairs && this.into(pairs);
   }
-  *[Symbol.iterator]() {
-    const queue = [["", this]];
-    while (queue.length) {
-      const [prefix, node] = queue.pop();
-      if (node.val !== void 0) {
-        yield [prefix, node.val];
-      } else {
-        node.queueChildren(queue, prefix);
-      }
-    }
+  [Symbol.iterator]() {
+    return this.iterate((key, node) => [key, node.val]);
   }
-  *keys(prefix = "") {
-    const queue = [[prefix, this]];
-    while (queue.length) {
-      const [key, node] = queue.pop();
-      if (node.val !== void 0) {
-        yield key;
-      } else {
-        node.queueChildren(queue, key);
-      }
-    }
+  keys(prefix, includePrefix = true) {
+    return this.iterate((key) => key, prefix, includePrefix);
   }
-  *values() {
-    const queue = [this];
-    while (queue.length) {
-      const node = queue.pop();
-      if (node.val !== void 0) {
-        yield node.val;
-      } else {
-        queue.push(...Object.values(node.next));
-      }
-    }
+  values(prefix) {
+    return this.iterate((_, node) => node.val, prefix);
   }
-  *suffixes(prefix, withPrefix = false) {
-    const node = this.find(prefix);
-    if (node) {
-      yield* node.keys(withPrefix ? prefix : "");
-    }
+  entries(prefix, includePrefix = true) {
+    return this.iterate(
+      (key, node) => [key, node.val],
+      prefix,
+      includePrefix
+    );
   }
   clear() {
     this.next = {};
@@ -122,16 +99,38 @@ class TrieMap {
     }
     return true;
   }
-  queueChildren(queue, prefix) {
-    queue.push(
-      ...Object.keys(this.next).map(
-        (k) => [prefix + k, this.next[k]]
-      )
-    );
+  *iterate(fn, prefix = "", includePrefix = true) {
+    const root = this.find(prefix);
+    if (!root) return;
+    const queue = [
+      [includePrefix ? prefix : "", root]
+    ];
+    while (queue.length) {
+      const [key, node] = queue.pop();
+      if (node.val !== void 0) yield fn(key, node);
+      queue.push(
+        ...Object.entries(node.next).map(
+          ([k, v]) => [key + k, v]
+        )
+      );
+    }
   }
 }
 const defTrieMap = (pairs) => new TrieMap(pairs);
+const defTrieMapFromJSON = (src) => {
+  const res = defTrieMap();
+  const queue = [["", src]];
+  while (queue.length) {
+    const [key, node] = queue.pop();
+    if (node.val) res.set(key, node.val);
+    for (let [k, child] of Object.entries(node.next)) {
+      queue.push([key + k, child]);
+    }
+  }
+  return res;
+};
 export {
   TrieMap,
-  defTrieMap
+  defTrieMap,
+  defTrieMapFromJSON
 };