graphql 16.13.2 → 16.14.1

package/type/directives.mjs

@@ -1,3 +1,4 @@
+/** @category Directives */
 import { devAssert } from '../jsutils/devAssert.mjs';
 import { inspect } from '../jsutils/inspect.mjs';
 import { instanceOf } from '../jsutils/instanceOf.mjs';
@@ -13,11 +14,45 @@ import {
 import { GraphQLBoolean, GraphQLString } from './scalars.mjs';
 /**
  * Test if the given value is a GraphQL directive.
+ * @param directive - Value to inspect.
+ * @returns True when the value is a GraphQLDirective.
+ * @example
+ * ```ts
+ * import { DirectiveLocation } from 'graphql/language';
+ * import { GraphQLDirective, GraphQLString, isDirective } from 'graphql/type';
+ *
+ * const upper = new GraphQLDirective({
+ *   name: 'upper',
+ *   locations: [DirectiveLocation.FIELD_DEFINITION],
+ * });
+ *
+ * isDirective(upper); // => true
+ * isDirective(GraphQLString); // => false
+ * ```
  */
 
 export function isDirective(directive) {
   return instanceOf(directive, GraphQLDirective);
 }
+/**
+ * Returns the value as a GraphQLDirective, or throws if it is not a directive.
+ * @param directive - Value to inspect.
+ * @returns The value typed as a GraphQLDirective.
+ * @example
+ * ```ts
+ * import { DirectiveLocation } from 'graphql/language';
+ * import { assertDirective, GraphQLDirective, GraphQLString } from 'graphql/type';
+ *
+ * const upper = new GraphQLDirective({
+ *   name: 'upper',
+ *   locations: [DirectiveLocation.FIELD_DEFINITION],
+ * });
+ *
+ * assertDirective(upper); // => upper
+ * assertDirective(GraphQLString); // throws an error
+ * ```
+ */
+
 export function assertDirective(directive) {
   if (!isDirective(directive)) {
     throw new Error(
@@ -29,7 +64,6 @@ export function assertDirective(directive) {
 }
 /**
  * Custom extensions
- *
  * @remarks
  * Use a unique identifier name for your extension, for example the name of
  * your library or project. Do not use a shortened identifier as this increases
@@ -42,8 +76,77 @@ export function assertDirective(directive) {
  * behavior. Type system creators will usually not create these directly.
  */
 export class GraphQLDirective {
+  /** The GraphQL name for this schema element. */
+
+  /** Human-readable description for this schema element, if provided. */
+
+  /** Locations where this directive may be applied. */
+
+  /** Arguments accepted by this field or directive. */
+
+  /** Whether this directive may appear more than once at the same location. */
+
+  /** Reason this element is deprecated, if one was provided. */
+
+  /** Extension fields to include in the formatted result. */
+
+  /** AST node from which this schema element was built, if available. */
+
+  /** AST extension nodes applied to this schema element. */
+
+  /**
+   * Creates a GraphQLDirective instance.
+   * @param config - Configuration describing this object.
+   * @example
+   * ```ts
+   * import { DirectiveLocation, parse } from 'graphql/language';
+   * import {
+   *   GraphQLBoolean,
+   *   GraphQLDirective,
+   *   GraphQLInt,
+   *   GraphQLNonNull,
+   * } from 'graphql/type';
+   *
+   * const document = parse(`
+   *   directive @cacheControl(maxAge: Int) repeatable on FIELD_DEFINITION
+   *   extend directive @cacheControl(maxAge: Int) on FIELD_DEFINITION
+   * `);
+   * const definition = document.definitions[0];
+   *
+   * const cacheControl = new GraphQLDirective({
+   *   name: 'cacheControl',
+   *   description: 'Controls HTTP cache hints for a field.',
+   *   locations: [DirectiveLocation.FIELD_DEFINITION],
+   *   args: {
+   *     inheritMaxAge: {
+   *       description: 'Inherit the parent cache hint.',
+   *       type: new GraphQLNonNull(GraphQLBoolean),
+   *       defaultValue: false,
+   *       deprecationReason: 'Use maxAge instead.',
+   *       extensions: { scope: 'cache' },
+   *     },
+   *     maxAge: {
+   *       type: GraphQLInt,
+   *       astNode: definition.arguments[0],
+   *     },
+   *   },
+   *   isRepeatable: true,
+   *   deprecationReason: 'Use @cache instead.',
+   *   extensions: { scope: 'cache' },
+   *   astNode: definition,
+   *   extensionASTNodes: [ document.definitions[1] ],
+   * });
+   *
+   * cacheControl.name; // => 'cacheControl'
+   * cacheControl.description; // => 'Controls HTTP cache hints for a field.'
+   * cacheControl.args[0].name; // => 'inheritMaxAge'
+   * cacheControl.args[0].defaultValue; // => false
+   * cacheControl.isRepeatable; // => true
+   * cacheControl.extensions; // => { scope: 'cache' }
+   * ```
+   */
   constructor(config) {
-    var _config$isRepeatable, _config$args;
+    var _config$isRepeatable, _config$extensionASTN, _config$args;
 
     this.name = assertName(config.name);
     this.description = config.description;
@@ -53,8 +156,14 @@ export class GraphQLDirective {
       _config$isRepeatable !== void 0
         ? _config$isRepeatable
         : false;
+    this.deprecationReason = config.deprecationReason;
     this.extensions = toObjMap(config.extensions);
     this.astNode = config.astNode;
+    this.extensionASTNodes =
+      (_config$extensionASTN = config.extensionASTNodes) !== null &&
+      _config$extensionASTN !== void 0
+        ? _config$extensionASTN
+        : [];
     Array.isArray(config.locations) ||
       devAssert(false, `@${config.name} locations must be an Array.`);
     const args =
@@ -68,10 +177,37 @@ export class GraphQLDirective {
       );
     this.args = defineArguments(args);
   }
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
 
   get [Symbol.toStringTag]() {
     return 'GraphQLDirective';
   }
+  /**
+   * Returns a normalized configuration object for this object.
+   * @returns A configuration object that can be used to recreate this object.
+   * @example
+   * ```ts
+   * import { DirectiveLocation } from 'graphql/language';
+   * import { GraphQLDirective, GraphQLString } from 'graphql/type';
+   *
+   * const tag = new GraphQLDirective({
+   *   name: 'tag',
+   *   locations: [DirectiveLocation.FIELD_DEFINITION],
+   *   args: {
+   *     name: { type: GraphQLString },
+   *   },
+   * });
+   *
+   * const config = tag.toConfig();
+   * const tagCopy = new GraphQLDirective(config);
+   *
+   * config.args.name.type; // => GraphQLString
+   * tagCopy.args[0].name; // => 'name'
+   * ```
+   */
 
   toConfig() {
     return {
@@ -80,23 +216,57 @@ export class GraphQLDirective {
       locations: this.locations,
       args: argsToArgsConfig(this.args),
       isRepeatable: this.isRepeatable,
+      deprecationReason: this.deprecationReason,
       extensions: this.extensions,
       astNode: this.astNode,
+      extensionASTNodes: this.extensionASTNodes,
     };
   }
+  /**
+   * Returns the schema coordinate identifying this directive.
+   * @returns The directive schema coordinate.
+   * @example
+   * ```ts
+   * import { DirectiveLocation } from 'graphql/language';
+   * import { GraphQLDirective } from 'graphql/type';
+   *
+   * const tag = new GraphQLDirective({
+   *   name: 'tag',
+   *   locations: [DirectiveLocation.FIELD_DEFINITION],
+   * });
+   *
+   * tag.toString(); // => '@tag'
+   * ```
+   */
 
   toString() {
     return '@' + this.name;
   }
+  /**
+   * Returns the JSON representation used when this object is serialized.
+   * @returns The JSON-serializable representation.
+   * @example
+   * ```ts
+   * import { DirectiveLocation } from 'graphql/language';
+   * import { GraphQLDirective } from 'graphql/type';
+   *
+   * const tag = new GraphQLDirective({
+   *   name: 'tag',
+   *   locations: [DirectiveLocation.FIELD_DEFINITION],
+   * });
+   *
+   * tag.toJSON(); // => '@tag'
+   * JSON.stringify({ directive: tag }); // => '{"directive":"@tag"}'
+   * ```
+   */
 
   toJSON() {
     return this.toString();
   }
 }
+/** Configuration used to construct a GraphQLDirective. */
 
-/**
- * Used to conditionally include fields or fragments.
- */
+/** Used to conditionally include fields or fragments. */
 export const GraphQLIncludeDirective = new GraphQLDirective({
   name: 'include',
   description:
@@ -113,9 +283,7 @@ export const GraphQLIncludeDirective = new GraphQLDirective({
     },
   },
 });
-/**
- * Used to conditionally skip (exclude) fields or fragments.
- */
+/** Used to conditionally skip (exclude) fields or fragments. */
 
 export const GraphQLSkipDirective = new GraphQLDirective({
   name: 'skip',
@@ -133,13 +301,13 @@ export const GraphQLSkipDirective = new GraphQLDirective({
     },
   },
 });
-/**
- * Constant string used for default reason for a deprecation.
- */
+/** Constant string used for default reason for a deprecation. */
 
 export const DEFAULT_DEPRECATION_REASON = 'No longer supported';
 /**
  * Used to declare element of a GraphQL schema as deprecated.
+ *
+ * The optional `reason` argument defaults to `DEFAULT_DEPRECATION_REASON`.
  */
 
 export const GraphQLDeprecatedDirective = new GraphQLDirective({
@@ -150,6 +318,7 @@ export const GraphQLDeprecatedDirective = new GraphQLDirective({
     DirectiveLocation.ARGUMENT_DEFINITION,
     DirectiveLocation.INPUT_FIELD_DEFINITION,
     DirectiveLocation.ENUM_VALUE,
+    DirectiveLocation.DIRECTIVE_DEFINITION,
   ],
   args: {
     reason: {
@@ -160,9 +329,7 @@ export const GraphQLDeprecatedDirective = new GraphQLDirective({
     },
   },
 });
-/**
- * Used to provide a URL for specifying the behavior of custom scalar definitions.
- */
+/** Used to provide a URL for specifying the behavior of custom scalar definitions. */
 
 export const GraphQLSpecifiedByDirective = new GraphQLDirective({
   name: 'specifiedBy',
@@ -175,9 +342,7 @@ export const GraphQLSpecifiedByDirective = new GraphQLDirective({
     },
   },
 });
-/**
- * Used to indicate an Input Object is a OneOf Input Object.
- */
+/** Used to indicate an Input Object is a OneOf Input Object. */
 
 export const GraphQLOneOfDirective = new GraphQLDirective({
   name: 'oneOf',
@@ -186,9 +351,7 @@ export const GraphQLOneOfDirective = new GraphQLDirective({
   locations: [DirectiveLocation.INPUT_OBJECT],
   args: {},
 });
-/**
- * The full list of specified directives.
- */
+/** Full list of stable directives specified by GraphQL.js. */
 
 export const specifiedDirectives = Object.freeze([
   GraphQLIncludeDirective,
@@ -197,6 +360,29 @@ export const specifiedDirectives = Object.freeze([
   GraphQLSpecifiedByDirective,
   GraphQLOneOfDirective,
 ]);
+/**
+ * Returns true when the directive is one of the directives specified by GraphQL.
+ * @param directive - Directive to inspect.
+ * @returns True when the directive is specified by GraphQL.
+ * @example
+ * ```ts
+ * import {
+ *   GraphQLDirective,
+ *   GraphQLIncludeDirective,
+ *   isSpecifiedDirective,
+ * } from 'graphql/type';
+ * import { DirectiveLocation } from 'graphql/language';
+ *
+ * const customDirective = new GraphQLDirective({
+ *   name: 'auth',
+ *   locations: [DirectiveLocation.FIELD_DEFINITION],
+ * });
+ *
+ * isSpecifiedDirective(GraphQLIncludeDirective); // => true
+ * isSpecifiedDirective(customDirective); // => false
+ * ```
+ */
+
 export function isSpecifiedDirective(directive) {
   return specifiedDirectives.some(({ name }) => name === directive.name);
 }

package/type/index.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Create and inspect GraphQL type definitions and schemas.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ */
 export type { Path as ResponsePath } from '../jsutils/Path';
 export { isSchema, assertSchema, GraphQLSchema } from './schema';
 export type { GraphQLSchemaConfig, GraphQLSchemaExtensions } from './schema';

package/type/index.mjs

@@ -1,3 +1,9 @@
+/**
+ * Create and inspect GraphQL type definitions and schemas.
+ *
+ * These exports are also available from the root `graphql` package.
+ * @packageDocumentation
+ */
 export {
   // Predicate
   isSchema, // Assertion

package/type/introspection.d.ts

@@ -1,30 +1,66 @@
+/** @category Introspection */
 import type { GraphQLField, GraphQLNamedType } from './definition';
 import { GraphQLEnumType, GraphQLObjectType } from './definition';
+/** The introspection type describing a GraphQL schema. */
 export declare const __Schema: GraphQLObjectType;
+/** The introspection type describing a GraphQL directive. */
 export declare const __Directive: GraphQLObjectType;
+/** The introspection enum describing directive locations. */
 export declare const __DirectiveLocation: GraphQLEnumType;
+/** The introspection type describing GraphQL types. */
 export declare const __Type: GraphQLObjectType;
+/** The introspection type describing object and interface fields. */
 export declare const __Field: GraphQLObjectType;
+/** The introspection type describing arguments and input fields. */
 export declare const __InputValue: GraphQLObjectType;
+/** The introspection type describing enum values. */
 export declare const __EnumValue: GraphQLObjectType;
+/**
+ * The introspection enum describing the different kinds of GraphQL types.
+ * @category Introspection
+ */
 declare enum TypeKind {
+  /** A scalar type. */
   SCALAR = 'SCALAR',
+  /** An object type. */
   OBJECT = 'OBJECT',
+  /** An interface type. */
   INTERFACE = 'INTERFACE',
+  /** A union type. */
   UNION = 'UNION',
+  /** An enum type. */
   ENUM = 'ENUM',
+  /** An input object type. */
   INPUT_OBJECT = 'INPUT_OBJECT',
+  /** A list wrapper type. */
   LIST = 'LIST',
+  /** A non-null wrapper type. */
   NON_NULL = 'NON_NULL',
 }
 export { TypeKind };
+/** The introspection enum describing GraphQL type kinds. */
 export declare const __TypeKind: GraphQLEnumType;
 /**
  * Note that these are GraphQLField and not GraphQLFieldConfig,
  * so the format for args is different.
  */
 export declare const SchemaMetaFieldDef: GraphQLField<unknown, unknown>;
+/** The `__type` meta field definition used by introspection. */
 export declare const TypeMetaFieldDef: GraphQLField<unknown, unknown>;
+/** The `__typename` meta field definition used by execution and introspection. */
 export declare const TypeNameMetaFieldDef: GraphQLField<unknown, unknown>;
+/** All introspection types defined by the GraphQL specification. */
 export declare const introspectionTypes: ReadonlyArray<GraphQLNamedType>;
+/**
+ * Returns true when the type is one of the built-in introspection types.
+ * @param type - The GraphQL type to inspect.
+ * @returns True when the type is one of the built-in introspection types.
+ * @example
+ * ```ts
+ * import { GraphQLString, isIntrospectionType, __Type } from 'graphql/type';
+ *
+ * isIntrospectionType(__Type); // => true
+ * isIntrospectionType(GraphQLString); // => false
+ * ```
+ */
 export declare function isIntrospectionType(type: GraphQLNamedType): boolean;

package/type/introspection.js

@@ -33,6 +33,9 @@ var _definition = require('./definition.js');
 
 var _scalars = require('./scalars.js');
 
+/** @category Introspection */
+
+/** The introspection type describing a GraphQL schema. */
 const __Schema = new _definition.GraphQLObjectType({
   name: '__Schema',
   description:
@@ -76,10 +79,22 @@ const __Schema = new _definition.GraphQLObjectType({
           new _definition.GraphQLNonNull(__Directive),
         ),
       ),
-      resolve: (schema) => schema.getDirectives(),
+      args: {
+        includeDeprecated: {
+          type: new _definition.GraphQLNonNull(_scalars.GraphQLBoolean),
+          defaultValue: false,
+        },
+      },
+      resolve: (schema, { includeDeprecated }) =>
+        includeDeprecated
+          ? schema.getDirectives()
+          : schema
+              .getDirectives()
+              .filter((directive) => directive.deprecationReason == null),
     },
   }),
 });
+/** The introspection type describing a GraphQL directive. */
 
 exports.__Schema = __Schema;
 
@@ -127,8 +142,17 @@ const __Directive = new _definition.GraphQLObjectType({
           : field.args.filter((arg) => arg.deprecationReason == null);
       },
     },
+    isDeprecated: {
+      type: new _definition.GraphQLNonNull(_scalars.GraphQLBoolean),
+      resolve: (directive) => directive.deprecationReason != null,
+    },
+    deprecationReason: {
+      type: _scalars.GraphQLString,
+      resolve: (directive) => directive.deprecationReason,
+    },
   }),
 });
+/** The introspection enum describing directive locations. */
 
 exports.__Directive = __Directive;
 
@@ -213,8 +237,13 @@ const __DirectiveLocation = new _definition.GraphQLEnumType({
       value: _directiveLocation.DirectiveLocation.INPUT_FIELD_DEFINITION,
       description: 'Location adjacent to an input object field definition.',
     },
+    DIRECTIVE_DEFINITION: {
+      value: _directiveLocation.DirectiveLocation.DIRECTIVE_DEFINITION,
+      description: 'Location adjacent to a directive definition.',
+    },
   },
 });
+/** The introspection type describing GraphQL types. */
 
 exports.__DirectiveLocation = __DirectiveLocation;
 
@@ -383,6 +412,7 @@ const __Type = new _definition.GraphQLObjectType({
     },
   }),
 });
+/** The introspection type describing object and interface fields. */
 
 exports.__Type = __Type;
 
@@ -432,6 +462,7 @@ const __Field = new _definition.GraphQLObjectType({
     },
   }),
 });
+/** The introspection type describing arguments and input fields. */
 
 exports.__Field = __Field;
 
@@ -473,6 +504,7 @@ const __InputValue = new _definition.GraphQLObjectType({
     },
   }),
 });
+/** The introspection type describing enum values. */
 
 exports.__InputValue = __InputValue;
 
@@ -499,6 +531,10 @@ const __EnumValue = new _definition.GraphQLObjectType({
     },
   }),
 });
+/**
+ * The introspection enum describing the different kinds of GraphQL types.
+ * @category Introspection
+ */
 
 exports.__EnumValue = __EnumValue;
 var TypeKind;
@@ -515,6 +551,7 @@ exports.TypeKind = TypeKind;
   TypeKind['NON_NULL'] = 'NON_NULL';
 })(TypeKind || (exports.TypeKind = TypeKind = {}));
 
+/** The introspection enum describing GraphQL type kinds. */
 const __TypeKind = new _definition.GraphQLEnumType({
   name: '__TypeKind',
   description: 'An enum describing what kind of type a given `__Type` is.',
@@ -575,6 +612,8 @@ const SchemaMetaFieldDef = {
   extensions: Object.create(null),
   astNode: undefined,
 };
+/** The `__type` meta field definition used by introspection. */
+
 exports.SchemaMetaFieldDef = SchemaMetaFieldDef;
 const TypeMetaFieldDef = {
   name: '__type',
@@ -596,6 +635,8 @@ const TypeMetaFieldDef = {
   extensions: Object.create(null),
   astNode: undefined,
 };
+/** The `__typename` meta field definition used by execution and introspection. */
+
 exports.TypeMetaFieldDef = TypeMetaFieldDef;
 const TypeNameMetaFieldDef = {
   name: '__typename',
@@ -607,6 +648,8 @@ const TypeNameMetaFieldDef = {
   extensions: Object.create(null),
   astNode: undefined,
 };
+/** All introspection types defined by the GraphQL specification. */
+
 exports.TypeNameMetaFieldDef = TypeNameMetaFieldDef;
 const introspectionTypes = Object.freeze([
   __Schema,
@@ -618,6 +661,19 @@ const introspectionTypes = Object.freeze([
   __EnumValue,
   __TypeKind,
 ]);
+/**
+ * Returns true when the type is one of the built-in introspection types.
+ * @param type - The GraphQL type to inspect.
+ * @returns True when the type is one of the built-in introspection types.
+ * @example
+ * ```ts
+ * import { GraphQLString, isIntrospectionType, __Type } from 'graphql/type';
+ *
+ * isIntrospectionType(__Type); // => true
+ * isIntrospectionType(GraphQLString); // => false
+ * ```
+ */
+
 exports.introspectionTypes = introspectionTypes;
 
 function isIntrospectionType(type) {