graphql 16.13.2 → 16.14.1

package/utilities/stripIgnoredCharacters.mjs

@@ -1,3 +1,4 @@
+/** @category AST Utilities */
 import { printBlockString } from '../language/blockString.mjs';
 import { isPunctuatorTokenKind, Lexer } from '../language/lexer.mjs';
 import { isSource, Source } from '../language/source.mjs';
@@ -21,9 +22,9 @@ import { TokenKind } from '../language/tokenKind.mjs';
  * Warning: It is guaranteed that this function will always produce stable results.
  * However, it's not guaranteed that it will stay the same between different
  * releases due to bugfixes or changes in the GraphQL specification.
- *
- * Query example:
- *
+ * @param source - The GraphQL source text or source object.
+ * @returns A semantically equivalent GraphQL source string without ignored characters.
+ * @example Query source
  * ```graphql
  * query SomeQuery($foo: String!, $bar: String) {
  *   someField(foo: $foo, bar: $bar) {
@@ -41,9 +42,7 @@ import { TokenKind } from '../language/tokenKind.mjs';
  * ```graphql
  * query SomeQuery($foo:String!$bar:String){someField(foo:$foo bar:$bar){a b{c d}}}
  * ```
- *
- * SDL example:
- *
+ * @example SDL source
  * ```graphql
  * """
  * Type description
@@ -61,6 +60,14 @@ import { TokenKind } from '../language/tokenKind.mjs';
  * ```graphql
  * """Type description""" type Foo{"""Field description""" bar:String}
  * ```
+ * @example
+ * ```ts
+ * import { stripIgnoredCharacters } from 'graphql/utilities';
+ *
+ * const source = stripIgnoredCharacters('query Example { name }');
+ *
+ * source; // => 'query Example{name}'
+ * ```
  */
 
 export function stripIgnoredCharacters(source) {
@@ -77,6 +84,8 @@ export function stripIgnoredCharacters(source) {
      * Every two non-punctuator tokens should have space between them.
      * Also prevent case of non-punctuator token following by spread resulting
      * in invalid token (e.g. `1...` is invalid Float token).
+     *
+     * @internal
      */
 
     const isNonPunctuator = !isPunctuatorTokenKind(currentToken.kind);

package/utilities/typeComparators.d.ts

@@ -1,7 +1,24 @@
+/** @category Type Comparisons */
 import type { GraphQLCompositeType, GraphQLType } from '../type/definition';
 import type { GraphQLSchema } from '../type/schema';
 /**
  * Provided two types, return true if the types are equal (invariant).
+ * @param typeA - The first GraphQL type to compare.
+ * @param typeB - The second GraphQL type to compare.
+ * @returns True when both types are equal.
+ * @example
+ * ```ts
+ * import {
+ *   GraphQLList,
+ *   GraphQLNonNull,
+ *   GraphQLString,
+ * } from 'graphql/type';
+ * import { isEqualType } from 'graphql/utilities';
+ *
+ * isEqualType(GraphQLString, GraphQLString); // => true
+ * isEqualType(new GraphQLList(GraphQLString), new GraphQLList(GraphQLString)); // => true
+ * isEqualType(new GraphQLNonNull(GraphQLString), GraphQLString); // => false
+ * ```
  */
 export declare function isEqualType(
   typeA: GraphQLType,
@@ -10,6 +27,40 @@ export declare function isEqualType(
 /**
  * Provided a type and a super type, return true if the first type is either
  * equal or a subset of the second super type (covariant).
+ * @param schema - GraphQL schema to use.
+ * @param maybeSubType - The possible subtype to compare.
+ * @param superType - The possible supertype to compare.
+ * @returns True when `maybeSubType` is equal to or a subtype of `superType`.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql/utilities';
+ * import {
+ *   GraphQLNonNull,
+ *   assertInterfaceType,
+ *   assertObjectType,
+ * } from 'graphql/type';
+ * import { isTypeSubTypeOf } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   interface Node {
+ *     id: ID!
+ *   }
+ *
+ *   type User implements Node {
+ *     id: ID!
+ *   }
+ *
+ *   type Query {
+ *     node: Node
+ *   }
+ * `);
+ * const Node = assertInterfaceType(schema.getType('Node'));
+ * const User = assertObjectType(schema.getType('User'));
+ *
+ * isTypeSubTypeOf(schema, User, Node); // => true
+ * isTypeSubTypeOf(schema, new GraphQLNonNull(User), Node); // => true
+ * isTypeSubTypeOf(schema, Node, User); // => false
+ * ```
  */
 export declare function isTypeSubTypeOf(
   schema: GraphQLSchema,
@@ -24,6 +75,39 @@ export declare function isTypeSubTypeOf(
  * be visited in a context of another type.
  *
  * This function is commutative.
+ * @param schema - GraphQL schema to use.
+ * @param typeA - The first GraphQL type to compare.
+ * @param typeB - The second GraphQL type to compare.
+ * @returns True when the two composite types can apply to at least one common object type.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql/utilities';
+ * import { assertObjectType, assertUnionType } from 'graphql/type';
+ * import { doTypesOverlap } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Photo {
+ *     url: String!
+ *   }
+ *
+ *   type Video {
+ *     url: String!
+ *   }
+ *
+ *   union Media = Photo | Video
+ *   union StillImage = Photo
+ *
+ *   type Query {
+ *     media: [Media]
+ *   }
+ * `);
+ * const Media = assertUnionType(schema.getType('Media'));
+ * const StillImage = assertUnionType(schema.getType('StillImage'));
+ * const Video = assertObjectType(schema.getType('Video'));
+ *
+ * doTypesOverlap(schema, Media, StillImage); // => true
+ * doTypesOverlap(schema, StillImage, Video); // => false
+ * ```
  */
 export declare function doTypesOverlap(
   schema: GraphQLSchema,

package/utilities/typeComparators.js

@@ -9,8 +9,26 @@ exports.isTypeSubTypeOf = isTypeSubTypeOf;
 
 var _definition = require('../type/definition.js');
 
+/** @category Type Comparisons */
+
 /**
  * Provided two types, return true if the types are equal (invariant).
+ * @param typeA - The first GraphQL type to compare.
+ * @param typeB - The second GraphQL type to compare.
+ * @returns True when both types are equal.
+ * @example
+ * ```ts
+ * import {
+ *   GraphQLList,
+ *   GraphQLNonNull,
+ *   GraphQLString,
+ * } from 'graphql/type';
+ * import { isEqualType } from 'graphql/utilities';
+ *
+ * isEqualType(GraphQLString, GraphQLString); // => true
+ * isEqualType(new GraphQLList(GraphQLString), new GraphQLList(GraphQLString)); // => true
+ * isEqualType(new GraphQLNonNull(GraphQLString), GraphQLString); // => false
+ * ```
  */
 function isEqualType(typeA, typeB) {
   // Equivalent types are equal.
@@ -37,6 +55,40 @@ function isEqualType(typeA, typeB) {
 /**
  * Provided a type and a super type, return true if the first type is either
  * equal or a subset of the second super type (covariant).
+ * @param schema - GraphQL schema to use.
+ * @param maybeSubType - The possible subtype to compare.
+ * @param superType - The possible supertype to compare.
+ * @returns True when `maybeSubType` is equal to or a subtype of `superType`.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql/utilities';
+ * import {
+ *   GraphQLNonNull,
+ *   assertInterfaceType,
+ *   assertObjectType,
+ * } from 'graphql/type';
+ * import { isTypeSubTypeOf } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   interface Node {
+ *     id: ID!
+ *   }
+ *
+ *   type User implements Node {
+ *     id: ID!
+ *   }
+ *
+ *   type Query {
+ *     node: Node
+ *   }
+ * `);
+ * const Node = assertInterfaceType(schema.getType('Node'));
+ * const User = assertObjectType(schema.getType('User'));
+ *
+ * isTypeSubTypeOf(schema, User, Node); // => true
+ * isTypeSubTypeOf(schema, new GraphQLNonNull(User), Node); // => true
+ * isTypeSubTypeOf(schema, Node, User); // => false
+ * ```
  */
 
 function isTypeSubTypeOf(schema, maybeSubType, superType) {
@@ -87,6 +139,39 @@ function isTypeSubTypeOf(schema, maybeSubType, superType) {
  * be visited in a context of another type.
  *
  * This function is commutative.
+ * @param schema - GraphQL schema to use.
+ * @param typeA - The first GraphQL type to compare.
+ * @param typeB - The second GraphQL type to compare.
+ * @returns True when the two composite types can apply to at least one common object type.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql/utilities';
+ * import { assertObjectType, assertUnionType } from 'graphql/type';
+ * import { doTypesOverlap } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Photo {
+ *     url: String!
+ *   }
+ *
+ *   type Video {
+ *     url: String!
+ *   }
+ *
+ *   union Media = Photo | Video
+ *   union StillImage = Photo
+ *
+ *   type Query {
+ *     media: [Media]
+ *   }
+ * `);
+ * const Media = assertUnionType(schema.getType('Media'));
+ * const StillImage = assertUnionType(schema.getType('StillImage'));
+ * const Video = assertObjectType(schema.getType('Video'));
+ *
+ * doTypesOverlap(schema, Media, StillImage); // => true
+ * doTypesOverlap(schema, StillImage, Video); // => false
+ * ```
  */
 
 function doTypesOverlap(schema, typeA, typeB) {

package/utilities/typeComparators.mjs

@@ -1,3 +1,4 @@
+/** @category Type Comparisons */
 import {
   isAbstractType,
   isInterfaceType,
@@ -8,6 +9,22 @@ import {
 
 /**
  * Provided two types, return true if the types are equal (invariant).
+ * @param typeA - The first GraphQL type to compare.
+ * @param typeB - The second GraphQL type to compare.
+ * @returns True when both types are equal.
+ * @example
+ * ```ts
+ * import {
+ *   GraphQLList,
+ *   GraphQLNonNull,
+ *   GraphQLString,
+ * } from 'graphql/type';
+ * import { isEqualType } from 'graphql/utilities';
+ *
+ * isEqualType(GraphQLString, GraphQLString); // => true
+ * isEqualType(new GraphQLList(GraphQLString), new GraphQLList(GraphQLString)); // => true
+ * isEqualType(new GraphQLNonNull(GraphQLString), GraphQLString); // => false
+ * ```
  */
 export function isEqualType(typeA, typeB) {
   // Equivalent types are equal.
@@ -28,6 +45,40 @@ export function isEqualType(typeA, typeB) {
 /**
  * Provided a type and a super type, return true if the first type is either
  * equal or a subset of the second super type (covariant).
+ * @param schema - GraphQL schema to use.
+ * @param maybeSubType - The possible subtype to compare.
+ * @param superType - The possible supertype to compare.
+ * @returns True when `maybeSubType` is equal to or a subtype of `superType`.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql/utilities';
+ * import {
+ *   GraphQLNonNull,
+ *   assertInterfaceType,
+ *   assertObjectType,
+ * } from 'graphql/type';
+ * import { isTypeSubTypeOf } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   interface Node {
+ *     id: ID!
+ *   }
+ *
+ *   type User implements Node {
+ *     id: ID!
+ *   }
+ *
+ *   type Query {
+ *     node: Node
+ *   }
+ * `);
+ * const Node = assertInterfaceType(schema.getType('Node'));
+ * const User = assertObjectType(schema.getType('User'));
+ *
+ * isTypeSubTypeOf(schema, User, Node); // => true
+ * isTypeSubTypeOf(schema, new GraphQLNonNull(User), Node); // => true
+ * isTypeSubTypeOf(schema, Node, User); // => false
+ * ```
  */
 
 export function isTypeSubTypeOf(schema, maybeSubType, superType) {
@@ -77,6 +128,39 @@ export function isTypeSubTypeOf(schema, maybeSubType, superType) {
  * be visited in a context of another type.
  *
  * This function is commutative.
+ * @param schema - GraphQL schema to use.
+ * @param typeA - The first GraphQL type to compare.
+ * @param typeB - The second GraphQL type to compare.
+ * @returns True when the two composite types can apply to at least one common object type.
+ * @example
+ * ```ts
+ * import { buildSchema } from 'graphql/utilities';
+ * import { assertObjectType, assertUnionType } from 'graphql/type';
+ * import { doTypesOverlap } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Photo {
+ *     url: String!
+ *   }
+ *
+ *   type Video {
+ *     url: String!
+ *   }
+ *
+ *   union Media = Photo | Video
+ *   union StillImage = Photo
+ *
+ *   type Query {
+ *     media: [Media]
+ *   }
+ * `);
+ * const Media = assertUnionType(schema.getType('Media'));
+ * const StillImage = assertUnionType(schema.getType('StillImage'));
+ * const Video = assertObjectType(schema.getType('Video'));
+ *
+ * doTypesOverlap(schema, Media, StillImage); // => true
+ * doTypesOverlap(schema, StillImage, Video); // => false
+ * ```
  */
 
 export function doTypesOverlap(schema, typeA, typeB) {

package/utilities/typeFromAST.d.ts

@@ -1,3 +1,4 @@
+/** @category Values */
 import type {
   ListTypeNode,
   NamedTypeNode,
@@ -13,19 +14,104 @@ import type { GraphQLSchema } from '../type/schema';
  * AST node for `[User]`, a GraphQLList instance will be returned, containing
  * the type called "User" found in the schema. If a type called "User" is not
  * found in the schema, then undefined will be returned.
+ * @param schema - GraphQL schema to use.
+ * @param typeNode - The GraphQL type AST node to resolve.
+ * @returns The GraphQL type referenced by the AST node, or undefined if it cannot be resolved.
+ * @example
+ * ```ts
+ * import { parseType } from 'graphql/language';
+ * import { buildSchema, typeFromAST } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String
+ *   }
+ * `);
+ *
+ * typeFromAST(schema, parseType('String'))?.toString(); // => 'String'
+ * typeFromAST(schema, parseType('Missing')); // => undefined
+ * ```
  */
 export declare function typeFromAST(
   schema: GraphQLSchema,
   typeNode: NamedTypeNode,
 ): GraphQLNamedType | undefined;
+/**
+ * Resolves a list type AST node against a schema.
+ * @param schema - GraphQL schema to use.
+ * @param typeNode - The list type AST node to resolve.
+ * @returns The GraphQL list type referenced by the AST node, or undefined if
+ * it cannot be resolved.
+ * @example
+ * ```ts
+ * import { parseType } from 'graphql/language';
+ * import { buildSchema, typeFromAST } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     tags: [String]
+ *   }
+ * `);
+ *
+ * typeFromAST(schema, parseType('[String]'))?.toString(); // => '[String]'
+ * typeFromAST(schema, parseType('[Missing]')); // => undefined
+ * ```
+ */
 export declare function typeFromAST(
   schema: GraphQLSchema,
   typeNode: ListTypeNode,
 ): GraphQLList<any> | undefined;
+/**
+ * Resolves a non-null type AST node against a schema.
+ * @param schema - GraphQL schema to use.
+ * @param typeNode - The non-null type AST node to resolve.
+ * @returns The GraphQL non-null type referenced by the AST node, or undefined
+ * if it cannot be resolved.
+ * @example
+ * ```ts
+ * import { parseType } from 'graphql/language';
+ * import { buildSchema, typeFromAST } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     name: String!
+ *   }
+ * `);
+ *
+ * typeFromAST(schema, parseType('String!'))?.toString(); // => 'String!'
+ * typeFromAST(schema, parseType('[String!]!'))?.toString(); // => '[String!]!'
+ * ```
+ */
 export declare function typeFromAST(
   schema: GraphQLSchema,
   typeNode: NonNullTypeNode,
 ): GraphQLNonNull<any> | undefined;
+/**
+ * Resolves a type AST node against a schema.
+ * @param schema - GraphQL schema to use.
+ * @param typeNode - The GraphQL type AST node to resolve.
+ * @returns The GraphQL type referenced by the AST node, or undefined if it
+ * cannot be resolved.
+ * @example
+ * ```ts
+ * import { parseType } from 'graphql/language';
+ * import { buildSchema, typeFromAST } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type User {
+ *     name: String
+ *   }
+ *
+ *   type Query {
+ *     users: [User!]!
+ *   }
+ * `);
+ *
+ * typeFromAST(schema, parseType('User'))?.toString(); // => 'User'
+ * typeFromAST(schema, parseType('[User!]!'))?.toString(); // => '[User!]!'
+ * typeFromAST(schema, parseType('Missing')); // => undefined
+ * ```
+ */
 export declare function typeFromAST(
   schema: GraphQLSchema,
   typeNode: TypeNode,

package/utilities/typeFromAST.js

@@ -9,6 +9,9 @@ var _kinds = require('../language/kinds.js');
 
 var _definition = require('../type/definition.js');
 
+/** @category Values */
+
+/** @internal */
 function typeFromAST(schema, typeNode) {
   switch (typeNode.kind) {
     case _kinds.Kind.LIST_TYPE: {

package/utilities/typeFromAST.mjs

@@ -1,5 +1,8 @@
+/** @category Values */
 import { Kind } from '../language/kinds.mjs';
 import { GraphQLList, GraphQLNonNull } from '../type/definition.mjs';
+
+/** @internal */
 export function typeFromAST(schema, typeNode) {
   switch (typeNode.kind) {
     case Kind.LIST_TYPE: {

package/utilities/typedQueryDocumentNode.d.ts

@@ -1,6 +1,9 @@
+/** @category Typed Documents */
 import type { DocumentNode, ExecutableDefinitionNode } from '../language/ast';
 /**
  * Wrapper type that contains DocumentNode and types that can be deduced from it.
+ * @typeParam TResponseData - Typed GraphQL response data shape.
+ * @typeParam TRequestVariables - Typed GraphQL request variables shape.
  */
 export interface TypedQueryDocumentNode<
   TResponseData = {
@@ -10,6 +13,7 @@ export interface TypedQueryDocumentNode<
     [key: string]: any;
   },
 > extends DocumentNode {
+  /** Top-level executable and type-system definitions in this document. */
   readonly definitions: ReadonlyArray<ExecutableDefinitionNode>;
   /**
    * This type is used to ensure that the variables you pass in to the query are assignable to Variables

package/utilities/valueFromAST.d.ts

@@ -1,3 +1,4 @@
+/** @category Values */
 import type { Maybe } from '../jsutils/Maybe';
 import type { ObjMap } from '../jsutils/ObjMap';
 import type { ValueNode } from '../language/ast';
@@ -20,7 +21,44 @@ import type { GraphQLInputType } from '../type/definition';
  * | Int / Float          | Number        |
  * | Enum Value           | Unknown       |
  * | NullValue            | null          |
+ * @param valueNode - GraphQL value AST node to convert.
+ * @param type - The GraphQL type to inspect.
+ * @param variables - Optional runtime variable values keyed by variable name.
+ * @returns The coerced JavaScript value, or undefined if the AST value cannot be coerced to the type.
+ * @example
+ * ```ts
+ * // Coerce literal values without variables.
+ * import { parseValue } from 'graphql/language';
+ * import {
+ *   GraphQLInputObjectType,
+ *   GraphQLInt,
+ *   GraphQLList,
+ *   GraphQLNonNull,
+ *   GraphQLString,
+ * } from 'graphql/type';
+ * import { valueFromAST } from 'graphql/utilities';
  *
+ * const ReviewInput = new GraphQLInputObjectType({
+ *   name: 'ReviewInput',
+ *   fields: {
+ *     stars: { type: new GraphQLNonNull(GraphQLInt) },
+ *     tags: { type: new GraphQLList(GraphQLString) },
+ *   },
+ * });
+ *
+ * valueFromAST(parseValue('{ stars: 5, tags: ["featured"] }'), ReviewInput); // => { stars: 5, tags: ['featured'] }
+ * valueFromAST(parseValue('{ stars: "bad" }'), ReviewInput); // => undefined
+ * ```
+ * @example
+ * ```ts
+ * // This variant resolves variable references from runtime values.
+ * import { parseValue } from 'graphql/language';
+ * import { GraphQLInt } from 'graphql/type';
+ * import { valueFromAST } from 'graphql/utilities';
+ *
+ * valueFromAST(parseValue('$stars'), GraphQLInt, { stars: 5 }); // => 5
+ * valueFromAST(parseValue('$stars'), GraphQLInt, {}); // => undefined
+ * ```
  */
 export declare function valueFromAST(
   valueNode: Maybe<ValueNode>,

package/utilities/valueFromAST.js

@@ -15,6 +15,8 @@ var _kinds = require('../language/kinds.js');
 
 var _definition = require('../type/definition.js');
 
+/** @category Values */
+
 /**
  * Produces a JavaScript value given a GraphQL Value AST.
  *
@@ -33,7 +35,44 @@ var _definition = require('../type/definition.js');
  * | Int / Float          | Number        |
  * | Enum Value           | Unknown       |
  * | NullValue            | null          |
+ * @param valueNode - GraphQL value AST node to convert.
+ * @param type - The GraphQL type to inspect.
+ * @param variables - Optional runtime variable values keyed by variable name.
+ * @returns The coerced JavaScript value, or undefined if the AST value cannot be coerced to the type.
+ * @example
+ * ```ts
+ * // Coerce literal values without variables.
+ * import { parseValue } from 'graphql/language';
+ * import {
+ *   GraphQLInputObjectType,
+ *   GraphQLInt,
+ *   GraphQLList,
+ *   GraphQLNonNull,
+ *   GraphQLString,
+ * } from 'graphql/type';
+ * import { valueFromAST } from 'graphql/utilities';
+ *
+ * const ReviewInput = new GraphQLInputObjectType({
+ *   name: 'ReviewInput',
+ *   fields: {
+ *     stars: { type: new GraphQLNonNull(GraphQLInt) },
+ *     tags: { type: new GraphQLList(GraphQLString) },
+ *   },
+ * });
+ *
+ * valueFromAST(parseValue('{ stars: 5, tags: ["featured"] }'), ReviewInput); // => { stars: 5, tags: ['featured'] }
+ * valueFromAST(parseValue('{ stars: "bad" }'), ReviewInput); // => undefined
+ * ```
+ * @example
+ * ```ts
+ * // This variant resolves variable references from runtime values.
+ * import { parseValue } from 'graphql/language';
+ * import { GraphQLInt } from 'graphql/type';
+ * import { valueFromAST } from 'graphql/utilities';
  *
+ * valueFromAST(parseValue('$stars'), GraphQLInt, { stars: 5 }); // => 5
+ * valueFromAST(parseValue('$stars'), GraphQLInt, {}); // => undefined
+ * ```
  */
 function valueFromAST(valueNode, type, variables) {
   if (!valueNode) {
@@ -45,7 +84,11 @@ function valueFromAST(valueNode, type, variables) {
   if (valueNode.kind === _kinds.Kind.VARIABLE) {
     const variableName = valueNode.name.value;
 
-    if (variables == null || variables[variableName] === undefined) {
+    if (
+      variables == null ||
+      variables[variableName] === undefined ||
+      !hasOwnProperty(variables, variableName)
+    ) {
       // No valid return value.
       return;
     }
@@ -192,6 +235,12 @@ function valueFromAST(valueNode, type, variables) {
 function isMissingVariable(valueNode, variables) {
   return (
     valueNode.kind === _kinds.Kind.VARIABLE &&
-    (variables == null || variables[valueNode.name.value] === undefined)
+    (variables == null ||
+      variables[valueNode.name.value] === undefined ||
+      !hasOwnProperty(variables, valueNode.name.value))
   );
 }
+
+function hasOwnProperty(obj, prop) {
+  return Object.prototype.hasOwnProperty.call(obj, prop);
+}