@remotex-labs/xmap 3.0.3 → 3.0.4

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import type * as ts from "typescript";
 /**
  * Represents a source map structure used for mapping code within a file to its original source
  * @since 1.0.0
@@ -162,7 +163,7 @@ export interface SourceOptionsInterface {
  *
  * @since 1.0.0
  */
-export function encodeVLQ(value: number): string;
+export declare function encodeVLQ(value: number): string;
 /**
  * Encodes an array of numbers using VLQ encoding by individually encoding each number and concatenating the results.
  *
@@ -179,7 +180,7 @@ export function encodeVLQ(value: number): string;
  *
  * @since 1.0.0
  */
-export function encodeArrayVLQ(values: number[]): string;
+export declare function encodeArrayVLQ(values: number[]): string;
 /**
  * Decodes a VLQ encoded string back into an array of numbers by processing Base64 characters and continuation bits.
  *
@@ -206,7 +207,7 @@ export function encodeArrayVLQ(values: number[]): string;
  *
  * @since 1.0.0
  */
-export function decodeVLQ(data: string): number[];
+export declare function decodeVLQ(data: string): number[];
 /**
  * Represents a source map mapping segment that links positions between original and generated code.
  *
@@ -296,7 +297,7 @@ export interface SegmentOffsetInterface extends SegmentInterface {
  *
  * @since 1.0.0
  */
-export const enum Bias {
+export declare const enum Bias {
     BOUND = 0,
     LOWER_BOUND = 1,
     UPPER_BOUND = 2
@@ -373,7 +374,7 @@ export type MapType = Array<null | FrameType>;
  *
  * @since 1.0.0
  */
-export class MappingProvider {
+export declare class MappingProvider {
     private mapping;
     /**
      * Creates a new MappingProvider instance.
@@ -674,7 +675,7 @@ export class MappingProvider {
  *
  * @since 1.0.0
  */
-export class SourceService {
+export declare class SourceService {
     /**
      * The name of the generated file this source map applies to.
      *
@@ -864,3 +865,810 @@ export class SourceService {
      */
     private validateSourceMap;
 }
+/**
+ * A callback function for formatting code lines
+ *
+ * @param lineString - The content of the line to be formatted
+ * @param padding - The amount of padding to be applied to the line
+ * @param line - The line number of the line to be formatted
+ * @returns Formatted line string
+ *
+ * @since 1.0.0
+ */
+export type FormatCodeCallbackType = (lineString: string, padding: number, line: number) => string;
+/**
+ * Configuration options for formatting code
+ *
+ * @since 1.0.0
+ */
+export interface FormatCodeInterface {
+    /**
+     * The amount of padding to be applied to each line
+     * @since 1.0.0
+     */
+    padding?: number;
+    /**
+     * The starting line number for formatting
+     * @since 1.0.0
+     */
+    startLine?: number;
+    /**
+     * An optional action object specifying a line where a callback function should be triggered.
+     * @since 1.0.0
+     */
+    action?: {
+        /**
+         * The line number at which the callback function should be triggered.
+         * @since 1.0.0
+         */
+        triggerLine: number;
+        /**
+         * The callback function to be executed when the trigger line is encountered.
+         * @since 1.0.0
+         */
+        callback: FormatCodeCallbackType;
+    };
+}
+/**
+ * Configuration for ANSI color styling of error pointers
+ * @since 1.0.0
+ */
+export interface AnsiOptionInterface {
+    /**
+     * ANSI color code to apply to the error pointer
+     * @since 1.0.0
+     */
+    color: string;
+    /**
+     * ANSI reset code to restore default styling after the error pointer
+     * @since 1.0.0
+     */
+    reset: string;
+}
+/**
+ * Formats a code snippet with optional line padding and custom actions
+ *
+ * @param code - The source code | stack to be formatted
+ * @param options - Configuration options for formatting the code
+ * @returns A formatted string of the code snippet with applied padding and custom actions
+ *
+ * @remarks
+ * This function takes a code string and an options object to format the code snippet.
+ * It applies padding to line numbers and can trigger custom actions for specific lines.
+ * Options include padding (default 10), startLine (default 0), and custom actions for specific lines.
+ *
+ * @example
+ * ```ts
+ * const formattedCode = formatCode(code, {
+ *     padding: 8,
+ *     startLine: 5,
+ *     action: {
+ *         triggerLine: 7,
+ *         callback: (lineString, padding, lineNumber) => {
+ *             return `Custom formatting for line ${lineNumber}: ${lineString}`;
+ *         }
+ *     }
+ * });
+ * ```
+ *
+ * @since 1.0.0
+ */
+export declare function formatCode(code: string, options?: FormatCodeInterface): string;
+/**
+ * Formats a code snippet around an error location with special highlighting
+ *
+ * @param sourcePosition - An object containing information about the source code and error location
+ * @param ansiOption - Optional configuration for ANSI color codes
+ * @returns A formatted string representing the relevant code snippet with error highlighting
+ *
+ * @throws Error - If the provided sourcePosition object has invalid line or column numbers
+ *
+ * @remarks
+ * This function takes a sourcePosition object with code content and error location information,
+ * then uses formatCode to format and highlight the relevant code snippet around the error.
+ * The sourcePosition object should contain code (string), line (number), column (number),
+ * and optional startLine (number, defaults to 1).
+ *
+ * @example
+ * ```ts
+ * const formattedErrorCode = formatErrorCode({
+ *     code: "const x = 1;\nconst y = x.undefined;\n",
+ *     line: 2,
+ *     column: 15,
+ *     startLine: 1
+ * });
+ * ```
+ *
+ * @see formatCode - The underlying function used for basic code formatting
+ *
+ * @since 1.0.0
+ */
+export declare function formatErrorCode(sourcePosition: PositionWithCodeInterface, ansiOption?: AnsiOptionInterface): string;
+/**
+ * Defines the color scheme for syntax highlighting different code elements.
+ *
+ * @interface HighlightSchemeInterface
+ *
+ * @property enumColor - Color code for enum declarations and references
+ * @property typeColor - Color code for type annotations and primitive types
+ * @property classColor - Color code for class declarations and references
+ * @property stringColor - Color code for string literals and template strings
+ * @property keywordColor - Color code for language keywords
+ * @property commentColor - Color code for comments (single-line and multi-line)
+ * @property functionColor - Color code for function declarations and calls
+ * @property variableColor - Color code for variable declarations and references
+ * @property interfaceColor - Color code for interface declarations and references
+ * @property parameterColor - Color code for function and method parameters
+ * @property getAccessorColor - Color code for getter accessor methods
+ * @property numericLiteralColor - Color code for numeric literals
+ * @property methodSignatureColor - Color code for method signatures in interfaces
+ * @property regularExpressionColor - Color code for regular expression literals
+ * @property propertyAssignmentColor - Color code for property assignments in object literals
+ * @property propertyAccessExpressionColor - Color code for property access expressions
+ * @property expressionWithTypeArgumentsColor - Color code for type arguments in expressions
+ *
+ * @example
+ * ```ts
+ * const darkTheme: HighlightSchemeInterface = {
+ *   enumColor: Colors.cyan,
+ *   typeColor: Colors.blue,
+ *   classColor: Colors.yellow,
+ *   // ...other color definitions
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ */
+export interface HighlightSchemeInterface {
+    enumColor: string;
+    typeColor: string;
+    classColor: string;
+    stringColor: string;
+    keywordColor: string;
+    commentColor: string;
+    functionColor: string;
+    variableColor: string;
+    interfaceColor: string;
+    parameterColor: string;
+    getAccessorColor: string;
+    numericLiteralColor: string;
+    methodSignatureColor: string;
+    regularExpressionColor: string;
+    propertyAssignmentColor: string;
+    propertyAccessExpressionColor: string;
+    expressionWithTypeArgumentsColor: string;
+}
+/**
+ * Represents a segment of source code to be highlighted with specific styling.
+ *
+ * @interface HighlightNodeSegmentInterface
+ *
+ * @property start - The starting character position of the segment in the source text
+ * @property end - The ending character position of the segment in the source text
+ * @property color - The color or style code to apply to this segment
+ * @property reset - The reset code that returns formatting to normal after this segment
+ *
+ * @remarks
+ * Segments are the fundamental units of the highlighting system.
+ * Each segment represents a portion of text that should receive specific styling.
+ * When the source code is processed for display,
+ * these segments are used to insert the appropriate color/style codes at the correct positions.
+ *
+ * The highlighter maintains a collection of these segments and applies them
+ * in position order to create the complete highlighted output.
+ *
+ * @example
+ * ```ts
+ * const keywordSegment: HighlightNodeSegmentInterface = {
+ *   start: 0,
+ *   end: 6,
+ *   color: '\x1b[34m', // Blue for the keyword "import"
+ *   reset: '\x1b[0m'   // Reset to default
+ * };
+ * ```
+ *
+ * @see HighlightSchemeInterface
+ * @see addSegment
+ *
+ * @since 1.0.0
+ */
+export interface HighlightNodeSegmentInterface {
+    end: number;
+    start: number;
+    color: string;
+    reset: string;
+}
+/**
+ * An enum containing ANSI escape sequences for various colors
+ *
+ * @remarks
+ * This enum is primarily intended for terminal output and won't work directly in JavaScript for web development.
+ * It defines color codes for various colors and a reset code to return to the default text color.
+ *
+ * @example
+ * ```ts
+ * console.log(`${Colors.red}This text will be red in the terminal.${Colors.reset}`);
+ * ```
+ *
+ * @since 1.0.0
+ */
+export declare const enum Colors {
+    reset = "\u001B[0m",
+    gray = "\u001B[38;5;243m",
+    darkGray = "\u001B[38;5;238m",
+    lightCoral = "\u001B[38;5;203m",
+    lightOrange = "\u001B[38;5;215m",
+    oliveGreen = "\u001B[38;5;149m",
+    burntOrange = "\u001B[38;5;208m",
+    lightGoldenrodYellow = "\u001B[38;5;221m",
+    lightYellow = "\u001B[38;5;230m",
+    canaryYellow = "\u001B[38;5;227m",
+    deepOrange = "\u001B[38;5;166m",
+    lightGray = "\u001B[38;5;252m",
+    brightPink = "\u001B[38;5;197m"
+}
+/**
+ * Class responsible for applying semantic highlighting to a source code string based on a given color scheme
+ *
+ * @remarks
+ * Processes TypeScript AST nodes and applies color formatting to different code elements
+ * according to the provided color scheme.
+ *
+ * @example
+ * ```ts
+ * const sourceFile = ts.createSourceFile('example.ts', code, ts.ScriptTarget.Latest);
+ * const highlighter = new CodeHighlighter(sourceFile, code, customScheme);
+ * highlighter.parseNode(sourceFile);
+ * const highlightedCode = highlighter.highlight();
+ * ```
+ *
+ * @since 1.0.0
+ */
+export declare class CodeHighlighter {
+    private sourceFile;
+    private code;
+    private schema;
+    /**
+     * A Map of segments where the key is a combination of start and end positions.
+     *
+     * @remarks
+     * This structure ensures unique segments and allows for fast lookups and updates.
+     *
+     * @see HighlightNodeSegmentInterface
+     * @since 1.0.0
+     */
+    private segments;
+    /**
+     * Creates an instance of the CodeHighlighter class.
+     *
+     * @param sourceFile - The TypeScript AST node representing the source file
+     * @param code - The source code string to be highlighted
+     * @param schema - The color scheme used for highlighting different elements in the code
+     *
+     * @since 1.0.0
+     */
+    constructor(sourceFile: ts.Node, code: string, schema: HighlightSchemeInterface);
+    /**
+     * Parses a TypeScript AST node and processes its comments to identify segments that need highlighting.
+     *
+     * @param node - The TypeScript AST node to be parsed
+     *
+     * @since 1.0.0
+     */
+    parseNode(node: ts.Node): void;
+    /**
+     * Generates a string with highlighted code segments based on the provided color scheme.
+     *
+     * @returns The highlighted code as a string, with ANSI color codes applied to the segments
+     *
+     * @remarks
+     * This method processes the stored segments, applies the appropriate colors to each segment,
+     * and returns the resulting highlighted code as a single string.
+     *
+     * @since 1.0.0
+     */
+    highlight(): string;
+    /**
+     * Extracts a text segment from the source code using position indices.
+     *
+     * @param start - The starting index position in the source text
+     * @param end - The ending index position in the source text (optional)
+     * @returns The substring of source text between the start and end positions
+     *
+     * @remarks
+     * This utility method provides access to specific portions of the source code
+     * based on character positions. When the end parameter is omitted, the extraction
+     * will continue to the end of the source text.
+     *
+     * This method is typically used during the highlighting process to access the
+     * actual text content that corresponds to syntax nodes or other text ranges
+     * before applying formatting.
+     *
+     * @example
+     * ```ts
+     * // Extract a variable name
+     * const variableName = this.getSegmentSource(10, 15);
+     *
+     * // Extract from a position to the end of source
+     * const remaining = this.getSegmentSource(100);
+     * ```
+     *
+     * @see addSegment
+     * @see highlight
+     *
+     * @since 1.0.0
+     */
+    private getSegmentSource;
+    /**
+     * Registers a text segment for syntax highlighting with specified style information.
+     *
+     * @param start - The starting position of the segment in the source text
+     * @param end - The ending position of the segment in the source text
+     * @param color - The color code to apply to this segment
+     * @param reset - The color reset code to apply after the segment (defaults to the standard reset code)
+     *
+     * @remarks
+     * This method creates a unique key for each segment based on its position and stores the segment information in a map.
+     * Each segment contains its position information, styling code,
+     * and reset code which will later be used during the highlighting process.
+     *
+     * If multiple segments are added with the same positions, the later additions will
+     * overwrite earlier ones due to the map's key-based storage.
+     *
+     * @example
+     * ```ts
+     * // Highlight a variable name in red
+     * this.addSegment(10, 15, Colors.red);
+     *
+     * // Highlight a keyword with custom color and reset
+     * this.addSegment(20, 26, Colors.blue, Colors.customReset);
+     * ```
+     *
+     * @see Colors
+     * @see processNode
+     *
+     * @since 1.0.0
+     */
+    private addSegment;
+    /**
+     * Processes and highlights comments associated with a TypeScript AST node.
+     *
+     * @param node - The TypeScript AST node whose comments are to be processed
+     *
+     * @remarks
+     * This method identifies both leading and trailing comments associated with the given node
+     * and adds them to the highlighting segments.
+     * The comments are extracted from the full source text using TypeScript's utility functions
+     * and are highlighted using the color specified
+     * in the schema's commentColor property.
+     *
+     * Leading comments appear before the node, while trailing comments appear after it.
+     * Both types are processed with the same highlighting style.
+     *
+     * @example
+     * ```ts
+     * // For a node that might have comments like:
+     * // This is a leading comment
+     * const x = 5; // This is a trailing comment
+     *
+     * this.processComments(someNode);
+     * // Both comments will be added to segments with the comment color
+     * ```
+     *
+     * @see addSegment
+     * @see ts.getLeadingCommentRanges
+     * @see ts.getTrailingCommentRanges
+     *
+     * @since 1.0.0
+     */
+    private processComments;
+    /**
+     * Processes TypeScript keywords and primitive type references in an AST node for syntax highlighting.
+     *
+     * @param node - The TypeScript AST node to be processed for keywords
+     *
+     * @remarks
+     * This method handles two categories of tokens that require special highlighting:
+     *
+     * 1. Primitive type references: Highlights references to built-in types like `null`,
+     *    `void`, `string`, `number`, `boolean`, and `undefined` using the type color.
+     *
+     * 2. TypeScript keywords: Identifies any node whose kind falls within the TypeScript
+     *    keyword range (between FirstKeyword and LastKeyword) and highlights it using
+     *    the keyword color.
+     *
+     * Each identified token is added to the segments collection with appropriate position
+     * and color information.
+     *
+     * @example
+     * ```ts
+     * // Inside syntax highlighting process
+     * this.processKeywords(someNode);
+     * // If the node represents a keyword like 'const' or a primitive type like 'string',
+     * // it will be added to the segments with the appropriate color
+     * ```
+     *
+     * @see addSegment
+     * @see ts.SyntaxKind
+     *
+     * @since 1.0.0
+     */
+    private processKeywords;
+    /**
+     * Processes identifier nodes and applies appropriate syntax highlighting based on their context.
+     *
+     * @param node - The TypeScript AST node representing the identifier to be processed
+     *
+     * @remarks
+     * This method determines the appropriate color for an identifier by examining its parent node's kind.
+     * Different colors are applied based on the identifier's role in the code:
+     * - Enum members use enumColor
+     * - Interface names use interfaceColor
+     * - Class names use classColor
+     * - Function and method names use functionColor
+     * - Parameters use parameterColor
+     * - Variables and properties use variableColor
+     * - Types use typeColor
+     * - And more specialized cases for other syntax kinds
+     *
+     * Special handling is applied to property access expressions to differentiate between
+     * the object being accessed and the property being accessed.
+     *
+     * @example
+     * ```ts
+     * // Inside the CodeHighlighter class
+     * const identifierNode = getIdentifierNode(); // Get some identifier node
+     * this.processIdentifier(identifierNode);
+     * // The identifier is now added to segments with appropriate color based on its context
+     * ```
+     *
+     * @see addSegment
+     * @see HighlightSchemeInterface
+     *
+     * @since 1.0.0
+     */
+    private processIdentifier;
+    /**
+     * Processes a TypeScript template expression and adds highlighting segments for its literal parts.
+     *
+     * @param templateExpression - The TypeScript template expression to be processed
+     *
+     * @remarks
+     * This method adds color segments for both the template head and each template span's literal part.
+     * All template string components are highlighted using the color defined in the schema's stringColor.
+     *
+     * @example
+     * ```ts
+     * // Given a template expression like: `Hello ${name}`
+     * this.processTemplateExpression(templateNode);
+     * // Both "Hello " and the closing part after the expression will be highlighted
+     * ```
+     *
+     * @see addSegment
+     *
+     * @since 1.0.0
+     */
+    private processTemplateExpression;
+    /**
+     * Processes a TypeScript AST node and adds highlighting segments based on the node's kind.
+     *
+     * @param node - The TypeScript AST node to be processed
+     *
+     * @remarks
+     * This method identifies the node's kind and applies the appropriate color for highlighting.
+     * It handles various syntax kinds including literals (string, numeric, regular expressions),
+     * template expressions, identifiers, and type references.
+     * For complex node types like template expressions and identifiers, it delegates to specialized processing methods.
+     *
+     * @throws Error - When casting to TypeParameterDeclaration fails for non-compatible node kinds
+     *
+     * @example
+     * ```ts
+     * // Inside the CodeHighlighter class
+     * const node = sourceFile.getChildAt(0);
+     * this.processNode(node);
+     * // Node is now added to the segments map with appropriate colors
+     * ```
+     *
+     * @see processTemplateExpression
+     * @see processIdentifier
+     *
+     * @since 1.0.0
+     */
+    private processNode;
+}
+/**
+ * Applies semantic highlighting to the provided code string using the specified color scheme.
+ *
+ * @param code - The source code to be highlighted
+ * @param schema - An optional partial schema defining the color styles for various code elements
+ *
+ * @returns A string with the code elements wrapped in the appropriate color styles
+ *
+ * @remarks
+ * If no schema is provided, the default schema will be used. The function creates a TypeScript
+ * source file from the provided code and walks through its AST to apply syntax highlighting.
+ *
+ * @example
+ * ```ts
+ * const code = 'const x: number = 42;';
+ * const schema = {
+ *   keywordColor: '\x1b[34m', // Blue
+ *   numberColor: '\x1b[31m',  // Red
+ * };
+ * const highlightedCode = highlightCode(code, schema);
+ * console.log(highlightedCode);
+ * ```
+ *
+ * @see CodeHighlighter
+ * @see HighlightSchemeInterface
+ *
+ * @since 1.0.0
+ */
+export declare function highlightCode(code: string, schema?: Partial<HighlightSchemeInterface>): string;
+/**
+ * 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;