@remotex-labs/xmap 3.0.0 → 3.0.2

package/dist/providers/interfaces/mapping-provider.interface.d.ts

@@ -1,141 +0,0 @@
-/**
- * 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>;

package/dist/providers/mapping.provider.d.ts

@@ -1,317 +0,0 @@
-/**
- * Import will remove at compile time
- */
-import type { MapType, SegmentInterface } from './interfaces/mapping-provider.interface';
-/**
- * Imports
- */
-import { Bias } from './interfaces/mapping-provider.interface';
-/**
- * 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;
-}

package/dist/services/interfaces/source-service.interface.d.ts

@@ -1,139 +0,0 @@
-/**
- * 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;
-}