@srcmap/sourcemap 0.1.2 → 0.2.0

package/README.md

@@ -0,0 +1,95 @@
+# @srcmap/sourcemap
+
+[![npm](https://img.shields.io/npm/v/@srcmap/sourcemap.svg)](https://www.npmjs.com/package/@srcmap/sourcemap)
+[![CI](https://github.com/BartWaardenburg/srcmap/actions/workflows/ci.yml/badge.svg)](https://github.com/BartWaardenburg/srcmap/actions/workflows/ci.yml)
+[![Coverage](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/BartWaardenburg/srcmap/badges/coverage.json)](https://github.com/BartWaardenburg/srcmap/actions/workflows/coverage.yml)
+
+High-performance source map parser and consumer powered by Rust via [NAPI](https://napi.rs).
+
+Parses source map JSON and provides position lookups. Implements [ECMA-426](https://tc39.es/ecma426/) (Source Map v3). Alternative to [`@jridgewell/trace-mapping`](https://github.com/jridgewell/trace-mapping).
+
+> For batch lookups in Node.js, consider [`@srcmap/sourcemap-wasm`](https://www.npmjs.com/package/@srcmap/sourcemap-wasm) which avoids NAPI per-call overhead and is faster for bulk operations.
+
+## Install
+
+```bash
+npm install @srcmap/sourcemap
+```
+
+Prebuilt binaries are available for:
+- macOS (x64, arm64)
+- Linux (x64, arm64, glibc + musl)
+- Windows (x64)
+
+## Usage
+
+```js
+import { SourceMap } from '@srcmap/sourcemap';
+
+const sm = new SourceMap(jsonString);
+
+// Forward lookup: generated -> original (0-based lines and columns)
+const loc = sm.originalPositionFor(42, 10);
+// { source: 'src/app.ts', line: 10, column: 4, name: 'handleClick' }
+// Returns null if no mapping exists
+
+// Reverse lookup: original -> generated
+const pos = sm.generatedPositionFor('src/app.ts', 10, 4);
+// { line: 42, column: 10 }
+
+// Batch lookup — amortizes NAPI overhead
+const positions = [42, 10, 43, 0, 44, 5];
+const results = sm.originalPositionsFor(positions);
+// number[] [srcIdx, line, col, nameIdx, ...]
+// -1 means no mapping / no name
+
+// Resolve indices
+const source = sm.source(results[0]);
+const name = results[3] >= 0 ? sm.name(results[3]) : null;
+```
+
+## API
+
+### `new SourceMap(json: string)`
+
+Parse a source map from a JSON string.
+
+### Instance methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `originalPositionFor(line, column)` | `{ source, line, column, name } \| null` | Forward lookup (0-based) |
+| `generatedPositionFor(source, line, column)` | `{ line, column } \| null` | Reverse lookup (0-based) |
+| `originalPositionsFor(positions: number[])` | `number[]` | Batch forward lookup |
+| `source(index)` | `string` | Resolve source index to filename |
+| `name(index)` | `string` | Resolve name index to string |
+
+### Instance properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `lineCount` | `number` | Number of generated lines |
+| `mappingCount` | `number` | Total decoded mappings |
+| `hasRangeMappings` | `boolean` | Whether any range mappings exist |
+| `rangeMappingCount` | `number` | Number of range mappings |
+| `sources` | `string[]` | All source filenames |
+| `names` | `string[]` | All names |
+
+## Performance
+
+| Operation | @srcmap/sourcemap | @jridgewell/trace-mapping |
+|-----------|-------------------|---------------------------|
+| 1000x batch lookup (large) | 160 us | 15 us |
+| Single lookup | 345 ns | 24 ns |
+
+NAPI has ~300ns overhead per call. For bulk operations, use the batch API (`originalPositionsFor`) or consider the [WASM package](https://www.npmjs.com/package/@srcmap/sourcemap-wasm) which has lower per-call overhead.
+
+## Part of [srcmap](https://github.com/BartWaardenburg/srcmap)
+
+High-performance source map tooling written in Rust. See also:
+- [`@srcmap/codec`](https://www.npmjs.com/package/@srcmap/codec) - VLQ codec (NAPI)
+- [`@srcmap/sourcemap-wasm`](https://www.npmjs.com/package/@srcmap/sourcemap-wasm) - Source map parser (WASM, recommended for batch ops)
+
+## License
+
+MIT

package/index.d.ts

@@ -1,42 +1,166 @@
+/**
+ * An original source position resolved from a generated position.
+ *
+ * All values are 0-based. Use `source` and `name` directly as resolved strings.
+ */
 export interface OriginalPosition {
+  /** Original source filename (e.g. `"src/app.ts"`). */
   source: string | null
+  /** 0-based line in the original source. */
   line: number
+  /** 0-based column in the original source. */
   column: number
+  /** Original identifier name, if available. */
   name: string | null
 }
 
+/**
+ * A generated position resolved from an original source position.
+ *
+ * All values are 0-based.
+ */
 export interface GeneratedPosition {
+  /** 0-based line in the generated output. */
   line: number
+  /** 0-based column in the generated output. */
   column: number
 }
 
+/**
+ * High-performance source map parser and consumer powered by Rust via NAPI.
+ *
+ * Parses source map JSON (v3 / ECMA-426) and provides O(log n) position lookups.
+ * Supports regular and indexed (sectioned) source maps.
+ *
+ * @example
+ * ```ts
+ * import { SourceMap } from '@srcmap/sourcemap'
+ *
+ * const sm = new SourceMap(jsonString)
+ *
+ * // Forward lookup: generated -> original (0-based)
+ * const loc = sm.originalPositionFor(42, 10)
+ * if (loc) {
+ *   console.log(`${loc.source}:${loc.line}:${loc.column}`)
+ * }
+ *
+ * // Reverse lookup: original -> generated (0-based)
+ * const pos = sm.generatedPositionFor('src/app.ts', 10, 4)
+ * ```
+ */
 export declare class SourceMap {
-  /** Parse a source map from a JSON string. Supports regular and indexed (sectioned) maps. */
+  /**
+   * Parse a source map from a JSON string.
+   *
+   * Accepts both regular source maps and indexed source maps with `sections`.
+   *
+   * @param json - Source map JSON string (must have `"version": 3`)
+   * @throws If the JSON is invalid or the source map version is unsupported
+   */
   constructor(json: string)
 
-  /** Look up the original source position for a generated position. 0-based line and column. */
+  /**
+   * Look up the original source position for a generated position.
+   *
+   * Uses greatest-lower-bound search (finds the closest mapping at or before the column).
+   *
+   * @param line - 0-based generated line
+   * @param column - 0-based generated column
+   * @returns The original position, or `null` if no mapping exists
+   */
   originalPositionFor(line: number, column: number): OriginalPosition | null
 
-  /** Look up the generated position for an original source position. 0-based line and column. */
+  /**
+   * Look up the original source position with a search bias.
+   *
+   * @param line - 0-based generated line
+   * @param column - 0-based generated column
+   * @param bias - `0` for greatest-lower-bound (default), `-1` for least-upper-bound
+   * @returns The original position, or `null` if no mapping exists
+   */
+  originalPositionForWithBias(line: number, column: number, bias: 0 | -1): OriginalPosition | null
+
+  /**
+   * Look up the generated position for an original source position.
+   *
+   * Uses least-upper-bound search (finds the first mapping at or after the position).
+   *
+   * @param source - Original source filename (e.g. `"src/app.ts"`)
+   * @param line - 0-based original line
+   * @param column - 0-based original column
+   * @returns The generated position, or `null` if no mapping exists
+   */
   generatedPositionFor(source: string, line: number, column: number): GeneratedPosition | null
 
   /**
-   * Batch lookup: find original positions for multiple generated positions.
-   * Takes a flat array [line0, col0, line1, col1, ...].
-   * Returns a flat array [srcIdx0, line0, col0, nameIdx0, srcIdx1, ...].
-   * -1 means no mapping found / no name.
+   * Look up the generated position with a search bias.
+   *
+   * @param source - Original source filename
+   * @param line - 0-based original line
+   * @param column - 0-based original column
+   * @param bias - `0` for default, `-1` for least-upper-bound, `1` for greatest-lower-bound
+   * @returns The generated position, or `null` if no mapping exists
+   */
+  generatedPositionForWithBias(source: string, line: number, column: number, bias: -1 | 0 | 1): GeneratedPosition | null
+
+  /**
+   * Batch forward lookup for multiple generated positions.
+   *
+   * Amortizes NAPI overhead by processing all positions in a single call.
+   * Input is a flat array of `[line0, col0, line1, col1, ...]` pairs.
+   * Output is a flat array of `[srcIdx0, line0, col0, nameIdx0, ...]` quads.
+   * `-1` indicates no mapping found or no name.
+   *
+   * @param positions - Flat array of 0-based `[line, column]` pairs
+   * @returns Flat array of `[sourceIndex, line, column, nameIndex]` quads
+   *
+   * @example
+   * ```ts
+   * const positions = [42, 10, 43, 0, 44, 5]
+   * const results = sm.originalPositionsFor(positions)
+   * // results: [srcIdx, line, col, nameIdx, srcIdx, line, col, nameIdx, ...]
+   * const source = results[0] >= 0 ? sm.source(results[0]) : null
+   * ```
    */
   originalPositionsFor(positions: number[]): number[]
 
-  /** Source file paths. */
-  get sources(): string[]
+  /**
+   * Resolve a source index to a source filename.
+   *
+   * @param index - Source index from a lookup result
+   * @returns The source filename
+   */
+  source(index: number): string
+
+  /**
+   * Resolve a name index to a name string.
+   *
+   * @param index - Name index from a lookup result
+   * @returns The name string
+   */
+  name(index: number): string
+
+  /** All source filenames in the source map. */
+  readonly sources: string[]
+
+  /** All names in the source map. */
+  readonly names: string[]
+
+  /** Debug ID (UUID) for associating generated files with source maps (ECMA-426). */
+  readonly debugId: string | null
+
+  /** Total number of decoded mappings. */
+  readonly mappingCount: number
+
+  /** Number of generated lines covered by mappings. */
+  readonly lineCount: number
 
-  /** Name identifiers. */
-  get names(): string[]
+  /** Whether the source map contains range mappings. */
+  readonly hasRangeMappings: boolean
 
-  /** Total number of decoded mapping segments. */
-  get mappingCount(): number
+  /** Number of range mappings in the source map. */
+  readonly rangeMappingCount: number
 
-  /** Number of generated lines. */
-  get lineCount(): number
+  /** Get the encoded range mappings string, or null if none. */
+  encodedRangeMappings(): string | null
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@srcmap/sourcemap",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "High-performance source map parser and consumer powered by Rust",
   "main": "index.js",
   "types": "index.d.ts",
@@ -26,27 +26,36 @@
   "license": "MIT",
   "files": [
     "index.js",
-    "index.d.ts"
+    "index.d.ts",
+    "README.md"
   ],
   "optionalDependencies": {
-    "@srcmap/sourcemap-darwin-x64": "0.1.2",
-    "@srcmap/sourcemap-darwin-arm64": "0.1.2",
-    "@srcmap/sourcemap-linux-x64-gnu": "0.1.2",
-    "@srcmap/sourcemap-linux-x64-musl": "0.1.2",
-    "@srcmap/sourcemap-linux-arm64-gnu": "0.1.2",
-    "@srcmap/sourcemap-linux-arm64-musl": "0.1.2",
-    "@srcmap/sourcemap-win32-x64-msvc": "0.1.2"
+    "@srcmap/sourcemap-darwin-x64": "0.1.3",
+    "@srcmap/sourcemap-darwin-arm64": "0.1.3",
+    "@srcmap/sourcemap-linux-x64-gnu": "0.1.3",
+    "@srcmap/sourcemap-linux-x64-musl": "0.1.3",
+    "@srcmap/sourcemap-linux-arm64-gnu": "0.1.3",
+    "@srcmap/sourcemap-linux-arm64-musl": "0.1.3",
+    "@srcmap/sourcemap-win32-x64-msvc": "0.1.3"
+  },
+  "dependencies": {
+    "detect-libc": "^2.0.0"
   },
   "devDependencies": {
     "@napi-rs/cli": "^3.0.0"
   },
   "scripts": {
+    "artifacts": "napi artifacts",
     "build": "napi build --release --platform",
-    "build:debug": "napi build --platform"
+    "build:debug": "napi build --platform",
+    "test": "node --test __tests__/sourcemap.test.mjs",
+    "test:coverage": "mkdir -p coverage && node --test --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=coverage/lcov.info --test-reporter=spec --test-reporter-destination=stdout __tests__/sourcemap.test.mjs",
+    "prepublishOnly": "napi prepublish -t npm",
+    "version": "napi version"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/BartWaardenburg/srcmap"
+    "url": "git+https://github.com/BartWaardenburg/srcmap.git"
   },
   "keywords": [
     "sourcemap",