cmpstr 3.2.1 → 3.3.0

package/dist/esm/CmpStr.mjs

@@ -1,8 +1,14 @@
-// CmpStr v3.2.1 build-3439ccb-260130 by Paul Köhler @komed3 / MIT License
-import { merge, set, rmv, get } 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 { DiffChecker } from './utils/DiffChecker.mjs';
+import {
+  CmpStrInternalError,
+  ErrorUtil,
+  CmpStrValidationError
+} from './utils/Errors.mjs';
 import { Filter } from './utils/Filter.mjs';
 import { Normalizer } from './utils/Normalizer.mjs';
+import { OptionsValidator } from './utils/OptionsValidator.mjs';
 import { Profiler } from './utils/Profiler.mjs';
 import { factory } from './utils/Registry.mjs';
 import { StructuredData } from './utils/StructuredData.mjs';
@@ -79,29 +85,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 ?? '');
@@ -117,7 +120,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;
   }
@@ -135,64 +138,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');
   }
@@ -231,15 +284,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 ?? {};
@@ -284,4 +357,3 @@ class CmpStr {
 }
 
 export { CmpStr };
-//# sourceMappingURL=CmpStr.mjs.map

package/dist/esm/CmpStrAsync.mjs

@@ -1,4 +1,5 @@
-// 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 } from './utils/Errors.mjs';
 import { Filter } from './utils/Filter.mjs';
 import { Normalizer } from './utils/Normalizer.mjs';
 import { factory } from './utils/Registry.mjs';
@@ -40,22 +41,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');
@@ -93,23 +100,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 ?? {};
@@ -155,4 +179,3 @@ class CmpStrAsync extends CmpStr {
 }
 
 export { CmpStrAsync };
-//# sourceMappingURL=CmpStrAsync.mjs.map

package/dist/esm/index.mjs

@@ -1,7 +1,6 @@
-// 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';
 export { Normalizer } from './utils/Normalizer.mjs';
 export { TextAnalyzer } from './utils/TextAnalyzer.mjs';
-//# sourceMappingURL=index.mjs.map

package/dist/esm/metric/Cosine.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 CosineSimilarity extends Metric {
 MetricRegistry.add('cosine', CosineSimilarity);
 
 export { CosineSimilarity };
-//# sourceMappingURL=Cosine.mjs.map

package/dist/esm/metric/DamerauLevenshtein.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';
 
@@ -45,4 +45,3 @@ class DamerauLevenshteinDistance extends Metric {
 MetricRegistry.add('damerau', DamerauLevenshteinDistance);
 
 export { DamerauLevenshteinDistance };
-//# sourceMappingURL=DamerauLevenshtein.mjs.map

package/dist/esm/metric/DiceSorensen.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';
 
@@ -34,4 +34,3 @@ class DiceSorensenCoefficient extends Metric {
 MetricRegistry.add('dice', DiceSorensenCoefficient);
 
 export { DiceSorensenCoefficient };
-//# sourceMappingURL=DiceSorensen.mjs.map

package/dist/esm/metric/Hamming.mjs

@@ -1,5 +1,6 @@
-// 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 { MetricRegistry, Metric } from './Metric.mjs';
+import { CmpStrUsageError } from '../utils/Errors.mjs';
 
 class HammingDistance extends Metric {
   constructor(a, b, opt = {}) {
@@ -12,9 +13,10 @@ class HammingDistance extends Metric {
         if (n < maxLen) b = b.padEnd(maxLen, this.options.pad);
         m = n = maxLen;
       } else
-        throw new Error(
+        throw new CmpStrUsageError(
           `Strings must be of equal length for Hamming Distance, a=${m} and b=${n} given, ` +
-            `use option.pad for automatic adjustment`
+            `use option.pad for automatic adjustment`,
+          { a: m, b: n }
         );
     }
     let dist = 0;
@@ -25,4 +27,3 @@ class HammingDistance extends Metric {
 MetricRegistry.add('hamming', HammingDistance);
 
 export { HammingDistance };
-//# sourceMappingURL=Hamming.mjs.map

package/dist/esm/metric/Jaccard.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';
 
@@ -27,4 +27,3 @@ class JaccardIndex extends Metric {
 MetricRegistry.add('jaccard', JaccardIndex);
 
 export { JaccardIndex };
-//# sourceMappingURL=Jaccard.mjs.map

package/dist/esm/metric/JaroWinkler.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';
 
@@ -59,4 +59,3 @@ class JaroWinklerDistance extends Metric {
 MetricRegistry.add('jaroWinkler', JaroWinklerDistance);
 
 export { JaroWinklerDistance };
-//# sourceMappingURL=JaroWinkler.mjs.map

package/dist/esm/metric/LCS.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';
 
@@ -34,4 +34,3 @@ class LCSMetric extends Metric {
 MetricRegistry.add('lcs', LCSMetric);
 
 export { LCSMetric };
-//# sourceMappingURL=LCS.mjs.map

package/dist/esm/metric/Levenshtein.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';
 
@@ -34,4 +34,3 @@ class LevenshteinDistance extends Metric {
 MetricRegistry.add('levenshtein', LevenshteinDistance);
 
 export { LevenshteinDistance };
-//# sourceMappingURL=Levenshtein.mjs.map