esrap 2.2.12 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "esrap",
-  "version": "2.2.12",
+  "version": "2.3.0",
   "description": "Parse in reverse",
   "repository": {
     "type": "git",

package/src/languages/ts/index.js

@@ -484,20 +484,50 @@ export default (options = {}) => {
 		}
 	}
 
+	const boundary_tokens = options.boundaryTokens === true;
+
+	/**
+	 * A one-character synthetic token node so structural tokens (`(`, `[`, `{`,
+	 * unary operators, …) written where a node's SOURCE span begins or ends get a
+	 * sourcemap anchor. Without it, everything up to the next mapped token is
+	 * attributed to the PREVIOUS token's source position — `write(content, node)`
+	 * only maps tokens written with a node, and these boundary characters belong
+	 * to no written token. Opt-in (`boundaryTokens`): denser maps, byte-identical
+	 * output.
+	 * @param {{ line: number, column: number } | undefined} pos
+	 * @param {number} [length]
+	 */
+	function token_at(pos, length = 1) {
+		if (!boundary_tokens) return undefined;
+		if (!pos) return undefined;
+		return /** @type {any} */ ({
+			loc: { start: pos, end: { line: pos.line, column: pos.column + length } }
+		});
+	}
+
+	/** @param {{ line: number, column: number } | undefined} pos */
+	function token_before(pos) {
+		if (!boundary_tokens) return undefined;
+		if (!pos || pos.column === 0) return undefined;
+		return /** @type {any} */ ({
+			loc: { start: { line: pos.line, column: pos.column - 1 }, end: pos }
+		});
+	}
+
 	const shared = {
 		/**
 		 * @param {TSESTree.ArrayExpression | TSESTree.ArrayPattern} node
 		 * @param {Context} context
 		 */
 		'ArrayExpression|ArrayPattern': (node, context) => {
-			context.write('[');
+			context.write('[', token_at(node.loc?.start));
 			sequence(
 				context,
 				/** @type {TSESTree.Node[]} */ (node.elements),
 				node.loc?.end ?? null,
 				false
 			);
-			context.write(']');
+			context.write(']', token_before(node.loc?.end));
 		},
 
 		/**
@@ -631,7 +661,7 @@ export default (options = {}) => {
 				join.write(' ');
 			}
 
-			context.write(')');
+			context.write(')', token_before(node.loc?.end));
 		},
 
 		/**
@@ -653,12 +683,25 @@ export default (options = {}) => {
 
 			if (node.id) {
 				context.visit(node.id);
+			}
+
+			if (node.typeParameters) {
+				context.visit(node.typeParameters);
+			}
+
+			if (node.id || node.typeParameters) {
 				context.write(' ');
 			}
 
 			if (node.superClass) {
 				context.write('extends ');
+				// the `extends` clause is a LeftHandSideExpression; anything lower (a
+				// logical/binary/conditional/etc.) must be parenthesized
+				const wrap_super =
+					EXPRESSIONS_PRECEDENCE[node.superClass.type] < EXPRESSIONS_PRECEDENCE.NewExpression;
+				if (wrap_super) context.write('(');
 				context.visit(node.superClass);
+				if (wrap_super) context.write(')');
 
 				// @ts-expect-error `acorn-typescript` and `@typescript-eslint/types` have slightly different type definitions
 				var type_arguments = node.superTypeParameters ?? node.superTypeArguments;
@@ -791,9 +834,15 @@ export default (options = {}) => {
 
 			if (node.value.generator) context.write('*');
 
-			if (node.computed) context.write('[');
+			if (node.computed) context.write('[', token_before(node.key.loc?.start));
 			context.visit(node.key);
-			if (node.computed) context.write(']');
+			if (node.computed) context.write(']', token_at(node.key.loc?.end));
+
+			// optional method (`m?()`)
+			if (node.optional) context.write('?');
+
+			// @ts-expect-error `typeParameters` lives on the method node, not its value
+			if (node.typeParameters) context.visit(node.typeParameters);
 
 			context.write('(');
 			sequence(
@@ -827,6 +876,8 @@ export default (options = {}) => {
 
 			const kw = create_keyword_write(context, node, field_modifiers_keywords_map_ok);
 
+			if (node.declare) kw('declare ');
+
 			if (node.accessibility) {
 				kw(node.accessibility + ' ');
 			}
@@ -844,6 +895,10 @@ export default (options = {}) => {
 				kw('static ');
 			}
 
+			if (node.override) kw('override ');
+
+			if (node.readonly) kw('readonly ');
+
 			if (
 				// @ts-expect-error `acorn-typescript` and `@typescript-eslint/types` have slightly different type definitions
 				node.accessor ||
@@ -854,13 +909,17 @@ export default (options = {}) => {
 			}
 
 			if (node.computed) {
-				context.write('[');
+				context.write('[', token_before(node.key.loc?.start));
 				context.visit(node.key);
-				context.write(']');
+				context.write(']', token_at(node.key.loc?.end));
 			} else {
 				context.visit(node.key);
 			}
 
+			// `x?: T` (optional) / `x!: T` (definite assignment)
+			if (node.optional) context.write('?');
+			else if (node.definite) context.write('!');
+
 			if (node.typeAnnotation) {
 				if (node.type === 'AccessorProperty' || node.type === 'TSAbstractAccessorProperty') {
 					context.visit(node.typeAnnotation);
@@ -1101,7 +1160,14 @@ export default (options = {}) => {
 
 		Decorator(node, context) {
 			context.write('@');
+			// a decorator must be an identifier/member/call (or parenthesized); anything
+			// else (ternary, logical, assignment, unary, `as`, optional chain…) needs wrapping
+			const wrap =
+				/** @type {string} */ (node.expression.type) === 'ChainExpression' ||
+				EXPRESSIONS_PRECEDENCE[node.expression.type] < EXPRESSIONS_PRECEDENCE.CallExpression;
+			if (wrap) context.write('(');
 			context.visit(node.expression);
+			if (wrap) context.write(')');
 			context.newline();
 		},
 
@@ -1211,12 +1277,8 @@ export default (options = {}) => {
 		},
 
 		ExpressionStatement(node, context) {
-			// wrap when a leading `{`/`function` would otherwise be parsed as a block/declaration
-			const wrap =
-				node.expression.type === 'ObjectExpression' ||
-				(node.expression.type === 'AssignmentExpression' &&
-					node.expression.left.type === 'ObjectPattern') ||
-				node.expression.type === 'FunctionExpression';
+			// would otherwise be parsed as a block / function / class declaration
+			const wrap = leads_with_curly_or_keyword(node.expression);
 			maybe_wrap(context, node.expression, wrap);
 			context.write(';');
 		},
@@ -1253,7 +1315,9 @@ export default (options = {}) => {
 			let name = node.name;
 			context.write(name, node);
 
+			// optional parameters (`a?: T`) carry `optional` on the identifier
 			if (node.optional) context.write('?');
+
 			if (node.typeAnnotation) context.visit(node.typeAnnotation);
 		},
 
@@ -1412,7 +1476,7 @@ export default (options = {}) => {
 				}
 				context.write('[');
 				context.visit(node.property);
-				context.write(']');
+				context.write(']', token_before(node.loc?.end));
 			} else {
 				context.write(node.optional ? '?.' : '.');
 				context.visit(node.property);
@@ -1430,22 +1494,28 @@ export default (options = {}) => {
 		NewExpression: shared['CallExpression|NewExpression'],
 
 		ObjectExpression(node, context) {
-			context.write('{');
+			context.write('{', token_at(node.loc?.start));
 			sequence(context, node.properties, node.loc?.end ?? null, true);
-			context.write('}');
+			context.write('}', token_before(node.loc?.end));
 		},
 
 		ObjectPattern(node, context) {
-			context.write('{');
+			context.write('{', token_at(node.loc?.start));
 			sequence(context, node.properties, node.loc?.end ?? null, true);
-			context.write('}');
+			context.write('}', token_before(node.loc?.end));
 
 			if (node.typeAnnotation) context.visit(node.typeAnnotation);
 		},
 
 		// @ts-expect-error this isn't a real node type, but Acorn produces it
 		ParenthesizedExpression(node, context) {
-			maybe_wrap(context, node.expression, true);
+			if (node.loc) {
+				context.write('(', token_at(node.loc.start));
+				context.visit(node.expression);
+				context.write(')', token_before(node.loc.end));
+			} else {
+				maybe_wrap(context, node.expression, true);
+			}
 		},
 
 		PrivateIdentifier(node, context) {
@@ -1479,9 +1549,9 @@ export default (options = {}) => {
 				if (node.kind !== 'init') kw(node.kind + ' ');
 				if (node.value.async) kw('async ');
 				if (node.value.generator) context.write('*');
-				if (node.computed) context.write('[');
+				if (node.computed) context.write('[', token_before(node.key.loc?.start));
 				context.visit(node.key);
-				if (node.computed) context.write(']');
+				if (node.computed) context.write(']', token_at(node.key.loc?.end));
 				context.write('(');
 				sequence(
 					context,
@@ -1496,12 +1566,17 @@ export default (options = {}) => {
 				context.write(' ');
 				context.visit(node.value.body);
 			} else {
-				if (node.computed) context.write('[');
+				if (node.computed) context.write('[', token_before(node.key.loc?.start));
 				if (node.kind === 'get' || node.kind === 'set') {
 					write_keyword(context, node, node.kind, ' ');
 				}
 				context.visit(node.key);
-				context.write(node.computed ? ']: ' : ': ');
+				if (node.computed) {
+					context.write(']', token_at(node.key.loc?.end));
+					context.write(': ');
+				} else {
+					context.write(': ');
+				}
 				context.visit(node.value);
 			}
 		},
@@ -1594,7 +1669,12 @@ export default (options = {}) => {
 		},
 
 		TaggedTemplateExpression(node, context) {
-			maybe_wrap(context, node.tag, node.tag.type === 'ChainExpression');
+			// the tag is a LeftHandSideExpression; a lower-precedence tag (logical,
+			// conditional, arrow, `as`, unary…) or an optional chain must be wrapped
+			const wrap =
+				/** @type {string} */ (node.tag.type) === 'ChainExpression' ||
+				EXPRESSIONS_PRECEDENCE[node.tag.type] < EXPRESSIONS_PRECEDENCE.CallExpression;
+			maybe_wrap(context, node.tag, wrap);
 			context.visit(node.quasi);
 		},
 
@@ -1663,7 +1743,7 @@ export default (options = {}) => {
 		},
 
 		UnaryExpression(node, context) {
-			context.write(node.operator);
+			context.write(node.operator, token_at(node.loc?.start, node.operator.length));
 
 			if (node.operator.length > 1) {
 				context.write(' ');
@@ -1847,7 +1927,9 @@ export default (options = {}) => {
 		},
 
 		TSPropertySignature(node, context) {
+			if (node.computed) context.write('[', token_before(node.key.loc?.start));
 			context.visit(node.key);
+			if (node.computed) context.write(']', token_at(node.key.loc?.end));
 			if (node.optional) context.write('?');
 			if (node.typeAnnotation) context.visit(node.typeAnnotation);
 		},
@@ -1939,6 +2021,11 @@ export default (options = {}) => {
 		},
 
 		TSTypeParameter(node, context) {
+			// modifiers: `const T`, `in T` / `out T` (variance)
+			if (node.const) context.write('const ');
+			if (node.in) context.write('in ');
+			if (node.out) context.write('out ');
+
 			if (node.name && node.name.type) context.visit(node.name);
 			// @ts-expect-error type mismatch TSESTree and acorn-typescript?
 			else context.write(node.name, node);
@@ -1955,19 +2042,14 @@ export default (options = {}) => {
 		},
 
 		TSTypePredicate(node, context) {
-			if (node.parameterName) {
-				context.visit(node.parameterName);
-			} else if (node.typeAnnotation) {
-				context.visit(node.typeAnnotation);
-			}
+			// `asserts` precedes the parameter name; `is <type>` follows it. Forms:
+			// `x is T`, `asserts x is T`, `asserts x`
+			if (node.asserts) context.write('asserts ');
 
-			if (node.asserts) {
-				context.write(' asserts ');
-			} else {
-				context.write(' is ');
-			}
+			if (node.parameterName) context.visit(node.parameterName);
 
 			if (node.typeAnnotation) {
+				context.write(' is ');
 				context.visit(node.typeAnnotation.typeAnnotation);
 			}
 		},
@@ -2005,7 +2087,16 @@ export default (options = {}) => {
 		},
 
 		TSMappedType(node, context) {
-			context.write('{[');
+			context.write('{');
+
+			// `readonly` / `+readonly` / `-readonly` modifier
+			if (node.readonly) {
+				context.write(
+					node.readonly === '-' ? '-readonly ' : node.readonly === '+' ? '+readonly ' : 'readonly '
+				);
+			}
+
+			context.write('[');
 
 			const legacy_type_parameter = node.typeParameter;
 			const key = node.key ?? legacy_type_parameter?.name;
@@ -2022,8 +2113,19 @@ export default (options = {}) => {
 				context.visit(constraint);
 			}
 
+			// `as` key remapping
+			if (node.nameType) {
+				context.write(' as ');
+				context.visit(node.nameType);
+			}
+
 			context.write(']');
 
+			// `?` / `+?` / `-?` optionality modifier
+			if (node.optional) {
+				context.write(node.optional === '-' ? '-?' : node.optional === '+' ? '+?' : '?');
+			}
+
 			if (node.typeAnnotation) {
 				context.write(': ');
 				context.visit(node.typeAnnotation);
@@ -2033,7 +2135,9 @@ export default (options = {}) => {
 		},
 
 		TSMethodSignature(node, context) {
+			if (node.computed) context.write('[', token_before(node.key.loc?.start));
 			context.visit(node.key);
+			if (node.computed) context.write(']', token_at(node.key.loc?.end));
 
 			context.write('(');
 			sequence(
@@ -2191,8 +2295,17 @@ export default (options = {}) => {
 				context.visit(node.id);
 			}
 
-			if (!node.body) return;
-			context.visit(node.body);
+			// a qualified name (`namespace A.B.C`) is represented as nested
+			// `TSModuleDeclaration`s whose body is the next name part, not a block
+			let body = /** @type {any} */ (node.body);
+			while (body && body.type === 'TSModuleDeclaration') {
+				context.write('.');
+				context.visit(body.id);
+				body = body.body;
+			}
+
+			if (!body) return;
+			context.visit(body);
 		},
 
 		TSNonNullExpression(node, context) {
@@ -2320,19 +2433,20 @@ function operand_needs_wrap(node, parent, is_right) {
 		return true;
 	}
 
-	// `**` can't take a unary/await left operand: `-2 ** 2`, `await x ** 2` are syntax errors
+	// `**` can't take a unary/await/assertion left operand: `-2 ** 2`, `await x ** 2`,
+	// `<T>x ** 2` are syntax errors
 	const unary_base_of_pow =
 		!is_right &&
 		parent.operator === '**' &&
-		(node.type === 'UnaryExpression' || node.type === 'AwaitExpression');
+		(node.type === 'UnaryExpression' ||
+			node.type === 'AwaitExpression' ||
+			node.type === 'TSTypeAssertion');
 	if (unary_base_of_pow) return true;
 
 	const precedence = EXPRESSIONS_PRECEDENCE[node.type];
 	const parent_precedence = EXPRESSIONS_PRECEDENCE[parent.type];
 	if (precedence !== parent_precedence) return precedence < parent_precedence;
-
 	const operator = /** @type {TSESTree.BinaryExpression} */ (node).operator;
-
 	if (operator === '**' && parent.operator === '**') {
 		// exponentiation is right-associative
 		return !is_right;
@@ -2375,6 +2489,95 @@ function has_call_expression(node) {
 	return false;
 }
 
+/**
+ * True when printing `node` as an expression statement would begin with `{`,
+ * `function`, or `class` — which the parser would misread as a block, function
+ * declaration, or class declaration. Walks the left spine following the same
+ * parenthesization the visitors apply, so it stops as soon as a child position
+ * would already be wrapped.
+ * @param {TSESTree.Node} node
+ * @returns {boolean}
+ */
+function leads_with_curly_or_keyword(node) {
+	while (node) {
+		switch (node.type) {
+			case 'ObjectExpression':
+			case 'ObjectPattern':
+			case 'FunctionExpression':
+			case 'ClassExpression':
+				return true;
+
+			case 'BinaryExpression':
+			case 'LogicalExpression':
+				if (operand_needs_wrap(node.left, node, false)) return false;
+				node = node.left;
+				continue;
+
+			case 'AssignmentExpression':
+				node = node.left;
+				continue;
+
+			case 'ConditionalExpression':
+				if (
+					EXPRESSIONS_PRECEDENCE[node.test.type] <= EXPRESSIONS_PRECEDENCE.ConditionalExpression
+				) {
+					return false;
+				}
+				node = node.test;
+				continue;
+
+			case 'MemberExpression':
+				if (
+					/** @type {string} */ (node.object.type) === 'ChainExpression' ||
+					EXPRESSIONS_PRECEDENCE[node.object.type] < EXPRESSIONS_PRECEDENCE.MemberExpression
+				) {
+					return false;
+				}
+				node = node.object;
+				continue;
+
+			case 'CallExpression':
+				if (
+					/** @type {string} */ (node.callee.type) === 'ChainExpression' ||
+					EXPRESSIONS_PRECEDENCE[node.callee.type] < EXPRESSIONS_PRECEDENCE.CallExpression
+				) {
+					return false;
+				}
+				node = node.callee;
+				continue;
+
+			case 'TaggedTemplateExpression':
+				if (
+					/** @type {string} */ (node.tag.type) === 'ChainExpression' ||
+					EXPRESSIONS_PRECEDENCE[node.tag.type] < EXPRESSIONS_PRECEDENCE.CallExpression
+				) {
+					return false;
+				}
+				node = node.tag;
+				continue;
+
+			case 'UpdateExpression':
+				if (node.prefix) return false;
+				node = node.argument;
+				continue;
+
+			case 'TSAsExpression':
+			case 'TSSatisfiesExpression':
+			case 'TSNonNullExpression':
+				node = node.expression;
+				continue;
+
+			// a sequence expression always prints its own wrapping parens
+			case 'SequenceExpression':
+				return false;
+
+			default:
+				return false;
+		}
+	}
+	return false;
+}
+
 /**
  * @param {TSESTree.VariableDeclaration} node
  * @param {Context} context

package/src/languages/types.d.ts

@@ -2,6 +2,14 @@ import type { BaseNode } from '../types';
 
 export type TSOptions = {
 	quotes?: 'double' | 'single';
+	/**
+	 * Anchor structural tokens (array/object brackets and braces, preserved
+	 * parentheses, unary operators, and the closing tokens of calls and
+	 * computed member access) with one-character source locations, so
+	 * node-boundary positions always resolve through the source map instead of
+	 * being attributed to the previous token. Denser maps; identical output.
+	 */
+	boundaryTokens?: boolean;
 	comments?: Comment[];
 	getLeadingComments?: (node: BaseNode) => BaseComment[] | undefined;
 	getTrailingComments?: (node: BaseNode) => BaseComment[] | undefined;

package/types/index.d.ts

@@ -95,6 +95,14 @@ declare module 'esrap/languages/ts' {
 		: SpecialisedVisitors<T> & { _?: (node: T, context: Context, visit: (node: T) => void) => void };
 	type TSOptions = {
 		quotes?: 'double' | 'single';
+		/**
+		 * Anchor structural tokens (array/object brackets and braces, preserved
+		 * parentheses, unary operators, and the closing tokens of calls and
+		 * computed member access) with one-character source locations, so
+		 * node-boundary positions always resolve through the source map instead of
+		 * being attributed to the previous token. Denser maps; identical output.
+		 */
+		boundaryTokens?: boolean;
 		comments?: Comment[];
 		getLeadingComments?: (node: BaseNode) => BaseComment[] | undefined;
 		getTrailingComments?: (node: BaseNode) => BaseComment[] | undefined;
@@ -149,6 +157,14 @@ declare module 'esrap/languages/tsx' {
 		: SpecialisedVisitors<T> & { _?: (node: T, context: Context, visit: (node: T) => void) => void };
 	type TSOptions = {
 		quotes?: 'double' | 'single';
+		/**
+		 * Anchor structural tokens (array/object brackets and braces, preserved
+		 * parentheses, unary operators, and the closing tokens of calls and
+		 * computed member access) with one-character source locations, so
+		 * node-boundary positions always resolve through the source map instead of
+		 * being attributed to the previous token. Denser maps; identical output.
+		 */
+		boundaryTokens?: boolean;
 		comments?: Comment[];
 		getLeadingComments?: (node: BaseNode) => BaseComment[] | undefined;
 		getTrailingComments?: (node: BaseNode) => BaseComment[] | undefined;

package/types/index.d.ts.map

@@ -37,6 +37,6 @@
 		null,
 		null
 	],
-	"mappings": ";MAEYA,QAAQA;;;;;;;;MAQfC,MAAMA;;MAENC,mBAAmBA;;;;MAIZC,OAAOA;;aAEPC,QAAQA;;;;WAWHC,QAAQA;;;;;;MAWbC,OAAOA;;kBAEFC,YAAYA;;;;;;;;;iBCWbC,KAAKA;;;;cC7CRC,OAAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aCLRC,IAAIA;yBACQC,EAAEA;;cAELC,sBAAsBA;MHJ/BZ,QAAQA;;;;;;;;MAQfC,MAAMA;;MAENC,mBAAmBA;;;;MAIZC,OAAOA;;MAEPC,QAAQA;;;MIhBRS,SAASA;;;;;;;WAOXC,QAAQA;;;;;;;kBAODC,WAAWA;;;;;;;kBAOXC,OAAOA;;;;;;;;;;;;aCpBZN,IAAIA;yBACQO,GAAGA;MLFfjB,QAAQA;;;;;;;;MAQfC,MAAMA;;MAENC,mBAAmBA;;;;MAIZC,OAAOA;;MAEPC,QAAQA;;;MIhBRS,SAASA;;;;;;;WAOXC,QAAQA;;;;;;;kBAODC,WAAWA;;;;;;;kBAOXC,OAAOA",
+	"mappings": ";MAEYA,QAAQA;;;;;;;;MAQfC,MAAMA;;MAENC,mBAAmBA;;;;MAIZC,OAAOA;;aAEPC,QAAQA;;;;WAWHC,QAAQA;;;;;;MAWbC,OAAOA;;kBAEFC,YAAYA;;;;;;;;;iBCWbC,KAAKA;;;;cC7CRC,OAAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;aCLRC,IAAIA;yBACQC,EAAEA;;cAELC,sBAAsBA;MHJ/BZ,QAAQA;;;;;;;;MAQfC,MAAMA;;MAENC,mBAAmBA;;;;MAIZC,OAAOA;;MAEPC,QAAQA;;;MIhBRS,SAASA;;;;;;;;;;;;;;;WAeXC,QAAQA;;;;;;;kBAODC,WAAWA;;;;;;;kBAOXC,OAAOA;;;;;;;;;;;;aC5BZN,IAAIA;yBACQO,GAAGA;MLFfjB,QAAQA;;;;;;;;MAQfC,MAAMA;;MAENC,mBAAmBA;;;;MAIZC,OAAOA;;MAEPC,QAAQA;;;MIhBRS,SAASA;;;;;;;;;;;;;;;WAeXC,QAAQA;;;;;;;kBAODC,WAAWA;;;;;;;kBAOXC,OAAOA",
 	"ignoreList": []
 }