cmpstr 3.2.1 → 3.2.2

package/dist/CmpStr.umd.js

@@ -1,5 +1,5 @@
 /**
- * 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
@@ -15,6 +15,110 @@
 })(this, function (exports) {
   'use strict';
 
+  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) {
@@ -50,15 +154,19 @@
     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);
@@ -425,30 +533,42 @@
     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);
@@ -473,14 +593,26 @@
       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();
@@ -568,42 +700,63 @@
       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();
@@ -693,19 +846,34 @@
   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) {
@@ -718,8 +886,16 @@
         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];
       }
     });
@@ -729,18 +905,18 @@
   }
   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 {
@@ -751,22 +927,37 @@
       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 = [];
@@ -819,6 +1010,8 @@
     }
     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)
@@ -829,7 +1022,10 @@
       return sizes.map((size) => this.acquire(type, size));
     }
     static release(type, buffer, size) {
-      if (size <= this.CONFIG[type].maxItemSize)
+      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 });
     }
   }
@@ -885,7 +1081,7 @@
           raw: r.raw
         }));
       else
-        throw new TypeError(
+        throw new CmpStrValidationError(
           'Unsupported result format for StructuredData normalization.'
         );
       return normalized.map((r, idx) => ({ ...r, __idx: idx }));
@@ -947,10 +1143,18 @@
       );
     }
     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();
@@ -1204,8 +1408,11 @@
       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())
@@ -1218,37 +1425,46 @@
       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));
@@ -1291,8 +1507,9 @@
         ? 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 }
               );
             })();
     }
@@ -1317,7 +1534,7 @@
           if (this.isPairwise()) this.runPairwise();
           break;
         default:
-          throw new Error(`Unsupported mode <${mode}>`);
+          throw new CmpStrInternalError(`Unsupported mode <${mode}>`);
       }
     }
     async runAsync(mode, clear = true) {
@@ -1338,13 +1555,15 @@
           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;
     }
   }
@@ -1476,9 +1695,10 @@
           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;
@@ -1757,10 +1977,16 @@
       const defaults = this.constructor.default ?? {};
       const mapId = opt.map ?? defaults.map;
       if (!mapId)
-        throw new Error(`No mapping specified for phonetic algorithm`);
+        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())
@@ -1851,35 +2077,47 @@
       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) {
@@ -1905,10 +2143,11 @@
     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) {
@@ -2335,20 +2574,22 @@
       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) {
@@ -2387,31 +2628,42 @@
       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);
@@ -2428,8 +2680,14 @@
       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);
@@ -2575,24 +2833,30 @@
         : 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');
@@ -2693,6 +2957,7 @@
 
   exports.CmpStr = CmpStr;
   exports.CmpStrAsync = CmpStrAsync;
+  exports.CmpStrError = Errors;
   exports.DeepMerge = DeepMerge;
   exports.DiffChecker = DiffChecker;
   exports.Filter = Filter;
@@ -2709,4 +2974,3 @@
   exports.StructuredData = StructuredData;
   exports.TextAnalyzer = TextAnalyzer;
 });
-//# sourceMappingURL=CmpStr.umd.js.map