cmpstr 3.2.1 → 3.3.0

package/dist/CmpStr.umd.js

@@ -1,5 +1,5 @@
 /**
- * CmpStr v3.2.1 build-3439ccb-260130
+ * CmpStr v3.3.0 build-3699f85-260318
  * 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,114 +15,227 @@
 })(this, function (exports) {
   'use strict';
 
-  const BRACKET_PATTERN = /\[(\d+)]/g;
-  const PATH_CACHE = new Map();
-  function parse(p) {
-    let cached = PATH_CACHE.get(p);
-    if (cached) return cached;
-    const parsed = p
-      .replace(BRACKET_PATTERN, '.$1')
-      .split('.')
-      .map((s) => {
-        const n = Number(s);
-        return Number.isInteger(n) && String(n) === s ? n : s;
-      });
-    PATH_CACHE.set(p, parsed);
-    return parsed;
+  class CmpStrError extends Error {
+    code;
+    meta;
+    when = new Date().toISOString();
+    constructor(code, message, meta, cause) {
+      super(message, cause !== undefined ? { cause } : undefined);
+      this.name = this.constructor.name;
+      this.code = code;
+      this.meta = meta;
+      if (typeof Error.captureStackTrace === 'function') {
+        Error.captureStackTrace(this, this.constructor);
+      }
+    }
+    format(stack = false) {
+      const parts = [`${this.name} [${this.code}]`, this.message];
+      if (this.meta)
+        for (const _ in this.meta) {
+          parts.push(JSON.stringify(this.meta));
+          break;
+        }
+      return (
+        parts.join(' - ') +
+        (stack && this.stack ? `\nStack Trace:\n${this.stack}` : '')
+      );
+    }
+    toString() {
+      return this.format(false);
+    }
+    toJSON(stack = false) {
+      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: stack && this.cause.stack
+              }
+            : this.cause
+      };
+    }
   }
-  function get(t, path, fb) {
-    let o = t;
-    for (const k of parse(path)) {
-      if (o == null || !(k in o)) return fb;
-      o = o[k];
+  class CmpStrValidationError extends CmpStrError {
+    constructor(message, meta, cause) {
+      super('E_VALIDATION', message, meta, cause);
     }
-    return o;
   }
-  function has(t, path) {
-    let o = t;
-    for (const k of parse(path)) {
-      if (o == null || !(k in o)) return false;
-      o = o[k];
+  class CmpStrNotFoundError extends CmpStrError {
+    constructor(message, meta, cause) {
+      super('E_NOT_FOUND', message, meta, cause);
     }
-    return true;
   }
-  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)}>`);
-    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)}>`
-        );
-      if (n == null)
-        n = cur[k] = typeof keys[i + 1] === 'number' ? [] : Object.create(null);
-      cur = n;
+  class CmpStrUsageError extends CmpStrError {
+    constructor(message, meta, cause) {
+      super('E_USAGE', message, meta, cause);
     }
-    cur[keys[keys.length - 1]] = value;
-    return root;
   }
-  function merge(
-    t = Object.create(null),
-    o = Object.create(null),
-    mergeUndefined = false
-  ) {
-    const target = t ?? Object.create(null);
-    Object.keys(o).forEach((k) => {
-      const val = o[k];
-      if (!mergeUndefined && val === undefined) return;
-      if (k === '__proto__' || k === 'constructor') return;
-      if (val !== null && typeof val === 'object' && !Array.isArray(val)) {
-        const existing = target[k];
-        target[k] = merge(
-          existing !== null &&
-            typeof existing === 'object' &&
-            !Array.isArray(existing)
-            ? existing
-            : Object.create(null),
-          val,
-          mergeUndefined
-        );
-      } else target[k] = val;
-    });
-    return target;
+  class CmpStrInternalError extends CmpStrError {
+    constructor(message, meta, cause) {
+      super('E_INTERNAL', message, meta, cause);
+    }
   }
-  function rmv(t, path, preserveEmpty = false) {
-    const keys = parse(path);
-    const remove = (obj, i = 0) => {
-      const key = keys[i];
-      if (!obj || typeof obj !== 'object') return false;
-      if (i === keys.length - 1) return delete obj[key];
-      if (!remove(obj[key], i + 1)) return false;
-      if (!preserveEmpty) {
-        const val = obj[key];
-        if (
-          typeof val === 'object' &&
-          ((Array.isArray(val) && val.every((v) => v == null)) ||
-            (!Array.isArray(val) && Object.keys(val).length === 0))
-        )
-          delete obj[key];
+  class ErrorUtil {
+    static assert(condition, message, meta) {
+      if (!condition) throw new CmpStrUsageError(message, meta);
+    }
+    static rethrow(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) {
+        if (err instanceof CmpStrError) throw err;
+        throw new CmpStrInternalError(message, meta, err);
       }
-      return true;
-    };
-    remove(t);
-    return t;
+    }
+    static async wrapAsync(fn, message, meta) {
+      try {
+        return await fn();
+      } catch (err) {
+        if (err instanceof CmpStrError) throw err;
+        throw new CmpStrInternalError(message, meta, err);
+      }
+    }
   }
 
-  var DeepMerge = /*#__PURE__*/ Object.freeze({
+  var Errors = /*#__PURE__*/ Object.freeze({
     __proto__: null,
-    get: get,
-    has: has,
-    merge: merge,
-    rmv: rmv,
-    set: set
+    CmpStrError: CmpStrError,
+    CmpStrInternalError: CmpStrInternalError,
+    CmpStrNotFoundError: CmpStrNotFoundError,
+    CmpStrUsageError: CmpStrUsageError,
+    CmpStrValidationError: CmpStrValidationError,
+    ErrorUtil: ErrorUtil
   });
 
+  class DeepMerge {
+    static BRACKET_PATTERN = /\[(\d+)]/g;
+    static PATH_CACHE = new Map();
+    static walk(obj, keys) {
+      let o = obj;
+      for (let i = 0; i < keys.length; i++) {
+        const k = keys[i];
+        if (o == null || !(k in o)) return { exists: false };
+        o = o[k];
+      }
+      return { exists: true, value: o };
+    }
+    static parse(p) {
+      const cached = DeepMerge.PATH_CACHE.get(p);
+      if (cached) return cached;
+      const parsed = p
+        .replace(DeepMerge.BRACKET_PATTERN, '.$1')
+        .split('.')
+        .map((s) => {
+          const n = Number(s);
+          return Number.isInteger(n) && String(n) === s ? n : s;
+        });
+      if (DeepMerge.PATH_CACHE.size > 2000) DeepMerge.PATH_CACHE.clear();
+      DeepMerge.PATH_CACHE.set(p, parsed);
+      return parsed;
+    }
+    static has(t, path) {
+      return DeepMerge.walk(t, DeepMerge.parse(path)).exists;
+    }
+    static get(t, path, fb) {
+      const r = DeepMerge.walk(t, DeepMerge.parse(path));
+      return r.exists ? r.value : fb;
+    }
+    static set(t, path, value) {
+      if (path === '') return value;
+      const keys = DeepMerge.parse(path);
+      ErrorUtil.assert(
+        t === undefined || (typeof t === 'object' && t !== null),
+        `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];
+        ErrorUtil.assert(
+          n == null || typeof n === 'object',
+          `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);
+        cur = n;
+      }
+      cur[keys[keys.length - 1]] = value;
+      return root;
+    }
+    static rmv(t, path, preserveEmpty = false) {
+      const keys = DeepMerge.parse(path);
+      const remove = (obj, i = 0) => {
+        const key = keys[i];
+        if (!obj || typeof obj !== 'object') return false;
+        if (i === keys.length - 1) return delete obj[key];
+        if (!remove(obj[key], i + 1)) return false;
+        if (!preserveEmpty) {
+          const val = obj[key];
+          let empty = true;
+          if (typeof val === 'object') {
+            if (Array.isArray(val))
+              for (let i = 0; i < val.length; i++) {
+                if (val[i] != null) {
+                  empty = false;
+                  break;
+                }
+              }
+            else empty = false;
+          }
+          if (empty) delete obj[key];
+        }
+        return true;
+      };
+      remove(t);
+      return t;
+    }
+    static merge(
+      t = Object.create(null),
+      o = Object.create(null),
+      mergeUndefined = false
+    ) {
+      const target = t ?? Object.create(null);
+      for (const k in o) {
+        const val = o[k];
+        if (!mergeUndefined && val === undefined) continue;
+        if (k === '__proto__' || k === 'constructor') continue;
+        if (val !== null && typeof val === 'object' && !Array.isArray(val)) {
+          const existing = target[k];
+          target[k] = DeepMerge.merge(
+            existing !== null &&
+              typeof existing === 'object' &&
+              !Array.isArray(existing)
+              ? existing
+              : Object.create(null),
+            val,
+            mergeUndefined
+          );
+        } else target[k] = val;
+      }
+      return target;
+    }
+  }
+
   class DiffChecker {
     a;
     b;
@@ -422,48 +535,89 @@
   }
 
   class Filter {
+    static IDENTITY = (s) => s;
     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;
+    static getPipeline(hook, force = false) {
+      return ErrorUtil.wrap(
+        () => {
+          if (!force) {
+            const cached = Filter.pipeline.get(hook);
+            if (cached) return cached;
+          }
+          const filter = Filter.filters.get(hook);
+          if (!filter) {
+            Filter.pipeline.set(hook, Filter.IDENTITY);
+            return Filter.IDENTITY;
+          }
+          const pipeline = [];
+          for (const f of filter.values()) if (f.active) pipeline.push(f);
+          pipeline.sort((a, b) => a.priority - b.priority);
+          const fn =
+            pipeline.length === 0
+              ? Filter.IDENTITY
+              : (input) => {
+                  let v = input;
+                  for (let i = 0; i < pipeline.length; i++)
+                    v = pipeline[i].fn(v);
+                  return v;
+                };
+          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;
+          if (
+            index &&
+            index.fn === fn &&
+            index.priority === priority &&
+            index.active === active
+          )
+            return true;
+          filter.set(id, { id, fn, priority, active, overrideable });
+          Filter.filters.set(hook, filter);
+          Filter.getPipeline(hook, true);
+          return true;
+        },
+        `Error adding filter <${id}> to hook <${hook}>`,
+        { hook, id, opt }
+      );
     }
     static remove(hook, id) {
-      Filter.pipeline.delete(hook);
       const filter = Filter.filters.get(hook);
-      return filter ? filter.delete(id) : false;
+      if (!filter || !filter.delete(id)) return false;
+      Filter.getPipeline(hook, true);
+      return true;
     }
     static pause(hook, id) {
-      Filter.pipeline.delete(hook);
-      const f = Filter.filters.get(hook)?.get(id);
-      return !!(f && ((f.active = false), true));
+      const filter = Filter.filters.get(hook);
+      if (!filter) return false;
+      const f = filter.get(id);
+      if (!f || !f.active) return false;
+      f.active = false;
+      Filter.getPipeline(hook, true);
+      return true;
     }
     static resume(hook, id) {
-      Filter.pipeline.delete(hook);
-      const f = Filter.filters.get(hook)?.get(id);
-      return !!(f && ((f.active = true), true));
+      const filter = Filter.filters.get(hook);
+      if (!filter) return false;
+      const f = filter.get(id);
+      if (!f || f.active) return false;
+      f.active = true;
+      Filter.getPipeline(hook, true);
+      return true;
     }
     static list(hook, active = false) {
       const filter = Filter.filters.get(hook);
@@ -473,17 +627,36 @@
       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);
+          if (typeof input === 'string') return fn(input);
+          const arr = input;
+          const out = new Array(arr.length);
+          for (let i = 0; i < arr.length; i++) out[i] = fn(arr[i]);
+          return out;
+        },
+        `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);
+          if (typeof input === 'string') return Promise.resolve(fn(input));
+          const arr = input;
+          const out = new Array(arr.length);
+          for (let i = 0; i < arr.length; i++)
+            out[i] = Promise.resolve(fn(arr[i]));
+          return Promise.all(out);
+        },
+        `Error applying filters for hook <${hook}>`,
+        { hook, input }
+      );
     }
     static clear(hook) {
-      Filter.pipeline.clear();
+      Filter.clearPipeline();
       if (hook) Filter.filters.delete(hook);
       else Filter.filters.clear();
     }
@@ -497,25 +670,21 @@
     static HASH_OFFSET = 0x811c9dc5;
     static fastFNV1a(str) {
       const len = str.length;
+      const limit = len & -4;
       let hash = this.HASH_OFFSET;
-      const chunks = Math.floor(len / 4);
-      for (let i = 0; i < chunks; i++) {
-        const pos = i * 4;
+      let i = 0;
+      for (; i < limit; i += 4) {
         const chunk =
-          str.charCodeAt(pos) |
-          (str.charCodeAt(pos + 1) << 8) |
-          (str.charCodeAt(pos + 2) << 16) |
-          (str.charCodeAt(pos + 3) << 24);
+          str.charCodeAt(i) |
+          (str.charCodeAt(i + 1) << 8) |
+          (str.charCodeAt(i + 2) << 16) |
+          (str.charCodeAt(i + 3) << 24);
         hash ^= chunk;
         hash = Math.imul(hash, this.FNV_PRIME);
       }
-      const remaining = len % 4;
-      if (remaining > 0) {
-        const pos = chunks * 4;
-        for (let i = 0; i < remaining; i++) {
-          hash ^= str.charCodeAt(pos + i);
-          hash = Math.imul(hash, this.FNV_PRIME);
-        }
+      for (; i < len; i++) {
+        hash ^= str.charCodeAt(i);
+        hash = Math.imul(hash, this.FNV_PRIME);
       }
       hash ^= hash >>> 16;
       hash *= 0x85ebca6b;
@@ -526,32 +695,51 @@
     }
   }
   class HashTable {
-    LRU;
+    FIFO;
+    maxSize;
     static MAX_LEN = 2048;
-    static TABLE_SIZE = 10_000;
     table = new Map();
-    constructor(LRU = true) {
-      this.LRU = LRU;
+    constructor(FIFO = true, maxSize = 10000) {
+      this.FIFO = FIFO;
+      this.maxSize = maxSize;
     }
     key(label, strs, sorted = false) {
-      for (const str of strs) if (str.length > HashTable.MAX_LEN) return false;
-      const hashes = strs.map((s) => Hasher.fastFNV1a(s));
-      return [label, ...(sorted ? hashes.sort() : hashes)].join('-');
+      const n = strs.length;
+      const hashes = new Array(n);
+      for (let i = 0; i < n; i++) {
+        const s = strs[i];
+        if (s.length > HashTable.MAX_LEN) return false;
+        hashes[i] = Hasher.fastFNV1a(s);
+      }
+      if (sorted) hashes.sort((a, b) => a - b);
+      let key = label;
+      for (let i = 0; i < hashes.length; i++) key += '-' + hashes[i];
+      return key;
+    }
+    has(key) {
+      return this.table.has(key);
+    }
+    get(key) {
+      return this.table.get(key);
     }
-    has = (key) => this.table.has(key);
-    get = (key) => this.table.get(key);
     set(key, entry, update = true) {
       if (!update && this.table.has(key)) return false;
-      while (!this.table.has(key) && this.table.size >= HashTable.TABLE_SIZE) {
-        if (!this.LRU) return false;
+      if (!this.table.has(key) && this.table.size >= this.maxSize) {
+        if (!this.FIFO) return false;
         this.table.delete(this.table.keys().next().value);
       }
       this.table.set(key, entry);
       return true;
     }
-    delete = (key) => this.table.delete(key);
-    clear = () => this.table.clear();
-    size = () => this.table.size;
+    delete(key) {
+      return this.table.delete(key);
+    }
+    clear() {
+      this.table.clear();
+    }
+    size() {
+      return this.table.size;
+    }
   }
 
   class Normalizer {
@@ -568,42 +756,91 @@
       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;
-    }
-    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(
+        () => {
+          const cached = Normalizer.pipeline.get(flags);
+          if (cached) return cached;
+          const { REGEX } = Normalizer;
+          const steps = [];
+          for (let i = 0; i < flags.length; i++) {
+            switch (flags[i]) {
+              case 'd':
+                steps.push((s) => s.normalize('NFD'));
+                break;
+              case 'i':
+                steps.push((s) => s.toLowerCase());
+                break;
+              case 'k':
+                steps.push((s) => s.replace(REGEX.nonLetters, ''));
+                break;
+              case 'n':
+                steps.push((s) => s.replace(REGEX.nonNumbers, ''));
+                break;
+              case 'r':
+                steps.push((s) => s.replace(REGEX.doubleChars, '$1'));
+                break;
+              case 's':
+                steps.push((s) => s.replace(REGEX.specialChars, ''));
+                break;
+              case 't':
+                steps.push((s) => s.trim());
+                break;
+              case 'u':
+                steps.push((s) => s.normalize('NFC'));
+                break;
+              case 'w':
+                steps.push((s) => s.replace(REGEX.whitespace, ' '));
+                break;
+              case 'x':
+                steps.push((s) => s.normalize('NFKC'));
+                break;
+            }
+          }
+          const fn = (input) => {
+            let v = input;
+            for (let i = 0; i < steps.length; i++) v = steps[i](v);
+            return v;
+          };
+          Normalizer.pipeline.set(flags, fn);
+          return fn;
+        },
+        `Failed to create normalization pipeline for flags: ${flags}`,
+        { flags }
+      );
+    }
+    static normalize(input, flags, normalizedFlags) {
+      return ErrorUtil.wrap(
+        () => {
+          if (!flags || typeof flags !== 'string' || !input) return input;
+          flags = normalizedFlags ?? this.canonicalFlags(flags);
+          const pipeline = Normalizer.getPipeline(flags);
+          const normalizeOne = (s) => {
+            const key = Normalizer.cache.key(flags, [s]);
+            if (key && Normalizer.cache.has(key))
+              return Normalizer.cache.get(key);
+            const res = pipeline(s);
+            if (key) Normalizer.cache.set(key, res);
+            return res;
+          };
+          return Array.isArray(input)
+            ? input.map(normalizeOne)
+            : normalizeOne(input);
+        },
+        `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();
@@ -611,17 +848,144 @@
     }
   }
 
+  class RingPool {
+    maxSize;
+    buffers = [];
+    pointer = 0;
+    constructor(maxSize) {
+      this.maxSize = maxSize;
+    }
+    acquire(minSize, allowOversize) {
+      return ErrorUtil.wrap(
+        () => {
+          const buffers = this.buffers;
+          const len = buffers.length;
+          for (let i = 0; i < len; i++) {
+            const idx = (this.pointer + i) % len;
+            const item = buffers[idx];
+            const size = item.size;
+            if (size >= minSize && (allowOversize || size === minSize)) {
+              this.pointer = (idx + 1) % len;
+              return item;
+            }
+          }
+          return null;
+        },
+        `Failed to acquire buffer of size >= ${minSize} from pool`,
+        { minSize, allowOversize }
+      );
+    }
+    release(item) {
+      ErrorUtil.wrap(
+        () => {
+          const buffers = this.buffers;
+          if (buffers.length < this.maxSize) {
+            buffers.push(item);
+            return;
+          }
+          buffers[this.pointer] = item;
+          this.pointer = (this.pointer + 1) % this.maxSize;
+        },
+        `Failed to release buffer back to pool`,
+        { item }
+      );
+    }
+    clear() {
+      this.buffers = [];
+      this.pointer = 0;
+    }
+  }
+  class Pool {
+    static CONFIG = {
+      int32: {
+        type: 'int32',
+        maxSize: 64,
+        maxItemSize: 2048,
+        allowOversize: true
+      },
+      'arr[]': {
+        type: 'arr[]',
+        maxSize: 4,
+        maxItemSize: 1024,
+        allowOversize: false
+      },
+      'number[]': {
+        type: 'number[]',
+        maxSize: 16,
+        maxItemSize: 1024,
+        allowOversize: false
+      },
+      'string[]': {
+        type: 'string[]',
+        maxSize: 2,
+        maxItemSize: 1024,
+        allowOversize: false
+      },
+      set: { type: 'set', maxSize: 8, maxItemSize: 0, allowOversize: false },
+      map: { type: 'map', maxSize: 8, maxItemSize: 0, allowOversize: false }
+    };
+    static POOLS = {
+      int32: new RingPool(64),
+      'arr[]': new RingPool(4),
+      'number[]': new RingPool(16),
+      'string[]': new RingPool(2),
+      set: new RingPool(8),
+      map: new RingPool(8)
+    };
+    static allocate(type, size) {
+      switch (type) {
+        case 'int32':
+          return new Int32Array(size);
+        case 'arr[]':
+          return new Array(size);
+        case 'number[]':
+          return new Float64Array(size);
+        case 'string[]':
+          return new Array(size);
+        case 'set':
+          return new Set();
+        case 'map':
+          return new Map();
+      }
+    }
+    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)
+        return type === 'int32' ? item.buffer.subarray(0, size) : item.buffer;
+      return this.allocate(type, size);
+    }
+    static acquireMany(type, sizes) {
+      const out = new Array(sizes.length);
+      for (let i = 0; i < sizes.length; i++)
+        out[i] = this.acquire(type, sizes[i]);
+      return out;
+    }
+    static release(type, 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 });
+    }
+  }
+
   class Profiler {
     active;
     static ENV;
     static instance;
     nowFn;
     memFn;
-    store = new Set();
+    store = [];
+    last;
     totalTime = 0;
     totalMem = 0;
     static detectEnv() {
-      if (typeof process !== 'undefined') Profiler.ENV = 'nodejs';
+      if (typeof process !== 'undefined' && process.versions?.node)
+        Profiler.ENV = 'nodejs';
       else if (typeof performance !== 'undefined') Profiler.ENV = 'browser';
       else Profiler.ENV = 'unknown';
     }
@@ -633,7 +997,7 @@
       this.active = active;
       switch (Profiler.ENV) {
         case 'nodejs':
-          this.nowFn = () => Number(process.hrtime.bigint()) / 1e6;
+          this.nowFn = () => Number(process.hrtime.bigint()) * 1e-6;
           this.memFn = () => process.memoryUsage().heapUsed;
           break;
         case 'browser':
@@ -646,40 +1010,52 @@
           break;
       }
     }
-    now = () => this.nowFn();
-    mem = () => this.memFn();
-    profile(fn, meta) {
-      const startTime = this.now(),
-        startMem = this.mem();
-      const res = fn();
-      const deltaTime = this.now() - startTime,
-        deltaMem = this.mem() - startMem;
-      this.store.add({ time: deltaTime, mem: deltaMem, res, meta });
-      ((this.totalTime += deltaTime), (this.totalMem += deltaMem));
-      return res;
+    storeRes(entry) {
+      this.store.push((this.last = entry));
+      this.totalTime += entry.time;
+      this.totalMem += entry.mem;
     }
-    enable = () => {
+    enable() {
       this.active = true;
-    };
-    disable = () => {
+    }
+    disable() {
       this.active = false;
-    };
+    }
     clear() {
-      this.store.clear();
+      this.store.length = 0;
+      this.last = undefined;
       this.totalTime = 0;
       this.totalMem = 0;
     }
     run(fn, meta = {}) {
-      return this.active ? this.profile(fn, meta) : fn();
+      if (!this.active) return fn();
+      const startTime = this.nowFn(),
+        startMem = this.memFn();
+      const res = fn();
+      const deltaTime = this.nowFn() - startTime,
+        deltaMem = this.memFn() - startMem;
+      this.storeRes({ time: deltaTime, mem: deltaMem, res, meta });
+      return res;
     }
     async runAsync(fn, meta = {}) {
-      return this.active
-        ? this.profile(async () => await fn(), meta)
-        : await fn();
+      if (!this.active) return fn();
+      const startTime = this.nowFn(),
+        startMem = this.memFn();
+      const res = await fn();
+      const deltaTime = this.nowFn() - startTime,
+        deltaMem = this.memFn() - startMem;
+      this.storeRes({ time: deltaTime, mem: deltaMem, res, meta });
+      return res;
+    }
+    getAll() {
+      return [...this.store];
+    }
+    getLast() {
+      return this.last;
+    }
+    getTotal() {
+      return { time: this.totalTime, mem: this.totalMem };
     }
-    getAll = () => [...this.store];
-    getLast = () => this.getAll().pop();
-    getTotal = () => ({ time: this.totalTime, mem: this.totalMem });
     services = Object.freeze({
       enable: this.enable.bind(this),
       disable: this.disable.bind(this),
@@ -693,19 +1069,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 +1109,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,764 +1128,356 @@
   }
   function resolveCls(reg, cls) {
     if (!(reg in registry))
-      throw new ReferenceError(`Registry <${reg}> does not exist`);
-    return typeof cls === 'string' ? registry[reg]?.get(cls) : cls;
+      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
-      });
-    }
+    const ctor = resolveCls(reg, cls);
+    return ErrorUtil.wrap(
+      () => new ctor(...args),
+      `Failed to create instance of class <${ctor.name ?? cls}> from registry <${reg}>`,
+      { registry: reg, class: cls, args }
+    );
   }
 
-  class RingPool {
-    maxSize;
-    buffers = [];
-    pointer = 0;
-    constructor(maxSize) {
-      this.maxSize = maxSize;
+  const profiler$2 = Profiler.getInstance();
+  class Metric {
+    static cache = new HashTable();
+    metric;
+    a;
+    b;
+    origA = [];
+    origB = [];
+    options;
+    optKey;
+    symmetric;
+    results;
+    static clear() {
+      this.cache.clear();
     }
-    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;
+    static swap(a, b, m, n) {
+      return m > n ? [b, a, n, m] : [a, b, m, n];
     }
-    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;
+    static clamp(res) {
+      return Math.max(0, Math.min(1, res));
     }
-    clear() {
-      this.buffers = [];
-      this.pointer = 0;
+    constructor(metric, a, b, opt = {}, symmetric = false) {
+      this.metric = metric;
+      this.a = Array.isArray(a) ? a : [a];
+      this.b = Array.isArray(b) ? b : [b];
+      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())
+      ).toString();
+      this.symmetric = symmetric;
     }
-  }
-  class Pool {
-    static CONFIG = {
-      int32: {
-        type: 'int32',
-        maxSize: 64,
-        maxItemSize: 2048,
-        allowOversize: true
-      },
-      'number[]': {
-        type: 'number[]',
-        maxSize: 16,
-        maxItemSize: 1024,
-        allowOversize: false
-      },
-      'string[]': {
-        type: 'string[]',
-        maxSize: 2,
-        maxItemSize: 1024,
-        allowOversize: false
-      },
-      set: { type: 'set', maxSize: 8, maxItemSize: 0, allowOversize: false },
-      map: { type: 'map', maxSize: 8, maxItemSize: 0, allowOversize: false }
-    };
-    static POOLS = {
-      int32: new RingPool(64),
-      'number[]': new RingPool(16),
-      'string[]': new RingPool(2),
-      set: new RingPool(8),
-      map: new RingPool(8)
-    };
-    static allocate(type, size) {
-      switch (type) {
-        case 'int32':
-          return new Int32Array(size);
-        case 'number[]':
-          return new Float64Array(size);
-        case 'string[]':
-          return new Array(size);
-        case 'set':
-          return new Set();
-        case 'map':
-          return new Map();
-      }
+    preCompute(a, b, m, n) {
+      if (a === b) return { res: 1 };
+      if (m == 0 || n == 0 || (m < 2 && n < 2)) return { res: 0 };
+      return undefined;
     }
-    static acquire(type, size) {
-      const CONFIG = this.CONFIG[type];
-      if (size > CONFIG.maxItemSize) return this.allocate(type, size);
-      const item = this.POOLS[type].acquire(size, CONFIG.allowOversize);
-      if (item)
-        return type === 'int32' ? item.buffer.subarray(0, size) : item.buffer;
-      return this.allocate(type, size);
+    compute(a, b, m, n, maxLen) {
+      throw new CmpStrInternalError(
+        `Method compute() must be overridden in a subclass`
+      );
     }
-    static acquireMany(type, sizes) {
-      return sizes.map((size) => this.acquire(type, size));
+    runSingle(i, j) {
+      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);
+              let key = Metric.cache.key(this.metric, [A, B], this.symmetric);
+              if (key) key += this.optKey;
+              return (
+                Metric.cache.get(key || '') ??
+                (() => {
+                  const maxLen = m > n ? m : n;
+                  const res = this.compute(A, B, m, n, maxLen);
+                  if (key) Metric.cache.set(key, res);
+                  return res;
+                })()
+              );
+            });
+          }
+          return {
+            metric: this.metric,
+            a: this.origA.length > i ? this.origA[i] : a,
+            b: this.origB.length > j ? this.origB[j] : b,
+            ...result
+          };
+        },
+        `Failed to compute metric for inputs at indices a[${i}] and b[${j}]`,
+        { i, j }
+      );
     }
-    static release(type, buffer, size) {
-      if (size <= this.CONFIG[type].maxItemSize)
-        this.POOLS[type].release({ buffer, size });
+    async runSingleAsync(i, j) {
+      return Promise.resolve(this.runSingle(i, j));
     }
-  }
-
-  class StructuredData {
-    data;
-    key;
-    static create(data, key) {
-      return new StructuredData(data, key);
+    runBatch() {
+      const results = [];
+      for (let i = 0; i < this.a.length; i++)
+        for (let j = 0; j < this.b.length; j++)
+          results.push(this.runSingle(i, j));
+      this.results = results;
     }
-    constructor(data, key) {
-      this.data = data;
-      this.key = key;
+    async runBatchAsync() {
+      const tasks = [];
+      for (let i = 0; i < this.a.length; i++)
+        for (let j = 0; j < this.b.length; j++)
+          tasks.push(this.runSingleAsync(i, j));
+      this.results = await Promise.all(tasks);
     }
-    extractFrom(arr, key) {
-      const result = Pool.acquire('string[]', arr.length);
-      for (let i = 0; i < arr.length; i++) {
-        const val = arr[i][key];
-        result[i] = typeof val === 'string' ? val : String(val ?? '');
-      }
-      return result;
+    runPairwise() {
+      const results = [];
+      for (let i = 0; i < this.a.length; i++)
+        results.push(this.runSingle(i, i));
+      this.results = results;
     }
-    extract = () => this.extractFrom(this.data, this.key);
-    isMetricResult(v) {
-      return (
-        typeof v === 'object' &&
-        v !== null &&
-        'a' in v &&
-        'b' in v &&
-        'res' in v
-      );
+    async runPairwiseAsync() {
+      const tasks = [];
+      for (let i = 0; i < this.a.length; i++)
+        tasks.push(this.runSingleAsync(i, i));
+      this.results = await Promise.all(tasks);
     }
-    isCmpStrResult(v) {
-      return (
-        typeof v === 'object' &&
-        v !== null &&
-        'source' in v &&
-        'target' in v &&
-        'match' in v
-      );
+    setOriginal(a, b) {
+      if (a) this.origA = Array.isArray(a) ? a : [a];
+      if (b) this.origB = Array.isArray(b) ? b : [b];
+      return this;
     }
-    normalizeResults(results) {
-      if (!Array.isArray(results) || results.length === 0) return [];
-      const first = results[0];
-      let normalized = [];
-      if (this.isMetricResult(first)) normalized = results;
-      else if (this.isCmpStrResult(first))
-        normalized = results.map((r) => ({
-          metric: 'unknown',
-          a: r.source,
-          b: r.target,
-          res: r.match,
-          raw: r.raw
-        }));
-      else
-        throw new TypeError(
-          'Unsupported result format for StructuredData normalization.'
-        );
-      return normalized.map((r, idx) => ({ ...r, __idx: idx }));
+    isBatch() {
+      return this.a.length > 1 || this.b.length > 1;
     }
-    rebuild(results, sourceData, extractedStrings, removeZero, objectsOnly) {
-      const stringToIndices = new Map();
-      for (let i = 0; i < extractedStrings.length; i++) {
-        const str = extractedStrings[i];
-        if (!stringToIndices.has(str)) stringToIndices.set(str, []);
-        stringToIndices.get(str).push(i);
-      }
-      const output = new Array(results.length);
-      const occurrenceCount = new Map();
-      let out = 0;
-      for (let i = 0; i < results.length; i++) {
-        const result = results[i];
-        if (removeZero && result.res === 0) continue;
-        const targetStr = result.b || '';
-        const indices = stringToIndices.get(targetStr);
-        let dataIndex;
-        if (indices && indices.length > 0) {
-          const occurrence = occurrenceCount.get(targetStr) ?? 0;
-          occurrenceCount.set(targetStr, occurrence + 1);
-          dataIndex = indices[occurrence % indices.length];
-        } else {
-          dataIndex = result.__idx ?? i;
-        }
-        if (dataIndex < 0 || dataIndex >= sourceData.length) continue;
-        const sourceObj = sourceData[dataIndex];
-        const mappedTarget = extractedStrings[dataIndex] || targetStr;
-        if (objectsOnly) output[out++] = sourceObj;
-        else
-          output[out++] = {
-            obj: sourceObj,
-            key: this.key,
-            result: {
-              source: result.a,
-              target: mappedTarget,
-              match: result.res
-            },
-            ...(result.raw ? { raw: result.raw } : null)
-          };
-      }
-      output.length = out;
-      return output;
+    isSingle() {
+      return !this.isBatch();
     }
-    sort(results, sort) {
-      if (!sort || results.length <= 1) return results;
-      const asc = sort === 'asc';
-      return results.sort((a, b) => (asc ? a.res - b.res : b.res - a.res));
+    isPairwise(safe = false) {
+      return this.isBatch() && this.a.length === this.b.length
+        ? true
+        : !safe &&
+            (() => {
+              throw new CmpStrUsageError(
+                `Mode <pairwise> requires arrays of equal length`,
+                { a: this.a, b: this.b }
+              );
+            })();
     }
-    finalizeLookup(results, extractedStrings, opt) {
-      return this.rebuild(
-        this.sort(this.normalizeResults(results), opt?.sort),
-        this.data,
-        extractedStrings,
-        opt?.removeZero,
-        opt?.objectsOnly
-      );
+    isSymmetrical() {
+      return this.symmetric;
     }
-    performLookup(fn, extractedStrings, opt) {
-      return this.finalizeLookup(fn(), extractedStrings, opt);
+    whichMode(mode) {
+      return mode ?? this.options.mode ?? 'default';
     }
-    async performLookupAsync(fn, extractedStrings, opt) {
-      return this.finalizeLookup(await fn(), extractedStrings, opt);
+    clear() {
+      this.results = undefined;
     }
-    lookup(fn, query, opt) {
-      const b = this.extract();
-      try {
-        return this.performLookup(() => fn(query, b, opt), b, opt);
-      } finally {
-        Pool.release('string[]', b, b.length);
+    run(mode, clear = true) {
+      if (clear) this.clear();
+      switch (this.whichMode(mode)) {
+        case 'default':
+          if (this.isSingle()) {
+            this.results = this.runSingle(0, 0);
+            break;
+          }
+        case 'batch':
+          this.runBatch();
+          break;
+        case 'single':
+          this.results = this.runSingle(0, 0);
+          break;
+        case 'pairwise':
+          if (this.isPairwise()) this.runPairwise();
+          break;
+        default:
+          throw new CmpStrInternalError(`Unsupported mode <${mode}>`);
       }
     }
-    async lookupAsync(fn, query, opt) {
-      const b = this.extract();
-      try {
-        return await this.performLookupAsync(() => fn(query, b, opt), b, opt);
-      } finally {
-        Pool.release('string[]', b, b.length);
+    async runAsync(mode, clear = true) {
+      if (clear) this.clear();
+      switch (this.whichMode(mode)) {
+        case 'default':
+          if (this.isSingle()) {
+            this.results = await this.runSingleAsync(0, 0);
+            break;
+          }
+        case 'batch':
+          await this.runBatchAsync();
+          break;
+        case 'single':
+          this.results = await this.runSingleAsync(0, 0);
+          break;
+        case 'pairwise':
+          if (this.isPairwise()) await this.runPairwiseAsync();
+          break;
+        default:
+          throw new CmpStrInternalError(`Unsupported async mode <${mode}>`);
       }
     }
-    lookupPairs(fn, other, otherKey, opt) {
-      const a = this.extract();
-      const b = this.extractFrom(other, otherKey);
-      try {
-        return this.performLookup(() => fn(a, b, opt), a, opt);
-      } finally {
-        Pool.release('string[]', a, a.length);
-        Pool.release('string[]', b, b.length);
-      }
+    getMetricName() {
+      return this.metric;
     }
-    async lookupPairsAsync(fn, other, otherKey, opt) {
-      const a = this.extract();
-      const b = this.extractFrom(other, otherKey);
+    getResults() {
+      ErrorUtil.assert(
+        this.results !== undefined,
+        `run() must be called before getResults()`
+      );
+      return this.results;
+    }
+  }
+  const MetricRegistry = Registry('metric', Metric);
+
+  class CosineSimilarity extends Metric {
+    constructor(a, b, opt = {}) {
+      super('cosine', a, b, opt, true);
+    }
+    _termFreq(str, delimiter) {
+      const terms = str.split(delimiter);
+      const freq = Pool.acquire('map', terms.length);
+      for (const term of terms) freq.set(term, (freq.get(term) || 0) + 1);
+      return freq;
+    }
+    compute(a, b) {
+      const { delimiter = ' ' } = this.options;
+      const termsA = this._termFreq(a, delimiter);
+      const termsB = this._termFreq(b, delimiter);
       try {
-        return await this.performLookupAsync(() => fn(a, b, opt), a, opt);
+        let dotP = 0,
+          magA = 0,
+          magB = 0;
+        for (const [term, freqA] of termsA) {
+          const freqB = termsB.get(term) || 0;
+          dotP += freqA * freqB;
+          magA += freqA * freqA;
+        }
+        for (const freqB of termsB.values()) magB += freqB * freqB;
+        magA = Math.sqrt(magA);
+        magB = Math.sqrt(magB);
+        return {
+          res: magA && magB ? Metric.clamp(dotP / (magA * magB)) : 0,
+          raw: { dotProduct: dotP, magnitudeA: magA, magnitudeB: magB }
+        };
       } finally {
-        Pool.release('string[]', a, a.length);
-        Pool.release('string[]', b, b.length);
+        Pool.release('map', termsA, termsA.size);
+        Pool.release('map', termsB, termsB.size);
       }
     }
   }
+  MetricRegistry.add('cosine', CosineSimilarity);
 
-  class TextAnalyzer {
-    static REGEX = {
-      number: /\d/,
-      sentence: /(?<=[.!?])\s+/,
-      word: /\p{L}+/gu,
-      nonWord: /[^\p{L}]/gu,
-      vowelGroup: /[aeiouy]+/g,
-      letter: /\p{L}/gu,
-      ucLetter: /\p{Lu}/gu
-    };
-    text;
-    words = [];
-    sentences = [];
-    charFrequency = new Map();
-    wordHistogram = new Map();
-    syllableCache = new Map();
-    syllableStats;
-    constructor(input) {
-      this.text = input.trim();
-      this.tokenize();
-      this.computeFrequencies();
+  class DamerauLevenshteinDistance extends Metric {
+    constructor(a, b, opt = {}) {
+      super('damerau', a, b, opt, true);
     }
-    tokenize() {
-      let match;
-      const lcText = this.text.toLowerCase();
-      while ((match = TextAnalyzer.REGEX.word.exec(lcText)) !== null)
-        this.words.push(match[0]);
-      this.sentences = this.text
-        .split(TextAnalyzer.REGEX.sentence)
-        .filter(Boolean);
-    }
-    computeFrequencies() {
-      for (const char of this.text)
-        this.charFrequency.set(char, (this.charFrequency.get(char) ?? 0) + 1);
-      for (const word of this.words)
-        this.wordHistogram.set(word, (this.wordHistogram.get(word) ?? 0) + 1);
-    }
-    estimateSyllables(word) {
-      const clean = word
-        .normalize('NFC')
-        .toLowerCase()
-        .replace(TextAnalyzer.REGEX.nonWord, '');
-      if (this.syllableCache.has(clean)) return this.syllableCache.get(clean);
-      const matches = clean.match(TextAnalyzer.REGEX.vowelGroup);
-      const count = matches ? matches.length : 1;
-      this.syllableCache.set(clean, count);
-      return count;
-    }
-    computeSyllableStats() {
-      return (this.syllableStats ||= (() => {
-        const perWord = this.words
-          .map((w) => this.estimateSyllables(w))
-          .sort((a, b) => a - b);
-        const total = perWord.reduce((sum, s) => sum + s, 0);
-        const mono = perWord.filter((s) => s === 1).length;
-        const median = !perWord.length
-          ? 0
-          : perWord.length % 2 === 0
-            ? (perWord[perWord.length / 2 - 1] + perWord[perWord.length / 2]) /
-              2
-            : perWord[Math.floor(perWord.length / 2)];
+    compute(a, b, m, n, maxLen) {
+      const len = m + 1;
+      const [test, prev, curr] = Pool.acquireMany('int32', [len, len, len]);
+      try {
+        for (let i = 0; i <= m; i++) prev[i] = i;
+        for (let j = 1; j <= n; j++) {
+          curr[0] = j;
+          const cb = b.charCodeAt(j - 1);
+          for (let i = 1; i <= m; i++) {
+            const ca = a.charCodeAt(i - 1);
+            const cost = ca === cb ? 0 : 1;
+            let val = Math.min(
+              curr[i - 1] + 1,
+              prev[i] + 1,
+              prev[i - 1] + cost
+            );
+            if (
+              i > 1 &&
+              j > 1 &&
+              ca === b.charCodeAt(j - 2) &&
+              cb === a.charCodeAt(i - 2)
+            )
+              val = Math.min(val, test[i - 2] + cost);
+            curr[i] = val;
+          }
+          test.set(prev);
+          prev.set(curr);
+        }
+        const dist = prev[m];
         return {
-          total,
-          mono,
-          perWord,
-          avg: perWord.length ? total / perWord.length : 0,
-          median
+          res: maxLen === 0 ? 1 : Metric.clamp(1 - dist / maxLen),
+          raw: { dist, maxLen }
         };
-      })());
-    }
-    getLength = () => this.text.length;
-    getWordCount = () => this.words.length;
-    getSentenceCount = () => this.sentences.length;
-    getAvgWordLength() {
-      return this.words.length
-        ? this.words.join('').length / this.words.length
-        : 0;
-    }
-    getAvgSentenceLength() {
-      return this.sentences.length
-        ? this.words.length / this.sentences.length
-        : 0;
-    }
-    getWordHistogram() {
-      return Object.fromEntries(this.wordHistogram);
-    }
-    getMostCommonWords(limit = 5) {
-      return [...this.wordHistogram.entries()]
-        .sort((a, b) => b[1] - a[1])
-        .slice(0, limit)
-        .map((e) => e[0]);
-    }
-    getHapaxLegomena() {
-      return [...this.wordHistogram.entries()]
-        .filter(([, c]) => c === 1)
-        .map((e) => e[0]);
-    }
-    hasNumbers = () => TextAnalyzer.REGEX.number.test(this.text);
-    getUpperCaseRatio() {
-      const matches = this.text.match(TextAnalyzer.REGEX.letter) || [];
-      const upper = this.text.match(TextAnalyzer.REGEX.ucLetter)?.length || 0;
-      return matches.length ? upper / matches.length : 0;
-    }
-    getCharFrequency() {
-      return Object.fromEntries(this.charFrequency);
-    }
-    getUnicodeCodepoints() {
-      const result = {};
-      for (const [char, count] of this.charFrequency) {
-        const block = char
-          .charCodeAt(0)
-          .toString(16)
-          .padStart(4, '0')
-          .toUpperCase();
-        result[block] = (result[block] || 0) + count;
+      } finally {
+        Pool.release('int32', test, len);
+        Pool.release('int32', prev, len);
+        Pool.release('int32', curr, len);
       }
-      return result;
-    }
-    getLongWordRatio(len = 7) {
-      let long = 0;
-      for (const w of this.words) if (w.length >= len) long++;
-      return this.words.length ? long / this.words.length : 0;
-    }
-    getShortWordRatio(len = 3) {
-      let short = 0;
-      for (const w of this.words) if (w.length <= len) short++;
-      return this.words.length ? short / this.words.length : 0;
-    }
-    getSyllablesCount() {
-      return this.computeSyllableStats().total;
-    }
-    getMonosyllabicWordCount() {
-      return this.computeSyllableStats().mono;
-    }
-    getMinSyllablesWordCount(min) {
-      return this.computeSyllableStats().perWord.filter((w) => w >= min).length;
-    }
-    getMaxSyllablesWordCount(max) {
-      return this.computeSyllableStats().perWord.filter((w) => w <= max).length;
     }
-    getAvgSyllablesPerWord() {
-      return this.computeSyllableStats().avg;
+  }
+  MetricRegistry.add('damerau', DamerauLevenshteinDistance);
+
+  class DiceSorensenCoefficient extends Metric {
+    constructor(a, b, opt = {}) {
+      super('dice', a, b, opt, true);
     }
-    getMedianSyllablesPerWord() {
-      return this.computeSyllableStats().median;
+    _bigrams(str) {
+      const len = str.length - 1;
+      const bigrams = Pool.acquire('set', len);
+      for (let i = 0; i < len; i++) bigrams.add(str.substring(i, i + 2));
+      return bigrams;
     }
-    getHonoresR() {
+    compute(a, b) {
+      const setA = this._bigrams(a),
+        setB = this._bigrams(b);
+      const sizeA = setA.size,
+        sizeB = setB.size;
       try {
-        return (
-          (100 * Math.log(this.words.length)) /
-          (1 - this.getHapaxLegomena().length / (this.wordHistogram.size ?? 1))
-        );
-      } catch {
-        return 0;
+        let intersection = 0;
+        for (const bigram of setA) if (setB.has(bigram)) intersection++;
+        const size = sizeA + sizeB;
+        return {
+          res: size === 0 ? 1 : Metric.clamp((2 * intersection) / size),
+          raw: { intersection, size }
+        };
+      } finally {
+        Pool.release('set', setA, sizeA);
+        Pool.release('set', setB, sizeB);
       }
     }
-    getReadingTime(wpm = 200) {
-      return this.words.length / (wpm ?? 1);
+  }
+  MetricRegistry.add('dice', DiceSorensenCoefficient);
+
+  class HammingDistance extends Metric {
+    constructor(a, b, opt = {}) {
+      super('hamming', a, b, opt, true);
     }
-    getReadabilityScore(metric = 'flesch') {
-      const w = this.words.length || 1;
-      const s = this.sentences.length || 1;
-      const y = this.getSyllablesCount() || 1;
-      const asl = w / s;
-      const asw = y / w;
-      switch (metric) {
-        case 'flesch':
-          return 206.835 - 1.015 * asl - 84.6 * asw;
-        case 'fleschde':
-          return 180 - asl - 58.5 * asw;
-        case 'kincaid':
-          return 0.39 * asl + 11.8 * asw - 15.59;
+    compute(a, b, m, n, maxLen) {
+      if (m !== n) {
+        if (this.options.pad !== undefined) {
+          if (m < maxLen) a = a.padEnd(maxLen, this.options.pad);
+          if (n < maxLen) b = b.padEnd(maxLen, this.options.pad);
+          m = n = maxLen;
+        } else
+          throw new CmpStrUsageError(
+            `Strings must be of equal length for Hamming Distance, a=${m} and b=${n} given, ` +
+              `use option.pad for automatic adjustment`,
+            { a: m, b: n }
+          );
       }
-    }
-    getLIXScore() {
-      const w = this.words.length || 1;
-      const s = this.sentences.length || 1;
-      const l = this.getLongWordRatio() * w;
-      return w / s + (l / w) * 100;
-    }
-    getWSTFScore() {
-      const w = this.words.length || 1;
-      const h = (this.getMinSyllablesWordCount(3) / w) * 100;
-      const s = this.getAvgSentenceLength();
-      const l = this.getLongWordRatio() * 100;
-      const m = (this.getMonosyllabicWordCount() / w) * 100;
-      return [
-        0.1935 * h + 0.1672 * s + 0.1297 * l - 0.0327 * m - 0.875,
-        0.2007 * h + 0.1682 * s + 0.1373 * l - 2.779,
-        0.2963 * h + 0.1905 * s - 1.1144,
-        0.2744 * h + 0.2656 * s - 1.693
-      ];
+      let dist = 0;
+      for (let i = 0; i < m; i++) if (a[i] !== b[i]) dist++;
+      return { res: m === 0 ? 1 : Metric.clamp(1 - dist / m), raw: { dist } };
     }
   }
-
-  const profiler$2 = Profiler.getInstance();
-  class Metric {
-    static cache = new HashTable();
-    metric;
-    a;
-    b;
-    origA = [];
-    origB = [];
-    options;
-    optKey;
-    symmetric;
-    results;
-    static clear = () => this.cache.clear();
-    static swap = (a, b, m, n) => (m > n ? [b, a, n, m] : [a, b, m, n]);
-    static clamp = (res) => Math.max(0, Math.min(1, res));
-    constructor(metric, a, b, opt = {}, symmetric = false) {
-      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`);
-      this.options = opt;
-      this.optKey = Hasher.fastFNV1a(
-        JSON.stringify(opt, Object.keys(opt).sort())
-      ).toString();
-      this.symmetric = symmetric;
-    }
-    preCompute(a, b, m, n) {
-      if (a === b) return { res: 1 };
-      if (m == 0 || n == 0 || (m < 2 && n < 2)) return { res: 0 };
-      return undefined;
-    }
-    compute(a, b, m, n, maxLen) {
-      throw new Error(`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
-      };
-    }
-    async runSingleAsync(i, j) {
-      return Promise.resolve(this.runSingle(i, j));
-    }
-    runBatch() {
-      const results = [];
-      for (let i = 0; i < this.a.length; i++)
-        for (let j = 0; j < this.b.length; j++)
-          results.push(this.runSingle(i, j));
-      this.results = results;
-    }
-    async runBatchAsync() {
-      const results = [];
-      for (let i = 0; i < this.a.length; i++)
-        for (let j = 0; j < this.b.length; j++)
-          results.push(await this.runSingleAsync(i, j));
-      this.results = results;
-    }
-    runPairwise() {
-      const results = [];
-      for (let i = 0; i < this.a.length; i++)
-        results.push(this.runSingle(i, i));
-      this.results = results;
-    }
-    async runPairwiseAsync() {
-      const results = [];
-      for (let i = 0; i < this.a.length; i++)
-        results.push(await this.runSingleAsync(i, i));
-      this.results = results;
-    }
-    setOriginal(a, b) {
-      if (a) this.origA = Array.isArray(a) ? a : [a];
-      if (b) this.origB = Array.isArray(b) ? b : [b];
-      return this;
-    }
-    isBatch = () => this.a.length > 1 || this.b.length > 1;
-    isSingle = () => !this.isBatch();
-    isPairwise(safe = false) {
-      return this.isBatch() && this.a.length === this.b.length
-        ? true
-        : !safe &&
-            (() => {
-              throw new Error(
-                `Mode <pairwise> requires arrays of equal length`
-              );
-            })();
-    }
-    isSymmetrical = () => this.symmetric;
-    whichMode = (mode) => mode ?? this.options?.mode ?? 'default';
-    clear = () => (this.results = undefined);
-    run(mode, clear = true) {
-      if (clear) this.clear();
-      switch (this.whichMode(mode)) {
-        case 'default':
-          if (this.isSingle()) {
-            this.results = this.runSingle(0, 0);
-            break;
-          }
-        case 'batch':
-          this.runBatch();
-          break;
-        case 'single':
-          this.results = this.runSingle(0, 0);
-          break;
-        case 'pairwise':
-          if (this.isPairwise()) this.runPairwise();
-          break;
-        default:
-          throw new Error(`Unsupported mode <${mode}>`);
-      }
-    }
-    async runAsync(mode, clear = true) {
-      if (clear) this.clear();
-      switch (this.whichMode(mode)) {
-        case 'default':
-          if (this.isSingle()) {
-            this.results = await this.runSingleAsync(0, 0);
-            break;
-          }
-        case 'batch':
-          await this.runBatchAsync();
-          break;
-        case 'single':
-          this.results = await this.runSingleAsync(0, 0);
-          break;
-        case 'pairwise':
-          if (this.isPairwise()) await this.runPairwiseAsync();
-          break;
-        default:
-          throw new Error(`Unsupported async mode <${mode}>`);
-      }
-    }
-    getMetricName = () => this.metric;
-    getResults() {
-      if (this.results === undefined)
-        throw new Error(`run() must be called before getResult()`);
-      return this.results;
-    }
-  }
-  const MetricRegistry = Registry('metric', Metric);
-
-  class CosineSimilarity extends Metric {
-    constructor(a, b, opt = {}) {
-      super('cosine', a, b, opt, true);
-    }
-    _termFreq(str, delimiter) {
-      const terms = str.split(delimiter);
-      const freq = Pool.acquire('map', terms.length);
-      for (const term of terms) freq.set(term, (freq.get(term) || 0) + 1);
-      return freq;
-    }
-    compute(a, b) {
-      const { delimiter = ' ' } = this.options;
-      const termsA = this._termFreq(a, delimiter);
-      const termsB = this._termFreq(b, delimiter);
-      try {
-        let dotP = 0,
-          magA = 0,
-          magB = 0;
-        for (const [term, freqA] of termsA) {
-          const freqB = termsB.get(term) || 0;
-          dotP += freqA * freqB;
-          magA += freqA * freqA;
-        }
-        for (const freqB of termsB.values()) magB += freqB * freqB;
-        magA = Math.sqrt(magA);
-        magB = Math.sqrt(magB);
-        return {
-          res: magA && magB ? Metric.clamp(dotP / (magA * magB)) : 0,
-          raw: { dotProduct: dotP, magnitudeA: magA, magnitudeB: magB }
-        };
-      } finally {
-        Pool.release('map', termsA, termsA.size);
-        Pool.release('map', termsB, termsB.size);
-      }
-    }
-  }
-  MetricRegistry.add('cosine', CosineSimilarity);
-
-  class DamerauLevenshteinDistance extends Metric {
-    constructor(a, b, opt = {}) {
-      super('damerau', a, b, opt, true);
-    }
-    compute(a, b, m, n, maxLen) {
-      const len = m + 1;
-      const [test, prev, curr] = Pool.acquireMany('int32', [len, len, len]);
-      try {
-        for (let i = 0; i <= m; i++) prev[i] = i;
-        for (let j = 1; j <= n; j++) {
-          curr[0] = j;
-          const cb = b.charCodeAt(j - 1);
-          for (let i = 1; i <= m; i++) {
-            const ca = a.charCodeAt(i - 1);
-            const cost = ca === cb ? 0 : 1;
-            let val = Math.min(
-              curr[i - 1] + 1,
-              prev[i] + 1,
-              prev[i - 1] + cost
-            );
-            if (
-              i > 1 &&
-              j > 1 &&
-              ca === b.charCodeAt(j - 2) &&
-              cb === a.charCodeAt(i - 2)
-            )
-              val = Math.min(val, test[i - 2] + cost);
-            curr[i] = val;
-          }
-          test.set(prev);
-          prev.set(curr);
-        }
-        const dist = prev[m];
-        return {
-          res: maxLen === 0 ? 1 : Metric.clamp(1 - dist / maxLen),
-          raw: { dist, maxLen }
-        };
-      } finally {
-        Pool.release('int32', test, len);
-        Pool.release('int32', prev, len);
-        Pool.release('int32', curr, len);
-      }
-    }
-  }
-  MetricRegistry.add('damerau', DamerauLevenshteinDistance);
-
-  class DiceSorensenCoefficient extends Metric {
-    constructor(a, b, opt = {}) {
-      super('dice', a, b, opt, true);
-    }
-    _bigrams(str) {
-      const len = str.length - 1;
-      const bigrams = Pool.acquire('set', len);
-      for (let i = 0; i < len; i++) bigrams.add(str.substring(i, i + 2));
-      return bigrams;
-    }
-    compute(a, b) {
-      const setA = this._bigrams(a),
-        setB = this._bigrams(b);
-      const sizeA = setA.size,
-        sizeB = setB.size;
-      try {
-        let intersection = 0;
-        for (const bigram of setA) if (setB.has(bigram)) intersection++;
-        const size = sizeA + sizeB;
-        return {
-          res: size === 0 ? 1 : Metric.clamp((2 * intersection) / size),
-          raw: { intersection, size }
-        };
-      } finally {
-        Pool.release('set', setA, sizeA);
-        Pool.release('set', setB, sizeB);
-      }
-    }
-  }
-  MetricRegistry.add('dice', DiceSorensenCoefficient);
-
-  class HammingDistance extends Metric {
-    constructor(a, b, opt = {}) {
-      super('hamming', a, b, opt, true);
-    }
-    compute(a, b, m, n, maxLen) {
-      if (m !== n) {
-        if (this.options.pad !== undefined) {
-          if (m < maxLen) a = a.padEnd(maxLen, this.options.pad);
-          if (n < maxLen) b = b.padEnd(maxLen, this.options.pad);
-          m = n = maxLen;
-        } else
-          throw new Error(
-            `Strings must be of equal length for Hamming Distance, a=${m} and b=${n} given, ` +
-              `use option.pad for automatic adjustment`
-          );
-      }
-      let dist = 0;
-      for (let i = 0; i < m; i++) if (a[i] !== b[i]) dist++;
-      return { res: m === 0 ? 1 : Metric.clamp(1 - dist / m), raw: { dist } };
-    }
-  }
-  MetricRegistry.add('hamming', HammingDistance);
+  MetricRegistry.add('hamming', HammingDistance);
 
   class JaccardIndex extends Metric {
     constructor(a, b, opt = {}) {
@@ -1752,43 +1743,59 @@
     options;
     optKey;
     map;
-    static clear = () => this.cache.clear();
+    ignoreSet;
+    static clear() {
+      this.cache.clear();
+    }
     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`);
+        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`);
-      this.options = merge(merge(defaults, map.options ?? {}), opt);
+        throw new CmpStrNotFoundError(
+          `Requested mapping <${mapId}> is not declared`,
+          { algo, mapId }
+        );
+      this.options = DeepMerge.merge(
+        DeepMerge.merge(defaults, map.options ?? {}),
+        opt
+      );
       this.optKey = Hasher.fastFNV1a(
         JSON.stringify(this.options, Object.keys(this.options).sort())
       ).toString();
       this.algo = algo;
       this.map = map;
+      this.ignoreSet = new Set(map.ignore ?? []);
     }
     applyPattern(word) {
       const { patterns = [] } = this.map;
-      if (!patterns || !patterns.length) return word;
+      if (!patterns.length) return word;
       for (const { pattern, replace, all = false } of patterns) {
-        word = word[all ? 'replaceAll' : 'replace'](pattern, replace);
+        word = all
+          ? word.replaceAll(pattern, replace)
+          : word.replace(pattern, replace);
       }
       return word;
     }
     applyRules(char, i, chars, charLen) {
       const { ruleset = [] } = this.map;
-      if (!ruleset || !ruleset.length) return undefined;
+      if (!ruleset.length) return undefined;
       const prev = chars[i - 1] || '',
         prev2 = chars[i - 2] || '';
       const next = chars[i + 1] || '',
         next2 = chars[i + 2] || '';
+      const str = chars.join('');
       for (const rule of ruleset) {
         if (rule.char && rule.char !== char) continue;
         if (rule.position === 'start' && i !== 0) continue;
         if (rule.position === 'middle' && (i === 0 || i === charLen - 1))
           continue;
-        if (rule.position === 'end' && i !== charLen) continue;
+        if (rule.position === 'end' && i !== charLen - 1) continue;
         if (rule.prev && !rule.prev.includes(prev)) continue;
         if (rule.prevNot && rule.prevNot.includes(prev)) continue;
         if (rule.prev2 && !rule.prev2.includes(prev2)) continue;
@@ -1799,12 +1806,12 @@
         if (rule.next2Not && rule.next2Not.includes(next2)) continue;
         if (
           rule.leading &&
-          !rule.leading.includes(chars.slice(0, rule.leading.length).join(''))
+          !rule.leading.includes(str.slice(0, rule.leading.length))
         )
           continue;
         if (
           rule.trailing &&
-          !rule.trailing.includes(chars.slice(-rule.trailing.length).join(''))
+          !rule.trailing.includes(str.slice(-rule.trailing.length))
         )
           continue;
         if (rule.match && !rule.match.every((c, j) => chars[i + j] === c))
@@ -1814,7 +1821,7 @@
       return undefined;
     }
     encode(word) {
-      const { map = {}, ignore = [] } = this.map;
+      const { map = {} } = this.map;
       word = this.applyPattern(word);
       const chars = this.word2Chars(word);
       const charLen = chars.length;
@@ -1822,7 +1829,7 @@
         lastCode = null;
       for (let i = 0; i < charLen; i++) {
         const char = chars[i];
-        if (ignore.includes(char)) continue;
+        if (this.ignoreSet.has(char)) continue;
         const mapped = this.mapChar(char, i, chars, charLen, lastCode, map);
         if (mapped === undefined) continue;
         ((code += mapped), (lastCode = mapped));
@@ -1842,7 +1849,9 @@
         ? input
         : (input + pad.repeat(length)).slice(0, length);
     }
-    word2Chars = (word) => word.toLowerCase().split('');
+    word2Chars(word) {
+      return Array.from(word.toLowerCase());
+    }
     exitEarly(code, i) {
       const { length = -1 } = this.options;
       return length > 0 && code.length >= length;
@@ -1851,37 +1860,52 @@
       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) {
+            let key = Phonetic.cache.key(this.algo, [word]);
+            if (key) key += 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() {
+      return this.algo;
     }
-    getAlgoName = () => this.algo;
     getIndex(input) {
       const { delimiter = ' ' } = this.options;
       return profiler$1.run(() =>
@@ -1905,10 +1929,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) {
@@ -2118,170 +2143,743 @@
     constructor(opt = {}) {
       super('metaphone', opt);
     }
-    encode(word) {
-      word = word.replace(Metaphone.REGEX.adjacent, (m, c) =>
-        c === 'C' ? m : c
-      );
-      return super.encode(word);
+    encode(word) {
+      word = word.replace(Metaphone.REGEX.adjacent, (m, c) =>
+        c === 'C' ? m : c
+      );
+      return super.encode(word);
+    }
+    adjustCode(code) {
+      return (
+        code.slice(0, 1) + code.slice(1).replace(Metaphone.REGEX.vowel, '')
+      );
+    }
+  }
+  PhoneticRegistry.add('metaphone', Metaphone);
+  PhoneticMappingRegistry.add('metaphone', 'en90', {
+    map: {
+      a: 'A',
+      b: 'B',
+      c: 'K',
+      d: 'T',
+      e: 'E',
+      f: 'F',
+      g: 'K',
+      h: 'H',
+      i: 'I',
+      j: 'J',
+      k: 'K',
+      l: 'L',
+      m: 'M',
+      n: 'N',
+      o: 'O',
+      p: 'P',
+      q: 'K',
+      r: 'R',
+      s: 'S',
+      t: 'T',
+      u: 'U',
+      v: 'F',
+      w: 'W',
+      x: 'KS',
+      y: 'Y',
+      z: 'S'
+    },
+    ruleset: [
+      { char: 'a', position: 'start', next: ['e'], code: '' },
+      { char: 'g', position: 'start', next: ['n'], code: '' },
+      { char: 'k', position: 'start', next: ['n'], code: '' },
+      { char: 'p', position: 'start', next: ['n'], code: '' },
+      { char: 'w', position: 'start', next: ['r'], code: '' },
+      { char: 'b', position: 'end', prev: ['m'], code: '' },
+      { char: 'c', next: ['h'], prevNot: ['s'], code: 'X' },
+      { char: 'c', next: ['i'], next2: ['a'], code: 'X' },
+      { char: 'c', next: ['e', 'i', 'y'], code: 'S' },
+      { char: 'd', next: ['g'], next2: ['e', 'i', 'y'], code: 'J' },
+      {
+        char: 'g',
+        next: ['h'],
+        next2Not: ['', 'a', 'e', 'i', 'o', 'u'],
+        code: ''
+      },
+      { char: 'g', trailing: 'n', code: '' },
+      { char: 'g', trailing: 'ned', code: '' },
+      { char: 'g', next: ['e', 'i', 'y'], prevNot: ['g'], code: 'J' },
+      {
+        char: 'h',
+        prev: ['a', 'e', 'i', 'o', 'u'],
+        nextNot: ['a', 'e', 'i', 'o', 'u'],
+        code: ''
+      },
+      { char: 'h', prev: ['c', 'g', 'p', 's', 't'], code: '' },
+      { char: 'k', prev: ['c'], code: '' },
+      { char: 'p', next: ['h'], code: 'F' },
+      { char: 's', next: ['h'], code: 'X' },
+      { char: 's', next: ['i'], next2: ['a', 'o'], code: 'X' },
+      { char: 't', next: ['i'], next2: ['a', 'o'], code: 'X' },
+      { char: 't', next: ['h'], code: '0' },
+      { char: 't', next: ['c'], next2: ['h'], code: '' },
+      { char: 'w', nextNot: ['a', 'e', 'i', 'o', 'u'], code: '' },
+      { char: 'h', leading: 'w', code: '' },
+      { char: 'x', position: 'start', code: 'S' },
+      { char: 'y', nextNot: ['a', 'e', 'i', 'o', 'u'], code: '' }
+    ]
+  });
+
+  class Soundex extends Phonetic {
+    static default = {
+      map: 'en',
+      delimiter: ' ',
+      length: 4,
+      pad: '0',
+      dedupe: true
+    };
+    constructor(opt = {}) {
+      super('soundex', opt);
+    }
+    adjustCode(code, chars) {
+      return chars[0].toUpperCase() + code.slice(1).replaceAll('0', '');
+    }
+  }
+  PhoneticRegistry.add('soundex', Soundex);
+  PhoneticMappingRegistry.add('soundex', 'en', {
+    map: {
+      a: '0',
+      e: '0',
+      h: '0',
+      i: '0',
+      o: '0',
+      u: '0',
+      w: '0',
+      y: '0',
+      b: '1',
+      f: '1',
+      p: '1',
+      v: '1',
+      c: '2',
+      g: '2',
+      j: '2',
+      k: '2',
+      q: '2',
+      s: '2',
+      x: '2',
+      z: '2',
+      d: '3',
+      t: '3',
+      l: '4',
+      m: '5',
+      n: '5',
+      r: '6'
+    }
+  });
+  PhoneticMappingRegistry.add('soundex', 'de', {
+    map: {
+      a: '0',
+      ä: '0',
+      e: '0',
+      h: '0',
+      i: '0',
+      j: '0',
+      o: '0',
+      ö: '0',
+      u: '0',
+      ü: '0',
+      y: '0',
+      b: '1',
+      f: '1',
+      p: '1',
+      v: '1',
+      w: '1',
+      c: '2',
+      g: '2',
+      k: '2',
+      q: '2',
+      s: '2',
+      ß: '2',
+      x: '2',
+      z: '2',
+      d: '3',
+      t: '3',
+      l: '4',
+      m: '5',
+      n: '5',
+      r: '6'
+    },
+    ruleset: [{ char: 'c', next: ['h'], code: '7' }]
+  });
+
+  class OptionsValidator {
+    static ALLOWED_FLAGS = new Set([
+      'd',
+      'u',
+      'x',
+      'w',
+      't',
+      'r',
+      's',
+      'k',
+      'n',
+      'i'
+    ]);
+    static ALLOWED_OUTPUT = new Set(['orig', 'prep']);
+    static ALLOWED_MODES = new Set(['default', 'batch', 'single', 'pairwise']);
+    static ALLOWED_SORT = new Set(['asc', 'desc']);
+    static PROCESSORS = {
+      phonetic: (opt) => {
+        if (!opt) return;
+        OptionsValidator.validatePhoneticName(opt.algo);
+        OptionsValidator.validatePhoneticOptions(opt.opt);
+      }
+    };
+    static METRIC_OPT_MAP = {
+      mode: (v) => OptionsValidator.validateMode(v),
+      delimiter: (v) => OptionsValidator.validateString(v, 'opt.delimiter'),
+      pad: (v) => OptionsValidator.validateString(v, 'opt.pad'),
+      q: (v) => OptionsValidator.validateNumber(v, 'opt.q'),
+      match: (v) => OptionsValidator.validateNumber(v, 'opt.match'),
+      mismatch: (v) => OptionsValidator.validateNumber(v, 'opt.mismatch'),
+      gap: (v) => OptionsValidator.validateNumber(v, 'opt.gap')
+    };
+    static PHONETIC_OPT_MAP = {
+      map: (v) =>
+        OptionsValidator.validateString(v, 'processors.phonetic.opt.map'),
+      delimiter: (v) =>
+        OptionsValidator.validateString(v, 'processors.phonetic.opt.delimiter'),
+      length: (v) =>
+        OptionsValidator.validateNumber(v, 'processors.phonetic.opt.length'),
+      pad: (v) =>
+        OptionsValidator.validateString(v, 'processors.phonetic.opt.pad'),
+      dedupe: (v) =>
+        OptionsValidator.validateBoolean(v, 'processors.phonetic.opt.dedupe'),
+      fallback: (v) =>
+        OptionsValidator.validateString(v, 'processors.phonetic.opt.fallback')
+    };
+    static CMPSTR_OPT_MAP = {
+      raw: (v) => OptionsValidator.validateBoolean(v, 'raw'),
+      removeZero: (v) => OptionsValidator.validateBoolean(v, 'removeZero'),
+      safeEmpty: (v) => OptionsValidator.validateBoolean(v, 'safeEmpty'),
+      flags: (v) => OptionsValidator.validateFlags(v),
+      metric: (v) => OptionsValidator.validateMetricName(v),
+      output: (v) => OptionsValidator.validateOutput(v),
+      opt: (v) => OptionsValidator.validateMetricOptions(v),
+      processors: (v) => OptionsValidator.validateProcessors(v),
+      sort: (v) => OptionsValidator.validateSort(v, 'sort'),
+      objectsOnly: (v) => OptionsValidator.validateBoolean(v, 'objectsOnly')
+    };
+    static set2string(set) {
+      return Array.from(set).join(' | ');
+    }
+    static validateType(value, name, type) {
+      if (value === undefined) return;
+      if (typeof value !== type || (type === 'number' && Number.isNaN(value))) {
+        throw new CmpStrValidationError(
+          `Invalid option <${name}>: expected ${type}`,
+          { name, value }
+        );
+      }
+    }
+    static validateEnum(value, name, set) {
+      if (value === undefined) return;
+      if (typeof value !== 'string' || !set.has(value)) {
+        throw new CmpStrValidationError(
+          `Invalid option <${name}>: expected ${OptionsValidator.set2string(set)}`,
+          { name, value }
+        );
+      }
+    }
+    static validateMap(opt, map) {
+      if (!opt) return;
+      for (const k in opt) {
+        const fn = map[k];
+        if (!fn)
+          throw new CmpStrValidationError(`Invalid option <${k}>`, {
+            option: k,
+            value: map[k]
+          });
+        fn(opt[k]);
+      }
+    }
+    static validateRegistryName(value, name, label, has, list) {
+      if (value === undefined) return;
+      if (typeof value !== 'string' || value.length === 0)
+        throw new CmpStrValidationError(
+          `Invalid option <${name}>: expected non-empty string`,
+          { name, value }
+        );
+      if (!has(value))
+        throw new CmpStrValidationError(
+          `${label} <${value}> is not registered`,
+          { name, value, available: list() }
+        );
+    }
+    static validateBoolean(value, name) {
+      OptionsValidator.validateType(value, name, 'boolean');
+    }
+    static validateNumber(value, name) {
+      OptionsValidator.validateType(value, name, 'number');
+    }
+    static validateString(value, name) {
+      OptionsValidator.validateType(value, name, 'string');
+    }
+    static validateFlags(value) {
+      if (value === undefined) return;
+      if (typeof value !== 'string')
+        throw new CmpStrValidationError(
+          `Invalid option <flags>: expected string`,
+          { flags: value }
+        );
+      for (let i = 0; i < value.length; i++) {
+        const ch = value[i];
+        if (!OptionsValidator.ALLOWED_FLAGS.has(ch))
+          throw new CmpStrValidationError(
+            `Invalid normalization flag <${ch}> in <flags>: expected ${OptionsValidator.set2string(OptionsValidator.ALLOWED_FLAGS)}`,
+            { flags: value, invalid: ch }
+          );
+      }
+    }
+    static validateOutput(value) {
+      OptionsValidator.validateEnum(
+        value,
+        'output',
+        OptionsValidator.ALLOWED_OUTPUT
+      );
+    }
+    static validateMode(value) {
+      OptionsValidator.validateEnum(
+        value,
+        'mode',
+        OptionsValidator.ALLOWED_MODES
+      );
+    }
+    static validateSort(value, name) {
+      if (value === undefined || typeof value === 'boolean') return;
+      OptionsValidator.validateEnum(value, name, OptionsValidator.ALLOWED_SORT);
+    }
+    static validateMetricName(value) {
+      OptionsValidator.validateRegistryName(
+        value,
+        'metric',
+        'Comparison metric',
+        MetricRegistry.has,
+        MetricRegistry.list
+      );
+    }
+    static validatePhoneticName(value) {
+      OptionsValidator.validateRegistryName(
+        value,
+        'phonetic',
+        'Phonetic algorithm',
+        PhoneticRegistry.has,
+        PhoneticRegistry.list
+      );
+    }
+    static validateMetricOptions(opt) {
+      OptionsValidator.validateMap(opt, OptionsValidator.METRIC_OPT_MAP);
+    }
+    static validatePhoneticOptions(opt) {
+      OptionsValidator.validateMap(opt, OptionsValidator.PHONETIC_OPT_MAP);
+    }
+    static validateProcessors(opt) {
+      if (!opt) return;
+      for (const key in opt) {
+        const fn = OptionsValidator.PROCESSORS[key];
+        if (!fn)
+          throw new CmpStrValidationError(
+            `Invalid processor type <${key}> in <processors>: expected ${Object.keys(OptionsValidator.PROCESSORS).join(' | ')}`,
+            { processors: opt, invalid: key }
+          );
+        fn(opt[key]);
+      }
+    }
+    static validateOptions(opt) {
+      OptionsValidator.validateMap(opt, OptionsValidator.CMPSTR_OPT_MAP);
+    }
+  }
+
+  class StructuredData {
+    data;
+    key;
+    static SORT_ASC = (a, b) => a.res - b.res;
+    static SORT_DESC = (a, b) => b.res - a.res;
+    static create(data, key) {
+      return new StructuredData(data, key);
+    }
+    constructor(data, key) {
+      this.data = data;
+      this.key = key;
+    }
+    extractFrom(arr, key) {
+      const n = arr.length;
+      const result = new Array(n);
+      for (let i = 0; i < n; i++) {
+        const val = arr[i][key];
+        result[i] = val != null ? String(val) : '';
+      }
+      return result;
+    }
+    extract() {
+      return this.extractFrom(this.data, this.key);
+    }
+    isMetricResult(v) {
+      return (
+        typeof v === 'object' &&
+        v !== null &&
+        'a' in v &&
+        'b' in v &&
+        'res' in v
+      );
+    }
+    isCmpStrResult(v) {
+      return (
+        typeof v === 'object' &&
+        v !== null &&
+        'source' in v &&
+        'target' in v &&
+        'match' in v
+      );
+    }
+    normalizeResults(results) {
+      if (!Array.isArray(results) || results.length === 0) return [];
+      const first = results[0];
+      let out = new Array(results.length);
+      if (this.isMetricResult(first)) {
+        const src = results;
+        for (let i = 0; i < src.length; i++) out[i] = { ...src[i], __idx: i };
+      } else if (this.isCmpStrResult(first)) {
+        const src = results;
+        for (let i = 0; i < src.length; i++) {
+          const r = src[i];
+          out[i] = {
+            metric: 'unknown',
+            a: r.source,
+            b: r.target,
+            res: r.match,
+            raw: r.raw,
+            __idx: i
+          };
+        }
+      } else
+        throw new CmpStrValidationError(
+          'Unsupported result format for StructuredData normalization.'
+        );
+      return out;
+    }
+    rebuild(results, sourceData, extractedStrings, removeZero, objectsOnly) {
+      const m = extractedStrings.length,
+        n = results.length;
+      const stringToIndices = Pool.acquire('map', m);
+      const occurrenceCount = Pool.acquire('map', n);
+      const output = new Array(n);
+      stringToIndices.clear();
+      occurrenceCount.clear();
+      try {
+        for (let i = 0; i < m; i++) {
+          const str = extractedStrings[i];
+          let arr = stringToIndices.get(str);
+          if (!arr) {
+            arr = [];
+            stringToIndices.set(str, arr);
+          }
+          arr.push(i);
+        }
+        let out = 0;
+        for (let i = 0; i < n; i++) {
+          const result = results[i];
+          if (removeZero && result.res === 0) continue;
+          const targetStr = result.b || '';
+          const indices = stringToIndices.get(targetStr);
+          let dataIndex;
+          if (indices && indices.length > 0) {
+            const occurrence = occurrenceCount.get(targetStr) ?? 0;
+            occurrenceCount.set(targetStr, occurrence + 1);
+            dataIndex = indices[occurrence % indices.length];
+          } else {
+            dataIndex = result.__idx ?? i;
+          }
+          if (dataIndex < 0 || dataIndex >= sourceData.length) continue;
+          const sourceObj = sourceData[dataIndex];
+          const mappedTarget = extractedStrings[dataIndex] || targetStr;
+          if (objectsOnly) output[out++] = sourceObj;
+          else
+            output[out++] = {
+              obj: sourceObj,
+              key: this.key,
+              result: {
+                source: result.a,
+                target: mappedTarget,
+                match: result.res
+              },
+              ...(result.raw ? { raw: result.raw } : null)
+            };
+        }
+        output.length = out;
+        return output;
+      } finally {
+        Pool.release('map', stringToIndices, m);
+        Pool.release('map', occurrenceCount, n);
+      }
+    }
+    sort(results, sort) {
+      if (!sort || results.length <= 1) return results;
+      return results.sort(
+        sort === 'asc' ? StructuredData.SORT_ASC : StructuredData.SORT_DESC
+      );
+    }
+    finalizeLookup(results, extractedStrings, opt) {
+      return this.rebuild(
+        this.sort(this.normalizeResults(results), opt?.sort),
+        this.data,
+        extractedStrings,
+        opt?.removeZero,
+        opt?.objectsOnly
+      );
+    }
+    performLookup(fn, extractedStrings, opt) {
+      return ErrorUtil.wrap(
+        () => this.finalizeLookup(fn(), extractedStrings, opt),
+        'StructuredData lookup failed',
+        { key: this.key }
+      );
+    }
+    async performLookupAsync(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();
+      try {
+        return this.performLookup(() => fn(query, b, opt), b, opt);
+      } finally {
+        Pool.release('string[]', b, b.length);
+      }
+    }
+    async lookupAsync(fn, query, opt) {
+      const b = this.extract();
+      try {
+        return await this.performLookupAsync(() => fn(query, b, opt), b, opt);
+      } finally {
+        Pool.release('string[]', b, b.length);
+      }
+    }
+    lookupPairs(fn, other, otherKey, opt) {
+      const a = this.extract();
+      const b = this.extractFrom(other, otherKey);
+      try {
+        return this.performLookup(() => fn(a, b, opt), a, opt);
+      } finally {
+        Pool.release('string[]', a, a.length);
+        Pool.release('string[]', b, b.length);
+      }
+    }
+    async lookupPairsAsync(fn, other, otherKey, opt) {
+      const a = this.extract();
+      const b = this.extractFrom(other, otherKey);
+      try {
+        return await this.performLookupAsync(() => fn(a, b, opt), a, opt);
+      } finally {
+        Pool.release('string[]', a, a.length);
+        Pool.release('string[]', b, b.length);
+      }
+    }
+  }
+
+  class TextAnalyzer {
+    static REGEX = {
+      number: /\d/,
+      sentence: /(?<=[.!?])\s+/,
+      word: /\p{L}+/gu,
+      nonWord: /[^\p{L}]/gu,
+      vowelGroup: /[aeiouy]+/g,
+      letter: /\p{L}/gu,
+      ucLetter: /\p{Lu}/gu
+    };
+    text;
+    words = [];
+    sentences = [];
+    charFrequency = new Map();
+    wordHistogram = new Map();
+    syllableCache = new Map();
+    syllableStats;
+    constructor(input) {
+      this.text = input.trim();
+      this.tokenize();
+      this.computeFrequencies();
+    }
+    tokenize() {
+      let match;
+      const lcText = this.text.toLowerCase();
+      while ((match = TextAnalyzer.REGEX.word.exec(lcText)) !== null)
+        this.words.push(match[0]);
+      this.sentences = this.text
+        .split(TextAnalyzer.REGEX.sentence)
+        .filter(Boolean);
+    }
+    computeFrequencies() {
+      for (const char of this.text)
+        this.charFrequency.set(char, (this.charFrequency.get(char) ?? 0) + 1);
+      for (const word of this.words)
+        this.wordHistogram.set(word, (this.wordHistogram.get(word) ?? 0) + 1);
+    }
+    estimateSyllables(word) {
+      const clean = word
+        .normalize('NFC')
+        .toLowerCase()
+        .replace(TextAnalyzer.REGEX.nonWord, '');
+      if (this.syllableCache.has(clean)) return this.syllableCache.get(clean);
+      const matches = clean.match(TextAnalyzer.REGEX.vowelGroup);
+      const count = matches ? matches.length : 1;
+      this.syllableCache.set(clean, count);
+      return count;
+    }
+    computeSyllableStats() {
+      return (this.syllableStats ||= (() => {
+        const perWord = this.words
+          .map((w) => this.estimateSyllables(w))
+          .sort((a, b) => a - b);
+        const total = perWord.reduce((sum, s) => sum + s, 0);
+        const mono = perWord.filter((s) => s === 1).length;
+        const median = !perWord.length
+          ? 0
+          : perWord.length % 2 === 0
+            ? (perWord[perWord.length / 2 - 1] + perWord[perWord.length / 2]) /
+              2
+            : perWord[Math.floor(perWord.length / 2)];
+        return {
+          total,
+          mono,
+          perWord,
+          avg: perWord.length ? total / perWord.length : 0,
+          median
+        };
+      })());
+    }
+    getLength = () => this.text.length;
+    getWordCount = () => this.words.length;
+    getSentenceCount = () => this.sentences.length;
+    getAvgWordLength() {
+      return this.words.length
+        ? this.words.join('').length / this.words.length
+        : 0;
+    }
+    getAvgSentenceLength() {
+      return this.sentences.length
+        ? this.words.length / this.sentences.length
+        : 0;
+    }
+    getWordHistogram() {
+      return Object.fromEntries(this.wordHistogram);
+    }
+    getMostCommonWords(limit = 5) {
+      return [...this.wordHistogram.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, limit)
+        .map((e) => e[0]);
+    }
+    getHapaxLegomena() {
+      return [...this.wordHistogram.entries()]
+        .filter(([, c]) => c === 1)
+        .map((e) => e[0]);
+    }
+    hasNumbers = () => TextAnalyzer.REGEX.number.test(this.text);
+    getUpperCaseRatio() {
+      const matches = this.text.match(TextAnalyzer.REGEX.letter) || [];
+      const upper = this.text.match(TextAnalyzer.REGEX.ucLetter)?.length || 0;
+      return matches.length ? upper / matches.length : 0;
+    }
+    getCharFrequency() {
+      return Object.fromEntries(this.charFrequency);
+    }
+    getUnicodeCodepoints() {
+      const result = {};
+      for (const [char, count] of this.charFrequency) {
+        const block = char
+          .charCodeAt(0)
+          .toString(16)
+          .padStart(4, '0')
+          .toUpperCase();
+        result[block] = (result[block] || 0) + count;
+      }
+      return result;
+    }
+    getLongWordRatio(len = 7) {
+      let long = 0;
+      for (const w of this.words) if (w.length >= len) long++;
+      return this.words.length ? long / this.words.length : 0;
+    }
+    getShortWordRatio(len = 3) {
+      let short = 0;
+      for (const w of this.words) if (w.length <= len) short++;
+      return this.words.length ? short / this.words.length : 0;
+    }
+    getSyllablesCount() {
+      return this.computeSyllableStats().total;
+    }
+    getMonosyllabicWordCount() {
+      return this.computeSyllableStats().mono;
+    }
+    getMinSyllablesWordCount(min) {
+      return this.computeSyllableStats().perWord.filter((w) => w >= min).length;
+    }
+    getMaxSyllablesWordCount(max) {
+      return this.computeSyllableStats().perWord.filter((w) => w <= max).length;
+    }
+    getAvgSyllablesPerWord() {
+      return this.computeSyllableStats().avg;
+    }
+    getMedianSyllablesPerWord() {
+      return this.computeSyllableStats().median;
+    }
+    getHonoresR() {
+      try {
+        return (
+          (100 * Math.log(this.words.length)) /
+          (1 - this.getHapaxLegomena().length / (this.wordHistogram.size ?? 1))
+        );
+      } catch {
+        return 0;
+      }
+    }
+    getReadingTime(wpm = 200) {
+      return this.words.length / (wpm ?? 1);
     }
-    adjustCode(code) {
-      return (
-        code.slice(0, 1) + code.slice(1).replace(Metaphone.REGEX.vowel, '')
-      );
+    getReadabilityScore(metric = 'flesch') {
+      const w = this.words.length || 1;
+      const s = this.sentences.length || 1;
+      const y = this.getSyllablesCount() || 1;
+      const asl = w / s;
+      const asw = y / w;
+      switch (metric) {
+        case 'flesch':
+          return 206.835 - 1.015 * asl - 84.6 * asw;
+        case 'fleschde':
+          return 180 - asl - 58.5 * asw;
+        case 'kincaid':
+          return 0.39 * asl + 11.8 * asw - 15.59;
+      }
     }
-  }
-  PhoneticRegistry.add('metaphone', Metaphone);
-  PhoneticMappingRegistry.add('metaphone', 'en90', {
-    map: {
-      a: 'A',
-      b: 'B',
-      c: 'K',
-      d: 'T',
-      e: 'E',
-      f: 'F',
-      g: 'K',
-      h: 'H',
-      i: 'I',
-      j: 'J',
-      k: 'K',
-      l: 'L',
-      m: 'M',
-      n: 'N',
-      o: 'O',
-      p: 'P',
-      q: 'K',
-      r: 'R',
-      s: 'S',
-      t: 'T',
-      u: 'U',
-      v: 'F',
-      w: 'W',
-      x: 'KS',
-      y: 'Y',
-      z: 'S'
-    },
-    ruleset: [
-      { char: 'a', position: 'start', next: ['e'], code: '' },
-      { char: 'g', position: 'start', next: ['n'], code: '' },
-      { char: 'k', position: 'start', next: ['n'], code: '' },
-      { char: 'p', position: 'start', next: ['n'], code: '' },
-      { char: 'w', position: 'start', next: ['r'], code: '' },
-      { char: 'b', position: 'end', prev: ['m'], code: '' },
-      { char: 'c', next: ['h'], prevNot: ['s'], code: 'X' },
-      { char: 'c', next: ['i'], next2: ['a'], code: 'X' },
-      { char: 'c', next: ['e', 'i', 'y'], code: 'S' },
-      { char: 'd', next: ['g'], next2: ['e', 'i', 'y'], code: 'J' },
-      {
-        char: 'g',
-        next: ['h'],
-        next2Not: ['', 'a', 'e', 'i', 'o', 'u'],
-        code: ''
-      },
-      { char: 'g', trailing: 'n', code: '' },
-      { char: 'g', trailing: 'ned', code: '' },
-      { char: 'g', next: ['e', 'i', 'y'], prevNot: ['g'], code: 'J' },
-      {
-        char: 'h',
-        prev: ['a', 'e', 'i', 'o', 'u'],
-        nextNot: ['a', 'e', 'i', 'o', 'u'],
-        code: ''
-      },
-      { char: 'h', prev: ['c', 'g', 'p', 's', 't'], code: '' },
-      { char: 'k', prev: ['c'], code: '' },
-      { char: 'p', next: ['h'], code: 'F' },
-      { char: 's', next: ['h'], code: 'X' },
-      { char: 's', next: ['i'], next2: ['a', 'o'], code: 'X' },
-      { char: 't', next: ['i'], next2: ['a', 'o'], code: 'X' },
-      { char: 't', next: ['h'], code: '0' },
-      { char: 't', next: ['c'], next2: ['h'], code: '' },
-      { char: 'w', nextNot: ['a', 'e', 'i', 'o', 'u'], code: '' },
-      { char: 'h', leading: 'w', code: '' },
-      { char: 'x', position: 'start', code: 'S' },
-      { char: 'y', nextNot: ['a', 'e', 'i', 'o', 'u'], code: '' }
-    ]
-  });
-
-  class Soundex extends Phonetic {
-    static default = {
-      map: 'en',
-      delimiter: ' ',
-      length: 4,
-      pad: '0',
-      dedupe: true
-    };
-    constructor(opt = {}) {
-      super('soundex', opt);
+    getLIXScore() {
+      const w = this.words.length || 1;
+      const s = this.sentences.length || 1;
+      const l = this.getLongWordRatio() * w;
+      return w / s + (l / w) * 100;
     }
-    adjustCode(code, chars) {
-      return chars[0].toUpperCase() + code.slice(1).replaceAll('0', '');
+    getWSTFScore() {
+      const w = this.words.length || 1;
+      const h = (this.getMinSyllablesWordCount(3) / w) * 100;
+      const s = this.getAvgSentenceLength();
+      const l = this.getLongWordRatio() * 100;
+      const m = (this.getMonosyllabicWordCount() / w) * 100;
+      return [
+        0.1935 * h + 0.1672 * s + 0.1297 * l - 0.0327 * m - 0.875,
+        0.2007 * h + 0.1682 * s + 0.1373 * l - 2.779,
+        0.2963 * h + 0.1905 * s - 1.1144,
+        0.2744 * h + 0.2656 * s - 1.693
+      ];
     }
   }
-  PhoneticRegistry.add('soundex', Soundex);
-  PhoneticMappingRegistry.add('soundex', 'en', {
-    map: {
-      a: '0',
-      e: '0',
-      h: '0',
-      i: '0',
-      o: '0',
-      u: '0',
-      w: '0',
-      y: '0',
-      b: '1',
-      f: '1',
-      p: '1',
-      v: '1',
-      c: '2',
-      g: '2',
-      j: '2',
-      k: '2',
-      q: '2',
-      s: '2',
-      x: '2',
-      z: '2',
-      d: '3',
-      t: '3',
-      l: '4',
-      m: '5',
-      n: '5',
-      r: '6'
-    }
-  });
-  PhoneticMappingRegistry.add('soundex', 'de', {
-    map: {
-      a: '0',
-      ä: '0',
-      e: '0',
-      h: '0',
-      i: '0',
-      j: '0',
-      o: '0',
-      ö: '0',
-      u: '0',
-      ü: '0',
-      y: '0',
-      b: '1',
-      f: '1',
-      p: '1',
-      v: '1',
-      w: '1',
-      c: '2',
-      g: '2',
-      k: '2',
-      q: '2',
-      s: '2',
-      ß: '2',
-      x: '2',
-      z: '2',
-      d: '3',
-      t: '3',
-      l: '4',
-      m: '5',
-      n: '5',
-      r: '6'
-    },
-    ruleset: [{ char: 'c', next: ['h'], code: '7' }]
-  });
 
   const profiler = Profiler.getInstance();
   class CmpStr {
@@ -2333,29 +2931,26 @@
     }
     assert(cond, test) {
       switch (cond) {
+        default:
+          throw new CmpStrInternalError(`Cmpstr condition <${cond}> unknown`);
         case 'metric':
-          if (!CmpStr.metric.has(test))
-            throw new Error(
-              `CmpStr <metric> must be set, call .setMetric(), ` +
-                `use CmpStr.metric.list() for available metrics`
-            );
+          OptionsValidator.validateMetricName(test);
           break;
         case 'phonetic':
-          if (!CmpStr.phonetic.has(test))
-            throw new Error(
-              `CmpStr <phonetic> must be set, call .setPhonetic(), ` +
-                `use CmpStr.phonetic.list() for available phonetic algorithms`
-            );
+          OptionsValidator.validatePhoneticName(test);
           break;
-        default:
-          throw new Error(`Cmpstr condition <${cond}> unknown`);
       }
     }
     assertMany(...cond) {
       for (const [c, test] of cond) this.assert(c, test);
     }
     resolveOptions(opt) {
-      return merge({ ...(this.options ?? Object.create(null)) }, opt);
+      const merged = DeepMerge.merge(
+        { ...(this.options ?? Object.create(null)) },
+        opt
+      );
+      OptionsValidator.validateOptions(merged);
+      return merged;
     }
     normalize(input, flags) {
       return Normalizer.normalize(input, flags ?? this.options.flags ?? '');
@@ -2371,7 +2966,7 @@
       return input;
     }
     postProcess(result, opt) {
-      if (opt?.removeZero && Array.isArray(result))
+      if (Array.isArray(result) && opt?.removeZero)
         result = result.filter((r) => r.res > 0);
       return result;
     }
@@ -2389,65 +2984,114 @@
     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 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 <${resolved.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 };
-    }
-    clone = () =>
-      Object.assign(Object.create(Object.getPrototypeOf(this)), this);
+      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() {
+      const inst = Object.assign(
+        Object.create(Object.getPrototypeOf(this)),
+        this
+      );
+      inst.options = DeepMerge.merge(Object.create(null), this.options);
+      return inst;
+    }
     reset() {
-      for (const k in this.options) delete this.options[k];
+      this.options = Object.create(null);
       return this;
     }
     setOptions(opt) {
+      OptionsValidator.validateOptions(opt);
       this.options = opt;
       return this;
     }
     mergeOptions(opt) {
-      merge(this.options, opt);
+      DeepMerge.merge(this.options, opt);
+      OptionsValidator.validateOptions(this.options);
       return this;
     }
     setSerializedOptions(opt) {
-      this.options = JSON.parse(opt);
-      return this;
+      try {
+        const parsed = JSON.parse(opt);
+        OptionsValidator.validateOptions(parsed);
+        this.options = parsed;
+        return this;
+      } catch (err) {
+        if (err instanceof SyntaxError)
+          throw new CmpStrValidationError(
+            `Failed to parse serialized options, invalid JSON string`,
+            { opt, error: err instanceof Error ? err.message : String(err) }
+          );
+        throw err;
+      }
     }
     setOption(path, value) {
-      set(this.options, path, value);
+      DeepMerge.set(this.options, path, value);
+      OptionsValidator.validateOptions(this.options);
       return this;
     }
     rmvOption(path) {
-      rmv(this.options, path);
+      DeepMerge.rmv(this.options, path);
       return this;
     }
-    setRaw = (enable) => this.setOption('raw', enable);
-    setMetric = (name) => this.setOption('metric', name);
-    setFlags = (flags) => this.setOption('flags', flags);
-    rmvFlags = () => this.rmvOption('flags');
-    setProcessors = (opt) => this.setOption('processors', opt);
-    rmvProcessors = () => this.rmvOption('processors');
-    getOptions = () => this.options;
-    getSerializedOptions = () => JSON.stringify(this.options);
-    getOption = (path) => get(this.options, path);
+    setRaw(enable) {
+      return this.setOption('raw', enable);
+    }
+    setMetric(name) {
+      return this.setOption('metric', name);
+    }
+    setFlags(flags) {
+      return this.setOption('flags', flags);
+    }
+    rmvFlags() {
+      return this.rmvOption('flags');
+    }
+    setProcessors(opt) {
+      return this.setOption('processors', opt);
+    }
+    rmvProcessors() {
+      return this.rmvOption('processors');
+    }
+    getOptions() {
+      return this.options;
+    }
+    getSerializedOptions() {
+      return JSON.stringify(this.options);
+    }
+    getOption(path) {
+      return DeepMerge.get(this.options, path);
+    }
     test(a, b, opt) {
       return this.compute(a, b, opt, 'single');
     }
@@ -2486,15 +3130,35 @@
       const resolved = this.resolveOptions({ flags, processors });
       const test = this.prepare(needle, resolved);
       const hstk = this.prepare(haystack, resolved);
-      return haystack.filter((_, i) => hstk[i].includes(test));
+      const out = [];
+      for (let i = 0, len = hstk.length; i < len; i++) {
+        if (hstk[i].includes(test)) out.push(haystack[i]);
+      }
+      return out;
     }
     matrix(input, opt) {
-      input = this.prepare(input, this.resolveOptions(opt));
-      return input.map((a) =>
-        this.compute(a, input, undefined, 'batch', true, true).map(
-          (b) => b.res ?? 0
-        )
-      );
+      const resolved = this.resolveOptions(opt);
+      const arr = this.prepare(input, resolved);
+      const n = arr.length;
+      const out = Array.from({ length: n }, () => new Array(n).fill(0));
+      for (let i = 0; i < n; i++)
+        for (let j = i; j < n; j++) {
+          if (i === j) {
+            out[i][j] = 1;
+          } else {
+            const score = this.compute(
+              arr[i],
+              arr[j],
+              resolved,
+              'single',
+              true,
+              true
+            ).res;
+            out[i][j] = score;
+            out[j][i] = score;
+          }
+        }
+      return out;
     }
     phoneticIndex(input, algo, opt) {
       const { algo: a, opt: o } = this.options.processors?.phonetic ?? {};
@@ -2577,22 +3241,28 @@
     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 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');
@@ -2630,23 +3300,40 @@
       const resolved = this.resolveOptions({ flags, processors });
       const test = await this.prepareAsync(needle, resolved);
       const hstk = await this.prepareAsync(haystack, resolved);
-      return haystack.filter((_, i) => hstk[i].includes(test));
+      const out = [];
+      for (let i = 0; i < hstk.length; i++) {
+        if (hstk[i].includes(test)) out.push(haystack[i]);
+      }
+      return out;
     }
     async matrixAsync(input, opt) {
-      input = await this.prepareAsync(input, this.resolveOptions(opt));
-      return Promise.all(
-        input.map(
-          async (a) =>
-            await this.computeAsync(
-              a,
-              input,
-              undefined,
-              'batch',
-              true,
-              true
-            ).then((r) => r.map((b) => b.res ?? 0))
-        )
-      );
+      const resolved = this.resolveOptions(opt);
+      const arr = await this.prepareAsync(input, resolved);
+      const n = arr.length;
+      const out = Array.from({ length: n }, () => new Array(n).fill(0));
+      for (let i = 0; i < n; i++) {
+        await Promise.all(
+          Array.from({ length: n - i }, (_, k) => i + k).map(async (j) => {
+            if (i === j) {
+              out[i][j] = 1;
+            } else {
+              const score = (
+                await this.computeAsync(
+                  arr[i],
+                  arr[j],
+                  resolved,
+                  'single',
+                  true,
+                  true
+                )
+              ).res;
+              out[i][j] = score;
+              out[j][i] = score;
+            }
+          })
+        );
+      }
+      return out;
     }
     async phoneticIndexAsync(input, algo, opt) {
       const { algo: a, opt: o } = this.options.processors?.phonetic ?? {};
@@ -2693,6 +3380,7 @@
 
   exports.CmpStr = CmpStr;
   exports.CmpStrAsync = CmpStrAsync;
+  exports.CmpStrError = Errors;
   exports.DeepMerge = DeepMerge;
   exports.DiffChecker = DiffChecker;
   exports.Filter = Filter;
@@ -2701,6 +3389,7 @@
   exports.Metric = Metric;
   exports.MetricRegistry = MetricRegistry;
   exports.Normalizer = Normalizer;
+  exports.OptionsValidator = OptionsValidator;
   exports.Phonetic = Phonetic;
   exports.PhoneticMappingRegistry = PhoneticMappingRegistry;
   exports.PhoneticRegistry = PhoneticRegistry;
@@ -2709,4 +3398,3 @@
   exports.StructuredData = StructuredData;
   exports.TextAnalyzer = TextAnalyzer;
 });
-//# sourceMappingURL=CmpStr.umd.js.map