/**
 * 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>;
}