rust-node-cache 0.2.0 → 0.3.0

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 *\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.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

@@ -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 * 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.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 * 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.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":[]}

package/dist/index.d.mts

@@ -1,63 +1,66 @@
 /**
- * rust-node-cache — API pública (TypeScript).
+ * rust-node-cache — public API (TypeScript).
  *
- * "Ultra-fast in-memory cache powered by Rust."
+ * "In-memory cache for Node.js that keeps your data off the V8 heap."
  *
- * Esta camada é um wrapper fino e tipado sobre a classe `Cache` nativa gerada
- * pelo Rust/napi-rs. Por que envolver em vez de re-exportar direto?
- *  - permite **genéricos** ergonômicos: `cache.get<User>("user:1")`;
- *  - normaliza `undefined`/`null` para sempre devolver `null` num miss;
- *  - dá um único lugar para JSDoc e para evoluir a API sem quebrar o core Rust.
- *
- * O custo é uma chamada de função extra por operação — desprezível frente ao
- * trabalho real (serialização + acesso ao DashMap) que acontece no Rust.
+ * This layer is a typed wrapper over the native `Cache` class generated by
+ * Rust/napi-rs. It does the JSON encoding on the JavaScript side, where V8's
+ * `JSON.stringify`/`JSON.parse` are fastest, and hands Rust plain strings:
+ *  - `set` validates the value (see `./encode`) and stores its JSON text;
+ *  - `get` parses the stored text back, so every read returns a fresh copy;
+ *  - it allows ergonomic **generics**: `cache.get<User>("user:1")`.
  */
-/** Estratégia de evicção quando `maxSize` é atingido. */
+/** Eviction strategy when `maxSize` is reached. */
 type EvictionPolicy = "reject" | "lru";
-/** Opções do construtor do cache. */
+/** Cache constructor options. */
 interface CacheOptions {
     /**
-     * Limite máximo de chaves. O que acontece ao atingir depende de
-     * `evictionPolicy`. Sem valor => cache ilimitado.
+     * Maximum number of keys (a positive integer). What happens when it is
+     * reached depends on `evictionPolicy`. No value => unlimited cache.
      */
     maxSize?: number;
     /**
-     * Política ao atingir `maxSize` numa chave **nova**:
-     * - `"reject"` (padrão): `set` retorna `false` (sobrescrever continua ok);
-     * - `"lru"`: remove a entrada menos recentemente usada e prossegue.
+     * Policy when `maxSize` is reached on a **new** key:
+     * - `"reject"` (default): `set` returns `false` (overwriting still works);
+     * - `"lru"`: removes the least recently used entry and goes on.
      */
     evictionPolicy?: EvictionPolicy;
     /**
-     * Se definido (> 0), liga uma thread que varre entradas expiradas a cada
-     * N segundos (expiração em background, além da preguiçosa por acesso).
+     * When set (> 0), starts a thread that sweeps expired entries every N
+     * seconds (background expiration, on top of the lazy one on access).
+     * Fractions are allowed; `0` or no value leaves it off.
      */
     cleanupIntervalSeconds?: number;
 }
-/** Opções por operação de escrita. */
+/** Per-write options. */
 interface SetOptions {
-    /** Tempo de vida em segundos. Ausente => a entrada não expira por tempo. */
+    /**
+     * Time to live in seconds; fractions are allowed (`0.5` = 500 ms, minimum
+     * 1 ms). Absent => the entry does not expire by time.
+     */
     ttlSeconds?: number;
 }
-/** Estatísticas acumuladas do cache (mais o tamanho atual). */
+/** Accumulated cache statistics (plus the current size). */
 interface CacheStats {
-    /** Leituras que encontraram uma entrada válida. */
+    /** Reads that found a valid entry. */
     hits: number;
-    /** Leituras sem chave válida (ausente ou expirada). */
+    /** Reads without a valid key (missing or expired). */
     misses: number;
-    /** Total de escritas (`set`). */
+    /** Total writes (`set`). */
     sets: number;
-    /** Total de remoções explícitas (`delete`). */
+    /** Total explicit removals (`delete`). */
     deletes: number;
-    /** Total de entradas removidas por expiração. */
+    /** Total entries removed by expiration. */
     expired: number;
-    /** Total de entradas removidas por evicção (política LRU ao atingir `maxSize`). */
+    /** Total entries removed by eviction (LRU policy when `maxSize` is reached). */
     evicted: number;
-    /** Número de chaves armazenadas agora. */
+    /** Number of keys stored right now. */
     size: number;
 }
 /**
- * Cache em memória ultrarrápido com núcleo em Rust (DashMap + contadores
- * atômicos). Thread-safe e com suporte a TTL por entrada.
+ * In-memory cache whose entries live in Rust memory, outside the V8 heap.
+ * Exact LRU eviction (O(1)), an optional TTL per entry and an optional
+ * background sweeper.
  *
  * @example
  * ```ts
@@ -69,38 +72,64 @@ interface CacheStats {
  * ```
  */
 declare class Cache {
-    /** Instância da classe nativa (Rust). */
+    /** Instance of the native (Rust) class. */
     private readonly native;
+    /** @throws if `maxSize`, `evictionPolicy` or `cleanupIntervalSeconds` is invalid. */
     constructor(options?: CacheOptions);
-    /** A política de evicção ativa: `"reject"` ou `"lru"`. */
+    /** The active eviction policy: `"reject"` or `"lru"`. */
     get evictionPolicy(): EvictionPolicy;
     /**
-     * Armazena (ou sobrescreve) um valor. O valor é serializado como JSON no core.
+     * Stores (or overwrites) a value, kept as JSON. Accepts plain objects,
+     * arrays, strings, finite numbers, booleans and `null`; object properties
+     * set to `undefined` are left out, as in JSON.
      *
-     * @returns `true` em sucesso; `false` se `maxSize` foi atingido e a chave é nova.
+     * @returns `true` on success; `false` if `maxSize` was reached and the key is new.
+     * @throws TypeError naming the offending path if the value holds something
+     *   JSON cannot represent (a `Date`, `Map`, `Set`, `BigInt`, class instance,
+     *   function, `NaN`, `Infinity`, an `undefined` array item, or `undefined`
+     *   itself) — instead of storing a silently different value.
      */
     set<T>(key: string, value: T, options?: SetOptions): boolean;
     /**
-     * Lê um valor. Aplica expiração preguiçosa: chaves vencidas contam como miss.
+     * Reads a value. Applies lazy expiration: expired keys count as a miss.
+     * Each call returns a new copy, so mutating it does not change the cache.
      *
-     * @returns o valor desserializado, ou `null` se ausente/expirado.
+     * @returns the stored value, or `null` if missing or expired.
      */
     get<T = unknown>(key: string): T | null;
-    /** Remove uma chave. Retorna `true` se ela existia. */
+    /**
+     * Stores text that is **already JSON**, as is — no validation, no
+     * re-encoding. Meant for payloads serialized elsewhere, such as an HTTP
+     * response body. Storing text that is not valid JSON makes `get()` throw.
+     *
+     * @returns `true` on success; `false` if `maxSize` was reached and the key is new.
+     */
+    setJson(key: string, json: string, options?: SetOptions): boolean;
+    /**
+     * Reads a value as its JSON text, without parsing it — e.g. to send it as
+     * an HTTP response body directly. Same expiration and stats as `get()`.
+     *
+     * @returns the JSON text, or `null` if missing or expired.
+     */
+    getJson(key: string): string | null;
+    /** Removes a key. Returns `true` if it existed. */
     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). Does not count
+     * as a use for LRU eviction.
+     */
     exists(key: string): boolean;
-    /** Esvazia o cache (não zera os contadores históricos de `stats`). */
+    /** Empties the cache (does not reset the historical `stats` counters). */
     clear(): void;
-    /** Número de chaves armazenadas no momento. */
+    /** Number of keys currently stored. */
     size(): number;
     /**
-     * Varre e remove todas as entradas expiradas de uma só vez.
+     * Sweeps and removes every expired entry at once.
      *
-     * @returns quantas entradas foram removidas.
+     * @returns how many entries were removed.
      */
     cleanupExpired(): number;
-    /** Retorna as estatísticas acumuladas + o tamanho atual. */
+    /** Returns the accumulated statistics + the current size. */
     stats(): CacheStats;
 }
 

package/dist/index.d.ts

@@ -1,63 +1,66 @@
 /**
- * rust-node-cache — API pública (TypeScript).
+ * rust-node-cache — public API (TypeScript).
  *
- * "Ultra-fast in-memory cache powered by Rust."
+ * "In-memory cache for Node.js that keeps your data off the V8 heap."
  *
- * Esta camada é um wrapper fino e tipado sobre a classe `Cache` nativa gerada
- * pelo Rust/napi-rs. Por que envolver em vez de re-exportar direto?
- *  - permite **genéricos** ergonômicos: `cache.get<User>("user:1")`;
- *  - normaliza `undefined`/`null` para sempre devolver `null` num miss;
- *  - dá um único lugar para JSDoc e para evoluir a API sem quebrar o core Rust.
- *
- * O custo é uma chamada de função extra por operação — desprezível frente ao
- * trabalho real (serialização + acesso ao DashMap) que acontece no Rust.
+ * This layer is a typed wrapper over the native `Cache` class generated by
+ * Rust/napi-rs. It does the JSON encoding on the JavaScript side, where V8's
+ * `JSON.stringify`/`JSON.parse` are fastest, and hands Rust plain strings:
+ *  - `set` validates the value (see `./encode`) and stores its JSON text;
+ *  - `get` parses the stored text back, so every read returns a fresh copy;
+ *  - it allows ergonomic **generics**: `cache.get<User>("user:1")`.
  */
-/** Estratégia de evicção quando `maxSize` é atingido. */
+/** Eviction strategy when `maxSize` is reached. */
 type EvictionPolicy = "reject" | "lru";
-/** Opções do construtor do cache. */
+/** Cache constructor options. */
 interface CacheOptions {
     /**
-     * Limite máximo de chaves. O que acontece ao atingir depende de
-     * `evictionPolicy`. Sem valor => cache ilimitado.
+     * Maximum number of keys (a positive integer). What happens when it is
+     * reached depends on `evictionPolicy`. No value => unlimited cache.
      */
     maxSize?: number;
     /**
-     * Política ao atingir `maxSize` numa chave **nova**:
-     * - `"reject"` (padrão): `set` retorna `false` (sobrescrever continua ok);
-     * - `"lru"`: remove a entrada menos recentemente usada e prossegue.
+     * Policy when `maxSize` is reached on a **new** key:
+     * - `"reject"` (default): `set` returns `false` (overwriting still works);
+     * - `"lru"`: removes the least recently used entry and goes on.
      */
     evictionPolicy?: EvictionPolicy;
     /**
-     * Se definido (> 0), liga uma thread que varre entradas expiradas a cada
-     * N segundos (expiração em background, além da preguiçosa por acesso).
+     * When set (> 0), starts a thread that sweeps expired entries every N
+     * seconds (background expiration, on top of the lazy one on access).
+     * Fractions are allowed; `0` or no value leaves it off.
      */
     cleanupIntervalSeconds?: number;
 }
-/** Opções por operação de escrita. */
+/** Per-write options. */
 interface SetOptions {
-    /** Tempo de vida em segundos. Ausente => a entrada não expira por tempo. */
+    /**
+     * Time to live in seconds; fractions are allowed (`0.5` = 500 ms, minimum
+     * 1 ms). Absent => the entry does not expire by time.
+     */
     ttlSeconds?: number;
 }
-/** Estatísticas acumuladas do cache (mais o tamanho atual). */
+/** Accumulated cache statistics (plus the current size). */
 interface CacheStats {
-    /** Leituras que encontraram uma entrada válida. */
+    /** Reads that found a valid entry. */
     hits: number;
-    /** Leituras sem chave válida (ausente ou expirada). */
+    /** Reads without a valid key (missing or expired). */
     misses: number;
-    /** Total de escritas (`set`). */
+    /** Total writes (`set`). */
     sets: number;
-    /** Total de remoções explícitas (`delete`). */
+    /** Total explicit removals (`delete`). */
     deletes: number;
-    /** Total de entradas removidas por expiração. */
+    /** Total entries removed by expiration. */
     expired: number;
-    /** Total de entradas removidas por evicção (política LRU ao atingir `maxSize`). */
+    /** Total entries removed by eviction (LRU policy when `maxSize` is reached). */
     evicted: number;
-    /** Número de chaves armazenadas agora. */
+    /** Number of keys stored right now. */
     size: number;
 }
 /**
- * Cache em memória ultrarrápido com núcleo em Rust (DashMap + contadores
- * atômicos). Thread-safe e com suporte a TTL por entrada.
+ * In-memory cache whose entries live in Rust memory, outside the V8 heap.
+ * Exact LRU eviction (O(1)), an optional TTL per entry and an optional
+ * background sweeper.
  *
  * @example
  * ```ts
@@ -69,38 +72,64 @@ interface CacheStats {
  * ```
  */
 declare class Cache {
-    /** Instância da classe nativa (Rust). */
+    /** Instance of the native (Rust) class. */
     private readonly native;
+    /** @throws if `maxSize`, `evictionPolicy` or `cleanupIntervalSeconds` is invalid. */
     constructor(options?: CacheOptions);
-    /** A política de evicção ativa: `"reject"` ou `"lru"`. */
+    /** The active eviction policy: `"reject"` or `"lru"`. */
     get evictionPolicy(): EvictionPolicy;
     /**
-     * Armazena (ou sobrescreve) um valor. O valor é serializado como JSON no core.
+     * Stores (or overwrites) a value, kept as JSON. Accepts plain objects,
+     * arrays, strings, finite numbers, booleans and `null`; object properties
+     * set to `undefined` are left out, as in JSON.
      *
-     * @returns `true` em sucesso; `false` se `maxSize` foi atingido e a chave é nova.
+     * @returns `true` on success; `false` if `maxSize` was reached and the key is new.
+     * @throws TypeError naming the offending path if the value holds something
+     *   JSON cannot represent (a `Date`, `Map`, `Set`, `BigInt`, class instance,
+     *   function, `NaN`, `Infinity`, an `undefined` array item, or `undefined`
+     *   itself) — instead of storing a silently different value.
      */
     set<T>(key: string, value: T, options?: SetOptions): boolean;
     /**
-     * Lê um valor. Aplica expiração preguiçosa: chaves vencidas contam como miss.
+     * Reads a value. Applies lazy expiration: expired keys count as a miss.
+     * Each call returns a new copy, so mutating it does not change the cache.
      *
-     * @returns o valor desserializado, ou `null` se ausente/expirado.
+     * @returns the stored value, or `null` if missing or expired.
      */
     get<T = unknown>(key: string): T | null;
-    /** Remove uma chave. Retorna `true` se ela existia. */
+    /**
+     * Stores text that is **already JSON**, as is — no validation, no
+     * re-encoding. Meant for payloads serialized elsewhere, such as an HTTP
+     * response body. Storing text that is not valid JSON makes `get()` throw.
+     *
+     * @returns `true` on success; `false` if `maxSize` was reached and the key is new.
+     */
+    setJson(key: string, json: string, options?: SetOptions): boolean;
+    /**
+     * Reads a value as its JSON text, without parsing it — e.g. to send it as
+     * an HTTP response body directly. Same expiration and stats as `get()`.
+     *
+     * @returns the JSON text, or `null` if missing or expired.
+     */
+    getJson(key: string): string | null;
+    /** Removes a key. Returns `true` if it existed. */
     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). Does not count
+     * as a use for LRU eviction.
+     */
     exists(key: string): boolean;
-    /** Esvazia o cache (não zera os contadores históricos de `stats`). */
+    /** Empties the cache (does not reset the historical `stats` counters). */
     clear(): void;
-    /** Número de chaves armazenadas no momento. */
+    /** Number of keys currently stored. */
     size(): number;
     /**
-     * Varre e remove todas as entradas expiradas de uma só vez.
+     * Sweeps and removes every expired entry at once.
      *
-     * @returns quantas entradas foram removidas.
+     * @returns how many entries were removed.
      */
     cleanupExpired(): number;
-    /** Retorna as estatísticas acumuladas + o tamanho atual. */
+    /** Returns the accumulated statistics + the current size. */
     stats(): CacheStats;
 }