@remotex-labs/xmap 1.0.4 → 2.0.0

package/dist/cjs/services/source.service.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Import will remove at compile time
+ */
+import type { PositionInterface, SourceMapInterface, SourceOptionsInterface, PositionWithCodeInterface, PositionWithContentInterface } from "./interfaces/source.interface";
+/**
+ * Imports
+ */
+import { MappingProvider } from "../providers/mapping.provider";
+import { Bias } from "../providers/interfaces/mapping.interface";
+/**
+ * A service for validating and processing source maps.
+ * This class allows parsing and manipulation of source maps, providing functionality such as
+ * retrieving position mappings between original and generated code, concatenating source maps,
+ * and getting code snippets based on mappings.
+ *
+ * @example
+ * ```ts
+ * const sourceMapJSON = '{"version": 3, "file": "bundle.js", "sources": ["foo.ts"], "names": [], "mappings": "AAAA"}';
+ * const sourceService = new SourceService(sourceMapJSON);
+ *
+ * console.log(sourceService.file); // Outputs: 'bundle.js'
+ * ```
+ */
+export declare class SourceService {
+    /**
+     * The name of the generated file (bundle) that this source map applies to.
+     *
+     * @example
+     * ```ts
+     * console.log(sourceService.file); // 'bundle.js'
+     * ```
+     */
+    readonly file: string | null;
+    /**
+     * A MappingProvider instance of base64 VLQ-encoded mappings.
+     */
+    readonly mappings: MappingProvider;
+    /**
+     * The root URL for the sources, if present in the source map.
+     */
+    readonly sourceRoot: string | null;
+    /**
+     * A list of symbol names used by the “mappings” entry.
+     */
+    readonly names: Array<string>;
+    /**
+     * An array of source file paths.
+     */
+    readonly sources: Array<string>;
+    /**
+     * An array of source files contents.
+     */
+    readonly sourcesContent: Array<string>;
+    /**
+     * Creates a new instance of the `SourceService` class.
+     *
+     * This constructor initializes the class using either a `SourceMapInterface` object,
+     * a JSON string representing the source map, or an existing `SourceService` instance.
+     * It validates the source map and populates its properties such as `file`, `sources`, and `mappings`.
+     *
+     * @param source - Can be one of the following:
+     *   - An object conforming to the `SourceMapInterface`.
+     *   - A JSON string representing the source map.
+     *   - A `SourceService` instance to copy the properties.
+     * @param file - (Optional) A string representing the file name of the generated bundle.
+     *               Defaults to `null`. It will overwrite any existing `file` property in the source map.
+     * @throws {Error} - If the source map does not contain required properties or has an invalid format.
+     *
+     * @example
+     * ```ts
+     * const sourceMapJSON = '{"version": 3, "file": "bundle.js", "sources": ["foo.ts"], "names": [], "mappings": "AAAA"}';
+     * const sourceService = new SourceService(sourceMapJSON);
+     * ```
+     */
+    constructor(source: SourceService);
+    constructor(source: SourceMapInterface | string, file?: string | null);
+    /**
+     * Converts the current source map data into a plain object format.
+     *
+     * @returns The source map json object.
+     *
+     * @example
+     * ```ts
+     * const mapObject = sourceService.getMapObject();
+     * console.log(mapObject.file); // 'bundle.js'
+     * ```
+     */
+    getMapObject(): SourceMapInterface;
+    /**
+     * Concatenates one or more source maps to the current source map.
+     *
+     * This method merges additional source maps into the current source map,
+     * updating the `mappings`, `names`, `sources`, and `sourcesContent` arrays.
+     *
+     * @param maps - An array of `SourceMapInterface` or `SourceService` instances to be concatenated.
+     * @throws { Error } If no source maps are provided for concatenation.
+     *
+     * @example
+     * ```ts
+     * sourceService.concat(anotherSourceMap);
+     * console.log(sourceService.sources); // Updated source paths
+     * ```
+     */
+    concat(...maps: Array<SourceMapInterface | SourceService>): void;
+    /**
+     * Creates a new instance of `SourceService` with concatenated source maps.
+     *
+     * @param maps - An array of `SourceMapInterface` or `SourceService` instances to be concatenated.
+     * @returns { SourceService } A new `SourceService` instance with the concatenated maps.
+     * @throws { Error } If no source maps are provided.
+     *
+     * @example
+     * ```ts
+     * const newService = sourceService.concatNewMap(anotherSourceMap);
+     * console.log(newService.file); // The file from the new source map
+     * ```
+     */
+    concatNewMap(...maps: Array<SourceMapInterface | SourceService>): SourceService;
+    /**
+     * Retrieves the position information based on the original source line and column.
+     *
+     * @param line - The line number in the generated code.
+     * @param column - The column number in the generated code.
+     * @param sourceIndex - The index or file path of the original source.
+     * @param bias - The bias to use when matching positions (`Bias.LOWER_BOUND`, `Bias.UPPER_BOUND`, or `Bias.BOUND`).
+     * @returns { PositionInterface | null } The corresponding position in the original source, or `null` if not found.
+     *
+     * @example
+     * ```ts
+     * const position = sourceService.getPositionByOriginal(1, 10, 'foo.ts');
+     * console.log(position?.line); // The line number in the original source
+     * ```
+     */
+    getPositionByOriginal(line: number, column: number, sourceIndex: number | string, bias?: Bias): PositionInterface | null;
+    /**
+     * Retrieves the position in the original source code based on a given line and column
+     * in the generated code.
+     *
+     * @param line - Line number in the generated code.
+     * @param column - Column number in the generated code.
+     * @param bias - The bias to use for matching positions. Defaults to `Bias.BOUND`.
+     * @returns {PositionInterface | null} The position in the original source, or null if not found.
+     *
+     * @example
+     * ```ts
+     * const position = sourceService.getPosition(2, 15);
+     * console.log(position?.source); // The original source file
+     * ```
+     */
+    getPosition(line: number, column: number, bias?: Bias): PositionInterface | null;
+    /**
+     * Retrieves the position and original source content for a given position in the generated code.
+     *
+     * @param line - Line number in the generated code.
+     * @param column - Column number in the generated code.
+     * @param bias - Bias used for position matching.
+     * @returns { PositionWithContentInterface | null } The position and its associated content, or `null` if not found.
+     *
+     * @example
+     * ```ts
+     * const positionWithContent = sourceService.getPositionWithContent(3, 5);
+     * console.log(positionWithContent?.sourcesContent); // The source code content
+     * ```
+     */
+    getPositionWithContent(line: number, column: number, bias?: Bias): PositionWithContentInterface | null;
+    /**
+     * Retrieves the position and a code snippet from the original source based on the given
+     * generated code position, with additional lines of code around the matching line.
+     *
+     * @param line - Line number in the generated code.
+     * @param column - Column number in the generated code.
+     * @param bias - Bias used for position matching.
+     * @param options - (Optional) Extra options for the amount of surrounding lines to include.
+     * @returns { PositionWithCodeInterface | null } The position and code snippet.
+     *
+     * @example
+     * ```ts
+     * const positionWithCode = sourceService.getPositionWithCode(4, 8, Bias.BOUND, { linesBefore: 2, linesAfter: 2 });
+     * console.log(positionWithCode?.code); // The code snippet from the original source
+     * ```
+     */
+    getPositionWithCode(line: number, column: number, bias?: Bias, options?: SourceOptionsInterface): PositionWithCodeInterface | null;
+    /**
+     * Converts the current source map object to a JSON string.
+     *
+     * @returns A stringified version of the source map object.
+     *
+     * @example
+     * ```ts
+     * console.log(sourceService.toString()); // JSON string of the source map
+     * ```
+     */
+    toString(): string;
+    /**
+     * Validates the provided source map object.
+     *
+     * This method checks whether all required keys are present in the source map object.
+     * It throws an error if any required keys are missing.
+     *
+     * @private
+     * @param input - The source map object to be validated.
+     * @throws Error If any required key is missing from the source map.
+     *
+     * @example
+     * ```ts
+     * const sourceMap = {
+     *     version: 3,
+     *     file: 'example.js',
+     *     names: ['src', 'maps', 'example', 'function', 'line', 'column'],
+     *     sources: ['source1.js', 'source2.js'],
+     *     mappings: 'AAAA,SAASA,CAAC,CAAC,CAAC;AAAA,CAAC,CAAC;AAAC,CAAC',
+     * };
+     * sourceService['validateSource'](sourceMap); // Throws if invalid
+     * ```
+     */
+    private validateSourceMap;
+}

package/dist/esm/components/base64.component.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Encodes a given number using Variable-Length Quantity (VLQ) encoding.
+ * Negative numbers are encoded by converting to a non-negative representation.
+ * The continuation bit is used to indicate if more bytes follow.
+ *
+ * @param value - The number to be encoded.
+ * @returns The VLQ encoded string.
+ */
+export declare function encodeVLQ(value: number): string;
+/**
+ * Encodes an array of numbers using VLQ encoding.
+ * Each number in the array is individually encoded and the results are concatenated.
+ *
+ * @param values - The array of numbers to be encoded.
+ * @returns The concatenated VLQ encoded string.
+ */
+export declare function encodeArrayVLQ(values: number[]): string;
+/**
+ * Decodes a VLQ encoded string back into an array of numbers.
+ * Each character is decoded using the Base64 map and continuation bits are processed.
+ *
+ * @param data - The VLQ encoded string.
+ * @returns The array of decoded numbers.
+ * @throws Error If the string contains invalid Base64 characters.
+ */
+export declare function decodeVLQ(data: string): number[];

package/dist/esm/components/formatter.component.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Import will remove at compile time
+ */
+import type { PositionWithCodeInterface } from "../services/interfaces/source.interface";
+import type { AnsiOptionInterface, FormatCodeInterface } from "./interfaces/formatter.interface";
+/**
+ * Formats a code snippet with optional line padding and custom actions.
+ *
+ * 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.
+ *
+ * @param code - The source code | stack to be formatted.
+ * @param options - Configuration options for formatting the code.
+ *   - `padding` (number, optional): Number of characters for line number padding. Defaults to 10.
+ *   - `startLine` (number, optional): The starting line number for formatting. Defaults to 1.
+ *   - `action` (object, optional): Custom actions to apply to specific lines.
+ *     - `triggerLine` (number): The line number where the action should be triggered.
+ *     - `callback` (function): A callback function to format the line string when `triggerLine` is matched.
+ *       The callback receives the formatted line string, the padding value, and the current line number as arguments.
+ *
+ * @returns A formatted string of the code snippet with applied padding and custom actions.
+ *
+ * @example
+ * ```typescript
+ * const formattedCode = formatCode(code, {
+ *     padding: 8,
+ *     startLine: 5,
+ *     action: {
+ *         triggerLine: 7,
+ *         callback: (lineString, padding, lineNumber) => {
+ *             return `Custom formatting for line ${lineNumber}: ${lineString}`;
+ *         }
+ *     }
+ * });
+ * console.log(formattedCode);
+ * ```
+ */
+export declare function formatCode(code: string, options?: FormatCodeInterface): string;
+/**
+ * Formats a code snippet around an error location with special highlighting.
+ *
+ * This function takes a `sourcePosition` object containing information about the source code
+ * and error location, then uses `formatCode` to format and highlight the relevant code snippet.
+ *
+ * @param sourcePosition - An object containing information about the source code and error location.
+ *   - `code` (string): The entire source code content.
+ *   - `line` (number): The line number where the error occurred (1-based indexing).
+ *   - `column` (number): The column number within the line where the error occurred (1-based indexing).
+ *   - `startLine` (number, optional): The starting line number of the code snippet (defaults to 1).
+ * @param ansiOption - Optional configuration for ANSI color codes.
+ *   - `color` (string): The ANSI escape sequence to colorize the error marker and prefix (e.g., `'\x1b[38;5;160m'`).
+ *   - `reset` (string): The ANSI escape sequence to reset the color (e.g., `'\x1b[0m'`).
+ *
+ * @throws Error - If the provided `sourcePosition` object has invalid line or column numbers,
+ *                  or if the error line is outside the boundaries of the provided code content.
+ *
+ * @returns A formatted string representing the relevant code snippet around the error location,
+ *          including special highlighting for the error line and column.
+ *
+ * @example
+ * ```typescript
+ * const formattedErrorCode = formatErrorCode(sourcePosition);
+ * console.log(formattedErrorCode);
+ * ```
+ */
+export declare function formatErrorCode(sourcePosition: PositionWithCodeInterface, ansiOption?: AnsiOptionInterface): string;

package/dist/esm/components/highlighter.component.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Import will remove at compile time
+ */
+import type { HighlightSchemeInterface } from "./interfaces/highlighter.interface";
+/**
+ * Imports
+ */
+import * as ts from 'typescript';
+/**
+ * An enum containing ANSI escape sequences for various colors.
+ *
+ * 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
+ * ```typescript
+ * console.log(`${Colors.red}This the text will be red in the terminal.${Colors.reset}`);
+ * ```
+ *
+ * This functionality is limited to terminal environments.
+ * Consider alternative methods
+ * for color highlighting in web development contexts, such as CSS classes.
+ */
+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.
+ *
+ * @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.
+ *
+ * const highlighter = new CodeHighlighter(sourceFile, code, schema);
+ */
+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,
+     * and the value is an object containing the color and reset code.
+     * This structure ensures unique segments and allows for fast lookups and updates.
+     *
+     * @example
+     * this.segments = new Map([
+     *   ['0-10', { start: 1, end: 11, color: '\x1b[31m', reset: '\x1b[0m' }],
+     *   ['11-20', { start: 12, end: 20, color: '\x1b[32m', reset: '\x1b[0m' }]
+     * ]);
+     */
+    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.
+     */
+    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.
+     */
+    parseNode(node: ts.Node): void;
+    /**
+     * Generates a string with highlighted code segments based on the provided color scheme.
+     *
+     * This method processes the stored segments, applies the appropriate colors to each segment,
+     * and returns the resulting highlighted code as a single string.
+     *
+     * @returns The highlighted code as a string, with ANSI color codes applied to the segments.
+     */
+    highlight(): string;
+    /**
+     * Extracts a substring from the code based on the specified start and end positions.
+     *
+     * This method is used to retrieve the source code segment that corresponds to the
+     * given start and end positions. It is primarily used for highlighting specific
+     * segments of the code.
+     *
+     * @param start - The starting index of the segment to be extracted.
+     * @param end - The ending index of the segment to be extracted.
+     * @returns The extracted substring from the code.
+     */
+    private getSegmentSource;
+    /**
+     * Adds a new segment to the list of segments to be highlighted.
+     * The segment is defined by its start and end positions, the color to apply, and an optional reset code.
+     *
+     * @param start - The starting index of the segment in the code string.
+     * @param end - The ending index of the segment in the code string.
+     * @param color - The color code to apply to the segment.
+     * @param reset - The color reset code to apply after the segment, Defaults to the reset code defined in `Colors.reset`.
+     */
+    private addSegment;
+    /**
+     * Processes comments within a TypeScript AST node and adds segments for highlighting.
+     * Extracts trailing and leading comments from the node and adds them as segments using the color defined in `this.colorSchema.comments`.
+     *
+     * @param node - The TypeScript AST node whose comments are to be processed.
+     */
+    private processComments;
+    /**
+     * Processes the keywords within a TypeScript AST node and adds them as segments for highlighting.
+     *
+     * This method identifies potential keyword tokens within the provided node and adds them to the
+     * list of segments with the color defined in `this.schema.keywordColor`.
+     * The method considers the current node, its first token, and its last token to determine if they should be highlighted
+     * as keywords.
+     *
+     * The method checks if the node's kind falls within the range of keyword kinds defined by TypeScript.
+     * If the node or any of its tokens are identified as keywords, a segment is added to `this.segments`
+     * with the start and end positions of the node and the specified color for keywords.
+     *
+     * @param  node - The TypeScript AST node to be processed for keywords.
+     */
+    private processKeywords;
+    /**
+     * Processes identifiers within a TypeScript AST node and adds them as segments for highlighting
+     * based on the node's parent type.
+     *
+     * This method determines the appropriate color for an identifier based on its parent node's kind.
+     * If the parent node matches one of the specified kinds, the identifier is highlighted with a cyan color.
+     * Supported parent kinds include various declarations, expressions, and signatures.
+     *
+     * @param node - The TypeScript AST node representing the identifier to be processed.
+     */
+    private processIdentifier;
+    /**
+     * Processes a TypeScript template expression and adds segments for highlighting its literal parts.
+     *
+     * This method adds a segment for the head of the template expression with the color specified in `this.schema.stringColor`.
+     * It also processes each template span within the expression, adding
+     * segments for each span's literal part.
+     *
+     * @param templateExpression - The TypeScript template expression to be processed.
+     */
+    private processTemplateExpression;
+    /**
+     * Processes a TypeScript AST node and adds segments for highlighting based on the node's kind.
+     *
+     * This method identifies the kind of the node and determines the appropriate color for highlighting.
+     * It handles various node kinds including string literals, regular expressions, template expressions, and identifiers.
+     * Specific methods are invoked for more complex node kinds, such as template expressions and identifiers.
+     *
+     * @param  node - The TypeScript AST node to be processed.
+     */
+    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.
+ *                 Defaults to an empty object, which means no specific highlighting will be applied.
+ *
+ * @returns A string with the code elements wrapped in the appropriate color styles as specified by the schema.
+ *
+ * @example
+ * const code = 'const x: number = 42;';
+ * const schema = {
+ *   keywordColor: '\x1b[34m', // Blue
+ *   stringColor: '\x1b[32m',  // Green
+ *   numberColor: '\x1b[31m',  // Red
+ *   reset: '\x1b[0m'          // Reset
+ * };
+ * const highlightedCode = highlightCode(code, schema);
+ * console.log(highlightedCode);
+ */
+export declare function highlightCode(code: string, schema?: Partial<HighlightSchemeInterface>): string;

package/dist/esm/components/interfaces/formatter.interface.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A callback function type used 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 The formatted line string.
+ */
+export type FormatCodeCallbackType = (lineString: string, padding: number, line: number) => string;
+/**
+ * Configuration options for formatting code.
+ */
+export interface FormatCodeInterface {
+    /**
+     * The amount of padding to be applied to each line. If not specified, defaults to 0.
+     */
+    padding?: number;
+    /**
+     * The starting line number for formatting. If not specified, defaults to 1.
+     */
+    startLine?: number;
+    /**
+     * An optional action object specifying a line where a callback function should be triggered.
+     */
+    action?: {
+        /**
+         * The line number at which the callback function should be triggered.
+         */
+        triggerLine: number;
+        /**
+         * The callback function to be executed when the trigger line is encountered.
+         */
+        callback: FormatCodeCallbackType;
+    };
+}
+/**
+ * Set color to an error pointer
+ */
+export interface AnsiOptionInterface {
+    color: string;
+    reset: string;
+}

package/dist/esm/components/interfaces/highlighter.interface.d.ts

@@ -0,0 +1,48 @@
+/**
+ * HighlightSchemeInterface defines the structure for a color style schema
+ * used in semantic highlighting.
+ * This interface ensures that the highlighting styles are consistent and easily configurable.
+ */
+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 a code string that needs to be highlighted.
+ *
+ * @interface
+ *
+ * @property start - The starting index of the segment in the code string.
+ * @property end - The ending index of the segment in the code string.
+ * @property color - The color code to apply to the segment.
+ * @property reset - The color reset code to apply after the segment.
+ *
+ * @example
+ * const segment: HighlightNodeSegment = {
+ *   start: 0,
+ *   end: 10,
+ *   color: '\x1b[31m', // Red
+ *   reset: '\x1b[0m' // Reset
+ * };
+ */
+export interface HighlightNodeSegmentInterface {
+    end: number;
+    start: number;
+    color: string;
+    reset: string;
+}

package/dist/esm/components/interfaces/parse.interface.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Represents an entry in the stack trace.
+ */
+export interface StackInterface {
+    /**
+     * The function or method where the error occurred.
+     */
+    at: string;
+    /**
+     * The file path where the error occurred.
+     */
+    file: string;
+    /**
+     * The line number where the error occurred.
+     */
+    line: number;
+    /**
+     * The column number where the error occurred.
+     */
+    column: number;
+}
+/**
+ * Represents a detailed entry in the stack trace, which may include an executor stack entry.
+ */
+export interface StackEntryInterface extends StackInterface {
+    /**
+     * The executor information if the error occurred within an eval function.
+     * This will be `null` if the error did not occur within an eval function.
+     */
+    executor?: StackInterface | null;
+}

package/dist/esm/components/parser.component.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Import will remove at compile time
+ */
+import type { StackEntryInterface } from "./interfaces/parse.interface";
+/**
+ * Parses an error stack trace and returns an object with a message and an array of stack entries.
+ *
+ * @param stackString - The error stack trace.
+ * @returns The parsed stack trace object.
+ */
+export declare function parseErrorStack(stackString: string): Array<StackEntryInterface>;

package/dist/esm/index.d.ts

@@ -0,0 +1,9 @@
+export type * from "./components/interfaces/parse.interface";
+export type * from "./components/interfaces/formatter.interface";
+export type * from "./components/interfaces/highlighter.interface";
+export type * from "./services/interfaces/source.interface";
+export * from "./components/parser.component";
+export * from "./components/base64.component";
+export * from "./components/formatter.component";
+export * from "./components/highlighter.component";
+export * from "./services/source.service";