@octanejs/apollo-client 0.1.0

package/src/react/hooks/useBackgroundQuery.js

@@ -0,0 +1,88 @@
+import * as React from 'octane';
+import {
+	getSuspenseCache,
+	unwrapQueryRef,
+	updateWrappedQueryRef,
+	wrapQueryRef,
+} from '@octanejs/apollo-client/react/internal';
+import { skipToken } from './constants.js';
+import { useSuspenseHookCacheKey, wrapHook } from './internal/index.js';
+import { isCompilerSite } from './internal/site.js';
+import { useApolloClient } from './useApolloClient.js';
+import { useWatchQueryOptions } from './useSuspenseQuery.js';
+export const useBackgroundQuery = function useBackgroundQuery(query, options) {
+	'use no memo';
+	if (isCompilerSite(options, skipToken)) options = undefined;
+	return wrapHook(
+		'useBackgroundQuery',
+		useBackgroundQuery_,
+		useApolloClient(typeof options === 'object' ? options.client : undefined),
+	)(query, options ?? {});
+};
+function useBackgroundQuery_(query, options) {
+	const client = useApolloClient(options.client);
+	const suspenseCache = getSuspenseCache(client);
+	const watchQueryOptions = useWatchQueryOptions({ client, query, options });
+	const { fetchPolicy } = watchQueryOptions;
+	const cacheKey = useSuspenseHookCacheKey(query, options);
+	// This ref tracks the first time query execution is enabled to determine
+	// whether to return a query ref or `undefined`. When initialized
+	// in a skipped state (either via `skip: true` or `skipToken`) we return
+	// `undefined` for the `queryRef` until the query has been enabled. Once
+	// enabled, a query ref is always returned regardless of whether the query is
+	// skipped again later.
+	const didFetchResult = React.useRef(fetchPolicy !== 'standby');
+	didFetchResult.current ||= fetchPolicy !== 'standby';
+	const queryRef = suspenseCache.getQueryRef(cacheKey, () => client.watchQuery(watchQueryOptions));
+	const [wrappedQueryRef, setWrappedQueryRef] = React.useState(wrapQueryRef(queryRef));
+	if (unwrapQueryRef(wrappedQueryRef) !== queryRef) {
+		setWrappedQueryRef(wrapQueryRef(queryRef));
+	}
+	if (queryRef.didChangeOptions(watchQueryOptions)) {
+		const promise = queryRef.applyOptions(watchQueryOptions);
+		updateWrappedQueryRef(wrappedQueryRef, promise);
+	}
+	// This prevents issues where rerendering useBackgroundQuery after the
+	// queryRef has been disposed would cause the hook to return a new queryRef
+	// instance since disposal also removes it from the suspense cache. We add
+	// the queryRef back in the suspense cache so that the next render will reuse
+	// this queryRef rather than initializing a new instance.
+	React.useEffect(() => {
+		// Since the queryRef is disposed async via `setTimeout`, we have to wait a
+		// tick before checking it and adding back to the suspense cache.
+		const id = setTimeout(() => {
+			if (queryRef.disposed) {
+				suspenseCache.add(cacheKey, queryRef);
+			}
+		});
+		return () => clearTimeout(id);
+		// Omitting the deps is intentional. This avoids stale closures and the
+		// conditional ensures we aren't running the logic on each render.
+	}, null);
+	const fetchMore = React.useCallback(
+		(options) => {
+			const promise = queryRef.fetchMore(options);
+			setWrappedQueryRef(wrapQueryRef(queryRef));
+			return promise;
+		},
+		[queryRef],
+	);
+	const refetch = React.useCallback(
+		(variables) => {
+			const promise = queryRef.refetch(variables);
+			setWrappedQueryRef(wrapQueryRef(queryRef));
+			return promise;
+		},
+		[queryRef],
+	);
+	React.useEffect(() => queryRef.softRetain(), [queryRef]);
+	return [
+		didFetchResult.current ? wrappedQueryRef : void 0,
+		{
+			fetchMore,
+			refetch,
+			// TODO: The internalQueryRef doesn't have TVariables' type information so we have to cast it here
+			subscribeToMore: queryRef.observable.subscribeToMore,
+		},
+	];
+}

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

@@ -0,0 +1,205 @@
+import type {
+	ApolloClient,
+	DataValue,
+	DocumentNode,
+	GetDataState,
+	OperationVariables,
+	TypedDocumentNode,
+} from '@apollo/client';
+import type { ApolloCache, MissingTree } from '@apollo/client/cache';
+import type { MaybeMasked } from '@apollo/client/masking';
+import type { NoInfer } from '@apollo/client/utilities/internal';
+export declare namespace useFragment {
+	import _self = useFragment;
+	interface Options<TData, TVariables extends OperationVariables> {
+		/**
+		 * A GraphQL document created using the `gql` template string tag from
+		 * `graphql-tag` with one or more fragments which will be used to determine
+		 * the shape of data to read. If you provide more than one fragment in this
+		 * document then you must also specify `fragmentName` to select a single.
+		 */
+		fragment: DocumentNode | TypedDocumentNode<TData, TVariables>;
+		/**
+		 * The name of the fragment in your GraphQL document to be used. If you do
+		 * not provide a `fragmentName` and there is only one fragment in your
+		 * `fragment` document then that fragment will be used.
+		 */
+		fragmentName?: string;
+		/**
+		 * Any variables that the GraphQL query may depend on.
+		 */
+		variables?: NoInfer<TVariables>;
+		/**
+		 * An object or array containing a `__typename` and primary key fields
+		 * (such as `id`) identifying the entity object from which the fragment will
+		 * be retrieved, or a `{ __ref: "..." }` reference, or a `string` ID (uncommon).
+		 */
+		from:
+			| 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
+		 * readQuery method can be omitted.
+		 *
+		 * @defaultValue true
+		 */
+		optimistic?: boolean;
+		/**
+		 * The instance of `ApolloClient` to use to look up the fragment.
+		 *
+		 * By default, the instance that's passed down via context is used, but you
+		 * can provide a different instance here.
+		 *
+		 * @docGroup 1. Operation options
+		 */
+		client?: ApolloClient;
+	}
+	namespace DocumentationTypes {
+		namespace useFragment {
+			interface Options<
+				TData = unknown,
+				TVariables extends OperationVariables = OperationVariables,
+			> extends _self.Options<TData, TVariables> {}
+		}
+	}
+	/**
+	 * Acceptable values provided to the `from` option.
+	 */
+	type FromOptionValue<TData> = ApolloCache.FromOptionValue<TData>;
+	type Result<TData> =
+		| ({
+				/**
+				 *
+				 */
+				complete: true;
+				/**
+				 * A tree of all `MissingFieldError` messages reported during fragment reading, where the branches of the tree indicate the paths of the errors within the query result.
+				 */
+				missing?: never;
+		  } & GetDataState<MaybeMasked<TData>, 'complete'>)
+		| {
+				/**
+				 *
+				 */
+				complete: false;
+				/**
+				 * A tree of all `MissingFieldError` messages reported during fragment reading, where the branches of the tree indicate the paths of the errors within the query result.
+				 */
+				missing?: MissingTree;
+				/**
+				 * An object containing the result of your GraphQL query after it completes.
+				 *
+				 * This value might be `undefined` if a query results in one or more errors (depending on the query's `errorPolicy`).
+				 *
+				 * @docGroup 1. Operation data
+				 */
+				data: TData extends Array<infer TItem>
+					? Array<DataValue.Partial<TItem> | null>
+					: DataValue.Partial<TData>;
+				/**
+				 * Describes the completeness of `data`.
+				 *
+				 * - `empty`: No data could be fulfilled from the cache or the result is
+				 *   incomplete. `data` is `undefined`.
+				 * - `partial`: Some data could be fulfilled from the cache but `data` is
+				 *   incomplete. This is only possible when `returnPartialData` is `true`.
+				 * - `streaming`: `data` is incomplete as a result of a deferred query and
+				 *   the result is still streaming in.
+				 * - `complete`: `data` is a fully satisfied query result fulfilled
+				 *   either from the cache or network.
+				 *
+				 * @docGroup 1. Operation data
+				 */
+				dataState: 'partial';
+		  };
+	namespace DocumentationTypes {
+		namespace useFragment {
+			interface Result<TData> {
+				data: MaybeMasked<TData> | DataValue.Partial<MaybeMasked<TData>>;
+				complete: boolean;
+				/**
+				 * A tree of all `MissingFieldError` messages reported during fragment reading, where the branches of the tree indicate the paths of the errors within the query result.
+				 */
+				missing?: MissingTree;
+			}
+		}
+	}
+	namespace DocumentationTypes {
+		/**
+		 * `useFragment` represents a lightweight live binding into the Apollo Client Cache and enables Apollo Client to broadcast very specific fragment results to individual components. This hook returns an always-up-to-date view of whatever data the cache currently contains for a given fragment. `useFragment` never triggers network requests of its own.
+		 *
+		 * Note that the `useQuery` hook remains the primary hook responsible for querying and populating data in the cache ([see the API reference](./hooks#usequery)). As a result, the component reading the fragment data via `useFragment` is still subscribed to all changes in the query data, but receives updates only when that fragment's specific data change.
+		 *
+		 * To view a `useFragment` example, see the [Fragments](https://www.apollographql.com/docs/react/data/fragments#usefragment) page.
+		 */
+		function useFragment<
+			TData = unknown,
+			TVariables extends OperationVariables = OperationVariables,
+		>({
+			fragment,
+			from,
+			fragmentName,
+			variables,
+			optimistic,
+			client,
+		}: useFragment.Options<TData, TVariables>): useFragment.Result<TData>;
+	}
+}
+/**
+ * `useFragment` represents a lightweight live binding into the Apollo Client Cache and enables Apollo Client to broadcast very specific fragment results to individual components. This hook returns an always-up-to-date view of whatever data the cache currently contains for a given fragment. `useFragment` never triggers network requests of its own.
+ *
+ * Note that the `useQuery` hook remains the primary hook responsible for querying and populating data in the cache ([see the API reference](./hooks#usequery)). As a result, the component reading the fragment data via `useFragment` is still subscribed to all changes in the query data, but receives updates only when that fragment's specific data change.
+ *
+ * To view a `useFragment` example, see the [Fragments](https://www.apollographql.com/docs/react/data/fragments#usefragment) page.
+ */
+export declare function useFragment<
+	TData = unknown,
+	TVariables extends OperationVariables = OperationVariables,
+>(
+	options: useFragment.Options<TData, TVariables> & {
+		from: Array<useFragment.FromOptionValue<TData>>;
+	},
+): useFragment.Result<Array<TData>>;
+/**
+ * `useFragment` represents a lightweight live binding into the Apollo Client Cache and enables Apollo Client to broadcast very specific fragment results to individual components. This hook returns an always-up-to-date view of whatever data the cache currently contains for a given fragment. `useFragment` never triggers network requests of its own.
+ *
+ * Note that the `useQuery` hook remains the primary hook responsible for querying and populating data in the cache ([see the API reference](./hooks#usequery)). As a result, the component reading the fragment data via `useFragment` is still subscribed to all changes in the query data, but receives updates only when that fragment's specific data change.
+ *
+ * To view a `useFragment` example, see the [Fragments](https://www.apollographql.com/docs/react/data/fragments#usefragment) page.
+ */
+export declare function useFragment<
+	TData = unknown,
+	TVariables extends OperationVariables = OperationVariables,
+>(
+	options: useFragment.Options<TData, TVariables> & {
+		from: Array<null>;
+	},
+): useFragment.Result<Array<null>>;
+/**
+ * `useFragment` represents a lightweight live binding into the Apollo Client Cache and enables Apollo Client to broadcast very specific fragment results to individual components. This hook returns an always-up-to-date view of whatever data the cache currently contains for a given fragment. `useFragment` never triggers network requests of its own.
+ *
+ * Note that the `useQuery` hook remains the primary hook responsible for querying and populating data in the cache ([see the API reference](./hooks#usequery)). As a result, the component reading the fragment data via `useFragment` is still subscribed to all changes in the query data, but receives updates only when that fragment's specific data change.
+ *
+ * To view a `useFragment` example, see the [Fragments](https://www.apollographql.com/docs/react/data/fragments#usefragment) page.
+ */
+export declare function useFragment<
+	TData = unknown,
+	TVariables extends OperationVariables = OperationVariables,
+>(
+	options: useFragment.Options<TData, TVariables> & {
+		from: Array<useFragment.FromOptionValue<TData> | null>;
+	},
+): useFragment.Result<Array<TData | null>>;
+/**
+ * `useFragment` represents a lightweight live binding into the Apollo Client Cache and enables Apollo Client to broadcast very specific fragment results to individual components. This hook returns an always-up-to-date view of whatever data the cache currently contains for a given fragment. `useFragment` never triggers network requests of its own.
+ *
+ * Note that the `useQuery` hook remains the primary hook responsible for querying and populating data in the cache ([see the API reference](./hooks#usequery)). As a result, the component reading the fragment data via `useFragment` is still subscribed to all changes in the query data, but receives updates only when that fragment's specific data change.
+ *
+ * To view a `useFragment` example, see the [Fragments](https://www.apollographql.com/docs/react/data/fragments#usefragment) page.
+ */
+export declare function useFragment<
+	TData = unknown,
+	TVariables extends OperationVariables = OperationVariables,
+>(options: useFragment.Options<TData, TVariables>): useFragment.Result<TData>;

package/src/react/hooks/useFragment.js

@@ -0,0 +1,75 @@
+import * as React from 'octane';
+import { useDeepMemo, wrapHook } from './internal/index.js';
+import { subSite } from './internal/site.js';
+import { useApolloClient } from './useApolloClient.js';
+import { useSyncExternalStore } from './useSyncExternalStore.js';
+export function useFragment(options, site) {
+	'use no memo';
+	return wrapHook('useFragment', useFragment_, useApolloClient(options.client))(options, site);
+}
+function useFragment_(options, site) {
+	const client = useApolloClient(options.client);
+	const { from, ...rest } = options;
+	const { cache } = client;
+	// We calculate the cache id seperately because we don't want changes to non
+	// key fields in the `from` property to recreate the observable. If the cache
+	// identifier stays the same between renders, we want to reuse the existing
+	// subscription.
+	const ids = useDeepMemo(
+		() => {
+			const fromArray = Array.isArray(from) ? from : [from];
+			const ids = fromArray.map((value) =>
+				typeof value === 'string' ? value : value === null ? null : cache.identify(value),
+			);
+			return Array.isArray(from) ? ids : ids[0];
+		},
+		[cache, from],
+		subSite(site, 'ids'),
+	);
+	const stableOptions = useDeepMemo(
+		() => ({ ...rest, from: ids }),
+		[rest, ids],
+		subSite(site, 'options'),
+	);
+	const observable = React.useMemo(
+		() => client.watchFragment(stableOptions),
+		[client, stableOptions],
+	);
+	// Unfortunately we forgot to update the use case of `from: null` on
+	// useFragment in 4.0 to match `useSuspenseFragment`. As such, we need to
+	// fallback to data: {} with complete: false when `from` is `null` to maintain
+	// backwards compatibility. We should plan to change this in v5.
+	const getSnapshot = React.useCallback(
+		() => (from === null ? nullResult : observable.getCurrentResult()),
+		[from, observable],
+	);
+	return useSyncExternalStore(
+		React.useCallback(
+			(update) => {
+				let lastTimeout = 0;
+				const subscription = observable.subscribe({
+					next: () => {
+						// If we get another update before we've re-rendered, bail out of
+						// the update and try again. This ensures that the relative timing
+						// between useQuery and useFragment stays roughly the same as
+						// fixed in https://github.com/apollographql/apollo-client/pull/11083
+						clearTimeout(lastTimeout);
+						lastTimeout = setTimeout(update);
+					},
+				});
+				return () => {
+					subscription.unsubscribe();
+					clearTimeout(lastTimeout);
+				};
+			},
+			[observable],
+		),
+		getSnapshot,
+		getSnapshot,
+	);
+}
+const nullResult = Object.freeze({
+	data: {},
+	dataState: 'partial',
+	complete: false,
+});