cmpstr 3.2.1 → 3.2.2

package/dist/CmpStr.esm.js

@@ -1,9 +1,113 @@
 /**
- * CmpStr v3.2.1 build-3439ccb-260130
+ * CmpStr v3.2.2 build-bb61120-260311
  * This is a lightweight, fast and well performing library for calculating string similarity.
  * (c) 2023-2026 Paul Köhler @komed3 / MIT License
  * Visit https://github.com/komed3/cmpstr and https://npmjs.org/package/cmpstr
  */
+class CmpStrError extends Error {
+  code;
+  meta;
+  cause;
+  when = new Date().toISOString();
+  constructor(code, message, meta, cause) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code;
+    this.meta = meta;
+    this.cause = cause;
+    if (typeof Error.captureStackTrace === 'function') {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      meta: this.meta,
+      when: this.when,
+      cause:
+        this.cause instanceof Error
+          ? {
+              name: this.cause.name,
+              message: this.cause.message,
+              stack: this.cause.stack
+            }
+          : this.cause
+    };
+  }
+  toString(stack = false) {
+    const parts = [`${this.name} [${this.code}]`, this.message];
+    if (this.meta && Object.keys(this.meta).length) {
+      try {
+        parts.push(JSON.stringify(this.meta));
+      } catch {}
+    }
+    return (
+      parts.join(' - ') +
+      (stack && this.stack ? `\nStack Trace:\n${this.stack}` : '')
+    );
+  }
+}
+class CmpStrValidationError extends CmpStrError {
+  constructor(message, meta, cause) {
+    super('E_VALIDATION', message, meta, cause);
+  }
+}
+class CmpStrNotFoundError extends CmpStrError {
+  constructor(message, meta, cause) {
+    super('E_NOT_FOUND', message, meta, cause);
+  }
+}
+class CmpStrUsageError extends CmpStrError {
+  constructor(message, meta, cause) {
+    super('E_USAGE', message, meta, cause);
+  }
+}
+class CmpStrInternalError extends CmpStrError {
+  constructor(message, meta, cause) {
+    super('E_INTERNAL', message, meta, cause);
+  }
+}
+class ErrorUtil {
+  static assert(condition, message, meta) {
+    if (!condition) throw new CmpStrUsageError(message, meta);
+  }
+  static create(err, message, meta) {
+    if (err instanceof CmpStrError) throw err;
+    throw new CmpStrInternalError(message, meta, err);
+  }
+  static format(err) {
+    if (err instanceof CmpStrError) return err.toString();
+    if (err instanceof Error) return `${err.name}: ${err.message}`;
+    return String(err);
+  }
+  static wrap(fn, message, meta) {
+    try {
+      return fn();
+    } catch (err) {
+      throw new CmpStrInternalError(message, meta, err);
+    }
+  }
+  static async wrapAsync(fn, message, meta) {
+    try {
+      return await fn();
+    } catch (err) {
+      throw new CmpStrInternalError(message, meta, err);
+    }
+  }
+}
+
+var Errors = /*#__PURE__*/ Object.freeze({
+  __proto__: null,
+  CmpStrError: CmpStrError,
+  CmpStrInternalError: CmpStrInternalError,
+  CmpStrNotFoundError: CmpStrNotFoundError,
+  CmpStrUsageError: CmpStrUsageError,
+  CmpStrValidationError: CmpStrValidationError,
+  ErrorUtil: ErrorUtil
+});
+
 const BRACKET_PATTERN = /\[(\d+)]/g;
 const PATH_CACHE = new Map();
 function parse(p) {
@@ -39,15 +143,19 @@ function set(t, path, value) {
   if (path === '') return value;
   const keys = parse(path);
   if (t !== undefined && (typeof t !== 'object' || t === null))
-    throw Error(`Cannot set property <${keys[0]}> of <${JSON.stringify(t)}>`);
+    throw new CmpStrUsageError(
+      `Cannot set property <${keys[0]}> of <${JSON.stringify(t)}>`,
+      { path: keys[0], target: t }
+    );
   const root = t ?? (typeof keys[0] === 'number' ? [] : Object.create(null));
   let cur = root;
   for (let i = 0; i < keys.length - 1; i++) {
     const k = keys[i];
     let n = cur[k];
     if (n != null && typeof n !== 'object')
-      throw Error(
-        `Cannot set property <${keys[i + 1]}> of <${JSON.stringify(n)}>`
+      throw new CmpStrUsageError(
+        `Cannot set property <${keys[i + 1]}> of <${JSON.stringify(n)}>`,
+        { path: keys.slice(0, i + 2), value: n }
       );
     if (n == null)
       n = cur[k] = typeof keys[i + 1] === 'number' ? [] : Object.create(null);
@@ -411,30 +519,42 @@ class Filter {
   static filters = new Map();
   static pipeline = new Map();
   static getPipeline(hook) {
-    const cached = Filter.pipeline.get(hook);
-    if (cached) return cached;
-    const filter = Filter.filters.get(hook);
-    if (!filter) return (s) => s;
-    const pipeline = Array.from(filter.values())
-      .filter((f) => f.active)
-      .sort((a, b) => a.priority - b.priority)
-      .map((f) => f.fn);
-    const fn = (input) => pipeline.reduce((v, f) => f(v), input);
-    Filter.pipeline.set(hook, fn);
-    return fn;
+    return ErrorUtil.wrap(
+      () => {
+        const cached = Filter.pipeline.get(hook);
+        if (cached) return cached;
+        const filter = Filter.filters.get(hook);
+        if (!filter) return (s) => s;
+        const pipeline = Array.from(filter.values())
+          .filter((f) => f.active)
+          .sort((a, b) => a.priority - b.priority)
+          .map((f) => f.fn);
+        const fn = (input) => pipeline.reduce((v, f) => f(v), input);
+        Filter.pipeline.set(hook, fn);
+        return fn;
+      },
+      `Error compiling filter pipeline for hook <${hook}>`,
+      { hook }
+    );
   }
   static has(hook, id) {
     return !!Filter.filters.get(hook)?.has(id);
   }
   static add(hook, id, fn, opt = {}) {
-    const { priority = 10, active = true, overrideable = true } = opt;
-    const filter = Filter.filters.get(hook) ?? new Map();
-    const index = filter.get(id);
-    if (index && !index.overrideable) return false;
-    filter.set(id, { id, fn, priority, active, overrideable });
-    Filter.filters.set(hook, filter);
-    Filter.pipeline.delete(hook);
-    return true;
+    return ErrorUtil.wrap(
+      () => {
+        const { priority = 10, active = true, overrideable = true } = opt;
+        const filter = Filter.filters.get(hook) ?? new Map();
+        const index = filter.get(id);
+        if (index && !index.overrideable) return false;
+        filter.set(id, { id, fn, priority, active, overrideable });
+        Filter.filters.set(hook, filter);
+        Filter.pipeline.delete(hook);
+        return true;
+      },
+      `Error adding filter <${id}> to hook <${hook}>`,
+      { hook, id, opt }
+    );
   }
   static remove(hook, id) {
     Filter.pipeline.delete(hook);
@@ -459,14 +579,26 @@ class Filter {
     return out;
   }
   static apply(hook, input) {
-    const fn = Filter.getPipeline(hook);
-    return Array.isArray(input) ? input.map(fn) : fn(input);
+    return ErrorUtil.wrap(
+      () => {
+        const fn = Filter.getPipeline(hook);
+        return Array.isArray(input) ? input.map(fn) : fn(input);
+      },
+      `Error applying filters for hook <${hook}>`,
+      { hook, input }
+    );
   }
   static async applyAsync(hook, input) {
-    const fn = Filter.getPipeline(hook);
-    return Array.isArray(input)
-      ? Promise.all(input.map(fn))
-      : Promise.resolve(fn(input));
+    return ErrorUtil.wrapAsync(
+      async () => {
+        const fn = Filter.getPipeline(hook);
+        return Array.isArray(input)
+          ? Promise.all(input.map(fn))
+          : Promise.resolve(fn(input));
+      },
+      `Error applying filters for hook <${hook}>`,
+      { hook, input }
+    );
   }
   static clear(hook) {
     Filter.pipeline.clear();
@@ -554,42 +686,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();
@@ -679,19 +831,34 @@ class Profiler {
 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) {
@@ -704,8 +871,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];
     }
   });
@@ -715,18 +890,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 }
+  );
 }
 
 class RingPool {
@@ -737,22 +912,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 = [];
@@ -805,6 +995,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)
@@ -815,8 +1007,10 @@ 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 });
   }
 }
 
@@ -867,7 +1061,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 }));
@@ -925,10 +1119,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();
@@ -1181,8 +1383,11 @@ class Metric {
     this.metric = metric;
     this.a = Array.isArray(a) ? a : [a];
     this.b = Array.isArray(b) ? b : [b];
-    if (this.a.length === 0 || this.b.length === 0)
-      throw new Error(`Inputs <a> and <b> must not be empty`);
+    ErrorUtil.assert(
+      this.a.length > 0 && this.b.length > 0,
+      `Inputs <a> and <b> must not be empty`,
+      { a: this.a, b: this.b }
+    );
     this.options = opt;
     this.optKey = Hasher.fastFNV1a(
       JSON.stringify(opt, Object.keys(opt).sort())
@@ -1195,37 +1400,46 @@ class Metric {
     return undefined;
   }
   compute(a, b, m, n, maxLen) {
-    throw new Error(`Method compute() must be overridden in a subclass`);
+    throw new CmpStrInternalError(
+      `Method compute() must be overridden in a subclass`
+    );
   }
   runSingle(i, j) {
-    let a = String(this.a[i]),
-      A = a;
-    let b = String(this.b[j]),
-      B = b;
-    let m = A.length,
-      n = B.length;
-    let result = this.preCompute(A, B, m, n);
-    if (!result) {
-      result = profiler$2.run(() => {
-        if (this.symmetric) [A, B, m, n] = Metric.swap(A, B, m, n);
-        const key =
-          Metric.cache.key(this.metric, [A, B], this.symmetric) + this.optKey;
-        return (
-          Metric.cache.get(key || '') ??
-          (() => {
-            const res = this.compute(A, B, m, n, Math.max(m, n));
-            if (key) Metric.cache.set(key, res);
-            return res;
-          })()
-        );
-      });
-    }
-    return {
-      metric: this.metric,
-      a: this.origA[i] ?? a,
-      b: this.origB[j] ?? b,
-      ...result
-    };
+    return ErrorUtil.wrap(
+      () => {
+        let a = String(this.a[i]),
+          A = a;
+        let b = String(this.b[j]),
+          B = b;
+        let m = A.length,
+          n = B.length;
+        let result = this.preCompute(A, B, m, n);
+        if (!result) {
+          result = profiler$2.run(() => {
+            if (this.symmetric) [A, B, m, n] = Metric.swap(A, B, m, n);
+            const key =
+              Metric.cache.key(this.metric, [A, B], this.symmetric) +
+              this.optKey;
+            return (
+              Metric.cache.get(key || '') ??
+              (() => {
+                const res = this.compute(A, B, m, n, Math.max(m, n));
+                if (key) Metric.cache.set(key, res);
+                return res;
+              })()
+            );
+          });
+        }
+        return {
+          metric: this.metric,
+          a: this.origA[i] ?? a,
+          b: this.origB[j] ?? b,
+          ...result
+        };
+      },
+      `Failed to compute metric for inputs at indices a[${i}] and b[${j}]`,
+      { i, j }
+    );
   }
   async runSingleAsync(i, j) {
     return Promise.resolve(this.runSingle(i, j));
@@ -1267,7 +1481,10 @@ class Metric {
       ? true
       : !safe &&
           (() => {
-            throw new Error(`Mode <pairwise> requires arrays of equal length`);
+            throw new CmpStrUsageError(
+              `Mode <pairwise> requires arrays of equal length`,
+              { a: this.a, b: this.b }
+            );
           })();
   }
   isSymmetrical = () => this.symmetric;
@@ -1291,7 +1508,7 @@ class Metric {
         if (this.isPairwise()) this.runPairwise();
         break;
       default:
-        throw new Error(`Unsupported mode <${mode}>`);
+        throw new CmpStrInternalError(`Unsupported mode <${mode}>`);
     }
   }
   async runAsync(mode, clear = true) {
@@ -1312,13 +1529,15 @@ class Metric {
         if (this.isPairwise()) await this.runPairwiseAsync();
         break;
       default:
-        throw new Error(`Unsupported async mode <${mode}>`);
+        throw new CmpStrInternalError(`Unsupported async mode <${mode}>`);
     }
   }
   getMetricName = () => this.metric;
   getResults() {
-    if (this.results === undefined)
-      throw new Error(`run() must be called before getResult()`);
+    ErrorUtil.assert(
+      this.results !== undefined,
+      `run() must be called before getResults()`
+    );
     return this.results;
   }
 }
@@ -1446,9 +1665,10 @@ class HammingDistance extends Metric {
         if (n < maxLen) b = b.padEnd(maxLen, this.options.pad);
         m = n = maxLen;
       } else
-        throw new Error(
+        throw new CmpStrUsageError(
           `Strings must be of equal length for Hamming Distance, a=${m} and b=${n} given, ` +
-            `use option.pad for automatic adjustment`
+            `use option.pad for automatic adjustment`,
+          { a: m, b: n }
         );
     }
     let dist = 0;
@@ -1721,10 +1941,17 @@ class Phonetic {
   constructor(algo, opt = {}) {
     const defaults = this.constructor.default ?? {};
     const mapId = opt.map ?? defaults.map;
-    if (!mapId) throw new Error(`No mapping specified for phonetic algorithm`);
+    if (!mapId)
+      throw new CmpStrNotFoundError(
+        `No mapping specified for phonetic algorithm`,
+        { algo }
+      );
     const map = PhoneticMappingRegistry.get(algo, mapId);
     if (map === undefined)
-      throw new Error(`Requested mapping <${mapId}> is not declared`);
+      throw new CmpStrNotFoundError(
+        `Requested mapping <${mapId}> is not declared`,
+        { algo, mapId }
+      );
     this.options = merge(merge(defaults, map.options ?? {}), opt);
     this.optKey = Hasher.fastFNV1a(
       JSON.stringify(this.options, Object.keys(this.options).sort())
@@ -1814,35 +2041,47 @@ class Phonetic {
     return code;
   }
   loop(words) {
-    const index = [];
-    for (const word of words) {
-      const key = Phonetic.cache.key(this.algo, [word]) + this.optKey;
-      const code =
-        Phonetic.cache.get(key || '') ??
-        (() => {
-          const res = this.encode(word);
-          if (key) Phonetic.cache.set(key, res);
-          return res;
-        })();
-      if (code && code.length) index.push(this.equalLen(code));
-    }
-    return index;
+    return ErrorUtil.wrap(
+      () => {
+        const index = [];
+        for (const word of words) {
+          const key = Phonetic.cache.key(this.algo, [word]) + this.optKey;
+          const code =
+            Phonetic.cache.get(key || '') ??
+            (() => {
+              const res = this.encode(word);
+              if (key) Phonetic.cache.set(key, res);
+              return res;
+            })();
+          if (code && code.length) index.push(this.equalLen(code));
+        }
+        return index;
+      },
+      `Failed to generate phonetic index`,
+      { algo: this.algo, words }
+    );
   }
   async loopAsync(words) {
-    const index = [];
-    for (const word of words) {
-      const key = Phonetic.cache.key(this.algo, [word]) + this.optKey;
-      const code = await Promise.resolve(
-        Phonetic.cache.get(key || '') ??
-          (() => {
-            const res = this.encode(word);
-            if (key) Phonetic.cache.set(key, res);
-            return res;
-          })()
-      );
-      if (code && code.length) index.push(this.equalLen(code));
-    }
-    return index;
+    return ErrorUtil.wrapAsync(
+      async () => {
+        const index = [];
+        for (const word of words) {
+          const key = Phonetic.cache.key(this.algo, [word]) + this.optKey;
+          const code = await Promise.resolve(
+            Phonetic.cache.get(key || '') ??
+              (() => {
+                const res = this.encode(word);
+                if (key) Phonetic.cache.set(key, res);
+                return res;
+              })()
+          );
+          if (code && code.length) index.push(this.equalLen(code));
+        }
+        return index;
+      },
+      `Failed to generate phonetic index asynchronously`,
+      { algo: this.algo, words }
+    );
   }
   getAlgoName = () => this.algo;
   getIndex(input) {
@@ -1867,10 +2106,11 @@ const PhoneticMappingRegistry = (() => {
   return Object.freeze({
     add(algo, id, map, update = false) {
       const mappings = maps(algo);
-      if (!update && id in mappings)
-        throw new Error(
-          `Entry <${id}> already exists / use <update=true> to overwrite`
-        );
+      ErrorUtil.assert(
+        !(!id || id in mappings) || update,
+        `Entry <${id}> already exists / use <update=true> to overwrite`,
+        { algo, id }
+      );
       mappings[id] = map;
     },
     remove(algo, id) {
@@ -2290,20 +2530,22 @@ class CmpStr {
     switch (cond) {
       case 'metric':
         if (!CmpStr.metric.has(test))
-          throw new Error(
+          throw new CmpStrNotFoundError(
             `CmpStr <metric> must be set, call .setMetric(), ` +
-              `use CmpStr.metric.list() for available metrics`
+              `use CmpStr.metric.list() for available metrics`,
+            { metric: test }
           );
         break;
       case 'phonetic':
         if (!CmpStr.phonetic.has(test))
-          throw new Error(
+          throw new CmpStrNotFoundError(
             `CmpStr <phonetic> must be set, call .setPhonetic(), ` +
-              `use CmpStr.phonetic.list() for available phonetic algorithms`
+              `use CmpStr.phonetic.list() for available phonetic algorithms`,
+            { phonetic: test }
           );
         break;
       default:
-        throw new Error(`Cmpstr condition <${cond}> unknown`);
+        throw new CmpStrInternalError(`Cmpstr condition <${cond}> unknown`);
     }
   }
   assertMany(...cond) {
@@ -2342,31 +2584,42 @@ class CmpStr {
     return StructuredData.create(data, key);
   }
   compute(a, b, opt, mode, raw, skip) {
-    const resolved = this.resolveOptions(opt);
-    this.assert('metric', resolved.metric);
-    const A = skip ? a : this.prepare(a, resolved);
-    const B = skip ? b : this.prepare(b, resolved);
-    if (
-      resolved.safeEmpty &&
-      ((Array.isArray(A) && A.length === 0) ||
-        (Array.isArray(B) && B.length === 0) ||
-        A === '' ||
-        B === '')
-    ) {
-      return [];
-    }
-    const metric = factory['metric'](resolved.metric, A, B, resolved.opt);
-    if (resolved.output !== 'prep') metric.setOriginal(a, b);
-    metric.run(mode);
-    const result = this.postProcess(metric.getResults(), resolved);
-    return this.output(result, raw ?? resolved.raw);
+    return ErrorUtil.wrap(
+      () => {
+        const resolved = this.resolveOptions(opt);
+        this.assert('metric', resolved.metric);
+        const A = skip ? a : this.prepare(a, resolved);
+        const B = skip ? b : this.prepare(b, resolved);
+        if (
+          resolved.safeEmpty &&
+          ((Array.isArray(A) && A.length === 0) ||
+            (Array.isArray(B) && B.length === 0) ||
+            A === '' ||
+            B === '')
+        ) {
+          return [];
+        }
+        const metric = factory['metric'](resolved.metric, A, B, resolved.opt);
+        if (resolved.output !== 'prep') metric.setOriginal(a, b);
+        metric.run(mode);
+        const result = this.postProcess(metric.getResults(), resolved);
+        return this.output(result, raw ?? resolved.raw);
+      },
+      `Failed to compute metric <${opt?.metric ?? this.options.metric}> for the given inputs`,
+      { a, b, options: opt }
+    );
   }
   output(result, raw) {
-    return (raw ?? this.options.raw)
-      ? result
-      : Array.isArray(result)
-        ? result.map((r) => ({ source: r.a, target: r.b, match: r.res }))
-        : { source: result.a, target: result.b, match: result.res };
+    return ErrorUtil.wrap(
+      () =>
+        (raw ?? this.options.raw)
+          ? result
+          : Array.isArray(result)
+            ? result.map((r) => ({ source: r.a, target: r.b, match: r.res }))
+            : { source: result.a, target: result.b, match: result.res },
+      `Failed to resolve output format for the metric result`,
+      { result, raw }
+    );
   }
   clone = () => Object.assign(Object.create(Object.getPrototypeOf(this)), this);
   reset() {
@@ -2382,8 +2635,14 @@ class CmpStr {
     return this;
   }
   setSerializedOptions(opt) {
-    this.options = JSON.parse(opt);
-    return this;
+    return ErrorUtil.wrap(
+      () => {
+        this.options = JSON.parse(opt);
+        return this;
+      },
+      `Failed to parse serialized options, invalid JSON string`,
+      { opt }
+    );
   }
   setOption(path, value) {
     set(this.options, path, value);
@@ -2526,24 +2785,30 @@ class CmpStrAsync extends CmpStr {
       : phonetic.getIndexAsync(input).then((r) => r.join(delimiter));
   }
   async computeAsync(a, b, opt, mode, raw, skip) {
-    const resolved = this.resolveOptions(opt);
-    this.assert('metric', resolved.metric);
-    const A = skip ? a : await this.prepareAsync(a, resolved);
-    const B = skip ? b : await this.prepareAsync(b, resolved);
-    if (
-      resolved.safeEmpty &&
-      ((Array.isArray(A) && A.length === 0) ||
-        (Array.isArray(B) && B.length === 0) ||
-        A === '' ||
-        B === '')
-    ) {
-      return [];
-    }
-    const metric = factory['metric'](resolved.metric, A, B, resolved.opt);
-    if (resolved.output !== 'prep') metric.setOriginal(a, b);
-    await metric.runAsync(mode);
-    const result = this.postProcess(metric.getResults(), resolved);
-    return this.output(result, raw ?? resolved.raw);
+    return ErrorUtil.wrapAsync(
+      async () => {
+        const resolved = this.resolveOptions(opt);
+        this.assert('metric', resolved.metric);
+        const A = skip ? a : await this.prepareAsync(a, resolved);
+        const B = skip ? b : await this.prepareAsync(b, resolved);
+        if (
+          resolved.safeEmpty &&
+          ((Array.isArray(A) && A.length === 0) ||
+            (Array.isArray(B) && B.length === 0) ||
+            A === '' ||
+            B === '')
+        ) {
+          return [];
+        }
+        const metric = factory['metric'](resolved.metric, A, B, resolved.opt);
+        if (resolved.output !== 'prep') metric.setOriginal(a, b);
+        await metric.runAsync(mode);
+        const result = this.postProcess(metric.getResults(), resolved);
+        return this.output(result, raw ?? resolved.raw);
+      },
+      `Failed to compute metric <${opt?.metric ?? this.options.metric}> for the given inputs`,
+      { a, b, opt }
+    );
   }
   async testAsync(a, b, opt) {
     return this.computeAsync(a, b, opt, 'single');
@@ -2645,6 +2910,7 @@ class CmpStrAsync extends CmpStr {
 export {
   CmpStr,
   CmpStrAsync,
+  Errors as CmpStrError,
   DeepMerge,
   DiffChecker,
   Filter,
@@ -2661,4 +2927,3 @@ export {
   StructuredData,
   TextAnalyzer
 };
-//# sourceMappingURL=CmpStr.esm.js.map