From d0ce36fa013afa22c29207475389ef4392c8ce59 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Wed, 6 Aug 2025 11:00:28 -0600 Subject: [PATCH 01/13] Update getMainDefinition doc block --- src/utilities/internal/getMainDefinition.ts | 38 ++++++++++++++++++--- 1 file changed, 34 insertions(+), 4 deletions(-) diff --git a/src/utilities/internal/getMainDefinition.ts b/src/utilities/internal/getMainDefinition.ts index 60615004f37..98c27fb0204 100644 --- a/src/utilities/internal/getMainDefinition.ts +++ b/src/utilities/internal/getMainDefinition.ts @@ -9,11 +9,41 @@ import { newInvariantError } from "@apollo/client/utilities/invariant"; import { checkDocument } from "./checkDocument.js"; /** - * Returns the first operation definition found in this document. - * If no operation definition is found, the first fragment definition will be returned. - * If no definitions are found, an error will be thrown. + * Returns the first operation definition from a GraphQL document. The function + * prioritizes operation definitions over fragment definitions, which makes it + * suitable for documents that may contain both. If no operation definition is + * found, the first fragment definition will be returned. If no definitions are + * found, an error is thrown. * - * @internal + * @remarks + * + * Use this function when you need to perform more advanced tasks with the main + * definition AST node. If you want to determine when a document is a specific + * operation type, prefer the `isQueryOperation`, `isMutationOperation`, and + * `isSubscriptionOperation` utility functions instead. + * + * @param queryDoc - The GraphQL document to extract the definition from + * @returns The main operation or fragment definition AST node + * + * @example + * + * ```ts + * import { gql } from "@apollo/client"; + * import { getMainDefinition } from "@apollo/client/utilities"; + * + * const query = gql` + * query GetUser($id: ID!) { + * user(id: $id) { + * name + * email + * } + * } + * `; + * + * const definition = getMainDefinition(query); + * ``` + * + * @throws When the document contains no operation or fragment definitions */ export function getMainDefinition( queryDoc: DocumentNode From 35c55d9fe223c2fe2959cf3159dc8e57830a05e6 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Wed, 6 Aug 2025 11:05:57 -0600 Subject: [PATCH 02/13] Update canonicalStringify doc block --- src/utilities/internal/canonicalStringify.ts | 37 ++++++++++++++++---- 1 file changed, 30 insertions(+), 7 deletions(-) diff --git a/src/utilities/internal/canonicalStringify.ts b/src/utilities/internal/canonicalStringify.ts index 34916766a7f..70e9e557c0f 100644 --- a/src/utilities/internal/canonicalStringify.ts +++ b/src/utilities/internal/canonicalStringify.ts @@ -6,21 +6,44 @@ import { AutoCleanedStrongCache } from "./caches.js"; import { registerGlobalCache } from "./getMemoryInternals.js"; /** - * Like JSON.stringify, but with object keys always sorted in the same order. + * Serializes a value to JSON with object keys in a consistent, sorted order. * - * To achieve performant sorting, this function uses a Map from JSON-serialized + * @remarks + * + * Unlike `JSON.stringify()`, this function ensures that object keys are always + * serialized in the same alphabetical order, regardless of their original order. + * This makes it suitable for creating consistent cache keys from objects, + * comparing objects by their serialized representation, or generating + * deterministic hashes of objects. + * + * To achieve performant sorting, this function uses a `Map` from JSON-serialized * arrays of keys (in any order) to sorted arrays of the same keys, with a * single sorted array reference shared by all permutations of the keys. * - * As a drawback, this function will add a little bit more memory for every - * object encountered that has different (more, less, a different order of) keys - * than in the past. + * As a drawback, this function will add a little more memory for every object + * encountered that has different (more, less, a different order of) keys than + * in the past. * * In a typical application, this extra memory usage should not play a * significant role, as `canonicalStringify` will be called for only a limited * number of object shapes, and the cache will not grow beyond a certain point. - * But in some edge cases, this could be a problem, so we provide - * canonicalStringify.reset() as a way of clearing the cache. + * But in some edge cases, this could be a problem. Use canonicalStringify.reset() + * as a way to clear the memoization cache. + * + * @param value - The value to stringify + * @returns JSON string with consistently ordered object keys + * + * @example + * + * ```ts + * import { canonicalStringify } from "@apollo/client/utilities"; + * + * const obj1 = { b: 2, a: 1 }; + * const obj2 = { a: 1, b: 2 }; + * + * console.log(canonicalStringify(obj1)); // '{"a":1,"b":2}' + * console.log(canonicalStringify(obj2)); // '{"a":1,"b":2}' + * ``` */ export const canonicalStringify = Object.assign( function canonicalStringify(value: any): string { From 98446e25586b14e644d2e38242ef3dcc13a36643 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Wed, 6 Aug 2025 11:07:04 -0600 Subject: [PATCH 03/13] Update doc block for isFormattedExecutionResult --- .../graphql/isFormattedExecutionResult.ts | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/src/utilities/graphql/isFormattedExecutionResult.ts b/src/utilities/graphql/isFormattedExecutionResult.ts index 9781a13e3ea..a743da16c4a 100644 --- a/src/utilities/graphql/isFormattedExecutionResult.ts +++ b/src/utilities/graphql/isFormattedExecutionResult.ts @@ -1,5 +1,32 @@ import type { FormattedExecutionResult } from "graphql"; +/** + * Determines whether the given object is a valid GraphQL execution result + * according to the GraphQL specification. + * + * @remarks + * + * A valid execution result must be an object that contains only `data`, + * `errors`, and/or `extensions` properties. At least one of `data` or `errors` + * must be present. + * + * @param result - The object to test + * @returns `true` if the object conforms to the GraphQL execution result format + * + * @example + * + * ```ts + * import { isFormattedExecutionResult } from "@apollo/client/utilities"; + * + * // Valid execution result + * const validResult = { data: { user: { name: "John" } } }; + * console.log(isFormattedExecutionResult(validResult)); // true + * + * // Invalid - contains non-standard properties + * const invalidResult = { data: {}, customField: "value" }; + * console.log(isFormattedExecutionResult(invalidResult)); // false + * ``` + */ export function isFormattedExecutionResult( result?: object ): result is FormattedExecutionResult { From 8d21e28e9ccc5730a60cde1fed7521800c31f1e0 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Wed, 6 Aug 2025 11:21:15 -0600 Subject: [PATCH 04/13] Update doc blocks for DocumentTransform --- src/utilities/graphql/DocumentTransform.ts | 99 ++++++++++++++++++++-- 1 file changed, 94 insertions(+), 5 deletions(-) diff --git a/src/utilities/graphql/DocumentTransform.ts b/src/utilities/graphql/DocumentTransform.ts index 11573ac341c..0bf13ed2f69 100644 --- a/src/utilities/graphql/DocumentTransform.ts +++ b/src/utilities/graphql/DocumentTransform.ts @@ -14,17 +14,23 @@ 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. + * 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`. + * @defaultValue `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. + * > [!NOTE] + * > The items in the array can be any type, but each item needs to be + * > referentially stable to guarantee a stable cache key. * - * The default implementation of this function returns the `document` as the cache key. + * @defaultValue `(document) => [document]` */ getCacheKey?: ( document: DocumentNode @@ -35,6 +41,25 @@ function identity(document: DocumentNode) { return document; } +/** + * A class for transforming GraphQL documents. See the [Document transforms + * documentation](https://www.apollographql.com/docs/react/data/document-transforms) for more details on using them. + * + * @example + * + * ```ts + * import { DocumentTransform } from "@apollo/client/utilities"; + * import { visit } from "graphql"; + * + * const documentTransform = new DocumentTransform((doc) => { + * return visit(doc, { + * // ... + * }); + * }); + * + * const transformedDoc = documentTransform.transformDocument(myDocument); + * ``` + */ export class DocumentTransform { private readonly transform: TransformFn; private cached: boolean; @@ -52,6 +77,11 @@ export class DocumentTransform { return [document]; } + /** + * Creates a DocumentTransform that returns the input document unchanged. + * + * @returns The input document + */ static identity() { // No need to cache this transform since it just returns the document // unchanged. This should save a bit of memory that would otherwise be @@ -59,6 +89,26 @@ export class DocumentTransform { return new DocumentTransform(identity, { cache: false }); } + /** + * Creates a DocumentTransform that conditionally applies one of two transforms. + * + * @param predicate - Function that determines which transform to apply + * @param left - Transform to apply when `predicate` returns `true` + * @param right - Transform to apply when `predicate` returns `false`. If not provided, it defaults to `DocumentTransform.identity()`. + * @returns A DocumentTransform that conditionally applies a document transform based on the predicate + * + * @example + * + * ```ts + * import { isQueryOperation } from "@apollo/client/utilities"; + * + * const conditionalTransform = DocumentTransform.split( + * (document) => isQueryOperation(document), + * queryTransform, + * mutationTransform + * ); + * ``` + */ static split( predicate: (document: DocumentNode) => boolean, left: DocumentTransform, @@ -91,7 +141,7 @@ export class DocumentTransform { } /** - * Resets the internal cache of this transform, if it has one. + * Resets the internal cache of this transform, if it is cached. */ resetCache() { if (this.cached) { @@ -121,6 +171,29 @@ export class DocumentTransform { return this.transform(document); } + /** + * Transforms a GraphQL document using the configured transform function. + * + * @remarks + * + * Note that `transformDocument` caches the transformed document. Calling + * `transformDocument` again with the already-transformed document will + * immediately return it. + * + * @param document - The GraphQL document to transform + * @returns The transformed document + * + * @example + * + * ```ts + * const document = gql` + * # ... + * `; + * + * const documentTransform = new DocumentTransform(transformFn); + * const transformedDocument = documentTransform.transformDocument(document); + * ``` + */ transformDocument(document: DocumentNode) { // If a user passes an already transformed result back to this function, // immediately return it. @@ -135,6 +208,22 @@ export class DocumentTransform { return transformedDocument; } + /** + * Combines this document transform with another document transform. The + * returned document transform first applies the current document transform, + * then applies the other document transform. + * + * @param otherTransform - The transform to apply after this one + * @returns A new DocumentTransform that applies both transforms in sequence + * + * @example + * + * ```ts + * const combinedTransform = addTypenameTransform.concat( + * removeDirectivesTransform + * ); + * ``` + */ concat(otherTransform: DocumentTransform): DocumentTransform { return Object.assign( new DocumentTransform( From 6267ced1aeade364fc4ac86f540bcd1674713c17 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Wed, 6 Aug 2025 11:42:23 -0600 Subject: [PATCH 05/13] Update doc block for addTypenameToDocument --- src/utilities/graphql/transform.ts | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/src/utilities/graphql/transform.ts b/src/utilities/graphql/transform.ts index 23358e003c3..cc3577e7bec 100644 --- a/src/utilities/graphql/transform.ts +++ b/src/utilities/graphql/transform.ts @@ -10,9 +10,20 @@ const TYPENAME_FIELD: FieldNode = { }; /** - * Adds `__typename` to all selection sets in the document. + * Adds `__typename` to all selection sets in the document. The operation + * definition's selection set remains unchanged. * * @param doc - The `ASTNode` to add `__typename` to + * + * @example + * + * ```ts + * const document = gql` + * # ... + * `; + * + * const withTypename = addTypenameToDocument(document); + * ``` */ export const addTypenameToDocument = Object.assign( function (doc: TNode): TNode { From 109ab2d7a3b49cba3d80bd3a4590d9352f984e1a Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Wed, 6 Aug 2025 11:42:44 -0600 Subject: [PATCH 06/13] First pass claude utilities --- docs/source/_sidebar.yaml | 46 +++++++++++++++++++ .../utilities/add-typename-to-document.mdx | 16 +++++++ docs/source/api/utilities/as-store-object.mdx | 10 ++++ docs/source/api/utilities/cache-sizes.mdx | 17 +++++++ .../api/utilities/canonical-stringify.mdx | 15 ++++++ .../api/utilities/concat-pagination.mdx | 17 +++++++ docs/source/api/utilities/deep-partial.mdx | 10 ++++ .../api/utilities/document-transform.mdx | 26 +++++++++++ .../api/utilities/get-main-definition.mdx | 17 +++++++ docs/source/api/utilities/hkt.mdx | 10 ++++ .../is-formatted-execution-result.mdx | 17 +++++++ .../api/utilities/is-mutation-operation.mdx | 15 ++++++ .../api/utilities/is-query-operation.mdx | 15 ++++++ docs/source/api/utilities/is-reference.mdx | 15 ++++++ .../utilities/is-subscription-operation.mdx | 15 ++++++ docs/source/api/utilities/observable.mdx | 12 +++++ .../api/utilities/offset-limit-pagination.mdx | 17 +++++++ docs/source/api/utilities/print.mdx | 15 ++++++ docs/source/api/utilities/reference.mdx | 10 ++++ .../api/utilities/relay-style-pagination.mdx | 25 ++++++++++ docs/source/api/utilities/store-object.mdx | 10 ++++ docs/source/api/utilities/store-value.mdx | 10 ++++ docs/source/api/utilities/strip-typename.mdx | 15 ++++++ 23 files changed, 375 insertions(+) create mode 100644 docs/source/api/utilities/add-typename-to-document.mdx create mode 100644 docs/source/api/utilities/as-store-object.mdx create mode 100644 docs/source/api/utilities/cache-sizes.mdx create mode 100644 docs/source/api/utilities/canonical-stringify.mdx create mode 100644 docs/source/api/utilities/concat-pagination.mdx create mode 100644 docs/source/api/utilities/deep-partial.mdx create mode 100644 docs/source/api/utilities/document-transform.mdx create mode 100644 docs/source/api/utilities/get-main-definition.mdx create mode 100644 docs/source/api/utilities/hkt.mdx create mode 100644 docs/source/api/utilities/is-formatted-execution-result.mdx create mode 100644 docs/source/api/utilities/is-mutation-operation.mdx create mode 100644 docs/source/api/utilities/is-query-operation.mdx create mode 100644 docs/source/api/utilities/is-reference.mdx create mode 100644 docs/source/api/utilities/is-subscription-operation.mdx create mode 100644 docs/source/api/utilities/observable.mdx create mode 100644 docs/source/api/utilities/offset-limit-pagination.mdx create mode 100644 docs/source/api/utilities/print.mdx create mode 100644 docs/source/api/utilities/reference.mdx create mode 100644 docs/source/api/utilities/relay-style-pagination.mdx create mode 100644 docs/source/api/utilities/store-object.mdx create mode 100644 docs/source/api/utilities/store-value.mdx create mode 100644 docs/source/api/utilities/strip-typename.mdx diff --git a/docs/source/_sidebar.yaml b/docs/source/_sidebar.yaml index d9b6dd3c34d..3d50e69735b 100644 --- a/docs/source/_sidebar.yaml +++ b/docs/source/_sidebar.yaml @@ -219,3 +219,49 @@ items: href: ./api/link/apollo-link-ws - label: Community links href: ./api/link/community-links + - label: Utilities + children: + - label: addTypenameToDocument + href: ./api/utilities/add-typename-to-document + - label: AsStoreObject + href: ./api/utilities/as-store-object + - label: cacheSizes + href: ./api/utilities/cache-sizes + - label: canonicalStringify + href: ./api/utilities/canonical-stringify + - label: concatPagination + href: ./api/utilities/concat-pagination + - label: DeepPartial + href: ./api/utilities/deep-partial + - label: DocumentTransform + href: ./api/utilities/document-transform + - label: getMainDefinition + href: ./api/utilities/get-main-definition + - label: HKT + href: ./api/utilities/hkt + - label: isFormattedExecutionResult + href: ./api/utilities/is-formatted-execution-result + - label: isMutationOperation + href: ./api/utilities/is-mutation-operation + - label: isQueryOperation + href: ./api/utilities/is-query-operation + - label: isReference + href: ./api/utilities/is-reference + - label: isSubscriptionOperation + href: ./api/utilities/is-subscription-operation + - label: Observable + href: ./api/utilities/observable + - label: offsetLimitPagination + href: ./api/utilities/offset-limit-pagination + - label: print + href: ./api/utilities/print + - label: Reference + href: ./api/utilities/reference + - label: relayStylePagination + href: ./api/utilities/relay-style-pagination + - label: StoreObject + href: ./api/utilities/store-object + - label: StoreValue + href: ./api/utilities/store-value + - label: stripTypename + href: ./api/utilities/strip-typename diff --git a/docs/source/api/utilities/add-typename-to-document.mdx b/docs/source/api/utilities/add-typename-to-document.mdx new file mode 100644 index 00000000000..b00ad8f813c --- /dev/null +++ b/docs/source/api/utilities/add-typename-to-document.mdx @@ -0,0 +1,16 @@ +--- +title: addTypenameToDocument +description: Adds __typename fields to all selection sets in a GraphQL document +--- + + + +## Function signature + +```ts +function addTypenameToDocument(doc: TNode): TNode; +``` + diff --git a/docs/source/api/utilities/as-store-object.mdx b/docs/source/api/utilities/as-store-object.mdx new file mode 100644 index 00000000000..b2fe4a1aa27 --- /dev/null +++ b/docs/source/api/utilities/as-store-object.mdx @@ -0,0 +1,10 @@ +--- +title: AsStoreObject +description: Type that adds an implicit index signature to make types assignable to StoreObject +--- + + \ No newline at end of file diff --git a/docs/source/api/utilities/cache-sizes.mdx b/docs/source/api/utilities/cache-sizes.mdx new file mode 100644 index 00000000000..07f13a29716 --- /dev/null +++ b/docs/source/api/utilities/cache-sizes.mdx @@ -0,0 +1,17 @@ +--- +title: cacheSizes +description: Global cache size configuration for Apollo Client internal caches +--- + + + +## Types + + \ No newline at end of file diff --git a/docs/source/api/utilities/canonical-stringify.mdx b/docs/source/api/utilities/canonical-stringify.mdx new file mode 100644 index 00000000000..e5a415d4a3d --- /dev/null +++ b/docs/source/api/utilities/canonical-stringify.mdx @@ -0,0 +1,15 @@ +--- +title: canonicalStringify +description: Serializes a value to JSON with object keys in a consistent, sorted order +--- + + + +## Function signature + +```ts +function canonicalStringify(value: any): string +``` \ No newline at end of file diff --git a/docs/source/api/utilities/concat-pagination.mdx b/docs/source/api/utilities/concat-pagination.mdx new file mode 100644 index 00000000000..3647688f35f --- /dev/null +++ b/docs/source/api/utilities/concat-pagination.mdx @@ -0,0 +1,17 @@ +--- +title: concatPagination +description: A field policy that concatenates new results onto existing arrays +--- + + + +## Function signature + +```ts +function concatPagination( + keyArgs?: KeyArgs +): FieldPolicy +``` \ No newline at end of file diff --git a/docs/source/api/utilities/deep-partial.mdx b/docs/source/api/utilities/deep-partial.mdx new file mode 100644 index 00000000000..1d5def44f73 --- /dev/null +++ b/docs/source/api/utilities/deep-partial.mdx @@ -0,0 +1,10 @@ +--- +title: DeepPartial +description: Type utility that makes all properties of a type recursively optional +--- + + \ No newline at end of file diff --git a/docs/source/api/utilities/document-transform.mdx b/docs/source/api/utilities/document-transform.mdx new file mode 100644 index 00000000000..f939f51b672 --- /dev/null +++ b/docs/source/api/utilities/document-transform.mdx @@ -0,0 +1,26 @@ +--- +title: DocumentTransform +description: A class for transforming GraphQL documents with configurable caching +--- + + + +## Constructor signature + +```ts +constructor( + transform: (document: DocumentNode) => DocumentNode, + options?: DocumentTransformOptions +): DocumentTransform +``` + +## Types + + \ No newline at end of file diff --git a/docs/source/api/utilities/get-main-definition.mdx b/docs/source/api/utilities/get-main-definition.mdx new file mode 100644 index 00000000000..3ceb5ede681 --- /dev/null +++ b/docs/source/api/utilities/get-main-definition.mdx @@ -0,0 +1,17 @@ +--- +title: getMainDefinition +description: Returns the main definition from a GraphQL document +--- + + + +## Function signature + +```ts +function getMainDefinition( + queryDoc: DocumentNode +): OperationDefinitionNode | FragmentDefinitionNode +``` \ No newline at end of file diff --git a/docs/source/api/utilities/hkt.mdx b/docs/source/api/utilities/hkt.mdx new file mode 100644 index 00000000000..e52be045916 --- /dev/null +++ b/docs/source/api/utilities/hkt.mdx @@ -0,0 +1,10 @@ +--- +title: HKT +description: A helper interface to implement Higher-Kinded-Types in TypeScript +--- + + \ No newline at end of file diff --git a/docs/source/api/utilities/is-formatted-execution-result.mdx b/docs/source/api/utilities/is-formatted-execution-result.mdx new file mode 100644 index 00000000000..b9ebdf8d9b9 --- /dev/null +++ b/docs/source/api/utilities/is-formatted-execution-result.mdx @@ -0,0 +1,17 @@ +--- +title: isFormattedExecutionResult +description: Determines whether an object is a valid GraphQL execution result +--- + + + +## Function signature + +```ts +function isFormattedExecutionResult( + result?: object +): result is FormattedExecutionResult +``` \ No newline at end of file diff --git a/docs/source/api/utilities/is-mutation-operation.mdx b/docs/source/api/utilities/is-mutation-operation.mdx new file mode 100644 index 00000000000..bc2a65e7c08 --- /dev/null +++ b/docs/source/api/utilities/is-mutation-operation.mdx @@ -0,0 +1,15 @@ +--- +title: isMutationOperation +description: Determine if a GraphQL document is a mutation operation +--- + + + +## Function signature + +```ts +function isMutationOperation(document: DocumentNode): boolean +``` \ No newline at end of file diff --git a/docs/source/api/utilities/is-query-operation.mdx b/docs/source/api/utilities/is-query-operation.mdx new file mode 100644 index 00000000000..817484c888f --- /dev/null +++ b/docs/source/api/utilities/is-query-operation.mdx @@ -0,0 +1,15 @@ +--- +title: isQueryOperation +description: Determine if a GraphQL document is a query operation +--- + + + +## Function signature + +```ts +function isQueryOperation(document: DocumentNode): boolean +``` \ No newline at end of file diff --git a/docs/source/api/utilities/is-reference.mdx b/docs/source/api/utilities/is-reference.mdx new file mode 100644 index 00000000000..d784ca9232a --- /dev/null +++ b/docs/source/api/utilities/is-reference.mdx @@ -0,0 +1,15 @@ +--- +title: isReference +description: Determines if a given object is a cache reference object +--- + + + +## Function signature + +```ts +function isReference(obj: any): obj is Reference +``` \ No newline at end of file diff --git a/docs/source/api/utilities/is-subscription-operation.mdx b/docs/source/api/utilities/is-subscription-operation.mdx new file mode 100644 index 00000000000..e616c093b20 --- /dev/null +++ b/docs/source/api/utilities/is-subscription-operation.mdx @@ -0,0 +1,15 @@ +--- +title: isSubscriptionOperation +description: Determine if a GraphQL document is a subscription operation +--- + + + +## Function signature + +```ts +function isSubscriptionOperation(document: DocumentNode): boolean +``` \ No newline at end of file diff --git a/docs/source/api/utilities/observable.mdx b/docs/source/api/utilities/observable.mdx new file mode 100644 index 00000000000..9f35fff9d93 --- /dev/null +++ b/docs/source/api/utilities/observable.mdx @@ -0,0 +1,12 @@ +--- +title: Observable +description: RxJS Observable re-exported from Apollo Client utilities +--- + +The `Observable` type is re-exported from RxJS for convenience. See the [RxJS Observable documentation](https://rxjs.dev/guide/observable) for complete details on usage. + +## Type signature + +```ts +type Observable = import('rxjs').Observable +``` \ No newline at end of file diff --git a/docs/source/api/utilities/offset-limit-pagination.mdx b/docs/source/api/utilities/offset-limit-pagination.mdx new file mode 100644 index 00000000000..347d3b40f58 --- /dev/null +++ b/docs/source/api/utilities/offset-limit-pagination.mdx @@ -0,0 +1,17 @@ +--- +title: offsetLimitPagination +description: A field policy for offset/limit pagination that splices results into arrays +--- + + + +## Function signature + +```ts +function offsetLimitPagination( + keyArgs?: KeyArgs +): FieldPolicy +``` \ No newline at end of file diff --git a/docs/source/api/utilities/print.mdx b/docs/source/api/utilities/print.mdx new file mode 100644 index 00000000000..1ae9c29f9aa --- /dev/null +++ b/docs/source/api/utilities/print.mdx @@ -0,0 +1,15 @@ +--- +title: print +description: Converts a GraphQL AST into a string with caching for performance +--- + + + +## Function signature + +```ts +function print(ast: ASTNode): string +``` \ No newline at end of file diff --git a/docs/source/api/utilities/reference.mdx b/docs/source/api/utilities/reference.mdx new file mode 100644 index 00000000000..aa456b273e3 --- /dev/null +++ b/docs/source/api/utilities/reference.mdx @@ -0,0 +1,10 @@ +--- +title: Reference +description: Type representing a reference object inside the cache +--- + + \ No newline at end of file diff --git a/docs/source/api/utilities/relay-style-pagination.mdx b/docs/source/api/utilities/relay-style-pagination.mdx new file mode 100644 index 00000000000..439bf7fe897 --- /dev/null +++ b/docs/source/api/utilities/relay-style-pagination.mdx @@ -0,0 +1,25 @@ +--- +title: relayStylePagination +description: A field policy for Relay-style cursor-based pagination +--- + + + +## Function signature + +```ts +function relayStylePagination( + keyArgs?: KeyArgs +): RelayFieldPolicy +``` + +## Types + + \ No newline at end of file diff --git a/docs/source/api/utilities/store-object.mdx b/docs/source/api/utilities/store-object.mdx new file mode 100644 index 00000000000..1eda8e438a9 --- /dev/null +++ b/docs/source/api/utilities/store-object.mdx @@ -0,0 +1,10 @@ +--- +title: StoreObject +description: Type representing an object that is stored in the cache +--- + + \ No newline at end of file diff --git a/docs/source/api/utilities/store-value.mdx b/docs/source/api/utilities/store-value.mdx new file mode 100644 index 00000000000..4b93ea792c9 --- /dev/null +++ b/docs/source/api/utilities/store-value.mdx @@ -0,0 +1,10 @@ +--- +title: StoreValue +description: Type representing the union of valid values that can be stored in the cache +--- + + \ No newline at end of file diff --git a/docs/source/api/utilities/strip-typename.mdx b/docs/source/api/utilities/strip-typename.mdx new file mode 100644 index 00000000000..0ca8ded1f52 --- /dev/null +++ b/docs/source/api/utilities/strip-typename.mdx @@ -0,0 +1,15 @@ +--- +title: stripTypename +description: Deeply removes all __typename properties in an object or array +--- + + + +## Function signature + +```ts +function stripTypename(value: T): T +``` \ No newline at end of file From e7e1c7045a2ec63a3efa157c4f70d2c8b5a6eef5 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Wed, 6 Aug 2025 12:03:58 -0600 Subject: [PATCH 07/13] Remove utilities for now --- docs/source/_sidebar.yaml | 46 ------------------- .../utilities/add-typename-to-document.mdx | 16 ------- docs/source/api/utilities/as-store-object.mdx | 10 ---- docs/source/api/utilities/cache-sizes.mdx | 17 ------- .../api/utilities/canonical-stringify.mdx | 15 ------ .../api/utilities/concat-pagination.mdx | 17 ------- docs/source/api/utilities/deep-partial.mdx | 10 ---- .../api/utilities/document-transform.mdx | 26 ----------- .../api/utilities/get-main-definition.mdx | 17 ------- docs/source/api/utilities/hkt.mdx | 10 ---- .../is-formatted-execution-result.mdx | 17 ------- .../api/utilities/is-mutation-operation.mdx | 15 ------ .../api/utilities/is-query-operation.mdx | 15 ------ docs/source/api/utilities/is-reference.mdx | 15 ------ .../utilities/is-subscription-operation.mdx | 15 ------ docs/source/api/utilities/observable.mdx | 12 ----- .../api/utilities/offset-limit-pagination.mdx | 17 ------- docs/source/api/utilities/print.mdx | 15 ------ docs/source/api/utilities/reference.mdx | 10 ---- .../api/utilities/relay-style-pagination.mdx | 25 ---------- docs/source/api/utilities/store-object.mdx | 10 ---- docs/source/api/utilities/store-value.mdx | 10 ---- docs/source/api/utilities/strip-typename.mdx | 15 ------ 23 files changed, 375 deletions(-) delete mode 100644 docs/source/api/utilities/add-typename-to-document.mdx delete mode 100644 docs/source/api/utilities/as-store-object.mdx delete mode 100644 docs/source/api/utilities/cache-sizes.mdx delete mode 100644 docs/source/api/utilities/canonical-stringify.mdx delete mode 100644 docs/source/api/utilities/concat-pagination.mdx delete mode 100644 docs/source/api/utilities/deep-partial.mdx delete mode 100644 docs/source/api/utilities/document-transform.mdx delete mode 100644 docs/source/api/utilities/get-main-definition.mdx delete mode 100644 docs/source/api/utilities/hkt.mdx delete mode 100644 docs/source/api/utilities/is-formatted-execution-result.mdx delete mode 100644 docs/source/api/utilities/is-mutation-operation.mdx delete mode 100644 docs/source/api/utilities/is-query-operation.mdx delete mode 100644 docs/source/api/utilities/is-reference.mdx delete mode 100644 docs/source/api/utilities/is-subscription-operation.mdx delete mode 100644 docs/source/api/utilities/observable.mdx delete mode 100644 docs/source/api/utilities/offset-limit-pagination.mdx delete mode 100644 docs/source/api/utilities/print.mdx delete mode 100644 docs/source/api/utilities/reference.mdx delete mode 100644 docs/source/api/utilities/relay-style-pagination.mdx delete mode 100644 docs/source/api/utilities/store-object.mdx delete mode 100644 docs/source/api/utilities/store-value.mdx delete mode 100644 docs/source/api/utilities/strip-typename.mdx diff --git a/docs/source/_sidebar.yaml b/docs/source/_sidebar.yaml index 3d50e69735b..d9b6dd3c34d 100644 --- a/docs/source/_sidebar.yaml +++ b/docs/source/_sidebar.yaml @@ -219,49 +219,3 @@ items: href: ./api/link/apollo-link-ws - label: Community links href: ./api/link/community-links - - label: Utilities - children: - - label: addTypenameToDocument - href: ./api/utilities/add-typename-to-document - - label: AsStoreObject - href: ./api/utilities/as-store-object - - label: cacheSizes - href: ./api/utilities/cache-sizes - - label: canonicalStringify - href: ./api/utilities/canonical-stringify - - label: concatPagination - href: ./api/utilities/concat-pagination - - label: DeepPartial - href: ./api/utilities/deep-partial - - label: DocumentTransform - href: ./api/utilities/document-transform - - label: getMainDefinition - href: ./api/utilities/get-main-definition - - label: HKT - href: ./api/utilities/hkt - - label: isFormattedExecutionResult - href: ./api/utilities/is-formatted-execution-result - - label: isMutationOperation - href: ./api/utilities/is-mutation-operation - - label: isQueryOperation - href: ./api/utilities/is-query-operation - - label: isReference - href: ./api/utilities/is-reference - - label: isSubscriptionOperation - href: ./api/utilities/is-subscription-operation - - label: Observable - href: ./api/utilities/observable - - label: offsetLimitPagination - href: ./api/utilities/offset-limit-pagination - - label: print - href: ./api/utilities/print - - label: Reference - href: ./api/utilities/reference - - label: relayStylePagination - href: ./api/utilities/relay-style-pagination - - label: StoreObject - href: ./api/utilities/store-object - - label: StoreValue - href: ./api/utilities/store-value - - label: stripTypename - href: ./api/utilities/strip-typename diff --git a/docs/source/api/utilities/add-typename-to-document.mdx b/docs/source/api/utilities/add-typename-to-document.mdx deleted file mode 100644 index b00ad8f813c..00000000000 --- a/docs/source/api/utilities/add-typename-to-document.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: addTypenameToDocument -description: Adds __typename fields to all selection sets in a GraphQL document ---- - - - -## Function signature - -```ts -function addTypenameToDocument(doc: TNode): TNode; -``` - diff --git a/docs/source/api/utilities/as-store-object.mdx b/docs/source/api/utilities/as-store-object.mdx deleted file mode 100644 index b2fe4a1aa27..00000000000 --- a/docs/source/api/utilities/as-store-object.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: AsStoreObject -description: Type that adds an implicit index signature to make types assignable to StoreObject ---- - - \ No newline at end of file diff --git a/docs/source/api/utilities/cache-sizes.mdx b/docs/source/api/utilities/cache-sizes.mdx deleted file mode 100644 index 07f13a29716..00000000000 --- a/docs/source/api/utilities/cache-sizes.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: cacheSizes -description: Global cache size configuration for Apollo Client internal caches ---- - - - -## Types - - \ No newline at end of file diff --git a/docs/source/api/utilities/canonical-stringify.mdx b/docs/source/api/utilities/canonical-stringify.mdx deleted file mode 100644 index e5a415d4a3d..00000000000 --- a/docs/source/api/utilities/canonical-stringify.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: canonicalStringify -description: Serializes a value to JSON with object keys in a consistent, sorted order ---- - - - -## Function signature - -```ts -function canonicalStringify(value: any): string -``` \ No newline at end of file diff --git a/docs/source/api/utilities/concat-pagination.mdx b/docs/source/api/utilities/concat-pagination.mdx deleted file mode 100644 index 3647688f35f..00000000000 --- a/docs/source/api/utilities/concat-pagination.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: concatPagination -description: A field policy that concatenates new results onto existing arrays ---- - - - -## Function signature - -```ts -function concatPagination( - keyArgs?: KeyArgs -): FieldPolicy -``` \ No newline at end of file diff --git a/docs/source/api/utilities/deep-partial.mdx b/docs/source/api/utilities/deep-partial.mdx deleted file mode 100644 index 1d5def44f73..00000000000 --- a/docs/source/api/utilities/deep-partial.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: DeepPartial -description: Type utility that makes all properties of a type recursively optional ---- - - \ No newline at end of file diff --git a/docs/source/api/utilities/document-transform.mdx b/docs/source/api/utilities/document-transform.mdx deleted file mode 100644 index f939f51b672..00000000000 --- a/docs/source/api/utilities/document-transform.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: DocumentTransform -description: A class for transforming GraphQL documents with configurable caching ---- - - - -## Constructor signature - -```ts -constructor( - transform: (document: DocumentNode) => DocumentNode, - options?: DocumentTransformOptions -): DocumentTransform -``` - -## Types - - \ No newline at end of file diff --git a/docs/source/api/utilities/get-main-definition.mdx b/docs/source/api/utilities/get-main-definition.mdx deleted file mode 100644 index 3ceb5ede681..00000000000 --- a/docs/source/api/utilities/get-main-definition.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: getMainDefinition -description: Returns the main definition from a GraphQL document ---- - - - -## Function signature - -```ts -function getMainDefinition( - queryDoc: DocumentNode -): OperationDefinitionNode | FragmentDefinitionNode -``` \ No newline at end of file diff --git a/docs/source/api/utilities/hkt.mdx b/docs/source/api/utilities/hkt.mdx deleted file mode 100644 index e52be045916..00000000000 --- a/docs/source/api/utilities/hkt.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: HKT -description: A helper interface to implement Higher-Kinded-Types in TypeScript ---- - - \ No newline at end of file diff --git a/docs/source/api/utilities/is-formatted-execution-result.mdx b/docs/source/api/utilities/is-formatted-execution-result.mdx deleted file mode 100644 index b9ebdf8d9b9..00000000000 --- a/docs/source/api/utilities/is-formatted-execution-result.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: isFormattedExecutionResult -description: Determines whether an object is a valid GraphQL execution result ---- - - - -## Function signature - -```ts -function isFormattedExecutionResult( - result?: object -): result is FormattedExecutionResult -``` \ No newline at end of file diff --git a/docs/source/api/utilities/is-mutation-operation.mdx b/docs/source/api/utilities/is-mutation-operation.mdx deleted file mode 100644 index bc2a65e7c08..00000000000 --- a/docs/source/api/utilities/is-mutation-operation.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: isMutationOperation -description: Determine if a GraphQL document is a mutation operation ---- - - - -## Function signature - -```ts -function isMutationOperation(document: DocumentNode): boolean -``` \ No newline at end of file diff --git a/docs/source/api/utilities/is-query-operation.mdx b/docs/source/api/utilities/is-query-operation.mdx deleted file mode 100644 index 817484c888f..00000000000 --- a/docs/source/api/utilities/is-query-operation.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: isQueryOperation -description: Determine if a GraphQL document is a query operation ---- - - - -## Function signature - -```ts -function isQueryOperation(document: DocumentNode): boolean -``` \ No newline at end of file diff --git a/docs/source/api/utilities/is-reference.mdx b/docs/source/api/utilities/is-reference.mdx deleted file mode 100644 index d784ca9232a..00000000000 --- a/docs/source/api/utilities/is-reference.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: isReference -description: Determines if a given object is a cache reference object ---- - - - -## Function signature - -```ts -function isReference(obj: any): obj is Reference -``` \ No newline at end of file diff --git a/docs/source/api/utilities/is-subscription-operation.mdx b/docs/source/api/utilities/is-subscription-operation.mdx deleted file mode 100644 index e616c093b20..00000000000 --- a/docs/source/api/utilities/is-subscription-operation.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: isSubscriptionOperation -description: Determine if a GraphQL document is a subscription operation ---- - - - -## Function signature - -```ts -function isSubscriptionOperation(document: DocumentNode): boolean -``` \ No newline at end of file diff --git a/docs/source/api/utilities/observable.mdx b/docs/source/api/utilities/observable.mdx deleted file mode 100644 index 9f35fff9d93..00000000000 --- a/docs/source/api/utilities/observable.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Observable -description: RxJS Observable re-exported from Apollo Client utilities ---- - -The `Observable` type is re-exported from RxJS for convenience. See the [RxJS Observable documentation](https://rxjs.dev/guide/observable) for complete details on usage. - -## Type signature - -```ts -type Observable = import('rxjs').Observable -``` \ No newline at end of file diff --git a/docs/source/api/utilities/offset-limit-pagination.mdx b/docs/source/api/utilities/offset-limit-pagination.mdx deleted file mode 100644 index 347d3b40f58..00000000000 --- a/docs/source/api/utilities/offset-limit-pagination.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: offsetLimitPagination -description: A field policy for offset/limit pagination that splices results into arrays ---- - - - -## Function signature - -```ts -function offsetLimitPagination( - keyArgs?: KeyArgs -): FieldPolicy -``` \ No newline at end of file diff --git a/docs/source/api/utilities/print.mdx b/docs/source/api/utilities/print.mdx deleted file mode 100644 index 1ae9c29f9aa..00000000000 --- a/docs/source/api/utilities/print.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: print -description: Converts a GraphQL AST into a string with caching for performance ---- - - - -## Function signature - -```ts -function print(ast: ASTNode): string -``` \ No newline at end of file diff --git a/docs/source/api/utilities/reference.mdx b/docs/source/api/utilities/reference.mdx deleted file mode 100644 index aa456b273e3..00000000000 --- a/docs/source/api/utilities/reference.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Reference -description: Type representing a reference object inside the cache ---- - - \ No newline at end of file diff --git a/docs/source/api/utilities/relay-style-pagination.mdx b/docs/source/api/utilities/relay-style-pagination.mdx deleted file mode 100644 index 439bf7fe897..00000000000 --- a/docs/source/api/utilities/relay-style-pagination.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: relayStylePagination -description: A field policy for Relay-style cursor-based pagination ---- - - - -## Function signature - -```ts -function relayStylePagination( - keyArgs?: KeyArgs -): RelayFieldPolicy -``` - -## Types - - \ No newline at end of file diff --git a/docs/source/api/utilities/store-object.mdx b/docs/source/api/utilities/store-object.mdx deleted file mode 100644 index 1eda8e438a9..00000000000 --- a/docs/source/api/utilities/store-object.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: StoreObject -description: Type representing an object that is stored in the cache ---- - - \ No newline at end of file diff --git a/docs/source/api/utilities/store-value.mdx b/docs/source/api/utilities/store-value.mdx deleted file mode 100644 index 4b93ea792c9..00000000000 --- a/docs/source/api/utilities/store-value.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: StoreValue -description: Type representing the union of valid values that can be stored in the cache ---- - - \ No newline at end of file diff --git a/docs/source/api/utilities/strip-typename.mdx b/docs/source/api/utilities/strip-typename.mdx deleted file mode 100644 index 0ca8ded1f52..00000000000 --- a/docs/source/api/utilities/strip-typename.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: stripTypename -description: Deeply removes all __typename properties in an object or array ---- - - - -## Function signature - -```ts -function stripTypename(value: T): T -``` \ No newline at end of file From ecac1149b6164d38aad6628a5143eb6c56fa0058 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Wed, 6 Aug 2025 12:04:07 -0600 Subject: [PATCH 08/13] Add example for isReference --- src/utilities/graphql/storeUtils.ts | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/src/utilities/graphql/storeUtils.ts b/src/utilities/graphql/storeUtils.ts index a512a524883..099630ff715 100644 --- a/src/utilities/graphql/storeUtils.ts +++ b/src/utilities/graphql/storeUtils.ts @@ -9,6 +9,15 @@ export interface Reference { * Determines if a given object is a reference object. * * @param obj - The object to check if its a reference object + * + * @example + * + * ```ts + * import { isReference } from "@apollo/client/utilities"; + * + * isReference({ __ref: "User:1" }); // true + * isReference({ __typename: "User", id: 1 }); // false + * ``` */ export function isReference(obj: any): obj is Reference { return Boolean( From b25ca1cf5c5e42ced9c061711b9ac94ea614c0a7 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Wed, 6 Aug 2025 12:08:36 -0600 Subject: [PATCH 09/13] Update doc blocks for operation utilities --- src/utilities/graphql/operations.ts | 45 +++++++++++++++++++++++++++-- 1 file changed, 42 insertions(+), 3 deletions(-) diff --git a/src/utilities/graphql/operations.ts b/src/utilities/graphql/operations.ts index 8ade62343fc..6cbbec89fbb 100644 --- a/src/utilities/graphql/operations.ts +++ b/src/utilities/graphql/operations.ts @@ -12,8 +12,21 @@ function isOperation( * Determine if a document is a mutation document. * * @param document - The GraphQL document to check + * @returns A boolean indicating if the document is a mutation operation * - * @since 3.8.0 + * @example + * + * ```ts + * import { isMutationOperation } from "@apollo/client/utilities"; + * + * const mutation = gql` + * mutation MyMutation { + * # ... + * } + * `; + * + * isMutationOperation(mutation); // true + * ``` */ export function isMutationOperation(document: DocumentNode) { return isOperation(document, "mutation"); @@ -23,8 +36,21 @@ export function isMutationOperation(document: DocumentNode) { * Determine if a document is a query document. * * @param document - The GraphQL document to check + * @returns A boolean indicating if the document is a query operation + * + * @example + * + * ```ts + * import { isQueryOperation } from "@apollo/client/utilities"; * - * @since 3.8.0 + * const query = gql` + * query MyQuery { + * # ... + * } + * `; + * + * isQueryOperation(query); // true + * ``` */ export function isQueryOperation(document: DocumentNode) { return isOperation(document, "query"); @@ -34,8 +60,21 @@ export function isQueryOperation(document: DocumentNode) { * Determine if a document is a subscription document. * * @param document - The GraphQL document to check + * @returns A boolean indicating if the document is a subscription operation + * + * @example + * + * ```ts + * import { isSubscriptionOperation } from "@apollo/client/utilities"; + * + * const subscription = gql` + * subscription MySubscription { + * # ... + * } + * `; * - * @since 3.8.0 + * isSubscriptionOperation(subscription); // true + * ``` */ export function isSubscriptionOperation(document: DocumentNode) { return isOperation(document, "subscription"); From c53edf0e89eb62f2db380b8a9eca9f32035c1603 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Wed, 6 Aug 2025 12:17:11 -0600 Subject: [PATCH 10/13] Add example to stripTypename --- src/utilities/common/stripTypename.ts | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/utilities/common/stripTypename.ts b/src/utilities/common/stripTypename.ts index ddb125578a9..fa479d2253d 100644 --- a/src/utilities/common/stripTypename.ts +++ b/src/utilities/common/stripTypename.ts @@ -5,6 +5,17 @@ import { omitDeep } from "@apollo/client/utilities/internal"; * * @param value - The object or array that should have `__typename` removed. * @returns The object with all `__typename` properties removed. + * + * @example + * + * ```ts + * stripTypename({ + * __typename: "User", + * id: 1, + * profile: { __typename: "Profile", name: "John Doe" }, + * }); + * // => { id: 1, profile: { name: "John Doe"}} + * ``` */ export function stripTypename(value: T) { return omitDeep(value, "__typename"); From 4b311a5c3d7c61c61dd5aac5a4fca15fe71cf3c5 Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Wed, 6 Aug 2025 12:19:09 -0600 Subject: [PATCH 11/13] Update api report --- .api-reports/api-report-utilities.api.md | 8 ++------ .api-reports/api-report-utilities_internal.api.md | 2 +- .api-reports/api-report.api.md | 6 +----- 3 files changed, 4 insertions(+), 12 deletions(-) diff --git a/.api-reports/api-report-utilities.api.md b/.api-reports/api-report-utilities.api.md index 60b1fe1d03a..c20f64a4e47 100644 --- a/.api-reports/api-report-utilities.api.md +++ b/.api-reports/api-report-utilities.api.md @@ -87,26 +87,22 @@ type DeepPartialReadonlySet = {} & ReadonlySet>; // @public (undocumented) type DeepPartialSet = {} & Set>; -// @public (undocumented) +// @public export class DocumentTransform { // Warning: (ae-forgotten-export) The symbol "TransformFn" needs to be exported by the entry point index.d.ts // Warning: (ae-forgotten-export) The symbol "DocumentTransformOptions" needs to be exported by the entry point index.d.ts constructor(transform: TransformFn, options?: DocumentTransformOptions); - // (undocumented) concat(otherTransform: DocumentTransform): DocumentTransform; - // (undocumented) static identity(): DocumentTransform; // @internal @deprecated readonly left?: DocumentTransform; resetCache(): void; // @internal @deprecated readonly right?: DocumentTransform; - // (undocumented) static split(predicate: (document: DocumentNode) => boolean, left: DocumentTransform, right?: DocumentTransform): DocumentTransform & { left: DocumentTransform; right: DocumentTransform; }; - // (undocumented) transformDocument(document: DocumentNode): DocumentNode; } @@ -135,7 +131,7 @@ export interface HKT { return: unknown; } -// @public (undocumented) +// @public export function isFormattedExecutionResult(result?: object): result is FormattedExecutionResult; // @public diff --git a/.api-reports/api-report-utilities_internal.api.md b/.api-reports/api-report-utilities_internal.api.md index 31bd77d7628..f4329853077 100644 --- a/.api-reports/api-report-utilities_internal.api.md +++ b/.api-reports/api-report-utilities_internal.api.md @@ -279,7 +279,7 @@ export const getInMemoryCacheMemoryInternals: (() => { }; }) | undefined; -// @internal @deprecated +// @public export function getMainDefinition(queryDoc: DocumentNode): OperationDefinitionNode | FragmentDefinitionNode; // @internal @deprecated (undocumented) diff --git a/.api-reports/api-report.api.md b/.api-reports/api-report.api.md index 6e6af958af2..29f1a261905 100644 --- a/.api-reports/api-report.api.md +++ b/.api-reports/api-report.api.md @@ -948,26 +948,22 @@ type DistributedRequiredExclude = T extends any ? Required extends Requ export { DocumentNode } -// @public (undocumented) +// @public export class DocumentTransform { // Warning: (ae-forgotten-export) The symbol "TransformFn" needs to be exported by the entry point index.d.ts // Warning: (ae-forgotten-export) The symbol "DocumentTransformOptions" needs to be exported by the entry point index.d.ts constructor(transform: TransformFn, options?: DocumentTransformOptions); - // (undocumented) concat(otherTransform: DocumentTransform): DocumentTransform; - // (undocumented) static identity(): DocumentTransform; // @internal @deprecated readonly left?: DocumentTransform; resetCache(): void; // @internal @deprecated readonly right?: DocumentTransform; - // (undocumented) static split(predicate: (document: DocumentNode) => boolean, left: DocumentTransform, right?: DocumentTransform): DocumentTransform & { left: DocumentTransform; right: DocumentTransform; }; - // (undocumented) transformDocument(document: DocumentNode): DocumentNode; } From 650a16e2d926bc6562d820dcc7e85677b998815c Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Fri, 8 Aug 2025 13:50:08 -0600 Subject: [PATCH 12/13] Update description --- src/utilities/graphql/transform.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/utilities/graphql/transform.ts b/src/utilities/graphql/transform.ts index cc3577e7bec..6d2cb117e81 100644 --- a/src/utilities/graphql/transform.ts +++ b/src/utilities/graphql/transform.ts @@ -10,8 +10,8 @@ const TYPENAME_FIELD: FieldNode = { }; /** - * Adds `__typename` to all selection sets in the document. The operation - * definition's selection set remains unchanged. + * Adds `__typename` to all selection sets in the document except for the root + * selection set. * * @param doc - The `ASTNode` to add `__typename` to * From 97af2768148f516141b3f711fef8fa30e60c33af Mon Sep 17 00:00:00 2001 From: Jerel Miller Date: Fri, 8 Aug 2025 13:52:33 -0600 Subject: [PATCH 13/13] Add remark to utils --- src/utilities/graphql/operations.ts | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/utilities/graphql/operations.ts b/src/utilities/graphql/operations.ts index 6cbbec89fbb..fdb970ecd7d 100644 --- a/src/utilities/graphql/operations.ts +++ b/src/utilities/graphql/operations.ts @@ -11,6 +11,10 @@ function isOperation( /** * Determine if a document is a mutation document. * + * @remarks + * If you are authoring an Apollo link, you might not need this utility. + * Prefer using the `operationType` property the `operation` object instead. + * * @param document - The GraphQL document to check * @returns A boolean indicating if the document is a mutation operation * @@ -35,6 +39,10 @@ export function isMutationOperation(document: DocumentNode) { /** * Determine if a document is a query document. * + * @remarks + * If you are authoring an Apollo link, you might not need this utility. + * Prefer using the `operationType` property the `operation` object instead. + * * @param document - The GraphQL document to check * @returns A boolean indicating if the document is a query operation * @@ -59,6 +67,10 @@ export function isQueryOperation(document: DocumentNode) { /** * Determine if a document is a subscription document. * + * @remarks + * If you are authoring an Apollo link, you might not need this utility. + * Prefer using the `operationType` property the `operation` object instead. + * * @param document - The GraphQL document to check * @returns A boolean indicating if the document is a subscription operation *