octane 0.1.4 → 0.1.5

package/README.md

@@ -6,9 +6,11 @@
 
 Octane is a fast, TypeScript-first UI framework, and the successor to
 [Inferno](https://github.com/infernojs/inferno). It gives you the React API you
-already know, a compiler that keeps the runtime small and fast, and no rules of
-hooks, so you can call hooks conditionally. This package ships both the runtime
-and the compiler, with the compiler exposed at `octane/compiler`.
+already know, a compiler that keeps the runtime small and fast, no rules of
+hooks, and no hand-maintained dependency arrays in the common case. Omit a hook's
+dependency list and the compiler derives it from the closure; explicit arrays
+retain React semantics, while `null` means every render. This package ships both
+the runtime and compiler, with the compiler exposed at `octane/compiler`.
 
 For the full story, see the
 [main README](https://github.com/octanejs/octane#readme).

package/dist/compiler/compile.js

@@ -36,6 +36,7 @@ import {
 } from '@tsrx/core';
 import { print as esrapPrint } from 'esrap';
 import esrapTsx from 'esrap/languages/tsx';
+import { applyHookDependencies } from './hook-deps.js';
 
 // DOM truth tables shared with the client/server runtimes (via constants.ts) —
 // static bakes and dynamic writes MUST agree on which attributes render, under
@@ -575,7 +576,7 @@ function collectComponentLocals(componentNode) {
  * memoising on.
  *
  * Stability sources:
- *   - useState / useReducer setters (second destructured slot)
+ *   - useState / useReducer setters and state getters (second/third slots)
  *   - useRef returns (the ref object itself, not .current)
  *   - useCallback / useEffectEvent returns
  *   - Arrows previously declared in this body whose free vars are themselves
@@ -605,8 +606,20 @@ function computeStableLocals(statements, componentLocals) {
 					decl.id.elements[1].type === 'Identifier'
 				) {
 					stable.add(decl.id.elements[1].name);
-					continue;
 				}
+				// [_, _, getX] = useState(...) — the compiler-generated getter
+				// closes over the hook cell and is stable for that cell's lifetime.
+				if (
+					(callName === 'useState' || callName === 'useReducer') &&
+					decl.id.type === 'ArrayPattern' &&
+					decl.id.elements &&
+					decl.id.elements.length >= 3 &&
+					decl.id.elements[2] &&
+					decl.id.elements[2].type === 'Identifier'
+				) {
+					stable.add(decl.id.elements[2].name);
+				}
+				if (callName === 'useState' || callName === 'useReducer') continue;
 				// x = useRef(...) / useCallback(...) / useEffectEvent(...) — the
 				// return value is stable for the lifetime of the component.
 				if (
@@ -1430,6 +1443,11 @@ export function compile(source, filename, options) {
 	// Normalize arrow-function components (`const X = () => @{…}`) to
 	// FunctionDeclaration form so the component pipeline recognizes them.
 	normalizeArrowComponents(ast);
+	// Omitted dependency lists are compiler-owned: infer reactive captures
+	// before any component splitting/hoisting so every lexical binding is still
+	// visible to the shared TSRX/TSX analysis. Explicit arrays and `null` pass
+	// through untouched.
+	applyHookDependencies(ast, { filename });
 	const hmrEnabled = !!(options && options.hmr);
 	// Dev mode: emit dev-only hydration source-location metadata (a per-component
 	// `__s.locs` table of structured {line,column} keyed by slot index + the module file
@@ -1897,6 +1915,10 @@ function compileServer(source, filename, options) {
 	// Normalize arrow-function components (`const X = () => @{…}`) to
 	// FunctionDeclaration form so the component pipeline recognizes them.
 	normalizeArrowComponents(ast);
+	// Mirror the client transform exactly. Effects are server no-ops, but
+	// useMemo/useCallback execute during SSR and must receive the same inferred
+	// dependency shape as hydration's client compile.
+	applyHookDependencies(ast, { filename });
 	const ctx = {
 		filename,
 		mode: 'server',
@@ -4152,7 +4174,86 @@ function rejectHookInJsLoop(loop, ctx, componentName) {
 	walk(loop);
 }
 
+const STATE_GETTER_HELPERS = {
+	useState: '__useStateWithGetter',
+	useReducer: '__useReducerWithGetter',
+};
+
+function arrayPatternObservesStateGetter(pattern) {
+	const elements = pattern.elements || [];
+	if (elements[2] != null) return true;
+	// A rest before/at index 2 observes the getter even without an explicit
+	// third binding: `[state, ...rest]` includes both update and getState.
+	for (let i = 0; i <= 2 && i < elements.length; i++) {
+		if (elements[i]?.type === 'RestElement') return true;
+	}
+	return false;
+}
+
+function isTransparentStateTupleWrapper(node, child) {
+	if (!node) return false;
+	if (
+		node.type === 'TSAsExpression' ||
+		node.type === 'TSTypeAssertion' ||
+		node.type === 'TSNonNullExpression' ||
+		node.type === 'ParenthesizedExpression' ||
+		node.type === 'ChainExpression'
+	) {
+		return node.expression === child;
+	}
+	return false;
+}
+
+// Source-level useState/useReducer tuples have a third getState member. Mark
+// calls that can observe it so rewriteHookCalls can select a specialized helper;
+// the ordinary two-item runtime path remains byte-for-byte for proven-dead
+// getters. Any escaping/ambiguous tuple is conservative and gets the full shape.
+function markStateGetterUsage(root) {
+	const ancestors = [];
+	function walk(node) {
+		if (node == null || typeof node !== 'object') return;
+		if (Array.isArray(node)) {
+			for (const child of node) walk(child);
+			return;
+		}
+		if (
+			node.type === 'CallExpression' &&
+			node.callee?.type === 'Identifier' &&
+			STATE_GETTER_HELPERS[node.callee.name]
+		) {
+			let child = node;
+			let i = ancestors.length - 1;
+			while (i >= 0 && isTransparentStateTupleWrapper(ancestors[i], child)) {
+				child = ancestors[i--];
+			}
+			const parent = i >= 0 ? ancestors[i] : null;
+			let observed = true;
+			if (parent?.type === 'VariableDeclarator' && parent.init === child) {
+				observed = parent.id.type !== 'ArrayPattern' || arrayPatternObservesStateGetter(parent.id);
+			} else if (parent?.type === 'AssignmentExpression' && parent.right === child) {
+				observed =
+					parent.left.type !== 'ArrayPattern' || arrayPatternObservesStateGetter(parent.left);
+			} else if (parent?.type === 'MemberExpression' && parent.object === child) {
+				const p = parent.property;
+				const index = parent.computed && p?.type === 'Literal' ? Number(p.value) : NaN;
+				observed = index !== 0 && index !== 1;
+			} else if (parent?.type === 'ExpressionStatement') {
+				observed = false;
+			}
+			node._octaneStateGetter = observed;
+		}
+		ancestors.push(node);
+		for (const key in node) {
+			if (AST_WALK_SKIP_KEYS.has(key) || key === '_octaneStateGetter') continue;
+			walk(node[key]);
+		}
+		ancestors.pop();
+	}
+	walk(root);
+}
+
 function rewriteHookCalls(node, ctx, componentName) {
+	markStateGetterUsage(node);
 	return mapAst(node, (n) => {
 		// A plain JS loop must not contain slot-keyed hook calls — reject before
 		// slotting. (A template `@for` is also a ForOfStatement; its JSX body tells
@@ -4183,6 +4284,7 @@ function rewriteHookCalls(node, ctx, componentName) {
 			const isCustom = /^use[A-Z]/.test(name) && name !== 'useContext';
 			const isServerUse = name === 'use' && ctx.mode === 'server';
 			if (isBuiltin || isCustom || isServerUse) {
+				const getterHelper = n._octaneStateGetter ? STATE_GETTER_HELPERS[name] : null;
 				// A builtin hook call site is USER code (the user's own identifier), so
 				// its import stays bare — EXCEPT compiler-inserted calls (auto-callback's
 				// `useCallback`), whose callee is renamed to the `_$` alias below so a
@@ -4190,6 +4292,7 @@ function rewriteHookCalls(node, ctx, componentName) {
 				if (isBuiltin) {
 					if (n.callee._octaneGenerated) ctx.runtimeNeeded.add(name);
 					else ctx.userRuntimeNames.add(name);
+					if (getterHelper !== null) ctx.runtimeNeeded.add(getterHelper);
 				}
 				if (isServerUse) ctx.userRuntimeNames.add('use');
 				const debug = isServerUse
@@ -4226,9 +4329,12 @@ function rewriteHookCalls(node, ctx, componentName) {
 				}
 				return {
 					...n,
-					callee: n.callee._octaneGenerated
-						? { type: 'Identifier', name: rtAlias(name) }
-						: n.callee,
+					callee:
+						getterHelper !== null
+							? { type: 'Identifier', name: rtAlias(getterHelper) }
+							: n.callee._octaneGenerated
+								? { type: 'Identifier', name: rtAlias(name) }
+								: n.callee,
 					arguments: [...args, { type: 'Identifier', name: symVar }],
 				};
 			}
@@ -6315,7 +6421,7 @@ function planJsx(jsxNodesRaw, ctx, componentName, inlinedSubs, parentNs = 'html'
 				const chv = `_b.${bag.letter(`_chv$${cc.id}`)}`;
 				pushAfter(
 					cc.id,
-					`  { const _v = (${cc.valueExpr}); if (${chp} !== _v) { ${chp} = _v; const _t = ${chv}; if (_t != null && typeof _v !== 'object' && typeof _v !== 'function') _$setText(_t, _v); else ${chv} = _$childTextHole(__s, ${slotIndex}, ${hostExpr}, _v, _t); } }`,
+					`  { const _v = (${cc.valueExpr}); const _o = _v !== null && (typeof _v === 'object' || typeof _v === 'function'); if (_o || ${chp} !== _v) { ${chp} = _v; const _t = ${chv}; if (_t != null && !_o && _v !== null) _$setText(_t, _v); else ${chv} = _$childTextHole(__s, ${slotIndex}, ${hostExpr}, _v, _t); } }`,
 				);
 				continue;
 			}
@@ -6338,7 +6444,11 @@ function planJsx(jsxNodesRaw, ctx, componentName, inlinedSubs, parentNs = 'html'
 			// unchanged-skippable primitive already backed by a text node, do a direct
 			// `setText` — exactly like a `.tsrx` `{… as string}` text binding. Objects /
 			// functions (component / element / array), the first render, and mode
-			// switches go through `textHole` → the full `childSlot`.
+			// switches go through `textHole` → the full `childSlot` — INCLUDING when
+			// the value is identity-UNCHANGED: only childSlot's bail path refreshes
+			// changed-context consumers below (a stable `{children}` passthrough under
+			// a re-rendering Provider), so an inline identity skip would strand them.
+			// Only unchanged primitives/null (no consumers possible) skip the call.
 			ctx.runtimeNeeded.add('setText');
 			ctx.runtimeNeeded.add('textHole');
 			// When the slot has its OWN `<!>` placeholder, tell textHole/childSlot to
@@ -6348,7 +6458,7 @@ function planJsx(jsxNodesRaw, ctx, componentName, inlinedSubs, parentNs = 'html'
 			const chv = `_b.${bag.letter(`_chv$${cc.id}`)}`;
 			pushAfter(
 				cc.id,
-				`  { const _v = (${cc.valueExpr}); if (${chp} !== _v) { ${chp} = _v; const _t = ${chv}; if (_t != null && typeof _v !== 'object' && typeof _v !== 'function') _$setText(_t, _v); else ${chv} = _$textHole(__s, ${slotIndex}, ${hostExpr}, _v, ${anchorExpr}${ownEndArg}); } }`,
+				`  { const _v = (${cc.valueExpr}); const _o = _v !== null && (typeof _v === 'object' || typeof _v === 'function'); if (_o || ${chp} !== _v) { ${chp} = _v; const _t = ${chv}; if (_t != null && !_o && _v !== null) _$setText(_t, _v); else ${chv} = _$textHole(__s, ${slotIndex}, ${hostExpr}, _v, ${anchorExpr}${ownEndArg}); } }`,
 			);
 			continue;
 		}