rust-node-cache 0.1.1 → 0.2.1

package/README.md

@@ -24,8 +24,10 @@ is **no compiler required at install time** on supported platforms.
 - 🦀 **Rust-powered** core for predictable, low-overhead performance
 - 🔒 **Thread-safe** via `DashMap` (lock-sharded concurrent map)
 - ⏱️ **TTL support** per entry (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**
-- 📊 Built-in **statistics** (hits, misses, sets, deletes, expired, size)
+- 📊 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,
   Next.js, or plain Node.js
@@ -42,6 +44,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
@@ -142,6 +163,35 @@ an active sweep:
 const removed = cache.cleanupExpired(); // number of entries removed
 ```
 
+Or let the cache sweep for you in the background — set `cleanupIntervalSeconds`
+and a thread reclaims expired entries on its own (no manual `cleanupExpired()`):
+
+```ts
+const cache = new Cache({ cleanupIntervalSeconds: 30 });
+```
+
+The thread is tied to the cache's lifetime: it stops automatically when the cache
+is garbage-collected.
+
+---
+
+## Eviction (maxSize)
+
+Cap the number of keys with `maxSize`. When the cache is full and a **new** key
+is written, `evictionPolicy` decides what happens:
+
+```ts
+// Default: reject the write (set returns false), keep existing entries.
+const a = new Cache({ maxSize: 1000 }); // evictionPolicy: "reject"
+
+// LRU: evict the least-recently-used entry to make room, then insert.
+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.
+
 ---
 
 ## Statistics
@@ -159,6 +209,7 @@ Returns:
   sets: 800,
   deletes: 20,
   expired: 15,
+  evicted: 40,
   size: 780
 }
 ```
@@ -208,8 +259,9 @@ Bincode) later without touching the cache logic.
 
 | Method                         | Returns        | Description                                                       |
 | ------------------------------ | -------------- | ----------------------------------------------------------------- |
-| `new Cache(options?)`          | `Cache`        | Create a cache. `options.maxSize` caps the number of keys.        |
+| `new Cache(options?)`          | `Cache`        | Create a cache (`maxSize`, `evictionPolicy`, `cleanupIntervalSeconds`). |
 | `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).                        |
 | `delete(key)`                  | `boolean`      | Remove a key. `true` if it existed.                               |
 | `exists(key)`                  | `boolean`      | Whether the key exists and is valid.                              |
@@ -223,6 +275,8 @@ Bincode) later without touching the cache logic.
 ```ts
 interface CacheOptions {
   maxSize?: number;
+  evictionPolicy?: "reject" | "lru"; // default "reject"
+  cleanupIntervalSeconds?: number; // enables the background sweeper
 }
 
 interface SetOptions {
@@ -235,6 +289,7 @@ interface CacheStats {
   sets: number;
   deletes: number;
   expired: number;
+  evicted: number;
   size: number;
 }
 ```
@@ -323,15 +378,14 @@ Coming soon.
 
 ## Roadmap
 
-| Version | Feature                  |
-| ------- | ------------------------ |
-| v0.1    | Basic cache              |
-| v0.2    | TTL cleanup thread       |
-| v0.3    | LRU cache                |
-| v0.4    | LFU cache                |
-| v0.5    | Redis synchronization    |
-| v0.6    | Prometheus metrics       |
-| v0.7    | ImmutableLog integration |
+| Version | Feature                  | Status |
+| ------- | ------------------------ | ------ |
+| 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 | 🔜     |
 
 ### Future: ImmutableLog Integration
 

package/binding.d.ts

@@ -3,52 +3,71 @@
 
 /* auto-generated by NAPI-RS */
 
-/** Opções do construtor: `new Cache({ maxSize })`. */
+/**
+ * Constructor options:
+ * `new Cache({ maxSize, evictionPolicy, cleanupIntervalSeconds })`.
+ */
 export interface CacheOptions {
-  /** Limite opcional de chaves. Ao atingir, `set` de chave nova retorna `false`. */
+  /**
+   * Optional limit on the number of keys. What happens when it is reached
+   * depends on `evictionPolicy`.
+   */
   maxSize?: number
+  /**
+   * `"reject"` (default) — `set` of a new key returns `false` when full;
+   * `"lru"` — removes the least recently used entry and goes on.
+   */
+  evictionPolicy?: string
+  /**
+   * When set (> 0), starts a thread that sweeps expired entries every N
+   * seconds (background expiration, on top of the lazy one).
+   */
+  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. 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
   sets: number
   deletes: number
   expired: number
+  evicted: number
   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 `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).
  */
 export declare class Cache {
-  /** `new Cache()` ou `new Cache({ maxSize })`. */
+  /** `new Cache()` or `new Cache({ maxSize, evictionPolicy, cleanupIntervalSeconds })`. */
   constructor(options?: CacheOptions | undefined | null)
+  /** 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.
    */
   set(key: string, value: any, options?: SetOptions | undefined | null): boolean
-  /** Lê uma chave. Retorna o valor ou `null` se ausente/expirada. */
+  /** Reads a key. Returns the value, or `null` if missing or expired. */
   get(key: string): any | null
-  /** Remove uma chave. Retorna `true` se existia, `false` caso contrário. */
+  /** 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,32 @@ 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.
  */
 declare function cacheMiddleware(options: CacheMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => void;
 

package/dist/express.d.ts

@@ -2,32 +2,32 @@ 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.
  */
 declare function cacheMiddleware(options: CacheMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => void;
 

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 */\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":[]}

package/dist/express.mjs.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":";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 */\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":[]}

package/dist/fastify.d.mts

@@ -2,31 +2,31 @@ import { FastifyRequest, FastifyInstance } from 'fastify';
 import { Cache } from './index.mjs';
 
 /**
- * Integração com Fastify: cache de respostas JSON via plugin.
+ * Fastify integration: caching of JSON responses through a plugin.
  *
- * Uso:
+ * Usage:
  *   import { Cache } from "rust-node-cache";
  *   import { cachePlugin } from "rust-node-cache/fastify";
  *
  *   const cache = new Cache();
  *   fastify.register(cachePlugin, { cache, ttlSeconds: 60 });
  *
- * Fluxo: o hook `onRequest` checa o cache e, num HIT, responde imediatamente
- * (curto-circuito). Num MISS, o hook `onSend` guarda o payload serializado.
+ * Flow: the `onRequest` hook checks the cache and, on a HIT, responds right away
+ * (short-circuit). On a MISS, the `onSend` hook stores the serialized payload.
  */
 
 interface CachePluginOptions {
-    /** 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: FastifyRequest) => string;
 }
 /**
- * Plugin Fastify que cacheia respostas JSON. Use com `fastify.register`.
+ * Fastify plugin that caches JSON responses. Use it with `fastify.register`.
  */
 declare function cachePlugin(fastify: FastifyInstance, options: CachePluginOptions): Promise<void>;
 

package/dist/fastify.d.ts

@@ -2,31 +2,31 @@ import { FastifyRequest, FastifyInstance } from 'fastify';
 import { Cache } from './index.js';
 
 /**
- * Integração com Fastify: cache de respostas JSON via plugin.
+ * Fastify integration: caching of JSON responses through a plugin.
  *
- * Uso:
+ * Usage:
  *   import { Cache } from "rust-node-cache";
  *   import { cachePlugin } from "rust-node-cache/fastify";
  *
  *   const cache = new Cache();
  *   fastify.register(cachePlugin, { cache, ttlSeconds: 60 });
  *
- * Fluxo: o hook `onRequest` checa o cache e, num HIT, responde imediatamente
- * (curto-circuito). Num MISS, o hook `onSend` guarda o payload serializado.
+ * Flow: the `onRequest` hook checks the cache and, on a HIT, responds right away
+ * (short-circuit). On a MISS, the `onSend` hook stores the serialized payload.
  */
 
 interface CachePluginOptions {
-    /** 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: FastifyRequest) => string;
 }
 /**
- * Plugin Fastify que cacheia respostas JSON. Use com `fastify.register`.
+ * Fastify plugin that caches JSON responses. Use it with `fastify.register`.
  */
 declare function cachePlugin(fastify: FastifyInstance, options: CachePluginOptions): Promise<void>;
 

package/dist/fastify.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../js/fastify.ts"],"sourcesContent":["/**\n * Integração com Fastify: cache de respostas JSON via plugin.\n *\n * Uso:\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 * Fluxo: o hook `onRequest` checa o cache e, num HIT, responde imediatamente\n * (curto-circuito). Num MISS, o hook `onSend` guarda o payload serializado.\n */\n\nimport type {\n  FastifyInstance,\n  FastifyReply,\n  FastifyRequest,\n} from \"fastify\";\nimport type { Cache } from \"./index\";\n\nexport interface CachePluginOptions {\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: FastifyRequest) => string;\n}\n\n// Guardamos a chave calculada na própria request entre os hooks.\nconst CACHE_KEY = Symbol(\"rustNodeCacheKey\");\n\n/**\n * Plugin Fastify que cacheia respostas JSON. Use com `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; // não chama done(): a resposta já foi enviada.\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          // payload não-JSON: simplesmente não cacheia.\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.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":[]}

package/dist/fastify.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../js/fastify.ts"],"sourcesContent":["/**\n * Integração com Fastify: cache de respostas JSON via plugin.\n *\n * Uso:\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 * Fluxo: o hook `onRequest` checa o cache e, num HIT, responde imediatamente\n * (curto-circuito). Num MISS, o hook `onSend` guarda o payload serializado.\n */\n\nimport type {\n  FastifyInstance,\n  FastifyReply,\n  FastifyRequest,\n} from \"fastify\";\nimport type { Cache } from \"./index\";\n\nexport interface CachePluginOptions {\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: FastifyRequest) => string;\n}\n\n// Guardamos a chave calculada na própria request entre os hooks.\nconst CACHE_KEY = Symbol(\"rustNodeCacheKey\");\n\n/**\n * Plugin Fastify que cacheia respostas JSON. Use com `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; // não chama done(): a resposta já foi enviada.\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          // payload não-JSON: simplesmente não cacheia.\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.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":[]}