@nowarajs/elysia-cache 1.2.9 → 1.3.1

package/AGENTS.md

@@ -0,0 +1,44 @@
+---
+name: Development_Workflow_and_Code_Standards
+description: Guidelines for development workflow and code standards
+applyTo: '**'
+---
+
+## TypeScript and Project Conventions
+1. Use underscore prefix for private or non-exported elements (e.g., _privateMethod)
+2. Always specify visibility modifiers (private, protected, public), plus readonly, override, etc. when applicable
+3. Naming conventions: camelCase for variables/functions/methods; PascalCase for classes/interfaces/types; SCREAMING_CASE for constants
+4. Explicit typing: Always specify types for variables, parameters, and return values; never use any; prefer unknown if type cannot be determined; prefer interface over type alias for extendable objects
+5. Documentation: Use TSDoc style; explain purpose, parameters, return values, and behavior; only document code when requested; for @throws, use format "@throws ({@link Type}) – description"; for object/interface properties, write comment above each property instead of @param
+6. Control structures: Omit curly braces for single-statement bodies
+7. Path Aliases: Use $ for internal imports; do not import barrel files except as entry points
+8. Export Pattern: Each directory has index.ts re-exporting public items; types exported in types/index.ts
+9. Function style: Class methods use standard method syntax; helpers/callbacks/HOFs prefer arrow functions unless function syntax is required
+
+## Contribution Principles
+1. Follow TypeScript best practices and idiomatic patterns
+2. Maintain existing code structure and modular organization
+3. Keep developer experience in mind
+4. Keep pull requests focused and well-documented (with TsDoc if asked)
+5. Commit different types of changes separately; avoid mixing tests and features in one commit
+
+## Commit Message Convention (Conventional Commits + Emoji)
+Format: <type>(<emoji>): [summary up to 72 chars]
+(blank line, then context or description)
+
+<type> is lowercase
+summary is surrounded by brackets `[summary]`
+
+Types:
+feat(🚀) – New features
+fix(🔧) – Bug fixes
+perf(⚡) – Performance improvements
+refactor(🧹) – Refactoring
+build(📦) – Build tools / dependency changes
+types(🌊) – Type definitions
+chore(🦉) – Maintenance, non-code/test changes
+examples(🏀) – Example updates
+docs(📖) – Documentation changes
+test(🧪) – Test code updates
+style(🎨) – Style/formatting only
+ci(🤖) – CI/CD configuration

package/README.md

@@ -8,6 +8,11 @@
 	- [✨ Features](#-features)
 	- [🔧 Installation](#-installation)
 	- [⚙️ Usage](#-usage)
+		- [Basic Setup (In-Memory Store)](#basic-setup-in-memory-store)
+		- [Cache Configuration](#cache-configuration)
+		- [Redis Store Setup (Production)](#redis-store-setup-production)
+		- [Route-specific Caching](#route-specific-caching)
+		- [Storage Options](#storage-options)
 	- [📊 Cache Headers](#-cache-headers)
 	- [📚 API Reference](#-api-reference)
 	- [⚖️ License](#-license)
@@ -56,7 +61,9 @@ const app = new Elysia()
 		// This response will be cached automatically
 		return await fetchUsers()
 	}, {
-		isCached: true // Enable caching for this route
+		isCached: {
+			ttl: 300  // Cache for 5 minutes
+		}
 	})
 	.listen(3000)
 ```
@@ -66,18 +73,15 @@ const app = new Elysia()
 ```ts
 import { cache } from '@nowarajs/elysia-cache'
 
+// Using in-memory store (default)
 const app = new Elysia()
-	.use(cache({
-		defaultTtl: 300,     // Cache for 5 minutes by default
-		prefix: 'api:',      // Add prefix to cache keys
-		storage: ':memory:'  // Use in-memory storage (default)
-	}))
+	.use(cache())
 ```
 
 ### Redis Store Setup (Production)
 
 ```ts
-import { IoRedisStore } from '@nowarajs/kv-store'
+import { IoRedisStore } from '@nowarajs/kv-store/ioredis' // or you can use BunRedis with /bun-redis
 import { cache } from '@nowarajs/elysia-cache'
 
 // Create Redis store instance
@@ -89,36 +93,25 @@ await redisStore.connect()
 
 // Create application with Redis-backed caching
 const app = new Elysia()
-	.use(cache({
-		storage: redisStore,
-		defaultTtl: 600
-	}))
+	.use(cache(redisStore))
 ```
 
 ### Route-specific Caching
 
 ```ts
 const app = new Elysia()
-	.use(cache({ defaultTtl: 60 }))
+	.use(cache())
 	.get('/fast', () => getData(), {
-		isCached: 30  // Cache for 30 seconds
+		isCached: { ttl: 30 }  // Cache for 30 seconds
 	})
 	.get('/slow', () => getSlowData(), {
-		isCached: 3600  // Cache for 1 hour
+		isCached: { ttl: 3600 }  // Cache for 1 hour
 	})
-	.get('/no-cache', () => getRealTimeData(), {
-		isCached: false  // Disable caching
+	.get('/prefixed', () => getData(), {
+		isCached: { ttl: 60, prefix: 'api:' }  // With custom prefix
 	})
 ```
 
-### Storage Options
-
-| Store Type | Usage | Best For |
-|------------|-------|----------|
-| Default (`:memory:`) | `cache({ defaultTtl: 60 })` | Development, single instance |
-| Explicit Memory | `cache({ storage: new MemoryStore(), ... })` | When you need store reference |
-| Redis Store | `cache({ storage: redisStore, ... })` | Production, distributed systems |
-
 ## 📊 Cache Headers
 
 The plugin automatically adds these headers to all responses:
@@ -143,36 +136,6 @@ X-Cache: HIT
 
 ## 📚 API Reference
 
-### Cache Options
-
-```ts
-interface CacheOptions {
-	/** Default TTL in seconds (default: 60) */
-	defaultTtl?: number
-	
-	/** Cache key prefix (default: '') */
-	prefix?: string
-	
-	/** Storage backend (default: ':memory:') */
-	storage?: ':memory:' | KvStore
-}
-```
-
-### Macro: `isCached`
-
-The `isCached` macro enables caching for specific routes:
-
-```ts
-// Enable with default TTL
-{ isCached: true }
-
-// Enable with custom TTL (in seconds)
-{ isCached: 300 }
-
-// Disable caching
-{ isCached: false }
-```
-
 You can find the complete API reference documentation for `Elysia Cache` at:
 
 - [TypeDoc Documentation](https://nowarajs.github.io/elysia-cache)
@@ -183,6 +146,6 @@ Distributed under the MIT License. See [LICENSE](./LICENSE) for more information
 
 ## 📧 Contact
 
+- Mail: [nowarajs@pm.me](mailto:nowarajs@pm.me)
 - GitHub: [NowaraJS](https://github.com/NowaraJS)
-- Package: [@nowarajs/elysia-cache](https://www.npmjs.com/package/@nowarajs/elysia-cache)
 

package/dist/cache.d.ts

@@ -1,12 +1,9 @@
+import type { KvStore } from '@nowarajs/kv-store/types';
 import { Elysia } from 'elysia';
-import { MemoryStore } from '@nowarajs/kv-store/memory';
 import type { CacheOptions } from './types/cache-options';
-export declare const cache: ({ defaultTtl, prefix, store }?: CacheOptions) => Elysia<"", {
+export declare const cache: (store?: KvStore) => Elysia<"", {
     decorator: {};
-    store: {
-        kvStore: import("@nowarajs/kv-store/types").KvStore | MemoryStore;
-        _cachedRoutes: Set<string>;
-    };
+    store: {};
     derive: {};
     resolve: {};
 }, {
@@ -16,11 +13,11 @@ export declare const cache: ({ defaultTtl, prefix, store }?: CacheOptions) => El
     schema: {};
     standaloneSchema: {};
     macro: Partial<{
-        readonly isCached: number | boolean;
+        readonly isCached: CacheOptions;
     }>;
     macroFn: {
-        readonly isCached: (enable: boolean | number) => {
-            readonly afterHandle: ({ set, responseValue, store, request }: {
+        readonly isCached: ({ ttl, prefix }: CacheOptions) => {
+            readonly afterHandle: ({ set, responseValue, request }: {
                 body: unknown;
                 query: Record<string, string>;
                 params: {};
@@ -37,10 +34,7 @@ export declare const cache: ({ defaultTtl, prefix, store }?: CacheOptions) => El
                 path: string;
                 route: string;
                 request: Request;
-                store: {
-                    kvStore: import("@nowarajs/kv-store/types").KvStore | MemoryStore;
-                    _cachedRoutes: Set<string>;
-                };
+                store: {};
                 status: <const Code extends number | keyof import("elysia").StatusMap, const T = Code extends 100 | 101 | 102 | 103 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 300 | 301 | 302 | 303 | 304 | 307 | 308 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 420 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511 ? {
                     readonly 100: "Continue";
                     readonly 101: "Switching Protocols";

package/dist/index.js

@@ -1,66 +1,85 @@
 // @bun
-import {
-  generateCacheKey
-} from "./chunk-kqx0zdcn.js";
-
 // source/cache.ts
-import { Elysia } from "elysia";
 import { MemoryStore } from "@nowarajs/kv-store/memory";
-var cache = ({
-  defaultTtl = 60,
-  prefix = "",
-  store = ":memory:"
-} = {}) => new Elysia().state({
-  kvStore: store === ":memory:" ? new MemoryStore : store
-}).state({
-  _cachedRoutes: new Set
-}).onRequest(async ({ request, store: store2, set }) => {
-  const sanitizeUrl = new URL(request.url).pathname;
-  if (store2._cachedRoutes.has(`${request.method}:${sanitizeUrl}`)) {
-    const cacheKey = await generateCacheKey(request.clone());
-    const cachedData = await store2.kvStore.get(`${prefix}${cacheKey}`);
-    if (cachedData && typeof cachedData === "object" && "response" in cachedData && "metadata" in cachedData) {
-      const { response, metadata } = cachedData;
-      set.headers["cache-control"] = `max-age=${metadata.ttl}, public`;
-      set.headers["x-cache"] = "HIT";
-      set.headers["etag"] = `"${prefix}${cacheKey}"`;
-      set.headers["expires"] = new Date(Date.now() + metadata.ttl * 1000).toUTCString();
-      set.headers["last-modified"] = metadata.createdAt;
-      if (response instanceof Response)
-        return response.clone();
-      return response;
+import { Elysia } from "elysia";
+
+// source/utils/generate-cache-key.ts
+var _calculateBodyHash = async (body, hasher) => {
+  if (!body)
+    return;
+  const reader = body.getReader();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done)
+        break;
+      if (value)
+        hasher.update(new Uint8Array(value));
     }
-    set.headers["x-cache"] = "MISS";
+  } finally {
+    reader.releaseLock();
   }
-  return;
-}).macro({
-  isCached: (enable) => {
-    const ttl = typeof enable === "number" ? enable : enable ? defaultTtl : 0;
-    return {
-      async afterHandle({ set, responseValue, store: store2, request }) {
-        const sanitizeUrl = new URL(request.url).pathname;
-        if (!store2._cachedRoutes.has(`${request.method}:${sanitizeUrl}`))
-          store2._cachedRoutes.add(`${request.method}:${sanitizeUrl}`);
+};
+var generateCacheKey = async (request) => {
+  const { method, url, headers } = request;
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(method);
+  hasher.update(url);
+  hasher.update(JSON.stringify(headers));
+  await _calculateBodyHash(request.body, hasher);
+  return hasher.digest("hex");
+};
+
+// source/cache.ts
+var cache = (store = new MemoryStore) => {
+  const cachedRoutes = new Map;
+  return new Elysia().onRequest(async ({ request, set }) => {
+    const route = `${request.method}:${new URL(request.url).pathname}`;
+    if (cachedRoutes.has(route)) {
+      const { ttl, prefix } = cachedRoutes.get(route);
+      const cacheKey = await generateCacheKey(request.clone());
+      const cacheItem = await store.get(`${prefix}${cacheKey}`);
+      if (cacheItem && typeof cacheItem === "object" && "response" in cacheItem && "metadata" in cacheItem) {
+        const createdAt = new Date(cacheItem.metadata.createdAt);
+        const expiresAt = new Date(createdAt.getTime() + ttl * 1000);
+        const now = Date.now();
+        const remaining = Math.max(0, Math.ceil((expiresAt.getTime() - now) / 1000));
+        set.headers["cache-control"] = `max-age=${remaining}, public`;
+        set.headers["etag"] = `"${prefix}${cacheKey}"`;
+        set.headers["last-modified"] = cacheItem.metadata.createdAt;
+        set.headers["expires"] = expiresAt.toUTCString();
+        set.headers["x-cache"] = "HIT";
+        if (cacheItem.response instanceof Response)
+          return cacheItem.response.clone();
+        return cacheItem.response;
+      }
+      set.headers["x-cache"] = "MISS";
+    }
+    return;
+  }).macro({
+    isCached: ({ ttl, prefix = "" }) => ({
+      async afterHandle({ set, responseValue, request }) {
+        const route = `${request.method}:${new URL(request.url).pathname}`;
+        if (!cachedRoutes.has(route))
+          cachedRoutes.set(route, { ttl, prefix });
         const cacheKey = await generateCacheKey(request.clone());
         const now = new Date;
         set.headers["cache-control"] = `max-age=${ttl}, public`;
         set.headers["etag"] = `"${prefix}${cacheKey}"`;
         set.headers["last-modified"] = now.toUTCString();
         set.headers["expires"] = new Date(now.getTime() + ttl * 1000).toUTCString();
-        if (!set.headers["x-cache"])
-          set.headers["x-cache"] = "MISS";
-        const cacheData = {
+        set.headers["x-cache"] = "MISS";
+        const cacheItem = {
           response: responseValue instanceof Response ? responseValue.clone() : responseValue,
           metadata: {
-            createdAt: now.toUTCString(),
-            ttl
+            createdAt: now.toUTCString()
           }
         };
-        await store2.kvStore.set(`${prefix}${cacheKey}`, cacheData, ttl);
+        await store.set(`${prefix}${cacheKey}`, cacheItem, ttl);
       }
-    };
-  }
-});
+    })
+  });
+};
 export {
   cache
 };

package/dist/types/cache-item.d.ts

@@ -2,6 +2,5 @@ export interface CacheItem {
     response: unknown;
     metadata: {
         createdAt: string;
-        ttl: number;
     };
 }

package/dist/types/cache-options.d.ts

@@ -1,21 +1,12 @@
-import type { KvStore } from '@nowarajs/kv-store/types';
 export interface CacheOptions {
     /**
-     * Default TTL in seconds
-     *
-     * @defaultValue 60
+     * TTL in seconds
      */
-    defaultTtl?: number;
+    ttl: number;
     /**
      * Cache key prefix
      *
      * @defaultValue ''
      */
     prefix?: string;
-    /**
-     * Storage backend
-     *
-     * @defaultValue ':memory:'
-     */
-    store?: ':memory:' | KvStore;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nowarajs/elysia-cache",
-	"version": "1.2.9",
+	"version": "1.3.1",
 	"author": "NowaraJS",
 	"description": "A template to create a bun package.",
 	"type": "module",
@@ -23,24 +23,24 @@
 		"test": "bun test --coverage"
 	},
 	"devDependencies": {
-		"@eslint/js": "^9.36.0",
-		"@nowarajs/error": "^1.3.2",
-		"@nowarajs/kv-store": "^1.1.6",
-		"@stylistic/eslint-plugin": "^5.4.0",
-		"@types/bun": "^1.2.22",
-		"eslint": "^9.36.0",
-		"globals": "^16.4.0",
-		"typescript-eslint": "^8.44.1",
-		"typescript": "^5.9.2"
+		"@eslint/js": "^9.39.2",
+		"@nowarajs/error": "^1.3.10",
+		"@nowarajs/kv-store": "^1.3.0",
+		"@stylistic/eslint-plugin": "^5.6.1",
+		"@types/bun": "^1.3.5",
+		"elysia": "^1.4.19",
+		"eslint": "^9.39.2",
+		"globals": "^16.5.0",
+		"typescript": "^5.9.3",
+		"typescript-eslint": "^8.51.0"
 	},
 	"peerDependencies": {
-		"@nowarajs/error": "^1.3.2",
-		"@nowarajs/kv-store": "^1.1.6",
-		"elysia": "^1.4.7"
+		"@nowarajs/error": "^1.3.10",
+		"@nowarajs/kv-store": "^1.3.0",
+		"elysia": "^1.4.19"
 	},
 	"exports": {
 		"./types": "./dist/types/index.js",
-		"./utils": "./dist/utils/index.js",
 		".": "./dist/index.js"
 	},
 	"changelog": {
@@ -74,19 +74,24 @@
 				"semver": "patch"
 			},
 			"chore": {
-				"title": "🦉 Chore"
+				"title": "🦉 Chore",
+				"semver": "patch"
 			},
 			"examples": {
-				"title": "🏀 Examples"
+				"title": "🏀 Examples",
+				"semver": "patch"
 			},
 			"test": {
-				"title": "🧪 Tests"
+				"title": "🧪 Tests",
+				"semver": "patch"
 			},
 			"style": {
-				"title": "🎨 Styles"
+				"title": "🎨 Styles",
+				"semver": "patch"
 			},
 			"ci": {
-				"title": "🤖 CI"
+				"title": "🤖 CI",
+				"semver": "patch"
 			}
 		},
 		"templates": {
@@ -98,8 +103,5 @@
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/NowaraJS/elysia-cache.git"
-	},
-	"dependencies": {
-		"ioredis": "^5.8.0"
 	}
 }

package/dist/chunk-kqx0zdcn.js

@@ -1,29 +0,0 @@
-// @bun
-// source/utils/generate-cache-key.ts
-var _calculateBodyHash = async (body, hasher) => {
-  if (!body)
-    return;
-  const reader = body.getReader();
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done)
-        break;
-      if (value)
-        hasher.update(new Uint8Array(value));
-    }
-  } finally {
-    reader.releaseLock();
-  }
-};
-var generateCacheKey = async (request) => {
-  const { method, url, headers } = request;
-  const hasher = new Bun.CryptoHasher("sha256");
-  hasher.update(method);
-  hasher.update(url);
-  hasher.update(JSON.stringify(headers));
-  await _calculateBodyHash(request.body, hasher);
-  return hasher.digest("hex");
-};
-
-export { generateCacheKey };

package/dist/utils/index.d.ts

@@ -1 +0,0 @@
-export { generateCacheKey } from './generate-cache-key';

package/dist/utils/index.js

@@ -1,7 +0,0 @@
-// @bun
-import {
-  generateCacheKey
-} from "../chunk-kqx0zdcn.js";
-export {
-  generateCacheKey
-};