@clov-std/elysia-cache 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clov
+
+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,157 @@
+<p align="center">
+  <img src="https://cdn.jsdelivr.net/gh/ClovLabs/std@main/packages/elysia-cache/logo-elysia-cache.png" alt="Clov Elysia Cache logo" width="200" />
+</p>
+
+# ⚡ Clov Elysia Cache
+
+Response caching for Elysia routes, guards, and groups, as a macro.  
+Drop `isCached` on any endpoint and repeated requests are served from the store before your logic ever runs.
+
+## Why this package?
+
+This plugin uses Elysia's macro system to add response caching to any route, guard, or group.  
+You add `isCached: { ttl: 60 }` and you're done.
+
+Cache keys are readable strings built from the request method, URL, the `vary` headers (default: `authorization`), and the parsed body - so different inputs never collide. `generateCacheKey` builds them, and keys longer than 1024 characters are hashed with SHA-256 before being stored.
+
+Storage is handled by `@clov-std/kv-store`, so you start with in-memory and move to Redis when you need to, without changing your routes.
+
+## 📌 Table of Contents
+
+- [Features](#-features)
+- [Installation](#-installation)
+- [Usage](#-usage)
+- [Cache semantics](#-cache-semantics)
+- [API Reference](#-api-reference)
+- [License](#-license)
+- [Contact](#-contact)
+
+## ✨ Features
+
+- 🎯 **Per-route macros** : Attach `isCached` to any route independently, with its own `ttl` and options.
+- 🔑 **Readable keys** : `method:url`, the `vary` header values, and the parsed body - SHA-256 hashed only when the key exceeds 1024 characters.
+- 🗃️ **KvStore-agnostic** : Works with `MemoryStore` out of the box; swap in `BunRedisStore` or your own adapter.
+- ⚡ **Early serving** : Returns the cached response in `beforeHandle`, before handlers run.
+- 📡 **Cache headers** : Sets `Cache-Control: max-age=N, private` and `X-Cache: HIT` / `MISS`.
+- 🛡️ **Opaque-body safety** : Requests carrying `Blob` / `ArrayBuffer` / typed-array bodies are never keyed, never cached.
+
+## 🔧 Installation
+
+```bash
+bun add @clov-std/elysia-cache elysia typebox
+```
+
+> **Peer dependencies:** `elysia`(v2) and `typebox` must be installed alongside.
+
+## ⚙️ Usage
+
+### Basic - cache GET responses
+
+The simplest form: pass `ttl` (time to live in seconds). Responses are cached for that window.
+
+```ts
+import { cachePlugin } from '@clov-std/elysia-cache';
+import { Elysia } from 'elysia';
+
+new Elysia()
+	.use(cachePlugin())
+	.get(
+		'/catalog/items',
+		{ isCached: { ttl: 60 } }, // cached for 60 seconds
+		() => listItems()
+	)
+	.listen(3000);
+```
+
+### Custom store - Redis
+
+By default, cached responses are kept in memory. Pass a `BunRedisStore` (or any `KvStore` adapter) for persistence across restarts and multi-instance deployments.
+
+```ts
+import { BunRedisStore } from '@clov-std/kv-store';
+import { cachePlugin } from '@clov-std/elysia-cache';
+import { Elysia } from 'elysia';
+
+const store = new BunRedisStore('redis://localhost:6379');
+
+new Elysia()
+	.use(cachePlugin(store))
+	.get('/catalog/items', { isCached: { ttl: 60 } }, () => listItems())
+	.listen(3000);
+```
+
+> **Note:** Elysia keeps one plugin instance per name, so the store must be passed to the first `cachePlugin()` used in the app tree. A later `cachePlugin(otherStore)` on the same app is ignored.
+
+### Narrowing the key - `vary`
+
+The default key only includes the `authorization` header. If a route varies on more headers, list them in `vary`:
+
+```ts
+new Elysia()
+	.use(cachePlugin())
+	.get(
+		'/catalog/items',
+		{ isCached: { ttl: 60, vary: ['authorization', 'accept-language'] } },
+		() => listItems()
+	)
+	.listen(3000);
+```
+
+### Custom key generation
+
+For full control, pass a `keyGenerator`. It receives the `Request` and the parsed body, and can return a string, `undefined` (opts the request out of caching), or a promise of either. When provided, `vary` is not used.
+
+```ts
+import { cachePlugin, generateCacheKey } from '@clov-std/elysia-cache';
+import { Elysia } from 'elysia';
+
+new Elysia()
+	.use(cachePlugin())
+	.get(
+		'/catalog/items',
+		{
+			isCached: {
+				ttl: 60,
+				keyGenerator: (request, body) => generateCacheKey(request, body, ['accept-language'])
+			}
+		},
+		() => listItems()
+	)
+	.listen(3000);
+```
+
+> **Tip:** `generateCacheKey` is exported so you can reuse the default key format with your own header subset.
+
+## 🧯 Cache semantics
+
+A cache hit short-circuits the handler: the stored response is returned from `beforeHandle` with `X-Cache: HIT` and `Cache-Control: max-age=<remaining>, private`, computed from the entry's creation time.
+
+A miss runs the handler, stores the response with the `ttl`, and stamps `X-Cache: MISS` with `Cache-Control: max-age=<ttl>, private`. `Response` instances are cloned before being stored or replayed, so a cached body can be reused across requests. `undefined` return values are never cached, and requests whose parsed body is (or contains) binary data (`Blob`, `ArrayBuffer`, typed arrays) are skipped entirely.
+
+## 📚 API Reference
+
+### `cachePlugin(store?)`
+
+Creates the plugin. `store` defaults to a new `MemoryStore`.
+
+### `generateCacheKey(request, body?, vary?)`
+
+Builds the key for a request: `method:url`, the `vary` header values, then the parsed body. Without `vary`, every request header is included. Returns `undefined` when the body is opaque and the request must not be cached.
+
+### `CacheOptions`
+
+| Option         | Type                                                                              | Default                                        | Description                                                                 |
+| -------------- | --------------------------------------------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------- |
+| `ttl`          | `number`                                                                          | -                                              | Time to live, in seconds.                                                   |
+| `vary`         | `string[]`                                                                        | `['authorization']`                            | Header names included in the key.                                           |
+| `keyGenerator` | `(request: Request, body: unknown) => string \| undefined \| Promise<string \| undefined>` | `generateCacheKey(request, body, vary)` | Custom key builder. Returning `undefined` opts the request out of caching. |
+
+Full docs: [https://clovlabs.github.io/std/](https://clovlabs.github.io/std/)
+
+## ⚖️ License
+
+MIT - see [LICENSE.md](LICENSE.md).
+
+## 📧 Contact
+
+Maintained by [Clov](https://github.com/ClovLabs).

package/dist/cache.d.ts

@@ -0,0 +1,84 @@
+import { type KvStore } from '@clov-std/kv-store';
+import { Elysia, type HTTPHeaders } from 'elysia';
+/**
+ * Generates a cache key from a request and the body Elysia parsed for it
+ *
+ * The key is a readable string built like the rate limit plugin's: `method:url` followed by
+ * the `vary` header values and the body. The cache macro prefixes it with `cache:` and
+ * hashes it when it grows past the store's key limit.
+ *
+ * @param request - The request to generate a cache key for
+ * @param body - The parsed body, keying on it avoids consuming the raw stream
+ * @param vary - Header names to include in the key, every header is included when omitted.
+ *   Iterating all of them is both the slowest part of this function and what fragments the
+ *   cache per client, so a route that varies on a few headers should list them.
+ * @returns The key, or `undefined` when the request cannot be keyed and must not be cached
+ */
+export declare const generateCacheKey: (request: Request, body?: unknown, vary?: string[]) => string | undefined;
+type CacheDerived = {
+    cacheKey?: string;
+};
+interface CacheDeriveContext {
+    request: Request;
+    body: unknown;
+}
+interface CacheContext extends CacheDerived {
+    set: {
+        headers: HTTPHeaders;
+    };
+}
+interface CacheAfterHandleContext extends CacheContext {
+    responseValue: unknown;
+}
+export interface CacheOptions {
+    /**
+     * TTL in seconds
+     */
+    ttl: number;
+    /**
+     * Header names the key varies on. Only those are hashed instead of every request header,
+     * which keeps the cache from fragmenting on `user-agent`, `accept-encoding`, etc.
+     *
+     * @defaultValue every request header
+     */
+    vary?: string[];
+    /**
+     * Builds the cache key for a request. Returning `undefined` leaves that request uncached,
+     * which is also the way to opt a request out
+     *
+     * @defaultValue {@link generateCacheKey}
+     */
+    keyGenerator?: (request: Request, body: unknown) => string | undefined | Promise<string | undefined>;
+}
+type CacheMacro = (options: CacheOptions) => {
+    derive: (context: CacheDeriveContext) => Promise<CacheDerived>;
+    beforeHandle: (context: CacheContext) => Promise<unknown>;
+    afterHandle: (context: CacheAfterHandleContext) => Promise<void>;
+};
+/**
+ * Creates the cache plugin
+ *
+ * Elysia keeps one definition per plugin name, so every `cachePlugin()` of an app tree
+ * resolves to a single plugin instance — the first one. Pass the store here to change it
+ * for the whole app, a later `cachePlugin(store)` is ignored.
+ */
+export declare const cachePlugin: (store?: KvStore) => Elysia<'cachePlugin', 'local', {
+    decorator: {};
+    derive: {};
+    store: {};
+}, {
+    typebox: {};
+    error: [];
+}, {
+    schema: {};
+    schemas: {};
+    macro: Partial<{
+        readonly isCached: CacheOptions;
+    }>;
+    macroFn: {
+        isCached: CacheMacro;
+    };
+    parser: {};
+    response: {};
+}>;
+export {};

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { cachePlugin, generateCacheKey, type CacheOptions } from './cache';

package/dist/index.js

@@ -0,0 +1,77 @@
+// @bun
+// src/cache.ts
+import { MemoryStore } from "@clov-std/kv-store";
+import { Elysia } from "elysia";
+var isOpaque = (value) => value instanceof Blob || value instanceof ArrayBuffer || ArrayBuffer.isView(value);
+var MAX_KEY_LENGTH = 1024;
+var generateCacheKey = (request, body, vary) => {
+  const { method, url, headers } = request;
+  let key = `${method}:${url}`;
+  if (vary)
+    for (const name of vary)
+      key += `:${name}=${headers.get(name) ?? ""}`;
+  else
+    for (const [name, value] of headers)
+      key += `:${name}=${value}`;
+  if (typeof body === "string")
+    key += `:${body}`;
+  else if (body !== undefined && body !== null) {
+    if (isOpaque(body) || Object.values(body).some(isOpaque))
+      return;
+    key += `:${JSON.stringify(body)}`;
+  }
+  return key;
+};
+var cachePlugin = (store = new MemoryStore) => new Elysia({ name: "cachePlugin" }).macro({
+  isCached: ({
+    ttl,
+    vary = ["authorization"],
+    keyGenerator = (request, body) => generateCacheKey(request, body, vary)
+  }) => ({
+    derive: async ({ request, body }) => {
+      const key = await keyGenerator(request, body);
+      if (key === undefined)
+        return {};
+      const cacheKey = `cache:${key}`;
+      if (cacheKey.length > MAX_KEY_LENGTH)
+        return {
+          cacheKey: `cache:${new Bun.CryptoHasher("sha256").update(cacheKey).digest("hex")}`
+        };
+      return { cacheKey };
+    },
+    beforeHandle: async ({ cacheKey, set }) => {
+      if (cacheKey === undefined)
+        return;
+      const cacheItem = await store.get(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 remaining = Math.max(0, Math.ceil((expiresAt.getTime() - Date.now()) / 1000));
+        set.headers["cache-control"] = `max-age=${remaining}, private`;
+        set.headers["x-cache"] = "HIT";
+        if (cacheItem.response instanceof Response)
+          return cacheItem.response.clone();
+        return cacheItem.response;
+      }
+      return;
+    },
+    afterHandle: async ({ cacheKey, set, responseValue }) => {
+      if (cacheKey === undefined || responseValue === undefined || set.headers["x-cache"] === "HIT")
+        return;
+      const now = new Date;
+      set.headers["cache-control"] = `max-age=${ttl}, private`;
+      set.headers["x-cache"] = "MISS";
+      const cacheItem = {
+        response: responseValue instanceof Response ? responseValue.clone() : responseValue,
+        metadata: {
+          createdAt: now.toUTCString()
+        }
+      };
+      await store.set(cacheKey, cacheItem, ttl);
+    }
+  })
+});
+export {
+  cachePlugin,
+  generateCacheKey
+};

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@clov-std/elysia-cache",
+  "version": "1.0.0",
+  "description": "Cache plugin for Elysia framework.",
+  "keywords": [
+    "bun",
+    "clov",
+    "elysia",
+    "macro",
+    "open-source",
+    "plugin",
+    "cache",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "Clov",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ClovLabs/std.git",
+    "directory": "packages/elysia-rcache"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun builder.ts",
+    "docs": "bunx typedoc --tsconfig tsconfig.build.json",
+    "fmt:check": "oxfmt --check",
+    "fmt": "oxfmt",
+    "lint:fix": "oxlint --type-aware --type-check --fix ./src",
+    "lint:github": "oxlint --type-aware --type-check --format=github ./src",
+    "lint": "oxlint --type-aware --type-check ./src",
+    "test": "bun test --pass-with-no-tests --coverage"
+  },
+  "dependencies": {
+    "@clov-std/kv-store": "workspace:^"
+  },
+  "devDependencies": {
+    "@types/bun": "catalog:base",
+    "oxfmt": "catalog:base",
+    "oxlint": "catalog:base",
+    "oxlint-tsgolint": "catalog:base",
+    "typescript": "catalog:base"
+  },
+  "peerDependencies": {
+    "@clov-std/kv-store": "workspace:^",
+    "elysia": "next",
+    "typebox": "^1.3.11"
+  }
+}