rust-node-cache 0.2.1 → 0.3.0

package/README.md

@@ -1,11 +1,15 @@
 # rust-node-cache
 
-**Ultra-fast in-memory cache powered by Rust.**
+**In-memory cache for Node.js that keeps your data off the V8 heap.**
 
-`rust-node-cache` is a high-performance in-memory cache for Node.js applications
-with a core written in Rust. It is built on top of a concurrent, lock-sharded
-hash map ([DashMap](https://docs.rs/dashmap)), giving you fast reads, fast
-writes, and thread-safe access with very low overhead.
+`rust-node-cache` stores entries in Rust memory instead of on the JavaScript
+heap. A large cache adds nothing for the garbage collector to trace, so it does
+not lengthen GC pauses or count against `--max-old-space-size`. Eviction is
+exact LRU in O(1), with an optional TTL per entry and a background sweeper.
+
+Values are kept as JSON. If you want the fastest possible cache of live object
+references, use [`lru-cache`](https://www.npmjs.com/package/lru-cache) — see
+[When to use it](#when-to-use-it).
 
 It ships as a prebuilt native addon (via [napi-rs](https://napi.rs/)), so there
 is **no compiler required at install time** on supported platforms.
@@ -21,12 +25,13 @@ is **no compiler required at install time** on supported platforms.
 
 ## Features
 
-- 🦀 **Rust-powered** core for predictable, low-overhead performance
-- 🔒 **Thread-safe** via `DashMap` (lock-sharded concurrent map)
-- ⏱️ **TTL support** per entry (lazy expiration + active cleanup)
+- 🦀 **Off-heap storage** — entries live in Rust memory; the V8 heap and GC do not see them
+- 🧠 **Exact LRU eviction in O(1)** — bound the cache by `maxSize` with `evictionPolicy: "lru"`
+- ⏱️ **TTL support** per entry, with millisecond precision (lazy expiration + active cleanup)
 - 🧹 **Background expiration** — optional sweeper thread (`cleanupIntervalSeconds`)
-- 🧠 **LRU eviction** — bound the cache by `maxSize` with `evictionPolicy: "lru"`
-- ⚡ **Fast reads** and **fast writes**
+- 🛡️ **What you store is what you get** — values that JSON cannot represent are rejected with
+  a clear error instead of coming back changed
+- 📦 **Raw JSON access** — `setJson`/`getJson` store and serve pre-serialized responses
 - 📊 Built-in **statistics** (hits, misses, sets, deletes, expired, evicted, size)
 - 🧩 **TypeScript** support with generics out of the box
 - 🌐 **Framework agnostic** — works with Express, Fastify, NestJS, Hono,
@@ -92,7 +97,8 @@ console.log(cache.get("greeting")); // "hello"
 ### `set(key, value, options?)`
 
 Stores (or overwrites) a value. Returns `true` on success, or `false` when a
-`maxSize` limit is set, the cache is full, and the key is new.
+`maxSize` limit is set, the cache is full, and the key is new. Throws a
+`TypeError` if the value cannot be stored as JSON (see [Values](#values)).
 
 ```ts
 cache.set("user:1", { id: 1, name: "Roberto" });
@@ -101,12 +107,25 @@ cache.set("session:123", session, { ttlSeconds: 60 });
 
 ### `get(key)`
 
-Returns the stored value, or `null` if the key is missing or expired.
+Returns the stored value, or `null` if the key is missing or expired. Every call
+returns a new copy, so changing it does not change the cache.
 
 ```ts
 const user = cache.get<User>("user:1"); // User | null
 ```
 
+### `setJson(key, json, options?)` / `getJson(key)`
+
+Store and read text that is **already JSON**, without parsing or re-encoding it —
+for example an HTTP response body. `setJson` does not validate the text; storing
+something that is not JSON makes a later `get()` throw. The framework adapters
+below use this pair, so a cache HIT sends the stored text as is.
+
+```ts
+cache.setJson("GET:/users/1", '{"id":1,"name":"Roberto"}', { ttlSeconds: 60 });
+res.type("application/json").send(cache.getJson("GET:/users/1"));
+```
+
 ### `delete(key)`
 
 Removes a key. Returns `true` if it existed, `false` otherwise.
@@ -117,7 +136,8 @@ cache.delete("user:1"); // true
 
 ### `exists(key)`
 
-Returns `true` if the key exists and is still valid (not expired).
+Returns `true` if the key exists and is still valid (not expired). It does not
+count as a use for LRU eviction.
 
 ```ts
 cache.exists("user:1"); // boolean
@@ -141,14 +161,39 @@ cache.size(); // 42
 
 ---
 
+## Values
+
+Values are stored as JSON, so the cache accepts what JSON represents exactly:
+plain objects, arrays, strings, finite numbers, booleans and `null`. Anything
+else would come back different from what you stored — `JSON.stringify` turns a
+`Date` into a string, a `Map` into `{}` and `NaN` into `null` — so `set` throws a
+`TypeError` that names where the problem is:
+
+```ts
+cache.set("user:1", { profile: { createdAt: new Date() } });
+// TypeError: rust-node-cache: cannot store value.profile.createdAt (a Date). Values are
+// kept as JSON, so only plain objects, arrays, strings, finite numbers, booleans and null
+// are accepted. Store date.toISOString() or date.getTime() instead.
+```
+
+Rejected: `Date`, `Map`, `Set`, `BigInt`, class instances, functions, symbols,
+`NaN`, `Infinity`, `undefined` as the value or as an array item, and circular
+references. Object properties set to `undefined` are left out, as JSON does.
+
+---
+
 ## TTL
 
-Set an entry with an expiration in seconds:
+Set an entry with an expiration in seconds. Fractions are allowed down to one
+millisecond (`ttlSeconds: 0.5` is 500 ms):
 
 ```ts
 cache.set("session:123", session, { ttlSeconds: 60 });
 ```
 
+`ttlSeconds` must be a positive number: `0`, negative values, `NaN` and
+`Infinity` throw instead of expiring at once or never.
+
 After the TTL elapses, reads return `null`:
 
 ```ts
@@ -189,8 +234,11 @@ const b = new Cache({ maxSize: 1000, evictionPolicy: "lru" });
 b.evictionPolicy; // "lru"
 ```
 
-LRU recency is tracked per entry (updated on every `get` hit) and the evicted
-count is surfaced in `stats().evicted`. Overwriting an existing key never evicts.
+Writes and `get` hits make an entry the most recently used; `exists` does not.
+Eviction is O(1) however large the cache is, and the evicted count is surfaced in
+`stats().evicted` (a victim that had already expired counts in `expired`
+instead). Overwriting an existing key never evicts. `maxSize` must be a positive
+integer.
 
 ---
 
@@ -219,20 +267,46 @@ the storage but does **not** reset the historical counters.
 
 ---
 
-## Performance
+## When to use it
+
+Each call crosses from JavaScript into Rust and values go through JSON, so this
+cache is **slower than a pure-JavaScript cache** that just keeps references to
+your objects. What it buys you is a cache the garbage collector does not have to
+trace.
+
+**Good fit:**
+
+- large caches (hundreds of thousands of entries or more) in latency-sensitive
+  services, where heap growth means longer GC pauses;
+- processes close to their heap limit (`--max-old-space-size`);
+- caching HTTP responses that are JSON anyway (`setJson`/`getJson`, or the
+  Express/Fastify/NestJS adapters).
+
+**Use `lru-cache` instead** when the cache is small, when you need to store live
+objects (class instances, `Date`, `Map`) or when raw operations per second is
+what matters most.
+
+---
+
+## Benchmarks
+
+200,000 entries, Apple M2, Node.js 24 (operations per second, higher is better):
 
-The cache core is implemented entirely in Rust and tuned for throughput:
+| Operation                         | rust-node-cache 0.3 | rust-node-cache 0.2 | lru-cache 11 |
+| --------------------------------- | ------------------- | ------------------- | ------------ |
+| `set` (5-field object)            | 1.6 M               | 0.4 M               | 12 M         |
+| `get` (5-field object)            | 1.9 M               | 0.5 M               | 13 M         |
+| `set` (string)                    | 3.4 M               | 2.2 M               | 11 M         |
+| `get` (string)                    | 3.9 M               | 3.0 M               | 13 M         |
+| `set` that evicts, `maxSize` 100k | 2.0 M               | 0.002 M             | —            |
 
-- **Rust core** — no GC pauses on the cache itself; deterministic memory handling
-  via RAII (entries are freed the instant they leave the map).
-- **DashMap** — the map is split into multiple internal shards, each guarded by
-  its own lock, so operations on different keys proceed in parallel.
-- **Lock-free reads** for statistics — counters use atomic integers
-  (`AtomicU64`) and are incremented with relaxed atomics, avoiding a global lock.
-- **Low allocation** — values are stored as a single contiguous `Vec<u8>`; there
-  is no per-field boxing.
-- **Fast TTL checks** — expiration is a single integer comparison against a
-  cached millisecond timestamp.
+Memory with 500,000 of those objects stored:
+
+|                          | rust-node-cache | lru-cache |
+| ------------------------ | --------------- | --------- |
+| V8 heap growth           | 0 MB            | 102 MB    |
+| Full GC (`global.gc()`)  | 1 ms            | 26 ms     |
+| Process RSS growth       | 150 MB          | 174 MB    |
 
 ---
 
@@ -241,17 +315,19 @@ The cache core is implemented entirely in Rust and tuned for throughput:
 ```txt
 Node.js
  ↓
-napi-rs   (the Rust ⇆ V8 bridge: #[napi] generates the glue code)
+TypeScript layer   (validates values, JSON.stringify / JSON.parse in V8)
+ ↓
+napi-rs            (the Rust ⇆ V8 bridge: #[napi] generates the glue code)
  ↓
-Rust Cache Engine   (set / get / ttl / stats / cleanup)
+Rust cache engine  (set / get / ttl / stats / cleanup)
  ↓
-DashMap   (concurrent, lock-sharded HashMap<String, CacheEntry>)
+LruCache behind a Mutex   (hash map + recency list: O(1) lookups and evictions)
 ```
 
-Values cross the boundary as `serde_json::Value` and are serialized to JSON
-bytes (`Vec<u8>`) inside the engine. This keeps the storage layer agnostic to the
-shape of your data and leaves room to adopt binary formats (MessagePack, CBOR,
-Bincode) later without touching the cache logic.
+Values cross the boundary as JSON **text**: V8 encodes and decodes JSON far
+faster than an object graph can be converted field by field through N-API. The
+lock is uncontended in practice — JavaScript calls come from one thread, and the
+only other thread is the optional sweeper. Statistics counters are atomics.
 
 ---
 
@@ -263,6 +339,8 @@ Bincode) later without touching the cache logic.
 | `set(key, value, options?)`    | `boolean`      | Store/overwrite a value. `options.ttlSeconds` sets expiration.    |
 | `evictionPolicy` (getter)      | `string`       | The active policy: `"reject"` or `"lru"`.                         |
 | `get<T>(key)`                  | `T \| null`    | Read a value (lazy-expires stale entries).                        |
+| `setJson(key, json, options?)` | `boolean`      | Store text that is already JSON, as is.                           |
+| `getJson(key)`                 | `string \| null` | Read the stored JSON text without parsing it.                   |
 | `delete(key)`                  | `boolean`      | Remove a key. `true` if it existed.                               |
 | `exists(key)`                  | `boolean`      | Whether the key exists and is valid.                              |
 | `clear()`                      | `void`         | Remove all entries.                                               |
@@ -274,13 +352,13 @@ Bincode) later without touching the cache logic.
 
 ```ts
 interface CacheOptions {
-  maxSize?: number;
+  maxSize?: number; // positive integer
   evictionPolicy?: "reject" | "lru"; // default "reject"
-  cleanupIntervalSeconds?: number; // enables the background sweeper
+  cleanupIntervalSeconds?: number; // enables the background sweeper; fractions allowed
 }
 
 interface SetOptions {
-  ttlSeconds?: number;
+  ttlSeconds?: number; // > 0, fractions allowed (min 0.001)
 }
 
 interface CacheStats {
@@ -324,6 +402,10 @@ app.get("/manual/:id", async (req, res) => {
 });
 ```
 
+The middleware stores the JSON the client received: a `Date` in the body is
+cached as its ISO string, exactly as `res.json` sent it, so a HIT and a MISS
+return the same response.
+
 ---
 
 ## Fastify Example
@@ -361,18 +443,13 @@ app.useGlobalInterceptors(new CacheInterceptor({ cache, ttlSeconds: 60 }));
 
 ---
 
-## Benchmarks
-
-Coming soon.
-
----
-
 ## Limitations
 
 - Local process only
 - Not distributed
 - Data is lost on restart
 - Multiple workers (cluster / PM2) have separate, independent caches
+- Values must be JSON-representable (see [Values](#values))
 
 ---
 
@@ -382,10 +459,11 @@ Coming soon.
 | ------- | ------------------------ | ------ |
 | v0.1    | Basic cache              | ✅     |
 | v0.2    | TTL cleanup thread + LRU eviction | ✅ |
-| v0.3    | LFU cache                | 🔜     |
-| v0.4    | Redis synchronization    | 🔜     |
-| v0.5    | Prometheus metrics       | 🔜     |
-| v0.6    | ImmutableLog integration | 🔜     |
+| v0.3    | O(1) LRU, JSON fast path, strict values, `setJson`/`getJson` | ✅ |
+| v0.4    | One cache shared by `worker_threads` + `maxBytes` memory limit | 🔜 |
+| v0.5    | LFU cache                | 🔜     |
+| v0.6    | Prometheus metrics       | 🔜     |
+| later   | Redis synchronization, ImmutableLog integration | 🔜 |
 
 ### Future: ImmutableLog Integration
 

package/binding.d.ts

@@ -20,13 +20,17 @@ export interface CacheOptions {
   evictionPolicy?: string
   /**
    * When set (> 0), starts a thread that sweeps expired entries every N
-   * seconds (background expiration, on top of the lazy one).
+   * seconds (background expiration, on top of the lazy one). Fractions are
+   * allowed; `0` leaves the sweeper off.
    */
   cleanupIntervalSeconds?: number
 }
 /** Per-write options: `cache.set(key, value, { ttlSeconds })`. */
 export interface SetOptions {
-  /** Time to live in seconds. Absent => the entry does not expire by time. */
+  /**
+   * Time to live in seconds (fractions allowed, at least 0.001). Absent =>
+   * the entry does not expire by time.
+   */
   ttlSeconds?: number
 }
 /** Object returned by `cache.stats()`. `i64` fields become `number` in JS. */
@@ -42,9 +46,9 @@ export interface CacheStatsObject {
 /**
  * In-memory cache exposed to Node as the `Cache` class.
  *
- * It delegates everything to `RustCache` (which holds the `DashMap` and the
- * atomic counters). Every method takes `&self`: the state is concurrent
- * inside, so it is safe to use from several threads (such as the sweeper).
+ * It delegates everything to `RustCache` (which holds the entries and the
+ * atomic counters). Every method takes `&self`: the state is synchronized
+ * inside, so it is safe to share with the background sweeper thread.
  */
 export declare class Cache {
   /** `new Cache()` or `new Cache({ maxSize, evictionPolicy, cleanupIntervalSeconds })`. */
@@ -53,11 +57,15 @@ export declare class Cache {
   get evictionPolicy(): string
   /**
    * Inserts or updates a key. Returns `true` on success, `false` if the cache
-   * is full (`maxSize`) and the key is new.
+   * is full (`maxSize`) and the key is new. `value` is the JSON text of the
+   * value (encoded by the TypeScript layer).
+   */
+  set(key: string, value: string, options?: SetOptions | undefined | null): boolean
+  /**
+   * Reads a key. Returns the value's JSON text, or `null` if missing or
+   * expired.
    */
-  set(key: string, value: any, options?: SetOptions | undefined | null): boolean
-  /** Reads a key. Returns the value, or `null` if missing or expired. */
-  get(key: string): any | null
+  get(key: string): string | null
   /** Removes a key. Returns `true` if it existed, `false` otherwise. */
   delete(key: string): boolean
   /** Whether the key exists and is still valid (not expired). */

package/dist/express.d.mts

@@ -28,6 +28,10 @@ interface CacheMiddlewareOptions {
 /**
  * Creates an Express middleware that caches JSON responses. Adds an
  * `X-Cache: HIT|MISS` header for observability.
+ *
+ * What is stored is the JSON the client received (a `Date` in the body is
+ * stored as its ISO string, as `res.json` sends it), and a HIT sends that text
+ * as is, without parsing or re-serializing it.
  */
 declare function cacheMiddleware(options: CacheMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => void;
 

package/dist/express.d.ts

@@ -28,6 +28,10 @@ interface CacheMiddlewareOptions {
 /**
  * Creates an Express middleware that caches JSON responses. Adds an
  * `X-Cache: HIT|MISS` header for observability.
+ *
+ * What is stored is the JSON the client received (a `Date` in the body is
+ * stored as its ISO string, as `res.json` sends it), and a HIT sends that text
+ * as is, without parsing or re-serializing it.
  */
 declare function cacheMiddleware(options: CacheMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => void;
 

package/dist/express.js

@@ -34,23 +34,33 @@ function cacheMiddleware(options) {
       return;
     }
     const key = keyGenerator(req);
-    const cached = cache.get(key);
+    const cached = cache.getJson(key);
     if (cached !== null) {
       res.setHeader("X-Cache", "HIT");
-      res.json(cached);
+      res.type("application/json").send(cached);
       return;
     }
     res.setHeader("X-Cache", "MISS");
     const originalJson = res.json.bind(res);
     res.json = (body) => {
       if (res.statusCode >= 200 && res.statusCode < 300) {
-        cache.set(key, body, ttlSeconds ? { ttlSeconds } : void 0);
+        const json = toJson(body);
+        if (json !== void 0) {
+          cache.setJson(key, json, ttlSeconds ? { ttlSeconds } : void 0);
+        }
       }
       return originalJson(body);
     };
     next();
   };
 }
+function toJson(body) {
+  try {
+    return JSON.stringify(body);
+  } catch {
+    return void 0;
+  }
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   cacheMiddleware

package/dist/express.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../js/express.ts"],"sourcesContent":["/**\n * Express integration: caching of JSON responses.\n *\n * Usage:\n *   import { Cache } from \"rust-node-cache\";\n *   import { cacheMiddleware } from \"rust-node-cache/express\";\n *\n *   const cache = new Cache();\n *   app.get(\"/users/:id\", cacheMiddleware({ cache, ttlSeconds: 60 }), handler);\n *\n * The middleware intercepts `res.json`: on a HIT it responds straight from the\n * cache; on a MISS it lets the handler run and stores the response body (2xx only).\n */\n\nimport type { Request, Response, NextFunction } from \"express\";\nimport type { Cache } from \"./index\";\n\nexport interface CacheMiddlewareOptions {\n  /** Cache instance to use. */\n  cache: Cache;\n  /** TTL applied to stored responses (in seconds). */\n  ttlSeconds?: number;\n  /** HTTP methods eligible for caching. Default: `[\"GET\"]`. */\n  methods?: string[];\n  /** Builds the cache key from the request. Default: `METHOD:url`. */\n  keyGenerator?: (req: Request) => string;\n}\n\n/**\n * Creates an Express middleware that caches JSON responses. Adds an\n * `X-Cache: HIT|MISS` header for observability.\n */\nexport function cacheMiddleware(options: CacheMiddlewareOptions) {\n  const { cache } = options;\n  const ttlSeconds = options.ttlSeconds;\n  const methods = options.methods ?? [\"GET\"];\n  const keyGenerator =\n    options.keyGenerator ?? ((req: Request) => `${req.method}:${req.originalUrl}`);\n\n  return function rustNodeCache(\n    req: Request,\n    res: Response,\n    next: NextFunction,\n  ): void {\n    if (!methods.includes(req.method)) {\n      next();\n      return;\n    }\n\n    const key = keyGenerator(req);\n    const cached = cache.get(key);\n    if (cached !== null) {\n      res.setHeader(\"X-Cache\", \"HIT\");\n      res.json(cached);\n      return;\n    }\n\n    res.setHeader(\"X-Cache\", \"MISS\");\n    const originalJson = res.json.bind(res);\n    res.json = (body: unknown): Response => {\n      // Only successful responses (2xx) are stored.\n      if (res.statusCode >= 200 && res.statusCode < 300) {\n        cache.set(key, body, ttlSeconds ? { ttlSeconds } : undefined);\n      }\n      return originalJson(body);\n    };\n\n    next();\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAgCO,SAAS,gBAAgB,SAAiC;AAC/D,QAAM,EAAE,MAAM,IAAI;AAClB,QAAM,aAAa,QAAQ;AAC3B,QAAM,UAAU,QAAQ,WAAW,CAAC,KAAK;AACzC,QAAM,eACJ,QAAQ,iBAAiB,CAAC,QAAiB,GAAG,IAAI,MAAM,IAAI,IAAI,WAAW;AAE7E,SAAO,SAAS,cACd,KACA,KACA,MACM;AACN,QAAI,CAAC,QAAQ,SAAS,IAAI,MAAM,GAAG;AACjC,WAAK;AACL;AAAA,IACF;AAEA,UAAM,MAAM,aAAa,GAAG;AAC5B,UAAM,SAAS,MAAM,IAAI,GAAG;AAC5B,QAAI,WAAW,MAAM;AACnB,UAAI,UAAU,WAAW,KAAK;AAC9B,UAAI,KAAK,MAAM;AACf;AAAA,IACF;AAEA,QAAI,UAAU,WAAW,MAAM;AAC/B,UAAM,eAAe,IAAI,KAAK,KAAK,GAAG;AACtC,QAAI,OAAO,CAAC,SAA4B;AAEtC,UAAI,IAAI,cAAc,OAAO,IAAI,aAAa,KAAK;AACjD,cAAM,IAAI,KAAK,MAAM,aAAa,EAAE,WAAW,IAAI,MAAS;AAAA,MAC9D;AACA,aAAO,aAAa,IAAI;AAAA,IAC1B;AAEA,SAAK;AAAA,EACP;AACF;","names":[]}
+{"version":3,"sources":["../js/express.ts"],"sourcesContent":["/**\n * Express integration: caching of JSON responses.\n *\n * Usage:\n *   import { Cache } from \"rust-node-cache\";\n *   import { cacheMiddleware } from \"rust-node-cache/express\";\n *\n *   const cache = new Cache();\n *   app.get(\"/users/:id\", cacheMiddleware({ cache, ttlSeconds: 60 }), handler);\n *\n * The middleware intercepts `res.json`: on a HIT it responds straight from the\n * cache; on a MISS it lets the handler run and stores the response body (2xx only).\n */\n\nimport type { Request, Response, NextFunction } from \"express\";\nimport type { Cache } from \"./index\";\n\nexport interface CacheMiddlewareOptions {\n  /** Cache instance to use. */\n  cache: Cache;\n  /** TTL applied to stored responses (in seconds). */\n  ttlSeconds?: number;\n  /** HTTP methods eligible for caching. Default: `[\"GET\"]`. */\n  methods?: string[];\n  /** Builds the cache key from the request. Default: `METHOD:url`. */\n  keyGenerator?: (req: Request) => string;\n}\n\n/**\n * Creates an Express middleware that caches JSON responses. Adds an\n * `X-Cache: HIT|MISS` header for observability.\n *\n * What is stored is the JSON the client received (a `Date` in the body is\n * stored as its ISO string, as `res.json` sends it), and a HIT sends that text\n * as is, without parsing or re-serializing it.\n */\nexport function cacheMiddleware(options: CacheMiddlewareOptions) {\n  const { cache } = options;\n  const ttlSeconds = options.ttlSeconds;\n  const methods = options.methods ?? [\"GET\"];\n  const keyGenerator =\n    options.keyGenerator ?? ((req: Request) => `${req.method}:${req.originalUrl}`);\n\n  return function rustNodeCache(\n    req: Request,\n    res: Response,\n    next: NextFunction,\n  ): void {\n    if (!methods.includes(req.method)) {\n      next();\n      return;\n    }\n\n    const key = keyGenerator(req);\n    const cached = cache.getJson(key);\n    if (cached !== null) {\n      res.setHeader(\"X-Cache\", \"HIT\");\n      res.type(\"application/json\").send(cached);\n      return;\n    }\n\n    res.setHeader(\"X-Cache\", \"MISS\");\n    const originalJson = res.json.bind(res);\n    res.json = (body: unknown): Response => {\n      // Only successful responses (2xx) are stored.\n      if (res.statusCode >= 200 && res.statusCode < 300) {\n        const json = toJson(body);\n        if (json !== undefined) {\n          cache.setJson(key, json, ttlSeconds ? { ttlSeconds } : undefined);\n        }\n      }\n      return originalJson(body);\n    };\n\n    next();\n  };\n}\n\n/** The body as `res.json` would send it, or `undefined` when it cannot be cached. */\nfunction toJson(body: unknown): string | undefined {\n  try {\n    return JSON.stringify(body);\n  } catch {\n    return undefined; // circular or BigInt: `res.json` reports it, not the cache.\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAoCO,SAAS,gBAAgB,SAAiC;AAC/D,QAAM,EAAE,MAAM,IAAI;AAClB,QAAM,aAAa,QAAQ;AAC3B,QAAM,UAAU,QAAQ,WAAW,CAAC,KAAK;AACzC,QAAM,eACJ,QAAQ,iBAAiB,CAAC,QAAiB,GAAG,IAAI,MAAM,IAAI,IAAI,WAAW;AAE7E,SAAO,SAAS,cACd,KACA,KACA,MACM;AACN,QAAI,CAAC,QAAQ,SAAS,IAAI,MAAM,GAAG;AACjC,WAAK;AACL;AAAA,IACF;AAEA,UAAM,MAAM,aAAa,GAAG;AAC5B,UAAM,SAAS,MAAM,QAAQ,GAAG;AAChC,QAAI,WAAW,MAAM;AACnB,UAAI,UAAU,WAAW,KAAK;AAC9B,UAAI,KAAK,kBAAkB,EAAE,KAAK,MAAM;AACxC;AAAA,IACF;AAEA,QAAI,UAAU,WAAW,MAAM;AAC/B,UAAM,eAAe,IAAI,KAAK,KAAK,GAAG;AACtC,QAAI,OAAO,CAAC,SAA4B;AAEtC,UAAI,IAAI,cAAc,OAAO,IAAI,aAAa,KAAK;AACjD,cAAM,OAAO,OAAO,IAAI;AACxB,YAAI,SAAS,QAAW;AACtB,gBAAM,QAAQ,KAAK,MAAM,aAAa,EAAE,WAAW,IAAI,MAAS;AAAA,QAClE;AAAA,MACF;AACA,aAAO,aAAa,IAAI;AAAA,IAC1B;AAEA,SAAK;AAAA,EACP;AACF;AAGA,SAAS,OAAO,MAAmC;AACjD,MAAI;AACF,WAAO,KAAK,UAAU,IAAI;AAAA,EAC5B,QAAQ;AACN,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/express.mjs

@@ -10,23 +10,33 @@ function cacheMiddleware(options) {
       return;
     }
     const key = keyGenerator(req);
-    const cached = cache.get(key);
+    const cached = cache.getJson(key);
     if (cached !== null) {
       res.setHeader("X-Cache", "HIT");
-      res.json(cached);
+      res.type("application/json").send(cached);
       return;
     }
     res.setHeader("X-Cache", "MISS");
     const originalJson = res.json.bind(res);
     res.json = (body) => {
       if (res.statusCode >= 200 && res.statusCode < 300) {
-        cache.set(key, body, ttlSeconds ? { ttlSeconds } : void 0);
+        const json = toJson(body);
+        if (json !== void 0) {
+          cache.setJson(key, json, ttlSeconds ? { ttlSeconds } : void 0);
+        }
       }
       return originalJson(body);
     };
     next();
   };
 }
+function toJson(body) {
+  try {
+    return JSON.stringify(body);
+  } catch {
+    return void 0;
+  }
+}
 export {
   cacheMiddleware
 };

package/dist/express.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../js/express.ts"],"sourcesContent":["/**\n * Express integration: caching of JSON responses.\n *\n * Usage:\n *   import { Cache } from \"rust-node-cache\";\n *   import { cacheMiddleware } from \"rust-node-cache/express\";\n *\n *   const cache = new Cache();\n *   app.get(\"/users/:id\", cacheMiddleware({ cache, ttlSeconds: 60 }), handler);\n *\n * The middleware intercepts `res.json`: on a HIT it responds straight from the\n * cache; on a MISS it lets the handler run and stores the response body (2xx only).\n */\n\nimport type { Request, Response, NextFunction } from \"express\";\nimport type { Cache } from \"./index\";\n\nexport interface CacheMiddlewareOptions {\n  /** Cache instance to use. */\n  cache: Cache;\n  /** TTL applied to stored responses (in seconds). */\n  ttlSeconds?: number;\n  /** HTTP methods eligible for caching. Default: `[\"GET\"]`. */\n  methods?: string[];\n  /** Builds the cache key from the request. Default: `METHOD:url`. */\n  keyGenerator?: (req: Request) => string;\n}\n\n/**\n * Creates an Express middleware that caches JSON responses. Adds an\n * `X-Cache: HIT|MISS` header for observability.\n */\nexport function cacheMiddleware(options: CacheMiddlewareOptions) {\n  const { cache } = options;\n  const ttlSeconds = options.ttlSeconds;\n  const methods = options.methods ?? [\"GET\"];\n  const keyGenerator =\n    options.keyGenerator ?? ((req: Request) => `${req.method}:${req.originalUrl}`);\n\n  return function rustNodeCache(\n    req: Request,\n    res: Response,\n    next: NextFunction,\n  ): void {\n    if (!methods.includes(req.method)) {\n      next();\n      return;\n    }\n\n    const key = keyGenerator(req);\n    const cached = cache.get(key);\n    if (cached !== null) {\n      res.setHeader(\"X-Cache\", \"HIT\");\n      res.json(cached);\n      return;\n    }\n\n    res.setHeader(\"X-Cache\", \"MISS\");\n    const originalJson = res.json.bind(res);\n    res.json = (body: unknown): Response => {\n      // Only successful responses (2xx) are stored.\n      if (res.statusCode >= 200 && res.statusCode < 300) {\n        cache.set(key, body, ttlSeconds ? { ttlSeconds } : undefined);\n      }\n      return originalJson(body);\n    };\n\n    next();\n  };\n}\n"],"mappings":";AAgCO,SAAS,gBAAgB,SAAiC;AAC/D,QAAM,EAAE,MAAM,IAAI;AAClB,QAAM,aAAa,QAAQ;AAC3B,QAAM,UAAU,QAAQ,WAAW,CAAC,KAAK;AACzC,QAAM,eACJ,QAAQ,iBAAiB,CAAC,QAAiB,GAAG,IAAI,MAAM,IAAI,IAAI,WAAW;AAE7E,SAAO,SAAS,cACd,KACA,KACA,MACM;AACN,QAAI,CAAC,QAAQ,SAAS,IAAI,MAAM,GAAG;AACjC,WAAK;AACL;AAAA,IACF;AAEA,UAAM,MAAM,aAAa,GAAG;AAC5B,UAAM,SAAS,MAAM,IAAI,GAAG;AAC5B,QAAI,WAAW,MAAM;AACnB,UAAI,UAAU,WAAW,KAAK;AAC9B,UAAI,KAAK,MAAM;AACf;AAAA,IACF;AAEA,QAAI,UAAU,WAAW,MAAM;AAC/B,UAAM,eAAe,IAAI,KAAK,KAAK,GAAG;AACtC,QAAI,OAAO,CAAC,SAA4B;AAEtC,UAAI,IAAI,cAAc,OAAO,IAAI,aAAa,KAAK;AACjD,cAAM,IAAI,KAAK,MAAM,aAAa,EAAE,WAAW,IAAI,MAAS;AAAA,MAC9D;AACA,aAAO,aAAa,IAAI;AAAA,IAC1B;AAEA,SAAK;AAAA,EACP;AACF;","names":[]}
+{"version":3,"sources":["../js/express.ts"],"sourcesContent":["/**\n * Express integration: caching of JSON responses.\n *\n * Usage:\n *   import { Cache } from \"rust-node-cache\";\n *   import { cacheMiddleware } from \"rust-node-cache/express\";\n *\n *   const cache = new Cache();\n *   app.get(\"/users/:id\", cacheMiddleware({ cache, ttlSeconds: 60 }), handler);\n *\n * The middleware intercepts `res.json`: on a HIT it responds straight from the\n * cache; on a MISS it lets the handler run and stores the response body (2xx only).\n */\n\nimport type { Request, Response, NextFunction } from \"express\";\nimport type { Cache } from \"./index\";\n\nexport interface CacheMiddlewareOptions {\n  /** Cache instance to use. */\n  cache: Cache;\n  /** TTL applied to stored responses (in seconds). */\n  ttlSeconds?: number;\n  /** HTTP methods eligible for caching. Default: `[\"GET\"]`. */\n  methods?: string[];\n  /** Builds the cache key from the request. Default: `METHOD:url`. */\n  keyGenerator?: (req: Request) => string;\n}\n\n/**\n * Creates an Express middleware that caches JSON responses. Adds an\n * `X-Cache: HIT|MISS` header for observability.\n *\n * What is stored is the JSON the client received (a `Date` in the body is\n * stored as its ISO string, as `res.json` sends it), and a HIT sends that text\n * as is, without parsing or re-serializing it.\n */\nexport function cacheMiddleware(options: CacheMiddlewareOptions) {\n  const { cache } = options;\n  const ttlSeconds = options.ttlSeconds;\n  const methods = options.methods ?? [\"GET\"];\n  const keyGenerator =\n    options.keyGenerator ?? ((req: Request) => `${req.method}:${req.originalUrl}`);\n\n  return function rustNodeCache(\n    req: Request,\n    res: Response,\n    next: NextFunction,\n  ): void {\n    if (!methods.includes(req.method)) {\n      next();\n      return;\n    }\n\n    const key = keyGenerator(req);\n    const cached = cache.getJson(key);\n    if (cached !== null) {\n      res.setHeader(\"X-Cache\", \"HIT\");\n      res.type(\"application/json\").send(cached);\n      return;\n    }\n\n    res.setHeader(\"X-Cache\", \"MISS\");\n    const originalJson = res.json.bind(res);\n    res.json = (body: unknown): Response => {\n      // Only successful responses (2xx) are stored.\n      if (res.statusCode >= 200 && res.statusCode < 300) {\n        const json = toJson(body);\n        if (json !== undefined) {\n          cache.setJson(key, json, ttlSeconds ? { ttlSeconds } : undefined);\n        }\n      }\n      return originalJson(body);\n    };\n\n    next();\n  };\n}\n\n/** The body as `res.json` would send it, or `undefined` when it cannot be cached. */\nfunction toJson(body: unknown): string | undefined {\n  try {\n    return JSON.stringify(body);\n  } catch {\n    return undefined; // circular or BigInt: `res.json` reports it, not the cache.\n  }\n}\n"],"mappings":";AAoCO,SAAS,gBAAgB,SAAiC;AAC/D,QAAM,EAAE,MAAM,IAAI;AAClB,QAAM,aAAa,QAAQ;AAC3B,QAAM,UAAU,QAAQ,WAAW,CAAC,KAAK;AACzC,QAAM,eACJ,QAAQ,iBAAiB,CAAC,QAAiB,GAAG,IAAI,MAAM,IAAI,IAAI,WAAW;AAE7E,SAAO,SAAS,cACd,KACA,KACA,MACM;AACN,QAAI,CAAC,QAAQ,SAAS,IAAI,MAAM,GAAG;AACjC,WAAK;AACL;AAAA,IACF;AAEA,UAAM,MAAM,aAAa,GAAG;AAC5B,UAAM,SAAS,MAAM,QAAQ,GAAG;AAChC,QAAI,WAAW,MAAM;AACnB,UAAI,UAAU,WAAW,KAAK;AAC9B,UAAI,KAAK,kBAAkB,EAAE,KAAK,MAAM;AACxC;AAAA,IACF;AAEA,QAAI,UAAU,WAAW,MAAM;AAC/B,UAAM,eAAe,IAAI,KAAK,KAAK,GAAG;AACtC,QAAI,OAAO,CAAC,SAA4B;AAEtC,UAAI,IAAI,cAAc,OAAO,IAAI,aAAa,KAAK;AACjD,cAAM,OAAO,OAAO,IAAI;AACxB,YAAI,SAAS,QAAW;AACtB,gBAAM,QAAQ,KAAK,MAAM,aAAa,EAAE,WAAW,IAAI,MAAS;AAAA,QAClE;AAAA,MACF;AACA,aAAO,aAAa,IAAI;AAAA,IAC1B;AAEA,SAAK;AAAA,EACP;AACF;AAGA,SAAS,OAAO,MAAmC;AACjD,MAAI;AACF,WAAO,KAAK,UAAU,IAAI;AAAA,EAC5B,QAAQ;AACN,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/fastify.js

@@ -37,10 +37,10 @@ async function cachePlugin(fastify, options) {
         return;
       }
       const key = keyGenerator(request);
-      const cached = cache.get(key);
+      const cached = cache.getJson(key);
       if (cached !== null) {
         reply.header("X-Cache", "HIT");
-        reply.send(cached);
+        reply.type("application/json; charset=utf-8").send(cached);
         return;
       }
       reply.header("X-Cache", "MISS");
@@ -52,20 +52,14 @@ async function cachePlugin(fastify, options) {
     "onSend",
     (request, reply, payload, done) => {
       const key = request[CACHE_KEY];
-      if (key && typeof payload === "string" && reply.statusCode >= 200 && reply.statusCode < 300) {
-        try {
-          cache.set(
-            key,
-            JSON.parse(payload),
-            ttlSeconds ? { ttlSeconds } : void 0
-          );
-        } catch {
-        }
+      if (key && typeof payload === "string" && reply.statusCode >= 200 && reply.statusCode < 300 && String(reply.getHeader("content-type") ?? "").startsWith("application/json")) {
+        cache.setJson(key, payload, ttlSeconds ? { ttlSeconds } : void 0);
       }
       done(null, payload);
     }
   );
 }
+cachePlugin[/* @__PURE__ */ Symbol.for("skip-override")] = true;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   cachePlugin

package/dist/fastify.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../js/fastify.ts"],"sourcesContent":["/**\n * Fastify integration: caching of JSON responses through a plugin.\n *\n * Usage:\n *   import { Cache } from \"rust-node-cache\";\n *   import { cachePlugin } from \"rust-node-cache/fastify\";\n *\n *   const cache = new Cache();\n *   fastify.register(cachePlugin, { cache, ttlSeconds: 60 });\n *\n * Flow: the `onRequest` hook checks the cache and, on a HIT, responds right away\n * (short-circuit). On a MISS, the `onSend` hook stores the serialized payload.\n */\n\nimport type {\n  FastifyInstance,\n  FastifyReply,\n  FastifyRequest,\n} from \"fastify\";\nimport type { Cache } from \"./index\";\n\nexport interface CachePluginOptions {\n  /** Cache instance to use. */\n  cache: Cache;\n  /** TTL applied to stored responses (in seconds). */\n  ttlSeconds?: number;\n  /** HTTP methods eligible for caching. Default: `[\"GET\"]`. */\n  methods?: string[];\n  /** Builds the cache key from the request. Default: `METHOD:url`. */\n  keyGenerator?: (req: FastifyRequest) => string;\n}\n\n// The computed key is kept on the request itself between hooks.\nconst CACHE_KEY = Symbol(\"rustNodeCacheKey\");\n\n/**\n * Fastify plugin that caches JSON responses. Use it with `fastify.register`.\n */\nexport async function cachePlugin(\n  fastify: FastifyInstance,\n  options: CachePluginOptions,\n): Promise<void> {\n  const { cache } = options;\n  const ttlSeconds = options.ttlSeconds;\n  const methods = options.methods ?? [\"GET\"];\n  const keyGenerator =\n    options.keyGenerator ?? ((req: FastifyRequest) => `${req.method}:${req.url}`);\n\n  fastify.addHook(\n    \"onRequest\",\n    (request: FastifyRequest, reply: FastifyReply, done: () => void) => {\n      if (!methods.includes(request.method)) {\n        done();\n        return;\n      }\n\n      const key = keyGenerator(request);\n      const cached = cache.get(key);\n      if (cached !== null) {\n        reply.header(\"X-Cache\", \"HIT\");\n        reply.send(cached);\n        return; // done() is not called: the response was already sent.\n      }\n\n      reply.header(\"X-Cache\", \"MISS\");\n      (request as unknown as Record<symbol, string>)[CACHE_KEY] = key;\n      done();\n    },\n  );\n\n  fastify.addHook(\n    \"onSend\",\n    (\n      request: FastifyRequest,\n      reply: FastifyReply,\n      payload: unknown,\n      done: (err: Error | null, value?: unknown) => void,\n    ) => {\n      const key = (request as unknown as Record<symbol, string | undefined>)[\n        CACHE_KEY\n      ];\n      if (\n        key &&\n        typeof payload === \"string\" &&\n        reply.statusCode >= 200 &&\n        reply.statusCode < 300\n      ) {\n        try {\n          cache.set(\n            key,\n            JSON.parse(payload),\n            ttlSeconds ? { ttlSeconds } : undefined,\n          );\n        } catch {\n          // non-JSON payload: simply not cached.\n        }\n      }\n      done(null, payload);\n    },\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAiCA,IAAM,YAAY,uBAAO,kBAAkB;AAK3C,eAAsB,YACpB,SACA,SACe;AACf,QAAM,EAAE,MAAM,IAAI;AAClB,QAAM,aAAa,QAAQ;AAC3B,QAAM,UAAU,QAAQ,WAAW,CAAC,KAAK;AACzC,QAAM,eACJ,QAAQ,iBAAiB,CAAC,QAAwB,GAAG,IAAI,MAAM,IAAI,IAAI,GAAG;AAE5E,UAAQ;AAAA,IACN;AAAA,IACA,CAAC,SAAyB,OAAqB,SAAqB;AAClE,UAAI,CAAC,QAAQ,SAAS,QAAQ,MAAM,GAAG;AACrC,aAAK;AACL;AAAA,MACF;AAEA,YAAM,MAAM,aAAa,OAAO;AAChC,YAAM,SAAS,MAAM,IAAI,GAAG;AAC5B,UAAI,WAAW,MAAM;AACnB,cAAM,OAAO,WAAW,KAAK;AAC7B,cAAM,KAAK,MAAM;AACjB;AAAA,MACF;AAEA,YAAM,OAAO,WAAW,MAAM;AAC9B,MAAC,QAA8C,SAAS,IAAI;AAC5D,WAAK;AAAA,IACP;AAAA,EACF;AAEA,UAAQ;AAAA,IACN;AAAA,IACA,CACE,SACA,OACA,SACA,SACG;AACH,YAAM,MAAO,QACX,SACF;AACA,UACE,OACA,OAAO,YAAY,YACnB,MAAM,cAAc,OACpB,MAAM,aAAa,KACnB;AACA,YAAI;AACF,gBAAM;AAAA,YACJ;AAAA,YACA,KAAK,MAAM,OAAO;AAAA,YAClB,aAAa,EAAE,WAAW,IAAI;AAAA,UAChC;AAAA,QACF,QAAQ;AAAA,QAER;AAAA,MACF;AACA,WAAK,MAAM,OAAO;AAAA,IACpB;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../js/fastify.ts"],"sourcesContent":["/**\n * Fastify integration: caching of JSON responses through a plugin.\n *\n * Usage:\n *   import { Cache } from \"rust-node-cache\";\n *   import { cachePlugin } from \"rust-node-cache/fastify\";\n *\n *   const cache = new Cache();\n *   fastify.register(cachePlugin, { cache, ttlSeconds: 60 });\n *\n * Flow: the `onRequest` hook checks the cache and, on a HIT, responds right away\n * (short-circuit). On a MISS, the `onSend` hook stores the serialized payload.\n */\n\nimport type {\n  FastifyInstance,\n  FastifyReply,\n  FastifyRequest,\n} from \"fastify\";\nimport type { Cache } from \"./index\";\n\nexport interface CachePluginOptions {\n  /** Cache instance to use. */\n  cache: Cache;\n  /** TTL applied to stored responses (in seconds). */\n  ttlSeconds?: number;\n  /** HTTP methods eligible for caching. Default: `[\"GET\"]`. */\n  methods?: string[];\n  /** Builds the cache key from the request. Default: `METHOD:url`. */\n  keyGenerator?: (req: FastifyRequest) => string;\n}\n\n// The computed key is kept on the request itself between hooks.\nconst CACHE_KEY = Symbol(\"rustNodeCacheKey\");\n\n/**\n * Fastify plugin that caches JSON responses. Use it with `fastify.register`.\n */\nexport async function cachePlugin(\n  fastify: FastifyInstance,\n  options: CachePluginOptions,\n): Promise<void> {\n  const { cache } = options;\n  const ttlSeconds = options.ttlSeconds;\n  const methods = options.methods ?? [\"GET\"];\n  const keyGenerator =\n    options.keyGenerator ?? ((req: FastifyRequest) => `${req.method}:${req.url}`);\n\n  fastify.addHook(\n    \"onRequest\",\n    (request: FastifyRequest, reply: FastifyReply, done: () => void) => {\n      if (!methods.includes(request.method)) {\n        done();\n        return;\n      }\n\n      const key = keyGenerator(request);\n      const cached = cache.getJson(key);\n      if (cached !== null) {\n        reply.header(\"X-Cache\", \"HIT\");\n        reply.type(\"application/json; charset=utf-8\").send(cached);\n        return; // done() is not called: the response was already sent.\n      }\n\n      reply.header(\"X-Cache\", \"MISS\");\n      (request as unknown as Record<symbol, string>)[CACHE_KEY] = key;\n      done();\n    },\n  );\n\n  fastify.addHook(\n    \"onSend\",\n    (\n      request: FastifyRequest,\n      reply: FastifyReply,\n      payload: unknown,\n      done: (err: Error | null, value?: unknown) => void,\n    ) => {\n      const key = (request as unknown as Record<symbol, string | undefined>)[\n        CACHE_KEY\n      ];\n      // The payload is already the serialized body: store that text as is.\n      // Only JSON responses are cached.\n      if (\n        key &&\n        typeof payload === \"string\" &&\n        reply.statusCode >= 200 &&\n        reply.statusCode < 300 &&\n        String(reply.getHeader(\"content-type\") ?? \"\").startsWith(\"application/json\")\n      ) {\n        cache.setJson(key, payload, ttlSeconds ? { ttlSeconds } : undefined);\n      }\n      done(null, payload);\n    },\n  );\n}\n\n// Disables Fastify encapsulation so the hooks apply to the scope where the\n// plugin is registered (the same as wrapping it with `fastify-plugin`). Without\n// it, routes registered as \"siblings\" of the plugin are never cached.\n(cachePlugin as unknown as Record<symbol, boolean>)[\n  Symbol.for(\"skip-override\")\n] = true;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAiCA,IAAM,YAAY,uBAAO,kBAAkB;AAK3C,eAAsB,YACpB,SACA,SACe;AACf,QAAM,EAAE,MAAM,IAAI;AAClB,QAAM,aAAa,QAAQ;AAC3B,QAAM,UAAU,QAAQ,WAAW,CAAC,KAAK;AACzC,QAAM,eACJ,QAAQ,iBAAiB,CAAC,QAAwB,GAAG,IAAI,MAAM,IAAI,IAAI,GAAG;AAE5E,UAAQ;AAAA,IACN;AAAA,IACA,CAAC,SAAyB,OAAqB,SAAqB;AAClE,UAAI,CAAC,QAAQ,SAAS,QAAQ,MAAM,GAAG;AACrC,aAAK;AACL;AAAA,MACF;AAEA,YAAM,MAAM,aAAa,OAAO;AAChC,YAAM,SAAS,MAAM,QAAQ,GAAG;AAChC,UAAI,WAAW,MAAM;AACnB,cAAM,OAAO,WAAW,KAAK;AAC7B,cAAM,KAAK,iCAAiC,EAAE,KAAK,MAAM;AACzD;AAAA,MACF;AAEA,YAAM,OAAO,WAAW,MAAM;AAC9B,MAAC,QAA8C,SAAS,IAAI;AAC5D,WAAK;AAAA,IACP;AAAA,EACF;AAEA,UAAQ;AAAA,IACN;AAAA,IACA,CACE,SACA,OACA,SACA,SACG;AACH,YAAM,MAAO,QACX,SACF;AAGA,UACE,OACA,OAAO,YAAY,YACnB,MAAM,cAAc,OACpB,MAAM,aAAa,OACnB,OAAO,MAAM,UAAU,cAAc,KAAK,EAAE,EAAE,WAAW,kBAAkB,GAC3E;AACA,cAAM,QAAQ,KAAK,SAAS,aAAa,EAAE,WAAW,IAAI,MAAS;AAAA,MACrE;AACA,WAAK,MAAM,OAAO;AAAA,IACpB;AAAA,EACF;AACF;AAKC,YACC,uBAAO,IAAI,eAAe,CAC5B,IAAI;","names":[]}

package/dist/fastify.mjs

@@ -13,10 +13,10 @@ async function cachePlugin(fastify, options) {
         return;
       }
       const key = keyGenerator(request);
-      const cached = cache.get(key);
+      const cached = cache.getJson(key);
       if (cached !== null) {
         reply.header("X-Cache", "HIT");
-        reply.send(cached);
+        reply.type("application/json; charset=utf-8").send(cached);
         return;
       }
       reply.header("X-Cache", "MISS");
@@ -28,20 +28,14 @@ async function cachePlugin(fastify, options) {
     "onSend",
     (request, reply, payload, done) => {
       const key = request[CACHE_KEY];
-      if (key && typeof payload === "string" && reply.statusCode >= 200 && reply.statusCode < 300) {
-        try {
-          cache.set(
-            key,
-            JSON.parse(payload),
-            ttlSeconds ? { ttlSeconds } : void 0
-          );
-        } catch {
-        }
+      if (key && typeof payload === "string" && reply.statusCode >= 200 && reply.statusCode < 300 && String(reply.getHeader("content-type") ?? "").startsWith("application/json")) {
+        cache.setJson(key, payload, ttlSeconds ? { ttlSeconds } : void 0);
       }
       done(null, payload);
     }
   );
 }
+cachePlugin[/* @__PURE__ */ Symbol.for("skip-override")] = true;
 export {
   cachePlugin
 };

package/dist/fastify.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../js/fastify.ts"],"sourcesContent":["/**\n * Fastify integration: caching of JSON responses through a plugin.\n *\n * Usage:\n *   import { Cache } from \"rust-node-cache\";\n *   import { cachePlugin } from \"rust-node-cache/fastify\";\n *\n *   const cache = new Cache();\n *   fastify.register(cachePlugin, { cache, ttlSeconds: 60 });\n *\n * Flow: the `onRequest` hook checks the cache and, on a HIT, responds right away\n * (short-circuit). On a MISS, the `onSend` hook stores the serialized payload.\n */\n\nimport type {\n  FastifyInstance,\n  FastifyReply,\n  FastifyRequest,\n} from \"fastify\";\nimport type { Cache } from \"./index\";\n\nexport interface CachePluginOptions {\n  /** Cache instance to use. */\n  cache: Cache;\n  /** TTL applied to stored responses (in seconds). */\n  ttlSeconds?: number;\n  /** HTTP methods eligible for caching. Default: `[\"GET\"]`. */\n  methods?: string[];\n  /** Builds the cache key from the request. Default: `METHOD:url`. */\n  keyGenerator?: (req: FastifyRequest) => string;\n}\n\n// The computed key is kept on the request itself between hooks.\nconst CACHE_KEY = Symbol(\"rustNodeCacheKey\");\n\n/**\n * Fastify plugin that caches JSON responses. Use it with `fastify.register`.\n */\nexport async function cachePlugin(\n  fastify: FastifyInstance,\n  options: CachePluginOptions,\n): Promise<void> {\n  const { cache } = options;\n  const ttlSeconds = options.ttlSeconds;\n  const methods = options.methods ?? [\"GET\"];\n  const keyGenerator =\n    options.keyGenerator ?? ((req: FastifyRequest) => `${req.method}:${req.url}`);\n\n  fastify.addHook(\n    \"onRequest\",\n    (request: FastifyRequest, reply: FastifyReply, done: () => void) => {\n      if (!methods.includes(request.method)) {\n        done();\n        return;\n      }\n\n      const key = keyGenerator(request);\n      const cached = cache.get(key);\n      if (cached !== null) {\n        reply.header(\"X-Cache\", \"HIT\");\n        reply.send(cached);\n        return; // done() is not called: the response was already sent.\n      }\n\n      reply.header(\"X-Cache\", \"MISS\");\n      (request as unknown as Record<symbol, string>)[CACHE_KEY] = key;\n      done();\n    },\n  );\n\n  fastify.addHook(\n    \"onSend\",\n    (\n      request: FastifyRequest,\n      reply: FastifyReply,\n      payload: unknown,\n      done: (err: Error | null, value?: unknown) => void,\n    ) => {\n      const key = (request as unknown as Record<symbol, string | undefined>)[\n        CACHE_KEY\n      ];\n      if (\n        key &&\n        typeof payload === \"string\" &&\n        reply.statusCode >= 200 &&\n        reply.statusCode < 300\n      ) {\n        try {\n          cache.set(\n            key,\n            JSON.parse(payload),\n            ttlSeconds ? { ttlSeconds } : undefined,\n          );\n        } catch {\n          // non-JSON payload: simply not cached.\n        }\n      }\n      done(null, payload);\n    },\n  );\n}\n"],"mappings":";AAiCA,IAAM,YAAY,uBAAO,kBAAkB;AAK3C,eAAsB,YACpB,SACA,SACe;AACf,QAAM,EAAE,MAAM,IAAI;AAClB,QAAM,aAAa,QAAQ;AAC3B,QAAM,UAAU,QAAQ,WAAW,CAAC,KAAK;AACzC,QAAM,eACJ,QAAQ,iBAAiB,CAAC,QAAwB,GAAG,IAAI,MAAM,IAAI,IAAI,GAAG;AAE5E,UAAQ;AAAA,IACN;AAAA,IACA,CAAC,SAAyB,OAAqB,SAAqB;AAClE,UAAI,CAAC,QAAQ,SAAS,QAAQ,MAAM,GAAG;AACrC,aAAK;AACL;AAAA,MACF;AAEA,YAAM,MAAM,aAAa,OAAO;AAChC,YAAM,SAAS,MAAM,IAAI,GAAG;AAC5B,UAAI,WAAW,MAAM;AACnB,cAAM,OAAO,WAAW,KAAK;AAC7B,cAAM,KAAK,MAAM;AACjB;AAAA,MACF;AAEA,YAAM,OAAO,WAAW,MAAM;AAC9B,MAAC,QAA8C,SAAS,IAAI;AAC5D,WAAK;AAAA,IACP;AAAA,EACF;AAEA,UAAQ;AAAA,IACN;AAAA,IACA,CACE,SACA,OACA,SACA,SACG;AACH,YAAM,MAAO,QACX,SACF;AACA,UACE,OACA,OAAO,YAAY,YACnB,MAAM,cAAc,OACpB,MAAM,aAAa,KACnB;AACA,YAAI;AACF,gBAAM;AAAA,YACJ;AAAA,YACA,KAAK,MAAM,OAAO;AAAA,YAClB,aAAa,EAAE,WAAW,IAAI;AAAA,UAChC;AAAA,QACF,QAAQ;AAAA,QAER;AAAA,MACF;AACA,WAAK,MAAM,OAAO;AAAA,IACpB;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../js/fastify.ts"],"sourcesContent":["/**\n * Fastify integration: caching of JSON responses through a plugin.\n *\n * Usage:\n *   import { Cache } from \"rust-node-cache\";\n *   import { cachePlugin } from \"rust-node-cache/fastify\";\n *\n *   const cache = new Cache();\n *   fastify.register(cachePlugin, { cache, ttlSeconds: 60 });\n *\n * Flow: the `onRequest` hook checks the cache and, on a HIT, responds right away\n * (short-circuit). On a MISS, the `onSend` hook stores the serialized payload.\n */\n\nimport type {\n  FastifyInstance,\n  FastifyReply,\n  FastifyRequest,\n} from \"fastify\";\nimport type { Cache } from \"./index\";\n\nexport interface CachePluginOptions {\n  /** Cache instance to use. */\n  cache: Cache;\n  /** TTL applied to stored responses (in seconds). */\n  ttlSeconds?: number;\n  /** HTTP methods eligible for caching. Default: `[\"GET\"]`. */\n  methods?: string[];\n  /** Builds the cache key from the request. Default: `METHOD:url`. */\n  keyGenerator?: (req: FastifyRequest) => string;\n}\n\n// The computed key is kept on the request itself between hooks.\nconst CACHE_KEY = Symbol(\"rustNodeCacheKey\");\n\n/**\n * Fastify plugin that caches JSON responses. Use it with `fastify.register`.\n */\nexport async function cachePlugin(\n  fastify: FastifyInstance,\n  options: CachePluginOptions,\n): Promise<void> {\n  const { cache } = options;\n  const ttlSeconds = options.ttlSeconds;\n  const methods = options.methods ?? [\"GET\"];\n  const keyGenerator =\n    options.keyGenerator ?? ((req: FastifyRequest) => `${req.method}:${req.url}`);\n\n  fastify.addHook(\n    \"onRequest\",\n    (request: FastifyRequest, reply: FastifyReply, done: () => void) => {\n      if (!methods.includes(request.method)) {\n        done();\n        return;\n      }\n\n      const key = keyGenerator(request);\n      const cached = cache.getJson(key);\n      if (cached !== null) {\n        reply.header(\"X-Cache\", \"HIT\");\n        reply.type(\"application/json; charset=utf-8\").send(cached);\n        return; // done() is not called: the response was already sent.\n      }\n\n      reply.header(\"X-Cache\", \"MISS\");\n      (request as unknown as Record<symbol, string>)[CACHE_KEY] = key;\n      done();\n    },\n  );\n\n  fastify.addHook(\n    \"onSend\",\n    (\n      request: FastifyRequest,\n      reply: FastifyReply,\n      payload: unknown,\n      done: (err: Error | null, value?: unknown) => void,\n    ) => {\n      const key = (request as unknown as Record<symbol, string | undefined>)[\n        CACHE_KEY\n      ];\n      // The payload is already the serialized body: store that text as is.\n      // Only JSON responses are cached.\n      if (\n        key &&\n        typeof payload === \"string\" &&\n        reply.statusCode >= 200 &&\n        reply.statusCode < 300 &&\n        String(reply.getHeader(\"content-type\") ?? \"\").startsWith(\"application/json\")\n      ) {\n        cache.setJson(key, payload, ttlSeconds ? { ttlSeconds } : undefined);\n      }\n      done(null, payload);\n    },\n  );\n}\n\n// Disables Fastify encapsulation so the hooks apply to the scope where the\n// plugin is registered (the same as wrapping it with `fastify-plugin`). Without\n// it, routes registered as \"siblings\" of the plugin are never cached.\n(cachePlugin as unknown as Record<symbol, boolean>)[\n  Symbol.for(\"skip-override\")\n] = true;\n"],"mappings":";AAiCA,IAAM,YAAY,uBAAO,kBAAkB;AAK3C,eAAsB,YACpB,SACA,SACe;AACf,QAAM,EAAE,MAAM,IAAI;AAClB,QAAM,aAAa,QAAQ;AAC3B,QAAM,UAAU,QAAQ,WAAW,CAAC,KAAK;AACzC,QAAM,eACJ,QAAQ,iBAAiB,CAAC,QAAwB,GAAG,IAAI,MAAM,IAAI,IAAI,GAAG;AAE5E,UAAQ;AAAA,IACN;AAAA,IACA,CAAC,SAAyB,OAAqB,SAAqB;AAClE,UAAI,CAAC,QAAQ,SAAS,QAAQ,MAAM,GAAG;AACrC,aAAK;AACL;AAAA,MACF;AAEA,YAAM,MAAM,aAAa,OAAO;AAChC,YAAM,SAAS,MAAM,QAAQ,GAAG;AAChC,UAAI,WAAW,MAAM;AACnB,cAAM,OAAO,WAAW,KAAK;AAC7B,cAAM,KAAK,iCAAiC,EAAE,KAAK,MAAM;AACzD;AAAA,MACF;AAEA,YAAM,OAAO,WAAW,MAAM;AAC9B,MAAC,QAA8C,SAAS,IAAI;AAC5D,WAAK;AAAA,IACP;AAAA,EACF;AAEA,UAAQ;AAAA,IACN;AAAA,IACA,CACE,SACA,OACA,SACA,SACG;AACH,YAAM,MAAO,QACX,SACF;AAGA,UACE,OACA,OAAO,YAAY,YACnB,MAAM,cAAc,OACpB,MAAM,aAAa,OACnB,OAAO,MAAM,UAAU,cAAc,KAAK,EAAE,EAAE,WAAW,kBAAkB,GAC3E;AACA,cAAM,QAAQ,KAAK,SAAS,aAAa,EAAE,WAAW,IAAI,MAAS;AAAA,MACrE;AACA,WAAK,MAAM,OAAO;AAAA,IACpB;AAAA,EACF;AACF;AAKC,YACC,uBAAO,IAAI,eAAe,CAC5B,IAAI;","names":[]}