@soundxyz/response-cache/dist/plugin/plugin.d.ts

Heavily inspired by @envelop/response-cache

import { Plugin, Maybe, DefaultContext } from "@envelop/core";
import { ExecutionArgs, ExecutionResult } from "graphql";
import type { Cache } from "./cache";
/**
 * Function for building the response cache key based on the input parameters
 */
export type BuildResponseCacheKeyFunction = (params: {
    /** Raw document string as sent from the client. */
    documentString: string;
    /** Variable values as sent form the client. */
    variableValues: ExecutionArgs["variableValues"];
    /** The name of the GraphQL operation that should be executed from within the document. */
    operationName?: Maybe<string>;
    /** optional sessionId for make unique cache keys based on the session.  */
    sessionId?: Maybe<string>;
}) => string;
export type GetDocumentStringFromContextFunction = (params: DefaultContext) => Maybe<string>;
export type ShouldCacheResultFunction = (params: {
    result: ExecutionResult;
}) => Boolean;
export type UseResponseCacheParameter<C = any> = {
    cache: Cache;
    /**
     * Maximum age in ms. Defaults to `Infinity`. Set it to 0 for disabling the global TTL.
     */
    ttl?: number;
    /**
     * Overwrite the ttl for query operations whose execution result contains a specific object type.
     * Useful if the occurrence of a object time in the execution result should reduce or increase the TTL of the query operation.
     * The TTL per type is always favored over the global TTL.
     */
    ttlPerType?: Record<string, number>;
    /**
     * Overwrite the ttl for query operations whose selection contains a specific schema coordinate (e.g. Query.users).
     * Useful if the selection of a specific field should reduce the TTL of the query operation.
     *
     * The default value is `{}` and it will be merged with a `{ 'Query.__schema': 0 }` object.
     * In the unusual case where you actually want to cache introspection query operations,
     * you need to provide the value `{ 'Query.__schema': undefined }`.
     */
    ttlPerSchemaCoordinate?: Record<string, number | undefined>;
    /**
     * Allows to cache responses based on the resolved session id.
     * Return a unique value for each session.
     * Return `null` or `undefined` to mark the session as public/global.
     * Creates a global session by default.
     * @param context GraphQL Context
     */
    session?(context: C): string | undefined | null;
    /**
     * Specify whether the cache should be used based on the context.
     * By default any request uses the cache.
     */
    enabled?(context: C): boolean;
    /**
     * Skip caching of following the types.
     */
    ignoredTypes?: string[];
    /**
     * List of fields that are used to identify a entity.
     * Defaults to `["id"]`
     */
    idFields?: Array<string>;
    /**
     * Whether the mutation execution result should be used for invalidating resources.
     * Defaults to `true`
     */
    invalidateViaMutation?: boolean;
    /**
     * Customize the behavior how the response cache key is computed from the document, variable values and sessionId.
     * Defaults to `defaultBuildResponseCacheKey`
     */
    buildResponseCacheKey?: BuildResponseCacheKeyFunction;
    /**
     * Function used for reading the document string that is used for building the response cache key from the context object.
     * By default, the useResponseCache plugin hooks into onParse and writes the original operation string to the context.
     * If you are hard overriding parse you need to set this function, otherwise responses will not be cached or served from the cache.
     * Defaults to `defaultGetDocumentStringFromContext`
     */
    getDocumentStringFromContext?: GetDocumentStringFromContextFunction;
    /**
     * Include extension values that provide useful information, such as whether the cache was hit or which resources a mutation invalidated.
     * Defaults to `true` if `process.env["NODE_ENV"]` is set to `"development"`, otherwise `false`.
     */
    includeExtensionMetadata?: boolean;
    /**
     * Checks if the execution result should be cached or ignored. By default, any execution that
     * raises any error, unexpected ot EnvelopError or GraphQLError are ignored.
     * Use this function to customize the behavior, such as caching results that have an EnvelopError.
     */
    shouldCacheResult?: ShouldCacheResultFunction;
};
/**
 * Default function used for building the response cache key.
 * It is exported here for advanced use-cases. E.g. if you want to short circuit and serve responses from the cache on a global level in order to completely by-pass the GraphQL flow.
 */
export declare const defaultBuildResponseCacheKey: BuildResponseCacheKeyFunction;
/**
 * Default function used to check if the result should be cached.
 *
 * It is exported here for advanced use-cases. E.g. if you want to choose if
 * results with certain error types should be cached.
 *
 * By default, results with errors (unexpected, EnvelopError, or GraphQLError) are not cached.
 */
export declare const defaultShouldCacheResult: ShouldCacheResultFunction;
export declare const defaultGetDocumentStringFromContext: GetDocumentStringFromContextFunction;
export interface ResponseCacheContext {
    $responseCache?: {
        setExpiry(args: {
            /**
             * TTL in milliseconds
             */
            ttl: number;
        }): void;
        getExpiry(): number;
    };
}
export declare function useResponseCache({ cache, ttl: globalTtl, session, enabled, ignoredTypes, ttlPerType, ttlPerSchemaCoordinate, idFields, invalidateViaMutation, buildResponseCacheKey, getDocumentStringFromContext, shouldCacheResult, includeExtensionMetadata, }: UseResponseCacheParameter): Plugin<any>;