Alexandro.Net

Download README · GitHub release

@stackline/source-map-resolve

Compatibility-first source map and source resolver with maintained packaging, browser builds, and first-party types.

npm version license GitHub repository Docs Reddit community

Documentation | npm | Issues | Repository

Current package version: 1.0.5

Why this package?

A compatibility-first maintained continuation of source-map-resolve@0.6.0. It locates a sourceMappingURL, reads an external or embedded source map, and optionally resolves and reads the map's sources.

This project is independent. It is not affiliated with or endorsed by Simon Lydell or the upstream project.

Compatibility

Item Value
Package @stackline/source-map-resolve@1.0.5
Node.js runtime >=12
CommonJS / primary entry ./index.js
ES module entry ./index.mjs
Type declarations ./index.d.ts

Compatibility target

The only intentional resolver correction in 1.0.0 preserves Windows drive letters. Upstream stripped D: from a path and could consequently ask a reader on C: for the wrong file.

Installation

Install

npm install @stackline/source-map-resolve

To keep an existing import unchanged after publication, use an npm alias:

Usage

npm install source-map-resolve@npm:@stackline/source-map-resolve

const sourceMapResolve = require('source-map-resolve')

The legacy-key alias changes package resolution only; application imports do not need to change.

Version 1.0.1 installs with no production, optional, or peer dependencies. Base64 decoding uses the runtime primitive, and tolerant URI decoding is maintained inside the package under its retained MIT attribution.

CommonJS

const sourceMapResolve = require('@stackline/source-map-resolve')
const fs = require('node:fs')

const result = sourceMapResolve.resolveSync(
  fs.readFileSync('dist/app.js', 'utf8'),
  'dist/app.js',
  fs.readFileSync
)

console.log(result && result.sourcesResolved)

ESM

import { resolveSourceMapSync } from '@stackline/source-map-resolve'

const result = resolveSourceMapSync(code, codeUrl, readSync)

The default ESM export is the same seven-function API object as CommonJS.

Features and Integrations

Browser use

Bundlers can select the package's browser export condition. Direct artifacts are also available:

Browser callers provide their own asynchronous or synchronous reader, such as one backed by fetch, an in-memory file table, or an application filesystem.

Important limitation

The historical matcher is deliberately language-agnostic. Text that looks like a source-map comment inside a string can be matched. Browser engines also differ on which comment wins when a file contains multiple directives. This release preserves upstream 0.6.0 behavior; it does not claim to parse every JavaScript or CSS grammar.

Consumers pinned to 0.5.x

The shared seven-function API and ordinary Node resolver behavior are tested against both 0.5.3 and 0.6.0. However, this is a 0.6.0 compatibility release, not a byte-for-byte 0.5.x clone:

See COMPATIBILITY_CONTRACT.md and MIGRATION.md before migrating a 0.5.x consumer.

Security

The production graph contains only this package. Release gates require a warning-free packed install, a valid npm tree, and zero production audit findings for both direct and historical-key alias consumers. Report suspected vulnerabilities privately as described in SECURITY.md.

API Surface

API

resolveSourceMap(code, codeUrl, read, callback)

Find and parse the first recognized sourceMappingURL. read(url, callback) is used only for an external map. No-map, embedded-map, and helper errors are delivered asynchronously.

resolveSourceMapSync(code, codeUrl, read)

Synchronous form. It returns null when no recognized comment exists.

resolveSources(map, mapUrl, read, [options], callback)

Resolve every map.sources entry. Existing string entries in map.sourcesContent are retained. A failure to read one source is placed in the corresponding sourcesContent slot rather than failing the whole call.

resolveSourcesSync(map, mapUrl, read, [options])

Synchronous form. Pass read === null to resolve URLs without reading source content.

resolve(code, codeUrl, read, [options], callback)

Resolve the map and its sources. When code === null, codeUrl is treated as the map URL and read directly.

resolveSync(code, codeUrl, read, [options])

Synchronous combined resolver.

parseMapToJSON(source, [partialData])

Parse JSON after removing the source-map XSSI prefix )]}'. Parse errors retain the supplied value as error.sourceMapData.

Options

sourceRoot may be a replacement string or false to ignore the map's own sourceRoot.

Local Development

git clone https://github.com/alexandroit/stackline-source-map-resolve.git
cd stackline-source-map-resolve
npm ci
npm run verify

Release tooling uses Node.js 24.20.0 and npm 11.19.0. The consumer runtime contract remains the one documented above.

Consumer Smoke Test

Run the repository's existing consumer/package check after installing development dependencies:

npm run test:smoke

Release Checklist

Run npm run verify and inspect the package contents before release. Publish a new version through the GitHub Actions publishing workflow, using the SHA-512 digest of the reviewed tarball. Verify the exact published version, tarball integrity, and npm provenance after the run.

License

MIT. Upstream copyright and attribution are retained in LICENSE, NOTICE, and THIRD_PARTY_LICENSES.md.

Maintenance and compatibility notes

The runtime audit is clean for the reviewed release. Historical decode-uri-component comparison fixtures in development retain two moderate findings; those fixtures stay independent of the implementation under test.

Credits and original authors

Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.

Community and Links

Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.