Skip to documentation
ALEXANDRONET

reference

Compatibility Contract — @stackline/convert-source-map

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

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

Compatibility Contract

Baseline

The behavioral oracle is [email protected], published from upstream commit f1ed815b4edacfa9c3c5552dd342e71a3cffbb0a.

Preserved JavaScript API

  • fromObject, fromJSON, fromURI, fromBase64, and fromComment;
  • fromSource, fromMapFileComment, and fromMapFileSource;
  • removeComments, removeMapFileComments, and generateMapFileComment;
  • converter methods toObject, toJSON, toURI, toBase64, toComment, addProperty, setProperty, and getProperty;
  • fresh, non-enumerable commentRegex and mapFileCommentRegex getters in CommonJS;
  • the version 2 readMap(filename) callback, including sync and async results;
  • mutation of the object supplied to fromObject.

Module and type contract

  • CommonJS: require('@stackline/convert-source-map');
  • Node ESM: default and named imports through a thin wrapper;
  • TypeScript: bundled declarations tested from 3.9 onward;
  • browser: bundled operation without a global Buffer;
  • runtime: Node.js 12 and newer.

The ESM regex exports are values captured during module initialization. CJS retains the original fresh-getter behavior.

Intentional hardening

  • Source discovery accepts valid same-line CSS block comments and ignores source-map-looking text inside ordinary strings.
  • URI data is split at its first comma rather than its last comma.
  • Invalid comments and missing readers fail with controlled errors.
  • addProperty works with null-prototype and hasOwnProperty-shadowing maps.
  • setProperty('__proto__', value) creates an own property without changing the object's prototype.
  • Public regexes no longer allow a whitespace match to traverse many lines.

Not promised

  • Parsing a complete JavaScript, CSS, or template grammar;
  • validating Source Map v3 field semantics;
  • fetching or reading external maps without a caller callback;
  • accepting unsupported MIME types or multiline sourceMappingURL values;
  • running on end-of-life Node.js versions below 12.

Package reference