cmpstr 3.2.2 → 3.3.0

package/dist/types/utils/OptionsValidator.d.ts

@@ -0,0 +1,193 @@
+/**
+ * CmpStr Options Validator
+ * src/utils/OptionsValidator.ts
+ *
+ * This module provides the OptionsValidator class, which contains static methods for validating
+ * the options passed to the CmpStr function. It checks for correct types, allowed values, and
+ * the existence of specified metrics and phonetic algorithms in their respective registries.
+ *
+ * If any validation fails, a CmpStrValidationError is thrown with a descriptive message and
+ * relevant details about the invalid option.
+ *
+ * @module Utils
+ * @name OptionsValidator
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+import type { CmpStrOptions, CmpStrProcessors, MetricOptions, PhoneticOptions, StructuredDataOptions } from './Types';
+/**
+ * Utility for validating CmpStr options.
+ *
+ * This class provides static methods to validate various aspects of the
+ * options object passed to CmpStr.
+ */
+export declare class OptionsValidator {
+    /** Allowed normalization flags */
+    private static readonly ALLOWED_FLAGS;
+    /** Allowed output modes */
+    private static readonly ALLOWED_OUTPUT;
+    /** Allowed comparison modes */
+    private static readonly ALLOWED_MODES;
+    /** Allowed sort modes */
+    private static readonly ALLOWED_SORT;
+    /** Processor dispatch table */
+    private static readonly PROCESSORS;
+    /** Metric options validation dispatch table */
+    private static readonly METRIC_OPT_MAP;
+    /** Phonetic algorithm options validation dispatch table */
+    private static readonly PHONETIC_OPT_MAP;
+    /** CmpStr options validation dispatch table */
+    private static readonly CMPSTR_OPT_MAP;
+    /**
+     * Internal helper to convert a Set to a string for error messages.
+     *
+     * @param {Set< string >} set - The set to convert
+     * @returns {string} - A string representation of the set
+     */
+    private static set2string;
+    /**
+     * Internal helper to validate primitive types.
+     *
+     * @param {unknown} value - The value to validate.
+     * @param {string} name - The name of the option (for error messages).
+     * @param {'boolean' | 'number' | 'string'} type - The expected type of the value.
+     * @throws {CmpStrValidationError} If the value is not of the expected type or is NaN (for numbers).
+     */
+    private static validateType;
+    /**
+     * Internal helper to validate enum-like values.
+     *
+     * @param {unknown} value - The value to validate.
+     * @param {string} name - The name of the option (for error messages).
+     * @param {Set< string >} set - The set of allowed values.
+     * @throws {CmpStrValidationError} If the value is not a string or is not in the allowed set.
+     */
+    private static validateEnum;
+    /**
+     * Internal helper to validate objects against a dispatch table of validation functions.
+     *
+     * @param {unknown} opt - The object to validate.
+     * @param {Object} map - A dispatch table mapping keys to validation functions.
+     * @throws {CmpStrValidationError} If any property in the object fails validation.
+     */
+    private static validateMap;
+    /**
+     * Internal helper to validate registry-based options (metrics and phonetic algorithms).
+     *
+     * @param {unknown} value - The value to validate.
+     * @param {string} name - The name of the option (for error messages).
+     * @param {string} label - The label to use in error messages (e.g. "Metric" or "Phonetic algorithm").
+     * @param {( v: string ) => boolean} has - A function that checks if the registry contains a given name.
+     * @param {() => string[]} list - A function that returns a list of registered names for error messages.
+     * @throws {CmpStrValidationError} If the value is not a non-empty string or is not registered.
+     */
+    private static validateRegistryName;
+    /**
+     * Validate boolean-like values.
+     *
+     * @param {unknown} value - The value to validate
+     * @param {string} name - The name of the option (for error messages)
+     * @throws {CmpStrValidationError} - If the value is not a boolean
+     */
+    static validateBoolean(value: unknown, name: string): void;
+    /**
+     * Validate number-like values.
+     *
+     * @param {unknown} value - The value to validate
+     * @param {string} name - The name of the option (for error messages)
+     * @throws {CmpStrValidationError} - If the value is not a number or is NaN
+     */
+    static validateNumber(value: unknown, name: string): void;
+    /**
+     * Validate string-like values.
+     *
+     * @param {unknown} value - The value to validate
+     * @param {string} name - The name of the option (for error messages)
+     * @throws {CmpStrValidationError} - If the value is not a string
+     */
+    static validateString(value: unknown, name: string): void;
+    /**
+     * Validate normalization flags.
+     *
+     * @param {unknown} value - The flags to validate
+     * @throws {CmpStrValidationError} - If the flags are not a string or contain invalid characters
+     */
+    static validateFlags(value: unknown): void;
+    /**
+     * Validate CmpStr output mode.
+     *
+     * @param {unknown} value - The output mode to validate
+     * @throws {CmpStrValidationError} - If the output mode is not a string or not allowed
+     */
+    static validateOutput(value: unknown): void;
+    /**
+     * Validate CmpStr comparison mode.
+     *
+     * @param {unknown} value - The comparison mode to validate
+     * @throws {CmpStrValidationError} - If the comparison mode is not a string or not allowed
+     */
+    static validateMode(value: unknown): void;
+    /**
+     * Validate CmpStr structured data sort mode.
+     *
+     * @param {unknown} value - The sort mode to validate
+     * @param {string} name - The name of the option (for error messages)
+     * @throws {CmpStrValidationError} - If the sort mode is neither 'asc', 'desc', nor a boolean
+     */
+    static validateSort(value: unknown, name: string): void;
+    /**
+     * Validate metric name against the MetricRegistry.
+     *
+     * @param {unknown} value - The metric name to validate
+     * @throws {CmpStrValidationError} - If the metric is not a string or not registered
+     */
+    static validateMetricName(value: unknown): void;
+    /**
+     * Validate phonetic algorithm name against the PhoneticRegistry.
+     *
+     * @param {unknown} value - The phonetic algorithm name to validate
+     * @throws {CmpStrValidationError} - If the phonetic algorithm is not a string or not registered
+     */
+    static validatePhoneticName(value: unknown): void;
+    /**
+     * Validate metric options.
+     *
+     * @param {MetricOptions} opt - The metric options to validate
+     * @throws {CmpStrValidationError} - If any metric option is invalid
+     */
+    static validateMetricOptions(opt?: MetricOptions): void;
+    /**
+     * Validate phonetic options.
+     *
+     * @param {PhoneticOptions} opt - The phonetic options to validate
+     * @throws {CmpStrValidationError} - If any phonetic option is invalid
+     */
+    static validatePhoneticOptions(opt?: PhoneticOptions): void;
+    /**
+     * Validate processor options.
+     *
+     * This method iterates over the keys in the provided processor options and dispatches
+     * validation to the corresponding function in the PROCESSORS table.
+     *
+     * If an invalid processor type is found, a CmpStrValidationError is thrown indicating
+     * the invalid type and the expected processor types.
+     *
+     * @param {unknown} opt - The processor options to validate
+     * @throws {CmpStrValidationError} - If any processor type is invalid
+     */
+    static validateProcessors(opt?: CmpStrProcessors): void;
+    /**
+     * Validate the provided CmpStr options object.
+     *
+     * This method performs a comprehensive validation of the options object passed to CmpStr.
+     * It checks for the presence and validity of all supported options, including primitive
+     * types, enum-like values, registry-based names, and nested processor options.
+     *
+     * If any validation check fails, a CmpStrValidationError is thrown with a descriptive
+     * message and relevant details about the invalid option.
+     *
+     * @param {CmpStrOptions | StructuredDataOptions} [opt] - The options object to validate
+     * @throws {CmpStrValidationError} - If any validation check fails
+     */
+    static validateOptions(opt?: CmpStrOptions | StructuredDataOptions): void;
+}

package/dist/types/utils/Profiler.d.ts

@@ -32,6 +32,7 @@ export declare class Profiler {
     private memFn;
     /** Store for profiler entries */
     private store;
+    private last?;
     /** Total time and memory consumption */
     private totalTime;
     private totalMem;
@@ -56,41 +57,21 @@ export declare class Profiler {
      */
     private constructor();
     /**
-     * Gets the current time based on the environment.
+     * Stores a profiler entry in the store and updates the total time and memory consumption.
      *
-     * Uses process.hrtime.bigint() for Node.js, performance.now() for browsers,
-     * and Date.now() as a fallback.
-     *
-     * @returns {number} - Current time in milliseconds
-     */
-    private now;
-    /**
-     * Gets the current memory usage based on the environment.
-     *
-     * Uses process.memoryUsage().heapUsed for Node.js, performance.memory.usedJSHeapSize
-     * for browsers, and returns 0 as a fallback.
-     *
-     * @returns {number} - Current memory usage in bytes
-     */
-    private mem;
-    /**
-     * Profiles a synchronous function by measuring its execution time and memory usage.
-     *
-     * @param {() => T} fn - Function to be executed and profiled
-     * @param {Record< string, any >} meta - Metadata to be associated with the profiling entry
-     * @returns {T} - The result of the executed function
+     * @param {ProfilerEntry< T >} entry - The profiler entry to be stored
      */
-    private profile;
+    private storeRes;
     /**
      * Enables the profiler.
      * Sets the active state to true, allowing profiling to occur.
      */
-    enable: () => void;
+    enable(): void;
     /**
      * Disables the profiler.
      * Sets the active state to false, preventing further profiling.
      */
-    disable: () => void;
+    disable(): void;
     /**
      * Resets the profiler by clearing the store, total time and memory consumption.
      * This method is useful for starting a new profiling session.
@@ -119,19 +100,19 @@ export declare class Profiler {
      *
      * @returns {ProfilerEntry< any >[]} - An array of profiler entries
      */
-    getAll: () => ProfilerEntry<any>[];
+    getAll(): ProfilerEntry<any>[];
     /**
      * Retrieves the last profiler entry stored in the profiler.
      *
      * @returns {ProfilerEntry< any > | undefined} - The last profiler entry or undefined if no entries exist
      */
-    getLast: () => ProfilerEntry<any> | undefined;
+    getLast(): ProfilerEntry<any> | undefined;
     /**
      * Retrieves the total time and memory consumption recorded by the profiler.
      *
      * @returns {{ time: number, mem: number }} - An object containing total time and memory usage
      */
-    getTotal: () => {
+    getTotal(): {
         time: number;
         mem: number;
     };

package/dist/types/utils/StructuredData.d.ts

@@ -29,6 +29,9 @@ import type { CmpFnResult, CmpStrOptions, MetricRaw, StructuredDataBatchResult,
 export declare class StructuredData<T = any, R = MetricRaw> {
     private readonly data;
     private readonly key;
+    /** Sorting functions for ascending and descending order based on the 'res' property. */
+    private static readonly SORT_ASC;
+    private static readonly SORT_DESC;
     /**
      * Creates a new StructuredData instance for processing structured data.
      *

package/dist/types/utils/Types.d.ts

@@ -79,7 +79,7 @@ export interface ProfilerService<T> {
 /**
  * PoolType enumerates the supported buffer types for the Pool utility.
  */
-export type PoolType = 'int32' | 'number[]' | 'string[]' | 'set' | 'map';
+export type PoolType = 'int32' | 'arr[]' | 'number[]' | 'string[]' | 'set' | 'map';
 /**
  * PoolConfig defines the configuration for a buffer pool.
  */
@@ -98,6 +98,18 @@ export interface PoolBuffer<T> {
     buffer: T;
     size: number;
 }
+/**
+ * ================================================================================
+ * VALIDATION
+ * ================================================================================
+ *
+ * Types for option validation.
+ */
+/**
+ * ValidatorFn defines the signature for a validation function.
+ * It takes an unknown value and either returns void if valid or throws an error if invalid.
+ */
+export type ValidatorFn = (v: unknown) => void;
 /**
  * ================================================================================
  * NORMALIZATION & FILTERING

package/package.json

@@ -2,7 +2,7 @@
   "name": "cmpstr",
   "description": "CmpStr is a lightweight, fast and well performing package for calculating string similarity",
   "license": "MIT",
-  "version": "3.2.2",
+  "version": "3.3.0",
   "author": {
     "name": "komed3 (Paul Köhler)",
     "email": "webmaster@komed3.de",
@@ -74,19 +74,28 @@
     "node": ">=18.0.0"
   },
   "types": "./dist/types/index.d.ts",
-  "browser": "./dist/CmpStr.umd.min.js",
   "main": "./dist/cjs/index.cjs",
-  "module": "./dist/esm/index.mjs",
   "exports": {
     ".": {
+      "browser": "./dist/CmpStr.umd.min.js",
       "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.mjs",
       "require": "./dist/cjs/index.cjs",
-      "import": "./dist/esm/index.mjs"
+      "default": "./dist/esm/index.mjs"
     },
     "./root": {
       "types": "./dist/types/root.d.ts",
       "require": "./dist/cjs/root.cjs",
-      "import": "./dist/esm/root.mjs"
+      "import": "./dist/esm/root.mjs",
+      "default": "./dist/esm/root.mjs"
+    },
+    "./bundle": {
+      "import": "./dist/CmpStr.esm.js",
+      "default": "./dist/CmpStr.esm.js"
+    },
+    "./bundle/min": {
+      "import": "./dist/CmpStr.esm.min.js",
+      "default": "./dist/CmpStr.esm.min.js"
     }
   },
   "scripts": {