cmpstr 3.2.1 → 3.3.0

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

@@ -2,71 +2,93 @@
  * Deep Merge Utility
  * src/utils/DeepMerge.ts
  *
- * This module provides utility functions for deep merging objects, getting values by path,
- * and setting values by path in a deeply nested object structure.
+ * This module provides the utility class `DeepMerge` for deep merging objects and
+ * manipulating nested properties using path strings. It allows you to get, set,
+ * check, and delete values at deeply nested paths within an object, as well as
+ * merge two objects together while preserving their structure.
  *
  * It supports dot and bracket notation (e.g. `a.b[0].c`) as well as escaped keys.
  *
- * Included functions:
- *  - `get`:   Retrieve a deeply nested value by path
- *  - `set`:   Assign a value to a nested path
- *  - `merge`: Deeply merge two objects
- *  - `has`:   Check whether a path exists
- *  - `rmv`:   Delete a value at a path
- *
  * @module Utils
  * @name DeepMerge
  * @author Paul Köhler
  * @license MIT
  */
 /**
- * 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} 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, fb?: R): R | undefined;
-/**
- * Check if a path exists in an object.
- *
- * @template T - The type of the object to get the value from
- * @param {T} t - The object to check
- * @param {string} path - The path string, e.g. `a.b.c`
- * @returns {boolean} - True if the path exists, otherwise false
- */
-export declare function has<T extends Record<string, any>>(t: T, path: string): boolean;
-/**
- * Deeply set a value in an object by a path string.
- *
- * @template T - The type of the object to get the value from
- * @param {T} t - The object to set the value in
- * @param {string} path - The path string, e.g. `a.b.c`
- * @param {any} value - The value to set at the specified path
- * @returns {T} - The modified object with the value set at the specified path
- * @throws {Error} - Throws an error if the key is not a valid identifier
- */
-export declare function set<T extends Record<string, any>>(t: T, path: string, value: any): T;
-/**
- * Deeply merge two objects, where the second object overrides the first.
- *
- * @template T - The type of the object to get the value from
- * @param {T} t - The target object to merge into
- * @param {T} o - The source object to merge from
- * @param {boolean} [mergeUndefined=false] - Whether to merge undefined values
- * @returns {T} - The merged object
- */
-export declare function merge<T extends Record<string, any>>(t?: T | undefined, o?: T | undefined, mergeUndefined?: boolean): T;
-/**
- * Delete a value at a specified path in an object.
- *
- * @template T - The type of the object to get the value from
- * @param {T} t - The object to delete the value from
- * @param {string} path - The path string, e.g. `a.b.c`
- * @param {boolean} [preserveEmpty=false] - Whether to preserve empty objects/arrays
- * @returns {T} - The modified object with the value deleted at the specified path
+ * DeepMerge class provides static methods for deep merging objects and
+ * manipulating nested properties using path strings.
  */
-export declare function rmv<T extends Record<string, any>>(t: T, path: string, preserveEmpty?: boolean): T;
+export declare class DeepMerge {
+    /** Regular expression to match bracket notation in paths */
+    private static readonly BRACKET_PATTERN;
+    /** Path cache for efficient parsing */
+    private static readonly PATH_CACHE;
+    /**
+     * Walk through an object using an array of keys and return
+     * whether the path exists and its value.
+     *
+     * @param {any} obj - The object to walk through
+     * @param {( string | number )[]} keys - An array of keys representing the path to walk
+     * @returns {{ exists: false } | { exists: true, value: any }} -
+     *      An object indicating whether the path exists and its value if it does
+     */
+    private static walk;
+    /**
+     * Parse a path string into an array of keys.
+     *
+     * @param {string} p - The path string, e.g. `a.b.c` or `a[0].b`
+     * @returns {( string | number )[]} - An array of keys, e.g. `['a', 'b', 'c']` or `['a', 0, 'b']`
+     */
+    static parse(p: string): (string | number)[];
+    /**
+     * Check if a path exists in an object.
+     *
+     * @template T - The type of the object to get the value from
+     * @param {T} t - The object to check
+     * @param {string} path - The path string, e.g. `a.b.c`
+     * @returns {boolean} - True if the path exists, otherwise false
+     */
+    static has<T extends Record<string, any>>(t: T, path: string): boolean;
+    /**
+     * 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} 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
+     */
+    static get<T extends Record<string, any>, R = any>(t: T, path: string, fb?: R): R | undefined;
+    /**
+     * Deeply set a value in an object by a path string.
+     *
+     * @template T - The type of the object to get the value from
+     * @param {T} t - The object to set the value in
+     * @param {string} path - The path string, e.g. `a.b.c`
+     * @param {any} value - The value to set at the specified path
+     * @returns {T} - The modified object with the value set at the specified path
+     * @throws {CmpStrUsageError} - If the path is invalid or if a non-object value is encountered along the path
+     */
+    static set<T extends Record<string, any>>(t: T, path: string, value: any): T;
+    /**
+     * Delete a value at a specified path in an object.
+     *
+     * @template T - The type of the object to get the value from
+     * @param {T} t - The object to delete the value from
+     * @param {string} path - The path string, e.g. `a.b.c`
+     * @param {boolean} [preserveEmpty=false] - Whether to preserve empty objects/arrays
+     * @returns {T} - The modified object with the value deleted at the specified path
+     */
+    static rmv<T extends Record<string, any>>(t: T, path: string, preserveEmpty?: boolean): T;
+    /**
+     * Deeply merge two objects, where the second object overrides the first.
+     *
+     * @template T - The type of the object to get the value from
+     * @param {T} t - The target object to merge into
+     * @param {T} o - The source object to merge from
+     * @param {boolean} [mergeUndefined=false] - Whether to merge undefined values
+     * @returns {T} - The merged object
+     */
+    static merge<T extends Record<string, any>>(t?: T | undefined, o?: T | undefined, mergeUndefined?: boolean): T;
+}

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

@@ -0,0 +1,154 @@
+/**
+ * Error Utilities
+ * src/utils/Errors.ts
+ *
+ * This module provides a small hierarchy of error classes and helper methods
+ * that standardize error creation and formatting across the CmpStr project.
+ * It improves on vanilla JavaScript errors by adding codes, structured metadata,
+ * and consistent `toString()` / `toJSON()` output while keeping the original
+ * message text intact.
+ *
+ * The error classes are designed to be lightweight and fast, while still
+ * providing useful context for debugging (including optional `cause` chaining).
+ *
+ * @module Utils
+ * @name Errors
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+import type { CmpStrErrorJSON, CmpStrErrorMeta } from './Types';
+/**
+ * Standardized error codes for CmpStr errors.
+ *
+ * These codes are used in the `code` field of `CmpStrError` instances to allow
+ * for easy programmatic handling of different error types without relying on
+ * string matching of messages or class names.
+ */
+export declare const enum ErrorCode {
+    VALIDATION = "E_VALIDATION",
+    NOT_FOUND = "E_NOT_FOUND",
+    USAGE = "E_USAGE",
+    INTERNAL = "E_INTERNAL"
+}
+/**
+ * Base error class for CmpStr.
+ *
+ * It provides a standard `code` field and a consistent `toString()` / `toJSON()`
+ * output without changing the original error message expectations.
+ */
+export declare class CmpStrError extends Error {
+    /** A short, machine-readable error code */
+    readonly code: string;
+    /** Optional structured metadata for the error */
+    readonly meta?: CmpStrErrorMeta;
+    /** Timestamp when the error was created (ISO 8601) */
+    readonly when: string;
+    /**
+     * Constructor for CmpStrError.
+     *
+     * Will construct an error with a code, message, optional metadata, and optional cause.
+     *
+     * @param {string} code - A short, machine-readable error code
+     * @param {string} message - The error message (human-readable)
+     * @param {CmpStrErrorMeta} [meta] - Optional structured metadata for the error
+     * @param {unknown} [cause] - Optional cause (native JS Error chaining)
+     */
+    constructor(code: string, message: string, meta?: CmpStrErrorMeta, cause?: unknown);
+    /**
+     * Format the error into a readable string, including code, message, and optional metadata.
+     *
+     * @param {boolean} [stack=false] - Whether to include the stack trace in the output
+     */
+    format(stack?: boolean): string;
+    /**
+     * Pretty string representation of the error.
+     */
+    toString(): string;
+    /**
+     * Serialize the error into a plain object for JSON output.
+     *
+     * @param {boolean} [stack=false] - Whether to include the stack trace in the JSON
+     */
+    toJSON(stack?: boolean): CmpStrErrorJSON;
+}
+/**
+ * Error thrown when user input (options, arguments) is invalid.
+ */
+export declare class CmpStrValidationError extends CmpStrError {
+    constructor(message: string, meta?: CmpStrErrorMeta, cause?: unknown);
+}
+/**
+ * Error thrown when a requested resource is missing or not found.
+ */
+export declare class CmpStrNotFoundError extends CmpStrError {
+    constructor(message: string, meta?: CmpStrErrorMeta, cause?: unknown);
+}
+/**
+ * Error thrown for incorrect usage or invalid state (assertions).
+ */
+export declare class CmpStrUsageError extends CmpStrError {
+    constructor(message: string, meta?: CmpStrErrorMeta, cause?: unknown);
+}
+/**
+ * Error thrown for internal failures that should not happen under normal usage.
+ */
+export declare class CmpStrInternalError extends CmpStrError {
+    constructor(message: string, meta?: CmpStrErrorMeta, cause?: unknown);
+}
+/**
+ * Helper utilities for throwing and formatting errors.
+ *
+ * Provides methods for asserting conditions, wrapping unknown errors, and formatting
+ * errors into readable strings. This centralizes error handling logic and ensures
+ * consistent error messages across the codebase.
+ */
+export declare class ErrorUtil {
+    /**
+     * Throw a `CmpStrUsageError` if a condition is not met.
+     *
+     * @param {boolean} condition - The condition to assert
+     * @param {string} message - The error message to throw if the condition is false
+     * @param {CmpStrErrorMeta} [meta] - Optional structured metadata for the error
+     * @throws {CmpStrUsageError} - If the condition is false
+     */
+    static assert(condition: boolean, message: string, meta?: CmpStrErrorMeta): asserts condition;
+    /**
+     * Wrap an unknown error into a `CmpStrInternalError`.
+     *
+     * @param {unknown} err - The error to wrap
+     * @param {string} message - The error message to use for the wrapped error
+     * @param {CmpStrErrorMeta} [meta] - Optional structured metadata for the error
+     * @throws {CmpStrInternalError} - Always throws a new `CmpStrInternalError` wrapping the original error
+     */
+    static rethrow(err: unknown, message: string, meta?: CmpStrErrorMeta): never;
+    /**
+     * Format any error into a readable string.
+     *
+     * @param {unknown} err - The error to format
+     * @returns {string} - A formatted string representation of the error
+     */
+    static format(err: unknown): string;
+    /**
+     * Execute a synchronous operation and wrap any exception as a `CmpStrInternalError`.
+     *
+     * This is used to avoid repeating try/catch blocks and to add consistent context
+     * to unexpected failures while preserving the original error as `cause`.
+     *
+     * @param {() => T} fn - The function to execute
+     * @param {string} message - The error message to use if an exception is thrown
+     * @param {CmpStrErrorMeta} [meta] - Optional structured metadata for the error
+     * @return {T} The result of the function if it executes successfully
+     * @throws {CmpStrInternalError} - If the function throws an error, it will be wrapped and re-thrown as a `CmpStrInternalError`
+     */
+    static wrap<T>(fn: () => T, message: string, meta?: CmpStrErrorMeta): T;
+    /**
+     * Execute an asynchronous operation and wrap any exception as a `CmpStrInternalError`.
+     *
+     * @param {() => Promise< T >} fn - The asynchronous function to execute
+     * @param {string} message - The error message to use if an exception is thrown
+     * @param {CmpStrErrorMeta} [meta] - Optional structured metadata for the error
+     * @return {Promise< T >} A promise that resolves to the result of the function if it executes successfully
+     * @throws {CmpStrInternalError} - If the function throws an error, it will be wrapped and re-thrown as a `CmpStrInternalError`
+     */
+    static wrapAsync<T>(fn: () => Promise<T>, message: string, meta?: CmpStrErrorMeta): Promise<T>;
+}

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

@@ -17,6 +17,8 @@ import type { FilterFn, FilterHooks, FilterOptions } from './Types';
  * The Filter class provides a way to manage and apply filters to strings based on hooks.
  */
 export declare class Filter {
+    /** Filter function that returns the input string unchanged */
+    private static readonly IDENTITY;
     /**
      * A static map to hold all filters.
      * The key is the hook name, and the value is an Map of FilterEntry objects.
@@ -32,7 +34,9 @@ export declare class Filter {
      * If the function is not cached, it compiles it from the active filters.
      *
      * @param {FilterHooks} hook - The name of the hook
+     * @param {boolean} [force=false] - If true, forces recompilation of the pipeline even if it is cached
      * @returns {FilterFn} - The compiled filter function for the hook
+     * @throws {CmpStrInternalError} - Throws an error if the pipeline compilation fails
      */
     private static getPipeline;
     /**
@@ -52,10 +56,11 @@ export declare class Filter {
      * @param {FilterOptions} [opt] - Additional options for the filter
      * @returns {boolean} - Returns true if the filter was added,
      *                      false if it was not added due to override restrictions
+     * @throws {CmpStrInternalError} - Throws an error if there is an issue adding the filter
      */
     static add(hook: FilterHooks, id: string, fn: FilterFn, opt?: FilterOptions): boolean;
     /**
-     * Removes a filter by its hook and id.
+     * Removes a filter from the specified hook by its id.
      *
      * @param {FilterHooks} hook - The name of the hook
      * @param {string} id - The id of the filter
@@ -92,6 +97,7 @@ export declare class Filter {
      * @param {FilterHooks} hook - The name of the hook
      * @param {string | string[]} input - The input string(s) to be filtered
      * @returns {string | string[]} - The filtered string(s)
+     * @throws {CmpStrInternalError} - Throws an error if there is an issue applying the filters
      */
     static apply(hook: FilterHooks, input: string | string[]): string | string[];
     /**
@@ -101,6 +107,7 @@ export declare class Filter {
      * @param {FilterHooks} 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)
+     * @throws {CmpStrInternalError} - Throws an error if there is an issue applying the filters
      */
     static applyAsync(hook: FilterHooks, input: string | string[]): Promise<string | string[]>;
     /**

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

@@ -48,11 +48,10 @@ export declare class Hasher {
  * @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;
+    private readonly FIFO;
+    private readonly maxSize;
     /** 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.
      * The key is a string generated from the label and any number of hashed strings.
@@ -62,9 +61,10 @@ export declare class HashTable<K extends string, T> {
     /**
      * Creates an instance of HashTable.
      *
-     * @param {boolean} [LRU=true] - Whether to use Least Recently Used (LRU) eviction policy
+     * @param {boolean} [FIFO=true] - Whether to use FIFO eviction (true) when the table is full
+     * @param {number} [maxSize=10000] - The maximum number of entries in the hash table
      */
-    constructor(LRU?: boolean);
+    constructor(FIFO?: boolean, maxSize?: number);
     /**
      * Generates a unique hash key for any number of string arguments.
      * Return false if any string exceeds the maximum length.
@@ -82,17 +82,18 @@ 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
      */
-    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).
+     * If the table is full, it evicts the least recently used entry
+     * (if FIFO is enabled) or returns false.
      *
      * @param {string} key - The hashed key for the entry
      * @param {T} entry - The entry itself to add
@@ -106,16 +107,16 @@ export declare class HashTable<K extends string, T> {
      * @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) => boolean;
+    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

@@ -57,6 +57,7 @@ export declare class Normalizer {
      *
      * @param {NormalizeFlags} flags - A string of characters representing the normalization steps
      * @returns {NormalizerFn} - A function that normalizes a string based on the provided flags
+     * @throws {CmpStrInternalError} - Throws an error if the pipeline creation fails
      */
     private static getPipeline;
     /**
@@ -65,9 +66,11 @@ export declare class Normalizer {
      *
      * @param {string | string[]} input - The string or array of strings to normalize
      * @param {NormalizeFlags} flags - A string of characters representing the normalization steps
+     * @param {NormalizeFlags} [normalizedFlags] - Optional pre-canonicalized flags to avoid redundant canonicalization
      * @returns {string | string[]} - The normalized string(s)
+     * @throws {CmpStrInternalError} - Throws an error if the normalization process fails
      */
-    static normalize(input: string | string[], flags: NormalizeFlags): string | string[];
+    static normalize(input: string | string[], flags: NormalizeFlags, normalizedFlags?: NormalizeFlags): string | string[];
     /**
      * Asynchronously normalizes the input string or array of strings based on the
      * provided flags. This method is useful for handling large inputs or when
@@ -76,6 +79,7 @@ export declare class Normalizer {
      * @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)
+     * @throws {CmpStrInternalError} - Throws an error if the normalization process fails
      */
     static normalizeAsync(input: string | string[], flags: NormalizeFlags): Promise<string | string[]>;
     /**

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/Pool.d.ts

@@ -44,6 +44,7 @@ export declare class Pool {
      * @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
+     * @throws {CmpStrUsageError} - Throws an error if the pool type is unsupported
      */
     static acquire<T = any>(type: PoolType, size: number): T;
     /**
@@ -61,6 +62,7 @@ export declare class Pool {
      * @param {PoolType} type - The type of buffer to release
      * @param {T} buffer - The buffer to release
      * @param {number} size - The size of the buffer
+     * @throws {CmpStrUsageError} - Throws an error if the pool type is unsupported
      */
     static release<T = any>(type: PoolType, buffer: T, size: number): void;
 }