cmpstr 3.1.1 → 3.2.0

package/dist/types/root.d.ts

@@ -9,7 +9,7 @@
  * Please visit CmpStr's documentation for more information:
  * https://github.com/komed3/cmpstr/wiki/Extending-CmpStr
  *
- * @version 3.1.1
+ * @version 3.2.0
  * @author Paul Köhler (komed3)
  * @license MIT
  */
@@ -17,23 +17,23 @@ export * from './index';
 /**
  * Export utils to implement new metrics
  *
- *  - MetricRegistry: Metric registry service for managing metric implementations.
  *  - Metric: Abstract class representing a generic string metric.
  *  - MetricCls: Type definition for a class constructor that extends the Metric class.
+ *  - MetricRegistry: Metric registry service for managing metric implementations.
  */
-export { MetricRegistry, Metric, MetricCls } from './metric';
+export { Metric, MetricCls, MetricRegistry } from './metric';
 /**
  * Export utils to implement new phonetic algorithms
  *
- *  - PhoneticRegistry: Phonetic registry service for managing phonetic algorithm implementations.
- *  - PhoneticMappingRegistry: Registry for managing phonetic character mappings.
  *  - Phonetic: Abstract class representing a generic phonetic algorithm.
  *  - PhoneticCls: Type definition for a class constructor that extends the Phonetic class.
+ *  - PhoneticMappingRegistry: Registry for managing phonetic character mappings.
+ *  - PhoneticRegistry: Phonetic registry service for managing phonetic algorithm implementations.
  */
-export { PhoneticRegistry, PhoneticMappingRegistry, Phonetic, PhoneticCls } from './phonetic';
+export { Phonetic, PhoneticCls, PhoneticMappingRegistry, PhoneticRegistry } from './phonetic';
 export * as DeepMerge from './utils/DeepMerge';
 export { Filter } from './utils/Filter';
-export { HashTable } from './utils/HashTable';
+export { Hasher, HashTable } from './utils/HashTable';
 export { Pool } from './utils/Pool';
 export { Profiler } from './utils/Profiler';
 export { StructuredData } from './utils/StructuredData';

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

@@ -22,12 +22,13 @@
  * Deeply get a value from an object by a path string.
  *
  * @template T - The type of the object to get the value from
+ * @template R - The return type of the value
  * @param {T} t - The object to get the value from
  * @param {string} path - The path string, e.g. `a.b.c`
- * @param {any} fallback - The default value to return if the path does not exist
- * @returns {T|R|undefined} - The value at the specified path, otherwise the default value
+ * @param {any} fb - The default value to return if the path does not exist
+ * @returns {R | undefined} - The value at the specified path, otherwise the default value
  */
-export declare function get<T extends Record<string, any>, R = any>(t: T, path: string, fallback?: any): T | R | undefined;
+export declare function get<T extends Record<string, any>, R = any>(t: T, path: string, fb?: R): R | undefined;
 /**
  * Check if a path exists in an object.
  *

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

@@ -24,17 +24,20 @@
  * @author Paul Köhler (komed3)
  * @license MIT
  */
-import type { DiffOptions, DiffLine, DiffGroup } from './Types';
+import type { DiffGroup, DiffLine, DiffOptions } from './Types';
 /**
  * The DiffChecker class provides methods to compare two texts and generate
  * structured diffs, grouped diffs, and unified diff outputs.
  */
 export declare class DiffChecker {
+    /** Original input texts and options */
     private readonly a;
     private readonly b;
     private readonly options;
+    /** Computed diff entries and groups */
     private entries;
     private grouped;
+    /** Flag to indicate if the diff has already been computed */
     private diffRun;
     /**
      * Constructs a new DiffChecker instance for comparing two texts.
@@ -45,8 +48,7 @@ export declare class DiffChecker {
      */
     constructor(a: string, b: string, opt?: DiffOptions);
     /**
-     * Splits both input texts into arrays of lines and returns them
-     * with the maximum line count.
+     * Splits both input texts into arrays of lines and returns them with the maximum line count.
      *
      * @returns { linesA: string[], linesB: string[], maxLen: number }
      */
@@ -115,23 +117,23 @@ export declare class DiffChecker {
      *
      * @returns {DiffLine[]} - Array of line-level diffs
      */
-    getStructuredDiff(): DiffLine[];
+    getStructuredDiff: () => DiffLine[];
     /**
      * Returns the grouped diff as an array of DiffGroup objects.
      *
      * @returns {DiffGroup[]} - Array of grouped diffs
      */
-    getGroupedDiff(): DiffGroup[];
+    getGroupedDiff: () => DiffGroup[];
     /**
      * Returns the unified diff as a plain ASCII string.
      *
      * @returns {string} - Unified diff (ASCII)
      */
-    getASCIIDiff(): string;
+    getASCIIDiff: () => string;
     /**
      * Returns the unified diff as a CLI-colored string.
      *
      * @returns {string} - Unified diff (CLI colors)
      */
-    getCLIDiff(): string;
+    getCLIDiff: () => string;
 }

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

@@ -18,17 +18,30 @@ import type { FilterFn, FilterOptions } from './Types';
 export declare class Filter {
     /**
      * A static map to hold all filters.
-     * The key is the hook name, and the value is an array of FilterEntry objects.
+     * The key is the hook name, and the value is an Map of FilterEntry objects.
      */
     private static filters;
     /**
-     * Finds a filter by its hook and id.
+     * A map that holds the pipeline of filters to be applied.
+     * The key is the hook name, and the value is the compiled function.
+     */
+    private static pipeline;
+    /**
+     * Retrieves the compiled filter function for a given hook.
+     * If the function is not cached, it compiles it from the active filters.
+     *
+     * @param {string} hook - The name of the hook
+     * @returns {FilterFn} - The compiled filter function for the hook
+     */
+    private static getPipeline;
+    /**
+     * Checks if a filter exists for a given hook and id.
      *
      * @param {string} hook - The name of the hook
      * @param {string} id - The id of the filter
-     * @returns {FilterEntry|undefined} - The FilterEntry if found, otherwise undefined
+     * @returns {boolean} - Returns true if the filter exists, false otherwise
      */
-    private static find;
+    static has(hook: string, id: string): boolean;
     /**
      * Adds a filter to the specified hook.
      *
@@ -75,8 +88,8 @@ export declare class Filter {
      * Applies all active filters for a given hook to the input string(s).
      *
      * @param {string} hook - The name of the hook
-     * @param {string|string[]} input - The input string(s) to be filtered
-     * @returns {string|string[]} - The filtered string(s)
+     * @param {string | string[]} input - The input string(s) to be filtered
+     * @returns {string | string[]} - The filtered string(s)
      */
     static apply(hook: string, input: string | string[]): string | string[];
     /**
@@ -84,12 +97,13 @@ export declare class Filter {
      * Each filter function may return a Promise or a plain string; all are awaited in order.
      *
      * @param {string} hook - The name of the hook
-     * @param {string|string[]} input - The input string(s) to be filtered
-     * @returns {Promise<string|string[]>} - The filtered string(s)
+     * @param {string | string[]} input - The input string(s) to be filtered
+     * @returns {Promise< string | string[] >} - The filtered string(s)
      */
     static applyAsync(hook: string, input: string | string[]): Promise<string | string[]>;
     /**
      * Clears all filters or filters for a specific hook.
+     * If no hook is provided, clear all filters
      *
      * @param {string} [hook] - Optional name of the hook to clear filters for
      */

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

@@ -3,12 +3,14 @@
  * src/utils/HashTable.ts
  *
  * @see https://en.wikipedia.org/wiki/Fowler–Noll–Vo_hash_function
+ * @see https://en.wikipedia.org/wiki/MurmurHash
  * @see https://en.wikipedia.org/wiki/Hash_table
  *
- * This module implements an instantiable hash table/cache using the FNV-1a hash algorithm.
+ * This module implements an instantiable hash table/cache using a modified FNV-1a hash
+ * algorithm, optimized for speed and low collision rates.
+ *
  * It allows for multiple independent caches (e.g. for metrics, normalization, etc.) with
- * type safety and high performance. The FNV-1a algorithm is factored out into its own
- * static utility class to avoid code duplication and memory overhead.
+ * type safety and high performance.
  *
  * The key() method supports any number of string arguments, enabling flexible cache keys
  * for different use cases (e.g. normalization, metrics, etc.).
@@ -17,6 +19,26 @@
  * @author Paul Köhler (komed3)
  * @license MIT
  */
+/**
+ * Hasher Utility
+ * Static class for modified FNV-1a hash algorithm implementation.
+ */
+export declare class Hasher {
+    /** Constants for the hash algorithm */
+    private static readonly FNV_PRIME;
+    private static readonly HASH_OFFSET;
+    /**
+     * Computes a hash value for a given string using the FNV-1a algorithm.
+     *
+     * Modifications:
+     * - Processes 4 characters at a time (chunks)
+     * - Using MurmurHash3 finalizer
+     *
+     * @param {string} str - The string to hash
+     * @return {number} - The computed hash value as an unsigned 32-bit integer
+     */
+    static fastFNV1a(str: string): number;
+}
 /**
  * HashTable class implements an instantiable hash table/cache.
  * Allows for multiple independent caches with type safety and high performance.
@@ -25,7 +47,10 @@
  * @template T - The type of value to be stored in the hash table (e.g. MetricCompute, string, …)
  */
 export declare class HashTable<K extends string, T> {
+    private readonly LRU;
+    /** The max. length of a string to hash, which is set to 2048 characters */
     private static readonly MAX_LEN;
+    /** The max. size of the hash table, which is set to 10,000 */
     private static readonly TABLE_SIZE;
     /**
      * The internal map to store entries.
@@ -33,14 +58,21 @@ export declare class HashTable<K extends string, T> {
      * The value is of type T.
      */
     private table;
+    /**
+     * Creates an instance of HashTable.
+     *
+     * @param {boolean} [LRU=true] - Whether to use Least Recently Used (LRU) eviction policy
+     */
+    constructor(LRU?: boolean);
     /**
      * Generates a unique hash key for any number of string arguments.
+     * Return false if any string exceeds the maximum length.
      * The key is in the format "label-H1-H2-H3-..."
      *
      * @param {K} label - Label for this key (e.g. metric name, normalization flags, …)
      * @param {string[]} strs - Array of strings to hash (e.g. input, params, …)
      * @param {boolean} [sorted=false] - Whether to sort the hashes before creating the key
-     * @returns {string|false} - A unique hash key or false if any string is too long
+     * @returns {string | false} - A unique hash key or false if any string is too long
      */
     key(label: K, strs: string[], sorted?: boolean): string | false;
     /**
@@ -49,16 +81,17 @@ export declare class HashTable<K extends string, T> {
      * @param {string} key - The key to check
      * @returns {boolean} - True if the key exists, false otherwise
      */
-    has(key: string): boolean;
+    has: (key: string) => boolean;
     /**
      * Retrieves the entry from the hash table by its key.
      *
      * @param {string} key - The key to look up
-     * @returns {T|undefined} - The entry if found, undefined otherwise
+     * @returns {T | undefined} - The entry if found, undefined otherwise
      */
-    get(key: string): T | undefined;
+    get: (key: string) => T | undefined;
     /**
      * Adds an entry to the hash table.
+     * If the table is full, it evicts the least recently used entry (if LRU is enabled).
      *
      * @param {string} key - The hashed key for the entry
      * @param {T} entry - The entry itself to add
@@ -70,17 +103,18 @@ export declare class HashTable<K extends string, T> {
      * Deletes an entry from the hash table by its key.
      *
      * @param {string} key - The key of the entry to delete
+     * @returns {boolean} - True if the entry was deleted, false if the key was not found
      */
-    delete(key: string): void;
+    delete: (key: string) => boolean;
     /**
      * Clears the hash table.
      * This method removes all entries from the hash table.
      */
-    clear(): void;
+    clear: () => void;
     /**
      * Returns the current size of the hash table.
      *
      * @returns {number} - The number of entries in the hash table
      */
-    size(): number;
+    size: () => number;
 }

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

@@ -41,6 +41,15 @@ export declare class Normalizer {
      * This helps avoid recomputing normalization for the same input and flags.
      */
     private static cache;
+    /** Regular expressions used in normalization steps */
+    private static readonly REGEX;
+    /**
+     * Returns a canonical version of the flags by removing duplicates and sorting them.
+     *
+     * @param {NormalizeFlags} flags - The normalization flags
+     * @returns {NormalizeFlags} - The canonicalized flags
+     */
+    private static canonicalFlags;
     /**
      * Returns a normalization function based on the provided flags.
      * The flags are a string of characters that define the normalization steps.
@@ -53,9 +62,9 @@ export declare class Normalizer {
      * Normalizes the input string or array of strings based on the provided flags.
      * The flags are a string of characters that define the normalization steps.
      *
-     * @param {string|string[]} input - The string or array of strings to normalize
+     * @param {string | string[]} input - The string or array of strings to normalize
      * @param {NormalizeFlags} flags - A string of characters representing the normalization steps
-     * @returns {string|string[]} - The normalized string(s)
+     * @returns {string | string[]} - The normalized string(s)
      */
     static normalize(input: string | string[], flags: NormalizeFlags): string | string[];
     /**
@@ -63,9 +72,9 @@ export declare class Normalizer {
      * provided flags. This method is useful for handling large inputs or when
      * normalization needs to be done in a non-blocking way.
      *
-     * @param {string|string[]} input - The string or array of strings to normalize
+     * @param {string | string[]} input - The string or array of strings to normalize
      * @param {NormalizeFlags} flags - A string of characters representing the normalization steps
-     * @returns {Promise<string|string[]>} - A promise that resolves to the normalized string(s)
+     * @returns {Promise< string | string[] >} - A promise that resolves to the normalized string(s)
      */
     static normalizeAsync(input: string | string[], flags: NormalizeFlags): Promise<string | string[]>;
     /**

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

@@ -9,7 +9,7 @@
  * By reusing pre-allocated typed arrays, it reduces memory allocations and garbage
  * collection overhead, especially for repeated or batch computations.
  *
- * It supports different types of buffers (Uint16Array, number[], string[], Set, Map)
+ * It supports different types of buffers (Int32Array, number[], string[], Set, Map)
  * and allows for acquiring buffers of specific sizes while managing a max pool size.
  *
  * @module Utils/Pool
@@ -20,11 +20,13 @@ import type { PoolType } from './Types';
 /**
  * The Pool class provides a buffer pool for dynamic programming algorithms.
  *
- * It allows for efficient reuse of buffers (Uint16Array, number[], Set, Map)
+ * It allows for efficient reuse of buffers (Int32Array, number[], Set, Map)
  * to reduce memory allocations and garbage collection overhead.
  */
 export declare class Pool {
+    /** Pool Types */
     private static readonly CONFIG;
+    /** Pool Rings for each type */
     private static readonly POOLS;
     /**
      * Allocates a new buffer of the specified type and size.
@@ -38,7 +40,7 @@ export declare class Pool {
      * Acquires a buffer of the specified type and size from the pool.
      * If no suitable buffer is available, it allocates a new one.
      *
-     * @param {PoolType} type - The type of buffer to acquire (e.g., 'uint16', 'number[]', 'set', 'map')
+     * @param {PoolType} type - The type of buffer to acquire (e.g., 'int32', 'number[]', 'map')
      * @param {number} size - The size of the buffer to acquire
      * @return {T} - The acquired buffer of the specified type
      */

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

@@ -21,19 +21,26 @@ import type { ProfilerEntry, ProfilerService } from './Types';
  * Profiler class for measuring execution time and memory usage of functions.
  */
 export declare class Profiler {
+    private active;
+    /** Environment detection */
     private static ENV;
+    /** Singleton instance */
     private static instance;
+    /** Pre-computed functions for time and memory retrieval */
+    private nowFn;
+    private memFn;
+    /** Store for profiler entries */
     private store;
+    /** Total time and memory consumption */
     private totalTime;
     private totalMem;
-    private active;
     /**
      * Sets the environment based on the available global objects.
      * Detects if running in Node.js or browser and sets the ENV property accordingly.
      */
     protected static detectEnv(): void;
     /**
-     * Returns the singleton instance of the Perf class.
+     * Returns the singleton instance of the Profiler class.
      * If the instance does not exist, it creates a new one.
      *
      * @param {boolean} [enable=false] - Optional parameter to enable the profiler upon instantiation
@@ -44,7 +51,7 @@ export declare class Profiler {
      * Private constructor to enforce singleton pattern.
      * Initializes the store for profiler entries.
      *
-     * @param {boolean} [enable=false] - Optional parameter to enable the profiler
+     * @param {boolean} [active=false] - Optional parameter to enable the profiler
      */
     private constructor();
     /**
@@ -65,16 +72,24 @@ export declare class Profiler {
      * @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
+     */
+    private profile;
     /**
      * 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.
@@ -85,7 +100,7 @@ export declare class Profiler {
      * If the profiler is not active, it simply executes the function without profiling.
      *
      * @param {() => T} fn - Function to be executed and profiled
-     * @param {Record<string, any>} meta - Metadata to be associated with the profiling entry
+     * @param {Record< string, any >} meta - Metadata to be associated with the profiling entry
      * @returns {T} - The result of the executed function
      */
     run<T>(fn: () => T, meta?: Record<string, any>): T;
@@ -93,29 +108,29 @@ export declare class Profiler {
      * Runs an asynchronous function and profiles its execution time and memory usage.
      * If the profiler is not active, it simply executes the function without profiling.
      *
-     * @param {() => Promise<T>} fn - Asynchronous function to be executed and profiled
-     * @param {Record<string, any>} meta - Metadata to be associated with the profiling entry
-     * @returns {Promise<T>} - A promise that resolves to the result of the executed function
+     * @param {() => Promise< T >} fn - Asynchronous function to be executed and profiled
+     * @param {Record< string, any >} meta - Metadata to be associated with the profiling entry
+     * @returns {Promise< T >} - A promise that resolves to the result of the executed function
      */
     runAsync<T>(fn: () => Promise<T>, meta?: Record<string, any>): Promise<T>;
     /**
      * Retrieves all profiler entries stored in the profiler.
      *
-     * @returns {ProfilerEntry<any>[]} - An array of profiler entries
+     * @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
+     * @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;
     };
@@ -123,7 +138,7 @@ export declare class Profiler {
      * Returns the services provided by the Profiler class.
      * This allows for easy access to the profiler's methods.
      *
-     * @returns {ProfilerService<any>} - An object containing methods to control the profiler
+     * @returns {ProfilerService< any >} - An object containing methods to control the profiler
      */
     services: ProfilerService<any>;
 }

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

@@ -12,44 +12,47 @@
  * @author Paul Köhler (komed3)
  * @license MIT
  */
-import type { RegistryService, RegistryConstructor } from './Types';
+import type { RegistryConstructor, RegistryService } from './Types';
 /**
  * Global registry object to hold multiple registries.
  * Each registry is keyed by a string identifier.
  *
- * @type {Record<string, RegistryService<any>>}
+ * @type {Record< string, RegistryService< any > >}
  */
 export declare const registry: Record<string, RegistryService<any>>;
 /**
  * Factory object to hold factory functions for creating instances.
  * This is used to create instances of registered classes.
  *
- * @type {Record<string, ( cls: string, ...args: any[] ) => InstanceType<any>>}
+ * @type {Record< string, ( cls: string, ...args: any[] ) => InstanceType< any > >}
  */
 export declare const factory: Record<string, (cls: string, ...args: any[]) => InstanceType<any>>;
 /**
  * Registry function to create a service for managing class constructors.
  *
+ * @template T - The basic type of all registry class constructors
  * @param {string} reg - The name of the registry
- * @param {RegistryConstructor<T>} ctor - The base constructor that all registered classes must extend
- * @returns {RegistryService<T>} - An object with methods to register, remove, check, get, and list classes
+ * @param {RegistryConstructor< T >} ctor - The base constructor that all registered classes must extend
+ * @returns {RegistryService< T >} - An object with methods to register, remove, check, get, and list classes
  * @throws {Error} If the registry already exists (overwriting is forbidden)
  */
 export declare function Registry<T>(reg: string, ctor: RegistryConstructor<T>): RegistryService<T>;
 /**
  * Resolve a class constructor from a specific registry.
  *
+ * @template T - Type of the registry class constructor
  * @param {string} reg - The name of the registry
- * @param {T|string} cls - The class itself or name of the class to resolve
- * @returns {T|undefined} - The class constructor if found, otherwise undefined
+ * @param {T | string} cls - The class itself or name of the class to resolve
+ * @returns {T | undefined} - The class constructor if found, otherwise undefined
  * @throws {ReferenceError} If the registry does not exist
  */
 export declare function resolveCls<T extends RegistryConstructor<any>>(reg: string, cls: T | string): T;
 /**
  * Create an instance of a class from a specific registry.
  *
+ * @template T - Type of the registry class constructor
  * @param {string} reg - The name of the registry
- * @param {T|string} cls - The class itself or name of the class to instantiate
+ * @param {T | string} cls - The class itself or name of the class to instantiate
  * @param {...any} args - Arguments to pass to the class constructor
  * @returns {T} - An instance of the class
  * @throws {Error} If the class cannot be instantiated