index.d.ts

import {
  FastifyError,
  FastifyReply,
  FastifyRequest,
  FastifyInstance,
  RouteOptions
} from "fastify";
import {
  DocumentNode,
  ExecutionResult,
  GraphQLSchema,
  Source,
  GraphQLResolveInfo,
  GraphQLScalarType,
  ValidationRule,
  FormattedExecutionResult,
  ParseOptions,
} from "graphql";
import type { WebSocket } from "ws";
import { IncomingMessage, OutgoingHttpHeaders } from "http";
import { Readable } from "stream";

type Mercurius = typeof mercurius

declare namespace mercurius {
  export interface PubSub {
    subscribe<TResult = any>(topics: string | string[]): Promise<Readable & AsyncIterableIterator<TResult>>;
    publish<TResult = any>(event: { topic: string; payload: TResult }, callback?: () => void): void;
  }
  
  export interface MercuriusContext {
    app: FastifyInstance;
    reply: FastifyReply;
    operationsCount?: number;
    operationId?: number;
    __currentQuery: string;
    /**
     * __Caution__: Only available if `subscriptions` are enabled
     */
    pubsub: PubSub;
  }
  
  export interface MercuriusError<TError extends Error = Error> extends FastifyError {
    errors?: TError[]
  }
  
  export interface Loader<
    TObj extends Record<string, any> = any,
    TParams extends Record<string, any> = any,
    TContext extends Record<string, any> = MercuriusContext
  > {
    (
      queries: Array<{
        obj: TObj;
        params: TParams;
      }>,
      context: TContext & {
        reply: FastifyReply;
      }
    ): any;
  }
  
  export interface MercuriusLoaders<TContext extends Record<string, any> = MercuriusContext> {
    [root: string]: {
      [field: string]:
        | Loader<any, any, TContext>
        | {
            loader: Loader<any, any, TContext>;
            opts?: {
              cache?: boolean;
            };
          };
    };
  }
  
  // ------------------------
  // Request Lifecycle hooks
  // ------------------------
  
  /**
   * `preParsing` is the first hook to be executed in the GraphQL request lifecycle. The next hook will be `preValidation`.
   */
  export interface preParsingHookHandler<TContext = MercuriusContext> {
    (
      schema: GraphQLSchema,
      source: string,
      context: TContext,
    ): Promise<void> | void;
  }
  
  /**
   * `preValidation` is the second hook to be executed in the GraphQL request lifecycle. The previous hook was `preParsing`, the next hook will be `preExecution`.
   */
  export interface preValidationHookHandler<TContext = MercuriusContext> {
    (
      schema: GraphQLSchema,
      source: DocumentNode,
      context: TContext,
    ): Promise<void> | void;
  }
  
  /**
   * `preExecution` is the third hook to be executed in the GraphQL request lifecycle. The previous hook was `preValidation`.
   * Notice: in the `preExecution` hook, you can modify the following items by returning them in the hook definition:
   *  - `schema`
   *  - `document`
   *  - `errors`
   *  - `variables`
   */
  export interface preExecutionHookHandler<TContext = MercuriusContext, TError extends Error = Error> {
    (
      schema: GraphQLSchema,
      source: DocumentNode,
      context: TContext,
      variables: Record<string, any>,
    ): Promise<PreExecutionHookResponse<TError> | void> | PreExecutionHookResponse<TError> | void;
  }
  
  /**
   * `onResolution` is the fifth and final hook to be executed in the GraphQL request lifecycle. The previous hook was `preExecution`.
   */
  export interface onResolutionHookHandler<TData extends Record<string, any> = Record<string, any>, TContext = MercuriusContext> {
    (
      execution: ExecutionResult<TData>,
      context: TContext,
    ): Promise<void> | void;
  }
  
  // -----------------------------
  // Subscription Lifecycle hooks
  // -----------------------------
  
  /**
   * `preSubscriptionParsing` is the first hook to be executed in the GraphQL subscription lifecycle. The next hook will be `preSubscriptionExecution`.
   * This hook will only be triggered when subscriptions are enabled.
   */
  export interface preSubscriptionParsingHookHandler<TContext = MercuriusContext> {
    (
      schema: GraphQLSchema,
      source: string,
      context: TContext,
    ): Promise<void> | void;
  }
  
  /**
   * `preSubscriptionExecution` is the second hook to be executed in the GraphQL subscription lifecycle. The previous hook was `preSubscriptionParsing`.
   * This hook will only be triggered when subscriptions are enabled.
   */
  export interface preSubscriptionExecutionHookHandler<TContext = MercuriusContext> {
    (
      schema: GraphQLSchema,
      source: DocumentNode,
      context: TContext,
    ): Promise<void> | void;
  }
  
  /**
   * `onSubscriptionResolution` is the fourth hook to be executed in the GraphQL subscription lifecycle. The next hook will be `onSubscriptionEnd`.
   * This hook will only be triggered when subscriptions are enabled.
   */
  export interface onSubscriptionResolutionHookHandler<TData extends Record<string, any> = Record<string, any>, TContext = MercuriusContext> {
    (
      execution: ExecutionResult<TData>,
      context: TContext,
    ): Promise<void> | void;
  }
  
  /**
   * `onSubscriptionEnd` is the fifth and final hook to be executed in the GraphQL subscription lifecycle. The previous hook was `onSubscriptionResolution`.
   * This hook will only be triggered when subscriptions are enabled.
   */
  export interface onSubscriptionEndHookHandler<TContext = MercuriusContext> {
    (
      context: TContext,
      id: string | number,
    ): Promise<void> | void;
  }
  
  // ----------------------------
  // Application Lifecycle hooks
  // ----------------------------
  
  export interface onExtendSchemaHandler<TContext = MercuriusContext> {
    (
      schema: GraphQLSchema,
      context: TContext,
    ): Promise<void> | void;
  }
  
  interface ServiceConfig {
    setSchema: (schema: string) => ServiceConfig;
  }
  
  export interface MercuriusPlugin {
    <
      TData extends Record<string, any> = Record<string, any>,
      TVariables extends Record<string, any> = Record<string, any>
    >(
      source: string,
      context?: Record<string, any>,
      variables?: TVariables,
      operationName?: string
    ): Promise<ExecutionResult<TData>>;
    /**
     * Replace existing schema
     * @param schema graphql schema
     */
    replaceSchema(schema: GraphQLSchema): void;
    /**
     * Extend existing schema
     * @param schema graphql schema
     */
    extendSchema(schema: string | Source | DocumentNode): Promise<void> | void;
    /**
     * Define additional resolvers
     * @param resolvers object with resolver functions
     */
    defineResolvers<TContext extends Record<string, any> = MercuriusContext>(resolvers: IResolvers<any, TContext>): void;
    /**
     * Define data loaders
     * @param loaders object with data loader functions
     */
    defineLoaders<TContext extends Record<string, any> = MercuriusContext>(loaders: MercuriusLoaders<TContext>): void;
    /**
     * Transform the existing schema
     */
    transformSchema: (
      schemaTransforms:
        | ((schema: GraphQLSchema) => GraphQLSchema)
        | Array<(schema: GraphQLSchema) => GraphQLSchema>
    ) => void;
    /**
     * __Caution__: Only available if `subscriptions` are enabled
     */
    pubsub: PubSub;
    /**
     * Managed GraphQL schema object for doing custom execution with. Will reflect changes made via `extendSchema`, `defineResolvers`, etc.
     */
    schema: GraphQLSchema;
  
    // addHook: overloads
  
    // Request lifecycle addHooks
  
    /**
     * `preParsing` is the first hook to be executed in the GraphQL request lifecycle. The next hook will be `preValidation`.
     */
    addHook<TContext = MercuriusContext>(name: 'preParsing', hook: preParsingHookHandler<TContext>): void;
  
    /**
     * `preValidation` is the second hook to be executed in the GraphQL request lifecycle. The previous hook was `preParsing`, the next hook will be `preExecution`.
     */
    addHook<TContext = MercuriusContext>(name: 'preValidation', hook: preValidationHookHandler<TContext>): void;
  
    /**
     * `preExecution` is the third hook to be executed in the GraphQL request lifecycle. The previous hook was `preValidation`.
     * Notice: in the `preExecution` hook, you can modify the following items by returning them in the hook definition:
     *  - `document`
     *  - `errors`
     */
    addHook<TContext = MercuriusContext, TError extends Error = Error>(name: 'preExecution', hook: preExecutionHookHandler<TContext, TError>): void;
  
    /**
     * `onResolution` is the fifth and final hook to be executed in the GraphQL request lifecycle. The previous hook was `preExecution`.
     */
    addHook<TData extends Record<string, any> = Record<string, any>, TContext = MercuriusContext>(name: 'onResolution', hook: onResolutionHookHandler<TData, TContext>): void;
  
    // Subscription lifecycle addHooks
  
    /**
     * `preSubscriptionParsing` is the first hook to be executed in the GraphQL subscription lifecycle. The next hook will be `preSubscriptionExecution`.
     * This hook will only be triggered when subscriptions are enabled.
     */
    addHook<TContext = MercuriusContext>(name: 'preSubscriptionParsing', hook: preSubscriptionParsingHookHandler<TContext>): void;
  
    /**
     * `preSubscriptionExecution` is the second hook to be executed in the GraphQL subscription lifecycle. The previous hook was `preSubscriptionParsing`.
     * This hook will only be triggered when subscriptions are enabled.
     */
    addHook<TContext = MercuriusContext>(name: 'preSubscriptionExecution', hook: preSubscriptionExecutionHookHandler<TContext>): void;
  
    /**
     * `onSubscriptionResolution` is the fourth and final hook to be executed in the GraphQL subscription lifecycle.
     * This hook will only be triggered when subscriptions are enabled.
     */
    addHook<TData extends Record<string, any> = Record<string, any>, TContext = MercuriusContext>(name: 'onSubscriptionResolution', hook: onSubscriptionResolutionHookHandler<TData, TContext>): void;
  
    /**
     * `onSubscriptionEnd` is the fifth and final hook to be executed in the GraphQL subscription lifecycle. The previous hook was `onSubscriptionResolution`.
     * This hook will only be triggered when subscriptions are enabled.
     */
    addHook<TContext = MercuriusContext>(name: 'onSubscriptionEnd', hook: onSubscriptionEndHookHandler<TContext>): void;
  
    // Application lifecycle addHooks
    addHook<TContext = MercuriusContext>(name: 'onExtendSchema', hook: onExtendSchemaHandler<TContext>): void;
  }
  
  interface QueryRequest {
    operationName?: string;
    query: string;
    variables?: object;
    extensions?: object;
  }
  
  interface WsConnectionParams {
    connectionInitPayload?:
      | (() => Record<string, any> | Promise<Record<string, any>>)
      | Record<string, any>;
    reconnect?: boolean;
    maxReconnectAttempts?: number;
    connectionCallback?: () => void;
    failedConnectionCallback?: (err: { message: string }) => void | Promise<void>;
    failedReconnectCallback?: () => void;
    rewriteConnectionInitPayload?:  <TContext extends MercuriusContext = MercuriusContext>(payload: Record<string, any> | undefined, context: TContext) => Record<string, any>;
  }
  
  export interface MercuriusSchemaOptions {
    /**
     * The GraphQL schema. String schema will be parsed
     */
    schema?: GraphQLSchema | string | string[];
    /**
     * Object with resolver functions
     */
    resolvers?: IResolvers;
    /**
     * Object with data loader functions
     */
    loaders?: MercuriusLoaders;
    /**
     * Schema transformation function or an array of schema transformation functions
     */
    schemaTransforms?: ((originalSchema: GraphQLSchema) => GraphQLSchema) | Array<(originalSchema: GraphQLSchema) => GraphQLSchema>;
  }
  
  export interface MercuriusGraphiQLOptions {
    /**
     * Expose the graphiql app, default `true`
     */
    enabled?: boolean;
    /**
     * The list of plugin to add to GraphiQL
     */
    plugins?: Array<{
      /**
       * The name of the plugin, it should be the same exported in the `umd`
       */
      name: string;
      /**
       * The props to be passed to the plugin
       */
      props?: Object;
      /**
       * The urls of the plugin, it's downloaded at runtime. (eg. https://unpkg.com/myplugin/....)
       */
      umdUrl: string;
      /**
       * A function name exported by the plugin to read/enrich the fetch response
       */
      fetcherWrapper?: string;
    }>
  }
  
  export interface GrapQLValidateOptions {
    maxErrors?: number;
  }
  
  export interface MercuriusGraphQLOptions {
    parseOptions?: ParseOptions,
    validateOptions?: GrapQLValidateOptions
  }
  
  export interface MercuriusCommonOptions {
    /**
     * Serve GraphiQL on /graphiql if true or 'graphiql' and if routes is true
     */
    graphiql?: boolean | 'graphiql' | MercuriusGraphiQLOptions;
    ide?: boolean | 'graphiql' | MercuriusGraphiQLOptions;
    /**
     * The minimum number of execution a query needs to be executed before being jit'ed.
     * @default 0 - disabled
     */
    jit?: number;
    /**
     * A graphql endpoint is exposed at /graphql when true
     * @default true
     */
    routes?: boolean;
    /**
     * Define if the plugin can cache the responses.
     * @default true
     */
    cache?: boolean | number;
    /**
     * An endpoint for graphql if routes is true
     * @default '/graphql'
     */
    path?: string;
    /**
     * Change the route prefix of the graphql endpoint if set
     */
    prefix?: string;
    /**
     * Add the empty Mutation definition if schema is not defined
     * @default false
     */
    defineMutation?: boolean;
    /**
     * Change the default error handler (Default: true).
     * If a custom error handler is defined, it should send the standardized response format according to [GraphQL spec](https://graphql.org/learn/serving-over-http/#response) using `reply.send`.
     * @default true
     */
    errorHandler?:
      | boolean
      | ((error: MercuriusError, request: FastifyRequest, reply: FastifyReply) => void | Promise<void>);
    /**
     * Change the default error formatter.
     */
    errorFormatter?: <TContext extends MercuriusContext = MercuriusContext>(
      execution: ExecutionResult & Required<Pick<ExecutionResult, 'errors'>>,
      context: TContext
    ) => {
      statusCode: number;
      response: ExecutionResult | FormattedExecutionResult;
    };
    /**
     * The maximum depth allowed for a single query.
     */
    queryDepth?: number;
    /**
     * GraphQL function optional option overrides
     */
    graphql?: MercuriusGraphQLOptions,
    context?: (
      request: FastifyRequest,
      reply: FastifyReply
    ) => Promise<Record<string, any>> | Record<string, any>;
    /**
     * Optional additional validation rules.
     * Queries must satisfy these rules in addition to those defined by the GraphQL specification.
     */
    validationRules?: ValidationRules;
    /**
     * Enable subscription support when options are provided. [`emitter`](https://github.com/mcollina/mqemitter) property is required when subscriptions is an object. (Default false)
     */
    subscription?:
      | boolean
      | {
          emitter?: object;
          pubsub?: any; // FIXME: Technically this should be the PubSub type. But PubSub is now typed as SubscriptionContext.
          verifyClient?: (
            info: { origin: string; secure: boolean; req: IncomingMessage },
            next: (
              result: boolean,
              code?: number,
              message?: string,
              headers?: OutgoingHttpHeaders
            ) => void
          ) => void;
          context?: (
            socket: WebSocket,
            request: FastifyRequest
          ) => Record<string, any> | Promise<Record<string, any>>;
          onConnect?: (data: {
            type: 'connection_init';
            payload: any;
          }) => any;
          onDisconnect?: (context: MercuriusContext) => void | Promise<void>;
          keepAlive?: number,
          fullWsTransport?: boolean,
        };
    /**
     * Persisted queries, overrides persistedQueryProvider.
     */
    persistedQueries?: Record<string,string>;
    /**
     * Only allow persisted queries. Required persistedQueries, overrides persistedQueryProvider.
     */
    onlyPersisted?: boolean;
    /**
     * Settings for enabling persisted queries.
     */
    persistedQueryProvider?: PersistedQueryProvider;
  
    /**
     * Enable support for batched queries (POST requests only).
     * Batched query support allows clients to send an array of queries and
     * receive an array of responses within a single request.
     */
    allowBatchedQueries?: boolean;

    /**
     * Customize the graphql routers initialized by mercurius with 
     * more fastify route options. 
     * 
     * Usecases:
     * - Add more validation 
     * - change the schema structure 
     * - Hook on the request's life cycle
     * - Increase body size limit for larger queries
    */
    additionalRouteOptions?:Omit<RouteOptions,"handler"|"wsHandler"|"method"|"url">
  }
  
  export type MercuriusOptions = MercuriusCommonOptions & (MercuriusSchemaOptions)

  export interface IResolvers<TSource = any, TContext = MercuriusContext> {
    [key: string]:
      | (() => any)
      | IResolverObject<TSource, TContext>
      | IResolverOptions<TSource, TContext>
      | GraphQLScalarType
      | IEnumResolver
      | undefined;
  }
  
  export type IResolverObject<TSource = any, TContext = MercuriusContext, TArgs = any> = {
    [key: string]:
      | IFieldResolver<TSource, TContext, TArgs>
      | IResolverOptions<TSource, TContext>
      | IResolverObject<TSource, TContext>
      | undefined;
  }
  
  export interface IResolverOptions<TSource = any, TContext = MercuriusContext, TArgs = any> {
    fragment?: string;
    resolve?: IFieldResolver<TSource, TContext, TArgs>;
    subscribe?: IFieldResolver<TSource, TContext, TArgs>;
  }
  
  type IEnumResolver = {
    [key: string]: string | number;
  };
  
  export interface IFieldResolver<TSource, TContext = MercuriusContext, TArgs = Record<string, any>> {
    (
      source: TSource,
      args: TArgs,
      context: TContext,
      info: GraphQLResolveInfo & {
        mergeInfo?: MergeInfo;
      }
    ): any;
  }
  
  type MergeInfo = {
    delegate: (
      type: "query" | "mutation" | "subscription",
      fieldName: string,
      args: {
        [key: string]: any;
      },
      context: {
        [key: string]: any;
      },
      info: GraphQLResolveInfo,
      transforms?: Array<Transform>
    ) => any;
    delegateToSchema<TContext>(options: IDelegateToSchemaOptions<TContext>): any;
    fragments: Array<{
      field: string;
      fragment: string;
    }>;
  };
  
  type Transform = {
    transformSchema?: (schema: GraphQLSchema) => GraphQLSchema;
    transformRequest?: (originalRequest: Request) => Request;
    transformResult?: (result: Result) => Result;
  };
  
  interface IDelegateToSchemaOptions<
    TContext = {
      [key: string]: any;
    }
  > {
    schema: GraphQLSchema;
    operation: Operation;
    fieldName: string;
    args?: {
      [key: string]: any;
    };
    context: TContext;
    info: IGraphQLToolsResolveInfo;
    transforms?: Array<Transform>;
    skipValidation?: boolean;
  }
  
  type Operation = "query" | "mutation" | "subscription";
  
  type Result = ExecutionResult & {
    extensions?: Record<string, any>;
  };
  
  interface IGraphQLToolsResolveInfo extends GraphQLResolveInfo {
    mergeInfo?: MergeInfo;
  }
  
  type Request = {
    document: DocumentNode;
    variables: Record<string, any>;
    extensions?: Record<string, any>;
  };
  
  type ValidationRules =
    | ValidationRule[]
    | ((params: {
        source: string;
        variables?: Record<string, any>;
        operationName?: string;
      }) => ValidationRule[]);
  
  export interface PreExecutionHookResponse<TError extends Error> {
    schema?: GraphQLSchema
    document?: DocumentNode
    errors?: TError[],
    variables?: Record<string, any>,
  }

  export interface PersistedQueryProvider {
    /**
     *  Return true if a given request matches the desired persisted query format.
     */
    isPersistedQuery: (r: QueryRequest) => boolean;
    /**
     *  Return the hash from a given request, or falsy if this request format is not supported.
     */
    getHash: (r: QueryRequest) => string;
    /**
     *  Return the query for a given hash.
     */
    getQueryFromHash: (hash: string) => Promise<string>;
    /**
     *  Return the hash for a given query string. Do not provide if you want to skip saving new queries.
     */
    getHashForQuery?: (query: string) => string;
    /**
     *  Save a query, given its hash.
     */
    saveQuery?: (hash: string, query: string) => Promise<void>;
    /**
     * An error message to return when getQueryFromHash returns a falsy result. Defaults to 'Bad Request'.
     */
    notFoundError?: string;
    /**
     * An error message to return when a query matches isPersistedQuery, but fasly from getHash. Defaults to 'Bad Request'.
     */
    notSupportedError?: string;
  }

  /**
   * @deprecated Use `PersistedQueryProvider`
   */
  export interface PeristedQueryProvider extends PersistedQueryProvider {}

  /**
   * Extended errors for adding additional information in error responses
   */
  export class ErrorWithProps extends Error {
    constructor(message: string, extensions?: object, statusCode?: number);
    /**
     * Custom additional properties of this error
     */
    extensions?: object;
    statusCode?: number;
  }

  /**
   * Default options for persisted queries.
   */
  export const persistedQueryDefaults: {
    prepared: (persistedQueries: object) => PersistedQueryProvider;
    preparedOnly: (persistedQueries: object) => PersistedQueryProvider;
    automatic: (maxSize?: number) => PersistedQueryProvider;
  };

  /**
   * Default error formatter.
   */
  export const defaultErrorFormatter: (
    execution: ExecutionResult & Required<Pick<ExecutionResult, 'errors'>>,
    context: MercuriusContext
  ) => { statusCode: number; response: FormattedExecutionResult };

  /**
   * Subscriptions with filter functionality
   */
  export const withFilter: <
    TPayload = any,
    TSource = any,
    TContext = MercuriusContext,
    TArgs = Record<string, any>
  >(
    subscribeFn: IFieldResolver<TSource, TContext, TArgs>,
    filterFn: (
      payload: TPayload,
      args: TArgs,
      context: TContext,
      info: GraphQLResolveInfo & {
        mergeInfo?: MergeInfo
      }
    ) => boolean | Promise<boolean>
  ) => (
    root: TSource,
    args: TArgs,
    context: TContext,
    info: GraphQLResolveInfo & {
      mergeInfo?: MergeInfo
    }
  ) => AsyncGenerator<TPayload>

  // named export
  // import { mercurius } from 'mercurius'
  // const { mercurius } = require('mercurius')
  export const mercurius: Mercurius
  // default export
  // import mercurius from 'mercurius'
  export { mercurius as default }
}

declare module "fastify" {
  interface FastifyInstance {
    /**
     * GraphQL plugin
     */
    graphql: mercurius.MercuriusPlugin;
  }

  interface FastifyReply {
    /**
     * @param source GraphQL query string
     * @param context request context
     * @param variables request variables which will get passed to the executor
     * @param operationName specify which operation will be run
     */
    graphql<
      TData extends Record<string, any> = Record<string, any>,
      TVariables extends Record<string, any> = Record<string, any>
    >(
      source: string,
      context?: Record<string, any>,
      variables?: TVariables,
      operationName?: string
    ): Promise<ExecutionResult<TData>>;
  }
}

/**
 * Mercurius GraphQL adapter function for a Fastify server instance.
 *
 * @param instance Fastify server instance
 * @param opts Mercurius options
 */
declare function mercurius
  (
    instance: FastifyInstance,
    opts: mercurius.MercuriusOptions
  ): void;


// CJS export
// const mercurius = require('mercurius')
export = mercurius;