trie-typed 2.4.4 → 2.5.0

package/README.md

@@ -35,36 +35,6 @@ yarn add trie-typed
 
 [//]: # (No deletion!!! Start of Example Replace Section)
 
-### basic Trie creation and add words
-```typescript
- // 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;
-```
-
-### Trie getWords and prefix search
-```typescript
- 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');
-```
-
 ### Trie isPrefix and isAbsolutePrefix checks
 ```typescript
  const trie = new Trie(['tree', 'trial', 'trick', 'trip', 'trie']);
@@ -82,25 +52,6 @@ yarn add trie-typed
     console.log(trie.size); // 5;
 ```
 
-### Trie delete and iteration
-```typescript
- 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;
-```
-
 ### Trie for autocomplete search index
 ```typescript
  // Trie is perfect for autocomplete: O(m + k) where m is prefix length, k is results

package/dist/cjs/index.cjs

@@ -226,6 +226,55 @@ var IterableElementBase = class {
   }
 };
 
+// src/common/error.ts
+var ERR = {
+  // Range / index
+  indexOutOfRange: /* @__PURE__ */ __name((index, min, max, ctx) => `${ctx ? ctx + ": " : ""}Index ${index} is out of range [${min}, ${max}].`, "indexOutOfRange"),
+  invalidIndex: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Index must be an integer.`, "invalidIndex"),
+  // Type / argument
+  invalidArgument: /* @__PURE__ */ __name((reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`, "invalidArgument"),
+  comparatorRequired: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Comparator is required for non-number/non-string/non-Date keys.`, "comparatorRequired"),
+  invalidKey: /* @__PURE__ */ __name((reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`, "invalidKey"),
+  notAFunction: /* @__PURE__ */ __name((name, ctx) => `${ctx ? ctx + ": " : ""}${name} must be a function.`, "notAFunction"),
+  invalidEntry: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Each entry must be a [key, value] tuple.`, "invalidEntry"),
+  invalidNaN: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}NaN is not a valid key.`, "invalidNaN"),
+  invalidDate: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Invalid Date key.`, "invalidDate"),
+  reduceEmpty: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Reduce of empty structure with no initial value.`, "reduceEmpty"),
+  callbackReturnType: /* @__PURE__ */ __name((expected, got, ctx) => `${ctx ? ctx + ": " : ""}Callback must return ${expected}; got ${got}.`, "callbackReturnType"),
+  // State / operation
+  invalidOperation: /* @__PURE__ */ __name((reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`, "invalidOperation"),
+  // Matrix
+  matrixDimensionMismatch: /* @__PURE__ */ __name((op) => `Matrix: Dimensions must be compatible for ${op}.`, "matrixDimensionMismatch"),
+  matrixSingular: /* @__PURE__ */ __name(() => "Matrix: Singular matrix, inverse does not exist.", "matrixSingular"),
+  matrixNotSquare: /* @__PURE__ */ __name(() => "Matrix: Must be square for inversion.", "matrixNotSquare"),
+  matrixNotRectangular: /* @__PURE__ */ __name(() => "Matrix: Must be rectangular for transposition.", "matrixNotRectangular"),
+  matrixRowMismatch: /* @__PURE__ */ __name((expected, got) => `Matrix: Expected row length ${expected}, but got ${got}.`, "matrixRowMismatch")
+};
+
+// 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;
+  }
+  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;
+  }
+};
+
 // src/data-structures/trie/trie.ts
 var TrieNode = class {
   static {
@@ -353,11 +402,37 @@ var Trie = class extends IterableElementBase {
     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.
-   */
+    * 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.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @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) {
     word = this._caseProcess(word);
     let cur = this.root;
@@ -378,11 +453,26 @@ var Trie = class extends IterableElementBase {
     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.
-   */
+    * 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.
+    
+    
+    
+    
+    
+    
+    
+    
+     * @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) {
     const ans = [];
     for (const word of words) {
@@ -395,11 +485,29 @@ var Trie = class extends IterableElementBase {
     return ans;
   }
   /**
-   * Check whether a word exists.
-   * @remarks Time O(L), Space O(1)
-   * @param word - Word to search for.
-   * @returns True if present.
-   */
+    * Check whether a word exists.
+    * @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;
+    */
   has(word) {
     word = this._caseProcess(word);
     let cur = this.root;
@@ -411,28 +519,83 @@ var Trie = class extends IterableElementBase {
     return cur.isEnd;
   }
   /**
-   * Check whether the trie is empty.
-   * @remarks Time O(1), Space O(1)
-   * @returns True if size is 0.
-   */
+    * 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;
+    */
   isEmpty() {
     return this._size === 0;
   }
   /**
-   * Remove all words and reset to a fresh root.
-   * @remarks Time O(1), Space O(1)
-   * @returns void
-   */
+    * 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;
+    */
   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 one word if present.
+    * @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;
+    */
   delete(word) {
     word = this._caseProcess(word);
     let isDeleted = false;
@@ -508,11 +671,29 @@ var Trie = class extends IterableElementBase {
     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.
-   */
+    * 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.
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @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) {
     input = this._caseProcess(input);
     let cur = this.root;
@@ -543,10 +724,26 @@ var Trie = class extends IterableElementBase {
     return commonPre === input;
   }
   /**
-   * Return the longest common prefix among all words.
-   * @remarks Time O(H), Space O(1)
-   * @returns The longest common prefix string.
-   */
+    * 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';
+    */
   getLongestCommonPrefix() {
     let commonPre = "";
     const dfs = /* @__PURE__ */ __name((cur) => {
@@ -559,13 +756,35 @@ var Trie = class extends IterableElementBase {
     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).
-   */
+    * 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).
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+    
+     * @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) {
     prefix = this._caseProcess(prefix);
     const words = [];
@@ -596,22 +815,49 @@ var Trie = class extends IterableElementBase {
     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.
-   */
+    * 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;
+    */
   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 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.
+    
+    
+    
+    
+    
+    
+    
+    
+     * @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, thisArg) {
     const results = this._createInstance();
     let index = 0;
@@ -629,7 +875,7 @@ var Trie = class extends IterableElementBase {
     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}`);
+        throw new TypeError(ERR.callbackReturnType("string", typeof v, "Trie.map"));
       }
       newTrie.add(v);
     }
@@ -717,30 +963,6 @@ var Trie = class extends IterableElementBase {
     return str;
   }
 };
-
-// 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;
-  }
-  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
  *
@@ -750,6 +972,7 @@ var Range = class {
  */
 
 exports.DFSOperation = DFSOperation;
+exports.ERR = ERR;
 exports.Range = Range;
 exports.Trie = Trie;
 exports.TrieNode = TrieNode;