@apollo/client 4.0.0-rc.9 → 4.0.0

package/utilities/graphql/operations.d.ts

@@ -2,25 +2,76 @@ import type { DocumentNode } from "@apollo/client";
 /**
  * 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
+ *
+ * @example
+ *
+ * ```ts
+ * import { isMutationOperation } from "@apollo/client/utilities";
  *
- * @since 3.8.0
+ * const mutation = gql`
+ *   mutation MyMutation {
+ *     # ...
+ *   }
+ * `;
+ *
+ * isMutationOperation(mutation); // true
+ * ```
  */
 export declare function isMutationOperation(document: DocumentNode): boolean;
 /**
  * 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
+ *
+ * @example
  *
- * @since 3.8.0
+ * ```ts
+ * import { isQueryOperation } from "@apollo/client/utilities";
+ *
+ * const query = gql`
+ *   query MyQuery {
+ *     # ...
+ *   }
+ * `;
+ *
+ * isQueryOperation(query); // true
+ * ```
  */
 export declare function isQueryOperation(document: DocumentNode): boolean;
 /**
  * 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
+ *
+ * @example
+ *
+ * ```ts
+ * import { isSubscriptionOperation } from "@apollo/client/utilities";
+ *
+ * const subscription = gql`
+ *   subscription MySubscription {
+ *     # ...
+ *   }
+ * `;
  *
- * @since 3.8.0
+ * isSubscriptionOperation(subscription); // true
+ * ```
  */
 export declare function isSubscriptionOperation(document: DocumentNode): boolean;
 //# sourceMappingURL=operations.d.ts.map

package/utilities/graphql/operations.js

@@ -5,9 +5,26 @@ function isOperation(document, operation) {
 /**
  * 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
+ *
+ * @example
+ *
+ * ```ts
+ * import { isMutationOperation } from "@apollo/client/utilities";
  *
- * @since 3.8.0
+ * const mutation = gql`
+ *   mutation MyMutation {
+ *     # ...
+ *   }
+ * `;
+ *
+ * isMutationOperation(mutation); // true
+ * ```
  */
 export function isMutationOperation(document) {
     return isOperation(document, "mutation");
@@ -15,9 +32,26 @@ export function isMutationOperation(document) {
 /**
  * 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
+ *
+ * @example
  *
- * @since 3.8.0
+ * ```ts
+ * import { isQueryOperation } from "@apollo/client/utilities";
+ *
+ * const query = gql`
+ *   query MyQuery {
+ *     # ...
+ *   }
+ * `;
+ *
+ * isQueryOperation(query); // true
+ * ```
  */
 export function isQueryOperation(document) {
     return isOperation(document, "query");
@@ -25,9 +59,26 @@ export function isQueryOperation(document) {
 /**
  * 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
+ *
+ * @example
+ *
+ * ```ts
+ * import { isSubscriptionOperation } from "@apollo/client/utilities";
+ *
+ * const subscription = gql`
+ *   subscription MySubscription {
+ *     # ...
+ *   }
+ * `;
  *
- * @since 3.8.0
+ * isSubscriptionOperation(subscription); // true
+ * ```
  */
 export function isSubscriptionOperation(document) {
     return isOperation(document, "subscription");

package/utilities/graphql/operations.js.map

@@ -1 +1 @@
-{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../../src/utilities/graphql/operations.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAE3E,SAAS,WAAW,CAClB,QAAsB,EACtB,SAAgD;IAEhD,OAAO,sBAAsB,CAAC,QAAQ,CAAC,EAAE,SAAS,KAAK,SAAS,CAAC;AACnE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAsB;IACxD,OAAO,WAAW,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAsB;IACrD,OAAO,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAAsB;IAC5D,OAAO,WAAW,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;AAC/C,CAAC","sourcesContent":["import type { DocumentNode } from \"@apollo/client\";\nimport { getOperationDefinition } from \"@apollo/client/utilities/internal\";\n\nfunction isOperation(\n  document: DocumentNode,\n  operation: \"query\" | \"mutation\" | \"subscription\"\n) {\n  return getOperationDefinition(document)?.operation === operation;\n}\n\n/**\n * Determine if a document is a mutation document.\n *\n * @param document - The GraphQL document to check\n *\n * @since 3.8.0\n */\nexport function isMutationOperation(document: DocumentNode) {\n  return isOperation(document, \"mutation\");\n}\n\n/**\n * Determine if a document is a query document.\n *\n * @param document - The GraphQL document to check\n *\n * @since 3.8.0\n */\nexport function isQueryOperation(document: DocumentNode) {\n  return isOperation(document, \"query\");\n}\n\n/**\n * Determine if a document is a subscription document.\n *\n * @param document - The GraphQL document to check\n *\n * @since 3.8.0\n */\nexport function isSubscriptionOperation(document: DocumentNode) {\n  return isOperation(document, \"subscription\");\n}\n"]}
+{"version":3,"file":"operations.js","sourceRoot":"","sources":["../../../src/utilities/graphql/operations.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAC;AAE3E,SAAS,WAAW,CAClB,QAAsB,EACtB,SAAgD;IAEhD,OAAO,sBAAsB,CAAC,QAAQ,CAAC,EAAE,SAAS,KAAK,SAAS,CAAC;AACnE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAsB;IACxD,OAAO,WAAW,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAsB;IACrD,OAAO,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,uBAAuB,CAAC,QAAsB;IAC5D,OAAO,WAAW,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;AAC/C,CAAC","sourcesContent":["import type { DocumentNode } from \"@apollo/client\";\nimport { getOperationDefinition } from \"@apollo/client/utilities/internal\";\n\nfunction isOperation(\n  document: DocumentNode,\n  operation: \"query\" | \"mutation\" | \"subscription\"\n) {\n  return getOperationDefinition(document)?.operation === operation;\n}\n\n/**\n * Determine if a document is a mutation document.\n *\n * @remarks\n * If you are authoring an Apollo link, you might not need this utility.\n * Prefer using the `operationType` property the `operation` object instead.\n *\n * @param document - The GraphQL document to check\n * @returns A boolean indicating if the document is a mutation operation\n *\n * @example\n *\n * ```ts\n * import { isMutationOperation } from \"@apollo/client/utilities\";\n *\n * const mutation = gql`\n *   mutation MyMutation {\n *     # ...\n *   }\n * `;\n *\n * isMutationOperation(mutation); // true\n * ```\n */\nexport function isMutationOperation(document: DocumentNode) {\n  return isOperation(document, \"mutation\");\n}\n\n/**\n * Determine if a document is a query document.\n *\n * @remarks\n * If you are authoring an Apollo link, you might not need this utility.\n * Prefer using the `operationType` property the `operation` object instead.\n *\n * @param document - The GraphQL document to check\n * @returns A boolean indicating if the document is a query operation\n *\n * @example\n *\n * ```ts\n * import { isQueryOperation } from \"@apollo/client/utilities\";\n *\n * const query = gql`\n *   query MyQuery {\n *     # ...\n *   }\n * `;\n *\n * isQueryOperation(query); // true\n * ```\n */\nexport function isQueryOperation(document: DocumentNode) {\n  return isOperation(document, \"query\");\n}\n\n/**\n * Determine if a document is a subscription document.\n *\n * @remarks\n * If you are authoring an Apollo link, you might not need this utility.\n * Prefer using the `operationType` property the `operation` object instead.\n *\n * @param document - The GraphQL document to check\n * @returns A boolean indicating if the document is a subscription operation\n *\n * @example\n *\n * ```ts\n * import { isSubscriptionOperation } from \"@apollo/client/utilities\";\n *\n * const subscription = gql`\n *   subscription MySubscription {\n *     # ...\n *   }\n * `;\n *\n * isSubscriptionOperation(subscription); // true\n * ```\n */\nexport function isSubscriptionOperation(document: DocumentNode) {\n  return isOperation(document, \"subscription\");\n}\n"]}

package/utilities/graphql/storeUtils.d.ts

@@ -8,6 +8,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 declare function isReference(obj: any): obj is Reference;
 /**

package/utilities/graphql/storeUtils.js

@@ -2,6 +2,15 @@
  * 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) {
     return Boolean(obj && typeof obj === "object" && typeof obj.__ref === "string");

package/utilities/graphql/storeUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"storeUtils.js","sourceRoot":"","sources":["../../../src/utilities/graphql/storeUtils.ts"],"names":[],"mappings":"AAOA;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,GAAQ;IAClC,OAAO,OAAO,CACZ,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,CAChE,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Representation of a reference object inside the cache.\n */\nexport interface Reference {\n  readonly __ref: string;\n}\n\n/**\n * Determines if a given object is a reference object.\n *\n * @param obj - The object to check if its a reference object\n */\nexport function isReference(obj: any): obj is Reference {\n  return Boolean(\n    obj && typeof obj === \"object\" && typeof obj.__ref === \"string\"\n  );\n}\n\n/**\n * Represents the union of valid values that can be stored in the cache.\n */\nexport type StoreValue =\n  | number\n  | string\n  | string[]\n  | Reference\n  | Reference[]\n  | null\n  | undefined\n  | void\n  | Object;\n\n/**\n * Represents an object that is stored in the cache.\n */\nexport interface StoreObject {\n  __typename?: string;\n  [storeFieldName: string]: StoreValue;\n}\n\n/**\n * Workaround for a TypeScript quirk:\n * types per default have an implicit index signature that makes them\n * assignable to `StoreObject`.\n * interfaces do not have that implicit index signature, so they cannot\n * be assigned to `StoreObject`.\n * This type just maps over a type or interface that is passed in,\n * implicitly adding the index signature.\n * That way, the result can be assigned to `StoreObject`.\n *\n * This is important if some user-defined interface is used e.g.\n * in cache.modify, where the `toReference` method expects a\n * `StoreObject` as input.\n */\nexport type AsStoreObject<T extends { __typename?: string }> = {\n  [K in keyof T]: T[K];\n};\n"]}
+{"version":3,"file":"storeUtils.js","sourceRoot":"","sources":["../../../src/utilities/graphql/storeUtils.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAC,GAAQ;IAClC,OAAO,OAAO,CACZ,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ,CAChE,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Representation of a reference object inside the cache.\n */\nexport interface Reference {\n  readonly __ref: string;\n}\n\n/**\n * Determines if a given object is a reference object.\n *\n * @param obj - The object to check if its a reference object\n *\n * @example\n *\n * ```ts\n * import { isReference } from \"@apollo/client/utilities\";\n *\n * isReference({ __ref: \"User:1\" }); // true\n * isReference({ __typename: \"User\", id: 1 }); // false\n * ```\n */\nexport function isReference(obj: any): obj is Reference {\n  return Boolean(\n    obj && typeof obj === \"object\" && typeof obj.__ref === \"string\"\n  );\n}\n\n/**\n * Represents the union of valid values that can be stored in the cache.\n */\nexport type StoreValue =\n  | number\n  | string\n  | string[]\n  | Reference\n  | Reference[]\n  | null\n  | undefined\n  | void\n  | Object;\n\n/**\n * Represents an object that is stored in the cache.\n */\nexport interface StoreObject {\n  __typename?: string;\n  [storeFieldName: string]: StoreValue;\n}\n\n/**\n * Workaround for a TypeScript quirk:\n * types per default have an implicit index signature that makes them\n * assignable to `StoreObject`.\n * interfaces do not have that implicit index signature, so they cannot\n * be assigned to `StoreObject`.\n * This type just maps over a type or interface that is passed in,\n * implicitly adding the index signature.\n * That way, the result can be assigned to `StoreObject`.\n *\n * This is important if some user-defined interface is used e.g.\n * in cache.modify, where the `toReference` method expects a\n * `StoreObject` as input.\n */\nexport type AsStoreObject<T extends { __typename?: string }> = {\n  [K in keyof T]: T[K];\n};\n"]}

package/utilities/graphql/transform.d.ts

@@ -1,8 +1,19 @@
 import type { ASTNode, FieldNode } from "graphql";
 /**
- * Adds `__typename` to all selection sets in the document.
+ * Adds `__typename` to all selection sets in the document except for the root
+ * selection set.
  *
  * @param doc - The `ASTNode` to add `__typename` to
+ *
+ * @example
+ *
+ * ```ts
+ * const document = gql`
+ *   # ...
+ * `;
+ *
+ * const withTypename = addTypenameToDocument(document);
+ * ```
  */
 export declare const addTypenameToDocument: (<TNode extends ASTNode>(doc: TNode) => TNode) & {
     added(field: FieldNode): boolean;

package/utilities/graphql/transform.js

@@ -7,9 +7,20 @@ const TYPENAME_FIELD = {
     },
 };
 /**
- * Adds `__typename` to all selection sets in the document.
+ * Adds `__typename` to all selection sets in the document except for the root
+ * selection set.
  *
  * @param doc - The `ASTNode` to add `__typename` to
+ *
+ * @example
+ *
+ * ```ts
+ * const document = gql`
+ *   # ...
+ * `;
+ *
+ * const withTypename = addTypenameToDocument(document);
+ * ```
  */
 export const addTypenameToDocument = Object.assign(function (doc) {
     return visit(doc, {

package/utilities/graphql/transform.js.map

@@ -1 +1 @@
-{"version":3,"file":"transform.js","sourceRoot":"","sources":["../../../src/utilities/graphql/transform.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAEtC,MAAM,cAAc,GAAc;IAChC,IAAI,EAAE,IAAI,CAAC,KAAK;IAChB,IAAI,EAAE;QACJ,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,KAAK,EAAE,YAAY;KACpB;CACF,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,CAChD,UAAiC,GAAU;IACzC,OAAO,KAAK,CAAC,GAAG,EAAE;QAChB,YAAY,EAAE;YACZ,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM;gBACtB,gDAAgD;gBAChD,IACE,MAAM;oBACL,MAAkC,CAAC,IAAI;wBACtC,IAAI,CAAC,oBAAoB,EAC3B,CAAC;oBACD,OAAO;gBACT,CAAC;gBAED,+BAA+B;gBAC/B,MAAM,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;gBAC5B,IAAI,CAAC,UAAU,EAAE,CAAC;oBAChB,OAAO;gBACT,CAAC;gBAED,6DAA6D;gBAC7D,mCAAmC;gBACnC,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE;oBACzC,OAAO,CACL,SAAS,CAAC,IAAI,KAAK,IAAI,CAAC,KAAK;wBAC7B,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,KAAK,YAAY;4BACpC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CACnD,CAAC;gBACJ,CAAC,CAAC,CAAC;gBACH,IAAI,IAAI,EAAE,CAAC;oBACT,OAAO;gBACT,CAAC;gBAED,qEAAqE;gBACrE,iDAAiD;gBACjD,MAAM,KAAK,GAAG,MAAmB,CAAC;gBAClC,IACE,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,KAAK;oBACzB,KAAK,CAAC,UAAU;oBAChB,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,EACvD,CAAC;oBACD,OAAO;gBACT,CAAC;gBAED,gEAAgE;gBAChE,OAAO;oBACL,GAAG,IAAI;oBACP,UAAU,EAAE,CAAC,GAAG,UAAU,EAAE,cAAc,CAAC;iBAC5C,CAAC;YACJ,CAAC;SACF;KACF,CAAC,CAAC;AACL,CAAC,EACD;IACE,KAAK,CAAC,KAAgB;QACpB,OAAO,KAAK,KAAK,cAAc,CAAC;IAClC,CAAC;CACF,CACF,CAAC","sourcesContent":["import type { ASTNode, FieldNode, OperationDefinitionNode } from \"graphql\";\nimport { Kind, visit } from \"graphql\";\n\nconst TYPENAME_FIELD: FieldNode = {\n  kind: Kind.FIELD,\n  name: {\n    kind: Kind.NAME,\n    value: \"__typename\",\n  },\n};\n\n/**\n * Adds `__typename` to all selection sets in the document.\n *\n * @param doc - The `ASTNode` to add `__typename` to\n */\nexport const addTypenameToDocument = Object.assign(\n  function <TNode extends ASTNode>(doc: TNode): TNode {\n    return visit(doc, {\n      SelectionSet: {\n        enter(node, _key, parent) {\n          // Don't add __typename to OperationDefinitions.\n          if (\n            parent &&\n            (parent as OperationDefinitionNode).kind ===\n              Kind.OPERATION_DEFINITION\n          ) {\n            return;\n          }\n\n          // No changes if no selections.\n          const { selections } = node;\n          if (!selections) {\n            return;\n          }\n\n          // If selections already have a __typename, or are part of an\n          // introspection query, do nothing.\n          const skip = selections.some((selection) => {\n            return (\n              selection.kind === Kind.FIELD &&\n              (selection.name.value === \"__typename\" ||\n                selection.name.value.lastIndexOf(\"__\", 0) === 0)\n            );\n          });\n          if (skip) {\n            return;\n          }\n\n          // If this SelectionSet is @export-ed as an input variable, it should\n          // not have a __typename field (see issue #4691).\n          const field = parent as FieldNode;\n          if (\n            field.kind === Kind.FIELD &&\n            field.directives &&\n            field.directives.some((d) => d.name.value === \"export\")\n          ) {\n            return;\n          }\n\n          // Create and return a new SelectionSet with a __typename Field.\n          return {\n            ...node,\n            selections: [...selections, TYPENAME_FIELD],\n          };\n        },\n      },\n    });\n  },\n  {\n    added(field: FieldNode): boolean {\n      return field === TYPENAME_FIELD;\n    },\n  }\n);\n"]}
+{"version":3,"file":"transform.js","sourceRoot":"","sources":["../../../src/utilities/graphql/transform.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAEtC,MAAM,cAAc,GAAc;IAChC,IAAI,EAAE,IAAI,CAAC,KAAK;IAChB,IAAI,EAAE;QACJ,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,KAAK,EAAE,YAAY;KACpB;CACF,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,CAChD,UAAiC,GAAU;IACzC,OAAO,KAAK,CAAC,GAAG,EAAE;QAChB,YAAY,EAAE;YACZ,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM;gBACtB,gDAAgD;gBAChD,IACE,MAAM;oBACL,MAAkC,CAAC,IAAI;wBACtC,IAAI,CAAC,oBAAoB,EAC3B,CAAC;oBACD,OAAO;gBACT,CAAC;gBAED,+BAA+B;gBAC/B,MAAM,EAAE,UAAU,EAAE,GAAG,IAAI,CAAC;gBAC5B,IAAI,CAAC,UAAU,EAAE,CAAC;oBAChB,OAAO;gBACT,CAAC;gBAED,6DAA6D;gBAC7D,mCAAmC;gBACnC,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE;oBACzC,OAAO,CACL,SAAS,CAAC,IAAI,KAAK,IAAI,CAAC,KAAK;wBAC7B,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,KAAK,YAAY;4BACpC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CACnD,CAAC;gBACJ,CAAC,CAAC,CAAC;gBACH,IAAI,IAAI,EAAE,CAAC;oBACT,OAAO;gBACT,CAAC;gBAED,qEAAqE;gBACrE,iDAAiD;gBACjD,MAAM,KAAK,GAAG,MAAmB,CAAC;gBAClC,IACE,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,KAAK;oBACzB,KAAK,CAAC,UAAU;oBAChB,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,EACvD,CAAC;oBACD,OAAO;gBACT,CAAC;gBAED,gEAAgE;gBAChE,OAAO;oBACL,GAAG,IAAI;oBACP,UAAU,EAAE,CAAC,GAAG,UAAU,EAAE,cAAc,CAAC;iBAC5C,CAAC;YACJ,CAAC;SACF;KACF,CAAC,CAAC;AACL,CAAC,EACD;IACE,KAAK,CAAC,KAAgB;QACpB,OAAO,KAAK,KAAK,cAAc,CAAC;IAClC,CAAC;CACF,CACF,CAAC","sourcesContent":["import type { ASTNode, FieldNode, OperationDefinitionNode } from \"graphql\";\nimport { Kind, visit } from \"graphql\";\n\nconst TYPENAME_FIELD: FieldNode = {\n  kind: Kind.FIELD,\n  name: {\n    kind: Kind.NAME,\n    value: \"__typename\",\n  },\n};\n\n/**\n * Adds `__typename` to all selection sets in the document except for the root\n * selection set.\n *\n * @param doc - The `ASTNode` to add `__typename` to\n *\n * @example\n *\n * ```ts\n * const document = gql`\n *   # ...\n * `;\n *\n * const withTypename = addTypenameToDocument(document);\n * ```\n */\nexport const addTypenameToDocument = Object.assign(\n  function <TNode extends ASTNode>(doc: TNode): TNode {\n    return visit(doc, {\n      SelectionSet: {\n        enter(node, _key, parent) {\n          // Don't add __typename to OperationDefinitions.\n          if (\n            parent &&\n            (parent as OperationDefinitionNode).kind ===\n              Kind.OPERATION_DEFINITION\n          ) {\n            return;\n          }\n\n          // No changes if no selections.\n          const { selections } = node;\n          if (!selections) {\n            return;\n          }\n\n          // If selections already have a __typename, or are part of an\n          // introspection query, do nothing.\n          const skip = selections.some((selection) => {\n            return (\n              selection.kind === Kind.FIELD &&\n              (selection.name.value === \"__typename\" ||\n                selection.name.value.lastIndexOf(\"__\", 0) === 0)\n            );\n          });\n          if (skip) {\n            return;\n          }\n\n          // If this SelectionSet is @export-ed as an input variable, it should\n          // not have a __typename field (see issue #4691).\n          const field = parent as FieldNode;\n          if (\n            field.kind === Kind.FIELD &&\n            field.directives &&\n            field.directives.some((d) => d.name.value === \"export\")\n          ) {\n            return;\n          }\n\n          // Create and return a new SelectionSet with a __typename Field.\n          return {\n            ...node,\n            selections: [...selections, TYPENAME_FIELD],\n          };\n        },\n      },\n    });\n  },\n  {\n    added(field: FieldNode): boolean {\n      return field === TYPENAME_FIELD;\n    },\n  }\n);\n"]}

package/utilities/internal/canonicalStringify.d.ts

@@ -1,19 +1,42 @@
 /**
- * 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 declare const canonicalStringify: ((value: any) => string) & {
     reset(): void;

package/utilities/internal/canonicalStringify.js

@@ -3,21 +3,44 @@ import { cacheSizes } from "../caching/sizes.js";
 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) {
     return JSON.stringify(value, stableObjectReplacer);

package/utilities/internal/canonicalStringify.js.map

@@ -1 +1 @@
-{"version":3,"file":"canonicalStringify.js","sourceRoot":"","sources":["../../../src/utilities/internal/canonicalStringify.ts"],"names":[],"mappings":"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","sourcesContent":["import { __DEV__ } from \"@apollo/client/utilities/environment\";\n\nimport { cacheSizes, defaultCacheSizes } from \"../caching/sizes.js\";\n\nimport { AutoCleanedStrongCache } from \"./caches.js\";\nimport { registerGlobalCache } from \"./getMemoryInternals.js\";\n\n/**\n * Like JSON.stringify, but with object keys always sorted in the same order.\n *\n * To achieve performant sorting, this function uses a Map from JSON-serialized\n * arrays of keys (in any order) to sorted arrays of the same keys, with a\n * single sorted array reference shared by all permutations of the keys.\n *\n * As a drawback, this function will add a little bit more memory for every\n * object encountered that has different (more, less, a different order of) keys\n * than in the past.\n *\n * In a typical application, this extra memory usage should not play a\n * significant role, as `canonicalStringify` will be called for only a limited\n * number of object shapes, and the cache will not grow beyond a certain point.\n * But in some edge cases, this could be a problem, so we provide\n * canonicalStringify.reset() as a way of clearing the cache.\n */\nexport const canonicalStringify = Object.assign(\n  function canonicalStringify(value: any): string {\n    return JSON.stringify(value, stableObjectReplacer);\n  },\n  {\n    reset() {\n      // Clearing the sortingMap will reclaim all cached memory, without\n      // affecting the logical results of canonicalStringify, but potentially\n      // sacrificing performance until the cache is refilled.\n      sortingMap = new AutoCleanedStrongCache<string, readonly string[]>(\n        cacheSizes.canonicalStringify || defaultCacheSizes.canonicalStringify\n      );\n    },\n  }\n);\n\nif (__DEV__) {\n  registerGlobalCache(\"canonicalStringify\", () => sortingMap.size);\n}\n\n// Values are JSON-serialized arrays of object keys (in any order), and values\n// are sorted arrays of the same keys.\nlet sortingMap!: AutoCleanedStrongCache<string, readonly string[]>;\ncanonicalStringify.reset();\n\n// The JSON.stringify function takes an optional second argument called a\n// replacer function. This function is called for each key-value pair in the\n// object being stringified, and its return value is used instead of the\n// original value. If the replacer function returns a new value, that value is\n// stringified as JSON instead of the original value of the property.\n// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#the_replacer_parameter\nfunction stableObjectReplacer(key: string, value: any) {\n  if (value && typeof value === \"object\") {\n    const proto = Object.getPrototypeOf(value);\n    // We don't want to mess with objects that are not \"plain\" objects, which\n    // means their prototype is either Object.prototype or null. This check also\n    // prevents needlessly rearranging the indices of arrays.\n    if (proto === Object.prototype || proto === null) {\n      const keys = Object.keys(value);\n      // If keys is already sorted, let JSON.stringify serialize the original\n      // value instead of creating a new object with keys in the same order.\n      if (keys.every(everyKeyInOrder)) return value;\n      const unsortedKey = JSON.stringify(keys);\n      let sortedKeys = sortingMap.get(unsortedKey);\n      if (!sortedKeys) {\n        keys.sort();\n        const sortedKey = JSON.stringify(keys);\n        // Checking for sortedKey in the sortingMap allows us to share the same\n        // sorted array reference for all permutations of the same set of keys.\n        sortedKeys = sortingMap.get(sortedKey) || keys;\n        sortingMap.set(unsortedKey, sortedKeys);\n        sortingMap.set(sortedKey, sortedKeys);\n      }\n      const sortedObject = Object.create(proto);\n      // Reassigning the keys in sorted order will cause JSON.stringify to\n      // serialize them in sorted order.\n      sortedKeys.forEach((key) => {\n        sortedObject[key] = value[key];\n      });\n      return sortedObject;\n    }\n  }\n  return value;\n}\n\n// Since everything that happens in stableObjectReplacer benefits from being as\n// efficient as possible, we use a static function as the callback for\n// keys.every in order to test if the provided keys are already sorted without\n// allocating extra memory for a callback.\nfunction everyKeyInOrder(\n  key: string,\n  i: number,\n  keys: readonly string[]\n): boolean {\n  return i === 0 || keys[i - 1] <= key;\n}\n"]}
+{"version":3,"file":"canonicalStringify.js","sourceRoot":"","sources":["../../../src/utilities/internal/canonicalStringify.ts"],"names":[],"mappings":"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","sourcesContent":["import { __DEV__ } from \"@apollo/client/utilities/environment\";\n\nimport { cacheSizes, defaultCacheSizes } from \"../caching/sizes.js\";\n\nimport { AutoCleanedStrongCache } from \"./caches.js\";\nimport { registerGlobalCache } from \"./getMemoryInternals.js\";\n\n/**\n * Serializes a value to JSON with object keys in a consistent, sorted order.\n *\n * @remarks\n *\n * Unlike `JSON.stringify()`, this function ensures that object keys are always\n * serialized in the same alphabetical order, regardless of their original order.\n * This makes it suitable for creating consistent cache keys from objects,\n * comparing objects by their serialized representation, or generating\n * deterministic hashes of objects.\n *\n * To achieve performant sorting, this function uses a `Map` from JSON-serialized\n * arrays of keys (in any order) to sorted arrays of the same keys, with a\n * single sorted array reference shared by all permutations of the keys.\n *\n * As a drawback, this function will add a little more memory for every object\n * encountered that has different (more, less, a different order of) keys than\n * in the past.\n *\n * In a typical application, this extra memory usage should not play a\n * significant role, as `canonicalStringify` will be called for only a limited\n * number of object shapes, and the cache will not grow beyond a certain point.\n * But in some edge cases, this could be a problem. Use canonicalStringify.reset()\n * as a way to clear the memoization cache.\n *\n * @param value - The value to stringify\n * @returns JSON string with consistently ordered object keys\n *\n * @example\n *\n * ```ts\n * import { canonicalStringify } from \"@apollo/client/utilities\";\n *\n * const obj1 = { b: 2, a: 1 };\n * const obj2 = { a: 1, b: 2 };\n *\n * console.log(canonicalStringify(obj1)); // '{\"a\":1,\"b\":2}'\n * console.log(canonicalStringify(obj2)); // '{\"a\":1,\"b\":2}'\n * ```\n */\nexport const canonicalStringify = Object.assign(\n  function canonicalStringify(value: any): string {\n    return JSON.stringify(value, stableObjectReplacer);\n  },\n  {\n    reset() {\n      // Clearing the sortingMap will reclaim all cached memory, without\n      // affecting the logical results of canonicalStringify, but potentially\n      // sacrificing performance until the cache is refilled.\n      sortingMap = new AutoCleanedStrongCache<string, readonly string[]>(\n        cacheSizes.canonicalStringify || defaultCacheSizes.canonicalStringify\n      );\n    },\n  }\n);\n\nif (__DEV__) {\n  registerGlobalCache(\"canonicalStringify\", () => sortingMap.size);\n}\n\n// Values are JSON-serialized arrays of object keys (in any order), and values\n// are sorted arrays of the same keys.\nlet sortingMap!: AutoCleanedStrongCache<string, readonly string[]>;\ncanonicalStringify.reset();\n\n// The JSON.stringify function takes an optional second argument called a\n// replacer function. This function is called for each key-value pair in the\n// object being stringified, and its return value is used instead of the\n// original value. If the replacer function returns a new value, that value is\n// stringified as JSON instead of the original value of the property.\n// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#the_replacer_parameter\nfunction stableObjectReplacer(key: string, value: any) {\n  if (value && typeof value === \"object\") {\n    const proto = Object.getPrototypeOf(value);\n    // We don't want to mess with objects that are not \"plain\" objects, which\n    // means their prototype is either Object.prototype or null. This check also\n    // prevents needlessly rearranging the indices of arrays.\n    if (proto === Object.prototype || proto === null) {\n      const keys = Object.keys(value);\n      // If keys is already sorted, let JSON.stringify serialize the original\n      // value instead of creating a new object with keys in the same order.\n      if (keys.every(everyKeyInOrder)) return value;\n      const unsortedKey = JSON.stringify(keys);\n      let sortedKeys = sortingMap.get(unsortedKey);\n      if (!sortedKeys) {\n        keys.sort();\n        const sortedKey = JSON.stringify(keys);\n        // Checking for sortedKey in the sortingMap allows us to share the same\n        // sorted array reference for all permutations of the same set of keys.\n        sortedKeys = sortingMap.get(sortedKey) || keys;\n        sortingMap.set(unsortedKey, sortedKeys);\n        sortingMap.set(sortedKey, sortedKeys);\n      }\n      const sortedObject = Object.create(proto);\n      // Reassigning the keys in sorted order will cause JSON.stringify to\n      // serialize them in sorted order.\n      sortedKeys.forEach((key) => {\n        sortedObject[key] = value[key];\n      });\n      return sortedObject;\n    }\n  }\n  return value;\n}\n\n// Since everything that happens in stableObjectReplacer benefits from being as\n// efficient as possible, we use a static function as the callback for\n// keys.every in order to test if the provided keys are already sorted without\n// allocating extra memory for a callback.\nfunction everyKeyInOrder(\n  key: string,\n  i: number,\n  keys: readonly string[]\n): boolean {\n  return i === 0 || keys[i - 1] <= key;\n}\n"]}

package/utilities/internal/getMainDefinition.d.ts

@@ -1,12 +1,40 @@
 import type { DocumentNode, FragmentDefinitionNode, OperationDefinitionNode } from "graphql";
 /**
-* 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.
-*
-* @internal
-* 
-* @deprecated This is an internal API and should not be used directly. This can be removed or changed at any time.
-*/
+ * 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.
+ *
+ * @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 declare function getMainDefinition(queryDoc: DocumentNode): OperationDefinitionNode | FragmentDefinitionNode;
-//# sourceMappingURL=getMainDefinition.d.ts.map
+//# sourceMappingURL=getMainDefinition.d.ts.map

package/utilities/internal/getMainDefinition.js

@@ -1,14 +1,42 @@
 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.
-*
-* @internal
-* 
-* @deprecated This is an internal API and should not be used directly. This can be removed or changed at any time.
-*/
+ * 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.
+ *
+ * @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) {
     checkDocument(queryDoc);
     let fragmentDefinition;

package/utilities/internal/getMainDefinition.js.map

@@ -1 +1 @@
-{"version":3,"file":"getMainDefinition.js","sources":["../../../src/utilities/internal/getMainDefinition.ts"],"sourcesContent":["import type {\n  DocumentNode,\n  FragmentDefinitionNode,\n  OperationDefinitionNode,\n} from \"graphql\";\n\nimport { newInvariantError } from \"@apollo/client/utilities/invariant\";\n\nimport { checkDocument } from \"./checkDocument.js\";\n\n/**\n * Returns the first operation definition found in this document.\n * If no operation definition is found, the first fragment definition will be returned.\n * If no definitions are found, an error will be thrown.\n *\n * @internal\n */\nexport function getMainDefinition(\n  queryDoc: DocumentNode\n): OperationDefinitionNode | FragmentDefinitionNode {\n  checkDocument(queryDoc);\n\n  let fragmentDefinition;\n\n  for (let definition of queryDoc.definitions) {\n    if (definition.kind === \"OperationDefinition\") {\n      return definition;\n    }\n\n    if (definition.kind === \"FragmentDefinition\" && !fragmentDefinition) {\n      // we do this because we want to allow multiple fragment definitions\n      // to precede an operation definition.\n      fragmentDefinition = definition;\n    }\n  }\n\n  if (fragmentDefinition) {\n    return fragmentDefinition;\n  }\n\n  throw newInvariantError(\n    \"Expected a parsed GraphQL query with a query, mutation, subscription, or a fragment.\"\n  );\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"getMainDefinition.js","sources":["../../../src/utilities/internal/getMainDefinition.ts"],"sourcesContent":["import type {\n  DocumentNode,\n  FragmentDefinitionNode,\n  OperationDefinitionNode,\n} from \"graphql\";\n\nimport { newInvariantError } from \"@apollo/client/utilities/invariant\";\n\nimport { checkDocument } from \"./checkDocument.js\";\n\n/**\n * Returns the first operation definition from a GraphQL document. The function\n * prioritizes operation definitions over fragment definitions, which makes it\n * suitable for documents that may contain both. If no operation definition is\n * found, the first fragment definition will be returned. If no definitions are\n * found, an error is thrown.\n *\n * @remarks\n *\n * Use this function when you need to perform more advanced tasks with the main\n * definition AST node. If you want to determine when a document is a specific\n * operation type, prefer the `isQueryOperation`, `isMutationOperation`, and\n * `isSubscriptionOperation` utility functions instead.\n *\n * @param queryDoc - The GraphQL document to extract the definition from\n * @returns The main operation or fragment definition AST node\n *\n * @example\n *\n * ```ts\n * import { gql } from \"@apollo/client\";\n * import { getMainDefinition } from \"@apollo/client/utilities\";\n *\n * const query = gql`\n *   query GetUser($id: ID!) {\n *     user(id: $id) {\n *       name\n *       email\n *     }\n *   }\n * `;\n *\n * const definition = getMainDefinition(query);\n * ```\n *\n * @throws When the document contains no operation or fragment definitions\n */\nexport function getMainDefinition(\n  queryDoc: DocumentNode\n): OperationDefinitionNode | FragmentDefinitionNode {\n  checkDocument(queryDoc);\n\n  let fragmentDefinition;\n\n  for (let definition of queryDoc.definitions) {\n    if (definition.kind === \"OperationDefinition\") {\n      return definition;\n    }\n\n    if (definition.kind === \"FragmentDefinition\" && !fragmentDefinition) {\n      // we do this because we want to allow multiple fragment definitions\n      // to precede an operation definition.\n      fragmentDefinition = definition;\n    }\n  }\n\n  if (fragmentDefinition) {\n    return fragmentDefinition;\n  }\n\n  throw newInvariantError(\n    \"Expected a parsed GraphQL query with a query, mutation, subscription, or a fragment.\"\n  );\n}\n"],"names":[],"mappings":"AAMA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAO,EAAE,CAAT,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,EAAA,CAAA,CAAA,CAAA,EAAkC,CAAlC,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAsE;AAEtE,CAAA,CAAA,CAAA,CAAA,CAAA,EAAO,EAAE,CAAT,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,EAAA,CAAA,CAAA,CAAA,EAA8B,CAA9B,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAkD;AAElD,CAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAoCA,CAAA;AACA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAgB,CAAhB,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAiC,CAC/B,CADF,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CACwB,EADxB;IAGE,CAAF,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAe,CAAC,CAAhB,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAwB,CAAC;IAEvB,CAAF,CAAA,EAAM,CAAN,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAwB;IAEtB,CAAF,CAAA,EAAA,CAAO,CAAP,CAAA,EAAW,CAAX,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,CAAA,EAAyB,CAAzB,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAiC,CAAC,CAAlC,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAA6C,EAAE;QAC3C,CAAJ,EAAA,CAAQ,CAAR,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAkB,CAAC,CAAnB,CAAA,CAAA,EAAA,CAAA,CAAA,EAA4B,CAA5B,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAiD,EAAE;YAC7C,CAAN,CAAA,CAAA,CAAA,CAAA,EAAa,CAAb,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAuB;QACnB;QAEA,CAAJ,EAAA,CAAQ,CAAR,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAkB,CAAC,CAAnB,CAAA,CAAA,EAAA,CAAA,CAAA,EAA4B,CAA5B,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,CAAA,EAAoD,CAAC,CAArD,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAuE,EAAE;YACnE,CAAN,EAAA,CAAA,EAAA,CAAA,EAAA,CAAA,CAAA,CAAA,EAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,CAAA,EAAA,CAAA,CAAA,CAAA,EAAA,CAAA,EAAA,CAAA,CAAA,CAAA,CAAA,EAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA;YACM,CAAN,EAAA,CAAA,EAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,CAAA,EAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA;YACM,CAAN,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,EAAA,EAA2B,CAA3B,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAqC;QACjC;IACF;IAEA,CAAF,EAAA,CAAM,CAAN,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAwB,EAAE;QACtB,CAAJ,CAAA,CAAA,CAAA,CAAA,EAAW,CAAX,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAA6B;IAC3B;IAEA,CAAF,CAAA,CAAA,CAAA,EAAQ,CAAR,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,CAAA,KAEG;AACH;"}

package/utilities/internal/types/DocumentationTypes.d.ts

@@ -52,7 +52,7 @@ export declare namespace DocumentationTypes {
         */
         error?: ErrorLike;
         /**
-        * If `true`, the query is still in flight and results have not yet been returned.
+        * If `true`, the query is still in flight.
         * 
         * @docGroup 2. Network info
         */