Interface: HandlerOptions<RequestRaw, RequestContext, Context>

handler.HandlerOptions

Type parameters

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

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

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

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

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

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

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

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

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

Returns

ReadonlyArray<GraphQLError>

Defined in

src/handler.ts:161