graphql 14.4.2 → 14.5.3

package/subscription/subscribe.d.ts

@@ -0,0 +1,86 @@
+import Maybe from '../tsutils/Maybe';
+import { DocumentNode } from '../language/ast';
+import {
+  ExecutionResult,
+  ExecutionResultDataDefault,
+} from '../execution/execute';
+import { GraphQLSchema } from '../type/schema';
+import { GraphQLFieldResolver } from '../type/definition';
+
+export interface SubscriptionArgs {
+  schema: GraphQLSchema;
+  document: DocumentNode;
+  rootValue?: any;
+  contextValue?: any;
+  variableValues?: Maybe<Record<string, any>>;
+  operationName?: Maybe<string>;
+  fieldResolver?: Maybe<GraphQLFieldResolver<any, any>>;
+  subscribeFieldResolver?: Maybe<GraphQLFieldResolver<any, any>>;
+}
+
+/**
+ * Implements the "Subscribe" algorithm described in the GraphQL specification.
+ *
+ * Returns a Promise which resolves to either an AsyncIterator (if successful)
+ * or an ExecutionResult (client error). The promise will be rejected if a
+ * server error occurs.
+ *
+ * If the client-provided arguments to this function do not result in a
+ * compliant subscription, a GraphQL Response (ExecutionResult) with
+ * descriptive errors and no data will be returned.
+ *
+ * If the the source stream could not be created due to faulty subscription
+ * resolver logic or underlying systems, the promise will resolve to a single
+ * ExecutionResult containing `errors` and no `data`.
+ *
+ * If the operation succeeded, the promise resolves to an AsyncIterator, which
+ * yields a stream of ExecutionResults representing the response stream.
+ *
+ * Accepts either an object with named arguments, or individual arguments.
+ */
+export function subscribe<TData = ExecutionResultDataDefault>(
+  args: SubscriptionArgs,
+): Promise<
+  AsyncIterableIterator<ExecutionResult<TData>> | ExecutionResult<TData>
+>;
+
+export function subscribe<TData = ExecutionResultDataDefault>(
+  schema: GraphQLSchema,
+  document: DocumentNode,
+  rootValue?: any,
+  contextValue?: any,
+  variableValues?: Maybe<{ [key: string]: any }>,
+  operationName?: Maybe<string>,
+  fieldResolver?: Maybe<GraphQLFieldResolver<any, any>>,
+  subscribeFieldResolver?: Maybe<GraphQLFieldResolver<any, any>>,
+): Promise<
+  AsyncIterableIterator<ExecutionResult<TData>> | ExecutionResult<TData>
+>;
+
+/**
+ * Implements the "CreateSourceEventStream" algorithm described in the
+ * GraphQL specification, resolving the subscription source event stream.
+ *
+ * Returns a Promise<AsyncIterable>.
+ *
+ * If the client-provided invalid arguments, the source stream could not be
+ * created, or the resolver did not return an AsyncIterable, this function will
+ * will throw an error, which should be caught and handled by the caller.
+ *
+ * A Source Event Stream represents a sequence of events, each of which triggers
+ * a GraphQL execution for that event.
+ *
+ * This may be useful when hosting the stateful subscription service in a
+ * different process or machine than the stateless GraphQL execution engine,
+ * or otherwise separating these two steps. For more on this, see the
+ * "Supporting Subscriptions at Scale" information in the GraphQL specification.
+ */
+export function createSourceEventStream<TData = ExecutionResultDataDefault>(
+  schema: GraphQLSchema,
+  document: DocumentNode,
+  rootValue?: any,
+  contextValue?: any,
+  variableValues?: { [key: string]: any },
+  operationName?: Maybe<string>,
+  fieldResolver?: Maybe<GraphQLFieldResolver<any, any>>,
+): Promise<AsyncIterable<any> | ExecutionResult<TData>>;

package/subscription/subscribe.js

@@ -10,16 +10,18 @@ var _iterall = require("iterall");
 
 var _inspect = _interopRequireDefault(require("../jsutils/inspect"));
 
+var _Path = require("../jsutils/Path");
+
 var _GraphQLError = require("../error/GraphQLError");
 
 var _locatedError = require("../error/locatedError");
 
 var _execute = require("../execution/execute");
 
-var _mapAsyncIterator = _interopRequireDefault(require("./mapAsyncIterator"));
-
 var _getOperationRootType = require("../utilities/getOperationRootType");
 
+var _mapAsyncIterator = _interopRequireDefault(require("./mapAsyncIterator"));
+
 function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { default: obj }; }
 
 function subscribe(argsOrSchema, document, rootValue, contextValue, variableValues, operationName, fieldResolver, subscribeFieldResolver) {
@@ -79,17 +81,27 @@ function subscribeImpl(args) {
     return (// Note: Flow can't refine isAsyncIterable, so explicit casts are used.
       (0, _iterall.isAsyncIterable)(resultOrStream) ? (0, _mapAsyncIterator.default)(resultOrStream, mapSourceToResponse, reportGraphQLError) : resultOrStream
     );
-  }, reportGraphQLError);
+  });
 }
 /**
  * Implements the "CreateSourceEventStream" algorithm described in the
  * GraphQL specification, resolving the subscription source event stream.
  *
- * Returns a Promise<AsyncIterable>.
+ * Returns a Promise which resolves to either an AsyncIterable (if successful)
+ * or an ExecutionResult (error). The promise will be rejected if the schema or
+ * other arguments to this function are invalid, or if the resolved event stream
+ * is not an async iterable.
+ *
+ * If the client-provided arguments to this function do not result in a
+ * compliant subscription, a GraphQL Response (ExecutionResult) with
+ * descriptive errors and no data will be returned.
  *
- * If the client-provided invalid arguments, the source stream could not be
- * created, or the resolver did not return an AsyncIterable, this function will
- * will throw an error, which should be caught and handled by the caller.
+ * If the the source stream could not be created due to faulty subscription
+ * resolver logic or underlying systems, the promise will resolve to a single
+ * ExecutionResult containing `errors` and no `data`.
+ *
+ * If the operation succeeded, the promise resolves to the AsyncIterable for the
+ * event stream returned by the resolver.
  *
  * A Source Event Stream represents a sequence of events, each of which triggers
  * a GraphQL execution for that event.
@@ -133,7 +145,7 @@ function createSourceEventStream(schema, document, rootValue, contextValue, vari
 
 
     var resolveFn = fieldDef.subscribe || exeContext.fieldResolver;
-    var path = (0, _execute.addPath)(undefined, responseName);
+    var path = (0, _Path.addPath)(undefined, responseName);
     var info = (0, _execute.buildResolveInfo)(exeContext, fieldDef, fieldNodes, type, path); // resolveFieldValueOrError implements the "ResolveFieldEventStream"
     // algorithm from GraphQL specification. It differs from
     // "ResolveFieldValue" due to providing a different `resolveFn`.
@@ -143,7 +155,9 @@ function createSourceEventStream(schema, document, rootValue, contextValue, vari
     return Promise.resolve(result).then(function (eventStream) {
       // If eventStream is an Error, rethrow a located error.
       if (eventStream instanceof Error) {
-        throw (0, _locatedError.locatedError)(eventStream, fieldNodes, (0, _execute.responsePathAsArray)(path));
+        return {
+          errors: [(0, _locatedError.locatedError)(eventStream, fieldNodes, (0, _Path.pathToArray)(path))]
+        };
       } // Assert field returned an event stream, otherwise yield an error.
 
 
@@ -155,6 +169,11 @@ function createSourceEventStream(schema, document, rootValue, contextValue, vari
       throw new Error('Subscription field must return Async Iterable. Received: ' + (0, _inspect.default)(eventStream));
     });
   } catch (error) {
-    return Promise.reject(error);
+    // As with reportGraphQLError above, if the error is a GraphQLError, report
+    // it as an ExecutionResult; otherwise treat it as a system-class error and
+    // re-throw it.
+    return error instanceof _GraphQLError.GraphQLError ? Promise.resolve({
+      errors: [error]
+    }) : Promise.reject(error);
   }
 }

package/subscription/subscribe.js.flow

@@ -1,12 +1,17 @@
 // @flow strict
 
 import { isAsyncIterable } from 'iterall';
+
 import inspect from '../jsutils/inspect';
+import { addPath, pathToArray } from '../jsutils/Path';
+
 import { GraphQLError } from '../error/GraphQLError';
 import { locatedError } from '../error/locatedError';
+
+import { type DocumentNode } from '../language/ast';
+
 import {
   type ExecutionResult,
-  addPath,
   assertValidExecutionArguments,
   buildExecutionContext,
   buildResolveInfo,
@@ -14,15 +19,15 @@ import {
   execute,
   getFieldDef,
   resolveFieldValueOrError,
-  responsePathAsArray,
 } from '../execution/execute';
-import { type GraphQLSchema } from '../type/schema';
-import mapAsyncIterator from './mapAsyncIterator';
 
-import { type DocumentNode } from '../language/ast';
+import { type GraphQLSchema } from '../type/schema';
 import { type GraphQLFieldResolver } from '../type/definition';
+
 import { getOperationRootType } from '../utilities/getOperationRootType';
 
+import mapAsyncIterator from './mapAsyncIterator';
+
 export type SubscriptionArgs = {|
   schema: GraphQLSchema,
   document: DocumentNode,
@@ -38,8 +43,9 @@ export type SubscriptionArgs = {|
  * Implements the "Subscribe" algorithm described in the GraphQL specification.
  *
  * Returns a Promise which resolves to either an AsyncIterator (if successful)
- * or an ExecutionResult (client error). The promise will be rejected if a
- * server error occurs.
+ * or an ExecutionResult (error). The promise will be rejected if the schema or
+ * other arguments to this function are invalid, or if the resolved event stream
+ * is not an async iterable.
  *
  * If the client-provided arguments to this function do not result in a
  * compliant subscription, a GraphQL Response (ExecutionResult) with
@@ -150,17 +156,15 @@ function subscribeImpl(
 
   // Resolve the Source Stream, then map every source value to a
   // ExecutionResult value as described above.
-  return sourcePromise.then(
-    resultOrStream =>
-      // Note: Flow can't refine isAsyncIterable, so explicit casts are used.
-      isAsyncIterable(resultOrStream)
-        ? mapAsyncIterator(
-            ((resultOrStream: any): AsyncIterable<mixed>),
-            mapSourceToResponse,
-            reportGraphQLError,
-          )
-        : ((resultOrStream: any): ExecutionResult),
-    reportGraphQLError,
+  return sourcePromise.then(resultOrStream =>
+    // Note: Flow can't refine isAsyncIterable, so explicit casts are used.
+    isAsyncIterable(resultOrStream)
+      ? mapAsyncIterator(
+          ((resultOrStream: any): AsyncIterable<mixed>),
+          mapSourceToResponse,
+          reportGraphQLError,
+        )
+      : ((resultOrStream: any): ExecutionResult),
   );
 }
 
@@ -168,11 +172,21 @@ function subscribeImpl(
  * Implements the "CreateSourceEventStream" algorithm described in the
  * GraphQL specification, resolving the subscription source event stream.
  *
- * Returns a Promise<AsyncIterable>.
+ * Returns a Promise which resolves to either an AsyncIterable (if successful)
+ * or an ExecutionResult (error). The promise will be rejected if the schema or
+ * other arguments to this function are invalid, or if the resolved event stream
+ * is not an async iterable.
+ *
+ * If the client-provided arguments to this function do not result in a
+ * compliant subscription, a GraphQL Response (ExecutionResult) with
+ * descriptive errors and no data will be returned.
+ *
+ * If the the source stream could not be created due to faulty subscription
+ * resolver logic or underlying systems, the promise will resolve to a single
+ * ExecutionResult containing `errors` and no `data`.
  *
- * If the client-provided invalid arguments, the source stream could not be
- * created, or the resolver did not return an AsyncIterable, this function will
- * will throw an error, which should be caught and handled by the caller.
+ * If the operation succeeded, the promise resolves to the AsyncIterable for the
+ * event stream returned by the resolver.
  *
  * A Source Event Stream represents a sequence of events, each of which triggers
  * a GraphQL execution for that event.
@@ -259,7 +273,9 @@ export function createSourceEventStream(
     return Promise.resolve(result).then(eventStream => {
       // If eventStream is an Error, rethrow a located error.
       if (eventStream instanceof Error) {
-        throw locatedError(eventStream, fieldNodes, responsePathAsArray(path));
+        return {
+          errors: [locatedError(eventStream, fieldNodes, pathToArray(path))],
+        };
       }
 
       // Assert field returned an event stream, otherwise yield an error.
@@ -273,6 +289,11 @@ export function createSourceEventStream(
       );
     });
   } catch (error) {
-    return Promise.reject(error);
+    // As with reportGraphQLError above, if the error is a GraphQLError, report
+    // it as an ExecutionResult; otherwise treat it as a system-class error and
+    // re-throw it.
+    return error instanceof GraphQLError
+      ? Promise.resolve({ errors: [error] })
+      : Promise.reject(error);
   }
 }

package/subscription/subscribe.mjs

@@ -1,10 +1,11 @@
 import { isAsyncIterable } from 'iterall';
 import inspect from '../jsutils/inspect';
+import { addPath, pathToArray } from '../jsutils/Path';
 import { GraphQLError } from '../error/GraphQLError';
 import { locatedError } from '../error/locatedError';
-import { addPath, assertValidExecutionArguments, buildExecutionContext, buildResolveInfo, collectFields, execute, getFieldDef, resolveFieldValueOrError, responsePathAsArray } from '../execution/execute';
-import mapAsyncIterator from './mapAsyncIterator';
+import { assertValidExecutionArguments, buildExecutionContext, buildResolveInfo, collectFields, execute, getFieldDef, resolveFieldValueOrError } from '../execution/execute';
 import { getOperationRootType } from '../utilities/getOperationRootType';
+import mapAsyncIterator from './mapAsyncIterator';
 export function subscribe(argsOrSchema, document, rootValue, contextValue, variableValues, operationName, fieldResolver, subscribeFieldResolver) {
   /* eslint-enable no-redeclare */
   // Extract arguments from object args if provided.
@@ -61,17 +62,27 @@ function subscribeImpl(args) {
     return (// Note: Flow can't refine isAsyncIterable, so explicit casts are used.
       isAsyncIterable(resultOrStream) ? mapAsyncIterator(resultOrStream, mapSourceToResponse, reportGraphQLError) : resultOrStream
     );
-  }, reportGraphQLError);
+  });
 }
 /**
  * Implements the "CreateSourceEventStream" algorithm described in the
  * GraphQL specification, resolving the subscription source event stream.
  *
- * Returns a Promise<AsyncIterable>.
+ * Returns a Promise which resolves to either an AsyncIterable (if successful)
+ * or an ExecutionResult (error). The promise will be rejected if the schema or
+ * other arguments to this function are invalid, or if the resolved event stream
+ * is not an async iterable.
  *
- * If the client-provided invalid arguments, the source stream could not be
- * created, or the resolver did not return an AsyncIterable, this function will
- * will throw an error, which should be caught and handled by the caller.
+ * If the client-provided arguments to this function do not result in a
+ * compliant subscription, a GraphQL Response (ExecutionResult) with
+ * descriptive errors and no data will be returned.
+ *
+ * If the the source stream could not be created due to faulty subscription
+ * resolver logic or underlying systems, the promise will resolve to a single
+ * ExecutionResult containing `errors` and no `data`.
+ *
+ * If the operation succeeded, the promise resolves to the AsyncIterable for the
+ * event stream returned by the resolver.
  *
  * A Source Event Stream represents a sequence of events, each of which triggers
  * a GraphQL execution for that event.
@@ -125,7 +136,9 @@ export function createSourceEventStream(schema, document, rootValue, contextValu
     return Promise.resolve(result).then(function (eventStream) {
       // If eventStream is an Error, rethrow a located error.
       if (eventStream instanceof Error) {
-        throw locatedError(eventStream, fieldNodes, responsePathAsArray(path));
+        return {
+          errors: [locatedError(eventStream, fieldNodes, pathToArray(path))]
+        };
       } // Assert field returned an event stream, otherwise yield an error.
 
 
@@ -137,6 +150,11 @@ export function createSourceEventStream(schema, document, rootValue, contextValu
       throw new Error('Subscription field must return Async Iterable. Received: ' + inspect(eventStream));
     });
   } catch (error) {
-    return Promise.reject(error);
+    // As with reportGraphQLError above, if the error is a GraphQLError, report
+    // it as an ExecutionResult; otherwise treat it as a system-class error and
+    // re-throw it.
+    return error instanceof GraphQLError ? Promise.resolve({
+      errors: [error]
+    }) : Promise.reject(error);
   }
 }

package/tsutils/Maybe.d.ts

@@ -0,0 +1,4 @@
+// Conveniently represents flow's "Maybe" type https://flow.org/en/docs/types/maybe/
+type Maybe<T> = null | undefined | T;
+
+export default Maybe;