import { DebugMessageOptions, LoggerElapsedLogOptions } from "../types/index.js";

//#region src/helper/elapsed.d.ts
/**
 * Creates a timer function that measures elapsed time from the moment of creation.
 *
 * Returns a function that, when called, returns an object containing the elapsed
 * time in milliseconds since the timer was created. This is useful for logging
 * operations with performance metrics.
 *
 * The timer uses high-resolution timing via `performance.now()` when available,
 * falling back to `Date.now()` for compatibility.
 *
 * @returns A function that returns elapsed time in milliseconds when called
 *
 * @example
 * ```ts
 * const timer = createElapsedTimer();
 *
 * // ... perform some operation ...
 *
 * logger.info('Operation completed', timer());
 * // Logs: "Operation completed" with elapsed time
 * ```
 */
declare const createElapsedTimer: () => (() => LoggerElapsedLogOptions);
//#endregion
//#region src/helper/debug-message.d.ts
/**
 * Formats debug message options into a standardized debug output string.
 *
 * This function creates a debug log message with the canonical format:
 * `context=... | decision=... | summary=... | timing=...`
 *
 * It sanitizes all input values to prevent excessively long output and ensures
 * complex objects are safely serialized for logging. Each field is validated
 * and formatted for readability.
 *
 * @param options - Debug message configuration
 * @param options.context - The context or phase of execution (e.g., "build phase")
 * @param options.decision - The conclusion or decision made (e.g., "skipping optimization")
 * @param options.summary - Optional data or object providing additional context
 * @param options.timingMs - Optional elapsed time in milliseconds
 * @returns A formatted debug message string ready for logging
 *
 * @example
 * ```ts
 * const message = formatDebugMessage({
 *   context: 'resolve dependencies',
 *   decision: 'using cached version',
 *   summary: { version: '1.2.3', cacheAge: 120 },
 *   timingMs: 45.5,
 * });
 * // Returns: "context=resolve dependencies | decision=using cached version | summary={...} | timing=45.50ms"
 * ```
 */
declare const formatDebugMessage: ({
  context,
  decision,
  summary,
  timingMs
}: DebugMessageOptions) => string;
//#endregion
//#region src/helper/error-message.d.ts
/**
 * Formats an error object or value into a readable error message string.
 *
 * This function safely extracts error messages from Error objects and converts
 * other values to strings. It handles edge cases like non-serializable objects
 * and ensures a fallback message is always returned.
 *
 * @param error - The error object or value to format
 * @returns A formatted error message string
 *
 * @example
 * ```ts
 * formatErrorMessage(new Error('Connection failed'));
 * // Returns: "Connection failed"
 *
 * formatErrorMessage('Invalid input');
 * // Returns: "Invalid input"
 * ```
 */
declare function formatErrorMessage(error: unknown): string;
//#endregion
export { createElapsedTimer, formatDebugMessage, formatErrorMessage };