graphql/execution/subscriptions

Functions

subscribe()

Implements the “Subscribe” algorithm described in the GraphQL specification.

Returns a Promise which resolves to either an AsyncIterator (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 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.

Each payload yielded by the source event stream is executed with the payload as the root value. This maps the subscription source stream into the response stream described by the GraphQL specification.

Accepts either an object with named arguments, or individual arguments.

Signature:

subscribe(args: ExecutionArgs): Promise<ExecutionResult | AsyncGenerator<ExecutionResult, void, void>>

Arguments

Returns

Example

import { subscribe } from 'graphql/execution';
 
const result = subscribe(args);
 
// result contains the subscribe return value

createSourceEventStream()

Overload 1

Implements the “CreateSourceEventStream” algorithm described in the GraphQL specification, resolving the subscription source event stream.

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 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.

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.

Signature:

createSourceEventStream(args: ExecutionArgs): Promise<ExecutionResult | AsyncIterable<unknown, any, any>>

Arguments

Returns

Example

import { createSourceEventStream } from 'graphql/execution';
 
const stream = await createSourceEventStream(args);
 
// stream is an AsyncIterable, or an ExecutionResult containing errors

Overload 2

Creates the source event stream for a subscription operation using the legacy positional argument overload. Use the args object overload instead; this overload will be removed in the next major version.

Signature:

createSourceEventStream(schema: GraphQLSchema, document: DocumentNode, rootValue?: unknown, contextValue?: unknown, variableValues?: null | undefined | object, operationName?: null | undefined | string, subscribeFieldResolver?: null | undefined | GraphQLFieldResolver<any, any>): Promise<ExecutionResult | AsyncIterable<unknown, any, any>>

Arguments

Returns

Example

import { createSourceEventStream } from 'graphql/execution';
 
const stream = await createSourceEventStream(schema, document);
 
// stream is an AsyncIterable, or an ExecutionResult containing errors