| 1 | import type { DocumentNode } from "graphql";
|
| 2 | import type { TypedDocumentNode } from "@graphql-typed-document-node/core";
|
| 3 | import type { NoInfer, SubscriptionHookOptions } from "../types/types.js";
|
| 4 | import type { OperationVariables } from "../../core/index.js";
|
| 5 | import { ApolloError } from "../../core/index.js";
|
| 6 | /**
|
| 7 | * > Refer to the [Subscriptions](https://www.apollographql.com/docs/react/data/subscriptions/) section for a more in-depth overview of `useSubscription`.
|
| 8 | *
|
| 9 | * @example
|
| 10 | * ```jsx
|
| 11 | * const COMMENTS_SUBSCRIPTION = gql`
|
| 12 | * subscription OnCommentAdded($repoFullName: String!) {
|
| 13 | * commentAdded(repoFullName: $repoFullName) {
|
| 14 | * id
|
| 15 | * content
|
| 16 | * }
|
| 17 | * }
|
| 18 | * `;
|
| 19 | *
|
| 20 | * function DontReadTheComments({ repoFullName }) {
|
| 21 | * const {
|
| 22 | * data: { commentAdded },
|
| 23 | * loading,
|
| 24 | * } = useSubscription(COMMENTS_SUBSCRIPTION, { variables: { repoFullName } });
|
| 25 | * return <h4>New comment: {!loading && commentAdded.content}</h4>;
|
| 26 | * }
|
| 27 | * ```
|
| 28 | * @remarks
|
| 29 | * #### Consider using `onData` instead of `useEffect`
|
| 30 | *
|
| 31 | * If you want to react to incoming data, please use the `onData` option instead of `useEffect`.
|
| 32 | * 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.
|
| 33 | * State updates made in an event handler like `onData` might - depending on the React version - be batched and cause only a single rerender.
|
| 34 | *
|
| 35 | * Consider the following component:
|
| 36 | *
|
| 37 | * ```jsx
|
| 38 | * export function Subscriptions() {
|
| 39 | * const { data, error, loading } = useSubscription(query);
|
| 40 | * const [accumulatedData, setAccumulatedData] = useState([]);
|
| 41 | *
|
| 42 | * useEffect(() => {
|
| 43 | * setAccumulatedData((prev) => [...prev, data]);
|
| 44 | * }, [data]);
|
| 45 | *
|
| 46 | * return (
|
| 47 | * <>
|
| 48 | * {loading && <p>Loading...</p>}
|
| 49 | * {JSON.stringify(accumulatedData, undefined, 2)}
|
| 50 | * </>
|
| 51 | * );
|
| 52 | * }
|
| 53 | * ```
|
| 54 | *
|
| 55 | * Instead of using `useEffect` here, we can re-write this component to use the `onData` callback function accepted in `useSubscription`'s `options` object:
|
| 56 | *
|
| 57 | * ```jsx
|
| 58 | * export function Subscriptions() {
|
| 59 | * const [accumulatedData, setAccumulatedData] = useState([]);
|
| 60 | * const { data, error, loading } = useSubscription(
|
| 61 | * query,
|
| 62 | * {
|
| 63 | * onData({ data }) {
|
| 64 | * setAccumulatedData((prev) => [...prev, data])
|
| 65 | * }
|
| 66 | * }
|
| 67 | * );
|
| 68 | *
|
| 69 | * return (
|
| 70 | * <>
|
| 71 | * {loading && <p>Loading...</p>}
|
| 72 | * {JSON.stringify(accumulatedData, undefined, 2)}
|
| 73 | * </>
|
| 74 | * );
|
| 75 | * }
|
| 76 | * ```
|
| 77 | *
|
| 78 | * > ⚠️ **Note:** The `useSubscription` option `onData` is available in Apollo Client >= 3.7. In previous versions, the equivalent option is named `onSubscriptionData`.
|
| 79 | *
|
| 80 | * 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`.
|
| 81 | *
|
| 82 | * @since 3.0.0
|
| 83 | * @param subscription - A GraphQL subscription document parsed into an AST by `gql`.
|
| 84 | * @param options - Options to control how the subscription is executed.
|
| 85 | * @returns Query result object
|
| 86 | */
|
| 87 | export declare function useSubscription<TData = any, TVariables extends OperationVariables = OperationVariables>(subscription: DocumentNode | TypedDocumentNode<TData, TVariables>, options?: SubscriptionHookOptions<NoInfer<TData>, NoInfer<TVariables>>): {
|
| 88 | restart(): void;
|
| 89 | loading: boolean;
|
| 90 | data?: TData | undefined;
|
| 91 | error?: ApolloError;
|
| 92 | variables?: TVariables | undefined;
|
| 93 | };
|
| 94 | //# sourceMappingURL=useSubscription.d.ts.map |
| \ | No newline at end of file |