cmpstr 3.0.4 → 3.1.1

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023-2025 Paul Köhler (komed3)
+Copyright (c) 2023-2026 Paul Köhler (komed3)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

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
@@ -78,4 +79,4 @@ Try out or use CmpStr on the terminal. Install the **[cmpstr-cli](https://npmjs.
 
 The full documentation, API reference and advanced usage examples are available in the [GitHub Wiki](https://github.com/komed3/cmpstr/wiki).
 
-**LICENSE MIT © 2023-2025 PAUL KÖHLER (KOMED3)**
+**LICENSE MIT © 2023-2026 PAUL KÖHLER (KOMED3)**

package/dist/CmpStr.esm.js

@@ -1,7 +1,7 @@
 /**
- * CmpStr v3.0.4 build-74e65a5-250915
+ * CmpStr v3.1.1 build-a140f52-260119
  * 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;
@@ -648,11 +663,11 @@ class Hasher {
     const chunks = Math.floor(len / 4);
     for (let i = 0; i < chunks; i++) {
       const pos = i * 4;
-      const chunk =
-        str.charCodeAt(pos) |
-        (str.charCodeAt(pos + 1) << 8) |
-        (str.charCodeAt(pos + 2) << 16) |
-        (str.charCodeAt(pos + 3) << 24);
+      const c0 = str.charCodeAt(pos);
+      const c1 = str.charCodeAt(pos + 1);
+      const c2 = str.charCodeAt(pos + 2);
+      const c3 = str.charCodeAt(pos + 3);
+      const chunk = c0 | (c1 << 8) | (c2 << 16) | (c3 << 24);
       hash ^= chunk;
       hash *= this.FNV_PRIME;
     }
@@ -830,6 +845,252 @@ 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: 64,
+      maxItemSize: 2048,
+      allowOversize: true
+    },
+    'number[]': {
+      type: 'number[]',
+      maxSize: 16,
+      maxItemSize: 1024,
+      allowOversize: false
+    },
+    'string[]': {
+      type: 'string[]',
+      maxSize: 2,
+      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(64),
+    'number[]': new RingPool(16),
+    'string[]': new RingPool(2),
+    set: new RingPool(8),
+    map: new RingPool(8)
+  };
+  static allocate(type, size) {
+    switch (type) {
+      case 'uint16':
+        return new Uint16Array(size);
+      case 'number[]':
+        return new Float64Array(size);
+      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];
+    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
+      }));
+    }
+    return normalized.map((r, idx) => ({ ...r, __idx: idx }));
+  }
+  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;
+      }
+      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;
+  }
+  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 +1317,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 +2301,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 +2437,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 +2586,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