Skip to documentation
ALEXANDRONET

reference

Compatibility Contract — @stackline/inline-source-map

Project compatibility notes for @stackline/inline-source-map 1.0.5. Review behavior, requirements and limitations.

Versioned project notes for @stackline/inline-source-map 1.0.5. Original attribution is retained in the linked repository.

Compatibility Contract

Reference: [email protected] plus merged upstream master 0.6.4.

Preserved public surface

  • require(package) returns a callable factory.
  • factory.Generator exposes the constructor.
  • Calling the factory without new returns a Generator instance.
  • Options: file, sourceRoot, and charset.
  • Methods: addMappings, addGeneratedMappings, addSourceContent, base64Encode, inlineMappingUrl, toJSON, toString, _mappings, and gen.
  • Add methods return the same generator for chaining.
  • Empty source text still generates one identity mapping.
  • A supplied offset applies line and column to every generated mapping.
  • Missing offset fields are written back as zero to a supplied mutable offset.
  • Mappings without original remain generated-only segments.
  • Missing or non-string source content appears as null.
  • Empty string source content remains an empty string.
  • Inline comments use //#, charset=<value>, and base64 JSON.
  • toString() is the compact JSON serialization of toJSON().

Intentional compatible improvements

  • Null-prototype and shadowed-hasOwnProperty offsets no longer throw solely because of the ownership check.
  • __proto__, prototype, and constructor source names retain content safely.
  • Browsers can encode UTF-8 without a Buffer polyfill.
  • TypeScript declarations are additive.
  • Node ESM default import is verified against the CommonJS implementation.

Underlying generator update

gen() returns SourceMapGenerator from [email protected]. Its generator methods are compatible with the methods used by this package. Consumer-only APIs in source-map are outside this package's contract.

_mappings() is retained as a diagnostic snapshot. Generated-only original fields are normalized to legacy false; mutations to the returned array are not propagated to the underlying generator.

Explicit non-goals for 1.x

  • No new mapping-name behavior; upstream ignored mapping.name and this release does too.
  • No change to the unusual all-lines column offset behavior.
  • No automatic input-size limit; callers own trust-boundary limits.
  • No browser global or CDN-specific build.

The package does include a bundler-selected CommonJS browser entry; it does not install a global variable or promise direct script-tag loading.

Package reference