cmpstr 3.0.1 → 3.0.3

package/README.md

@@ -68,8 +68,14 @@ console.log( result );
 // [ 'Meyer', 'Meier' ]
 ```
 
+_Try with [OneCompiler](https://onecompiler.com/nodejs/43qr6trny)._
+
+## CLI Tool
+
+Try out or use CmpStr on the terminal. Install the **[cmpstr-cli](https://npmjs.com/package/cmpstr-cli)** package and use many features of CmpStr directly on the console via the cmpstr command. Many options and parameters also make the command suitable for scripts and automatic processing.
+
 ## Documentation
 
 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-2025 PAUL KÖHLER (KOMED3)**

package/dist/CmpStr.esm.js

@@ -1,5 +1,5 @@
 /**
- * CmpStr v3.0.1 dev-052fa0c-250614
+ * CmpStr v3.0.3 build-462b952-250813
  * This is a lightweight, fast and well performing library for calculating string similarity.
  * (c) 2023-2025 Paul Köhler @komed3 / MIT License
  * Visit https://github.com/komed3/cmpstr and https://npmjs.org/package/cmpstr
@@ -61,7 +61,7 @@ function set(t, path, value) {
     const [k, ...r] = parse(path);
     // Throw an error if the key is not a valid identifier
     if (t !== undefined && (typeof t !== 'object' || t === null))
-        throw Error(`cannot set property <${k}> of <${JSON.stringify(t)}>`);
+        throw Error(`Cannot set property <${k}> of <${JSON.stringify(t)}>`);
     // Assign the value to the specified key in the object
     return Object.assign(t ?? (typeof k === 'number' ? [] : Object.create(null)), {
         [k]: set(t?.[k], r.join('.'), value)
@@ -1680,7 +1680,7 @@ const factory = Object.create(null);
 function Registry(reg, ctor) {
     // Throws an error if the registry already exists
     if (reg in registry || reg in factory)
-        throw new Error(`registry <${reg}> already exists / overwriting is forbidden`);
+        throw new Error(`Registry <${reg}> already exists / overwriting is forbidden`);
     // Create a registry object to hold class constructors
     const classes = Object.create(null);
     const service = {
@@ -1695,9 +1695,9 @@ function Registry(reg, ctor) {
          */
         add(name, cls, update = false) {
             if (!(cls.prototype instanceof ctor))
-                throw new TypeError(`class must extend <${reg}>`);
+                throw new TypeError(`Class must extend <${reg}>`);
             if (!update && name in classes)
-                throw new Error(`entry <${name}> already exists / use <update=true> to overwrite`);
+                throw new Error(`Entry <${name}> already exists / use <update=true> to overwrite`);
             classes[name] = cls;
         },
         /**
@@ -1728,7 +1728,7 @@ function Registry(reg, ctor) {
          */
         get(name) {
             if (!(name in classes))
-                throw new Error(`class <${name}> not registered for <${reg}>`);
+                throw new Error(`Class <${name}> not registered for <${reg}>`);
             return classes[name];
         }
     };
@@ -1749,7 +1749,7 @@ function Registry(reg, ctor) {
  */
 function resolveCls(reg, cls) {
     if (!(reg in registry))
-        throw new ReferenceError(`registry <${reg}> does not exist`);
+        throw new ReferenceError(`Registry <${reg}> does not exist`);
     return (typeof cls === 'string' ? registry[reg]?.get(cls) : cls);
 }
 /**
@@ -1767,7 +1767,9 @@ function createFromRegistry(reg, cls, ...args) {
         return new cls(...args);
     }
     catch (err) {
-        throw new Error(`cannot instantiate class <${cls}>`);
+        throw new Error(`Cannot instantiate class <${cls}>`, {
+            cause: err
+        });
     }
 }
 
@@ -1865,7 +1867,7 @@ class Metric {
         this.b = Array.isArray(b) ? b : [b];
         // Validate inputs: ensure they are not empty
         if (this.a.length === 0 || this.b.length === 0)
-            throw new Error(`inputs <a> and <b> must not be empty`);
+            throw new Error(`Inputs <a> and <b> must not be empty`);
         // Set options
         this.options = opt;
         this.symmetric = symmetric;
@@ -1902,7 +1904,7 @@ class Metric {
      * @throws {Error} - If not overridden in a subclass
      */
     compute(a, b, m, n, maxLen) {
-        throw new Error(`method compute() must be overridden in a subclass`);
+        throw new Error(`Method compute() must be overridden in a subclass`);
     }
     /**
      * Run the metric computation for single inputs (two strings).
@@ -2059,7 +2061,7 @@ class Metric {
      */
     isPairwise(safe = false) {
         return this.isBatch() && this.a.length === this.b.length ? true : !safe && (() => {
-            throw new Error(`mode <pairwise> requires arrays of equal length`);
+            throw new Error(`Mode <pairwise> requires arrays of equal length`);
         })();
     }
     /**
@@ -2120,7 +2122,7 @@ class Metric {
                     this.runPairwise();
                 break;
             // Unsupported mode
-            default: throw new Error(`unsupported mode <${mode}>`);
+            default: throw new Error(`Unsupported mode <${mode}>`);
         }
     }
     /**
@@ -2155,7 +2157,7 @@ class Metric {
                     await this.runPairwiseAsync();
                 break;
             // Unsupported mode
-            default: throw new Error(`unsupported async mode <${mode}>`);
+            default: throw new Error(`Unsupported async mode <${mode}>`);
         }
     }
     /**
@@ -2698,7 +2700,7 @@ class HammingDistance extends Metric {
             }
             // Standard: Error for unequal length
             else
-                throw new Error(`strings must be of equal length for Hamming Distance, a=${m} and b=${n} given, ` +
+                throw new Error(`Strings must be of equal length for Hamming Distance, a=${m} and b=${n} given, ` +
                     `use option.pad for automatic adjustment`);
         }
         // Calculate the Hamming distance
@@ -3347,8 +3349,8 @@ MetricRegistry.add('smithWaterman', SmithWatermanDistance);
  * pose a risk of infringing upon existing trademarks due to their pronunciation.
  *
  * This module provides an abstract class for generating phonetic indices based
- * on mappings and rules. It allows for the implementation of various phonetic
- * algorithms by extending the abstract class.
+ * on mappings, patterns and rules. It allows for the implementation of various
+ * phonetic algorithms by extending the abstract class.
  *
  * @module Phonetic
  * @author Paul Köhler (komed3)
@@ -3388,22 +3390,55 @@ class Phonetic {
      * Constructor for the Phonetic class.
      *
      * Initializes the phonetic algorithm with the specified options and mapping.
+     * Options hierarchy: User input > mapping options > default
      *
      * @param {string} algo - The name of the algorithm (e.g. 'soundex')
      * @param {PhoneticOptions} [opt] - Options for the phonetic algorithm
      * @throws {Error} - If the requested mapping is not declared
      */
     constructor(algo, opt = {}) {
-        // Set the options by merging the default options with the provided ones
-        this.options = merge(this.constructor.default ?? {}, opt);
-        // Get the mapping based on the provided options
-        const map = PhoneticMappingRegistry.get(algo, this.options.map);
+        // Get the phonetic default options
+        const defaults = this.constructor.default ?? {};
+        // Determine phonetic map ID from options or use defaults
+        const mapId = opt.map ?? defaults.map;
+        // If no algorithm is specified, throw an error
+        if (!mapId)
+            throw new Error(`No mapping specified for phonetic algorithm`);
+        // Get the mapping based on the determined map ID
+        const map = PhoneticMappingRegistry.get(algo, mapId);
         // If the mapping is not defined, throw an error
         if (map === undefined)
-            throw new Error(`requested mapping <${this.options.map}> is not declared`);
+            throw new Error(`Requested mapping <${mapId}> is not declared`);
+        // Set the options by merging the default options with the provided ones
+        this.options = merge(merge(defaults, map.options ?? {}), opt);
+        // Set the algorithm name and mapping
         this.algo = algo;
         this.map = map;
     }
+    /**
+     * Applies patterns to a word based on the phonetic map.
+     *
+     * This method processes the word by applying all defined patterns in the
+     * phonetic map. It replaces occurrences of specified patterns with their
+     * corresponding replacements.
+     *
+     * @param {string} word - The input word to be processed
+     * @returns {string} - The modified word after applying all patterns
+     */
+    applyPattern(word) {
+        const { patterns = [] } = this.map;
+        // If no patterns are provided, return the input
+        if (!patterns || !patterns.length)
+            return word;
+        // Iterate over the patterns and replace all matches
+        for (const { pattern, replace, all = false } of patterns) {
+            // Search for the pattern in the word and replace it
+            // Use replaceAll if 'all' is true, otherwise use replace
+            word = word[all ? 'replaceAll' : 'replace'](pattern, replace);
+        }
+        // Return the modified word after applying all patterns
+        return word;
+    }
     /**
      * Applies phonetic rules to a character in a word context.
      *
@@ -3481,6 +3516,9 @@ class Phonetic {
      */
     encode(word) {
         const { map = {}, ignore = [] } = this.map;
+        // Apply patterns to the word before processing
+        // This allows for pre-processing of the word based on defined patterns
+        word = this.applyPattern(word);
         // Get the characters of the word and its length
         const chars = this.word2Chars(word);
         const charLen = chars.length;
@@ -3517,11 +3555,11 @@ class Phonetic {
      * @returns {string|undefined} - The phonetic code or undefined if no code applies
      */
     mapChar(char, i, chars, charLen, lastCode, map) {
-        const { dedupe = true } = this.options;
+        const { dedupe = true, fallback = undefined } = this.options;
         // Apply phonetic rules to the character
         // If no rules apply, use the mapping
-        // If the character is not in the mapping, return undefined
-        const c = this.applyRules(char, i, chars, charLen) ?? map[char] ?? undefined;
+        // If the character is not in the mapping, return the fallback
+        const c = this.applyRules(char, i, chars, charLen) ?? map[char] ?? fallback;
         // De-duplicate the code if necessary
         return dedupe && c === lastCode ? undefined : c;
     }
@@ -3674,7 +3712,7 @@ const PhoneticMappingRegistry = (() => {
         add(algo, id, map, update = false) {
             const mappings = maps(algo);
             if (!update && id in mappings)
-                throw new Error(`entry <${id}> already exists / use <update=true> to overwrite`);
+                throw new Error(`Entry <${id}> already exists / use <update=true> to overwrite`);
             mappings[id] = map;
         },
         /**
@@ -3710,6 +3748,188 @@ const PhoneticMappingRegistry = (() => {
     };
 })();
 
+/**
+ * Caverphone Phonetic Algorithm
+ * src/phonetic/Caverphone.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Caverphone
+ *
+ * This module implements the Caverphone phonetic algorithm, which is designed
+ * to encode words into a phonetic representation. The Caverphone algorithm is
+ * used primarily in New Zealand and was developed to assist in the indexing of
+ * names in genealogical databases.
+ *
+ * It converts words into a standardized phonetic code, allowing for variations
+ * in spelling and pronunciation to be matched.
+ *
+ * @module Phonetic/Caverphone
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+/**
+ * Caverphone class extends the Phonetic class to implement the Caverphone phonetic algorithm.
+ */
+class Caverphone extends Phonetic {
+    // Default options for the Caverphone phonetic algorithm
+    static default = {
+        map: 'en2', delimiter: ' ', length: -1, pad: '', dedupe: false
+    };
+    /**
+     * Constructor for the Caverphone class.
+     *
+     * Initializes the Caverphone phonetic algorithm with the mapping and options.
+     *
+     * @param {PhoneticOptions} [opt] - Options for the Caverphone phonetic algorithm
+     */
+    constructor(opt = {}) { super('caverphone', opt); }
+    /**
+     * Generates the Caverphone code for a given word.
+     *
+     * @param {string} word - The input word to be converted into a Caverphone code
+     * @returns {string} - The generated Caverphone code
+     */
+    encode(word) {
+        // Remove anything not A-Z and convert to lowercase
+        word = word.replace(/[^A-Z]/gi, '').toLowerCase();
+        // Use the base implementation for rule/mapping application
+        return super.encode(word);
+    }
+    /**
+     * Overrides the mapChar method to skip character mapping.
+     *
+     * @param {string} char - The character to be mapped
+     * @returns {string} - The mapped character
+     */
+    mapChar(char) { return char; }
+    /**
+     * Adjusts the phonetic code to uppercase.
+     *
+     * @param {string} code - The phonetic code to adjust
+     * @returns {string} - The adjusted phonetic code
+     */
+    adjustCode(code) { return code.toUpperCase(); }
+}
+// Register the Caverphone algorithm in the phonetic registry
+PhoneticRegistry.add('caverphone', Caverphone);
+// Register the Caverphone 1.0 phonetic mapping for English
+PhoneticMappingRegistry.add('caverphone', 'en1', {
+    options: { length: 6, pad: '1' },
+    map: {},
+    patterns: [
+        // Special word-initial replacements
+        { pattern: /^(c|r|t|en)ough/, replace: '$1ou2f' },
+        { pattern: /^gn/, replace: '2n' },
+        // Special word-final replacement
+        { pattern: /mb$/, replace: 'm2' },
+        // Character group replacements
+        { pattern: /cq/g, replace: '2q' },
+        { pattern: /c(e|i|y)/g, replace: 's$1' },
+        { pattern: /tch/g, replace: '2ch' },
+        { pattern: /[cqx]/g, replace: 'k' },
+        { pattern: /v/g, replace: 'f' },
+        { pattern: /dg/g, replace: '2g' },
+        { pattern: /ti(a|o)/g, replace: 'si$1' },
+        { pattern: /d/g, replace: 't' },
+        { pattern: /ph/g, replace: 'fh' },
+        { pattern: /b/g, replace: 'p' },
+        { pattern: /sh/g, replace: 's2' },
+        { pattern: /z/g, replace: 's' },
+        // Vowel handling
+        { pattern: /^[aeiou]/, replace: 'A' },
+        { pattern: /[aeiou]/g, replace: '3' },
+        // Special gh handling
+        { pattern: /3gh3/g, replace: '3kh3' },
+        { pattern: /gh/g, replace: '22' },
+        // Single character replacements
+        { pattern: /g/g, replace: 'k' },
+        // Collapse repeated consonants
+        { pattern: /s+/g, replace: 'S' },
+        { pattern: /t+/g, replace: 'T' },
+        { pattern: /p+/g, replace: 'P' },
+        { pattern: /k+/g, replace: 'K' },
+        { pattern: /f+/g, replace: 'F' },
+        { pattern: /m+/g, replace: 'M' },
+        { pattern: /n+/g, replace: 'N' },
+        // Y and other single-letter handling
+        { pattern: /j/g, replace: 'y' },
+        // L/R/W/Y3 handling
+        { pattern: /l3/g, replace: 'L3' },
+        { pattern: /r3/g, replace: 'R3' },
+        { pattern: /w3/g, replace: 'W3' },
+        { pattern: /y3/g, replace: 'Y3' },
+        // L/R/W followed by y
+        { pattern: /ly/g, replace: 'Ly' },
+        { pattern: /ry/g, replace: 'Ry' },
+        { pattern: /wy/g, replace: 'Wy' },
+        // WH handling
+        { pattern: /wh3/g, replace: 'Wh3' },
+        { pattern: /why/g, replace: 'Why' },
+        // H at start
+        { pattern: /^h/, replace: 'A' },
+        // Remove certain letters
+        { pattern: /[hlrwy23]/g, replace: '' }
+    ]
+});
+// Register the Caverphone 2.0 phonetic mapping for English
+PhoneticMappingRegistry.add('caverphone', 'en2', {
+    options: { length: 10, pad: '1' },
+    map: {},
+    patterns: [
+        // Remove trailing 'e'
+        { pattern: /e$/, replace: '' },
+        // Special word-initial replacements
+        { pattern: /^(c|r|t|en|tr)ough/, replace: '$1ou2f' },
+        { pattern: /^gn/, replace: '2n' },
+        // Special word-final replacement
+        { pattern: /mb$/, replace: 'm2' },
+        // Character group replacements
+        { pattern: /cq/g, replace: '2q' },
+        { pattern: /c(e|i|y)/g, replace: 's$1' },
+        { pattern: /tch/g, replace: '2ch' },
+        { pattern: /[cqx]/g, replace: 'k' },
+        { pattern: /v/g, replace: 'f' },
+        { pattern: /dg/g, replace: '2g' },
+        { pattern: /ti(a|o)/g, replace: 'si$1' },
+        { pattern: /d/g, replace: 't' },
+        { pattern: /ph/g, replace: 'fh' },
+        { pattern: /b/g, replace: 'p' },
+        { pattern: /sh/g, replace: 's2' },
+        { pattern: /z/g, replace: 's' },
+        // Vowel handling
+        { pattern: /^[aeiou]/, replace: 'A' },
+        { pattern: /[aeiou]/g, replace: '3' },
+        // Y handling
+        { pattern: /j/g, replace: 'y' },
+        { pattern: /^y3/, replace: 'Y3' },
+        { pattern: /^y/, replace: 'A' },
+        { pattern: /y/g, replace: '3' },
+        // Special gh handling
+        { pattern: /3gh3/g, replace: '3kh3' },
+        { pattern: /gh/g, replace: '22' },
+        // Single character replacements
+        { pattern: /g/g, replace: 'k' },
+        // Collapse repeated consonants
+        { pattern: /s+/g, replace: 'S' },
+        { pattern: /t+/g, replace: 'T' },
+        { pattern: /p+/g, replace: 'P' },
+        { pattern: /k+/g, replace: 'K' },
+        { pattern: /f+/g, replace: 'F' },
+        { pattern: /m+/g, replace: 'M' },
+        { pattern: /n+/g, replace: 'N' },
+        // L/R/W3 handling
+        { pattern: /l3/g, replace: 'L3' },
+        { pattern: /r3/g, replace: 'R3' },
+        { pattern: /w3/g, replace: 'W3' },
+        { pattern: /wh3/g, replace: 'Wh3' },
+        { pattern: /[lrw]$/, replace: '3' },
+        // // H at start and final 3 handling
+        { pattern: /^h/, replace: 'A' },
+        { pattern: /3$/, replace: 'A' },
+        // Remove certain letters
+        { pattern: /[hlrw23]/g, replace: '' }
+    ]
+});
+
 /**
  * Cologne Phonetic Algorithm
  * src/phonetic/Cologne.ts
@@ -4258,6 +4478,12 @@ class CmpStr {
         // 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) ||
+            (Array.isArray(B) && B.length === 0) ||
+            A === '' || B === '')) {
+            return [];
+        }
         // Get the metric class
         const metric = factory.metric(resolved.metric, A, B, resolved.opt);
         // Pass the original inputs to the metric
@@ -4688,6 +4914,12 @@ class CmpStrAsync extends CmpStr {
         // Prepare the input
         const A = skip ? a : await this.prepareAsync(a, resolved);
         const B = skip ? b : await this.prepareAsync(b, resolved);
+        // If the inputs are empty and safeEmpty is enabled, return an empty array
+        if (resolved.safeEmpty && ((Array.isArray(A) && A.length === 0) ||
+            (Array.isArray(B) && B.length === 0) ||
+            A === '' || B === '')) {
+            return [];
+        }
         // Get the metric class
         const metric = factory.metric(resolved.metric, A, B, resolved.opt);
         // Pass the original inputs to the metric