graphql 16.14.0 → 16.14.1

package/utilities/resolveSchemaCoordinate.d.ts

@@ -1,3 +1,4 @@
+/** @category Schema Coordinates */
 import type { SchemaCoordinateNode } from '../language/ast';
 import type { Source } from '../language/source';
 import type {
@@ -15,41 +16,50 @@ import type { GraphQLDirective } from '../type/directives';
 import type { GraphQLSchema } from '../type/schema';
 /**
  * A resolved schema element may be one of the following kinds:
+ *
+ * @internal
  */
 export interface ResolvedNamedType {
   readonly kind: 'NamedType';
   readonly type: GraphQLNamedType;
 }
+/** @internal */
 export interface ResolvedField {
   readonly kind: 'Field';
   readonly type: GraphQLObjectType | GraphQLInterfaceType;
   readonly field: GraphQLField<unknown, unknown>;
 }
+/** @internal */
 export interface ResolvedInputField {
   readonly kind: 'InputField';
   readonly type: GraphQLInputObjectType;
   readonly inputField: GraphQLInputField;
 }
+/** @internal */
 export interface ResolvedEnumValue {
   readonly kind: 'EnumValue';
   readonly type: GraphQLEnumType;
   readonly enumValue: GraphQLEnumValue;
 }
+/** @internal */
 export interface ResolvedFieldArgument {
   readonly kind: 'FieldArgument';
   readonly type: GraphQLObjectType | GraphQLInterfaceType;
   readonly field: GraphQLField<unknown, unknown>;
   readonly fieldArgument: GraphQLArgument;
 }
+/** @internal */
 export interface ResolvedDirective {
   readonly kind: 'Directive';
   readonly directive: GraphQLDirective;
 }
+/** @internal */
 export interface ResolvedDirectiveArgument {
   readonly kind: 'DirectiveArgument';
   readonly directive: GraphQLDirective;
   readonly directiveArgument: GraphQLArgument;
 }
+/** A schema element resolved from a schema coordinate. */
 export declare type ResolvedSchemaElement =
   | ResolvedNamedType
   | ResolvedField
@@ -66,6 +76,38 @@ export declare type ResolvedSchemaElement =
  * applicable) does not exist.
  *
  * https://spec.graphql.org/draft/#sec-Schema-Coordinates.Semantics
+ * @param schema - GraphQL schema to use.
+ * @param schemaCoordinate - The schema coordinate to resolve.
+ * @returns The schema element identified by the coordinate, or undefined if none exists.
+ * @example
+ * ```ts
+ * import { buildSchema, resolveSchemaCoordinate } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   directive @tag(name: String!) on FIELD_DEFINITION
+ *
+ *   input ReviewInput {
+ *     stars: Int!
+ *   }
+ *
+ *   enum Episode {
+ *     NEW_HOPE
+ *   }
+ *
+ *   type Query {
+ *     reviews(input: ReviewInput): [String] @tag(name: "reviews")
+ *   }
+ * `);
+ *
+ * resolveSchemaCoordinate(schema, 'Query').kind; // => 'NamedType'
+ * resolveSchemaCoordinate(schema, 'Query.reviews').kind; // => 'Field'
+ * resolveSchemaCoordinate(schema, 'Query.reviews(input:)').kind; // => 'FieldArgument'
+ * resolveSchemaCoordinate(schema, 'ReviewInput.stars').kind; // => 'InputField'
+ * resolveSchemaCoordinate(schema, 'Episode.NEW_HOPE').kind; // => 'EnumValue'
+ * resolveSchemaCoordinate(schema, '@tag').kind; // => 'Directive'
+ * resolveSchemaCoordinate(schema, '@tag(name:)').kind; // => 'DirectiveArgument'
+ * resolveSchemaCoordinate(schema, 'Query.missing'); // => undefined
+ * ```
  */
 export declare function resolveSchemaCoordinate(
   schema: GraphQLSchema,
@@ -73,6 +115,26 @@ export declare function resolveSchemaCoordinate(
 ): ResolvedSchemaElement | undefined;
 /**
  * Resolves schema coordinate from a parsed SchemaCoordinate node.
+ * @param schema - GraphQL schema to use.
+ * @param schemaCoordinate - The schema coordinate to resolve.
+ * @returns The schema element identified by the parsed coordinate, or undefined if none exists.
+ * @example
+ * ```ts
+ * import { parseSchemaCoordinate } from 'graphql/language';
+ * import { buildSchema, resolveASTSchemaCoordinate } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting(name: String): String
+ *   }
+ * `);
+ * const coordinate = parseSchemaCoordinate('Query.greeting(name:)');
+ * const resolved = resolveASTSchemaCoordinate(schema, coordinate);
+ *
+ * resolved.kind; // => 'FieldArgument'
+ * resolved.field.name; // => 'greeting'
+ * resolved.fieldArgument.name; // => 'name'
+ * ```
  */
 export declare function resolveASTSchemaCoordinate(
   schema: GraphQLSchema,

package/utilities/resolveSchemaCoordinate.js

@@ -14,6 +14,8 @@ var _parser = require('../language/parser.js');
 
 var _definition = require('../type/definition.js');
 
+/** @category Schema Coordinates */
+
 /**
  * A schema coordinate is resolved in the context of a GraphQL schema to
  * uniquely identify a schema element. It returns undefined if the schema
@@ -22,6 +24,38 @@ var _definition = require('../type/definition.js');
  * applicable) does not exist.
  *
  * https://spec.graphql.org/draft/#sec-Schema-Coordinates.Semantics
+ * @param schema - GraphQL schema to use.
+ * @param schemaCoordinate - The schema coordinate to resolve.
+ * @returns The schema element identified by the coordinate, or undefined if none exists.
+ * @example
+ * ```ts
+ * import { buildSchema, resolveSchemaCoordinate } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   directive @tag(name: String!) on FIELD_DEFINITION
+ *
+ *   input ReviewInput {
+ *     stars: Int!
+ *   }
+ *
+ *   enum Episode {
+ *     NEW_HOPE
+ *   }
+ *
+ *   type Query {
+ *     reviews(input: ReviewInput): [String] @tag(name: "reviews")
+ *   }
+ * `);
+ *
+ * resolveSchemaCoordinate(schema, 'Query').kind; // => 'NamedType'
+ * resolveSchemaCoordinate(schema, 'Query.reviews').kind; // => 'Field'
+ * resolveSchemaCoordinate(schema, 'Query.reviews(input:)').kind; // => 'FieldArgument'
+ * resolveSchemaCoordinate(schema, 'ReviewInput.stars').kind; // => 'InputField'
+ * resolveSchemaCoordinate(schema, 'Episode.NEW_HOPE').kind; // => 'EnumValue'
+ * resolveSchemaCoordinate(schema, '@tag').kind; // => 'Directive'
+ * resolveSchemaCoordinate(schema, '@tag(name:)').kind; // => 'DirectiveArgument'
+ * resolveSchemaCoordinate(schema, 'Query.missing'); // => undefined
+ * ```
  */
 function resolveSchemaCoordinate(schema, schemaCoordinate) {
   return resolveASTSchemaCoordinate(
@@ -31,6 +65,8 @@ function resolveSchemaCoordinate(schema, schemaCoordinate) {
 }
 /**
  * TypeCoordinate : Name
+ *
+ * @internal
  */
 
 function resolveTypeCoordinate(schema, schemaCoordinate) {
@@ -49,6 +85,8 @@ function resolveTypeCoordinate(schema, schemaCoordinate) {
 }
 /**
  * MemberCoordinate : Name . Name
+ *
+ * @internal
  */
 
 function resolveMemberCoordinate(schema, schemaCoordinate) {
@@ -126,6 +164,8 @@ function resolveMemberCoordinate(schema, schemaCoordinate) {
 }
 /**
  * ArgumentCoordinate : Name . Name ( Name : )
+ *
+ * @internal
  */
 
 function resolveArgumentCoordinate(schema, schemaCoordinate) {
@@ -185,6 +225,8 @@ function resolveArgumentCoordinate(schema, schemaCoordinate) {
 }
 /**
  * DirectiveCoordinate : \@ Name
+ *
+ * @internal
  */
 
 function resolveDirectiveCoordinate(schema, schemaCoordinate) {
@@ -203,6 +245,8 @@ function resolveDirectiveCoordinate(schema, schemaCoordinate) {
 }
 /**
  * DirectiveArgumentCoordinate : \@ Name ( Name : )
+ *
+ * @internal
  */
 
 function resolveDirectiveArgumentCoordinate(schema, schemaCoordinate) {
@@ -238,6 +282,26 @@ function resolveDirectiveArgumentCoordinate(schema, schemaCoordinate) {
 }
 /**
  * Resolves schema coordinate from a parsed SchemaCoordinate node.
+ * @param schema - GraphQL schema to use.
+ * @param schemaCoordinate - The schema coordinate to resolve.
+ * @returns The schema element identified by the parsed coordinate, or undefined if none exists.
+ * @example
+ * ```ts
+ * import { parseSchemaCoordinate } from 'graphql/language';
+ * import { buildSchema, resolveASTSchemaCoordinate } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting(name: String): String
+ *   }
+ * `);
+ * const coordinate = parseSchemaCoordinate('Query.greeting(name:)');
+ * const resolved = resolveASTSchemaCoordinate(schema, coordinate);
+ *
+ * resolved.kind; // => 'FieldArgument'
+ * resolved.field.name; // => 'greeting'
+ * resolved.fieldArgument.name; // => 'name'
+ * ```
  */
 
 function resolveASTSchemaCoordinate(schema, schemaCoordinate) {

package/utilities/resolveSchemaCoordinate.mjs

@@ -1,3 +1,4 @@
+/** @category Schema Coordinates */
 import { inspect } from '../jsutils/inspect.mjs';
 import { Kind } from '../language/kinds.mjs';
 import { parseSchemaCoordinate } from '../language/parser.mjs';
@@ -16,6 +17,38 @@ import {
  * applicable) does not exist.
  *
  * https://spec.graphql.org/draft/#sec-Schema-Coordinates.Semantics
+ * @param schema - GraphQL schema to use.
+ * @param schemaCoordinate - The schema coordinate to resolve.
+ * @returns The schema element identified by the coordinate, or undefined if none exists.
+ * @example
+ * ```ts
+ * import { buildSchema, resolveSchemaCoordinate } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   directive @tag(name: String!) on FIELD_DEFINITION
+ *
+ *   input ReviewInput {
+ *     stars: Int!
+ *   }
+ *
+ *   enum Episode {
+ *     NEW_HOPE
+ *   }
+ *
+ *   type Query {
+ *     reviews(input: ReviewInput): [String] @tag(name: "reviews")
+ *   }
+ * `);
+ *
+ * resolveSchemaCoordinate(schema, 'Query').kind; // => 'NamedType'
+ * resolveSchemaCoordinate(schema, 'Query.reviews').kind; // => 'Field'
+ * resolveSchemaCoordinate(schema, 'Query.reviews(input:)').kind; // => 'FieldArgument'
+ * resolveSchemaCoordinate(schema, 'ReviewInput.stars').kind; // => 'InputField'
+ * resolveSchemaCoordinate(schema, 'Episode.NEW_HOPE').kind; // => 'EnumValue'
+ * resolveSchemaCoordinate(schema, '@tag').kind; // => 'Directive'
+ * resolveSchemaCoordinate(schema, '@tag(name:)').kind; // => 'DirectiveArgument'
+ * resolveSchemaCoordinate(schema, 'Query.missing'); // => undefined
+ * ```
  */
 export function resolveSchemaCoordinate(schema, schemaCoordinate) {
   return resolveASTSchemaCoordinate(
@@ -25,6 +58,8 @@ export function resolveSchemaCoordinate(schema, schemaCoordinate) {
 }
 /**
  * TypeCoordinate : Name
+ *
+ * @internal
  */
 
 function resolveTypeCoordinate(schema, schemaCoordinate) {
@@ -43,6 +78,8 @@ function resolveTypeCoordinate(schema, schemaCoordinate) {
 }
 /**
  * MemberCoordinate : Name . Name
+ *
+ * @internal
  */
 
 function resolveMemberCoordinate(schema, schemaCoordinate) {
@@ -118,6 +155,8 @@ function resolveMemberCoordinate(schema, schemaCoordinate) {
 }
 /**
  * ArgumentCoordinate : Name . Name ( Name : )
+ *
+ * @internal
  */
 
 function resolveArgumentCoordinate(schema, schemaCoordinate) {
@@ -168,6 +207,8 @@ function resolveArgumentCoordinate(schema, schemaCoordinate) {
 }
 /**
  * DirectiveCoordinate : \@ Name
+ *
+ * @internal
  */
 
 function resolveDirectiveCoordinate(schema, schemaCoordinate) {
@@ -186,6 +227,8 @@ function resolveDirectiveCoordinate(schema, schemaCoordinate) {
 }
 /**
  * DirectiveArgumentCoordinate : \@ Name ( Name : )
+ *
+ * @internal
  */
 
 function resolveDirectiveArgumentCoordinate(schema, schemaCoordinate) {
@@ -221,6 +264,26 @@ function resolveDirectiveArgumentCoordinate(schema, schemaCoordinate) {
 }
 /**
  * Resolves schema coordinate from a parsed SchemaCoordinate node.
+ * @param schema - GraphQL schema to use.
+ * @param schemaCoordinate - The schema coordinate to resolve.
+ * @returns The schema element identified by the parsed coordinate, or undefined if none exists.
+ * @example
+ * ```ts
+ * import { parseSchemaCoordinate } from 'graphql/language';
+ * import { buildSchema, resolveASTSchemaCoordinate } from 'graphql/utilities';
+ *
+ * const schema = buildSchema(`
+ *   type Query {
+ *     greeting(name: String): String
+ *   }
+ * `);
+ * const coordinate = parseSchemaCoordinate('Query.greeting(name:)');
+ * const resolved = resolveASTSchemaCoordinate(schema, coordinate);
+ *
+ * resolved.kind; // => 'FieldArgument'
+ * resolved.field.name; // => 'greeting'
+ * resolved.fieldArgument.name; // => 'name'
+ * ```
  */
 
 export function resolveASTSchemaCoordinate(schema, schemaCoordinate) {

package/utilities/separateOperations.d.ts

@@ -1,3 +1,4 @@
+/** @category AST Utilities */
 import type { ObjMap } from '../jsutils/ObjMap';
 import type { DocumentNode } from '../language/ast';
 /**
@@ -5,6 +6,35 @@ import type { DocumentNode } from '../language/ast';
  * operations and fragments and returns a collection of AST documents each of
  * which contains a single operation as well the fragment definitions it
  * refers to.
+ * @param documentAST - The parsed GraphQL document AST.
+ * @returns A map of operation names to documents containing each operation and its referenced fragments.
+ * @example
+ * ```ts
+ * import { parse, print } from 'graphql/language';
+ * import { separateOperations } from 'graphql/utilities';
+ *
+ * const document = parse(`
+ *   query GetUser {
+ *     viewer {
+ *       ...UserFields
+ *     }
+ *   }
+ *
+ *   query GetStatus {
+ *     status
+ *   }
+ *
+ *   fragment UserFields on User {
+ *     id
+ *   }
+ * `);
+ *
+ * const separated = separateOperations(document);
+ *
+ * Object.keys(separated); // => ['GetUser', 'GetStatus']
+ * print(separated.GetUser); // matches /fragment UserFields/
+ * print(separated.GetStatus); // does not match /fragment UserFields/
+ * ```
  */
 export declare function separateOperations(
   documentAST: DocumentNode,

package/utilities/separateOperations.js

@@ -9,11 +9,42 @@ var _kinds = require('../language/kinds.js');
 
 var _visitor = require('../language/visitor.js');
 
+/** @category AST Utilities */
+
 /**
  * separateOperations accepts a single AST document which may contain many
  * operations and fragments and returns a collection of AST documents each of
  * which contains a single operation as well the fragment definitions it
  * refers to.
+ * @param documentAST - The parsed GraphQL document AST.
+ * @returns A map of operation names to documents containing each operation and its referenced fragments.
+ * @example
+ * ```ts
+ * import { parse, print } from 'graphql/language';
+ * import { separateOperations } from 'graphql/utilities';
+ *
+ * const document = parse(`
+ *   query GetUser {
+ *     viewer {
+ *       ...UserFields
+ *     }
+ *   }
+ *
+ *   query GetStatus {
+ *     status
+ *   }
+ *
+ *   fragment UserFields on User {
+ *     id
+ *   }
+ * `);
+ *
+ * const separated = separateOperations(document);
+ *
+ * Object.keys(separated); // => ['GetUser', 'GetStatus']
+ * print(separated.GetUser); // matches /fragment UserFields/
+ * print(separated.GetStatus); // does not match /fragment UserFields/
+ * ```
  */
 function separateOperations(documentAST) {
   const operations = [];

package/utilities/separateOperations.mjs

@@ -1,3 +1,4 @@
+/** @category AST Utilities */
 import { Kind } from '../language/kinds.mjs';
 import { visit } from '../language/visitor.mjs';
 /**
@@ -5,6 +6,35 @@ import { visit } from '../language/visitor.mjs';
  * operations and fragments and returns a collection of AST documents each of
  * which contains a single operation as well the fragment definitions it
  * refers to.
+ * @param documentAST - The parsed GraphQL document AST.
+ * @returns A map of operation names to documents containing each operation and its referenced fragments.
+ * @example
+ * ```ts
+ * import { parse, print } from 'graphql/language';
+ * import { separateOperations } from 'graphql/utilities';
+ *
+ * const document = parse(`
+ *   query GetUser {
+ *     viewer {
+ *       ...UserFields
+ *     }
+ *   }
+ *
+ *   query GetStatus {
+ *     status
+ *   }
+ *
+ *   fragment UserFields on User {
+ *     id
+ *   }
+ * `);
+ *
+ * const separated = separateOperations(document);
+ *
+ * Object.keys(separated); // => ['GetUser', 'GetStatus']
+ * print(separated.GetUser); // matches /fragment UserFields/
+ * print(separated.GetStatus); // does not match /fragment UserFields/
+ * ```
  */
 
 export function separateOperations(documentAST) {

package/utilities/stripIgnoredCharacters.d.ts

@@ -1,3 +1,4 @@
+/** @category AST Utilities */
 import { Source } from '../language/source';
 /**
  * Strips characters that are not significant to the validity or execution
@@ -18,9 +19,9 @@ import { Source } from '../language/source';
  * 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) {
@@ -38,9 +39,7 @@ import { Source } from '../language/source';
  * ```graphql
  * query SomeQuery($foo:String!$bar:String){someField(foo:$foo bar:$bar){a b{c d}}}
  * ```
- *
- * SDL example:
- *
+ * @example SDL source
  * ```graphql
  * """
  * Type description
@@ -58,5 +57,13 @@ import { Source } from '../language/source';
  * ```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 declare function stripIgnoredCharacters(source: string | Source): string;

package/utilities/stripIgnoredCharacters.js

@@ -13,6 +13,8 @@ var _source = require('../language/source.js');
 
 var _tokenKind = require('../language/tokenKind.js');
 
+/** @category AST Utilities */
+
 /**
  * Strips characters that are not significant to the validity or execution
  * of a GraphQL document:
@@ -32,9 +34,9 @@ var _tokenKind = require('../language/tokenKind.js');
  * 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) {
@@ -52,9 +54,7 @@ var _tokenKind = require('../language/tokenKind.js');
  * ```graphql
  * query SomeQuery($foo:String!$bar:String){someField(foo:$foo bar:$bar){a b{c d}}}
  * ```
- *
- * SDL example:
- *
+ * @example SDL source
  * ```graphql
  * """
  * Type description
@@ -72,6 +72,14 @@ var _tokenKind = require('../language/tokenKind.js');
  * ```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}'
+ * ```
  */
 function stripIgnoredCharacters(source) {
   const sourceObj = (0, _source.isSource)(source)
@@ -89,6 +97,8 @@ 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 = !(0, _lexer.isPunctuatorTokenKind)(

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