Alexandro.Net — @stackline/source-map-support API, runtime boundary, and migration

01 / Native boundary

Start with the platform.

For ordinary modern Node.js files, prefer native source maps. The built-in path has less global state and does not need a userland stack formatter. Use this package when a verified residual contract matters: VM-generated code, browser delivery, the historical side-effect register modules, or custom synchronous retrieval.

The intake differential on Node.js 26.8.1 mapped a normal file natively but left an otherwise equivalent vm.runInThisContext() frame at the generated location. This package mapped that VM frame when the generated filename and map were available. That bounded observation is not a claim that userland mapping is better for every Node process.

ordinary modern Nodenative source maps

residual integrationVM · browser · hooks

generated positiongenerated.js:1:1

original positionoriginal.ts:1:1

02 / Quick start

Install deliberately.

install() replaces the process-wide Error.prepareStackTrace. Disable the uncaught-exception shim when another framework or Electron integration already owns process error handling.

const sourceMapSupport = require(
  '@stackline/source-map-support'
)

sourceMapSupport.install({
  handleUncaughtExceptions: false
})

try {
  runGeneratedCode()
} catch (error) {
  console.error(error.stack)
}

03 / Public API

Six callable exports.

Open the complete API reference →

install(options?) → void

Configure global mapping

Select auto, node, or browser; add file/map retrieval handlers; optionally hook CommonJS compilation; control cache clearing and uncaught-exception handling.

mapSourcePosition(position) → position

Trace one location

Input and output use one-based lines and zero-based columns. A miss or malformed map falls back to the generated position instead of replacing the application failure.

wrapCallSite(frame, state?) → frame

Map a V8 frame

Wrap a compatible CallSite while retaining native and eval behavior. Formatting code includes copied V8 material under the separately retained BSD 3-Clause terms.

getErrorSource(error) → string | null

Show source context

Return the mapped filename, source line, and caret when source content is already available from sourcesContent or a readable local file.

retrieveSourceMap(source) → payload | null

Run retrieval providers

Resolve inline data maps, adjacent external maps, browser response headers, or synchronous custom providers into a { map, url? } payload.

resetRetrieveHandlers() → void

Restore retrieval defaults

Reset file and source-map provider lists. This does not uninstall Error.prepareStackTrace, restore process.emit, or remove a CommonJS compiler hook.

../source-map-support./register./register-hook-require./browser-source-map-support./package.jsonESM hostTypeScript 3.9+

04 / Package entries

Side effects stay visible.

The CommonJS root keeps the six-function namespace. ESM hosts receive the same object as the default export plus the same six functions as named bindings. First-party declarations distinguish modern ESM and CommonJS without converting the runtime into a second implementation.

register immediately calls install(). register-hook-require immediately calls install({ hookRequire: true }). A browser-aware bundler routes root imports to browser artifacts: ESM imports use the browser ESM host, while CommonJS uses the UMD implementation. The explicit browser deep entry remains the historical UMD file.

01
require('@stackline/source-map-support')CommonJS namespace; no install side effect
02
import sourceMapSupport from …ESM-host facade over the same CommonJS identity
03
…/registerInstalls stack formatting immediately
04
…/register-hook-requireAlso hooks Module.prototype._compile
05
…/browser-source-map-supportCommonJS, named AMD, or globalThis.sourceMapSupport
06
root + browser + importSide-effect-free browser ESM host over the same API

05 / Mapping behavior

Compatibility where it is observable.

VM code

A filename passed to vm.runInThisContext() can resolve an inline, external, or custom-provided map and produce original frames.

Map forms

The final sourceMappingURL comment wins. Inline, external, and indexed Source Map v3 sections, including offsets, names, sourceRoot, URLs, Windows paths, and embedded source text, remain covered through AnyMap.

Custom hooks

retrieveFile and retrieveSourceMap are synchronous priority providers. Override flags replace the defaults; otherwise a miss can fall through.

Browser retrieval

The browser mode can use synchronous XHR plus SourceMap or X-SourceMap headers. Origin policy still applies; preloaded custom maps avoid implicit I/O.

Malformed input

Malformed maps, strict browser atob() failures, and mapping lookup failures preserve the generated location. Misses are cached and special keys do not share Object.prototype.

Retention

Generated files without a map are released after discovery instead of remaining indefinitely in the content cache. Maps and inline sources that are used can still be cached.

Error formatting

Uncaught Error.cause rendering and an existing nonzero exit code are retained. Differently named properties keep current native V8 formatting such as Object.doSomething [as customMethod].

Production graph

Exact @jridgewell/trace-mapping@0.3.31 replaces the historical parser graph. Its AnyMap constructor handles regular and indexed/sectioned maps through two exact MIT transitive packages.

06 / Browser contract

A bundle, not a universal promise.

The ES2015-targeted UMD file exposes a CommonJS value, the named AMD module browser-source-map-support, or globalThis.sourceMapSupport. Browser-aware root ESM imports resolve to a companion ESM host with the same default/named identities. Both artifacts resolve relative map/source paths without a Node process global and fail back on malformed inline base64. Direct mapping and both browser root routes are tested. Automatic stack rewriting still depends on a compatible V8-style stack API and accessible map data.

<script src="/vendor/browser-source-map-support.js"></script>
<script>
  sourceMapSupport.install({
    environment: 'browser',
    handleUncaughtExceptions: false,
    retrieveSourceMap(source) {
      return preloadedMaps[source] || null
    }
  })
</script>

07 / Migration

Choose the smallest owner change.

Full migration checklist →

Lowest application diff

Alias the dependency

"source-map-support":
  "npm:@stackline/source-map-support@1.0.0"

Existing root imports, source-map-support/register, and webpack externals keep the historical key. Commit the manifest and lockfile together.

Explicit residual use

Use the scoped entries

import sourceMapSupport, {
  install
} from
  '@stackline/source-map-support'

Use the package only in processes that need its residual contract. Prefer native mapping for ordinary Node entrypoints and keep mapping ownership explicit.

Re-test in your application VM filenamesregular and indexed mapsElectron main/rendererwebpack externalscustom retrieversError.prepareStackTraceuncaught exit codesbrowser origin policy

08 / Process and input boundary

Stack formatting is global and synchronous.

install() owns Error.prepareStackTrace. It can also wrap process.emit and Module.prototype._compile. Those hooks affect unrelated libraries in the same process, can conflict with profilers or test runners, and are not removed by resetRetrieveHandlers(). Install once, preserve any prior formatter your integration needs, and test the complete process.

Default Node retrieval reads generated files and referenced maps synchronously. Browser retrieval can make synchronous XHR requests. Custom handlers run during stack work and must be bounded, trusted, synchronous, and responsible for their own failures. The package does not impose byte, source-count, nesting, filesystem-root, URL, or network limits.

Source maps and sourcesContent can expose original source code and secrets. Treat production map publication as a separate security decision. Malformed-input hardening and retention corrections are defense-in-depth; no vulnerability, advisory, or CVE is claimed.

Read the complete safe-use boundary →

09 / Provenance

Two upstream license layers remain.

Runtime

Copied V8 code

CallSiteToString includes code copied almost verbatim from V8 4.3.49. The V8 BSD 3-Clause terms are retained separately.

Dependencies

The three exact @jridgewell production components are MIT-licensed. Packed browser artifacts bundle those three plus path-browserify@1.0.1; all four exact MIT texts are retained.

Independence

This is an independent continuation. It is not affiliated with or endorsed by Evan Wallace, the upstream project, V8, Google, Justin Ridgewell, or the @jridgewell projects.

10 / Reference files

The residual contract is inspectable.

READMEInstall, native boundary, entries API referenceFunctions, options, types CompatibilityPreserved and corrected behavior MigrationNative, alias, scoped use SecurityGlobal hooks and input limits LicensesMIT, V8 BSD, installed and browser graphs CommonJS exampleExplicit process installation ESM exampleDefault and named identity VM exampleInline map for generated code Custom-hook examplePreloaded virtual source map Browser exampleStandalone bundle and map hook Changelog1.0.0 maintenance changes Machine referenceCompact complete contract Package metadataEntries, graph, provenance