@blacklizard/inertia-cache-redis 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 blacklizard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# @blacklizard/inertia-cache-redis
+
+[![CI](https://github.com/blacklizard/inertia-express/actions/workflows/ci.yml/badge.svg)](https://github.com/blacklizard/inertia-express/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@blacklizard/inertia-cache-redis.svg)](https://www.npmjs.com/package/@blacklizard/inertia-cache-redis)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js >= 24](https://img.shields.io/badge/node-%3E%3D24-brightgreen)](https://nodejs.org)
+
+Redis-backed SSR view cache store for [@blacklizard/inertia-express](../inertia-express). Compatible with [`node-redis` v4+](https://github.com/redis/node-redis) and `ioredis`.
+
+## Install
+
+```bash
+pnpm add @blacklizard/inertia-cache-redis redis
+```
+
+## Usage
+
+```ts
+import express from "express";
+import { createClient } from "redis";
+import { inertia, viteManifestVersion } from "@blacklizard/inertia-express";
+import { createRedisCacheStore } from "@blacklizard/inertia-cache-redis";
+
+const redis = createClient({ url: process.env.REDIS_URL });
+await redis.connect();
+
+const app = express();
+app.use(
+  inertia({
+    version: viteManifestVersion({ manifestPath: "./dist/client/manifest.json" }),
+    ssr: yourSsrFetcher,
+    cache: {
+      store: createRedisCacheStore({
+        client: redis,
+        keyPrefix: "myapp:prod",
+        onError: (op, err) => console.warn(`redis cache ${op} failed`, err),
+      }),
+      ttlSeconds: 600,
+    },
+  }),
+);
+```
+
+## ioredis
+
+Pass `setMode: "ioredis"`:
+
+```ts
+import Redis from "ioredis";
+import { createRedisCacheStore } from "@blacklizard/inertia-cache-redis";
+
+const client = new Redis(process.env.REDIS_URL);
+
+createRedisCacheStore({ client, setMode: "ioredis" });
+```
+
+## Cache invalidation on deploy
+
+Cache keys include the asset version. On deploy, a new version automatically retires every existing entry with no manual flush. Old keys expire via TTL.

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+import { SsrCacheStore } from "@blacklizard/inertia-express/core";
+
+//#region src/index.d.ts
+/**
+ * Structural type representing the subset of the `redis` (node-redis v4+)
+ * client API that we use. Defined here so this package does not need a
+ * runtime dependency on a specific node-redis version — pass any client
+ * with these methods, including `ioredis` (which has a compatible signature
+ * for `get`/`set`/`del`).
+ */
+interface RedisClientLike {
+  get: (key: string) => Promise<string | null>;
+  /**
+   * node-redis v4+ accepts an options object: `set(key, value, { EX: n })`
+   * for TTL in seconds. We pass that shape; the call is type-erased here so
+   * either `redis@4+` or `ioredis` (which uses `set(key, value, "EX", n)`)
+   * can be adapted at construction time via `setMode`.
+   */
+  set: (key: string, value: string, options?: unknown) => Promise<unknown>;
+  del: (keys: string | string[]) => Promise<number>;
+}
+/**
+ * Construction options for {@link createRedisCacheStore}.
+ */
+interface RedisCacheStoreOptions {
+  /** Redis client. node-redis v4+ recommended; ioredis works with `setMode: "ioredis"`. */
+  client: RedisClientLike;
+  /**
+   * Calling convention for `SET` with TTL.
+   *   - `"node-redis"` (default): `client.set(key, value, { EX: ttl })`
+   *   - `"ioredis"`: `client.set(key, value, "EX", ttl)`
+   */
+  setMode?: 'node-redis' | 'ioredis';
+  /**
+   * Optional key-prefix wrapper applied on top of whatever prefix the
+   * adapter computes. Use this for additional namespacing (per-environment,
+   * per-tenant, etc.).
+   */
+  keyPrefix?: string;
+  /**
+   * Called when a Redis op throws. Cache failures are non-fatal — the
+   * adapter's middleware swallows them — but logging here is recommended.
+   */
+  onError?: (op: 'get' | 'set' | 'delete', err: unknown) => void;
+}
+/**
+ * Build a {@link SsrCacheStore} backed by Redis.
+ *
+ * Entries are stored as JSON strings. A `JSON.parse` failure on read is
+ * treated as a cache miss (the poisoned key is reported via `onError` and
+ * best-effort deleted) so a corrupted entry can never break a page render.
+ *
+ * @param options Store configuration — see {@link RedisCacheStoreOptions}.
+ */
+declare function createRedisCacheStore(options: RedisCacheStoreOptions): SsrCacheStore;
+//#endregion
+export { RedisCacheStoreOptions, RedisClientLike, createRedisCacheStore };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;;AASA;;;;;UAAiB,eAAA;EACf,GAAA,GAAM,GAAA,aAAgB,OAAA;EAQmB;;;;;;EADzC,GAAA,GAAM,GAAA,UAAa,KAAA,UAAe,OAAA,eAAsB,OAAA;EACxD,GAAA,GAAM,IAAA,wBAA4B,OAAA;AAAA;;;;UAMnB,sBAAA;EAN0B;EAQzC,MAAA,EAAQ,eAAe;EAFc;;;;;EAQrC,OAAA;EAMA;;;;;EAAA,SAAA;EAgDc;;;;EA3Cd,OAAA,IAAW,EAAA,4BAA8B,GAAA;AAAA;;;AA2C0C;;;;;;;iBAArE,qBAAA,CAAsB,OAAA,EAAS,sBAAA,GAAyB,aAAa"}

package/dist/index.js

@@ -0,0 +1,105 @@
+//#region src/index.ts
+/**
+* Join an optional namespace prefix onto a cache key with a `:` separator.
+*
+* @param prefix Optional namespace; when undefined the key is returned unchanged.
+* @param key Cache key to prefix.
+*/
+function withPrefix(prefix, key) {
+	return prefix ? `${prefix}:${key}` : key;
+}
+/**
+* Delete a key, swallowing any failure after reporting it via `onError`.
+* Used to evict a poisoned (unparseable) cache entry without letting the
+* cleanup error mask the original read.
+*
+* @param client Redis client.
+* @param key Fully-prefixed key to remove.
+* @param onError Optional error reporter.
+*/
+async function bestEffortDelete(client, key, onError) {
+	try {
+		await client.del(key);
+	} catch (delErr) {
+		onError?.("delete", delErr);
+	}
+}
+/**
+* Build a {@link SsrCacheStore} backed by Redis.
+*
+* Entries are stored as JSON strings. A `JSON.parse` failure on read is
+* treated as a cache miss (the poisoned key is reported via `onError` and
+* best-effort deleted) so a corrupted entry can never break a page render.
+*
+* @param options Store configuration — see {@link RedisCacheStoreOptions}.
+*/
+function createRedisCacheStore(options) {
+	const setMode = options.setMode ?? "node-redis";
+	const prefix = options.keyPrefix;
+	return {
+		/**
+		* Read a cache entry. Returns `null` on miss or on poisoned (unparseable)
+		* data; rethrows when the Redis client itself errors after reporting via
+		* `onError`.
+		*
+		* @param key Cache key, before prefixing.
+		*/
+		async get(key) {
+			const fullKey = withPrefix(prefix, key);
+			try {
+				const raw = await options.client.get(fullKey);
+				if (raw === null) return null;
+				try {
+					return JSON.parse(raw);
+				} catch (parseErr) {
+					options.onError?.("get", parseErr);
+					await bestEffortDelete(options.client, fullKey, options.onError);
+					return null;
+				}
+			} catch (err) {
+				options.onError?.("get", err);
+				throw err;
+			}
+		},
+		/**
+		* Write a cache entry with a TTL. Reports via `onError` and rethrows on
+		* Redis failure (the calling middleware swallows the throw — writes are
+		* fire-and-forget).
+		*
+		* @param key Cache key, before prefixing.
+		* @param value Entry to JSON-serialize and store.
+		* @param ttlSeconds Time-to-live in seconds.
+		*/
+		async set(key, value, ttlSeconds) {
+			const fullKey = withPrefix(prefix, key);
+			const payload = JSON.stringify(value);
+			try {
+				if (setMode === "ioredis") {
+					const setFn = options.client.set;
+					await setFn(fullKey, payload, "EX", ttlSeconds);
+				} else await options.client.set(fullKey, payload, { EX: ttlSeconds });
+			} catch (err) {
+				options.onError?.("set", err);
+				throw err;
+			}
+		},
+		/**
+		* Remove a cache entry. Reports via `onError` and rethrows on failure.
+		*
+		* @param key Cache key, before prefixing.
+		*/
+		async delete(key) {
+			const fullKey = withPrefix(prefix, key);
+			try {
+				await options.client.del(fullKey);
+			} catch (err) {
+				options.onError?.("delete", err);
+				throw err;
+			}
+		}
+	};
+}
+//#endregion
+export { createRedisCacheStore };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { SsrCacheEntry, SsrCacheStore } from '@blacklizard/inertia-express/core';\n\n/**\n * Structural type representing the subset of the `redis` (node-redis v4+)\n * client API that we use. Defined here so this package does not need a\n * runtime dependency on a specific node-redis version — pass any client\n * with these methods, including `ioredis` (which has a compatible signature\n * for `get`/`set`/`del`).\n */\nexport interface RedisClientLike {\n  get: (key: string) => Promise<string | null>;\n  /**\n   * node-redis v4+ accepts an options object: `set(key, value, { EX: n })`\n   * for TTL in seconds. We pass that shape; the call is type-erased here so\n   * either `redis@4+` or `ioredis` (which uses `set(key, value, \"EX\", n)`)\n   * can be adapted at construction time via `setMode`.\n   */\n  set: (key: string, value: string, options?: unknown) => Promise<unknown>;\n  del: (keys: string | string[]) => Promise<number>;\n}\n\n/**\n * Construction options for {@link createRedisCacheStore}.\n */\nexport interface RedisCacheStoreOptions {\n  /** Redis client. node-redis v4+ recommended; ioredis works with `setMode: \"ioredis\"`. */\n  client: RedisClientLike;\n  /**\n   * Calling convention for `SET` with TTL.\n   *   - `\"node-redis\"` (default): `client.set(key, value, { EX: ttl })`\n   *   - `\"ioredis\"`: `client.set(key, value, \"EX\", ttl)`\n   */\n  setMode?: 'node-redis' | 'ioredis';\n  /**\n   * Optional key-prefix wrapper applied on top of whatever prefix the\n   * adapter computes. Use this for additional namespacing (per-environment,\n   * per-tenant, etc.).\n   */\n  keyPrefix?: string;\n  /**\n   * Called when a Redis op throws. Cache failures are non-fatal — the\n   * adapter's middleware swallows them — but logging here is recommended.\n   */\n  onError?: (op: 'get' | 'set' | 'delete', err: unknown) => void;\n}\n\n/**\n * Join an optional namespace prefix onto a cache key with a `:` separator.\n *\n * @param prefix Optional namespace; when undefined the key is returned unchanged.\n * @param key Cache key to prefix.\n */\nfunction withPrefix(prefix: string | undefined, key: string): string {\n  return prefix ? `${prefix}:${key}` : key;\n}\n\n/**\n * Delete a key, swallowing any failure after reporting it via `onError`.\n * Used to evict a poisoned (unparseable) cache entry without letting the\n * cleanup error mask the original read.\n *\n * @param client Redis client.\n * @param key Fully-prefixed key to remove.\n * @param onError Optional error reporter.\n */\nasync function bestEffortDelete(\n  client: RedisClientLike,\n  key: string,\n  onError: RedisCacheStoreOptions['onError'],\n): Promise<void> {\n  try {\n    await client.del(key);\n  } catch (delErr) {\n    onError?.('delete', delErr);\n  }\n}\n\n/**\n * Build a {@link SsrCacheStore} backed by Redis.\n *\n * Entries are stored as JSON strings. A `JSON.parse` failure on read is\n * treated as a cache miss (the poisoned key is reported via `onError` and\n * best-effort deleted) so a corrupted entry can never break a page render.\n *\n * @param options Store configuration — see {@link RedisCacheStoreOptions}.\n */\nexport function createRedisCacheStore(options: RedisCacheStoreOptions): SsrCacheStore {\n  const setMode = options.setMode ?? 'node-redis';\n  const prefix = options.keyPrefix;\n\n  return {\n    /**\n     * Read a cache entry. Returns `null` on miss or on poisoned (unparseable)\n     * data; rethrows when the Redis client itself errors after reporting via\n     * `onError`.\n     *\n     * @param key Cache key, before prefixing.\n     */\n    async get(key: string): Promise<SsrCacheEntry | null> {\n      const fullKey = withPrefix(prefix, key);\n\n      try {\n        const raw = await options.client.get(fullKey);\n\n        if (raw === null) {\n          return null;\n        }\n\n        try {\n          return JSON.parse(raw) as SsrCacheEntry;\n        } catch (parseErr) {\n          // Poisoned key — report it, best-effort delete, then treat as a miss.\n          options.onError?.('get', parseErr);\n          await bestEffortDelete(options.client, fullKey, options.onError);\n\n          return null;\n        }\n      } catch (err) {\n        options.onError?.('get', err);\n        throw err;\n      }\n    },\n    /**\n     * Write a cache entry with a TTL. Reports via `onError` and rethrows on\n     * Redis failure (the calling middleware swallows the throw — writes are\n     * fire-and-forget).\n     *\n     * @param key Cache key, before prefixing.\n     * @param value Entry to JSON-serialize and store.\n     * @param ttlSeconds Time-to-live in seconds.\n     */\n    async set(key: string, value: SsrCacheEntry, ttlSeconds: number): Promise<void> {\n      const fullKey = withPrefix(prefix, key);\n      const payload = JSON.stringify(value);\n\n      try {\n        if (setMode === 'ioredis') {\n          // ioredis: client.set(key, value, \"EX\", ttl)\n          const setFn = options.client.set as unknown as (\n            k: string,\n            v: string,\n            mode: string,\n            ttl: number,\n          ) => Promise<unknown>;\n          await setFn(fullKey, payload, 'EX', ttlSeconds);\n        } else {\n          // node-redis v4+: client.set(key, value, { EX: ttl })\n          await options.client.set(fullKey, payload, { EX: ttlSeconds });\n        }\n      } catch (err) {\n        options.onError?.('set', err);\n        throw err;\n      }\n    },\n    /**\n     * Remove a cache entry. Reports via `onError` and rethrows on failure.\n     *\n     * @param key Cache key, before prefixing.\n     */\n    async delete(key: string): Promise<void> {\n      const fullKey = withPrefix(prefix, key);\n\n      try {\n        await options.client.del(fullKey);\n      } catch (err) {\n        options.onError?.('delete', err);\n        throw err;\n      }\n    },\n  };\n}\n"],"mappings":";;;;;;;AAoDA,SAAS,WAAW,QAA4B,KAAqB;CACnE,OAAO,SAAS,GAAG,OAAO,GAAG,QAAQ;AACvC;;;;;;;;;;AAWA,eAAe,iBACb,QACA,KACA,SACe;CACf,IAAI;EACF,MAAM,OAAO,IAAI,GAAG;CACtB,SAAS,QAAQ;EACf,UAAU,UAAU,MAAM;CAC5B;AACF;;;;;;;;;;AAWA,SAAgB,sBAAsB,SAAgD;CACpF,MAAM,UAAU,QAAQ,WAAW;CACnC,MAAM,SAAS,QAAQ;CAEvB,OAAO;;;;;;;;EAQL,MAAM,IAAI,KAA4C;GACpD,MAAM,UAAU,WAAW,QAAQ,GAAG;GAEtC,IAAI;IACF,MAAM,MAAM,MAAM,QAAQ,OAAO,IAAI,OAAO;IAE5C,IAAI,QAAQ,MACV,OAAO;IAGT,IAAI;KACF,OAAO,KAAK,MAAM,GAAG;IACvB,SAAS,UAAU;KAEjB,QAAQ,UAAU,OAAO,QAAQ;KACjC,MAAM,iBAAiB,QAAQ,QAAQ,SAAS,QAAQ,OAAO;KAE/D,OAAO;IACT;GACF,SAAS,KAAK;IACZ,QAAQ,UAAU,OAAO,GAAG;IAC5B,MAAM;GACR;EACF;;;;;;;;;;EAUA,MAAM,IAAI,KAAa,OAAsB,YAAmC;GAC9E,MAAM,UAAU,WAAW,QAAQ,GAAG;GACtC,MAAM,UAAU,KAAK,UAAU,KAAK;GAEpC,IAAI;IACF,IAAI,YAAY,WAAW;KAEzB,MAAM,QAAQ,QAAQ,OAAO;KAM7B,MAAM,MAAM,SAAS,SAAS,MAAM,UAAU;IAChD,OAEE,MAAM,QAAQ,OAAO,IAAI,SAAS,SAAS,EAAE,IAAI,WAAW,CAAC;GAEjE,SAAS,KAAK;IACZ,QAAQ,UAAU,OAAO,GAAG;IAC5B,MAAM;GACR;EACF;;;;;;EAMA,MAAM,OAAO,KAA4B;GACvC,MAAM,UAAU,WAAW,QAAQ,GAAG;GAEtC,IAAI;IACF,MAAM,QAAQ,OAAO,IAAI,OAAO;GAClC,SAAS,KAAK;IACZ,QAAQ,UAAU,UAAU,GAAG;IAC/B,MAAM;GACR;EACF;CACF;AACF"}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@blacklizard/inertia-cache-redis",
+  "version": "0.1.0",
+  "description": "Redis-backed SSR view cache store for @blacklizard/inertia-express. Compatible with node-redis v4+.",
+  "type": "module",
+  "license": "MIT",
+  "author": "blacklizard",
+  "homepage": "https://github.com/blacklizard/inertia-express/tree/main/packages/inertia-cache-redis#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blacklizard/inertia-express.git",
+    "directory": "packages/inertia-cache-redis"
+  },
+  "bugs": {
+    "url": "https://github.com/blacklizard/inertia-express/issues"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "redis": "^4.6.0 || ^5.0.0",
+    "@blacklizard/inertia-express": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "tsdown": "^0.22.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7",
+    "@blacklizard/inertia-express": "0.1.0"
+  },
+  "keywords": [
+    "inertia",
+    "inertia-js",
+    "inertiajs",
+    "express",
+    "adapter",
+    "ssr",
+    "spa",
+    "redis",
+    "cache",
+    "worker",
+    "load-balancer",
+    "self-healing"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}