esrap 1.4.8 → 2.0.0

package/README.md

@@ -6,8 +6,9 @@ Parse in reverse. AST goes in, code comes out.
 
 ```js
 import { print } from 'esrap';
+import ts from 'esrap/languages/ts';
 
-const { code, map } = print({
+const ast = {
   type: 'Program',
   body: [
     {
@@ -26,19 +27,105 @@ const { code, map } = print({
       }
     }
   ]
-});
+};
+
+const { code, map } = print(ast, ts());
 
 console.log(code); // alert('hello world!');
 ```
 
 If the nodes of the input AST have `loc` properties (e.g. the AST was generated with [`acorn`](https://github.com/acornjs/acorn/tree/master/acorn/#interface) 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`](https://www.npmjs.com/package/@typescript-eslint/types) (which extends [ESTree](https://github.com/estree/estree)):
+
+```js
+import ts from 'esrap/languages/ts';
+import tsx from 'esrap/languages/tsx'; // experimental!
+```
+
+Both languages accept an options object:
+
+```js
+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: []
+  })
+);
+```
+
+You can generate the `comments` array by, for example, using [Acorn's](https://github.com/acornjs/acorn/tree/master/acorn/#interface) `onComment` option.
+
+## Custom languages
+
+You can also create your own languages:
+
+```ts
+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('foo');
+  },
+  Bar(node, context) {
+    // node.type === 'Bar'
+    context.write('bar');
+  }
+};
+
+const ast: MyNodeType = {
+  type: 'List',
+  children: [{ type: 'Foo' }, { type: 'Bar' }]
+};
+
+const { code, map } = print(ast, language);
+
+code; // `[[foo][bar]]`
+```
+
+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
+- `context.indent()` — increase the indentation level, typically before adding a newline
+- `context.newline()` — self-explanatory
+- `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:
 
 ```js
-const { code, map } = print(ast, {
+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',
@@ -51,20 +138,10 @@ const { code, map } = print(ast, {
   sourceMapEncodeMappings: false,
 
   // String to use for indentation — defaults to '\t'
-  indent: '  ',
-
-  // Whether to wrap strings in single or double quotes — defaults to 'single'.
-  // This only applies to string literals with no `raw` value, which generally
-  // means the AST node was generated programmatically, rather than parsed
-  // from an original source
-  quotes: 'single'
+  indent: '  '
 });
 ```
 
-## TypeScript
-
-`esrap` can also print TypeScript nodes, assuming they match the ESTree-like [`@typescript-eslint/types`](https://www.npmjs.com/package/@typescript-eslint/types).
-
 ## Why not just use Prettier?
 
 Because it's ginormous.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "esrap",
-  "version": "1.4.8",
+  "version": "2.0.0",
   "description": "Parse in reverse",
   "repository": {
     "type": "git",
@@ -15,6 +15,14 @@
     ".": {
       "types": "./types/index.d.ts",
       "default": "./src/index.js"
+    },
+    "./languages/ts": {
+      "types": "./types/index.d.ts",
+      "default": "./src/languages/ts/index.js"
+    },
+    "./languages/tsx": {
+      "types": "./types/index.d.ts",
+      "default": "./src/languages/tsx/index.js"
     }
   },
   "types": "./types/index.d.ts",
@@ -23,8 +31,8 @@
     "@sveltejs/acorn-typescript": "^1.0.5",
     "@typescript-eslint/types": "^8.2.0",
     "@vitest/ui": "^2.1.1",
-    "acorn": "^8.11.3",
-    "dts-buddy": "^0.5.4",
+    "acorn": "^8.15.0",
+    "dts-buddy": "^0.6.2",
     "prettier": "^3.0.3",
     "typescript": "^5.7.2",
     "vitest": "^2.1.1",

package/src/context.js

@@ -0,0 +1,150 @@
+/** @import { TSESTree } from '@typescript-eslint/types' */
+/** @import { BaseNode, Command, Visitors } from './types' */
+
+export const margin = 0;
+export const newline = 1;
+export const indent = 2;
+export const dedent = 3;
+
+export class Context {
+	#visitors;
+	#commands;
+
+	multiline = false;
+
+	/**
+	 *
+	 * @param {Visitors} visitors
+	 * @param {Command[]} commands
+	 */
+	constructor(visitors, commands = []) {
+		this.#visitors = visitors;
+		this.#commands = commands;
+	}
+
+	indent() {
+		this.#commands.push(indent);
+	}
+
+	dedent() {
+		this.#commands.push(dedent);
+	}
+
+	margin() {
+		this.#commands.push(margin);
+	}
+
+	newline() {
+		this.multiline = true;
+		this.#commands.push(newline);
+	}
+
+	/**
+	 * @param {Context} context
+	 */
+	append(context) {
+		this.#commands.push(context.#commands);
+	}
+
+	/**
+	 *
+	 * @param {string} content
+	 * @param {BaseNode} [node]
+	 */
+	write(content, node) {
+		if (node?.loc) {
+			this.location(node.loc.start.line, node.loc.start.column);
+			this.#commands.push(content);
+			this.location(node.loc.end.line, node.loc.end.column);
+		} else {
+			this.#commands.push(content);
+		}
+	}
+
+	/**
+	 *
+	 * @param {number} line
+	 * @param {number} column
+	 */
+	location(line, column) {
+		this.#commands.push({ type: 'Location', line, column });
+	}
+
+	/**
+	 * @param {{ type: string }} node
+	 */
+	visit(node) {
+		const visitor = this.#visitors[node.type];
+
+		if (!visitor) {
+			let message = `Not implemented: ${node.type}`;
+
+			if (node.type.includes('TS')) {
+				message += ` (consider using 'esrap/languages/ts')`;
+			}
+
+			if (node.type.includes('JSX')) {
+				message += ` (consider using 'esrap/languages/tsx')`;
+			}
+
+			throw new Error(message);
+		}
+
+		if (this.#visitors._) {
+			// @ts-ignore
+			this.#visitors._(node, this, (node) => visitor(node, this));
+		} else {
+			// @ts-ignore
+			visitor(node, this);
+		}
+	}
+
+	empty() {
+		return !this.#commands.some(has_content);
+	}
+
+	measure() {
+		return measure(this.#commands);
+	}
+
+	new() {
+		return new Context(this.#visitors);
+	}
+}
+
+/**
+ *
+ * @param {Command[]} commands
+ * @param {number} [from]
+ * @param {number} [to]
+ */
+function measure(commands, from = 0, to = commands.length) {
+	let total = 0;
+
+	for (let i = from; i < to; i += 1) {
+		const command = commands[i];
+
+		if (typeof command === 'string') {
+			total += command.length;
+		} else if (Array.isArray(command)) {
+			total += measure(command);
+		}
+	}
+
+	return total;
+}
+
+/**
+ * @param {Command} command
+ */
+function has_content(command) {
+	if (Array.isArray(command)) {
+		return command.some(has_content);
+	}
+
+	if (typeof command === 'string') {
+		return command.length > 0;
+	}
+
+	return false;
+}

package/src/index.js

@@ -1,7 +1,6 @@
-/** @import { TSESTree } from '@typescript-eslint/types' */
-/** @import { Command, PrintOptions, State } from './types' */
-import { handle } from './handlers.js';
+/** @import { BaseNode, Command, Visitors, PrintOptions } from './types' */
 import { encode } from '@jridgewell/sourcemap-codec';
+import { Context, dedent, indent, margin, newline } from './context.js';
 
 /** @type {(str: string) => string} str */
 let btoa = () => {
@@ -10,38 +9,56 @@ let btoa = () => {
 
 if (typeof window !== 'undefined' && typeof window.btoa === 'function') {
 	btoa = (str) => window.btoa(unescape(encodeURIComponent(str)));
-	// @ts-expect-error
 } else if (typeof Buffer === 'function') {
-	// @ts-expect-error
 	btoa = (str) => Buffer.from(str, 'utf-8').toString('base64');
 }
 
+class SourceMap {
+	version = 3;
+
+	/** @type {string[]} */
+	names = [];
+
+	/**
+	 * @param {[number, number, number, number][][]} mappings
+	 * @param {PrintOptions} opts
+	 */
+	constructor(mappings, opts) {
+		this.sources = [opts.sourceMapSource || null];
+		this.sourcesContent = [opts.sourceMapContent || null];
+		this.mappings = opts.sourceMapEncodeMappings === false ? mappings : encode(mappings);
+	}
+
+	/**
+	 * Returns a JSON representation suitable for saving as a `*.map` file
+	 */
+	toString() {
+		return JSON.stringify(this);
+	}
+
+	/**
+	 * Returns a base64-encoded JSON representation suitable for inlining at the bottom of a file with `//# sourceMappingURL={...}`
+	 */
+	toUrl() {
+		return 'data:application/json;charset=utf-8;base64,' + btoa(this.toString());
+	}
+}
+
 /**
- * @param {{ type: string, [key: string]: any }} node
+ * @template {BaseNode} [T=BaseNode]
+ * @param {T} node
+ * @param {Visitors<T>} visitors
  * @param {PrintOptions} opts
  * @returns {{ code: string, map: any }} // TODO
  */
-export function print(node, opts = {}) {
-	if (Array.isArray(node)) {
-		return print(
-			{
-				type: 'Program',
-				body: node,
-				sourceType: 'module'
-			},
-			opts
-		);
-	}
+export function print(node, visitors, opts = {}) {
+	/** @type {Command[]} */
+	const commands = [];
 
-	/** @type {State} */
-	const state = {
-		commands: [],
-		comments: [],
-		multiline: false,
-		quote: opts.quotes === 'double' ? '"' : "'"
-	};
+	// @ts-expect-error some nonsense I don't understand
+	const context = new Context(visitors, commands);
 
-	handle(/** @type {TSESTree.Node} */ (node), state);
+	context.visit(node);
 
 	/** @typedef {[number, number, number, number]} Segment */
 
@@ -69,16 +86,14 @@ export function print(node, opts = {}) {
 		}
 	}
 
-	let newline = '\n';
-	const indent = opts.indent ?? '\t';
+	let current_newline = '\n';
+	const indent_str = opts.indent ?? '\t';
+
+	let needs_newline = false;
+	let needs_margin = false;
 
 	/** @param {Command} command */
 	function run(command) {
-		if (typeof command === 'string') {
-			append(command);
-			return;
-		}
-
 		if (Array.isArray(command)) {
 			for (let i = 0; i < command.length; i += 1) {
 				run(command[i]);
@@ -86,74 +101,60 @@ export function print(node, opts = {}) {
 			return;
 		}
 
-		switch (command.type) {
-			case 'Location':
-				current_line.push([
-					current_column,
-					0, // source index is always zero
-					command.line - 1,
-					command.column
-				]);
-				break;
-
-			case 'Newline':
-				append(newline);
-				break;
-
-			case 'Indent':
-				newline += indent;
-				break;
-
-			case 'Dedent':
-				newline = newline.slice(0, -indent.length);
-				break;
-
-			case 'Comment':
-				if (command.comment.type === 'Line') {
-					append(`//${command.comment.value}`);
-				} else {
-					append(`/*${command.comment.value.replace(/\n/g, newline)}*/`);
-				}
-
-				break;
+		if (typeof command === 'number') {
+			if (command === newline) {
+				needs_newline = true;
+			} else if (command === margin) {
+				needs_margin = true;
+			} else if (command === indent) {
+				current_newline += indent_str;
+			} else if (command === dedent) {
+				current_newline = current_newline.slice(0, -indent_str.length);
+			}
+
+			return;
+		}
+
+		if (needs_newline) {
+			append(needs_margin ? '\n' + current_newline : current_newline);
+		}
+
+		needs_margin = needs_newline = false;
+
+		if (typeof command === 'string') {
+			append(command);
+			return;
+		}
+
+		if (command.type === 'Location') {
+			current_line.push([
+				current_column,
+				0, // source index is always zero
+				command.line - 1,
+				command.column
+			]);
 		}
 	}
 
-	for (let i = 0; i < state.commands.length; i += 1) {
-		run(state.commands[i]);
+	for (let i = 0; i < commands.length; i += 1) {
+		run(commands[i]);
 	}
 
 	mappings.push(current_line);
 
-	const map = {
-		version: 3,
-		/** @type {string[]} */
-		names: [],
-		sources: [opts.sourceMapSource || null],
-		sourcesContent: [opts.sourceMapContent || null],
-		mappings:
-			opts.sourceMapEncodeMappings == undefined || opts.sourceMapEncodeMappings
-				? encode(mappings)
-				: mappings
-	};
-
-	Object.defineProperties(map, {
-		toString: {
-			enumerable: false,
-			value: function toString() {
-				return JSON.stringify(this);
-			}
-		},
-		toUrl: {
-			enumerable: false,
-			value: function toUrl() {
-				return 'data:application/json;charset=utf-8;base64,' + btoa(this.toString());
-			}
-		}
-	});
+	/** @type {SourceMap} */
+	let map;
 
 	return {
 		code,
-		map
+		// create sourcemap lazily in case we don't need it
+		get map() {
+			return (map ??= new SourceMap(mappings, opts));
+		}
 	};
 }
+
+// it sucks that we have to export the class rather than just
+// re-exporting it via public.d.ts, but otherwise TypeScript
+// gets confused about private fields because it is really dumb!
+export { Context };