@remotex-labs/xmap 1.0.0

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

@@ -0,0 +1,147 @@
+/**
+ * Import will remove at compile time
+ */
+import type { PositionInterface, SourceMapInterface, SourceOptionsInterface, PositionSourceInterface } from './interfaces/source.interface';
+/**
+ * Imports
+ */
+import { Bias } from './interfaces/source.interface';
+/**
+ * A service for validating and processing source maps.
+ */
+export declare class SourceService {
+    /**
+     * A list of symbol names used by the “mappings” entry.
+     */
+    private readonly names;
+    /**
+     * An array of source file paths.
+     */
+    private readonly sources;
+    /**
+     * A string of base64 VLQ-encoded mappings.
+     */
+    private readonly mappings;
+    /**
+     * An array of source files contents.
+     */
+    private readonly sourcesContent;
+    /**
+     * Creates a new SourceService instance.
+     *
+     * @param source - The source map object to be validated.
+     * @throws Error If any required key is missing from the source map.
+     */
+    constructor(source: SourceMapInterface);
+    /**
+     * Returns a plain object representation of the source map data.
+     *
+     * This method creates a new object containing essential source map properties:
+     * - `version`: The version of the source map (typically 3).
+     * - `names`: An array of function or variable names from the original source code.
+     * - `sources`: An array of source file names referenced in the mappings.
+     * - `mappings`: A string representation of the encoded source map mappings. (Generated by `encodeMappings`)
+     * - `sourcesContent`: An optional array containing the content of the source files. (May not be present in all source maps)
+     *
+     * @returns A plain object representing the source map data.
+     */
+    getMapObject(): SourceMapInterface;
+    /**
+     * Retrieves source code information for a given line and column in the generated code.
+     *
+     * @param line - The line number in the generated code.
+     * @param column - The column number in the generated code.
+     * @param options - Optional configuration for retrieving source information.
+     *   linesBefore (default: 3) - Number of lines before the matching source line to include.
+     *   linesAfter (default: 4) - Number of lines after the matching source line to include.
+     *   includeSourceContent (default: false) - Flag to include the relevant source code snippet.
+     * @returns An object containing source location information (line, column, name, source)
+     *         or including source code (code) if the includeSourceContent flag is set.
+     *         Returns null if no matching mapping is found.
+     */
+    getSourcePosition(line: number, column: number, options?: SourceOptionsInterface): PositionSourceInterface | null;
+    /**
+     * Retrieves the position information in the original source code for a given line and column in the generated code.
+     *
+     * @param line - The line number in the generated code.
+     * @param column - The column number in the generated code.
+     * @param bias - An optional bias value specifying how to handle cases where only the line number matches. Defaults to Bias.LOWER_BOUND.
+     *               Bias.LOWER_BOUND: If the line number matches but the column is less, return the closest mapping with a lower column.
+     *               Bias.UPPER_BOUND: If the line number matches but the column is greater, return the closest mapping with a higher column.
+     *               Bias.BOUND: If the line number matches and the column doesn't, return null (default behavior).
+     * @returns A PositionInterface object representing the position in the original source code, or null if no matching position is found.
+     */
+    getPosition(line: number, column: number, bias?: Bias): PositionInterface | null;
+    /**
+     * Merges multiple source maps into this source map object.
+     * The order of the provided source maps must match the order in which the corresponding source files were concatenated.
+     *
+     * @param maps - An array of `SourceService` instances representing the source maps to be merged.
+     * @throws Error - If no source maps are provided for concatenation.
+     */
+    concat(...maps: Array<SourceMapInterface>): void;
+    /**
+     * Converts the source map object to a base64 encoded string representation.
+     *
+     * This method performs the following steps:
+     * 1. Creates a plain object representation of the source map using `getMapObject`.
+     * 2. Convert the plain object to a JSON string using `JSON.stringify`.
+     * 3. Encodes the JSON string using the `encode` function (assumed to be a base64 encoding function).
+     *
+     * @returns A string representing the source map.
+     */
+    toString(): string;
+    /**
+     * Validates the provided source map object.
+     *
+     * This private method throws an error if any of the required keys are missing from the source map.
+     *
+     * @private
+     * @param input - The source map object to be validated.
+     * @throws Error If any required key is missing from the source map.
+     */
+    private validateSourceMap;
+    /**
+     * Decodes and processes the encoded mappings.
+     *
+     *  @param encodedMappings - The source map object to be decoded.
+     * @param thresholdSegment
+     */
+    private decodeMappings;
+    /**
+     * Processes a decoded segment and updates the mappings.
+     *
+     * @param shift - The current state of the mapping information.
+     * @param decodedSegment - The decoded VLQ segment.
+     * @param generatedLine - The current line index in the generated code.
+     */
+    private decodedSegment;
+    /**
+     * Encodes the mappings into a VLQ string.
+     *
+     * @param mappings - An array of MappingInterface objects to encode.
+     * @returns A VLQ-encoded string representing the mappings.
+     */
+    private encodeMappings;
+    /**
+     * Encodes a single segment of the mappings.
+     *
+     * @param map - The MappingInterface object representing a single mapping.
+     * @param segments - An array of encoded segments.
+     * @param shift - The current state of the mapping information.
+     */
+    private encodeSegment;
+    /**
+     * Performs a binary search on the internal `mappings` array to find a mapping object based on the line and column information.
+     * This function utilizes a binary search algorithm to efficiently locate the mapping corresponding to a specific line and column in the generated code.
+     *
+     * @param targetLine - The line number in the generated code to search for.
+     * @param targetColumn - The column number in the generated code to search for.
+     * @param bias - An optional bias value specifying how to handle cases where only the line number matches (DEFAULT: Bias.BOUND).
+     *                 Bias.LOWER_BOUND: If the line number matches but the column is less, return the closest mapping with a lower column.
+     *                 Bias.UPPER_BOUND: If the line number matches but the column is greater, return the closest mapping with a higher column.
+     *                 Bias.BOUND: If the line number matches and the column doesn't, return null (default behavior).
+     * @returns A MappingInterface object representing the found mapping, or null if no matching mapping is found based on the bias.
+     */
+    private findMapping;
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+    "type": "module",
+    "name": "@remotex-labs/xmap",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "author": "Garefild",
+    "version": "1.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",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/remotex-lab/xMap.git"
+    },
+    "bugs": {
+        "url": "https://github.com/remotex-lab/xMap/issues"
+    },
+    "keywords": [
+        "xmap",
+        "xMap",
+        "sourcemap",
+        "parser",
+        "typescript",
+        "formatter",
+        "CLI",
+        "syntax-highlighting",
+        "code-formatting",
+        "javascript",
+        "debugging",
+        "developer-tools",
+        "typescript runner"
+    ],
+    "engines": {
+        "node": ">=18"
+    },
+    "files": [
+        "dist",
+        "LICENSE",
+        "README.md"
+    ],
+    "scripts": {
+        "dev": "xBuild -w",
+        "build": "xBuild",
+        "lint": "tsc -noEmit && eslint . -c ./eslint.config.mjs",
+        "test": "jest",
+        "test:coverage": "jest --coverage",
+        "ci:test": "jest",
+        "ci:clean": "rm -rf ./dist",
+        "ci:build": "npm run build"
+    },
+    "devDependencies": {
+        "@remotex-labs/xbuild": "^0.0.1-beta.4",
+        "@swc/jest": "^0.2.36",
+        "@types/jest": "^29.5.12",
+        "@types/node": "^22.5.1",
+        "eslint": "^9.9.1",
+        "eslint-plugin-jsdoc": "^50.2.2",
+        "jest": "^29.7.0",
+        "typescript-eslint": "^8.3.0"
+    },
+    "dependencies": {
+        "typescript": "^5.5.4"
+    }
+}