@remotex-labs/xmap 2.0.4 → 3.0.0

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

@@ -1,217 +1,216 @@
 /**
  * Import will remove at compile time
  */
-import type { PositionInterface, SourceMapInterface, SourceOptionsInterface, PositionWithCodeInterface, PositionWithContentInterface } from "./interfaces/source.interface";
+import type { PositionInterface, SourceMapInterface, SourceOptionsInterface, PositionWithCodeInterface, PositionWithContentInterface } from "./interfaces/source-service.interface";
 /**
  * Imports
  */
 import { MappingProvider } from "../providers/mapping.provider";
-import { Bias } from "../providers/interfaces/mapping.interface";
+import { Bias } from "../providers/interfaces/mapping-provider.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.
+ * 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); // Outputs: 'bundle.js'
+ * console.log(sourceService.file); // 'bundle.js'
  * ```
+ *
+ * @since 1.0.0
  */
 export declare class SourceService {
     /**
-     * The name of the generated file (bundle) that this source map applies to.
+     * The name of the generated file this source map applies to.
      *
-     * @example
-     * ```ts
-     * console.log(sourceService.file); // 'bundle.js'
-     * ```
+     * @since 1.0.0
      */
     readonly file: string | null;
     /**
-     * A MappingProvider instance of base64 VLQ-encoded mappings.
+     * Provider for accessing and manipulating the base64 VLQ-encoded mappings.
+     *
+     * @since 1.0.0
      */
     readonly mappings: MappingProvider;
     /**
-     * The root URL for the sources, if present in the source map.
+     * The root URL for resolving relative paths in the source files.
+     * @since 1.0.0
      */
     readonly sourceRoot: string | null;
     /**
-     * A list of symbol names used by the “mappings” entry.
+     * List of symbol names referenced by the mappings.
+     * @since 1.0.0
      */
     readonly names: Array<string>;
     /**
-     * An array of source file paths.
+     * Array of source file paths.
+     * @since 1.0.0
      */
     readonly sources: Array<string>;
     /**
-     * An array of source files contents.
+     * Array of source file contents.
+     * @since 1.0.0
      */
     readonly sourcesContent: Array<string>;
     /**
-     * Creates a new instance of the `SourceService` class.
+     * Creates a new SourceService instance.
      *
-     * 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 - Source map data (SourceService, SourceMapInterface object, or JSON string)
+     * @param file - Optional file name for the generated bundle
      *
-     * @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.
+     * @throws Error - When a source map has an invalid format or missing required properties
      *
-     * @example
-     * ```ts
-     * const sourceMapJSON = '{"version": 3, "file": "bundle.js", "sources": ["foo.ts"], "names": [], "mappings": "AAAA"}';
-     * const sourceService = new SourceService(sourceMapJSON);
-     * ```
+     * @since 1.0.0
      */
     constructor(source: SourceService);
     constructor(source: SourceMapInterface | string, file?: string | null);
     /**
-     * Converts the current source map data into a plain object format.
+     * Converts the source map data to a plain object.
      *
-     * @returns The source map json 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 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.
+     * Concatenates additional source maps into the current instance.
      *
-     * @param maps - An array of `SourceMapInterface` or `SourceService` instances to be concatenated.
-     * @throws { Error } If no source maps are provided for concatenation.
+     * @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 instance of `SourceService` with concatenated source maps.
+     * Creates a new SourceService instance 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.
+     * @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.file); // The file from the new source map
+     * console.log(newService.sources); // Combined sources array
      * ```
+     *
+     * @throws Error - When no maps are provided
+     *
+     * @since 1.0.0
      */
     concatNewMap(...maps: Array<SourceMapInterface | SourceService>): SourceService;
     /**
-     * Retrieves the position information based on the original source line and column.
+     * Finds position in generated code based on original source position.
      *
-     * @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.
+     * @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?.line); // The line number in the original source
+     * console.log(position?.generatedLine); // Line in generated code
      * ```
+     *
+     * @since 1.0.0
      */
     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.
+     * 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 - 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.
+     * @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); // The original source file
+     * console.log(position?.source); // Original source file
      * ```
+     *
+     * @since 1.0.0
      */
     getPosition(line: number, column: number, bias?: Bias): PositionInterface | null;
     /**
-     * Retrieves the position and original source content for a given position in the generated code.
+     * 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 - Bias used for position matching.
-     * @returns { PositionWithContentInterface | null } The position and its associated content, or `null` if not found.
+     * @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 positionWithContent = sourceService.getPositionWithContent(3, 5);
-     * console.log(positionWithContent?.sourcesContent); // The source code content
+     * 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 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.
+     * 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 - 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.
+     * @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 positionWithCode = sourceService.getPositionWithCode(4, 8, Bias.BOUND, { linesBefore: 2, linesAfter: 2 });
-     * console.log(positionWithCode?.code); // The code snippet from the original source
+     * 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;
     /**
-     * Converts the current source map object to a JSON string.
+     * Serializes the source map to a JSON string.
      *
-     * @returns A stringified version of the source map object.
+     * @returns JSON string representation of the source map
      *
      * @example
      * ```ts
-     * console.log(sourceService.toString()); // JSON string of the source map
+     * const jsonString = sourceService.toString();
+     * console.log(jsonString); // '{"version":3,"file":"bundle.js",...}'
      * ```
+     *
+     * @since 1.0.0
      */
     toString(): string;
     /**
-     * Validates the provided source map object.
+     * Validates a source map object has all required properties.
      *
-     * This method checks whether all required keys are present in the source map object.
-     * It throws an error if any required keys are missing.
+     * @param input - Source map object to validate
      *
-     * @private
-     * @param input - The source map object to be validated.
-     * @throws Error If any required key is missing from the source map.
+     * @throws Error - When required properties are missing
      *
-     * @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
-     * ```
+     * @since 1.0.0
      */
     private validateSourceMap;
 }

package/package.json

@@ -5,7 +5,7 @@
     "types": "./dist/index.d.ts",
     "module": "./dist/esm/index.js",
     "author": "Garefild",
-    "version": "2.0.4",
+    "version": "3.0.0",
     "license": "Mozilla Public License Version 2.0",
     "description": "A library with a sourcemap parser and TypeScript code formatter for the CLI",
     "homepage": "https://github.com/remotex-lab/xMap",
@@ -37,14 +37,40 @@
     "exports": {
         "./package.json": "./package.json",
         ".": {
+            "types": "./dist/index.d.ts",
             "import": {
-                "types": "./dist/index.d.ts",
                 "default": "./dist/esm/index.js"
             },
             "require": {
-                "types": "./dist/index.d.ts",
                 "default": "./dist/cjs/index.js"
             }
+        },
+        "./parser.component": {
+            "types": "./dist/components/parser.component.d.ts",
+            "import": {
+                "default": "./dist/esm/parser.component.js"
+            },
+            "require": {
+                "default": "./dist/cjs/parser.component.js"
+            }
+        },
+        "./formatter.component": {
+            "types": "./dist/components/formatter.component.d.ts",
+            "import": {
+                "default": "./dist/esm/formatter.component.js"
+            },
+            "require": {
+                "default": "./dist/cjs/formatter.component.js"
+            }
+        },
+        "./highlighter.component": {
+            "types": "./dist/components/highlighter.component.d.ts",
+            "import": {
+                "default": "./dist/esm/highlighter.component.js"
+            },
+            "require": {
+                "default": "./dist/cjs/highlighter.component.js"
+            }
         }
     },
     "files": [
@@ -64,15 +90,15 @@
     },
     "devDependencies": {
         "jest": "^29.7.0",
-        "eslint": "^9.13.0",
-        "typescript-eslint": "^8.11.0",
-        "eslint-plugin-jsdoc": "^50.4.3",
-        "@swc/jest": "^0.2.36",
-        "@types/jest": "^29.5.13",
-        "@types/node": "^22.7.8",
-        "@remotex-labs/xbuild": "^1.3.1"
+        "eslint": "^9.22.0",
+        "typescript-eslint": "^8.27.0",
+        "eslint-plugin-tsdoc": "^0.4.0",
+        "@swc/jest": "^0.2.37",
+        "@types/jest": "^29.5.14",
+        "@types/node": "^22.13.11",
+        "@remotex-labs/xbuild": "^1.5.3"
     },
     "dependencies": {
-        "typescript": "^5.6.3"
+        "typescript": "^5.8.2"
     }
 }

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

@@ -1,48 +0,0 @@
-/**
- * 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/components/interfaces/parse.interface.d.ts

@@ -1,31 +0,0 @@
-/**
- * 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/providers/interfaces/mapping.interface.d.ts

@@ -1,52 +0,0 @@
-/**
- * Represents a mapping segment that corresponds to a position in the source map.
- *
- * @property line - The original line number in the source file.
- * @property column - The original column number in the source file.
- * @property nameIndex - The index of the symbol name in the source map, or `null` if there is no associated name.
- * @property sourceIndex - The index of the source file in the source map.
- * @property generatedLine - The line number in the generated code.
- * @property generatedColumn - The column number in the generated code.
- */
-export interface SegmentInterface {
-    line: number;
-    column: number;
-    nameIndex: number | null;
-    sourceIndex: number;
-    generatedLine: number;
-    generatedColumn: number;
-}
-/**
- * Extends the `SegmentInterface` to represent an offset segment used during mapping calculations.
- * The main difference is that `nameIndex` is always a number.
- *
- * @augments { SegmentInterface }
- * @property nameIndex - The index of the symbol name in the source map (cannot be null in this context).
- */
-export interface SegmentOffsetInterface extends SegmentInterface {
-    nameIndex: number;
-}
-/**
- * Represents the bias used when searching for segments in the source map.
- * This enum is useful for determining the preferred matching behavior
- * when the exact line and column cannot be found.
- *
- * @property BOUND - No preference for column matching; returns the first match found.
- * @property LOWER_BOUND - Prefer the closest mapping with a lower column value.
- * @property UPPER_BOUND - Prefer the closest mapping with a higher column value.
- */
-export declare const enum Bias {
-    BOUND = 0,
-    LOWER_BOUND = 1,
-    UPPER_BOUND = 2
-}
-/**
- * A type alias for a frame in the source map, representing an array of segments.
- * Each frame consists of multiple mapping segments for a given line in the generated code.
- */
-export type FrameType = Array<SegmentInterface>;
-/**
- * A type alias for the source map, where each entry represents a frame of mappings.
- * A frame can either be an array of segments (frame) or `null` if the line has no mappings (represented by a semicolon in the mapping string).
- */
-export type MapType = Array<null | FrameType>;

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

@@ -1,53 +0,0 @@
-/**
- * Represents a source map structure used for mapping code within a file
- * to its original source. Source maps are essential for debugging minified
- * or transpiled code, as they allow developers to trace back to the
- * original source files and understand the context of the code execution.
- *
- * @interface SourceMapInterface
- * @property file - The generated file's name that the source map is associated with.
- * This property is optional and may be null if not specified.
- * @property names - An array of variable/function names that are present in the original source.
- * These names help in mapping the original code context during debugging.
- * @property version - The version of the source map specification.
- * This should be set to `3` for the standard source map version.
- * @property sources - An array of URLs or paths to the original source files.
- * These sources are used to locate the original code that corresponds to the generated code.
- * @property mappings - A VLQ (Variable-Length Quantity) encoded string that describes how to map the
- * generated code back to the original source code. This property is crucial for the correct functioning of the source map.
- * @property sourceRoot - An optional root URL for the sources.
- * It can be used to specify a base path for resolving the sources, which may be null if not applicable.
- * @property sourcesContent - An optional array containing the content of the original source files.
- * This property can be useful when the original files are not available at runtime.
- */
-export interface SourceMapInterface {
-    file?: string | null;
-    names: Array<string>;
-    version: number;
-    sources: Array<string>;
-    mappings: string;
-    sourceRoot?: string | null;
-    sourcesContent?: Array<string>;
-}
-export interface PositionInterface {
-    name: string | null;
-    line: number;
-    column: number;
-    source: string;
-    sourceRoot: string | null;
-    sourceIndex: number;
-    generatedLine: number;
-    generatedColumn: number;
-}
-export interface PositionWithContentInterface extends PositionInterface {
-    sourcesContent: string;
-}
-export interface PositionWithCodeInterface extends PositionInterface {
-    code: string;
-    endLine: number;
-    startLine: number;
-}
-export interface SourceOptionsInterface {
-    linesAfter?: number;
-    linesBefore?: number;
-}