@octanejs/apollo-client 0.1.7 → 0.1.11

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.7",
+  "version": "0.1.11",
   "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"
@@ -50,26 +54,26 @@
     }
   },
   "dependencies": {
-    "@graphql-typed-document-node/core": "^3.1.1",
-    "@wry/equality": "^0.5.6",
+    "@graphql-typed-document-node/core": "^3.2.0",
+    "@wry/equality": "^0.5.7",
     "@wry/trie": "^0.5.0"
   },
   "peerDependencies": {
     "@apollo/client": ">=4.2.6 <4.3.0",
     "graphql": "^16.0.0 || ^17.0.0",
     "rxjs": "^7.3.0",
-    "octane": "0.1.12"
+    "octane": "0.1.16"
   },
   "devDependencies": {
     "@apollo/client": "4.2.6",
-    "@tsrx/react": "^0.2.44",
+    "@tsrx/react": "^0.2.50",
     "esbuild": "^0.28.1",
-    "graphql": "^16.11.0",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
+    "graphql": "^16.14.2",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
     "rxjs": "^7.8.2",
-    "vitest": "^4.1.9",
-    "octane": "0.1.12"
+    "vitest": "^4.1.10",
+    "octane": "0.1.16"
   },
   "scripts": {
     "test": "vitest run --root ../.. --project apollo-client"

package/src/react/hooks/useBackgroundQuery.d.ts

@@ -196,28 +196,21 @@ export declare namespace useBackgroundQuery {
 		queryRef: TOptions extends any
 			? TOptions extends SkipToken
 				? undefined
-				:
-						| QueryRef<
-								TData,
-								TVariables,
-								| 'complete'
-								| 'streaming'
-								| (
-										| (OptionWithFallback<TOptions, DefaultOptions, 'errorPolicy'> extends 'none'
-												? never
-												: 'empty')
-										| (OptionWithFallback<
-												TOptions,
-												DefaultOptions,
-												'returnPartialData'
-										  > extends false
-												? never
-												: 'partial')
-								  )
-						  >
-						| (OptionWithFallback<TOptions, DefaultOptions, 'skip'> extends false
-								? never
-								: undefined)
+				: | QueryRef<
+							TData,
+							TVariables,
+							| 'complete'
+							| 'streaming'
+							| (
+									| (OptionWithFallback<TOptions, DefaultOptions, 'errorPolicy'> extends 'none'
+											? never
+											: 'empty')
+									| (OptionWithFallback<TOptions, DefaultOptions, 'returnPartialData'> extends false
+											? never
+											: 'partial')
+							  )
+					  >
+					| (OptionWithFallback<TOptions, DefaultOptions, 'skip'> extends false ? never : undefined)
 			: never,
 		result: useBackgroundQuery.Result<TData, TVariables>,
 	];

package/src/react/hooks/useFragment.d.ts

@@ -35,9 +35,7 @@ export declare namespace useFragment {
 		 * be retrieved, or a `{ __ref: "..." }` reference, or a `string` ID (uncommon).
 		 */
 		from:
-			| useFragment.FromOptionValue<TData>
-			| Array<useFragment.FromOptionValue<TData> | null>
-			| null;
+			useFragment.FromOptionValue<TData> | Array<useFragment.FromOptionValue<TData> | null> | null;
 		/**
 		 * Whether to read from optimistic or non-optimistic cache data. If
 		 * this named option is provided, the optimistic parameter of the

package/src/react/hooks/useSuspenseQuery.d.ts

@@ -234,16 +234,13 @@ export declare namespace useSuspenseQuery {
 		| (TOptions extends any
 				? TOptions extends SkipToken
 					? 'empty'
-					:
-							| (OptionWithFallback<TOptions, DefaultOptions, 'errorPolicy'> extends 'none'
-									? never
-									: 'empty')
-							| (OptionWithFallback<TOptions, DefaultOptions, 'skip'> extends false
-									? never
-									: 'empty')
-							| (OptionWithFallback<TOptions, DefaultOptions, 'returnPartialData'> extends false
-									? never
-									: 'partial')
+					: | (OptionWithFallback<TOptions, DefaultOptions, 'errorPolicy'> extends 'none'
+								? never
+								: 'empty')
+						| (OptionWithFallback<TOptions, DefaultOptions, 'skip'> extends false ? never : 'empty')
+						| (OptionWithFallback<TOptions, DefaultOptions, 'returnPartialData'> extends false
+								? never
+								: 'partial')
 				: never)
 		| ([TOptions] extends [SkipToken]
 				? DefaultOptions extends {

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,
+	};
+};