data-structure-typed 2.5.3 → 2.6.1

package/src/data-structures/trie/trie.ts

@@ -5,7 +5,6 @@
  * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
  * @license MIT License
  */
-
 import type { ElementCallback, TrieOptions } from '../../types';
 import { IterableElementBase } from '../base';
 import { ERR, raise } from '../../common';
@@ -20,7 +19,6 @@ export class TrieNode {
    * @remarks Time O(1), Space O(1)
    * @returns New TrieNode instance.
    */
-
   constructor(key: string) {
     this._key = key;
     this._isEnd = false;
@@ -34,7 +32,6 @@ export class TrieNode {
    * @remarks Time O(1), Space O(1)
    * @returns Character key string.
    */
-
   get key(): string {
     return this._key;
   }
@@ -45,7 +42,6 @@ export class TrieNode {
    * @param value - New character key.
    * @returns void
    */
-
   set key(value: string) {
     this._key = value;
   }
@@ -57,7 +53,6 @@ export class TrieNode {
    * @remarks Time O(1), Space O(1)
    * @returns Map from character to child node.
    */
-
   get children(): Map<string, TrieNode> {
     return this._children;
   }
@@ -68,7 +63,6 @@ export class TrieNode {
    * @param value - New map of character → node.
    * @returns void
    */
-
   set children(value: Map<string, TrieNode>) {
     this._children = value;
   }
@@ -80,7 +74,6 @@ export class TrieNode {
    * @remarks Time O(1), Space O(1)
    * @returns True if this node ends a word.
    */
-
   get isEnd(): boolean {
     return this._isEnd;
   }
@@ -91,7 +84,6 @@ export class TrieNode {
    * @param value - Whether this node ends a word.
    * @returns void
    */
-
   set isEnd(value: boolean) {
     this._isEnd = value;
   }
@@ -221,7 +213,6 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * @param [options] - Options such as toElementFn and caseSensitive.
    * @returns New Trie instance.
    */
-
   constructor(words: Iterable<string> | Iterable<R> = [], options?: TrieOptions<R>) {
     super(options);
     if (options) {
@@ -240,7 +231,6 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * @remarks Time O(1), Space O(1)
    * @returns Word count.
    */
-
   get size(): number {
     return this._size;
   }
@@ -252,7 +242,6 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * @remarks Time O(1), Space O(1)
    * @returns True if case-sensitive.
    */
-
   get caseSensitive(): boolean {
     return this._caseSensitive;
   }
@@ -264,7 +253,6 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * @remarks Time O(1), Space O(1)
    * @returns Root TrieNode.
    */
-
   get root() {
     return this._root;
   }
@@ -274,7 +262,6 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * @remarks Time O(1), Space O(1)
    * @returns Total number of elements.
    */
-
   protected get _total() {
     return this._size;
   }
@@ -284,62 +271,22 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * @remarks Time O(L), Space O(L)
    * @param word - Word to insert.
    * @returns True if the word was newly added.
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // basic Trie creation and add words
- *  // Create a simple Trie with initial words
- *     const trie = new Trie(['apple', 'app', 'apply']);
- *
- *     // Verify size
- *     console.log(trie.size); // 3;
- *
- *     // Check if words exist
- *     console.log(trie.has('apple')); // true;
- *     console.log(trie.has('app')); // true;
- *
- *     // Add a new word
- *     trie.add('application');
- *     console.log(trie.size); // 4;
+   * @example
+   * // basic Trie creation and add words
+   *  // Create a simple Trie with initial words
+   *     const trie = new Trie(['apple', 'app', 'apply']);
+   *
+   *     // Verify size
+   *     console.log(trie.size); // 3;
+   *
+   *     // Check if words exist
+   *     console.log(trie.has('apple')); // true;
+   *     console.log(trie.has('app')); // true;
+   *
+   *     // Add a new word
+   *     trie.add('application');
+   *     console.log(trie.size); // 4;
    */
-
   add(word: string): boolean {
     word = this._caseProcess(word);
     let cur = this.root;
@@ -365,51 +312,14 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * @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.
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Add multiple words
- *  const trie = new Trie();
- *     trie.addMany(['cat', 'car', 'card']);
- *     console.log(trie.has('cat')); // true;
- *     console.log(trie.has('car')); // true;
- *     console.log(trie.size); // 3;
+   * @example
+   * // Add multiple words
+   *  const trie = new Trie();
+   *     trie.addMany(['cat', 'car', 'card']);
+   *     console.log(trie.has('cat')); // true;
+   *     console.log(trie.has('car')); // true;
+   *     console.log(trie.size); // 3;
    */
-
   addMany(words: Iterable<string> | Iterable<R>): boolean[] {
     const ans: boolean[] = [];
     for (const word of words) {
@@ -427,54 +337,14 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * @remarks Time O(L), Space O(1)
    * @param word - Word to search for.
    * @returns True if present.
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Check if a word exists
- *  const dict = new Trie(['apple', 'app', 'application']);
- *
- *     console.log(dict.has('app')); // true;
- *     console.log(dict.has('apple')); // true;
- *     console.log(dict.has('ap')); // false;
+   * @example
+   * // Check if a word exists
+   *  const dict = new Trie(['apple', 'app', 'application']);
+   *
+   *     console.log(dict.has('app')); // true;
+   *     console.log(dict.has('apple')); // true;
+   *     console.log(dict.has('ap')); // false;
    */
-
   override has(word: string): boolean {
     word = this._caseProcess(word);
     let cur = this.root;
@@ -490,50 +360,13 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * Check whether the trie is empty.
    * @remarks Time O(1), Space O(1)
    * @returns True if size is 0.
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Check if empty
- *  const trie = new Trie();
- *     console.log(trie.isEmpty()); // true;
- *     trie.add('word');
- *     console.log(trie.isEmpty()); // false;
+   * @example
+   * // Check if empty
+   *  const trie = new Trie();
+   *     console.log(trie.isEmpty()); // true;
+   *     trie.add('word');
+   *     console.log(trie.isEmpty()); // false;
    */
-
   isEmpty(): boolean {
     return this._size === 0;
   }
@@ -542,49 +375,12 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * Remove all words and reset to a fresh root.
    * @remarks Time O(1), Space O(1)
    * @returns void
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Remove all words
- *  const trie = new Trie(['a', 'b', 'c']);
- *     trie.clear();
- *     console.log(trie.isEmpty()); // true;
+   * @example
+   * // Remove all words
+   *  const trie = new Trie(['a', 'b', 'c']);
+   *     trie.clear();
+   *     console.log(trie.isEmpty()); // true;
    */
-
   clear(): void {
     this._size = 0;
     this._root = new TrieNode('');
@@ -595,64 +391,24 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * @remarks Time O(L), Space O(1)
    * @param word - Word to delete.
    * @returns True if a word was removed.
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Trie delete and iteration
- *  const trie = new Trie(['car', 'card', 'care', 'careful', 'can', 'cat']);
- *
- *     // Delete a word
- *     trie.delete('card');
- *     console.log(trie.has('card')); // false;
- *
- *     // Word with same prefix still exists
- *     console.log(trie.has('care')); // true;
- *
- *     // Size decreased
- *     console.log(trie.size); // 5;
- *
- *     // Iterate through all words
- *     const allWords = [...trie];
- *     console.log(allWords.length); // 5;
+   * @example
+   * // Trie delete and iteration
+   *  const trie = new Trie(['car', 'card', 'care', 'careful', 'can', 'cat']);
+   *
+   *     // Delete a word
+   *     trie.delete('card');
+   *     console.log(trie.has('card')); // false;
+   *
+   *     // Word with same prefix still exists
+   *     console.log(trie.has('care')); // true;
+   *
+   *     // Size decreased
+   *     console.log(trie.size); // 5;
+   *
+   *     // Iterate through all words
+   *     const allWords = [...trie];
+   *     console.log(allWords.length); // 5;
    */
-
   delete(word: string): boolean {
     word = this._caseProcess(word);
     let isDeleted = false;
@@ -681,7 +437,6 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
       }
       return false;
     };
-
     dfs(this.root, 0);
     if (isDeleted) {
       this._size--;
@@ -694,7 +449,6 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * @remarks Time O(N), Space O(H)
    * @returns Maximum depth from root to a leaf.
    */
-
   getHeight(): number {
     const startNode = this.root;
     let maxDepth = 0;
@@ -721,7 +475,6 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * @param input - String to test as prefix.
    * @returns True if input is a prefix but not a full word.
    */
-
   hasPurePrefix(input: string): boolean {
     input = this._caseProcess(input);
     let cur = this.root;
@@ -738,54 +491,14 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * @remarks Time O(L), Space O(1)
    * @param input - String to test as prefix.
    * @returns True if input matches a path from root.
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Check if a prefix exists
- *  const trie = new Trie(['hello', 'help', 'world']);
- *
- *     console.log(trie.hasPrefix('hel')); // true;
- *     console.log(trie.hasPrefix('wor')); // true;
- *     console.log(trie.hasPrefix('xyz')); // false;
+   * @example
+   * // Check if a prefix exists
+   *  const trie = new Trie(['hello', 'help', 'world']);
+   *
+   *     console.log(trie.hasPrefix('hel')); // true;
+   *     console.log(trie.hasPrefix('wor')); // true;
+   *     console.log(trie.hasPrefix('xyz')); // false;
    */
-
   hasPrefix(input: string): boolean {
     input = this._caseProcess(input);
     let cur = this.root;
@@ -803,7 +516,6 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * @param input - Candidate longest common prefix.
    * @returns True if input equals the common prefix.
    */
-
   hasCommonPrefix(input: string): boolean {
     input = this._caseProcess(input);
     let commonPre = '';
@@ -822,52 +534,12 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * Return the longest common prefix among all words.
    * @remarks Time O(H), Space O(1)
    * @returns The longest common prefix string.
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Find shared prefix
- *  const trie = new Trie(['flower', 'flow', 'flight']);
- *
- *     console.log(trie.getLongestCommonPrefix()); // 'fl';
+   * @example
+   * // Find shared prefix
+   *  const trie = new Trie(['flower', 'flow', 'flight']);
+   *
+   *     console.log(trie.getLongestCommonPrefix()); // 'fl';
    */
-
   getLongestCommonPrefix(): string {
     let commonPre = '';
     const dfs = (cur: TrieNode) => {
@@ -887,63 +559,22 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * @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).
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Trie getWords and prefix search
- *  const trie = new Trie(['apple', 'app', 'apply', 'application', 'apricot']);
- *
- *     // Get all words with prefix 'app'
- *     const appWords = trie.getWords('app');
- *     console.log(appWords); // contains 'app';
- *     console.log(appWords); // contains 'apple';
- *     console.log(appWords); // contains 'apply';
- *     console.log(appWords); // contains 'application';
- *     expect(appWords).not.toContain('apricot');
+   * @example
+   * // Trie getWords and prefix search
+   *  const trie = new Trie(['apple', 'app', 'apply', 'application', 'apricot']);
+   *
+   *     // Get all words with prefix 'app'
+   *     const appWords = trie.getWords('app');
+   *     console.log(appWords); // contains 'app';
+   *     console.log(appWords); // contains 'apple';
+   *     console.log(appWords); // contains 'apply';
+   *     console.log(appWords); // contains 'application';
+   *     expect(appWords).not.toContain('apricot');
    */
-
   getWords(prefix = '', max = Number.MAX_SAFE_INTEGER, isAllWhenEmptyPrefix = false): string[] {
     prefix = this._caseProcess(prefix);
     const words: string[] = [];
     let found = 0;
-
     const dfs = (node: TrieNode, word: string): void => {
       for (const [char, childNode] of node.children) {
         if (found >= max) return;
@@ -955,9 +586,7 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
         found++;
       }
     };
-
     let startNode = this.root;
-
     if (prefix) {
       for (const c of prefix) {
         const nodeC = startNode.children.get(c);
@@ -968,9 +597,7 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
         }
       }
     }
-
     if (isAllWhenEmptyPrefix || startNode !== this.root) dfs(startNode, prefix);
-
     return words;
   }
 
@@ -978,50 +605,13 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * 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.
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Create independent copy
- *  const trie = new Trie(['hello', 'world']);
- *     const copy = trie.clone();
- *     copy.delete('hello');
- *     console.log(trie.has('hello')); // true;
+   * @example
+   * // Create independent copy
+   *  const trie = new Trie(['hello', 'world']);
+   *     const copy = trie.clone();
+   *     copy.delete('hello');
+   *     console.log(trie.has('hello')); // true;
    */
-
   clone(): this {
     const next = this._createInstance();
     for (const x of this) next.add(x);
@@ -1034,49 +624,12 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * @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.
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Filter words
- *  const trie = new Trie(['cat', 'car', 'dog', 'card']);
- *     const result = trie.filter(w => w.startsWith('ca'));
- *     console.log(result.size); // 3;
+   * @example
+   * // Filter words
+   *  const trie = new Trie(['cat', 'car', 'dog', 'card']);
+   *     const result = trie.filter(w => w.startsWith('ca'));
+   *     console.log(result.size); // 3;
    */
-
   filter(predicate: ElementCallback<string, R, boolean>, thisArg?: unknown): this {
     const results = this._createInstance();
     let index = 0;
@@ -1089,49 +642,13 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
     return results;
   }
 
-    /**
+  /**
    * Transform words
-  
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-   
-    * @example
- * // Transform words
- *  const trie = new Trie(['hello', 'world']);
- *     const upper = trie.map(w => w.toUpperCase());
- *     console.log(upper.has('HELLO')); // true;
+   * @example
+   * // Transform words
+   *  const trie = new Trie(['hello', 'world']);
+   *     const upper = trie.map(w => w.toUpperCase());
+   *     console.log(upper.has('HELLO')); // true;
    */
   map<RM>(callback: ElementCallback<string, R, string>, options?: TrieOptions<RM>, thisArg?: unknown): Trie<RM>;
 
@@ -1145,13 +662,11 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * @param [thisArg] - Value for `this` inside the callback.
    * @returns A new Trie constructed from mapped words.
    */
-
   map<EM, RM>(
     callback: ElementCallback<string, R, EM>,
     options?: TrieOptions<RM>,
     thisArg?: unknown
   ): IterableElementBase<EM, RM>;
-
   map<EM, RM>(callback: ElementCallback<string, R, EM>, options?: TrieOptions<RM>, thisArg?: unknown): any {
     const newTrie = this._createLike<RM>([], options);
     let i = 0;
@@ -1172,7 +687,6 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * @param [thisArg] - Value for `this` inside the callback.
    * @returns A new trie with mapped words.
    */
-
   mapSame(callback: ElementCallback<string, R, string>, thisArg?: unknown): this {
     const next = this._createInstance();
     let i = 0;
@@ -1189,12 +703,8 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * @param [options] - Options forwarded to the constructor.
    * @returns An empty like-kind trie instance.
    */
-
   protected _createInstance(options?: TrieOptions<R>): this {
-    const Ctor = this.constructor as new (
-      elements?: Iterable<string> | Iterable<R>,
-      options?: TrieOptions<R>
-    ) => this;
+    const Ctor = this.constructor as new (elements?: Iterable<string> | Iterable<R>, options?: TrieOptions<R>) => this;
     return new Ctor([], {
       toElementFn: this.toElementFn,
       caseSensitive: this.caseSensitive,
@@ -1210,7 +720,6 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * @param [options] - Options forwarded to the constructor.
    * @returns A like-kind Trie instance.
    */
-
   protected _createLike<RM>(elements: Iterable<string> | Iterable<RM> = [], options?: TrieOptions<RM>): Trie<RM> {
     const Ctor = this.constructor as new (
       elements?: Iterable<string> | Iterable<RM>,
@@ -1226,7 +735,6 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * @param [options] - Options forwarded to the constructor.
    * @returns An empty like-kind Trie instance.
    */
-
   protected _spawnLike<RM>(options?: TrieOptions<RM>): Trie<RM> {
     return this._createLike<RM>([], options);
   }
@@ -1236,7 +744,6 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * @remarks Time O(ΣL), Space O(H)
    * @returns Iterator of words.
    */
-
   protected *_getIterator(): IterableIterator<string> {
     function* _dfs(node: TrieNode, path: string): IterableIterator<string> {
       if (node.isEnd) {
@@ -1256,7 +763,6 @@ export class Trie<R = any> extends IterableElementBase<string, R> {
    * @param str - Input string to normalize.
    * @returns Normalized string based on caseSensitive.
    */
-
   protected _caseProcess(str: string) {
     if (!this._caseSensitive) {
       str = str.toLowerCase();