rust-node-cache 0.2.0 → 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,
@@ -44,6 +49,25 @@ Works with both **ESM** and **CommonJS**, and requires **Node.js 18+**.
 
 ---
 
+## Supported platforms
+
+Prebuilt binaries are published for:
+
+| OS      | Architecture          | Triple                       |
+| ------- | --------------------- | ---------------------------- |
+| macOS   | arm64                 | `aarch64-apple-darwin`       |
+| macOS   | x64                   | `x86_64-apple-darwin`        |
+| Linux   | x64 (glibc)           | `x86_64-unknown-linux-gnu`   |
+| Linux   | arm64 (glibc)         | `aarch64-unknown-linux-gnu`  |
+| Linux   | x64 (musl, Alpine)    | `x86_64-unknown-linux-musl`  |
+| Linux   | arm64 (musl, Alpine)  | `aarch64-unknown-linux-musl` |
+| Windows | x64                   | `x86_64-pc-windows-msvc`     |
+
+Every release is installed from the packed tarball and exercised on each of these platforms
+in CI before it is published.
+
+---
+
 ## Quick Start
 
 ```ts
@@ -73,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" });
@@ -82,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.
@@ -98,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
@@ -122,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
@@ -170,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.
 
 ---
 
@@ -200,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.
 
-The cache core is implemented entirely in Rust and tuned for throughput:
+**Good fit:**
 
-- **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.
+- 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):
+
+| 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             | —            |
+
+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    |
 
 ---
 
@@ -222,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.
 
 ---
 
@@ -244,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.                                               |
@@ -255,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 {
@@ -305,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
@@ -342,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))
 
 ---
 
@@ -363,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

@@ -4,32 +4,36 @@
 /* auto-generated by NAPI-RS */
 
 /**
- * Opções do construtor:
+ * Constructor options:
  * `new Cache({ maxSize, evictionPolicy, cleanupIntervalSeconds })`.
  */
 export interface CacheOptions {
   /**
-   * Limite opcional de chaves. Comportamento ao atingir depende de
-   * `evictionPolicy`.
+   * Optional limit on the number of keys. What happens when it is reached
+   * depends on `evictionPolicy`.
    */
   maxSize?: number
   /**
-   * `"reject"` (padrão) — `set` de chave nova retorna `false` quando cheio;
-   * `"lru"` — remove a entrada menos recentemente usada e prossegue.
+   * `"reject"` (default) — `set` of a new key returns `false` when full;
+   * `"lru"` — removes the least recently used entry and goes on.
    */
   evictionPolicy?: string
   /**
-   * Se definido (> 0), liga uma thread que varre entradas expiradas a cada
-   * N segundos (expiração em background, além da lazy).
+   * When set (> 0), starts a thread that sweeps expired entries every N
+   * seconds (background expiration, on top of the lazy one). Fractions are
+   * allowed; `0` leaves the sweeper off.
    */
   cleanupIntervalSeconds?: number
 }
-/** Opções por escrita: `cache.set(key, value, { ttlSeconds })`. */
+/** Per-write options: `cache.set(key, value, { ttlSeconds })`. */
 export interface SetOptions {
-  /** Tempo de vida em segundos. Ausente => a entrada não expira por tempo. */
+  /**
+   * Time to live in seconds (fractions allowed, at least 0.001). Absent =>
+   * the entry does not expire by time.
+   */
   ttlSeconds?: number
 }
-/** Objeto devolvido por `cache.stats()`. Campos `i64` viram `number` no JS. */
+/** Object returned by `cache.stats()`. `i64` fields become `number` in JS. */
 export interface CacheStatsObject {
   hits: number
   misses: number
@@ -40,34 +44,38 @@ export interface CacheStatsObject {
   size: number
 }
 /**
- * Cache em memória exposto ao Node como a classe `Cache`.
+ * In-memory cache exposed to Node as the `Cache` class.
  *
- * Internamente delega tudo para o `RustCache` (que carrega o `DashMap` e os
- * contadores atômicos). Todos os métodos recebem `&self`: como o estado é
- * concorrente por dentro, várias chamadas podem rodar em paralelo.
+ * 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()` ou `new Cache({ maxSize, evictionPolicy, cleanupIntervalSeconds })`. */
+  /** `new Cache()` or `new Cache({ maxSize, evictionPolicy, cleanupIntervalSeconds })`. */
   constructor(options?: CacheOptions | undefined | null)
-  /** A política de evicção ativa: `"reject"` ou `"lru"`. */
+  /** The active eviction policy: `"reject"` or `"lru"`. */
   get evictionPolicy(): string
   /**
-   * Insere/atualiza uma chave. Retorna `true` em sucesso, `false` se o cache
-   * estiver cheio (`maxSize`) e a chave for nova.
+   * Inserts or updates a key. Returns `true` on success, `false` if the cache
+   * 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
-  /** Lê uma chave. Retorna o valor ou `null` se ausente/expirada. */
-  get(key: string): any | null
-  /** Remove uma chave. Retorna `true` se existia, `false` caso contrário. */
+  get(key: string): string | null
+  /** Removes a key. Returns `true` if it existed, `false` otherwise. */
   delete(key: string): boolean
-  /** Indica se a chave existe e está válida (não expirada). */
+  /** Whether the key exists and is still valid (not expired). */
   exists(key: string): boolean
-  /** Esvazia todas as entradas do cache. */
+  /** Removes every entry from the cache. */
   clear(): void
-  /** Quantidade de chaves armazenadas no momento. */
+  /** Number of keys currently stored. */
   size(): number
-  /** Varre e remove todas as entradas expiradas. Retorna quantas removeu. */
+  /** Sweeps and removes every expired entry. Returns how many it removed. */
   cleanupExpired(): number
-  /** Estatísticas acumuladas + tamanho atual. */
+  /** Accumulated statistics + the current size. */
   stats(): CacheStatsObject
 }

package/dist/express.d.mts

@@ -2,32 +2,36 @@ import { Request, Response, NextFunction } from 'express';
 import { Cache } from './index.mjs';
 
 /**
- * Integração com Express: cache de respostas JSON.
+ * Express integration: caching of JSON responses.
  *
- * Uso:
+ * Usage:
  *   import { Cache } from "rust-node-cache";
  *   import { cacheMiddleware } from "rust-node-cache/express";
  *
  *   const cache = new Cache();
  *   app.get("/users/:id", cacheMiddleware({ cache, ttlSeconds: 60 }), handler);
  *
- * O middleware intercepta `res.json`: num HIT responde direto do cache; num
- * MISS deixa o handler rodar e guarda o corpo da resposta (apenas em 2xx).
+ * The middleware intercepts `res.json`: on a HIT it responds straight from the
+ * cache; on a MISS it lets the handler run and stores the response body (2xx only).
  */
 
 interface CacheMiddlewareOptions {
-    /** Instância de cache a usar. */
+    /** Cache instance to use. */
     cache: Cache;
-    /** TTL aplicado às respostas guardadas (em segundos). */
+    /** TTL applied to stored responses (in seconds). */
     ttlSeconds?: number;
-    /** Métodos HTTP elegíveis para cache. Padrão: `["GET"]`. */
+    /** HTTP methods eligible for caching. Default: `["GET"]`. */
     methods?: string[];
-    /** Gera a chave de cache a partir da requisição. Padrão: `METHOD:url`. */
+    /** Builds the cache key from the request. Default: `METHOD:url`. */
     keyGenerator?: (req: Request) => string;
 }
 /**
- * Cria um middleware Express que cacheia respostas JSON. Adiciona o cabeçalho
- * `X-Cache: HIT|MISS` para facilitar a observabilidade.
+ * 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

@@ -2,32 +2,36 @@ import { Request, Response, NextFunction } from 'express';
 import { Cache } from './index.js';
 
 /**
- * Integração com Express: cache de respostas JSON.
+ * Express integration: caching of JSON responses.
  *
- * Uso:
+ * Usage:
  *   import { Cache } from "rust-node-cache";
  *   import { cacheMiddleware } from "rust-node-cache/express";
  *
  *   const cache = new Cache();
  *   app.get("/users/:id", cacheMiddleware({ cache, ttlSeconds: 60 }), handler);
  *
- * O middleware intercepta `res.json`: num HIT responde direto do cache; num
- * MISS deixa o handler rodar e guarda o corpo da resposta (apenas em 2xx).
+ * The middleware intercepts `res.json`: on a HIT it responds straight from the
+ * cache; on a MISS it lets the handler run and stores the response body (2xx only).
  */
 
 interface CacheMiddlewareOptions {
-    /** Instância de cache a usar. */
+    /** Cache instance to use. */
     cache: Cache;
-    /** TTL aplicado às respostas guardadas (em segundos). */
+    /** TTL applied to stored responses (in seconds). */
     ttlSeconds?: number;
-    /** Métodos HTTP elegíveis para cache. Padrão: `["GET"]`. */
+    /** HTTP methods eligible for caching. Default: `["GET"]`. */
     methods?: string[];
-    /** Gera a chave de cache a partir da requisição. Padrão: `METHOD:url`. */
+    /** Builds the cache key from the request. Default: `METHOD:url`. */
     keyGenerator?: (req: Request) => string;
 }
 /**
- * Cria um middleware Express que cacheia respostas JSON. Adiciona o cabeçalho
- * `X-Cache: HIT|MISS` para facilitar a observabilidade.
+ * 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 * Integração com Express: cache de respostas JSON.\n *\n * Uso:\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 * O middleware intercepta `res.json`: num HIT responde direto do cache; num\n * MISS deixa o handler rodar e guarda o corpo da resposta (apenas em 2xx).\n */\n\nimport type { Request, Response, NextFunction } from \"express\";\nimport type { Cache } from \"./index\";\n\nexport interface CacheMiddlewareOptions {\n  /** Instância de cache a usar. */\n  cache: Cache;\n  /** TTL aplicado às respostas guardadas (em segundos). */\n  ttlSeconds?: number;\n  /** Métodos HTTP elegíveis para cache. Padrão: `[\"GET\"]`. */\n  methods?: string[];\n  /** Gera a chave de cache a partir da requisição. Padrão: `METHOD:url`. */\n  keyGenerator?: (req: Request) => string;\n}\n\n/**\n * Cria um middleware Express que cacheia respostas JSON. Adiciona o cabeçalho\n * `X-Cache: HIT|MISS` para facilitar a observabilidade.\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      // Só guardamos respostas bem-sucedidas (2xx).\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
 };