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

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

/**
 * This file was automatically generated by xBuild.
 * DO NOT EDIT MANUALLY.
 */

/**
 * Describes the origin of evaluated code referenced by a stack frame.
 *
 * @since 3.0.0
 */
interface EvalOriginInterface {
    /**
     * 1-based line number within the evaluated source, when available.
     * @since 3.0.0
     */
    line?: number;
    /**
     * 1-based column number within the evaluated source line, when available.
     * @since 3.0.0
     */
    column?: number;
    /**
     * File name associated with the evaluated source, when available.
     * @since 3.0.0
     */
    fileName?: string;
    /**
     * Function name associated with the evaluated source, when available.
     * @since 3.0.0
     */
    functionName?: string;
}
/**
 * Represents a stack frame in a stack trace.
 *
 * @remarks
 * This structure provides location and classification details about a single call site,
 * primarily used for diagnostics, stack analysis, and rendering stack traces in a structured form.
 *
 * @since 3.0.0
 */
interface StackFrameInterface {
    /**
     * The original frame text as provided by the runtime or parser.
     * @since 3.0.0
     */
    source: string;
    /**
     * 1-based line number within the source file, when available.
     * @since 3.0.0
     */
    line?: number;
    /**
     * 1-based column number within the source line, when available.
     * @since 3.0.0
     */
    column?: number;
    /**
     * File name for the call site, when available.
     * @since 3.0.0
     */
    fileName?: string;
    /**
     * Function name for the call site, when available.
     * @since 3.0.0
     */
    functionName?: string;
    /**
     * True when the frame originates from evaluated code (for example, `eval()`).
     * @since 3.0.0
     */
    eval: boolean;
    /**
     * True when the frame is part of an asynchronous call chain, when detectable.
     * @since 3.0.0
     */
    async: boolean;
    /**
     * True when the frame originates from native code execution.
     * @since 3.0.0
     */
    native: boolean;
    /**
     * True when the frame represents a constructor invocation.
     * @since 3.0.0
     */
    constructor: boolean;
    /**
     * Information about the evaluated code origin, when `eval` is true and the runtime provides it.
     * @see EvalOriginInterface
     * @since 3.0.0
     */
    evalOrigin?: EvalOriginInterface;
}
/**
 * Represents a fully parsed error stack trace with structured information.
 *
 * @remarks
 * `rawStack` preserves the original stack string for debugging and fallback rendering.
 *
 * @see StackFrameInterface
 * @since 2.1.0
 */
interface ParsedStackTraceInterface {
    /**
     * Error name (for example, `TypeError`).
     * @since 2.1.0
     */
    name: string;
    /**
     * Error message.
     * @since 2.1.0
     */
    message: string;
    /**
     * Parsed frames in call order.
     * @see StackFrameInterface
     * @since 2.1.0
     */
    stack: Array<StackFrameInterface>;
    /**
     * The raw stack string as received from the runtime.
     * @since 2.1.0
     */
    rawStack: string;
}
/**
 * Enumeration of JavaScript engines that can be detected from stack traces
 *
 * @since 2.1.0
 */
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
 */
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
 */
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 StackFrameInterface object with default null values
 *
 * @see ParsedStackTraceInterface
 * @see StackFrameInterface
 *
 * @since 2.1.0
 */
declare function createDefaultFrame(source: string): StackFrameInterface;
/**
 * 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
 */
declare function safeParseInt(value: string | undefined | null): number | undefined;
/**
 * Parses a V8 JavaScript engine stack trace line into a structured StackFrameInterface object
 *
 * @param line - The stack trace line to parse
 * @returns A StackFrameInterface 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 StackFrameInterface
 * @see createDefaultFrame
 *
 * @since 2.1.0
 */
declare function parseV8StackLine(line: string): StackFrameInterface;
/**
 * Parses a SpiderMonkey JavaScript engine stack trace line into a structured StackFrameInterface object
 *
 * @param line - The stack trace line to parse
 * @returns A StackFrameInterface 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 StackFrameInterface
 * @see createDefaultFrame
 *
 * @since 2.1.0
 */
declare function parseSpiderMonkeyStackLine(line: string): StackFrameInterface;
/**
 * Parses a JavaScriptCore engine stack trace line into a structured StackFrameInterface object
 *
 * @param line - The stack trace line to parse
 * @returns A StackFrameInterface 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 StackFrameInterface
 * @see createDefaultFrame
 *
 * @since 2.1.0
 */
declare function parseJavaScriptCoreStackLine(line: string): StackFrameInterface;
/**
 * 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 StackFrameInterface 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
 */
declare function parseStackLine(line: string, engine: JSEngines): StackFrameInterface;
/**
 * Extracts the stack frames from a full stack trace string, removing the error message line.
 *
 * @param stack - The full error stack string, possibly including the error message
 * @returns The stack trace starting from the first stack frame, or an empty string if no frames are found
 *
 * @remarks
 * This function scans the stack string for lines matching common stack frame formats,
 * including V8 (`at ...`) and SpiderMonkey/JavaScriptCore (`function@file:line:column`) patterns.
 * It returns only the portion of the stack that contains the frames, discarding the initial
 * error message or any non-stack lines.
 *
 * @example
 * ```ts
 * const stack = `
 * Error: Something went wrong
 *     at doSomething (file.js:10:15)
 *     at main (file.js:20:5)
 * `;
 *
 * console.log(getStackWithoutMessage(stack));
 * // Output:
 * // at doSomething (file.js:10:15)
 * // at main (file.js:20:5)
 * ```
 *
 * @since 4.0.1
 */
declare function getStackWithoutMessage(stack: string): string;
/**
 * Parses a complete error stack trace into a structured format
 *
 * @param error - Error object or error message string to parse
 * @returns A ParsedStackTraceInterface 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 StackFrameInterface objects
 * }
 * ```
 *
 * @see ParsedStackTraceInterface
 * @see StackFrameInterface
 * @see parseStackLine
 * @see detectJSEngine
 *
 * @since 2.1.0
 */
declare function parseErrorStack(error: Error | string): ParsedStackTraceInterface;

export {
	EvalOriginInterface,
	JSEngines,
	ParsedStackTraceInterface,
	StackFrameInterface,
	createDefaultFrame,
	detectJSEngine,
	getStackWithoutMessage,
	normalizePath,
	parseErrorStack,
	parseJavaScriptCoreStackLine,
	parseSpiderMonkeyStackLine,
	parseStackLine,
	parseV8StackLine,
	safeParseInt
};