From 2a67ffc4e75745d4225fd26a95d0b3d39e448107 Mon Sep 17 00:00:00 2001 From: Lenz Weber-Tronic Date: Wed, 24 Jan 2024 18:25:54 +0100 Subject: [PATCH] move hook documentation (and others) into code, improve documentation components (#11381) * move some docs to comments * remove comments * fix missing space * add api_doc * tweak in file generation * build from docs branch * switch docs branch back to `main` * bump CI * Enum & PropertyDetails * WIP - see current state of `hooks.mdx` * completely remove `query-options` and `query-result` mdx * useMutation * handle subscription docs * better function signature * more hooks * fix up import * chores * formatting * suppress tsdoc warning * api explorer nitpicks * support for @deprecated * use prerendered markdown in comments to prevent client-side parsing * add propTypes * apply prettier * fixup * also display interface details for slightly complex types * heading styling, do not use h6 * since everywhere, styling, `link` defaults * add grouping, create documentation interface * `MutationOptionsDocumentation` interface * api reports * subscription options * api repots * prettier * fix some references * cleanup * fix up SubHeading links * don't add prefix to parameter properties * allow property deep linking * prettier * more cleanup * also add result documentation * more doccomment work * fixup * add missing import * fixup * remove `result` property (it's not a function) * Revert "remove `result` property (it's not a function)" This reverts commit 57c8526eb36d275f59811e5b27811f43ee1ba51c. * functions adjustments only show parameters section if there are parameters only show results if result is not `void` or user-specified * move heading out of example children * Update docs/shared/ApiDoc/EnumDetails.js Co-authored-by: Jerel Miller * remove obsolete props * address top padding for "smaller" headings * review feedback * fixup codeblock * move `SourceLink` out of `Heading` * throw an error if both `as` and `headingLevel` are specified in `Heading` * move jsx * always link headings * move headings out of table components * review comment * Update docs/shared/ApiDoc/Tuple.js Co-authored-by: Jerel Miller * nit :) * more updates * fix link --------- Co-authored-by: Jerel Miller --- .api-reports/api-report-cache.md | 2 +- .api-reports/api-report-core.md | 88 +-- .api-reports/api-report-react.md | 233 ++++--- .api-reports/api-report-react_components.md | 189 +++--- .api-reports/api-report-react_context.md | 152 +++-- .api-reports/api-report-react_hoc.md | 136 ++-- .api-reports/api-report-react_hooks.md | 234 ++++--- .api-reports/api-report-react_internal.md | 113 ++-- .api-reports/api-report-react_ssr.md | 153 +++-- .api-reports/api-report-testing.md | 113 ++-- .api-reports/api-report-testing_core.md | 113 ++-- .api-reports/api-report-utilities.md | 112 ++-- .api-reports/api-report.md | 203 +++--- api-extractor.json | 13 +- config/apiExtractor.ts | 8 +- config/entryPoints.js | 11 + config/inlineInheritDoc.ts | 35 +- docs/shared/ApiDoc/DocBlock.js | 57 +- docs/shared/ApiDoc/EnumDetails.js | 72 +++ docs/shared/ApiDoc/Function.js | 156 ++++- docs/shared/ApiDoc/Heading.js | 122 ++-- docs/shared/ApiDoc/InterfaceDetails.js | 24 +- docs/shared/ApiDoc/ParameterTable.js | 57 +- docs/shared/ApiDoc/PropertyDetails.js | 27 + docs/shared/ApiDoc/PropertySignatureTable.js | 152 ++--- docs/shared/ApiDoc/ResponsiveGrid.js | 8 +- docs/shared/ApiDoc/SourceLink.js | 24 + docs/shared/ApiDoc/Tuple.js | 68 ++ docs/shared/ApiDoc/getInterfaceReference.js | 8 + docs/shared/ApiDoc/index.js | 16 +- docs/shared/ApiDoc/mdToReact.js | 20 - docs/shared/ApiDoc/sortWithCustomOrder.js | 71 +++ docs/shared/apollo-provider.mdx | 1 - docs/shared/document-transform-options.mdx | 50 -- docs/shared/mutation-options.mdx | 298 --------- docs/shared/mutation-result.mdx | 145 ----- docs/shared/query-options.mdx | 304 --------- docs/shared/query-result.mdx | 275 -------- docs/shared/subscription-options.mdx | 14 - docs/shared/subscription-result.mdx | 5 - docs/shared/useSuspenseQuery-options.mdx | 217 ------- docs/source/api/core/ObservableQuery.mdx | 34 +- docs/source/api/react/components.mdx | 26 +- docs/source/api/react/hooks.mdx | 438 +++---------- docs/source/data/document-transforms.mdx | 29 +- docs/source/data/mutations.mdx | 10 +- docs/source/data/queries.mdx | 10 +- docs/source/data/subscriptions.mdx | 10 +- netlify.toml | 2 +- src/cache/core/types/DataProxy.ts | 24 +- src/cache/inmemory/types.ts | 1 - src/core/ApolloClient.ts | 2 +- src/core/ObservableQuery.ts | 22 + src/core/types.ts | 8 +- src/core/watchQueryOptions.ts | 242 ++----- src/react/components/types.ts | 1 + src/react/hooks/useApolloClient.ts | 15 + src/react/hooks/useLazyQuery.ts | 35 + src/react/hooks/useMutation.ts | 47 ++ src/react/hooks/useQuery.ts | 34 + src/react/hooks/useReactiveVar.ts | 17 + src/react/hooks/useSubscription.ts | 86 ++- .../query-preloader/createQueryPreloader.ts | 18 +- src/react/types/types.documentation.ts | 598 ++++++++++++++++++ src/react/types/types.ts | 252 +++++--- src/utilities/graphql/DocumentTransform.ts | 12 + tsdoc.json | 24 + 67 files changed, 2830 insertions(+), 3266 deletions(-) create mode 100644 docs/shared/ApiDoc/EnumDetails.js create mode 100644 docs/shared/ApiDoc/PropertyDetails.js create mode 100644 docs/shared/ApiDoc/SourceLink.js create mode 100644 docs/shared/ApiDoc/Tuple.js create mode 100644 docs/shared/ApiDoc/getInterfaceReference.js delete mode 100644 docs/shared/ApiDoc/mdToReact.js create mode 100644 docs/shared/ApiDoc/sortWithCustomOrder.js delete mode 100644 docs/shared/apollo-provider.mdx delete mode 100644 docs/shared/document-transform-options.mdx delete mode 100644 docs/shared/mutation-options.mdx delete mode 100644 docs/shared/mutation-result.mdx delete mode 100644 docs/shared/query-options.mdx delete mode 100644 docs/shared/query-result.mdx delete mode 100644 docs/shared/subscription-options.mdx delete mode 100644 docs/shared/subscription-result.mdx delete mode 100644 docs/shared/useSuspenseQuery-options.mdx create mode 100644 src/react/types/types.documentation.ts create mode 100644 tsdoc.json diff --git a/.api-reports/api-report-cache.md b/.api-reports/api-report-cache.md index 55957897f33..7eed64d3052 100644 --- a/.api-reports/api-report-cache.md +++ b/.api-reports/api-report-cache.md @@ -234,7 +234,7 @@ export namespace DataProxy { } // (undocumented) export interface ReadFragmentOptions extends Fragment { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; optimistic?: boolean; returnPartialData?: boolean; diff --git a/.api-reports/api-report-core.md b/.api-reports/api-report-core.md index 5e267b7b567..24cf06f5a60 100644 --- a/.api-reports/api-report-core.md +++ b/.api-reports/api-report-core.md @@ -253,14 +253,18 @@ export interface ApolloPayloadResult, TExtensions = } // @public (undocumented) -export type ApolloQueryResult = { +export interface ApolloQueryResult { + // (undocumented) data: T; - errors?: ReadonlyArray; error?: ApolloError; + errors?: ReadonlyArray; + // (undocumented) loading: boolean; + // (undocumented) networkStatus: NetworkStatus; + // (undocumented) partial?: boolean; -}; +} // @public (undocumented) export type ApolloReducerConfig = { @@ -479,7 +483,7 @@ export namespace DataProxy { } // (undocumented) export interface ReadFragmentOptions extends Fragment { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; optimistic?: boolean; returnPartialData?: boolean; @@ -591,9 +595,7 @@ export type DocumentTransformCacheKey = ReadonlyArray; // @public (undocumented) interface DocumentTransformOptions { - // (undocumented) cache?: boolean; - // (undocumented) getCacheKey?: (document: DocumentNode) => DocumentTransformCacheKey | undefined; } @@ -766,9 +768,7 @@ export interface FetchMoreOptions export interface FetchMoreQueryOptions { // (undocumented) context?: DefaultContext; - // (undocumented) query?: DocumentNode | TypedDocumentNode; - // (undocumented) variables?: Partial; } @@ -1359,12 +1359,10 @@ interface MutationBaseOptions; -// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts +// Warning: (ae-forgotten-export) The symbol "MutationSharedOptions" needs to be exported by the entry point index.d.ts // // @public (undocumented) -export interface MutationOptions = ApolloCache> extends MutationBaseOptions { - fetchPolicy?: MutationFetchPolicy; - keepRootFields?: boolean; +export interface MutationOptions = ApolloCache> extends MutationSharedOptions { mutation: DocumentNode | TypedDocumentNode; } @@ -1382,6 +1380,14 @@ export type MutationQueryReducersMap; }; +// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts +// +// @public (undocumented) +interface MutationSharedOptions = ApolloCache> extends MutationBaseOptions { + fetchPolicy?: MutationFetchPolicy; + keepRootFields?: boolean; +} + // @public (undocumented) interface MutationStoreValue { // (undocumented) @@ -1394,7 +1400,7 @@ interface MutationStoreValue { variables: Record; } -// @public (undocumented) +// @public @deprecated (undocumented) export type MutationUpdaterFn = (cache: ApolloCache, mutationResult: FetchResult) => void; @@ -1486,7 +1492,6 @@ export class ObservableQuery; }); - // (undocumented) fetchMore(fetchMoreOptions: FetchMoreQueryOptions & { updateQuery?: (previousQueryResult: TData, options: { fetchMoreResult: TFetchData; @@ -1535,15 +1540,10 @@ export class ObservableQuery | void>; // (undocumented) silentSetOptions(newOptions: Partial>): void; - // (undocumented) startPolling(pollInterval: number): void; - // (undocumented) stopPolling(): void; - // (undocumented) subscribeToMore(options: SubscribeToMoreOptions): () => void; - // (undocumented) updateQuery(mapFn: (previousQueryResult: TData, options: Pick, "variables">) => TData): void; - // (undocumented) get variables(): TVariables | undefined; } @@ -1830,12 +1830,13 @@ class QueryManager { // @public interface QueryOptions { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; context?: DefaultContext; errorPolicy?: ErrorPolicy; fetchPolicy?: FetchPolicy; notifyOnNetworkStatusChange?: boolean; + // @deprecated partialRefetch?: boolean; pollInterval?: number; query: DocumentNode | TypedDocumentNode; @@ -2012,6 +2013,26 @@ export type ServerParseError = Error & { export { setLogVerbosity } +// @public (undocumented) +interface SharedWatchQueryOptions { + // @deprecated + canonizeResults?: boolean; + context?: DefaultContext; + errorPolicy?: ErrorPolicy; + fetchPolicy?: WatchQueryFetchPolicy; + initialFetchPolicy?: WatchQueryFetchPolicy; + // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts + nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); + notifyOnNetworkStatusChange?: boolean; + // @deprecated + partialRefetch?: boolean; + pollInterval?: number; + refetchWritePolicy?: RefetchWritePolicy; + returnPartialData?: boolean; + skipPollAttempt?: () => boolean; + variables?: TVariables; +} + // @public (undocumented) export interface SingleExecutionResult, TContext = DefaultContext, TExtensions = Record> extends ExecutionResult { // (undocumented) @@ -2156,24 +2177,11 @@ export interface UriFunction { // @public (undocumented) export type WatchQueryFetchPolicy = FetchPolicy | "cache-and-network"; +// Warning: (ae-forgotten-export) The symbol "SharedWatchQueryOptions" needs to be exported by the entry point index.d.ts +// // @public -export interface WatchQueryOptions { - // @deprecated (undocumented) - canonizeResults?: boolean; - context?: DefaultContext; - errorPolicy?: ErrorPolicy; - fetchPolicy?: WatchQueryFetchPolicy; - initialFetchPolicy?: WatchQueryFetchPolicy; - // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts - nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); - notifyOnNetworkStatusChange?: boolean; - partialRefetch?: boolean; - pollInterval?: number; +export interface WatchQueryOptions extends SharedWatchQueryOptions { query: DocumentNode | TypedDocumentNode; - refetchWritePolicy?: RefetchWritePolicy; - returnPartialData?: boolean; - skipPollAttempt?: () => boolean; - variables?: TVariables; } // @public (undocumented) @@ -2214,13 +2222,13 @@ interface WriteContext extends ReadMergeModifyContext { // src/cache/inmemory/policies.ts:161:3 - (ae-forgotten-export) The symbol "KeySpecifier" needs to be exported by the entry point index.d.ts // src/cache/inmemory/policies.ts:161:3 - (ae-forgotten-export) The symbol "KeyArgsFunction" needs to be exported by the entry point index.d.ts // src/cache/inmemory/types.ts:139:3 - (ae-forgotten-export) The symbol "KeyFieldsFunction" needs to be exported by the entry point index.d.ts -// src/core/ObservableQuery.ts:113:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts -// src/core/ObservableQuery.ts:114:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts +// src/core/ObservableQuery.ts:116:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts +// src/core/ObservableQuery.ts:117:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:124:5 - (ae-forgotten-export) The symbol "MutationStoreValue" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:158:5 - (ae-forgotten-export) The symbol "LocalState" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:399:7 - (ae-forgotten-export) The symbol "UpdateQueries" needs to be exported by the entry point index.d.ts -// src/core/watchQueryOptions.ts:277:3 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts -// src/core/watchQueryOptions.ts:316:3 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts +// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts +// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts // src/link/http/selectHttpOptionsAndBody.ts:128:32 - (ae-forgotten-export) The symbol "HttpQueryOptions" needs to be exported by the entry point index.d.ts // (No @packageDocumentation comment for this package) diff --git a/.api-reports/api-report-react.md b/.api-reports/api-report-react.md index 84109c58e2e..e7a4e16d51c 100644 --- a/.api-reports/api-report-react.md +++ b/.api-reports/api-report-react.md @@ -322,14 +322,21 @@ interface ApolloProviderProps { } // @public (undocumented) -type ApolloQueryResult = { +interface ApolloQueryResult { + // (undocumented) data: T; - errors?: ReadonlyArray; + // Warning: (ae-forgotten-export) The symbol "ApolloError" needs to be exported by the entry point index.d.ts error?: ApolloError; + errors?: ReadonlyArray; + // (undocumented) loading: boolean; + // Warning: (ae-forgotten-export) The symbol "NetworkStatus" needs to be exported by the entry point index.d.ts + // + // (undocumented) networkStatus: NetworkStatus; + // (undocumented) partial?: boolean; -}; +} // @public type AsStoreObject = BackgroundQueryHookOptions, NoInfer>; +// Warning: (ae-forgotten-export) The symbol "MutationSharedOptions" needs to be exported by the entry point index.d.ts +// // @public (undocumented) -export interface BaseMutationOptions = ApolloCache> extends Omit, "mutation"> { - // (undocumented) +export interface BaseMutationOptions = ApolloCache> extends MutationSharedOptions { client?: ApolloClient; - // (undocumented) ignoreResults?: boolean; - // (undocumented) notifyOnNetworkStatusChange?: boolean; - // (undocumented) onCompleted?: (data: TData, clientOptions?: BaseMutationOptions) => void; - // (undocumented) onError?: (error: ApolloError, clientOptions?: BaseMutationOptions) => void; } +// Warning: (ae-forgotten-export) The symbol "SharedWatchQueryOptions" needs to be exported by the entry point index.d.ts +// // @public (undocumented) -export interface BaseQueryOptions extends Omit, "query"> { - // (undocumented) +export interface BaseQueryOptions extends SharedWatchQueryOptions { + // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ApolloClient" client?: ApolloClient; - // (undocumented) context?: Context; - // (undocumented) ssr?: boolean; } // @public (undocumented) export interface BaseSubscriptionOptions { - // (undocumented) client?: ApolloClient; - // (undocumented) context?: Context; // Warning: (ae-forgotten-export) The symbol "FetchPolicy" needs to be exported by the entry point index.d.ts - // - // (undocumented) fetchPolicy?: FetchPolicy; - // (undocumented) onComplete?: () => void; - // (undocumented) onData?: (options: OnDataOptions) => any; - // (undocumented) onError?: (error: ApolloError) => void; - // @deprecated (undocumented) + // @deprecated onSubscriptionComplete?: () => void; - // @deprecated (undocumented) + // @deprecated onSubscriptionData?: (options: OnSubscriptionDataOptions) => any; - // (undocumented) shouldResubscribe?: boolean | ((options: BaseSubscriptionOptions) => boolean); - // (undocumented) skip?: boolean; - // (undocumented) variables?: TVariables; } @@ -582,7 +576,7 @@ namespace DataProxy { // // (undocumented) interface ReadFragmentOptions extends Fragment { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; optimistic?: boolean; returnPartialData?: boolean; @@ -713,11 +707,8 @@ type DocumentTransformCacheKey = ReadonlyArray; // @public (undocumented) interface DocumentTransformOptions { - // (undocumented) cache?: boolean; // Warning: (ae-forgotten-export) The symbol "DocumentTransformCacheKey" needs to be exported by the entry point index.d.ts - // - // (undocumented) getCacheKey?: (document: DocumentNode) => DocumentTransformCacheKey | undefined; } @@ -792,9 +783,7 @@ type FetchMoreOptions = Parameters["fetchMore"]>[0 interface FetchMoreQueryOptions { // (undocumented) context?: Context; - // (undocumented) query?: DocumentNode | TypedDocumentNode; - // (undocumented) variables?: Partial; } @@ -1042,14 +1031,21 @@ export interface LazyQueryHookExecOptions extends Omit, "skip"> { +export interface LazyQueryHookOptions extends BaseQueryOptions { + // @internal (undocumented) + defaultOptions?: Partial>; + onCompleted?: (data: TData) => void; + onError?: (error: ApolloError) => void; } // @public @deprecated (undocumented) export type LazyQueryResult = QueryResult; // @public (undocumented) -export type LazyQueryResultTuple = [LazyQueryExecFunction, QueryResult]; +export type LazyQueryResultTuple = [ +execute: LazyQueryExecFunction, +result: QueryResult +]; // @public (undocumented) type Listener = (promise: QueryRefPromise) => void; @@ -1059,18 +1055,16 @@ export type LoadableQueryHookFetchPolicy = Extract; context?: Context; // Warning: (ae-forgotten-export) The symbol "ErrorPolicy" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; fetchPolicy?: LoadableQueryHookFetchPolicy; queryKey?: string | number | any[]; // Warning: (ae-forgotten-export) The symbol "RefetchWritePolicy" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "NetworkStatus" refetchWritePolicy?: RefetchWritePolicy; returnPartialData?: boolean; } @@ -1179,7 +1173,6 @@ type Modifiers = Record> = Partia interface MutationBaseOptions = ApolloCache> { awaitRefetchQueries?: boolean; context?: TContext; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; // Warning: (ae-forgotten-export) The symbol "OnQueryUpdated" needs to be exported by the entry point index.d.ts onQueryUpdated?: OnQueryUpdated; @@ -1188,7 +1181,6 @@ interface MutationBaseOptions TData); refetchQueries?: ((result: FetchResult) => InternalRefetchQueriesInclude) | InternalRefetchQueriesInclude; // Warning: (ae-forgotten-export) The symbol "MutationUpdaterFunction" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ApolloCache" update?: MutationUpdaterFunction; // Warning: (ae-forgotten-export) The symbol "MutationQueryReducersMap" needs to be exported by the entry point index.d.ts // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "MutationQueryReducersMap" @@ -1210,7 +1202,6 @@ export type MutationFunction = ApolloCache> extends BaseMutationOptions { - // (undocumented) mutation?: DocumentNode | TypedDocumentNode; } @@ -1218,14 +1209,8 @@ export interface MutationFunctionOptions = ApolloCache> extends BaseMutationOptions { } -// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts -// // @public (undocumented) -interface MutationOptions = ApolloCache> extends MutationBaseOptions { - // Warning: (ae-forgotten-export) The symbol "MutationFetchPolicy" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "MutationFetchPolicy" - fetchPolicy?: MutationFetchPolicy; - keepRootFields?: boolean; +interface MutationOptions = ApolloCache> extends MutationSharedOptions { mutation: DocumentNode | TypedDocumentNode; } @@ -1245,20 +1230,23 @@ type MutationQueryReducersMap { - // (undocumented) called: boolean; - // (undocumented) client: ApolloClient; - // (undocumented) data?: TData | null; - // (undocumented) error?: ApolloError; - // (undocumented) loading: boolean; - // (undocumented) reset(): void; } +// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts +// +// @public (undocumented) +interface MutationSharedOptions = ApolloCache> extends MutationBaseOptions { + // Warning: (ae-forgotten-export) The symbol "MutationFetchPolicy" needs to be exported by the entry point index.d.ts + fetchPolicy?: MutationFetchPolicy; + keepRootFields?: boolean; +} + // @public (undocumented) interface MutationStoreValue { // (undocumented) @@ -1273,8 +1261,8 @@ interface MutationStoreValue { // @public (undocumented) export type MutationTuple = ApolloCache> = [ -(options?: MutationFunctionOptions) => Promise>, -MutationResult +mutate: (options?: MutationFunctionOptions) => Promise>, +result: MutationResult ]; // @public (undocumented) @@ -1322,7 +1310,6 @@ class ObservableQuery; }); - // (undocumented) fetchMore(fetchMoreOptions: FetchMoreQueryOptions & { updateQuery?: (previousQueryResult: TData, options: { fetchMoreResult: TFetchData; @@ -1371,22 +1358,31 @@ class ObservableQuery | void>; // (undocumented) silentSetOptions(newOptions: Partial>): void; - // (undocumented) startPolling(pollInterval: number): void; - // (undocumented) stopPolling(): void; // Warning: (ae-forgotten-export) The symbol "SubscribeToMoreOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) subscribeToMore(options: SubscribeToMoreOptions): () => void; - // (undocumented) updateQuery(mapFn: (previousQueryResult: TData, options: Pick, "variables">) => TData): void; - // (undocumented) get variables(): TVariables | undefined; } // @public (undocumented) -export type ObservableQueryFields = Pick, "startPolling" | "stopPolling" | "subscribeToMore" | "updateQuery" | "refetch" | "reobserve" | "variables" | "fetchMore">; +export interface ObservableQueryFields { + fetchMore(fetchMoreOptions: FetchMoreQueryOptions & { + updateQuery?: (previousQueryResult: TData, options: { + fetchMoreResult: TFetchData; + variables: TFetchVars; + }) => TData; + }): Promise>; + refetch(variables?: Partial): Promise>; + // @internal (undocumented) + reobserve(newOptions?: Partial>, newNetworkStatus?: NetworkStatus): Promise>; + startPolling(pollInterval: number): void; + stopPolling(): void; + subscribeToMore(options: SubscribeToMoreOptions): () => void; + updateQuery(mapFn: (previousQueryResult: TData, options: Pick, "variables">) => TData): void; + variables: TVariables | undefined; +} // @public (undocumented) const OBSERVED_CHANGED_OPTIONS: readonly ["canonizeResults", "context", "errorPolicy", "fetchPolicy", "refetchWritePolicy", "returnPartialData"]; @@ -1529,19 +1525,15 @@ interface QueryData { export interface QueryDataOptions extends QueryFunctionOptions { // (undocumented) children?: (result: QueryResult) => ReactTypes.ReactNode; - // (undocumented) query: DocumentNode | TypedDocumentNode; } // @public (undocumented) -export interface QueryFunctionOptions extends BaseQueryOptions { - // (undocumented) +export interface QueryFunctionOptions extends BaseQueryOptions { + // @internal (undocumented) defaultOptions?: Partial>; - // (undocumented) onCompleted?: (data: TData) => void; - // (undocumented) onError?: (error: ApolloError) => void; - // (undocumented) skip?: boolean; } @@ -1616,9 +1608,7 @@ interface QueryKey { // @public @deprecated (undocumented) export interface QueryLazyOptions { - // (undocumented) context?: Context; - // (undocumented) variables?: TVariables; } @@ -1751,14 +1741,13 @@ class QueryManager { // @public interface QueryOptions { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; context?: Context; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" fetchPolicy?: FetchPolicy; notifyOnNetworkStatusChange?: boolean; + // @deprecated partialRefetch?: boolean; pollInterval?: number; query: DocumentNode | TypedDocumentNode; @@ -1787,21 +1776,13 @@ type QueryRefPromise = PromiseWithState>; // @public (undocumented) export interface QueryResult extends ObservableQueryFields { - // (undocumented) called: boolean; - // (undocumented) client: ApolloClient; - // (undocumented) data: TData | undefined; - // (undocumented) error?: ApolloError; - // (undocumented) loading: boolean; - // (undocumented) networkStatus: NetworkStatus; - // (undocumented) observable: ObservableQuery; - // (undocumented) previousData?: TData; } @@ -1966,6 +1947,27 @@ type ServerParseError = Error & { bodyText: string; }; +// @public (undocumented) +interface SharedWatchQueryOptions { + // @deprecated + canonizeResults?: boolean; + context?: Context; + errorPolicy?: ErrorPolicy; + fetchPolicy?: WatchQueryFetchPolicy; + initialFetchPolicy?: WatchQueryFetchPolicy; + // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts + // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" + nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); + notifyOnNetworkStatusChange?: boolean; + // @deprecated + partialRefetch?: boolean; + pollInterval?: number; + refetchWritePolicy?: RefetchWritePolicy; + returnPartialData?: boolean; + skipPollAttempt?: () => boolean; + variables?: TVariables; +} + // @public (undocumented) interface SingleExecutionResult, TContext = Context, TExtensions = Record> extends ExecutionResult { // (undocumented) @@ -2039,7 +2041,6 @@ interface SubscriptionOptions { context?: Context; // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" fetchPolicy?: FetchPolicy; query: DocumentNode | TypedDocumentNode; variables?: TVariables; @@ -2047,13 +2048,10 @@ interface SubscriptionOptions { // @public (undocumented) export interface SubscriptionResult { - // (undocumented) data?: TData; - // (undocumented) error?: ApolloError; - // (undocumented) loading: boolean; - // (undocumented) + // @internal (undocumented) variables?: TVariables; } @@ -2061,13 +2059,20 @@ export interface SubscriptionResult { export type SuspenseQueryHookFetchPolicy = Extract; // @public (undocumented) -export interface SuspenseQueryHookOptions extends Pick, "client" | "variables" | "errorPolicy" | "context" | "canonizeResults" | "returnPartialData" | "refetchWritePolicy"> { - // (undocumented) +export interface SuspenseQueryHookOptions { + // @deprecated + canonizeResults?: boolean; + // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ApolloClient" + client?: ApolloClient; + context?: Context; + errorPolicy?: ErrorPolicy; fetchPolicy?: SuspenseQueryHookFetchPolicy; - // (undocumented) queryKey?: string | number | any[]; + refetchWritePolicy?: RefetchWritePolicy; + returnPartialData?: boolean; // @deprecated skip?: boolean; + variables?: TVariables; } // @public (undocumented) @@ -2224,7 +2229,7 @@ export type UseFragmentResult = { missing?: MissingTree; }; -// @public (undocumented) +// @public export function useLazyQuery(query: DocumentNode | TypedDocumentNode, options?: LazyQueryHookOptions, NoInfer>): LazyQueryResultTuple; // @public (undocumented) @@ -2260,10 +2265,10 @@ QueryReference | null, } ]; -// @public (undocumented) +// @public export function useMutation = ApolloCache>(mutation: DocumentNode | TypedDocumentNode, options?: MutationHookOptions, NoInfer, TContext, TCache>): MutationTuple; -// @public (undocumented) +// @public export function useQuery(query: DocumentNode | TypedDocumentNode, options?: QueryHookOptions, NoInfer>): QueryResult; // @public @@ -2271,15 +2276,13 @@ export function useQueryRefHandlers { - // (undocumented) fetchMore: FetchMoreFunction; - refetch: RefetchFunction; } // Warning: (ae-forgotten-export) The symbol "ReactiveVar" needs to be exported by the entry point index.d.ts // -// @public (undocumented) +// @public export function useReactiveVar(rv: ReactiveVar): T; // @public (undocumented) @@ -2292,7 +2295,7 @@ export interface UseReadQueryResult { networkStatus: NetworkStatus; } -// @public (undocumented) +// @public export function useSubscription(subscription: DocumentNode | TypedDocumentNode, options?: SubscriptionHookOptions, NoInfer>): SubscriptionResult; // @public (undocumented) @@ -2371,55 +2374,31 @@ TVariables type WatchQueryFetchPolicy = FetchPolicy | "cache-and-network"; // @public -interface WatchQueryOptions { - // @deprecated (undocumented) - canonizeResults?: boolean; - context?: Context; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" - errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" - fetchPolicy?: WatchQueryFetchPolicy; - initialFetchPolicy?: WatchQueryFetchPolicy; - // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" - nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); - notifyOnNetworkStatusChange?: boolean; - partialRefetch?: boolean; - pollInterval?: number; +interface WatchQueryOptions extends SharedWatchQueryOptions { query: DocumentNode | TypedDocumentNode; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "NetworkStatus" - refetchWritePolicy?: RefetchWritePolicy; - returnPartialData?: boolean; - skipPollAttempt?: () => boolean; - variables?: TVariables; } // Warnings were encountered during analysis: // -// src/cache/core/types/DataProxy.ts:153:5 - (ae-forgotten-export) The symbol "MissingFieldError" needs to be exported by the entry point index.d.ts +// src/cache/core/types/DataProxy.ts:146:7 - (ae-forgotten-export) The symbol "MissingFieldError" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:100:3 - (ae-forgotten-export) The symbol "ReadFieldFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:101:3 - (ae-forgotten-export) The symbol "CanReadFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:102:3 - (ae-forgotten-export) The symbol "isReference" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:103:3 - (ae-forgotten-export) The symbol "ToReferenceFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:104:3 - (ae-forgotten-export) The symbol "StorageType" needs to be exported by the entry point index.d.ts // src/core/LocalState.ts:46:5 - (ae-forgotten-export) The symbol "FragmentMap" needs to be exported by the entry point index.d.ts -// src/core/ObservableQuery.ts:113:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts -// src/core/ObservableQuery.ts:114:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts +// src/core/ObservableQuery.ts:116:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts +// src/core/ObservableQuery.ts:117:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:124:5 - (ae-forgotten-export) The symbol "MutationStoreValue" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:158:5 - (ae-forgotten-export) The symbol "LocalState" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:399:7 - (ae-forgotten-export) The symbol "UpdateQueries" needs to be exported by the entry point index.d.ts -// src/core/types.ts:154:3 - (ae-forgotten-export) The symbol "ApolloError" needs to be exported by the entry point index.d.ts -// src/core/types.ts:156:3 - (ae-forgotten-export) The symbol "NetworkStatus" needs to be exported by the entry point index.d.ts // src/core/types.ts:174:3 - (ae-forgotten-export) The symbol "MutationQueryReducer" needs to be exported by the entry point index.d.ts -// src/core/types.ts:201:5 - (ae-forgotten-export) The symbol "Resolver" needs to be exported by the entry point index.d.ts -// src/core/watchQueryOptions.ts:277:3 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts -// src/core/watchQueryOptions.ts:316:3 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts +// src/core/types.ts:203:5 - (ae-forgotten-export) The symbol "Resolver" needs to be exported by the entry point index.d.ts +// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts +// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts // src/react/hooks/useBackgroundQuery.ts:29:3 - (ae-forgotten-export) The symbol "FetchMoreFunction" needs to be exported by the entry point index.d.ts // src/react/hooks/useBackgroundQuery.ts:30:3 - (ae-forgotten-export) The symbol "RefetchFunction" needs to be exported by the entry point index.d.ts // src/react/hooks/useLoadableQuery.ts:49:5 - (ae-forgotten-export) The symbol "ResetFunction" needs to be exported by the entry point index.d.ts -// src/react/query-preloader/createQueryPreloader.ts:80:5 - (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" -// src/react/query-preloader/createQueryPreloader.ts:85:5 - (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" -// src/react/query-preloader/createQueryPreloader.ts:95:5 - (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "NetworkStatus" // (No @packageDocumentation comment for this package) diff --git a/.api-reports/api-report-react_components.md b/.api-reports/api-report-react_components.md index 4908305f332..8307e63ec9c 100644 --- a/.api-reports/api-report-react_components.md +++ b/.api-reports/api-report-react_components.md @@ -287,14 +287,21 @@ class ApolloLink { } // @public (undocumented) -type ApolloQueryResult = { +interface ApolloQueryResult { + // (undocumented) data: T; - errors?: ReadonlyArray; + // Warning: (ae-forgotten-export) The symbol "ApolloError" needs to be exported by the entry point index.d.ts error?: ApolloError; + errors?: ReadonlyArray; + // (undocumented) loading: boolean; + // Warning: (ae-forgotten-export) The symbol "NetworkStatus" needs to be exported by the entry point index.d.ts + // + // (undocumented) networkStatus: NetworkStatus; + // (undocumented) partial?: boolean; -}; +} // @public type AsStoreObject = ApolloCache> extends Omit, "mutation"> { +interface BaseMutationOptions = ApolloCache> extends MutationSharedOptions { // Warning: (ae-forgotten-export) The symbol "ApolloClient" needs to be exported by the entry point index.d.ts - // - // (undocumented) client?: ApolloClient; - // (undocumented) ignoreResults?: boolean; - // (undocumented) notifyOnNetworkStatusChange?: boolean; - // (undocumented) onCompleted?: (data: TData, clientOptions?: BaseMutationOptions) => void; - // (undocumented) onError?: (error: ApolloError, clientOptions?: BaseMutationOptions) => void; } +// Warning: (ae-forgotten-export) The symbol "SharedWatchQueryOptions" needs to be exported by the entry point index.d.ts +// // @public (undocumented) -interface BaseQueryOptions extends Omit, "query"> { - // (undocumented) +interface BaseQueryOptions extends SharedWatchQueryOptions { + // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ApolloClient" client?: ApolloClient; - // (undocumented) context?: DefaultContext; - // (undocumented) ssr?: boolean; } // @public (undocumented) interface BaseSubscriptionOptions { - // (undocumented) client?: ApolloClient; - // (undocumented) context?: DefaultContext; // Warning: (ae-forgotten-export) The symbol "FetchPolicy" needs to be exported by the entry point index.d.ts - // - // (undocumented) fetchPolicy?: FetchPolicy; - // (undocumented) onComplete?: () => void; // Warning: (ae-forgotten-export) The symbol "OnDataOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) onData?: (options: OnDataOptions) => any; - // (undocumented) onError?: (error: ApolloError) => void; - // @deprecated (undocumented) + // @deprecated onSubscriptionComplete?: () => void; // Warning: (ae-forgotten-export) The symbol "OnSubscriptionDataOptions" needs to be exported by the entry point index.d.ts // - // @deprecated (undocumented) + // @deprecated onSubscriptionData?: (options: OnSubscriptionDataOptions) => any; - // (undocumented) shouldResubscribe?: boolean | ((options: BaseSubscriptionOptions) => boolean); - // (undocumented) skip?: boolean; - // (undocumented) variables?: TVariables; } @@ -523,7 +515,7 @@ namespace DataProxy { // // (undocumented) interface ReadFragmentOptions extends Fragment { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; optimistic?: boolean; returnPartialData?: boolean; @@ -624,11 +616,8 @@ type DocumentTransformCacheKey = ReadonlyArray; // @public (undocumented) interface DocumentTransformOptions { - // (undocumented) cache?: boolean; // Warning: (ae-forgotten-export) The symbol "DocumentTransformCacheKey" needs to be exported by the entry point index.d.ts - // - // (undocumented) getCacheKey?: (document: DocumentNode) => DocumentTransformCacheKey | undefined; } @@ -679,9 +668,7 @@ interface ExecutionPatchResultBase { interface FetchMoreQueryOptions { // (undocumented) context?: DefaultContext; - // (undocumented) query?: DocumentNode | TypedDocumentNode; - // (undocumented) variables?: Partial; } @@ -963,7 +950,6 @@ interface MutationBaseOptions; @@ -972,7 +958,6 @@ interface MutationBaseOptions TData); refetchQueries?: ((result: FetchResult) => InternalRefetchQueriesInclude) | InternalRefetchQueriesInclude; // Warning: (ae-forgotten-export) The symbol "MutationUpdaterFunction" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ApolloCache" update?: MutationUpdaterFunction; // Warning: (ae-forgotten-export) The symbol "MutationQueryReducersMap" needs to be exported by the entry point index.d.ts // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "MutationQueryReducersMap" @@ -1003,18 +988,11 @@ type MutationFunction = ApolloCache> extends BaseMutationOptions { - // (undocumented) mutation?: DocumentNode | TypedDocumentNode; } -// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts -// // @public (undocumented) -interface MutationOptions = ApolloCache> extends MutationBaseOptions { - // Warning: (ae-forgotten-export) The symbol "MutationFetchPolicy" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "MutationFetchPolicy" - fetchPolicy?: MutationFetchPolicy; - keepRootFields?: boolean; +interface MutationOptions = ApolloCache> extends MutationSharedOptions { mutation: DocumentNode | TypedDocumentNode; } @@ -1034,20 +1012,23 @@ type MutationQueryReducersMap { - // (undocumented) called: boolean; - // (undocumented) client: ApolloClient; - // (undocumented) data?: TData | null; - // (undocumented) error?: ApolloError; - // (undocumented) loading: boolean; - // (undocumented) reset(): void; } +// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts +// +// @public (undocumented) +interface MutationSharedOptions = ApolloCache> extends MutationBaseOptions { + // Warning: (ae-forgotten-export) The symbol "MutationFetchPolicy" needs to be exported by the entry point index.d.ts + fetchPolicy?: MutationFetchPolicy; + keepRootFields?: boolean; +} + // @public (undocumented) interface MutationStoreValue { // (undocumented) @@ -1105,8 +1086,6 @@ class ObservableQuery; }); // Warning: (ae-forgotten-export) The symbol "FetchMoreQueryOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) fetchMore(fetchMoreOptions: FetchMoreQueryOptions & { updateQuery?: (previousQueryResult: TData, options: { fetchMoreResult: TFetchData; @@ -1155,22 +1134,31 @@ class ObservableQuery | void>; // (undocumented) silentSetOptions(newOptions: Partial>): void; - // (undocumented) startPolling(pollInterval: number): void; - // (undocumented) stopPolling(): void; // Warning: (ae-forgotten-export) The symbol "SubscribeToMoreOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) subscribeToMore(options: SubscribeToMoreOptions): () => void; - // (undocumented) updateQuery(mapFn: (previousQueryResult: TData, options: Pick, "variables">) => TData): void; - // (undocumented) get variables(): TVariables | undefined; } // @public (undocumented) -type ObservableQueryFields = Pick, "startPolling" | "stopPolling" | "subscribeToMore" | "updateQuery" | "refetch" | "reobserve" | "variables" | "fetchMore">; +interface ObservableQueryFields { + fetchMore(fetchMoreOptions: FetchMoreQueryOptions & { + updateQuery?: (previousQueryResult: TData, options: { + fetchMoreResult: TFetchData; + variables: TFetchVars; + }) => TData; + }): Promise>; + refetch(variables?: Partial): Promise>; + // @internal (undocumented) + reobserve(newOptions?: Partial>, newNetworkStatus?: NetworkStatus): Promise>; + startPolling(pollInterval: number): void; + stopPolling(): void; + subscribeToMore(options: SubscribeToMoreOptions): () => void; + updateQuery(mapFn: (previousQueryResult: TData, options: Pick, "variables">) => TData): void; + variables: TVariables | undefined; +} // @public (undocumented) interface OnDataOptions { @@ -1245,14 +1233,11 @@ export interface QueryComponentOptions extends BaseQueryOptions { - // (undocumented) +interface QueryFunctionOptions extends BaseQueryOptions { + // @internal (undocumented) defaultOptions?: Partial>; - // (undocumented) onCompleted?: (data: TData) => void; - // (undocumented) onError?: (error: ApolloError) => void; - // (undocumented) skip?: boolean; } @@ -1444,14 +1429,13 @@ class QueryManager { // @public interface QueryOptions { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; context?: DefaultContext; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" fetchPolicy?: FetchPolicy; notifyOnNetworkStatusChange?: boolean; + // @deprecated partialRefetch?: boolean; pollInterval?: number; query: DocumentNode | TypedDocumentNode; @@ -1463,21 +1447,13 @@ interface QueryOptions { // // @public (undocumented) interface QueryResult extends ObservableQueryFields { - // (undocumented) called: boolean; - // (undocumented) client: ApolloClient; - // (undocumented) data: TData | undefined; - // (undocumented) error?: ApolloError; - // (undocumented) loading: boolean; - // (undocumented) networkStatus: NetworkStatus; - // (undocumented) observable: ObservableQuery; - // (undocumented) previousData?: TData; } @@ -1582,6 +1558,28 @@ type ServerParseError = Error & { bodyText: string; }; +// @public (undocumented) +interface SharedWatchQueryOptions { + // @deprecated + canonizeResults?: boolean; + context?: DefaultContext; + errorPolicy?: ErrorPolicy; + fetchPolicy?: WatchQueryFetchPolicy; + initialFetchPolicy?: WatchQueryFetchPolicy; + // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts + // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" + nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); + notifyOnNetworkStatusChange?: boolean; + // @deprecated + partialRefetch?: boolean; + pollInterval?: number; + // Warning: (ae-forgotten-export) The symbol "RefetchWritePolicy" needs to be exported by the entry point index.d.ts + refetchWritePolicy?: RefetchWritePolicy; + returnPartialData?: boolean; + skipPollAttempt?: () => boolean; + variables?: TVariables; +} + // @public (undocumented) interface SingleExecutionResult, TContext = DefaultContext, TExtensions = Record> extends ExecutionResult { // (undocumented) @@ -1642,7 +1640,6 @@ export interface Subscription { export interface SubscriptionComponentOptions extends BaseSubscriptionOptions { // (undocumented) children?: null | ((result: SubscriptionResult) => ReactTypes.JSX.Element | null); - // (undocumented) subscription: DocumentNode | TypedDocumentNode; } @@ -1651,7 +1648,6 @@ interface SubscriptionOptions { context?: DefaultContext; // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" fetchPolicy?: FetchPolicy; query: DocumentNode | TypedDocumentNode; variables?: TVariables; @@ -1659,13 +1655,10 @@ interface SubscriptionOptions { // @public (undocumented) interface SubscriptionResult { - // (undocumented) data?: TData; - // (undocumented) error?: ApolloError; - // (undocumented) loading: boolean; - // (undocumented) + // @internal (undocumented) variables?: TVariables; } @@ -1723,50 +1716,28 @@ interface UriFunction { type WatchQueryFetchPolicy = FetchPolicy | "cache-and-network"; // @public -interface WatchQueryOptions { - // @deprecated (undocumented) - canonizeResults?: boolean; - context?: DefaultContext; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" - errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" - fetchPolicy?: WatchQueryFetchPolicy; - initialFetchPolicy?: WatchQueryFetchPolicy; - // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" - nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); - notifyOnNetworkStatusChange?: boolean; - partialRefetch?: boolean; - pollInterval?: number; +interface WatchQueryOptions extends SharedWatchQueryOptions { query: DocumentNode | TypedDocumentNode; - // Warning: (ae-forgotten-export) The symbol "RefetchWritePolicy" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "NetworkStatus" - refetchWritePolicy?: RefetchWritePolicy; - returnPartialData?: boolean; - skipPollAttempt?: () => boolean; - variables?: TVariables; } // Warnings were encountered during analysis: // -// src/cache/core/types/DataProxy.ts:153:5 - (ae-forgotten-export) The symbol "MissingFieldError" needs to be exported by the entry point index.d.ts +// src/cache/core/types/DataProxy.ts:146:7 - (ae-forgotten-export) The symbol "MissingFieldError" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:100:3 - (ae-forgotten-export) The symbol "ReadFieldFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:101:3 - (ae-forgotten-export) The symbol "CanReadFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:102:3 - (ae-forgotten-export) The symbol "isReference" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:103:3 - (ae-forgotten-export) The symbol "ToReferenceFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:104:3 - (ae-forgotten-export) The symbol "StorageType" needs to be exported by the entry point index.d.ts // src/core/LocalState.ts:46:5 - (ae-forgotten-export) The symbol "FragmentMap" needs to be exported by the entry point index.d.ts -// src/core/ObservableQuery.ts:113:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts -// src/core/ObservableQuery.ts:114:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts +// src/core/ObservableQuery.ts:116:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts +// src/core/ObservableQuery.ts:117:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:124:5 - (ae-forgotten-export) The symbol "MutationStoreValue" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:158:5 - (ae-forgotten-export) The symbol "LocalState" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:399:7 - (ae-forgotten-export) The symbol "UpdateQueries" needs to be exported by the entry point index.d.ts -// src/core/types.ts:154:3 - (ae-forgotten-export) The symbol "ApolloError" needs to be exported by the entry point index.d.ts -// src/core/types.ts:156:3 - (ae-forgotten-export) The symbol "NetworkStatus" needs to be exported by the entry point index.d.ts // src/core/types.ts:174:3 - (ae-forgotten-export) The symbol "MutationQueryReducer" needs to be exported by the entry point index.d.ts -// src/core/types.ts:201:5 - (ae-forgotten-export) The symbol "Resolver" needs to be exported by the entry point index.d.ts -// src/core/watchQueryOptions.ts:277:3 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts -// src/core/watchQueryOptions.ts:316:3 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts +// src/core/types.ts:203:5 - (ae-forgotten-export) The symbol "Resolver" needs to be exported by the entry point index.d.ts +// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts +// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts // (No @packageDocumentation comment for this package) diff --git a/.api-reports/api-report-react_context.md b/.api-reports/api-report-react_context.md index dd5ecb6c320..337281bb134 100644 --- a/.api-reports/api-report-react_context.md +++ b/.api-reports/api-report-react_context.md @@ -318,14 +318,21 @@ export interface ApolloProviderProps { } // @public (undocumented) -type ApolloQueryResult = { +interface ApolloQueryResult { + // (undocumented) data: T; - errors?: ReadonlyArray; + // Warning: (ae-forgotten-export) The symbol "ApolloError" needs to be exported by the entry point index.d.ts error?: ApolloError; + errors?: ReadonlyArray; + // (undocumented) loading: boolean; + // Warning: (ae-forgotten-export) The symbol "NetworkStatus" needs to be exported by the entry point index.d.ts + // + // (undocumented) networkStatus: NetworkStatus; + // (undocumented) partial?: boolean; -}; +} // @public type AsStoreObject extends Omit, "query"> { - // (undocumented) +interface BaseQueryOptions extends SharedWatchQueryOptions { + // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ApolloClient" client?: ApolloClient; - // (undocumented) context?: DefaultContext; - // (undocumented) ssr?: boolean; } @@ -506,7 +513,7 @@ namespace DataProxy { // // (undocumented) interface ReadFragmentOptions extends Fragment { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; optimistic?: boolean; returnPartialData?: boolean; @@ -607,11 +614,8 @@ type DocumentTransformCacheKey = ReadonlyArray; // @public (undocumented) interface DocumentTransformOptions { - // (undocumented) cache?: boolean; // Warning: (ae-forgotten-export) The symbol "DocumentTransformCacheKey" needs to be exported by the entry point index.d.ts - // - // (undocumented) getCacheKey?: (document: DocumentNode) => DocumentTransformCacheKey | undefined; } @@ -662,9 +666,7 @@ interface ExecutionPatchResultBase { interface FetchMoreQueryOptions { // (undocumented) context?: DefaultContext; - // (undocumented) query?: DocumentNode | TypedDocumentNode; - // (undocumented) variables?: Partial; } @@ -934,7 +936,6 @@ interface MutationBaseOptions; @@ -943,7 +944,6 @@ interface MutationBaseOptions TData); refetchQueries?: ((result: FetchResult) => InternalRefetchQueriesInclude) | InternalRefetchQueriesInclude; // Warning: (ae-forgotten-export) The symbol "MutationUpdaterFunction" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ApolloCache" update?: MutationUpdaterFunction; // Warning: (ae-forgotten-export) The symbol "MutationQueryReducersMap" needs to be exported by the entry point index.d.ts // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "MutationQueryReducersMap" @@ -956,14 +956,10 @@ interface MutationBaseOptions; -// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts +// Warning: (ae-forgotten-export) The symbol "MutationSharedOptions" needs to be exported by the entry point index.d.ts // // @public (undocumented) -interface MutationOptions = ApolloCache> extends MutationBaseOptions { - // Warning: (ae-forgotten-export) The symbol "MutationFetchPolicy" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "MutationFetchPolicy" - fetchPolicy?: MutationFetchPolicy; - keepRootFields?: boolean; +interface MutationOptions = ApolloCache> extends MutationSharedOptions { mutation: DocumentNode | TypedDocumentNode; } @@ -981,6 +977,15 @@ type MutationQueryReducersMap; }; +// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts +// +// @public (undocumented) +interface MutationSharedOptions = ApolloCache> extends MutationBaseOptions { + // Warning: (ae-forgotten-export) The symbol "MutationFetchPolicy" needs to be exported by the entry point index.d.ts + fetchPolicy?: MutationFetchPolicy; + keepRootFields?: boolean; +} + // @public (undocumented) interface MutationStoreValue { // (undocumented) @@ -1038,8 +1043,6 @@ class ObservableQuery; }); // Warning: (ae-forgotten-export) The symbol "FetchMoreQueryOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) fetchMore(fetchMoreOptions: FetchMoreQueryOptions & { updateQuery?: (previousQueryResult: TData, options: { fetchMoreResult: TFetchData; @@ -1088,22 +1091,31 @@ class ObservableQuery | void>; // (undocumented) silentSetOptions(newOptions: Partial>): void; - // (undocumented) startPolling(pollInterval: number): void; - // (undocumented) stopPolling(): void; // Warning: (ae-forgotten-export) The symbol "SubscribeToMoreOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) subscribeToMore(options: SubscribeToMoreOptions): () => void; - // (undocumented) updateQuery(mapFn: (previousQueryResult: TData, options: Pick, "variables">) => TData): void; - // (undocumented) get variables(): TVariables | undefined; } // @public (undocumented) -type ObservableQueryFields = Pick, "startPolling" | "stopPolling" | "subscribeToMore" | "updateQuery" | "refetch" | "reobserve" | "variables" | "fetchMore">; +interface ObservableQueryFields { + fetchMore(fetchMoreOptions: FetchMoreQueryOptions & { + updateQuery?: (previousQueryResult: TData, options: { + fetchMoreResult: TFetchData; + variables: TFetchVars; + }) => TData; + }): Promise>; + refetch(variables?: Partial): Promise>; + // @internal (undocumented) + reobserve(newOptions?: Partial>, newNetworkStatus?: NetworkStatus): Promise>; + startPolling(pollInterval: number): void; + stopPolling(): void; + subscribeToMore(options: SubscribeToMoreOptions): () => void; + updateQuery(mapFn: (previousQueryResult: TData, options: Pick, "variables">) => TData): void; + variables: TVariables | undefined; +} // @public (undocumented) type OnQueryUpdated = (observableQuery: ObservableQuery, diff: Cache_2.DiffResult, lastDiff: Cache_2.DiffResult | undefined) => boolean | TResult; @@ -1146,21 +1158,17 @@ interface QueryDataOptions) => ReactTypes.ReactNode; - // (undocumented) query: DocumentNode | TypedDocumentNode; } // Warning: (ae-forgotten-export) The symbol "BaseQueryOptions" needs to be exported by the entry point index.d.ts // // @public (undocumented) -interface QueryFunctionOptions extends BaseQueryOptions { - // (undocumented) +interface QueryFunctionOptions extends BaseQueryOptions { + // @internal (undocumented) defaultOptions?: Partial>; - // (undocumented) onCompleted?: (data: TData) => void; - // (undocumented) onError?: (error: ApolloError) => void; - // (undocumented) skip?: boolean; } @@ -1352,14 +1360,13 @@ class QueryManager { // @public interface QueryOptions { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; context?: DefaultContext; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" fetchPolicy?: FetchPolicy; notifyOnNetworkStatusChange?: boolean; + // @deprecated partialRefetch?: boolean; pollInterval?: number; query: DocumentNode | TypedDocumentNode; @@ -1371,21 +1378,13 @@ interface QueryOptions { // // @public (undocumented) interface QueryResult extends ObservableQueryFields { - // (undocumented) called: boolean; - // (undocumented) client: ApolloClient; - // (undocumented) data: TData | undefined; - // (undocumented) error?: ApolloError; - // (undocumented) loading: boolean; - // (undocumented) networkStatus: NetworkStatus; - // (undocumented) observable: ObservableQuery; - // (undocumented) previousData?: TData; } @@ -1515,6 +1514,28 @@ type ServerParseError = Error & { bodyText: string; }; +// @public (undocumented) +interface SharedWatchQueryOptions { + // @deprecated + canonizeResults?: boolean; + context?: DefaultContext; + errorPolicy?: ErrorPolicy; + fetchPolicy?: WatchQueryFetchPolicy; + initialFetchPolicy?: WatchQueryFetchPolicy; + // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts + // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" + nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); + notifyOnNetworkStatusChange?: boolean; + // @deprecated + partialRefetch?: boolean; + pollInterval?: number; + // Warning: (ae-forgotten-export) The symbol "RefetchWritePolicy" needs to be exported by the entry point index.d.ts + refetchWritePolicy?: RefetchWritePolicy; + returnPartialData?: boolean; + skipPollAttempt?: () => boolean; + variables?: TVariables; +} + // @public (undocumented) interface SingleExecutionResult, TContext = DefaultContext, TExtensions = Record> extends ExecutionResult { // (undocumented) @@ -1559,7 +1580,6 @@ interface SubscriptionOptions { context?: DefaultContext; // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" fetchPolicy?: FetchPolicy; query: DocumentNode | TypedDocumentNode; variables?: TVariables; @@ -1619,50 +1639,28 @@ interface UriFunction { type WatchQueryFetchPolicy = FetchPolicy | "cache-and-network"; // @public -interface WatchQueryOptions { - // @deprecated (undocumented) - canonizeResults?: boolean; - context?: DefaultContext; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" - errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" - fetchPolicy?: WatchQueryFetchPolicy; - initialFetchPolicy?: WatchQueryFetchPolicy; - // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" - nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); - notifyOnNetworkStatusChange?: boolean; - partialRefetch?: boolean; - pollInterval?: number; +interface WatchQueryOptions extends SharedWatchQueryOptions { query: DocumentNode | TypedDocumentNode; - // Warning: (ae-forgotten-export) The symbol "RefetchWritePolicy" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "NetworkStatus" - refetchWritePolicy?: RefetchWritePolicy; - returnPartialData?: boolean; - skipPollAttempt?: () => boolean; - variables?: TVariables; } // Warnings were encountered during analysis: // -// src/cache/core/types/DataProxy.ts:153:5 - (ae-forgotten-export) The symbol "MissingFieldError" needs to be exported by the entry point index.d.ts +// src/cache/core/types/DataProxy.ts:146:7 - (ae-forgotten-export) The symbol "MissingFieldError" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:100:3 - (ae-forgotten-export) The symbol "ReadFieldFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:101:3 - (ae-forgotten-export) The symbol "CanReadFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:102:3 - (ae-forgotten-export) The symbol "isReference" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:103:3 - (ae-forgotten-export) The symbol "ToReferenceFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:104:3 - (ae-forgotten-export) The symbol "StorageType" needs to be exported by the entry point index.d.ts // src/core/LocalState.ts:46:5 - (ae-forgotten-export) The symbol "FragmentMap" needs to be exported by the entry point index.d.ts -// src/core/ObservableQuery.ts:113:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts -// src/core/ObservableQuery.ts:114:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts +// src/core/ObservableQuery.ts:116:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts +// src/core/ObservableQuery.ts:117:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:124:5 - (ae-forgotten-export) The symbol "MutationStoreValue" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:158:5 - (ae-forgotten-export) The symbol "LocalState" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:399:7 - (ae-forgotten-export) The symbol "UpdateQueries" needs to be exported by the entry point index.d.ts -// src/core/types.ts:154:3 - (ae-forgotten-export) The symbol "ApolloError" needs to be exported by the entry point index.d.ts -// src/core/types.ts:156:3 - (ae-forgotten-export) The symbol "NetworkStatus" needs to be exported by the entry point index.d.ts // src/core/types.ts:174:3 - (ae-forgotten-export) The symbol "MutationQueryReducer" needs to be exported by the entry point index.d.ts -// src/core/types.ts:201:5 - (ae-forgotten-export) The symbol "Resolver" needs to be exported by the entry point index.d.ts -// src/core/watchQueryOptions.ts:277:3 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts -// src/core/watchQueryOptions.ts:316:3 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts +// src/core/types.ts:203:5 - (ae-forgotten-export) The symbol "Resolver" needs to be exported by the entry point index.d.ts +// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts +// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts // (No @packageDocumentation comment for this package) diff --git a/.api-reports/api-report-react_hoc.md b/.api-reports/api-report-react_hoc.md index 8c7591656ce..2be6017e01e 100644 --- a/.api-reports/api-report-react_hoc.md +++ b/.api-reports/api-report-react_hoc.md @@ -286,14 +286,21 @@ class ApolloLink { } // @public (undocumented) -type ApolloQueryResult = { +interface ApolloQueryResult { + // (undocumented) data: T; - errors?: ReadonlyArray; + // Warning: (ae-forgotten-export) The symbol "ApolloError" needs to be exported by the entry point index.d.ts error?: ApolloError; + errors?: ReadonlyArray; + // (undocumented) loading: boolean; + // Warning: (ae-forgotten-export) The symbol "NetworkStatus" needs to be exported by the entry point index.d.ts + // + // (undocumented) networkStatus: NetworkStatus; + // (undocumented) partial?: boolean; -}; +} // @public type AsStoreObject = ApolloCache> extends Omit, "mutation"> { +interface BaseMutationOptions = ApolloCache> extends MutationSharedOptions { // Warning: (ae-forgotten-export) The symbol "ApolloClient" needs to be exported by the entry point index.d.ts - // - // (undocumented) client?: ApolloClient; - // (undocumented) ignoreResults?: boolean; - // (undocumented) notifyOnNetworkStatusChange?: boolean; - // (undocumented) onCompleted?: (data: TData, clientOptions?: BaseMutationOptions) => void; - // (undocumented) onError?: (error: ApolloError, clientOptions?: BaseMutationOptions) => void; } +// Warning: (ae-forgotten-export) The symbol "SharedWatchQueryOptions" needs to be exported by the entry point index.d.ts +// // @public (undocumented) -interface BaseQueryOptions extends Omit, "query"> { - // (undocumented) +interface BaseQueryOptions extends SharedWatchQueryOptions { + // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ApolloClient" client?: ApolloClient; - // (undocumented) context?: DefaultContext; - // (undocumented) ssr?: boolean; } @@ -505,7 +508,7 @@ namespace DataProxy { // // (undocumented) interface ReadFragmentOptions extends Fragment { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; optimistic?: boolean; returnPartialData?: boolean; @@ -609,11 +612,8 @@ type DocumentTransformCacheKey = ReadonlyArray; // @public (undocumented) interface DocumentTransformOptions { - // (undocumented) cache?: boolean; // Warning: (ae-forgotten-export) The symbol "DocumentTransformCacheKey" needs to be exported by the entry point index.d.ts - // - // (undocumented) getCacheKey?: (document: DocumentNode) => DocumentTransformCacheKey | undefined; } @@ -673,9 +673,7 @@ interface FetchMoreOptions { interface FetchMoreQueryOptions { // (undocumented) context?: DefaultContext; - // (undocumented) query?: DocumentNode | TypedDocumentNode; - // (undocumented) variables?: Partial; } @@ -957,7 +955,6 @@ interface MutationBaseOptions; @@ -966,7 +963,6 @@ interface MutationBaseOptions TData); refetchQueries?: ((result: FetchResult) => InternalRefetchQueriesInclude) | InternalRefetchQueriesInclude; // Warning: (ae-forgotten-export) The symbol "MutationUpdaterFunction" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ApolloCache" update?: MutationUpdaterFunction; // Warning: (ae-forgotten-export) The symbol "MutationQueryReducersMap" needs to be exported by the entry point index.d.ts // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "MutationQueryReducersMap" @@ -988,18 +984,11 @@ type MutationFunction = ApolloCache> extends BaseMutationOptions { - // (undocumented) mutation?: DocumentNode | TypedDocumentNode; } -// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts -// // @public (undocumented) -interface MutationOptions = ApolloCache> extends MutationBaseOptions { - // Warning: (ae-forgotten-export) The symbol "MutationFetchPolicy" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "MutationFetchPolicy" - fetchPolicy?: MutationFetchPolicy; - keepRootFields?: boolean; +interface MutationOptions = ApolloCache> extends MutationSharedOptions { mutation: DocumentNode | TypedDocumentNode; } @@ -1019,20 +1008,23 @@ type MutationQueryReducersMap { - // (undocumented) called: boolean; - // (undocumented) client: ApolloClient; - // (undocumented) data?: TData | null; - // (undocumented) error?: ApolloError; - // (undocumented) loading: boolean; - // (undocumented) reset(): void; } +// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts +// +// @public (undocumented) +interface MutationSharedOptions = ApolloCache> extends MutationBaseOptions { + // Warning: (ae-forgotten-export) The symbol "MutationFetchPolicy" needs to be exported by the entry point index.d.ts + fetchPolicy?: MutationFetchPolicy; + keepRootFields?: boolean; +} + // @public (undocumented) interface MutationStoreValue { // (undocumented) @@ -1090,8 +1082,6 @@ class ObservableQuery; }); // Warning: (ae-forgotten-export) The symbol "FetchMoreQueryOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) fetchMore(fetchMoreOptions: FetchMoreQueryOptions & { updateQuery?: (previousQueryResult: TData, options: { fetchMoreResult: TFetchData; @@ -1140,17 +1130,11 @@ class ObservableQuery | void>; // (undocumented) silentSetOptions(newOptions: Partial>): void; - // (undocumented) startPolling(pollInterval: number): void; - // (undocumented) stopPolling(): void; // Warning: (ae-forgotten-export) The symbol "SubscribeToMoreOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) subscribeToMore(options: SubscribeToMoreOptions): () => void; - // (undocumented) updateQuery(mapFn: (previousQueryResult: TData, options: Pick, "variables">) => TData): void; - // (undocumented) get variables(): TVariables | undefined; } @@ -1421,14 +1405,13 @@ class QueryManager { // @public interface QueryOptions { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; context?: DefaultContext; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" fetchPolicy?: FetchPolicy; notifyOnNetworkStatusChange?: boolean; + // @deprecated partialRefetch?: boolean; pollInterval?: number; query: DocumentNode | TypedDocumentNode; @@ -1537,6 +1520,28 @@ type ServerParseError = Error & { bodyText: string; }; +// @public (undocumented) +interface SharedWatchQueryOptions { + // @deprecated + canonizeResults?: boolean; + context?: DefaultContext; + errorPolicy?: ErrorPolicy; + fetchPolicy?: WatchQueryFetchPolicy; + initialFetchPolicy?: WatchQueryFetchPolicy; + // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts + // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" + nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); + notifyOnNetworkStatusChange?: boolean; + // @deprecated + partialRefetch?: boolean; + pollInterval?: number; + // Warning: (ae-forgotten-export) The symbol "RefetchWritePolicy" needs to be exported by the entry point index.d.ts + refetchWritePolicy?: RefetchWritePolicy; + returnPartialData?: boolean; + skipPollAttempt?: () => boolean; + variables?: TVariables; +} + // @public (undocumented) interface SingleExecutionResult, TContext = DefaultContext, TExtensions = Record> extends ExecutionResult { // (undocumented) @@ -1581,7 +1586,6 @@ interface SubscriptionOptions { context?: DefaultContext; // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" fetchPolicy?: FetchPolicy; query: DocumentNode | TypedDocumentNode; variables?: TVariables; @@ -1647,28 +1651,8 @@ interface UriFunction { type WatchQueryFetchPolicy = FetchPolicy | "cache-and-network"; // @public -interface WatchQueryOptions { - // @deprecated (undocumented) - canonizeResults?: boolean; - context?: DefaultContext; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" - errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" - fetchPolicy?: WatchQueryFetchPolicy; - initialFetchPolicy?: WatchQueryFetchPolicy; - // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" - nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); - notifyOnNetworkStatusChange?: boolean; - partialRefetch?: boolean; - pollInterval?: number; +interface WatchQueryOptions extends SharedWatchQueryOptions { query: DocumentNode | TypedDocumentNode; - // Warning: (ae-forgotten-export) The symbol "RefetchWritePolicy" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "NetworkStatus" - refetchWritePolicy?: RefetchWritePolicy; - returnPartialData?: boolean; - skipPollAttempt?: () => boolean; - variables?: TVariables; } // @public @deprecated (undocumented) @@ -1690,24 +1674,22 @@ export function withSubscription = { +interface ApolloQueryResult { + // (undocumented) data: T; - errors?: ReadonlyArray; + // Warning: (ae-forgotten-export) The symbol "ApolloError" needs to be exported by the entry point index.d.ts error?: ApolloError; + errors?: ReadonlyArray; + // (undocumented) loading: boolean; + // Warning: (ae-forgotten-export) The symbol "NetworkStatus" needs to be exported by the entry point index.d.ts + // + // (undocumented) networkStatus: NetworkStatus; + // (undocumented) partial?: boolean; -}; +} // @public type AsStoreObject = BackgroundQueryHookOptions, NoInfer>; +// Warning: (ae-forgotten-export) The symbol "MutationSharedOptions" needs to be exported by the entry point index.d.ts +// // @public (undocumented) -interface BaseMutationOptions = ApolloCache> extends Omit, "mutation"> { +interface BaseMutationOptions = ApolloCache> extends MutationSharedOptions { // Warning: (ae-forgotten-export) The symbol "ApolloClient" needs to be exported by the entry point index.d.ts - // - // (undocumented) client?: ApolloClient; - // (undocumented) ignoreResults?: boolean; - // (undocumented) notifyOnNetworkStatusChange?: boolean; - // (undocumented) onCompleted?: (data: TData, clientOptions?: BaseMutationOptions) => void; - // (undocumented) onError?: (error: ApolloError, clientOptions?: BaseMutationOptions) => void; } +// Warning: (ae-forgotten-export) The symbol "SharedWatchQueryOptions" needs to be exported by the entry point index.d.ts +// // @public (undocumented) -interface BaseQueryOptions extends Omit, "query"> { - // (undocumented) +interface BaseQueryOptions extends SharedWatchQueryOptions { + // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ApolloClient" client?: ApolloClient; - // (undocumented) context?: DefaultContext; - // (undocumented) ssr?: boolean; } // @public (undocumented) interface BaseSubscriptionOptions { - // (undocumented) client?: ApolloClient; - // (undocumented) context?: DefaultContext; // Warning: (ae-forgotten-export) The symbol "FetchPolicy" needs to be exported by the entry point index.d.ts - // - // (undocumented) fetchPolicy?: FetchPolicy; - // (undocumented) onComplete?: () => void; // Warning: (ae-forgotten-export) The symbol "OnDataOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) onData?: (options: OnDataOptions) => any; - // (undocumented) onError?: (error: ApolloError) => void; - // @deprecated (undocumented) + // @deprecated onSubscriptionComplete?: () => void; // Warning: (ae-forgotten-export) The symbol "OnSubscriptionDataOptions" needs to be exported by the entry point index.d.ts // - // @deprecated (undocumented) + // @deprecated onSubscriptionData?: (options: OnSubscriptionDataOptions) => any; - // (undocumented) shouldResubscribe?: boolean | ((options: BaseSubscriptionOptions) => boolean); - // (undocumented) skip?: boolean; - // (undocumented) variables?: TVariables; } @@ -546,7 +538,7 @@ namespace DataProxy { // // (undocumented) interface ReadFragmentOptions extends Fragment { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; optimistic?: boolean; returnPartialData?: boolean; @@ -681,11 +673,8 @@ type DocumentTransformCacheKey = ReadonlyArray; // @public (undocumented) interface DocumentTransformOptions { - // (undocumented) cache?: boolean; // Warning: (ae-forgotten-export) The symbol "DocumentTransformCacheKey" needs to be exported by the entry point index.d.ts - // - // (undocumented) getCacheKey?: (document: DocumentNode) => DocumentTransformCacheKey | undefined; } @@ -749,9 +738,7 @@ type FetchMoreOptions = Parameters["fetchMore"]>[0 interface FetchMoreQueryOptions { // (undocumented) context?: DefaultContext; - // (undocumented) query?: DocumentNode | TypedDocumentNode; - // (undocumented) variables?: Partial; } @@ -990,14 +977,23 @@ interface LazyQueryHookExecOptions; } +// Warning: (ae-forgotten-export) The symbol "BaseQueryOptions" needs to be exported by the entry point index.d.ts +// // @public (undocumented) -interface LazyQueryHookOptions extends Omit, "skip"> { +interface LazyQueryHookOptions extends BaseQueryOptions { + // @internal (undocumented) + defaultOptions?: Partial>; + onCompleted?: (data: TData) => void; + onError?: (error: ApolloError) => void; } // Warning: (ae-forgotten-export) The symbol "LazyQueryExecFunction" needs to be exported by the entry point index.d.ts // // @public (undocumented) -type LazyQueryResultTuple = [LazyQueryExecFunction, QueryResult]; +type LazyQueryResultTuple = [ +execute: LazyQueryExecFunction, +result: QueryResult +]; // @public (undocumented) type Listener = (promise: QueryRefPromise) => void; @@ -1007,19 +1003,17 @@ type LoadableQueryHookFetchPolicy = Extract; context?: DefaultContext; // Warning: (ae-forgotten-export) The symbol "ErrorPolicy" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; // Warning: (ae-forgotten-export) The symbol "LoadableQueryHookFetchPolicy" needs to be exported by the entry point index.d.ts fetchPolicy?: LoadableQueryHookFetchPolicy; queryKey?: string | number | any[]; // Warning: (ae-forgotten-export) The symbol "RefetchWritePolicy" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "NetworkStatus" refetchWritePolicy?: RefetchWritePolicy; returnPartialData?: boolean; } @@ -1128,7 +1122,6 @@ type Modifiers = Record> = Partia interface MutationBaseOptions = ApolloCache> { awaitRefetchQueries?: boolean; context?: TContext; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; // Warning: (ae-forgotten-export) The symbol "OnQueryUpdated" needs to be exported by the entry point index.d.ts onQueryUpdated?: OnQueryUpdated; @@ -1137,7 +1130,6 @@ interface MutationBaseOptions TData); refetchQueries?: ((result: FetchResult) => InternalRefetchQueriesInclude) | InternalRefetchQueriesInclude; // Warning: (ae-forgotten-export) The symbol "MutationUpdaterFunction" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ApolloCache" update?: MutationUpdaterFunction; // Warning: (ae-forgotten-export) The symbol "MutationQueryReducersMap" needs to be exported by the entry point index.d.ts // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "MutationQueryReducersMap" @@ -1152,7 +1144,6 @@ type MutationFetchPolicy = Extract; // // @public (undocumented) interface MutationFunctionOptions = ApolloCache> extends BaseMutationOptions { - // (undocumented) mutation?: DocumentNode | TypedDocumentNode; } @@ -1160,14 +1151,8 @@ interface MutationFunctionOptions = ApolloCache> extends BaseMutationOptions { } -// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts -// // @public (undocumented) -interface MutationOptions = ApolloCache> extends MutationBaseOptions { - // Warning: (ae-forgotten-export) The symbol "MutationFetchPolicy" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "MutationFetchPolicy" - fetchPolicy?: MutationFetchPolicy; - keepRootFields?: boolean; +interface MutationOptions = ApolloCache> extends MutationSharedOptions { mutation: DocumentNode | TypedDocumentNode; } @@ -1187,20 +1172,23 @@ type MutationQueryReducersMap { - // (undocumented) called: boolean; - // (undocumented) client: ApolloClient; - // (undocumented) data?: TData | null; - // (undocumented) error?: ApolloError; - // (undocumented) loading: boolean; - // (undocumented) reset(): void; } +// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts +// +// @public (undocumented) +interface MutationSharedOptions = ApolloCache> extends MutationBaseOptions { + // Warning: (ae-forgotten-export) The symbol "MutationFetchPolicy" needs to be exported by the entry point index.d.ts + fetchPolicy?: MutationFetchPolicy; + keepRootFields?: boolean; +} + // @public (undocumented) interface MutationStoreValue { // (undocumented) @@ -1218,8 +1206,8 @@ interface MutationStoreValue { // // @public (undocumented) type MutationTuple = ApolloCache> = [ -(options?: MutationFunctionOptions) => Promise>, -MutationResult +mutate: (options?: MutationFunctionOptions) => Promise>, +result: MutationResult ]; // @public (undocumented) @@ -1267,7 +1255,6 @@ class ObservableQuery; }); - // (undocumented) fetchMore(fetchMoreOptions: FetchMoreQueryOptions & { updateQuery?: (previousQueryResult: TData, options: { fetchMoreResult: TFetchData; @@ -1316,22 +1303,31 @@ class ObservableQuery | void>; // (undocumented) silentSetOptions(newOptions: Partial>): void; - // (undocumented) startPolling(pollInterval: number): void; - // (undocumented) stopPolling(): void; // Warning: (ae-forgotten-export) The symbol "SubscribeToMoreOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) subscribeToMore(options: SubscribeToMoreOptions): () => void; - // (undocumented) updateQuery(mapFn: (previousQueryResult: TData, options: Pick, "variables">) => TData): void; - // (undocumented) get variables(): TVariables | undefined; } // @public (undocumented) -type ObservableQueryFields = Pick, "startPolling" | "stopPolling" | "subscribeToMore" | "updateQuery" | "refetch" | "reobserve" | "variables" | "fetchMore">; +interface ObservableQueryFields { + fetchMore(fetchMoreOptions: FetchMoreQueryOptions & { + updateQuery?: (previousQueryResult: TData, options: { + fetchMoreResult: TFetchData; + variables: TFetchVars; + }) => TData; + }): Promise>; + refetch(variables?: Partial): Promise>; + // @internal (undocumented) + reobserve(newOptions?: Partial>, newNetworkStatus?: NetworkStatus): Promise>; + startPolling(pollInterval: number): void; + stopPolling(): void; + subscribeToMore(options: SubscribeToMoreOptions): () => void; + updateQuery(mapFn: (previousQueryResult: TData, options: Pick, "variables">) => TData): void; + variables: TVariables | undefined; +} // @public (undocumented) const OBSERVED_CHANGED_OPTIONS: readonly ["canonizeResults", "context", "errorPolicy", "fetchPolicy", "refetchWritePolicy", "returnPartialData"]; @@ -1411,17 +1407,12 @@ type PromiseWithState = PendingPromise | FulfilledPromise extends BaseQueryOptions { - // (undocumented) +interface QueryFunctionOptions extends BaseQueryOptions { + // @internal (undocumented) defaultOptions?: Partial>; - // (undocumented) onCompleted?: (data: TData) => void; - // (undocumented) onError?: (error: ApolloError) => void; - // (undocumented) skip?: boolean; } @@ -1625,14 +1616,13 @@ class QueryManager { // @public interface QueryOptions { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; context?: DefaultContext; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" fetchPolicy?: FetchPolicy; notifyOnNetworkStatusChange?: boolean; + // @deprecated partialRefetch?: boolean; pollInterval?: number; query: DocumentNode | TypedDocumentNode; @@ -1663,21 +1653,13 @@ type QueryRefPromise = PromiseWithState>; // // @public (undocumented) interface QueryResult extends ObservableQueryFields { - // (undocumented) called: boolean; - // (undocumented) client: ApolloClient; - // (undocumented) data: TData | undefined; - // (undocumented) error?: ApolloError; - // (undocumented) loading: boolean; - // (undocumented) networkStatus: NetworkStatus; - // (undocumented) observable: ObservableQuery; - // (undocumented) previousData?: TData; } @@ -1813,6 +1795,27 @@ type ServerParseError = Error & { bodyText: string; }; +// @public (undocumented) +interface SharedWatchQueryOptions { + // @deprecated + canonizeResults?: boolean; + context?: DefaultContext; + errorPolicy?: ErrorPolicy; + fetchPolicy?: WatchQueryFetchPolicy; + initialFetchPolicy?: WatchQueryFetchPolicy; + // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts + // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" + nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); + notifyOnNetworkStatusChange?: boolean; + // @deprecated + partialRefetch?: boolean; + pollInterval?: number; + refetchWritePolicy?: RefetchWritePolicy; + returnPartialData?: boolean; + skipPollAttempt?: () => boolean; + variables?: TVariables; +} + // @public (undocumented) interface SingleExecutionResult, TContext = DefaultContext, TExtensions = Record> extends ExecutionResult { // (undocumented) @@ -1872,7 +1875,6 @@ interface SubscriptionOptions { context?: DefaultContext; // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" fetchPolicy?: FetchPolicy; query: DocumentNode | TypedDocumentNode; variables?: TVariables; @@ -1880,13 +1882,10 @@ interface SubscriptionOptions { // @public (undocumented) interface SubscriptionResult { - // (undocumented) data?: TData; - // (undocumented) error?: ApolloError; - // (undocumented) loading: boolean; - // (undocumented) + // @internal (undocumented) variables?: TVariables; } @@ -1894,15 +1893,21 @@ interface SubscriptionResult { type SuspenseQueryHookFetchPolicy = Extract; // @public (undocumented) -interface SuspenseQueryHookOptions extends Pick, "client" | "variables" | "errorPolicy" | "context" | "canonizeResults" | "returnPartialData" | "refetchWritePolicy"> { +interface SuspenseQueryHookOptions { + // @deprecated + canonizeResults?: boolean; + // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ApolloClient" + client?: ApolloClient; + context?: DefaultContext; + errorPolicy?: ErrorPolicy; // Warning: (ae-forgotten-export) The symbol "SuspenseQueryHookFetchPolicy" needs to be exported by the entry point index.d.ts - // - // (undocumented) fetchPolicy?: SuspenseQueryHookFetchPolicy; - // (undocumented) queryKey?: string | number | any[]; + refetchWritePolicy?: RefetchWritePolicy; + returnPartialData?: boolean; // @deprecated skip?: boolean; + variables?: TVariables; } // @public (undocumented) @@ -2062,7 +2067,7 @@ export type UseFragmentResult = { // Warning: (ae-forgotten-export) The symbol "LazyQueryResultTuple" needs to be exported by the entry point index.d.ts // -// @public (undocumented) +// @public export function useLazyQuery(query: DocumentNode | TypedDocumentNode, options?: LazyQueryHookOptions, NoInfer>): LazyQueryResultTuple; // Warning: (ae-forgotten-export) The symbol "LoadableQueryHookOptions" needs to be exported by the entry point index.d.ts @@ -2103,10 +2108,10 @@ QueryReference | null, // Warning: (ae-forgotten-export) The symbol "MutationHookOptions" needs to be exported by the entry point index.d.ts // Warning: (ae-forgotten-export) The symbol "MutationTuple" needs to be exported by the entry point index.d.ts // -// @public (undocumented) +// @public export function useMutation = ApolloCache>(mutation: DocumentNode | TypedDocumentNode, options?: MutationHookOptions, NoInfer, TContext, TCache>): MutationTuple; -// @public (undocumented) +// @public export function useQuery(query: DocumentNode | TypedDocumentNode, options?: QueryHookOptions, NoInfer>): QueryResult; // @public @@ -2114,15 +2119,13 @@ export function useQueryRefHandlers { - // (undocumented) fetchMore: FetchMoreFunction; - refetch: RefetchFunction; } // Warning: (ae-forgotten-export) The symbol "ReactiveVar" needs to be exported by the entry point index.d.ts // -// @public (undocumented) +// @public export function useReactiveVar(rv: ReactiveVar): T; // @public (undocumented) @@ -2137,7 +2140,7 @@ export interface UseReadQueryResult { // Warning: (ae-forgotten-export) The symbol "SubscriptionHookOptions" needs to be exported by the entry point index.d.ts // -// @public (undocumented) +// @public export function useSubscription(subscription: DocumentNode | TypedDocumentNode, options?: SubscriptionHookOptions, NoInfer>): SubscriptionResult; // Warning: (ae-forgotten-export) The symbol "SuspenseQueryHookOptions" needs to be exported by the entry point index.d.ts @@ -2207,49 +2210,28 @@ export interface UseSuspenseQueryResult { - // @deprecated (undocumented) - canonizeResults?: boolean; - context?: DefaultContext; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" - errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" - fetchPolicy?: WatchQueryFetchPolicy; - initialFetchPolicy?: WatchQueryFetchPolicy; - // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" - nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); - notifyOnNetworkStatusChange?: boolean; - partialRefetch?: boolean; - pollInterval?: number; +interface WatchQueryOptions extends SharedWatchQueryOptions { query: DocumentNode | TypedDocumentNode; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "NetworkStatus" - refetchWritePolicy?: RefetchWritePolicy; - returnPartialData?: boolean; - skipPollAttempt?: () => boolean; - variables?: TVariables; } // Warnings were encountered during analysis: // -// src/cache/core/types/DataProxy.ts:153:5 - (ae-forgotten-export) The symbol "MissingFieldError" needs to be exported by the entry point index.d.ts +// src/cache/core/types/DataProxy.ts:146:7 - (ae-forgotten-export) The symbol "MissingFieldError" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:100:3 - (ae-forgotten-export) The symbol "ReadFieldFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:101:3 - (ae-forgotten-export) The symbol "CanReadFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:102:3 - (ae-forgotten-export) The symbol "isReference" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:103:3 - (ae-forgotten-export) The symbol "ToReferenceFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:104:3 - (ae-forgotten-export) The symbol "StorageType" needs to be exported by the entry point index.d.ts // src/core/LocalState.ts:46:5 - (ae-forgotten-export) The symbol "FragmentMap" needs to be exported by the entry point index.d.ts -// src/core/ObservableQuery.ts:113:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts -// src/core/ObservableQuery.ts:114:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts +// src/core/ObservableQuery.ts:116:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts +// src/core/ObservableQuery.ts:117:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:124:5 - (ae-forgotten-export) The symbol "MutationStoreValue" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:158:5 - (ae-forgotten-export) The symbol "LocalState" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:399:7 - (ae-forgotten-export) The symbol "UpdateQueries" needs to be exported by the entry point index.d.ts -// src/core/types.ts:154:3 - (ae-forgotten-export) The symbol "ApolloError" needs to be exported by the entry point index.d.ts -// src/core/types.ts:156:3 - (ae-forgotten-export) The symbol "NetworkStatus" needs to be exported by the entry point index.d.ts // src/core/types.ts:174:3 - (ae-forgotten-export) The symbol "MutationQueryReducer" needs to be exported by the entry point index.d.ts -// src/core/types.ts:201:5 - (ae-forgotten-export) The symbol "Resolver" needs to be exported by the entry point index.d.ts -// src/core/watchQueryOptions.ts:277:3 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts -// src/core/watchQueryOptions.ts:316:3 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts +// src/core/types.ts:203:5 - (ae-forgotten-export) The symbol "Resolver" needs to be exported by the entry point index.d.ts +// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts +// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts // src/react/hooks/useBackgroundQuery.ts:29:3 - (ae-forgotten-export) The symbol "FetchMoreFunction" needs to be exported by the entry point index.d.ts // src/react/hooks/useBackgroundQuery.ts:30:3 - (ae-forgotten-export) The symbol "RefetchFunction" needs to be exported by the entry point index.d.ts // src/react/hooks/useLoadableQuery.ts:49:5 - (ae-forgotten-export) The symbol "ResetFunction" needs to be exported by the entry point index.d.ts diff --git a/.api-reports/api-report-react_internal.md b/.api-reports/api-report-react_internal.md index 436e8e0cb73..258f0f992b9 100644 --- a/.api-reports/api-report-react_internal.md +++ b/.api-reports/api-report-react_internal.md @@ -285,14 +285,21 @@ class ApolloLink { } // @public (undocumented) -type ApolloQueryResult = { +interface ApolloQueryResult { + // (undocumented) data: T; - errors?: ReadonlyArray; + // Warning: (ae-forgotten-export) The symbol "ApolloError" needs to be exported by the entry point index.d.ts error?: ApolloError; + errors?: ReadonlyArray; + // (undocumented) loading: boolean; + // Warning: (ae-forgotten-export) The symbol "NetworkStatus" needs to be exported by the entry point index.d.ts + // + // (undocumented) networkStatus: NetworkStatus; + // (undocumented) partial?: boolean; -}; +} // @public type AsStoreObject extends Fragment { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; optimistic?: boolean; returnPartialData?: boolean; @@ -571,11 +578,8 @@ type DocumentTransformCacheKey = ReadonlyArray; // @public (undocumented) interface DocumentTransformOptions { - // (undocumented) cache?: boolean; // Warning: (ae-forgotten-export) The symbol "DocumentTransformCacheKey" needs to be exported by the entry point index.d.ts - // - // (undocumented) getCacheKey?: (document: DocumentNode) => DocumentTransformCacheKey | undefined; } @@ -629,9 +633,7 @@ type FetchMoreOptions = Parameters["fetchMore"]>[0 interface FetchMoreQueryOptions { // (undocumented) context?: DefaultContext; - // (undocumented) query?: DocumentNode | TypedDocumentNode; - // (undocumented) variables?: Partial; } @@ -968,7 +970,6 @@ interface MutationBaseOptions; @@ -977,7 +978,6 @@ interface MutationBaseOptions TData); refetchQueries?: ((result: FetchResult) => InternalRefetchQueriesInclude) | InternalRefetchQueriesInclude; // Warning: (ae-forgotten-export) The symbol "MutationUpdaterFunction" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ApolloCache" update?: MutationUpdaterFunction; // Warning: (ae-forgotten-export) The symbol "MutationQueryReducersMap" needs to be exported by the entry point index.d.ts // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "MutationQueryReducersMap" @@ -990,14 +990,10 @@ interface MutationBaseOptions; -// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts +// Warning: (ae-forgotten-export) The symbol "MutationSharedOptions" needs to be exported by the entry point index.d.ts // // @public (undocumented) -interface MutationOptions = ApolloCache> extends MutationBaseOptions { - // Warning: (ae-forgotten-export) The symbol "MutationFetchPolicy" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "MutationFetchPolicy" - fetchPolicy?: MutationFetchPolicy; - keepRootFields?: boolean; +interface MutationOptions = ApolloCache> extends MutationSharedOptions { mutation: DocumentNode | TypedDocumentNode; } @@ -1015,6 +1011,15 @@ type MutationQueryReducersMap; }; +// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts +// +// @public (undocumented) +interface MutationSharedOptions = ApolloCache> extends MutationBaseOptions { + // Warning: (ae-forgotten-export) The symbol "MutationFetchPolicy" needs to be exported by the entry point index.d.ts + fetchPolicy?: MutationFetchPolicy; + keepRootFields?: boolean; +} + // @public (undocumented) interface MutationStoreValue { // (undocumented) @@ -1072,8 +1077,6 @@ class ObservableQuery; }); // Warning: (ae-forgotten-export) The symbol "FetchMoreQueryOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) fetchMore(fetchMoreOptions: FetchMoreQueryOptions & { updateQuery?: (previousQueryResult: TData, options: { fetchMoreResult: TFetchData; @@ -1122,17 +1125,11 @@ class ObservableQuery | void>; // (undocumented) silentSetOptions(newOptions: Partial>): void; - // (undocumented) startPolling(pollInterval: number): void; - // (undocumented) stopPolling(): void; // Warning: (ae-forgotten-export) The symbol "SubscribeToMoreOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) subscribeToMore(options: SubscribeToMoreOptions): () => void; - // (undocumented) updateQuery(mapFn: (previousQueryResult: TData, options: Pick, "variables">) => TData): void; - // (undocumented) get variables(): TVariables | undefined; } @@ -1382,14 +1379,13 @@ class QueryManager { // @public interface QueryOptions { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; context?: DefaultContext; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" fetchPolicy?: FetchPolicy; notifyOnNetworkStatusChange?: boolean; + // @deprecated partialRefetch?: boolean; pollInterval?: number; query: DocumentNode | TypedDocumentNode; @@ -1524,6 +1520,28 @@ type ServerParseError = Error & { bodyText: string; }; +// @public (undocumented) +interface SharedWatchQueryOptions { + // @deprecated + canonizeResults?: boolean; + context?: DefaultContext; + errorPolicy?: ErrorPolicy; + fetchPolicy?: WatchQueryFetchPolicy; + initialFetchPolicy?: WatchQueryFetchPolicy; + // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts + // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" + nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); + notifyOnNetworkStatusChange?: boolean; + // @deprecated + partialRefetch?: boolean; + pollInterval?: number; + // Warning: (ae-forgotten-export) The symbol "RefetchWritePolicy" needs to be exported by the entry point index.d.ts + refetchWritePolicy?: RefetchWritePolicy; + returnPartialData?: boolean; + skipPollAttempt?: () => boolean; + variables?: TVariables; +} + // @public (undocumented) interface SingleExecutionResult, TContext = DefaultContext, TExtensions = Record> extends ExecutionResult { // (undocumented) @@ -1568,7 +1586,6 @@ interface SubscriptionOptions { context?: DefaultContext; // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" fetchPolicy?: FetchPolicy; query: DocumentNode | TypedDocumentNode; variables?: TVariables; @@ -1648,29 +1665,11 @@ interface UriFunction { // @public (undocumented) type WatchQueryFetchPolicy = FetchPolicy | "cache-and-network"; +// Warning: (ae-forgotten-export) The symbol "SharedWatchQueryOptions" needs to be exported by the entry point index.d.ts +// // @public -interface WatchQueryOptions { - // @deprecated (undocumented) - canonizeResults?: boolean; - context?: DefaultContext; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" - errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" - fetchPolicy?: WatchQueryFetchPolicy; - initialFetchPolicy?: WatchQueryFetchPolicy; - // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" - nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); - notifyOnNetworkStatusChange?: boolean; - partialRefetch?: boolean; - pollInterval?: number; +interface WatchQueryOptions extends SharedWatchQueryOptions { query: DocumentNode | TypedDocumentNode; - // Warning: (ae-forgotten-export) The symbol "RefetchWritePolicy" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "NetworkStatus" - refetchWritePolicy?: RefetchWritePolicy; - returnPartialData?: boolean; - skipPollAttempt?: () => boolean; - variables?: TVariables; } // @public (undocumented) @@ -1678,24 +1677,22 @@ export function wrapQueryRef(inter // Warnings were encountered during analysis: // -// src/cache/core/types/DataProxy.ts:153:5 - (ae-forgotten-export) The symbol "MissingFieldError" needs to be exported by the entry point index.d.ts +// src/cache/core/types/DataProxy.ts:146:7 - (ae-forgotten-export) The symbol "MissingFieldError" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:100:3 - (ae-forgotten-export) The symbol "ReadFieldFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:101:3 - (ae-forgotten-export) The symbol "CanReadFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:102:3 - (ae-forgotten-export) The symbol "isReference" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:103:3 - (ae-forgotten-export) The symbol "ToReferenceFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:104:3 - (ae-forgotten-export) The symbol "StorageType" needs to be exported by the entry point index.d.ts // src/core/LocalState.ts:46:5 - (ae-forgotten-export) The symbol "FragmentMap" needs to be exported by the entry point index.d.ts -// src/core/ObservableQuery.ts:113:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts -// src/core/ObservableQuery.ts:114:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts +// src/core/ObservableQuery.ts:116:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts +// src/core/ObservableQuery.ts:117:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:124:5 - (ae-forgotten-export) The symbol "MutationStoreValue" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:158:5 - (ae-forgotten-export) The symbol "LocalState" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:399:7 - (ae-forgotten-export) The symbol "UpdateQueries" needs to be exported by the entry point index.d.ts -// src/core/types.ts:154:3 - (ae-forgotten-export) The symbol "ApolloError" needs to be exported by the entry point index.d.ts -// src/core/types.ts:156:3 - (ae-forgotten-export) The symbol "NetworkStatus" needs to be exported by the entry point index.d.ts // src/core/types.ts:174:3 - (ae-forgotten-export) The symbol "MutationQueryReducer" needs to be exported by the entry point index.d.ts -// src/core/types.ts:201:5 - (ae-forgotten-export) The symbol "Resolver" needs to be exported by the entry point index.d.ts -// src/core/watchQueryOptions.ts:277:3 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts -// src/core/watchQueryOptions.ts:316:3 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts +// src/core/types.ts:203:5 - (ae-forgotten-export) The symbol "Resolver" needs to be exported by the entry point index.d.ts +// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts +// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts // (No @packageDocumentation comment for this package) diff --git a/.api-reports/api-report-react_ssr.md b/.api-reports/api-report-react_ssr.md index 16bf49666da..a6057e4a7eb 100644 --- a/.api-reports/api-report-react_ssr.md +++ b/.api-reports/api-report-react_ssr.md @@ -286,14 +286,21 @@ class ApolloLink { } // @public (undocumented) -type ApolloQueryResult = { +interface ApolloQueryResult { + // (undocumented) data: T; - errors?: ReadonlyArray; + // Warning: (ae-forgotten-export) The symbol "ApolloError" needs to be exported by the entry point index.d.ts error?: ApolloError; + errors?: ReadonlyArray; + // (undocumented) loading: boolean; + // Warning: (ae-forgotten-export) The symbol "NetworkStatus" needs to be exported by the entry point index.d.ts + // + // (undocumented) networkStatus: NetworkStatus; + // (undocumented) partial?: boolean; -}; +} // @public type AsStoreObject extends Omit, "query"> { +interface BaseQueryOptions extends SharedWatchQueryOptions { // Warning: (ae-forgotten-export) The symbol "ApolloClient" needs to be exported by the entry point index.d.ts - // - // (undocumented) + // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ApolloClient" client?: ApolloClient; - // (undocumented) context?: DefaultContext; - // (undocumented) ssr?: boolean; } @@ -476,7 +482,7 @@ namespace DataProxy { // // (undocumented) interface ReadFragmentOptions extends Fragment { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; optimistic?: boolean; returnPartialData?: boolean; @@ -577,11 +583,8 @@ type DocumentTransformCacheKey = ReadonlyArray; // @public (undocumented) interface DocumentTransformOptions { - // (undocumented) cache?: boolean; // Warning: (ae-forgotten-export) The symbol "DocumentTransformCacheKey" needs to be exported by the entry point index.d.ts - // - // (undocumented) getCacheKey?: (document: DocumentNode) => DocumentTransformCacheKey | undefined; } @@ -632,9 +635,7 @@ interface ExecutionPatchResultBase { interface FetchMoreQueryOptions { // (undocumented) context?: DefaultContext; - // (undocumented) query?: DocumentNode | TypedDocumentNode; - // (undocumented) variables?: Partial; } @@ -920,7 +921,6 @@ interface MutationBaseOptions; @@ -929,7 +929,6 @@ interface MutationBaseOptions TData); refetchQueries?: ((result: FetchResult) => InternalRefetchQueriesInclude) | InternalRefetchQueriesInclude; // Warning: (ae-forgotten-export) The symbol "MutationUpdaterFunction" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ApolloCache" update?: MutationUpdaterFunction; // Warning: (ae-forgotten-export) The symbol "MutationQueryReducersMap" needs to be exported by the entry point index.d.ts // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "MutationQueryReducersMap" @@ -942,14 +941,10 @@ interface MutationBaseOptions; -// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts +// Warning: (ae-forgotten-export) The symbol "MutationSharedOptions" needs to be exported by the entry point index.d.ts // // @public (undocumented) -interface MutationOptions = ApolloCache> extends MutationBaseOptions { - // Warning: (ae-forgotten-export) The symbol "MutationFetchPolicy" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "MutationFetchPolicy" - fetchPolicy?: MutationFetchPolicy; - keepRootFields?: boolean; +interface MutationOptions = ApolloCache> extends MutationSharedOptions { mutation: DocumentNode | TypedDocumentNode; } @@ -967,6 +962,15 @@ type MutationQueryReducersMap; }; +// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts +// +// @public (undocumented) +interface MutationSharedOptions = ApolloCache> extends MutationBaseOptions { + // Warning: (ae-forgotten-export) The symbol "MutationFetchPolicy" needs to be exported by the entry point index.d.ts + fetchPolicy?: MutationFetchPolicy; + keepRootFields?: boolean; +} + // @public (undocumented) interface MutationStoreValue { // (undocumented) @@ -1024,8 +1028,6 @@ class ObservableQuery; }); // Warning: (ae-forgotten-export) The symbol "FetchMoreQueryOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) fetchMore(fetchMoreOptions: FetchMoreQueryOptions & { updateQuery?: (previousQueryResult: TData, options: { fetchMoreResult: TFetchData; @@ -1074,22 +1076,31 @@ class ObservableQuery | void>; // (undocumented) silentSetOptions(newOptions: Partial>): void; - // (undocumented) startPolling(pollInterval: number): void; - // (undocumented) stopPolling(): void; // Warning: (ae-forgotten-export) The symbol "SubscribeToMoreOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) subscribeToMore(options: SubscribeToMoreOptions): () => void; - // (undocumented) updateQuery(mapFn: (previousQueryResult: TData, options: Pick, "variables">) => TData): void; - // (undocumented) get variables(): TVariables | undefined; } // @public (undocumented) -type ObservableQueryFields = Pick, "startPolling" | "stopPolling" | "subscribeToMore" | "updateQuery" | "refetch" | "reobserve" | "variables" | "fetchMore">; +interface ObservableQueryFields { + fetchMore(fetchMoreOptions: FetchMoreQueryOptions & { + updateQuery?: (previousQueryResult: TData, options: { + fetchMoreResult: TFetchData; + variables: TFetchVars; + }) => TData; + }): Promise>; + refetch(variables?: Partial): Promise>; + // @internal (undocumented) + reobserve(newOptions?: Partial>, newNetworkStatus?: NetworkStatus): Promise>; + startPolling(pollInterval: number): void; + stopPolling(): void; + subscribeToMore(options: SubscribeToMoreOptions): () => void; + updateQuery(mapFn: (previousQueryResult: TData, options: Pick, "variables">) => TData): void; + variables: TVariables | undefined; +} // @public (undocumented) type OnQueryUpdated = (observableQuery: ObservableQuery, diff: Cache_2.DiffResult, lastDiff: Cache_2.DiffResult | undefined) => boolean | TResult; @@ -1132,21 +1143,17 @@ interface QueryDataOptions) => ReactTypes.ReactNode; - // (undocumented) query: DocumentNode | TypedDocumentNode; } // Warning: (ae-forgotten-export) The symbol "BaseQueryOptions" needs to be exported by the entry point index.d.ts // // @public (undocumented) -interface QueryFunctionOptions extends BaseQueryOptions { - // (undocumented) +interface QueryFunctionOptions extends BaseQueryOptions { + // @internal (undocumented) defaultOptions?: Partial>; - // (undocumented) onCompleted?: (data: TData) => void; - // (undocumented) onError?: (error: ApolloError) => void; - // (undocumented) skip?: boolean; } @@ -1338,14 +1345,13 @@ class QueryManager { // @public interface QueryOptions { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; context?: DefaultContext; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" fetchPolicy?: FetchPolicy; notifyOnNetworkStatusChange?: boolean; + // @deprecated partialRefetch?: boolean; pollInterval?: number; query: DocumentNode | TypedDocumentNode; @@ -1357,21 +1363,13 @@ interface QueryOptions { // // @public (undocumented) interface QueryResult extends ObservableQueryFields { - // (undocumented) called: boolean; - // (undocumented) client: ApolloClient; - // (undocumented) data: TData | undefined; - // (undocumented) error?: ApolloError; - // (undocumented) loading: boolean; - // (undocumented) networkStatus: NetworkStatus; - // (undocumented) observable: ObservableQuery; - // (undocumented) previousData?: TData; } @@ -1501,6 +1499,28 @@ type ServerParseError = Error & { bodyText: string; }; +// @public (undocumented) +interface SharedWatchQueryOptions { + // @deprecated + canonizeResults?: boolean; + context?: DefaultContext; + errorPolicy?: ErrorPolicy; + fetchPolicy?: WatchQueryFetchPolicy; + initialFetchPolicy?: WatchQueryFetchPolicy; + // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts + // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" + nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); + notifyOnNetworkStatusChange?: boolean; + // @deprecated + partialRefetch?: boolean; + pollInterval?: number; + // Warning: (ae-forgotten-export) The symbol "RefetchWritePolicy" needs to be exported by the entry point index.d.ts + refetchWritePolicy?: RefetchWritePolicy; + returnPartialData?: boolean; + skipPollAttempt?: () => boolean; + variables?: TVariables; +} + // @public (undocumented) interface SingleExecutionResult, TContext = DefaultContext, TExtensions = Record> extends ExecutionResult { // (undocumented) @@ -1545,7 +1565,6 @@ interface SubscriptionOptions { context?: DefaultContext; // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" fetchPolicy?: FetchPolicy; query: DocumentNode | TypedDocumentNode; variables?: TVariables; @@ -1605,50 +1624,28 @@ interface UriFunction { type WatchQueryFetchPolicy = FetchPolicy | "cache-and-network"; // @public -interface WatchQueryOptions { - // @deprecated (undocumented) - canonizeResults?: boolean; - context?: DefaultContext; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" - errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" - fetchPolicy?: WatchQueryFetchPolicy; - initialFetchPolicy?: WatchQueryFetchPolicy; - // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" - nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); - notifyOnNetworkStatusChange?: boolean; - partialRefetch?: boolean; - pollInterval?: number; +interface WatchQueryOptions extends SharedWatchQueryOptions { query: DocumentNode | TypedDocumentNode; - // Warning: (ae-forgotten-export) The symbol "RefetchWritePolicy" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "NetworkStatus" - refetchWritePolicy?: RefetchWritePolicy; - returnPartialData?: boolean; - skipPollAttempt?: () => boolean; - variables?: TVariables; } // Warnings were encountered during analysis: // -// src/cache/core/types/DataProxy.ts:153:5 - (ae-forgotten-export) The symbol "MissingFieldError" needs to be exported by the entry point index.d.ts +// src/cache/core/types/DataProxy.ts:146:7 - (ae-forgotten-export) The symbol "MissingFieldError" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:100:3 - (ae-forgotten-export) The symbol "ReadFieldFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:101:3 - (ae-forgotten-export) The symbol "CanReadFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:102:3 - (ae-forgotten-export) The symbol "isReference" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:103:3 - (ae-forgotten-export) The symbol "ToReferenceFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:104:3 - (ae-forgotten-export) The symbol "StorageType" needs to be exported by the entry point index.d.ts // src/core/LocalState.ts:46:5 - (ae-forgotten-export) The symbol "FragmentMap" needs to be exported by the entry point index.d.ts -// src/core/ObservableQuery.ts:113:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts -// src/core/ObservableQuery.ts:114:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts +// src/core/ObservableQuery.ts:116:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts +// src/core/ObservableQuery.ts:117:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:124:5 - (ae-forgotten-export) The symbol "MutationStoreValue" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:158:5 - (ae-forgotten-export) The symbol "LocalState" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:399:7 - (ae-forgotten-export) The symbol "UpdateQueries" needs to be exported by the entry point index.d.ts -// src/core/types.ts:154:3 - (ae-forgotten-export) The symbol "ApolloError" needs to be exported by the entry point index.d.ts -// src/core/types.ts:156:3 - (ae-forgotten-export) The symbol "NetworkStatus" needs to be exported by the entry point index.d.ts // src/core/types.ts:174:3 - (ae-forgotten-export) The symbol "MutationQueryReducer" needs to be exported by the entry point index.d.ts -// src/core/types.ts:201:5 - (ae-forgotten-export) The symbol "Resolver" needs to be exported by the entry point index.d.ts -// src/core/watchQueryOptions.ts:277:3 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts -// src/core/watchQueryOptions.ts:316:3 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts +// src/core/types.ts:203:5 - (ae-forgotten-export) The symbol "Resolver" needs to be exported by the entry point index.d.ts +// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts +// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts // (No @packageDocumentation comment for this package) diff --git a/.api-reports/api-report-testing.md b/.api-reports/api-report-testing.md index 79404c0510e..5b4ae8e658b 100644 --- a/.api-reports/api-report-testing.md +++ b/.api-reports/api-report-testing.md @@ -286,14 +286,21 @@ class ApolloLink { } // @public (undocumented) -type ApolloQueryResult = { +interface ApolloQueryResult { + // (undocumented) data: T; - errors?: ReadonlyArray; + // Warning: (ae-forgotten-export) The symbol "ApolloError" needs to be exported by the entry point index.d.ts error?: ApolloError; + errors?: ReadonlyArray; + // (undocumented) loading: boolean; + // Warning: (ae-forgotten-export) The symbol "NetworkStatus" needs to be exported by the entry point index.d.ts + // + // (undocumented) networkStatus: NetworkStatus; + // (undocumented) partial?: boolean; -}; +} // @public type AsStoreObject extends Fragment { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; optimistic?: boolean; returnPartialData?: boolean; @@ -571,11 +578,8 @@ type DocumentTransformCacheKey = ReadonlyArray; // @public (undocumented) interface DocumentTransformOptions { - // (undocumented) cache?: boolean; // Warning: (ae-forgotten-export) The symbol "DocumentTransformCacheKey" needs to be exported by the entry point index.d.ts - // - // (undocumented) getCacheKey?: (document: DocumentNode) => DocumentTransformCacheKey | undefined; } @@ -626,9 +630,7 @@ interface ExecutionPatchResultBase { interface FetchMoreQueryOptions { // (undocumented) context?: DefaultContext; - // (undocumented) query?: DocumentNode | TypedDocumentNode; - // (undocumented) variables?: Partial; } @@ -1034,7 +1036,6 @@ interface MutationBaseOptions; @@ -1043,7 +1044,6 @@ interface MutationBaseOptions TData); refetchQueries?: ((result: FetchResult) => InternalRefetchQueriesInclude) | InternalRefetchQueriesInclude; // Warning: (ae-forgotten-export) The symbol "MutationUpdaterFunction" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ApolloCache" update?: MutationUpdaterFunction; // Warning: (ae-forgotten-export) The symbol "MutationQueryReducersMap" needs to be exported by the entry point index.d.ts // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "MutationQueryReducersMap" @@ -1056,14 +1056,10 @@ interface MutationBaseOptions; -// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts +// Warning: (ae-forgotten-export) The symbol "MutationSharedOptions" needs to be exported by the entry point index.d.ts // // @public (undocumented) -interface MutationOptions = ApolloCache> extends MutationBaseOptions { - // Warning: (ae-forgotten-export) The symbol "MutationFetchPolicy" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "MutationFetchPolicy" - fetchPolicy?: MutationFetchPolicy; - keepRootFields?: boolean; +interface MutationOptions = ApolloCache> extends MutationSharedOptions { mutation: DocumentNode | TypedDocumentNode; } @@ -1081,6 +1077,15 @@ type MutationQueryReducersMap; }; +// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts +// +// @public (undocumented) +interface MutationSharedOptions = ApolloCache> extends MutationBaseOptions { + // Warning: (ae-forgotten-export) The symbol "MutationFetchPolicy" needs to be exported by the entry point index.d.ts + fetchPolicy?: MutationFetchPolicy; + keepRootFields?: boolean; +} + // @public (undocumented) interface MutationStoreValue { // (undocumented) @@ -1148,8 +1153,6 @@ class ObservableQuery; }); // Warning: (ae-forgotten-export) The symbol "FetchMoreQueryOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) fetchMore(fetchMoreOptions: FetchMoreQueryOptions & { updateQuery?: (previousQueryResult: TData, options: { fetchMoreResult: TFetchData; @@ -1198,17 +1201,11 @@ class ObservableQuery | void>; // (undocumented) silentSetOptions(newOptions: Partial>): void; - // (undocumented) startPolling(pollInterval: number): void; - // (undocumented) stopPolling(): void; // Warning: (ae-forgotten-export) The symbol "SubscribeToMoreOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) subscribeToMore(options: SubscribeToMoreOptions): () => void; - // (undocumented) updateQuery(mapFn: (previousQueryResult: TData, options: Pick, "variables">) => TData): void; - // (undocumented) get variables(): TVariables | undefined; } @@ -1423,14 +1420,13 @@ class QueryManager { // @public interface QueryOptions { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; context?: DefaultContext; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" fetchPolicy?: FetchPolicy; notifyOnNetworkStatusChange?: boolean; + // @deprecated partialRefetch?: boolean; pollInterval?: number; query: DocumentNode | TypedDocumentNode; @@ -1542,6 +1538,28 @@ type ServerParseError = Error & { bodyText: string; }; +// @public (undocumented) +interface SharedWatchQueryOptions { + // @deprecated + canonizeResults?: boolean; + context?: DefaultContext; + errorPolicy?: ErrorPolicy; + fetchPolicy?: WatchQueryFetchPolicy; + initialFetchPolicy?: WatchQueryFetchPolicy; + // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts + // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" + nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); + notifyOnNetworkStatusChange?: boolean; + // @deprecated + partialRefetch?: boolean; + pollInterval?: number; + // Warning: (ae-forgotten-export) The symbol "RefetchWritePolicy" needs to be exported by the entry point index.d.ts + refetchWritePolicy?: RefetchWritePolicy; + returnPartialData?: boolean; + skipPollAttempt?: () => boolean; + variables?: TVariables; +} + // @public (undocumented) interface SingleExecutionResult, TContext = DefaultContext, TExtensions = Record> extends ExecutionResult { // (undocumented) @@ -1589,7 +1607,6 @@ interface SubscriptionOptions { context?: DefaultContext; // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" fetchPolicy?: FetchPolicy; query: DocumentNode | TypedDocumentNode; variables?: TVariables; @@ -1657,29 +1674,11 @@ export function wait(ms: number): Promise; // @public (undocumented) type WatchQueryFetchPolicy = FetchPolicy | "cache-and-network"; +// Warning: (ae-forgotten-export) The symbol "SharedWatchQueryOptions" needs to be exported by the entry point index.d.ts +// // @public -interface WatchQueryOptions { - // @deprecated (undocumented) - canonizeResults?: boolean; - context?: DefaultContext; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" - errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" - fetchPolicy?: WatchQueryFetchPolicy; - initialFetchPolicy?: WatchQueryFetchPolicy; - // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" - nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); - notifyOnNetworkStatusChange?: boolean; - partialRefetch?: boolean; - pollInterval?: number; +interface WatchQueryOptions extends SharedWatchQueryOptions { query: DocumentNode | TypedDocumentNode; - // Warning: (ae-forgotten-export) The symbol "RefetchWritePolicy" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "NetworkStatus" - refetchWritePolicy?: RefetchWritePolicy; - returnPartialData?: boolean; - skipPollAttempt?: () => boolean; - variables?: TVariables; } // @public @deprecated (undocumented) @@ -1693,24 +1692,22 @@ export function withWarningSpy(it: (...args: TArgs // Warnings were encountered during analysis: // -// src/cache/core/types/DataProxy.ts:153:5 - (ae-forgotten-export) The symbol "MissingFieldError" needs to be exported by the entry point index.d.ts +// src/cache/core/types/DataProxy.ts:146:7 - (ae-forgotten-export) The symbol "MissingFieldError" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:100:3 - (ae-forgotten-export) The symbol "ReadFieldFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:101:3 - (ae-forgotten-export) The symbol "CanReadFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:102:3 - (ae-forgotten-export) The symbol "isReference" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:103:3 - (ae-forgotten-export) The symbol "ToReferenceFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:104:3 - (ae-forgotten-export) The symbol "StorageType" needs to be exported by the entry point index.d.ts // src/core/LocalState.ts:46:5 - (ae-forgotten-export) The symbol "FragmentMap" needs to be exported by the entry point index.d.ts -// src/core/ObservableQuery.ts:113:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts -// src/core/ObservableQuery.ts:114:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts +// src/core/ObservableQuery.ts:116:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts +// src/core/ObservableQuery.ts:117:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:124:5 - (ae-forgotten-export) The symbol "MutationStoreValue" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:158:5 - (ae-forgotten-export) The symbol "LocalState" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:399:7 - (ae-forgotten-export) The symbol "UpdateQueries" needs to be exported by the entry point index.d.ts -// src/core/types.ts:154:3 - (ae-forgotten-export) The symbol "ApolloError" needs to be exported by the entry point index.d.ts -// src/core/types.ts:156:3 - (ae-forgotten-export) The symbol "NetworkStatus" needs to be exported by the entry point index.d.ts // src/core/types.ts:174:3 - (ae-forgotten-export) The symbol "MutationQueryReducer" needs to be exported by the entry point index.d.ts -// src/core/types.ts:201:5 - (ae-forgotten-export) The symbol "Resolver" needs to be exported by the entry point index.d.ts -// src/core/watchQueryOptions.ts:277:3 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts -// src/core/watchQueryOptions.ts:316:3 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts +// src/core/types.ts:203:5 - (ae-forgotten-export) The symbol "Resolver" needs to be exported by the entry point index.d.ts +// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts +// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts // (No @packageDocumentation comment for this package) diff --git a/.api-reports/api-report-testing_core.md b/.api-reports/api-report-testing_core.md index cee2394e945..202108f79c7 100644 --- a/.api-reports/api-report-testing_core.md +++ b/.api-reports/api-report-testing_core.md @@ -285,14 +285,21 @@ class ApolloLink { } // @public (undocumented) -type ApolloQueryResult = { +interface ApolloQueryResult { + // (undocumented) data: T; - errors?: ReadonlyArray; + // Warning: (ae-forgotten-export) The symbol "ApolloError" needs to be exported by the entry point index.d.ts error?: ApolloError; + errors?: ReadonlyArray; + // (undocumented) loading: boolean; + // Warning: (ae-forgotten-export) The symbol "NetworkStatus" needs to be exported by the entry point index.d.ts + // + // (undocumented) networkStatus: NetworkStatus; + // (undocumented) partial?: boolean; -}; +} // @public type AsStoreObject extends Fragment { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; optimistic?: boolean; returnPartialData?: boolean; @@ -570,11 +577,8 @@ type DocumentTransformCacheKey = ReadonlyArray; // @public (undocumented) interface DocumentTransformOptions { - // (undocumented) cache?: boolean; // Warning: (ae-forgotten-export) The symbol "DocumentTransformCacheKey" needs to be exported by the entry point index.d.ts - // - // (undocumented) getCacheKey?: (document: DocumentNode) => DocumentTransformCacheKey | undefined; } @@ -625,9 +629,7 @@ interface ExecutionPatchResultBase { interface FetchMoreQueryOptions { // (undocumented) context?: DefaultContext; - // (undocumented) query?: DocumentNode | TypedDocumentNode; - // (undocumented) variables?: Partial; } @@ -989,7 +991,6 @@ interface MutationBaseOptions; @@ -998,7 +999,6 @@ interface MutationBaseOptions TData); refetchQueries?: ((result: FetchResult) => InternalRefetchQueriesInclude) | InternalRefetchQueriesInclude; // Warning: (ae-forgotten-export) The symbol "MutationUpdaterFunction" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ApolloCache" update?: MutationUpdaterFunction; // Warning: (ae-forgotten-export) The symbol "MutationQueryReducersMap" needs to be exported by the entry point index.d.ts // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "MutationQueryReducersMap" @@ -1011,14 +1011,10 @@ interface MutationBaseOptions; -// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts +// Warning: (ae-forgotten-export) The symbol "MutationSharedOptions" needs to be exported by the entry point index.d.ts // // @public (undocumented) -interface MutationOptions = ApolloCache> extends MutationBaseOptions { - // Warning: (ae-forgotten-export) The symbol "MutationFetchPolicy" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "MutationFetchPolicy" - fetchPolicy?: MutationFetchPolicy; - keepRootFields?: boolean; +interface MutationOptions = ApolloCache> extends MutationSharedOptions { mutation: DocumentNode | TypedDocumentNode; } @@ -1036,6 +1032,15 @@ type MutationQueryReducersMap; }; +// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts +// +// @public (undocumented) +interface MutationSharedOptions = ApolloCache> extends MutationBaseOptions { + // Warning: (ae-forgotten-export) The symbol "MutationFetchPolicy" needs to be exported by the entry point index.d.ts + fetchPolicy?: MutationFetchPolicy; + keepRootFields?: boolean; +} + // @public (undocumented) interface MutationStoreValue { // (undocumented) @@ -1103,8 +1108,6 @@ class ObservableQuery; }); // Warning: (ae-forgotten-export) The symbol "FetchMoreQueryOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) fetchMore(fetchMoreOptions: FetchMoreQueryOptions & { updateQuery?: (previousQueryResult: TData, options: { fetchMoreResult: TFetchData; @@ -1153,17 +1156,11 @@ class ObservableQuery | void>; // (undocumented) silentSetOptions(newOptions: Partial>): void; - // (undocumented) startPolling(pollInterval: number): void; - // (undocumented) stopPolling(): void; // Warning: (ae-forgotten-export) The symbol "SubscribeToMoreOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) subscribeToMore(options: SubscribeToMoreOptions): () => void; - // (undocumented) updateQuery(mapFn: (previousQueryResult: TData, options: Pick, "variables">) => TData): void; - // (undocumented) get variables(): TVariables | undefined; } @@ -1380,14 +1377,13 @@ class QueryManager { // @public interface QueryOptions { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; context?: DefaultContext; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" fetchPolicy?: FetchPolicy; notifyOnNetworkStatusChange?: boolean; + // @deprecated partialRefetch?: boolean; pollInterval?: number; query: DocumentNode | TypedDocumentNode; @@ -1499,6 +1495,28 @@ type ServerParseError = Error & { bodyText: string; }; +// @public (undocumented) +interface SharedWatchQueryOptions { + // @deprecated + canonizeResults?: boolean; + context?: DefaultContext; + errorPolicy?: ErrorPolicy; + fetchPolicy?: WatchQueryFetchPolicy; + initialFetchPolicy?: WatchQueryFetchPolicy; + // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts + // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" + nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); + notifyOnNetworkStatusChange?: boolean; + // @deprecated + partialRefetch?: boolean; + pollInterval?: number; + // Warning: (ae-forgotten-export) The symbol "RefetchWritePolicy" needs to be exported by the entry point index.d.ts + refetchWritePolicy?: RefetchWritePolicy; + returnPartialData?: boolean; + skipPollAttempt?: () => boolean; + variables?: TVariables; +} + // @public (undocumented) interface SingleExecutionResult, TContext = DefaultContext, TExtensions = Record> extends ExecutionResult { // (undocumented) @@ -1546,7 +1564,6 @@ interface SubscriptionOptions { context?: DefaultContext; // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" fetchPolicy?: FetchPolicy; query: DocumentNode | TypedDocumentNode; variables?: TVariables; @@ -1614,29 +1631,11 @@ export function wait(ms: number): Promise; // @public (undocumented) type WatchQueryFetchPolicy = FetchPolicy | "cache-and-network"; +// Warning: (ae-forgotten-export) The symbol "SharedWatchQueryOptions" needs to be exported by the entry point index.d.ts +// // @public -interface WatchQueryOptions { - // @deprecated (undocumented) - canonizeResults?: boolean; - context?: DefaultContext; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" - errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" - fetchPolicy?: WatchQueryFetchPolicy; - initialFetchPolicy?: WatchQueryFetchPolicy; - // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" - nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); - notifyOnNetworkStatusChange?: boolean; - partialRefetch?: boolean; - pollInterval?: number; +interface WatchQueryOptions extends SharedWatchQueryOptions { query: DocumentNode | TypedDocumentNode; - // Warning: (ae-forgotten-export) The symbol "RefetchWritePolicy" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "NetworkStatus" - refetchWritePolicy?: RefetchWritePolicy; - returnPartialData?: boolean; - skipPollAttempt?: () => boolean; - variables?: TVariables; } // @public @deprecated (undocumented) @@ -1650,24 +1649,22 @@ export function withWarningSpy(it: (...args: TArgs // Warnings were encountered during analysis: // -// src/cache/core/types/DataProxy.ts:153:5 - (ae-forgotten-export) The symbol "MissingFieldError" needs to be exported by the entry point index.d.ts +// src/cache/core/types/DataProxy.ts:146:7 - (ae-forgotten-export) The symbol "MissingFieldError" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:100:3 - (ae-forgotten-export) The symbol "ReadFieldFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:101:3 - (ae-forgotten-export) The symbol "CanReadFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:102:3 - (ae-forgotten-export) The symbol "isReference" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:103:3 - (ae-forgotten-export) The symbol "ToReferenceFunction" needs to be exported by the entry point index.d.ts // src/cache/core/types/common.ts:104:3 - (ae-forgotten-export) The symbol "StorageType" needs to be exported by the entry point index.d.ts // src/core/LocalState.ts:46:5 - (ae-forgotten-export) The symbol "FragmentMap" needs to be exported by the entry point index.d.ts -// src/core/ObservableQuery.ts:113:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts -// src/core/ObservableQuery.ts:114:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts +// src/core/ObservableQuery.ts:116:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts +// src/core/ObservableQuery.ts:117:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:124:5 - (ae-forgotten-export) The symbol "MutationStoreValue" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:158:5 - (ae-forgotten-export) The symbol "LocalState" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:399:7 - (ae-forgotten-export) The symbol "UpdateQueries" needs to be exported by the entry point index.d.ts -// src/core/types.ts:154:3 - (ae-forgotten-export) The symbol "ApolloError" needs to be exported by the entry point index.d.ts -// src/core/types.ts:156:3 - (ae-forgotten-export) The symbol "NetworkStatus" needs to be exported by the entry point index.d.ts // src/core/types.ts:174:3 - (ae-forgotten-export) The symbol "MutationQueryReducer" needs to be exported by the entry point index.d.ts -// src/core/types.ts:201:5 - (ae-forgotten-export) The symbol "Resolver" needs to be exported by the entry point index.d.ts -// src/core/watchQueryOptions.ts:277:3 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts -// src/core/watchQueryOptions.ts:316:3 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts +// src/core/types.ts:203:5 - (ae-forgotten-export) The symbol "Resolver" needs to be exported by the entry point index.d.ts +// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts +// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts // (No @packageDocumentation comment for this package) diff --git a/.api-reports/api-report-utilities.md b/.api-reports/api-report-utilities.md index 5529eb18b85..715d0827a56 100644 --- a/.api-reports/api-report-utilities.md +++ b/.api-reports/api-report-utilities.md @@ -309,14 +309,21 @@ interface ApolloPayloadResult, TExtensions = Record< } // @public (undocumented) -type ApolloQueryResult = { +interface ApolloQueryResult { + // (undocumented) data: T; - errors?: ReadonlyArray; + // Warning: (ae-forgotten-export) The symbol "ApolloError" needs to be exported by the entry point index.d.ts error?: ApolloError; + errors?: ReadonlyArray; + // (undocumented) loading: boolean; + // Warning: (ae-forgotten-export) The symbol "NetworkStatus" needs to be exported by the entry point index.d.ts + // + // (undocumented) networkStatus: NetworkStatus; + // (undocumented) partial?: boolean; -}; +} // @public (undocumented) type ApolloReducerConfig = { @@ -606,7 +613,7 @@ namespace DataProxy { // // (undocumented) interface ReadFragmentOptions extends Fragment { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; optimistic?: boolean; returnPartialData?: boolean; @@ -815,9 +822,7 @@ export type DocumentTransformCacheKey = ReadonlyArray; // @public (undocumented) interface DocumentTransformOptions { - // (undocumented) cache?: boolean; - // (undocumented) getCacheKey?: (document: DocumentNode) => DocumentTransformCacheKey | undefined; } @@ -970,9 +975,7 @@ interface ExecutionPatchResultBase { interface FetchMoreQueryOptions { // (undocumented) context?: DefaultContext; - // (undocumented) query?: DocumentNode | TypedDocumentNode; - // (undocumented) variables?: Partial; } @@ -1675,7 +1678,6 @@ interface MutationBaseOptions; @@ -1684,7 +1686,6 @@ interface MutationBaseOptions TData); refetchQueries?: ((result: FetchResult) => InternalRefetchQueriesInclude) | InternalRefetchQueriesInclude; // Warning: (ae-forgotten-export) The symbol "MutationUpdaterFunction" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ApolloCache" update?: MutationUpdaterFunction; // Warning: (ae-forgotten-export) The symbol "MutationQueryReducersMap" needs to be exported by the entry point index.d.ts // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "MutationQueryReducersMap" @@ -1697,14 +1698,10 @@ interface MutationBaseOptions; -// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts +// Warning: (ae-forgotten-export) The symbol "MutationSharedOptions" needs to be exported by the entry point index.d.ts // // @public (undocumented) -interface MutationOptions = ApolloCache> extends MutationBaseOptions { - // Warning: (ae-forgotten-export) The symbol "MutationFetchPolicy" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "MutationFetchPolicy" - fetchPolicy?: MutationFetchPolicy; - keepRootFields?: boolean; +interface MutationOptions = ApolloCache> extends MutationSharedOptions { mutation: DocumentNode | TypedDocumentNode; } @@ -1722,6 +1719,15 @@ type MutationQueryReducersMap; }; +// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts +// +// @public (undocumented) +interface MutationSharedOptions = ApolloCache> extends MutationBaseOptions { + // Warning: (ae-forgotten-export) The symbol "MutationFetchPolicy" needs to be exported by the entry point index.d.ts + fetchPolicy?: MutationFetchPolicy; + keepRootFields?: boolean; +} + // @public (undocumented) interface MutationStoreValue { // (undocumented) @@ -1824,8 +1830,6 @@ class ObservableQuery; }); // Warning: (ae-forgotten-export) The symbol "FetchMoreQueryOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) fetchMore(fetchMoreOptions: FetchMoreQueryOptions & { updateQuery?: (previousQueryResult: TData, options: { fetchMoreResult: TFetchData; @@ -1872,17 +1876,11 @@ class ObservableQuery | void>; // (undocumented) silentSetOptions(newOptions: Partial>): void; - // (undocumented) startPolling(pollInterval: number): void; - // (undocumented) stopPolling(): void; // Warning: (ae-forgotten-export) The symbol "SubscribeToMoreOptions" needs to be exported by the entry point index.d.ts - // - // (undocumented) subscribeToMore(options: SubscribeToMoreOptions): () => void; - // (undocumented) updateQuery(mapFn: (previousQueryResult: TData, options: Pick, "variables">) => TData): void; - // (undocumented) get variables(): TVariables | undefined; } @@ -2185,14 +2183,13 @@ class QueryManager { // @public interface QueryOptions { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; context?: DefaultContext; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" fetchPolicy?: FetchPolicy; notifyOnNetworkStatusChange?: boolean; + // @deprecated partialRefetch?: boolean; pollInterval?: number; query: DocumentNode | TypedDocumentNode; @@ -2383,6 +2380,28 @@ type ServerParseError = Error & { bodyText: string; }; +// @public (undocumented) +interface SharedWatchQueryOptions { + // @deprecated + canonizeResults?: boolean; + context?: DefaultContext; + errorPolicy?: ErrorPolicy; + fetchPolicy?: WatchQueryFetchPolicy; + initialFetchPolicy?: WatchQueryFetchPolicy; + // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts + // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" + nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); + notifyOnNetworkStatusChange?: boolean; + // @deprecated + partialRefetch?: boolean; + pollInterval?: number; + // Warning: (ae-forgotten-export) The symbol "RefetchWritePolicy" needs to be exported by the entry point index.d.ts + refetchWritePolicy?: RefetchWritePolicy; + returnPartialData?: boolean; + skipPollAttempt?: () => boolean; + variables?: TVariables; +} + // @public (undocumented) export function shouldInclude({ directives }: SelectionNode, variables?: Record): boolean; @@ -2449,7 +2468,6 @@ interface SubscriptionOptions { context?: DefaultContext; // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" fetchPolicy?: FetchPolicy; query: DocumentNode | TypedDocumentNode; variables?: TVariables; @@ -2562,29 +2580,11 @@ export type VariableValue = (node: VariableNode) => any; // @public (undocumented) type WatchQueryFetchPolicy = FetchPolicy | "cache-and-network"; +// Warning: (ae-forgotten-export) The symbol "SharedWatchQueryOptions" needs to be exported by the entry point index.d.ts +// // @public -interface WatchQueryOptions { - // @deprecated (undocumented) - canonizeResults?: boolean; - context?: DefaultContext; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "ErrorPolicy" - errorPolicy?: ErrorPolicy; - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" - fetchPolicy?: WatchQueryFetchPolicy; - initialFetchPolicy?: WatchQueryFetchPolicy; - // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "FetchPolicy" - nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); - notifyOnNetworkStatusChange?: boolean; - partialRefetch?: boolean; - pollInterval?: number; +interface WatchQueryOptions extends SharedWatchQueryOptions { query: DocumentNode | TypedDocumentNode; - // Warning: (ae-forgotten-export) The symbol "RefetchWritePolicy" needs to be exported by the entry point index.d.ts - // Warning: (ae-unresolved-link) The @link reference could not be resolved: The package "@apollo/client" does not have an export "NetworkStatus" - refetchWritePolicy?: RefetchWritePolicy; - returnPartialData?: boolean; - skipPollAttempt?: () => boolean; - variables?: TVariables; } // @public (undocumented) @@ -2622,7 +2622,7 @@ interface WriteContext extends ReadMergeModifyContext { // Warnings were encountered during analysis: // -// src/cache/core/types/DataProxy.ts:153:5 - (ae-forgotten-export) The symbol "MissingFieldError" needs to be exported by the entry point index.d.ts +// src/cache/core/types/DataProxy.ts:146:7 - (ae-forgotten-export) The symbol "MissingFieldError" needs to be exported by the entry point index.d.ts // src/cache/inmemory/policies.ts:57:3 - (ae-forgotten-export) The symbol "TypePolicy" needs to be exported by the entry point index.d.ts // src/cache/inmemory/policies.ts:161:3 - (ae-forgotten-export) The symbol "KeySpecifier" needs to be exported by the entry point index.d.ts // src/cache/inmemory/policies.ts:161:3 - (ae-forgotten-export) The symbol "KeyArgsFunction" needs to be exported by the entry point index.d.ts @@ -2631,17 +2631,15 @@ interface WriteContext extends ReadMergeModifyContext { // src/cache/inmemory/types.ts:139:3 - (ae-forgotten-export) The symbol "KeyFieldsFunction" needs to be exported by the entry point index.d.ts // src/cache/inmemory/writeToStore.ts:65:7 - (ae-forgotten-export) The symbol "MergeTree" needs to be exported by the entry point index.d.ts // src/core/LocalState.ts:71:3 - (ae-forgotten-export) The symbol "ApolloClient" needs to be exported by the entry point index.d.ts -// src/core/ObservableQuery.ts:113:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts -// src/core/ObservableQuery.ts:114:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts +// src/core/ObservableQuery.ts:116:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts +// src/core/ObservableQuery.ts:117:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:124:5 - (ae-forgotten-export) The symbol "MutationStoreValue" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:158:5 - (ae-forgotten-export) The symbol "LocalState" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:399:7 - (ae-forgotten-export) The symbol "UpdateQueries" needs to be exported by the entry point index.d.ts -// src/core/types.ts:154:3 - (ae-forgotten-export) The symbol "ApolloError" needs to be exported by the entry point index.d.ts -// src/core/types.ts:156:3 - (ae-forgotten-export) The symbol "NetworkStatus" needs to be exported by the entry point index.d.ts // src/core/types.ts:174:3 - (ae-forgotten-export) The symbol "MutationQueryReducer" needs to be exported by the entry point index.d.ts -// src/core/types.ts:201:5 - (ae-forgotten-export) The symbol "Resolver" needs to be exported by the entry point index.d.ts -// src/core/watchQueryOptions.ts:277:3 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts -// src/core/watchQueryOptions.ts:316:3 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts +// src/core/types.ts:203:5 - (ae-forgotten-export) The symbol "Resolver" needs to be exported by the entry point index.d.ts +// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts +// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts // src/utilities/graphql/storeUtils.ts:226:12 - (ae-forgotten-export) The symbol "storeKeyNameStringify" needs to be exported by the entry point index.d.ts // src/utilities/policies/pagination.ts:76:3 - (ae-forgotten-export) The symbol "TRelayEdge" needs to be exported by the entry point index.d.ts // src/utilities/policies/pagination.ts:77:3 - (ae-forgotten-export) The symbol "TRelayPageInfo" needs to be exported by the entry point index.d.ts diff --git a/.api-reports/api-report.md b/.api-reports/api-report.md index c88a0d6b1e3..39d55033f88 100644 --- a/.api-reports/api-report.md +++ b/.api-reports/api-report.md @@ -289,14 +289,18 @@ interface ApolloProviderProps { } // @public (undocumented) -export type ApolloQueryResult = { +export interface ApolloQueryResult { + // (undocumented) data: T; - errors?: ReadonlyArray; error?: ApolloError; + errors?: ReadonlyArray; + // (undocumented) loading: boolean; + // (undocumented) networkStatus: NetworkStatus; + // (undocumented) partial?: boolean; -}; +} // @public (undocumented) export type ApolloReducerConfig = { @@ -327,53 +331,40 @@ export interface BackgroundQueryHookOptions = BackgroundQueryHookOptions, NoInfer>; +// Warning: (ae-forgotten-export) The symbol "MutationSharedOptions" needs to be exported by the entry point index.d.ts +// // @public (undocumented) -export interface BaseMutationOptions = ApolloCache> extends Omit, "mutation"> { - // (undocumented) +export interface BaseMutationOptions = ApolloCache> extends MutationSharedOptions { client?: ApolloClient; - // (undocumented) ignoreResults?: boolean; - // (undocumented) notifyOnNetworkStatusChange?: boolean; - // (undocumented) onCompleted?: (data: TData, clientOptions?: BaseMutationOptions) => void; - // (undocumented) onError?: (error: ApolloError, clientOptions?: BaseMutationOptions) => void; } +// Warning: (ae-forgotten-export) The symbol "SharedWatchQueryOptions" needs to be exported by the entry point index.d.ts +// // @public (undocumented) -export interface BaseQueryOptions extends Omit, "query"> { - // (undocumented) +export interface BaseQueryOptions extends SharedWatchQueryOptions { client?: ApolloClient; - // (undocumented) context?: DefaultContext; - // (undocumented) ssr?: boolean; } // @public (undocumented) export interface BaseSubscriptionOptions { - // (undocumented) client?: ApolloClient; - // (undocumented) context?: DefaultContext; - // (undocumented) fetchPolicy?: FetchPolicy; - // (undocumented) onComplete?: () => void; - // (undocumented) onData?: (options: OnDataOptions) => any; - // (undocumented) onError?: (error: ApolloError) => void; - // @deprecated (undocumented) + // @deprecated onSubscriptionComplete?: () => void; - // @deprecated (undocumented) + // @deprecated onSubscriptionData?: (options: OnSubscriptionDataOptions) => any; - // (undocumented) shouldResubscribe?: boolean | ((options: BaseSubscriptionOptions) => boolean); - // (undocumented) skip?: boolean; - // (undocumented) variables?: TVariables; } @@ -589,7 +580,7 @@ export namespace DataProxy { } // (undocumented) export interface ReadFragmentOptions extends Fragment { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; optimistic?: boolean; returnPartialData?: boolean; @@ -737,9 +728,7 @@ export type DocumentTransformCacheKey = ReadonlyArray; // @public (undocumented) interface DocumentTransformOptions { - // (undocumented) cache?: boolean; - // (undocumented) getCacheKey?: (document: DocumentNode) => DocumentTransformCacheKey | undefined; } @@ -934,9 +923,7 @@ type FetchMoreOptions_2 = Parameters["fetchMore"]> export interface FetchMoreQueryOptions { // (undocumented) context?: DefaultContext; - // (undocumented) query?: DocumentNode | TypedDocumentNode; - // (undocumented) variables?: Partial; } @@ -1458,14 +1445,21 @@ export interface LazyQueryHookExecOptions extends Omit, "skip"> { +export interface LazyQueryHookOptions extends BaseQueryOptions { + // @internal (undocumented) + defaultOptions?: Partial>; + onCompleted?: (data: TData) => void; + onError?: (error: ApolloError) => void; } // @public @deprecated (undocumented) export type LazyQueryResult = QueryResult; // @public (undocumented) -export type LazyQueryResultTuple = [LazyQueryExecFunction, QueryResult]; +export type LazyQueryResultTuple = [ +execute: LazyQueryExecFunction, +result: QueryResult +]; // @public (undocumented) type Listener = (promise: QueryRefPromise) => void; @@ -1475,7 +1469,7 @@ export type LoadableQueryHookFetchPolicy = Extract; context?: DefaultContext; @@ -1652,7 +1646,6 @@ export type MutationFunction = ApolloCache> extends BaseMutationOptions { - // (undocumented) mutation?: DocumentNode | TypedDocumentNode; } @@ -1660,12 +1653,8 @@ export interface MutationFunctionOptions = ApolloCache> extends BaseMutationOptions { } -// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts -// // @public (undocumented) -export interface MutationOptions = ApolloCache> extends MutationBaseOptions { - fetchPolicy?: MutationFetchPolicy; - keepRootFields?: boolean; +export interface MutationOptions = ApolloCache> extends MutationSharedOptions { mutation: DocumentNode | TypedDocumentNode; } @@ -1685,20 +1674,22 @@ export type MutationQueryReducersMap { - // (undocumented) called: boolean; - // (undocumented) client: ApolloClient; - // (undocumented) data?: TData | null; - // (undocumented) error?: ApolloError; - // (undocumented) loading: boolean; - // (undocumented) reset(): void; } +// Warning: (ae-forgotten-export) The symbol "MutationBaseOptions" needs to be exported by the entry point index.d.ts +// +// @public (undocumented) +interface MutationSharedOptions = ApolloCache> extends MutationBaseOptions { + fetchPolicy?: MutationFetchPolicy; + keepRootFields?: boolean; +} + // @public (undocumented) interface MutationStoreValue { // (undocumented) @@ -1713,11 +1704,11 @@ interface MutationStoreValue { // @public (undocumented) export type MutationTuple = ApolloCache> = [ -(options?: MutationFunctionOptions) => Promise>, -MutationResult +mutate: (options?: MutationFunctionOptions) => Promise>, +result: MutationResult ]; -// @public (undocumented) +// @public @deprecated (undocumented) export type MutationUpdaterFn = (cache: ApolloCache, mutationResult: FetchResult) => void; @@ -1812,7 +1803,6 @@ export class ObservableQuery; }); - // (undocumented) fetchMore(fetchMoreOptions: FetchMoreQueryOptions & { updateQuery?: (previousQueryResult: TData, options: { fetchMoreResult: TFetchData; @@ -1861,20 +1851,30 @@ export class ObservableQuery | void>; // (undocumented) silentSetOptions(newOptions: Partial>): void; - // (undocumented) startPolling(pollInterval: number): void; - // (undocumented) stopPolling(): void; - // (undocumented) subscribeToMore(options: SubscribeToMoreOptions): () => void; - // (undocumented) updateQuery(mapFn: (previousQueryResult: TData, options: Pick, "variables">) => TData): void; - // (undocumented) get variables(): TVariables | undefined; } // @public (undocumented) -export type ObservableQueryFields = Pick, "startPolling" | "stopPolling" | "subscribeToMore" | "updateQuery" | "refetch" | "reobserve" | "variables" | "fetchMore">; +export interface ObservableQueryFields { + fetchMore(fetchMoreOptions: FetchMoreQueryOptions & { + updateQuery?: (previousQueryResult: TData, options: { + fetchMoreResult: TFetchData; + variables: TFetchVars; + }) => TData; + }): Promise>; + refetch(variables?: Partial): Promise>; + // @internal (undocumented) + reobserve(newOptions?: Partial>, newNetworkStatus?: NetworkStatus): Promise>; + startPolling(pollInterval: number): void; + stopPolling(): void; + subscribeToMore(options: SubscribeToMoreOptions): () => void; + updateQuery(mapFn: (previousQueryResult: TData, options: Pick, "variables">) => TData): void; + variables: TVariables | undefined; +} export { ObservableSubscription } @@ -2094,19 +2094,15 @@ interface QueryData { export interface QueryDataOptions extends QueryFunctionOptions { // (undocumented) children?: (result: QueryResult) => ReactTypes.ReactNode; - // (undocumented) query: DocumentNode | TypedDocumentNode; } // @public (undocumented) -export interface QueryFunctionOptions extends BaseQueryOptions { - // (undocumented) +export interface QueryFunctionOptions extends BaseQueryOptions { + // @internal (undocumented) defaultOptions?: Partial>; - // (undocumented) onCompleted?: (data: TData) => void; - // (undocumented) onError?: (error: ApolloError) => void; - // (undocumented) skip?: boolean; } @@ -2179,9 +2175,7 @@ interface QueryKey { // @public @deprecated (undocumented) export interface QueryLazyOptions { - // (undocumented) context?: DefaultContext; - // (undocumented) variables?: TVariables; } @@ -2309,12 +2303,13 @@ class QueryManager { // @public interface QueryOptions { - // @deprecated (undocumented) + // @deprecated canonizeResults?: boolean; context?: DefaultContext; errorPolicy?: ErrorPolicy; fetchPolicy?: FetchPolicy; notifyOnNetworkStatusChange?: boolean; + // @deprecated partialRefetch?: boolean; pollInterval?: number; query: DocumentNode | TypedDocumentNode; @@ -2345,21 +2340,13 @@ type QueryRefPromise = PromiseWithState>; // @public (undocumented) export interface QueryResult extends ObservableQueryFields { - // (undocumented) called: boolean; - // (undocumented) client: ApolloClient; - // (undocumented) data: TData | undefined; - // (undocumented) error?: ApolloError; - // (undocumented) loading: boolean; - // (undocumented) networkStatus: NetworkStatus; - // (undocumented) observable: ObservableQuery; - // (undocumented) previousData?: TData; } @@ -2573,6 +2560,26 @@ export type ServerParseError = Error & { export { setLogVerbosity } +// @public (undocumented) +interface SharedWatchQueryOptions { + // @deprecated + canonizeResults?: boolean; + context?: DefaultContext; + errorPolicy?: ErrorPolicy; + fetchPolicy?: WatchQueryFetchPolicy; + initialFetchPolicy?: WatchQueryFetchPolicy; + // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts + nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); + notifyOnNetworkStatusChange?: boolean; + // @deprecated + partialRefetch?: boolean; + pollInterval?: number; + refetchWritePolicy?: RefetchWritePolicy; + returnPartialData?: boolean; + skipPollAttempt?: () => boolean; + variables?: TVariables; +} + // @public (undocumented) export interface SingleExecutionResult, TContext = DefaultContext, TExtensions = Record> extends ExecutionResult { // (undocumented) @@ -2664,13 +2671,10 @@ export interface SubscriptionOptions { - // (undocumented) data?: TData; - // (undocumented) error?: ApolloError; - // (undocumented) loading: boolean; - // (undocumented) + // @internal (undocumented) variables?: TVariables; } @@ -2678,13 +2682,19 @@ export interface SubscriptionResult { export type SuspenseQueryHookFetchPolicy = Extract; // @public (undocumented) -export interface SuspenseQueryHookOptions extends Pick, "client" | "variables" | "errorPolicy" | "context" | "canonizeResults" | "returnPartialData" | "refetchWritePolicy"> { - // (undocumented) +export interface SuspenseQueryHookOptions { + // @deprecated + canonizeResults?: boolean; + client?: ApolloClient; + context?: DefaultContext; + errorPolicy?: ErrorPolicy; fetchPolicy?: SuspenseQueryHookFetchPolicy; - // (undocumented) queryKey?: string | number | any[]; + refetchWritePolicy?: RefetchWritePolicy; + returnPartialData?: boolean; // @deprecated skip?: boolean; + variables?: TVariables; } // @public (undocumented) @@ -2872,7 +2882,7 @@ export type UseFragmentResult = { missing?: MissingTree; }; -// @public (undocumented) +// @public export function useLazyQuery(query: DocumentNode | TypedDocumentNode, options?: LazyQueryHookOptions, NoInfer>): LazyQueryResultTuple; // @public (undocumented) @@ -2908,10 +2918,10 @@ QueryReference | null, } ]; -// @public (undocumented) +// @public export function useMutation = ApolloCache>(mutation: DocumentNode | TypedDocumentNode, options?: MutationHookOptions, NoInfer, TContext, TCache>): MutationTuple; -// @public (undocumented) +// @public export function useQuery(query: DocumentNode | TypedDocumentNode, options?: QueryHookOptions, NoInfer>): QueryResult; // @public @@ -2919,13 +2929,11 @@ export function useQueryRefHandlers { - // (undocumented) fetchMore: FetchMoreFunction; - refetch: RefetchFunction; } -// @public (undocumented) +// @public export function useReactiveVar(rv: ReactiveVar): T; // @public (undocumented) @@ -2938,7 +2946,7 @@ export interface UseReadQueryResult { networkStatus: NetworkStatus; } -// @public (undocumented) +// @public export function useSubscription(subscription: DocumentNode | TypedDocumentNode, options?: SubscriptionHookOptions, NoInfer>): SubscriptionResult; // @public (undocumented) @@ -3017,23 +3025,8 @@ TVariables export type WatchQueryFetchPolicy = FetchPolicy | "cache-and-network"; // @public -export interface WatchQueryOptions { - // @deprecated (undocumented) - canonizeResults?: boolean; - context?: DefaultContext; - errorPolicy?: ErrorPolicy; - fetchPolicy?: WatchQueryFetchPolicy; - initialFetchPolicy?: WatchQueryFetchPolicy; - // Warning: (ae-forgotten-export) The symbol "NextFetchPolicyContext" needs to be exported by the entry point index.d.ts - nextFetchPolicy?: WatchQueryFetchPolicy | ((this: WatchQueryOptions, currentFetchPolicy: WatchQueryFetchPolicy, context: NextFetchPolicyContext) => WatchQueryFetchPolicy); - notifyOnNetworkStatusChange?: boolean; - partialRefetch?: boolean; - pollInterval?: number; +export interface WatchQueryOptions extends SharedWatchQueryOptions { query: DocumentNode | TypedDocumentNode; - refetchWritePolicy?: RefetchWritePolicy; - returnPartialData?: boolean; - skipPollAttempt?: () => boolean; - variables?: TVariables; } // @public (undocumented) @@ -3074,13 +3067,13 @@ interface WriteContext extends ReadMergeModifyContext { // src/cache/inmemory/policies.ts:161:3 - (ae-forgotten-export) The symbol "KeySpecifier" needs to be exported by the entry point index.d.ts // src/cache/inmemory/policies.ts:161:3 - (ae-forgotten-export) The symbol "KeyArgsFunction" needs to be exported by the entry point index.d.ts // src/cache/inmemory/types.ts:139:3 - (ae-forgotten-export) The symbol "KeyFieldsFunction" needs to be exported by the entry point index.d.ts -// src/core/ObservableQuery.ts:113:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts -// src/core/ObservableQuery.ts:114:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts +// src/core/ObservableQuery.ts:116:5 - (ae-forgotten-export) The symbol "QueryManager" needs to be exported by the entry point index.d.ts +// src/core/ObservableQuery.ts:117:5 - (ae-forgotten-export) The symbol "QueryInfo" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:124:5 - (ae-forgotten-export) The symbol "MutationStoreValue" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:158:5 - (ae-forgotten-export) The symbol "LocalState" needs to be exported by the entry point index.d.ts // src/core/QueryManager.ts:399:7 - (ae-forgotten-export) The symbol "UpdateQueries" needs to be exported by the entry point index.d.ts -// src/core/watchQueryOptions.ts:277:3 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts -// src/core/watchQueryOptions.ts:316:3 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts +// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "IgnoreModifier" needs to be exported by the entry point index.d.ts +// src/core/watchQueryOptions.ts:269:2 - (ae-forgotten-export) The symbol "UpdateQueryFn" needs to be exported by the entry point index.d.ts // src/link/http/selectHttpOptionsAndBody.ts:128:32 - (ae-forgotten-export) The symbol "HttpQueryOptions" needs to be exported by the entry point index.d.ts // src/react/hooks/useBackgroundQuery.ts:29:3 - (ae-forgotten-export) The symbol "FetchMoreFunction" needs to be exported by the entry point index.d.ts // src/react/hooks/useBackgroundQuery.ts:30:3 - (ae-forgotten-export) The symbol "RefetchFunction" needs to be exported by the entry point index.d.ts diff --git a/api-extractor.json b/api-extractor.json index b257d21f772..d026e304ed8 100644 --- a/api-extractor.json +++ b/api-extractor.json @@ -128,13 +128,12 @@ "logLevel": "warning", "addToApiReportFile": true } + }, + "tsdocMessageReporting": { + "tsdoc-escape-greater-than": { + "logLevel": "none", + "addToApiReportFile": false + } } - - // "ae-extra-release-tag": { - // "logLevel": "warning", - // "addToApiReportFile": true - // }, - // - // . . . } } diff --git a/config/apiExtractor.ts b/config/apiExtractor.ts index f64b0d7b525..b902353a14c 100644 --- a/config/apiExtractor.ts +++ b/config/apiExtractor.ts @@ -9,7 +9,7 @@ import { parseArgs } from "node:util"; import fs from "node:fs"; // @ts-ignore -import { map } from "./entryPoints.js"; +import { map, buildDocEntryPoints } from "./entryPoints.js"; import { readFileSync } from "fs"; const parsed = parseArgs({ @@ -47,12 +47,8 @@ try { console.log( "\n\nCreating API extractor docmodel for the a combination of all entry points" ); - const dist = path.resolve(__dirname, "../dist"); - const entryPoints = map((entryPoint: { dirs: string[] }) => { - return `export * from "${dist}/${entryPoint.dirs.join("/")}/index.d.ts";`; - }).join("\n"); const entryPointFile = path.join(tempDir, "entry.d.ts"); - fs.writeFileSync(entryPointFile, entryPoints); + fs.writeFileSync(entryPointFile, buildDocEntryPoints()); buildReport(entryPointFile, "docModel"); } diff --git a/config/entryPoints.js b/config/entryPoints.js index 896f87acf9f..cad194d61aa 100644 --- a/config/entryPoints.js +++ b/config/entryPoints.js @@ -126,3 +126,14 @@ function arraysEqualUpTo(a, b, end) { } return true; } + +exports.buildDocEntryPoints = () => { + const dist = path.resolve(__dirname, "../dist"); + const entryPoints = exports.map((entryPoint) => { + return `export * from "${dist}/${entryPoint.dirs.join("/")}/index.d.ts";`; + }); + entryPoints.push( + `export * from "${dist}/react/types/types.documentation.ts";` + ); + return entryPoints.join("\n"); +}; diff --git a/config/inlineInheritDoc.ts b/config/inlineInheritDoc.ts index 5c94a53363c..704054f28ec 100644 --- a/config/inlineInheritDoc.ts +++ b/config/inlineInheritDoc.ts @@ -23,10 +23,13 @@ */ /** End file docs */ +// @ts-ignore +import { buildDocEntryPoints } from "./entryPoints.js"; // @ts-ignore import { Project, ts, printNode, Node } from "ts-morph"; import { ApiModel, ApiDocumentedItem } from "@microsoft/api-extractor-model"; import { DeclarationReference } from "@microsoft/tsdoc/lib-commonjs/beta/DeclarationReference"; +import { StringBuilder, TSDocEmitter } from "@microsoft/tsdoc"; import fs from "node:fs"; import path from "node:path"; @@ -53,7 +56,12 @@ function getCommentFor(canonicalReference: string) { `Could not resolve canonical reference "${canonicalReference}"` ); if (apiItem instanceof ApiDocumentedItem) { - return apiItem.tsdocComment?.emitAsTsdoc(); + if (!apiItem.tsdocComment) return ""; + const stringBuilder = new StringBuilder(); + const emitter = new TSDocEmitter(); + emitter["_emitCommentFraming"] = false; + emitter["_renderCompleteObject"](stringBuilder, apiItem.tsdocComment); + return stringBuilder.toString(); } else { throw new Error( `"${canonicalReference}" is not documented, so no documentation can be inherited.` @@ -64,6 +72,9 @@ function getCommentFor(canonicalReference: string) { function loadApiModel() { const tempDir = fs.mkdtempSync("api-model"); try { + const entryPointFile = path.join(tempDir, "entry.d.ts"); + fs.writeFileSync(entryPointFile, buildDocEntryPoints()); + // Load and parse the api-extractor.json file const configObjectFullPath = path.resolve( __dirname, @@ -73,6 +84,7 @@ function loadApiModel() { const tempModelFile = path.join(tempDir, "client.api.json"); const configObject = ExtractorConfig.loadFile(configObjectFullPath); + configObject.mainEntryPointFilePath = entryPointFile; configObject.docModel = { ...configObject.docModel, enabled: true, @@ -136,17 +148,24 @@ function processComments() { const docsNode = node.getJsDocs()[0]; if (!docsNode) return; const oldText = docsNode.getInnerText(); - const newText = oldText.replace( - inheritDocRegex, - (_, canonicalReference) => { - return getCommentFor(canonicalReference) || ""; - } - ); + let newText = oldText; + while (inheritDocRegex.test(newText)) { + newText = newText.replace( + inheritDocRegex, + (_, canonicalReference) => { + return getCommentFor(canonicalReference) || ""; + } + ); + } if (oldText !== newText) { - docsNode.replaceWithText(newText); + docsNode.replaceWithText(frameComment(newText)) as any; } } }); file.saveSync(); } } + +function frameComment(text: string) { + return `/**\n * ${text.trim().replace(/\n/g, "\n * ")}\n */`; +} diff --git a/docs/shared/ApiDoc/DocBlock.js b/docs/shared/ApiDoc/DocBlock.js index 157ece36fdc..18e29d26d19 100644 --- a/docs/shared/ApiDoc/DocBlock.js +++ b/docs/shared/ApiDoc/DocBlock.js @@ -1,27 +1,24 @@ import PropTypes from "prop-types"; import React from "react"; import { Stack } from "@chakra-ui/react"; -import { mdToReact } from "./mdToReact"; import { useApiDocContext } from "."; +import { useMDXComponents } from "@mdx-js/react"; export function DocBlock({ canonicalReference, summary = true, remarks = false, example = false, - remarkCollapsible = true, - since = true, - deprecated = true, + remarksCollapsible = false, + deprecated = false, }) { return ( - {/** TODO: @since, @deprecated etc. */} {deprecated && } - {since && } {summary && } {remarks && ( )} @@ -35,8 +32,7 @@ DocBlock.propTypes = { summary: PropTypes.bool, remarks: PropTypes.bool, example: PropTypes.bool, - remarkCollapsible: PropTypes.bool, - since: PropTypes.bool, + remarksCollapsible: PropTypes.bool, deprecated: PropTypes.bool, }; @@ -57,17 +53,18 @@ MaybeCollapsible.propTypes = { children: PropTypes.node, }; -/** - * Might still need more work on the Gatsby side to get this to work. - */ export function Deprecated({ canonicalReference, collapsible = false }) { const getItem = useApiDocContext(); const item = getItem(canonicalReference); + const MDX = useMDXComponents(); const value = item.comment?.deprecated; if (!value) return null; return ( - {mdToReact(value)} + +

⚠️ Deprecated

+ {value} + ); } @@ -76,33 +73,15 @@ Deprecated.propTypes = { collapsible: PropTypes.bool, }; -/** - * Might still need more work on the Gatsby side to get this to work. - */ -export function Since({ canonicalReference, collapsible = false }) { - const getItem = useApiDocContext(); - const item = getItem(canonicalReference); - const value = item.comment?.since; - if (!value) return null; - return ( - - Added to Apollo Client in version {value} - - ); -} -Since.propTypes = { - canonicalReference: PropTypes.string.isRequired, - collapsible: PropTypes.bool, -}; - export function Summary({ canonicalReference, collapsible = false }) { const getItem = useApiDocContext(); const item = getItem(canonicalReference); + const MDX = useMDXComponents(); const value = item.comment?.summary; if (!value) return null; return ( - {mdToReact(value)} + {value && {value}} ); } @@ -114,11 +93,12 @@ Summary.propTypes = { export function Remarks({ canonicalReference, collapsible = false }) { const getItem = useApiDocContext(); const item = getItem(canonicalReference); + const MDX = useMDXComponents(); const value = item.comment?.remarks?.replace(/^@remarks/g, ""); if (!value) return null; return ( - {mdToReact(value)} + {value && {value}} ); } @@ -134,12 +114,15 @@ export function Example({ }) { const getItem = useApiDocContext(); const item = getItem(canonicalReference); + const MDX = useMDXComponents(); const value = item.comment?.examples[index]; if (!value) return null; return ( - - {mdToReact(value)} - + <> + + {value && {value}} + + ); } Example.propTypes = { diff --git a/docs/shared/ApiDoc/EnumDetails.js b/docs/shared/ApiDoc/EnumDetails.js new file mode 100644 index 00000000000..a0f7966f55e --- /dev/null +++ b/docs/shared/ApiDoc/EnumDetails.js @@ -0,0 +1,72 @@ +import { useMDXComponents } from "@mdx-js/react"; + +import PropTypes from "prop-types"; +import React, { useMemo } from "react"; +import { DocBlock, useApiDocContext, ApiDocHeading, SectionHeading } from "."; +import { GridItem, Text } from "@chakra-ui/react"; +import { ResponsiveGrid } from "./ResponsiveGrid"; +import { sortWithCustomOrder } from "./sortWithCustomOrder"; + +export function EnumDetails({ + canonicalReference, + headingLevel, + customOrder = [], +}) { + const getItem = useApiDocContext(); + const item = getItem(canonicalReference); + + const sortedMembers = useMemo( + () => item.members.map(getItem).sort(sortWithCustomOrder(customOrder)), + [item.members, getItem, customOrder] + ); + + return ( + <> + + + + + Enumeration Members + + + + {sortedMembers.map((member) => ( + + + + + ))} + + + ); +} + +EnumDetails.propTypes = { + canonicalReference: PropTypes.string.isRequired, + headingLevel: PropTypes.number.isRequired, + customOrder: PropTypes.arrayOf(PropTypes.string), +}; diff --git a/docs/shared/ApiDoc/Function.js b/docs/shared/ApiDoc/Function.js index 97cb0934ce8..7cf0e8cbc3d 100644 --- a/docs/shared/ApiDoc/Function.js +++ b/docs/shared/ApiDoc/Function.js @@ -1,34 +1,55 @@ import PropTypes from "prop-types"; import React from "react"; -import { ApiDocHeading, DocBlock, ParameterTable, useApiDocContext } from "."; - +import { useMDXComponents } from "@mdx-js/react"; +import { + ApiDocHeading, + SubHeading, + DocBlock, + ParameterTable, + useApiDocContext, + PropertySignatureTable, + SourceLink, + Example, + getInterfaceReference, +} from "."; +import { GridItem } from "@chakra-ui/react"; export function FunctionSignature({ canonicalReference, parameterTypes = false, name = true, arrow = false, + highlight = false, }) { + const MDX = useMDXComponents(); const getItem = useApiDocContext(); const { displayName, parameters, returnType } = getItem(canonicalReference); - return ( - <> - {name ? displayName : ""}( - {parameters - .map((p) => { - let pStr = p.name; - if (p.optional) { - pStr += "?"; - } - if (parameterTypes) { - pStr += ": " + p.type; - } - return pStr; - }) - .join(", ")} - ){arrow ? " =>" : ":"} {returnType} - - ); + let paramSignature = parameters + .map((p) => { + let pStr = p.name; + if (p.optional) { + pStr += "?"; + } + if (parameterTypes) { + pStr += ": " + p.type; + } + return pStr; + }) + .join(",\n "); + + if (paramSignature) { + paramSignature = "\n " + paramSignature + "\n"; + } + + const signature = `${arrow ? "" : "function "}${ + name ? displayName : "" + }(${paramSignature})${arrow ? " =>" : ":"} ${returnType}`; + + return highlight ? + + {signature} + + : signature; } FunctionSignature.propTypes = { @@ -36,29 +57,109 @@ FunctionSignature.propTypes = { parameterTypes: PropTypes.bool, name: PropTypes.bool, arrow: PropTypes.bool, + highlight: PropTypes.bool, +}; + +export function ReturnType({ canonicalReference }) { + const MDX = useMDXComponents(); + const getItem = useApiDocContext(); + const item = getItem(canonicalReference); + + const interfaceReference = getInterfaceReference( + item.returnType, + item, + getItem + ); + return ( + <> + {item.comment?.returns} + + {item.returnType} + + {interfaceReference ? +
+ + Show/hide child attributes + + +
+ : null} + + ); +} +ReturnType.propTypes = { + canonicalReference: PropTypes.string.isRequired, }; export function FunctionDetails({ canonicalReference, customParameterOrder, headingLevel, + result, }) { + const getItem = useApiDocContext(); + const item = getItem(canonicalReference); return ( <> - + {item.comment?.examples.length == 0 ? null : ( + <> + + Example + + + + )} + - + Signature + + + + {item.parameters.length == 0 ? null : ( + <> + + Parameters + + + + )} + {( + result === false || (result === undefined && item.returnType === "void") + ) ? + null + : <> + + Result + + {result || } + } ); } @@ -67,4 +168,5 @@ FunctionDetails.propTypes = { canonicalReference: PropTypes.string.isRequired, headingLevel: PropTypes.number.isRequired, customParameterOrder: PropTypes.arrayOf(PropTypes.string), + result: PropTypes.oneOfType([PropTypes.bool, PropTypes.node]), }; diff --git a/docs/shared/ApiDoc/Heading.js b/docs/shared/ApiDoc/Heading.js index e4a5aa9db69..fea39f5c9f4 100644 --- a/docs/shared/ApiDoc/Heading.js +++ b/docs/shared/ApiDoc/Heading.js @@ -1,67 +1,117 @@ import { useMDXComponents } from "@mdx-js/react"; import PropTypes from "prop-types"; import React from "react"; -import { Box, Heading } from "@chakra-ui/react"; +import { Box, Text } from "@chakra-ui/react"; import { FunctionSignature } from "."; import { useApiDocContext } from "./Context"; -const levels = { - 2: "xl", - 3: "lg", - 4: "md", - 5: "sm", - 6: "xs", +export function Heading({ headingLevel, children, as, minVersion, ...props }) { + const MDX = useMDXComponents(); + let heading = children; + + if (as != undefined && headingLevel != undefined) { + throw new Error( + "Heading: Cannot specify both `as` and `headingLevel` at the same time." + ); + } + const Tag = as ? as : MDX[`h${headingLevel}`]; + + return ( + + {heading} + {minVersion ? + + : null} + + ); +} +Heading.propTypes = { + headingLevel: PropTypes.number, + children: PropTypes.node.isRequired, + id: PropTypes.string, + as: PropTypes.any, + minVersion: PropTypes.string, +}; + +export function SubHeading({ canonicalReference, headingLevel, ...props }) { + const getItem = useApiDocContext(); + const item = getItem(canonicalReference); + + return ( + + ); +} +SubHeading.propTypes = { + ...Heading.propTypes, + canonicalReference: PropTypes.string.isRequired, }; export function ApiDocHeading({ canonicalReference, headingLevel, - link = true, + signature = false, + since = false, + prefix = "", + suffix = "", + ...props }) { const MDX = useMDXComponents(); const getItem = useApiDocContext(); const item = getItem(canonicalReference); - const heading = + let heading = ( - item.kind === "MethodSignature" || - item.kind === "Function" || - item.kind === "Method" + signature && + (item.kind === "MethodSignature" || + item.kind === "Function" || + item.kind === "Method") ) ? - : item.displayName; + : {item.displayName}; + return ( - + - {link ? - - {heading} - - : heading} + {prefix} + {heading} + {suffix} - {item.file && ( - - - ({item.file}) - - - )} ); } ApiDocHeading.propTypes = { canonicalReference: PropTypes.string.isRequired, - headingLevel: PropTypes.number.isRequired, - link: PropTypes.bool, + headingLevel: PropTypes.number, + signature: PropTypes.bool, + since: PropTypes.bool, + prefix: PropTypes.oneOfType([PropTypes.string, PropTypes.node]), + suffix: PropTypes.oneOfType([PropTypes.string, PropTypes.node]), }; + +export function SectionHeading(props) { + return ( + + ); +} +SectionHeading.propTypes = Text.propTypes; diff --git a/docs/shared/ApiDoc/InterfaceDetails.js b/docs/shared/ApiDoc/InterfaceDetails.js index e4b439181c4..92c5ae7ae55 100644 --- a/docs/shared/ApiDoc/InterfaceDetails.js +++ b/docs/shared/ApiDoc/InterfaceDetails.js @@ -1,12 +1,21 @@ import PropTypes from "prop-types"; import React from "react"; -import { ApiDocHeading, DocBlock, PropertySignatureTable } from "."; +import { GridItem } from "@chakra-ui/react"; +import { + ApiDocHeading, + DocBlock, + PropertySignatureTable, + useApiDocContext, + SectionHeading, +} from "."; export function InterfaceDetails({ canonicalReference, headingLevel, link, customPropertyOrder, }) { + const getItem = useApiDocContext(); + const item = getItem(canonicalReference); return ( <> - + + + Properties + ); diff --git a/docs/shared/ApiDoc/ParameterTable.js b/docs/shared/ApiDoc/ParameterTable.js index 49f2a7abf9c..44bd51feada 100644 --- a/docs/shared/ApiDoc/ParameterTable.js +++ b/docs/shared/ApiDoc/ParameterTable.js @@ -2,10 +2,14 @@ import { useMDXComponents } from "@mdx-js/react"; import PropTypes from "prop-types"; import React from "react"; -import { GridItem, chakra } from "@chakra-ui/react"; -import { PropertySignatureTable, useApiDocContext } from "."; +import { GridItem, Text } from "@chakra-ui/react"; +import { + PropertySignatureTable, + SectionHeading, + getInterfaceReference, + useApiDocContext, +} from "."; import { ResponsiveGrid } from "./ResponsiveGrid"; -import { mdToReact } from "./mdToReact"; export function ParameterTable({ canonicalReference }) { const MDX = useMDXComponents(); @@ -16,45 +20,34 @@ export function ParameterTable({ canonicalReference }) { return ( <> - - - Parameters - - Name / Type Description {item.parameters.map((parameter) => { - const baseType = parameter.type.split("<")[0]; - const reference = getItem( - item.references?.find((r) => r.text === baseType) - ?.canonicalReference, - false + const interfaceReference = getInterfaceReference( + parameter.type, + item, + getItem ); - const interfaceReference = - reference?.kind === "Interface" ? reference : null; + const id = `${item.displayName.toLowerCase()}-parameters-${parameter.name.toLowerCase()}`; return ( - + - - {parameter.name} - {parameter.optional ? - (optional) - : null} - + + + {parameter.name} + {parameter.optional ? + (optional) + : null} + + {parameter.type} @@ -65,7 +58,9 @@ export function ParameterTable({ canonicalReference }) { lineHeight="base" borderBottom={interfaceReference ? "none" : undefined} > - {mdToReact(parameter.comment)} + {parameter.comment && ( + {parameter.comment} + )} {interfaceReference && (
@@ -75,8 +70,7 @@ export function ParameterTable({ canonicalReference }) {
)} @@ -90,4 +84,5 @@ export function ParameterTable({ canonicalReference }) { ParameterTable.propTypes = { canonicalReference: PropTypes.string.isRequired, + showHeaders: PropTypes.bool, }; diff --git a/docs/shared/ApiDoc/PropertyDetails.js b/docs/shared/ApiDoc/PropertyDetails.js new file mode 100644 index 00000000000..e8c0f28faae --- /dev/null +++ b/docs/shared/ApiDoc/PropertyDetails.js @@ -0,0 +1,27 @@ +import PropTypes from "prop-types"; +import React from "react"; +import { ApiDocHeading, DocBlock } from "."; + +export function PropertyDetails({ canonicalReference, headingLevel }) { + return ( + <> + + + + ); +} + +PropertyDetails.propTypes = { + canonicalReference: PropTypes.string.isRequired, + headingLevel: PropTypes.number.isRequired, +}; diff --git a/docs/shared/ApiDoc/PropertySignatureTable.js b/docs/shared/ApiDoc/PropertySignatureTable.js index b5d31feb18d..b25a9fd0810 100644 --- a/docs/shared/ApiDoc/PropertySignatureTable.js +++ b/docs/shared/ApiDoc/PropertySignatureTable.js @@ -2,56 +2,43 @@ import { useMDXComponents } from "@mdx-js/react"; import PropTypes from "prop-types"; import React, { useMemo } from "react"; -import { DocBlock, FunctionSignature, useApiDocContext } from "."; -import { GridItem, Text, chakra } from "@chakra-ui/react"; +import { + DocBlock, + FunctionSignature, + useApiDocContext, + ApiDocHeading, + SectionHeading, +} from "."; +import { GridItem, Text } from "@chakra-ui/react"; import { ResponsiveGrid } from "./ResponsiveGrid"; +import { groupItems } from "./sortWithCustomOrder"; export function PropertySignatureTable({ canonicalReference, prefix = "", - showHeaders = true, + showHeaders = false, display = "parent", customOrder = [], + idPrefix = "", }) { const MDX = useMDXComponents(); const getItem = useApiDocContext(); const item = getItem(canonicalReference); - const Wrapper = display === "parent" ? ResponsiveGrid : React.Fragment; - const sortedProperties = useMemo( - () => - item.properties.map(getItem).sort((a, b) => { - const aIndex = customOrder.indexOf(a.displayName); - const bIndex = customOrder.indexOf(b.displayName); - if (aIndex >= 0 && bIndex >= 0) { - return aIndex - bIndex; - } else if (aIndex >= 0) { - return -1; - } else if (bIndex >= 0) { - return 1; - } else { - return a.displayName.localeCompare(b.displayName); - } - }), + const Wrapper = display === "parent" ? ResponsiveGrid : React.Fragment; + const groupedProperties = useMemo( + () => groupItems(item.properties.map(getItem), customOrder), [item.properties, getItem, customOrder] ); + if (item.childrenIncomplete) { + console.warn( + "Warning: some properties might be missing from the table due to complex inheritance!", + item.childrenIncompleteDetails + ); + } return ( <> - {showHeaders ? - - - Properties - - - : null} {item.childrenIncomplete ?
@@ -67,46 +54,64 @@ export function PropertySignatureTable({ Description : null} - - {sortedProperties.map((property) => ( - - - - - - {prefix} - - {property.displayName} - - {property.optional ? - (optional) - : null} - - - {property.kind === "MethodSignature" ? - - : property.type} - - - - - - - ))} + {Object.entries(groupedProperties).map( + ([groupName, sortedProperties]) => ( + <> + {groupName ? + {groupName} + : null} + {sortedProperties.map((property) => ( + + + + {prefix} + + : null + } + suffix={property.optional ? (optional) : null} + link={!!idPrefix} + id={ + idPrefix ? + `${idPrefix}-${property.displayName.toLowerCase()}` + : undefined + } + /> + + {property.kind === "MethodSignature" ? + + : property.type} + + + + + + + ))} + + ) + )} ); @@ -118,4 +123,5 @@ PropertySignatureTable.propTypes = { showHeaders: PropTypes.bool, display: PropTypes.oneOf(["parent", "child"]), customOrder: PropTypes.arrayOf(PropTypes.string), + idPrefix: PropTypes.string, }; diff --git a/docs/shared/ApiDoc/ResponsiveGrid.js b/docs/shared/ApiDoc/ResponsiveGrid.js index 691a4afebcf..2f7b1b93931 100644 --- a/docs/shared/ApiDoc/ResponsiveGrid.js +++ b/docs/shared/ApiDoc/ResponsiveGrid.js @@ -57,7 +57,7 @@ export function ResponsiveGridStyles() { ); } -export function ResponsiveGrid({ children }) { +export function ResponsiveGrid({ children, columns = 2 }) { /* responsiveness not regarding screen width, but actual available space: if less than 350px, show only one column @@ -66,7 +66,11 @@ export function ResponsiveGrid({ children }) { return ( + + ({item.file}) + + + : null; +} +SourceLink.propTypes = { + canonicalReference: PropTypes.string.isRequired, +}; diff --git a/docs/shared/ApiDoc/Tuple.js b/docs/shared/ApiDoc/Tuple.js new file mode 100644 index 00000000000..3ab881151b3 --- /dev/null +++ b/docs/shared/ApiDoc/Tuple.js @@ -0,0 +1,68 @@ +import React from "react"; +import { useMDXComponents } from "@mdx-js/react"; +import { useApiDocContext, PropertySignatureTable } from "."; +import PropTypes from "prop-types"; + +export function ManualTuple({ elements = [], idPrefix = "" }) { + const MDX = useMDXComponents(); + const getItem = useApiDocContext(); + + return ( + + + + Name + Type + Description + + + + {elements.map( + ({ name, type, description, canonicalReference }, idx) => { + const item = getItem(canonicalReference); + const separatorStyle = item ? { borderBottom: 0 } : {}; + return ( + + + {name} + + {type} + + {description} + + {item ? + + +
+ Show/hide child attributes + +
+ + + : null} + + ); + } + )} + + + ); +} +ManualTuple.propTypes = { + elements: PropTypes.arrayOf( + PropTypes.shape({ + name: PropTypes.string.isRequired, + type: PropTypes.string.isRequired, + description: PropTypes.oneOfType([PropTypes.node, PropTypes.string]) + .isRequired, + canonicalReference: PropTypes.string, + }) + ).isRequired, +}; diff --git a/docs/shared/ApiDoc/getInterfaceReference.js b/docs/shared/ApiDoc/getInterfaceReference.js new file mode 100644 index 00000000000..b9b9202ae92 --- /dev/null +++ b/docs/shared/ApiDoc/getInterfaceReference.js @@ -0,0 +1,8 @@ +export function getInterfaceReference(type, item, getItem) { + const baseType = type.replace(/\b(Partial|Omit|Promise) r.text === baseType)?.canonicalReference, + false + ); + return reference?.kind === "Interface" ? reference : null; +} diff --git a/docs/shared/ApiDoc/index.js b/docs/shared/ApiDoc/index.js index 66bfa413afa..4173bdebe62 100644 --- a/docs/shared/ApiDoc/index.js +++ b/docs/shared/ApiDoc/index.js @@ -1,14 +1,12 @@ export { useApiDocContext } from "./Context"; -export { - DocBlock, - Deprecated, - Example, - Remarks, - Since, - Summary, -} from "./DocBlock"; +export { DocBlock, Deprecated, Example, Remarks, Summary } from "./DocBlock"; export { PropertySignatureTable } from "./PropertySignatureTable"; -export { ApiDocHeading } from "./Heading"; +export { ApiDocHeading, SubHeading, SectionHeading } from "./Heading"; export { InterfaceDetails } from "./InterfaceDetails"; export { FunctionSignature, FunctionDetails } from "./Function"; export { ParameterTable } from "./ParameterTable"; +export { PropertyDetails } from "./PropertyDetails"; +export { EnumDetails } from "./EnumDetails"; +export { ManualTuple } from "./Tuple"; +export { getInterfaceReference } from "./getInterfaceReference"; +export { SourceLink } from "./SourceLink"; diff --git a/docs/shared/ApiDoc/mdToReact.js b/docs/shared/ApiDoc/mdToReact.js deleted file mode 100644 index 307ca38c7bf..00000000000 --- a/docs/shared/ApiDoc/mdToReact.js +++ /dev/null @@ -1,20 +0,0 @@ -import PropTypes from "prop-types"; -import React from "react"; -import ReactMarkdown from "react-markdown"; -import { useMDXComponents } from "@mdx-js/react"; - -export function mdToReact(text) { - const sanitized = text - .replace(/\{@link (\w*)\}/g, "[$1](#$1)") - .replace(//g, ""); - return ; -} - -function RenderMd({ markdown }) { - return ( - {markdown} - ); -} -RenderMd.propTypes = { - markdown: PropTypes.string.isRequired, -}; diff --git a/docs/shared/ApiDoc/sortWithCustomOrder.js b/docs/shared/ApiDoc/sortWithCustomOrder.js new file mode 100644 index 00000000000..c2cd411e304 --- /dev/null +++ b/docs/shared/ApiDoc/sortWithCustomOrder.js @@ -0,0 +1,71 @@ +/** + * Sorts items by their `displayName` with a custom order: + * - items within the `customOrder` array will be sorted to the start, + * sorted by the order of the `customOrder` array + * - items not in the `customOrder` array will be sorted in lexicographical order after that + * - deprecated items will be sorted in lexicographical order to the end + */ +export function sortWithCustomOrder(customOrder = []) { + return (a, b) => { + let aIndex = customOrder.indexOf(a.displayName); + if (aIndex == -1) { + aIndex = + a.comment?.deprecated ? + Number.MAX_SAFE_INTEGER + : Number.MAX_SAFE_INTEGER - 1; + } + let bIndex = customOrder.indexOf(b.displayName); + if (bIndex == -1) { + bIndex = + b.comment?.deprecated ? + Number.MAX_SAFE_INTEGER + : Number.MAX_SAFE_INTEGER - 1; + } + if (aIndex === bIndex) { + return sortLocally(a.displayName, b.displayName); + } else { + return aIndex - bIndex; + } + }; +} + +function sortLocally(a, b) { + return a.localeCompare(b); +} + +/** + * + * @param {Array<{displayName: string, comment: { docGroup: string }}>} items + * @param {string[]} customOrder + */ +export function groupItems(items = [], customOrder = []) { + const customItems = []; + const groupedItems = []; + for (const item of items) { + if (customOrder.includes(item.displayName)) customItems.push(item); + else groupedItems.push(item); + } + customItems.sort(sortWithCustomOrder(customOrder)); + const groupNames = [ + ...new Set(groupedItems.map((item) => item.comment?.docGroup || "Other")), + ].sort(sortLocally); + const groups = Object.fromEntries(groupNames.map((name) => [name, []])); + for (const item of groupedItems) { + groups[item.comment?.docGroup || "Other"].push(item); + } + for (const group of Object.values(groups)) { + group.sort(sortWithCustomOrder([])); + } + const groupsWithoutPrefix = Object.fromEntries( + Object.entries(groups).map(([name, items]) => [ + name.replace(/^\s*\d*\.\s*/, ""), + items, + ]) + ); + return customItems.length === 0 ? + groupsWithoutPrefix + : { + "": customItems, + ...groupsWithoutPrefix, + }; +} diff --git a/docs/shared/apollo-provider.mdx b/docs/shared/apollo-provider.mdx deleted file mode 100644 index 8b137891791..00000000000 --- a/docs/shared/apollo-provider.mdx +++ /dev/null @@ -1 +0,0 @@ - diff --git a/docs/shared/document-transform-options.mdx b/docs/shared/document-transform-options.mdx deleted file mode 100644 index 3675c19cfdf..00000000000 --- a/docs/shared/document-transform-options.mdx +++ /dev/null @@ -1,50 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - -
Name /
Type		Description
- -###### `getCacheKey` - -`(document: DocumentNode) => any[] | undefined` - - -Defines a custom cache key for a GraphQL document that will determine whether to re-run the document transform when given the same input GraphQL document. Returns an array that defines the cache key. Return `undefined` to disable caching for that GraphQL document. - -> **Note:** The items in the array may be any type, but also need to be referentially stable to guarantee a stable cache key. - -The default implementation of this function returns the `document` as the cache key. -
- -###### `cache` - -`boolean` - - -Determines whether to cache the transformed GraphQL document. Caching can speed up repeated calls to the document transform for the same input document. Set to `false` to completely disable caching for the document transform. When disabled, this option takes precedence over the [`getCacheKey`](#getcachekey) option. - -The default value is `true`. -
- diff --git a/docs/shared/mutation-options.mdx b/docs/shared/mutation-options.mdx deleted file mode 100644 index 4357464ae9b..00000000000 --- a/docs/shared/mutation-options.mdx +++ /dev/null @@ -1,298 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Name /
Type		Description
- -**Operation options** - -
- -###### `mutation` - -`DocumentNode` - - -A GraphQL query string parsed into an AST with the `gql` template literal. - -**Optional** for the `useMutation` hook, because the mutation can also be provided as the first parameter to the hook. - -**Required** for the `Mutation` component. -
- -###### `variables` - -`{ [key: string]: any }` - - -An object containing all of the GraphQL variables your mutation requires to execute. - -Each key in the object corresponds to a variable name, and that key's value corresponds to the variable value. - -
- -###### `errorPolicy` - -`ErrorPolicy` - - -Specifies how the mutation handles a response that returns both GraphQL errors and partial results. - -For details, see [GraphQL error policies](/react/data/error-handling/#graphql-error-policies). - -The default value is `none`, meaning that the mutation result includes error details but _not_ partial results. - -
- -###### `onCompleted` - -`(data?: TData, clientOptions?: BaseMutationOptions) => void` - - -A callback function that's called when your mutation successfully completes with zero errors (or if `errorPolicy` is `ignore` and partial data is returned). - -This function is passed the mutation's result `data` and any options passed to the mutation. - -
- -###### `onError` - -`(error: ApolloError, clientOptions?: BaseMutationOptions) => void` - - -A callback function that's called when the mutation encounters one or more errors (unless `errorPolicy` is `ignore`). - -This function is passed an [`ApolloError`](https://github.com/apollographql/apollo-client/blob/d96f4578f89b933c281bb775a39503f6cdb59ee8/src/errors/index.ts#L36-L39) object that contains either a `networkError` object or a `graphQLErrors` array, depending on the error(s) that occurred, as well as any options passed the mutation. - -
- -###### `onQueryUpdated` - -`(observableQuery: ObservableQuery, diff: Cache.DiffResult, lastDiff: Cache.DiffResult | undefined) => boolean | TResult` - - - -Optional callback for intercepting queries whose cache data has been updated by the mutation, as well as any queries specified in the [`refetchQueries: [...]`](#refetchQueries) list passed to `client.mutate`. - -Returning a `Promise` from `onQueryUpdated` will cause the final mutation `Promise` to await the returned `Promise`. Returning `false` causes the query to be ignored. - -
- -###### `refetchQueries` - -`Array | ((mutationResult: FetchResult) => Array)` - - -An array (or a function that _returns_ an array) that specifies which queries you want to refetch after the mutation occurs. - -Each array value can be either: - -* An object containing the `query` to execute, along with any `variables` -* A string indicating the operation name of the query to refetch - -
- -###### `awaitRefetchQueries` - -`boolean` - - -If `true`, makes sure all queries included in `refetchQueries` are completed before the mutation is considered complete. - -The default value is `false` (queries are refetched asynchronously). - -
- -###### `ignoreResults` - -`boolean` - - -If `true`, the mutation's `data` property is not updated with the mutation's result. - -The default value is `false`. - -
- -**Networking options** - -
- -###### `notifyOnNetworkStatusChange` - -`boolean` - - -If `true`, the in-progress mutation's associated component re-renders whenever the network status changes or a network error occurs. - -The default value is `false`. - -
- -###### `client` - -`ApolloClient` - - -The instance of `ApolloClient` to use to execute the mutation. - -By default, the instance that's passed down via context is used, but you can provide a different instance here. - -
- -###### `context` - -`Record` - - -If you're using [Apollo Link](/react/api/link/introduction/), this object is the initial value of the `context` object that's passed along your link chain. - -
- -**Caching options** - -
- -###### `update` - -`(cache: ApolloCache, mutationResult: FetchResult) => void` - - -A function used to update the Apollo Client cache after the mutation completes. - -For more information, see [Updating the cache after a mutation](/react/data/mutations#updating-the-cache-after-a-mutation). - -
- -###### `optimisticResponse` - -`TData | (vars: TVariables, { IGNORE }: { IGNORE: IgnoreModifier }) => TData` - - -By providing either an object or a callback function that, when invoked after a mutation, allows you to return optimistic data and optionally skip updates via the `IGNORE` sentinel object, Apollo Client caches this temporary (and potentially incorrect) response until the mutation completes, enabling more responsive UI updates. - -For more information, see [Optimistic mutation results](/react/performance/optimistic-ui/). - -
- -###### `fetchPolicy` - -`MutationFetchPolicy` - - -Provide `no-cache` if the mutation's result should _not_ be written to the Apollo Client cache. - -The default value is `network-only` (which means the result _is_ written to the cache). - -Unlike queries, mutations _do not_ support [fetch policies](/react/data/queries/#setting-a-fetch-policy) besides `network-only` and `no-cache`. - -
diff --git a/docs/shared/mutation-result.mdx b/docs/shared/mutation-result.mdx deleted file mode 100644 index 21e4e858137..00000000000 --- a/docs/shared/mutation-result.mdx +++ /dev/null @@ -1,145 +0,0 @@ -**Mutate function:** - - - - - - - - - - - - - - - -
Name /
Type		Description
- -###### `mutate` - -`(options?: MutationOptions) => Promise` - - -A function to trigger the mutation from your UI. You can optionally pass this function any of the following options: - -* `awaitRefetchQueries` -* `context` -* `fetchPolicy` -* `onCompleted` -* `onError` -* `optimisticResponse` -* `refetchQueries` -* `onQueryUpdated` -* `update` -* `variables` -* `client` - -Any option you pass here overrides any existing value for that option that you passed to `useMutation`. - -The mutate function returns a promise that fulfills with your mutation result. -
- -**Mutation result:** - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Name /
Type		Description
- -###### `data` - -`TData` - - -The data returned from your mutation. Can be `undefined` if `ignoreResults` is `true`. -
- -###### `loading` - -`boolean` - - -If `true`, the mutation is currently in flight. -
- -###### `error` - -`ApolloError` - - -If the mutation produces one or more errors, this object contains either an array of `graphQLErrors` or a single `networkError`. Otherwise, this value is `undefined`. - -For more information, see [Handling operation errors](/react/data/error-handling/). - -
- -###### `called` - -`boolean` - - -If `true`, the mutation's mutate function has been called. - -
- -###### `client` - -`ApolloClient` - - -The instance of Apollo Client that executed the mutation. - -Can be useful for manually executing followup operations or writing data to the cache. - -
- -###### `reset` - -`() => void` - - -A function that you can call to reset the mutation's result to its initial, uncalled state. - -
diff --git a/docs/shared/query-options.mdx b/docs/shared/query-options.mdx deleted file mode 100644 index 2a265ada2da..00000000000 --- a/docs/shared/query-options.mdx +++ /dev/null @@ -1,304 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Name /
Type		Description
- -**Operation options** - -
- -###### `query` - -`DocumentNode` - - -A GraphQL query string parsed into an AST with the `gql` template literal. - -**Optional** for the `useQuery` hook, because the query can be provided as the first parameter to the hook. **Required** for the `Query` component. -
- -###### `variables` - -`{ [key: string]: any }` - - -An object containing all of the GraphQL variables your query requires to execute. - -Each key in the object corresponds to a variable name, and that key's value corresponds to the variable value. - -
- -###### `errorPolicy` - -`ErrorPolicy` - - -Specifies how the query handles a response that returns both GraphQL errors and partial results. - -For details, see [GraphQL error policies](/react/data/error-handling/#graphql-error-policies). - -The default value is `none`, meaning that the query result includes error details but _not_ partial results. - -
- -###### `onCompleted` - -`(data: TData | {}) => void` - - -A callback function that's called when your query successfully completes with zero errors (or if `errorPolicy` is `ignore` and partial data is returned). - -This function is passed the query's result `data`. - -
- -###### `onError` - -`(error: ApolloError) => void` - - -A callback function that's called when the query encounters one or more errors (unless `errorPolicy` is `ignore`). - -This function is passed an [`ApolloError`](https://github.com/apollographql/apollo-client/blob/d96f4578f89b933c281bb775a39503f6cdb59ee8/src/errors/index.ts#L36-L39) object that contains either a `networkError` object or a `graphQLErrors` array, depending on the error(s) that occurred. - -
- -###### `skip` - -`boolean` - - -If `true`, the query is _not_ executed. **Not available with `useLazyQuery`.** - -This property is part of Apollo Client's React integration, and it is _not_ available in the [core `ApolloClient` API](/react/api/core/ApolloClient/). - -The default value is `false`. - -
- -**Networking options** - -
- -###### `pollInterval` - -`number` - - -Specifies the interval (in milliseconds) at which the query polls for updated results. - -The default value is `0` (no polling). - -
- -###### `notifyOnNetworkStatusChange` - -`boolean` - - -If `true`, the in-progress query's associated component re-renders whenever the network status changes or a network error occurs. - -The default value is `false`. - -
- -###### `context` - -`Record` - - -If you're using [Apollo Link](/react/api/link/introduction/), this object is the initial value of the `context` object that's passed along your link chain. - -
- -###### `ssr` - -`boolean` - - -Pass `false` to skip executing the query during [server-side rendering](/react/performance/server-side-rendering/). - -
- -###### `client` - -`ApolloClient` - - -The instance of `ApolloClient` to use to execute the query. - -By default, the instance that's passed down via context is used, but you can provide a different instance here. - -
- -**Caching options** - -
- -###### `fetchPolicy` - -`FetchPolicy` - - -Specifies how the query interacts with the Apollo Client cache during execution (for example, whether it checks the cache for results before sending a request to the server). - -For details, see [Setting a fetch policy](/react/data/queries/#setting-a-fetch-policy). - -The default value is `cache-first`. - -
- -###### `nextFetchPolicy` - -`FetchPolicy` - - -Specifies the [`fetchPolicy`](#fetchpolicy) to use for all executions of this query _after_ this execution. - -For example, you can use this to switch back to a `cache-first` fetch policy after using `cache-and-network` or `network-only` for a single execution. - -
- -###### `returnPartialData` - -`boolean` - - -If `true`, the query can return _partial_ results from the cache if the cache doesn't contain results for _all_ queried fields. - -The default value is `false`. - -
- -**Deprecated options** - -
- -###### `partialRefetch` - -`boolean` - - -**Deprecated.** If `true`, causes a query `refetch` if the query result is detected as partial. Setting this option is unnecessary in Apollo Client 3, thanks to a more consistent application of fetch policies. It might be removed in a future release. - -The default value is `false`. - -
diff --git a/docs/shared/query-result.mdx b/docs/shared/query-result.mdx deleted file mode 100644 index aed5e2f478f..00000000000 --- a/docs/shared/query-result.mdx +++ /dev/null @@ -1,275 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Name /
Type		Description
- -**Operation data** - -
- -###### `data` - -`TData` - - -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`). - -
- -###### `previousData` - -`TData` - - -An object containing the result from the most recent _previous_ execution of this query. - -This value is `undefined` if this is the query's first execution. - -
- -###### `error` - -`ApolloError` - - -If the query produces one or more errors, this object contains either an array of `graphQLErrors` or a single `networkError`. Otherwise, this value is `undefined`. - -For more information, see [Handling operation errors](/react/data/error-handling/). - -
- -###### `variables` - -`{ [key: string]: any }` - - -An object containing the variables that were provided for the query. - -
- -**Network info** - -
- -###### `loading` - -`boolean` - - -If `true`, the query is still in flight and results have not yet been returned. - -
- -###### `networkStatus` - -`NetworkStatus` - - -A number indicating the current network state of the query's associated request. [See possible values.](https://github.com/apollographql/apollo-client/blob/d96f4578f89b933c281bb775a39503f6cdb59ee8/src/core/networkStatus.ts#L4) - -Used in conjunction with the [`notifyOnNetworkStatusChange`](#notifyonnetworkstatuschange) option. - -
- -###### `client` - -`ApolloClient` - - -The instance of Apollo Client that executed the query. - -Can be useful for manually executing followup queries or writing data to the cache. - -
- -###### `called` - -`boolean` - - -If `true`, the associated lazy query has been executed. - -This field is only present on the result object returned by [`useLazyQuery`](/react/data/queries/#executing-queries-manually). - -
- -**Helper functions** - -
- -###### `refetch` - -`(variables?: Partial) => Promise` - - -A function that enables you to re-execute the query, optionally passing in new `variables`. - -To guarantee that the refetch performs a network request, its `fetchPolicy` is set to `network-only` (unless the original query's `fetchPolicy` is `no-cache` or `cache-and-network`, which also guarantee a network request). - -See also [Refetching](/react/data/queries/#refetching). - -
- -###### `fetchMore` - -`({ query?: DocumentNode, variables?: TVariables, updateQuery: Function}) => Promise` - - -A function that helps you fetch the next set of results for a [paginated list field](/react/pagination/core-api/). - -
- -###### `startPolling` - -`(interval: number) => void` - - -A function that instructs the query to begin re-executing at a specified interval (in milliseconds). - -
- -###### `stopPolling` - -`() => void` - - -A function that instructs the query to stop polling after a previous call to `startPolling`. - -
- -###### `subscribeToMore` - -`(options: { document: DocumentNode, variables?: TVariables, updateQuery?: Function, onError?: Function}) => () => void` - - -A function that enables you to execute a [subscription](/react/data/subscriptions/), usually to subscribe to specific fields that were included in the query. - -This function returns _another_ function that you can call to terminate the subscription. - -
- -###### `updateQuery` - -`(mapFn: (previousResult: TData, options: { variables: TVariables }) => TData) => void` - - -A function that enables you to update the query's cached result without executing a followup GraphQL operation. -See [using updateQuery and updateFragment](/react/caching/cache-interaction/#using-updatequery-and-updatefragment) for additional information. -
diff --git a/docs/shared/subscription-options.mdx b/docs/shared/subscription-options.mdx deleted file mode 100644 index 00148fa2fce..00000000000 --- a/docs/shared/subscription-options.mdx +++ /dev/null @@ -1,14 +0,0 @@ -| Option | Type | Description | -| - | - | - | -| `subscription` | DocumentNode | A GraphQL subscription document parsed into an AST by `graphql-tag`. **Optional** for the `useSubscription` Hook since the subscription can be passed in as the first parameter to the Hook. **Required** for the `Subscription` component. | -| `variables` | { [key: string]: any } | An object containing all of the variables your subscription needs to execute | -| `shouldResubscribe` | boolean | Determines if your subscription should be unsubscribed and subscribed again when an input to the hook (such as `subscription` or `variables`) changes. | -| `skip` | boolean | Determines if the current subscription should be skipped. Useful if, for example, variables depend on previous queries and are not ready yet. | -| `onSubscriptionData` | **Deprecated.** (options: OnSubscriptionDataOptions<TData>) => any | Allows the registration of a callback function that will be triggered each time the `useSubscription` Hook / `Subscription` component receives data. The callback `options` object param consists of the current Apollo Client instance in `client`, and the received subscription data in `subscriptionData`. | -| `onData` | (options: OnDataOptions<TData>) => any | Allows the registration of a callback function that will be triggered each time the `useSubscription` Hook / `Subscription` component receives data. The callback `options` object param consists of the current Apollo Client instance in `client`, and the received subscription data in `data`. | -| `onError` | (error: ApolloError) => void | Allows the registration of a callback function that will be triggered each time the `useSubscription` Hook / `Subscription` component receives an error. | -| `onSubscriptionComplete` | **Deprecated.** () => void | Allows the registration of a callback function that will be triggered when the `useSubscription` Hook / `Subscription` component completes the subscription. | -| `onComplete` | () => void | Allows the registration of a callback function that will be triggered each time the `useSubscription` Hook / `Subscription` component completes the subscription. | -| `fetchPolicy` | FetchPolicy | How you want your component to interact with the Apollo cache. For details, see [Setting a fetch policy](/react/data/queries/#setting-a-fetch-policy). | -| `context` | Record<string, any> | Shared context between your component and your network interface (Apollo Link). | -| `client` | ApolloClient | An `ApolloClient` instance. By default `useSubscription` / `Subscription` uses the client passed down via context, but a different client can be passed in. | diff --git a/docs/shared/subscription-result.mdx b/docs/shared/subscription-result.mdx deleted file mode 100644 index be7d5295613..00000000000 --- a/docs/shared/subscription-result.mdx +++ /dev/null @@ -1,5 +0,0 @@ -| Property | Type | Description | -| - | - | - | -| `data` | TData | An object containing the result of your GraphQL subscription. Defaults to an empty object. | -| `loading` | boolean | A boolean that indicates whether any initial data has been returned | -| `error` | ApolloError | A runtime error with `graphQLErrors` and `networkError` properties | diff --git a/docs/shared/useSuspenseQuery-options.mdx b/docs/shared/useSuspenseQuery-options.mdx deleted file mode 100644 index 38d6189d21f..00000000000 --- a/docs/shared/useSuspenseQuery-options.mdx +++ /dev/null @@ -1,217 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Name /
Type		Description
- -**Operation options** - -
- -###### `variables` - -`{ [key: string]: any }` - - -An object containing all of the GraphQL variables your query requires to execute. - -Each key in the object corresponds to a variable name, and that key's value corresponds to the variable value. - -
- -###### `errorPolicy` - -`ErrorPolicy` - - -Specifies how the query handles a response that returns both GraphQL errors and partial results. - -For details, see [GraphQL error policies](/react/data/error-handling/#graphql-error-policies). - -The default value is `none`, which causes the hook to throw the error. -
- -**Networking options** - -
- -###### `context` - -`Record` - - -If you're using [Apollo Link](/react/api/link/introduction/), this object is the initial value of the `context` object that's passed along your link chain. - -
- -###### `canonizeResults` - -`Boolean` - - -> **⚠️ Deprecated**: -> Using `canonizeResults` can result in memory leaks so we generally do not recommend using this option anymore. -> A future version of Apollo Client will contain a similar feature without the risk of memory leaks. - -If `true`, result objects read from the cache will be _canonized_, which means deeply-equal objects will also be `===` (literally the same object), allowing much more efficient comparison of past/present results. - -The default value is `false`. - -
- -###### `client` - -`ApolloClient` - - -The instance of `ApolloClient` to use to execute the query. - -By default, the instance that's passed down via context is used, but you can provide a different instance here. - -
- -###### `queryKey` - -`string | number | any[]` - - -A unique identifier for the query. Each item in the array must be a stable identifier to prevent infinite fetches. - -This is useful when using the same query and variables combination in more than one component, otherwise the components may clobber each other. This can also be used to force the query to re-evaluate fresh. - -
- -**Caching options** - -
- -###### `fetchPolicy` - -`SuspenseQueryHookFetchPolicy` - - -Specifies how the query interacts with the Apollo Client cache during execution (for example, whether it checks the cache for results before sending a request to the server). - -For details, see [Setting a fetch -policy](/react/data/queries/#setting-a-fetch-policy). This hook only supports -the `cache-first`, `network-only`, `no-cache`, and `cache-and-network` fetch -policies. - -The default value is `cache-first`. - -
- -###### `returnPartialData` - -`boolean` - - -If `true`, the query can return _partial_ results from the cache if the cache doesn't contain results for _all_ queried fields. - -The default value is `false`. - -
- -###### `refetchWritePolicy` - -`"merge" | "overwrite"` - - -Watched queries must opt into overwriting existing data on refetch, by passing `refetchWritePolicy: "overwrite"` in their `WatchQueryOptions`. - -The default value is `"overwrite"`. - -
- -###### `skip` (deprecated) - -`boolean` - - -If `true`, the query is not executed. The default value is `false`. - -This option is deprecated and only supported to ease the migration from `useQuery`. It will be removed in a future release. -Please use [`skipToken`](/react/api/react/hooks#skiptoken`) instead of the `skip` option as it is more type-safe. - -
diff --git a/docs/source/api/core/ObservableQuery.mdx b/docs/source/api/core/ObservableQuery.mdx index 90d4450dfe6..806091f8b28 100644 --- a/docs/source/api/core/ObservableQuery.mdx +++ b/docs/source/api/core/ObservableQuery.mdx @@ -1,26 +1,30 @@ --- title: ObservableQuery description: API reference +api_doc: + - "@apollo/client!ObservableQuery:class" + - "@apollo/client!ApolloQueryResult:interface" + - "@apollo/client!NetworkStatus:enum" --- +import { InterfaceDetails, FunctionDetails, PropertyDetails, EnumDetails } from '../../../shared/ApiDoc'; + ## `ObservableQuery` functions `ApolloClient` Observables extend the Observables implementation provided by [`zen-observable`](https://github.com/zenparsing/zen-observable). Refer to the `zen-observable` documentation for additional context and API options. - - - - - - - - - - - + + + + + + + + + + -## Types - - - +## Types + + diff --git a/docs/source/api/react/components.mdx b/docs/source/api/react/components.mdx index 629d1475c8d..7322b162234 100644 --- a/docs/source/api/react/components.mdx +++ b/docs/source/api/react/components.mdx @@ -1,14 +1,16 @@ --- title: Components description: Deprecated React Apollo render prop component API +api_doc: + - "@apollo/client!QueryFunctionOptions:interface" + - "@apollo/client!QueryResult:interface" + - "@apollo/client!MutationFunctionOptions:interface" + - "@apollo/client!MutationResult:interface" + - "@apollo/client!SubscriptionComponentOptions:interface" + - "@apollo/client!SubscriptionResult:interface" --- -import QueryOptions3 from '../../../shared/query-options.mdx'; -import QueryResult3 from '../../../shared/query-result.mdx'; -import MutationOptions3 from '../../../shared/mutation-options.mdx'; -import MutationResult3 from '../../../shared/mutation-result.mdx'; -import SubscriptionOptions3 from '../../../shared/subscription-options.mdx'; -import SubscriptionResult3 from '../../../shared/subscription-result.mdx'; +import { PropertySignatureTable } from '../../../shared/ApiDoc'; > **Note:** Official support for React Apollo render prop components ended in March 2020. This library is still included in the `@apollo/client` package, but it no longer receives feature updates or bug fixes. @@ -28,25 +30,25 @@ You then import the library's symbols from `@apollo/client/react/components`. The `Query` component accepts the following props. `query` is **required**. - + ### Render prop function The render prop function that you pass to the `children` prop of `Query` is called with an object (`QueryResult`) that has the following properties. This object contains your query result, plus some helpful functions for refetching, dynamic polling, and pagination. - + ## `Mutation` The Mutation component accepts the following props. Only `mutation` is **required**. - + ### Render prop function The render prop function that you pass to the `children` prop of `Mutation` is called with the `mutate` function and an object with the mutation result. The `mutate` function is how you trigger the mutation from your UI. The object contains your mutation result, plus loading and error state. - + ## `Subscription` @@ -54,10 +56,10 @@ The render prop function that you pass to the `children` prop of `Mutation` is c The Subscription component accepts the following props. Only `subscription` is **required**. - + ### Render prop function -The render prop function that you pass to the `children` prop of `Subscription` is called with an object that has the following properties. + diff --git a/docs/source/api/react/hooks.mdx b/docs/source/api/react/hooks.mdx index 9a729b1c3a6..c6e3249253b 100644 --- a/docs/source/api/react/hooks.mdx +++ b/docs/source/api/react/hooks.mdx @@ -1,25 +1,24 @@ --- title: Hooks description: Apollo Client react hooks API reference +minVersion: 3.0.0 +api_doc: + - "@apollo/client!SuspenseQueryHookOptions:interface" + - "@apollo/client!useQuery:function(1)" + - "@apollo/client!useLazyQuery:function(1)" + - "@apollo/client!useMutation:function(1)" + - "@apollo/client!useSubscription:function(1)" + - "@apollo/client!useApolloClient:function(1)" + - "@apollo/client!useReactiveVar:function(1)" --- -import QueryOptions3 from '../../../shared/query-options.mdx'; -import QueryResult3 from '../../../shared/query-result.mdx'; -import MutationOptions3 from '../../../shared/mutation-options.mdx'; -import MutationResult3 from '../../../shared/mutation-result.mdx'; -import SubscriptionOptions3 from '../../../shared/subscription-options.mdx'; -import SubscriptionResult3 from '../../../shared/subscription-result.mdx'; import UseFragmentOptions from '../../../shared/useFragment-options.mdx'; import UseFragmentResult from '../../../shared/useFragment-result.mdx'; -import UseSuspenseQueryOptions from '../../../shared/useSuspenseQuery-options.mdx'; import UseBackgroundQueryOptions from '../../../shared/useBackgroundQuery-options.mdx'; import UseSuspenseQueryResult from '../../../shared/useSuspenseQuery-result.mdx'; import UseBackgroundQueryResult from '../../../shared/useBackgroundQuery-result.mdx'; import UseReadQueryResult from '../../../shared/useReadQuery-result.mdx'; - -## Installation - -Apollo Client >= 3 includes React hooks functionality out of the box. You don't need to install any additional packages. +import { FunctionDetails, PropertySignatureTable, ManualTuple, InterfaceDetails } from '../../../shared/ApiDoc'; ## The `ApolloProvider` component @@ -69,350 +68,93 @@ function WithApolloClient() { } ``` -## `useQuery` - -### Example - -```jsx -import { gql, useQuery } from '@apollo/client'; - -const GET_GREETING = gql` - query GetGreeting($language: String!) { - greeting(language: $language) { - message - } - } -`; - -function Hello() { - const { loading, error, data } = useQuery(GET_GREETING, { - variables: { language: 'english' }, - }); - if (loading) return

Loading ...

; - return

Hello {data.greeting.message}!

; -} -``` - -> Refer to the [Queries](../../data/queries/) section for a more in-depth overview of `useQuery`. - -### Signature - -```ts -function useQuery( - query: DocumentNode, - options?: QueryHookOptions, -): QueryResult {} -``` - -### Params - -#### `query` - -| Param | Type | Description | -| ------- | ------------ | ------------------------------------------------------------- | -| `query` | DocumentNode | A GraphQL query document parsed into an AST by `gql`. | - -#### `options` - - - -### Result - - - -## `useLazyQuery` - -### Example - -```jsx -import { gql, useLazyQuery } from "@apollo/client"; - -const GET_GREETING = gql` - query GetGreeting($language: String!) { - greeting(language: $language) { - message - } - } -`; - -function Hello() { - const [loadGreeting, { called, loading, data }] = useLazyQuery( - GET_GREETING, - { variables: { language: "english" } } - ); - if (called && loading) return

Loading ...

- if (!called) { - return - } - return

Hello {data.greeting.message}!

; -} -``` - -> Refer to the [Queries](../../data/queries/) section for a more in-depth overview of `useLazyQuery`. - -### Signature - -```ts -function useLazyQuery( - query: DocumentNode, - options?: LazyQueryHookOptions, -): [ - (options?: LazyQueryHookOptions) => Promise>, - LazyQueryResult -] {} -``` - -### Params - -#### `query` - -| Param | Type | Description | -| ------- | ------------ | ------------------------------------------------------------- | -| `query` | DocumentNode | A GraphQL query document parsed into an AST by `gql`. | - -#### `options` - - - -### Result tuple - -**Execute function (first tuple item)** - -| Param | Type | Description | -| ---------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -| Execute function | `(options?: LazyQueryHookOptions) => Promise>` | Function that can be triggered to execute the suspended query. After being called, `useLazyQuery` behaves just like `useQuery`. The `useLazyQuery` function returns a promise that fulfills with a query result when the query succeeds or fails. | + -**`LazyQueryResult` object (second tuple item)** + +

+[execute: LazyQueryExecFunction<TData, TVariables>, result: QueryResult<TData, TVariables>]
+
- +A tuple of two values: -## `useMutation` - -### Example - -```jsx -import { gql, useMutation } from '@apollo/client'; - -const ADD_TODO = gql` - mutation AddTodo($type: String!) { - addTodo(type: $type) { - id - type - } +) => Promise>", + description: "Function that can be triggered to execute the suspended query. After being called, `useLazyQuery` behaves just like `useQuery`. The `useLazyQuery` function returns a promise that fulfills with a query result when the query succeeds or fails." + }, + { + name: "result", + type: "QueryResult", + description: "The result of the query. See the `useQuery` hook for more details.", + canonicalReference: "@apollo/client!QueryResult:interface" } -`; - -function AddTodo() { - let input; - const [addTodo, { data }] = useMutation(ADD_TODO); - - return ( +]}/> +} +/> + + -
{ - e.preventDefault(); - addTodo({ variables: { type: input.value } }); - input.value = ''; - }} - > - { - input = node; - }} - /> - -
+ 
+        
+        {`[
+  mutate: (options?: MutationFunctionOptions) => Promise>,
+  result: MutationResult
+]`}
+        
+
+ A tuple of two values: + + ) => Promise>`, + description:
+A function to trigger the mutation from your UI. You can optionally pass this function any of the following options: + +
    +
  • awaitRefetchQueries
    • +
  • context
    • +
  • fetchPolicy
    • +
  • onCompleted
    • +
  • onError
    • +
  • optimisticResponse
    • +
  • refetchQueries
    • +
  • onQueryUpdated
    • +
  • update
    • +
  • variables
    • +
  • client
    • +
+ +Any option you pass here overrides any existing value for that option that you passed to useMutation. + +The mutate function returns a promise that fulfills with your mutation result. +
, + }, + { + name: "result", + type: "MutationResult", + description: "The result of the mutation.", + canonicalReference: "@apollo/client!MutationResult:interface", + }, + ]} + /> - ); -} -``` - -> Refer to the [Mutations](../../data/mutations/) section for a more in-depth overview of `useMutation`. - -### Signature - -```ts -function useMutation( - mutation: DocumentNode, - options?: MutationHookOptions, -): MutationTuple {} -``` - -### Params - -#### `mutation` - -| Param | Type | Description | -| ---------- | ------------ | ---------------------------------------------------------------- | -| `mutation` | DocumentNode | A GraphQL mutation document parsed into an AST by `gql`. | - -#### `options` - - - -### `MutationTuple` result tuple - - - -## `useSubscription` - -### Example - -```jsx -const COMMENTS_SUBSCRIPTION = gql` - subscription OnCommentAdded($repoFullName: String!) { - commentAdded(repoFullName: $repoFullName) { - id - content - } } -`; - -function DontReadTheComments({ repoFullName }) { - const { - data: { commentAdded }, - loading, - } = useSubscription(COMMENTS_SUBSCRIPTION, { variables: { repoFullName } }); - return

New comment: {!loading && commentAdded.content}

; -} -``` - -> Refer to the [Subscriptions](../../data/subscriptions/) section for a more in-depth overview of `useSubscription`. - -#### Subscriptions and React 18 Automatic Batching - -With React 18's [automatic batching](https://react.dev/blog/2022/03/29/react-v18#new-feature-automatic-batching), multiple state updates may be grouped into a single re-render for better performance. - -If your subscription API sends multiple messages at the same time or in very fast succession (within fractions of a millisecond), it is likely that only the last message received in that narrow time frame will result in a re-render. - -Consider the following component: - -```jsx -export function Subscriptions() { - const { data, error, loading } = useSubscription(query); - const [accumulatedData, setAccumulatedData] = useState([]); - - useEffect(() => { - setAccumulatedData((prev) => [...prev, data]); - }, [data]); - - return ( - <> - {loading &&

Loading...

} - {JSON.stringify(accumulatedData, undefined, 2)} - - ); -} -``` - -If your subscription back-end emits two messages with the same timestamp, only the last message received by Apollo Client will be rendered. This is because React 18 will batch these two state updates into a single re-render. - -Since the component above is using `useEffect` to push `data` into a piece of local state on each `Subscriptions` re-render, the first message will never be added to the `accumulatedData` array since its render was skipped. - -Instead of using `useEffect` here, we can re-write this component to use the `onData` callback function accepted in `useSubscription`'s `options` object: - -```jsx -export function Subscriptions() { - const [accumulatedData, setAccumulatedData] = useState([]); - const { data, error, loading } = useSubscription( - query, - { - onData({ data }) { - setAccumulatedData((prev) => [...prev, data]) - } - } - ); - - return ( - <> - {loading &&

Loading...

} - {JSON.stringify(accumulatedData, undefined, 2)} - - ); -} -``` +/> -> ⚠️ **Note:** The `useSubscription` option `onData` is available in Apollo Client >= 3.7. In previous versions, the equivalent option is named `onSubscriptionData`. + -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`. + -### Signature - -```ts -function useSubscription( - subscription: DocumentNode, - options?: SubscriptionHookOptions, -): { - variables: TVariables; - loading: boolean; - data?: TData; - error?: ApolloError; -} {} -``` - -### Params - -#### `subscription` - -| Param | Type | Description | -| -------------- | ------------ | -------------------------------------------------------------------- | -| `subscription` | DocumentNode | A GraphQL subscription document parsed into an AST by `gql`. | - -#### `options` - - - -### Result - - - -## `useApolloClient` - -### Example - -```jsx -import { useApolloClient } from '@apollo/client'; - -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`) -} -``` - -### Signature - -```ts -function useApolloClient(): ApolloClient {} -``` - -### Result - -| Param | Type | Description | -| ---------------------- | -------------------------- | ---------------------------------------------------------- | -| Apollo Client instance | ApolloClient<object> | The `ApolloClient` instance being used by the application. | - - -## `useReactiveVar` - -Reads the value of a [reactive variable](../../local-state/reactive-variables/) and re-renders the containing component whenever that variable's value changes. This enables a reactive variable to trigger changes _without_ relying on the `useQuery` hook. - -### Example - -```jsx -import { makeVar, useReactiveVar } from "@apollo/client"; -export const cartItemsVar = makeVar([]); - -export function Cart() { - const cartItems = useReactiveVar(cartItemsVar); - // ... -``` - -### Signature - -```tsx -function useReactiveVar(rv: ReactiveVar): T {} -``` + @@ -520,7 +262,11 @@ function useSuspenseQuery( Instead of passing a `SuspenseQueryHookOptions` object into the hook, you can also pass a [`skipToken`](#skiptoken) to prevent the `useSuspenseQuery` hook from executing the query or suspending. - + ### Result diff --git a/docs/source/data/document-transforms.mdx b/docs/source/data/document-transforms.mdx index d9acc5f8a54..96510c4e27e 100644 --- a/docs/source/data/document-transforms.mdx +++ b/docs/source/data/document-transforms.mdx @@ -2,9 +2,10 @@ title: Document transforms description: Make custom modifications to your GraphQL documents minVersion: 3.8.0 +api_doc: + - "@apollo/client!~DocumentTransformOptions:interface" --- - -import DocumentTransformOptions from '../../shared/document-transform-options.mdx'; +import { InterfaceDetails } from '../../shared/ApiDoc'; > This article assumes you're familiar with the [anatomy of a GraphQL query](https://www.apollographql.com/blog/graphql/basics/the-anatomy-of-a-graphql-query/) and the concept of an [abstract syntax tree (AST)](https://en.wikipedia.org/wiki/Abstract_syntax_tree). To explore a GraphQL AST, visit [AST Explorer](https://astexplorer.net/). @@ -29,7 +30,7 @@ const client = new ApolloClient({ }); ``` -### Lifecycle +### Lifecycle Apollo Client runs document transforms before every GraphQL request for all operations. This extends to any API that performs a network request, such as the [`useQuery`](/react/api/react/hooks#usequery) hook or the [`refetch`](/react/api/core/ObservableQuery#refetch) function on [`ObservableQuery`](/react/api/core/ObservableQuery). @@ -111,11 +112,11 @@ const transformedDocument = visit(document, { ``` > Returning `undefined` from our `Field` visitor tells the `visit` function to leave the node unchanged. -Now that we've determined we are working with the `currentUser` field, we need to figure out if our `id` field is already part of the `currentUser` field's selection set. This ensures we don't accidentally select the field twice in our query. +Now that we've determined we are working with the `currentUser` field, we need to figure out if our `id` field is already part of the `currentUser` field's selection set. This ensures we don't accidentally select the field twice in our query. To do so, let's get the field's `selectionSet` property and loop over its `selections` property to determine if the `id` field is included. -It's important to note that a `selectionSet` may contain `selections` of both fields and fragments. Our implementation only needs to perform checks against fields, so we also check the selection's `kind` property. If we find a match on a field named `id`, we can stop traversal of the AST. +It's important to note that a `selectionSet` may contain `selections` of both fields and fragments. Our implementation only needs to perform checks against fields, so we also check the selection's `kind` property. If we find a match on a field named `id`, we can stop traversal of the AST. We will bring in both the [`Kind`](https://graphql.org/graphql-js/language/#kind) enum from `graphql-js`, which allows us to compare against the selection's `kind` property, and the [`BREAK`](https://graphql.org/graphql-js/language/#break) sentinel, which directs the `visit` function to stop traversal of the AST. @@ -160,7 +161,7 @@ const transformedDocument = visit(document, { Field(field) { // ... const idField = { - // ... + // ... }; return { @@ -224,7 +225,7 @@ const documentTransform = new DocumentTransform((document) => { ### Check our document transform -We can check our custom document transform by calling the `transformDocument` function and passing a GraphQL query to it. +We can check our custom document transform by calling the `transformDocument` function and passing a GraphQL query to it. ```ts import { print } from 'graphql'; @@ -331,7 +332,7 @@ Here `documentTransform1` is combined with `documentTransform2` into a single do #### A note about performance -Combining multiple transforms is a powerful feature that makes it easy to split up transform logic, which can boost maintainability. Depending on the implementation of your visitor, this can result in the traversal of the GraphQL document AST multiple times. Most of the time, this shouldn't be an issue. We recommend using the [`BREAK`](https://graphql.org/graphql-js/language/#break) sentinel from `graphql-js` to prevent unnecessary traversal. +Combining multiple transforms is a powerful feature that makes it easy to split up transform logic, which can boost maintainability. Depending on the implementation of your visitor, this can result in the traversal of the GraphQL document AST multiple times. Most of the time, this shouldn't be an issue. We recommend using the [`BREAK`](https://graphql.org/graphql-js/language/#break) sentinel from `graphql-js` to prevent unnecessary traversal. Suppose you are sending very large queries that require several traversals and have already optimized your visitors with the `BREAK` sentinel. In that case, it's best to combine the transforms into a single visitor that traverses the AST once. @@ -464,7 +465,7 @@ const documentTransform = new DocumentTransform( getCacheKey: (document) => { // Always run the transform function when `shouldCache` is `false` if (shouldCache(document)) { - return [document] + return [document] } } } @@ -507,7 +508,7 @@ const nonCachedTransform = new DocumentTransform(transform, { cache: false }); -const documentTransform = +const documentTransform = cachedTransform .concat(varyingTransform) .concat(conditionalCachedTransform) @@ -527,7 +528,7 @@ Thankfully, GraphQL Code Generator provides a [document transform](https://the-g ```ts title="codegen.ts" {2,12-18} import type { CodegenConfig } from '@graphql-codegen/cli'; import { documentTransform } from './path/to/your/transform'; - + const config: CodegenConfig = { schema: 'https://localhost:4000/graphql', documents: ['src/**/*.tsx'], @@ -574,7 +575,7 @@ Here is an example that uses a DSL-like directive that depends on a feature flag ```ts const query = gql` query MyQuery { - myCustomField @feature(name: "custom", version: 2) + myCustomField @feature(name: "custom", version: 2) } `; @@ -584,7 +585,7 @@ const documentTransform = new DocumentTransform((document) => { documentTransform.transformDocument(query); // query MyQuery($feature_custom_v2: Boolean!) { -// myCustomField @include(if: $feature_custom_v2) +// myCustomField @include(if: $feature_custom_v2) // } ``` @@ -592,4 +593,4 @@ documentTransform.transformDocument(query); ### Options - + diff --git a/docs/source/data/mutations.mdx b/docs/source/data/mutations.mdx index 3a6eec83618..8a7c4c806cf 100644 --- a/docs/source/data/mutations.mdx +++ b/docs/source/data/mutations.mdx @@ -1,10 +1,12 @@ --- title: Mutations in Apollo Client description: Modify data with the useMutation hook +api_doc: + - "@apollo/client!MutationHookOptions:interface" + - "@apollo/client!MutationResult:interface" --- -import MutationOptions3 from '../../shared/mutation-options.mdx'; -import MutationResult3 from '../../shared/mutation-result.mdx'; +import { PropertySignatureTable } from '../../shared/ApiDoc'; Now that we've [learned how to query data](queries/) from our backend with Apollo Client, the natural next step is to learn how to _modify_ back-end data with **mutations**. @@ -380,7 +382,7 @@ detail with usage examples, see the [API reference](../api/react/hooks/). The `useMutation` hook accepts the following options: - + ### Result @@ -388,7 +390,7 @@ The `useMutation` result is a tuple with a mutate function in the first position You call the mutate function to trigger the mutation from your UI. - + ## Next steps diff --git a/docs/source/data/queries.mdx b/docs/source/data/queries.mdx index 4814d615370..5ee6ae03d49 100644 --- a/docs/source/data/queries.mdx +++ b/docs/source/data/queries.mdx @@ -1,10 +1,12 @@ --- title: Queries description: Fetch data with the useQuery hook +api_doc: + - "@apollo/client!QueryHookOptions:interface" + - "@apollo/client!QueryResult:interface" --- -import QueryOptions from '../../shared/query-options.mdx'; -import QueryResult from '../../shared/query-result.mdx'; +import { PropertySignatureTable } from '../../shared/ApiDoc'; This article shows how to fetch GraphQL data in React with the `useQuery` hook and attach the result to your UI. You'll also learn how Apollo Client simplifies data management code by tracking error and loading states for you. @@ -504,13 +506,13 @@ Most calls to `useQuery` can omit the majority of these options, but it's useful The `useQuery` hook accepts the following options: - + ### Result After being called, the `useQuery` hook returns a result object with the following properties. This object contains your query result, plus some helpful functions for refetching, dynamic polling, and pagination. - + ## Next steps diff --git a/docs/source/data/subscriptions.mdx b/docs/source/data/subscriptions.mdx index 1c48ac253ca..59e451c44ee 100644 --- a/docs/source/data/subscriptions.mdx +++ b/docs/source/data/subscriptions.mdx @@ -1,10 +1,12 @@ --- title: Subscriptions description: Get real-time updates from your GraphQL server +api_doc: + - "@apollo/client!SubscriptionHookOptions:interface" + - "@apollo/client!SubscriptionResult:interface" --- -import SubscriptionOptions from '../../shared/subscription-options.mdx'; -import SubscriptionResult from '../../shared/subscription-result.mdx'; +import { PropertySignatureTable } from '../../shared/ApiDoc'; In addition to [queries](./queries/) and [mutations](./mutations/), GraphQL supports a third operation type: **subscriptions**. @@ -373,13 +375,13 @@ export function CommentsPage({subscribeToNewComments}) { The `useSubscription` Hook accepts the following options: - + ### Result After being called, the `useSubscription` Hook returns a result object with the following properties: - + ## The older `subscriptions-transport-ws` library diff --git a/netlify.toml b/netlify.toml index 67879a8b0ba..2a741ec142c 100644 --- a/netlify.toml +++ b/netlify.toml @@ -13,7 +13,7 @@ npm run docmodel cd ../ rm -rf monodocs - git clone https://github.com/apollographql/docs --branch main --single-branch monodocs + git clone https://github.com/apollographql/docs --branch pr/apidoc-enums-since --single-branch monodocs cd monodocs npm i cp -r ../docs local diff --git a/src/cache/core/types/DataProxy.ts b/src/cache/core/types/DataProxy.ts index d340f187d4e..4e3e0f9cc73 100644 --- a/src/cache/core/types/DataProxy.ts +++ b/src/cache/core/types/DataProxy.ts @@ -68,18 +68,7 @@ export namespace DataProxy { * readQuery method can be omitted. Defaults to false. */ optimistic?: boolean; - /** - /** - * @deprecated - * Using `canonizeResults` can result in memory leaks so we generally do not - * recommend using this option anymore. - * A future version of Apollo Client will contain a similar feature without - * the risk of memory leaks. - * - * Whether to canonize cache results before returning them. Canonization - * takes some extra time, but it speeds up future deep equality comparisons. - * Defaults to false. - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#canonizeResults:member} */ canonizeResults?: boolean; } @@ -96,16 +85,7 @@ export namespace DataProxy { * readQuery method can be omitted. Defaults to false. */ optimistic?: boolean; - /** - * @deprecated - * Using `canonizeResults` can result in memory leaks so we generally do not - * recommend using this option anymore. - * A future version of Apollo Client will contain a similar feature. - * - * Whether to canonize cache results before returning them. Canonization - * takes some extra time, but it speeds up future deep equality comparisons. - * Defaults to false. - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#canonizeResults:member} */ canonizeResults?: boolean; } diff --git a/src/cache/inmemory/types.ts b/src/cache/inmemory/types.ts index bd05ff7aacf..10678ce5ad7 100644 --- a/src/cache/inmemory/types.ts +++ b/src/cache/inmemory/types.ts @@ -147,7 +147,6 @@ export interface InMemoryCacheConfig extends ApolloReducerConfig { /** * @deprecated * Please use `cacheSizes` instead. - * TODO: write docs page, add link here */ resultCacheMaxSize?: number; /** diff --git a/src/core/ApolloClient.ts b/src/core/ApolloClient.ts index a0b33993d61..55bae5b11a9 100644 --- a/src/core/ApolloClient.ts +++ b/src/core/ApolloClient.ts @@ -76,7 +76,7 @@ export interface ApolloClientOptions { */ ssrForceFetchDelay?: number; /** - * When using Apollo Client for [server-side rendering](https://www.apollographql.com/docs/react//performance/server-side-rendering/), set this to `true` so that the [`getDataFromTree` function](../react/ssr/#getdatafromtree) can work effectively. + * When using Apollo Client for [server-side rendering](https://www.apollographql.com/docs/react/performance/server-side-rendering/), set this to `true` so that the [`getDataFromTree` function](../react/ssr/#getdatafromtree) can work effectively. * * @defaultValue `false` */ diff --git a/src/core/ObservableQuery.ts b/src/core/ObservableQuery.ts index 03418c0e1d9..2b42f3b044e 100644 --- a/src/core/ObservableQuery.ts +++ b/src/core/ObservableQuery.ts @@ -80,6 +80,9 @@ export class ObservableQuery< // Computed shorthand for this.options.variables, preserved for // backwards compatibility. + /** + * An object containing the variables that were provided for the query. + */ public get variables(): TVariables | undefined { return this.options.variables; } @@ -417,6 +420,9 @@ Did you mean to call refetch(variables) instead of refetch({ variables })?`, return this.reobserve(reobserveOptions, NetworkStatus.refetch); } + /** + * A function that helps you fetch the next set of results for a [paginated list field](https://www.apollographql.com/docs/react/pagination/core-api/). + */ public fetchMore< TFetchData = TData, TFetchVars extends OperationVariables = TVariables, @@ -545,6 +551,11 @@ Did you mean to call refetch(variables) instead of refetch({ variables })?`, // XXX the subscription variables are separate from the query variables. // if you want to update subscription variables, right now you have to do that separately, // and you can only do it by stopping the subscription and then subscribing again with new variables. + /** + * A function that enables you to execute a [subscription](https://www.apollographql.com/docs/react/data/subscriptions/), usually to subscribe to specific fields that were included in the query. + * + * This function returns _another_ function that you can call to terminate the subscription. + */ public subscribeToMore< TSubscriptionData = TData, TSubscriptionVariables extends OperationVariables = TVariables, @@ -650,6 +661,11 @@ Did you mean to call refetch(variables) instead of refetch({ variables })?`, ); } + /** + * A function that enables you to update the query's cached result without executing a followup GraphQL operation. + * + * See [using updateQuery and updateFragment](https://www.apollographql.com/docs/react/caching/cache-interaction/#using-updatequery-and-updatefragment) for additional information. + */ public updateQuery( mapFn: ( previousQueryResult: TData, @@ -679,11 +695,17 @@ Did you mean to call refetch(variables) instead of refetch({ variables })?`, } } + /** + * A function that instructs the query to begin re-executing at a specified interval (in milliseconds). + */ public startPolling(pollInterval: number) { this.options.pollInterval = pollInterval; this.updatePolling(); } + /** + * A function that instructs the query to stop polling after a previous call to `startPolling`. + */ public stopPolling() { this.options.pollInterval = 0; this.updatePolling(); diff --git a/src/core/types.ts b/src/core/types.ts index eeda05fa41c..8085d013839 100644 --- a/src/core/types.ts +++ b/src/core/types.ts @@ -139,7 +139,7 @@ export type { QueryOptions as PureQueryOptions }; export type OperationVariables = Record; -export type ApolloQueryResult = { +export interface ApolloQueryResult { data: T; /** * A list of any errors that occurred during server-side execution of a GraphQL operation. @@ -158,7 +158,7 @@ export type ApolloQueryResult = { // result.partial will be true. Otherwise, result.partial will be falsy // (usually because the property is absent from the result object). partial?: boolean; -}; +} // This is part of the public API, people write these functions in `updateQueries`. export type MutationQueryReducer = ( @@ -174,7 +174,9 @@ export type MutationQueryReducersMap = { [queryName: string]: MutationQueryReducer; }; -// @deprecated Use MutationUpdaterFunction instead. +/** + * @deprecated Use `MutationUpdaterFunction` instead. + */ export type MutationUpdaterFn = ( // The MutationUpdaterFn type is broken because it mistakenly uses the same // type parameter T for both the cache and the mutationResult. Do not use this diff --git a/src/core/watchQueryOptions.ts b/src/core/watchQueryOptions.ts index c4844826c75..5810c6464c4 100644 --- a/src/core/watchQueryOptions.ts +++ b/src/core/watchQueryOptions.ts @@ -52,70 +52,34 @@ export type ErrorPolicy = "none" | "ignore" | "all"; * Query options. */ export interface QueryOptions { - /** - * A GraphQL document that consists of a single query to be sent down to the - * server. - */ - // TODO REFACTOR: rename this to document. Didn't do it yet because it's in a - // lot of tests. + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#query:member} */ query: DocumentNode | TypedDocumentNode; - /** - * A map going from variable name to variable value, where the variables are used - * within the GraphQL query. - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#variables:member} */ variables?: TVariables; - /** - * Specifies the {@link ErrorPolicy} to be used for this query - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#errorPolicy:member} */ errorPolicy?: ErrorPolicy; - /** - * Context to be passed to link execution chain - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#context:member} */ context?: DefaultContext; - /** - * Specifies the {@link FetchPolicy} to be used for this query - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#fetchPolicy:member} */ fetchPolicy?: FetchPolicy; - /** - * The time interval (in milliseconds) on which this query should be - * refetched from the server. - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#pollInterval:member} */ pollInterval?: number; - /** - * Whether or not updates to the network status should trigger next on the observer of this query - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#notifyOnNetworkStatusChange:member} */ notifyOnNetworkStatusChange?: boolean; - /** - * Allow returning incomplete data from the cache when a larger query cannot - * be fully satisfied by the cache, instead of returning nothing. - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#returnPartialData:member} */ returnPartialData?: boolean; - /** - * If `true`, perform a query `refetch` if the query result is marked as - * being partial, and the returned data is reset to an empty Object by the - * Apollo Client `QueryManager` (due to a cache miss). - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#partialRefetch:member} */ partialRefetch?: boolean; - /** - * @deprecated - * Using `canonizeResults` can result in memory leaks so we generally do not - * recommend using this option anymore. - * A future version of Apollo Client will contain a similar feature without - * the risk of memory leaks. - * - * Whether to canonize cache results before returning them. Canonization - * takes some extra time, but it speeds up future deep equality comparisons. - * Defaults to false. - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#canonizeResults:member} */ canonizeResults?: boolean; } @@ -125,15 +89,19 @@ export interface QueryOptions { export interface WatchQueryOptions< TVariables extends OperationVariables = OperationVariables, TData = any, +> extends SharedWatchQueryOptions { + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#query:member} */ + query: DocumentNode | TypedDocumentNode; +} + +export interface SharedWatchQueryOptions< + TVariables extends OperationVariables, + TData, > { - /** - * Specifies the {@link FetchPolicy} to be used for this query. - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#fetchPolicy:member} */ fetchPolicy?: WatchQueryFetchPolicy; - /** - * Specifies the {@link FetchPolicy} to be used after this query has completed. - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#nextFetchPolicy:member} */ nextFetchPolicy?: | WatchQueryFetchPolicy | (( @@ -142,53 +110,37 @@ export interface WatchQueryOptions< context: NextFetchPolicyContext ) => WatchQueryFetchPolicy); - /** - * Defaults to the initial value of options.fetchPolicy, but can be explicitly - * configured to specify the WatchQueryFetchPolicy to revert back to whenever - * variables change (unless nextFetchPolicy intervenes). - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#initialFetchPolicy:member} */ initialFetchPolicy?: WatchQueryFetchPolicy; - /** - * Specifies whether a {@link NetworkStatus.refetch} operation should merge - * incoming field data with existing data, or overwrite the existing data. - * Overwriting is probably preferable, but merging is currently the default - * behavior, for backwards compatibility with Apollo Client 3.x. - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#refetchWritePolicy:member} */ refetchWritePolicy?: RefetchWritePolicy; - /** {@inheritDoc @apollo/client!QueryOptions#query:member} */ - query: DocumentNode | TypedDocumentNode; - - /** {@inheritDoc @apollo/client!QueryOptions#variables:member} */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#variables:member} */ variables?: TVariables; - /** {@inheritDoc @apollo/client!QueryOptions#errorPolicy:member} */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#errorPolicy:member} */ errorPolicy?: ErrorPolicy; - /** {@inheritDoc @apollo/client!QueryOptions#context:member} */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#context:member} */ context?: DefaultContext; - /** {@inheritDoc @apollo/client!QueryOptions#pollInterval:member} */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#pollInterval:member} */ pollInterval?: number; - /** {@inheritDoc @apollo/client!QueryOptions#notifyOnNetworkStatusChange:member} */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#notifyOnNetworkStatusChange:member} */ notifyOnNetworkStatusChange?: boolean; - /** {@inheritDoc @apollo/client!QueryOptions#returnPartialData:member} */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#returnPartialData:member} */ returnPartialData?: boolean; - /** {@inheritDoc @apollo/client!QueryOptions#partialRefetch:member} */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#partialRefetch:member} */ partialRefetch?: boolean; - /** {@inheritDoc @apollo/client!QueryOptions#canonizeResults:member} */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#canonizeResults:member} */ canonizeResults?: boolean; - /** - * A callback function that's called whenever a refetch attempt occurs - * while polling. If the function returns `true`, the refetch is - * skipped and not reattempted until the next poll interval. - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#skipPollAttempt:member} */ skipPollAttempt?: () => boolean; } @@ -203,7 +155,9 @@ export interface NextFetchPolicyContext< } export interface FetchMoreQueryOptions { + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#query:member} */ query?: DocumentNode | TypedDocumentNode; + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#variables:member} */ variables?: Partial; context?: DefaultContext; } @@ -238,31 +192,19 @@ export interface SubscriptionOptions< TVariables = OperationVariables, TData = any, > { - /** - * A GraphQL document, often created with `gql` from the `graphql-tag` - * package, that contains a single subscription inside of it. - */ + /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#query:member} */ query: DocumentNode | TypedDocumentNode; - /** - * An object that maps from the name of a variable as used in the subscription - * GraphQL document to that variable's value. - */ + /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#variables:member} */ variables?: TVariables; - /** - * Specifies the {@link FetchPolicy} to be used for this subscription. - */ + /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#fetchPolicy:member} */ fetchPolicy?: FetchPolicy; - /** - * Specifies the {@link ErrorPolicy} to be used for this operation - */ + /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#errorPolicy:member} */ errorPolicy?: ErrorPolicy; - /** - * Context object to be passed through the link execution chain. - */ + /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#context:member} */ context?: DefaultContext; } @@ -272,94 +214,35 @@ export interface MutationBaseOptions< TContext = DefaultContext, TCache extends ApolloCache = ApolloCache, > { - /** - * An object that represents the result of this mutation that will be - * optimistically stored before the server has actually returned a result. - * This is most often used for optimistic UI, where we want to be able to see - * the result of a mutation immediately, and update the UI later if any errors - * appear. - */ + /** {@inheritDoc @apollo/client!MutationOptionsDocumentation#optimisticResponse:member} */ optimisticResponse?: | TData | ((vars: TVariables, { IGNORE }: { IGNORE: IgnoreModifier }) => TData); - /** - * A {@link MutationQueryReducersMap}, which is map from query names to - * mutation query reducers. Briefly, this map defines how to incorporate the - * results of the mutation into the results of queries that are currently - * being watched by your application. - */ + /** {@inheritDoc @apollo/client!MutationOptionsDocumentation#updateQueries:member} */ updateQueries?: MutationQueryReducersMap; - /** - * A list of query names which will be refetched once this mutation has - * returned. This is often used if you have a set of queries which may be - * affected by a mutation and will have to update. Rather than writing a - * mutation query reducer (i.e. `updateQueries`) for this, you can simply - * refetch the queries that will be affected and achieve a consistent store - * once these queries return. - */ + /** {@inheritDoc @apollo/client!MutationOptionsDocumentation#refetchQueries:member} */ refetchQueries?: | ((result: FetchResult) => InternalRefetchQueriesInclude) | InternalRefetchQueriesInclude; - /** - * By default, `refetchQueries` does not wait for the refetched queries to - * be completed, before resolving the mutation `Promise`. This ensures that - * query refetching does not hold up mutation response handling (query - * refetching is handled asynchronously). Set `awaitRefetchQueries` to - * `true` if you would like to wait for the refetched queries to complete, - * before the mutation can be marked as resolved. - */ + /** {@inheritDoc @apollo/client!MutationOptionsDocumentation#awaitRefetchQueries:member} */ awaitRefetchQueries?: boolean; - /** - * A function which provides an {@link ApolloCache} instance, and the result - * of the mutation, to allow the user to update the store based on the - * results of the mutation. - * - * This function will be called twice over the lifecycle of a mutation. Once - * at the very beginning if an `optimisticResponse` was provided. The writes - * created from the optimistic data will be rolled back before the second time - * this function is called which is when the mutation has successfully - * resolved. At that point `update` will be called with the *actual* mutation - * result and those writes will not be rolled back. - * - * Note that since this function is intended to be used to update the - * store, it cannot be used with a `no-cache` fetch policy. If you're - * interested in performing some action after a mutation has completed, - * and you don't need to update the store, use the Promise returned from - * `client.mutate` instead. - */ + /** {@inheritDoc @apollo/client!MutationOptionsDocumentation#update:member} */ update?: MutationUpdaterFunction; - /** - * A function that will be called for each ObservableQuery affected by - * this mutation, after the mutation has completed. - */ + /** {@inheritDoc @apollo/client!MutationOptionsDocumentation#onQueryUpdated:member} */ onQueryUpdated?: OnQueryUpdated; - /** - * Specifies the {@link ErrorPolicy} to be used for this operation - */ + /** {@inheritDoc @apollo/client!MutationOptionsDocumentation#errorPolicy:member} */ errorPolicy?: ErrorPolicy; - /** - * An object that maps from the name of a variable as used in the mutation - * GraphQL document to that variable's value. - */ + /** {@inheritDoc @apollo/client!MutationOptionsDocumentation#variables:member} */ variables?: TVariables; - /** - * The context to be passed to the link execution chain. This context will - * only be used with this mutation. It will not be used with - * `refetchQueries`. Refetched queries use the context they were - * initialized with (since the initial context is stored as part of the - * `ObservableQuery` instance). If a specific context is needed when - * refetching queries, make sure it is configured (via the - * [query `context` option](https://www.apollographql.com/docs/react/api/apollo-client#ApolloClient.query)) - * when the query is first initialized/run. - */ + /** {@inheritDoc @apollo/client!MutationOptionsDocumentation#context:member} */ context?: TContext; } @@ -368,28 +251,19 @@ export interface MutationOptions< TVariables = OperationVariables, TContext = DefaultContext, TCache extends ApolloCache = ApolloCache, -> extends MutationBaseOptions { - /** - * A GraphQL document, often created with `gql` from the `graphql-tag` - * package, that contains a single mutation inside of it. - */ +> extends MutationSharedOptions { + /** {@inheritDoc @apollo/client!MutationOptionsDocumentation#mutation:member} */ mutation: DocumentNode | TypedDocumentNode; - - /** - * Specifies the {@link MutationFetchPolicy} to be used for this query. - * Mutations support only 'network-only' and 'no-cache' fetchPolicy strings. - * If fetchPolicy is not provided, it defaults to 'network-only'. - */ +} +export interface MutationSharedOptions< + TData = any, + TVariables = OperationVariables, + TContext = DefaultContext, + TCache extends ApolloCache = ApolloCache, +> extends MutationBaseOptions { + /** {@inheritDoc @apollo/client!MutationOptionsDocumentation#fetchPolicy:member} */ fetchPolicy?: MutationFetchPolicy; - /** - * To avoid retaining sensitive information from mutation root field - * arguments, Apollo Client v3.4+ automatically clears any `ROOT_MUTATION` - * fields from the cache after each mutation finishes. If you need this - * information to remain in the cache, you can prevent the removal by passing - * `keepRootFields: true` to the mutation. `ROOT_MUTATION` result data are - * also passed to the mutation `update` function, so we recommend obtaining - * the results that way, rather than using this option, if possible. - */ + /** {@inheritDoc @apollo/client!MutationOptionsDocumentation#keepRootFields:member} */ keepRootFields?: boolean; } diff --git a/src/react/components/types.ts b/src/react/components/types.ts index a0114f65ae2..a742b905ac6 100644 --- a/src/react/components/types.ts +++ b/src/react/components/types.ts @@ -45,6 +45,7 @@ export interface SubscriptionComponentOptions< TData = any, TVariables extends OperationVariables = OperationVariables, > extends BaseSubscriptionOptions { + /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#query:member} */ subscription: DocumentNode | TypedDocumentNode; children?: | null diff --git a/src/react/hooks/useApolloClient.ts b/src/react/hooks/useApolloClient.ts index 54bf7bd0874..8f4fdc80f0c 100644 --- a/src/react/hooks/useApolloClient.ts +++ b/src/react/hooks/useApolloClient.ts @@ -3,6 +3,21 @@ import * as React from "rehackt"; import type { ApolloClient } from "../../core/index.js"; import { getApolloContext } from "../context/index.js"; +/** + * @example + * ```jsx + * import { useApolloClient } from '@apollo/client'; + * + * 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`) + * } + * ``` + * + * @since 3.0.0 + * @returns The `ApolloClient` instance being used by the application. + */ export function useApolloClient( override?: ApolloClient ): ApolloClient { diff --git a/src/react/hooks/useLazyQuery.ts b/src/react/hooks/useLazyQuery.ts index e0f237dffbc..6c58c86e3ce 100644 --- a/src/react/hooks/useLazyQuery.ts +++ b/src/react/hooks/useLazyQuery.ts @@ -25,6 +25,41 @@ const EAGER_METHODS = [ "subscribeToMore", ] as const; +/** + * A hook for imperatively executing queries in an Apollo application, e.g. in response to user interaction. + * + * > Refer to the [Queries - Manual execution with useLazyQuery](https://www.apollographql.com/docs/react/data/queries#manual-execution-with-uselazyquery) section for a more in-depth overview of `useLazyQuery`. + * + * @example + * ```jsx + * import { gql, useLazyQuery } from "@apollo/client"; + * + * const GET_GREETING = gql` + * query GetGreeting($language: String!) { + * greeting(language: $language) { + * message + * } + * } + * `; + * + * function Hello() { + * const [loadGreeting, { called, loading, data }] = useLazyQuery( + * GET_GREETING, + * { variables: { language: "english" } } + * ); + * if (called && loading) return

Loading ...

+ * if (!called) { + * return + * } + * return

Hello {data.greeting.message}!

; + * } + * ``` + * @since 3.0.0 + * + * @param query - A GraphQL query document parsed into an AST by `gql`. + * @param options - Default options to control how the query is executed. + * @returns A tuple in the form of `[execute, result]` + */ export function useLazyQuery< TData = any, TVariables extends OperationVariables = OperationVariables, diff --git a/src/react/hooks/useMutation.ts b/src/react/hooks/useMutation.ts index ac3d3cfea8f..79825f91524 100644 --- a/src/react/hooks/useMutation.ts +++ b/src/react/hooks/useMutation.ts @@ -21,6 +21,53 @@ import { DocumentType, verifyDocumentType } from "../parser/index.js"; import { ApolloError } from "../../errors/index.js"; import { useApolloClient } from "./useApolloClient.js"; +/** + * + * + * > Refer to the [Mutations](https://www.apollographql.com/docs/react/data/mutations/) section for a more in-depth overview of `useMutation`. + * + * @example + * ```jsx + * import { gql, useMutation } from '@apollo/client'; + * + * const ADD_TODO = gql` + * mutation AddTodo($type: String!) { + * addTodo(type: $type) { + * id + * type + * } + * } + * `; + * + * function AddTodo() { + * let input; + * const [addTodo, { data }] = useMutation(ADD_TODO); + * + * return ( + *
+ *
{ + * e.preventDefault(); + * addTodo({ variables: { type: input.value } }); + * input.value = ''; + * }} + * > + * { + * input = node; + * }} + * /> + * + *
+ *
+ * ); + * } + * ``` + * @since 3.0.0 + * @param mutation - A GraphQL mutation document parsed into an AST by `gql`. + * @param options - Options to control how the mutation is executed. + * @returns A tuple in the form of `[mutate, result]` + */ export function useMutation< TData = any, TVariables = OperationVariables, diff --git a/src/react/hooks/useQuery.ts b/src/react/hooks/useQuery.ts index b83f8558888..4bc596ed371 100644 --- a/src/react/hooks/useQuery.ts +++ b/src/react/hooks/useQuery.ts @@ -41,6 +41,40 @@ const { prototype: { hasOwnProperty }, } = Object; +/** + * A hook for executing queries in an Apollo application. + * + * To run a query within a React component, call `useQuery` and pass it a GraphQL query document. + * + * When your component renders, `useQuery` returns an object from Apollo Client that contains `loading`, `error`, and `data` properties you can use to render your UI. + * + * > Refer to the [Queries](https://www.apollographql.com/docs/react/data/queries) section for a more in-depth overview of `useQuery`. + * + * @example + * ```jsx + * import { gql, useQuery } from '@apollo/client'; + * + * const GET_GREETING = gql` + * query GetGreeting($language: String!) { + * greeting(language: $language) { + * message + * } + * } + * `; + * + * function Hello() { + * const { loading, error, data } = useQuery(GET_GREETING, { + * variables: { language: 'english' }, + * }); + * if (loading) return

Loading ...

; + * return

Hello {data.greeting.message}!

; + * } + * ``` + * @since 3.0.0 + * @param query - A GraphQL query document parsed into an AST by `gql`. + * @param options - Options to control how the query is executed. + * @returns Query result object + */ export function useQuery< TData = any, TVariables extends OperationVariables = OperationVariables, diff --git a/src/react/hooks/useReactiveVar.ts b/src/react/hooks/useReactiveVar.ts index b98c4401e69..ed7ac2379d3 100644 --- a/src/react/hooks/useReactiveVar.ts +++ b/src/react/hooks/useReactiveVar.ts @@ -2,6 +2,23 @@ import * as React from "rehackt"; import type { ReactiveVar } from "../../core/index.js"; import { useSyncExternalStore } from "./useSyncExternalStore.js"; +/** + * Reads the value of a [reactive variable](https://www.apollographql.com/docs/react/local-state/reactive-variables/) and re-renders the containing component whenever that variable's value changes. This enables a reactive variable to trigger changes _without_ relying on the `useQuery` hook. + * + * @example + * ```jsx + * import { makeVar, useReactiveVar } from "@apollo/client"; + * export const cartItemsVar = makeVar([]); + * + * export function Cart() { + * const cartItems = useReactiveVar(cartItemsVar); + * // ... + * } + * ``` + * @since 3.2.0 + * @param rv - A reactive variable. + * @returns The current value of the reactive variable. + */ export function useReactiveVar(rv: ReactiveVar): T { return useSyncExternalStore( React.useCallback( diff --git a/src/react/hooks/useSubscription.ts b/src/react/hooks/useSubscription.ts index 33029adbb9a..366ebfe97f4 100644 --- a/src/react/hooks/useSubscription.ts +++ b/src/react/hooks/useSubscription.ts @@ -12,7 +12,91 @@ import type { } from "../types/types.js"; import type { OperationVariables } from "../../core/index.js"; import { useApolloClient } from "./useApolloClient.js"; - +/** + * > Refer to the [Subscriptions](https://www.apollographql.com/docs/react/data/subscriptions/) section for a more in-depth overview of `useSubscription`. + * + * @example + * ```jsx + * const COMMENTS_SUBSCRIPTION = gql` + * subscription OnCommentAdded($repoFullName: String!) { + * commentAdded(repoFullName: $repoFullName) { + * id + * content + * } + * } + * `; + * + * function DontReadTheComments({ repoFullName }) { + * const { + * data: { commentAdded }, + * loading, + * } = useSubscription(COMMENTS_SUBSCRIPTION, { variables: { repoFullName } }); + * return

New comment: {!loading && commentAdded.content}

; + * } + * ``` + * @remarks + * #### Subscriptions and React 18 Automatic Batching + * + * With React 18's [automatic batching](https://react.dev/blog/2022/03/29/react-v18#new-feature-automatic-batching), multiple state updates may be grouped into a single re-render for better performance. + * + * If your subscription API sends multiple messages at the same time or in very fast succession (within fractions of a millisecond), it is likely that only the last message received in that narrow time frame will result in a re-render. + * + * Consider the following component: + * + * ```jsx + * export function Subscriptions() { + * const { data, error, loading } = useSubscription(query); + * const [accumulatedData, setAccumulatedData] = useState([]); + * + * useEffect(() => { + * setAccumulatedData((prev) => [...prev, data]); + * }, [data]); + * + * return ( + * <> + * {loading &&

Loading...

} + * {JSON.stringify(accumulatedData, undefined, 2)} + * + * ); + * } + * ``` + * + * If your subscription back-end emits two messages with the same timestamp, only the last message received by Apollo Client will be rendered. This is because React 18 will batch these two state updates into a single re-render. + * + * Since the component above is using `useEffect` to push `data` into a piece of local state on each `Subscriptions` re-render, the first message will never be added to the `accumulatedData` array since its render was skipped. + * + * Instead of using `useEffect` here, we can re-write this component to use the `onData` callback function accepted in `useSubscription`'s `options` object: + * + * ```jsx + * export function Subscriptions() { + * const [accumulatedData, setAccumulatedData] = useState([]); + * const { data, error, loading } = useSubscription( + * query, + * { + * onData({ data }) { + * setAccumulatedData((prev) => [...prev, data]) + * } + * } + * ); + * + * return ( + * <> + * {loading &&

Loading...

} + * {JSON.stringify(accumulatedData, undefined, 2)} + * + * ); + * } + * ``` + * + * > ⚠️ **Note:** The `useSubscription` option `onData` is available in Apollo Client >= 3.7. In previous versions, the equivalent option is named `onSubscriptionData`. + * + * 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`. + * + * @since 3.0.0 + * @param subscription - A GraphQL subscription document parsed into an AST by `gql`. + * @param options - Options to control how the subscription is executed. + * @returns Query result object + */ export function useSubscription< TData = any, TVariables extends OperationVariables = OperationVariables, diff --git a/src/react/query-preloader/createQueryPreloader.ts b/src/react/query-preloader/createQueryPreloader.ts index f5a3a03ab05..12b7efd7983 100644 --- a/src/react/query-preloader/createQueryPreloader.ts +++ b/src/react/query-preloader/createQueryPreloader.ts @@ -20,16 +20,16 @@ import type { NoInfer } from "../index.js"; type VariablesOption = [TVariables] extends [never] ? { - /** {@inheritDoc @apollo/client!QueryOptions#variables:member} */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#variables:member} */ variables?: Record; } : {} extends OnlyRequiredProperties ? { - /** {@inheritDoc @apollo/client!QueryOptions#variables:member} */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#variables:member} */ variables?: TVariables; } : { - /** {@inheritDoc @apollo/client!QueryOptions#variables:member} */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#variables:member} */ variables: TVariables; }; @@ -41,17 +41,17 @@ export type PreloadQueryFetchPolicy = Extract< export type PreloadQueryOptions< TVariables extends OperationVariables = OperationVariables, > = { - /** {@inheritDoc @apollo/client!QueryOptions#canonizeResults:member} */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#canonizeResults:member} */ canonizeResults?: boolean; - /** {@inheritDoc @apollo/client!QueryOptions#context:member} */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#context:member} */ context?: DefaultContext; - /** {@inheritDoc @apollo/client!QueryOptions#errorPolicy:member} */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#errorPolicy:member} */ errorPolicy?: ErrorPolicy; - /** {@inheritDoc @apollo/client!QueryOptions#fetchPolicy:member} */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#fetchPolicy:member} */ fetchPolicy?: PreloadQueryFetchPolicy; - /** {@inheritDoc @apollo/client!QueryOptions#returnPartialData:member} */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#returnPartialData:member} */ returnPartialData?: boolean; - /** {@inheritDoc @apollo/client!WatchQueryOptions#refetchWritePolicy:member} */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#refetchWritePolicy:member} */ refetchWritePolicy?: RefetchWritePolicy; } & VariablesOption; diff --git a/src/react/types/types.documentation.ts b/src/react/types/types.documentation.ts new file mode 100644 index 00000000000..364e8e3f188 --- /dev/null +++ b/src/react/types/types.documentation.ts @@ -0,0 +1,598 @@ +export interface QueryOptionsDocumentation { + /** + * A GraphQL query string parsed into an AST with the gql template literal. + * + * @docGroup 1. Operation options + */ + query: unknown; + + /** + * An object containing all of the GraphQL variables your query requires to execute. + * + * Each key in the object corresponds to a variable name, and that key's value corresponds to the variable value. + * + * @docGroup 1. Operation options + */ + variables: unknown; + + /** + * Specifies how the query handles a response that returns both GraphQL errors and partial results. + * + * For details, see [GraphQL error policies](https://www.apollographql.com/docs/react/data/error-handling/#graphql-error-policies). + * + * The default value is `none`, meaning that the query result includes error details but not partial results. + * + * @docGroup 1. Operation options + */ + errorPolicy: unknown; + + /** + * If you're using [Apollo Link](https://www.apollographql.com/docs/react/api/link/introduction/), this object is the initial value of the `context` object that's passed along your link chain. + * + * @docGroup 2. Networking options + */ + context: unknown; + + /** + * Specifies how the query interacts with the Apollo Client cache during execution (for example, whether it checks the cache for results before sending a request to the server). + * + * For details, see [Setting a fetch policy](https://www.apollographql.com/docs/react/data/queries/#setting-a-fetch-policy). + * + * The default value is `cache-first`. + * + * @docGroup 3. Caching options + */ + fetchPolicy: unknown; + + /** + * Specifies the {@link FetchPolicy} to be used after this query has completed. + * + * @docGroup 3. Caching options + */ + nextFetchPolicy: unknown; + + /** + * Defaults to the initial value of options.fetchPolicy, but can be explicitly + * configured to specify the WatchQueryFetchPolicy to revert back to whenever + * variables change (unless nextFetchPolicy intervenes). + * + * @docGroup 3. Caching options + */ + initialFetchPolicy: unknown; + + /** + * Specifies the interval (in milliseconds) at which the query polls for updated results. + * + * The default value is `0` (no polling). + * + * @docGroup 2. Networking options + */ + pollInterval: unknown; + + /** + * If `true`, the in-progress query's associated component re-renders whenever the network status changes or a network error occurs. + * + * The default value is `false`. + * + * @docGroup 2. Networking options + */ + notifyOnNetworkStatusChange: unknown; + + /** + * If `true`, the query can return partial results from the cache if the cache doesn't contain results for all queried fields. + * + * The default value is `false`. + * + * @docGroup 3. Caching options + */ + returnPartialData: unknown; + + /** + * Specifies whether a `NetworkStatus.refetch` operation should merge + * incoming field data with existing data, or overwrite the existing data. + * Overwriting is probably preferable, but merging is currently the default + * behavior, for backwards compatibility with Apollo Client 3.x. + * + * @docGroup 3. Caching options + */ + refetchWritePolicy: unknown; + + /** + * Watched queries must opt into overwriting existing data on refetch, by passing refetchWritePolicy: "overwrite" in their WatchQueryOptions. + * + * The default value is "overwrite". + * + * @docGroup 3. Caching options + */ + refetchWritePolicy_suspense: unknown; + + /** + * If `true`, causes a query refetch if the query result is detected as partial. + * + * The default value is `false`. + * + * @deprecated + * Setting this option is unnecessary in Apollo Client 3, thanks to a more consistent application of fetch policies. It might be removed in a future release. + */ + partialRefetch: unknown; + + /** + * Whether to canonize cache results before returning them. Canonization + * takes some extra time, but it speeds up future deep equality comparisons. + * Defaults to false. + * + * @deprecated + * Using `canonizeResults` can result in memory leaks so we generally do not + * recommend using this option anymore. + * A future version of Apollo Client will contain a similar feature without + * the risk of memory leaks. + */ + canonizeResults: unknown; + + /** + * If true, the query is not executed. + * + * The default value is `false`. + * + * @docGroup 1. Operation options + */ + skip: unknown; + + /** + * If `true`, the query is not executed. The default value is `false`. + * + * @deprecated We recommend using `skipToken` in place of the `skip` option as + * it is more type-safe. + * + * This option is deprecated and only supported to ease the migration from useQuery. It will be removed in a future release. + * + * @docGroup 1. Operation options + */ + skip_deprecated: unknown; + + /** + * A callback function that's called when your query successfully completes with zero errors (or if `errorPolicy` is `ignore` and partial data is returned). + * + * This function is passed the query's result `data`. + * + * @docGroup 1. Operation options + */ + onCompleted: unknown; + /** + * A callback function that's called when the query encounters one or more errors (unless `errorPolicy` is `ignore`). + * + * This function is passed an `ApolloError` object that contains either a `networkError` object or a `graphQLErrors` array, depending on the error(s) that occurred. + * + * @docGroup 1. Operation options + */ + onError: unknown; + + /** + * The instance of {@link ApolloClient} to use to execute the query. + * + * 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: unknown; + + /** + * A unique identifier for the query. Each item in the array must be a stable + * identifier to prevent infinite fetches. + * + * This is useful when using the same query and variables combination in more + * than one component, otherwise the components may clobber each other. This + * can also be used to force the query to re-evaluate fresh. + * + * @docGroup 1. Operation options + */ + queryKey: unknown; + + /** + * Pass `false` to skip executing the query during [server-side rendering](https://www.apollographql.com/docs/react/performance/server-side-rendering/). + * + * @docGroup 2. Networking options + */ + ssr: unknown; + + /** + * A callback function that's called whenever a refetch attempt occurs + * while polling. If the function returns `true`, the refetch is + * skipped and not reattempted until the next poll interval. + * + * @docGroup 2. Networking options + */ + skipPollAttempt: unknown; +} + +export interface QueryResultDocumentation { + /** + * The instance of Apollo Client that executed the query. + * Can be useful for manually executing followup queries or writing data to the cache. + * + * @docGroup 2. Network info + */ + client: unknown; + /** + * A reference to the internal `ObservableQuery` used by the hook. + */ + observable: unknown; + /** + * 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: unknown; + /** + * An object containing the result from the most recent _previous_ execution of this query. + * + * This value is `undefined` if this is the query's first execution. + * + * @docGroup 1. Operation data + */ + previousData: unknown; + /** + * If the query produces one or more errors, this object contains either an array of `graphQLErrors` or a single `networkError`. Otherwise, this value is `undefined`. + * + * For more information, see [Handling operation errors](https://www.apollographql.com/docs/react/data/error-handling/). + * + * @docGroup 1. Operation data + */ + error: unknown; + /** + * If `true`, the query is still in flight and results have not yet been returned. + * + * @docGroup 2. Network info + */ + loading: unknown; + /** + * A number indicating the current network state of the query's associated request. [See possible values.](https://github.com/apollographql/apollo-client/blob/d96f4578f89b933c281bb775a39503f6cdb59ee8/src/core/networkStatus.ts#L4) + * + * Used in conjunction with the [`notifyOnNetworkStatusChange`](#notifyonnetworkstatuschange) option. + * + * @docGroup 2. Network info + */ + networkStatus: unknown; + /** + * If `true`, the associated lazy query has been executed. + * + * This field is only present on the result object returned by [`useLazyQuery`](/react/data/queries/#executing-queries-manually). + * + * @docGroup 2. Network info + */ + called: unknown; + /** + * An object containing the variables that were provided for the query. + * + * @docGroup 1. Operation data + */ + variables: unknown; + + /** + * A function that enables you to re-execute the query, optionally passing in new `variables`. + * + * To guarantee that the refetch performs a network request, its `fetchPolicy` is set to `network-only` (unless the original query's `fetchPolicy` is `no-cache` or `cache-and-network`, which also guarantee a network request). + * + * See also [Refetching](https://www.apollographql.com/docs/react/data/queries/#refetching). + * + * @docGroup 3. Helper functions + */ + refetch: unknown; + /** + * {@inheritDoc @apollo/client!ObservableQuery#fetchMore:member(1)} + * + * @docGroup 3. Helper functions + */ + fetchMore: unknown; + /** + * {@inheritDoc @apollo/client!ObservableQuery#startPolling:member(1)} + * + * @docGroup 3. Helper functions + */ + startPolling: unknown; + /** + * {@inheritDoc @apollo/client!ObservableQuery#stopPolling:member(1)} + * + * @docGroup 3. Helper functions + */ + stopPolling: unknown; + /** + * {@inheritDoc @apollo/client!ObservableQuery#subscribeToMore:member(1)} + * + * @docGroup 3. Helper functions + */ + subscribeToMore: unknown; + /** + * {@inheritDoc @apollo/client!ObservableQuery#updateQuery:member(1)} + * + * @docGroup 3. Helper functions + */ + updateQuery: unknown; +} + +export interface MutationOptionsDocumentation { + /** + * A GraphQL document, often created with `gql` from the `graphql-tag` + * package, that contains a single mutation inside of it. + * + * @docGroup 1. Operation options + */ + mutation: unknown; + + /** + * Provide `no-cache` if the mutation's result should _not_ be written to the Apollo Client cache. + * + * The default value is `network-only` (which means the result _is_ written to the cache). + * + * Unlike queries, mutations _do not_ support [fetch policies](https://www.apollographql.com/docs/react/data/queries/#setting-a-fetch-policy) besides `network-only` and `no-cache`. + * + * @docGroup 3. Caching options + */ + fetchPolicy: unknown; + + /** + * To avoid retaining sensitive information from mutation root field + * arguments, Apollo Client v3.4+ automatically clears any `ROOT_MUTATION` + * fields from the cache after each mutation finishes. If you need this + * information to remain in the cache, you can prevent the removal by passing + * `keepRootFields: true` to the mutation. `ROOT_MUTATION` result data are + * also passed to the mutation `update` function, so we recommend obtaining + * the results that way, rather than using this option, if possible. + */ + keepRootFields: unknown; + + /** + * By providing either an object or a callback function that, when invoked after + * a mutation, allows you to return optimistic data and optionally skip updates + * via the `IGNORE` sentinel object, Apollo Client caches this temporary + * (and potentially incorrect) response until the mutation completes, enabling + * more responsive UI updates. + * + * For more information, see [Optimistic mutation results](https://www.apollographql.com/docs/react/performance/optimistic-ui/). + * + * @docGroup 3. Caching options + */ + optimisticResponse: unknown; + + /** + * A {@link MutationQueryReducersMap}, which is map from query names to + * mutation query reducers. Briefly, this map defines how to incorporate the + * results of the mutation into the results of queries that are currently + * being watched by your application. + */ + updateQueries: unknown; + + /** + * An array (or a function that _returns_ an array) that specifies which queries you want to refetch after the mutation occurs. + * + * Each array value can be either: + * + * - An object containing the `query` to execute, along with any `variables` + * + * - A string indicating the operation name of the query to refetch + * + * @docGroup 1. Operation options + */ + refetchQueries: unknown; + + /** + * If `true`, makes sure all queries included in `refetchQueries` are completed before the mutation is considered complete. + * + * The default value is `false` (queries are refetched asynchronously). + * + * @docGroup 1. Operation options + */ + awaitRefetchQueries: unknown; + + /** + * A function used to update the Apollo Client cache after the mutation completes. + * + * For more information, see [Updating the cache after a mutation](https://www.apollographql.com/docs/react/data/mutations#updating-the-cache-after-a-mutation). + * + * @docGroup 3. Caching options + */ + update: unknown; + + /** + * Optional callback for intercepting queries whose cache data has been updated by the mutation, as well as any queries specified in the `refetchQueries: [...]` list passed to `client.mutate`. + * + * Returning a `Promise` from `onQueryUpdated` will cause the final mutation `Promise` to await the returned `Promise`. Returning `false` causes the query to be ignored. + * + * @docGroup 1. Operation options + */ + onQueryUpdated: unknown; + + /** + * Specifies how the mutation handles a response that returns both GraphQL errors and partial results. + * + * For details, see [GraphQL error policies](https://www.apollographql.com/docs/react/data/error-handling/#graphql-error-policies). + * + * The default value is `none`, meaning that the mutation result includes error details but _not_ partial results. + * + * @docGroup 1. Operation options + */ + errorPolicy: unknown; + + /** + * An object containing all of the GraphQL variables your mutation requires to execute. + * + * Each key in the object corresponds to a variable name, and that key's value corresponds to the variable value. + * + * @docGroup 1. Operation options + */ + variables: unknown; + + /** + * If you're using [Apollo Link](https://www.apollographql.com/docs/react/api/link/introduction/), this object is the initial value of the `context` object that's passed along your link chain. + * + * @docGroup 2. Networking options + */ + context: unknown; + + /** + * The instance of `ApolloClient` to use to execute the mutation. + * + * By default, the instance that's passed down via context is used, but you can provide a different instance here. + * + * @docGroup 2. Networking options + */ + client: unknown; + /** + * If `true`, the in-progress mutation's associated component re-renders whenever the network status changes or a network error occurs. + * + * The default value is `false`. + * + * @docGroup 2. Networking options + */ + notifyOnNetworkStatusChange: unknown; + /** + * A callback function that's called when your mutation successfully completes with zero errors (or if `errorPolicy` is `ignore` and partial data is returned). + * + * This function is passed the mutation's result `data` and any options passed to the mutation. + * + * @docGroup 1. Operation options + */ + onCompleted: unknown; + /** + * A callback function that's called when the mutation encounters one or more errors (unless `errorPolicy` is `ignore`). + * + * This function is passed an [`ApolloError`](https://github.com/apollographql/apollo-client/blob/d96f4578f89b933c281bb775a39503f6cdb59ee8/src/errors/index.ts#L36-L39) object that contains either a `networkError` object or a `graphQLErrors` array, depending on the error(s) that occurred, as well as any options passed the mutation. + * + * @docGroup 1. Operation options + */ + onError: unknown; + /** + * If `true`, the mutation's `data` property is not updated with the mutation's result. + * + * The default value is `false`. + * + * @docGroup 1. Operation options + */ + ignoreResults: unknown; +} + +export interface MutationResultDocumentation { + /** + * The data returned from your mutation. Can be `undefined` if `ignoreResults` is `true`. + */ + data: unknown; + /** + * If the mutation produces one or more errors, this object contains either an array of `graphQLErrors` or a single `networkError`. Otherwise, this value is `undefined`. + * + * For more information, see [Handling operation errors](https://www.apollographql.com/docs/react/data/error-handling/). + */ + error: unknown; + /** + * If `true`, the mutation is currently in flight. + */ + loading: unknown; + /** + * If `true`, the mutation's mutate function has been called. + */ + called: unknown; + /** + * The instance of Apollo Client that executed the mutation. + * + * Can be useful for manually executing followup operations or writing data to the cache. + */ + client: unknown; + /** + * A function that you can call to reset the mutation's result to its initial, uncalled state. + */ + reset: unknown; +} + +export interface SubscriptionOptionsDocumentation { + /** + * A GraphQL document, often created with `gql` from the `graphql-tag` + * package, that contains a single subscription inside of it. + */ + query: unknown; + /** + * An object containing all of the variables your subscription needs to execute + */ + variables: unknown; + + /** + * Specifies the {@link ErrorPolicy} to be used for this operation + */ + errorPolicy: unknown; + + /** + * How you want your component to interact with the Apollo cache. For details, see [Setting a fetch policy](https://www.apollographql.com/docs/react/data/queries/#setting-a-fetch-policy). + */ + fetchPolicy: unknown; + + /** + * Determines if your subscription should be unsubscribed and subscribed again when an input to the hook (such as `subscription` or `variables`) changes. + */ + shouldResubscribe: unknown; + + /** + * An `ApolloClient` instance. By default `useSubscription` / `Subscription` uses the client passed down via context, but a different client can be passed in. + */ + client: unknown; + + /** + * Determines if the current subscription should be skipped. Useful if, for example, variables depend on previous queries and are not ready yet. + */ + skip: unknown; + + /** + * Shared context between your component and your network interface (Apollo Link). + */ + context: unknown; + + /** + * Allows the registration of a callback function that will be triggered each time the `useSubscription` Hook / `Subscription` component completes the subscription. + * + * @since 3.7.0 + */ + onComplete: unknown; + + /** + * Allows the registration of a callback function that will be triggered each time the `useSubscription` Hook / `Subscription` component receives data. The callback `options` object param consists of the current Apollo Client instance in `client`, and the received subscription data in `data`. + * + * @since 3.7.0 + */ + onData: unknown; + + /** + * Allows the registration of a callback function that will be triggered each time the `useSubscription` Hook / `Subscription` component receives data. The callback `options` object param consists of the current Apollo Client instance in `client`, and the received subscription data in `subscriptionData`. + * + * @deprecated Use `onData` instead + */ + onSubscriptionData: unknown; + + /** + * Allows the registration of a callback function that will be triggered each time the `useSubscription` Hook / `Subscription` component receives an error. + * + * @since 3.7.0 + */ + onError: unknown; + + /** + * Allows the registration of a callback function that will be triggered when the `useSubscription` Hook / `Subscription` component completes the subscription. + * + * @deprecated Use `onComplete` instead + */ + onSubscriptionComplete: unknown; +} + +export interface SubscriptionResultDocumentation { + /** + * A boolean that indicates whether any initial data has been returned + */ + loading: unknown; + /** + * An object containing the result of your GraphQL subscription. Defaults to an empty object. + */ + data: unknown; + /** + * A runtime error with `graphQLErrors` and `networkError` properties + */ + error: unknown; +} diff --git a/src/react/types/types.ts b/src/react/types/types.ts index f6e24f33474..785c2ed793b 100644 --- a/src/react/types/types.ts +++ b/src/react/types/types.ts @@ -13,16 +13,22 @@ import type { ApolloClient, DefaultContext, FetchPolicy, - MutationOptions, NetworkStatus, ObservableQuery, OperationVariables, InternalRefetchQueriesInclude, WatchQueryOptions, WatchQueryFetchPolicy, + SubscribeToMoreOptions, + ApolloQueryResult, + FetchMoreQueryOptions, ErrorPolicy, RefetchWritePolicy, } from "../../core/index.js"; +import type { + MutationSharedOptions, + SharedWatchQueryOptions, +} from "../../core/watchQueryOptions.js"; /* QueryReference type */ @@ -40,18 +46,25 @@ export type CommonOptions = TOptions & { export interface BaseQueryOptions< TVariables extends OperationVariables = OperationVariables, -> extends Omit, "query"> { + TData = any, +> extends SharedWatchQueryOptions { + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#ssr:member} */ ssr?: boolean; + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#client:member} */ client?: ApolloClient; + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#context:member} */ context?: DefaultContext; } export interface QueryFunctionOptions< TData = any, TVariables extends OperationVariables = OperationVariables, -> extends BaseQueryOptions { +> extends BaseQueryOptions { + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#skip:member} */ skip?: boolean; + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#onCompleted:member} */ onCompleted?: (data: TData) => void; + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#onError:member} */ onError?: (error: ApolloError) => void; // Default WatchQueryOptions for this useQuery, providing initial values for @@ -59,35 +72,81 @@ export interface QueryFunctionOptions< // by option, not whole), but never overriding options previously passed to // useQuery (or options added/modified later by other means). // TODO What about about default values that are expensive to evaluate? + /** @internal */ defaultOptions?: Partial>; } -export type ObservableQueryFields< +export interface ObservableQueryFields< TData, TVariables extends OperationVariables, -> = Pick< - ObservableQuery, - | "startPolling" - | "stopPolling" - | "subscribeToMore" - | "updateQuery" - | "refetch" - | "reobserve" - | "variables" - | "fetchMore" ->; +> { + /** {@inheritDoc @apollo/client!QueryResultDocumentation#startPolling:member} */ + startPolling(pollInterval: number): void; + /** {@inheritDoc @apollo/client!QueryResultDocumentation#stopPolling:member} */ + stopPolling(): void; + /** {@inheritDoc @apollo/client!QueryResultDocumentation#subscribeToMore:member} */ + subscribeToMore< + TSubscriptionData = TData, + TSubscriptionVariables extends OperationVariables = TVariables, + >( + options: SubscribeToMoreOptions< + TData, + TSubscriptionVariables, + TSubscriptionData + > + ): () => void; + /** {@inheritDoc @apollo/client!QueryResultDocumentation#updateQuery:member} */ + updateQuery( + mapFn: ( + previousQueryResult: TData, + options: Pick, "variables"> + ) => TData + ): void; + /** {@inheritDoc @apollo/client!QueryResultDocumentation#refetch:member} */ + refetch(variables?: Partial): Promise>; + /** @internal */ + reobserve( + newOptions?: Partial>, + newNetworkStatus?: NetworkStatus + ): Promise>; + /** {@inheritDoc @apollo/client!QueryResultDocumentation#variables:member} */ + variables: TVariables | undefined; + /** {@inheritDoc @apollo/client!QueryResultDocumentation#fetchMore:member} */ + fetchMore< + TFetchData = TData, + TFetchVars extends OperationVariables = TVariables, + >( + fetchMoreOptions: FetchMoreQueryOptions & { + updateQuery?: ( + previousQueryResult: TData, + options: { + fetchMoreResult: TFetchData; + variables: TFetchVars; + } + ) => TData; + } + ): Promise>; +} export interface QueryResult< TData = any, TVariables extends OperationVariables = OperationVariables, > extends ObservableQueryFields { + /** {@inheritDoc @apollo/client!QueryResultDocumentation#client:member} */ client: ApolloClient; + /** {@inheritDoc @apollo/client!QueryResultDocumentation#observable:member} */ observable: ObservableQuery; + /** {@inheritDoc @apollo/client!QueryResultDocumentation#data:member} */ data: TData | undefined; + /** {@inheritDoc @apollo/client!QueryResultDocumentation#previousData:member} */ previousData?: TData; + /** {@inheritDoc @apollo/client!QueryResultDocumentation#error:member} */ error?: ApolloError; + /** {@inheritDoc @apollo/client!QueryResultDocumentation#loading:member} */ loading: boolean; + /** {@inheritDoc @apollo/client!QueryResultDocumentation#networkStatus:member} */ networkStatus: NetworkStatus; + /** {@inheritDoc @apollo/client!QueryResultDocumentation#called:member} */ called: boolean; } @@ -96,6 +155,7 @@ export interface QueryDataOptions< TVariables extends OperationVariables = OperationVariables, > extends QueryFunctionOptions { children?: (result: QueryResult) => ReactTypes.ReactNode; + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#query:member} */ query: DocumentNode | TypedDocumentNode; } @@ -107,8 +167,15 @@ export interface QueryHookOptions< export interface LazyQueryHookOptions< TData = any, TVariables extends OperationVariables = OperationVariables, -> extends Omit, "skip"> {} +> extends BaseQueryOptions { + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#onCompleted:member} */ + onCompleted?: (data: TData) => void; + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#onError:member} */ + onError?: (error: ApolloError) => void; + /** @internal */ + defaultOptions?: Partial>; +} export interface LazyQueryHookExecOptions< TData = any, TVariables extends OperationVariables = OperationVariables, @@ -124,24 +191,28 @@ export type SuspenseQueryHookFetchPolicy = Extract< export interface SuspenseQueryHookOptions< TData = unknown, TVariables extends OperationVariables = OperationVariables, -> extends Pick< - QueryHookOptions, - | "client" - | "variables" - | "errorPolicy" - | "context" - | "canonizeResults" - | "returnPartialData" - | "refetchWritePolicy" - > { +> { + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#client:member} */ + client?: ApolloClient; + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#context:member} */ + context?: DefaultContext; + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#variables:member} */ + variables?: TVariables; + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#errorPolicy:member} */ + errorPolicy?: ErrorPolicy; + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#canonizeResults:member} */ + canonizeResults?: boolean; + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#returnPartialData:member} */ + returnPartialData?: boolean; + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#refetchWritePolicy_suspense:member} */ + refetchWritePolicy?: RefetchWritePolicy; + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#fetchPolicy:member} */ fetchPolicy?: SuspenseQueryHookFetchPolicy; + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#queryKey:member} */ queryKey?: string | number | any[]; /** - * If `true`, the query is not executed. The default value is `false`. - * - * @deprecated We recommend using `skipToken` in place of the `skip` option as - * it is more type-safe. + * {@inheritDoc @apollo/client!QueryOptionsDocumentation#skip_deprecated:member} * * @example Recommended usage of `skipToken`: * ```ts @@ -175,10 +246,7 @@ export interface BackgroundQueryHookOptions< queryKey?: string | number | any[]; /** - * If `true`, the query is not executed. The default value is `false`. - * - * @deprecated We recommend using `skipToken` in place of the `skip` option as - * it is more type-safe. + * {@inheritDoc @apollo/client!QueryOptionsDocumentation#skip_deprecated:member} * * @example Recommended usage of `skipToken`: * ```ts @@ -196,77 +264,36 @@ export type LoadableQueryHookFetchPolicy = Extract< >; export interface LoadableQueryHookOptions { - /** - * @deprecated - * Using `canonizeResults` can result in memory leaks so we generally do not - * recommend using this option anymore. - * A future version of Apollo Client will contain a similar feature without - * the risk of memory leaks. - * - * Whether to canonize cache results before returning them. Canonization - * takes some extra time, but it speeds up future deep equality comparisons. - * Defaults to false. - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#canonizeResults:member} */ canonizeResults?: boolean; - /** - * The instance of {@link ApolloClient} to use to execute the query. - * - * By default, the instance that's passed down via context is used, but you - * can provide a different instance here. - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#client:member} */ client?: ApolloClient; - /** - * Context to be passed to link execution chain - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#context:member} */ context?: DefaultContext; - /** - * Specifies the {@link ErrorPolicy} to be used for this query - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#errorPolicy:member} */ errorPolicy?: ErrorPolicy; - /** - * - * Specifies how the query interacts with the Apollo Client cache during - * execution (for example, whether it checks the cache for results before - * sending a request to the server). - * - * For details, see {@link https://www.apollographql.com/docs/react/data/queries/#setting-a-fetch-policy | Setting a fetch policy}. - * - * The default value is `cache-first`. - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#fetchPolicy:member} */ fetchPolicy?: LoadableQueryHookFetchPolicy; - /** - * A unique identifier for the query. Each item in the array must be a stable - * identifier to prevent infinite fetches. - * - * This is useful when using the same query and variables combination in more - * than one component, otherwise the components may clobber each other. This - * can also be used to force the query to re-evaluate fresh. - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#queryKey:member} */ queryKey?: string | number | any[]; - /** - * Specifies whether a {@link NetworkStatus.refetch} operation should merge - * incoming field data with existing data, or overwrite the existing data. - * Overwriting is probably preferable, but merging is currently the default - * behavior, for backwards compatibility with Apollo Client 3.x. - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#refetchWritePolicy:member} */ refetchWritePolicy?: RefetchWritePolicy; - /** - * Allow returning incomplete data from the cache when a larger query cannot - * be fully satisfied by the cache, instead of returning nothing. - */ + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#returnPartialData:member} */ returnPartialData?: boolean; } /** - * @deprecated TODO Delete this unused interface. + * @deprecated This type will be removed in the next major version of Apollo Client */ export interface QueryLazyOptions { + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#variables:member} */ variables?: TVariables; + /** {@inheritDoc @apollo/client!QueryOptionsDocumentation#context:member} */ context?: DefaultContext; } /** - * @deprecated TODO Delete this unused type alias. + * @deprecated This type will be removed in the next major version of Apollo Client */ export type LazyQueryResult< TData, @@ -274,7 +301,7 @@ export type LazyQueryResult< > = QueryResult; /** - * @deprecated TODO Delete this unused type alias. + * @deprecated This type will be removed in the next major version of Apollo Client */ export type QueryTuple< TData, @@ -291,7 +318,10 @@ export type LazyQueryExecFunction< export type LazyQueryResultTuple< TData, TVariables extends OperationVariables, -> = [LazyQueryExecFunction, QueryResult]; +> = [ + execute: LazyQueryExecFunction, + result: QueryResult, +]; /* Mutation types */ @@ -304,14 +334,16 @@ export interface BaseMutationOptions< TVariables = OperationVariables, TContext = DefaultContext, TCache extends ApolloCache = ApolloCache, -> extends Omit< - MutationOptions, - "mutation" - > { +> extends MutationSharedOptions { + /** {@inheritDoc @apollo/client!MutationOptionsDocumentation#client:member} */ client?: ApolloClient; + /** {@inheritDoc @apollo/client!MutationOptionsDocumentation#notifyOnNetworkStatusChange:member} */ notifyOnNetworkStatusChange?: boolean; + /** {@inheritDoc @apollo/client!MutationOptionsDocumentation#onCompleted:member} */ onCompleted?: (data: TData, clientOptions?: BaseMutationOptions) => void; + /** {@inheritDoc @apollo/client!MutationOptionsDocumentation#onError:member} */ onError?: (error: ApolloError, clientOptions?: BaseMutationOptions) => void; + /** {@inheritDoc @apollo/client!MutationOptionsDocumentation#ignoreResults:member} */ ignoreResults?: boolean; } @@ -321,15 +353,22 @@ export interface MutationFunctionOptions< TContext = DefaultContext, TCache extends ApolloCache = ApolloCache, > extends BaseMutationOptions { + /** {@inheritDoc @apollo/client!MutationOptionsDocumentation#mutation:member} */ mutation?: DocumentNode | TypedDocumentNode; } export interface MutationResult { + /** {@inheritDoc @apollo/client!MutationResultDocumentation#data:member} */ data?: TData | null; + /** {@inheritDoc @apollo/client!MutationResultDocumentation#error:member} */ error?: ApolloError; + /** {@inheritDoc @apollo/client!MutationResultDocumentation#loading:member} */ loading: boolean; + /** {@inheritDoc @apollo/client!MutationResultDocumentation#called:member} */ called: boolean; + /** {@inheritDoc @apollo/client!MutationResultDocumentation#client:member} */ client: ApolloClient; + /** {@inheritDoc @apollo/client!MutationResultDocumentation#reset:member} */ reset(): void; } @@ -364,12 +403,12 @@ export type MutationTuple< TContext = DefaultContext, TCache extends ApolloCache = ApolloCache, > = [ - ( + mutate: ( options?: MutationFunctionOptions // TODO This FetchResult seems strange here, as opposed to an // ApolloQueryResult ) => Promise>, - MutationResult, + result: MutationResult, ]; /* Subscription types */ @@ -388,33 +427,44 @@ export interface BaseSubscriptionOptions< TData = any, TVariables extends OperationVariables = OperationVariables, > { + /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#variables:member} */ variables?: TVariables; + /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#fetchPolicy:member} */ fetchPolicy?: FetchPolicy; + /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#shouldResubscribe:member} */ shouldResubscribe?: | boolean | ((options: BaseSubscriptionOptions) => boolean); + /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#client:member} */ client?: ApolloClient; + /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#skip:member} */ skip?: boolean; + /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#context:member} */ context?: DefaultContext; + /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#onComplete:member} */ onComplete?: () => void; + /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#onData:member} */ onData?: (options: OnDataOptions) => any; - /** - * @deprecated Use onData instead - */ + /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#onSubscriptionData:member} */ onSubscriptionData?: (options: OnSubscriptionDataOptions) => any; + /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#onError:member} */ onError?: (error: ApolloError) => void; - /** - * @deprecated Use onComplete instead - */ + /** {@inheritDoc @apollo/client!SubscriptionOptionsDocumentation#onSubscriptionComplete:member} */ onSubscriptionComplete?: () => void; } export interface SubscriptionResult { + /** {@inheritDoc @apollo/client!SubscriptionResultDocumentation#loading:member} */ loading: boolean; + /** {@inheritDoc @apollo/client!SubscriptionResultDocumentation#data:member} */ data?: TData; + /** {@inheritDoc @apollo/client!SubscriptionResultDocumentation#error:member} */ error?: ApolloError; // This was added by the legacy useSubscription type, and is tested in unit // tests, but probably shouldn’t be added to the result. + /** + * @internal + */ variables?: TVariables; } diff --git a/src/utilities/graphql/DocumentTransform.ts b/src/utilities/graphql/DocumentTransform.ts index 732c1c7d1a6..ec6e0e44152 100644 --- a/src/utilities/graphql/DocumentTransform.ts +++ b/src/utilities/graphql/DocumentTransform.ts @@ -12,7 +12,19 @@ export type DocumentTransformCacheKey = ReadonlyArray; type TransformFn = (document: DocumentNode) => DocumentNode; interface DocumentTransformOptions { + /** + * Determines whether to cache the transformed GraphQL document. Caching can speed up repeated calls to the document transform for the same input document. Set to `false` to completely disable caching for the document transform. When disabled, this option takes precedence over the [`getCacheKey`](#getcachekey) option. + * + * The default value is `true`. + */ cache?: boolean; + /** + * Defines a custom cache key for a GraphQL document that will determine whether to re-run the document transform when given the same input GraphQL document. Returns an array that defines the cache key. Return `undefined` to disable caching for that GraphQL document. + * + * > **Note:** The items in the array may be any type, but also need to be referentially stable to guarantee a stable cache key. + * + * The default implementation of this function returns the `document` as the cache key. + */ getCacheKey?: ( document: DocumentNode ) => DocumentTransformCacheKey | undefined; diff --git a/tsdoc.json b/tsdoc.json new file mode 100644 index 00000000000..c49aafb4c6e --- /dev/null +++ b/tsdoc.json @@ -0,0 +1,24 @@ +{ + "$schema": "https://developer.microsoft.com/json-schemas/tsdoc/v0/tsdoc.schema.json", + + // Inherit the TSDoc configuration for API Extractor + "extends": ["@microsoft/api-extractor/extends/tsdoc-base.json"], + + "tagDefinitions": [ + { + "tagName": "@since", + "syntaxKind": "block", + "allowMultiple": false + }, + { + "tagName": "@docGroup", + "syntaxKind": "block", + "allowMultiple": false + } + ], + + "supportForTags": { + "@since": true, + "@docGroup": true + } +}