@octanejs/tanstack-start 0.1.1 → 0.1.5

package/src/client-only-server-strip.js

@@ -0,0 +1,461 @@
+import MagicString from 'magic-string';
+import { compileToVolarMappings } from 'octane/compiler/volar';
+import { START_ENVIRONMENT_NAMES } from '#tanstack-start/plugin-core/vite';
+
+/**
+ * Remove the children of the Router ClientOnly binding before Octane compiles
+ * server TSRX. This keeps client-only imports out of the server module graph,
+ * while preserving fallback content and identically-named local components.
+ */
+export function octaneClientOnlyServerStrip() {
+	return {
+		name: 'octanejs-tanstack-start:client-only-server-strip',
+		enforce: 'pre',
+		applyToEnvironment(environment) {
+			return environment.name === START_ENVIRONMENT_NAMES.server;
+		},
+		transform: {
+			filter: {
+				id: { include: [/\.tsrx($|\?)/] },
+				code: { include: ['ClientOnly'] },
+			},
+			handler(code, id) {
+				if (!code.includes('ClientOnly')) return undefined;
+
+				const filename = id.split('?', 1)[0];
+				const { sourceAst } = compileToVolarMappings(code, filename);
+				const childReplacements = stripClientOnlyChildren(sourceAst);
+				if (childReplacements.length === 0) return undefined;
+
+				const prunedImportSpecifiers = findImportsUsedOnlyInRanges(sourceAst, childReplacements);
+				const replacements = [
+					...rewritePrunedImports(code, sourceAst, prunedImportSpecifiers),
+					...childReplacements,
+				];
+				const output = new MagicString(code);
+				for (const replacement of replacements.sort((a, b) => b.start - a.start)) {
+					output.overwrite(replacement.start, replacement.end, replacement.content);
+				}
+
+				return {
+					code: output.toString(),
+					map: output.generateMap({
+						source: filename,
+						includeContent: true,
+						hires: true,
+					}),
+				};
+			},
+		},
+	};
+}
+
+function rewritePrunedImports(code, program, prunedImportSpecifiers) {
+	const replacements = [];
+
+	for (const statement of asNodes(program.body)) {
+		if (
+			statement.type !== 'ImportDeclaration' ||
+			!hasRange(statement) ||
+			!hasRange(statement.source)
+		) {
+			continue;
+		}
+
+		const prunedSpecifiers = prunedImportSpecifiers.get(statement);
+		if (!prunedSpecifiers?.size) continue;
+
+		const remainingSpecifiers = (statement.specifiers ?? []).filter(
+			(specifier) => !prunedSpecifiers.has(specifier),
+		);
+		replacements.push({
+			start: statement.start,
+			end: statement.end,
+			content: printRemainingImport(code, statement, remainingSpecifiers),
+		});
+	}
+
+	return replacements;
+}
+
+function findImportsUsedOnlyInRanges(program, removedRanges) {
+	const bindings = new Map();
+	for (const statement of asNodes(program.body)) {
+		if (statement.type !== 'ImportDeclaration' || statement.importKind === 'type') {
+			continue;
+		}
+		for (const specifier of statement.specifiers ?? []) {
+			const localName = specifier.local?.name;
+			if (specifier.importKind === 'type' || !localName) continue;
+			bindings.set(localName, {
+				declaration: statement,
+				specifier,
+				removed: false,
+				live: false,
+			});
+		}
+	}
+
+	if (bindings.size === 0 || removedRanges.length === 0) return new Map();
+
+	visitImportedBindingReferences(program, bindings, removedRanges);
+
+	const result = new Map();
+	for (const usage of bindings.values()) {
+		// Keep imports that were already unused: importing may intentionally run
+		// module initialization. Only remove bindings whose uses were stripped.
+		if (!usage.removed || usage.live) continue;
+		const specifiers = result.get(usage.declaration) ?? new Set();
+		specifiers.add(usage.specifier);
+		result.set(usage.declaration, specifiers);
+	}
+	return result;
+}
+
+function visitImportedBindingReferences(program, bindings, removedRanges) {
+	const visit = (value, shadowed, parent, parentKey, bindingPattern = false) => {
+		if (!value || typeof value !== 'object') return;
+		if (Array.isArray(value)) {
+			for (const item of value) {
+				visit(item, shadowed, parent, parentKey, bindingPattern);
+			}
+			return;
+		}
+
+		const node = value;
+		if (node.type === 'ImportDeclaration') return;
+
+		const scopedNames = scopeBindings(node);
+		const nextShadowed = scopedNames.size ? new Set([...shadowed, ...scopedNames]) : shadowed;
+
+		if (
+			!bindingPattern &&
+			isBindingReference(node, parent, parentKey) &&
+			node.name &&
+			!nextShadowed.has(node.name)
+		) {
+			const usage = bindings.get(node.name);
+			if (usage && hasRange(node)) {
+				if (isInsideRange(node, removedRanges)) usage.removed = true;
+				else usage.live = true;
+			}
+		}
+
+		for (const [key, child] of Object.entries(node)) {
+			if (key === 'metadata' || key === 'loc' || key === 'parent') continue;
+			visit(child, nextShadowed, node, key, isBindingPatternChild(node, key, bindingPattern));
+		}
+	};
+
+	visit(program, new Set());
+}
+
+function isBindingReference(node, parent, parentKey) {
+	if (node.type === 'Identifier') {
+		if (!parent) return true;
+		if (
+			(parent.type === 'MemberExpression' || parent.type === 'OptionalMemberExpression') &&
+			parentKey === 'property' &&
+			!parent.computed
+		) {
+			return false;
+		}
+		if (
+			(parent.type === 'Property' ||
+				parent.type === 'PropertyDefinition' ||
+				parent.type === 'MethodDefinition') &&
+			parentKey === 'key' &&
+			!parent.computed
+		) {
+			return Boolean(parent.shorthand);
+		}
+		if (parent.type === 'ExportSpecifier') return parentKey === 'local';
+		if (
+			(parent.type === 'LabeledStatement' ||
+				parent.type === 'BreakStatement' ||
+				parent.type === 'ContinueStatement') &&
+			parentKey === 'label'
+		) {
+			return false;
+		}
+		return true;
+	}
+
+	if (node.type !== 'JSXIdentifier' || !node.name || !parent) return false;
+	if (
+		(parent.type === 'JSXOpeningElement' || parent.type === 'JSXClosingElement') &&
+		parentKey === 'name'
+	) {
+		return true;
+	}
+	return parent.type === 'JSXMemberExpression' && parentKey === 'object';
+}
+
+function isBindingPatternChild(parent, key, parentIsBindingPattern) {
+	if (parentIsBindingPattern) {
+		if (parent.type === 'AssignmentPattern') return key === 'left';
+		if (parent.type === 'Property') {
+			return key === 'value' || (key === 'key' && !parent.computed);
+		}
+		return true;
+	}
+
+	if (parent.type === 'VariableDeclarator') return key === 'id';
+	if (isFunction(parent)) return key === 'id' || key === 'params';
+	if (parent.type === 'ClassDeclaration' || parent.type === 'ClassExpression') {
+		return key === 'id';
+	}
+	if (parent.type === 'CatchClause') return key === 'param';
+	if (parent.type === 'ImportSpecifier') return true;
+	return false;
+}
+
+function isInsideRange(node, ranges) {
+	return ranges.some((range) => range.start <= node.start && range.end >= node.end);
+}
+
+function printRemainingImport(code, statement, specifiers) {
+	const sourceNode = statement.source;
+	if (specifiers.length === 0 || !hasRange(sourceNode)) return '';
+
+	const defaultSpecifier = specifiers.find(
+		(specifier) => specifier.type === 'ImportDefaultSpecifier',
+	);
+	const namespaceSpecifier = specifiers.find(
+		(specifier) => specifier.type === 'ImportNamespaceSpecifier',
+	);
+	const namedSpecifiers = specifiers.filter((specifier) => specifier.type === 'ImportSpecifier');
+	const clauses = [];
+
+	if (defaultSpecifier && hasRange(defaultSpecifier)) {
+		clauses.push(code.slice(defaultSpecifier.start, defaultSpecifier.end));
+	}
+	if (namespaceSpecifier && hasRange(namespaceSpecifier)) {
+		clauses.push(code.slice(namespaceSpecifier.start, namespaceSpecifier.end));
+	}
+	if (namedSpecifiers.length > 0) {
+		clauses.push(
+			`{ ${namedSpecifiers
+				.filter(hasRange)
+				.map((specifier) => code.slice(specifier.start, specifier.end))
+				.join(', ')} }`,
+		);
+	}
+
+	const source = code.slice(sourceNode.start, sourceNode.end);
+	const suffix = hasRange(statement) ? code.slice(sourceNode.end, statement.end) : '';
+	return `import ${clauses.join(', ')} from ${source}${suffix}`;
+}
+
+function stripClientOnlyChildren(program) {
+	const importedNames = new Set();
+	for (const statement of asNodes(program.body)) {
+		if (statement.type !== 'ImportDeclaration' || statement.importKind === 'type') {
+			continue;
+		}
+
+		for (const specifier of statement.specifiers ?? []) {
+			if (
+				specifier.type === 'ImportSpecifier' &&
+				specifier.importKind !== 'type' &&
+				specifier.imported?.name === 'ClientOnly' &&
+				specifier.local?.name
+			) {
+				importedNames.add(specifier.local.name);
+			}
+		}
+	}
+
+	if (importedNames.size === 0) return [];
+
+	const replacements = [];
+	const visited = new WeakSet();
+	const visit = (value, shadowed) => {
+		if (!value || typeof value !== 'object' || visited.has(value)) return;
+		visited.add(value);
+
+		if (Array.isArray(value)) {
+			for (const item of value) visit(item, shadowed);
+			return;
+		}
+
+		const node = value;
+		const scopedNames = scopeBindings(node);
+		const nextShadowed = scopedNames.size ? new Set([...shadowed, ...scopedNames]) : shadowed;
+		const elementName = node.openingElement?.name?.name;
+
+		if (
+			node.type === 'JSXElement' &&
+			elementName &&
+			importedNames.has(elementName) &&
+			!nextShadowed.has(elementName) &&
+			node.children?.length
+		) {
+			const first = node.children[0];
+			const last = node.children[node.children.length - 1];
+			if (first && last && hasRange(first) && hasRange(last) && last.end > first.start) {
+				replacements.push({
+					start: first.start,
+					end: last.end,
+					content: '{null}',
+				});
+			}
+		}
+
+		for (const [key, child] of Object.entries(node)) {
+			if (key !== 'metadata' && key !== 'loc' && key !== 'parent') {
+				visit(child, nextShadowed);
+			}
+		}
+	};
+
+	visit(program, new Set());
+
+	// Replacing an outer ClientOnly child range also removes nested boundaries.
+	return replacements.filter(
+		(candidate, index) =>
+			!replacements.some(
+				(other, otherIndex) =>
+					otherIndex !== index && other.start <= candidate.start && other.end >= candidate.end,
+			),
+	);
+}
+
+function scopeBindings(node) {
+	const names = new Set();
+
+	if (isFunction(node)) {
+		for (const param of node.params ?? []) collectBindingNames(param, names);
+		collectBindingNames(node.id, names);
+		for (const statement of directStatements(node.body)) {
+			collectStatementBindings(statement, names);
+		}
+		collectFunctionVarBindings(node.body, names);
+	} else if (node.type === 'BlockStatement' || node.type === 'JSXCodeBlock') {
+		for (const statement of directStatements(node)) {
+			collectStatementBindings(statement, names);
+		}
+	} else if (node.type === 'CatchClause') {
+		collectBindingNames(node.param, names);
+	} else if (
+		node.type === 'ForStatement' ||
+		node.type === 'ForInStatement' ||
+		node.type === 'ForOfStatement'
+	) {
+		const declaration = node.init ?? node.left;
+		if (declaration?.type === 'VariableDeclaration' && declaration.kind !== 'var') {
+			for (const item of declaration.declarations ?? []) {
+				collectBindingNames(item.id, names);
+			}
+		}
+	} else if (node.type === 'SwitchStatement') {
+		for (const switchCase of asNodes(node.cases)) {
+			for (const statement of asNodes(switchCase.consequent)) {
+				collectStatementBindings(statement, names);
+			}
+		}
+	} else if (node.type === 'StaticBlock') {
+		for (const statement of directStatements(node)) {
+			collectStatementBindings(statement, names);
+		}
+	} else if (node.type === 'ClassDeclaration' || node.type === 'ClassExpression') {
+		collectBindingNames(node.id, names);
+	}
+
+	return names;
+}
+
+function directStatements(node) {
+	if (Array.isArray(node)) return node;
+	if (!node || !Array.isArray(node.body)) return [];
+	return asNodes(node.body);
+}
+
+function collectStatementBindings(statement, output) {
+	const declaration =
+		statement.type === 'ExportNamedDeclaration' || statement.type === 'ExportDefaultDeclaration'
+			? statement.declaration
+			: statement;
+
+	if (declaration?.type === 'VariableDeclaration') {
+		for (const item of declaration.declarations ?? []) {
+			collectBindingNames(item.id, output);
+		}
+	} else if (
+		declaration?.type === 'FunctionDeclaration' ||
+		declaration?.type === 'ClassDeclaration'
+	) {
+		collectBindingNames(declaration.id, output);
+	}
+}
+
+function collectFunctionVarBindings(value, output) {
+	const visited = new WeakSet();
+	const visit = (child, root = false) => {
+		if (!child || typeof child !== 'object' || visited.has(child)) return;
+		visited.add(child);
+
+		if (Array.isArray(child)) {
+			for (const item of child) visit(item);
+			return;
+		}
+
+		const node = child;
+		if (!root && isFunction(node)) return;
+		if (node.type === 'VariableDeclaration' && node.kind === 'var') {
+			for (const item of node.declarations ?? []) {
+				collectBindingNames(item.id, output);
+			}
+		}
+		for (const [key, nested] of Object.entries(node)) {
+			if (key !== 'metadata' && key !== 'loc' && key !== 'parent') {
+				visit(nested);
+			}
+		}
+	};
+
+	visit(value, true);
+}
+
+function collectBindingNames(pattern, output) {
+	if (!pattern) return;
+	if (pattern.type === 'Identifier' && pattern.name) {
+		output.add(pattern.name);
+		return;
+	}
+	if (pattern.type === 'RestElement') {
+		collectBindingNames(pattern.argument, output);
+		return;
+	}
+	if (pattern.type === 'AssignmentPattern') {
+		collectBindingNames(pattern.left, output);
+		return;
+	}
+	if (pattern.type === 'ArrayPattern') {
+		for (const element of asNodes(pattern.elements)) {
+			collectBindingNames(element, output);
+		}
+		return;
+	}
+	if (pattern.type === 'ObjectPattern') {
+		for (const property of asNodes(pattern.properties)) {
+			collectBindingNames(property.argument ?? property.value, output);
+		}
+	}
+}
+
+function isFunction(node) {
+	return (
+		node.type === 'FunctionDeclaration' ||
+		node.type === 'FunctionExpression' ||
+		node.type === 'ArrowFunctionExpression'
+	);
+}
+
+function hasRange(node) {
+	return typeof node?.start === 'number' && typeof node.end === 'number';
+}
+
+function asNodes(value) {
+	return Array.isArray(value) ? value : [];
+}

package/src/hydration/generic.d.ts

@@ -0,0 +1,18 @@
+import type {
+	HydrationCondition,
+	HydrationInteractionEvents,
+	HydrationPrefetchStrategy,
+} from '@tanstack/start-client-core/hydration';
+import type { OctaneHydrationStrategy } from '../Hydrate.tsrx';
+
+export declare function media(
+	query: string,
+): OctaneHydrationStrategy<'media', true> & HydrationPrefetchStrategy<'media'>;
+
+export declare function condition(
+	condition: HydrationCondition,
+): OctaneHydrationStrategy<'condition', false>;
+
+export declare function interaction(options?: {
+	events?: HydrationInteractionEvents;
+}): OctaneHydrationStrategy<'interaction', true> & HydrationPrefetchStrategy<'interaction'>;

package/src/hydration/generic.js

@@ -0,0 +1,26 @@
+// media / condition / interaction hydration strategies — port of
+// @tanstack/react-start-client's hydration/generic.ts. The gating logic lives
+// in @tanstack/start-client-core; these factories just attach octane's
+// GenericHydrate renderer.
+import {
+	condition as coreCondition,
+	interaction as coreInteraction,
+	media as coreMedia,
+	withHydrationRenderer,
+} from '@tanstack/start-client-core/hydration';
+import { GenericHydrate } from '../GenericHydrate.tsrx';
+
+/* @__NO_SIDE_EFFECTS__ */
+export function media(query) {
+	return /* @__PURE__ */ withHydrationRenderer(coreMedia(query), GenericHydrate);
+}
+
+/* @__NO_SIDE_EFFECTS__ */
+export function condition(condition) {
+	return /* @__PURE__ */ withHydrationRenderer(coreCondition(condition), GenericHydrate);
+}
+
+/* @__NO_SIDE_EFFECTS__ */
+export function interaction(options) {
+	return /* @__PURE__ */ withHydrationRenderer(coreInteraction(options), GenericHydrate);
+}

package/src/hydration/idle.d.ts

@@ -0,0 +1,9 @@
+import type {
+	HydrationPrefetchStrategy,
+	IdleHydrationOptions,
+} from '@tanstack/start-client-core/hydration';
+import type { OctaneHydrationStrategy } from '../Hydrate.tsrx';
+
+export declare function idle(
+	options?: IdleHydrationOptions,
+): OctaneHydrationStrategy<'idle', true> & HydrationPrefetchStrategy<'idle'>;

package/src/hydration/idle.js

@@ -0,0 +1,10 @@
+// idle hydration strategy — port of @tanstack/react-start-client's
+// hydration/idle.ts. Delegates the requestIdleCallback gating to
+// @tanstack/start-client-core and attaches octane's GenericHydrate renderer.
+import { idle as coreIdle, withHydrationRenderer } from '@tanstack/start-client-core/hydration';
+import { GenericHydrate } from '../GenericHydrate.tsrx';
+
+/* @__NO_SIDE_EFFECTS__ */
+export function idle(options = {}) {
+	return /* @__PURE__ */ withHydrationRenderer(coreIdle(options), GenericHydrate);
+}

package/src/hydration/load.tsrx

@@ -0,0 +1,38 @@
+// load hydration strategy — port of @tanstack/react-start-client's
+// hydration/load.tsx. `load` hydrates immediately, so its renderer skips the
+// marker/gate machinery entirely: a bare Suspense wrapper plus an onHydrated
+// notification effect.
+import { Suspense, useEffect, useRef } from 'octane';
+import type { OctaneNode } from 'octane';
+import { load as coreLoad, withHydrationRenderer } from '@tanstack/start-client-core/hydration';
+import type { HydrateProps } from '../Hydrate.tsrx';
+
+function HydratedBoundary(props: { onHydrated?: () => void; children?: OctaneNode }) {
+	const { onHydrated } = props;
+	const didHydrateRef = useRef(false);
+
+	useEffect(() => {
+		if (didHydrateRef.current) return;
+		didHydrateRef.current = true;
+		onHydrated?.();
+	}, [onHydrated]);
+
+	return props.children;
+}
+
+// OCTANE ADAPTATION: octane's `Hydrate` renders `_h` as a child component
+// (upstream bare-calls it inline); LoadHydrate is that component.
+export function LoadHydrate(props: HydrateProps) @{
+	<div>
+		<Suspense fallback={props.fallback ?? null}>
+			<HydratedBoundary onHydrated={props.onHydrated}>{props.children}</HydratedBoundary>
+		</Suspense>
+	</div>
+}
+
+const loadStrategy = /* @__PURE__ */ withHydrationRenderer(coreLoad(), LoadHydrate);
+
+/* @__NO_SIDE_EFFECTS__ */
+export function load() {
+	return loadStrategy;
+}

package/src/hydration/load.tsrx.d.ts

@@ -0,0 +1,8 @@
+import type { OctaneNode } from 'octane';
+import type { HydrationPrefetchStrategy } from '@tanstack/start-client-core/hydration';
+import type { HydrateProps, OctaneHydrationStrategy } from '../Hydrate.tsrx';
+
+export declare function LoadHydrate(props: HydrateProps): OctaneNode;
+
+export declare function load(): OctaneHydrationStrategy<'load', true> &
+	HydrationPrefetchStrategy<'load'>;

package/src/hydration/never.tsrx

@@ -0,0 +1,71 @@
+// never hydration strategy — port of @tanstack/react-start-client's
+// hydration/never.tsx. Server HTML is preserved verbatim and the subtree is
+// never hydrated: the gate promise never resolves, so the Suspense boundary
+// keeps showing the saved server HTML (re-injected via dangerouslySetInnerHTML)
+// forever. `reactUse` feature-detection is dropped — octane's `use` always
+// exists.
+import { Suspense, use, useCallback, useId, useRef } from 'octane';
+import type { OctaneNode } from 'octane';
+import { useHydrated } from '@octanejs/tanstack-router';
+import { isServer } from '@tanstack/router-core/isServer';
+import { never as coreNever, withHydrationRenderer } from '@tanstack/start-client-core/hydration';
+import {
+	hydrateIdAttribute,
+	hydrateWhenAttribute,
+} from '@tanstack/start-client-core/hydration/constants';
+import { getFallbackHtml, saveFallbackHtml } from '@tanstack/start-client-core/hydration/runtime';
+import type { HydrateProps, InternalHydrateProps } from '../Hydrate.tsrx';
+
+const neverType = 'never';
+const neverPromise = new Promise<void>(() => {});
+
+function NeverGate(props: { children?: OctaneNode }) {
+	if (isServer ?? typeof window === 'undefined') {
+		return props.children;
+	}
+
+	use(neverPromise);
+
+	return props.children;
+}
+
+// OCTANE ADAPTATION: octane's `Hydrate` renders `_h` as a child component
+// (upstream bare-calls it inline); NeverHydrate is that component.
+export function NeverHydrate(props: HydrateProps) @{
+	const internalProps = props as InternalHydrateProps;
+	const hydrated = useHydrated();
+	const octaneId = useId();
+	const id = internalProps.h ? `${internalProps.h}${octaneId}` : octaneId;
+	const shouldPreserveServerHTMLRef = useRef<boolean | undefined>(undefined);
+	shouldPreserveServerHTMLRef.current ??= (isServer ?? typeof window === 'undefined') || !hydrated;
+	const markerRef = useCallback((element: HTMLDivElement | null) => {
+		if (!element) return;
+		if (!shouldPreserveServerHTMLRef.current) {
+			element.replaceChildren();
+		} else {
+			saveFallbackHtml(id, element);
+		}
+	}, [id]);
+	const savedHtml = getFallbackHtml(id);
+
+	<div
+		ref={markerRef}
+		{...{
+			[hydrateIdAttribute]: id,
+			[hydrateWhenAttribute]: neverType,
+		}}
+	>
+		<Suspense
+			fallback={savedHtml
+				? <div style={{ display: 'contents' }} dangerouslySetInnerHTML={{ __html: savedHtml }} />
+				: props.fallback ?? null}
+		>
+			<NeverGate>{props.children}</NeverGate>
+		</Suspense>
+	</div>
+}
+
+/* @__NO_SIDE_EFFECTS__ */
+export function never() {
+	return /* @__PURE__ */ withHydrationRenderer(coreNever(), NeverHydrate);
+}

package/src/hydration/never.tsrx.d.ts

@@ -0,0 +1,6 @@
+import type { OctaneNode } from 'octane';
+import type { HydrateProps, OctaneHydrationStrategy } from '../Hydrate.tsrx';
+
+export declare function NeverHydrate(props: HydrateProps): OctaneNode;
+
+export declare function never(): OctaneHydrationStrategy<'never', false>;