@visualbravo/zenstack-cache 0.0.0 → 1.0.1

package/README.md

@@ -1,7 +1,6 @@
 <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.
@@ -11,13 +10,16 @@
     <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 href="https://www.npmjs.com/package/@visualbravo/zenstack-cache">
+      <img alt="NPM Downloads" src="https://img.shields.io/npm/dm/%40visualbravo%2Fzenstack-cache">
     </a>
-    <a href="https://discord.gg/Ykhr738dUe">
-      <img alt="Join the ZenStack server" src="https://img.shields.io/discord/1035538056146595961">
+    <a href="https://github.com/visualbravo/zenstack-cache/actions/workflows/build-and-test.yaml?query=branch%3Adev++">
+      <img alt="Build Status" src="https://img.shields.io/github/actions/workflow/status/visualbravo/zenstack-cache/build-and-test.yaml">
     </a>
-    <a href="https://github.com/visualbravo/zenstack-cache/blob/main/LICENSE">
+    <a href="https://discord.gg/2PaRSu7X">
+      <img alt="Join the ZenStack Cache channel" src="https://img.shields.io/discord/1035538056146595961">
+    </a>
+    <a href="https://github.com/visualbravo/zenstack-cache/blob/76a2de03245c26841b04525dd8b424a8799d654c/LICENSE">
       <img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-green">
     </a>
 
@@ -27,13 +29,14 @@
 </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.
+* 🌐 **Redis Cache:** A central cache to scale across different systems.
+* 🖥️ **Memory Cache:** A simple cache when scale is not a concern.
+* 🛟 **Type-safety:** The caching options appear in the intellisense for all read queries.
+* 🏷️ **Tag-based Invalidation:** Easily invalidate multiple related cache entries.
 
 ## Requirements
 
-* ZenStack (version >= `canary`)
+* ZenStack (version >= `3.3.0`)
 * Node.js (version >= `20.0.0`)
 * Redis (version >= `7.0.0`)
   * ℹ️ Only if you intend to use the `RedisCacheProvider`

package/dist/providers/memory.cjs

@@ -16,10 +16,12 @@ var MemoryCacheProvider = class {
 		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);
+			if (entry.options.tags) for (const tag of entry.options.tags) {
+				const keys = this.tagStore.get(tag);
+				if (!keys) continue;
+				keys.delete(key);
+				if (keys.size === 0) this.tagStore.delete(tag);
+			}
 		}
 	}
 	get(key) {
@@ -40,7 +42,9 @@ var MemoryCacheProvider = class {
 	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);
+			if (!keys) continue;
+			for (const key of keys) this.entryStore.delete(key);
+			this.tagStore.delete(tag);
 		}
 		return Promise.resolve();
 	}

package/dist/providers/memory.mjs

@@ -16,10 +16,12 @@ var MemoryCacheProvider = class {
 		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);
+			if (entry.options.tags) for (const tag of entry.options.tags) {
+				const keys = this.tagStore.get(tag);
+				if (!keys) continue;
+				keys.delete(key);
+				if (keys.size === 0) this.tagStore.delete(tag);
+			}
 		}
 	}
 	get(key) {
@@ -40,7 +42,9 @@ var MemoryCacheProvider = class {
 	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);
+			if (!keys) continue;
+			for (const key of keys) this.entryStore.delete(key);
+			this.tagStore.delete(tag);
 		}
 		return Promise.resolve();
 	}

package/dist/providers/redis.cjs

@@ -11,30 +11,30 @@ var RedisCacheProvider = class {
 		this.redis = new ioredis.Redis(options.url);
 	}
 	async get(key) {
-		const entryJson = await this.redis.get(formatQueryKey(key));
+		const entryJson = await this.redis.get(makeQueryKey(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 queryKey = makeQueryKey(key);
+		multi.set(queryKey, superjson.default.stringify(entry));
 		const totalTtl = require_utils.getTotalTtl(entry);
-		if (totalTtl > 0) multi.expire(formattedKey, totalTtl);
+		if (totalTtl > 0) multi.expire(queryKey, totalTtl);
 		if (entry.options.tags) for (const tag of entry.options.tags) {
-			const formattedTagKey = formatTagKey(tag);
-			multi.sadd(formattedTagKey, formattedKey);
+			const tagKey = makeTagKey(tag);
+			multi.sadd(tagKey, queryKey);
 			if (totalTtl > 0) {
-				multi.expire(formattedTagKey, totalTtl, "GT");
-				multi.expire(formattedTagKey, totalTtl, "NX");
-			}
+				multi.expire(tagKey, totalTtl, "GT");
+				multi.expire(tagKey, totalTtl, "NX");
+			} else multi.persist(tagKey);
 		}
 		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 });
+				const stream = this.redis.sscanStream(makeTagKey(tag), { count: 100 });
 				stream.on("data", async (keys) => {
 					if (keys.length > 1) await this.redis.del(...keys);
 				});
@@ -57,10 +57,10 @@ var RedisCacheProvider = class {
 		});
 	}
 };
-function formatQueryKey(key) {
+function makeQueryKey(key) {
 	return `zenstack:cache:query:${key}`;
 }
-function formatTagKey(key) {
+function makeTagKey(key) {
 	return `zenstack:cache:tag:${key}`;
 }
 

package/dist/providers/redis.mjs

@@ -9,30 +9,30 @@ var RedisCacheProvider = class {
 		this.redis = new Redis(options.url);
 	}
 	async get(key) {
-		const entryJson = await this.redis.get(formatQueryKey(key));
+		const entryJson = await this.redis.get(makeQueryKey(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 queryKey = makeQueryKey(key);
+		multi.set(queryKey, superjson.stringify(entry));
 		const totalTtl = getTotalTtl(entry);
-		if (totalTtl > 0) multi.expire(formattedKey, totalTtl);
+		if (totalTtl > 0) multi.expire(queryKey, totalTtl);
 		if (entry.options.tags) for (const tag of entry.options.tags) {
-			const formattedTagKey = formatTagKey(tag);
-			multi.sadd(formattedTagKey, formattedKey);
+			const tagKey = makeTagKey(tag);
+			multi.sadd(tagKey, queryKey);
 			if (totalTtl > 0) {
-				multi.expire(formattedTagKey, totalTtl, "GT");
-				multi.expire(formattedTagKey, totalTtl, "NX");
-			}
+				multi.expire(tagKey, totalTtl, "GT");
+				multi.expire(tagKey, totalTtl, "NX");
+			} else multi.persist(tagKey);
 		}
 		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 });
+				const stream = this.redis.sscanStream(makeTagKey(tag), { count: 100 });
 				stream.on("data", async (keys) => {
 					if (keys.length > 1) await this.redis.del(...keys);
 				});
@@ -55,10 +55,10 @@ var RedisCacheProvider = class {
 		});
 	}
 };
-function formatQueryKey(key) {
+function makeQueryKey(key) {
 	return `zenstack:cache:query:${key}`;
 }
-function formatTagKey(key) {
+function makeTagKey(key) {
 	return `zenstack:cache:tag:${key}`;
 }
 

package/dist/schemas.cjs

@@ -4,8 +4,8 @@ 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(),
+	ttl: zod.default.int().positive().optional(),
+	swr: zod.default.int().positive().optional(),
 	tags: zod.default.string().array().optional()
 });
 const cacheEnvelopeSchema = zod.default.object({ cache: cacheOptionsSchema.optional() });

package/dist/schemas.d.cts

@@ -2,14 +2,14 @@ import z from "zod";
 
 //#region src/schemas.d.ts
 declare const cacheOptionsSchema: z.ZodObject<{
-  ttl: z.ZodOptional<z.ZodNumber>;
-  swr: z.ZodOptional<z.ZodNumber>;
+  ttl: z.ZodOptional<z.ZodInt>;
+  swr: z.ZodOptional<z.ZodInt>;
   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>;
+    ttl: z.ZodOptional<z.ZodInt>;
+    swr: z.ZodOptional<z.ZodInt>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
   }, z.core.$strict>>;
 }, z.core.$strip>;

package/dist/schemas.d.mts

@@ -2,14 +2,14 @@ import z from "zod";
 
 //#region src/schemas.d.ts
 declare const cacheOptionsSchema: z.ZodObject<{
-  ttl: z.ZodOptional<z.ZodNumber>;
-  swr: z.ZodOptional<z.ZodNumber>;
+  ttl: z.ZodOptional<z.ZodInt>;
+  swr: z.ZodOptional<z.ZodInt>;
   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>;
+    ttl: z.ZodOptional<z.ZodInt>;
+    swr: z.ZodOptional<z.ZodInt>;
     tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
   }, z.core.$strict>>;
 }, z.core.$strip>;

package/dist/schemas.mjs

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

package/dist/utils.cjs

@@ -4,13 +4,15 @@ 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;
+	return entry.options.ttl ? Date.now() <= entry.createdAt + (entry.options.ttl ?? 0) * 1e3 : !entry.options.swr;
 }
 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;
+	const totalTtl = getTotalTtl(entry);
+	if (totalTtl === 0) return false;
+	return Date.now() > entry.createdAt + totalTtl * 1e3;
 }
 
 //#endregion

package/dist/utils.mjs

@@ -3,13 +3,15 @@ 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;
+	return entry.options.ttl ? Date.now() <= entry.createdAt + (entry.options.ttl ?? 0) * 1e3 : !entry.options.swr;
 }
 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;
+	const totalTtl = getTotalTtl(entry);
+	if (totalTtl === 0) return false;
+	return Date.now() > entry.createdAt + totalTtl * 1e3;
 }
 
 //#endregion

package/package.json

@@ -1,10 +1,20 @@
 {
   "name": "@visualbravo/zenstack-cache",
-  "version": "0.0.0",
+  "version": "1.0.1",
+  "license": "MIT",
+  "repository": "github:visualbravo/zenstack-cache",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.cts",
+  "keywords": [
+    "zenstack",
+    "cache",
+    "caching",
+    "prisma",
+    "accelerate",
+    "orm"
+  ],
   "exports": {
     ".": {
       "@zenstack-cache/source": "./src/index.ts",
@@ -103,13 +113,13 @@
     "zod": "^4.1.0"
   },
   "devDependencies": {
+    "@types/better-sqlite3": "7.6.13",
     "@zenstack-cache/config": "0.0.0",
-    "kysely": "~0.28.8",
     "better-sqlite3": "12.6.2",
-    "@types/better-sqlite3": "7.6.13"
+    "kysely": "~0.28.8"
   },
   "peerDependencies": {
     "@zenstackhq/orm": "canary"
   },
-  "packageManager": "bun@1.3.6"
+  "packageManager": "bun@1.3.8"
 }