graphql 16.13.2 → 16.14.1

package/type/directives.d.ts

@@ -1,5 +1,9 @@
+/** @category Directives */
 import type { Maybe } from '../jsutils/Maybe';
-import type { DirectiveDefinitionNode } from '../language/ast';
+import type {
+  DirectiveDefinitionNode,
+  DirectiveExtensionNode,
+} from '../language/ast';
 import { DirectiveLocation } from '../language/directiveLocation';
 import type {
   GraphQLArgument,
@@ -7,14 +11,46 @@ import type {
 } from './definition';
 /**
  * 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 declare function isDirective(
   directive: unknown,
 ): directive is 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 declare function assertDirective(directive: unknown): GraphQLDirective;
 /**
  * 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
@@ -29,61 +65,208 @@ export interface GraphQLDirectiveExtensions {
  * behavior. Type system creators will usually not create these directly.
  */
 export declare class GraphQLDirective {
+  /** The GraphQL name for this schema element. */
   name: string;
+  /** Human-readable description for this schema element, if provided. */
   description: Maybe<string>;
+  /** Locations where this directive may be applied. */
   locations: ReadonlyArray<DirectiveLocation>;
+  /** Arguments accepted by this field or directive. */
   args: ReadonlyArray<GraphQLArgument>;
+  /** Whether this directive may appear more than once at the same location. */
   isRepeatable: boolean;
+  /** Reason this element is deprecated, if one was provided. */
+  deprecationReason: Maybe<string>;
+  /** Extension fields to include in the formatted result. */
   extensions: Readonly<GraphQLDirectiveExtensions>;
+  /** AST node from which this schema element was built, if available. */
   astNode: Maybe<DirectiveDefinitionNode>;
+  /** AST extension nodes applied to this schema element. */
+  extensionASTNodes: ReadonlyArray<DirectiveExtensionNode>;
+  /**
+   * 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: Readonly<GraphQLDirectiveConfig>);
+  /**
+   * Returns the value used by `Object.prototype.toString`.
+   * @returns The built-in string tag for this object.
+   */
   get [Symbol.toStringTag](): string;
+  /**
+   * 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(): GraphQLDirectiveNormalizedConfig;
+  /**
+   * 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(): string;
+  /**
+   * 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(): string;
 }
+/** Configuration used to construct a GraphQLDirective. */
 export interface GraphQLDirectiveConfig {
+  /** The GraphQL name for this schema element. */
   name: string;
+  /** Human-readable description for this schema element, if provided. */
   description?: Maybe<string>;
+  /** Locations where this directive may be applied. */
   locations: ReadonlyArray<DirectiveLocation>;
+  /** Arguments accepted by this field or directive. */
   args?: Maybe<GraphQLFieldConfigArgumentMap>;
+  /** Whether this directive may appear more than once at the same location. */
   isRepeatable?: Maybe<boolean>;
+  /** Reason this element is deprecated, if one was provided. */
+  deprecationReason?: Maybe<string>;
+  /** Extension fields to include in the formatted result. */
   extensions?: Maybe<Readonly<GraphQLDirectiveExtensions>>;
+  /** AST node from which this schema element was built, if available. */
   astNode?: Maybe<DirectiveDefinitionNode>;
+  /** AST extension nodes applied to this schema element. */
+  extensionASTNodes?: Maybe<ReadonlyArray<DirectiveExtensionNode>>;
 }
 interface GraphQLDirectiveNormalizedConfig extends GraphQLDirectiveConfig {
   args: GraphQLFieldConfigArgumentMap;
   isRepeatable: boolean;
   extensions: Readonly<GraphQLDirectiveExtensions>;
+  extensionASTNodes: ReadonlyArray<DirectiveExtensionNode>;
 }
-/**
- * Used to conditionally include fields or fragments.
- */
+/** Used to conditionally include fields or fragments. */
 export declare const GraphQLIncludeDirective: GraphQLDirective;
-/**
- * Used to conditionally skip (exclude) fields or fragments.
- */
+/** Used to conditionally skip (exclude) fields or fragments. */
 export declare const GraphQLSkipDirective: GraphQLDirective;
-/**
- * Constant string used for default reason for a deprecation.
- */
+/** Constant string used for default reason for a deprecation. */
 export declare 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 declare const GraphQLDeprecatedDirective: 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 declare const GraphQLSpecifiedByDirective: GraphQLDirective;
-/**
- * Used to indicate an Input Object is a OneOf Input Object.
- */
+/** Used to indicate an Input Object is a OneOf Input Object. */
 export declare const GraphQLOneOfDirective: GraphQLDirective;
+/** Full list of stable directives specified by GraphQL.js. */
+export declare const specifiedDirectives: ReadonlyArray<GraphQLDirective>;
 /**
- * The full list of specified directives.
+ * 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 declare const specifiedDirectives: ReadonlyArray<GraphQLDirective>;
 export declare function isSpecifiedDirective(
   directive: GraphQLDirective,
 ): boolean;

package/type/directives.js

@@ -34,12 +34,47 @@ var _definition = require('./definition.js');
 
 var _scalars = require('./scalars.js');
 
+/** @category Directives */
+
 /**
  * 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
+ * ```
  */
 function isDirective(directive) {
   return (0, _instanceOf.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
+ * ```
+ */
 
 function assertDirective(directive) {
   if (!isDirective(directive)) {
@@ -52,7 +87,6 @@ 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
@@ -65,8 +99,77 @@ function assertDirective(directive) {
  * behavior. Type system creators will usually not create these directly.
  */
 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 = (0, _assertName.assertName)(config.name);
     this.description = config.description;
@@ -76,8 +179,14 @@ class GraphQLDirective {
       _config$isRepeatable !== void 0
         ? _config$isRepeatable
         : false;
+    this.deprecationReason = config.deprecationReason;
     this.extensions = (0, _toObjMap.toObjMap)(config.extensions);
     this.astNode = config.astNode;
+    this.extensionASTNodes =
+      (_config$extensionASTN = config.extensionASTNodes) !== null &&
+      _config$extensionASTN !== void 0
+        ? _config$extensionASTN
+        : [];
     Array.isArray(config.locations) ||
       (0, _devAssert.devAssert)(
         false,
@@ -94,10 +203,37 @@ class GraphQLDirective {
       );
     this.args = (0, _definition.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 {
@@ -106,25 +242,59 @@ class GraphQLDirective {
       locations: this.locations,
       args: (0, _definition.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. */
 
 exports.GraphQLDirective = GraphQLDirective;
 
-/**
- * Used to conditionally include fields or fragments.
- */
+/** Used to conditionally include fields or fragments. */
 const GraphQLIncludeDirective = new GraphQLDirective({
   name: 'include',
   description:
@@ -141,9 +311,7 @@ const GraphQLIncludeDirective = new GraphQLDirective({
     },
   },
 });
-/**
- * Used to conditionally skip (exclude) fields or fragments.
- */
+/** Used to conditionally skip (exclude) fields or fragments. */
 
 exports.GraphQLIncludeDirective = GraphQLIncludeDirective;
 const GraphQLSkipDirective = new GraphQLDirective({
@@ -162,14 +330,14 @@ const GraphQLSkipDirective = new GraphQLDirective({
     },
   },
 });
-/**
- * Constant string used for default reason for a deprecation.
- */
+/** Constant string used for default reason for a deprecation. */
 
 exports.GraphQLSkipDirective = GraphQLSkipDirective;
 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`.
  */
 
 exports.DEFAULT_DEPRECATION_REASON = DEFAULT_DEPRECATION_REASON;
@@ -181,6 +349,7 @@ const GraphQLDeprecatedDirective = new GraphQLDirective({
     _directiveLocation.DirectiveLocation.ARGUMENT_DEFINITION,
     _directiveLocation.DirectiveLocation.INPUT_FIELD_DEFINITION,
     _directiveLocation.DirectiveLocation.ENUM_VALUE,
+    _directiveLocation.DirectiveLocation.DIRECTIVE_DEFINITION,
   ],
   args: {
     reason: {
@@ -191,9 +360,7 @@ 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. */
 
 exports.GraphQLDeprecatedDirective = GraphQLDeprecatedDirective;
 const GraphQLSpecifiedByDirective = new GraphQLDirective({
@@ -207,9 +374,7 @@ 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. */
 
 exports.GraphQLSpecifiedByDirective = GraphQLSpecifiedByDirective;
 const GraphQLOneOfDirective = new GraphQLDirective({
@@ -219,9 +384,7 @@ const GraphQLOneOfDirective = new GraphQLDirective({
   locations: [_directiveLocation.DirectiveLocation.INPUT_OBJECT],
   args: {},
 });
-/**
- * The full list of specified directives.
- */
+/** Full list of stable directives specified by GraphQL.js. */
 
 exports.GraphQLOneOfDirective = GraphQLOneOfDirective;
 const specifiedDirectives = Object.freeze([
@@ -231,6 +394,29 @@ 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
+ * ```
+ */
+
 exports.specifiedDirectives = specifiedDirectives;
 
 function isSpecifiedDirective(directive) {