cmpstr 3.2.1 → 3.3.0

package/dist/cjs/utils/Filter.cjs

@@ -1,49 +1,91 @@
-// CmpStr v3.2.1 build-3439ccb-260130 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.3.0 build-3699f85-260318 by Paul Köhler @komed3 / MIT License
 'use strict';
 
+var Errors = require('./Errors.cjs');
+
 class Filter {
+  static IDENTITY = (s) => s;
   static filters = new Map();
   static pipeline = new Map();
-  static getPipeline(hook) {
-    const cached = Filter.pipeline.get(hook);
-    if (cached) return cached;
-    const filter = Filter.filters.get(hook);
-    if (!filter) return (s) => s;
-    const pipeline = Array.from(filter.values())
-      .filter((f) => f.active)
-      .sort((a, b) => a.priority - b.priority)
-      .map((f) => f.fn);
-    const fn = (input) => pipeline.reduce((v, f) => f(v), input);
-    Filter.pipeline.set(hook, fn);
-    return fn;
+  static getPipeline(hook, force = false) {
+    return Errors.ErrorUtil.wrap(
+      () => {
+        if (!force) {
+          const cached = Filter.pipeline.get(hook);
+          if (cached) return cached;
+        }
+        const filter = Filter.filters.get(hook);
+        if (!filter) {
+          Filter.pipeline.set(hook, Filter.IDENTITY);
+          return Filter.IDENTITY;
+        }
+        const pipeline = [];
+        for (const f of filter.values()) if (f.active) pipeline.push(f);
+        pipeline.sort((a, b) => a.priority - b.priority);
+        const fn =
+          pipeline.length === 0
+            ? Filter.IDENTITY
+            : (input) => {
+                let v = input;
+                for (let i = 0; i < pipeline.length; i++) v = pipeline[i].fn(v);
+                return v;
+              };
+        Filter.pipeline.set(hook, fn);
+        return fn;
+      },
+      `Error compiling filter pipeline for hook <${hook}>`,
+      { hook }
+    );
   }
   static has(hook, id) {
     return !!Filter.filters.get(hook)?.has(id);
   }
   static add(hook, id, fn, opt = {}) {
-    const { priority = 10, active = true, overrideable = true } = opt;
-    const filter = Filter.filters.get(hook) ?? new Map();
-    const index = filter.get(id);
-    if (index && !index.overrideable) return false;
-    filter.set(id, { id, fn, priority, active, overrideable });
-    Filter.filters.set(hook, filter);
-    Filter.pipeline.delete(hook);
-    return true;
+    return Errors.ErrorUtil.wrap(
+      () => {
+        const { priority = 10, active = true, overrideable = true } = opt;
+        const filter = Filter.filters.get(hook) ?? new Map();
+        const index = filter.get(id);
+        if (index && !index.overrideable) return false;
+        if (
+          index &&
+          index.fn === fn &&
+          index.priority === priority &&
+          index.active === active
+        )
+          return true;
+        filter.set(id, { id, fn, priority, active, overrideable });
+        Filter.filters.set(hook, filter);
+        Filter.getPipeline(hook, true);
+        return true;
+      },
+      `Error adding filter <${id}> to hook <${hook}>`,
+      { hook, id, opt }
+    );
   }
   static remove(hook, id) {
-    Filter.pipeline.delete(hook);
     const filter = Filter.filters.get(hook);
-    return filter ? filter.delete(id) : false;
+    if (!filter || !filter.delete(id)) return false;
+    Filter.getPipeline(hook, true);
+    return true;
   }
   static pause(hook, id) {
-    Filter.pipeline.delete(hook);
-    const f = Filter.filters.get(hook)?.get(id);
-    return !!(f && ((f.active = false), true));
+    const filter = Filter.filters.get(hook);
+    if (!filter) return false;
+    const f = filter.get(id);
+    if (!f || !f.active) return false;
+    f.active = false;
+    Filter.getPipeline(hook, true);
+    return true;
   }
   static resume(hook, id) {
-    Filter.pipeline.delete(hook);
-    const f = Filter.filters.get(hook)?.get(id);
-    return !!(f && ((f.active = true), true));
+    const filter = Filter.filters.get(hook);
+    if (!filter) return false;
+    const f = filter.get(id);
+    if (!f || f.active) return false;
+    f.active = true;
+    Filter.getPipeline(hook, true);
+    return true;
   }
   static list(hook, active = false) {
     const filter = Filter.filters.get(hook);
@@ -53,17 +95,36 @@ class Filter {
     return out;
   }
   static apply(hook, input) {
-    const fn = Filter.getPipeline(hook);
-    return Array.isArray(input) ? input.map(fn) : fn(input);
+    return Errors.ErrorUtil.wrap(
+      () => {
+        const fn = Filter.getPipeline(hook);
+        if (typeof input === 'string') return fn(input);
+        const arr = input;
+        const out = new Array(arr.length);
+        for (let i = 0; i < arr.length; i++) out[i] = fn(arr[i]);
+        return out;
+      },
+      `Error applying filters for hook <${hook}>`,
+      { hook, input }
+    );
   }
   static async applyAsync(hook, input) {
-    const fn = Filter.getPipeline(hook);
-    return Array.isArray(input)
-      ? Promise.all(input.map(fn))
-      : Promise.resolve(fn(input));
+    return Errors.ErrorUtil.wrapAsync(
+      async () => {
+        const fn = Filter.getPipeline(hook);
+        if (typeof input === 'string') return Promise.resolve(fn(input));
+        const arr = input;
+        const out = new Array(arr.length);
+        for (let i = 0; i < arr.length; i++)
+          out[i] = Promise.resolve(fn(arr[i]));
+        return Promise.all(out);
+      },
+      `Error applying filters for hook <${hook}>`,
+      { hook, input }
+    );
   }
   static clear(hook) {
-    Filter.pipeline.clear();
+    Filter.clearPipeline();
     if (hook) Filter.filters.delete(hook);
     else Filter.filters.clear();
   }
@@ -73,4 +134,3 @@ class Filter {
 }
 
 exports.Filter = Filter;
-//# sourceMappingURL=Filter.cjs.map

package/dist/cjs/utils/HashTable.cjs

@@ -1,4 +1,4 @@
-// CmpStr v3.2.1 build-3439ccb-260130 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.3.0 build-3699f85-260318 by Paul Köhler @komed3 / MIT License
 'use strict';
 
 class Hasher {
@@ -6,25 +6,21 @@ class Hasher {
   static HASH_OFFSET = 0x811c9dc5;
   static fastFNV1a(str) {
     const len = str.length;
+    const limit = len & -4;
     let hash = this.HASH_OFFSET;
-    const chunks = Math.floor(len / 4);
-    for (let i = 0; i < chunks; i++) {
-      const pos = i * 4;
+    let i = 0;
+    for (; i < limit; i += 4) {
       const chunk =
-        str.charCodeAt(pos) |
-        (str.charCodeAt(pos + 1) << 8) |
-        (str.charCodeAt(pos + 2) << 16) |
-        (str.charCodeAt(pos + 3) << 24);
+        str.charCodeAt(i) |
+        (str.charCodeAt(i + 1) << 8) |
+        (str.charCodeAt(i + 2) << 16) |
+        (str.charCodeAt(i + 3) << 24);
       hash ^= chunk;
       hash = Math.imul(hash, this.FNV_PRIME);
     }
-    const remaining = len % 4;
-    if (remaining > 0) {
-      const pos = chunks * 4;
-      for (let i = 0; i < remaining; i++) {
-        hash ^= str.charCodeAt(pos + i);
-        hash = Math.imul(hash, this.FNV_PRIME);
-      }
+    for (; i < len; i++) {
+      hash ^= str.charCodeAt(i);
+      hash = Math.imul(hash, this.FNV_PRIME);
     }
     hash ^= hash >>> 16;
     hash *= 0x85ebca6b;
@@ -35,34 +31,52 @@ class Hasher {
   }
 }
 class HashTable {
-  LRU;
+  FIFO;
+  maxSize;
   static MAX_LEN = 2048;
-  static TABLE_SIZE = 10_000;
   table = new Map();
-  constructor(LRU = true) {
-    this.LRU = LRU;
+  constructor(FIFO = true, maxSize = 10000) {
+    this.FIFO = FIFO;
+    this.maxSize = maxSize;
   }
   key(label, strs, sorted = false) {
-    for (const str of strs) if (str.length > HashTable.MAX_LEN) return false;
-    const hashes = strs.map((s) => Hasher.fastFNV1a(s));
-    return [label, ...(sorted ? hashes.sort() : hashes)].join('-');
+    const n = strs.length;
+    const hashes = new Array(n);
+    for (let i = 0; i < n; i++) {
+      const s = strs[i];
+      if (s.length > HashTable.MAX_LEN) return false;
+      hashes[i] = Hasher.fastFNV1a(s);
+    }
+    if (sorted) hashes.sort((a, b) => a - b);
+    let key = label;
+    for (let i = 0; i < hashes.length; i++) key += '-' + hashes[i];
+    return key;
+  }
+  has(key) {
+    return this.table.has(key);
+  }
+  get(key) {
+    return this.table.get(key);
   }
-  has = (key) => this.table.has(key);
-  get = (key) => this.table.get(key);
   set(key, entry, update = true) {
     if (!update && this.table.has(key)) return false;
-    while (!this.table.has(key) && this.table.size >= HashTable.TABLE_SIZE) {
-      if (!this.LRU) return false;
+    if (!this.table.has(key) && this.table.size >= this.maxSize) {
+      if (!this.FIFO) return false;
       this.table.delete(this.table.keys().next().value);
     }
     this.table.set(key, entry);
     return true;
   }
-  delete = (key) => this.table.delete(key);
-  clear = () => this.table.clear();
-  size = () => this.table.size;
+  delete(key) {
+    return this.table.delete(key);
+  }
+  clear() {
+    this.table.clear();
+  }
+  size() {
+    return this.table.size;
+  }
 }
 
 exports.HashTable = HashTable;
 exports.Hasher = Hasher;
-//# sourceMappingURL=HashTable.cjs.map

package/dist/cjs/utils/Normalizer.cjs

@@ -1,6 +1,7 @@
-// CmpStr v3.2.1 build-3439ccb-260130 by Paul Köhler @komed3 / MIT License
+// CmpStr v3.3.0 build-3699f85-260318 by Paul Köhler @komed3 / MIT License
 'use strict';
 
+var Errors = require('./Errors.cjs');
 var HashTable = require('./HashTable.cjs');
 
 class Normalizer {
@@ -17,42 +18,91 @@ class Normalizer {
     return Array.from(new Set(flags)).sort().join('');
   }
   static getPipeline(flags) {
-    if (Normalizer.pipeline.has(flags)) return Normalizer.pipeline.get(flags);
-    const { REGEX } = Normalizer;
-    const steps = [
-      ['d', (s) => s.normalize('NFD')],
-      ['i', (s) => s.toLowerCase()],
-      ['k', (s) => s.replace(REGEX.nonLetters, '')],
-      ['n', (s) => s.replace(REGEX.nonNumbers, '')],
-      ['r', (s) => s.replace(REGEX.doubleChars, '$1')],
-      ['s', (s) => s.replace(REGEX.specialChars, '')],
-      ['t', (s) => s.trim()],
-      ['u', (s) => s.normalize('NFC')],
-      ['w', (s) => s.replace(REGEX.whitespace, ' ')],
-      ['x', (s) => s.normalize('NFKC')]
-    ];
-    const pipeline = steps
-      .filter(([f]) => flags.includes(f))
-      .map(([, fn]) => fn);
-    const fn = (s) => pipeline.reduce((v, f) => f(v), s);
-    Normalizer.pipeline.set(flags, fn);
-    return fn;
+    return Errors.ErrorUtil.wrap(
+      () => {
+        const cached = Normalizer.pipeline.get(flags);
+        if (cached) return cached;
+        const { REGEX } = Normalizer;
+        const steps = [];
+        for (let i = 0; i < flags.length; i++) {
+          switch (flags[i]) {
+            case 'd':
+              steps.push((s) => s.normalize('NFD'));
+              break;
+            case 'i':
+              steps.push((s) => s.toLowerCase());
+              break;
+            case 'k':
+              steps.push((s) => s.replace(REGEX.nonLetters, ''));
+              break;
+            case 'n':
+              steps.push((s) => s.replace(REGEX.nonNumbers, ''));
+              break;
+            case 'r':
+              steps.push((s) => s.replace(REGEX.doubleChars, '$1'));
+              break;
+            case 's':
+              steps.push((s) => s.replace(REGEX.specialChars, ''));
+              break;
+            case 't':
+              steps.push((s) => s.trim());
+              break;
+            case 'u':
+              steps.push((s) => s.normalize('NFC'));
+              break;
+            case 'w':
+              steps.push((s) => s.replace(REGEX.whitespace, ' '));
+              break;
+            case 'x':
+              steps.push((s) => s.normalize('NFKC'));
+              break;
+          }
+        }
+        const fn = (input) => {
+          let v = input;
+          for (let i = 0; i < steps.length; i++) v = steps[i](v);
+          return v;
+        };
+        Normalizer.pipeline.set(flags, fn);
+        return fn;
+      },
+      `Failed to create normalization pipeline for flags: ${flags}`,
+      { flags }
+    );
   }
-  static normalize(input, flags) {
-    if (!flags || typeof flags !== 'string' || !input) return input;
-    flags = this.canonicalFlags(flags);
-    if (Array.isArray(input))
-      return input.map((s) => Normalizer.normalize(s, flags));
-    const key = Normalizer.cache.key(flags, [input]);
-    if (key && Normalizer.cache.has(key)) return Normalizer.cache.get(key);
-    const res = Normalizer.getPipeline(flags)(input);
-    if (key) Normalizer.cache.set(key, res);
-    return res;
+  static normalize(input, flags, normalizedFlags) {
+    return Errors.ErrorUtil.wrap(
+      () => {
+        if (!flags || typeof flags !== 'string' || !input) return input;
+        flags = normalizedFlags ?? this.canonicalFlags(flags);
+        const pipeline = Normalizer.getPipeline(flags);
+        const normalizeOne = (s) => {
+          const key = Normalizer.cache.key(flags, [s]);
+          if (key && Normalizer.cache.has(key))
+            return Normalizer.cache.get(key);
+          const res = pipeline(s);
+          if (key) Normalizer.cache.set(key, res);
+          return res;
+        };
+        return Array.isArray(input)
+          ? input.map(normalizeOne)
+          : normalizeOne(input);
+      },
+      `Failed to normalize input with flags: ${flags}`,
+      { input, flags }
+    );
   }
   static async normalizeAsync(input, flags) {
-    return await (Array.isArray(input)
-      ? Promise.all(input.map((s) => Normalizer.normalize(s, flags)))
-      : Promise.resolve(Normalizer.normalize(input, flags)));
+    return await Errors.ErrorUtil.wrapAsync(
+      async () => {
+        if (!flags || typeof flags !== 'string' || !input) return input;
+        return await (Array.isArray(input)
+          ? Promise.all(input.map((s) => Normalizer.normalize(s, flags)))
+          : Promise.resolve(Normalizer.normalize(input, flags)));
+      },
+      `Failed to asynchronously normalize input with flags: ${flags}`,
+      { input, flags }
+    );
   }
   static clear() {
     Normalizer.pipeline.clear();
@@ -61,4 +111,3 @@ class Normalizer {
 }
 
 exports.Normalizer = Normalizer;
-//# sourceMappingURL=Normalizer.cjs.map

package/dist/cjs/utils/OptionsValidator.cjs

@@ -0,0 +1,211 @@
+// CmpStr v3.3.0 build-3699f85-260318 by Paul Köhler @komed3 / MIT License
+'use strict';
+
+var Errors = require('./Errors.cjs');
+require('../metric/Cosine.cjs');
+require('../metric/DamerauLevenshtein.cjs');
+require('../metric/DiceSorensen.cjs');
+require('../metric/Hamming.cjs');
+require('../metric/Jaccard.cjs');
+require('../metric/JaroWinkler.cjs');
+require('../metric/LCS.cjs');
+require('../metric/Levenshtein.cjs');
+require('../metric/NeedlemanWunsch.cjs');
+require('../metric/QGram.cjs');
+require('../metric/SmithWaterman.cjs');
+var Metric = require('../metric/Metric.cjs');
+require('../phonetic/Caverphone.cjs');
+require('../phonetic/Cologne.cjs');
+require('../phonetic/Metaphone.cjs');
+require('../phonetic/Soundex.cjs');
+var Phonetic = require('../phonetic/Phonetic.cjs');
+
+class OptionsValidator {
+  static ALLOWED_FLAGS = new Set([
+    'd',
+    'u',
+    'x',
+    'w',
+    't',
+    'r',
+    's',
+    'k',
+    'n',
+    'i'
+  ]);
+  static ALLOWED_OUTPUT = new Set(['orig', 'prep']);
+  static ALLOWED_MODES = new Set(['default', 'batch', 'single', 'pairwise']);
+  static ALLOWED_SORT = new Set(['asc', 'desc']);
+  static PROCESSORS = {
+    phonetic: (opt) => {
+      if (!opt) return;
+      OptionsValidator.validatePhoneticName(opt.algo);
+      OptionsValidator.validatePhoneticOptions(opt.opt);
+    }
+  };
+  static METRIC_OPT_MAP = {
+    mode: (v) => OptionsValidator.validateMode(v),
+    delimiter: (v) => OptionsValidator.validateString(v, 'opt.delimiter'),
+    pad: (v) => OptionsValidator.validateString(v, 'opt.pad'),
+    q: (v) => OptionsValidator.validateNumber(v, 'opt.q'),
+    match: (v) => OptionsValidator.validateNumber(v, 'opt.match'),
+    mismatch: (v) => OptionsValidator.validateNumber(v, 'opt.mismatch'),
+    gap: (v) => OptionsValidator.validateNumber(v, 'opt.gap')
+  };
+  static PHONETIC_OPT_MAP = {
+    map: (v) =>
+      OptionsValidator.validateString(v, 'processors.phonetic.opt.map'),
+    delimiter: (v) =>
+      OptionsValidator.validateString(v, 'processors.phonetic.opt.delimiter'),
+    length: (v) =>
+      OptionsValidator.validateNumber(v, 'processors.phonetic.opt.length'),
+    pad: (v) =>
+      OptionsValidator.validateString(v, 'processors.phonetic.opt.pad'),
+    dedupe: (v) =>
+      OptionsValidator.validateBoolean(v, 'processors.phonetic.opt.dedupe'),
+    fallback: (v) =>
+      OptionsValidator.validateString(v, 'processors.phonetic.opt.fallback')
+  };
+  static CMPSTR_OPT_MAP = {
+    raw: (v) => OptionsValidator.validateBoolean(v, 'raw'),
+    removeZero: (v) => OptionsValidator.validateBoolean(v, 'removeZero'),
+    safeEmpty: (v) => OptionsValidator.validateBoolean(v, 'safeEmpty'),
+    flags: (v) => OptionsValidator.validateFlags(v),
+    metric: (v) => OptionsValidator.validateMetricName(v),
+    output: (v) => OptionsValidator.validateOutput(v),
+    opt: (v) => OptionsValidator.validateMetricOptions(v),
+    processors: (v) => OptionsValidator.validateProcessors(v),
+    sort: (v) => OptionsValidator.validateSort(v, 'sort'),
+    objectsOnly: (v) => OptionsValidator.validateBoolean(v, 'objectsOnly')
+  };
+  static set2string(set) {
+    return Array.from(set).join(' | ');
+  }
+  static validateType(value, name, type) {
+    if (value === undefined) return;
+    if (typeof value !== type || (type === 'number' && Number.isNaN(value))) {
+      throw new Errors.CmpStrValidationError(
+        `Invalid option <${name}>: expected ${type}`,
+        { name, value }
+      );
+    }
+  }
+  static validateEnum(value, name, set) {
+    if (value === undefined) return;
+    if (typeof value !== 'string' || !set.has(value)) {
+      throw new Errors.CmpStrValidationError(
+        `Invalid option <${name}>: expected ${OptionsValidator.set2string(set)}`,
+        { name, value }
+      );
+    }
+  }
+  static validateMap(opt, map) {
+    if (!opt) return;
+    for (const k in opt) {
+      const fn = map[k];
+      if (!fn)
+        throw new Errors.CmpStrValidationError(`Invalid option <${k}>`, {
+          option: k,
+          value: map[k]
+        });
+      fn(opt[k]);
+    }
+  }
+  static validateRegistryName(value, name, label, has, list) {
+    if (value === undefined) return;
+    if (typeof value !== 'string' || value.length === 0)
+      throw new Errors.CmpStrValidationError(
+        `Invalid option <${name}>: expected non-empty string`,
+        { name, value }
+      );
+    if (!has(value))
+      throw new Errors.CmpStrValidationError(
+        `${label} <${value}> is not registered`,
+        { name, value, available: list() }
+      );
+  }
+  static validateBoolean(value, name) {
+    OptionsValidator.validateType(value, name, 'boolean');
+  }
+  static validateNumber(value, name) {
+    OptionsValidator.validateType(value, name, 'number');
+  }
+  static validateString(value, name) {
+    OptionsValidator.validateType(value, name, 'string');
+  }
+  static validateFlags(value) {
+    if (value === undefined) return;
+    if (typeof value !== 'string')
+      throw new Errors.CmpStrValidationError(
+        `Invalid option <flags>: expected string`,
+        { flags: value }
+      );
+    for (let i = 0; i < value.length; i++) {
+      const ch = value[i];
+      if (!OptionsValidator.ALLOWED_FLAGS.has(ch))
+        throw new Errors.CmpStrValidationError(
+          `Invalid normalization flag <${ch}> in <flags>: expected ${OptionsValidator.set2string(OptionsValidator.ALLOWED_FLAGS)}`,
+          { flags: value, invalid: ch }
+        );
+    }
+  }
+  static validateOutput(value) {
+    OptionsValidator.validateEnum(
+      value,
+      'output',
+      OptionsValidator.ALLOWED_OUTPUT
+    );
+  }
+  static validateMode(value) {
+    OptionsValidator.validateEnum(
+      value,
+      'mode',
+      OptionsValidator.ALLOWED_MODES
+    );
+  }
+  static validateSort(value, name) {
+    if (value === undefined || typeof value === 'boolean') return;
+    OptionsValidator.validateEnum(value, name, OptionsValidator.ALLOWED_SORT);
+  }
+  static validateMetricName(value) {
+    OptionsValidator.validateRegistryName(
+      value,
+      'metric',
+      'Comparison metric',
+      Metric.MetricRegistry.has,
+      Metric.MetricRegistry.list
+    );
+  }
+  static validatePhoneticName(value) {
+    OptionsValidator.validateRegistryName(
+      value,
+      'phonetic',
+      'Phonetic algorithm',
+      Phonetic.PhoneticRegistry.has,
+      Phonetic.PhoneticRegistry.list
+    );
+  }
+  static validateMetricOptions(opt) {
+    OptionsValidator.validateMap(opt, OptionsValidator.METRIC_OPT_MAP);
+  }
+  static validatePhoneticOptions(opt) {
+    OptionsValidator.validateMap(opt, OptionsValidator.PHONETIC_OPT_MAP);
+  }
+  static validateProcessors(opt) {
+    if (!opt) return;
+    for (const key in opt) {
+      const fn = OptionsValidator.PROCESSORS[key];
+      if (!fn)
+        throw new Errors.CmpStrValidationError(
+          `Invalid processor type <${key}> in <processors>: expected ${Object.keys(OptionsValidator.PROCESSORS).join(' | ')}`,
+          { processors: opt, invalid: key }
+        );
+      fn(opt[key]);
+    }
+  }
+  static validateOptions(opt) {
+    OptionsValidator.validateMap(opt, OptionsValidator.CMPSTR_OPT_MAP);
+  }
+}
+
+exports.OptionsValidator = OptionsValidator;