@remotex-labs/xmap 3.0.3 → 3.0.4

package/dist/highlighter.component.d.ts

@@ -1,4 +1,989 @@
-import * as ts from "typescript";
+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
+ */
+export interface SourceMapInterface {
+    /**
+     * The generated file's name that the source map is associated with
+     * @since 1.0.0
+     */
+    file?: string | null;
+    /**
+     * An array of variable/function names present in the original source
+     * @since 1.0.0
+     */
+    names: Array<string>;
+    /**
+     * The version of the source map specification (standard is 3)
+     * @since 1.0.0
+     */
+    version: number;
+    /**
+     * An array of URLs or paths to the original source files
+     * @since 1.0.0
+     */
+    sources: Array<string>;
+    /**
+     * VLQ encoded string that maps generated code back to original source code
+     * @since 1.0.0
+     */
+    mappings: string;
+    /**
+     * Root URL for resolving the sources
+     * @since 1.0.0
+     */
+    sourceRoot?: string | null;
+    /**
+     * Array containing the content of the original source files
+     * @since 1.0.0
+     */
+    sourcesContent?: Array<string>;
+}
+/**
+ * Represents a position in source code with mapping information
+ * @since 1.0.0
+ */
+export interface PositionInterface {
+    /**
+     * Name of the identifier at this position
+     * @since 1.0.0
+     */
+    name: string | null;
+    /**
+     * Line number in the original source
+     * @since 1.0.0
+     */
+    line: number;
+    /**
+     * Column number in the original source
+     * @since 1.0.0
+     */
+    column: number;
+    /**
+     * Path or URL to the original source file
+     * @since 1.0.0
+     */
+    source: string;
+    /**
+     * Root URL for resolving the source
+     * @since 1.0.0
+     */
+    sourceRoot: string | null;
+    /**
+     * Index of the source in the sources array
+     * @since 1.0.0
+     */
+    sourceIndex: number;
+    /**
+     * Line number in the generated code
+     * @since 1.0.0
+     */
+    generatedLine: number;
+    /**
+     * Column number in the generated code
+     * @since 1.0.0
+     */
+    generatedColumn: number;
+}
+/**
+ * Position in source code including the original source content
+ *
+ * @see PositionInterface
+ * @since 1.0.0
+ */
+export interface PositionWithContentInterface extends PositionInterface {
+    /**
+     * Content of the original source file
+     * @since 1.0.0
+     */
+    sourcesContent: string;
+}
+/**
+ * Position in source code including code fragment information
+ *
+ * @see PositionInterface
+ * @since 1.0.0
+ */
+export interface PositionWithCodeInterface extends PositionInterface {
+    /**
+     * Code fragment from the original source
+     * @since 1.0.0
+     */
+    code: string;
+    /**
+     * Ending line number of the code fragment
+     * @since 1.0.0
+     */
+    endLine: number;
+    /**
+     * Starting line number of the code fragment
+     * @since 1.0.0
+     */
+    startLine: number;
+}
+/**
+ * Options for retrieving source code context
+ * @since 1.0.0
+ */
+export interface SourceOptionsInterface {
+    /**
+     * Number of lines to include after the target line
+     * @since 1.0.0
+     */
+    linesAfter?: number;
+    /**
+     * Number of lines to include before the target line
+     * @since 1.0.0
+     */
+    linesBefore?: number;
+}
+/**
+ * Encodes a given number using Variable-Length Quantity (VLQ) encoding. Negative numbers are encoded by
+ * converting to a non-negative representation and the continuation bit is used to indicate if more bytes follow.
+ *
+ * @param value - The number to be encoded
+ * @returns The VLQ encoded string represented as Base64 characters
+ *
+ * @throws Error - If the value cannot be properly encoded
+ *
+ * @remarks The encoding process shifts the value left by 1 bit to accommodate a sign bit in the least significant position.
+ * Negative values have their sign bit set to 1, while positive values have it set to 0.
+ *
+ * @example
+ * ```ts
+ * // Encoding a positive number
+ * const encoded = encodeVLQ(25);  // Returns "Y"
+ *
+ * // Encoding a negative number
+ * const encodedNegative = encodeVLQ(-25);  // Returns "Z"
+ * ```
+ *
+ * @see decodeVLQ - For the corresponding decode function
+ *
+ * @since 1.0.0
+ */
+export declare function encodeVLQ(value: number): string;
+/**
+ * Encodes an array of numbers using VLQ encoding by individually encoding each number and concatenating the results.
+ *
+ * @param values - The array of numbers to be encoded
+ * @returns The concatenated VLQ encoded string
+ *
+ * @example
+ * ```ts
+ * // Encoding multiple values
+ * const encoded = encodeArrayVLQ([1, 0, -5]);  // Returns "CAAK"
+ * ```
+ *
+ * @see encodeVLQ - The underlying function used to encode each number
+ *
+ * @since 1.0.0
+ */
+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.
+ *
+ * @param data - The VLQ encoded string
+ * @returns The array of decoded numbers
+ *
+ * @throws Error - If the string contains invalid Base64 characters
+ *
+ * @remarks The decoding process examines each Base64 character,
+ * checking for continuation bits and progressively building up numeric values.
+ * The sign bit is extracted from the least significant position
+ * to determine if the original number was negative.
+ *
+ * @example
+ * ```ts
+ * // Decoding a simple VLQ string
+ * const decoded = decodeVLQ("Y");  // Returns [25]
+ *
+ * // Decoding multiple values
+ * const multiDecoded = decodeVLQ("CAAK");  // Returns [1, 0, -5]
+ * ```
+ *
+ * @see encodeVLQ - For the corresponding encode function
+ *
+ * @since 1.0.0
+ */
+export declare function decodeVLQ(data: string): number[];
+/**
+ * Represents a source map mapping segment that links positions between original and generated code.
+ *
+ * @interface SegmentInterface
+ *
+ * @property line - Original line number in the source file
+ * @property column - Original column number in the source file
+ * @property nameIndex - Index of the symbol name in the source map's names array (null if no associated name)
+ * @property sourceIndex - Index of the source file in the source map's sources array
+ * @property generatedLine - Line number in the generated output code
+ * @property generatedColumn - Column number in the generated output code
+ *
+ * @remarks
+ * These segments form the core data structure of source maps, providing the necessary
+ * information to trace locations between original source code and generated output code.
+ * Each segment represents a single mapping point in the transformation process.
+ *
+ * @example
+ * ```ts
+ * const segment: SegmentInterface = {
+ *   line: 42,
+ *   column: 10,
+ *   nameIndex: 5,
+ *   sourceIndex: 0,
+ *   generatedLine: 100,
+ *   generatedColumn: 15
+ * };
+ * ```
+ *
+ * @since 1.0.0
+ */
+export interface SegmentInterface {
+    line: number;
+    column: number;
+    nameIndex: number | null;
+    sourceIndex: number;
+    generatedLine: number;
+    generatedColumn: number;
+}
+/**
+ * A specialized segment interface used during source map offset calculations.
+ *
+ * @property nameIndex - Index of the symbol name in the source map's names array (always numeric)
+ *
+ * @remarks
+ * Unlike the base SegmentInterface where nameIndex can be null,
+ * in offset calculations this value must always be a concrete numeric index.
+ * This specialized interface ensures type safety during mapping offset operations.
+ *
+ * @example
+ * ```ts
+ * const offsetSegment: SegmentOffsetInterface = {
+ *   line: 42,
+ *   column: 10,
+ *   nameIndex: 5, // Must be a number, not null
+ *   sourceIndex: 0,
+ *   generatedLine: 100,
+ *   generatedColumn: 15
+ * };
+ * ```
+ *
+ * @see SegmentInterface
+ *
+ * @since 1.0.0
+ */
+export interface SegmentOffsetInterface extends SegmentInterface {
+    nameIndex: number;
+}
+/**
+ * Determines the matching behavior when searching for segments in a source map.
+ *
+ * @property BOUND - No directional preference; returns the first matching segment found
+ * @property LOWER_BOUND - Prefers segments with column values lower than or equal to the target
+ * @property UPPER_BOUND - Prefers segments with column values greater than or equal to the target
+ *
+ * @remarks
+ * The bias affects how segment lookups behave when an exact position match cannot be found.
+ * This provides flexibility in determining which nearby mapping should be preferred when
+ * working with source map data that might not have exact matches for every position.
+ *
+ * @example
+ * ```ts
+ * // When searching for a position not exactly in the map:
+ * findSegmentForPosition(line, column, Bias.LOWER_BOUND); // Prefers the position just before
+ * findSegmentForPosition(line, column, Bias.UPPER_BOUND); // Prefers the position just after
+ * ```
+ *
+ * @since 1.0.0
+ */
+export declare const enum Bias {
+    BOUND = 0,
+    LOWER_BOUND = 1,
+    UPPER_BOUND = 2
+}
+/**
+ * Represents a collection of mapping segments for a single line in generated code.
+ *
+ * @remarks
+ * A frame contains all the segments that map to a particular line of generated code.
+ * Each segment within the frame provides mapping information for a specific range
+ * of columns within that line.
+ *
+ * @example
+ * ```ts
+ * const lineFrame: FrameType = [
+ *   { line: 10, column: 0, nameIndex: null, sourceIndex: 0, generatedLine: 5, generatedColumn: 0 },
+ *   { line: 10, column: 5, nameIndex: 3, sourceIndex: 0, generatedLine: 5, generatedColumn: 10 }
+ * ];
+ * ```
+ *
+ * @see SegmentInterface
+ *
+ * @since 1.0.0
+ */
+export type FrameType = Array<SegmentInterface>;
+/**
+ * Represents the complete mapping structure of a source map.
+ *
+ * @remarks
+ * A source map contains an array where each index corresponds to a line in the generated code.
+ * Each entry is either:
+ * - A frame (array of segments) containing mappings for that line
+ * - Null, indicating the line has no mappings (represented by a semicolon in the source map)
+ *
+ * The array index corresponds directly to the line number in generated code (0-based).
+ *
+ * @example
+ * ```ts
+ * const sourceMap: MapType = [
+ *   [{ line: 1, column: 0, nameIndex: null, sourceIndex: 0, generatedLine: 0, generatedColumn: 0 }], // Line 0
+ *   null, // Line 1 has no mappings
+ *   [{ line: 2, column: 0, nameIndex: 1, sourceIndex: 0, generatedLine: 2, generatedColumn: 0 }]  // Line 2
+ * ];
+ * ```
+ *
+ * @see FrameType
+ * @see SegmentInterface
+ *
+ * @since 1.0.0
+ */
+export type MapType = Array<null | FrameType>;
+/**
+ * Provides functionality for encoding and decoding source map mappings.
+ *
+ * The MappingProvider class handles the conversion between various mapping representations:
+ * - String format (VLQ-encoded mappings)
+ * - Structured array format (MapType)
+ * - Internal structured representation
+ *
+ * It also provides methods to query and retrieve source map segments based on
+ * generated or original source positions.
+ *
+ * @example
+ * ```ts
+ * // Create from VLQ-encoded mapping string
+ * const provider = new MappingProvider(mappingString);
+ *
+ * // Get a segment by generated position
+ * const segment = provider.getSegment(10, 15);
+ *
+ * // Convert back to mapping string
+ * const encoded = provider.encode();
+ * ```
+ *
+ * @since 1.0.0
+ */
+export declare class MappingProvider {
+    private mapping;
+    /**
+     * Creates a new MappingProvider instance.
+     *
+     * @param mapping - Source map mapping data in one of three formats:
+     *                 - VLQ-encoded string
+     *                 - Structured array (MapType)
+     *                 - Another MappingProvider instance (copy constructor)
+     * @param namesOffset - Optional offset to apply to name indices (default: 0)
+     * @param sourceOffset - Optional offset to apply to source indices (default: 0)
+     *
+     * @remarks
+     * The constructor automatically detects the mapping format and decodes it accordingly.
+     * When providing offsets, these values will be added to the corresponding indices
+     * in the decoded mapping data, which is useful when concatenating multiple source maps.
+     *
+     * @since 1.0.0
+     */
+    constructor(mapping: string, namesOffset?: number, sourceOffset?: number);
+    constructor(mapping: MapType, namesOffset?: number, sourceOffset?: number);
+    constructor(mapping: MappingProvider, namesOffset?: number, sourceOffset?: number);
+    /**
+     * Encodes the internal mapping representation to a VLQ-encoded mapping string.
+     *
+     * @returns VLQ-encoded mapping string compatible with the source map format specification
+     *
+     * @remarks
+     * This method converts the internal structured mapping representation into a compact
+     * string format using Variable Length Quantity (VLQ) encoding.
+     * The resulting string follows the source map v3 format for the 'mappings' field.
+     *
+     * @see https://sourcemaps.info/spec.html
+     *
+     * @since 1.0.0
+     */
+    encode(): string;
+    /**
+     * Decodes mapping data into the internal representation.
+     *
+     * @param mapping - Mapping data to decode in one of three formats:
+     *                 - VLQ-encoded string
+     *                 - Structured array (MapType)
+     *                 - Another MappingProvider instance
+     * @param namesOffset - Optional offset for name indices (default: 0)
+     * @param sourcesOffset - Optional offset for source indices (default: 0)
+     *
+     * @remarks
+     * This method replaces the current internal mapping data with the newly decoded mapping.
+     * The format of the input mapping is automatically detected and processed accordingly.
+     *
+     * @see MapType
+     * @see MappingProvider
+     *
+     * @since 1.0.0
+     */
+    decode(mapping: MappingProvider | MapType | string, namesOffset?: number, sourcesOffset?: number): void;
+    /**
+     * Retrieves a segment based on a position in the generated code.
+     *
+     * @param generatedLine - Line number in generated code (1-based)
+     * @param generatedColumn - Column number in generated code (0-based)
+     * @param bias - Controls matching behavior when exact position not found:
+     *              - BOUND: No preference (default)
+     *              - LOWER_BOUND: Prefer segment with lower column
+     *              - UPPER_BOUND: Prefer segment with higher column
+     * @returns Matching segment or null if not found
+     *
+     * @remarks
+     * Uses binary search to efficiently locate matching segments.
+     * When no exact match is found, the bias parameter determines which nearby segment to return.
+     *
+     * @since 1.0.0
+     */
+    getSegment(generatedLine: number, generatedColumn: number, bias?: Bias): SegmentInterface | null;
+    /**
+     * Retrieves a segment based on a position in the original source code.
+     *
+     * @param line - Line number in original source (1-based)
+     * @param column - Column number in original source (0-based)
+     * @param sourceIndex - Index of source file in the sources array
+     * @param bias - Controls matching behavior when exact position not found:
+     *              - BOUND: No preference (default)
+     *              - LOWER_BOUND: Prefer segment with lower column
+     *              - UPPER_BOUND: Prefer segment with higher column
+     * @returns Matching segment or null if not found
+     *
+     * @remarks
+     * Searches across all mapping segments to find those matching the specified original source position.
+     * When multiple matches are possible, the bias
+     * parameter determines which segment to return.
+     *
+     * This operation is more expensive than getSegment as it must potentially
+     * scan the entire mapping structure.
+     *
+     * @since 1.0.0
+     */
+    getOriginalSegment(line: number, column: number, sourceIndex: number, bias?: Bias): SegmentInterface | null;
+    /**
+     * Initializes a new segment offset object with default values.
+     *
+     * @param namesOffset - Initial name index offset value (default: 0)
+     * @param sourceIndex - Initial source index offset value (default: 0)
+     * @returns A new segment offset object with initialized position tracking values
+     *
+     * @remarks
+     * This method creates an object that tracks position data during mapping operations.
+     * All position values (line, column, generatedLine, generatedColumn) are initialized to 0,
+     * while the nameIndex and sourceIndex can be initialized with custom offsets.
+     *
+     * @since 1.0.0
+     */
+    private initPositionOffsets;
+    /**
+     * Validates the format of an encoded mapping string.
+     *
+     * @param encodedSourceMap - The encoded source map string to validate
+     * @returns `true` if the string contains only valid VLQ mapping characters, otherwise `false`
+     *
+     * @remarks
+     * Checks if the string contains only characters valid in source map mappings:
+     * - Base64 characters (a-z, A-Z, 0-9, +, /)
+     * - Separators (commas for segments, semicolons for lines)
+     *
+     * This is a basic format validation and doesn't verify the semantic correctness
+     * of the VLQ encoding itself.
+     *
+     * @since 1.0.0
+     */
+    private validateMappingString;
+    /**
+     * Validates that a segment's properties conform to expected types.
+     *
+     * @param segment - The segment object to validate
+     *
+     * @remarks
+     * Performs the following validations on the segment properties:
+     * - line: Must be a finite number
+     * - column: Must be a finite number
+     * - nameIndex: Must be either null or a finite number
+     * - sourceIndex: Must be a finite number
+     * - generatedLine: Must be a finite number
+     * - generatedColumn: Must be a finite number
+     *
+     * This validation ensures that segments can be safely used in mapping operations
+     * and prevents potential issues with non-numeric or infinite values.
+     *
+     * @throws Error - When any property of the segment is invalid, with a message
+     *                 indicating which property failed validation and its value
+     *
+     * @since 1.0.0
+     */
+    private validateSegment;
+    /**
+     * Encodes a segment into a VLQ-encoded string based on relative offsets.
+     *
+     * @param segmentOffset - The current segment offset tracking state
+     * @param segmentObject - The segment to encode
+     * @returns A VLQ-encoded string representation of the segment
+     *
+     * @remarks
+     * The encoding process:
+     * 1. Adjusts line and column values (subtracts 1 to convert from 1-based to 0-based)
+     * 2. Calculates relative differences between current values and previous offsets
+     * 3. Creates an array with the following components:
+     *    - generatedColumn difference
+     *    - sourceIndex difference (0 if unchanged)
+     *    - line difference
+     *    - column difference
+     *    - nameIndex difference (only if nameIndex is present)
+     * 4. Updates the segment offset state for the next encoding
+     * 5. Returns the array as a VLQ-encoded string
+     *
+     * This method implements the source map V3 specification's delta encoding scheme
+     * where values are stored as differences from previous positions.
+     *
+     * @since 1.0.0
+     */
+    private encodeSegment;
+    /**
+     * Encodes a mapping array into a VLQ-encoded mapping string following the source map V3 spec.
+     *
+     * @param map - The mapping array to encode, organized by generated lines and segments
+     * @returns A complete VLQ-encoded mapping string with line and segment separators
+     *
+     * @remarks
+     * The encoding process:
+     * 1. Initializes position offsets to track state across the entire mapping
+     * 2. Processes each frame (line) in the mapping array:
+     *    - Resets generated column offset to 0 at the start of each line
+     *    - Encodes each segment within the line using relative VLQ encoding
+     *    - Joins segments with commas (,)
+     * 3. Joins lines with semicolons (;)
+     *
+     * Empty frames are preserved as empty strings in the output to maintain
+     * the correct line numbering in the resulting source map.
+     *
+     * @since 1.0.0
+     */
+    private encodeMappings;
+    /**
+     * Converts a VLQ-decoded segment array into a structured segment object.
+     *
+     * @param segmentOffset - The current positional state tracking offsets
+     * @param decodedSegment - Array of VLQ-decoded values representing relative offsets
+     * @returns A complete segment object with absolute positions
+     *
+     * @remarks
+     * The decoding process:
+     * 1. Extracts position values from the decoded array:
+     *    - [0]: generatedColumn delta
+     *    - [1]: sourceIndex delta
+     *    - [2]: sourceLine delta
+     *    - [3]: sourceColumn delta
+     *    - [4]: nameIndex delta (optional)
+     * 2. Updates the segmentOffset state by adding each delta
+     * 3. Constructs a segment object with absolute positions (adding 1 to convert
+     *    from 0-based to 1-based coordinates)
+     * 4. Handles nameIndex appropriately (null if not present in the input)
+     *
+     * This method implements the inverse operation of the delta encoding scheme
+     * defined in the source map V3 specification.
+     *
+     * @since 1.0.0
+     */
+    private decodedSegment;
+    /**
+     * Decodes a VLQ-encoded mapping string into the internal mapping data structure.
+     *
+     * @param encodedMap - The VLQ-encoded mapping string from a source map
+     * @param namesOffset - Base offset for name indices in the global names array
+     * @param sourceOffset - Base offset for source indices in the global sources array
+     *
+     * @remarks
+     * The decoding process:
+     * 1. Validates the mapping string format before processing
+     * 2. Splits the string into frames using semicolons (;) as line separators
+     * 3. Initializes position offsets with the provided name and source offsets
+     * 4. For each frame (line):
+     *    - Adds `null` to the mapping array if the frame is empty
+     *    - Resets the generated column offset to 0 for each new line
+     *    - Sets the generated line index using the offset + current index
+     *    - Splits segments using commas (,) and decodes each segment
+     *    - Transforms each decoded segment into a segment object
+     * 5. Updates the internal mapping array with the decoded data
+     *
+     * Error handling includes validation checks and descriptive error messages
+     * indicating which frame caused a decoding failure.
+     *
+     * @throws Error - When the mapping string format is invalid or decoding fails
+     *
+     * @since 1.0.0
+     */
+    private decodeMappingString;
+    /**
+     * Decodes a structured mapping array into the internal mapping representation.
+     *
+     * @param encodedMap - The structured mapping array (array of frames, with each frame being an array of segments)
+     * @param namesOffset - Offset to add to each segment's nameIndex (for merging multiple source maps)
+     * @param sourceOffset - Offset to add to each segment's sourceIndex (for merging multiple source maps)
+     *
+     * @remarks
+     * The decoding process:
+     * 1. Validates that the input is a properly structured array
+     * 2. Tracks the current line offset based on the existing mapping length
+     * 3. For each frame (line) in the mapping:
+     *    - Preserves null frames as-is (representing empty lines)
+     *    - Validates that each frame is an array
+     *    - For each segment in a frame:
+     *      - Validates the segment structure
+     *      - Applies the name and source offsets
+     *      - Adjusts the generated line index by the line offset
+     *    - Adds the processed frame to the internal mapping array
+     *
+     * This method is primarily used when combining multiple source maps or
+     * importing mapping data from pre-structured arrays rather than VLQ strings.
+     * The offsets enable proper indexing when concatenating multiple mappings.
+     *
+     * @throws Error - When the input format is invalid or segments don't conform to requirements
+     *
+     * @since 1.0.0
+     */
+    private decodeMappingArray;
+}
+/**
+ * A service for validating and processing source maps that provides functionality for parsing,
+ * position mapping, concatenation, and code snippet extraction.
+ *
+ * @param source - Source map data (SourceService, SourceMapInterface object, or JSON string)
+ * @param file - Optional file name for the generated bundle
+ * @returns A new SourceService instance
+ *
+ * @example
+ * ```ts
+ * const sourceMapJSON = '{"version": 3, "file": "bundle.js", "sources": ["foo.ts"], "names": [], "mappings": "AAAA"}';
+ * const sourceService = new SourceService(sourceMapJSON);
+ * console.log(sourceService.file); // 'bundle.js'
+ * ```
+ *
+ * @since 1.0.0
+ */
+export declare class SourceService {
+    /**
+     * The name of the generated file this source map applies to.
+     *
+     * @since 1.0.0
+     */
+    readonly file: string | null;
+    /**
+     * Provider for accessing and manipulating the base64 VLQ-encoded mappings.
+     *
+     * @since 1.0.0
+     */
+    readonly mappings: MappingProvider;
+    /**
+     * The root URL for resolving relative paths in the source files.
+     * @since 1.0.0
+     */
+    readonly sourceRoot: string | null;
+    /**
+     * List of symbol names referenced by the mappings.
+     * @since 1.0.0
+     */
+    readonly names: Array<string>;
+    /**
+     * Array of source file paths.
+     * @since 1.0.0
+     */
+    readonly sources: Array<string>;
+    /**
+     * Array of source file contents.
+     * @since 1.0.0
+     */
+    readonly sourcesContent: Array<string>;
+    /**
+     * Creates a new SourceService instance.
+     *
+     * @param source - Source map data (SourceService, SourceMapInterface object, or JSON string)
+     * @param file - Optional file name for the generated bundle
+     *
+     * @throws Error - When a source map has an invalid format or missing required properties
+     *
+     * @since 1.0.0
+     */
+    constructor(source: SourceService);
+    constructor(source: SourceMapInterface | string, file?: string | null);
+    /**
+     * Converts the source map data to a plain object.
+     *
+     * @returns A SourceMapInterface object representing the current state
+     *
+     * @example
+     * ```ts
+     * const mapObject = sourceService.getMapObject();
+     * console.log(mapObject.file); // 'bundle.js'
+     * ```
+     *
+     * @since 1.0.0
+     */
+    getMapObject(): SourceMapInterface;
+    /**
+     * Concatenates additional source maps into the current instance.
+     *
+     * @param maps - Source maps to concatenate with the current map
+     *
+     * @example
+     * ```ts
+     * sourceService.concat(anotherSourceMap);
+     * console.log(sourceService.sources); // Updated source paths
+     * ```
+     *
+     * @throws Error - When no maps are provided
+     *
+     * @since 1.0.0
+     */
+    concat(...maps: Array<SourceMapInterface | SourceService>): void;
+    /**
+     * Creates a new SourceService instance with concatenated source maps.
+     *
+     * @param maps - Source maps to concatenate with a copy of the current map
+     * @returns A new SourceService instance with the combined maps
+     *
+     * @example
+     * ```ts
+     * const newService = sourceService.concatNewMap(anotherSourceMap);
+     * console.log(newService.sources); // Combined sources array
+     * ```
+     *
+     * @throws Error - When no maps are provided
+     *
+     * @since 1.0.0
+     */
+    concatNewMap(...maps: Array<SourceMapInterface | SourceService>): SourceService;
+    /**
+     * Finds position in generated code based on original source position.
+     *
+     * @param line - Line number in the original source
+     * @param column - Column number in the original source
+     * @param sourceIndex - Index or file path of the original source
+     * @param bias - Position matching strategy (default: Bias.BOUND)
+     * @returns Position information or null if not found
+     *
+     * @example
+     * ```ts
+     * const position = sourceService.getPositionByOriginal(1, 10, 'foo.ts');
+     * console.log(position?.generatedLine); // Line in generated code
+     * ```
+     *
+     * @since 1.0.0
+     */
+    getPositionByOriginal(line: number, column: number, sourceIndex: number | string, bias?: Bias): PositionInterface | null;
+    /**
+     * Finds position in an original source based on generated code position.
+     *
+     * @param line - Line number in the generated code
+     * @param column - Column number in the generated code
+     * @param bias - Position matching strategy (default: Bias.BOUND)
+     * @returns Position information or null if not found
+     *
+     * @example
+     * ```ts
+     * const position = sourceService.getPosition(2, 15);
+     * console.log(position?.source); // Original source file
+     * ```
+     *
+     * @since 1.0.0
+     */
+    getPosition(line: number, column: number, bias?: Bias): PositionInterface | null;
+    /**
+     * Retrieves position with source content for a location in generated code.
+     *
+     * @param line - Line number in the generated code
+     * @param column - Column number in the generated code
+     * @param bias - Position matching strategy (default: Bias.BOUND)
+     * @returns Position with content information or null if not found
+     *
+     * @example
+     * ```ts
+     * const posWithContent = sourceService.getPositionWithContent(3, 5);
+     * console.log(posWithContent?.sourcesContent); // Original source content
+     * ```
+     *
+     * @since 1.0.0
+     */
+    getPositionWithContent(line: number, column: number, bias?: Bias): PositionWithContentInterface | null;
+    /**
+     * Retrieves position with a code snippet from the original source.
+     *
+     * @param line - Line number in the generated code
+     * @param column - Column number in the generated code
+     * @param bias - Position matching strategy (default: Bias.BOUND)
+     * @param options - Configuration for the amount of surrounding lines
+     * @returns Position with code snippet or null if not found
+     *
+     * @example
+     * ```ts
+     * const posWithCode = sourceService.getPositionWithCode(4, 8, Bias.BOUND, {
+     *   linesBefore: 2,
+     *   linesAfter: 2
+     * });
+     * console.log(posWithCode?.code); // Code snippet with context
+     * ```
+     *
+     * @since 1.0.0
+     */
+    getPositionWithCode(line: number, column: number, bias?: Bias, options?: SourceOptionsInterface): PositionWithCodeInterface | null;
+    /**
+     * Serializes the source map to a JSON string.
+     *
+     * @returns JSON string representation of the source map
+     *
+     * @example
+     * ```ts
+     * const jsonString = sourceService.toString();
+     * console.log(jsonString); // '{"version":3,"file":"bundle.js",...}'
+     * ```
+     *
+     * @since 1.0.0
+     */
+    toString(): string;
+    /**
+     * Validates a source map object has all required properties.
+     *
+     * @param input - Source map object to validate
+     *
+     * @throws Error - When required properties are missing
+     *
+     * @since 1.0.0
+     */
+    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.
  *
@@ -107,7 +1092,7 @@ export interface HighlightNodeSegmentInterface {
  *
  * @since 1.0.0
  */
-export const enum Colors {
+export declare const enum Colors {
     reset = "\u001B[0m",
     gray = "\u001B[38;5;243m",
     darkGray = "\u001B[38;5;238m",
@@ -139,7 +1124,7 @@ export const enum Colors {
  *
  * @since 1.0.0
  */
-export class CodeHighlighter {
+export declare class CodeHighlighter {
     private sourceFile;
     private code;
     private schema;
@@ -420,4 +1405,270 @@ export class CodeHighlighter {
  *
  * @since 1.0.0
  */
-export function highlightCode(code: string, schema?: Partial<HighlightSchemeInterface>): string;
+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;