cmpstr 3.0.3 → 3.1.0

package/dist/esm/CmpStr.mjs

@@ -1,10 +1,11 @@
-// CmpStr v3.0.3 build-462b952-250813 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.1.0 build-76aadb9-260117 by Paul Köhler @komed3 / MIT License
 import { merge, set, rmv, get } from './utils/DeepMerge.mjs';
 import { Profiler } from './utils/Profiler.mjs';
 import { TextAnalyzer } from './utils/TextAnalyzer.mjs';
 import { DiffChecker } from './utils/DiffChecker.mjs';
 import { Normalizer } from './utils/Normalizer.mjs';
 import { Filter } from './utils/Filter.mjs';
+import { StructuredData } from './utils/StructuredData.mjs';
 import { factory } from './utils/Registry.mjs';
 import './metric/Cosine.mjs';
 import './metric/DamerauLevenshtein.mjs';
@@ -28,49 +29,8 @@ import {
   Phonetic
 } from './phonetic/Phonetic.mjs';
 
-/**
- * CmpStr Main API
- * src/CmpStr.ts
- *
- * The CmpStr class provides a comprehensive, highly abstracted, and type-safe interface
- * for string comparison, similarity measurement, phonetic indexing, filtering, normalization,
- * and text analysis. It unifies all core features of the CmpStr package and exposes a
- * consistent, user-friendly API for both single and batch operations.
- *
- * Features:
- *  - Centralized management of metrics, phonetic algorithms, and filters
- *  - Flexible normalization and filtering pipeline for all inputs
- *  - Batch, pairwise, and single string comparison with detailed results
- *  - Phonetic indexing and phonetic-aware search and comparison
- *  - Text analysis and unified diff utilities
- *  - Full TypeScript type safety and extensibility
- *
- * @module CmpStr
- * @author Paul Köhler (komed3)
- * @license MIT
- */
-// Import the Profiler instance for global profiling
 const profiler = Profiler.getInstance();
-/**
- * The main CmpStr class that provides a unified interface for string comparison,
- * phonetic indexing, filtering, and text analysis.
- *
- * @template R - The type of the metric result, defaults to MetricRaw
- */
 class CmpStr {
-  /**
-   * --------------------------------------------------------------------------------
-   * Static methods and properties for global access to CmpStr features
-   * --------------------------------------------------------------------------------
-   *
-   * These static methods provide a convenient way to access the core features of
-   * the CmpStr package without needing to instantiate a CmpStr object.
-   */
-  /**
-   * Adds, removes, pauses, resumes, lists, or clears global filters.
-   *
-   * @see Filter
-   */
   static filter = {
     add: Filter.add,
     remove: Filter.remove,
@@ -79,22 +39,12 @@ class CmpStr {
     list: Filter.list,
     clear: Filter.clear
   };
-  /**
-   * Adds, removes, checks, or lists available metrics.
-   *
-   * @see MetricRegistry
-   */
   static metric = {
     add: MetricRegistry.add,
     remove: MetricRegistry.remove,
     has: MetricRegistry.has,
     list: MetricRegistry.list
   };
-  /**
-   * Adds, removes, checks, or lists available phonetic algorithms and mappings.
-   *
-   * @see PhoneticRegistry
-   */
   static phonetic = {
     add: PhoneticRegistry.add,
     remove: PhoneticRegistry.remove,
@@ -107,89 +57,30 @@ class CmpStr {
       list: PhoneticMappingRegistry.list
     }
   };
-  /**
-   * Provides access to the global profiler services.
-   *
-   * @see Profiler
-   */
   static profiler = profiler.services;
-  /**
-   * Clears the caches for normalizer, metric, and phonetic modules.
-   */
   static clearCache = {
     normalizer: Normalizer.clear,
     metric: Metric.clear,
     phonetic: Phonetic.clear
   };
-  /**
-   * Returns a TextAnalyzer instance for the given input string.
-   *
-   * @param {string} [input] - The input string
-   * @returns {TextAnalyzer} - The text analyzer
-   */
   static analyze(input) {
     return new TextAnalyzer(input);
   }
-  /**
-   * Returns a DiffChecker instance for computing the unified diff between two texts.
-   *
-   * @param {string} a - The first (original) text
-   * @param {string} b - The second (modified) text
-   * @param {DiffOptions} [opt] - Optional diff configuration
-   * @returns {DiffChecker} - The diff checker instance
-   */
   static diff(a, b, opt) {
     return new DiffChecker(a, b, opt);
   }
-  /**
-   * --------------------------------------------------------------------------------
-   * Instanciate the CmpStr class
-   * --------------------------------------------------------------------------------
-   *
-   * Methods to create a new CmpStr instance with the given options.
-   * Using the static `create` method is recommended to ensure proper instantiation.
-   */
-  /**
-   * Creates a new CmpStr instance with the given options.
-   *
-   * @param {string|CmpStrOptions} [opt] - Optional serialized or options object
-   * @returns {CmpStr<R>} - A new CmpStr instance
-   */
   static create(opt) {
     return new CmpStr(opt);
   }
-  // The options object that holds the configuration for this CmpStr instance
   options = Object.create(null);
-  /**
-   * Creates a new CmpStr instance with the given options.
-   * The constructor is protected to enforce the use of the static `create` method.
-   *
-   * @param {string|CmpStrOptions} [opt] - Optional serialized or options object
-   */
   constructor(opt) {
     if (opt)
       typeof opt === 'string'
         ? this.setSerializedOptions(opt)
         : this.setOptions(opt);
   }
-  /**
-   * ---------------------------------------------------------------------------------
-   * Protected utility methods for internal use
-   * ---------------------------------------------------------------------------------
-   *
-   * These methods provide utility functions for converting inputs, merging options,
-   * normalizing inputs, filtering, and preparing inputs for comparison.
-   */
-  /**
-   * Assert a condition and throws if the condition is not met.
-   *
-   * @param {string} cond - The condition to met
-   * @param {any} [test] - Value to test for
-   * @throws {Error} If the condition is not met
-   */
   assert(cond, test) {
     switch (cond) {
-      // Check if the metric exists
       case 'metric':
         if (!CmpStr.metric.has(test))
           throw new Error(
@@ -197,7 +88,6 @@ class CmpStr {
               `use CmpStr.metric.list() for available metrics`
           );
         break;
-      // Check if the phonetic algorithm exists
       case 'phonetic':
         if (!CmpStr.phonetic.has(test))
           throw new Error(
@@ -205,85 +95,34 @@ class CmpStr {
               `use CmpStr.phonetic.list() for available phonetic algorithms`
           );
         break;
-      // Throw an error for unknown conditions
       default:
         throw new Error(`Cmpstr condition <${cond}> unknown`);
     }
   }
-  /**
-   * Assert multiple conditions.
-   *
-   * @param {[ string, any? ][]} cond - Array of [ condition, value ] pairs
-   */
   assertMany(...cond) {
     for (const [c, test] of cond) this.assert(c, test);
   }
-  /**
-   * Resolves the options for the CmpStr instance, merging the provided options with
-   * the existing options.
-   *
-   * @param {CmpStrOptions} [opt] - Optional options to merge
-   * @returns {CmpStrOptions} - The resolved options
-   */
   resolveOptions(opt) {
     return merge({ ...(this.options ?? Object.create(null)) }, opt);
   }
-  /**
-   * Normalizes the input string or array using the configured or provided flags.
-   *
-   * @param {MetricInput} input - The input string or array
-   * @param {NormalizeFlags} [flags] - Normalization flags
-   * @returns {MetricInput} - The normalized input
-   */
   normalize(input, flags) {
     return Normalizer.normalize(input, flags ?? this.options.flags ?? '');
   }
-  /**
-   * Applies all active filters to the input string or array.
-   *
-   * @param {MetricInput} input - The input string or array
-   * @param {string} [hook='input'] - The filter hook
-   * @returns {MetricInput} - The filtered string(s)
-   */
   filter(input, hook) {
     return Filter.apply(hook, input);
   }
-  /**
-   * Prepares the input by normalizing and filtering.
-   *
-   * @param {MetricInput} [input] - The input string or array
-   * @param {CmpStrOptions} [opt] - Optional options to use
-   * @returns {MetricInput} - The prepared input
-   */
   prepare(input, opt) {
     const { flags, processors } = opt ?? this.options;
-    // Normalize the input using flags (i.e., 'itw')
     if (flags?.length) input = this.normalize(input, flags);
-    // Filter the input using hooked up filters
     input = this.filter(input, 'input');
-    // Apply phonetic processors if configured
     if (processors?.phonetic) input = this.index(input, processors.phonetic);
     return input;
   }
-  /**
-   * Post-process the results of the metric computation.
-   *
-   * @param {MetricResult<R>} result - The metric result
-   * @returns {MetricResult<R>} - The post-processed results
-   */
   postProcess(result, opt) {
-    // Remove "zero similarity" from batch results if configured
     if (opt?.removeZero && Array.isArray(result))
       result = result.filter((r) => r.res > 0);
     return result;
   }
-  /**
-   * Computes the phonetic index for the given input using the specified phonetic algorithm.
-   *
-   * @param {MetricInput} input - The input string or array
-   * @param {{ algo: string, opt?: PhoneticOptions }} options - The phonetic algorithm and options
-   * @returns {MetricInput} - The phonetic index for the given input
-   */
   index(input, { algo, opt }) {
     this.assert('phonetic', algo);
     const phonetic = factory.phonetic(algo, opt);
@@ -292,26 +131,14 @@ class CmpStr {
       ? input.map((s) => phonetic.getIndex(s).join(delimiter))
       : phonetic.getIndex(input).join(delimiter);
   }
-  /**
-   * Computes the metric result for the given inputs, applying normalization and
-   * filtering as configured.
-   *
-   * @template T - The type of the metric result
-   * @param {MetricInput} a - The first input string or array
-   * @param {MetricInput} b - The second input string or array
-   * @param {CmpStrOptions} [opt] - Optional options to use
-   * @param {MetricMode} [mode='single'] - The metric mode to use
-   * @param {boolean} [raw=false] - Whether to return raw results
-   * @param {boolean} [skip=false] - Whether to skip normalization and filtering
-   * @returns {T} - The computed metric result
-   */
+  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);
-    // Prepare the input
     const A = skip ? a : this.prepare(a, resolved);
     const B = skip ? b : this.prepare(b, resolved);
-    // If the inputs are empty and safeEmpty is enabled, return an empty array
     if (
       resolved.safeEmpty &&
       ((Array.isArray(A) && A.length === 0) ||
@@ -321,25 +148,12 @@ class CmpStr {
     ) {
       return [];
     }
-    // Get the metric class
     const metric = factory.metric(resolved.metric, A, B, resolved.opt);
-    // Pass the original inputs to the metric
     if (resolved.output !== 'prep') metric.setOriginal(a, b);
-    // Compute the metric result
     metric.run(mode);
-    // Post-process the results
     const result = this.postProcess(metric.getResults(), resolved);
-    // Resolve and return the result based on the raw flag
     return this.output(result, raw ?? resolved.raw);
   }
-  /**
-   * Resolves the result format (raw or formatted).
-   *
-   * @template T - The type of the metric result
-   * @param {MetricResult<R>} result - The metric result
-   * @param {boolean} [raw] - Whether to return raw results
-   * @returns {T} - The resolved result
-   */
   output(result, raw) {
     return (raw ?? this.options.raw)
       ? result
@@ -347,213 +161,69 @@ class CmpStr {
         ? result.map((r) => ({ source: r.a, target: r.b, match: r.res }))
         : { source: result.a, target: result.b, match: result.res };
   }
-  /**
-   * ---------------------------------------------------------------------------------
-   * Managing methods for CmpStr
-   * ---------------------------------------------------------------------------------
-   *
-   * These methods provides an interface to set and get properties of the CmpStr
-   * instance, such as options, metric, phonetic algorithm, and more.
-   */
-  /**
-   * Creates a shallow clone of the current instance.
-   *
-   * @returns {CmpStr<R>} - The cloned instance
-   */
   clone() {
     return Object.assign(Object.create(Object.getPrototypeOf(this)), this);
   }
-  /**
-   * Resets the instance, clearing all data and options.
-   *
-   * @returns {this}
-   */
   reset() {
     for (const k in this.options) delete this.options[k];
     return this;
   }
-  /**
-   * Sets / replaces the full options object.
-   *
-   * @param {CmpStrOptions} opt - The options
-   * @returns {this}
-   */
   setOptions(opt) {
     this.options = opt;
     return this;
   }
-  /**
-   * Deep merges and sets new options.
-   *
-   * @param {CmpStrOptions} opt - The options to merge
-   * @returns {this}
-   */
   mergeOptions(opt) {
     merge(this.options, opt);
     return this;
   }
-  /**
-   * Sets the serialized options from a JSON string.
-   *
-   * @param {string} opt - The serialized options
-   * @returns {this}
-   */
   setSerializedOptions(opt) {
     this.options = JSON.parse(opt);
     return this;
   }
-  /**
-   * Sets a specific option at the given path.
-   *
-   * @param {string} path - The path to the option
-   * @param {any} value - The value to set
-   * @returns {this}
-   */
   setOption(path, value) {
     set(this.options, path, value);
     return this;
   }
-  /**
-   * Removes an option at the given path.
-   *
-   * @param {string} path - The path to the option
-   * @returns {this}
-   */
   rmvOption(path) {
     rmv(this.options, path);
     return this;
   }
-  /**
-   * Enable or disable raw output.
-   *
-   * @param {boolean} enable - Whether to enable or disable raw output
-   * @returns {this}
-   */
   setRaw(enable) {
     return this.setOption('raw', enable);
   }
-  /**
-   * Sets the similatity metric to use (e.g., 'levenshtein', 'dice').
-   *
-   * @param {string} name - The metric name
-   * @returns {this}
-   */
   setMetric(name) {
     return this.setOption('metric', name);
   }
-  /**
-   * Sets the normalization flags (e.g., 'itw', 'nfc').
-   *
-   * @param {NormalizeFlags} flags - The normalization flags
-   * @returns {this}
-   */
   setFlags(flags) {
     return this.setOption('flags', flags);
   }
-  /**
-   * Removes the normalization flags entirely.
-   *
-   * @return {this}
-   */
   rmvFlags() {
     return this.rmvOption('flags');
   }
-  /**
-   * Sets the pre-processors to use for preparing the input.
-   *
-   * @param {CmpStrProcessors} opt - The processors to set
-   * @returns {this}
-   */
   setProcessors(opt) {
     return this.setOption('processors', opt);
   }
-  /**
-   * Removes the processors entirely.
-   *
-   * @returns {this}
-   */
   rmvProcessors() {
     return this.rmvOption('processors');
   }
-  /**
-   * Returns the current options object.
-   *
-   * @returns {CmpStrOptions} - The options
-   */
   getOptions() {
     return this.options;
   }
-  /**
-   * Returns the options as a JSON string.
-   *
-   * @returns {string} - The serialized options
-   */
   getSerializedOptions() {
     return JSON.stringify(this.options);
   }
-  /**
-   * Returns a specific option value by path.
-   *
-   * @param {string} path - The path to the option
-   * @returns {any} - The option value
-   */
   getOption(path) {
     return get(this.options, path);
   }
-  /**
-   * ---------------------------------------------------------------------------------
-   * Public core methods for string comparison
-   * ---------------------------------------------------------------------------------
-   *
-   * These methods provide the core functionality of the CmpStr class, allowing for
-   * string comparison, phonetic indexing, filtering, and text search.
-   */
-  /**
-   * Performs a single metric comparison between the source and target.
-   *
-   * @template T - The type of the metric result
-   * @param {string} a - The source string
-   * @param {string} b - The target string
-   * @param {CmpStrOptions} [opt] - Optional options
-   * @returns {T} - The metric result
-   */
   test(a, b, opt) {
     return this.compute(a, b, opt, 'single');
   }
-  /**
-   * Performs a single metric comparison and returns only the numeric score.
-   *
-   * @param {string} a - The source string
-   * @param {string} b - The target string
-   * @param {CmpStrOptions} [opt] - Optional options
-   * @returns {number} - The similarity score (0..1)
-   */
   compare(a, b, opt) {
     return this.compute(a, b, opt, 'single', true).res;
   }
-  /**
-   * Performs a batch metric comparison between source and target strings
-   * or array of strings.
-   *
-   * @template T - The type of the metric result
-   * @param {MetricInput} a - The source string or array of strings
-   * @param {MetricInput} b - The target string or array of strings
-   * @param {CmpStrOptions} [opt] - Optional options
-   * @returns {T} - The batch metric results
-   */
   batchTest(a, b, opt) {
     return this.compute(a, b, opt, 'batch');
   }
-  /**
-   * Performs a batch metric comparison and returns results sorted by score.
-   *
-   * @template T - The type of the metric result
-   * @param {MetricInput} a - The source string or array of strings
-   * @param {MetricInput} b - The target string or array of strings
-   * @param {'desc'|'asc'} [dir='desc'] - Sort direction (desc, asc)
-   * @param {CmpStrOptions} [opt] - Optional options
-   * @returns {T} - The sorted batch results
-   */
   batchSorted(a, b, dir = 'desc', opt) {
     return this.output(
       this.compute(a, b, opt, 'batch', true).sort((a, b) =>
@@ -562,32 +232,9 @@ class CmpStr {
       opt?.raw ?? this.options.raw
     );
   }
-  /**
-   * Performs a pairwise metric comparison between source and target strings
-   * or array of strings.
-   *
-   * Input arrays needs of the same length to perform pairwise comparison,
-   * otherwise the method will throw an error.
-   *
-   * @template T - The type of the metric result
-   * @param {MetricInput} a - The source string or array of strings
-   * @param {MetricInput} b - The target string or array of strings
-   * @param {CmpStrOptions} [opt] - Optional options
-   * @returns {T} - The pairwise metric results
-   */
   pairs(a, b, opt) {
     return this.compute(a, b, opt, 'pairwise');
   }
-  /**
-   * Performs a batch comparison and returns only results above the threshold.
-   *
-   * @template T - The type of the metric result
-   * @param {MetricInput} a - The source string or array of strings
-   * @param {MetricInput} b - The target string or array of strings
-   * @param {number} threshold - The similarity threshold (0..1)
-   * @param {CmpStrOptions} [opt] - Optional options
-   * @returns {T} - The filtered batch results
-   */
   match(a, b, threshold, opt) {
     return this.output(
       this.compute(a, b, opt, 'batch', true)
@@ -596,56 +243,18 @@ class CmpStr {
       opt?.raw ?? this.options.raw
     );
   }
-  /**
-   * Returns the n closest matches from a batch comparison.
-   *
-   * @template T - The type of the metric result
-   * @param {MetricInput} a - The source string or array of strings
-   * @param {MetricInput} b - The target string or array of strings
-   * @param {number} [n=1] - Number of closest matches
-   * @param {CmpStrOptions} [opt] - Optional options
-   * @returns {T} - The closest matches
-   */
   closest(a, b, n = 1, opt) {
     return this.batchSorted(a, b, 'desc', opt).slice(0, n);
   }
-  /**
-   * Returns the n furthest matches from a batch comparison.
-   *
-   * @template T - The type of the metric result
-   * @param {MetricInput} a - The source string or array of strings
-   * @param {MetricInput} b - The target string or array of strings
-   * @param {number} [n=1] - Number of furthest matches
-   * @param {CmpStrOptions} [opt] - Optional options
-   * @returns {T} - The furthest matches
-   */
   furthest(a, b, n = 1, opt) {
     return this.batchSorted(a, b, 'asc', opt).slice(0, n);
   }
-  /**
-   * Performs a normalized and filtered substring search.
-   *
-   * @param {string} needle - The search string
-   * @param {string[]} haystack - The array to search in
-   * @param {NormalizeFlags} [flags] - Normalization flags
-   * @param {CmpStrProcessors} [processors] - Pre-processors to apply
-   * @returns {string[]} - Array of matching entries
-   */
   search(needle, haystack, flags, processors) {
     const resolved = this.resolveOptions({ flags, processors });
-    // Prepare the needle and haystack, normalizing and filtering them
     const test = this.prepare(needle, resolved);
     const hstk = this.prepare(haystack, resolved);
-    // Filter the haystack based on the normalized test string
     return haystack.filter((_, i) => hstk[i].includes(test));
   }
-  /**
-   * Computes a similarity matrix for the given input array.
-   *
-   * @param {string[]} input - The input array
-   * @param {CmpStrOptions} [opt] - Optional options
-   * @returns {number[][]} - The similarity matrix
-   */
   matrix(input, opt) {
     input = this.prepare(input, this.resolveOptions(opt));
     return input.map((a) =>
@@ -654,19 +263,46 @@ class CmpStr {
       )
     );
   }
-  /**
-   * Computes the phonetic index for a string using the configured
-   * or given algorithm.
-   *
-   * @param {string} [input] - The input string
-   * @param {string} [algo] - The phonetic algorithm to use
-   * @param {PhoneticOptions} [opt] - Optional phonetic options
-   * @returns {string} - The phonetic index as a string
-   */
   phoneticIndex(input, algo, opt) {
     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
+    );
+  }
 }
 
 export { CmpStr };