cmpstr 3.2.1 → 3.3.0

package/dist/esm/metric/Metric.mjs

@@ -1,4 +1,9 @@
-// CmpStr v3.2.1 build-3439ccb-260130 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.3.0 build-3699f85-260318 by Paul Köhler @komed3 / MIT License
+import {
+  ErrorUtil,
+  CmpStrInternalError,
+  CmpStrUsageError
+} from '../utils/Errors.mjs';
 import { HashTable, Hasher } from '../utils/HashTable.mjs';
 import { Profiler } from '../utils/Profiler.mjs';
 import { Registry } from '../utils/Registry.mjs';
@@ -15,15 +20,24 @@ class Metric {
   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));
+  static clear() {
+    this.cache.clear();
+  }
+  static swap(a, b, m, n) {
+    return m > n ? [b, a, n, m] : [a, b, m, n];
+  }
+  static clamp(res) {
+    return 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`);
+    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())
@@ -36,37 +50,46 @@ class Metric {
     return undefined;
   }
   compute(a, b, m, n, maxLen) {
-    throw new Error(`Method compute() must be overridden in a subclass`);
+    throw new CmpStrInternalError(
+      `Method compute() must be overridden in a subclass`
+    );
   }
   runSingle(i, j) {
-    let a = String(this.a[i]),
-      A = a;
-    let b = String(this.b[j]),
-      B = b;
-    let m = A.length,
-      n = B.length;
-    let result = this.preCompute(A, B, m, n);
-    if (!result) {
-      result = profiler.run(() => {
-        if (this.symmetric) [A, B, m, n] = Metric.swap(A, B, m, n);
-        const key =
-          Metric.cache.key(this.metric, [A, B], this.symmetric) + this.optKey;
-        return (
-          Metric.cache.get(key || '') ??
-          (() => {
-            const res = this.compute(A, B, m, n, Math.max(m, n));
-            if (key) Metric.cache.set(key, res);
-            return res;
-          })()
-        );
-      });
-    }
-    return {
-      metric: this.metric,
-      a: this.origA[i] ?? a,
-      b: this.origB[j] ?? b,
-      ...result
-    };
+    return ErrorUtil.wrap(
+      () => {
+        let a = String(this.a[i]),
+          A = a;
+        let b = String(this.b[j]),
+          B = b;
+        let m = A.length,
+          n = B.length;
+        let result = this.preCompute(A, B, m, n);
+        if (!result) {
+          result = profiler.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 }
+    );
   }
   async runSingleAsync(i, j) {
     return Promise.resolve(this.runSingle(i, j));
@@ -79,11 +102,11 @@ class Metric {
     this.results = results;
   }
   async runBatchAsync() {
-    const results = [];
+    const tasks = [];
     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;
+        tasks.push(this.runSingleAsync(i, j));
+    this.results = await Promise.all(tasks);
   }
   runPairwise() {
     const results = [];
@@ -91,29 +114,42 @@ class Metric {
     this.results = results;
   }
   async runPairwiseAsync() {
-    const results = [];
+    const tasks = [];
     for (let i = 0; i < this.a.length; i++)
-      results.push(await this.runSingleAsync(i, i));
-    this.results = results;
+      tasks.push(this.runSingleAsync(i, i));
+    this.results = await Promise.all(tasks);
   }
   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();
+  isBatch() {
+    return this.a.length > 1 || this.b.length > 1;
+  }
+  isSingle() {
+    return !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`);
+            throw new CmpStrUsageError(
+              `Mode <pairwise> requires arrays of equal length`,
+              { a: this.a, b: this.b }
+            );
           })();
   }
-  isSymmetrical = () => this.symmetric;
-  whichMode = (mode) => mode ?? this.options?.mode ?? 'default';
-  clear = () => (this.results = undefined);
+  isSymmetrical() {
+    return this.symmetric;
+  }
+  whichMode(mode) {
+    return mode ?? this.options.mode ?? 'default';
+  }
+  clear() {
+    this.results = undefined;
+  }
   run(mode, clear = true) {
     if (clear) this.clear();
     switch (this.whichMode(mode)) {
@@ -132,7 +168,7 @@ class Metric {
         if (this.isPairwise()) this.runPairwise();
         break;
       default:
-        throw new Error(`Unsupported mode <${mode}>`);
+        throw new CmpStrInternalError(`Unsupported mode <${mode}>`);
     }
   }
   async runAsync(mode, clear = true) {
@@ -153,17 +189,20 @@ class Metric {
         if (this.isPairwise()) await this.runPairwiseAsync();
         break;
       default:
-        throw new Error(`Unsupported async mode <${mode}>`);
+        throw new CmpStrInternalError(`Unsupported async mode <${mode}>`);
     }
   }
-  getMetricName = () => this.metric;
+  getMetricName() {
+    return this.metric;
+  }
   getResults() {
-    if (this.results === undefined)
-      throw new Error(`run() must be called before getResult()`);
+    ErrorUtil.assert(
+      this.results !== undefined,
+      `run() must be called before getResults()`
+    );
     return this.results;
   }
 }
 const MetricRegistry = Registry('metric', Metric);
 
 export { Metric, MetricRegistry };
-//# sourceMappingURL=Metric.mjs.map

package/dist/esm/metric/NeedlemanWunsch.mjs

@@ -1,4 +1,4 @@
-// CmpStr v3.2.1 build-3439ccb-260130 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.3.0 build-3699f85-260318 by Paul Köhler @komed3 / MIT License
 import { Pool } from '../utils/Pool.mjs';
 import { MetricRegistry, Metric } from './Metric.mjs';
 
@@ -41,4 +41,3 @@ class NeedlemanWunschDistance extends Metric {
 MetricRegistry.add('needlemanWunsch', NeedlemanWunschDistance);
 
 export { NeedlemanWunschDistance };
-//# sourceMappingURL=NeedlemanWunsch.mjs.map

package/dist/esm/metric/QGram.mjs

@@ -1,4 +1,4 @@
-// CmpStr v3.2.1 build-3439ccb-260130 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.3.0 build-3699f85-260318 by Paul Köhler @komed3 / MIT License
 import { Pool } from '../utils/Pool.mjs';
 import { MetricRegistry, Metric } from './Metric.mjs';
 
@@ -35,4 +35,3 @@ class QGramSimilarity extends Metric {
 MetricRegistry.add('qGram', QGramSimilarity);
 
 export { QGramSimilarity };
-//# sourceMappingURL=QGram.mjs.map

package/dist/esm/metric/SmithWaterman.mjs

@@ -1,4 +1,4 @@
-// CmpStr v3.2.1 build-3439ccb-260130 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.3.0 build-3699f85-260318 by Paul Köhler @komed3 / MIT License
 import { Pool } from '../utils/Pool.mjs';
 import { MetricRegistry, Metric } from './Metric.mjs';
 
@@ -42,4 +42,3 @@ class SmithWatermanDistance extends Metric {
 MetricRegistry.add('smithWaterman', SmithWatermanDistance);
 
 export { SmithWatermanDistance };
-//# sourceMappingURL=SmithWaterman.mjs.map

package/dist/esm/phonetic/Caverphone.mjs

@@ -1,4 +1,4 @@
-// CmpStr v3.2.1 build-3439ccb-260130 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.3.0 build-3699f85-260318 by Paul Köhler @komed3 / MIT License
 import {
   PhoneticRegistry,
   PhoneticMappingRegistry,
@@ -118,4 +118,3 @@ PhoneticMappingRegistry.add('caverphone', 'en2', {
 });
 
 export { Caverphone };
-//# sourceMappingURL=Caverphone.mjs.map

package/dist/esm/phonetic/Cologne.mjs

@@ -1,4 +1,4 @@
-// CmpStr v3.2.1 build-3439ccb-260130 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.3.0 build-3699f85-260318 by Paul Köhler @komed3 / MIT License
 import {
   PhoneticRegistry,
   PhoneticMappingRegistry,
@@ -69,4 +69,3 @@ PhoneticMappingRegistry.add('cologne', 'default', {
 });
 
 export { Cologne };
-//# sourceMappingURL=Cologne.mjs.map

package/dist/esm/phonetic/Metaphone.mjs

@@ -1,4 +1,4 @@
-// CmpStr v3.2.1 build-3439ccb-260130 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.3.0 build-3699f85-260318 by Paul Köhler @komed3 / MIT License
 import {
   PhoneticRegistry,
   PhoneticMappingRegistry,
@@ -99,4 +99,3 @@ PhoneticMappingRegistry.add('metaphone', 'en90', {
 });
 
 export { Metaphone };
-//# sourceMappingURL=Metaphone.mjs.map

package/dist/esm/phonetic/Phonetic.mjs

@@ -1,5 +1,6 @@
-// CmpStr v3.2.1 build-3439ccb-260130 by Paul Köhler @komed3 / MIT License
-import { merge } from '../utils/DeepMerge.mjs';
+// CmpStr v3.3.0 build-3699f85-260318 by Paul Köhler @komed3 / MIT License
+import { DeepMerge } from '../utils/DeepMerge.mjs';
+import { CmpStrNotFoundError, ErrorUtil } from '../utils/Errors.mjs';
 import { HashTable, Hasher } from '../utils/HashTable.mjs';
 import { Profiler } from '../utils/Profiler.mjs';
 import { Registry } from '../utils/Registry.mjs';
@@ -12,42 +13,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;
@@ -58,12 +76,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))
@@ -73,7 +91,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;
@@ -81,7 +99,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));
@@ -100,7 +118,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;
@@ -109,37 +129,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.run(() =>
@@ -162,10 +197,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) {
@@ -184,4 +220,3 @@ const PhoneticMappingRegistry = (() => {
 })();
 
 export { Phonetic, PhoneticMappingRegistry, PhoneticRegistry };
-//# sourceMappingURL=Phonetic.mjs.map

package/dist/esm/phonetic/Soundex.mjs

@@ -1,4 +1,4 @@
-// CmpStr v3.2.1 build-3439ccb-260130 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.3.0 build-3699f85-260318 by Paul Köhler @komed3 / MIT License
 import {
   PhoneticRegistry,
   PhoneticMappingRegistry,
@@ -88,4 +88,3 @@ PhoneticMappingRegistry.add('soundex', 'de', {
 });
 
 export { Soundex };
-//# sourceMappingURL=Soundex.mjs.map

package/dist/esm/root.mjs

@@ -1,4 +1,4 @@
-// CmpStr v3.2.1 build-3439ccb-260130 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.3.0 build-3699f85-260318 by Paul Köhler @komed3 / MIT License
 export { CmpStr } from './CmpStr.mjs';
 export { CmpStrAsync } from './CmpStrAsync.mjs';
 export { DiffChecker } from './utils/DiffChecker.mjs';
@@ -25,11 +25,12 @@ export {
   PhoneticMappingRegistry,
   PhoneticRegistry
 } from './phonetic/Phonetic.mjs';
-import * as DeepMerge from './utils/DeepMerge.mjs';
-export { DeepMerge };
+export { DeepMerge } from './utils/DeepMerge.mjs';
+import * as Errors from './utils/Errors.mjs';
+export { Errors as CmpStrError };
 export { Filter } from './utils/Filter.mjs';
 export { HashTable, Hasher } from './utils/HashTable.mjs';
+export { OptionsValidator } from './utils/OptionsValidator.mjs';
 export { Pool } from './utils/Pool.mjs';
 export { Profiler } from './utils/Profiler.mjs';
 export { StructuredData } from './utils/StructuredData.mjs';
-//# sourceMappingURL=root.mjs.map