@octanejs/tanstack-router 0.1.9 → 0.1.11

package/src/routeHookTypes.ts

@@ -0,0 +1,228 @@
+import type { StructuralSharingOption, ValidateSelected } from './structuralSharing';
+import type {
+	AnyRouter,
+	FromPathOption,
+	MakeRouteMatch,
+	MakeRouteMatchUnion,
+	RegisteredRouter,
+	ResolveUseLoaderData,
+	ResolveUseLoaderDeps,
+	ResolveUseParams,
+	ResolveUseSearch,
+	RouterState,
+	StrictOrFrom,
+	ThrowConstraint,
+	ThrowOrOptional,
+	UseLoaderDataResult,
+	UseLoaderDepsResult,
+	UseNavigateResult,
+	UseParamsResult,
+	UseRouteContextBaseOptions,
+	UseRouteContextOptions,
+	UseRouteContextResult,
+	UseSearchResult,
+} from '@tanstack/router-core';
+
+export interface UseMatchBaseOptions<
+	TRouter extends AnyRouter,
+	TFrom,
+	TStrict extends boolean,
+	TThrow extends boolean,
+	TSelected,
+	TStructuralSharing extends boolean,
+> {
+	select?: (
+		match: MakeRouteMatch<TRouter['routeTree'], TFrom, TStrict>,
+	) => ValidateSelected<TRouter, TSelected, TStructuralSharing>;
+	shouldThrow?: TThrow;
+}
+
+export type UseMatchRoute<out TFrom> = <
+	TRouter extends AnyRouter = RegisteredRouter,
+	TSelected = unknown,
+	TStructuralSharing extends boolean = boolean,
+>(
+	opts?: UseMatchBaseOptions<TRouter, TFrom, true, true, TSelected, TStructuralSharing> &
+		StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
+) => UseMatchResult<TRouter, TFrom, true, TSelected>;
+
+export type UseMatchOptions<
+	TRouter extends AnyRouter,
+	TFrom extends string | undefined,
+	TStrict extends boolean,
+	TThrow extends boolean,
+	TSelected,
+	TStructuralSharing extends boolean,
+> = StrictOrFrom<TRouter, TFrom, TStrict> &
+	UseMatchBaseOptions<TRouter, TFrom, TStrict, TThrow, TSelected, TStructuralSharing> &
+	StructuralSharingOption<TRouter, TSelected, TStructuralSharing>;
+
+export type UseMatchResult<
+	TRouter extends AnyRouter,
+	TFrom,
+	TStrict extends boolean,
+	TSelected,
+> = unknown extends TSelected
+	? TStrict extends true
+		? MakeRouteMatch<TRouter['routeTree'], TFrom, TStrict>
+		: MakeRouteMatchUnion<TRouter>
+	: TSelected;
+
+export interface UseParamsBaseOptions<
+	TRouter extends AnyRouter,
+	TFrom,
+	TStrict extends boolean,
+	TThrow extends boolean,
+	TSelected,
+	TStructuralSharing,
+> {
+	select?: (
+		params: ResolveUseParams<TRouter, TFrom, TStrict>,
+	) => ValidateSelected<TRouter, TSelected, TStructuralSharing>;
+	shouldThrow?: TThrow;
+}
+
+export type UseParamsRoute<out TFrom> = <
+	TRouter extends AnyRouter = RegisteredRouter,
+	TSelected = unknown,
+	TStructuralSharing extends boolean = boolean,
+>(
+	opts?: UseParamsBaseOptions<TRouter, TFrom, true, true, TSelected, TStructuralSharing> &
+		StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
+) => UseParamsResult<TRouter, TFrom, true, TSelected>;
+
+export type UseParamsOptions<
+	TRouter extends AnyRouter,
+	TFrom extends string | undefined,
+	TStrict extends boolean,
+	TThrow extends boolean,
+	TSelected,
+	TStructuralSharing,
+> = StrictOrFrom<TRouter, TFrom, TStrict> &
+	UseParamsBaseOptions<TRouter, TFrom, TStrict, TThrow, TSelected, TStructuralSharing> &
+	StructuralSharingOption<TRouter, TSelected, TStructuralSharing>;
+
+export interface UseSearchBaseOptions<
+	TRouter extends AnyRouter,
+	TFrom,
+	TStrict extends boolean,
+	TThrow extends boolean,
+	TSelected,
+	TStructuralSharing,
+> {
+	select?: (
+		search: ResolveUseSearch<TRouter, TFrom, TStrict>,
+	) => ValidateSelected<TRouter, TSelected, TStructuralSharing>;
+	shouldThrow?: TThrow;
+}
+
+export type UseSearchRoute<out TFrom> = <
+	TRouter extends AnyRouter = RegisteredRouter,
+	TSelected = unknown,
+	TStructuralSharing extends boolean = boolean,
+>(
+	opts?: UseSearchBaseOptions<TRouter, TFrom, true, true, TSelected, TStructuralSharing> &
+		StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
+) => UseSearchResult<TRouter, TFrom, true, TSelected>;
+
+export type UseSearchOptions<
+	TRouter extends AnyRouter,
+	TFrom,
+	TStrict extends boolean,
+	TThrow extends boolean,
+	TSelected,
+	TStructuralSharing,
+> = StrictOrFrom<TRouter, TFrom, TStrict> &
+	UseSearchBaseOptions<TRouter, TFrom, TStrict, TThrow, TSelected, TStructuralSharing> &
+	StructuralSharingOption<TRouter, TSelected, TStructuralSharing>;
+
+export interface UseLoaderDataBaseOptions<
+	TRouter extends AnyRouter,
+	TFrom,
+	TStrict extends boolean,
+	TSelected,
+	TStructuralSharing,
+> {
+	select?: (
+		data: ResolveUseLoaderData<TRouter, TFrom, TStrict>,
+	) => ValidateSelected<TRouter, TSelected, TStructuralSharing>;
+}
+
+export type UseLoaderDataRoute<out TFrom> = <
+	TRouter extends AnyRouter = RegisteredRouter,
+	TSelected = unknown,
+	TStructuralSharing extends boolean = boolean,
+>(
+	opts?: UseLoaderDataBaseOptions<TRouter, TFrom, true, TSelected, TStructuralSharing> &
+		StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
+) => UseLoaderDataResult<TRouter, TFrom, true, TSelected>;
+
+export type UseLoaderDataOptions<
+	TRouter extends AnyRouter,
+	TFrom extends string | undefined,
+	TStrict extends boolean,
+	TSelected,
+	TStructuralSharing,
+> = StrictOrFrom<TRouter, TFrom, TStrict> &
+	UseLoaderDataBaseOptions<TRouter, TFrom, TStrict, TSelected, TStructuralSharing> &
+	StructuralSharingOption<TRouter, TSelected, TStructuralSharing>;
+
+export interface UseLoaderDepsBaseOptions<
+	TRouter extends AnyRouter,
+	TFrom,
+	TSelected,
+	TStructuralSharing,
+> {
+	select?: (
+		deps: ResolveUseLoaderDeps<TRouter, TFrom>,
+	) => ValidateSelected<TRouter, TSelected, TStructuralSharing>;
+}
+
+export type UseLoaderDepsRoute<out TFrom> = <
+	TRouter extends AnyRouter = RegisteredRouter,
+	TSelected = unknown,
+	TStructuralSharing extends boolean = boolean,
+>(
+	opts?: UseLoaderDepsBaseOptions<TRouter, TFrom, TSelected, TStructuralSharing> &
+		StructuralSharingOption<TRouter, TSelected, TStructuralSharing>,
+) => UseLoaderDepsResult<TRouter, TFrom, TSelected>;
+
+export type UseLoaderDepsOptions<
+	TRouter extends AnyRouter,
+	TFrom extends string | undefined,
+	TSelected,
+	TStructuralSharing,
+> = StrictOrFrom<TRouter, TFrom> &
+	UseLoaderDepsBaseOptions<TRouter, TFrom, TSelected, TStructuralSharing> &
+	StructuralSharingOption<TRouter, TSelected, TStructuralSharing>;
+
+export type UseRouteContextRoute<out TFrom> = <
+	TRouter extends AnyRouter = RegisteredRouter,
+	TSelected = unknown,
+>(
+	opts?: UseRouteContextBaseOptions<TRouter, TFrom, true, TSelected>,
+) => UseRouteContextResult<TRouter, TFrom, true, TSelected>;
+
+export interface UseLocationBaseOptions<
+	TRouter extends AnyRouter,
+	TSelected,
+	TStructuralSharing extends boolean = boolean,
+> {
+	select?: (
+		location: RouterState<TRouter['routeTree']>['location'],
+	) => ValidateSelected<TRouter, TSelected, TStructuralSharing>;
+}
+
+export type UseLocationResult<TRouter extends AnyRouter, TSelected> = unknown extends TSelected
+	? RouterState<TRouter['routeTree']>['location']
+	: TSelected;
+
+export interface UseMatchesBaseOptions<TRouter extends AnyRouter, TSelected, TStructuralSharing> {
+	select?: (
+		matches: Array<MakeRouteMatchUnion<TRouter>>,
+	) => ValidateSelected<TRouter, TSelected, TStructuralSharing>;
+}
+
+export type UseMatchesResult<TRouter extends AnyRouter, TSelected> = unknown extends TSelected
+	? Array<MakeRouteMatchUnion<TRouter>>
+	: TSelected;

package/src/router.ts

@@ -13,6 +13,13 @@ import {
 } from '@tanstack/router-core';
 import { createAtom, batch } from '@tanstack/store';
 import { startTransition } from 'octane';
+import type { RouterHistory } from '@tanstack/history';
+import type {
+	AnyRoute,
+	CreateRouterFn,
+	RouterConstructorOptions,
+	TrailingSlashOption,
+} from '@tanstack/router-core';
 
 const isServerEnv = typeof document === 'undefined';
 
@@ -52,8 +59,28 @@ const octaneStoreFactory = (opts: { isServer?: boolean }) => {
 	};
 };
 
-export class Router extends (RouterCore as any) {
-	constructor(options: any) {
+export class Router<
+	in out TRouteTree extends AnyRoute,
+	in out TTrailingSlashOption extends TrailingSlashOption = 'never',
+	in out TDefaultStructuralSharingOption extends boolean = false,
+	in out TRouterHistory extends RouterHistory = RouterHistory,
+	in out TDehydrated extends Record<string, any> = Record<string, any>,
+> extends RouterCore<
+	TRouteTree,
+	TTrailingSlashOption,
+	TDefaultStructuralSharingOption,
+	TRouterHistory,
+	TDehydrated
+> {
+	constructor(
+		options: RouterConstructorOptions<
+			TRouteTree,
+			TTrailingSlashOption,
+			TDefaultStructuralSharingOption,
+			TRouterHistory,
+			TDehydrated
+		>,
+	) {
 		super(options, octaneStoreFactory);
 
 		// router-core starts the resolved-match commit through startViewTransition,
@@ -106,7 +133,7 @@ export class Router extends (RouterCore as any) {
 			activeLoadScopes.add(viewCommits);
 			let hasLoadError = false;
 			let loadError: unknown;
-			let result: unknown;
+			let result: void;
 			try {
 				result = await coreLoad(...args);
 			} catch (error) {
@@ -153,6 +180,4 @@ export class Router extends (RouterCore as any) {
 	}
 }
 
-export function createRouter(options: any): any {
-	return new Router(options);
-}
+export const createRouter: CreateRouterFn = (options) => new Router(options);

package/src/scriptContentUtils.ts

@@ -0,0 +1,64 @@
+import { deepEqual } from '@tanstack/router-core';
+import { isServer } from '@tanstack/router-core/isServer';
+import { useRouter } from './context';
+import { splitSlot, subSlot } from './internal';
+import { useStore } from './useStore';
+import type { AnyRouteMatch, AnyRouter, RouterManagedTag } from '@tanstack/router-core';
+
+function getScripts(router: AnyRouter, matches: Array<AnyRouteMatch>) {
+	const nonce = router.options.ssr?.nonce;
+	const scripts: Array<RouterManagedTag> = matches
+		.flatMap((match) => match.scripts ?? [])
+		.filter((script) => script !== undefined)
+		.map(({ children, ...attrs }) => ({
+			tag: 'script',
+			attrs: { ...attrs, nonce },
+			children,
+		}));
+
+	const manifest = router.ssr?.manifest;
+	if (manifest) {
+		for (const match of matches) {
+			for (const asset of manifest.routes[match.routeId]?.scripts ?? []) {
+				scripts.push({
+					tag: 'script',
+					attrs: { ...asset.attrs, nonce },
+					children: asset.children,
+				});
+			}
+		}
+	}
+
+	return scripts;
+}
+
+export function useScripts(...args: Array<unknown>): Array<RouterManagedTag> {
+	const [, slot] = splitSlot(args);
+	const router = useRouter();
+
+	if (isServer ?? router.isServer) {
+		const scripts = getScripts(router, router.stores.matches.get());
+		const buffered = router.serverSsr?.takeBufferedScripts();
+		if (!buffered || buffered.tag !== 'script') {
+			return scripts;
+		}
+		return [
+			{
+				tag: 'script',
+				attrs: buffered.attrs,
+				children:
+					typeof buffered.children === 'string'
+						? buffered.children.replace(/;document\.currentScript\.remove\(\)$/, '')
+						: buffered.children,
+			},
+			...scripts,
+		];
+	}
+
+	return useStore(
+		router.stores.matches,
+		(matches: Array<AnyRouteMatch>) => getScripts(router, matches),
+		deepEqual,
+		subSlot(slot, 'body:scripts'),
+	);
+}

package/src/scroll-restoration.tsrx

@@ -0,0 +1,16 @@
+import {
+	getScrollRestorationScriptForRouter,
+} from '@tanstack/router-core/scroll-restoration-script';
+import { useRouter } from './context.ts';
+import { ScriptOnce } from './ScriptOnce.tsrx';
+
+export function ScrollRestorationScript() @{
+	const router = useRouter();
+	const script = getScrollRestorationScriptForRouter(router);
+
+	@if (script) {
+		<ScriptOnce children={script} />
+	} @else {
+		<></>
+	}
+}

package/src/scroll-restoration.tsrx.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentBody } from 'octane';
+
+export declare const ScrollRestorationScript: ComponentBody<Record<never, never>>;

package/src/ssr/RouterClient.tsrx

@@ -0,0 +1,36 @@
+import { use } from 'octane';
+import { hydrate } from '@tanstack/router-core/ssr/client';
+import type { AnyRouter } from '@tanstack/router-core';
+import { RouterProvider } from '../RouterProvider.tsrx';
+import { toExternalHydrationThenable } from '../externalHydration.ts';
+
+const hydrationPromises = new WeakMap<AnyRouter, PromiseLike<void>>();
+const ready = {
+	status: 'fulfilled',
+	value: undefined,
+	then(onfulfilled?: (() => void) | null): Promise<void> {
+		return Promise.resolve(onfulfilled?.());
+	},
+};
+
+function getHydrationPromise(router: AnyRouter) {
+	let promise = hydrationPromises.get(router);
+	if (!promise) {
+		promise = router.stores.matchesId.get().length ? ready as PromiseLike<void> : hydrate(router);
+		hydrationPromises.set(router, promise);
+	}
+	return promise;
+}
+
+function RouterClientInner(props: { router: AnyRouter }) @{
+	use(toExternalHydrationThenable(getHydrationPromise(props.router)));
+	<RouterProvider router={props.router} />
+}
+
+export function RouterClient(props: { router: AnyRouter }) @{
+	@try {
+		<RouterClientInner router={props.router} />
+	} @pending {
+		<></>
+	}
+}

package/src/ssr/RouterClient.tsrx.d.ts

@@ -0,0 +1,4 @@
+import type { ComponentBody } from 'octane';
+import type { AnyRouter } from '@tanstack/router-core';
+
+export declare const RouterClient: ComponentBody<{ router: AnyRouter }>;

package/src/ssr/RouterServer.tsrx

@@ -0,0 +1,6 @@
+import { RouterProvider } from '../RouterProvider.tsrx';
+import type { AnyRouter } from '@tanstack/router-core';
+
+export function RouterServer(props: { router: AnyRouter }) @{
+	<RouterProvider router={props.router} />
+}

package/src/ssr/RouterServer.tsrx.d.ts

@@ -0,0 +1,4 @@
+import type { ComponentBody } from 'octane';
+import type { AnyRouter } from '@tanstack/router-core';
+
+export declare const RouterServer: ComponentBody<{ router: AnyRouter }>;

package/src/ssr/client.ts

@@ -0,0 +1,4 @@
+import '../frameworkTypes';
+
+export { RouterClient } from './RouterClient.tsrx';
+export * from '@tanstack/router-core/ssr/client';

package/src/ssr/defaultRenderHandler.ts

@@ -0,0 +1,11 @@
+import { defineHandlerCallback } from '@tanstack/router-core/ssr/server';
+import { RouterServer } from './RouterServer.tsrx';
+import { renderRouterToString } from './renderRouterToString';
+
+export const defaultRenderHandler = defineHandlerCallback(({ router, responseHeaders }) =>
+	renderRouterToString({
+		router,
+		responseHeaders,
+		App: RouterServer,
+	}),
+);

package/src/ssr/defaultStreamHandler.ts

@@ -0,0 +1,12 @@
+import { defineHandlerCallback } from '@tanstack/router-core/ssr/server';
+import { RouterServer } from './RouterServer.tsrx';
+import { renderRouterToStream } from './renderRouterToStream';
+
+export const defaultStreamHandler = defineHandlerCallback(({ request, router, responseHeaders }) =>
+	renderRouterToStream({
+		request,
+		router,
+		responseHeaders,
+		App: RouterServer,
+	}),
+);

package/src/ssr/renderRouterToStream.ts

@@ -0,0 +1,195 @@
+import { renderToReadableStream } from 'octane/server';
+import { prerender } from 'octane/static';
+import { isbot } from 'isbot';
+import { createSsrStreamResponse } from '@tanstack/router-core/ssr/server';
+import { finalizeBufferedHtml } from './renderRouterToString';
+import type { ComponentBody } from 'octane';
+import type { StreamInjectionSource } from 'octane/server';
+import type { AnyRouter } from '@tanstack/router-core';
+
+type RouterApp = ComponentBody<{ router: AnyRouter }>;
+type ServerComponent = Parameters<typeof renderToReadableStream>[0];
+
+// The router's data stream is merged through octane's native
+// `StreamOptions.injection` (octane >= 0.1.11) instead of router-core's
+// `transformStreamWithRouter` text transform. Octane emits tag-complete
+// chunks and owns the document tail, so the byte-level re-parse
+// (closing-tag scans, leftover buffers, the held-`</body>` tail that also
+// buffered every post-shell suspense segment until stream end) is
+// unnecessary — boundary segments stream out of order for document renders,
+// and the transform's 64 KiB tail cap on segment volume disappears.
+// Octane's document mode also emits `<!DOCTYPE html>` and folds the leading
+// renderer-owned styles into `<head>`, replacing the `prependDoctype` and
+// `relocateLeadingOctaneStylesToHead` transforms this file previously piped
+// the stream through.
+//
+// The serialization timeout is preserved: it arms when octane reports the
+// render finished (`renderComplete`) and fails the stream if serialization
+// never completes. The script barrier lifts when octane subscribes — octane
+// only subscribes after the shell (which carries the barrier anchor) is on
+// the wire, matching the transform's lift-after-marker-flush.
+// (`setRenderFinished` lifts it as a backstop regardless, exactly as
+// before.)
+
+const SERIALIZATION_TIMEOUT_MS = 60_000;
+
+export async function renderRouterToStream({
+	request,
+	router,
+	responseHeaders,
+	App,
+}: {
+	request: Request;
+	router: AnyRouter;
+	responseHeaders: Headers;
+	App: RouterApp;
+}) {
+	if (isbot(request.headers.get('User-Agent'))) {
+		return renderRouterForBot({ request, router, responseHeaders, App });
+	}
+
+	const serverSsr = router.serverSsr;
+	if (!serverSsr) {
+		throw new Error('Invariant failed: router.serverSsr is required');
+	}
+
+	const renderController = new AbortController();
+	const onRequestAbort = () => renderController.abort(request.signal.reason);
+	if (request.signal.aborted) {
+		onRequestAbort();
+	} else {
+		request.signal.addEventListener('abort', onRequestAbort, { once: true });
+		serverSsr.onCleanup(() => {
+			request.signal.removeEventListener('abort', onRequestAbort);
+		});
+	}
+
+	let serializationTimeout: ReturnType<typeof setTimeout> | undefined;
+	let stopSerializationListener: (() => void) | undefined;
+	let settleDone!: () => void;
+	let failDone!: (reason: unknown) => void;
+	const done = new Promise<void>((resolve, reject) => {
+		settleDone = resolve;
+		failDone = reject;
+	});
+	if (serverSsr.isSerializationFinished()) {
+		settleDone();
+	} else {
+		stopSerializationListener = serverSsr.onSerializationFinished(() => settleDone());
+	}
+	const releaseInjection = () => {
+		if (serializationTimeout !== undefined) {
+			clearTimeout(serializationTimeout);
+			serializationTimeout = undefined;
+		}
+		stopSerializationListener?.();
+		stopSerializationListener = undefined;
+	};
+
+	const injection: StreamInjectionSource = {
+		take: () => serverSsr.takeBufferedHtml() ?? '',
+		subscribe(notify) {
+			serverSsr.liftScriptBarrier();
+			return serverSsr.onInjectedHtml(notify);
+		},
+		done,
+		renderComplete() {
+			serverSsr.setRenderFinished();
+			if (!serverSsr.isSerializationFinished() && serializationTimeout === undefined) {
+				serializationTimeout = setTimeout(() => {
+					failDone(new Error('Serialization timeout after app render finished'));
+				}, SERIALIZATION_TIMEOUT_MS);
+			}
+		},
+	};
+
+	try {
+		const stream = await renderToReadableStream(
+			App as unknown as ServerComponent,
+			{ router },
+			{
+				signal: renderController.signal,
+				nonce: router.options.ssr?.nonce,
+				injection,
+				onError(error) {
+					if (!isAbortError(request, error)) {
+						console.error('Error in renderToReadableStream:', error);
+					}
+				},
+			},
+		);
+
+		// The renderer's stream is the response body verbatim. `allReady` settles
+		// in every terminal state (close, abort, fatal, consumer cancel) — the
+		// single place to release the injection wiring and the router's SSR state.
+		stream.allReady.then(
+			() => {
+				releaseInjection();
+				serverSsr.cleanup();
+			},
+			() => {
+				releaseInjection();
+				serverSsr.cleanup();
+			},
+		);
+
+		return createSsrStreamResponse(
+			router,
+			new Response(stream as unknown as BodyInit, {
+				status: router.stores.statusCode.get(),
+				headers: responseHeaders,
+			}),
+		);
+	} catch (error) {
+		renderController.abort(error);
+		releaseInjection();
+		router.serverSsr?.cleanup();
+		throw error;
+	}
+}
+
+async function renderRouterForBot({
+	request,
+	router,
+	responseHeaders,
+	App,
+}: {
+	request: Request;
+	router: AnyRouter;
+	responseHeaders: Headers;
+	App: RouterApp;
+}) {
+	try {
+		const result = await prerender(
+			App as unknown as Parameters<typeof prerender>[0],
+			{ router },
+			{
+				signal: request.signal,
+				nonce: router.options.ssr?.nonce,
+				onError(error) {
+					if (!isAbortError(request, error)) {
+						console.error('Error in prerender:', error);
+					}
+				},
+			},
+		);
+		router.serverSsr!.setRenderFinished();
+
+		return new Response(
+			finalizeBufferedHtml(result.html, result.css, router.serverSsr!.takeBufferedHtml()),
+			{
+				status: router.stores.statusCode.get(),
+				headers: responseHeaders,
+			},
+		);
+	} finally {
+		router.serverSsr?.cleanup();
+	}
+}
+
+function isAbortError(request: Request, error: unknown) {
+	return (
+		(request.signal.aborted && error === request.signal.reason) ||
+		(error instanceof Error && error.name === 'AbortError')
+	);
+}