cmpstr 3.0.4 → 3.1.0

package/README.md

@@ -5,7 +5,7 @@
 [![Static Badge](https://img.shields.io/badge/Typescript-support?style=for-the-badge&logo=typescript&logoColor=fff&color=blue)](https://www.typescriptlang.org)
 [![GitHub package.json version](https://img.shields.io/github/package-json/v/komed3/cmpstr?style=for-the-badge&logo=npm&logoColor=fff)](https://npmjs.com/package/cmpstr)
 [![npm bundle size](https://img.shields.io/bundlephobia/min/cmpstr?style=for-the-badge&logo=gitlfs&logoColor=fff)](https://bundlephobia.com/package/cmpstr)
-[![NPM Downloads](https://img.shields.io/npm/dy/cmpstr?style=for-the-badge&logo=transmission&logoColor=fff)](https://npmpackage.info/package/cmpstr?t=downloads)
+[![NPM Downloads](https://img.shields.io/npm/dy/cmpstr?style=for-the-badge&logo=transmission&logoColor=fff)](https://npm-stat.com/charts.html?package=cmpstr)
 [![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/komed3/cmpstr/build.yml?style=for-the-badge&logo=educative&logoColor=fff)](https://github.com/komed3/cmpstr/actions/workflows/build.yml)
 [![Static Badge](https://img.shields.io/badge/ESM_%26_CJS-TypeScript?style=for-the-badge&logo=nodedotjs&logoColor=fff&color=purple)](https://github.com/komed3/cmpstr/wiki/Installation-&-Setup#import-in-your-project)
 [![Static Badge](https://img.shields.io/badge/UMD_%26_ESM-JavaScript?style=for-the-badge&logo=javascript&logoColor=fff&color=orange)](https://github.com/komed3/cmpstr/wiki/Installation-&-Setup#browser)
@@ -24,6 +24,7 @@ Originally launched in 2023 with a minimal feature set, the library was redesign
 - Normalization and filtering pipeline for consistent input processing
 - Single, batch and pairwise comparisons with structured, type-safe results
 - Phonetic-aware search and comparison
+- Structured data comparison by extracting object properties
 - Utilities for text structure and readability analysis (e.g., syllables, word statistics)
 - Diffing tools with CLI-friendly formatting
 - TypeScript-native with full type declarations and extensibility

package/dist/CmpStr.esm.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
  */
 const parse = (p) =>
@@ -12,6 +12,12 @@ const parse = (p) =>
 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);
@@ -66,6 +72,15 @@ function rmv(t, path, preserveEmpty = false) {
   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;
@@ -830,6 +845,240 @@ class Filter {
   }
 }
 
+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) {
@@ -1056,93 +1305,6 @@ class Metric {
 }
 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);
@@ -2127,6 +2289,9 @@ class CmpStr {
       ? 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);
@@ -2260,6 +2425,42 @@ class CmpStr {
     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 {
@@ -2373,7 +2574,61 @@ class CmpStrAsync extends CmpStr {
     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
+    );
+  }
 }
 
-export { CmpStr, CmpStrAsync, DiffChecker, Normalizer, TextAnalyzer };
+export {
+  CmpStr,
+  CmpStrAsync,
+  DeepMerge,
+  DiffChecker,
+  Filter,
+  HashTable,
+  Metric,
+  MetricRegistry,
+  Normalizer,
+  Phonetic,
+  PhoneticMappingRegistry,
+  PhoneticRegistry,
+  Pool,
+  Profiler,
+  StructuredData,
+  TextAnalyzer
+};
 //# sourceMappingURL=CmpStr.esm.js.map