source_map_parser_node（Node SDK）

基于 Rust + WebAssembly 的高性能 Source Map 解析库（Node 环境）。提供错误堆栈解析、位置回溯与上下文提取等能力，API 返回已解析好的 JS 对象（内部已完成 JSON.parse）。

注意：本包为 Node SDK（ESM 模块）。使用前需先调用一次 init() 完成按需加载。

安装

npm install source_map_parser_node
# 或
pnpm add source_map_parser_node

Packaged skill

This npm package also ships an integration skill for AI or LLM tooling consumers.

• Installed path: node_modules/source_map_parser_node/skills/source-map-parser-node-integration/SKILL.md
• Eval prompts: node_modules/source_map_parser_node/skills/source-map-parser-node-integration/evals/evals.json

If you are building agent workflows around this package, prefer the packaged skill so usage guidance stays aligned with the published npm version.

If your agent tooling supports skills add, install the packaged skill after npm install with:

skills add ./node_modules/source_map_parser_node/skills/source-map-parser-node-integration

You can also install it directly from the GitHub repository without depending on node_modules:

skills add https://github.com/MasonChow/source-map-parser.git

快速开始

初始化

import { init } from 'source_map_parser_node';

await init(); // 仅需调用一次

映射单个位置（lookup_token）

import { init, lookup_token } from 'source_map_parser_node';
import fs from 'node:fs';

await init();

const sm = fs.readFileSync('bundle.js.map', 'utf8');
const tok = lookup_token(sm, 10, 25);
console.log(tok);
// { src, line, column, name?, source?, original? }

映射单行堆栈（map_stack_line）

import { init, map_stack_line } from 'source_map_parser_node';
import fs from 'node:fs';

await init();

const sm = fs.readFileSync('bundle.js.map', 'utf8');
const stackLine = '    at myFunction (bundle.js:10:25)';
const mapped = map_stack_line(sm, stackLine);
console.log(mapped);
// { src, line, column, name?, source?, original? }

映射完整错误堆栈（map_error_stack）

import { init, map_error_stack } from 'source_map_parser_node';
import fs from 'node:fs';

await init();

const sm = fs.readFileSync('bundle.js.map', 'utf8');
const errorStack = [
  'Error: Something went wrong',
  '    at myFunction (bundle.js:10:25)',
  '    at anotherFunction (bundle.js:15:8)',
].join('\n');

const result = map_error_stack(sm, errorStack, 2);
console.log(result.error_message);
console.log(result.frames_with_context?.length);

批量处理错误堆栈（generate_token_by_stack_raw）

当你持有“原始错误堆栈文本（含首行消息）”，并且可以按路径解析对应的 Source Map 内容时，推荐用批量 API：

import { init, generate_token_by_stack_raw } from 'source_map_parser_node';
import fs from 'node:fs';

await init();

const errorStack = [
  'Error: test',
  '    at foo (bundle.js:10:25)',
  '    at bar (bundle.js:15:8)',
].join('\n');

// 可选：统一重写源文件路径（例如附加 .map 或绝对化）
const formatter = (p: string) => p;

// 必要：按路径返回 Source Map 内容字符串
const resolver = (p: string) => {
  if (p.endsWith('bundle.js')) return fs.readFileSync('bundle.js.map', 'utf8');
  return undefined; // 无法解析的帧将被计入 fail
};

const onError = (line: string, message: string) => {
  console.warn('[map fail]', line, message);
};

const r = generate_token_by_stack_raw(errorStack, formatter, resolver, onError);
console.log(r.success.length, r.fail.length);

便捷辅助（自动 init）：mapErrorStackWithResolver

对于最常见的“拿到错误堆栈 + 我能根据路径拿到 sourcemap 内容”的场景，可以直接使用内置辅助方法；它会自动调用 init() 并返回与批量 API 同结构结果：

import { mapErrorStackWithResolver } from 'source_map_parser_node';

const mapStore = new Map<string, string>();
mapStore.set('https://example.com/app.min.js', '{"version":3,...}');

const result = await mapErrorStackWithResolver({
  errorStack: 'Error: boom\n    at fn (https://example.com/app.min.js:1:10)',
  resolveSourceMap: (p) => mapStore.get(p),
  formatter: (p) => p,
});
console.log(result.success.length);

API 参考（与导出一致，全部已 JSON.parse）

• init(): Promise

  • 说明：按需加载并缓存 wasm 模块。除 mapErrorStackWithResolver 外，使用其它 API 前需手动调用一次。

• lookup_token(sm: string, line: number, column: number): SourceMapToken | null

• lookup_token_with_context(sm: string, line: number, column: number, context_lines: number): Token | null

• lookup_context(sm: string, line: number, column: number, context_lines: number): WasmContextSnippet | null

• map_stack_line(sm: string, stack_line: string): SourceMapToken | null

• map_stack_line_with_context(sm: string, stack_line: string, context_lines: number): Token | null

• map_stack_trace(sm: string, stack_trace: string): SourceMapToken[]

• map_error_stack(sm: string, error_stack_raw: string, context_lines?: number): MappedErrorStack

• generate_token_by_single_stack(line: number, column: number, sm: string, context_offset?: number): Token | null

• generate_token_by_stack_raw(stack_raw: string, formatter?: (p: string) => string, resolver?: (p: string) => string | undefined, on_error?: (rawLine: string, message: string) => void): GenerateResult

• mapErrorStackWithResolver(options: { errorStack: string; resolveSourceMap: (p: string) => string | undefined; formatter?: (p: string) => string; onError?: (rawLine: string, message: string) => void; }): Promise

返回类型（节选）：

import type {
  SourceMapToken,
  Token,
  GenerateResult,
  MappedErrorStack,
  WasmContextSnippet,
} from 'source_map_parser_node';

可选参数使用标准的可选写法（不再使用 | null 暴露在 API 表面），内部会自动处理与 wasm 层期望的对接。

运行环境与特性

• Node.js 18+（ESM 模块）
• 内部使用 Rust + WebAssembly，性能优异
• 返回值均为已解析的 JS 对象（无需再手动 JSON.parse）

本地开发（可选）

pnpm install
pnpm run build   # 构建 wasm + 打包库 + 生成 d.ts
pnpm test        # 运行 vitest 测试

许可证

MIT License