cmpstr 3.2.2 → 3.3.0

package/dist/cjs/utils/Pool.cjs

@@ -1,4 +1,4 @@
-// CmpStr v3.2.2 build-bb61120-260311 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.3.0 build-3699f85-260318 by Paul Köhler @komed3 / MIT License
 'use strict';
 
 var Errors = require('./Errors.cjs');
@@ -13,15 +13,14 @@ class RingPool {
   acquire(minSize, allowOversize) {
     return Errors.ErrorUtil.wrap(
       () => {
-        const len = this.buffers.length;
+        const buffers = this.buffers;
+        const len = 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);
+          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;
           }
         }
@@ -34,9 +33,12 @@ class RingPool {
   release(item) {
     Errors.ErrorUtil.wrap(
       () => {
-        if (this.buffers.length < this.maxSize)
-          return void [this.buffers.push(item)];
-        this.buffers[this.pointer] = item;
+        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`,
@@ -56,6 +58,12 @@ class Pool {
       maxItemSize: 2048,
       allowOversize: true
     },
+    'arr[]': {
+      type: 'arr[]',
+      maxSize: 4,
+      maxItemSize: 1024,
+      allowOversize: false
+    },
     'number[]': {
       type: 'number[]',
       maxSize: 16,
@@ -73,6 +81,7 @@ class Pool {
   };
   static POOLS = {
     int32: new RingPool(64),
+    'arr[]': new RingPool(4),
     'number[]': new RingPool(16),
     'string[]': new RingPool(2),
     set: new RingPool(8),
@@ -82,6 +91,8 @@ class Pool {
     switch (type) {
       case 'int32':
         return new Int32Array(size);
+      case 'arr[]':
+        return new Array(size);
       case 'number[]':
         return new Float64Array(size);
       case 'string[]':
@@ -105,7 +116,10 @@ class Pool {
     return this.allocate(type, size);
   }
   static acquireMany(type, sizes) {
-    return sizes.map((size) => this.acquire(type, size));
+    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];

package/dist/cjs/utils/Profiler.cjs

@@ -1,4 +1,4 @@
-// CmpStr v3.2.2 build-bb61120-260311 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.3.0 build-3699f85-260318 by Paul Köhler @komed3 / MIT License
 'use strict';
 
 class Profiler {
@@ -7,11 +7,13 @@ class Profiler {
   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';
   }
@@ -23,7 +25,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':
@@ -36,40 +38,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),

package/dist/cjs/utils/Registry.cjs

@@ -1,4 +1,4 @@
-// CmpStr v3.2.2 build-bb61120-260311 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.3.0 build-3699f85-260318 by Paul Köhler @komed3 / MIT License
 'use strict';
 
 var Errors = require('./Errors.cjs');
@@ -68,13 +68,13 @@ function resolveCls(reg, cls) {
     throw new Errors.CmpStrNotFoundError(`Registry <${reg}> does not exist`, {
       registry: reg
     });
-  return typeof cls === 'string' ? registry[reg]?.get(cls) : cls;
+  return typeof cls === 'string' ? registry[reg].get(cls) : cls;
 }
 function createFromRegistry(reg, cls, ...args) {
-  cls = resolveCls(reg, cls);
+  const ctor = resolveCls(reg, cls);
   return Errors.ErrorUtil.wrap(
-    () => new cls(...args),
-    `Failed to create instance of class <${cls.name ?? cls}> from registry <${reg}>`,
+    () => new ctor(...args),
+    `Failed to create instance of class <${ctor.name ?? cls}> from registry <${reg}>`,
     { registry: reg, class: cls, args }
   );
 }

package/dist/cjs/utils/StructuredData.cjs

@@ -1,4 +1,4 @@
-// CmpStr v3.2.2 build-bb61120-260311 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.3.0 build-3699f85-260318 by Paul Köhler @komed3 / MIT License
 'use strict';
 
 var Errors = require('./Errors.cjs');
@@ -7,6 +7,8 @@ var Pool = require('./Pool.cjs');
 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);
   }
@@ -15,14 +17,17 @@ class StructuredData {
     this.key = key;
   }
   extractFrom(arr, key) {
-    const result = Pool.Pool.acquire('string[]', arr.length);
-    for (let i = 0; i < arr.length; i++) {
+    const n = arr.length;
+    const result = new Array(n);
+    for (let i = 0; i < n; i++) {
       const val = arr[i][key];
-      result[i] = typeof val === 'string' ? val : String(val ?? '');
+      result[i] = val != null ? String(val) : '';
     }
     return result;
   }
-  extract = () => this.extractFrom(this.data, this.key);
+  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
@@ -40,64 +45,89 @@ class StructuredData {
   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
+    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 Errors.CmpStrValidationError(
         'Unsupported result format for StructuredData normalization.'
       );
-    return normalized.map((r, idx) => ({ ...r, __idx: idx }));
+    return out;
   }
   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;
+    const m = extractedStrings.length,
+      n = results.length;
+    const stringToIndices = Pool.Pool.acquire('map', m);
+    const occurrenceCount = Pool.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);
       }
-      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)
-        };
+      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.Pool.release('map', stringToIndices, m);
+      Pool.Pool.release('map', occurrenceCount, n);
     }
-    output.length = out;
-    return output;
   }
   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));
+    return results.sort(
+      sort === 'asc' ? StructuredData.SORT_ASC : StructuredData.SORT_DESC
+    );
   }
   finalizeLookup(results, extractedStrings, opt) {
     return this.rebuild(

package/dist/cjs/utils/TextAnalyzer.cjs

@@ -1,4 +1,4 @@
-// CmpStr v3.2.2 build-bb61120-260311 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.3.0 build-3699f85-260318 by Paul Köhler @komed3 / MIT License
 'use strict';
 
 class TextAnalyzer {

package/dist/esm/CmpStr.mjs

@@ -1,13 +1,14 @@
-// CmpStr v3.2.2 build-bb61120-260311 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,
-  CmpStrNotFoundError,
-  ErrorUtil
+  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';
@@ -84,31 +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 CmpStrNotFoundError(
-            `CmpStr <metric> must be set, call .setMetric(), ` +
-              `use CmpStr.metric.list() for available metrics`,
-            { metric: test }
-          );
+        OptionsValidator.validateMetricName(test);
         break;
       case 'phonetic':
-        if (!CmpStr.phonetic.has(test))
-          throw new CmpStrNotFoundError(
-            `CmpStr <phonetic> must be set, call .setPhonetic(), ` +
-              `use CmpStr.phonetic.list() for available phonetic algorithms`,
-            { phonetic: test }
-          );
+        OptionsValidator.validatePhoneticName(test);
         break;
-      default:
-        throw new CmpStrInternalError(`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 ?? '');
@@ -124,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;
   }
@@ -140,10 +136,10 @@ class CmpStr {
     return StructuredData.create(data, key);
   }
   compute(a, b, opt, mode, raw, skip) {
+    const resolved = this.resolveOptions(opt);
+    this.assert('metric', resolved.metric);
     return ErrorUtil.wrap(
       () => {
-        const resolved = this.resolveOptions(opt);
-        this.assert('metric', resolved.metric);
         const A = skip ? a : this.prepare(a, resolved);
         const B = skip ? b : this.prepare(b, resolved);
         if (
@@ -161,7 +157,7 @@ class CmpStr {
         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`,
+      `Failed to compute metric <${resolved.metric}> for the given inputs`,
       { a, b, options: opt }
     );
   }
@@ -177,46 +173,79 @@ class CmpStr {
       { result, raw }
     );
   }
-  clone = () => Object.assign(Object.create(Object.getPrototypeOf(this)), this);
+  clone() {
+    const inst = Object.assign(
+      Object.create(Object.getPrototypeOf(this)),
+      this
+    );
+    inst.options = DeepMerge.merge(Object.create(null), this.options);
+    return inst;
+  }
   reset() {
-    for (const k in this.options) delete this.options[k];
+    this.options = Object.create(null);
     return this;
   }
   setOptions(opt) {
+    OptionsValidator.validateOptions(opt);
     this.options = opt;
     return this;
   }
   mergeOptions(opt) {
-    merge(this.options, opt);
+    DeepMerge.merge(this.options, opt);
+    OptionsValidator.validateOptions(this.options);
     return this;
   }
   setSerializedOptions(opt) {
-    return ErrorUtil.wrap(
-      () => {
-        this.options = JSON.parse(opt);
-        return this;
-      },
-      `Failed to parse serialized options, invalid JSON string`,
-      { opt }
-    );
+    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');
   }
@@ -255,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 ?? {};