@tsrx/core 0.1.49 → 0.1.51

package/src/runtime/language-helpers.js

@@ -46,9 +46,10 @@ export function has_prototype_accessor(value, key) {
 
 /**
  * Slice helper for arrays and array-like values.
- * @param {ArrayLike<any>} array_like
+ * @template T
+ * @param {ArrayLike<T>} array_like
  * @param {...number} args
- * @returns {any[]}
+ * @returns {T[]}
  */
 export function array_slice(array_like, ...args) {
 	return is_array(array_like)
@@ -93,38 +94,46 @@ export function iterable_array_from(iterable, index = 0) {
 /**
  * Creates a shallow forwarding object without one prop. Values are exposed through
  * getters so compiler-emitted reactive prop accessors are not snapshotted.
- * @param {Record<PropertyKey, any> | null | undefined} props
- * @param {PropertyKey} exclude_prop
- * @returns {Record<PropertyKey, any>}
+ *
+ * @template {object} [T=Record<PropertyKey, unknown>]
+ * @template {PropertyKey} [K=PropertyKey]
+ * @param {T | null | undefined} props
+ * @param {K} exclude_prop
+ * @returns {Omit<T, K>} the forwarding object; `{}` when `props` is nullish
  */
 export function exclude_prop_from_object(props, exclude_prop) {
-	/** @type {Record<PropertyKey, any>} */
+	/** @type {Record<PropertyKey, unknown>} */
 	const next = {};
-	if (props == null) return next;
 
-	for (const prop of Reflect.ownKeys(props)) {
-		if (prop === exclude_prop) continue;
+	if (props != null) {
+		const source = /** @type {Record<PropertyKey, unknown>} */ (props);
 
-		const descriptor = get_descriptor(props, prop);
-		if (!descriptor?.enumerable) continue;
+		for (const prop of Reflect.ownKeys(source)) {
+			if (prop === exclude_prop) continue;
 
-		/** @type {PropertyDescriptor} */
-		const forwarding_descriptor = {
-			enumerable: true,
-			configurable: true,
-			get() {
-				return props[prop];
-			},
-		};
+			const descriptor = get_descriptor(source, prop);
+			if (!descriptor?.enumerable) continue;
 
-		if (descriptor.writable === true || typeof descriptor.set === 'function') {
-			forwarding_descriptor.set = (value) => {
-				props[prop] = value;
+			/** @type {PropertyDescriptor} */
+			const forwarding_descriptor = {
+				enumerable: true,
+				configurable: true,
+				get() {
+					return source[prop];
+				},
 			};
-		}
 
-		define_property(next, prop, forwarding_descriptor);
+			if (descriptor.writable === true || typeof descriptor.set === 'function') {
+				forwarding_descriptor.set = (value) => {
+					source[prop] = value;
+				};
+			}
+
+			define_property(next, prop, forwarding_descriptor);
+		}
 	}
 
-	return next;
+	// The forwarding object is assembled key by key, which no incremental type
+	// can describe; it mirrors `props` minus `exclude_prop` by construction.
+	return /** @type {Omit<T, K>} */ (next);
 }

package/src/runtime/ref.js

@@ -1,3 +1,5 @@
+/** @import { MergeableRef, RefProp, RefValue, SpreadProps } from '../../types/runtime/ref' */
+
 import {
 	has_own_property,
 	get_descriptor,
@@ -15,8 +17,9 @@ const REF_VALUE = Symbol();
  * any of the supported syntaxes.  It does not process spreads, that is delegated to
  * `normalize_spread_props`.
  *
- * @param {...((node: any) => void | (() => void)) | { current: any } | { value: any } | null | undefined} refs
- * @returns {(node: any) => (() => void)}
+ * @template [T=Element]
+ * @param {...MergeableRef<T>} refs
+ * @returns {(node: T | null) => (() => void)}
  */
 export function mergeRefs(...refs) {
 	return (node) => {
@@ -32,14 +35,14 @@ export function mergeRefs(...refs) {
 					cleanups.push(() => ref(null));
 				}
 			} else if (is_ref_object(ref, 'current')) {
-				/** @type {{ current: any }} */ (ref).current = node;
+				ref.current = node;
 				cleanups.push(() => {
-					/** @type {{ current: any }} */ (ref).current = null;
+					ref.current = null;
 				});
 			} else if (is_ref_object(ref, 'value')) {
-				/** @type {{ value: any }} */ (ref).value = node;
+				ref.value = node;
 				cleanups.push(() => {
-					/** @type {{ value: any }} */ (ref).value = null;
+					ref.value = null;
 				});
 			}
 		}
@@ -51,18 +54,31 @@ export function mergeRefs(...refs) {
 
 export { is_ref_prop as isRefProp };
 
+/**
+ * A ref value that is a function is a callback ref — the bare-element branch of
+ * `RefValue` is never callable.
+ *
+ * @template T
+ * @param {RefValue<T>} value
+ * @returns {value is (node: T | null) => void | (() => void)}
+ */
+function is_ref_callback(value) {
+	return typeof value === 'function';
+}
+
 /**
  * @param {unknown} value
- * @returns {boolean}
+ * @returns {value is RefProp<Element>}
  */
 function is_ref_prop(value) {
 	return typeof value === 'function' && REF_VALUE in value;
 }
 
 /**
- * @param {any} ref_value
- * @param {any} node
- * @param {(value: any) => void} [set_ref_value]
+ * @template [T=Element]
+ * @param {RefValue<T>} ref_value
+ * @param {T | null} node
+ * @param {(value: T | null) => void} [set_ref_value]
  * @returns {void | (() => void)}
  */
 export function apply_ref_value(ref_value, node, set_ref_value) {
@@ -73,7 +89,7 @@ export function apply_ref_value(ref_value, node, set_ref_value) {
 			const cleanup = apply_ref_value(item, node);
 			if (typeof cleanup === 'function') {
 				cleanups.push(cleanup);
-			} else if (typeof item === 'function' && node !== null) {
+			} else if (is_ref_callback(item) && node !== null) {
 				cleanups.push(() => item(null));
 			}
 		}
@@ -85,7 +101,7 @@ export function apply_ref_value(ref_value, node, set_ref_value) {
 		return;
 	}
 
-	if (typeof ref_value === 'function') {
+	if (is_ref_callback(ref_value)) {
 		return ref_value(node);
 	}
 
@@ -111,13 +127,14 @@ export function apply_ref_value(ref_value, node, set_ref_value) {
 }
 
 /**
- * @param {() => any} get_ref_value
- * @param {(value: any) => void} [set_ref_value]
- * @returns {(node: any) => void | (() => void)}
+ * @template [T=Element]
+ * @param {() => RefValue<T>} get_ref_value
+ * @param {(value: T | null) => void} [set_ref_value]
+ * @returns {RefProp<T>}
  */
 export function create_ref_prop(get_ref_value, set_ref_value) {
 	/**
-	 * @param {any} node
+	 * @param {T | null} node
 	 * @returns {void | (() => void)}
 	 */
 	function ref_prop_callback(node) {
@@ -140,8 +157,9 @@ export function create_ref_prop(get_ref_value, set_ref_value) {
 }
 
 /**
- * @param {...any} refs
- * @returns {any}
+ * @template [T=Element]
+ * @param {...RefValue<T>} refs
+ * @returns {RefValue<T>} the single surviving ref, or a callback applying all
  */
 export function merge_ref_props(...refs) {
 	const filtered = refs.filter((ref) => ref != null);
@@ -155,7 +173,7 @@ export function merge_ref_props(...refs) {
 	}
 
 	/**
-	 * @param {any} node
+	 * @param {T | null} node
 	 * @returns {void | (() => void)}
 	 */
 	function merged_ref_prop(node) {
@@ -166,7 +184,7 @@ export function merge_ref_props(...refs) {
 			const cleanup = apply_ref_value(ref, node);
 			if (typeof cleanup === 'function') {
 				cleanups.push(cleanup);
-			} else if (typeof ref === 'function' && node !== null) {
+			} else if (is_ref_callback(ref) && node !== null) {
 				cleanups.push(() => ref(null));
 			}
 		}
@@ -182,36 +200,38 @@ export function merge_ref_props(...refs) {
 }
 
 /**
- * @param {Record<string | symbol, any> | null | undefined} props
- * @param {...any} outer_refs
- * @returns {Record<string | symbol, any> | null | undefined}
+ * @param {object | null | undefined} props a props bag; `object` rather than an
+ *   index signature so an interface-typed bag is accepted
+ * @param {...RefValue<Element>} outer_refs
+ * @returns {SpreadProps | null | undefined}
  */
 export function normalize_spread_props(props, ...outer_refs) {
 	if (props == null) {
 		return props;
 	}
 
-	/** @type {any[]} */
+	const source = /** @type {SpreadProps} */ (props);
+	/** @type {Array<RefValue<Element>>} */
 	const refs = [];
-	/** @type {Record<string | symbol, any>} */
-	let next = {};
+	/** @type {SpreadProps} */
+	const next = {};
 	let changed = false;
 	let existing_ref;
 
-	for (const key of Reflect.ownKeys(props)) {
-		const descriptor = get_descriptor(props, key);
+	for (const key of Reflect.ownKeys(source)) {
+		const descriptor = get_descriptor(source, key);
 		if (!descriptor?.enumerable) {
 			continue;
 		}
 
-		const value = /** @type {any} */ (props)[key];
+		const value = source[key];
 
 		if (key === 'ref') {
 			if (is_ref_prop(value)) {
 				refs.push(value);
 				changed = true;
 			} else {
-				existing_ref = value;
+				existing_ref = /** @type {RefValue<Element>} */ (value);
 			}
 			continue;
 		}
@@ -226,7 +246,7 @@ export function normalize_spread_props(props, ...outer_refs) {
 	}
 
 	if (!changed && outer_refs.length === 0) {
-		return props;
+		return source;
 	}
 
 	const merged_ref = merge_ref_props(existing_ref, ...refs, ...outer_refs);
@@ -243,9 +263,9 @@ export function normalize_spread_props(props, ...outer_refs) {
  * attribute but is non-enumerable so `{...normalized}` does not also pass it as
  * a DOM prop.
  *
- * @param {Record<string | symbol, any> | null | undefined} props
- * @param {...any} outer_refs
- * @returns {Record<string | symbol, any> | null | undefined}
+ * @param {object | null | undefined} props
+ * @param {...RefValue<Element>} outer_refs
+ * @returns {SpreadProps | null | undefined}
  */
 export function normalize_spread_props_for_ref_attr(props, ...outer_refs) {
 	const next = normalize_spread_props(props, ...outer_refs);
@@ -266,9 +286,10 @@ export function normalize_spread_props_for_ref_attr(props, ...outer_refs) {
 }
 
 /**
+ * @template {'current' | 'value'} K
  * @param {object} value
- * @param {'current' | 'value'} key
- * @returns {boolean}
+ * @param {K} key
+ * @returns {value is Record<K, unknown>}
  */
 function is_ref_object(value, key) {
 	if (is_dom_node(value)) {

package/src/scope.js

@@ -5,7 +5,8 @@
 	ScopeRootInterface,
 	Context,
 	ScopeConstructorInterface,
-	ScopeConstructorParameters
+	ScopeConstructorParameters,
+	ScopeState
 } from '../types/index';
  @import * as AST from 'estree';
  */
@@ -27,14 +28,12 @@ import * as b from './utils/builders.js';
  * @returns {{ scope: ScopeInterface, scopes: Map<AST.Node, ScopeInterface> }} Scope information
  */
 export function create_scopes(ast, root, parent, error_options) {
-	/** @typedef {{ scope: ScopeInterface }} State */
-
 	/** @type {Map<AST.Node, ScopeInterface>} */
 	const scopes = new Map();
 	const scope = new Scope(root, parent, false, error_options);
 	scopes.set(ast, scope);
 
-	/** @type {State} */
+	/** @type {ScopeState} */
 	const state = { scope };
 	/** @type {Array<[ScopeInterface, { node: AST.Identifier, path: AST.Node[] }]>} */
 	const references = [];
@@ -57,7 +56,7 @@ export function create_scopes(ast, root, parent, error_options) {
 	/**
 	 * Create a block scope
 	 * @param {AST.Node} node - AST node
-	 * @param {Context<AST.Node, State>} context - Visitor context
+	 * @param {Context<AST.Node, ScopeState>} context - Visitor context
 	 */
 	const create_block_scope = (node, { state, next }) => {
 		const scope = state.scope.child(true);

package/src/source-map-utils.js

@@ -1,32 +1,18 @@
 /**
  * @import { PostProcessingChanges, LineOffsets } from '../types/index.js';
  * @import * as AST from 'estree';
- * @import { CodeMapping } from '../types/index.js';
+ * @import {
+ *   CodeMapping,
+ *   CodePosition,
+ *   CodeToGeneratedMap,
+ *   GeneratedToSourceMap,
+ *   SourceLineGeneratedMap,
+ *   SourceLineGeneratedPosition,
+ * } from '../types/index.js';
  * @import { CodeMapping as VolarCodeMapping } from '@volar/language-core';
  * @import { RawSourceMap } from 'source-map';
  */
 
-/**
- * @typedef {{
- *   line: number,
- *   column: number,
- *   end_line: number,
- *   end_column: number,
- *   code: string,
- *   metadata: {
- *     css?: AST.Node['metadata']['css']
- *   },
- * }} CodePosition
- * @typedef {{
- *   column: number,
- *   position: CodePosition,
- * }} SourceLineGeneratedPosition
- */
-
-/** @typedef {Map<string, CodePosition[]>} CodeToGeneratedMap */
-/** @typedef {Map<string, {line: number, column: number}[]>} GeneratedToSourceMap */
-/** @typedef {Map<number, SourceLineGeneratedPosition[]>} SourceLineGeneratedMap */
-
 import { decode } from '@jridgewell/sourcemap-codec';
 
 /** @type {VolarCodeMapping['data']} */

package/src/transform/imports.js

@@ -1,4 +1,5 @@
 /** @import * as AST from 'estree' */
+/** @import * as ESRap from 'esrap' */
 
 /**
  * Add TSRX import-phase support to an esrap TS/TSX visitor set. esrap 2.3
@@ -6,7 +7,7 @@
  * `phase` field yet, so delegating would silently turn a deferred import into
  * an eager one.
  *
- * @template {Record<string, any>} T
+ * @template {ESRap.Visitors} T
  * @param {T} visitors
  * @returns {T}
  */
@@ -24,11 +25,10 @@ export function with_deferred_imports(visitors) {
 		...visitors,
 		/**
 		 * @param {AST.ImportDeclaration} node
-		 * @param {import('esrap').Context} context
+		 * @param {ESRap.Context} context
 		 */
 		ImportDeclaration(node, context) {
-			const import_node = /** @type {AST.ImportDeclaration & { phase?: 'defer' | null }} */ (node);
-			if (import_node.phase !== 'defer') {
+			if (node.phase !== 'defer') {
 				print_import_declaration(node, context);
 				return;
 			}
@@ -48,10 +48,7 @@ export function with_deferred_imports(visitors) {
 			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 ?? []
-				);
+			const attributes = node.attributes ?? node.assertions ?? [];
 			if (attributes.length > 0) {
 				context.write(' with { ');
 				for (let index = 0; index < attributes.length; index++) {
@@ -68,11 +65,10 @@ export function with_deferred_imports(visitors) {
 		},
 		/**
 		 * @param {AST.ImportExpression} node
-		 * @param {import('esrap').Context} context
+		 * @param {ESRap.Context} context
 		 */
 		ImportExpression(node, context) {
-			const import_node = /** @type {AST.ImportExpression & { phase?: 'defer' | null }} */ (node);
-			if (import_node.phase !== 'defer') {
+			if (node.phase !== 'defer') {
 				print_import_expression(node, context);
 				return;
 			}
@@ -81,9 +77,7 @@ export function with_deferred_imports(visitors) {
 			context.write('import.defer(');
 			context.visit(node.source);
 
-			const options =
-				node.options ??
-				/** @type {AST.Expression | undefined} */ (/** @type {any} */ (node).arguments?.[0]);
+			const options = node.options ?? node.arguments?.[0];
 			if (options) {
 				context.write(', ');
 				context.visit(options);

package/src/transform/jsx/ast-builders.js

@@ -108,7 +108,10 @@ function clone_jsx_member_expression(name, source_node) {
 export function add_extra_source_mappings_from_matching_expression(generated, source) {
 	if (!generated || !source || generated.type !== source.type) return;
 
-	if (generated.type === 'Identifier' || generated.type === 'PrivateIdentifier') {
+	if (
+		(generated.type === 'Identifier' && source.type === 'Identifier') ||
+		(generated.type === 'PrivateIdentifier' && source.type === 'PrivateIdentifier')
+	) {
 		if (!has_location(source)) return;
 		generated.metadata ??= { path: [] };
 		generated.metadata.extra_source_mappings ??= [];

package/src/transform/jsx/index.js

@@ -66,6 +66,7 @@ import {
 	is_function_node,
 	is_function_or_class_node as is_function_or_class_boundary,
 	is_template_directive as is_jsx_control_flow_expression,
+	node_children,
 } from '../../utils/ast.js';
 
 const TEMPLATE_FRAGMENT_ERROR =
@@ -1046,19 +1047,6 @@ function inject_dynamic_import(program, transform_context) {
 	);
 }
 
-/**
- * The children a node carries, as nodes. Node types differ in whether they
- * have a `children` slot at all (`JSXCodeBlock` does not) and in what it may
- * hold, so this reads it uniformly instead of forcing every caller to narrow.
- *
- * @param {AST.Node} node
- * @returns {AST.Node[]}
- */
-function node_children(node) {
-	const children = /** @type {AST.TraversableAstNode} */ (node).children;
-	return Array.isArray(children) ? children.filter(is_ast_node) : [];
-}
-
 /**
  * Attach selector-location metadata used by editor definitions/hover before
  * the shared scoping pass mutates class attributes with the component hash.