cmpstr 3.0.1 → 3.0.3

package/dist/CmpStr.umd.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
@@ -67,7 +67,7 @@
         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)
@@ -1686,7 +1686,7 @@
     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 = {
@@ -1701,9 +1701,9 @@
              */
             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;
             },
             /**
@@ -1734,7 +1734,7 @@
              */
             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];
             }
         };
@@ -1755,7 +1755,7 @@
      */
     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);
     }
     /**
@@ -1773,7 +1773,9 @@
             return new cls(...args);
         }
         catch (err) {
-            throw new Error(`cannot instantiate class <${cls}>`);
+            throw new Error(`Cannot instantiate class <${cls}>`, {
+                cause: err
+            });
         }
     }
 
@@ -1871,7 +1873,7 @@
             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;
@@ -1908,7 +1910,7 @@
          * @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).
@@ -2065,7 +2067,7 @@
          */
         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`);
             })();
         }
         /**
@@ -2126,7 +2128,7 @@
                         this.runPairwise();
                     break;
                 // Unsupported mode
-                default: throw new Error(`unsupported mode <${mode}>`);
+                default: throw new Error(`Unsupported mode <${mode}>`);
             }
         }
         /**
@@ -2161,7 +2163,7 @@
                         await this.runPairwiseAsync();
                     break;
                 // Unsupported mode
-                default: throw new Error(`unsupported async mode <${mode}>`);
+                default: throw new Error(`Unsupported async mode <${mode}>`);
             }
         }
         /**
@@ -2704,7 +2706,7 @@
                 }
                 // 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
@@ -3353,8 +3355,8 @@
      * 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)
@@ -3394,22 +3396,55 @@
          * 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.
          *
@@ -3487,6 +3522,9 @@
          */
         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;
@@ -3523,11 +3561,11 @@
          * @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;
         }
@@ -3680,7 +3718,7 @@
             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;
             },
             /**
@@ -3716,6 +3754,188 @@
         };
     })();
 
+    /**
+     * 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
@@ -4264,6 +4484,12 @@
             // 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
@@ -4694,6 +4920,12 @@
             // 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