graphql-yoga

const createLRUCache: <T extends {}>({
    max,
    ttl,
}?: _LRUCacheOptions) => LRU<string, T, unknown>;

const defaultGenerateRequestId: GenerateRequestIdFn<any>;

const defaultRequestIdHeader: string;

const maskError: MaskError;

createLoggerFromLogging: (
    logging: boolean | Logger | LogLevel | undefined
) => Logger;

createSchema: <TContext = {}>(
    opts: IExecutableSchemaDefinition<TContext & YogaInitialContext>
) => GraphQLSchemaWithContext<TContext & YogaInitialContext>;

createYoga: <
    TServerContext extends Record<string, any> = {},
    TUserContext extends Record<string, any> = {}
>(
    options: YogaServerOptions<TServerContext, TUserContext>
) => ServerAdapter<TServerContext, YogaServer<TServerContext, TUserContext>>;

getRequestId: (
    headerValue: string | null | undefined,
    generateId: () => string
) => string;

getSSEProcessor: () => ResultProcessor;

processRegularResult: (
    executionResult: ResultProcessorInput,
    fetchAPI: FetchAPI,
    acceptedHeader: string
) => Response;

renderGraphiQL: (opts: GraphiQLOptions) => string;

shouldRenderGraphiQL: ({ headers, method }: Request) => boolean;

useConfigInServerContext: ({
    configContext,
}: ConfigInServerContextOptions) => Plugin;

useErrorCoordinate: () => Plugin;

useExecutionCancellation: () => Plugin;

useReadinessCheck: ({ endpoint, check }: ReadinessCheckPluginOptions) => Plugin;

useRequestId: <TServerContext extends Record<string, any>>(
    opts?: RequestIdOptions<TServerContext>
) => Plugin<{}, TServerContext>;

useSchema: <TServerContext = {}, TUserContext = {}>(schemaDef?: any) => any;

withSchemaCoordinate: (
    error: GraphQLError,
    coordinate: string | undefined
) => GraphQLError;

type BatchingOptions =
    | boolean
    | {
          /**
           * You can limit the number of batched operations per request.
           *
           * @default 10
           */
          limit?: number;
      };

type CORSOptions =
    | {
          origin?: string[] | string;
          methods?: string[];
          allowedHeaders?: string[];
          exposedHeaders?: string[];
          credentials?: boolean;
          maxAge?: number;
      }
    | false;

type FetchAPI = ReturnType<typeof createFetch>;

type GenerateRequestIdFn<TContext> = (
    payload: GenerateRequestIdPayload<TContext>
) => string;

type GraphiQLOptions = {
    /**
     * Headers to be set when opening a new tab
     */
    defaultHeaders?: string;
    /**
     * An optional GraphQL string to use when no query is provided and no stored
     * query exists from a previous session.  If undefined is provided, GraphiQL
     * will use its own default query.
     */
    defaultQuery?: string;
    /**
     * This prop can be used to define the default set of tabs, with their
     * queries, variables, and headers. It will be used as default only if there
     * is no tab state persisted in storage.
     */
    defaultTabs?: TabDefinition[];
    /**
     * The initial headers to render inside the header editor. Defaults to `"{}"`.
     * The value should be a JSON encoded string, for example:
     * `headers: JSON.stringify({Authorization: "Bearer your-auth-key"})`
     */
    headers?: string;
    /**
     * This prop toggles if the contents of the headers editor are persisted in
     * storage.
     */
    shouldPersistHeaders?: boolean | undefined;
    /**
     * More info there: https://developer.mozilla.org/en-US/docs/Web/API/Request/credentials
     */
    credentials?: RequestCredentials;
    /**
     * The favicon URL to display for the page. Defaults to Yoga logo.
     */
    favicon?: string;
    /**
     * The title to display at the top of the page. Defaults to `"Yoga GraphiQL"`.
     */
    title?: string;
    /**
     * Logo to be displayed in the top right corner of GraphiQL.
     */
    logo?: string;
    /**
     * Protocol for subscriptions
     */
    subscriptionsProtocol?: 'SSE' | 'GRAPHQL_SSE' | 'WS' | 'LEGACY_WS';
    /**
     * Extra headers you always want to pass with users' headers input
     */
    additionalHeaders?: Record<string, string>;
    /**
     * HTTP method to use when querying the original schema.
     */
    method?: 'GET' | 'POST';
    /**
     * Whether to use the GET HTTP method for queries when querying the original schema
     */
    useGETForQueries?: boolean;
    /**
     * "external" fragments that will be included in the query document (depending on usage)
     */
    externalFragments?: string;
    /**
     * The maximum number of executed operations to store.
     * @default 20
     */
    maxHistoryLength?: number;
    /**
     * Whether target GraphQL server support deprecation of input values.
     * @default false
     */
    inputValueDeprecation?: boolean;
    /**
     * Custom operation name for the introspection query.
     */
    introspectionQueryName?: string;
    /**
     * Whether to include schema description in introspection query.
     * @default false
     */
    schemaDescription?: boolean;
    /**
     * Editor theme
     * @default "graphiql"
     */
    editorTheme?: string;
    /**
     *  Sets the key map to use when using the editor.
     * @default 'sublime'
     */
    keyMap?: 'sublime' | 'emacs' | 'vim';
    defaultEditorToolsVisibility?: boolean | 'variables' | 'headers';
    isHeadersEditorEnabled?: boolean;
    disableTabs?: boolean;
    /**
     * Whether to include `isRepeatable` flag on directives.
     * @default false
     */
    directiveIsRepeatable?: boolean;
    experimentalFragmentVariables?: boolean;
    /**
     * Set to `true` in order to convert all GraphQL comments (marked with # sign) to descriptions (""")
     * GraphQL has built-in support for transforming descriptions to comments (with `print`), but not while
     * parsing. Turning the flag on will support the other way as well (`parse`)
     */
    commentDescriptions?: boolean;
    /**
     * Timeout in milliseconds
     */
    timeout?: number;
    /**
     * Retry attempts
     */
    retry?: number;
    /**
     * The endpoint requests should be sent.
     * Defaults to the graphql endpoint ("/graphql" by default).
     */
    endpoint?: string;
};

type GraphiQLOptionsOrFactory<TServerContext> =
    | GraphiQLOptions
    | GraphiQLOptionsFactory<TServerContext>
    | boolean;

type GraphiQLRenderer = (options: GraphiQLOptions) => PromiseOrValue<BodyInit>;

type GraphQLSchemaWithContext<TContext> = GraphQLSchema & {
    _context?: TContext;
};

type Instrumentation<TContext extends Record<string, any>> =
    EnvelopInstrumentation<TContext> &
        ServerAdapterInstrumentation & {
            operation?: (
                payload: {
                    context: TContext;
                    request: Request;
                },
                wrapped: () => PromiseOrValue<void>
            ) => PromiseOrValue<void>;
            requestParse?: (
                payload: {
                    request: Request;
                },
                wrapped: () => MaybePromise<void>
            ) => MaybePromise<void>;
            resultProcess?: (
                payload: {
                    request: Request;
                },
                wrapped: () => MaybePromise<void>
            ) => MaybePromise<void>;
        };

type LandingPageRenderer = (
    opts: LandingPageRendererOpts
) => PromiseOrValue<Response>;

type MaskError = (
    error: unknown,
    message: string,
    isDev?: boolean,
    /**
     * The context of the request that caused the error, so a masked error (and any logging
     * around it) can be correlated with - and informed by - the request, e.g. its `log`ger,
     * headers or authenticated user. Passed by whichever caller has it: `handleError` (error.ts)
     * for the HTTP path, or envelop's `useMaskedErrors` itself for subscription/streaming errors
     * (it gets one from the context it's given at the point of the call). May be partial, or
     * unset entirely, for an error before a full context could be built.
     */
    context?: Partial<YogaInitialContext> & YogaConfigContext
) => Error;

type MaybeArray<T> = T | T[];

type Plugin<
    PluginContext extends Record<string, any> = {},
    TServerContext extends Record<string, any> = {},
    TUserContext = {}
> = EnvelopPlugin<YogaInitialContext & PluginContext> &
    ServerAdapterPlugin<TServerContext & YogaConfigContext> & {
        /**
         * onExecute hook that is invoked before the execute function is invoked.
         */
        onExecute?: OnExecuteHook<YogaInitialContext & PluginContext & TUserContext>;
        /**
         * onSubscribe hook that is invoked before the subscribe function is called.
         * Return a OnSubscribeHookResult for hooking into phase after the subscribe function has been called.
         */
        onSubscribe?: OnSubscribeHook<
            YogaInitialContext & PluginContext & TUserContext
        >;
        /**
         * Invoked when a plugin is initialized. You can use this hook to add other plugin you may depend on.
         */
        onPluginInit?: OnPluginInitHook<
            YogaInitialContext & PluginContext & TUserContext
        >;
    } & {
        /**
         * A Tracer instance that will wrap each phases of the request pipeline.
         * This should be used primarly as an observability tool (for monitoring, tracing, etc...).
         */
        instrumentation?: Instrumentation<
            YogaInitialContext & PluginContext & TUserContext
        >;
        /**
         * This hook is invoked at Yoga Server initialization, before it starts.
         * Here you can setup long running resources (like monitoring or caching clients)
         * or customize the Yoga instance.
         */
        onYogaInit?: OnYogaInitHook<TServerContext>;
        /**
         * This hook is invoked for any incoming GraphQL HTTP request and is invoked before attempting
         * to parse the GraphQL parameters. Here you can manipulate the request, set a custom request
         * parser or apply security measures such as checking for access tokens etc.
         */
        onRequestParse?: OnRequestParseHook<TServerContext>;
        /**
         * This hook is invoked for an incoming GraphQL request after the GraphQL parameters
         * (query, variables, extensions and operationName) have been ATTEMPTED to be parsed.
         *
         * Within this hook you can manipulate and customize the parameters or even implement a whole
         * new way of parsing the parameters.
         *
         * In addition to that you could also short-circuit and skip the GraphQL execution.
         */
        onParams?: OnParamsHook<TServerContext>;
        /**
         * This hook is invoked for each result produced for GraphQL operation, before it is processed
         * to be sent to client.
         *
         * In particular, if a request contains batched operations, this hook is called once of each
         * operation.
         *
         * Here, you can modify the result, to add monitoring or instrumentation extensions for example.
         */
        onExecutionResult?: OnExecutionResultHook<TServerContext>;
        /**
         * This hook is invoked after a GraphQL request has been processed and before the response is
         * forwarded to the client. Here you can customize what transport/response processor format
         * should be used for sending the result over the wire.
         */
        onResultProcess?: OnResultProcess<TServerContext>;
    };

type YogaConfigContext = {
    /**
     * The logger to use throughout Yoga and its plugins.
     *
     * Within a request, this is a request-scoped child logger carrying a `requestId` attribute,
     * so every log line produced while handling that request can be correlated together.
     */
    log: Logger;
};

type YogaMaskedErrorOpts = {
    maskError: MaskError;
    errorMessage: string;
    isDev?: boolean;
};

type YogaSchemaDefinition<TServerContext, TUserContext> =
    | PromiseOrValue<
          GraphQLSchemaWithContext<
              TServerContext & YogaInitialContext & TUserContext
          >
      >
    | ((
          context: TServerContext & {
              request: YogaInitialContext['request'];
          }
      ) => PromiseOrValue<
          GraphQLSchemaWithContext<
              TServerContext & YogaInitialContext & TUserContext
          >
      >);

type YogaServerInstance<
    TServerContext extends Record<string, any>,
    TUserContext extends Record<string, any>
> = ServerAdapter<TServerContext, YogaServer<TServerContext, TUserContext>>;

type YogaServerOptions<TServerContext, TUserContext> = Omit<
    ServerAdapterOptions<TServerContext>,
    'plugins'
> & {
    /**
     * Enable, disable or implement a custom logger for logging.
     *
     * @default true
     *
     * @see https://the-guild.dev/graphql/yoga-server/docs/features/logging-and-debugging
     */
    logging?: boolean | Logger | LogLevel | undefined;
    /**
     * Enable, disable or configure the request id.
     *
     * A request id the host integration already assigned to the native request object (e.g.
     * Fastify's `request.id`) is reused first, if there is one; otherwise, the `x-request-id`
     * header of the incoming request is used if present (see `trustHeader`); otherwise, one is
     * generated. It is added to the `log`ger available in the context as the `requestId`
     * attribute, and set on the outgoing response's headers.
     *
     * @default true
     */
    requestId?: boolean | RequestIdOptions<TServerContext> | undefined;
    /**
     * Prevent leaking unexpected errors to the client. We highly recommend enabling this in production.
     * If you throw `EnvelopError`/`GraphQLError` within your GraphQL resolvers then that error will be sent back to the client.
     *
     * You can lean more about this here:
     * @see https://the-guild.dev/graphql/yoga-server/docs/features/error-masking
     *
     * @default true
     */
    maskedErrors?: boolean | Partial<YogaMaskedErrorOpts> | undefined;
    /**
     * Context
     */
    context?:
        | ((
              initialContext: YogaInitialContext & TServerContext
          ) => Promise<TUserContext> | TUserContext)
        | Promise<TUserContext>
        | TUserContext
        | undefined;
    cors?: Parameters<typeof useCORS>[0] | undefined;
    /**
     * GraphQL endpoint
     * So you need to define it explicitly if GraphQL API lives in a different path other than `/graphql`
     *
     * @default "/graphql"
     */
    graphqlEndpoint?: string | undefined;
    /**
     * Readiness check endpoint
     *
     * @default "/health"
     */
    healthCheckEndpoint?: string | undefined;
    /**
     * Whether the landing page should be shown.
     */
    landingPage?: boolean | LandingPageRenderer | undefined;
    /**
     * GraphiQL options
     *
     * @default true
     */
    graphiql?: GraphiQLOptionsOrFactory<TServerContext> | undefined;
    renderGraphiQL?:
        | ((options: GraphiQLOptions) => PromiseOrValue<BodyInit>)
        | undefined;
    schema?: YogaSchemaDefinition<TServerContext, TUserContext> | undefined;
    /**
     * Envelop Plugins
     * @see https://envelop.dev/plugins
     */
    plugins?:
        | Array<
              | Plugin<TUserContext & TServerContext & YogaInitialContext>
              | Plugin
              | {}
          >
        | undefined;
    parserAndValidationCache?: boolean | ParserAndValidationCacheOptions | undefined;
    fetchAPI?: Partial<Record<keyof FetchAPI, any>> | undefined;
    /**
     * GraphQL Multipart Request spec support
     *
     * @see https://github.com/jaydenseric/graphql-multipart-request-spec
     *
     * @default true
     */
    multipart?: boolean | undefined;
    id?: string | undefined;
    /**
     * Limit the size (in bytes) of the incoming HTTP request body that will be read by the
     * built-in request parsers (JSON, GraphQL string, url-encoded and multipart).
     *
     * Requests whose `Content-Length` exceeds this value (or whose `Content-Length` is invalid)
     * are rejected with an HTTP 413/400 response before the body is read. Bodies are also counted
     * while streaming, so requests with a missing, wrong, or chunked-transfer-encoded body cannot
     * bypass the limit.
     *
     * Set to `false` to disable the limit. This is not recommended unless an upstream reverse
     * proxy already enforces a body-size limit (e.g. nginx's `client_max_body_size`).
     *
     * @default 25_000_000 (25 MB)
     */
    maxRequestBodySize?: number | false | undefined;
    /**
     * Batching RFC Support configuration
     *
     * @see https://github.com/graphql/graphql-over-http/blob/main/rfcs/Batching.md
     *
     * @default false
     */
    batching?: BatchingOptions | undefined;
    /**
     * By default, GraphQL Yoga does not allow parameters in the request body except `query`, `variables`, `extensions`, and `operationName`.
     *
     * This option allows you to specify additional parameters that are allowed in the request body.
     *
     * @default []
     *
     * @example ['doc_id', 'id']
     */
    extraParamNames?: string[] | undefined;
    /**
     * Allowed headers. Headers not part of this list will be striped out.
     */
    allowedHeaders?: {
        /** Allowed headers for outgoing responses */
        response?: string[] | undefined;
        /** Allowed headers for ingoing requests */
        request?: string[] | undefined;
    };
};