cmpstr 3.2.1 → 3.2.2

package/dist/esm/utils/Normalizer.mjs

@@ -1,4 +1,5 @@
-// CmpStr v3.2.1 build-3439ccb-260130 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.2.2 build-bb61120-260311 by Paul Köhler @komed3 / MIT License
+import { ErrorUtil } from './Errors.mjs';
 import { HashTable } from './HashTable.mjs';
 
 class Normalizer {
@@ -15,42 +16,62 @@ class Normalizer {
     return Array.from(new Set(flags)).sort().join('');
   }
   static getPipeline(flags) {
-    if (Normalizer.pipeline.has(flags)) return Normalizer.pipeline.get(flags);
-    const { REGEX } = Normalizer;
-    const steps = [
-      ['d', (s) => s.normalize('NFD')],
-      ['i', (s) => s.toLowerCase()],
-      ['k', (s) => s.replace(REGEX.nonLetters, '')],
-      ['n', (s) => s.replace(REGEX.nonNumbers, '')],
-      ['r', (s) => s.replace(REGEX.doubleChars, '$1')],
-      ['s', (s) => s.replace(REGEX.specialChars, '')],
-      ['t', (s) => s.trim()],
-      ['u', (s) => s.normalize('NFC')],
-      ['w', (s) => s.replace(REGEX.whitespace, ' ')],
-      ['x', (s) => s.normalize('NFKC')]
-    ];
-    const pipeline = steps
-      .filter(([f]) => flags.includes(f))
-      .map(([, fn]) => fn);
-    const fn = (s) => pipeline.reduce((v, f) => f(v), s);
-    Normalizer.pipeline.set(flags, fn);
-    return fn;
+    return ErrorUtil.wrap(
+      () => {
+        if (Normalizer.pipeline.has(flags))
+          return Normalizer.pipeline.get(flags);
+        const { REGEX } = Normalizer;
+        const steps = [
+          ['d', (s) => s.normalize('NFD')],
+          ['i', (s) => s.toLowerCase()],
+          ['k', (s) => s.replace(REGEX.nonLetters, '')],
+          ['n', (s) => s.replace(REGEX.nonNumbers, '')],
+          ['r', (s) => s.replace(REGEX.doubleChars, '$1')],
+          ['s', (s) => s.replace(REGEX.specialChars, '')],
+          ['t', (s) => s.trim()],
+          ['u', (s) => s.normalize('NFC')],
+          ['w', (s) => s.replace(REGEX.whitespace, ' ')],
+          ['x', (s) => s.normalize('NFKC')]
+        ];
+        const pipeline = steps
+          .filter(([f]) => flags.includes(f))
+          .map(([, fn]) => fn);
+        const fn = (s) => pipeline.reduce((v, f) => f(v), s);
+        Normalizer.pipeline.set(flags, fn);
+        return fn;
+      },
+      `Failed to create normalization pipeline for flags: ${flags}`,
+      { flags }
+    );
   }
   static normalize(input, flags) {
-    if (!flags || typeof flags !== 'string' || !input) return input;
-    flags = this.canonicalFlags(flags);
-    if (Array.isArray(input))
-      return input.map((s) => Normalizer.normalize(s, flags));
-    const key = Normalizer.cache.key(flags, [input]);
-    if (key && Normalizer.cache.has(key)) return Normalizer.cache.get(key);
-    const res = Normalizer.getPipeline(flags)(input);
-    if (key) Normalizer.cache.set(key, res);
-    return res;
+    return ErrorUtil.wrap(
+      () => {
+        if (!flags || typeof flags !== 'string' || !input) return input;
+        flags = this.canonicalFlags(flags);
+        if (Array.isArray(input))
+          return input.map((s) => Normalizer.normalize(s, flags));
+        const key = Normalizer.cache.key(flags, [input]);
+        if (key && Normalizer.cache.has(key)) return Normalizer.cache.get(key);
+        const res = Normalizer.getPipeline(flags)(input);
+        if (key) Normalizer.cache.set(key, res);
+        return res;
+      },
+      `Failed to normalize input with flags: ${flags}`,
+      { input, flags }
+    );
   }
   static async normalizeAsync(input, flags) {
-    return await (Array.isArray(input)
-      ? Promise.all(input.map((s) => Normalizer.normalize(s, flags)))
-      : Promise.resolve(Normalizer.normalize(input, flags)));
+    return await ErrorUtil.wrapAsync(
+      async () => {
+        if (!flags || typeof flags !== 'string' || !input) return input;
+        return await (Array.isArray(input)
+          ? Promise.all(input.map((s) => Normalizer.normalize(s, flags)))
+          : Promise.resolve(Normalizer.normalize(input, flags)));
+      },
+      `Failed to asynchronously normalize input with flags: ${flags}`,
+      { input, flags }
+    );
   }
   static clear() {
     Normalizer.pipeline.clear();
@@ -59,4 +80,3 @@ class Normalizer {
 }
 
 export { Normalizer };
-//# sourceMappingURL=Normalizer.mjs.map

package/dist/esm/utils/Pool.mjs

@@ -1,4 +1,6 @@
-// CmpStr v3.2.1 build-3439ccb-260130 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.2.2 build-bb61120-260311 by Paul Köhler @komed3 / MIT License
+import { CmpStrUsageError, ErrorUtil } from './Errors.mjs';
+
 class RingPool {
   maxSize;
   buffers = [];
@@ -7,22 +9,37 @@ class RingPool {
     this.maxSize = maxSize;
   }
   acquire(minSize, allowOversize) {
-    const len = this.buffers.length;
-    for (let i = 0; i < len; i++) {
-      const idx = (this.pointer + i) & (len - 1);
-      const item = this.buffers[idx];
-      if (item.size >= minSize && (allowOversize || item.size === minSize)) {
-        this.pointer = (idx + 1) & (len - 1);
-        return item;
-      }
-    }
-    return null;
+    return ErrorUtil.wrap(
+      () => {
+        const len = this.buffers.length;
+        for (let i = 0; i < len; i++) {
+          const idx = (this.pointer + i) & (len - 1);
+          const item = this.buffers[idx];
+          if (
+            item.size >= minSize &&
+            (allowOversize || item.size === minSize)
+          ) {
+            this.pointer = (idx + 1) & (len - 1);
+            return item;
+          }
+        }
+        return null;
+      },
+      `Failed to acquire buffer of size >= ${minSize} from pool`,
+      { minSize, allowOversize }
+    );
   }
   release(item) {
-    if (this.buffers.length < this.maxSize)
-      return void [this.buffers.push(item)];
-    this.buffers[this.pointer] = item;
-    this.pointer = (this.pointer + 1) % this.maxSize;
+    ErrorUtil.wrap(
+      () => {
+        if (this.buffers.length < this.maxSize)
+          return void [this.buffers.push(item)];
+        this.buffers[this.pointer] = item;
+        this.pointer = (this.pointer + 1) % this.maxSize;
+      },
+      `Failed to release buffer back to pool`,
+      { item }
+    );
   }
   clear() {
     this.buffers = [];
@@ -75,6 +92,8 @@ class Pool {
   }
   static acquire(type, size) {
     const CONFIG = this.CONFIG[type];
+    if (!CONFIG)
+      throw new CmpStrUsageError(`Unsupported pool type <${type}>`, { type });
     if (size > CONFIG.maxItemSize) return this.allocate(type, size);
     const item = this.POOLS[type].acquire(size, CONFIG.allowOversize);
     if (item)
@@ -85,10 +104,11 @@ class Pool {
     return sizes.map((size) => this.acquire(type, size));
   }
   static release(type, buffer, size) {
-    if (size <= this.CONFIG[type].maxItemSize)
-      this.POOLS[type].release({ buffer, size });
+    const CONFIG = this.CONFIG[type];
+    if (!CONFIG)
+      throw new CmpStrUsageError(`Unsupported pool type <${type}>`, { type });
+    if (size <= CONFIG.maxItemSize) this.POOLS[type].release({ buffer, size });
   }
 }
 
 export { Pool };
-//# sourceMappingURL=Pool.mjs.map

package/dist/esm/utils/Profiler.mjs

@@ -1,4 +1,4 @@
-// CmpStr v3.2.1 build-3439ccb-260130 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.2.2 build-bb61120-260311 by Paul Köhler @komed3 / MIT License
 class Profiler {
   active;
   static ENV;
@@ -79,4 +79,3 @@ class Profiler {
 }
 
 export { Profiler };
-//# sourceMappingURL=Profiler.mjs.map

package/dist/esm/utils/Registry.mjs

@@ -1,20 +1,37 @@
-// CmpStr v3.2.1 build-3439ccb-260130 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.2.2 build-bb61120-260311 by Paul Köhler @komed3 / MIT License
+import { ErrorUtil, CmpStrNotFoundError } from './Errors.mjs';
+
 const registry = Object.create(null);
 const factory = Object.create(null);
 function Registry(reg, ctor) {
-  if (reg in registry || reg in factory)
-    throw new Error(
-      `Registry <${reg}> already exists / overwriting is forbidden`
-    );
+  ErrorUtil.assert(
+    !(reg in registry || reg in factory),
+    `Registry <${reg}> already exists / overwriting is forbidden`,
+    { registry: reg }
+  );
   const classes = Object.create(null);
   const service = Object.freeze({
     add(name, cls, update = false) {
-      if (!(cls.prototype instanceof ctor))
-        throw new TypeError(`Class must extend <${reg}>`);
-      if (!update && name in classes)
-        throw new Error(
-          `Entry <${name}> already exists / use <update=true> to overwrite`
-        );
+      ErrorUtil.assert(
+        typeof name === 'string' && name.length > 0,
+        `Class name must be a non-empty string`,
+        { registry: reg, name }
+      );
+      ErrorUtil.assert(
+        typeof cls === 'function',
+        `Class must be a constructor function`,
+        { registry: reg, class: cls }
+      );
+      ErrorUtil.assert(
+        cls.prototype instanceof ctor,
+        `Class must extend <${reg}>`,
+        { registry: reg, class: cls }
+      );
+      ErrorUtil.assert(
+        update || !(name in classes),
+        `Class <${name}> already exists / use <update=true> to overwrite`,
+        { registry: reg, name }
+      );
       classes[name] = cls;
     },
     remove(name) {
@@ -27,8 +44,16 @@ function Registry(reg, ctor) {
       return Object.keys(classes);
     },
     get(name) {
-      if (!(name in classes))
-        throw new Error(`Class <${name}> not registered for <${reg}>`);
+      ErrorUtil.assert(
+        typeof name === 'string' && name.length > 0,
+        `Class name must be a non-empty string`,
+        { registry: reg, name }
+      );
+      ErrorUtil.assert(
+        name in classes,
+        `Class <${name}> not registered for <${reg}>`,
+        { registry: reg, name }
+      );
       return classes[name];
     }
   });
@@ -38,19 +63,18 @@ function Registry(reg, ctor) {
 }
 function resolveCls(reg, cls) {
   if (!(reg in registry))
-    throw new ReferenceError(`Registry <${reg}> does not exist`);
+    throw new CmpStrNotFoundError(`Registry <${reg}> does not exist`, {
+      registry: reg
+    });
   return typeof cls === 'string' ? registry[reg]?.get(cls) : cls;
 }
 function createFromRegistry(reg, cls, ...args) {
   cls = resolveCls(reg, cls);
-  try {
-    return new cls(...args);
-  } catch (err) {
-    throw new Error(`Cannot instantiate class <${cls.name ?? cls}>`, {
-      cause: err
-    });
-  }
+  return ErrorUtil.wrap(
+    () => new cls(...args),
+    `Failed to create instance of class <${cls.name ?? cls}> from registry <${reg}>`,
+    { registry: reg, class: cls, args }
+  );
 }
 
 export { Registry, createFromRegistry, factory, registry, resolveCls };
-//# sourceMappingURL=Registry.mjs.map

package/dist/esm/utils/StructuredData.mjs

@@ -1,4 +1,5 @@
-// CmpStr v3.2.1 build-3439ccb-260130 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.2.2 build-bb61120-260311 by Paul Köhler @komed3 / MIT License
+import { CmpStrValidationError, ErrorUtil } from './Errors.mjs';
 import { Pool } from './Pool.mjs';
 
 class StructuredData {
@@ -48,7 +49,7 @@ class StructuredData {
         raw: r.raw
       }));
     else
-      throw new TypeError(
+      throw new CmpStrValidationError(
         'Unsupported result format for StructuredData normalization.'
       );
     return normalized.map((r, idx) => ({ ...r, __idx: idx }));
@@ -106,10 +107,18 @@ class StructuredData {
     );
   }
   performLookup(fn, extractedStrings, opt) {
-    return this.finalizeLookup(fn(), extractedStrings, opt);
+    return ErrorUtil.wrap(
+      () => this.finalizeLookup(fn(), extractedStrings, opt),
+      'StructuredData lookup failed',
+      { key: this.key }
+    );
   }
   async performLookupAsync(fn, extractedStrings, opt) {
-    return this.finalizeLookup(await fn(), extractedStrings, opt);
+    return await ErrorUtil.wrapAsync(
+      async () => this.finalizeLookup(await fn(), extractedStrings, opt),
+      'StructuredData async lookup failed',
+      { key: this.key }
+    );
   }
   lookup(fn, query, opt) {
     const b = this.extract();
@@ -150,4 +159,3 @@ class StructuredData {
 }
 
 export { StructuredData };
-//# sourceMappingURL=StructuredData.mjs.map

package/dist/esm/utils/TextAnalyzer.mjs

@@ -1,4 +1,4 @@
-// CmpStr v3.2.1 build-3439ccb-260130 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.2.2 build-bb61120-260311 by Paul Köhler @komed3 / MIT License
 class TextAnalyzer {
   static REGEX = {
     number: /\d/,
@@ -194,4 +194,3 @@ class TextAnalyzer {
 }
 
 export { TextAnalyzer };
-//# sourceMappingURL=TextAnalyzer.mjs.map

package/dist/types/CmpStr.d.ts

@@ -153,7 +153,8 @@ export declare class CmpStr<R = MetricRaw> {
      *
      * @param {string} cond - The condition to met
      * @param {any} [test] - Value to test for
-     * @throws {Error} If the condition is not met
+     * @throws {CmpStrNotFoundError} - If the specified metric or phonetic algorithm is not found
+     * @throws {CmpStrInternalError} - If an unknown condition is specified
      */
     protected assert(cond: string, test?: any): void;
     /**
@@ -233,6 +234,7 @@ export declare class CmpStr<R = MetricRaw> {
      * @param {boolean} [raw=false] - Whether to return raw results
      * @param {boolean} [skip=false] - Whether to skip normalization and filtering
      * @returns {T} - The computed metric result
+     * @throws {CmpStrInternalError} - If the computation fails due to internal errors
      */
     protected compute<T extends MetricResult<R> | CmpStrResult | CmpStrResult[]>(a: MetricInput, b: MetricInput, opt?: CmpStrOptions, mode?: MetricMode, raw?: boolean, skip?: boolean): T;
     /**
@@ -242,6 +244,7 @@ export declare class CmpStr<R = MetricRaw> {
      * @param {MetricResult< R >} result - The metric result
      * @param {boolean} [raw] - Whether to return raw results
      * @returns {T} - The resolved result
+     * @throws {CmpStrInternalError} - If the output format cannot be resolved
      */
     protected output<T extends MetricResult<R> | CmpStrResult | CmpStrResult[]>(result: MetricResult<R>, raw?: boolean): T;
     /**
@@ -283,6 +286,7 @@ export declare class CmpStr<R = MetricRaw> {
      *
      * @param {string} opt - The serialized options
      * @returns {this}
+     * @throws {CmpStrValidationError} - If the provided string is not valid JSON
      */
     setSerializedOptions(opt: string): this;
     /**

package/dist/types/CmpStrAsync.d.ts

@@ -106,6 +106,7 @@ export declare class CmpStrAsync<R = MetricRaw> extends CmpStr<R> {
      * @param {boolean} [raw=false] - Whether to return raw results
      * @param {boolean} [skip=false] - Whether to skip normalization and filtering
      * @returns {Promise< T >} - The computed metric result
+     * @throws {CmpStrInternalError} - If the computation fails due to internal errors
      */
     protected computeAsync<T extends MetricResult<R> | CmpStrResult | CmpStrResult[]>(a: MetricInput, b: MetricInput, opt?: CmpStrOptions, mode?: MetricMode, raw?: boolean, skip?: boolean): Promise<T>;
     /**

package/dist/types/index.d.ts

@@ -7,7 +7,7 @@
  * filtering, and text analysis. It is designed for both high-level application development
  * and research, offering a unified API for single, batch, and pairwise operations.
  *
- * Version: 3.2.1
+ * Version: 3.2.2
  * Author: Paul Köhler (komed3)
  * License: MIT
  *
@@ -41,11 +41,12 @@
  * For asynchronous workloads, use `CmpStrAsync`, which provides the same API with
  * Promise-based, non-blocking methods for large-scale or I/O-bound operations.
  *
- * @version 3.2.1
+ * @version 3.2.2
  * @author Paul Köhler (komed3)
  * @license MIT
  */
 export * from './utils/Types';
+export type { CmpStrError, CmpStrValidationError, CmpStrNotFoundError, CmpStrUsageError, CmpStrInternalError } from './utils/Errors';
 export { CmpStr } from './CmpStr';
 export { CmpStrAsync } from './CmpStrAsync';
 export { DiffChecker } from './utils/DiffChecker';

package/dist/types/metric/Metric.d.ts

@@ -83,7 +83,7 @@ export declare abstract class Metric<R = MetricRaw> {
      * @param {MetricInput} b - Second input string or array of strings
      * @param {MetricOptions} [opt] - Options for the metric computation
      * @param {boolean} [symmetric=false] - Whether the metric is symmetric (same result for inputs in any order)
-     * @throws {Error} - If inputs `a` or `b` are empty
+     * @throws {CmpStrUsageError} - If the inputs are empty or invalid
      */
     constructor(metric: string, a: MetricInput, b: MetricInput, opt?: MetricOptions, symmetric?: boolean);
     /**
@@ -107,7 +107,7 @@ export declare abstract class Metric<R = MetricRaw> {
      * @param {number} n - Length of the second string
      * @param {number} maxLen - Maximum length of the strings
      * @returns {MetricCompute< R >} - The result of the metric computation
-     * @throws {Error} - If not overridden in a subclass
+     * @throws {CmpStrInternalError} - If the method is not overridden in a subclass
      */
     protected compute(a: string, b: string, m: number, n: number, maxLen: number): MetricCompute<R>;
     /**
@@ -119,6 +119,7 @@ export declare abstract class Metric<R = MetricRaw> {
      * @param {number} i - Pointer to the first string
      * @param {number} j - Pointer to the second string
      * @returns {MetricResultSingle< R >} - The result of the metric computation
+     * @throws {CmpStrInternalError} - If the metric computation fails for the given inputs
      */
     private runSingle;
     /**
@@ -184,7 +185,7 @@ export declare abstract class Metric<R = MetricRaw> {
      *
      * @returns {boolean} - True if both inputs are arrays of equal length
      * @param {boolean} [safe=false] - If true, does not throw an error if lengths are not equal
-     * @throws {Error} - If `safe` is false and the lengths of `a` and `b` are not equal
+     * @throws {CmpStrUsageError} - If `safe` is false and the lengths of `a` and `b` are not equal
      */
     isPairwise(safe?: boolean): boolean;
     /**
@@ -219,7 +220,7 @@ export declare abstract class Metric<R = MetricRaw> {
      *
      * @param {MetricMode} [mode] - The mode to run the metric in (optional)
      * @param {boolean} [clear=true] - Whether to clear previous results before running
-     * @throws {Error} - If an unsupported mode is specified
+     * @throws {CmpStrInternalError} - If an unsupported mode is specified
      */
     run(mode?: MetricMode, clear?: boolean): void;
     /**
@@ -228,7 +229,7 @@ export declare abstract class Metric<R = MetricRaw> {
      * @param {MetricMode} [mode] - The mode to run the metric in (optional)
      * @param {boolean} [clear=true] - Whether to clear previous results before running
      * @returns {Promise<void>} - A promise that resolves when the metric computation is complete
-     * @throws {Error} - If an unsupported mode is specified
+     * @throws {CmpStrInternalError} - If an unsupported mode is specified
      */
     runAsync(mode?: MetricMode, clear?: boolean): Promise<void>;
     /**

package/dist/types/phonetic/Phonetic.d.ts

@@ -61,7 +61,7 @@ export declare abstract class Phonetic {
      *
      * @param {string} algo - The name of the algorithm (e.g. 'soundex')
      * @param {PhoneticOptions} [opt] - Options for the phonetic algorithm
-     * @throws {Error} - If the requested mapping is not declared
+     * @throws {CmpStrNotFoundError} - If no mapping is specified or if the requested mapping is not declared
      */
     constructor(algo: string, opt?: PhoneticOptions);
     /**
@@ -149,6 +149,7 @@ export declare abstract class Phonetic {
      *
      * @param {string[]} words - An array of words to be processed
      * @returns {string[]} - An array of phonetic indices for the input words
+     * @throws {CmpStrInternalError} - If the phonetic index generation fails
      */
     protected loop(words: string[]): string[];
     /**
@@ -159,6 +160,7 @@ export declare abstract class Phonetic {
      *
      * @param {string[]} words - An array of words to be processed
      * @returns {Promise< string[] >} - A promise that resolves to an array of phonetic indices for the input words
+     * @throws {CmpStrInternalError} - If the asynchronous phonetic index generation fails
      */
     protected loopAsync(words: string[]): Promise<string[]>;
     /**

package/dist/types/root.d.ts

@@ -9,7 +9,7 @@
  * Please visit CmpStr's documentation for more information:
  * https://github.com/komed3/cmpstr/wiki/Extending-CmpStr
  *
- * @version 3.2.1
+ * @version 3.2.2
  * @author Paul Köhler (komed3)
  * @license MIT
  */
@@ -32,6 +32,7 @@ export { Metric, MetricCls, MetricRegistry } from './metric';
  */
 export { Phonetic, PhoneticCls, PhoneticMappingRegistry, PhoneticRegistry } from './phonetic';
 export * as DeepMerge from './utils/DeepMerge';
+export * as CmpStrError from './utils/Errors';
 export { Filter } from './utils/Filter';
 export { Hasher, HashTable } from './utils/HashTable';
 export { Pool } from './utils/Pool';

package/dist/types/utils/DeepMerge.d.ts

@@ -47,7 +47,7 @@ export declare function has<T extends Record<string, any>>(t: T, path: string):
  * @param {string} path - The path string, e.g. `a.b.c`
  * @param {any} value - The value to set at the specified path
  * @returns {T} - The modified object with the value set at the specified path
- * @throws {Error} - Throws an error if the key is not a valid identifier
+ * @throws {CmpStrUsageError} - If the path is invalid or if a non-object value is encountered along the path
  */
 export declare function set<T extends Record<string, any>>(t: T, path: string, value: any): T;
 /**