If the nodes of the input AST have loc properties (e.g. the AST was generated with acorn with the locations option set), sourcemap mappings will be created.
Built-in languages
esrap ships with two built-in languages — ts() and tsx() (considered experimental at present!) — which can print ASTs conforming to @typescript-eslint/types (which extends ESTree):
import ts from 'esrap/languages/ts';import tsx from 'esrap/languages/tsx'; // experimental!
Both languages accept an options object:
const { code, map } = print( ast, ts({ // how string literals should be quoted — `single` (the default) or `double` quotes: 'single', // an array of `{ type: 'Line' | 'Block', value: string, loc: { start, end } }` objects comments: [], // a pair of functions for inserting additional comments before or after a given node. // returns `Array<{ type: 'Line' | 'Block', value: string }>` or `undefined` getLeadingComments: (node) => [{ type: 'Line', value: ' a comment before the node' }], getTrailingComments: (node) => [{ type: 'Block', value: ' a comment after the node' }] }));
You can generate the comments array by, for example, using Acorn'sonComment option.
Custom languages
You can also create your own languages:
import { print, type Visitors } from 'esrap';const language: Visitors<MyNodeType> = { _(node, context, visit) { // the `_` visitor handles any node type context.write('['); visit(node); context.write(']'); }, List(node, context) { // node.type === 'List' for (const child of node.children) { context.visit(child); } }, Foo(node, context) { // node.type === 'Foo' context.write
The context API has several methods:
context.write(data: string, node?: BaseNode) — add a string. If node is provided and has a standard loc property (with start and end properties each with a line and column), a sourcemap mapping will be created. Otherwise, if tokens were passed to print and data (ignoring surrounding whitespace) is the next token in the source, it will be mapped to that token — so write tokens individually (e.g. ')' then ' {' rather than ') {')
context.indent() — increase the indentation level, typically before adding a newline
context.newline() — self-explanatory
context.space() — adds a space character, if it doesn't immediately follow a newline
context.margin() — causes the next newline to be repeated (consecutive newlines are otherwise merged into one)
context.dedent() — decrease the indentation level (again, typically before adding a newline)
context.visit(node: BaseNode) — calls the visitor corresponding to node.type
context.location(line: number, column: number) — insert a sourcemap mapping without calling context.write(...)
context.measure() — returns the number of characters contained in context
context.empty() — returns true if the context has no content
context.new() — creates a child context
context.append(child) — appends a child context
In addition, context.multiline is true if the context has multiline content. (This is useful for knowing, for example, when to insert newlines between nodes.)
To understand how to wield these methods effectively, read the source code for the built-in languages.
Options
You can pass the following options:
const { code, map } = print(ast, ts(), { // Populate the `sources` field of the resulting sourcemap // (note that the AST is assumed to come from a single file) sourceMapSource: 'input.js', // Populate the `sourcesContent` field of the resulting sourcemap sourceMapContent: fs.readFileSync('input.js', 'utf-8'), // Whether to encode the `mappings` field of the resulting sourcemap // as a VLQ string, rather than an unencoded array. Defaults to `true` sourceMapEncodeMappings: false, // The parser's tokens, if `ast` came from parsing source code. Used to // create accurate mappings for punctuation and keywords. Tokens must have // `loc` properties — e.g. Acorn's `onToken` array (with `locations: true`), // or `ast.tokens` from espree/@typescript-eslint/parser (with // `tokens: true, loc: true`) tokens, // String to use for indentation — defaults to '\t' indent: ' '
Why not just use Prettier?
Because it's ginormous.
Developing
This repo uses pnpm. Once it's installed, do pnpm install to install dependencies, and pnpm test to run the tests.