trie-typed 2.1.1 → 2.2.0

package/dist/cjs/index.cjs

@@ -0,0 +1,797 @@
+'use strict';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/data-structures/base/iterable-element-base.ts
+var IterableElementBase = class {
+  static {
+    __name(this, "IterableElementBase");
+  }
+  /**
+   * Create a new iterable base.
+   *
+   * @param options Optional behavior overrides. When provided, a `toElementFn`
+   * is used to convert a raw element (`R`) into a public element (`E`).
+   *
+   * @remarks
+   * Time O(1), Space O(1).
+   */
+  constructor(options) {
+    if (options) {
+      const { toElementFn } = options;
+      if (typeof toElementFn === "function") this._toElementFn = toElementFn;
+      else if (toElementFn) throw new TypeError("toElementFn must be a function type");
+    }
+  }
+  /**
+   * The converter used to transform a raw element (`R`) into a public element (`E`).
+   *
+   * @remarks
+   * Time O(1), Space O(1).
+   */
+  _toElementFn;
+  /**
+   * Exposes the current `toElementFn`, if configured.
+   *
+   * @returns The converter function or `undefined` when not set.
+   * @remarks
+   * Time O(1), Space O(1).
+   */
+  get toElementFn() {
+    return this._toElementFn;
+  }
+  /**
+   * Returns an iterator over the structure's elements.
+   *
+   * @param args Optional iterator arguments forwarded to the internal iterator.
+   * @returns An `IterableIterator<E>` that yields the elements in traversal order.
+   *
+   * @remarks
+   * Producing the iterator is O(1); consuming the entire iterator is Time O(n) with O(1) extra space.
+   */
+  *[Symbol.iterator](...args) {
+    yield* this._getIterator(...args);
+  }
+  /**
+   * Returns an iterator over the values (alias of the default iterator).
+   *
+   * @returns An `IterableIterator<E>` over all elements.
+   * @remarks
+   * Creating the iterator is O(1); full iteration is Time O(n), Space O(1).
+   */
+  *values() {
+    for (const item of this) yield item;
+  }
+  /**
+   * Tests whether all elements satisfy the predicate.
+   *
+   * @template TReturn
+   * @param predicate Function invoked for each element with signature `(value, index, self)`.
+   * @param thisArg Optional `this` binding for the predicate.
+   * @returns `true` if every element passes; otherwise `false`.
+   *
+   * @remarks
+   * Time O(n) in the worst case; may exit early when the first failure is found. Space O(1).
+   */
+  every(predicate, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      if (thisArg === void 0) {
+        if (!predicate(item, index++, this)) return false;
+      } else {
+        const fn = predicate;
+        if (!fn.call(thisArg, item, index++, this)) return false;
+      }
+    }
+    return true;
+  }
+  /**
+   * Tests whether at least one element satisfies the predicate.
+   *
+   * @param predicate Function invoked for each element with signature `(value, index, self)`.
+   * @param thisArg Optional `this` binding for the predicate.
+   * @returns `true` if any element passes; otherwise `false`.
+   *
+   * @remarks
+   * Time O(n) in the worst case; may exit early on first success. Space O(1).
+   */
+  some(predicate, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      if (thisArg === void 0) {
+        if (predicate(item, index++, this)) return true;
+      } else {
+        const fn = predicate;
+        if (fn.call(thisArg, item, index++, this)) return true;
+      }
+    }
+    return false;
+  }
+  /**
+   * Invokes a callback for each element in iteration order.
+   *
+   * @param callbackfn Function invoked per element with signature `(value, index, self)`.
+   * @param thisArg Optional `this` binding for the callback.
+   * @returns `void`.
+   *
+   * @remarks
+   * Time O(n), Space O(1).
+   */
+  forEach(callbackfn, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      if (thisArg === void 0) {
+        callbackfn(item, index++, this);
+      } else {
+        const fn = callbackfn;
+        fn.call(thisArg, item, index++, this);
+      }
+    }
+  }
+  // Implementation signature
+  find(predicate, thisArg) {
+    let index = 0;
+    for (const item of this) {
+      if (thisArg === void 0) {
+        if (predicate(item, index++, this)) return item;
+      } else {
+        const fn = predicate;
+        if (fn.call(thisArg, item, index++, this)) return item;
+      }
+    }
+    return;
+  }
+  /**
+   * Checks whether a strictly-equal element exists in the structure.
+   *
+   * @param element The element to test with `===` equality.
+   * @returns `true` if an equal element is found; otherwise `false`.
+   *
+   * @remarks
+   * Time O(n) in the worst case. Space O(1).
+   */
+  has(element) {
+    for (const ele of this) if (ele === element) return true;
+    return false;
+  }
+  /**
+   * Reduces all elements to a single accumulated value.
+   *
+   * @overload
+   * @param callbackfn Reducer of signature `(acc, value, index, self) => nextAcc`. The first element is used as the initial accumulator.
+   * @returns The final accumulated value typed as `E`.
+   *
+   * @overload
+   * @param callbackfn Reducer of signature `(acc, value, index, self) => nextAcc`.
+   * @param initialValue The initial accumulator value of type `E`.
+   * @returns The final accumulated value typed as `E`.
+   *
+   * @overload
+   * @template U The accumulator type when it differs from `E`.
+   * @param callbackfn Reducer of signature `(acc: U, value, index, self) => U`.
+   * @param initialValue The initial accumulator value of type `U`.
+   * @returns The final accumulated value typed as `U`.
+   *
+   * @remarks
+   * Time O(n), Space O(1). Throws if called on an empty structure without `initialValue`.
+   */
+  reduce(callbackfn, initialValue) {
+    let index = 0;
+    const iter = this[Symbol.iterator]();
+    let acc;
+    if (arguments.length >= 2) {
+      acc = initialValue;
+    } else {
+      const first = iter.next();
+      if (first.done) throw new TypeError("Reduce of empty structure with no initial value");
+      acc = first.value;
+      index = 1;
+    }
+    for (const value of iter) {
+      acc = callbackfn(acc, value, index++, this);
+    }
+    return acc;
+  }
+  /**
+   * Materializes the elements into a new array.
+   *
+   * @returns A shallow array copy of the iteration order.
+   * @remarks
+   * Time O(n), Space O(n).
+   */
+  toArray() {
+    return [...this];
+  }
+  /**
+   * Returns a representation of the structure suitable for quick visualization.
+   * Defaults to an array of elements; subclasses may override to provide richer visuals.
+   *
+   * @returns A visual representation (array by default).
+   * @remarks
+   * Time O(n), Space O(n).
+   */
+  toVisual() {
+    return [...this];
+  }
+  /**
+   * Prints `toVisual()` to the console. Intended for quick debugging.
+   *
+   * @returns `void`.
+   * @remarks
+   * Time O(n) due to materialization, Space O(n) for the intermediate representation.
+   */
+  print() {
+    console.log(this.toVisual());
+  }
+};
+
+// src/data-structures/trie/trie.ts
+var TrieNode = class {
+  static {
+    __name(this, "TrieNode");
+  }
+  /**
+   * Create a Trie node with a character key.
+   * @remarks Time O(1), Space O(1)
+   * @returns New TrieNode instance.
+   */
+  constructor(key) {
+    this._key = key;
+    this._isEnd = false;
+    this._children = /* @__PURE__ */ new Map();
+  }
+  _key;
+  /**
+   * Get the character key of this node.
+   * @remarks Time O(1), Space O(1)
+   * @returns Character key string.
+   */
+  get key() {
+    return this._key;
+  }
+  /**
+   * Set the character key of this node.
+   * @remarks Time O(1), Space O(1)
+   * @param value - New character key.
+   * @returns void
+   */
+  set key(value) {
+    this._key = value;
+  }
+  _children;
+  /**
+   * Get the child map of this node.
+   * @remarks Time O(1), Space O(1)
+   * @returns Map from character to child node.
+   */
+  get children() {
+    return this._children;
+  }
+  /**
+   * Replace the child map of this node.
+   * @remarks Time O(1), Space O(1)
+   * @param value - New map of character → node.
+   * @returns void
+   */
+  set children(value) {
+    this._children = value;
+  }
+  _isEnd;
+  /**
+   * Check whether this node marks the end of a word.
+   * @remarks Time O(1), Space O(1)
+   * @returns True if this node ends a word.
+   */
+  get isEnd() {
+    return this._isEnd;
+  }
+  /**
+   * Mark this node as the end of a word or not.
+   * @remarks Time O(1), Space O(1)
+   * @param value - Whether this node ends a word.
+   * @returns void
+   */
+  set isEnd(value) {
+    this._isEnd = value;
+  }
+};
+var Trie = class extends IterableElementBase {
+  static {
+    __name(this, "Trie");
+  }
+  /**
+   * Create a Trie and optionally bulk-insert words.
+   * @remarks Time O(totalChars), Space O(totalChars)
+   * @param [words] - Iterable of strings (or raw records if toElementFn is provided).
+   * @param [options] - Options such as toElementFn and caseSensitive.
+   * @returns New Trie instance.
+   */
+  constructor(words = [], options) {
+    super(options);
+    if (options) {
+      const { caseSensitive } = options;
+      if (caseSensitive !== void 0) this._caseSensitive = caseSensitive;
+    }
+    if (words) {
+      this.addMany(words);
+    }
+  }
+  _size = 0;
+  /**
+   * Get the number of stored words.
+   * @remarks Time O(1), Space O(1)
+   * @returns Word count.
+   */
+  get size() {
+    return this._size;
+  }
+  _caseSensitive = true;
+  /**
+   * Get whether comparisons are case-sensitive.
+   * @remarks Time O(1), Space O(1)
+   * @returns True if case-sensitive.
+   */
+  get caseSensitive() {
+    return this._caseSensitive;
+  }
+  _root = new TrieNode("");
+  /**
+   * Get the root node.
+   * @remarks Time O(1), Space O(1)
+   * @returns Root TrieNode.
+   */
+  get root() {
+    return this._root;
+  }
+  /**
+   * (Protected) Get total count for base class iteration.
+   * @remarks Time O(1), Space O(1)
+   * @returns Total number of elements.
+   */
+  get _total() {
+    return this._size;
+  }
+  /**
+   * Insert one word into the trie.
+   * @remarks Time O(L), Space O(L)
+   * @param word - Word to insert.
+   * @returns True if the word was newly added.
+   */
+  add(word) {
+    word = this._caseProcess(word);
+    let cur = this.root;
+    let isNewWord = false;
+    for (const c of word) {
+      let nodeC = cur.children.get(c);
+      if (!nodeC) {
+        nodeC = new TrieNode(c);
+        cur.children.set(c, nodeC);
+      }
+      cur = nodeC;
+    }
+    if (!cur.isEnd) {
+      isNewWord = true;
+      cur.isEnd = true;
+      this._size++;
+    }
+    return isNewWord;
+  }
+  /**
+   * Insert many words from an iterable.
+   * @remarks Time O(ΣL), Space O(ΣL)
+   * @param words - Iterable of strings (or raw records if toElementFn is provided).
+   * @returns Array of per-word 'added' flags.
+   */
+  addMany(words) {
+    const ans = [];
+    for (const word of words) {
+      if (this.toElementFn) {
+        ans.push(this.add(this.toElementFn(word)));
+      } else {
+        ans.push(this.add(word));
+      }
+    }
+    return ans;
+  }
+  /**
+   * Check whether a word exists.
+   * @remarks Time O(L), Space O(1)
+   * @param word - Word to search for.
+   * @returns True if present.
+   */
+  has(word) {
+    word = this._caseProcess(word);
+    let cur = this.root;
+    for (const c of word) {
+      const nodeC = cur.children.get(c);
+      if (!nodeC) return false;
+      cur = nodeC;
+    }
+    return cur.isEnd;
+  }
+  /**
+   * Check whether the trie is empty.
+   * @remarks Time O(1), Space O(1)
+   * @returns True if size is 0.
+   */
+  isEmpty() {
+    return this._size === 0;
+  }
+  /**
+   * Remove all words and reset to a fresh root.
+   * @remarks Time O(1), Space O(1)
+   * @returns void
+   */
+  clear() {
+    this._size = 0;
+    this._root = new TrieNode("");
+  }
+  /**
+   * Delete one word if present.
+   * @remarks Time O(L), Space O(1)
+   * @param word - Word to delete.
+   * @returns True if a word was removed.
+   */
+  delete(word) {
+    word = this._caseProcess(word);
+    let isDeleted = false;
+    const dfs = /* @__PURE__ */ __name((cur, i) => {
+      const char = word[i];
+      const child = cur.children.get(char);
+      if (child) {
+        if (i === word.length - 1) {
+          if (child.isEnd) {
+            if (child.children.size > 0) {
+              child.isEnd = false;
+            } else {
+              cur.children.delete(char);
+            }
+            isDeleted = true;
+            return true;
+          }
+          return false;
+        }
+        const res = dfs(child, i + 1);
+        if (res && !cur.isEnd && child.children.size === 0) {
+          cur.children.delete(char);
+          return true;
+        }
+        return false;
+      }
+      return false;
+    }, "dfs");
+    dfs(this.root, 0);
+    if (isDeleted) {
+      this._size--;
+    }
+    return isDeleted;
+  }
+  /**
+   * Compute the height (max depth) of the trie.
+   * @remarks Time O(N), Space O(H)
+   * @returns Maximum depth from root to a leaf.
+   */
+  getHeight() {
+    const startNode = this.root;
+    let maxDepth = 0;
+    if (startNode) {
+      const bfs = /* @__PURE__ */ __name((node, level) => {
+        if (level > maxDepth) {
+          maxDepth = level;
+        }
+        const { children } = node;
+        if (children) {
+          for (const child of children.entries()) {
+            bfs(child[1], level + 1);
+          }
+        }
+      }, "bfs");
+      bfs(startNode, 0);
+    }
+    return maxDepth;
+  }
+  /**
+   * Check whether input is a proper prefix of at least one word.
+   * @remarks Time O(L), Space O(1)
+   * @param input - String to test as prefix.
+   * @returns True if input is a prefix but not a full word.
+   */
+  hasPurePrefix(input) {
+    input = this._caseProcess(input);
+    let cur = this.root;
+    for (const c of input) {
+      const nodeC = cur.children.get(c);
+      if (!nodeC) return false;
+      cur = nodeC;
+    }
+    return !cur.isEnd;
+  }
+  /**
+   * Check whether any word starts with input.
+   * @remarks Time O(L), Space O(1)
+   * @param input - String to test as prefix.
+   * @returns True if input matches a path from root.
+   */
+  hasPrefix(input) {
+    input = this._caseProcess(input);
+    let cur = this.root;
+    for (const c of input) {
+      const nodeC = cur.children.get(c);
+      if (!nodeC) return false;
+      cur = nodeC;
+    }
+    return true;
+  }
+  /**
+   * Check whether the trie’s longest common prefix equals input.
+   * @remarks Time O(min(H,L)), Space O(1)
+   * @param input - Candidate longest common prefix.
+   * @returns True if input equals the common prefix.
+   */
+  hasCommonPrefix(input) {
+    input = this._caseProcess(input);
+    let commonPre = "";
+    const dfs = /* @__PURE__ */ __name((cur) => {
+      commonPre += cur.key;
+      if (commonPre === input) return;
+      if (cur.isEnd) return;
+      if (cur && cur.children && cur.children.size === 1) dfs(Array.from(cur.children.values())[0]);
+      else return;
+    }, "dfs");
+    dfs(this.root);
+    return commonPre === input;
+  }
+  /**
+   * Return the longest common prefix among all words.
+   * @remarks Time O(H), Space O(1)
+   * @returns The longest common prefix string.
+   */
+  getLongestCommonPrefix() {
+    let commonPre = "";
+    const dfs = /* @__PURE__ */ __name((cur) => {
+      commonPre += cur.key;
+      if (cur.isEnd) return;
+      if (cur && cur.children && cur.children.size === 1) dfs(Array.from(cur.children.values())[0]);
+      else return;
+    }, "dfs");
+    dfs(this.root);
+    return commonPre;
+  }
+  /**
+   * Collect words under a prefix up to a maximum count.
+   * @remarks Time O(K·L), Space O(K·L)
+   * @param [prefix] - Prefix to match; default empty string for root.
+   * @param [max] - Maximum number of words to return; default is Number.MAX_SAFE_INTEGER.
+   * @param [isAllWhenEmptyPrefix] - When true, collect from root even if prefix is empty.
+   * @returns Array of collected words (at most max).
+   */
+  getWords(prefix = "", max = Number.MAX_SAFE_INTEGER, isAllWhenEmptyPrefix = false) {
+    prefix = this._caseProcess(prefix);
+    const words = [];
+    let found = 0;
+    function dfs(node, word) {
+      for (const char of node.children.keys()) {
+        const charNode = node.children.get(char);
+        if (charNode !== void 0) {
+          dfs(charNode, word.concat(char));
+        }
+      }
+      if (node.isEnd) {
+        if (found > max - 1) return;
+        words.push(word);
+        found++;
+      }
+    }
+    __name(dfs, "dfs");
+    let startNode = this.root;
+    if (prefix) {
+      for (const c of prefix) {
+        const nodeC = startNode.children.get(c);
+        if (nodeC) {
+          startNode = nodeC;
+        } else {
+          return [];
+        }
+      }
+    }
+    if (isAllWhenEmptyPrefix || startNode !== this.root) dfs(startNode, prefix);
+    return words;
+  }
+  /**
+   * Deep clone this trie by iterating and inserting all words.
+   * @remarks Time O(ΣL), Space O(ΣL)
+   * @returns A new trie with the same words and options.
+   */
+  clone() {
+    const next = this._createInstance();
+    for (const x of this) next.add(x);
+    return next;
+  }
+  /**
+   * Filter words into a new trie of the same class.
+   * @remarks Time O(ΣL), Space O(ΣL)
+   * @param predicate - Predicate (word, index, trie) → boolean to keep word.
+   * @param [thisArg] - Value for `this` inside the predicate.
+   * @returns A new trie containing words that satisfy the predicate.
+   */
+  filter(predicate, thisArg) {
+    const results = this._createInstance();
+    let index = 0;
+    for (const word of this) {
+      if (predicate.call(thisArg, word, index, this)) {
+        results.add(word);
+      }
+      index++;
+    }
+    return results;
+  }
+  map(callback, options, thisArg) {
+    const newTrie = this._createLike([], options);
+    let i = 0;
+    for (const x of this) {
+      const v = thisArg === void 0 ? callback(x, i++, this) : callback.call(thisArg, x, i++, this);
+      if (typeof v !== "string") {
+        throw new TypeError(`Trie.map callback must return string; got ${typeof v}`);
+      }
+      newTrie.add(v);
+    }
+    return newTrie;
+  }
+  /**
+   * Map words into a new trie of the same element type.
+   * @remarks Time O(ΣL), Space O(ΣL)
+   * @param callback - Mapping function (word, index, trie) → string.
+   * @param [thisArg] - Value for `this` inside the callback.
+   * @returns A new trie with mapped words.
+   */
+  mapSame(callback, thisArg) {
+    const next = this._createInstance();
+    let i = 0;
+    for (const key of this) {
+      const mapped = thisArg === void 0 ? callback(key, i++, this) : callback.call(thisArg, key, i++, this);
+      next.add(mapped);
+    }
+    return next;
+  }
+  /**
+   * (Protected) Create an empty instance of the same concrete class.
+   * @remarks Time O(1), Space O(1)
+   * @param [options] - Options forwarded to the constructor.
+   * @returns An empty like-kind trie instance.
+   */
+  _createInstance(options) {
+    const Ctor = this.constructor;
+    const next = new Ctor([], {
+      toElementFn: this.toElementFn,
+      caseSensitive: this.caseSensitive,
+      ...options ?? {}
+    });
+    return next;
+  }
+  /**
+   * (Protected) Create a like-kind trie and seed it from an iterable.
+   * @remarks Time O(ΣL), Space O(ΣL)
+   * @template RM
+   * @param [elements] - Iterable used to seed the new trie.
+   * @param [options] - Options forwarded to the constructor.
+   * @returns A like-kind Trie instance.
+   */
+  _createLike(elements = [], options) {
+    const Ctor = this.constructor;
+    return new Ctor(elements, options);
+  }
+  /**
+   * (Protected) Spawn an empty like-kind trie instance.
+   * @remarks Time O(1), Space O(1)
+   * @template RM
+   * @param [options] - Options forwarded to the constructor.
+   * @returns An empty like-kind Trie instance.
+   */
+  _spawnLike(options) {
+    return this._createLike([], options);
+  }
+  /**
+   * (Protected) Iterate all words in lexicographic order of edges.
+   * @remarks Time O(ΣL), Space O(H)
+   * @returns Iterator of words.
+   */
+  *_getIterator() {
+    function* _dfs(node, path) {
+      if (node.isEnd) {
+        yield path;
+      }
+      for (const [char, childNode] of node.children) {
+        yield* _dfs(childNode, path + char);
+      }
+    }
+    __name(_dfs, "_dfs");
+    yield* _dfs(this.root, "");
+  }
+  /**
+   * (Protected) Normalize a string according to case sensitivity.
+   * @remarks Time O(L), Space O(L)
+   * @param str - Input string to normalize.
+   * @returns Normalized string based on caseSensitive.
+   */
+  _caseProcess(str) {
+    if (!this._caseSensitive) {
+      str = str.toLowerCase();
+    }
+    return str;
+  }
+};
+
+// src/utils/utils.ts
+function isPrimitiveComparable(value) {
+  const valueType = typeof value;
+  if (valueType === "number") return true;
+  return valueType === "bigint" || valueType === "string" || valueType === "boolean";
+}
+__name(isPrimitiveComparable, "isPrimitiveComparable");
+function tryObjectToPrimitive(obj) {
+  if (typeof obj.valueOf === "function") {
+    const valueOfResult = obj.valueOf();
+    if (valueOfResult !== obj) {
+      if (isPrimitiveComparable(valueOfResult)) return valueOfResult;
+      if (typeof valueOfResult === "object" && valueOfResult !== null) return tryObjectToPrimitive(valueOfResult);
+    }
+  }
+  if (typeof obj.toString === "function") {
+    const stringResult = obj.toString();
+    if (stringResult !== "[object Object]") return stringResult;
+  }
+  return null;
+}
+__name(tryObjectToPrimitive, "tryObjectToPrimitive");
+function isComparable(value, isForceObjectComparable = false) {
+  if (value === null || value === void 0) return false;
+  if (isPrimitiveComparable(value)) return true;
+  if (typeof value !== "object") return false;
+  if (value instanceof Date) return true;
+  if (isForceObjectComparable) return true;
+  const comparableValue = tryObjectToPrimitive(value);
+  if (comparableValue === null || comparableValue === void 0) return false;
+  return isPrimitiveComparable(comparableValue);
+}
+__name(isComparable, "isComparable");
+
+// src/common/index.ts
+var DFSOperation = /* @__PURE__ */ ((DFSOperation2) => {
+  DFSOperation2[DFSOperation2["VISIT"] = 0] = "VISIT";
+  DFSOperation2[DFSOperation2["PROCESS"] = 1] = "PROCESS";
+  return DFSOperation2;
+})(DFSOperation || {});
+var Range = class {
+  constructor(low, high, includeLow = true, includeHigh = true) {
+    this.low = low;
+    this.high = high;
+    this.includeLow = includeLow;
+    this.includeHigh = includeHigh;
+    if (!(isComparable(low) && isComparable(high))) throw new RangeError("low or high is not comparable");
+    if (low > high) throw new RangeError("low must be less than or equal to high");
+  }
+  static {
+    __name(this, "Range");
+  }
+  // Determine whether a key is within the range
+  isInRange(key, comparator) {
+    const lowCheck = this.includeLow ? comparator(key, this.low) >= 0 : comparator(key, this.low) > 0;
+    const highCheck = this.includeHigh ? comparator(key, this.high) <= 0 : comparator(key, this.high) < 0;
+    return lowCheck && highCheck;
+  }
+};
+/**
+ * data-structure-typed
+ *
+ * @author Pablo Zeng
+ * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+
+exports.DFSOperation = DFSOperation;
+exports.Range = Range;
+exports.Trie = Trie;
+exports.TrieNode = TrieNode;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map