`prisma-redis-middleware`

This is a Prisma middleware used for caching and storing of Prisma queries in Redis (uses an in-memory LRU cache as fallback storage).

Uses async-cache-dedupe.

Features

Cache Invalidation
Supports custom cache keys
Cache persistance with Redis (uses an in-memory LRU cache as fallback)
Caching multiple Prisma models each with a specific cache time
Excluding certain Prisma models from being cached
Excluding certain Prisma queries from being cached across all models

Supported Node.js versions

The latest versions of the following Node.js versions are tested and supported.

Default Cached Methods

Here is a list of all the Prisma methods that are currently cached by default in prisma-redis-middleware.

findUnique
findUniqueOrThrow
findFirst
findFirstOrThrow
findMany
count
aggregate
groupBy
findRaw
aggregateRaw

queryRaw is not cached as it's executed against the Prisma db itself and not a model. This Prisma middleware is used for caching queries based on the models that they are executed against.

Quick Start

Install the package using npm:

npm i --save-exact prisma-redis-middleware

You will also need to install and configure an external dependency for Redis (for example: ioredis or one that uses a similar API) if you don't already have a Redis Client in your project.

npm i --save-exact ioredis @types/ioredis

Code Example (ESM / Import)

import Prisma from "prisma";
import { PrismaClient } from "@prisma/client";
import { createPrismaRedisCache } from "prisma-redis-middleware";
import Redis from "ioredis";

const redis = new Redis(); // Uses default options for Redis connection

const prisma = new PrismaClient();

const cacheMiddleware: Prisma.Middleware = createPrismaRedisCache({
  models: [
    { model: "User", excludeMethods: ["findMany"] },
    { model: "Post", cacheTime: 180, cacheKey: "article" },
  ],
  storage: { type: "redis", options: { client: redis, invalidation: { referencesTTL: 300 }, log: console } },
  cacheTime: 300,
  excludeModels: ["Product", "Cart"],
  excludeMethods: ["count", "groupBy"],
  onHit: (key) => {
    console.log("hit", key);
  },
  onMiss: (key) => {
    console.log("miss", key);
  },
  onError: (key) => {
    console.log("error", key);
  },
});

prisma.$use(cacheMiddleware);

Code Example (Common JS / Require)

const Prisma = require("prisma");
const { PrismaClient } = require("@prisma/client");
const { createPrismaRedisCache } = require("prisma-redis-middleware");

const prisma = new PrismaClient();

const cacheMiddleware: Prisma.Middleware = createPrismaRedisCache({
  models: [
    { model: "User", cacheTime: 60 },
    { model: "Post", cacheTime: 180 },
  ],
  storage: { type: "memory", options: { invalidation: true, log: console } },
  cacheTime: 300,
  onHit: (key) => {
    console.log("hit", key);
  },
  onMiss: (key) => {
    console.log("miss", key);
  },
  onError: (key) => {
    console.log("error", key);
  },
});

prisma.$use(cacheMiddleware);

API

`createPrismaRedisCache(opts)`

Options:

onDedupe: (optional) a function that is called every time a query is deduped.
onError: (optional) a function that is called every time there is a cache error.
onHit: (optional) a function that is called every time there is a hit in the cache.
onMiss: (optional) a function that is called every time the result is not in the cache.
cacheTime: (optional) (number) the default time (in seconds) to use for models that don't have a cacheTime value set. Default is 0.
excludeModels: (optional) (string) an array of models to exclude from being cached.
excludeMethods: (optional) (string) an array of Prisma methods to exclude from being cached for all models.
models: (optional) an array of Prisma models. Models options are:
- model: (required) string.
- cacheKey: (optional) string. Default is the model value.
- cacheTime: (optional) number (in seconds).
- excludeMethods: (optional) (string) an array of Prisma methods to exclude from being cached for this model.
- invalidateRelated: (optional) (string) an array of Prisma models to invalidate when mutating this model.
  
  Example:
```
createPrismaRedisCache({
  models: [
    { model: "User", cacheTime: 60, invalidateRelated: ["Post"] },
    { model: "Post", cacheKey: "article", excludeMethods: ["findFirst"] },
  ],
});
```
storage: (optional) the storage options; default is { type: "memory" }. Storage options are:
- type: memory (default) or redis
- options: by storage type
  - for memory type
    - size: (optional) maximum number of items to store in the cache. Default is 1024.
    - invalidation: (optional) enable invalidation. Default is disabled.
    - log: (optional) logger instance pino compatible, or console, default is disabled.
    Example:
```
createPrismaRedisCache({
  storage: { type: "memory", options: { size: 2048 }, log: console },
});
```
  - for redis type
    - client: a redis client instance, mandatory. Should be an ioredis client or compatible.
    - invalidation: (optional) enable invalidation. Default is disabled.
    - invalidation.referencesTTL: (optional) references TTL in seconds, it means how long the references are alive; it should be set at the maximum of all the caches ttl.
    - log: (optional) logger instance pino compatible, or console, default is disabled.
    Example
```
const redis = new Redis();

createPrismaRedisCache({
  storage: {
    type: "redis",
    options: { client: redis, invalidation: { referencesTTL: 60 }, log: console },
  },
});
```
transformer: (optional) the transformer to used to serialize and deserialize the cache entries. It must be an object with the following methods:
- serialize: a function that receives the result of the original function and returns a serializable object.
- deserialize: a function that receives the serialized object and returns the original result.
- Default is undefined, so the default transformer is used.
  
  Example
```
import superjson from "superjson";

createPrismaRedisCache({
  transformer: {
    serialize: (result) => superjson.serialize(result),
    deserialize: (serialized) => superjson.deserialize(serialized),
  },
});
```

Debugging

You can pass functions for onMiss, onHit, onError and onDedupe to createPrismaRedisCache which can then be used to debug whether a Prisma query is being cached or not.

You can also pass a custom log (pino or console) to the storage option and async-cache-dedupe will print debug info as it queries, sets, expires and invalidates the cache. Note that the log option can print out very verbose output.

cloverink / prisma-redis-middleware