error-stack-parser-es

error-stack-parser-es is a TypeScript rewrite of the widely used stacktracejs/error-stack-parser, distributed as native ES modules. It normalizes the wildly inconsistent Error.stack format across V8 (Chrome, Node.js, Edge), Firefox, Safari, IE, and legacy Opera into a single array of StackFrame objects carrying function name, file, line, and column information.

Alongside the full API, it ships a /lite entry point that returns a smaller StackFrameLite representation with short property names (file, line, col) and exposes a parseStack() function for parsing a raw stack string directly, without needing an actual Error instance — useful for error-tracking tools and source-map remapping pipelines that already have stack text in hand.

What You Get

• A parse(error, options?) function returning full StackFrame[] objects with functionName, fileName, lineNumber, columnNumber, args, and raw source
• A /lite entry point exporting a smaller StackFrameLite[] shape (function, file, line, col, raw) for callers who don’t need the verbose property names
• A parseStack(stackString, options?) function that parses a raw stack trace string directly, with no Error object required
• Dedicated per-engine parsers (parseV8OrIE, parseFFOrSafari, parseOpera9/10/11) exported individually for callers that already know which engine produced the stack
• An extractLocation() helper for pulling file/line/column out of a (uri:line:col)-style location string
• A slice option to trim the parsed frame list without extra allocation, and an allowEmpty option to return [] instead of throwing when no stack is present

Common Use Cases

• Normalizing crash reports in a self-hosted error-tracking or logging service that needs consistent frame data regardless of which browser/runtime an error came from
• Rendering a readable stack trace overlay in a devtools panel or in-app error boundary
• Re-parsing stack strings recovered from stored logs or serialized error payloads (via parseStack) when the original Error object is no longer available
• Feeding structured frame data into a source-map remapping step to resolve minified production stacks back to original source locations

Under The Hood

Architecture The package has a two-layer design: src/lite.ts implements all format-specific parsing logic (regex-based detection and extraction for V8/IE, Firefox/Safari, and Opera 9/10/11 stack strings) and returns the minimal StackFrameLite shape, while src/index.ts is a thin wrapper that re-exports the lite parsers and maps StackFrameLite into the richer StackFrame shape via stackframesLiteToStackframes(). There is no dependency injection or event-driven flow — it is a pure functional pipeline: an Error goes into parse(), which dispatches on engine-specific signals (error.stacktrace, or CHROME_IE_STACK_REGEXP matching against error.stack) to the correct per-engine string parser, which returns an array of frame objects. Each engine parser (parseV8OrIE, parseFFOrSafari, parseOpera9/10/11) is also exported individually so callers who already know the source engine can skip detection. The abstraction everything depends on is StackFrameLite in types.ts — changing its shape would require synchronized updates across both the lite and full API surfaces.

Tech Stack Written in TypeScript and bundled with tsdown into dual ESM output declared through package.json’s exports map (. and ./lite, plus ./package.json), shipping .d.mts type declarations. The published package has zero runtime dependencies. Dev tooling follows the author’s (antfu) standard stack: @antfu/eslint-config for linting, simple-git-hooks + nano-staged for pre-commit lint-on-staged-files, vitest for testing, tsx for the dev entrypoint, and bumpp for releases, inside a pnpm-workspace-managed single package published to npm.

Code Quality Tests live in test/fixtures.test.ts using vitest with a custom toMatchStackFrame matcher, driving assertions from an extensive captured-errors fixture covering real stack strings from Safari 6/7/8/9, Firefox 31/43/60, Chrome 15/36/46/48, IE 9/10/11, Edge 20, and Opera 9.27/10/11/25 — comprehensive fixture-based regression coverage for a parsing library, though there are no isolated unit tests for extractLocation or the slice/allowEmpty options on their own. Error handling is explicit: parse() throws a specific Error('Cannot parse given Error object') when no known engine format matches and allowEmpty isn’t set, rather than silently returning an empty array. Typing is thorough — every public function has a typed signature, options are a small ParseOptions interface, and the project compiles cleanly under tsc in CI. CI runs lint plus typecheck in one job and build plus test across Ubuntu, Windows, and macOS in a second, giving genuine cross-platform verification for a library whose entire purpose is cross-platform stack parsing.

API Design The package’s main value-add over the unmaintained original it forked from (stacktracejs/error-stack-parser) is the split between a full, verbose-property API (StackFrame, kept compatible with the original for drop-in migration) and a /lite subpath export (StackFrameLite, short properties: file, line, col) plus a parseStack() entry point for parsing a bare stack string without needing a live Error object — something the upstream project doesn’t offer. The public surface is small and consistent: one parse() function per API tier, individually-exported per-engine parsers for advanced use, and a single shared ParseOptions object (slice, allowEmpty) across every parse path. Getting started needs no configuration — import { parse } from 'error-stack-parser-es' and call it on any Error. Documentation is limited to a short README with two usage snippets, but the API surface is small enough that this is adequate; the project isn’t attempting novel parsing techniques, its value is being a well-maintained, dependency-free, ESM-native, typed continuation of an otherwise-stale original.