Documentation
Interfaces
handler.HandlerOptions

Interface: HandlerOptions<RequestRaw, RequestContext, Context>

handler.HandlerOptions

Type parameters

NameType
RequestRawunknown
RequestContextunknown
Contextextends OperationContext = undefined

Properties

authenticate

Optional authenticate: (req: Request<RequestRaw, RequestContext>) => undefined | null | string | Response | Promise<undefined | null | string | Response>

Authenticate the client. Returning a string indicates that the client is authenticated and the request is ready to be processed.

A distinct token of type string must be supplied to enable the “single connection mode”.

Providing null as the token will completely disable the “single connection mode” and all incoming requests will always use the “distinct connection mode”.

Default

'req.headers["x-graphql-event-stream-token"] || req.url.searchParams["token"] || generateRandomUUID()' // https://gist.github.com/jed/982883

Type declaration

▸ (req): undefined | null | string | Response | Promise<undefined | null | string | Response>

Authenticate the client. Returning a string indicates that the client is authenticated and the request is ready to be processed.

A distinct token of type string must be supplied to enable the “single connection mode”.

Providing null as the token will completely disable the “single connection mode” and all incoming requests will always use the “distinct connection mode”.

Parameters
NameType
reqRequest<RequestRaw, RequestContext>
Returns

undefined | null | string | Response | Promise<undefined | null | string | Response>

Default

'req.headers["x-graphql-event-stream-token"] || req.url.searchParams["token"] || generateRandomUUID()' // https://gist.github.com/jed/982883

Defined in

src/handler.ts:204


context

Optional context: Context | (req: Request<RequestRaw, RequestContext>, params: RequestParams) => Context | Promise<Context>

A value which is provided to every resolver and holds important contextual information like the currently logged in user, or access to a database.

Note that the context function is invoked on each operation only once. Meaning, for subscriptions, only at the point of initialising the subscription; not on every subscription event emission. Read more about the context lifecycle in subscriptions here: https://github.com/graphql/graphql-js/issues/894.

If you don’t provide the context context field, but have a context - you’re trusted to provide one in onSubscribe.

Defined in

src/handler.ts:238


execute

Optional execute: (args: OperationArgs<Context>) => OperationResult

Is the execute function from GraphQL which is used to execute the query and mutation operations.

Type declaration

▸ (args): OperationResult

Is the execute function from GraphQL which is used to execute the query and mutation operations.

Parameters
NameType
argsOperationArgs<Context>
Returns

OperationResult

Defined in

src/handler.ts:166


onComplete

Optional onComplete: (ctx: Context, req: Request<RequestRaw, RequestContext>) => void | Promise<void>

The complete callback is executed after the operation has completed and the client has been notified.

Since the library makes sure to complete streaming operations even after an abrupt closure, this callback will always be called.

Param

Always the request that contains the GraphQL operation.

Type declaration

▸ (ctx, req): void | Promise<void>

The complete callback is executed after the operation has completed and the client has been notified.

Since the library makes sure to complete streaming operations even after an abrupt closure, this callback will always be called.

Parameters
NameTypeDescription
ctxContext-
reqRequest<RequestRaw, RequestContext>Always the request that contains the GraphQL operation.
Returns

void | Promise<void>

Defined in

src/handler.ts:325


onConnect

Optional onConnect: (req: Request<RequestRaw, RequestContext>) => undefined | null | void | Response | Promise<undefined | null | void | Response>

Called when a new event stream is connecting BEFORE it is accepted. By accepted, its meant the server processed the request and responded with a 200 (OK), alongside flushing the necessary event stream headers.

Type declaration

▸ (req): undefined | null | void | Response | Promise<undefined | null | void | Response>

Called when a new event stream is connecting BEFORE it is accepted. By accepted, its meant the server processed the request and responded with a 200 (OK), alongside flushing the necessary event stream headers.

Parameters
NameType
reqRequest<RequestRaw, RequestContext>
Returns

undefined | null | void | Response | Promise<undefined | null | void | Response>

Defined in

src/handler.ts:217


onNext

Optional onNext: (ctx: Context, req: Request<RequestRaw, RequestContext>, result: ExecutionResult<Record<string, unknown>, Record<string, unknown>> | ExecutionPatchResult<unknown, Record<string, unknown>>) => void | ExecutionResult<Record<string, unknown>, Record<string, unknown>> | ExecutionPatchResult<unknown, Record<string, unknown>> | Promise<void | ExecutionResult<Record<string, unknown>, Record<string, unknown>> | ExecutionPatchResult<unknown, Record<string, unknown>>>

Executed after an operation has emitted a result right before that result has been sent to the client.

Results from both single value and streaming operations will invoke this callback.

Use this callback if you want to format the execution result before it reaches the client.

Param

Always the request that contains the GraphQL operation.

Type declaration

▸ (ctx, req, result): void | ExecutionResult<Record<string, unknown>, Record<string, unknown>> | ExecutionPatchResult<unknown, Record<string, unknown>> | Promise<void | ExecutionResult<Record<string, unknown>, Record<string, unknown>> | ExecutionPatchResult<unknown, Record<string, unknown>>>

Executed after an operation has emitted a result right before that result has been sent to the client.

Results from both single value and streaming operations will invoke this callback.

Use this callback if you want to format the execution result before it reaches the client.

Parameters
NameTypeDescription
ctxContext-
reqRequest<RequestRaw, RequestContext>Always the request that contains the GraphQL operation.
resultExecutionResult<Record<string, unknown>, Record<string, unknown>> | ExecutionPatchResult<unknown, Record<string, unknown>>-
Returns

void | ExecutionResult<Record<string, unknown>, Record<string, unknown>> | ExecutionPatchResult<unknown, Record<string, unknown>> | Promise<void | ExecutionResult<Record<string, unknown>, Record<string, unknown>> | ExecutionPatchResult<unknown, Record<string, unknown>>>

Defined in

src/handler.ts:306


onOperation

Optional onOperation: (ctx: Context, req: Request<RequestRaw, RequestContext>, args: ExecutionArgs, result: OperationResult) => void | OperationResult | Promise<void | OperationResult>

Executed after the operation call resolves. For streaming operations, triggering this callback does not necessarely mean that there is already a result available - it means that the subscription process for the stream has resolved and that the client is now subscribed.

The OperationResult argument is the result of operation execution. It can be an iterator or already a value.

If you want the single result and the events from a streaming operation, use the onNext callback.

If onSubscribe returns an OperationResult, this hook will NOT be called.

Type declaration

▸ (ctx, req, args, result): void | OperationResult | Promise<void | OperationResult>

Executed after the operation call resolves. For streaming operations, triggering this callback does not necessarely mean that there is already a result available - it means that the subscription process for the stream has resolved and that the client is now subscribed.

The OperationResult argument is the result of operation execution. It can be an iterator or already a value.

If you want the single result and the events from a streaming operation, use the onNext callback.

If onSubscribe returns an OperationResult, this hook will NOT be called.

Parameters
NameType
ctxContext
reqRequest<RequestRaw, RequestContext>
argsExecutionArgs
resultOperationResult
Returns

void | OperationResult | Promise<void | OperationResult>

Defined in

src/handler.ts:288


onSubscribe

Optional onSubscribe: (req: Request<RequestRaw, RequestContext>, params: RequestParams) => void | Response | OperationResult | OperationArgs<Context> | Promise<void | Response | OperationResult | OperationArgs<Context>>

The subscribe callback executed right after processing the request before proceeding with the GraphQL operation execution.

If you return ExecutionArgs from the callback, it will be used instead of trying to build one internally. In this case, you are responsible for providing a ready set of arguments which will be directly plugged in the operation execution.

Omitting the fields contextValue from the returned ExecutionArgs will use the provided context option, if available.

If you want to respond to the client with a custom status or body, you should do so using the provided res argument which will stop further execution.

Useful for preparing the execution arguments following a custom logic. A typical use-case is persisted queries. You can identify the query from the request parameters and supply the appropriate GraphQL operation execution arguments.

Type declaration

▸ (req, params): void | Response | OperationResult | OperationArgs<Context> | Promise<void | Response | OperationResult | OperationArgs<Context>>

The subscribe callback executed right after processing the request before proceeding with the GraphQL operation execution.

If you return ExecutionArgs from the callback, it will be used instead of trying to build one internally. In this case, you are responsible for providing a ready set of arguments which will be directly plugged in the operation execution.

Omitting the fields contextValue from the returned ExecutionArgs will use the provided context option, if available.

If you want to respond to the client with a custom status or body, you should do so using the provided res argument which will stop further execution.

Useful for preparing the execution arguments following a custom logic. A typical use-case is persisted queries. You can identify the query from the request parameters and supply the appropriate GraphQL operation execution arguments.

Parameters
NameType
reqRequest<RequestRaw, RequestContext>
paramsRequestParams
Returns

void | Response | OperationResult | OperationArgs<Context> | Promise<void | Response | OperationResult | OperationArgs<Context>>

Defined in

src/handler.ts:263


schema

Optional schema: GraphQLSchema | (req: Request<RequestRaw, RequestContext>, args: Pick<OperationArgs<Context>, "contextValue" | "operationName" | "document" | "variableValues">) => GraphQLSchema | Promise<GraphQLSchema>

The GraphQL schema on which the operations will be executed and validated against.

If a function is provided, it will be called on every subscription request allowing you to manipulate schema dynamically.

If the schema is left undefined, you’re trusted to provide one in the returned ExecutionArgs from the onSubscribe callback.

Defined in

src/handler.ts:184


subscribe

Optional subscribe: (args: OperationArgs<Context>) => OperationResult

Is the subscribe function from GraphQL which is used to execute the subscription operation.

Type declaration

▸ (args): OperationResult

Is the subscribe function from GraphQL which is used to execute the subscription operation.

Parameters
NameType
argsOperationArgs<Context>
Returns

OperationResult

Defined in

src/handler.ts:171


validate

Optional validate: (schema: GraphQLSchema, documentAST: DocumentNode, rules?: readonly ValidationRule[], options?: {}, typeInfo?: TypeInfo) => ReadonlyArray<GraphQLError>

A custom GraphQL validate function allowing you to apply your own validation rules.

Type declaration

▸ (schema, documentAST, rules?, options?, typeInfo?): ReadonlyArray<GraphQLError>

A custom GraphQL validate function allowing you to apply your own validation rules.

Parameters
NameTypeDescription
schemaGraphQLSchema-
documentASTDocumentNode-
rules?readonly ValidationRule[]-
options?Object-
typeInfo?TypeInfoDeprecated will be removed in 17.0.0
Returns

ReadonlyArray<GraphQLError>

Defined in

src/handler.ts:161