Interface: ServerOptions<P, E>

server.ServerOptions

Type parameters

Properties

connectionInitWaitTimeout

• Optional connectionInitWaitTimeout: number

The amount of time for which the server will wait for ConnectionInit message.

Set the value to Infinity, '', 0, null or undefined to skip waiting.

If the wait timeout has passed and the client has not sent the ConnectionInit message, the server will terminate the socket by dispatching a close event 4408: Connection initialisation timeout

Default

3_000 // 3 seconds

Defined in

src/server.ts:193

context

• Optional context: GraphQLExecutionContextValue | (ctx: Context<P, E>, message: SubscribeMessage, args: ExecutionArgs) => GraphQLExecutionContextValue | Promise<GraphQLExecutionContextValue>

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

If you return from onSubscribe, and the returned value is missing the contextValue field, this context will be used instead.

If you use the function signature, the final execution arguments will be passed in (also the returned value from onSubscribe). Since the context is injected on every subscribe, the SubscribeMessage with the regular Context will be passed in through the arguments too.

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.

Defined in

src/server.ts:124

execute

• Optional execute: (args: ExecutionArgs) => OperationResult

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

Throwing an error from within this function will close the socket with the Error message in the close event reason.

Type declaration

▸ (args): OperationResult

Parameters

Returns

OperationResult

Defined in

src/server.ts:170

jsonMessageReplacer

• Optional jsonMessageReplacer: JSONMessageReplacer

An optional override for the JSON.stringify function used to serialize outgoing messages to from server. Useful for serializing custom datatypes out to the client.

Defined in

src/server.ts:398

jsonMessageReviver

• Optional jsonMessageReviver: JSONMessageReviver

An optional override for the JSON.parse function used to hydrate incoming messages to this server. Useful for parsing custom datatypes out of the incoming JSON.

Defined in

src/server.ts:392

onClose

• Optional onClose: (ctx: Context<P, E>, code?: number, reason?: string) => void | Promise<void>

Called when the socket closes for whatever reason, at any point in time. Provides the close event too. Beware that this callback happens AFTER all subscriptions have been gracefully completed and AFTER the onDisconnect callback.

If you are interested in tracking the subscriptions completions, consider using the onComplete callback.

In comparison to onDisconnect, this callback will ALWAYS be called, regardless if the user successfully went through the connection initialisation or not. onConnect might not called before the onClose.

Type declaration

▸ (ctx, code?, reason?): void | Promise<void>

Parameters

Returns

void | Promise<void>

Defined in

src/server.ts:260

onComplete

• Optional onComplete: (ctx: Context<P, E>, message: CompleteMessage) => void | Promise<void>

The complete callback is executed after the operation has completed right before sending the complete message to the client.

Throwing an error from within this function will close the socket with the Error message in the close event reason.

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

Type declaration

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

Parameters

Returns

void | Promise<void>

Defined in

src/server.ts:383

onConnect

• Optional onConnect: (ctx: Context<P, E>) => boolean | void | Record<string, unknown> | Promise<boolean | void | Record<string, unknown>>

Is the connection callback called when the client requests the connection initialisation through the message ConnectionInit.

The message payload (connectionParams from the client) is present in the Context.connectionParams.

• Returning true or nothing from the callback will allow the client to connect.

• Returning false from the callback will terminate the socket by dispatching the close event 4403: Forbidden.

• Returning a Record from the callback will allow the client to connect and pass the returned value to the client through the optional payload field in the ConnectionAck message.

Throwing an error from within this function will close the socket with the Error message in the close event reason.

Type declaration

▸ (ctx): boolean | void | Record<string, unknown> | Promise<boolean | void | Record<string, unknown>>

Parameters

Returns

boolean | void | Record<string, unknown> | Promise<boolean | void | Record<string, unknown>>

Defined in

src/server.ts:218

onDisconnect

• Optional onDisconnect: (ctx: Context<P, E>, code?: number, reason?: string) => void | Promise<void>

Called when the client disconnects for whatever reason after he successfully went through the connection initialisation phase. Provides the close event too. Beware that this callback happens AFTER all subscriptions have been gracefully completed and BEFORE the onClose callback.

If you are interested in tracking the subscriptions completions, consider using the onComplete callback.

This callback will be called EXCLUSIVELY if the client connection is acknowledged. Meaning, onConnect will be called before the onDisconnect.

For tracking socket closures at any point in time, regardless of the connection state - consider using the onClose callback.

Type declaration

▸ (ctx, code?, reason?): void | Promise<void>

Parameters

Returns

void | Promise<void>

Defined in

src/server.ts:241

onError

• Optional onError: (ctx: Context<P, E>, message: ErrorMessage, errors: readonly GraphQLError[]) => void | readonly GraphQLError[] | Promise<void | readonly GraphQLError[]>

Executed after an error occurred right before it has been dispatched to the client.

Use this callback to format the outgoing GraphQL errors before they reach the client.

Returned result will be injected in the error message payload.

Throwing an error from within this function will close the socket with the Error message in the close event reason.

Type declaration

▸ (ctx, message, errors): void | readonly GraphQLError[] | Promise<void | readonly GraphQLError[]>

Parameters

Returns

void | readonly GraphQLError[] | Promise<void | readonly GraphQLError[]>

Defined in

src/server.ts:341

onNext

• Optional onNext: (ctx: Context<P, E>, message: NextMessage, args: ExecutionArgs, 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 appear in this callback.

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

Returned result will be injected in the next message payload.

Throwing an error from within this function will close the socket with the Error message in the close event reason.

Type declaration

▸ (ctx, message, args, 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>>>

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/server.ts:360

onOperation

• Optional onOperation: (ctx: Context<P, E>, message: SubscribeMessage, 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.

Use this callback to listen for subscribe operation and execution result manipulation.

Throwing an error from within this function will close the socket with the Error message in the close event reason.

Type declaration

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

Parameters

Returns

void | OperationResult | Promise<void | OperationResult>

Defined in

src/server.ts:322

onSubscribe

• Optional onSubscribe: (ctx: Context<P, E>, message: SubscribeMessage) => void | readonly GraphQLError[] | ExecutionArgs | Promise<void | readonly GraphQLError[] | ExecutionArgs>

The subscribe callback executed right after acknowledging the request before any payload processing has been performed.

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 or rootValue from the returned value will have the provided server options fill in the gaps.

To report GraphQL errors simply return an array of them from the callback, they will be reported to the client through the error message.

Useful for preparing the execution arguments following a custom logic. A typical use case are persisted queries, you can identify the query from the subscribe message and create the GraphQL operation execution args which are then returned by the function.

Throwing an error from within this function will close the socket with the Error message in the close event reason.

Type declaration

▸ (ctx, message): void | readonly GraphQLError[] | ExecutionArgs | Promise<void | readonly GraphQLError[] | ExecutionArgs>

Parameters

Returns

void | readonly GraphQLError[] | ExecutionArgs | Promise<void | readonly GraphQLError[] | ExecutionArgs>

Defined in

src/server.ts:294

roots

• Optional roots: Object

The GraphQL root fields or resolvers to go alongside the schema. Learn more about them here: https://graphql.org/learn/execution/#root-fields-resolvers.

If you return from onSubscribe, and the returned value is missing the rootValue field, the relevant operation root will be used instead.

Type declaration

Defined in

src/server.ts:142

schema

• Optional schema: GraphQLSchema | (ctx: Context<P, E>, message: SubscribeMessage, args: Omit<ExecutionArgs, "schema">) => 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.

Throwing an error from within this function will close the socket with the Error message in the close event reason.

Defined in

src/server.ts:98

subscribe

• Optional subscribe: (args: ExecutionArgs) => OperationResult

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

Throwing an error from within this function will close the socket with the Error message in the close event reason.

Type declaration

▸ (args): OperationResult

Parameters

Returns

OperationResult

Defined in

src/server.ts:179

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.

Returned, non-empty, array of GraphQLErrors will be communicated to the client through the ErrorMessage. Use an empty array if the document is valid and no errors have been encountered.

Will not be used when implementing a custom onSubscribe.

Throwing an error from within this function will close the socket with the Error message in the close event reason.

Type declaration

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

Parameters

Returns

ReadonlyArray<GraphQLError>

Defined in

src/server.ts:161