cmpstr 3.0.4 → 3.1.0

package/dist/CmpStr.umd.js

@@ -1,7 +1,7 @@
 /**
- * CmpStr v3.0.4 build-74e65a5-250915
+ * CmpStr v3.1.0 build-76aadb9-260117
  * This is a lightweight, fast and well performing library for calculating string similarity.
- * (c) 2023-2025 Paul Köhler @komed3 / MIT License
+ * (c) 2023-2026 Paul Köhler @komed3 / MIT License
  * Visit https://github.com/komed3/cmpstr and https://npmjs.org/package/cmpstr
  */
 (function (global, factory) {
@@ -23,6 +23,12 @@
   function get(t, path, fallback) {
     return parse(path).reduce((o, k) => o?.[k] ?? fallback, t);
   }
+  function has(t, path) {
+    return (
+      parse(path).reduce((o, k) => (o && k in o ? o[k] : undefined), t) !==
+      undefined
+    );
+  }
   function set(t, path, value) {
     if (path === '') return value;
     const [k, ...r] = parse(path);
@@ -77,6 +83,15 @@
     return t;
   }
 
+  var DeepMerge = /*#__PURE__*/ Object.freeze({
+    __proto__: null,
+    get: get,
+    has: has,
+    merge: merge,
+    rmv: rmv,
+    set: set
+  });
+
   class Profiler {
     static ENV;
     static instance;
@@ -847,6 +862,244 @@
     }
   }
 
+  class RingPool {
+    maxSize;
+    buffers = [];
+    pointer = 0;
+    constructor(maxSize) {
+      this.maxSize = maxSize;
+    }
+    acquire(minSize, allowOversize) {
+      const len = this.buffers.length;
+      for (let i = 0; i < len; i++) {
+        const idx = (this.pointer + i) % len;
+        const item = this.buffers[idx];
+        if (item.size >= minSize) {
+          this.pointer = (idx + 1) % len;
+          return allowOversize || item.size === minSize ? item : null;
+        }
+      }
+      return null;
+    }
+    release(item) {
+      if (this.buffers.length < this.maxSize) {
+        this.buffers.push(item);
+      } else {
+        this.buffers[this.pointer] = item;
+        this.pointer = (this.pointer + 1) % this.maxSize;
+      }
+    }
+    clear() {
+      this.buffers = [];
+      this.pointer = 0;
+    }
+  }
+  class Pool {
+    static CONFIG = {
+      uint16: {
+        type: 'uint16',
+        maxSize: 32,
+        maxItemSize: 2048,
+        allowOversize: true
+      },
+      'number[]': {
+        type: 'number[]',
+        maxSize: 16,
+        maxItemSize: 1024,
+        allowOversize: false
+      },
+      'string[]': {
+        type: 'string[]',
+        maxSize: 4,
+        maxItemSize: 1024,
+        allowOversize: false
+      },
+      set: { type: 'set', maxSize: 8, maxItemSize: 0, allowOversize: false },
+      map: { type: 'map', maxSize: 8, maxItemSize: 0, allowOversize: false }
+    };
+    static POOLS = {
+      uint16: new RingPool(32),
+      'number[]': new RingPool(16),
+      'string[]': new RingPool(4),
+      set: new RingPool(8),
+      map: new RingPool(8)
+    };
+    static allocate(type, size) {
+      switch (type) {
+        case 'uint16':
+          return new Uint16Array(size);
+        case 'number[]':
+          return new Array(size).fill(0);
+        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 (size > CONFIG.maxItemSize) return this.allocate(type, size);
+      const item = this.POOLS[type].acquire(size, CONFIG.allowOversize);
+      if (item) {
+        return type === 'uint16' ? item.buffer.subarray(0, size) : item.buffer;
+      }
+      return this.allocate(type, size);
+    }
+    static acquireMany(type, sizes) {
+      return sizes.map((size) => this.acquire(type, size));
+    }
+    static release(type, buffer, size) {
+      const CONFIG = this.CONFIG[type];
+      if (size <= CONFIG.maxItemSize) {
+        this.POOLS[type].release({ buffer, size });
+      }
+    }
+  }
+
+  class StructuredData {
+    static create(data, key) {
+      return new StructuredData(data, key);
+    }
+    data;
+    key;
+    constructor(data, key) {
+      this.data = data;
+      this.key = key;
+    }
+    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;
+    }
+    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];
+      if (this.isMetricResult(first)) return results;
+      if (this.isCmpStrResult(first))
+        return results.map((r) => ({
+          metric: 'unknown',
+          a: r.source,
+          b: r.target,
+          res: r.match,
+          raw: r.raw
+        }));
+      return [];
+    }
+    rebuild(results, sourceData, extractedStrings, removeZero, objectsOnly) {
+      const output = new Array(results.length);
+      let out = 0;
+      for (let i = 0; i < results.length; i++) {
+        const result = results[i];
+        if (removeZero && result.res === 0) continue;
+        let dataIndex =
+          result.b && extractedStrings.length
+            ? extractedStrings.indexOf(result.b)
+            : i;
+        if (dataIndex < 0 || dataIndex >= sourceData.length) dataIndex = i;
+        const sourceObj = sourceData[dataIndex];
+        if (objectsOnly) output[out++] = sourceObj;
+        else
+          output[out++] = {
+            obj: sourceObj,
+            key: this.key,
+            result: {
+              source: result.a,
+              target: extractedStrings[dataIndex] || result.b,
+              match: result.res
+            },
+            ...(result.raw ? { raw: result.raw } : null)
+          };
+      }
+      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));
+    }
+    performLookup(fn, extractedStrings, opt) {
+      return this.rebuild(
+        this.sort(this.normalizeResults(fn()), opt?.sort),
+        this.data,
+        extractedStrings,
+        opt?.removeZero,
+        opt?.objectsOnly
+      );
+    }
+    async performLookupAsync(fn, extractedStrings, opt) {
+      return this.rebuild(
+        this.sort(this.normalizeResults(await fn()), opt?.sort),
+        this.data,
+        extractedStrings,
+        opt?.removeZero,
+        opt?.objectsOnly
+      );
+    }
+    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);
+      }
+    }
+    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 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 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);
+      }
+    }
+  }
+
   const registry = Object.create(null);
   const factory = Object.create(null);
   function Registry(reg, ctor) {
@@ -1076,93 +1329,6 @@
   }
   const MetricRegistry = Registry('metric', Metric);
 
-  class RingPool {
-    maxSize;
-    buffers = [];
-    pointer = 0;
-    constructor(maxSize) {
-      this.maxSize = maxSize;
-    }
-    acquire(minSize, allowOversize) {
-      const len = this.buffers.length;
-      for (let i = 0; i < len; i++) {
-        const idx = (this.pointer + i) % len;
-        const item = this.buffers[idx];
-        if (item.size >= minSize) {
-          this.pointer = (idx + 1) % len;
-          return allowOversize || item.size === minSize ? item : null;
-        }
-      }
-      return null;
-    }
-    release(item) {
-      if (this.buffers.length < this.maxSize) {
-        this.buffers.push(item);
-      } else {
-        this.buffers[this.pointer] = item;
-        this.pointer = (this.pointer + 1) % this.maxSize;
-      }
-    }
-    clear() {
-      this.buffers = [];
-      this.pointer = 0;
-    }
-  }
-  class Pool {
-    static CONFIG = {
-      uint16: {
-        type: 'uint16',
-        maxSize: 32,
-        maxItemSize: 2048,
-        allowOversize: true
-      },
-      'number[]': {
-        type: 'number[]',
-        maxSize: 16,
-        maxItemSize: 1024,
-        allowOversize: false
-      },
-      set: { type: 'set', maxSize: 8, maxItemSize: 0, allowOversize: false },
-      map: { type: 'map', maxSize: 8, maxItemSize: 0, allowOversize: false }
-    };
-    static POOLS = {
-      uint16: new RingPool(32),
-      'number[]': new RingPool(16),
-      set: new RingPool(8),
-      map: new RingPool(8)
-    };
-    static allocate(type, size) {
-      switch (type) {
-        case 'uint16':
-          return new Uint16Array(size);
-        case 'number[]':
-          return new Array(size).fill(0);
-        case 'set':
-          return new Set();
-        case 'map':
-          return new Map();
-      }
-    }
-    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 === 'uint16' ? item.buffer.subarray(0, size) : item.buffer;
-      }
-      return this.allocate(type, size);
-    }
-    static acquireMany(type, sizes) {
-      return sizes.map((size) => this.acquire(type, size));
-    }
-    static release(type, buffer, size) {
-      const CONFIG = this.CONFIG[type];
-      if (size <= CONFIG.maxItemSize) {
-        this.POOLS[type].release({ buffer, size });
-      }
-    }
-  }
-
   class CosineSimilarity extends Metric {
     constructor(a, b, opt = {}) {
       super('cosine', a, b, opt, true);
@@ -2155,6 +2321,9 @@
         ? input.map((s) => phonetic.getIndex(s).join(delimiter))
         : phonetic.getIndex(input).join(delimiter);
     }
+    structured(data, key) {
+      return StructuredData.create(data, key);
+    }
     compute(a, b, opt, mode, raw, skip) {
       const resolved = this.resolveOptions(opt);
       this.assert('metric', resolved.metric);
@@ -2288,6 +2457,42 @@
       const { algo: a, opt: o } = this.options.processors?.phonetic ?? {};
       return this.index(input, { algo: algo ?? a, opt: opt ?? o });
     }
+    structuredLookup(query, data, key, opt) {
+      return this.structured(data, key).lookup(
+        (q, items, options) => this.batchTest(q, items, options),
+        query,
+        opt
+      );
+    }
+    structuredMatch(query, data, key, threshold, opt) {
+      return this.structured(data, key).lookup(
+        (q, items, options) => this.match(q, items, threshold, options),
+        query,
+        { ...opt, sort: 'desc' }
+      );
+    }
+    structuredClosest(query, data, key, n = 1, opt) {
+      return this.structured(data, key).lookup(
+        (q, items, options) => this.closest(q, items, n, options),
+        query,
+        { ...opt, sort: 'desc' }
+      );
+    }
+    structuredFurthest(query, data, key, n = 1, opt) {
+      return this.structured(data, key).lookup(
+        (q, items, options) => this.furthest(q, items, n, options),
+        query,
+        { ...opt, sort: 'asc' }
+      );
+    }
+    structuredPairs(data, key, other, otherKey, opt) {
+      return this.structured(data, key).lookupPairs(
+        (items, otherItems, options) => this.pairs(items, otherItems, options),
+        other,
+        otherKey,
+        opt
+      );
+    }
   }
 
   class CmpStrAsync extends CmpStr {
@@ -2404,12 +2609,60 @@
       const { algo: a, opt: o } = this.options.processors?.phonetic ?? {};
       return this.indexAsync(input, { algo: algo ?? a, opt: opt ?? o });
     }
+    async structuredLookupAsync(query, data, key, opt) {
+      return await this.structured(data, key).lookupAsync(
+        (q, items, options) => this.batchTestAsync(q, items, options),
+        query,
+        opt
+      );
+    }
+    async structuredMatchAsync(query, data, key, threshold, opt) {
+      return await this.structured(data, key).lookupAsync(
+        (q, items, options) => this.matchAsync(q, items, threshold, options),
+        query,
+        { ...opt, sort: 'desc' }
+      );
+    }
+    async structuredClosestAsync(query, data, key, n = 1, opt) {
+      return await this.structured(data, key).lookupAsync(
+        (q, items, options) => this.closestAsync(q, items, n, options),
+        query,
+        { ...opt, sort: 'desc' }
+      );
+    }
+    async structuredFurthestAsync(query, data, key, n = 1, opt) {
+      return await this.structured(data, key).lookupAsync(
+        (q, items, options) => this.furthestAsync(q, items, n, options),
+        query,
+        { ...opt, sort: 'asc' }
+      );
+    }
+    async structuredPairsAsync(data, key, other, otherKey, opt) {
+      return await this.structured(data, key).lookupPairsAsync(
+        (items, otherItems, options) =>
+          this.pairsAsync(items, otherItems, options),
+        other,
+        otherKey,
+        opt
+      );
+    }
   }
 
   exports.CmpStr = CmpStr;
   exports.CmpStrAsync = CmpStrAsync;
+  exports.DeepMerge = DeepMerge;
   exports.DiffChecker = DiffChecker;
+  exports.Filter = Filter;
+  exports.HashTable = HashTable;
+  exports.Metric = Metric;
+  exports.MetricRegistry = MetricRegistry;
   exports.Normalizer = Normalizer;
+  exports.Phonetic = Phonetic;
+  exports.PhoneticMappingRegistry = PhoneticMappingRegistry;
+  exports.PhoneticRegistry = PhoneticRegistry;
+  exports.Pool = Pool;
+  exports.Profiler = Profiler;
+  exports.StructuredData = StructuredData;
   exports.TextAnalyzer = TextAnalyzer;
 });
 //# sourceMappingURL=CmpStr.umd.js.map