@tsrx/core 0.1.47 → 0.1.48

package/package.json

@@ -3,7 +3,7 @@
   "description": "Core compiler infrastructure for TSRX syntax",
   "license": "MIT",
   "author": "Dominic Gannaway",
-  "version": "0.1.47",
+  "version": "0.1.48",
   "type": "module",
   "repository": {
     "type": "git",

package/src/index.js

@@ -149,6 +149,7 @@ export { normalize_css_property_name as normalizeCssPropertyName } from './utils
 export { escape, escape_script as escapeScript } from './utils/escaping.js';
 
 // Transform
+export { with_deferred_imports as withDeferredImports } from './transform/imports.js';
 export {
 	add_jsx_setup_declaration as addJsxSetupDeclaration,
 	clone_switch_helper_invocation as cloneSwitchHelperInvocation,

package/src/plugin.js

@@ -4688,6 +4688,67 @@ export function TSRXPlugin(config) {
 				this.parseTemplateBody(body);
 			}
 
+			/**
+			 * Parse the argument list of a deferred dynamic import,
+			 * `import.defer(specifier, options?)`, starting at the opening paren.
+			 *
+			 * This mirrors Acorn's ES2025 `import(...)` grammar (optional `options`
+			 * argument, optional trailing comma), which neither inherited parser
+			 * produces here: acorn-typescript's `parseDynamicImport` emits legacy
+			 * `arguments`, and Acorn's own only enables the `options` shape at
+			 * `ecmaVersion >= 16` while TSRX parses at 13.
+			 *
+			 * @param {AST.ImportExpression} node
+			 * @returns {AST.ImportExpression}
+			 */
+			parseDeferredDynamicImport(node) {
+				this.next(); // `(`
+				node.source = this.parseMaybeAssign();
+				node.options = null;
+
+				if (!this.eat(tt.parenR)) {
+					this.expect(tt.comma);
+					if (!this.afterTrailingComma(tt.parenR)) {
+						node.options = this.parseMaybeAssign();
+						if (!this.eat(tt.parenR)) {
+							this.expect(tt.comma);
+							if (!this.afterTrailingComma(tt.parenR)) this.unexpected();
+						}
+					}
+				}
+
+				return this.finishNode(node, 'ImportExpression');
+			}
+
+			/**
+			 * Recognize the deferred dynamic-import form
+			 * `import.defer(specifier, options?)` before Acorn parses `import.<name>`
+			 * as an `import.meta` member access. Ordinary `import()` and `import.meta`
+			 * fall through to Acorn unchanged, so the proposal never alters their
+			 * existing AST shape.
+			 * @type {Parse.Parser['parseExprImport']}
+			 */
+			parseExprImport(forNew) {
+				if (
+					!forNew &&
+					this.lookahead().type === tt.dot &&
+					this.isContextualWithState('defer', this.lookahead(2))
+				) {
+					const node = /** @type {AST.ImportExpression} */ (this.startNode());
+					if (this.containsEsc) {
+						this.raiseRecoverable(this.start, 'Escape sequence in keyword import');
+					}
+					this.next(); // `import`
+					this.next(); // `.`
+					this.next(); // `defer`
+					node.phase = 'defer';
+					if (this.type !== tt.parenL) this.unexpected();
+					return this.parseDeferredDynamicImport(node);
+				}
+
+				return super.parseExprImport(forNew);
+			}
+
 			/**
 			 * Parse proposal-style imports from an inline module declaration:
 			 * `import { foo } from server;`
@@ -4698,54 +4759,77 @@ export function TSRXPlugin(config) {
 			 * @type {Parse.Parser['parseImport']}
 			 */
 			parseImport(node) {
-				const tokenIsIdentifier = /** @type {any} */ (Parser.acornTypeScript).tokenIsIdentifier;
-				const parser = /** @type {any} */ (this);
-				const import_node = /** @type {any} */ (node);
-				let enterHead = parser.lookahead();
-				import_node.importKind = 'value';
-				parser.importOrExportOuterKind = 'value';
+				const tokenIsIdentifier = Parser.acornTypeScript.tokenIsIdentifier;
+				let enterHead = this.lookahead();
+				let deferred = false;
+				let defer_start = -1;
+				node.importKind = 'value';
+				this.importOrExportOuterKind = 'value';
 				if (tokenIsIdentifier(enterHead.type) || this.match(tt.star) || this.match(tt.braceL)) {
-					let ahead = parser.lookahead(2);
-					if (
+					let ahead = this.lookahead(2);
+					// `defer` and `type` are only phase/kind modifiers when the following
+					// token cannot continue a default import (`, `/`from`) or an
+					// import-equals declaration (`=`); otherwise they are ordinary bindings.
+					const head_modifies =
 						ahead.type !== tt.comma &&
-						!parser.isContextualWithState('from', ahead) &&
-						ahead.type !== tt.eq &&
-						parser.ts_eatContextualWithState('type', 1, enterHead)
-					) {
-						parser.importOrExportOuterKind = 'type';
-						import_node.importKind = 'type';
-						enterHead = parser.lookahead();
-						ahead = parser.lookahead(2);
+						!this.isContextualWithState('from', ahead) &&
+						ahead.type !== tt.eq;
+					// The namespace-only restriction is checked after parsing the clause,
+					// which also gives invalid named/default deferred imports a focused
+					// diagnostic.
+					if (head_modifies && this.isContextualWithState('defer', enterHead)) {
+						deferred = true;
+						defer_start = enterHead.start;
+						node.phase = 'defer';
+						this.ts_eatContextualWithState('defer', 1, enterHead);
+						enterHead = this.lookahead();
+						ahead = this.lookahead(2);
+					} else if (head_modifies && this.ts_eatContextualWithState('type', 1, enterHead)) {
+						this.importOrExportOuterKind = 'type';
+						node.importKind = 'type';
+						enterHead = this.lookahead();
+						ahead = this.lookahead(2);
 					}
 					if (tokenIsIdentifier(enterHead.type) && ahead.type === tt.eq) {
 						this.next();
-						const importNode = parser.tsParseImportEqualsDeclaration(node);
-						parser.importOrExportOuterKind = 'value';
+						const importNode = this.tsParseImportEqualsDeclaration(node);
+						this.importOrExportOuterKind = 'value';
 						return importNode;
 					}
 				}
 				this.next();
 				if (this.type === tt.string) {
-					import_node.specifiers = [];
-					import_node.source = this.parseExprAtom();
+					node.specifiers = [];
+					node.source = /** @type {AST.Literal} */ (this.parseExprAtom());
 				} else {
-					import_node.specifiers = this.parseImportSpecifiers();
+					node.specifiers = this.parseImportSpecifiers();
 					this.expectContextual('from');
 					if (this.type === tt.string) {
-						import_node.source = this.parseExprAtom();
+						node.source = /** @type {AST.Literal} */ (this.parseExprAtom());
 					} else if (tokenIsIdentifier(this.type)) {
 						const source = this.parseIdent(false);
 						source.metadata ??= { path: [] };
-						import_node.source = source;
+						node.source = source;
 					} else {
 						this.unexpected();
 					}
 				}
-				parser.parseMaybeImportAttributes(node);
+				if (
+					deferred &&
+					(node.specifiers.length !== 1 ||
+						node.specifiers[0].type !== 'ImportNamespaceSpecifier' ||
+						node.source.type !== 'Literal')
+				) {
+					this.raise(
+						defer_start,
+						'`import defer` only supports a namespace import from a string literal.',
+					);
+				}
+				this.parseMaybeImportAttributes(node);
 				this.semicolon();
 				this.finishNode(node, 'ImportDeclaration');
-				parser.importOrExportOuterKind = 'value';
-				return import_node;
+				this.importOrExportOuterKind = 'value';
+				return node;
 			}
 
 			/**

package/src/transform/imports.js

@@ -0,0 +1,96 @@
+/** @import * as AST from 'estree' */
+
+/**
+ * Add TSRX import-phase support to an esrap TS/TSX visitor set. esrap 2.3
+ * understands the rest of ImportDeclaration but does not print its Stage 3
+ * `phase` field yet, so delegating would silently turn a deferred import into
+ * an eager one.
+ *
+ * @template {Record<string, any>} T
+ * @param {T} visitors
+ * @returns {T}
+ */
+export function with_deferred_imports(visitors) {
+	const print_import_declaration = visitors.ImportDeclaration;
+	const print_import_expression = visitors.ImportExpression;
+	if (
+		typeof print_import_declaration !== 'function' ||
+		typeof print_import_expression !== 'function'
+	) {
+		throw new TypeError('Deferred imports require a complete esrap TS or TSX visitor set.');
+	}
+
+	return /** @type {T} */ ({
+		...visitors,
+		/**
+		 * @param {AST.ImportDeclaration} node
+		 * @param {import('esrap').Context} context
+		 */
+		ImportDeclaration(node, context) {
+			const import_node = /** @type {AST.ImportDeclaration & { phase?: 'defer' | null }} */ (node);
+			if (import_node.phase !== 'defer') {
+				print_import_declaration(node, context);
+				return;
+			}
+
+			const [specifier] = node.specifiers;
+			if (node.specifiers.length !== 1 || specifier.type !== 'ImportNamespaceSpecifier') {
+				throw new Error('`import defer` only supports a namespace import.');
+			}
+
+			if (node.loc) context.location(node.loc.start.line, node.loc.start.column);
+			context.write('import defer ');
+			if (specifier.loc) {
+				context.location(specifier.loc.start.line, specifier.loc.start.column);
+			}
+			context.write('* as ');
+			context.visit(specifier.local);
+			context.write(' from ');
+			context.visit(node.source);
+
+			const attributes =
+				/** @type {Array<{ key: AST.Identifier | AST.Literal, value: AST.Literal }>} */ (
+					/** @type {any} */ (node).attributes ?? /** @type {any} */ (node).assertions ?? []
+				);
+			if (attributes.length > 0) {
+				context.write(' with { ');
+				for (let index = 0; index < attributes.length; index++) {
+					context.visit(attributes[index].key);
+					context.write(': ');
+					context.visit(attributes[index].value);
+					if (index + 1 !== attributes.length) context.write(', ');
+				}
+				context.write(' }');
+			}
+
+			context.write(';');
+			if (node.loc) context.location(node.loc.end.line, node.loc.end.column);
+		},
+		/**
+		 * @param {AST.ImportExpression} node
+		 * @param {import('esrap').Context} context
+		 */
+		ImportExpression(node, context) {
+			const import_node = /** @type {AST.ImportExpression & { phase?: 'defer' | null }} */ (node);
+			if (import_node.phase !== 'defer') {
+				print_import_expression(node, context);
+				return;
+			}
+
+			if (node.loc) context.location(node.loc.start.line, node.loc.start.column);
+			context.write('import.defer(');
+			context.visit(node.source);
+
+			const options =
+				node.options ??
+				/** @type {AST.Expression | undefined} */ (/** @type {any} */ (node).arguments?.[0]);
+			if (options) {
+				context.write(', ');
+				context.visit(options);
+			}
+
+			context.write(')');
+			if (node.loc) context.location(node.loc.end.line, node.loc.end.column);
+		},
+	});
+}

package/src/transform/jsx/helpers.js

@@ -3,6 +3,7 @@
 
 import tsx from 'esrap/languages/tsx';
 import { should_preserve_comment, format_comment } from '../../comment-utils.js';
+import { with_deferred_imports } from '../imports.js';
 
 /**
  * Zimmerframe provides `path` as the ancestor chain. A native template node in
@@ -75,7 +76,7 @@ export function set_node_path_metadata(node, path) {
  * TS input — dropping a leading pragma changes how the whole file checks.
  */
 export function tsx_with_ts_locations(boundary_tokens = false, comments = undefined) {
-	const base = tsx({ boundaryTokens: boundary_tokens });
+	const base = with_deferred_imports(tsx({ boundaryTokens: boundary_tokens }));
 	const { _: base_visitor, ...base_visitors } = base;
 
 	const leading_preserved = (/** @type {AST.Program} */ program) => {

package/types/index.d.ts

@@ -310,6 +310,7 @@ declare module 'estree' {
 	// Include TypeScript node types and TSRX-specific nodes in NodeMap
 	interface NodeMap {
 		JSXSpreadChild: ESTreeJSX.JSXSpreadChild;
+		TSRXImportDeclaration: TSRXImportDeclaration;
 		TSRXJSXElement: TSRXJSXElement;
 		TSRXJSXFragment: TSRXJSXFragment;
 		TSRXJSXOpeningElement: ESTreeJSX.TSRXJSXOpeningElement;
@@ -547,6 +548,13 @@ declare module 'estree' {
 
 	interface ImportDeclaration {
 		importKind: TSESTree.ImportDeclaration['importKind'];
+		phase?: 'defer' | null;
+	}
+	interface TSRXImportDeclaration extends Omit<ImportDeclaration, 'source'> {
+		source: AST.Literal | AST.Identifier;
+	}
+	interface ImportExpression {
+		phase?: 'defer' | null;
 	}
 	interface ImportSpecifier {
 		importKind: TSESTree.ImportSpecifier['importKind'];
@@ -1391,7 +1399,7 @@ export interface AnalysisResult {
 	component_metadata: Array<{ id: string }>;
 	metadata: {
 		serverImportsPresent: boolean;
-		serverImportDeclarations: AST.ImportDeclaration[];
+		serverImportDeclarations: AST.TSRXImportDeclaration[];
 		serverModule: AST.TSModuleDeclaration | null;
 	};
 	errors: CompileError[];

package/types/parse.d.ts

@@ -420,6 +420,8 @@ export namespace Parse {
 	export interface AcornTypeScriptExtensions {
 		tokTypes: AcornTypeScriptTokTypes;
 		tokContexts: AcornTypeScriptTokContexts;
+		/** Whether a token type can start/continue an identifier (incl. TS soft keywords) */
+		tokenIsIdentifier(token: TokenType): boolean;
 	}
 
 	export interface AcornTypeScriptFunctionBodyConfig {
@@ -427,6 +429,31 @@ export namespace Parse {
 		isClassMethod?: boolean;
 	}
 
+	/**
+	 * Snapshot of tokenizer state returned by `lookahead()`, mirroring
+	 * @sveltejs/acorn-typescript's saved lookahead state. Callers inspect the
+	 * upcoming token (`type`/`value`/`start`/`containsEsc`) without consuming it,
+	 * and pass the snapshot to the `*WithState` contextual helpers.
+	 */
+	export interface LookaheadState {
+		pos: number;
+		type: TokenType;
+		value: string | number | RegExp | bigint | null;
+		start: number;
+		end: number;
+		startLoc: AST.Position;
+		endLoc: AST.Position;
+		lastTokEnd: number;
+		lastTokStart: number;
+		lastTokStartLoc: AST.Position;
+		lastTokEndLoc: AST.Position;
+		context: TokContext[];
+		curLine: number;
+		lineStart: number;
+		curPosition: () => AST.Position;
+		containsEsc: boolean;
+	}
+
 	interface Scope {
 		flags: number;
 		var: string[];
@@ -496,6 +523,11 @@ export namespace Parse {
 		inFunction: boolean;
 		/** Whether @sveltejs/acorn-typescript is currently parsing a TypeScript type */
 		inType: boolean;
+		/**
+		 * `value`/`type` kind of the import or export declaration currently being
+		 * parsed (@sveltejs/acorn-typescript). `undefined` when not inside one.
+		 */
+		importOrExportOuterKind?: 'value' | 'type';
 		/** Stack of label names for break/continue statements */
 		labels: Array<{ kind: string | null; name?: string; statementStart?: number }>;
 		/** Current scope flags stack */
@@ -756,6 +788,23 @@ export namespace Parse {
 		 */
 		expectContextual(name: string): void;
 
+		/**
+		 * Like `isContextual`, but tests a `lookahead()` snapshot instead of the
+		 * current token (@sveltejs/acorn-typescript).
+		 * @param keyword Keyword to check (e.g. "from", "defer")
+		 * @param state Lookahead snapshot to test
+		 */
+		isContextualWithState(keyword: string, state: LookaheadState): boolean;
+
+		/**
+		 * If `state` is the contextual keyword `name`, consume `nextCount` tokens
+		 * and return true (@sveltejs/acorn-typescript).
+		 * @param name Contextual keyword to eat (e.g. "type", "defer")
+		 * @param nextCount Number of tokens to advance when it matches
+		 * @param state Lookahead snapshot to test
+		 */
+		ts_eatContextualWithState(name: string, nextCount: number, state: LookaheadState): boolean;
+
 		/**
 		 * Check if semicolon can be inserted at current position (ASI)
 		 */
@@ -831,10 +880,11 @@ export namespace Parse {
 		// Lookahead
 		// ============================================================
 		/**
-		 * Look ahead one token without consuming
-		 * @returns Object with type and value of next token
+		 * Look ahead `number` tokens (default 1) without consuming, returning a
+		 * snapshot of the tokenizer state at that position.
+		 * @param number How many tokens to look ahead (default 1)
 		 */
-		lookahead(): { type: TokenType; value: any };
+		lookahead(number?: number): LookaheadState;
 
 		/**
 		 * Get next token start position
@@ -1461,7 +1511,17 @@ export namespace Parse {
 		// Module Parsing (Import/Export)
 		// ============================================================
 		/** Parse import declaration */
-		parseImport(node: AST.Node): AST.ImportDeclaration;
+		parseImport(node: AST.TSRXImportDeclaration): AST.TSRXImportDeclaration;
+
+		/**
+		 * Parse a TypeScript import-equals declaration, `import x = require('y')`
+		 * or `import x = A.B` (@sveltejs/acorn-typescript). Typed as
+		 * `ImportDeclaration` because estree has no `TSImportEqualsDeclaration`.
+		 */
+		tsParseImportEqualsDeclaration(node: AST.Node, isExport?: boolean): AST.ImportDeclaration;
+
+		/** Parse an optional import-attributes clause (`with { … }` / `assert { … }`) */
+		parseMaybeImportAttributes(node: AST.Node): void;
 
 		/** Parse import specifiers */
 		parseImportSpecifiers(): AST.ImportSpecifier[];