cmpstr 3.0.0 → 3.0.2

package/README.md

@@ -2,13 +2,13 @@
 
 [![GitHub License](https://img.shields.io/github/license/komed3/cmpstr?style=for-the-badge&logo=unlicense&logoColor=fff)](LICENSE)
 [![Static Badge](https://img.shields.io/badge/docs-docs?style=for-the-badge&logo=readthedocs&logoColor=fff&color=blue)](https://github.com/komed3/cmpstr/wiki)
-[![Static Badge](https://img.shields.io/badge/Typescript-support?style=for-the-badge&logo=typescript&logoColor=fff&color=blue)]()
+[![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)
 [![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)]()
-[![Static Badge](https://img.shields.io/badge/UMD_%26_ESM-JavaScript?style=for-the-badge&logo=javascript&logoColor=fff&color=orange)]()
+[![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)
 
 **CmpStr** is a TypeScript library for advanced string comparison, similarity measurement, phonetic indexing, and text analysis. It includes implementations of several established algorithms such as Levenshtein, Dice–Sørensen, Damerau–Levenshtein and Soundex. The library has no external dependencies and allows for the integration of custom metrics, phonetic mappings, and normalization filters.
 
@@ -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.0 dev-1a82e20-250612
+ * CmpStr v3.0.2 build-522ae69-250720
  * 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,7 @@ 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}>`);
     }
 }
 
@@ -1902,7 +1902,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 +2059,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 +2120,7 @@ class Metric {
                     this.runPairwise();
                 break;
             // Unsupported mode
-            default: throw new Error(`unsupported mode <${mode}>`);
+            default: throw new Error(`Unsupported mode <${mode}>`);
         }
     }
     /**
@@ -2155,7 +2155,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 +2698,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 +3347,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 +3388,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 +3514,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 +3553,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 +3710,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 +3746,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