@envelop/response-cache 3.0.1 → 3.0.2-alpha-1eb54ef.0

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@envelop/response-cache",
-  "version": "3.0.1",
+  "version": "3.0.2-alpha-1eb54ef.0",
   "sideEffects": false,
   "peerDependencies": {
-    "@envelop/core": "^2.4.1",
+    "@envelop/core": "2.4.2-alpha-1eb54ef.0",
     "graphql": "^14.0.0 || ^15.0.0 || ^16.0.0"
   },
   "dependencies": {
@@ -28,7 +28,7 @@
   "exports": {
     ".": {
       "require": {
-        "types": "./typings/index.d.ts",
+        "types": "./typings/index.d.cts",
         "default": "./cjs/index.js"
       },
       "import": {
@@ -42,7 +42,7 @@
     },
     "./*": {
       "require": {
-        "types": "./typings/*.d.ts",
+        "types": "./typings/*.d.cts",
         "default": "./cjs/*.js"
       },
       "import": {

package/typings/cache-document-str.d.cts

@@ -0,0 +1,4 @@
+import { ExecutionArgs } from 'graphql';
+import { Plugin } from '@envelop/core';
+export declare function useCacheDocumentString(): Plugin;
+export declare function defaultGetDocumentString(executionArgs: ExecutionArgs): string;

package/typings/cache.d.cts

@@ -0,0 +1,25 @@
+import type { Maybe, PromiseOrValue } from '@envelop/core';
+import type { ExecutionResult } from 'graphql';
+export declare type CacheEntityRecord = {
+    typename: string;
+    id?: number | string;
+};
+/**
+ * Interface for implementing a cache that will be used for `useResponseCache`.
+ */
+export declare type Cache = {
+    /** set a cache response */
+    set(
+    /** id/hash of the operation */
+    id: string, 
+    /** the result that should be cached */
+    data: ExecutionResult, 
+    /** array of entity records that were collected during execution */
+    entities: Iterable<CacheEntityRecord>, 
+    /** how long the operation should be cached */
+    ttl: number): PromiseOrValue<void>;
+    /** get a cached response */
+    get(id: string): PromiseOrValue<Maybe<ExecutionResult>>;
+    /** invalidate operations via typename or id */
+    invalidate(entities: Iterable<CacheEntityRecord>): PromiseOrValue<void>;
+};

package/typings/hash-sha256.d.cts

@@ -0,0 +1 @@
+export declare const hashSHA256: (text: string) => Promise<string>;

package/typings/in-memory-cache.d.cts

@@ -0,0 +1,15 @@
+import type { Cache } from './cache.cjs';
+export declare type BuildEntityId = (typename: string, id: number | string) => string;
+export declare type InMemoryCacheParameter = {
+    /**
+     * Maximum amount of items in the cache. Defaults to `Infinity`.
+     */
+    max?: number;
+    /**
+     * Customize how the cache entity id is built.
+     * By default the typename is concatenated with the id e.g. `User:1`
+     */
+    buildEntityId?: BuildEntityId;
+};
+export declare const createInMemoryCache: (params?: InMemoryCacheParameter) => Cache;
+export declare const defaultBuildEntityId: BuildEntityId;

package/typings/index.d.cts

@@ -0,0 +1,3 @@
+export * from './in-memory-cache.cjs';
+export * from './plugin.cjs';
+export * from './cache.cjs';

package/typings/plugin.d.cts

@@ -0,0 +1,122 @@
+import { Plugin, Maybe } from '@envelop/core';
+import { ExecutionArgs, ExecutionResult } from 'graphql';
+import type { Cache } from './cache.cjs';
+/**
+ * Function for building the response cache key based on the input parameters
+ */
+export declare 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>;
+}) => Promise<string>;
+export declare type GetDocumentStringFunction = (executionArgs: ExecutionArgs) => string;
+export declare type ShouldCacheResultFunction = (params: {
+    result: ExecutionResult;
+}) => Boolean;
+export declare 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
+     *
+     * **Global Example:**
+     * ```ts
+     * useResponseCache({
+     *   session: () => null,
+     * });
+     * ```
+     *
+     * **User Specific with global fallback example:**
+     * ```ts
+     * useResponseCache({
+     *   session: (context) => context.user?.id ?? null,
+     * });
+     * ```
+     */
+    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 execution arguments.
+     * By default, the useResponseCache plugin hooks into onParse and caches the original operation string in a WeakMap.
+     * 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 `defaultGetDocumentString`
+     *
+     */
+    getDocumentString?: GetDocumentStringFunction;
+    /**
+     * 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 function useResponseCache({ cache, ttl: globalTtl, session, enabled, ignoredTypes, ttlPerType, ttlPerSchemaCoordinate, idFields, invalidateViaMutation, buildResponseCacheKey, getDocumentString, shouldCacheResult, includeExtensionMetadata, }: UseResponseCacheParameter): Plugin;