@octanejs/apollo-client 0.1.0

package/LICENSE

@@ -0,0 +1,49 @@
+Octane binding
+==============
+
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Apollo Client-derived adapter sources
+=====================================
+
+The MIT License (MIT)
+
+Copyright (c) 2022 Apollo Graph, Inc. (Formerly Meteor Development Group, Inc.)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# @octanejs/apollo-client
+
+Apollo Client 4 bindings for Octane. The package reuses Apollo's client, cache,
+links, GraphQL types, and testing core unchanged, while porting the published
+React hook adapter to Octane's compiler-slotted hooks.
+
+The adapter is pinned and surface-tested against `@apollo/client@4.2.6`.
+
+## Install
+
+```bash
+pnpm add @octanejs/apollo-client @apollo/client graphql rxjs
+```
+
+## Use
+
+Apollo 4 keeps its framework-neutral API at the package root and its component
+adapter on `/react`. The Octane package mirrors that split:
+
+```ts
+import {
+	ApolloClient,
+	InMemoryCache,
+	HttpLink,
+	gql,
+	type TypedDocumentNode,
+} from '@octanejs/apollo-client';
+import { ApolloProvider, useQuery } from '@octanejs/apollo-client/react';
+```
+
+```tsrx
+interface ViewerData {
+	viewer: {
+		id: string;
+		name: string;
+	};
+}
+
+const client = new ApolloClient({
+	cache: new InMemoryCache(),
+	link: new HttpLink({ uri: '/graphql' }),
+});
+
+const GET_VIEWER: TypedDocumentNode<ViewerData> = gql`
+	query Viewer {
+		viewer {
+			id
+			name
+		}
+	}
+`;
+
+function Viewer() @{
+	const result = useQuery(GET_VIEWER);
+
+	@if (result.loading) {
+		<p>Loading…</p>
+	} @else if (result.error) {
+		<p>{result.error.message}</p>
+	} @else {
+		<p>{(result.data?.viewer.name ?? 'Unknown viewer') as string}</p>
+	}
+}
+
+export function App() @{
+	<ApolloProvider client={client}>
+		<Viewer />
+	</ApolloProvider>
+}
+```
+
+The complete Apollo 4.2.6 client hook surface is available, including lazy
+queries, mutations, subscriptions, fragments, Suspense queries, background and
+loadable queries, query references, `skipToken`, and query preloading.
+
+For tests, import Apollo's framework-neutral mocks from
+`@octanejs/apollo-client/testing` and the Octane `MockedProvider` from
+`@octanejs/apollo-client/testing/react`.
+
+## Compatibility
+
+- Hooks and public TypeScript overloads track Apollo Client 4.2.6.
+- Suspense unwraps Apollo's stable query promises through Octane `use()` rather
+  than throwing promises.
+- Omitted React dependency arrays that intentionally mean “every render” are
+  explicit `null` in the port so Octane does not infer a narrower dependency
+  set.
+- 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.
+
+The adapter sources are derived from Apollo Client at commit
+`f934b60720fc828a61e04b00988eeefb83d273bc`, under Apollo's MIT license. Local
+changes are limited to Octane imports, hook semantics, Suspense site identity,
+the render-phase guard, and the functional `MockedProvider`.

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@octanejs/apollo-client",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "description": "Apollo Client bindings for the octane renderer — reuses Apollo's framework-neutral core and ports its React adapter onto octane.",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/apollo-client"
+  },
+  "main": "src/index.js",
+  "module": "src/index.js",
+  "types": "src/index.d.ts",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./react": {
+      "types": "./src/react/index.d.ts",
+      "default": "./src/react/index.js"
+    },
+    "./react/internal": {
+      "types": "./src/react/internal/index.d.ts",
+      "default": "./src/react/internal/index.js"
+    },
+    "./testing": {
+      "types": "./src/testing/index.d.ts",
+      "default": "./src/testing/index.js"
+    },
+    "./testing/react": {
+      "types": "./src/testing/react/index.d.ts",
+      "default": "./src/testing/react/index.js"
+    }
+  },
+  "dependencies": {
+    "@graphql-typed-document-node/core": "^3.1.1",
+    "@wry/equality": "^0.5.6",
+    "@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.5"
+  },
+  "devDependencies": {
+    "@apollo/client": "4.2.6",
+    "@tsrx/react": "^0.2.37",
+    "esbuild": "^0.28.1",
+    "graphql": "^16.11.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "rxjs": "^7.8.2",
+    "vitest": "^4.1.9",
+    "octane": "0.1.5"
+  },
+  "scripts": {
+    "test": "vitest run --root ../.. --project apollo-client"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1 @@
+export * from '@apollo/client';

package/src/index.js

@@ -0,0 +1,3 @@
+// Apollo Client 4 keeps its framework-neutral client/cache/link surface at the
+// package root. Hooks intentionally remain on the matching `/react` subpath.
+export * from '@apollo/client';

package/src/react/context/ApolloContext.d.ts

@@ -0,0 +1,8 @@
+import type { Context } from 'octane';
+import type { ApolloClient } from '@apollo/client';
+import type { HookWrappers, wrapperSymbol } from '@octanejs/apollo-client/react/internal';
+export interface ApolloContextValue {
+	client?: ApolloClient;
+	[wrapperSymbol]?: HookWrappers;
+}
+export declare function getApolloContext(): Context<ApolloContextValue>;

package/src/react/context/ApolloContext.js

@@ -0,0 +1,21 @@
+import * as React from 'octane';
+import { invariant } from '@apollo/client/utilities/invariant';
+// To make sure Apollo Client doesn't create more than one React context
+// (which can lead to problems like having an Apollo Client instance added
+// in one context, then attempting to retrieve it from another different
+// context), a single Apollo context is created and tracked in global state.
+const contextKey = Symbol.for('__APOLLO_CONTEXT__');
+export function getApolloContext() {
+	invariant('createContext' in React, 37);
+	let context = React.createContext[contextKey];
+	if (!context) {
+		Object.defineProperty(React.createContext, contextKey, {
+			value: (context = React.createContext({})),
+			enumerable: false,
+			writable: false,
+			configurable: true,
+		});
+		context.displayName = 'ApolloContext';
+	}
+	return context;
+}

package/src/react/context/ApolloProvider.d.ts

@@ -0,0 +1,9 @@
+import type { ComponentBody } from 'octane';
+import type { ApolloClient } from '@apollo/client';
+export declare namespace ApolloProvider {
+	interface Props {
+		client: ApolloClient;
+		children?: unknown;
+	}
+}
+export declare const ApolloProvider: ComponentBody<ApolloProvider.Props>;

package/src/react/context/ApolloProvider.js

@@ -0,0 +1,15 @@
+import * as React from 'octane';
+import { invariant } from '@apollo/client/utilities/invariant';
+import { getApolloContext } from './ApolloContext.js';
+export const ApolloProvider = ({ client, children }) => {
+	const ApolloContext = getApolloContext();
+	const parentContext = React.useContext(ApolloContext);
+	const context = React.useMemo(() => {
+		return {
+			...parentContext,
+			client: client || parentContext.client,
+		};
+	}, [parentContext, client]);
+	invariant(context.client, 38);
+	return React.createElement(ApolloContext.Provider, { value: context }, children);
+};

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

@@ -0,0 +1,2 @@
+export declare const skipToken: unique symbol;
+export type SkipToken = typeof skipToken;

package/src/react/hooks/constants.js

@@ -0,0 +1 @@
+export const skipToken = Symbol.for('apollo.skipToken');

package/src/react/hooks/internal/__use.d.ts

@@ -0,0 +1,3 @@
+type Use = <T>(promise: Promise<T>, site?: symbol | string) => T;
+export declare const __use: Use;
+export {};

package/src/react/hooks/internal/__use.js

@@ -0,0 +1,9 @@
+import * as React from 'octane';
+const fallbackSite = Symbol('apollo.__use');
+// Apollo's React adapter falls back to throwing decorated promises on React 18.
+// Octane always has use(), and raw promise throws are errors rather than
+// suspension. The public hook's compiler-provided site is threaded through on
+// the server so conditional sibling hooks keep stable SSR cache identities.
+export function __use(promise, site) {
+	return React.use(promise, site ?? fallbackSite);
+}

package/src/react/hooks/internal/index.d.ts

@@ -0,0 +1,5 @@
+export { useDeepMemo } from './useDeepMemo.js';
+export { useRenderGuard } from './useRenderGuard.js';
+export { useSuspenseHookCacheKey } from './useSuspenseHookCacheKey.js';
+export { __use } from './__use.js';
+export { wrapHook } from './wrapHook.js';

package/src/react/hooks/internal/index.js

@@ -0,0 +1,6 @@
+// These hooks are used internally and are not exported publicly by the library
+export { useDeepMemo } from './useDeepMemo.js';
+export { useRenderGuard } from './useRenderGuard.js';
+export { useSuspenseHookCacheKey } from './useSuspenseHookCacheKey.js';
+export { __use } from './__use.js';
+export { wrapHook } from './wrapHook.js';

package/src/react/hooks/internal/site.d.ts

@@ -0,0 +1,2 @@
+export declare function subSite(site: symbol | undefined, tag: string): symbol;
+export declare function isCompilerSite(value: unknown, reserved?: symbol): value is symbol;

package/src/react/hooks/internal/site.js

@@ -0,0 +1,20 @@
+const ROOT_SITE = Symbol('apollo.root');
+const subSites = new Map();
+
+/** Return a stable child site for repeated helper hooks inside one public hook. */
+export function subSite(site, tag) {
+	const parent = typeof site === 'symbol' ? site : ROOT_SITE;
+	let children = subSites.get(parent);
+	if (!children) subSites.set(parent, (children = new Map()));
+	let child = children.get(tag);
+	if (!child) {
+		child = Symbol(`${parent.description || 'apollo'}:${tag}`);
+		children.set(tag, child);
+	}
+	return child;
+}
+
+/** Compiler hook sites are symbols, but Apollo's skipToken is user data. */
+export function isCompilerSite(value, reserved) {
+	return typeof value === 'symbol' && value !== reserved;
+}

package/src/react/hooks/internal/useDeepMemo.d.ts

@@ -0,0 +1,5 @@
+export declare function useDeepMemo<TValue>(
+	memoFn: () => TValue,
+	deps: readonly unknown[],
+	site?: symbol,
+): TValue;

package/src/react/hooks/internal/useDeepMemo.js

@@ -0,0 +1,11 @@
+import { equal } from '@wry/equality';
+import * as React from 'octane';
+export function useDeepMemo(memoFn, deps, site) {
+	const ref = React.useRef(void 0, site);
+	// eslint-disable-next-line react-hooks/refs
+	if (!ref.current || !equal(ref.current.deps, deps)) {
+		ref.current = { value: memoFn(), deps };
+	}
+	// eslint-disable-next-line react-hooks/refs
+	return ref.current.value;
+}

package/src/react/hooks/internal/useIsomorphicLayoutEffect.d.ts

@@ -0,0 +1,2 @@
+import * as React from 'octane';
+export declare const useIsomorphicLayoutEffect: typeof React.useLayoutEffect;

package/src/react/hooks/internal/useIsomorphicLayoutEffect.js

@@ -0,0 +1,8 @@
+import * as React from 'octane';
+import { canUseDOM } from '@apollo/client/utilities/internal';
+// use canUseDOM here instead of canUseLayoutEffect because we want to be able
+// to use useLayoutEffect in our jest tests. useLayoutEffect seems to work fine
+// in useSuspenseQuery tests, but to honor the original comment about the
+// warnings for useSyncExternalStore implementation, canUseLayoutEffect is left
+// alone.
+export const useIsomorphicLayoutEffect = canUseDOM ? React.useLayoutEffect : React.useEffect;

package/src/react/hooks/internal/useRenderGuard.d.ts

@@ -0,0 +1 @@
+export declare function useRenderGuard(): () => boolean;

package/src/react/hooks/internal/useRenderGuard.js

@@ -0,0 +1,14 @@
+import * as React from 'octane';
+export function useRenderGuard() {
+	return React.useCallback(() => {
+		try {
+			// Unlike React, Octane context reads are valid outside a render. A
+			// slot-keyed hook is the reliable render-phase probe: conditional
+			// hooks are supported, and useRef throws when no component is active.
+			React.useRef(null);
+			return true;
+		} catch {
+			return false;
+		}
+	}, []);
+}

package/src/react/hooks/internal/useSuspenseHookCacheKey.d.ts

@@ -0,0 +1,13 @@
+import type { DocumentNode } from 'graphql';
+import type { OperationVariables } from '@apollo/client';
+import type { SkipToken } from '../constants.js';
+export declare namespace useSuspenseHookCacheKey {
+	interface Options {
+		variables?: OperationVariables;
+		queryKey?: string | number | any[];
+	}
+}
+export declare function useSuspenseHookCacheKey(
+	query: DocumentNode,
+	options: (SkipToken & Partial<useSuspenseHookCacheKey.Options>) | useSuspenseHookCacheKey.Options,
+): [DocumentNode, string, ...any[]];

package/src/react/hooks/internal/useSuspenseHookCacheKey.js

@@ -0,0 +1,19 @@
+import * as React from 'octane';
+import { canonicalStringify } from '@apollo/client/utilities';
+import { skipToken } from '../constants.js';
+export function useSuspenseHookCacheKey(query, options) {
+	const { queryKey = [], variables } = options;
+	const canonicalVariables = canonicalStringify(variables);
+	// This state value let's us maintain the variables used for the cache key
+	// when `skipToken` is used to skip a query after its been executed.
+	// Since options aren't provided when using `skipToken`, `variables` would
+	// otherwise disappear which means we'd return a new cache key without a
+	// variables value which creates a new `ObservableQuery` instance. This was
+	// particularly problematic when `refetchQueries` was used because it meant
+	// refetching against an `ObservableQuery` instance that had no variables.
+	let [cacheKeyVariables, setCacheKeyVariables] = React.useState(canonicalVariables);
+	if (options !== skipToken && cacheKeyVariables !== canonicalVariables) {
+		setCacheKeyVariables((cacheKeyVariables = canonicalVariables));
+	}
+	return [query, cacheKeyVariables, ...[].concat(queryKey)];
+}

package/src/react/hooks/internal/validateSuspenseHookOptions.d.ts

@@ -0,0 +1,4 @@
+import type { ApolloClient, OperationVariables } from '@apollo/client';
+export declare function validateSuspenseHookOptions<TData, TVariables extends OperationVariables>(
+	options: ApolloClient.WatchQueryOptions<TData, TVariables>,
+): void;

package/src/react/hooks/internal/validateSuspenseHookOptions.js

@@ -0,0 +1,16 @@
+import { __DEV__ } from '@apollo/client/utilities/environment';
+import { invariant } from '@apollo/client/utilities/invariant';
+export function validateSuspenseHookOptions(options) {
+	const { fetchPolicy, returnPartialData } = options;
+	validateFetchPolicy(fetchPolicy);
+	validatePartialDataReturn(fetchPolicy, returnPartialData);
+}
+function validateFetchPolicy(fetchPolicy = 'cache-first') {
+	const supportedFetchPolicies = ['cache-first', 'network-only', 'no-cache', 'cache-and-network'];
+	invariant(supportedFetchPolicies.includes(fetchPolicy), 35, fetchPolicy);
+}
+function validatePartialDataReturn(fetchPolicy, returnPartialData) {
+	if (fetchPolicy === 'no-cache' && returnPartialData) {
+		__DEV__ && invariant.warn(36);
+	}
+}

package/src/react/hooks/internal/wrapHook.d.ts

@@ -0,0 +1,77 @@
+import type { ApolloClient } from '@apollo/client';
+import type { ObservableQuery } from '@apollo/client';
+import type { createQueryPreloader } from '@octanejs/apollo-client/react';
+import type {
+	useBackgroundQuery,
+	useFragment,
+	useQuery,
+	useQueryRefHandlers,
+	useReadQuery,
+	useSuspenseFragment,
+	useSuspenseQuery,
+} from '@octanejs/apollo-client/react';
+type FunctionSignature<T> = T extends (...args: infer A) => infer R ? (...args: A) => R : never;
+interface WrappableHooks {
+	createQueryPreloader: FunctionSignature<typeof createQueryPreloader>;
+	useQuery: FunctionSignature<typeof useQuery>;
+	useSuspenseQuery: FunctionSignature<typeof useSuspenseQuery>;
+	useSuspenseFragment: FunctionSignature<typeof useSuspenseFragment>;
+	useBackgroundQuery: FunctionSignature<typeof useBackgroundQuery>;
+	useReadQuery: FunctionSignature<typeof useReadQuery>;
+	useFragment: FunctionSignature<typeof useFragment>;
+	useQueryRefHandlers: FunctionSignature<typeof useQueryRefHandlers>;
+}
+/**
+ * @internal
+ * Can be used to correctly type the [Symbol.for("apollo.hook.wrappers")] property of
+ * `QueryManager`, to override/wrap hook functionality.
+ *
+ * @deprecated This is an internal API and should not be used directly. This can be removed or changed at any time.
+ */
+export type HookWrappers = {
+	[K in keyof WrappableHooks]?: (originalHook: WrappableHooks[K]) => WrappableHooks[K];
+};
+/**
+ * @internal
+ *
+ * Makes an Apollo Client hook "wrappable".
+ * That means that the Apollo Client instance can expose a "wrapper" that will be
+ * used to wrap the original hook implementation with additional logic.
+ * @example
+ *
+ * ```tsx
+ * // this is already done in `@apollo/client` for all wrappable hooks (see `WrappableHooks`)
+ * // following this pattern
+ * function useQuery() {
+ *   return wrapHook('useQuery', _useQuery, options.client)(query, options);
+ * }
+ * function _useQuery(query, options) {
+ *   // original implementation
+ * }
+ *
+ * // this is what a library like `@apollo/client-react-streaming` would do
+ * class ApolloClientWithStreaming extends ApolloClient {
+ *   constructor(options) {
+ *     super(options);
+ *     this.queryManager[Symbol.for("apollo.hook.wrappers")] = {
+ *       useQuery: (original) => (query, options) => {
+ *         console.log("useQuery was called with options", options);
+ *         return original(query, options);
+ *       }
+ *     }
+ *   }
+ * }
+ *
+ * // this will now log the options and then call the original `useQuery`
+ * const client = new ApolloClientWithStreaming({ ... });
+ * useQuery(query, { client });
+ * ```
+ *
+ * @deprecated This is an internal API and should not be used directly. This can be removed or changed at any time.
+ */
+export declare function wrapHook<Hook extends (...args: any[]) => any>(
+	hookName: keyof WrappableHooks,
+	useHook: Hook,
+	clientOrObsQuery: ObservableQuery<any> | ApolloClient,
+): Hook;
+export {};

package/src/react/hooks/internal/wrapHook.js

@@ -0,0 +1,64 @@
+import * as React from 'octane';
+import { wrapperSymbol } from '@octanejs/apollo-client/react/internal';
+// direct import to avoid circular dependency
+import { getApolloContext } from '../../context/ApolloContext.js';
+/**
+ * @internal
+ *
+ * Makes an Apollo Client hook "wrappable".
+ * That means that the Apollo Client instance can expose a "wrapper" that will be
+ * used to wrap the original hook implementation with additional logic.
+ * @example
+ *
+ * ```tsx
+ * // this is already done in `@apollo/client` for all wrappable hooks (see `WrappableHooks`)
+ * // following this pattern
+ * function useQuery() {
+ *   return wrapHook('useQuery', _useQuery, options.client)(query, options);
+ * }
+ * function _useQuery(query, options) {
+ *   // original implementation
+ * }
+ *
+ * // this is what a library like `@apollo/client-react-streaming` would do
+ * class ApolloClientWithStreaming extends ApolloClient {
+ *   constructor(options) {
+ *     super(options);
+ *     this.queryManager[Symbol.for("apollo.hook.wrappers")] = {
+ *       useQuery: (original) => (query, options) => {
+ *         console.log("useQuery was called with options", options);
+ *         return original(query, options);
+ *       }
+ *     }
+ *   }
+ * }
+ *
+ * // this will now log the options and then call the original `useQuery`
+ * const client = new ApolloClientWithStreaming({ ... });
+ * useQuery(query, { client });
+ * ```
+ *
+ * @deprecated This is an internal API and should not be used directly. This can be removed or changed at any time.
+ */
+export function wrapHook(hookName, useHook, clientOrObsQuery) {
+	// Priority-wise, the later entries in this array wrap
+	// previous entries and could prevent them (and in the end,
+	// even the original hook) from running
+	const wrapperSources = [
+		clientOrObsQuery['queryManager'],
+		// if we are a hook (not `preloadQuery`), we are guaranteed to be inside of
+		// a React render and can use context
+		hookName.startsWith('use')
+			? // eslint-disable-next-line react-hooks/rules-of-hooks
+				React.useContext(getApolloContext())
+			: undefined,
+	];
+	let wrapped = useHook;
+	for (const source of wrapperSources) {
+		const wrapper = source?.[wrapperSymbol]?.[hookName];
+		if (wrapper) {
+			wrapped = wrapper(wrapped);
+		}
+	}
+	return wrapped;
+}

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

@@ -0,0 +1,17 @@
+import type { ApolloClient } from '@apollo/client';
+/**
+ * @example
+ *
+ * ```jsx
+ * import { useApolloClient } from "@octanejs/apollo-client/react";
+ *
+ * function SomeComponent() {
+ *   const client = useApolloClient();
+ *   // `client` is now set to the `ApolloClient` instance being used by the
+ *   // application (that was configured using something like `ApolloProvider`)
+ * }
+ * ```
+ *
+ * @returns The `ApolloClient` instance being used by the application.
+ */
+export declare function useApolloClient(override?: ApolloClient): ApolloClient;

package/src/react/hooks/useApolloClient.js

@@ -0,0 +1,27 @@
+import * as React from 'octane';
+import { invariant } from '@apollo/client/utilities/invariant';
+import { getApolloContext } from '../context/ApolloContext.js';
+/**
+ * @example
+ *
+ * ```jsx
+ * import { useApolloClient } from "@octanejs/apollo-client/react";
+ *
+ * function SomeComponent() {
+ *   const client = useApolloClient();
+ *   // `client` is now set to the `ApolloClient` instance being used by the
+ *   // application (that was configured using something like `ApolloProvider`)
+ * }
+ * ```
+ *
+ * @returns The `ApolloClient` instance being used by the application.
+ */
+export function useApolloClient(override) {
+	// A zero-argument custom hook call is compiled as useApolloClient(site).
+	// ApolloClient is an object, so a symbol here can only be Octane's site.
+	if (typeof override === 'symbol') override = undefined;
+	const context = React.useContext(getApolloContext());
+	const client = override || context.client;
+	invariant(!!client, 28);
+	return client;
+}