@apollo/client 4.1.6 → 4.1.8

package/react/hooks-compiled/useSubscription.d.ts

@@ -151,7 +151,7 @@ export declare namespace useSubscription {
         *   const [accumulatedData, setAccumulatedData] = useState([]);
         *   const { data, error, loading } = useSubscription(query, {
         *     onData({ data }) {
-        *       setAccumulatedData((prev) => [...prev, data]);
+        *       setAccumulatedData((prev) => [...prev, data.data]);
         *     },
         *   });
         * 
@@ -243,7 +243,7 @@ export declare namespace useSubscription {
  *   const [accumulatedData, setAccumulatedData] = useState([]);
  *   const { data, error, loading } = useSubscription(query, {
  *     onData({ data }) {
- *       setAccumulatedData((prev) => [...prev, data]);
+ *       setAccumulatedData((prev) => [...prev, data.data]);
  *     },
  *   });
  *

package/react/hooks-compiled/useSubscription.js

@@ -65,7 +65,7 @@ import { useSyncExternalStore } from "./useSyncExternalStore.js";
  *   const [accumulatedData, setAccumulatedData] = useState([]);
  *   const { data, error, loading } = useSubscription(query, {
  *     onData({ data }) {
- *       setAccumulatedData((prev) => [...prev, data]);
+ *       setAccumulatedData((prev) => [...prev, data.data]);
  *     },
  *   });
  *

package/react/hooks-compiled/useSubscription.js.map

@@ -1 +1 @@
-{"version":3,"file":"useSubscription.js","sources":["../../../src/react/hooks/useSubscription.ts"],"sourcesContent":["import type { TypedDocumentNode } from \"@graphql-typed-document-node/core\";\nimport { equal } from \"@wry/equality\";\nimport type { DocumentNode } from \"graphql\";\nimport * as React from \"react\";\n\nimport type {\n  ApolloClient,\n  DefaultContext,\n  ErrorLike,\n  ErrorPolicy,\n  FetchPolicy,\n  OperationVariables,\n} from \"@apollo/client\";\nimport type { MaybeMasked } from \"@apollo/client/masking\";\nimport type { DocumentationTypes as UtilityDocumentationTypes } from \"@apollo/client/utilities/internal\";\nimport type {\n  NoInfer,\n  VariablesOption,\n} from \"@apollo/client/utilities/internal\";\nimport { invariant } from \"@apollo/client/utilities/invariant\";\n\nimport { useDeepMemo } from \"./internal/useDeepMemo.js\";\nimport { useIsomorphicLayoutEffect } from \"./internal/useIsomorphicLayoutEffect.js\";\nimport { useApolloClient } from \"./useApolloClient.js\";\nimport { useSyncExternalStore } from \"./useSyncExternalStore.js\";\n\nexport declare namespace useSubscription {\n  import _self = useSubscription;\n  export namespace Base {\n    export interface Options<\n      TData = unknown,\n      TVariables extends OperationVariables = OperationVariables,\n    > {\n      /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#fetchPolicy:member} */\n      fetchPolicy?: FetchPolicy;\n\n      /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#errorPolicy:member} */\n      errorPolicy?: ErrorPolicy;\n\n      /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#shouldResubscribe:member} */\n      shouldResubscribe?:\n        | boolean\n        | ((options: Options<TData, TVariables>) => boolean);\n\n      /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#client:member} */\n      client?: ApolloClient;\n\n      /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#skip:member} */\n      skip?: boolean;\n\n      /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#context:member} */\n      context?: DefaultContext;\n\n      /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#extensions:member} */\n      extensions?: Record<string, any>;\n\n      /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#onComplete:member} */\n      onComplete?: () => void;\n\n      /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#onData:member} */\n      onData?: (options: OnDataOptions<TData>) => any;\n\n      /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#onError:member} */\n      onError?: (error: ErrorLike) => void;\n\n      /**\n       * {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#ignoreResults:member}\n       * @defaultValue `false`\n       */\n      ignoreResults?: boolean;\n    }\n  }\n\n  export type Options<\n    TData = unknown,\n    TVariables extends OperationVariables = OperationVariables,\n  > = Base.Options<TData, TVariables> & VariablesOption<TVariables>;\n\n  export namespace DocumentationTypes {\n    namespace useSubscription {\n      export interface Options<\n        TData = unknown,\n        TVariables extends OperationVariables = OperationVariables,\n      > extends Base.Options<TData, TVariables>,\n          UtilityDocumentationTypes.VariableOptions<TVariables> {}\n    }\n  }\n\n  export interface Result<TData = unknown> {\n    /** {@inheritDoc @apollo/client!SubscriptionResultDocumentation#loading:member} */\n    loading: boolean;\n\n    /** {@inheritDoc @apollo/client!SubscriptionResultDocumentation#data:member} */\n    data?: MaybeMasked<TData>;\n\n    /** {@inheritDoc @apollo/client!SubscriptionResultDocumentation#error:member} */\n    error?: ErrorLike;\n\n    /**\n     * A function that when called will disconnect and reconnect the connection\n     * to the subscription. If the subscription is deduplicated, this will\n     * restart the connection for all deduplicated subscriptions.\n     */\n    restart: () => void;\n  }\n\n  export namespace DocumentationTypes {\n    namespace useSubscription {\n      export interface Result<TData = unknown> extends _self.Result<TData> {}\n    }\n  }\n\n  export namespace DocumentationTypes {\n    /** {@inheritDoc @apollo/client/react!useSubscription:function(1)} */\n    export function useSubscription<\n      TData = unknown,\n      TVariables extends OperationVariables = OperationVariables,\n    >(\n      options?: useSubscription.Options<TData, TVariables>\n    ): useSubscription.Result<TData>;\n  }\n\n  export type OnDataResult<TData = unknown> = Omit<Result<TData>, \"restart\">;\n\n  export interface OnDataOptions<TData = unknown> {\n    client: ApolloClient;\n    data: OnDataResult<TData>;\n  }\n\n  export interface OnSubscriptionDataOptions<TData = unknown> {\n    client: ApolloClient;\n    subscriptionData: OnDataResult<TData>;\n  }\n}\n\n/**\n * > Refer to the [Subscriptions](https://www.apollographql.com/docs/react/data/subscriptions/) section for a more in-depth overview of `useSubscription`.\n *\n * @example\n *\n * ```jsx\n * const COMMENTS_SUBSCRIPTION = gql`\n *   subscription OnCommentAdded($repoFullName: String!) {\n *     commentAdded(repoFullName: $repoFullName) {\n *       id\n *       content\n *     }\n *   }\n * `;\n *\n * function DontReadTheComments({ repoFullName }) {\n *   const {\n *     data: { commentAdded },\n *     loading,\n *   } = useSubscription(COMMENTS_SUBSCRIPTION, { variables: { repoFullName } });\n *   return <h4>New comment: {!loading && commentAdded.content}</h4>;\n * }\n * ```\n *\n * @remarks\n *\n * #### Consider using `onData` instead of `useEffect`\n *\n * If you want to react to incoming data, please use the `onData` option instead of `useEffect`.\n * State updates you make inside a `useEffect` hook might cause additional rerenders, and `useEffect` is mostly meant for side effects of rendering, not as an event handler.\n * State updates made in an event handler like `onData` might - depending on the React version - be batched and cause only a single rerender.\n *\n * Consider the following component:\n *\n * ```jsx\n * export function Subscriptions() {\n *   const { data, error, loading } = useSubscription(query);\n *   const [accumulatedData, setAccumulatedData] = useState([]);\n *\n *   useEffect(() => {\n *     setAccumulatedData((prev) => [...prev, data]);\n *   }, [data]);\n *\n *   return (\n *     <>\n *       {loading && <p>Loading...</p>}\n *       {JSON.stringify(accumulatedData, undefined, 2)}\n *     </>\n *   );\n * }\n * ```\n *\n * Instead of using `useEffect` here, we can re-write this component to use the `onData` callback function accepted in `useSubscription`'s `options` object:\n *\n * ```jsx\n * export function Subscriptions() {\n *   const [accumulatedData, setAccumulatedData] = useState([]);\n *   const { data, error, loading } = useSubscription(query, {\n *     onData({ data }) {\n *       setAccumulatedData((prev) => [...prev, data]);\n *     },\n *   });\n *\n *   return (\n *     <>\n *       {loading && <p>Loading...</p>}\n *       {JSON.stringify(accumulatedData, undefined, 2)}\n *     </>\n *   );\n * }\n * ```\n *\n * > ⚠️ **Note:** The `useSubscription` option `onData` is available in Apollo Client >= 3.7. In previous versions, the equivalent option is named `onSubscriptionData`.\n *\n * Now, the first message will be added to the `accumulatedData` array since `onData` is called _before_ the component re-renders. React 18 automatic batching is still in effect and results in a single re-render, but with `onData` we can guarantee each message received after the component mounts is added to `accumulatedData`.\n *\n * @param subscription - A GraphQL subscription document parsed into an AST by `gql`.\n * @param options - Options to control how the subscription is executed.\n * @returns Query result object\n */\nexport function useSubscription<\n  TData = unknown,\n  TVariables extends OperationVariables = OperationVariables,\n>(\n  subscription: DocumentNode | TypedDocumentNode<TData, TVariables>,\n  ...[options = {} as useSubscription.Options<TData, TVariables>]: {} extends (\n    TVariables\n  ) ?\n    [options?: useSubscription.Options<NoInfer<TData>, NoInfer<TVariables>>]\n  : [options: useSubscription.Options<NoInfer<TData>, NoInfer<TVariables>>]\n): useSubscription.Result<TData> {\n  const client = useApolloClient(options.client);\n\n  const {\n    skip,\n    fetchPolicy,\n    errorPolicy,\n    shouldResubscribe,\n    context,\n    extensions,\n    ignoreResults,\n  } = options;\n  const variables = useDeepMemo(() => options.variables, [options.variables]);\n\n  const recreate = () =>\n    createSubscription(\n      client,\n      subscription,\n      variables,\n      fetchPolicy,\n      errorPolicy,\n      context,\n      extensions\n    );\n\n  let [observable, setObservable] = React.useState(\n    options.skip ? null : recreate\n  );\n\n  const recreateRef = React.useRef(recreate);\n  useIsomorphicLayoutEffect(() => {\n    recreateRef.current = recreate;\n  });\n\n  if (skip) {\n    if (observable) {\n      setObservable((observable = null));\n    }\n  } else if (\n    !observable ||\n    ((client !== observable.__.client ||\n      subscription !== observable.__.query ||\n      fetchPolicy !== observable.__.fetchPolicy ||\n      errorPolicy !== observable.__.errorPolicy ||\n      !equal(variables, observable.__.variables)) &&\n      (typeof shouldResubscribe === \"function\" ?\n        !!shouldResubscribe(options!)\n      : shouldResubscribe) !== false)\n  ) {\n    setObservable((observable = recreate()));\n  }\n\n  const optionsRef = React.useRef(options);\n  React.useEffect(() => {\n    optionsRef.current = options;\n  });\n\n  const fallbackLoading = !skip && !ignoreResults;\n  const fallbackResult = React.useMemo(\n    () => ({\n      loading: fallbackLoading,\n      error: void 0,\n      data: void 0,\n    }),\n    [fallbackLoading]\n  );\n\n  const ignoreResultsRef = React.useRef(ignoreResults);\n  useIsomorphicLayoutEffect(() => {\n    // We cannot reference `ignoreResults` directly in the effect below\n    // it would add a dependency to the `useEffect` deps array, which means the\n    // subscription would be recreated if `ignoreResults` changes\n    // As a result, on resubscription, the last result would be re-delivered,\n    // rendering the component one additional time, and re-triggering `onData`.\n    // The same applies to `fetchPolicy`, which results in a new `observable`\n    // being created. We cannot really avoid it in that case, but we can at least\n    // avoid it for `ignoreResults`.\n    ignoreResultsRef.current = ignoreResults;\n  });\n\n  const ret = useSyncExternalStore(\n    React.useCallback(\n      (update) => {\n        if (!observable) {\n          return () => {};\n        }\n\n        let subscriptionStopped = false;\n        const client = observable.__.client;\n        const subscription = observable.subscribe({\n          next(value) {\n            if (subscriptionStopped) {\n              return;\n            }\n\n            const result = {\n              loading: false,\n              data: value.data,\n              error: value.error,\n            };\n\n            observable.__.setResult(result);\n            if (!ignoreResultsRef.current) update();\n\n            if (result.error) {\n              optionsRef.current.onError?.(result.error);\n            } else if (optionsRef.current.onData) {\n              optionsRef.current.onData({\n                client,\n                data: result,\n              });\n            }\n          },\n          complete() {\n            observable.__.completed = true;\n            if (!subscriptionStopped && optionsRef.current.onComplete) {\n              optionsRef.current.onComplete();\n            }\n          },\n        });\n\n        return () => {\n          // immediately stop receiving subscription values, but do not unsubscribe\n          // until after a short delay in case another useSubscription hook is\n          // reusing the same underlying observable and is about to subscribe\n          subscriptionStopped = true;\n\n          setTimeout(() => subscription.unsubscribe());\n        };\n      },\n      [observable]\n    ),\n    () =>\n      observable && !skip && !ignoreResults ?\n        observable.__.result\n      : fallbackResult,\n    () => fallbackResult\n  );\n\n  const restart = React.useCallback(() => {\n    invariant(\n      !optionsRef.current.skip,\n      \"A subscription that is skipped cannot be restarted.\"\n    );\n    if (observable?.__.completed) {\n      setObservable(recreateRef.current());\n    } else {\n      observable?.restart();\n    }\n  }, [observable, setObservable, optionsRef, recreateRef]);\n\n  return React.useMemo(() => ({ ...ret, restart }), [ret, restart]);\n}\n\ntype SubscriptionResult<TData> = Omit<useSubscription.Result<TData>, \"restart\">;\n\nfunction createSubscription<\n  TData = unknown,\n  TVariables extends OperationVariables = OperationVariables,\n>(\n  client: ApolloClient,\n  query: TypedDocumentNode<TData, TVariables>,\n  variables: TVariables | undefined,\n  fetchPolicy: FetchPolicy | undefined,\n  errorPolicy: ErrorPolicy | undefined,\n  context: DefaultContext | undefined,\n  extensions: Record<string, any> | undefined\n) {\n  const options = {\n    query,\n    variables,\n    fetchPolicy,\n    errorPolicy,\n    context,\n    extensions,\n  } as ApolloClient.SubscribeOptions<TData, TVariables>;\n  const __ = {\n    ...options,\n    client,\n    completed: false,\n    result: {\n      loading: true,\n      data: void 0,\n      error: void 0,\n    } as SubscriptionResult<TData>,\n    setResult(result: SubscriptionResult<TData>) {\n      __.result = result;\n    },\n  };\n\n  return Object.assign(client.subscribe(options), {\n    /**\n     * A tracking object to store details about the observable and the latest result of the subscription.\n     */\n    __,\n  });\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"useSubscription.js","sources":["../../../src/react/hooks/useSubscription.ts"],"sourcesContent":["import type { TypedDocumentNode } from \"@graphql-typed-document-node/core\";\nimport { equal } from \"@wry/equality\";\nimport type { DocumentNode } from \"graphql\";\nimport * as React from \"react\";\n\nimport type {\n  ApolloClient,\n  DefaultContext,\n  ErrorLike,\n  ErrorPolicy,\n  FetchPolicy,\n  OperationVariables,\n} from \"@apollo/client\";\nimport type { MaybeMasked } from \"@apollo/client/masking\";\nimport type { DocumentationTypes as UtilityDocumentationTypes } from \"@apollo/client/utilities/internal\";\nimport type {\n  NoInfer,\n  VariablesOption,\n} from \"@apollo/client/utilities/internal\";\nimport { invariant } from \"@apollo/client/utilities/invariant\";\n\nimport { useDeepMemo } from \"./internal/useDeepMemo.js\";\nimport { useIsomorphicLayoutEffect } from \"./internal/useIsomorphicLayoutEffect.js\";\nimport { useApolloClient } from \"./useApolloClient.js\";\nimport { useSyncExternalStore } from \"./useSyncExternalStore.js\";\n\nexport declare namespace useSubscription {\n  import _self = useSubscription;\n  export namespace Base {\n    export interface Options<\n      TData = unknown,\n      TVariables extends OperationVariables = OperationVariables,\n    > {\n      /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#fetchPolicy:member} */\n      fetchPolicy?: FetchPolicy;\n\n      /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#errorPolicy:member} */\n      errorPolicy?: ErrorPolicy;\n\n      /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#shouldResubscribe:member} */\n      shouldResubscribe?:\n        | boolean\n        | ((options: Options<TData, TVariables>) => boolean);\n\n      /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#client:member} */\n      client?: ApolloClient;\n\n      /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#skip:member} */\n      skip?: boolean;\n\n      /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#context:member} */\n      context?: DefaultContext;\n\n      /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#extensions:member} */\n      extensions?: Record<string, any>;\n\n      /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#onComplete:member} */\n      onComplete?: () => void;\n\n      /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#onData:member} */\n      onData?: (options: OnDataOptions<TData>) => any;\n\n      /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#onError:member} */\n      onError?: (error: ErrorLike) => void;\n\n      /**\n       * {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#ignoreResults:member}\n       * @defaultValue `false`\n       */\n      ignoreResults?: boolean;\n    }\n  }\n\n  export type Options<\n    TData = unknown,\n    TVariables extends OperationVariables = OperationVariables,\n  > = Base.Options<TData, TVariables> & VariablesOption<TVariables>;\n\n  export namespace DocumentationTypes {\n    namespace useSubscription {\n      export interface Options<\n        TData = unknown,\n        TVariables extends OperationVariables = OperationVariables,\n      > extends Base.Options<TData, TVariables>,\n          UtilityDocumentationTypes.VariableOptions<TVariables> {}\n    }\n  }\n\n  export interface Result<TData = unknown> {\n    /** {@inheritDoc @apollo/client!SubscriptionResultDocumentation#loading:member} */\n    loading: boolean;\n\n    /** {@inheritDoc @apollo/client!SubscriptionResultDocumentation#data:member} */\n    data?: MaybeMasked<TData>;\n\n    /** {@inheritDoc @apollo/client!SubscriptionResultDocumentation#error:member} */\n    error?: ErrorLike;\n\n    /**\n     * A function that when called will disconnect and reconnect the connection\n     * to the subscription. If the subscription is deduplicated, this will\n     * restart the connection for all deduplicated subscriptions.\n     */\n    restart: () => void;\n  }\n\n  export namespace DocumentationTypes {\n    namespace useSubscription {\n      export interface Result<TData = unknown> extends _self.Result<TData> {}\n    }\n  }\n\n  export namespace DocumentationTypes {\n    /** {@inheritDoc @apollo/client/react!useSubscription:function(1)} */\n    export function useSubscription<\n      TData = unknown,\n      TVariables extends OperationVariables = OperationVariables,\n    >(\n      options?: useSubscription.Options<TData, TVariables>\n    ): useSubscription.Result<TData>;\n  }\n\n  export type OnDataResult<TData = unknown> = Omit<Result<TData>, \"restart\">;\n\n  export interface OnDataOptions<TData = unknown> {\n    client: ApolloClient;\n    data: OnDataResult<TData>;\n  }\n\n  export interface OnSubscriptionDataOptions<TData = unknown> {\n    client: ApolloClient;\n    subscriptionData: OnDataResult<TData>;\n  }\n}\n\n/**\n * > Refer to the [Subscriptions](https://www.apollographql.com/docs/react/data/subscriptions/) section for a more in-depth overview of `useSubscription`.\n *\n * @example\n *\n * ```jsx\n * const COMMENTS_SUBSCRIPTION = gql`\n *   subscription OnCommentAdded($repoFullName: String!) {\n *     commentAdded(repoFullName: $repoFullName) {\n *       id\n *       content\n *     }\n *   }\n * `;\n *\n * function DontReadTheComments({ repoFullName }) {\n *   const {\n *     data: { commentAdded },\n *     loading,\n *   } = useSubscription(COMMENTS_SUBSCRIPTION, { variables: { repoFullName } });\n *   return <h4>New comment: {!loading && commentAdded.content}</h4>;\n * }\n * ```\n *\n * @remarks\n *\n * #### Consider using `onData` instead of `useEffect`\n *\n * If you want to react to incoming data, please use the `onData` option instead of `useEffect`.\n * State updates you make inside a `useEffect` hook might cause additional rerenders, and `useEffect` is mostly meant for side effects of rendering, not as an event handler.\n * State updates made in an event handler like `onData` might - depending on the React version - be batched and cause only a single rerender.\n *\n * Consider the following component:\n *\n * ```jsx\n * export function Subscriptions() {\n *   const { data, error, loading } = useSubscription(query);\n *   const [accumulatedData, setAccumulatedData] = useState([]);\n *\n *   useEffect(() => {\n *     setAccumulatedData((prev) => [...prev, data]);\n *   }, [data]);\n *\n *   return (\n *     <>\n *       {loading && <p>Loading...</p>}\n *       {JSON.stringify(accumulatedData, undefined, 2)}\n *     </>\n *   );\n * }\n * ```\n *\n * Instead of using `useEffect` here, we can re-write this component to use the `onData` callback function accepted in `useSubscription`'s `options` object:\n *\n * ```jsx\n * export function Subscriptions() {\n *   const [accumulatedData, setAccumulatedData] = useState([]);\n *   const { data, error, loading } = useSubscription(query, {\n *     onData({ data }) {\n *       setAccumulatedData((prev) => [...prev, data.data]);\n *     },\n *   });\n *\n *   return (\n *     <>\n *       {loading && <p>Loading...</p>}\n *       {JSON.stringify(accumulatedData, undefined, 2)}\n *     </>\n *   );\n * }\n * ```\n *\n * > ⚠️ **Note:** The `useSubscription` option `onData` is available in Apollo Client >= 3.7. In previous versions, the equivalent option is named `onSubscriptionData`.\n *\n * Now, the first message will be added to the `accumulatedData` array since `onData` is called _before_ the component re-renders. React 18 automatic batching is still in effect and results in a single re-render, but with `onData` we can guarantee each message received after the component mounts is added to `accumulatedData`.\n *\n * @param subscription - A GraphQL subscription document parsed into an AST by `gql`.\n * @param options - Options to control how the subscription is executed.\n * @returns Query result object\n */\nexport function useSubscription<\n  TData = unknown,\n  TVariables extends OperationVariables = OperationVariables,\n>(\n  subscription: DocumentNode | TypedDocumentNode<TData, TVariables>,\n  ...[options = {} as useSubscription.Options<TData, TVariables>]: {} extends (\n    TVariables\n  ) ?\n    [options?: useSubscription.Options<NoInfer<TData>, NoInfer<TVariables>>]\n  : [options: useSubscription.Options<NoInfer<TData>, NoInfer<TVariables>>]\n): useSubscription.Result<TData> {\n  const client = useApolloClient(options.client);\n\n  const {\n    skip,\n    fetchPolicy,\n    errorPolicy,\n    shouldResubscribe,\n    context,\n    extensions,\n    ignoreResults,\n  } = options;\n  const variables = useDeepMemo(() => options.variables, [options.variables]);\n\n  const recreate = () =>\n    createSubscription(\n      client,\n      subscription,\n      variables,\n      fetchPolicy,\n      errorPolicy,\n      context,\n      extensions\n    );\n\n  let [observable, setObservable] = React.useState(\n    options.skip ? null : recreate\n  );\n\n  const recreateRef = React.useRef(recreate);\n  useIsomorphicLayoutEffect(() => {\n    recreateRef.current = recreate;\n  });\n\n  if (skip) {\n    if (observable) {\n      setObservable((observable = null));\n    }\n  } else if (\n    !observable ||\n    ((client !== observable.__.client ||\n      subscription !== observable.__.query ||\n      fetchPolicy !== observable.__.fetchPolicy ||\n      errorPolicy !== observable.__.errorPolicy ||\n      !equal(variables, observable.__.variables)) &&\n      (typeof shouldResubscribe === \"function\" ?\n        !!shouldResubscribe(options!)\n      : shouldResubscribe) !== false)\n  ) {\n    setObservable((observable = recreate()));\n  }\n\n  const optionsRef = React.useRef(options);\n  React.useEffect(() => {\n    optionsRef.current = options;\n  });\n\n  const fallbackLoading = !skip && !ignoreResults;\n  const fallbackResult = React.useMemo(\n    () => ({\n      loading: fallbackLoading,\n      error: void 0,\n      data: void 0,\n    }),\n    [fallbackLoading]\n  );\n\n  const ignoreResultsRef = React.useRef(ignoreResults);\n  useIsomorphicLayoutEffect(() => {\n    // We cannot reference `ignoreResults` directly in the effect below\n    // it would add a dependency to the `useEffect` deps array, which means the\n    // subscription would be recreated if `ignoreResults` changes\n    // As a result, on resubscription, the last result would be re-delivered,\n    // rendering the component one additional time, and re-triggering `onData`.\n    // The same applies to `fetchPolicy`, which results in a new `observable`\n    // being created. We cannot really avoid it in that case, but we can at least\n    // avoid it for `ignoreResults`.\n    ignoreResultsRef.current = ignoreResults;\n  });\n\n  const ret = useSyncExternalStore(\n    React.useCallback(\n      (update) => {\n        if (!observable) {\n          return () => {};\n        }\n\n        let subscriptionStopped = false;\n        const client = observable.__.client;\n        const subscription = observable.subscribe({\n          next(value) {\n            if (subscriptionStopped) {\n              return;\n            }\n\n            const result = {\n              loading: false,\n              data: value.data,\n              error: value.error,\n            };\n\n            observable.__.setResult(result);\n            if (!ignoreResultsRef.current) update();\n\n            if (result.error) {\n              optionsRef.current.onError?.(result.error);\n            } else if (optionsRef.current.onData) {\n              optionsRef.current.onData({\n                client,\n                data: result,\n              });\n            }\n          },\n          complete() {\n            observable.__.completed = true;\n            if (!subscriptionStopped && optionsRef.current.onComplete) {\n              optionsRef.current.onComplete();\n            }\n          },\n        });\n\n        return () => {\n          // immediately stop receiving subscription values, but do not unsubscribe\n          // until after a short delay in case another useSubscription hook is\n          // reusing the same underlying observable and is about to subscribe\n          subscriptionStopped = true;\n\n          setTimeout(() => subscription.unsubscribe());\n        };\n      },\n      [observable]\n    ),\n    () =>\n      observable && !skip && !ignoreResults ?\n        observable.__.result\n      : fallbackResult,\n    () => fallbackResult\n  );\n\n  const restart = React.useCallback(() => {\n    invariant(\n      !optionsRef.current.skip,\n      \"A subscription that is skipped cannot be restarted.\"\n    );\n    if (observable?.__.completed) {\n      setObservable(recreateRef.current());\n    } else {\n      observable?.restart();\n    }\n  }, [observable, setObservable, optionsRef, recreateRef]);\n\n  return React.useMemo(() => ({ ...ret, restart }), [ret, restart]);\n}\n\ntype SubscriptionResult<TData> = Omit<useSubscription.Result<TData>, \"restart\">;\n\nfunction createSubscription<\n  TData = unknown,\n  TVariables extends OperationVariables = OperationVariables,\n>(\n  client: ApolloClient,\n  query: TypedDocumentNode<TData, TVariables>,\n  variables: TVariables | undefined,\n  fetchPolicy: FetchPolicy | undefined,\n  errorPolicy: ErrorPolicy | undefined,\n  context: DefaultContext | undefined,\n  extensions: Record<string, any> | undefined\n) {\n  const options = {\n    query,\n    variables,\n    fetchPolicy,\n    errorPolicy,\n    context,\n    extensions,\n  } as ApolloClient.SubscribeOptions<TData, TVariables>;\n  const __ = {\n    ...options,\n    client,\n    completed: false,\n    result: {\n      loading: true,\n      data: void 0,\n      error: void 0,\n    } as SubscriptionResult<TData>,\n    setResult(result: SubscriptionResult<TData>) {\n      __.result = result;\n    },\n  };\n\n  return Object.assign(client.subscribe(options), {\n    /**\n     * A tracking object to store details about the observable and the latest result of the subscription.\n     */\n    __,\n  });\n}\n"],"names":[],"mappings":"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"}

package/skills/apollo-client/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: apollo-client
+description: >
+  Guide for building React applications with Apollo Client 4.x. Use this skill when:
+  (1) setting up Apollo Client in a React project,
+  (2) writing GraphQL queries or mutations with hooks,
+  (3) configuring caching or cache policies,
+  (4) managing local state with reactive variables,
+  (5) troubleshooting Apollo Client errors or performance issues.
+license: MIT
+compatibility: React 18+, React 19 (Suspense/RSC). Works with Next.js, Vite, CRA, and other React frameworks.
+metadata:
+  author: apollographql
+  version: "1.0.0"
+allowed-tools: Bash(npm:*) Bash(npx:*) Bash(node:*) Read Write Edit Glob Grep
+---
+
+# Apollo Client 4.x Guide
+
+Apollo Client is a comprehensive state management library for JavaScript that enables you to manage both local and remote data with GraphQL. Version 4.x brings improved caching, better TypeScript support, and React 19 compatibility.
+
+## Integration Guides
+
+Choose the integration guide that matches your application setup:
+
+- **[Client-Side Apps](references/integration-client.md)** - For client-side React applications without SSR (Vite, Create React App, etc.)
+- **[Next.js App Router](references/integration-nextjs.md)** - For Next.js applications using the App Router with React Server Components
+- **[React Router Framework Mode](references/integration-react-router.md)** - For React Router 7 applications with streaming SSR
+- **[TanStack Start](references/integration-tanstack-start.md)** - For TanStack Start applications with modern routing
+
+Each guide includes installation steps, configuration, and framework-specific patterns optimized for that environment.
+
+## Quick Reference
+
+### Basic Query
+
+```tsx
+import { gql } from "@apollo/client";
+import { useQuery } from "@apollo/client/react";
+
+const GET_USER = gql`
+  query GetUser($id: ID!) {
+    user(id: $id) {
+      id
+      name
+    }
+  }
+`;
+
+function UserProfile({ userId }: { userId: string }) {
+  const { loading, error, data, dataState } = useQuery(GET_USER, {
+    variables: { id: userId },
+  });
+
+  if (loading) return <p>Loading...</p>;
+  if (error) return <p>Error: {error.message}</p>;
+
+  // TypeScript note: for stricter type narrowing, you can also check `dataState === "complete"` before accessing data
+  return <div>{data?.user.name}</div>;
+}
+```
+
+### Basic Mutation
+
+```tsx
+import { gql } from "@apollo/client";
+import { useMutation } from "@apollo/client/react";
+
+const CREATE_USER = gql`
+  mutation CreateUser($input: CreateUserInput!) {
+    createUser(input: $input) {
+      id
+      name
+    }
+  }
+`;
+
+function CreateUserForm() {
+  const [createUser, { loading, error }] = useMutation(CREATE_USER);
+
+  const handleSubmit = async (name: string) => {
+    await createUser({ variables: { input: { name } } });
+  };
+
+  return <button onClick={() => handleSubmit("John")}>Create User</button>;
+}
+```
+
+### Suspense Query
+
+```tsx
+import { Suspense } from "react";
+import { useSuspenseQuery } from "@apollo/client/react";
+
+function UserProfile({ userId }: { userId: string }) {
+  const { data } = useSuspenseQuery(GET_USER, {
+    variables: { id: userId },
+  });
+
+  return <div>{data.user.name}</div>;
+}
+
+function App() {
+  return (
+    <Suspense fallback={<p>Loading user...</p>}>
+      <UserProfile userId="1" />
+    </Suspense>
+  );
+}
+```
+
+## Reference Files
+
+Detailed documentation for specific topics:
+
+- [TypeScript Code Generation](references/typescript-codegen.md) - GraphQL Code Generator setup for type-safe operations
+- [Queries](references/queries.md) - useQuery, useLazyQuery, polling, refetching
+- [Suspense Hooks](references/suspense-hooks.md) - useSuspenseQuery, useBackgroundQuery, useReadQuery, useLoadableQuery
+- [Mutations](references/mutations.md) - useMutation, optimistic UI, cache updates
+- [Fragments](references/fragments.md) - Fragment colocation, useFragment, useSuspenseFragment, data masking
+- [Caching](references/caching.md) - InMemoryCache, typePolicies, cache manipulation
+- [State Management](references/state-management.md) - Reactive variables, local state
+- [Error Handling](references/error-handling.md) - Error policies, error links, retries
+- [Troubleshooting](references/troubleshooting.md) - Common issues and solutions
+
+## Key Rules
+
+### Query Best Practices
+
+- **Each page should generally only have one query, composed from colocated fragments.** Use `useFragment` or `useSuspenseFragment` in all non-page-components. Use `@defer` to allow slow fields below the fold to stream in later and avoid blocking the page load.
+- **Fragments are for colocation, not reuse.** Each fragment should describe exactly the data needs of a specific component, not be shared across components for common fields. See [Fragments reference](references/fragments.md) for details on fragment colocation and data masking.
+- Always handle `loading` and `error` states in UI when using non-suspenseful hooks (`useQuery`, `useLazyQuery`). When using Suspense hooks (`useSuspenseQuery`, `useBackgroundQuery`), React handles this through `<Suspense>` boundaries and error boundaries.
+- Use `fetchPolicy` to control cache behavior per query
+- Use the TypeScript type server to look up documentation for functions and options (Apollo Client has extensive docblocks)
+
+### Mutation Best Practices
+
+- **If the schema permits, mutation return values should return everything necessary to update the cache.** Neither manual updates nor refetching should be necessary.
+- If the mutation response is insufficient, carefully weigh manual cache manipulation vs refetching. Manual updates risk missing server logic. Consider optimistic updates with a granular refetch if needed.
+- Handle errors gracefully in the UI
+- Use `refetchQueries` sparingly (prefer letting the cache update automatically)
+
+### Caching Best Practices
+
+- Configure `keyFields` for types without `id` field
+- Disable normalization by setting `keyFields: false` for types that don't include an identifier and are meant to group related fields under the parent
+- Use `typePolicies` for pagination and computed fields
+- Understand cache normalization to debug issues
+- **Enable [data masking](references/fragments.md#data-masking) for all new applications** - it prevents components from accessing fragment data they don't own, enforcing proper data boundaries and preventing over-rendering
+
+### Performance
+
+- Avoid over-fetching with proper field selection
+- Configure appropriate `fetchPolicy` per use case
+- Use `@defer` for incremental delivery of deferred query parts, and `@stream` for streaming list fields (`@stream` available in Apollo Client 4.1+)
+- **Prefer Suspense hooks (`useSuspenseQuery`, `useBackgroundQuery`) in modern applications** for better loading state handling and code simplicity
+
+## Ground Rules
+
+- ALWAYS use Apollo Client 4.x patterns (not v3 or earlier)
+- ALWAYS wrap your app with `ApolloProvider`
+- ALWAYS handle loading and error states when using non-suspenseful hooks
+- PREFER Suspense hooks (`useSuspenseQuery`, `useBackgroundQuery`) in modern applications for better DX
+- NEVER store Apollo Client in React state (use module-level or context)
+- PREFER `cache-first` for read-heavy data, `network-only` for real-time data
+- USE TypeScript for better type safety with GraphQL
+- IMPLEMENT proper cache updates instead of refetching entire queries
+- ADVISE the human steering you to look into Apollo DevTools when collaboratively debugging Apollo Client issues