# sorcery

> Resolve a chain of sourcemaps back to the original source

Latest version **1.0.0** (published 2024-06-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install sorcery
pnpm add sorcery
yarn add sorcery
bun add sorcery
```

Provides the command `sorcery`.

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2024-06-12 |
| First published | 2014-10-01 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 3 |
| Unpacked size | 22.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 336 |
| Author | Rich Harris |
| Maintainers | rich_harris |

## Links

- npm: https://www.npmjs.com/package/sorcery
- Repository: https://github.com/Rich-Harris/sorcery
- Homepage: https://github.com/Rich-Harris/sorcery#readme
- Issues: https://github.com/Rich-Harris/sorcery/issues
- npm.io page: https://npm.io/package/sorcery

## Dependencies (3)

- [minimist](https://npm.io/package/minimist.md) ^1.2.0
- [tiny-glob](https://npm.io/package/tiny-glob.md) ^0.2.9
- [@jridgewell/sourcemap-codec](https://npm.io/package/@jridgewell/sourcemap-codec.md) ^1.4.14

## Recent versions

- 1.0.0 (latest) — 2024-06-12
- 0.11.1 — 2024-06-12
- 0.11.0 — 2023-01-19
- 0.10.0 — 2016-04-23
- 0.9.4 — 2016-04-23
- 0.9.3 — 2016-04-17
- 0.9.2 — 2015-12-20
- 0.9.1 — 2015-12-20
- 0.9.0 — 2015-12-20
- 0.8.0 — 2015-10-23
- 0.7.0 — 2015-10-18
- 0.6.5 — 2015-10-10
- 0.6.4 — 2015-10-10
- 0.6.3 — 2015-06-15
- 0.6.2 — 2015-06-07
- … 21 more at https://npm.io/package/sorcery/versions

## 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](https://github.com/mishoo/UglifyJS2) 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 a 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:

```bash
npm install sorcery
```

```js
import * as sorcery from '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:

```js
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:

```bash
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:

```bash
# 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

---
_Source: https://npm.io/package/sorcery · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._