cmpstr 3.2.1 → 3.2.2

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

@@ -0,0 +1,137 @@
+/**
+ * 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';
+/**
+ * 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;
+    /** Optional cause (native JS Error chaining) */
+    readonly cause?: unknown;
+    /** 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);
+    /**
+     * Serialize the error into a plain object for JSON output.
+     */
+    toJSON(): CmpStrErrorJSON;
+    /**
+     * Pretty string representation of the error.
+     *
+     * @param {boolean} [stack=false] - Whether to include the stack trace in the output
+     */
+    toString(stack?: boolean): string;
+}
+/**
+ * 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 create(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

@@ -33,6 +33,7 @@ export declare class Filter {
      *
      * @param {FilterHooks} hook - The name of the hook
      * @returns {FilterFn} - The compiled filter function for the hook
+     * @throws {CmpStrInternalError} - Throws an error if the pipeline compilation fails
      */
     private static getPipeline;
     /**
@@ -52,6 +53,7 @@ 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;
     /**
@@ -92,6 +94,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 +104,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/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;
     /**
@@ -66,6 +67,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 {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[];
     /**
@@ -76,6 +78,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/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;
 }

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

@@ -35,7 +35,7 @@ export declare const factory: Record<string, (cls: string, ...args: any[]) => In
  * @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
- * @throws {Error} If the registry already exists (overwriting is forbidden)
+ * @throws {Error} - If the registry already exists (overwriting is forbidden)
  */
 export declare function Registry<T>(reg: string, ctor: RegistryConstructor<T>): RegistryService<T>;
 /**
@@ -45,7 +45,7 @@ export declare function Registry<T>(reg: string, ctor: RegistryConstructor<T>):
  * @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
- * @throws {ReferenceError} If the registry does not exist
+ * @throws {CmpStrNotFoundError} - If the registry or class does not exist
  */
 export declare function resolveCls<T extends RegistryConstructor<any>>(reg: string, cls: T | string): T;
 /**
@@ -56,6 +56,6 @@ export declare function resolveCls<T extends RegistryConstructor<any>>(reg: stri
  * @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
+ * @throws {CmpStrInternalError} - If instantiation fails due to an internal error
  */
 export declare function createFromRegistry<T extends RegistryConstructor<any>>(reg: string, cls: T | string, ...args: any[]): InstanceType<T>;

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

@@ -80,7 +80,7 @@ export declare class StructuredData<T = any, R = MetricRaw> {
      *
      * @param {any} results - The raw metric results
      * @returns {IndexedResult< R >[]} - Normalized results with indices
-     * @throws {TypeError} - If results format is unsupported
+     * @throws {CmpStrValidationError} - If the results format is unsupported
      */
     private normalizeResults;
     /**
@@ -121,6 +121,7 @@ export declare class StructuredData<T = any, R = MetricRaw> {
      * @param {string[]} extractedStrings - The extracted strings for index mapping
      * @param {StructuredDataOptions} [opt] - Additional options
      * @returns {StructuredDataBatchResult< T, R > | T[]} - The lookup results
+     * @throws {CmpStrUsageError} - If the lookup process fails
      */
     private performLookup;
     /**
@@ -130,6 +131,7 @@ export declare class StructuredData<T = any, R = MetricRaw> {
      * @param {string[]} extractedStrings - The extracted strings for index mapping
      * @param {StructuredDataOptions} [opt] - Additional options
      * @returns {Promise< StructuredDataBatchResult< T, R > | T[] >} - The async lookup results
+     * @throws {CmpStrUsageError} - If the async lookup process fails
      */
     private performLookupAsync;
     /**

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

@@ -14,6 +14,32 @@
  * @author Paul Köhler (komed3)
  * @license MIT
  */
+/**
+ * ================================================================================
+ * ERROR HANDLING
+ * ================================================================================
+ *
+ * Types for standardized error classes and structured error metadata.
+ */
+/**
+ * Metadata attached to a CmpStr error.
+ */
+export type CmpStrErrorMeta = Record<string, any> | undefined;
+/**
+ * Structured format for CmpStr errors when serialized to JSON.
+ */
+export interface CmpStrErrorJSON {
+    name: string;
+    code: string;
+    message: string;
+    meta?: CmpStrErrorMeta;
+    when: string;
+    cause?: {
+        name: string;
+        message: string;
+        stack?: string;
+    } | unknown;
+}
 /**
  * ================================================================================
  * PROFILER & POOL UTILITIES

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.1",
+  "version": "3.2.2",
   "author": {
     "name": "komed3 (Paul Köhler)",
     "email": "webmaster@komed3.de",
@@ -97,19 +97,19 @@
     "docs": "typedoc --logLevel Verbose --options typedoc.json"
   },
   "devDependencies": {
-    "@rollup/plugin-commonjs": "^29.0.0",
+    "@rollup/plugin-commonjs": "^29.0.2",
     "@rollup/plugin-node-resolve": "^16.0.3",
-    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-terser": "^1.0.0",
     "@rollup/plugin-typescript": "^12.3.0",
-    "@types/node": "^25.0.10",
+    "@types/node": "^25.4.0",
     "package-verify": "^1.0.3",
     "prettier": "^3.8.1",
-    "rollup": "^4.57.0",
+    "rollup": "^4.59.0",
     "rollup-plugin-cleanup": "^3.2.1",
     "rollup-plugin-prettier": "^4.1.2",
     "tslib": "^2.8.1",
-    "typedoc": "^0.28.16",
-    "typedoc-github-theme": "^0.3.1",
+    "typedoc": "^0.28.17",
+    "typedoc-github-theme": "^0.4.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   }