@remotex-labs/xmap/dist/parser.component.d.ts

A library with a sourcemap parser and TypeScript code formatter for the CLI

/**
 * Interface representing a stack frame in a stack trace.
 *
 * This structure provides detailed information about the location
 * of a specific frame in the stack trace, primarily used in error debugging and stack analysis.
 * It optionally includes information about the line, column, file, function name, and other details
 * about the origin of the code.
 *
 * Properties:
 * - source: The source code relevant to the stack frame.
 * - line: An optional line number in the code associated with this frame.
 * - column: An optional column number in the line associated with this frame.
 * - fileName: The name of the file associated with the frame, if available.
 * - functionName: The name of the function where the stack frame is located, if available.
 * - eval: Indicates if the stack frame originates from an evaluated script.
 * - async: Indicates if the stack frame is part of an asynchronous operation.
 * - native: Indicates if the stack frame is part of native code execution.
 * - constructor: Indicates if the frame is related to an object constructor invocation.
 * - evalOrigin: Optional information about the origin of the code if it resulted from an eval execution,
 * including line number, column number, file name, and function name.
 *
 * @since 3.0.0
 */
export interface StackFrame {
    source: string;
    line?: number;
    column?: number;
    fileName?: string;
    functionName?: string;
    eval: boolean;
    async: boolean;
    native: boolean;
    constructor: boolean;
    evalOrigin?: {
        line?: number;
        column?: number;
        fileName?: string;
        functionName?: string;
    };
}
/**
 * Represents a fully parsed error stack trace with structured information
 *
 * @see StackFrame
 * @since 2.1.0
 */
export interface ParsedStackTrace {
    name: string;
    message: string;
    stack: StackFrame[];
    rawStack: string;
}
/**
 * Enumeration of JavaScript engines that can be detected from stack traces
 *
 * @since 2.1.0
 */
export declare const enum JSEngines {
    V8 = 0,
    SPIDERMONKEY = 1,
    JAVASCRIPT_CORE = 2,
    UNKNOWN = 3
}
/**
 * Detects the JavaScript engine based on the format of a stack trace line
 *
 * @param stack - The stack trace to analyze
 * @returns The identified JavaScript engine type
 *
 * @example
 * ```ts
 * const engine = detectJSEngine("at functionName (/path/to/file.js:10:15)");
 * if (engine === JSEngines.V8) {
 *   // Handle V8 specific logic
 * }
 * ```
 *
 * @since 2.1.0
 */
export declare function detectJSEngine(stack: string): JSEngines;
/**
 * Normalizes file paths from various formats to a standard format
 *
 * @param filePath - The file path to normalize, which may include protocol prefixes
 * @returns A normalized file path with consistent separators and without protocol prefixes
 *
 * @remarks
 * Handles both Windows and Unix-style paths, as well as file:// protocol URLs.
 * Converts all backslashes to forward slashes for consistency.
 *
 * @example
 * ```ts
 * // Windows file URL to a normal path
 * normalizePath("file:///C:/path/to/file.js"); // "C:/path/to/file.js"
 *
 * // Unix file URL to a normal path
 * normalizePath("file:///path/to/file.js"); // "/path/to/file.js"
 *
 * // Windows backslashes to forward slashes
 * normalizePath("C:\\path\\to\\file.js"); // "C:/path/to/file.js"
 * ```
 *
 * @since 2.1.0
 */
export declare function normalizePath(filePath: string): string;
/**
 * Creates a default stack frame object with initial values
 *
 * @param source - The original source line from the stack trace
 * @returns A new StackFrame object with default null values
 *
 * @see ParsedStackTrace
 * @see StackFrame
 *
 * @since 2.1.0
 */
export declare function createDefaultFrame(source: string): StackFrame;
/**
 * Safely parses a string value to an integer, handling undefined and null cases
 *
 * @param value - The string value to parse
 * @returns The parsed integer or null if the input is undefined/null
 *
 * @example
 * ```ts
 * safeParseInt("42"); // 42
 * safeParseInt(undefined); // null
 * safeParseInt(null); // null
 * ```
 *
 * @since 2.1.0
 */
export declare function safeParseInt(value: string | undefined | null): number | undefined;
/**
 * Parses a V8 JavaScript engine stack trace line into a structured StackFrame object
 *
 * @param line - The stack trace line to parse
 * @returns A StackFrame object containing the parsed information
 *
 * @remarks
 * Handles both standard V8 stack frames and eval-generated stack frames which
 * have a more complex structure with nested origin information.
 *
 * @example
 * ```ts
 * // Standard frame
 * parseV8StackLine("at functionName (/path/to/file.js:10:15)");
 *
 * // Eval frame
 * parseV8StackLine("at eval (eval at evalFn (/source.js:5:10), <anonymous>:1:5)");
 * ```
 *
 * @throws Error - If the line format doesn't match any known V8 pattern
 *
 * @see StackFrame
 * @see createDefaultFrame
 *
 * @since 2.1.0
 */
export declare function parseV8StackLine(line: string): StackFrame;
/**
 * Parses a SpiderMonkey JavaScript engine stack trace line into a structured StackFrame object
 *
 * @param line - The stack trace line to parse
 * @returns A StackFrame object containing the parsed information
 *
 * @remarks
 * Handles both standard SpiderMonkey stack frames and eval/Function-generated stack frames
 * which contain additional evaluation context information.
 *
 * @example
 * ```ts
 * // Standard frame
 * parseSpiderMonkeyStackLine("functionName@/path/to/file.js:10:15");
 *
 * // Eval frame
 * parseSpiderMonkeyStackLine("evalFn@/source.js line 5 > eval:1:5");
 * ```
 *
 * @see StackFrame
 * @see createDefaultFrame
 *
 * @since 2.1.0
 */
export declare function parseSpiderMonkeyStackLine(line: string): StackFrame;
/**
 * Parses a JavaScriptCore engine stack trace line into a structured StackFrame object
 *
 * @param line - The stack trace line to parse
 * @returns A StackFrame object containing the parsed information
 *
 * @remarks
 * Handles both standard JavaScriptCore stack frames and eval-generated stack frames.
 * Special handling is provided for "global code" references and native code.
 *
 * @example
 * ```ts
 * // Standard frame
 * parseJavaScriptCoreStackLine("functionName@/path/to/file.js:10:15");
 *
 * // Eval frame
 * parseJavaScriptCoreStackLine("eval code@");
 * ```
 *
 * @see StackFrame
 * @see createDefaultFrame
 *
 * @since 2.1.0
 */
export declare function parseJavaScriptCoreStackLine(line: string): StackFrame;
/**
 * Parses a stack trace line based on the detected JavaScript engine
 *
 * @param line - The stack trace line to parse
 * @param engine - The JavaScript engine type that generated the stack trace
 * @returns A StackFrame object containing the parsed information
 *
 * @remarks
 * Delegates to the appropriate parsing function based on the JavaScript engine.
 * Defaults to V8 parsing if the engine is unknown.
 *
 * @example
 * ```ts
 * const engine = detectJSEngine(stackLine);
 * const frame = parseStackLine(stackLine, engine);
 * ```
 *
 * @see JSEngines
 * @see parseV8StackLine
 * @see parseSpiderMonkeyStackLine
 * @see parseJavaScriptCoreStackLine
 *
 * @since 2.1.0
 */
export declare function parseStackLine(line: string, engine: JSEngines): StackFrame;
/**
 * Parses a complete error stack trace into a structured format
 *
 * @param error - Error object or error message string to parse
 * @returns A ParsedStackTrace object containing structured stack trace information
 *
 * @remarks
 * Automatically detects the JavaScript engine from the stack format.
 * Filters out redundant information like the error name/message line.
 * Handles both Error objects and string error messages.
 *
 * @example
 * ```ts
 * try {
 *   throw new Error ("Something went wrong");
 * } catch (error) {
 *   const parsedStack = parseErrorStack(error);
 *   console.log(parsedStack.name); // "Error"
 *   console.log(parsedStack.message); // "Something went wrong"
 *   console.log(parsedStack.stack); // Array of StackFrame objects
 * }
 * ```
 *
 * @see ParsedStackTrace
 * @see StackFrame
 * @see parseStackLine
 * @see detectJSEngine
 *
 * @since 2.1.0
 */
export declare function parseErrorStack(error: Error | string): ParsedStackTrace;