cmpstr 3.2.1 → 3.3.0

package/dist/CmpStr.esm.js

@@ -1,117 +1,228 @@
 /**
- * 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
  */
-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;
@@ -408,48 +519,88 @@ class DiffChecker {
 }
 
 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);
@@ -459,17 +610,36 @@ class Filter {
     return out;
   }
   static apply(hook, input) {
-    const fn = Filter.getPipeline(hook);
-    return Array.isArray(input) ? input.map(fn) : fn(input);
+    return ErrorUtil.wrap(
+      () => {
+        const fn = Filter.getPipeline(hook);
+        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();
   }
@@ -483,25 +653,21 @@ class Hasher {
   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;
@@ -512,32 +678,51 @@ class Hasher {
   }
 }
 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 {
@@ -554,42 +739,91 @@ class Normalizer {
     return Array.from(new Set(flags)).sort().join('');
   }
   static getPipeline(flags) {
-    if (Normalizer.pipeline.has(flags)) return Normalizer.pipeline.get(flags);
-    const { REGEX } = Normalizer;
-    const steps = [
-      ['d', (s) => s.normalize('NFD')],
-      ['i', (s) => s.toLowerCase()],
-      ['k', (s) => s.replace(REGEX.nonLetters, '')],
-      ['n', (s) => s.replace(REGEX.nonNumbers, '')],
-      ['r', (s) => s.replace(REGEX.doubleChars, '$1')],
-      ['s', (s) => s.replace(REGEX.specialChars, '')],
-      ['t', (s) => s.trim()],
-      ['u', (s) => s.normalize('NFC')],
-      ['w', (s) => s.replace(REGEX.whitespace, ' ')],
-      ['x', (s) => s.normalize('NFKC')]
-    ];
-    const pipeline = steps
-      .filter(([f]) => flags.includes(f))
-      .map(([, fn]) => fn);
-    const fn = (s) => pipeline.reduce((v, f) => f(v), s);
-    Normalizer.pipeline.set(flags, fn);
-    return fn;
-  }
-  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();
@@ -597,17 +831,143 @@ class Normalizer {
   }
 }
 
+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';
   }
@@ -619,7 +979,7 @@ class Profiler {
     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':
@@ -632,40 +992,52 @@ class Profiler {
         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),
@@ -679,19 +1051,34 @@ class Profiler {
 const registry = Object.create(null);
 const factory = Object.create(null);
 function Registry(reg, ctor) {
-  if (reg in registry || reg in factory)
-    throw new Error(
-      `Registry <${reg}> already exists / overwriting is forbidden`
-    );
+  ErrorUtil.assert(
+    !(reg in registry || reg in factory),
+    `Registry <${reg}> already exists / overwriting is forbidden`,
+    { registry: reg }
+  );
   const classes = Object.create(null);
   const service = Object.freeze({
     add(name, cls, update = false) {
-      if (!(cls.prototype instanceof ctor))
-        throw new TypeError(`Class must extend <${reg}>`);
-      if (!update && name in classes)
-        throw new Error(
-          `Entry <${name}> already exists / use <update=true> to overwrite`
-        );
+      ErrorUtil.assert(
+        typeof name === 'string' && name.length > 0,
+        `Class name must be a non-empty string`,
+        { registry: reg, name }
+      );
+      ErrorUtil.assert(
+        typeof cls === 'function',
+        `Class must be a constructor function`,
+        { registry: reg, class: cls }
+      );
+      ErrorUtil.assert(
+        cls.prototype instanceof ctor,
+        `Class must extend <${reg}>`,
+        { registry: reg, class: cls }
+      );
+      ErrorUtil.assert(
+        update || !(name in classes),
+        `Class <${name}> already exists / use <update=true> to overwrite`,
+        { registry: reg, name }
+      );
       classes[name] = cls;
     },
     remove(name) {
@@ -704,8 +1091,16 @@ function Registry(reg, ctor) {
       return Object.keys(classes);
     },
     get(name) {
-      if (!(name in classes))
-        throw new Error(`Class <${name}> not registered for <${reg}>`);
+      ErrorUtil.assert(
+        typeof name === 'string' && name.length > 0,
+        `Class name must be a non-empty string`,
+        { registry: reg, name }
+      );
+      ErrorUtil.assert(
+        name in classes,
+        `Class <${name}> not registered for <${reg}>`,
+        { registry: reg, name }
+      );
       return classes[name];
     }
   });
@@ -715,745 +1110,348 @@ function Registry(reg, ctor) {
 }
 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();
-  }
-  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);
+class DamerauLevenshteinDistance extends Metric {
+  constructor(a, b, opt = {}) {
+    super('damerau', a, b, opt, true);
   }
-  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;
-    }
-  }
-  getReadingTime(wpm = 200) {
-    return this.words.length / (wpm ?? 1);
-  }
-  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;
+      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);
     }
   }
-  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
-    ];
-  }
 }
+MetricRegistry.add('dice', DiceSorensenCoefficient);
 
-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;
+class HammingDistance extends Metric {
+  constructor(a, b, opt = {}) {
+    super('hamming', a, b, opt, true);
   }
   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;
-          })()
+    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 }
         );
-      });
-    }
-    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 } };
+    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);
@@ -1717,42 +1715,59 @@ class Phonetic {
   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`);
+    if (!mapId)
+      throw new CmpStrNotFoundError(
+        `No mapping specified for phonetic algorithm`,
+        { algo }
+      );
     const map = PhoneticMappingRegistry.get(algo, mapId);
     if (map === undefined)
-      throw new Error(`Requested mapping <${mapId}> is not declared`);
-    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;
@@ -1763,12 +1778,12 @@ class Phonetic {
       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))
@@ -1778,7 +1793,7 @@ class Phonetic {
     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;
@@ -1786,7 +1801,7 @@ class Phonetic {
       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));
@@ -1805,7 +1820,9 @@ class Phonetic {
       ? 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;
@@ -1814,37 +1831,52 @@ class Phonetic {
     return code;
   }
   loop(words) {
-    const index = [];
-    for (const word of words) {
-      const key = Phonetic.cache.key(this.algo, [word]) + this.optKey;
-      const code =
-        Phonetic.cache.get(key || '') ??
-        (() => {
-          const res = this.encode(word);
-          if (key) Phonetic.cache.set(key, res);
-          return res;
-        })();
-      if (code && code.length) index.push(this.equalLen(code));
-    }
-    return index;
+    return ErrorUtil.wrap(
+      () => {
+        const index = [];
+        for (const word of words) {
+          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(() =>
@@ -1867,10 +1899,11 @@ const PhoneticMappingRegistry = (() => {
   return Object.freeze({
     add(algo, id, map, update = false) {
       const mappings = maps(algo);
-      if (!update && id in mappings)
-        throw new Error(
-          `Entry <${id}> already exists / use <update=true> to overwrite`
-        );
+      ErrorUtil.assert(
+        !(!id || id in mappings) || update,
+        `Entry <${id}> already exists / use <update=true> to overwrite`,
+        { algo, id }
+      );
       mappings[id] = map;
     },
     remove(algo, id) {
@@ -2075,168 +2108,737 @@ class Metaphone extends Phonetic {
   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;
+    }
   }
-  adjustCode(code) {
-    return code.slice(0, 1) + code.slice(1).replace(Metaphone.REGEX.vowel, '');
+  getReadingTime(wpm = 200) {
+    return this.words.length / (wpm ?? 1);
   }
-}
-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);
+  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;
+    }
   }
-  adjustCode(code, chars) {
-    return chars[0].toUpperCase() + code.slice(1).replaceAll('0', '');
+  getLIXScore() {
+    const w = this.words.length || 1;
+    const s = this.sentences.length || 1;
+    const l = this.getLongWordRatio() * w;
+    return w / s + (l / w) * 100;
   }
-}
-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'
+  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
+    ];
   }
-});
-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 {
@@ -2288,29 +2890,26 @@ class CmpStr {
   }
   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 ?? '');
@@ -2326,7 +2925,7 @@ class CmpStr {
     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;
   }
@@ -2344,64 +2943,114 @@ class CmpStr {
   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 };
+    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;
   }
-  clone = () => Object.assign(Object.create(Object.getPrototypeOf(this)), this);
   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');
   }
@@ -2440,15 +3089,35 @@ class CmpStr {
     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 ?? {};
@@ -2528,22 +3197,28 @@ class CmpStrAsync extends CmpStr {
   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');
@@ -2581,23 +3256,40 @@ class CmpStrAsync extends CmpStr {
     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 ?? {};
@@ -2645,6 +3337,7 @@ class CmpStrAsync extends CmpStr {
 export {
   CmpStr,
   CmpStrAsync,
+  Errors as CmpStrError,
   DeepMerge,
   DiffChecker,
   Filter,
@@ -2653,6 +3346,7 @@ export {
   Metric,
   MetricRegistry,
   Normalizer,
+  OptionsValidator,
   Phonetic,
   PhoneticMappingRegistry,
   PhoneticRegistry,
@@ -2661,4 +3355,3 @@ export {
   StructuredData,
   TextAnalyzer
 };
-//# sourceMappingURL=CmpStr.esm.js.map