sorcery

What is sorcery?

The 'sorcery' npm package is used for working with source maps. It allows you to resolve, manipulate, and generate source maps, which are crucial for debugging minified JavaScript code.

What are sorcery's main functionalities?

Resolve Source Maps

This feature allows you to resolve the source maps for a given file. The code sample demonstrates how to load a file and resolve its source maps, then write the resolved source maps back to the file.

const sorcery = require('sorcery');
sorcery.load('path/to/your/file.js').then(function (chain) {
  chain.write();
});

Generate Source Maps

This feature allows you to generate new source maps for a given file. The code sample shows how to load a file, generate source maps with the content included, and write the new source maps back to the file.

const sorcery = require('sorcery');
sorcery.load('path/to/your/file.js').then(function (chain) {
  chain.apply({ includeContent: true }).write();
});

Manipulate Source Maps

This feature allows you to manipulate existing source maps. The code sample demonstrates how to load a file, apply changes to its source maps, and write the manipulated source maps to a new destination file.

const sorcery = require('sorcery');
sorcery.load('path/to/your/file.js').then(function (chain) {
  chain.apply({ includeContent: true });
  chain.write({ dest: 'path/to/output/file.js' });
});

Other packages similar to sorcery

source-map

The 'source-map' package provides a library to generate and consume source maps. It is more low-level compared to 'sorcery' and requires more manual handling of source maps.

gulp-sourcemaps

The 'gulp-sourcemaps' package is a plugin for Gulp that simplifies working with source maps in a Gulp build pipeline. It is more integrated into the Gulp ecosystem and provides a more streamlined experience for Gulp users.

webpack

Webpack is a module bundler that has built-in support for generating source maps. It is a more comprehensive tool that handles module bundling, asset management, and source map generation as part of its build process.

README

sorcery.js

Sourcemaps are great - if you have a JavaScript file, and you minify it, your minifier can generate a map that lets you debug as though you were looking at the original uncompressed code.

But if you have more than one transformation - say you want to transpile your JavaScript, concatenate several files into one, and minify the result - it gets a little trickier. Each intermediate step needs to be able to both ingest a sourcemap and generate one, all the time pointing back to the original source.

Most compilers don't do that. (UglifyJS is an honourable exception.) So when you fire up devtools, instead of looking at the original source you find yourself looking at the final intermediate step in the chain of transformations.

Sorcery aims to fix that. Given an file at the end of a transformation chain (e.g., your minified JavaScript), it will follow the entire chain back to the original source, and generate a new sourcemap that describes the whole process. How? Magic.

This is a work-in-progress - suitable for playing around with, but don't rely on it to debug air traffic control software or medical equipment. Other than that, it can't do much harm.

Usage

As a node module

Install sorcery locally:

npm install sorcery

var sorcery = require( 'sorcery' );

sorcery.load( 'some/generated/code.min.js' ).then( function ( chain ) {
  // generate a flattened sourcemap
  var map = chain.apply(); // { version: 3, file: 'code.min.js', ... }

  // get a JSON representation of the sourcemap
  map.toString(); // '{"version":3,"file":"code.min.js",...}'

  // get a data URI representation
  map.toUrl(); // 'data:application/json;charset=utf-8;base64,eyJ2ZXJ...'

  // write to a new file - this will create `output.js` and
  // `output.js.map`, and will preserve relative paths. It
  // returns a Promise
  chain.write( 'output.js' );

  // write to a new file but use an absolute path for the
  // sourceMappingURL
  chain.write( 'output.js', { absolutePath: true });

  // write to a new file, but append the flattened sourcemap as a data URI
  chain.write( 'output.js', { inline: true });

  // overwrite the existing file
  chain.write();
  chain.write({ inline: true });

  // find the origin of line x, column y. Returns an object with
  // `source`, `line`, `column` and (if applicable) `name` properties.
  // Note - for consistency with other tools, line numbers are always
  // one-based, column numbers are always zero-based. It's daft, I know.
  var loc = chain.trace( x, y );
});

// You can also use sorcery synchronously:
var chain = sorcery.loadSync( 'some/generated/code.min.js' );
var map = chain.apply();
var loc = chain.trace( x, y );
chain.writeSync();

Advanced options

You can pass an optional second argument to sorcery.load() and sorcery.loadSync(), with zero or more of the following properties:

• content - a map of filename: contents pairs. filename will be resolved against the current working directory if needs be
• sourcemaps - a map of filename: sourcemap pairs, where filename is the name of the file the sourcemap is related to. This will override any sourceMappingURL comments in the file itself.

For example:

sorcery.load( 'some/generated/code.min.js', {
  content: {
    'some/minified/code.min.js': '...',
    'some/transpiled/code.js': '...',
    'some/original/code.js': '...'
  },
  sourcemaps: {
    'some/minified/code.min.js': {...},
    'some/transpiled/code.js': {...}
  }
}).then( chain => {
  /* ... */
});

Any files not found will be read from the filesystem as normal.

On the command line

First, install sorcery globally:

npm install -g sorcery

Usage:
  sorcery [options]

Options:
  -h, --help               Show help message
  -v, --version            Show version
  -i, --input <file>       Input file
  -o, --output <file>      Output file (if absent, will overwrite input)
  -d, --datauri            Append map as a data URI, rather than separate file
  -x, --excludeContent     Don't populate the sourcesContent array

Examples:

# overwrite sourcemap in place (will write map to
# some/generated/code.min.js.map, and update
# sourceMappingURL comment if necessary
sorcery -i some/generated/code.min.js

# append flattened sourcemap as an inline data URI
# (will delete existing .map file, if applicable)
sorcery -d -i some/generated/code.min.js

# write to a new file (will create newfile.js and
# newfile.js.map)
sorcery -i some/generated/code.min.js -o newfile.js

License

MIT

Changelog

0.10.0

• Allow CLI to recurse over a directory (#13)