@visualbravo/zenstack-cache 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Visual Bravo LLC
+
+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,136 @@
+<div align="center">
+  <h1>
+    ZenStack Cache
+    <small>(beta)</small>
+  </h1>
+
+  Reduce response times and database load with query-level caching integrated with the ZenStack ORM.
+</div>
+
+<div align="center">
+    <a href="https://www.npmjs.com/package/@visualbravo/zenstack-cache?activeTab=versions">
+      <img alt="NPM Version" src="https://img.shields.io/npm/v/%40visualbravo%2Fzenstack-cache/latest">
+    </a>
+    <a>
+      <img alt="GitHub Actions Workflow Status" src="https://img.shields.io/github/actions/workflow/status/visualbravo/zenstack-cache/build-and-test.yaml">
+    </a>
+    <a href="https://discord.gg/Ykhr738dUe">
+      <img alt="Join the ZenStack server" src="https://img.shields.io/discord/1035538056146595961">
+    </a>
+    <a href="https://github.com/visualbravo/zenstack-cache/blob/main/LICENSE">
+      <img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green">
+    </a>
+
+  <p>
+    ℹ️ This project is not affiliated with or endorsed by the ZenStack team.
+  </p>
+</div>
+
+## Features
+* 🌐 **Redis Caching:** Centralizes your caching to scale across different systems.
+* 🖥️ **Memory Caching:** Simplifies caching when scale is not a concern.
+* 🛟 **Type-safe:** The caching options appear in the intellisense for all read queries.
+
+## Requirements
+
+* ZenStack (version >= `canary`)
+* Node.js (version >= `20.0.0`)
+* Redis (version >= `7.0.0`)
+  * ℹ️ Only if you intend to use the `RedisCacheProvider`
+
+## Installation
+
+```bash
+npm install @visualbravo/zenstack-cache
+pnpm add @visualbravo/zenstack-cache
+bun add @visualbravo/zenstack-cache
+```
+
+## Sample Usage
+
+```typescript
+import { schema } from './zenstack/schema'
+import { ZenStackClient } from '@zenstackhq/orm'
+import { defineCachePlugin } from '@visualbravo/zenstack-cache'
+import { RedisCacheProvider } from '@visualbravo/zenstack-cache/providers/redis'
+import { MemoryCacheProvider } from '@visualbravo/zenstack-cache/providers/memory'
+
+const client = new ZenStackClient(schema, {
+  dialect: ...,
+}).$use(
+  defineCachePlugin({
+    // Choose only one provider.
+
+    // 1️⃣
+    provider: new RedisCacheProvider({
+      url: process.env['REDIS_URL'],
+    }),
+
+    // 2️⃣
+    provider: new MemoryCacheProvider(),
+  }),
+)
+
+async function getPostsPublishedByUser(userId: string) {
+  const publishedPosts = await client.post.findMany({
+    where: {
+      published: true,
+      authorId: userId,
+    },
+
+    // All of these are optional.
+    cache: {
+      ttl: 60,
+      swr: 120,
+      tags: [`user:${userId}`],
+    },
+  })
+
+  return publishedPosts
+}
+```
+
+## Invalidation
+
+You can easily invalidate multiple cache entries.
+
+```typescript
+// Invalidate specific tags.
+await client.$cache.invalidate({
+  tags: ['user:1'],
+})
+
+// Invalidate everything.
+await client.$cache.invalidateAll()
+```
+
+## Cache Status
+
+After performing a query, you can check where the result came from.
+
+```typescript
+const publishedPostsStatus = client.$cache.status // 'hit' | 'miss' | 'stale'
+```
+
+* `hit` - a cache entry in the `ttl` window was found, and the database was not queried.
+* `miss` - a cache entry was not found, and the database was queried.
+* `stale` - a cache entry in the `swr` window was found, and the database was queried in the background to revalidate it.
+
+## Revalidation
+
+If the result was stale, you can choose to await its revalidation.
+```typescript
+const revalidatedPublishedPosts = await client.$cache.revalidation as Post[]
+```
+
+## Cache Options
+
+* `ttl` reduces response times and database load by serving cached results.
+* `swr` reduces response times by serving cached results, but does not reduce database load because it performs a revalidation in the background after each request.
+
+> [!NOTE]
+> The total TTL of a cache entry is equal to its `ttl` + `swr`. The `ttl` window comes first, followed by the `swr` window. You can combine the two options to best suit the needs of your application.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,3 @@
+const require_plugin = require('./plugin.cjs');
+
+exports.defineCachePlugin = require_plugin.defineCachePlugin;

package/dist/index.d.cts

@@ -0,0 +1,2 @@
+import { defineCachePlugin } from "./plugin.cjs";
+export { defineCachePlugin };

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+import { defineCachePlugin } from "./plugin.mjs";
+export { defineCachePlugin };

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import { defineCachePlugin } from "./plugin.mjs";
+
+export { defineCachePlugin };

package/dist/plugin.cjs

@@ -0,0 +1,84 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const require_schemas = require('./schemas.cjs');
+const require_utils = require('./utils.cjs');
+let _zenstackhq_orm = require("@zenstackhq/orm");
+let stable_hash = require("stable-hash");
+let murmurhash = require("murmurhash");
+murmurhash = require_rolldown_runtime.__toESM(murmurhash);
+
+//#region src/plugin.ts
+function lowerCaseFirst(input) {
+	return input.charAt(0).toLowerCase() + input.slice(1);
+}
+function defineCachePlugin(pluginOptions) {
+	let status = null;
+	let revalidation = null;
+	return (0, _zenstackhq_orm.definePlugin)({
+		id: "cache",
+		name: "Cache",
+		description: "Optionally caches read queries.",
+		queryArgs: { $read: require_schemas.cacheEnvelopeSchema },
+		client: { $cache: {
+			invalidate: (options) => {
+				return pluginOptions.provider.invalidate(options);
+			},
+			invalidateAll() {
+				return pluginOptions.provider.invalidateAll();
+			},
+			get status() {
+				return status;
+			},
+			get revalidation() {
+				return revalidation;
+			}
+		} },
+		onQuery: async ({ args, model, operation, proceed }) => {
+			if (args && "cache" in args) {
+				const json = (0, stable_hash.stableHash)({
+					args,
+					model,
+					operation
+				});
+				if (!json) throw new Error(`Failed to serialize cache entry for ${lowerCaseFirst(model)}.${operation}`);
+				const cache = pluginOptions.provider;
+				const options = args.cache;
+				const key = murmurhash.default.v3(json).toString();
+				const entry = await cache.get(key);
+				if (entry) {
+					if (require_utils.entryIsFresh(entry)) {
+						status = "hit";
+						return entry.result;
+					} else if (require_utils.entryIsStale(entry)) {
+						revalidation = proceed(args).then(async (result$1) => {
+							try {
+								await cache.set(key, {
+									createdAt: Date.now(),
+									options,
+									result: result$1
+								});
+								return result$1;
+							} catch (err) {
+								console.error(`Failed to cache query result: ${err}`);
+								return null;
+							}
+						});
+						status = "stale";
+						return entry.result;
+					}
+				}
+				const result = await proceed(args);
+				cache.set(key, {
+					createdAt: Date.now(),
+					options,
+					result
+				}).catch((err) => console.error(`Failed to cache query result: ${err}`));
+				status = "miss";
+				return result;
+			}
+			return proceed(args);
+		}
+	});
+}
+
+//#endregion
+exports.defineCachePlugin = defineCachePlugin;

package/dist/plugin.d.cts

@@ -0,0 +1,31 @@
+import { CacheInvalidationOptions, CachePluginOptions, CacheStatus } from "./types.cjs";
+import * as node_modules__zenstackhq_orm_dist0 from "node_modules/@zenstackhq/orm/dist";
+
+//#region src/plugin.d.ts
+declare function defineCachePlugin(pluginOptions: CachePluginOptions): node_modules__zenstackhq_orm_dist0.RuntimePlugin<any, {
+  readonly $read: {
+    cache?: {
+      ttl?: number | undefined;
+      swr?: number | undefined;
+      tags?: string[] | undefined;
+    } | undefined;
+  };
+}, {
+  readonly $cache: {
+    readonly invalidate: (options: CacheInvalidationOptions) => Promise<void>;
+    readonly invalidateAll: () => Promise<void>;
+    /**
+     * Returns the status of the last result returned, or `null`
+     * if a result has yet to be returned.
+     */
+    readonly status: CacheStatus | null;
+    /**
+     * Returns a `Promise` that fulfills when the last stale result
+     * returned has been revalidated, or `null` if a stale result has
+     * yet to be returned.
+     */
+    readonly revalidation: Promise<unknown> | null;
+  };
+}>;
+//#endregion
+export { defineCachePlugin };

package/dist/plugin.d.mts

@@ -0,0 +1,31 @@
+import { CacheInvalidationOptions, CachePluginOptions, CacheStatus } from "./types.mjs";
+import * as node_modules__zenstackhq_orm_dist0 from "node_modules/@zenstackhq/orm/dist";
+
+//#region src/plugin.d.ts
+declare function defineCachePlugin(pluginOptions: CachePluginOptions): node_modules__zenstackhq_orm_dist0.RuntimePlugin<any, {
+  readonly $read: {
+    cache?: {
+      ttl?: number | undefined;
+      swr?: number | undefined;
+      tags?: string[] | undefined;
+    } | undefined;
+  };
+}, {
+  readonly $cache: {
+    readonly invalidate: (options: CacheInvalidationOptions) => Promise<void>;
+    readonly invalidateAll: () => Promise<void>;
+    /**
+     * Returns the status of the last result returned, or `null`
+     * if a result has yet to be returned.
+     */
+    readonly status: CacheStatus | null;
+    /**
+     * Returns a `Promise` that fulfills when the last stale result
+     * returned has been revalidated, or `null` if a stale result has
+     * yet to be returned.
+     */
+    readonly revalidation: Promise<unknown> | null;
+  };
+}>;
+//#endregion
+export { defineCachePlugin };

package/dist/plugin.mjs

@@ -0,0 +1,82 @@
+import { cacheEnvelopeSchema } from "./schemas.mjs";
+import { entryIsFresh, entryIsStale } from "./utils.mjs";
+import { definePlugin } from "@zenstackhq/orm";
+import { stableHash } from "stable-hash";
+import murmurhash from "murmurhash";
+
+//#region src/plugin.ts
+function lowerCaseFirst(input) {
+	return input.charAt(0).toLowerCase() + input.slice(1);
+}
+function defineCachePlugin(pluginOptions) {
+	let status = null;
+	let revalidation = null;
+	return definePlugin({
+		id: "cache",
+		name: "Cache",
+		description: "Optionally caches read queries.",
+		queryArgs: { $read: cacheEnvelopeSchema },
+		client: { $cache: {
+			invalidate: (options) => {
+				return pluginOptions.provider.invalidate(options);
+			},
+			invalidateAll() {
+				return pluginOptions.provider.invalidateAll();
+			},
+			get status() {
+				return status;
+			},
+			get revalidation() {
+				return revalidation;
+			}
+		} },
+		onQuery: async ({ args, model, operation, proceed }) => {
+			if (args && "cache" in args) {
+				const json = stableHash({
+					args,
+					model,
+					operation
+				});
+				if (!json) throw new Error(`Failed to serialize cache entry for ${lowerCaseFirst(model)}.${operation}`);
+				const cache = pluginOptions.provider;
+				const options = args.cache;
+				const key = murmurhash.v3(json).toString();
+				const entry = await cache.get(key);
+				if (entry) {
+					if (entryIsFresh(entry)) {
+						status = "hit";
+						return entry.result;
+					} else if (entryIsStale(entry)) {
+						revalidation = proceed(args).then(async (result$1) => {
+							try {
+								await cache.set(key, {
+									createdAt: Date.now(),
+									options,
+									result: result$1
+								});
+								return result$1;
+							} catch (err) {
+								console.error(`Failed to cache query result: ${err}`);
+								return null;
+							}
+						});
+						status = "stale";
+						return entry.result;
+					}
+				}
+				const result = await proceed(args);
+				cache.set(key, {
+					createdAt: Date.now(),
+					options,
+					result
+				}).catch((err) => console.error(`Failed to cache query result: ${err}`));
+				status = "miss";
+				return result;
+			}
+			return proceed(args);
+		}
+	});
+}
+
+//#endregion
+export { defineCachePlugin };

package/dist/providers/memory.cjs

@@ -0,0 +1,55 @@
+const require_utils = require('../utils.cjs');
+
+//#region src/providers/memory.ts
+var MemoryCacheProvider = class {
+	entryStore;
+	tagStore;
+	constructor(options) {
+		this.options = options;
+		this.entryStore = /* @__PURE__ */ new Map();
+		this.tagStore = /* @__PURE__ */ new Map();
+		setInterval(() => {
+			this.checkExpiration();
+		}, (this.options?.checkInterval ?? 60) * 1e3).unref();
+	}
+	checkExpiration() {
+		for (const [key, entry] of this.entryStore) if (require_utils.entryIsExpired(entry)) {
+			this.entryStore.delete(key);
+			this.options?.onIntervalExpiration?.(entry);
+		}
+		for (const [tag, keys] of this.tagStore) {
+			for (const key of keys) if (!this.entryStore.has(key)) keys.delete(key);
+			if (keys.size === 0) this.tagStore.delete(tag);
+		}
+	}
+	get(key) {
+		return Promise.resolve(this.entryStore.get(key));
+	}
+	set(key, entry) {
+		this.entryStore.set(key, entry);
+		if (entry.options.tags) for (const tag of entry.options.tags) {
+			let keys = this.tagStore.get(tag);
+			if (!keys) {
+				keys = /* @__PURE__ */ new Set();
+				this.tagStore.set(tag, keys);
+			}
+			keys.add(key);
+		}
+		return Promise.resolve();
+	}
+	invalidate(options) {
+		if (options.tags) for (const tag of options.tags) {
+			const keys = this.tagStore.get(tag);
+			if (keys) for (const key of keys) this.entryStore.delete(key);
+		}
+		return Promise.resolve();
+	}
+	invalidateAll() {
+		this.entryStore.clear();
+		this.tagStore.clear();
+		return Promise.resolve();
+	}
+};
+
+//#endregion
+exports.MemoryCacheProvider = MemoryCacheProvider;

package/dist/providers/memory.d.cts

@@ -0,0 +1,28 @@
+import { CacheEntry, CacheInvalidationOptions, CacheProvider } from "../types.cjs";
+
+//#region src/providers/memory.d.ts
+declare class MemoryCacheProvider implements CacheProvider {
+  private readonly options?;
+  private readonly entryStore;
+  private readonly tagStore;
+  constructor(options?: MemoryCacheOptions | undefined);
+  private checkExpiration;
+  get(key: string): Promise<CacheEntry | undefined>;
+  set(key: string, entry: CacheEntry): Promise<void>;
+  invalidate(options: CacheInvalidationOptions): Promise<void>;
+  invalidateAll(): Promise<void>;
+}
+type MemoryCacheOptions = {
+  /**
+   * How often, in seconds, entries will be checked for expiration.
+   *
+   * @default 60
+   */
+  checkInterval?: number;
+  /**
+   * Called when an entry has expired via the interval check.
+   */
+  onIntervalExpiration?: (entry: CacheEntry) => void;
+};
+//#endregion
+export { MemoryCacheOptions, MemoryCacheProvider };

package/dist/providers/memory.d.mts

@@ -0,0 +1,28 @@
+import { CacheEntry, CacheInvalidationOptions, CacheProvider } from "../types.mjs";
+
+//#region src/providers/memory.d.ts
+declare class MemoryCacheProvider implements CacheProvider {
+  private readonly options?;
+  private readonly entryStore;
+  private readonly tagStore;
+  constructor(options?: MemoryCacheOptions | undefined);
+  private checkExpiration;
+  get(key: string): Promise<CacheEntry | undefined>;
+  set(key: string, entry: CacheEntry): Promise<void>;
+  invalidate(options: CacheInvalidationOptions): Promise<void>;
+  invalidateAll(): Promise<void>;
+}
+type MemoryCacheOptions = {
+  /**
+   * How often, in seconds, entries will be checked for expiration.
+   *
+   * @default 60
+   */
+  checkInterval?: number;
+  /**
+   * Called when an entry has expired via the interval check.
+   */
+  onIntervalExpiration?: (entry: CacheEntry) => void;
+};
+//#endregion
+export { MemoryCacheOptions, MemoryCacheProvider };

package/dist/providers/memory.mjs

@@ -0,0 +1,55 @@
+import { entryIsExpired } from "../utils.mjs";
+
+//#region src/providers/memory.ts
+var MemoryCacheProvider = class {
+	entryStore;
+	tagStore;
+	constructor(options) {
+		this.options = options;
+		this.entryStore = /* @__PURE__ */ new Map();
+		this.tagStore = /* @__PURE__ */ new Map();
+		setInterval(() => {
+			this.checkExpiration();
+		}, (this.options?.checkInterval ?? 60) * 1e3).unref();
+	}
+	checkExpiration() {
+		for (const [key, entry] of this.entryStore) if (entryIsExpired(entry)) {
+			this.entryStore.delete(key);
+			this.options?.onIntervalExpiration?.(entry);
+		}
+		for (const [tag, keys] of this.tagStore) {
+			for (const key of keys) if (!this.entryStore.has(key)) keys.delete(key);
+			if (keys.size === 0) this.tagStore.delete(tag);
+		}
+	}
+	get(key) {
+		return Promise.resolve(this.entryStore.get(key));
+	}
+	set(key, entry) {
+		this.entryStore.set(key, entry);
+		if (entry.options.tags) for (const tag of entry.options.tags) {
+			let keys = this.tagStore.get(tag);
+			if (!keys) {
+				keys = /* @__PURE__ */ new Set();
+				this.tagStore.set(tag, keys);
+			}
+			keys.add(key);
+		}
+		return Promise.resolve();
+	}
+	invalidate(options) {
+		if (options.tags) for (const tag of options.tags) {
+			const keys = this.tagStore.get(tag);
+			if (keys) for (const key of keys) this.entryStore.delete(key);
+		}
+		return Promise.resolve();
+	}
+	invalidateAll() {
+		this.entryStore.clear();
+		this.tagStore.clear();
+		return Promise.resolve();
+	}
+};
+
+//#endregion
+export { MemoryCacheProvider };

package/dist/providers/redis.cjs

@@ -0,0 +1,68 @@
+const require_rolldown_runtime = require('../_virtual/rolldown_runtime.cjs');
+const require_utils = require('../utils.cjs');
+require('../superjson.cjs');
+let ioredis = require("ioredis");
+let superjson = require("superjson");
+
+//#region src/providers/redis.ts
+var RedisCacheProvider = class {
+	redis;
+	constructor(options) {
+		this.redis = new ioredis.Redis(options.url);
+	}
+	async get(key) {
+		const entryJson = await this.redis.get(formatQueryKey(key));
+		if (!entryJson) return;
+		return superjson.default.parse(entryJson);
+	}
+	async set(key, entry) {
+		const multi = this.redis.multi();
+		const formattedKey = formatQueryKey(key);
+		multi.set(formattedKey, superjson.default.stringify(entry));
+		const totalTtl = require_utils.getTotalTtl(entry);
+		if (totalTtl > 0) multi.expire(formattedKey, totalTtl);
+		if (entry.options.tags) for (const tag of entry.options.tags) {
+			const formattedTagKey = formatTagKey(tag);
+			multi.sadd(formattedTagKey, formattedKey);
+			if (totalTtl > 0) {
+				multi.expire(formattedTagKey, totalTtl, "GT");
+				multi.expire(formattedTagKey, totalTtl, "NX");
+			}
+		}
+		await multi.exec();
+	}
+	async invalidate(options) {
+		if (options.tags && options.tags.length > 0) await Promise.all(options.tags.map((tag) => {
+			return new Promise((resolve, reject) => {
+				const stream = this.redis.sscanStream(formatTagKey(tag), { count: 100 });
+				stream.on("data", async (keys) => {
+					if (keys.length > 1) await this.redis.del(...keys);
+				});
+				stream.on("error", reject);
+				stream.on("end", resolve);
+			});
+		}));
+	}
+	async invalidateAll() {
+		await new Promise((resolve, reject) => {
+			const stream = this.redis.scanStream({
+				count: 100,
+				match: "zenstack:cache:*"
+			});
+			stream.on("data", async (keys) => {
+				if (keys.length > 1) await this.redis.del(...keys);
+			});
+			stream.on("error", reject);
+			stream.on("end", resolve);
+		});
+	}
+};
+function formatQueryKey(key) {
+	return `zenstack:cache:query:${key}`;
+}
+function formatTagKey(key) {
+	return `zenstack:cache:tag:${key}`;
+}
+
+//#endregion
+exports.RedisCacheProvider = RedisCacheProvider;

package/dist/providers/redis.d.cts

@@ -0,0 +1,16 @@
+import { CacheEntry, CacheInvalidationOptions, CacheProvider } from "../types.cjs";
+
+//#region src/providers/redis.d.ts
+declare class RedisCacheProvider implements CacheProvider {
+  private readonly redis;
+  constructor(options: RedisCacheProviderOptions);
+  get(key: string): Promise<CacheEntry | undefined>;
+  set(key: string, entry: CacheEntry): Promise<void>;
+  invalidate(options: CacheInvalidationOptions): Promise<void>;
+  invalidateAll(): Promise<void>;
+}
+type RedisCacheProviderOptions = {
+  url: string;
+};
+//#endregion
+export { RedisCacheProvider, RedisCacheProviderOptions };

package/dist/providers/redis.d.mts

@@ -0,0 +1,16 @@
+import { CacheEntry, CacheInvalidationOptions, CacheProvider } from "../types.mjs";
+
+//#region src/providers/redis.d.ts
+declare class RedisCacheProvider implements CacheProvider {
+  private readonly redis;
+  constructor(options: RedisCacheProviderOptions);
+  get(key: string): Promise<CacheEntry | undefined>;
+  set(key: string, entry: CacheEntry): Promise<void>;
+  invalidate(options: CacheInvalidationOptions): Promise<void>;
+  invalidateAll(): Promise<void>;
+}
+type RedisCacheProviderOptions = {
+  url: string;
+};
+//#endregion
+export { RedisCacheProvider, RedisCacheProviderOptions };

package/dist/providers/redis.mjs

@@ -0,0 +1,66 @@
+import { getTotalTtl } from "../utils.mjs";
+import { superjson } from "../superjson.mjs";
+import { Redis } from "ioredis";
+
+//#region src/providers/redis.ts
+var RedisCacheProvider = class {
+	redis;
+	constructor(options) {
+		this.redis = new Redis(options.url);
+	}
+	async get(key) {
+		const entryJson = await this.redis.get(formatQueryKey(key));
+		if (!entryJson) return;
+		return superjson.parse(entryJson);
+	}
+	async set(key, entry) {
+		const multi = this.redis.multi();
+		const formattedKey = formatQueryKey(key);
+		multi.set(formattedKey, superjson.stringify(entry));
+		const totalTtl = getTotalTtl(entry);
+		if (totalTtl > 0) multi.expire(formattedKey, totalTtl);
+		if (entry.options.tags) for (const tag of entry.options.tags) {
+			const formattedTagKey = formatTagKey(tag);
+			multi.sadd(formattedTagKey, formattedKey);
+			if (totalTtl > 0) {
+				multi.expire(formattedTagKey, totalTtl, "GT");
+				multi.expire(formattedTagKey, totalTtl, "NX");
+			}
+		}
+		await multi.exec();
+	}
+	async invalidate(options) {
+		if (options.tags && options.tags.length > 0) await Promise.all(options.tags.map((tag) => {
+			return new Promise((resolve, reject) => {
+				const stream = this.redis.sscanStream(formatTagKey(tag), { count: 100 });
+				stream.on("data", async (keys) => {
+					if (keys.length > 1) await this.redis.del(...keys);
+				});
+				stream.on("error", reject);
+				stream.on("end", resolve);
+			});
+		}));
+	}
+	async invalidateAll() {
+		await new Promise((resolve, reject) => {
+			const stream = this.redis.scanStream({
+				count: 100,
+				match: "zenstack:cache:*"
+			});
+			stream.on("data", async (keys) => {
+				if (keys.length > 1) await this.redis.del(...keys);
+			});
+			stream.on("error", reject);
+			stream.on("end", resolve);
+		});
+	}
+};
+function formatQueryKey(key) {
+	return `zenstack:cache:query:${key}`;
+}
+function formatTagKey(key) {
+	return `zenstack:cache:tag:${key}`;
+}
+
+//#endregion
+export { RedisCacheProvider };

package/dist/schemas.cjs

@@ -0,0 +1,15 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+let zod = require("zod");
+zod = require_rolldown_runtime.__toESM(zod);
+
+//#region src/schemas.ts
+const cacheOptionsSchema = zod.default.strictObject({
+	ttl: zod.default.number().min(1).optional(),
+	swr: zod.default.number().min(1).optional(),
+	tags: zod.default.string().array().optional()
+});
+const cacheEnvelopeSchema = zod.default.object({ cache: cacheOptionsSchema.optional() });
+
+//#endregion
+exports.cacheEnvelopeSchema = cacheEnvelopeSchema;
+exports.cacheOptionsSchema = cacheOptionsSchema;

package/dist/schemas.d.cts

@@ -0,0 +1,17 @@
+import z from "zod";
+
+//#region src/schemas.d.ts
+declare const cacheOptionsSchema: z.ZodObject<{
+  ttl: z.ZodOptional<z.ZodNumber>;
+  swr: z.ZodOptional<z.ZodNumber>;
+  tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+declare const cacheEnvelopeSchema: z.ZodObject<{
+  cache: z.ZodOptional<z.ZodObject<{
+    ttl: z.ZodOptional<z.ZodNumber>;
+    swr: z.ZodOptional<z.ZodNumber>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  }, z.core.$strict>>;
+}, z.core.$strip>;
+//#endregion
+export { cacheEnvelopeSchema, cacheOptionsSchema };

package/dist/schemas.d.mts

@@ -0,0 +1,17 @@
+import z from "zod";
+
+//#region src/schemas.d.ts
+declare const cacheOptionsSchema: z.ZodObject<{
+  ttl: z.ZodOptional<z.ZodNumber>;
+  swr: z.ZodOptional<z.ZodNumber>;
+  tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+declare const cacheEnvelopeSchema: z.ZodObject<{
+  cache: z.ZodOptional<z.ZodObject<{
+    ttl: z.ZodOptional<z.ZodNumber>;
+    swr: z.ZodOptional<z.ZodNumber>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  }, z.core.$strict>>;
+}, z.core.$strip>;
+//#endregion
+export { cacheEnvelopeSchema, cacheOptionsSchema };

package/dist/schemas.mjs

@@ -0,0 +1,12 @@
+import z from "zod";
+
+//#region src/schemas.ts
+const cacheOptionsSchema = z.strictObject({
+	ttl: z.number().min(1).optional(),
+	swr: z.number().min(1).optional(),
+	tags: z.string().array().optional()
+});
+const cacheEnvelopeSchema = z.object({ cache: cacheOptionsSchema.optional() });
+
+//#endregion
+export { cacheEnvelopeSchema, cacheOptionsSchema };

package/dist/superjson.cjs

@@ -0,0 +1,14 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+let decimal_js = require("decimal.js");
+let superjson = require("superjson");
+superjson = require_rolldown_runtime.__toESM(superjson);
+
+//#region src/superjson.ts
+superjson.default.registerCustom({
+	isApplicable: (v) => decimal_js.Decimal.isDecimal(v),
+	serialize: (v) => v.toJSON(),
+	deserialize: (v) => new decimal_js.Decimal(v)
+}, "decimal.js");
+
+//#endregion
+exports.superjson = superjson.default;

package/dist/superjson.d.cts

@@ -0,0 +1,2 @@
+import superjson from "superjson";
+export { superjson };

package/dist/superjson.d.mts

@@ -0,0 +1,2 @@
+import superjson from "superjson";
+export { superjson };

package/dist/superjson.mjs

@@ -0,0 +1,12 @@
+import { Decimal } from "decimal.js";
+import superjson from "superjson";
+
+//#region src/superjson.ts
+superjson.registerCustom({
+	isApplicable: (v) => Decimal.isDecimal(v),
+	serialize: (v) => v.toJSON(),
+	deserialize: (v) => new Decimal(v)
+}, "decimal.js");
+
+//#endregion
+export { superjson };

package/dist/types.d.cts

@@ -0,0 +1,35 @@
+import { cacheEnvelopeSchema, cacheOptionsSchema } from "./schemas.cjs";
+import z from "zod";
+
+//#region src/types.d.ts
+type CacheEnvelope = z.infer<typeof cacheEnvelopeSchema>;
+type CacheOptions = z.infer<typeof cacheOptionsSchema>;
+interface CacheProvider {
+  get: (key: string) => Promise<CacheEntry | undefined>;
+  set: (key: string, entry: CacheEntry) => Promise<void>;
+  invalidate: (options: CacheInvalidationOptions) => Promise<void>;
+  invalidateAll: () => Promise<void>;
+}
+type CacheInvalidationOptions = {
+  tags?: string[];
+};
+type CacheEntry = {
+  /**
+   * In unix epoch milliseconds.
+   */
+  createdAt: number;
+  /**
+   * The caching options that were passed to the query.
+   */
+  options: CacheOptions;
+  /**
+   * The result of executing the query.
+   */
+  result: unknown;
+};
+type CachePluginOptions = {
+  provider: CacheProvider;
+};
+type CacheStatus = 'hit' | 'miss' | 'stale';
+//#endregion
+export { CacheEntry, CacheEnvelope, CacheInvalidationOptions, CacheOptions, CachePluginOptions, CacheProvider, CacheStatus };

package/dist/types.d.mts

@@ -0,0 +1,35 @@
+import { cacheEnvelopeSchema, cacheOptionsSchema } from "./schemas.mjs";
+import z from "zod";
+
+//#region src/types.d.ts
+type CacheEnvelope = z.infer<typeof cacheEnvelopeSchema>;
+type CacheOptions = z.infer<typeof cacheOptionsSchema>;
+interface CacheProvider {
+  get: (key: string) => Promise<CacheEntry | undefined>;
+  set: (key: string, entry: CacheEntry) => Promise<void>;
+  invalidate: (options: CacheInvalidationOptions) => Promise<void>;
+  invalidateAll: () => Promise<void>;
+}
+type CacheInvalidationOptions = {
+  tags?: string[];
+};
+type CacheEntry = {
+  /**
+   * In unix epoch milliseconds.
+   */
+  createdAt: number;
+  /**
+   * The caching options that were passed to the query.
+   */
+  options: CacheOptions;
+  /**
+   * The result of executing the query.
+   */
+  result: unknown;
+};
+type CachePluginOptions = {
+  provider: CacheProvider;
+};
+type CacheStatus = 'hit' | 'miss' | 'stale';
+//#endregion
+export { CacheEntry, CacheEnvelope, CacheInvalidationOptions, CacheOptions, CachePluginOptions, CacheProvider, CacheStatus };

package/dist/types.mjs

@@ -0,0 +1 @@
+export {  };

package/dist/utils.cjs

@@ -0,0 +1,20 @@
+
+//#region src/utils.ts
+function getTotalTtl(entry) {
+	return (entry.options.ttl ?? 0) + (entry.options.swr ?? 0);
+}
+function entryIsFresh(entry) {
+	return entry.options.ttl ? Date.now() <= entry.createdAt + (entry.options.ttl ?? 0) * 1e3 : false;
+}
+function entryIsStale(entry) {
+	return entry.options.swr ? Date.now() <= entry.createdAt + getTotalTtl(entry) * 1e3 : false;
+}
+function entryIsExpired(entry) {
+	return Date.now() > entry.createdAt + getTotalTtl(entry) * 1e3;
+}
+
+//#endregion
+exports.entryIsExpired = entryIsExpired;
+exports.entryIsFresh = entryIsFresh;
+exports.entryIsStale = entryIsStale;
+exports.getTotalTtl = getTotalTtl;

package/dist/utils.d.cts

@@ -0,0 +1,9 @@
+import { CacheEntry } from "./types.cjs";
+
+//#region src/utils.d.ts
+declare function getTotalTtl(entry: CacheEntry): number;
+declare function entryIsFresh(entry: CacheEntry): boolean;
+declare function entryIsStale(entry: CacheEntry): boolean;
+declare function entryIsExpired(entry: CacheEntry): boolean;
+//#endregion
+export { entryIsExpired, entryIsFresh, entryIsStale, getTotalTtl };

package/dist/utils.d.mts

@@ -0,0 +1,9 @@
+import { CacheEntry } from "./types.mjs";
+
+//#region src/utils.d.ts
+declare function getTotalTtl(entry: CacheEntry): number;
+declare function entryIsFresh(entry: CacheEntry): boolean;
+declare function entryIsStale(entry: CacheEntry): boolean;
+declare function entryIsExpired(entry: CacheEntry): boolean;
+//#endregion
+export { entryIsExpired, entryIsFresh, entryIsStale, getTotalTtl };

package/dist/utils.mjs

@@ -0,0 +1,16 @@
+//#region src/utils.ts
+function getTotalTtl(entry) {
+	return (entry.options.ttl ?? 0) + (entry.options.swr ?? 0);
+}
+function entryIsFresh(entry) {
+	return entry.options.ttl ? Date.now() <= entry.createdAt + (entry.options.ttl ?? 0) * 1e3 : false;
+}
+function entryIsStale(entry) {
+	return entry.options.swr ? Date.now() <= entry.createdAt + getTotalTtl(entry) * 1e3 : false;
+}
+function entryIsExpired(entry) {
+	return Date.now() > entry.createdAt + getTotalTtl(entry) * 1e3;
+}
+
+//#endregion
+export { entryIsExpired, entryIsFresh, entryIsStale, getTotalTtl };

package/package.json

@@ -0,0 +1,115 @@
+{
+  "name": "@visualbravo/zenstack-cache",
+  "version": "0.0.0",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "@zenstack-cache/source": "./src/index.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.mjs"
+    },
+    "./plugin": {
+      "@zenstack-cache/source": "./src/plugin.ts",
+      "require": "./dist/plugin.cjs",
+      "import": "./dist/plugin.mjs"
+    },
+    "./providers/memory": {
+      "@zenstack-cache/source": "./src/providers/memory.ts",
+      "require": "./dist/providers/memory.cjs",
+      "import": "./dist/providers/memory.mjs"
+    },
+    "./providers/redis": {
+      "@zenstack-cache/source": "./src/providers/redis.ts",
+      "require": "./dist/providers/redis.cjs",
+      "import": "./dist/providers/redis.mjs"
+    },
+    "./schemas": {
+      "@zenstack-cache/source": "./src/schemas.ts",
+      "require": "./dist/schemas.cjs",
+      "import": "./dist/schemas.mjs"
+    },
+    "./superjson": {
+      "@zenstack-cache/source": "./src/superjson.ts",
+      "require": "./dist/superjson.cjs",
+      "import": "./dist/superjson.mjs"
+    },
+    "./types": {
+      "@zenstack-cache/source": "./src/types.ts",
+      "require": "./dist/types.cjs",
+      "import": "./dist/types.mjs"
+    },
+    "./utils": {
+      "@zenstack-cache/source": "./src/utils.ts",
+      "require": "./dist/utils.cjs",
+      "import": "./dist/utils.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "require": "./dist/index.cjs",
+        "import": "./dist/index.mjs"
+      },
+      "./plugin": {
+        "require": "./dist/plugin.cjs",
+        "import": "./dist/plugin.mjs"
+      },
+      "./providers/memory": {
+        "require": "./dist/providers/memory.cjs",
+        "import": "./dist/providers/memory.mjs"
+      },
+      "./providers/redis": {
+        "require": "./dist/providers/redis.cjs",
+        "import": "./dist/providers/redis.mjs"
+      },
+      "./schemas": {
+        "require": "./dist/schemas.cjs",
+        "import": "./dist/schemas.mjs"
+      },
+      "./superjson": {
+        "require": "./dist/superjson.cjs",
+        "import": "./dist/superjson.mjs"
+      },
+      "./types": {
+        "require": "./dist/types.cjs",
+        "import": "./dist/types.mjs"
+      },
+      "./utils": {
+        "require": "./dist/utils.cjs",
+        "import": "./dist/utils.mjs"
+      },
+      "./package.json": "./package.json"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "watch": "tsdown --watch",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix --fix-suggestions",
+    "format:fix": "oxfmt",
+    "test": "vitest run",
+    "test:watch": "vitest --watch"
+  },
+  "dependencies": {
+    "decimal.js": "^10.6.0",
+    "ioredis": "^5.0.0",
+    "murmurhash": "^2.0.1",
+    "stable-hash": "^0.0.6",
+    "superjson": "^2.2.2",
+    "zod": "^4.1.0"
+  },
+  "devDependencies": {
+    "@zenstack-cache/config": "0.0.0",
+    "kysely": "~0.28.8",
+    "better-sqlite3": "12.6.2",
+    "@types/better-sqlite3": "7.6.13"
+  },
+  "peerDependencies": {
+    "@zenstackhq/orm": "canary"
+  },
+  "packageManager": "bun@1.3.6"
+}