/** * Developer-friendly warning and error utilities for LadrillosJS. * * - Consistent prefix for easy filtering * - Component name and file context * - Code frame generation for templates * - Console styling for better readability * - Error codes with documentation links * * Bundle size optimization: * The global `__DEV__` constant is replaced at build time by the bundler. * All dev-only code wrapped in `if (__DEV__)` is completely eliminated * from production builds via dead code elimination. */ /** * Context information about the current component being processed. * This is set by the framework during component initialization. */ export interface ComponentContext { /** The component tag name (e.g., "my-counter") */ tagName?: string; /** The source file path (e.g., "components/counter.html") */ sourcePath?: string; /** The unique instance ID */ instanceId?: string; } /** * Set the current component context for error reporting. * Call this at the start of component initialization. */ export declare function setComponentContext(context: ComponentContext | null): void; /** * Get the current component context. */ export declare function getComponentContext(): ComponentContext | null; /** * Run a function with a specific component context. * Automatically restores previous context after execution. */ export declare function withComponentContext(context: ComponentContext, fn: () => T): T; /** * Async version of withComponentContext */ export declare function withComponentContextAsync(context: ComponentContext, fn: () => Promise): Promise; /** * Generate a code frame showing the error location in source code. * * @param source - The source code * @param start - Start position of the error * @param end - End position of the error * @returns Formatted code frame string */ export declare function generateCodeFrame(source: string, start?: number, end?: number): string; /** * Find the position of an expression in template source. */ export declare function findExpressionPosition(template: string, expression: string): { start: number; end: number; } | null; /** * Error codes for documentation linking */ export declare enum ErrorCode { EXPRESSION_EVAL_FAILED = 101, EXPRESSION_SYNTAX_ERROR = 102, EXPRESSION_UNDEFINED_VAR = 103, EXPRESSION_NULL_ACCESS = 104, SCRIPT_EXTRACT_FAILED = 201, SCRIPT_EXECUTION_FAILED = 202, EVENT_HANDLER_FAILED = 301, DIRECTIVE_ERROR = 401, LOOP_ERROR = 402, CONDITIONAL_ERROR = 403, COMPONENT_LOAD_FAILED = 501, COMPONENT_NOT_FOUND = 502, COMPONENT_ALREADY_REGISTERED = 503, INVALID_COMPONENT_PATH = 504, COMPONENT_REGISTRATION_FAILED = 505, INVALID_COMPONENT_NAME = 506, MODULE_LOAD_FAILED = 601, MODULE_EXECUTION_FAILED = 602 } /** * Get documentation URL for an error code */ export declare function getErrorDocsUrl(code: ErrorCode): string; export interface DiagnosticDetails { /** Stable code that links this diagnostic to the error reference. */ code: ErrorCode; /** A concise, concrete action the developer can take. */ hint?: string; } export declare class LadrillosError extends Error { readonly code: ErrorCode; readonly docsUrl: string; readonly componentContext: ComponentContext | null; readonly hint?: string; readonly diagnosticMessage: string; constructor(message: string, code: ErrorCode, options?: { context?: ComponentContext | null; hint?: string; cause?: unknown; }); } /** * Custom error handler signature. If registered via `configure({ onError })`, * framework errors are forwarded here in addition to being logged. */ export type LadrillosErrorHandler = (error: Error, context?: ComponentContext | null) => void; /** * Register (or clear) a custom error handler. Called by `configure()`. * Pass `null` to remove. */ export declare function setErrorHandler(handler: LadrillosErrorHandler | null): void; /** * Log a styled warning message (dev mode only). * Includes component context if available. */ export declare function warn(message: string, context?: ComponentContext | null, details?: DiagnosticDetails): void; /** * Log a styled error message. * Errors are always logged, even in production. * * If a custom error handler is registered via `configure({ onError })`, it is * also invoked so embedders can route framework errors to telemetry. */ export declare function error(message: string, context?: ComponentContext | null, cause?: unknown, details?: DiagnosticDetails): void; /** * Log an expression evaluation error with detailed context. * * This is the main function for reporting binding/expression errors. * It shows: * - The expression that failed * - The component where it occurred * - The actual JavaScript error * - A code frame if template source is available */ export declare function expressionError(expression: string, originalError: Error, options?: { context?: ComponentContext | null; template?: string; errorCode?: ErrorCode; }): void; /** * Log a script extraction error with context. */ export declare function scriptError(message: string, originalError: Error, context?: ComponentContext | null): void; /** * Create a formatted error for throwing with component context. */ export declare function createError(message: string, code: ErrorCode, context?: ComponentContext | null, hint?: string, cause?: unknown): LadrillosError; /** * Log a deprecation warning (only once per feature). */ export declare function deprecate(feature: string, replacement?: string, version?: string): void;