Skip to content

handler.HandlerOptions.md

Latest commit

 

History

History
293 lines (183 loc) · 11.1 KB

handler.HandlerOptions.md

File metadata and controls

293 lines (183 loc) · 11.1 KB

graphql-http / handler / HandlerOptions

Interface: HandlerOptions<RequestRaw, RequestContext, Context>

handler.HandlerOptions

Type parameters

Name Type
RequestRaw unknown
RequestContext unknown
Context extends OperationContext = undefined

Table of contents

Properties

Properties

context

• Optional context: Context | (req: Request<RequestRaw, RequestContext>, params: RequestParams) => Response | Context | Promise<Response | 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.

execute

• Optional execute: (args: ExecutionArgs) => PromiseOrValue<ExecutionResult>

Type declaration

▸ (args): PromiseOrValue<ExecutionResult>

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

Parameters
Name Type
args ExecutionArgs
Returns

PromiseOrValue<ExecutionResult>

formatError

• Optional formatError: FormatError

Format handled errors to your satisfaction. Either GraphQL errors or safe request processing errors are meant by "handled errors".

If multiple errors have occurred, all of them will be mapped using this formatter.

getOperationAST

• Optional getOperationAST: (documentAST: DocumentNode, operationName?: Maybe<string>) => Maybe<OperationDefinitionNode>

Type declaration

▸ (documentAST, operationName?): Maybe<OperationDefinitionNode>

GraphQL operation AST getter used for detecting the operation type.

Parameters
Name Type
documentAST DocumentNode
operationName? Maybe<string>
Returns

Maybe<OperationDefinitionNode>

onOperation

• Optional onOperation: (req: Request<RequestRaw, RequestContext>, args: OperationArgs<Context>, result: ExecutionResult<ObjMap<unknown>, ObjMap<unknown>>) => void | ExecutionResult<ObjMap<unknown>, ObjMap<unknown>> | Response | Promise<void | ExecutionResult<ObjMap<unknown>, ObjMap<unknown>> | Response>

Type declaration

▸ (req, args, result): void | ExecutionResult<ObjMap<unknown>, ObjMap<unknown>> | Response | Promise<void | ExecutionResult<ObjMap<unknown>, ObjMap<unknown>> | Response>

Executed after the operation call resolves.

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

Use this callback to listen for GraphQL operations and execution result manipulation.

If you want to respond to the client with a custom status and/or body, you should do by returning a Request argument which will stop further execution.

Parameters
Name Type
req Request<RequestRaw, RequestContext>
args OperationArgs<Context>
result ExecutionResult<ObjMap<unknown>, ObjMap<unknown>>
Returns

void | ExecutionResult<ObjMap<unknown>, ObjMap<unknown>> | Response | Promise<void | ExecutionResult<ObjMap<unknown>, ObjMap<unknown>> | Response>

onSubscribe

• Optional onSubscribe: (req: Request<RequestRaw, RequestContext>, params: RequestParams) => void | ExecutionResult<ObjMap<unknown>, ObjMap<unknown>> | Response | OperationArgs<Context> | readonly GraphQLError[] | Promise<void | ExecutionResult<ObjMap<unknown>, ObjMap<unknown>> | Response | OperationArgs<Context> | readonly GraphQLError[]>

Type declaration

▸ (req, params): void | ExecutionResult<ObjMap<unknown>, ObjMap<unknown>> | Response | OperationArgs<Context> | readonly GraphQLError[] | Promise<void | ExecutionResult<ObjMap<unknown>, ObjMap<unknown>> | Response | OperationArgs<Context> | readonly GraphQLError[]>

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

If you return ExecutionResult from the callback, it will be used directly for responding to the request. Useful for implementing a response cache.

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.

You must validate the ExecutionArgs yourself if returning them.

If you return an array of GraphQLError from the callback, they will be reported to the client while complying with the spec.

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

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.

If you want to respond to the client with a custom status and/or body, you should do by returning a Request argument which will stop further execution.

Parameters
Name Type
req Request<RequestRaw, RequestContext>
params RequestParams
Returns

void | ExecutionResult<ObjMap<unknown>, ObjMap<unknown>> | Response | OperationArgs<Context> | readonly GraphQLError[] | Promise<void | ExecutionResult<ObjMap<unknown>, ObjMap<unknown>> | Response | OperationArgs<Context> | readonly GraphQLError[]>

parse

• Optional parse: (source: string | Source, options?: ParseOptions) => DocumentNode

Type declaration

▸ (source, options?): DocumentNode

GraphQL parse function allowing you to apply a custom parser.

Parameters
Name Type
source string | Source
options? ParseOptions
Returns

DocumentNode

parseRequestParams

• Optional parseRequestParams: ParseRequestParams<RequestRaw, RequestContext>

The request parser for an incoming GraphQL request.

Read more about it in ParseRequestParams.

rootValue

• Optional rootValue: unknown

The GraphQL root value or resolvers to go alongside the execution. 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.

schema

• Optional schema: GraphQLSchema | (req: Request<RequestRaw, RequestContext>, args: Omit<OperationArgs<Context>, "schema">) => Response | GraphQLSchema | Promise<Response | 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 operation 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.

If you want to respond to the client with a custom status and/or body, you should do by returning a Request argument which will stop further execution.

validate

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

Type declaration

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

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

Will not be used when implementing a custom onSubscribe.

Parameters
Name Type Description
schema GraphQLSchema -
documentAST DocumentNode -
rules? readonly ValidationRule[] -
options? Object -
typeInfo? TypeInfo Deprecated will be removed in 17.0.0
Returns

ReadonlyArray<GraphQLError>

validationRules

• Optional validationRules: readonly ValidationRule[] | (req: Request<RequestRaw, RequestContext>, args: OperationArgs<Context>, specifiedRules: readonly ValidationRule[]) => readonly ValidationRule[] | Promise<readonly ValidationRule[]>

The validation rules for running GraphQL validate.

When providing an array, the rules will be APPENDED to the default specifiedRules array provided by the graphql-js module.

Alternatively, providing a function instead will OVERWRITE the defaults and use exclusively the rules returned by the function. The third (last) argument of the function are the default specifiedRules array provided by the graphql-js module, you're free to prepend/append the defaults to your rule set, or omit them altogether.