$inspect rune

.changeset/large-clouds-carry.md

@@ -0,0 +1,5 @@
+---
+'svelte': patch
+---
+
+feat: $inspect rune

packages/svelte/src/compiler/phases/2-analyze/index.js

@@ -265,7 +265,7 @@ export function analyze_component(root, options) {
 		// is referencing a rune and not a global store.
 		if (
 			options.runes === false ||
-			!Runes.includes(name) ||
+			!Runes.includes(/** @type {any} */ (name)) ||
 			(declaration !== null &&
 				// const state = $state(0) is valid
 				get_rune(declaration.initial, instance.scope) === null &&
@@ -279,7 +279,7 @@ export function analyze_component(root, options) {
 			if (options.runes !== false) {
 				if (declaration === null && /[a-z]/.test(store_name[0])) {
 					error(references[0].node, 'illegal-global', name);
-				} else if (declaration !== null && Runes.includes(name)) {
+				} else if (declaration !== null && Runes.includes(/** @type {any} */ (name))) {
 					for (const { node, path } of references) {
 						if (path.at(-1)?.type === 'CallExpression') {
 							warn(warnings, node, [], 'store-with-rune-name', store_name);
@@ -326,7 +326,10 @@ export function analyze_component(root, options) {
 			get_css_hash: options.cssHash
 		}),
 		runes:
-			options.runes ?? Array.from(module.scope.references).some(([name]) => Runes.includes(name)),
+			options.runes ??
+			Array.from(module.scope.references).some(([name]) =>
+				Runes.includes(/** @type {any} */ (name))
+			),
 		exports: [],
 		uses_props: false,
 		uses_rest_props: false,
@@ -660,6 +663,14 @@ const runes_scope_js_tweaker = {
 
 /** @type {import('./types').Visitors} */
 const runes_scope_tweaker = {
+	CallExpression(node, { state, next }) {
+		const rune = get_rune(node, state.scope);
+
+		// `$inspect(foo)` should not trigger the `static-state-reference` warning
+		if (rune === '$inspect') {
+			next({ ...state, function_depth: state.function_depth + 1 });
+		}
+	},
 	VariableDeclarator(node, { state }) {
 		const init = unwrap_ts_expression(node.init);
 		if (!init || init.type !== 'CallExpression') return;
@@ -880,6 +891,7 @@ const common_visitors = {
 	Identifier(node, context) {
 		const parent = /** @type {import('estree').Node} */ (context.path.at(-1));
 		if (!is_reference(node, parent)) return;
+
 		const binding = context.state.scope.get(node.name);
 
 		// if no binding, means some global variable

packages/svelte/src/compiler/phases/2-analyze/validation.js

@@ -521,13 +521,19 @@ function validate_call_expression(node, scope, path) {
 
 	if (rune === '$effect.active') {
 		if (node.arguments.length !== 0) {
-			error(node, 'invalid-rune-args-length', '$effect.active', [0]);
+			error(node, 'invalid-rune-args-length', rune, [0]);
 		}
 	}
 
 	if (rune === '$effect.root') {
 		if (node.arguments.length !== 1) {
-			error(node, 'invalid-rune-args-length', '$effect.root', [1]);
+			error(node, 'invalid-rune-args-length', rune, [1]);
+		}
+	}
+
+	if (rune === '$inspect') {
+		if (node.arguments.length < 1 || node.arguments.length > 2) {
+			error(node, 'invalid-rune-args-length', rune, [1, 2]);
 		}
 	}
 }

packages/svelte/src/compiler/phases/3-transform/client/utils.js

@@ -288,7 +288,8 @@ function get_hoistable_params(node, context) {
 				params.push(b.id(binding.node.name.slice(1)));
 				params.push(b.id(binding.node.name));
 			} else {
-				params.push(binding.node);
+				// create a copy to remove start/end tags which would mess up source maps
+				params.push(b.id(binding.node.name));
 			}
 		}
 	}

packages/svelte/src/compiler/phases/3-transform/client/visitors/javascript-runes.js

@@ -136,7 +136,7 @@ export const javascript_visitors_runes = {
 		for (const declarator of node.declarations) {
 			const init = unwrap_ts_expression(declarator.init);
 			const rune = get_rune(init, state.scope);
-			if (!rune || rune === '$effect.active' || rune === '$effect.root') {
+			if (!rune || rune === '$effect.active' || rune === '$effect.root' || rune === '$inspect') {
 				if (init != null && is_hoistable_function(init)) {
 					const hoistable_function = visit(init);
 					state.hoisted.push(
@@ -307,6 +307,19 @@ export const javascript_visitors_runes = {
 			return b.call('$.user_root_effect', ...args);
 		}
 
+		if (rune === '$inspect') {
+			if (state.options.dev) {
+				const arg = /** @type {import('estree').Expression} */ (visit(node.arguments[0]));
+				const fn =
+					node.arguments[1] &&
+					/** @type {import('estree').Expression} */ (visit(node.arguments[1]));
+
+				return b.call('$.inspect', b.thunk(arg), fn);
+			}
+
+			return b.unary('void', b.literal(0));
+		}
+
 		next();
 	}
 };

packages/svelte/src/compiler/phases/3-transform/server/transform-server.js

@@ -575,7 +575,7 @@ const javascript_visitors_runes = {
 		for (const declarator of node.declarations) {
 			const init = unwrap_ts_expression(declarator.init);
 			const rune = get_rune(init, state.scope);
-			if (!rune || rune === '$effect.active') {
+			if (!rune || rune === '$effect.active' || rune === '$inspect') {
 				declarations.push(/** @type {import('estree').VariableDeclarator} */ (visit(declarator)));
 				continue;
 			}
@@ -630,13 +630,25 @@ const javascript_visitors_runes = {
 		}
 		context.next();
 	},
-	CallExpression(node, { state, next }) {
+	CallExpression(node, { state, next, visit }) {
 		const rune = get_rune(node, state.scope);
 
 		if (rune === '$effect.active') {
 			return b.literal(false);
 		}
 
+		if (rune === '$inspect') {
+			if (state.options.dev) {
+				const args = /** @type {import('estree').Expression[]} */ (
+					node.arguments.map((arg) => visit(arg))
+				);
+
+				return b.call('console.log', ...args);
+			}
+
+			return b.unary('void', b.literal(0));
+		}
+
 		next();
 	}
 };

packages/svelte/src/compiler/phases/constants.js

@@ -70,15 +70,16 @@ export const ElementBindings = [
 	'indeterminate'
 ];
 
-export const Runes = [
+export const Runes = /** @type {const} */ ([
 	'$state',
 	'$props',
 	'$derived',
 	'$effect',
 	'$effect.pre',
 	'$effect.active',
-	'$effect.root'
-];
+	'$effect.root',
+	'$inspect'
+]);
 
 /**
  * Whitespace inside one of these elements will not result in

packages/svelte/src/compiler/phases/scope.js

@@ -672,6 +672,7 @@ export function set_scope(scopes) {
  * Returns the name of the rune if the given expression is a `CallExpression` using a rune.
  * @param {import('estree').Node | null | undefined} node
  * @param {Scope} scope
+ * @returns {Runes[number] | null}
  */
 export function get_rune(node, scope) {
 	if (!node) return null;
@@ -691,10 +692,10 @@ export function get_rune(node, scope) {
 	if (n.type !== 'Identifier') return null;
 
 	joined = n.name + joined;
-	if (!Runes.includes(joined)) return null;
+	if (!Runes.includes(/** @type {any} */ (joined))) return null;
 
 	const binding = scope.get(n.name);
 	if (binding !== null) return null; // rune name, but references a variable or store
 
-	return joined;
+	return /** @type {Runes[number] | null} */ (joined);
 }

packages/svelte/src/compiler/utils/builders.js

@@ -72,7 +72,7 @@ export function labeled(name, body) {
 
 /**
  * @param {string | import('estree').Expression} callee
- * @param {...import('estree').Expression} args
+ * @param {...(import('estree').Expression | import('estree').SpreadElement)} args
  * @returns {import('estree').CallExpression}
  */
 export function call(callee, ...args) {

packages/svelte/src/internal/client/runtime.js

@@ -2,7 +2,7 @@ import { DEV } from 'esm-env';
 import { subscribe_to_store } from '../../store/utils.js';
 import { EMPTY_FUNC, run_all } from '../common.js';
 import { unwrap } from './render.js';
-import { is_array } from './utils.js';
+import { get_descriptors, is_array } from './utils.js';
 
 export const SOURCE = 1;
 export const DERIVED = 1 << 1;
@@ -69,8 +69,14 @@ let current_skip_consumer = false;
 // Handle collecting all signals which are read during a specific time frame
 let is_signals_recorded = false;
 let captured_signals = new Set();
-// Handle rendering tree blocks and anchors
 
+/** @type {Function | null} */
+let inspect_fn = null;
+
+/** @type {Array<import('./types.js').SourceSignal & import('./types.js').SourceSignalDebug>} */
+let inspect_captured_signals = [];
+
+// Handle rendering tree blocks and anchors
 /** @type {null | import('./types.js').Block} */
 export let current_block = null;
 // Handling runtime component context
@@ -145,10 +151,26 @@ function default_equals(a, b) {
  * @template V
  * @param {import('./types.js').SignalFlags} flags
  * @param {V} value
- * @returns {import('./types.js').SourceSignal<V>}
+ * @returns {import('./types.js').SourceSignal<V> | import('./types.js').SourceSignal<V> & import('./types.js').SourceSignalDebug}
  */
 function create_source_signal(flags, value) {
-	const source = {
+	if (DEV) {
+		return {
+			// consumers
+			c: null,
+			// equals
+			e: null,
+			// flags
+			f: flags,
+			// value
+			v: value,
+			// context: We can remove this if we get rid of beforeUpdate/afterUpdate
+			x: null,
+			// this is for DEV only
+			inspect: new Set()
+		};
+	}
+	return {
 		// consumers
 		c: null,
 		// equals
@@ -160,7 +182,6 @@ function create_source_signal(flags, value) {
 		// context: We can remove this if we get rid of beforeUpdate/afterUpdate
 		x: null
 	};
-	return source;
 }
 
 /**
@@ -688,7 +709,7 @@ export function store_get(store, store_name, stores) {
 /**
  * @template V
  * @param {import('./types.js').Store<V> | null | undefined} store
- * @param {import('./types.js').Signal<V>} source
+ * @param {import('./types.js').SourceSignal<V>} source
  */
 function connect_store_to_signal(store, source) {
 	if (store == null) {
@@ -756,6 +777,14 @@ export function exposable(fn) {
  * @returns {V}
  */
 export function get(signal) {
+	// @ts-expect-error
+	if (DEV && signal.inspect && inspect_fn) {
+		// @ts-expect-error
+		signal.inspect.add(inspect_fn);
+		// @ts-expect-error
+		inspect_captured_signals.push(signal);
+	}
+
 	const flags = signal.f;
 	if ((flags & DESTROYED) !== 0) {
 		return signal.v;
@@ -811,7 +840,7 @@ export function set(signal, value) {
  * @returns {void}
  */
 export function set_sync(signal, value) {
-	flushSync(() => set_signal_value(signal, value));
+	flushSync(() => set(signal, value));
 }
 
 /**
@@ -1016,6 +1045,12 @@ export function set_signal_value(signal, value) {
 				});
 			}
 		}
+
+		// @ts-expect-error
+		if (DEV && signal.inspect) {
+			// @ts-expect-error
+			for (const fn of signal.inspect) fn();
+		}
 	}
 }
 
@@ -1727,3 +1762,69 @@ export function pop(accessors) {
 		context_stack_item.m = true;
 	}
 }
+
+/**
+ * @param {any} value
+ * @param {Set<any>} visited
+ * @returns {void}
+ */
+function deep_read(value, visited = new Set()) {
+	if (typeof value === 'object' && value !== null && !visited.has(value)) {
+		visited.add(value);
+		for (let key in value) {
+			deep_read(value[key], visited);
+		}
+		const proto = Object.getPrototypeOf(value);
+		if (
+			proto !== Object.prototype &&
+			proto !== Array.prototype &&
+			proto !== Map.prototype &&
+			proto !== Set.prototype &&
+			proto !== Date.prototype
+		) {
+			const descriptors = get_descriptors(proto);
+			for (let key in descriptors) {
+				const get = descriptors[key].get;
+				if (get) {
+					get.call(value);
+				}
+			}
+		}
+	}
+}
+
+/**
+ * @param {() => import('./types.js').MaybeSignal<>} get_value
+ * @param {Function} inspect
+ * @returns {void}
+ */
+// eslint-disable-next-line no-console
+export function inspect(get_value, inspect = console.log) {
+	let initial = true;
+
+	pre_effect(() => {
+		const fn = () => {
+			const value = get_value();
+			inspect(value, initial ? 'init' : 'update');
+		};
+
+		inspect_fn = fn;
+		const value = get_value();
+		deep_read(value);
+		inspect_fn = null;
+
+		const signals = inspect_captured_signals.slice();
+		inspect_captured_signals = [];
+
+		if (initial) {
+			fn();
+			initial = false;
+		}
+
+		return () => {
+			for (const s of signals) {
+				s.inspect.delete(fn);
+			}
+		};
+	});
+}

packages/svelte/src/internal/client/types.d.ts

@@ -80,6 +80,11 @@ export type SourceSignal<V = unknown> = {
 	v: V;
 };
 
+export type SourceSignalDebug = {
+	/** This is DEV only */
+	inspect: Set<Function>;
+};
+
 export type ComputationSignal<V = unknown> = {
 	/** block: The block associated with this effect/computed */
 	b: null | Block;