graphql 16.14.0 → 16.14.1

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) {

package/utilities/valueFromAST.mjs

@@ -1,3 +1,4 @@
+/** @category Values */
 import { inspect } from '../jsutils/inspect.mjs';
 import { invariant } from '../jsutils/invariant.mjs';
 import { keyMap } from '../jsutils/keyMap.mjs';
@@ -26,7 +27,44 @@ import {
  * | 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 function valueFromAST(valueNode, type, variables) {

package/utilities/valueFromASTUntyped.d.ts

@@ -1,11 +1,12 @@
+/** @category Values */
 import type { Maybe } from '../jsutils/Maybe';
 import type { ObjMap } from '../jsutils/ObjMap';
 import type { ValueNode } from '../language/ast';
 /**
  * Produces a JavaScript value given a GraphQL Value AST.
  *
- * Unlike `valueFromAST()`, no type is provided. The resulting JavaScript value
- * will reflect the provided GraphQL value AST.
+ * Because no GraphQL type is provided, the returned JavaScript value reflects
+ * the provided GraphQL value AST.
  *
  * | GraphQL Value        | JavaScript Value |
  * | -------------------- | ---------------- |
@@ -15,7 +16,19 @@ import type { ValueNode } from '../language/ast';
  * | String / Enum        | String           |
  * | Int / Float          | Number           |
  * | Null                 | null             |
+ * @param valueNode - GraphQL value AST node to convert.
+ * @param variables - Optional runtime variable values keyed by variable name.
+ * @returns JavaScript value represented by the GraphQL value AST.
+ * @example
+ * ```ts
+ * import { parseValue } from 'graphql/language';
+ * import { valueFromASTUntyped } from 'graphql/utilities';
  *
+ * const value = valueFromASTUntyped(parseValue('[1, 2, 3]'));
+ *
+ * value; // => [1, 2, 3]
+ * valueFromASTUntyped(parseValue('$name'), { name: 'Ada' }); // => 'Ada'
+ * ```
  */
 export declare function valueFromASTUntyped(
   valueNode: ValueNode,

package/utilities/valueFromASTUntyped.js

@@ -9,11 +9,13 @@ var _keyValMap = require('../jsutils/keyValMap.js');
 
 var _kinds = require('../language/kinds.js');
 
+/** @category Values */
+
 /**
  * Produces a JavaScript value given a GraphQL Value AST.
  *
- * Unlike `valueFromAST()`, no type is provided. The resulting JavaScript value
- * will reflect the provided GraphQL value AST.
+ * Because no GraphQL type is provided, the returned JavaScript value reflects
+ * the provided GraphQL value AST.
  *
  * | GraphQL Value        | JavaScript Value |
  * | -------------------- | ---------------- |
@@ -23,7 +25,19 @@ var _kinds = require('../language/kinds.js');
  * | String / Enum        | String           |
  * | Int / Float          | Number           |
  * | Null                 | null             |
+ * @param valueNode - GraphQL value AST node to convert.
+ * @param variables - Optional runtime variable values keyed by variable name.
+ * @returns JavaScript value represented by the GraphQL value AST.
+ * @example
+ * ```ts
+ * import { parseValue } from 'graphql/language';
+ * import { valueFromASTUntyped } from 'graphql/utilities';
+ *
+ * const value = valueFromASTUntyped(parseValue('[1, 2, 3]'));
  *
+ * value; // => [1, 2, 3]
+ * valueFromASTUntyped(parseValue('$name'), { name: 'Ada' }); // => 'Ada'
+ * ```
  */
 function valueFromASTUntyped(valueNode, variables) {
   switch (valueNode.kind) {