@octanejs/apollo-client 0.1.8 → 0.1.12

package/README.md

@@ -77,6 +77,32 @@ For tests, import Apollo's framework-neutral mocks from
 `@octanejs/apollo-client/testing` and the Octane `MockedProvider` from
 `@octanejs/apollo-client/testing/react`.
 
+## Server rendering
+
+Apollo's `useQuery` does not suspend, so a single server-rendering pass cannot
+wait for network data. Use the Apollo-aware prepass to retain subscriptions,
+finish nested queries, and return Octane's final HTML and scoped CSS:
+
+```ts
+import { createElement } from 'octane';
+import { renderToString } from 'octane/server';
+import { prerenderStatic } from '@octanejs/apollo-client/react/ssr';
+
+const rendered = await prerenderStatic({
+	tree: createElement(App, { client }),
+	renderFunction: renderToString,
+});
+
+const { html, css } = rendered.renderFnResult;
+const apolloState = client.extract();
+```
+
+Create a separate Apollo client for every server request. Restore `apolloState`
+into the browser client's `InMemoryCache` before calling `hydrateRoot` so cached
+queries adopt the server markup without duplicate network requests. Queries
+using `ssr: false` or `fetchPolicy: 'no-cache'` remain client-only, matching
+Apollo 4.2.6. Streaming cache patches are not provided.
+
 ## Compatibility
 
 - Hooks and public TypeScript overloads track Apollo Client 4.2.6.
@@ -88,8 +114,8 @@ For tests, import Apollo's framework-neutral mocks from
 - React Server Components and Apollo's React Compiler output are out of scope.
 - `MockedProvider` accepts normal Octane children blocks; use a descriptor-style
   `children={<App />}` prop when `childProps` must be cloned onto the child.
-- Apollo-aware buffered SSR/cache extraction is not included in this first
-  client release.
+- Apollo-aware buffered SSR is available from `/react/ssr`; streaming cache
+  patches remain out of scope.
 
 The adapter sources are derived from Apollo Client at commit
 `f934b60720fc828a61e04b00988eeefb83d273bc`, under Apollo's MIT license. Local

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/apollo-client",
-  "version": "0.1.8",
+  "version": "0.1.12",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -40,6 +40,10 @@
       "types": "./src/react/internal/index.d.ts",
       "default": "./src/react/internal/index.js"
     },
+    "./react/ssr": {
+      "types": "./src/react/ssr/index.d.ts",
+      "default": "./src/react/ssr/index.js"
+    },
     "./testing": {
       "types": "./src/testing/index.d.ts",
       "default": "./src/testing/index.js"
@@ -58,18 +62,18 @@
     "@apollo/client": ">=4.2.6 <4.3.0",
     "graphql": "^16.0.0 || ^17.0.0",
     "rxjs": "^7.3.0",
-    "octane": "0.1.13"
+    "octane": "0.1.17"
   },
   "devDependencies": {
     "@apollo/client": "4.2.6",
-    "@tsrx/react": "^0.2.46",
+    "@tsrx/react": "^0.2.50",
     "esbuild": "^0.28.1",
     "graphql": "^16.14.2",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "rxjs": "^7.8.2",
     "vitest": "^4.1.10",
-    "octane": "0.1.13"
+    "octane": "0.1.17"
   },
   "scripts": {
     "test": "vitest run --root ../.. --project apollo-client"

package/src/react/ssr/index.d.ts

@@ -0,0 +1,2 @@
+export { prerenderStatic } from './prerenderStatic.js';
+export type { PrerenderStaticInternalContext } from './prerenderStatic.js';

package/src/react/ssr/index.js

@@ -0,0 +1 @@
+export { prerenderStatic } from './prerenderStatic.js';

package/src/react/ssr/prerenderStatic.d.ts

@@ -0,0 +1,52 @@
+import type {
+	ApolloClient,
+	DocumentNode,
+	ObservableQuery,
+	OperationVariables,
+} from '@apollo/client';
+import type { OctaneNode } from 'octane';
+import type { RenderResult } from 'octane/server';
+
+export interface PrerenderStaticInternalContext {
+	getObservableQuery(
+		query: DocumentNode,
+		variables?: Record<string, unknown>,
+	): ObservableQuery | undefined;
+	onCreatedObservableQuery(
+		observable: ObservableQuery,
+		query: DocumentNode,
+		variables: OperationVariables,
+	): void;
+}
+
+export declare namespace prerenderStatic {
+	type ServerTree = OctaneNode | (() => OctaneNode);
+	type PrerenderFunction = (
+		component: () => OctaneNode,
+	) => string | RenderResult | PromiseLike<string | RenderResult>;
+
+	interface Options<Prerender extends PrerenderFunction = PrerenderFunction> {
+		tree: ServerTree;
+		context?: { client?: ApolloClient };
+		renderFunction: Prerender;
+		signal?: AbortSignal;
+		ignoreResults?: boolean;
+		diagnostics?: boolean;
+		maxRerenders?: number;
+	}
+
+	interface Diagnostics {
+		renderCount: number;
+	}
+
+	interface Result<Prerender extends PrerenderFunction = PrerenderFunction> {
+		result: string;
+		renderFnResult: Awaited<ReturnType<Prerender>>;
+		aborted: boolean;
+		diagnostics?: Diagnostics;
+	}
+}
+
+export declare function prerenderStatic<
+	Prerender extends prerenderStatic.PrerenderFunction = prerenderStatic.PrerenderFunction,
+>(options: prerenderStatic.Options<Prerender>): Promise<prerenderStatic.Result<Prerender>>;

package/src/react/ssr/prerenderStatic.js

@@ -0,0 +1,123 @@
+import { print } from 'graphql';
+import { createElement } from 'octane';
+import { filter, firstValueFrom } from 'rxjs';
+import { canonicalStringify } from '@apollo/client/utilities';
+import { invariant } from '@apollo/client/utilities/invariant';
+
+import { getApolloContext } from '../context/ApolloContext.js';
+import { wrapperSymbol } from '../internal/index.js';
+import { useSSRQuery } from './useSSRQuery.js';
+
+function getObservableQueryKey(query, variables = {}) {
+	return `${print(query)}|${canonicalStringify(variables)}`;
+}
+
+const noopObserver = { complete() {} };
+
+/**
+ * Render an Octane tree repeatedly until Apollo's non-suspending useQuery
+ * operations settle. The final Octane render result retains its scoped CSS.
+ */
+export function prerenderStatic({
+	tree,
+	context = {},
+	renderFunction,
+	signal,
+	ignoreResults,
+	diagnostics,
+	maxRerenders = 50,
+}) {
+	const availableObservableQueries = new Map();
+	const subscriptions = new Set();
+	const recentlyCreatedObservableQueries = new Set();
+	let renderCount = 0;
+
+	const internalContext = {
+		getObservableQuery(query, variables) {
+			return availableObservableQueries.get(getObservableQueryKey(query, variables));
+		},
+		onCreatedObservableQuery(observable, query, variables) {
+			availableObservableQueries.set(getObservableQueryKey(query, variables), observable);
+			subscriptions.add(observable.subscribe(noopObserver));
+			if (observable.options.fetchPolicy !== 'cache-only') {
+				recentlyCreatedObservableQueries.add(observable);
+			}
+		},
+	};
+
+	async function process() {
+		renderCount += 1;
+		invariant(renderCount <= maxRerenders, 25, maxRerenders);
+		invariant(!signal?.aborted, 26);
+
+		const ApolloContext = getApolloContext();
+		const child = typeof tree === 'function' ? createElement(tree, {}) : tree;
+		function ApolloSSRTree() {
+			return createElement(ApolloContext.Provider, {
+				value: {
+					...context,
+					[wrapperSymbol]: {
+						useQuery: () => useSSRQuery.bind(internalContext),
+					},
+				},
+				children: child,
+			});
+		}
+
+		const renderFnResult = await renderFunction(ApolloSSRTree);
+		const result = consume(renderFnResult, ignoreResults);
+		if (recentlyCreatedObservableQueries.size === 0) {
+			return { result, renderFnResult, aborted: signal?.aborted ?? false };
+		}
+		if (signal?.aborted) {
+			return { result, renderFnResult, aborted: true };
+		}
+
+		const dataPromise = Promise.all(
+			Array.from(recentlyCreatedObservableQueries, async (observable) => {
+				await firstValueFrom(observable.pipe(filter((value) => value.loading === false)));
+				recentlyCreatedObservableQueries.delete(observable);
+			}),
+		);
+
+		if (signal) {
+			let resolveAbort;
+			const abortPromise = new Promise((resolve) => {
+				resolveAbort = resolve;
+			});
+			signal.addEventListener('abort', resolveAbort);
+			try {
+				await Promise.race([abortPromise, dataPromise]);
+			} finally {
+				signal.removeEventListener('abort', resolveAbort);
+			}
+		} else {
+			await dataPromise;
+		}
+
+		if (signal?.aborted) {
+			return { result, renderFnResult, aborted: true };
+		}
+		return process();
+	}
+
+	return Promise.resolve()
+		.then(process)
+		.then((result) => (diagnostics ? { ...result, diagnostics: { renderCount } } : result))
+		.finally(() => {
+			availableObservableQueries.clear();
+			recentlyCreatedObservableQueries.clear();
+			for (const subscription of subscriptions) subscription.unsubscribe();
+			subscriptions.clear();
+		});
+}
+
+function consume(value, ignoreResults) {
+	if (typeof value === 'string') return ignoreResults ? '' : value;
+	if (value && typeof value.html === 'string' && typeof value.css === 'string') {
+		return ignoreResults ? '' : value.html;
+	}
+	throw new Error(
+		'`prerenderStatic` requires an Octane renderer returning `{ html, css }` or a string.',
+	);
+}

package/src/react/ssr/useSSRQuery.js

@@ -0,0 +1,76 @@
+import { NetworkStatus } from '@apollo/client';
+import { maybeDeepFreeze } from '@apollo/client/utilities/internal';
+
+import { skipToken } from '../hooks/constants.js';
+import { useApolloClient } from '../hooks/useApolloClient.js';
+import { useQuery } from '../hooks/useQuery.js';
+
+const skipStandbyResult = maybeDeepFreeze({
+	loading: false,
+	data: undefined,
+	dataState: 'empty',
+	error: undefined,
+	networkStatus: NetworkStatus.ready,
+	partial: true,
+});
+
+function withoutObservableAccess(value) {
+	Object.defineProperty(value, 'observable', {
+		get() {
+			throw new Error(
+				'"observable" property is not accessible on skipped hooks or hook calls with `ssr: false` during SSR',
+			);
+		},
+	});
+	return value;
+}
+
+// Matches Apollo Client 4.2.6's SSR hook while using Octane's provider and
+// call-site-slotted useApolloClient. The prepass owns the observable lifetime.
+export const useSSRQuery = function (query, options = {}) {
+	'use no memo';
+
+	function notAllowed() {
+		throw new Error('This method cannot be called during SSR.');
+	}
+
+	const client = useApolloClient(typeof options === 'object' ? options.client : undefined);
+	const baseResult = {
+		client,
+		refetch: notAllowed,
+		fetchMore: notAllowed,
+		subscribeToMore: notAllowed,
+		updateQuery: notAllowed,
+		startPolling: notAllowed,
+		stopPolling: notAllowed,
+		variables: typeof options === 'object' ? options.variables : undefined,
+		previousData: undefined,
+	};
+
+	if (options === skipToken || options.skip || options.fetchPolicy === 'standby') {
+		return withoutObservableAccess({ ...baseResult, ...skipStandbyResult });
+	}
+
+	if (options.ssr === false || options.fetchPolicy === 'no-cache') {
+		return withoutObservableAccess({ ...baseResult, ...useQuery.ssrDisabledResult });
+	}
+
+	let observable = this.getObservableQuery(query, options.variables);
+	if (!observable) {
+		observable = client.watchQuery({
+			query,
+			...options,
+			fetchPolicy:
+				options.fetchPolicy === 'network-only' || options.fetchPolicy === 'cache-and-network'
+					? 'cache-first'
+					: options.fetchPolicy,
+		});
+		this.onCreatedObservableQuery(observable, query, options.variables);
+	}
+
+	return {
+		observable,
+		...observable.getCurrentResult(),
+		...baseResult,
+	};
+};