rust-node-cache 0.2.0 → 0.3.0

package/dist/index.js

@@ -34,7 +34,91 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 var native = __toESM(require("../binding.js"));
+
+// js/encode.ts
+var MAX_DEPTH = 1e3;
+var HINTS = {
+  Date: " Store date.toISOString() or date.getTime() instead.",
+  Map: " Store Object.fromEntries(map) instead.",
+  Set: " Store [...set] instead.",
+  BigInt: " Store String(n) instead."
+};
+var IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+function encode(value) {
+  const problem2 = check(value, 0);
+  if (problem2 !== void 0) throw toError(problem2);
+  return JSON.stringify(value);
+}
+function check(value, depth) {
+  switch (typeof value) {
+    case "string":
+    case "boolean":
+      return void 0;
+    case "number":
+      return Number.isFinite(value) ? void 0 : problem(String(value));
+    case "object": {
+      if (value === null) return void 0;
+      if (depth >= MAX_DEPTH) return tooDeep(value);
+      if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+          const item = value[i];
+          const p = item === void 0 ? problem("undefined") : check(item, depth + 1);
+          if (p !== void 0) {
+            p.path.unshift(i);
+            return p;
+          }
+        }
+        return void 0;
+      }
+      const proto = Object.getPrototypeOf(value);
+      if (proto !== Object.prototype && proto !== null) {
+        const name = value.constructor?.name;
+        return problem(
+          name ? `a ${name}` : "an object with a custom prototype",
+          name && HINTS[name] || ""
+        );
+      }
+      for (const key in value) {
+        const item = value[key];
+        if (item === void 0) continue;
+        const p = check(item, depth + 1);
+        if (p !== void 0) {
+          p.path.unshift(key);
+          return p;
+        }
+      }
+      return void 0;
+    }
+    case "bigint":
+      return problem("a BigInt", HINTS.BigInt);
+    case "undefined":
+      return problem("undefined");
+    default:
+      return problem(`a ${typeof value}`);
+  }
+}
+function problem(what, hint = "") {
+  return { path: [], what, hint };
+}
+function toError({ path, what, hint }) {
+  let where = "value";
+  for (const part of path) {
+    if (typeof part === "number") where += `[${part}]`;
+    else if (IDENTIFIER.test(part)) where += `.${part}`;
+    else where += `[${JSON.stringify(part)}]`;
+  }
+  return new TypeError(
+    `rust-node-cache: cannot store ${where} (${what}). Values are kept as JSON, so only plain objects, arrays, strings, finite numbers, booleans and null are accepted.${hint}`
+  );
+}
+function tooDeep(value) {
+  JSON.stringify(value);
+  throw new TypeError(`rust-node-cache: cannot store a value nested more than ${MAX_DEPTH} levels deep.`);
+}
+
+// js/index.ts
 var Cache2 = class {
+  /** @throws if `maxSize`, `evictionPolicy` or `cleanupIntervalSeconds` is invalid. */
   constructor(options = {}) {
     const hasOptions = options.maxSize !== void 0 || options.evictionPolicy !== void 0 || options.cleanupIntervalSeconds !== void 0;
     this.native = hasOptions ? new native.Cache({
@@ -43,52 +127,81 @@ var Cache2 = class {
       cleanupIntervalSeconds: options.cleanupIntervalSeconds
     }) : new native.Cache();
   }
-  /** A política de evicção ativa: `"reject"` ou `"lru"`. */
+  /** The active eviction policy: `"reject"` or `"lru"`. */
   get evictionPolicy() {
     return this.native.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(key, value, options) {
-    return this.native.set(key, value, options);
+    return this.native.set(key, encode(value), options);
   }
   /**
-   * 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(key) {
-    const value = this.native.get(key);
-    return value === null || value === void 0 ? null : value;
+    const json = this.native.get(key);
+    return json === null ? null : JSON.parse(json);
+  }
+  /**
+   * 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, json, options) {
+    return this.native.set(key, json, options);
+  }
+  /**
+   * 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) {
+    return this.native.get(key);
   }
-  /** Remove uma chave. Retorna `true` se ela existia. */
+  /** Removes a key. Returns `true` if it existed. */
   delete(key) {
     return this.native.delete(key);
   }
-  /** 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) {
     return this.native.exists(key);
   }
-  /** Esvazia o cache (não zera os contadores históricos de `stats`). */
+  /** Empties the cache (does not reset the historical `stats` counters). */
   clear() {
     this.native.clear();
   }
-  /** Número de chaves armazenadas no momento. */
+  /** Number of keys currently stored. */
   size() {
     return this.native.size();
   }
   /**
-   * 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() {
     return this.native.cleanupExpired();
   }
-  /** Retorna as estatísticas acumuladas + o tamanho atual. */
+  /** Returns the accumulated statistics + the current size. */
   stats() {
     return this.native.stats();
   }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../js/index.ts"],"sourcesContent":["/**\n * rust-node-cache — API pública (TypeScript).\n *\n * \"Ultra-fast in-memory cache powered by Rust.\"\n *\n * Esta camada é um wrapper fino e tipado sobre a classe `Cache` nativa gerada\n * pelo Rust/napi-rs. Por que envolver em vez de re-exportar direto?\n *  - permite **genéricos** ergonômicos: `cache.get<User>(\"user:1\")`;\n *  - normaliza `undefined`/`null` para sempre devolver `null` num miss;\n *  - dá um único lugar para JSDoc e para evoluir a API sem quebrar o core Rust.\n *\n * O custo é uma chamada de função extra por operação — desprezível frente ao\n * trabalho real (serialização + acesso ao DashMap) que acontece no Rust.\n */\n\n// Namespace import: funciona igual em CommonJS e ESM ao consumir o addon nativo\n// (que é um módulo CJS gerado pelo napi-rs).\nimport * as native from \"../binding.js\";\n\n/** Estratégia de evicção quando `maxSize` é atingido. */\nexport type EvictionPolicy = \"reject\" | \"lru\";\n\n/** Opções do construtor do cache. */\nexport interface CacheOptions {\n  /**\n   * Limite máximo de chaves. O que acontece ao atingir depende de\n   * `evictionPolicy`. Sem valor => cache ilimitado.\n   */\n  maxSize?: number;\n  /**\n   * Política ao atingir `maxSize` numa chave **nova**:\n   * - `\"reject\"` (padrão): `set` retorna `false` (sobrescrever continua ok);\n   * - `\"lru\"`: remove a entrada menos recentemente usada e prossegue.\n   */\n  evictionPolicy?: EvictionPolicy;\n  /**\n   * Se definido (> 0), liga uma thread que varre entradas expiradas a cada\n   * N segundos (expiração em background, além da preguiçosa por acesso).\n   */\n  cleanupIntervalSeconds?: number;\n}\n\n/** Opções por operação de escrita. */\nexport interface SetOptions {\n  /** Tempo de vida em segundos. Ausente => a entrada não expira por tempo. */\n  ttlSeconds?: number;\n}\n\n/** Estatísticas acumuladas do cache (mais o tamanho atual). */\nexport interface CacheStats {\n  /** Leituras que encontraram uma entrada válida. */\n  hits: number;\n  /** Leituras sem chave válida (ausente ou expirada). */\n  misses: number;\n  /** Total de escritas (`set`). */\n  sets: number;\n  /** Total de remoções explícitas (`delete`). */\n  deletes: number;\n  /** Total de entradas removidas por expiração. */\n  expired: number;\n  /** Total de entradas removidas por evicção (política LRU ao atingir `maxSize`). */\n  evicted: number;\n  /** Número de chaves armazenadas agora. */\n  size: number;\n}\n\n/**\n * Cache em memória ultrarrápido com núcleo em Rust (DashMap + contadores\n * atômicos). Thread-safe e com suporte a TTL por entrada.\n *\n * @example\n * ```ts\n * import { Cache } from \"rust-node-cache\";\n *\n * const cache = new Cache();\n * cache.set(\"user:1\", { id: 1, name: \"Roberto\" });\n * cache.get<{ id: number; name: string }>(\"user:1\"); // { id: 1, name: \"Roberto\" }\n * ```\n */\nexport class Cache {\n  /** Instância da classe nativa (Rust). */\n  private readonly native: native.Cache;\n\n  constructor(options: CacheOptions = {}) {\n    // Só repassamos um objeto de opções ao Rust quando há algo relevante.\n    const hasOptions =\n      options.maxSize !== undefined ||\n      options.evictionPolicy !== undefined ||\n      options.cleanupIntervalSeconds !== undefined;\n    this.native = hasOptions\n      ? new native.Cache({\n          maxSize: options.maxSize,\n          evictionPolicy: options.evictionPolicy,\n          cleanupIntervalSeconds: options.cleanupIntervalSeconds,\n        })\n      : new native.Cache();\n  }\n\n  /** A política de evicção ativa: `\"reject\"` ou `\"lru\"`. */\n  get evictionPolicy(): EvictionPolicy {\n    return this.native.evictionPolicy as EvictionPolicy;\n  }\n\n  /**\n   * Armazena (ou sobrescreve) um valor. O valor é serializado como JSON no core.\n   *\n   * @returns `true` em sucesso; `false` se `maxSize` foi atingido e a chave é nova.\n   */\n  set<T>(key: string, value: T, options?: SetOptions): boolean {\n    return this.native.set(key, value as unknown as object, options);\n  }\n\n  /**\n   * Lê um valor. Aplica expiração preguiçosa: chaves vencidas contam como miss.\n   *\n   * @returns o valor desserializado, ou `null` se ausente/expirado.\n   */\n  get<T = unknown>(key: string): T | null {\n    const value = this.native.get(key);\n    return value === null || value === undefined ? null : (value as T);\n  }\n\n  /** Remove uma chave. Retorna `true` se ela existia. */\n  delete(key: string): boolean {\n    return this.native.delete(key);\n  }\n\n  /** Indica se a chave existe e está válida (não expirada). */\n  exists(key: string): boolean {\n    return this.native.exists(key);\n  }\n\n  /** Esvazia o cache (não zera os contadores históricos de `stats`). */\n  clear(): void {\n    this.native.clear();\n  }\n\n  /** Número de chaves armazenadas no momento. */\n  size(): number {\n    return this.native.size();\n  }\n\n  /**\n   * Varre e remove todas as entradas expiradas de uma só vez.\n   *\n   * @returns quantas entradas foram removidas.\n   */\n  cleanupExpired(): number {\n    return this.native.cleanupExpired();\n  }\n\n  /** Retorna as estatísticas acumuladas + o tamanho atual. */\n  stats(): CacheStats {\n    return this.native.stats();\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA,eAAAA;AAAA;AAAA;AAiBA,aAAwB;AA8DjB,IAAMA,SAAN,MAAY;AAAA,EAIjB,YAAY,UAAwB,CAAC,GAAG;AAEtC,UAAM,aACJ,QAAQ,YAAY,UACpB,QAAQ,mBAAmB,UAC3B,QAAQ,2BAA2B;AACrC,SAAK,SAAS,aACV,IAAW,aAAM;AAAA,MACf,SAAS,QAAQ;AAAA,MACjB,gBAAgB,QAAQ;AAAA,MACxB,wBAAwB,QAAQ;AAAA,IAClC,CAAC,IACD,IAAW,aAAM;AAAA,EACvB;AAAA;AAAA,EAGA,IAAI,iBAAiC;AACnC,WAAO,KAAK,OAAO;AAAA,EACrB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,IAAO,KAAa,OAAU,SAA+B;AAC3D,WAAO,KAAK,OAAO,IAAI,KAAK,OAA4B,OAAO;AAAA,EACjE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,IAAiB,KAAuB;AACtC,UAAM,QAAQ,KAAK,OAAO,IAAI,GAAG;AACjC,WAAO,UAAU,QAAQ,UAAU,SAAY,OAAQ;AAAA,EACzD;AAAA;AAAA,EAGA,OAAO,KAAsB;AAC3B,WAAO,KAAK,OAAO,OAAO,GAAG;AAAA,EAC/B;AAAA;AAAA,EAGA,OAAO,KAAsB;AAC3B,WAAO,KAAK,OAAO,OAAO,GAAG;AAAA,EAC/B;AAAA;AAAA,EAGA,QAAc;AACZ,SAAK,OAAO,MAAM;AAAA,EACpB;AAAA;AAAA,EAGA,OAAe;AACb,WAAO,KAAK,OAAO,KAAK;AAAA,EAC1B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,iBAAyB;AACvB,WAAO,KAAK,OAAO,eAAe;AAAA,EACpC;AAAA;AAAA,EAGA,QAAoB;AAClB,WAAO,KAAK,OAAO,MAAM;AAAA,EAC3B;AACF;","names":["Cache"]}
+{"version":3,"sources":["../js/index.ts","../js/encode.ts"],"sourcesContent":["/**\n * rust-node-cache — public API (TypeScript).\n *\n * \"In-memory cache for Node.js that keeps your data off the V8 heap.\"\n *\n * This layer is a typed wrapper over the native `Cache` class generated by\n * Rust/napi-rs. It does the JSON encoding on the JavaScript side, where V8's\n * `JSON.stringify`/`JSON.parse` are fastest, and hands Rust plain strings:\n *  - `set` validates the value (see `./encode`) and stores its JSON text;\n *  - `get` parses the stored text back, so every read returns a fresh copy;\n *  - it allows ergonomic **generics**: `cache.get<User>(\"user:1\")`.\n */\n\n// Namespace import: works the same in CommonJS and ESM when consuming the native\n// addon (a CJS module generated by napi-rs).\nimport * as native from \"../binding.js\";\nimport { encode } from \"./encode\";\n\n/** Eviction strategy when `maxSize` is reached. */\nexport type EvictionPolicy = \"reject\" | \"lru\";\n\n/** Cache constructor options. */\nexport interface CacheOptions {\n  /**\n   * Maximum number of keys (a positive integer). What happens when it is\n   * reached depends on `evictionPolicy`. No value => unlimited cache.\n   */\n  maxSize?: number;\n  /**\n   * Policy when `maxSize` is reached on a **new** key:\n   * - `\"reject\"` (default): `set` returns `false` (overwriting still works);\n   * - `\"lru\"`: removes the least recently used entry and goes on.\n   */\n  evictionPolicy?: EvictionPolicy;\n  /**\n   * When set (> 0), starts a thread that sweeps expired entries every N\n   * seconds (background expiration, on top of the lazy one on access).\n   * Fractions are allowed; `0` or no value leaves it off.\n   */\n  cleanupIntervalSeconds?: number;\n}\n\n/** Per-write options. */\nexport interface SetOptions {\n  /**\n   * Time to live in seconds; fractions are allowed (`0.5` = 500 ms, minimum\n   * 1 ms). Absent => the entry does not expire by time.\n   */\n  ttlSeconds?: number;\n}\n\n/** Accumulated cache statistics (plus the current size). */\nexport interface CacheStats {\n  /** Reads that found a valid entry. */\n  hits: number;\n  /** Reads without a valid key (missing or expired). */\n  misses: number;\n  /** Total writes (`set`). */\n  sets: number;\n  /** Total explicit removals (`delete`). */\n  deletes: number;\n  /** Total entries removed by expiration. */\n  expired: number;\n  /** Total entries removed by eviction (LRU policy when `maxSize` is reached). */\n  evicted: number;\n  /** Number of keys stored right now. */\n  size: number;\n}\n\n/**\n * In-memory cache whose entries live in Rust memory, outside the V8 heap.\n * Exact LRU eviction (O(1)), an optional TTL per entry and an optional\n * background sweeper.\n *\n * @example\n * ```ts\n * import { Cache } from \"rust-node-cache\";\n *\n * const cache = new Cache();\n * cache.set(\"user:1\", { id: 1, name: \"Roberto\" });\n * cache.get<{ id: number; name: string }>(\"user:1\"); // { id: 1, name: \"Roberto\" }\n * ```\n */\nexport class Cache {\n  /** Instance of the native (Rust) class. */\n  private readonly native: native.Cache;\n\n  /** @throws if `maxSize`, `evictionPolicy` or `cleanupIntervalSeconds` is invalid. */\n  constructor(options: CacheOptions = {}) {\n    // An options object is passed to Rust only when it carries something.\n    const hasOptions =\n      options.maxSize !== undefined ||\n      options.evictionPolicy !== undefined ||\n      options.cleanupIntervalSeconds !== undefined;\n    this.native = hasOptions\n      ? new native.Cache({\n          maxSize: options.maxSize,\n          evictionPolicy: options.evictionPolicy,\n          cleanupIntervalSeconds: options.cleanupIntervalSeconds,\n        })\n      : new native.Cache();\n  }\n\n  /** The active eviction policy: `\"reject\"` or `\"lru\"`. */\n  get evictionPolicy(): EvictionPolicy {\n    return this.native.evictionPolicy as EvictionPolicy;\n  }\n\n  /**\n   * Stores (or overwrites) a value, kept as JSON. Accepts plain objects,\n   * arrays, strings, finite numbers, booleans and `null`; object properties\n   * set to `undefined` are left out, as in JSON.\n   *\n   * @returns `true` on success; `false` if `maxSize` was reached and the key is new.\n   * @throws TypeError naming the offending path if the value holds something\n   *   JSON cannot represent (a `Date`, `Map`, `Set`, `BigInt`, class instance,\n   *   function, `NaN`, `Infinity`, an `undefined` array item, or `undefined`\n   *   itself) — instead of storing a silently different value.\n   */\n  set<T>(key: string, value: T, options?: SetOptions): boolean {\n    return this.native.set(key, encode(value), options);\n  }\n\n  /**\n   * Reads a value. Applies lazy expiration: expired keys count as a miss.\n   * Each call returns a new copy, so mutating it does not change the cache.\n   *\n   * @returns the stored value, or `null` if missing or expired.\n   */\n  get<T = unknown>(key: string): T | null {\n    const json = this.native.get(key);\n    return json === null ? null : (JSON.parse(json) as T);\n  }\n\n  /**\n   * Stores text that is **already JSON**, as is — no validation, no\n   * re-encoding. Meant for payloads serialized elsewhere, such as an HTTP\n   * response body. Storing text that is not valid JSON makes `get()` throw.\n   *\n   * @returns `true` on success; `false` if `maxSize` was reached and the key is new.\n   */\n  setJson(key: string, json: string, options?: SetOptions): boolean {\n    return this.native.set(key, json, options);\n  }\n\n  /**\n   * Reads a value as its JSON text, without parsing it — e.g. to send it as\n   * an HTTP response body directly. Same expiration and stats as `get()`.\n   *\n   * @returns the JSON text, or `null` if missing or expired.\n   */\n  getJson(key: string): string | null {\n    return this.native.get(key);\n  }\n\n  /** Removes a key. Returns `true` if it existed. */\n  delete(key: string): boolean {\n    return this.native.delete(key);\n  }\n\n  /**\n   * Whether the key exists and is still valid (not expired). Does not count\n   * as a use for LRU eviction.\n   */\n  exists(key: string): boolean {\n    return this.native.exists(key);\n  }\n\n  /** Empties the cache (does not reset the historical `stats` counters). */\n  clear(): void {\n    this.native.clear();\n  }\n\n  /** Number of keys currently stored. */\n  size(): number {\n    return this.native.size();\n  }\n\n  /**\n   * Sweeps and removes every expired entry at once.\n   *\n   * @returns how many entries were removed.\n   */\n  cleanupExpired(): number {\n    return this.native.cleanupExpired();\n  }\n\n  /** Returns the accumulated statistics + the current size. */\n  stats(): CacheStats {\n    return this.native.stats();\n  }\n}\n","/**\n * Value encoding for the cache: validate, then `JSON.stringify`.\n *\n * Values are kept as JSON text in Rust memory. JSON cannot represent a `Date`,\n * `Map`, `Set`, `BigInt`, class instance, `NaN`/`Infinity` or an `undefined`\n * array slot — `JSON.stringify` would silently turn them into `{}`, a string or\n * `null`, and `get()` would return something else than what was stored. So\n * those are rejected with a `TypeError` naming where they are, instead.\n */\n\n/** Nesting deeper than this is reported instead of overflowing the stack. */\nconst MAX_DEPTH = 1000;\n\nconst HINTS: Record<string, string> = {\n  Date: \" Store date.toISOString() or date.getTime() instead.\",\n  Map: \" Store Object.fromEntries(map) instead.\",\n  Set: \" Store [...set] instead.\",\n  BigInt: \" Store String(n) instead.\",\n};\n\nconst IDENTIFIER = /^[A-Za-z_$][\\w$]*$/;\n\n/** Validates `value` and returns its JSON text. Throws `TypeError` otherwise. */\nexport function encode(value: unknown): string {\n  const problem = check(value, 0);\n  if (problem !== undefined) throw toError(problem);\n  return JSON.stringify(value);\n}\n\n/** Why a value was rejected. `path` is filled in while unwinding, root first. */\ninterface Problem {\n  path: (string | number)[];\n  what: string;\n  hint: string;\n}\n\n/**\n * Returns `undefined` when `value` round-trips through JSON unchanged, or the\n * first problem found. The path is only built on failure, so the common case\n * stays a bare walk.\n */\nfunction check(value: unknown, depth: number): Problem | undefined {\n  switch (typeof value) {\n    case \"string\":\n    case \"boolean\":\n      return undefined;\n    case \"number\":\n      return Number.isFinite(value) ? undefined : problem(String(value));\n    case \"object\": {\n      if (value === null) return undefined;\n      if (depth >= MAX_DEPTH) return tooDeep(value);\n      if (Array.isArray(value)) {\n        for (let i = 0; i < value.length; i++) {\n          const item = value[i];\n          const p = item === undefined ? problem(\"undefined\") : check(item, depth + 1);\n          if (p !== undefined) {\n            p.path.unshift(i);\n            return p;\n          }\n        }\n        return undefined;\n      }\n      const proto = Object.getPrototypeOf(value);\n      if (proto !== Object.prototype && proto !== null) {\n        const name = (value as object).constructor?.name;\n        return problem(\n          name ? `a ${name}` : \"an object with a custom prototype\",\n          (name && HINTS[name]) || \"\",\n        );\n      }\n      for (const key in value) {\n        const item = (value as Record<string, unknown>)[key];\n        // JSON omits undefined properties, and reading one back yields undefined\n        // anyway, so they are accepted.\n        if (item === undefined) continue;\n        const p = check(item, depth + 1);\n        if (p !== undefined) {\n          p.path.unshift(key);\n          return p;\n        }\n      }\n      return undefined;\n    }\n    case \"bigint\":\n      return problem(\"a BigInt\", HINTS.BigInt);\n    case \"undefined\":\n      return problem(\"undefined\");\n    default:\n      // function, symbol\n      return problem(`a ${typeof value}`);\n  }\n}\n\nfunction problem(what: string, hint = \"\"): Problem {\n  return { path: [], what, hint };\n}\n\nfunction toError({ path, what, hint }: Problem): TypeError {\n  let where = \"value\";\n  for (const part of path) {\n    if (typeof part === \"number\") where += `[${part}]`;\n    else if (IDENTIFIER.test(part)) where += `.${part}`;\n    else where += `[${JSON.stringify(part)}]`;\n  }\n  return new TypeError(\n    `rust-node-cache: cannot store ${where} (${what}). Values are kept as JSON, so only ` +\n      `plain objects, arrays, strings, finite numbers, booleans and null are accepted.${hint}`,\n  );\n}\n\nfunction tooDeep(value: unknown): never {\n  // A cycle also ends up here; let JSON.stringify name it if that is the case.\n  JSON.stringify(value);\n  throw new TypeError(`rust-node-cache: cannot store a value nested more than ${MAX_DEPTH} levels deep.`);\n}\n"],"mappings":"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","names":["Cache","problem","Cache"]}

package/dist/index.mjs

@@ -1,6 +1,90 @@
 // js/index.ts
 import * as native from "../binding.js";
+
+// js/encode.ts
+var MAX_DEPTH = 1e3;
+var HINTS = {
+  Date: " Store date.toISOString() or date.getTime() instead.",
+  Map: " Store Object.fromEntries(map) instead.",
+  Set: " Store [...set] instead.",
+  BigInt: " Store String(n) instead."
+};
+var IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+function encode(value) {
+  const problem2 = check(value, 0);
+  if (problem2 !== void 0) throw toError(problem2);
+  return JSON.stringify(value);
+}
+function check(value, depth) {
+  switch (typeof value) {
+    case "string":
+    case "boolean":
+      return void 0;
+    case "number":
+      return Number.isFinite(value) ? void 0 : problem(String(value));
+    case "object": {
+      if (value === null) return void 0;
+      if (depth >= MAX_DEPTH) return tooDeep(value);
+      if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+          const item = value[i];
+          const p = item === void 0 ? problem("undefined") : check(item, depth + 1);
+          if (p !== void 0) {
+            p.path.unshift(i);
+            return p;
+          }
+        }
+        return void 0;
+      }
+      const proto = Object.getPrototypeOf(value);
+      if (proto !== Object.prototype && proto !== null) {
+        const name = value.constructor?.name;
+        return problem(
+          name ? `a ${name}` : "an object with a custom prototype",
+          name && HINTS[name] || ""
+        );
+      }
+      for (const key in value) {
+        const item = value[key];
+        if (item === void 0) continue;
+        const p = check(item, depth + 1);
+        if (p !== void 0) {
+          p.path.unshift(key);
+          return p;
+        }
+      }
+      return void 0;
+    }
+    case "bigint":
+      return problem("a BigInt", HINTS.BigInt);
+    case "undefined":
+      return problem("undefined");
+    default:
+      return problem(`a ${typeof value}`);
+  }
+}
+function problem(what, hint = "") {
+  return { path: [], what, hint };
+}
+function toError({ path, what, hint }) {
+  let where = "value";
+  for (const part of path) {
+    if (typeof part === "number") where += `[${part}]`;
+    else if (IDENTIFIER.test(part)) where += `.${part}`;
+    else where += `[${JSON.stringify(part)}]`;
+  }
+  return new TypeError(
+    `rust-node-cache: cannot store ${where} (${what}). Values are kept as JSON, so only plain objects, arrays, strings, finite numbers, booleans and null are accepted.${hint}`
+  );
+}
+function tooDeep(value) {
+  JSON.stringify(value);
+  throw new TypeError(`rust-node-cache: cannot store a value nested more than ${MAX_DEPTH} levels deep.`);
+}
+
+// js/index.ts
 var Cache2 = class {
+  /** @throws if `maxSize`, `evictionPolicy` or `cleanupIntervalSeconds` is invalid. */
   constructor(options = {}) {
     const hasOptions = options.maxSize !== void 0 || options.evictionPolicy !== void 0 || options.cleanupIntervalSeconds !== void 0;
     this.native = hasOptions ? new native.Cache({
@@ -9,52 +93,81 @@ var Cache2 = class {
       cleanupIntervalSeconds: options.cleanupIntervalSeconds
     }) : new native.Cache();
   }
-  /** A política de evicção ativa: `"reject"` ou `"lru"`. */
+  /** The active eviction policy: `"reject"` or `"lru"`. */
   get evictionPolicy() {
     return this.native.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(key, value, options) {
-    return this.native.set(key, value, options);
+    return this.native.set(key, encode(value), options);
   }
   /**
-   * 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(key) {
-    const value = this.native.get(key);
-    return value === null || value === void 0 ? null : value;
+    const json = this.native.get(key);
+    return json === null ? null : JSON.parse(json);
+  }
+  /**
+   * 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, json, options) {
+    return this.native.set(key, json, options);
   }
-  /** Remove uma chave. Retorna `true` se ela existia. */
+  /**
+   * 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) {
+    return this.native.get(key);
+  }
+  /** Removes a key. Returns `true` if it existed. */
   delete(key) {
     return this.native.delete(key);
   }
-  /** 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) {
     return this.native.exists(key);
   }
-  /** Esvazia o cache (não zera os contadores históricos de `stats`). */
+  /** Empties the cache (does not reset the historical `stats` counters). */
   clear() {
     this.native.clear();
   }
-  /** Número de chaves armazenadas no momento. */
+  /** Number of keys currently stored. */
   size() {
     return this.native.size();
   }
   /**
-   * 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() {
     return this.native.cleanupExpired();
   }
-  /** Retorna as estatísticas acumuladas + o tamanho atual. */
+  /** Returns the accumulated statistics + the current size. */
   stats() {
     return this.native.stats();
   }

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../js/index.ts"],"sourcesContent":["/**\n * rust-node-cache — API pública (TypeScript).\n *\n * \"Ultra-fast in-memory cache powered by Rust.\"\n *\n * Esta camada é um wrapper fino e tipado sobre a classe `Cache` nativa gerada\n * pelo Rust/napi-rs. Por que envolver em vez de re-exportar direto?\n *  - permite **genéricos** ergonômicos: `cache.get<User>(\"user:1\")`;\n *  - normaliza `undefined`/`null` para sempre devolver `null` num miss;\n *  - dá um único lugar para JSDoc e para evoluir a API sem quebrar o core Rust.\n *\n * O custo é uma chamada de função extra por operação — desprezível frente ao\n * trabalho real (serialização + acesso ao DashMap) que acontece no Rust.\n */\n\n// Namespace import: funciona igual em CommonJS e ESM ao consumir o addon nativo\n// (que é um módulo CJS gerado pelo napi-rs).\nimport * as native from \"../binding.js\";\n\n/** Estratégia de evicção quando `maxSize` é atingido. */\nexport type EvictionPolicy = \"reject\" | \"lru\";\n\n/** Opções do construtor do cache. */\nexport interface CacheOptions {\n  /**\n   * Limite máximo de chaves. O que acontece ao atingir depende de\n   * `evictionPolicy`. Sem valor => cache ilimitado.\n   */\n  maxSize?: number;\n  /**\n   * Política ao atingir `maxSize` numa chave **nova**:\n   * - `\"reject\"` (padrão): `set` retorna `false` (sobrescrever continua ok);\n   * - `\"lru\"`: remove a entrada menos recentemente usada e prossegue.\n   */\n  evictionPolicy?: EvictionPolicy;\n  /**\n   * Se definido (> 0), liga uma thread que varre entradas expiradas a cada\n   * N segundos (expiração em background, além da preguiçosa por acesso).\n   */\n  cleanupIntervalSeconds?: number;\n}\n\n/** Opções por operação de escrita. */\nexport interface SetOptions {\n  /** Tempo de vida em segundos. Ausente => a entrada não expira por tempo. */\n  ttlSeconds?: number;\n}\n\n/** Estatísticas acumuladas do cache (mais o tamanho atual). */\nexport interface CacheStats {\n  /** Leituras que encontraram uma entrada válida. */\n  hits: number;\n  /** Leituras sem chave válida (ausente ou expirada). */\n  misses: number;\n  /** Total de escritas (`set`). */\n  sets: number;\n  /** Total de remoções explícitas (`delete`). */\n  deletes: number;\n  /** Total de entradas removidas por expiração. */\n  expired: number;\n  /** Total de entradas removidas por evicção (política LRU ao atingir `maxSize`). */\n  evicted: number;\n  /** Número de chaves armazenadas agora. */\n  size: number;\n}\n\n/**\n * Cache em memória ultrarrápido com núcleo em Rust (DashMap + contadores\n * atômicos). Thread-safe e com suporte a TTL por entrada.\n *\n * @example\n * ```ts\n * import { Cache } from \"rust-node-cache\";\n *\n * const cache = new Cache();\n * cache.set(\"user:1\", { id: 1, name: \"Roberto\" });\n * cache.get<{ id: number; name: string }>(\"user:1\"); // { id: 1, name: \"Roberto\" }\n * ```\n */\nexport class Cache {\n  /** Instância da classe nativa (Rust). */\n  private readonly native: native.Cache;\n\n  constructor(options: CacheOptions = {}) {\n    // Só repassamos um objeto de opções ao Rust quando há algo relevante.\n    const hasOptions =\n      options.maxSize !== undefined ||\n      options.evictionPolicy !== undefined ||\n      options.cleanupIntervalSeconds !== undefined;\n    this.native = hasOptions\n      ? new native.Cache({\n          maxSize: options.maxSize,\n          evictionPolicy: options.evictionPolicy,\n          cleanupIntervalSeconds: options.cleanupIntervalSeconds,\n        })\n      : new native.Cache();\n  }\n\n  /** A política de evicção ativa: `\"reject\"` ou `\"lru\"`. */\n  get evictionPolicy(): EvictionPolicy {\n    return this.native.evictionPolicy as EvictionPolicy;\n  }\n\n  /**\n   * Armazena (ou sobrescreve) um valor. O valor é serializado como JSON no core.\n   *\n   * @returns `true` em sucesso; `false` se `maxSize` foi atingido e a chave é nova.\n   */\n  set<T>(key: string, value: T, options?: SetOptions): boolean {\n    return this.native.set(key, value as unknown as object, options);\n  }\n\n  /**\n   * Lê um valor. Aplica expiração preguiçosa: chaves vencidas contam como miss.\n   *\n   * @returns o valor desserializado, ou `null` se ausente/expirado.\n   */\n  get<T = unknown>(key: string): T | null {\n    const value = this.native.get(key);\n    return value === null || value === undefined ? null : (value as T);\n  }\n\n  /** Remove uma chave. Retorna `true` se ela existia. */\n  delete(key: string): boolean {\n    return this.native.delete(key);\n  }\n\n  /** Indica se a chave existe e está válida (não expirada). */\n  exists(key: string): boolean {\n    return this.native.exists(key);\n  }\n\n  /** Esvazia o cache (não zera os contadores históricos de `stats`). */\n  clear(): void {\n    this.native.clear();\n  }\n\n  /** Número de chaves armazenadas no momento. */\n  size(): number {\n    return this.native.size();\n  }\n\n  /**\n   * Varre e remove todas as entradas expiradas de uma só vez.\n   *\n   * @returns quantas entradas foram removidas.\n   */\n  cleanupExpired(): number {\n    return this.native.cleanupExpired();\n  }\n\n  /** Retorna as estatísticas acumuladas + o tamanho atual. */\n  stats(): CacheStats {\n    return this.native.stats();\n  }\n}\n"],"mappings":";AAiBA,YAAY,YAAY;AA8DjB,IAAMA,SAAN,MAAY;AAAA,EAIjB,YAAY,UAAwB,CAAC,GAAG;AAEtC,UAAM,aACJ,QAAQ,YAAY,UACpB,QAAQ,mBAAmB,UAC3B,QAAQ,2BAA2B;AACrC,SAAK,SAAS,aACV,IAAW,aAAM;AAAA,MACf,SAAS,QAAQ;AAAA,MACjB,gBAAgB,QAAQ;AAAA,MACxB,wBAAwB,QAAQ;AAAA,IAClC,CAAC,IACD,IAAW,aAAM;AAAA,EACvB;AAAA;AAAA,EAGA,IAAI,iBAAiC;AACnC,WAAO,KAAK,OAAO;AAAA,EACrB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,IAAO,KAAa,OAAU,SAA+B;AAC3D,WAAO,KAAK,OAAO,IAAI,KAAK,OAA4B,OAAO;AAAA,EACjE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,IAAiB,KAAuB;AACtC,UAAM,QAAQ,KAAK,OAAO,IAAI,GAAG;AACjC,WAAO,UAAU,QAAQ,UAAU,SAAY,OAAQ;AAAA,EACzD;AAAA;AAAA,EAGA,OAAO,KAAsB;AAC3B,WAAO,KAAK,OAAO,OAAO,GAAG;AAAA,EAC/B;AAAA;AAAA,EAGA,OAAO,KAAsB;AAC3B,WAAO,KAAK,OAAO,OAAO,GAAG;AAAA,EAC/B;AAAA;AAAA,EAGA,QAAc;AACZ,SAAK,OAAO,MAAM;AAAA,EACpB;AAAA;AAAA,EAGA,OAAe;AACb,WAAO,KAAK,OAAO,KAAK;AAAA,EAC1B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,iBAAyB;AACvB,WAAO,KAAK,OAAO,eAAe;AAAA,EACpC;AAAA;AAAA,EAGA,QAAoB;AAClB,WAAO,KAAK,OAAO,MAAM;AAAA,EAC3B;AACF;","names":["Cache"]}
+{"version":3,"sources":["../js/index.ts","../js/encode.ts"],"sourcesContent":["/**\n * rust-node-cache — public API (TypeScript).\n *\n * \"In-memory cache for Node.js that keeps your data off the V8 heap.\"\n *\n * This layer is a typed wrapper over the native `Cache` class generated by\n * Rust/napi-rs. It does the JSON encoding on the JavaScript side, where V8's\n * `JSON.stringify`/`JSON.parse` are fastest, and hands Rust plain strings:\n *  - `set` validates the value (see `./encode`) and stores its JSON text;\n *  - `get` parses the stored text back, so every read returns a fresh copy;\n *  - it allows ergonomic **generics**: `cache.get<User>(\"user:1\")`.\n */\n\n// Namespace import: works the same in CommonJS and ESM when consuming the native\n// addon (a CJS module generated by napi-rs).\nimport * as native from \"../binding.js\";\nimport { encode } from \"./encode\";\n\n/** Eviction strategy when `maxSize` is reached. */\nexport type EvictionPolicy = \"reject\" | \"lru\";\n\n/** Cache constructor options. */\nexport interface CacheOptions {\n  /**\n   * Maximum number of keys (a positive integer). What happens when it is\n   * reached depends on `evictionPolicy`. No value => unlimited cache.\n   */\n  maxSize?: number;\n  /**\n   * Policy when `maxSize` is reached on a **new** key:\n   * - `\"reject\"` (default): `set` returns `false` (overwriting still works);\n   * - `\"lru\"`: removes the least recently used entry and goes on.\n   */\n  evictionPolicy?: EvictionPolicy;\n  /**\n   * When set (> 0), starts a thread that sweeps expired entries every N\n   * seconds (background expiration, on top of the lazy one on access).\n   * Fractions are allowed; `0` or no value leaves it off.\n   */\n  cleanupIntervalSeconds?: number;\n}\n\n/** Per-write options. */\nexport interface SetOptions {\n  /**\n   * Time to live in seconds; fractions are allowed (`0.5` = 500 ms, minimum\n   * 1 ms). Absent => the entry does not expire by time.\n   */\n  ttlSeconds?: number;\n}\n\n/** Accumulated cache statistics (plus the current size). */\nexport interface CacheStats {\n  /** Reads that found a valid entry. */\n  hits: number;\n  /** Reads without a valid key (missing or expired). */\n  misses: number;\n  /** Total writes (`set`). */\n  sets: number;\n  /** Total explicit removals (`delete`). */\n  deletes: number;\n  /** Total entries removed by expiration. */\n  expired: number;\n  /** Total entries removed by eviction (LRU policy when `maxSize` is reached). */\n  evicted: number;\n  /** Number of keys stored right now. */\n  size: number;\n}\n\n/**\n * In-memory cache whose entries live in Rust memory, outside the V8 heap.\n * Exact LRU eviction (O(1)), an optional TTL per entry and an optional\n * background sweeper.\n *\n * @example\n * ```ts\n * import { Cache } from \"rust-node-cache\";\n *\n * const cache = new Cache();\n * cache.set(\"user:1\", { id: 1, name: \"Roberto\" });\n * cache.get<{ id: number; name: string }>(\"user:1\"); // { id: 1, name: \"Roberto\" }\n * ```\n */\nexport class Cache {\n  /** Instance of the native (Rust) class. */\n  private readonly native: native.Cache;\n\n  /** @throws if `maxSize`, `evictionPolicy` or `cleanupIntervalSeconds` is invalid. */\n  constructor(options: CacheOptions = {}) {\n    // An options object is passed to Rust only when it carries something.\n    const hasOptions =\n      options.maxSize !== undefined ||\n      options.evictionPolicy !== undefined ||\n      options.cleanupIntervalSeconds !== undefined;\n    this.native = hasOptions\n      ? new native.Cache({\n          maxSize: options.maxSize,\n          evictionPolicy: options.evictionPolicy,\n          cleanupIntervalSeconds: options.cleanupIntervalSeconds,\n        })\n      : new native.Cache();\n  }\n\n  /** The active eviction policy: `\"reject\"` or `\"lru\"`. */\n  get evictionPolicy(): EvictionPolicy {\n    return this.native.evictionPolicy as EvictionPolicy;\n  }\n\n  /**\n   * Stores (or overwrites) a value, kept as JSON. Accepts plain objects,\n   * arrays, strings, finite numbers, booleans and `null`; object properties\n   * set to `undefined` are left out, as in JSON.\n   *\n   * @returns `true` on success; `false` if `maxSize` was reached and the key is new.\n   * @throws TypeError naming the offending path if the value holds something\n   *   JSON cannot represent (a `Date`, `Map`, `Set`, `BigInt`, class instance,\n   *   function, `NaN`, `Infinity`, an `undefined` array item, or `undefined`\n   *   itself) — instead of storing a silently different value.\n   */\n  set<T>(key: string, value: T, options?: SetOptions): boolean {\n    return this.native.set(key, encode(value), options);\n  }\n\n  /**\n   * Reads a value. Applies lazy expiration: expired keys count as a miss.\n   * Each call returns a new copy, so mutating it does not change the cache.\n   *\n   * @returns the stored value, or `null` if missing or expired.\n   */\n  get<T = unknown>(key: string): T | null {\n    const json = this.native.get(key);\n    return json === null ? null : (JSON.parse(json) as T);\n  }\n\n  /**\n   * Stores text that is **already JSON**, as is — no validation, no\n   * re-encoding. Meant for payloads serialized elsewhere, such as an HTTP\n   * response body. Storing text that is not valid JSON makes `get()` throw.\n   *\n   * @returns `true` on success; `false` if `maxSize` was reached and the key is new.\n   */\n  setJson(key: string, json: string, options?: SetOptions): boolean {\n    return this.native.set(key, json, options);\n  }\n\n  /**\n   * Reads a value as its JSON text, without parsing it — e.g. to send it as\n   * an HTTP response body directly. Same expiration and stats as `get()`.\n   *\n   * @returns the JSON text, or `null` if missing or expired.\n   */\n  getJson(key: string): string | null {\n    return this.native.get(key);\n  }\n\n  /** Removes a key. Returns `true` if it existed. */\n  delete(key: string): boolean {\n    return this.native.delete(key);\n  }\n\n  /**\n   * Whether the key exists and is still valid (not expired). Does not count\n   * as a use for LRU eviction.\n   */\n  exists(key: string): boolean {\n    return this.native.exists(key);\n  }\n\n  /** Empties the cache (does not reset the historical `stats` counters). */\n  clear(): void {\n    this.native.clear();\n  }\n\n  /** Number of keys currently stored. */\n  size(): number {\n    return this.native.size();\n  }\n\n  /**\n   * Sweeps and removes every expired entry at once.\n   *\n   * @returns how many entries were removed.\n   */\n  cleanupExpired(): number {\n    return this.native.cleanupExpired();\n  }\n\n  /** Returns the accumulated statistics + the current size. */\n  stats(): CacheStats {\n    return this.native.stats();\n  }\n}\n","/**\n * Value encoding for the cache: validate, then `JSON.stringify`.\n *\n * Values are kept as JSON text in Rust memory. JSON cannot represent a `Date`,\n * `Map`, `Set`, `BigInt`, class instance, `NaN`/`Infinity` or an `undefined`\n * array slot — `JSON.stringify` would silently turn them into `{}`, a string or\n * `null`, and `get()` would return something else than what was stored. So\n * those are rejected with a `TypeError` naming where they are, instead.\n */\n\n/** Nesting deeper than this is reported instead of overflowing the stack. */\nconst MAX_DEPTH = 1000;\n\nconst HINTS: Record<string, string> = {\n  Date: \" Store date.toISOString() or date.getTime() instead.\",\n  Map: \" Store Object.fromEntries(map) instead.\",\n  Set: \" Store [...set] instead.\",\n  BigInt: \" Store String(n) instead.\",\n};\n\nconst IDENTIFIER = /^[A-Za-z_$][\\w$]*$/;\n\n/** Validates `value` and returns its JSON text. Throws `TypeError` otherwise. */\nexport function encode(value: unknown): string {\n  const problem = check(value, 0);\n  if (problem !== undefined) throw toError(problem);\n  return JSON.stringify(value);\n}\n\n/** Why a value was rejected. `path` is filled in while unwinding, root first. */\ninterface Problem {\n  path: (string | number)[];\n  what: string;\n  hint: string;\n}\n\n/**\n * Returns `undefined` when `value` round-trips through JSON unchanged, or the\n * first problem found. The path is only built on failure, so the common case\n * stays a bare walk.\n */\nfunction check(value: unknown, depth: number): Problem | undefined {\n  switch (typeof value) {\n    case \"string\":\n    case \"boolean\":\n      return undefined;\n    case \"number\":\n      return Number.isFinite(value) ? undefined : problem(String(value));\n    case \"object\": {\n      if (value === null) return undefined;\n      if (depth >= MAX_DEPTH) return tooDeep(value);\n      if (Array.isArray(value)) {\n        for (let i = 0; i < value.length; i++) {\n          const item = value[i];\n          const p = item === undefined ? problem(\"undefined\") : check(item, depth + 1);\n          if (p !== undefined) {\n            p.path.unshift(i);\n            return p;\n          }\n        }\n        return undefined;\n      }\n      const proto = Object.getPrototypeOf(value);\n      if (proto !== Object.prototype && proto !== null) {\n        const name = (value as object).constructor?.name;\n        return problem(\n          name ? `a ${name}` : \"an object with a custom prototype\",\n          (name && HINTS[name]) || \"\",\n        );\n      }\n      for (const key in value) {\n        const item = (value as Record<string, unknown>)[key];\n        // JSON omits undefined properties, and reading one back yields undefined\n        // anyway, so they are accepted.\n        if (item === undefined) continue;\n        const p = check(item, depth + 1);\n        if (p !== undefined) {\n          p.path.unshift(key);\n          return p;\n        }\n      }\n      return undefined;\n    }\n    case \"bigint\":\n      return problem(\"a BigInt\", HINTS.BigInt);\n    case \"undefined\":\n      return problem(\"undefined\");\n    default:\n      // function, symbol\n      return problem(`a ${typeof value}`);\n  }\n}\n\nfunction problem(what: string, hint = \"\"): Problem {\n  return { path: [], what, hint };\n}\n\nfunction toError({ path, what, hint }: Problem): TypeError {\n  let where = \"value\";\n  for (const part of path) {\n    if (typeof part === \"number\") where += `[${part}]`;\n    else if (IDENTIFIER.test(part)) where += `.${part}`;\n    else where += `[${JSON.stringify(part)}]`;\n  }\n  return new TypeError(\n    `rust-node-cache: cannot store ${where} (${what}). Values are kept as JSON, so only ` +\n      `plain objects, arrays, strings, finite numbers, booleans and null are accepted.${hint}`,\n  );\n}\n\nfunction tooDeep(value: unknown): never {\n  // A cycle also ends up here; let JSON.stringify name it if that is the case.\n  JSON.stringify(value);\n  throw new TypeError(`rust-node-cache: cannot store a value nested more than ${MAX_DEPTH} levels deep.`);\n}\n"],"mappings":"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","names":["problem","Cache"]}

package/dist/nestjs.d.mts

@@ -3,36 +3,36 @@ import { Observable } from 'rxjs';
 import { Cache } from './index.mjs';
 
 /**
- * Integração com NestJS: interceptor de cache de respostas.
+ * NestJS integration: a response caching interceptor.
  *
- * Uso:
+ * Usage:
  *   import { Cache } from "rust-node-cache";
  *   import { CacheInterceptor } from "rust-node-cache/nestjs";
  *
  *   const cache = new Cache();
  *   app.useGlobalInterceptors(new CacheInterceptor({ cache, ttlSeconds: 60 }));
  *
- * Usamos `import type` para `@nestjs/common`, ou seja, NÃO há import em runtime
- * do Nest aqui — o pacote não força o Nest como dependência. A única dependência
- * de runtime são os operadores `of`/`tap` do RxJS (presentes em qualquer app Nest).
+ * `@nestjs/common` is imported with `import type`, so there is NO runtime import
+ * of Nest here — the package does not force Nest as a dependency. The only runtime
+ * dependencies are RxJS's `of`/`tap` operators (present in any Nest app).
  */
 
 interface CacheInterceptorOptions {
-    /** 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: {
         method: string;
         url: string;
     }) => string;
 }
 /**
- * Interceptor NestJS que cacheia o valor retornado pelos handlers. Num HIT,
- * devolve o valor do cache sem executar o handler.
+ * NestJS interceptor that caches the value returned by handlers. On a HIT, it
+ * returns the cached value without running the handler.
  */
 declare class CacheInterceptor implements NestInterceptor {
     private readonly cache;

package/dist/nestjs.d.ts

@@ -3,36 +3,36 @@ import { Observable } from 'rxjs';
 import { Cache } from './index.js';
 
 /**
- * Integração com NestJS: interceptor de cache de respostas.
+ * NestJS integration: a response caching interceptor.
  *
- * Uso:
+ * Usage:
  *   import { Cache } from "rust-node-cache";
  *   import { CacheInterceptor } from "rust-node-cache/nestjs";
  *
  *   const cache = new Cache();
  *   app.useGlobalInterceptors(new CacheInterceptor({ cache, ttlSeconds: 60 }));
  *
- * Usamos `import type` para `@nestjs/common`, ou seja, NÃO há import em runtime
- * do Nest aqui — o pacote não força o Nest como dependência. A única dependência
- * de runtime são os operadores `of`/`tap` do RxJS (presentes em qualquer app Nest).
+ * `@nestjs/common` is imported with `import type`, so there is NO runtime import
+ * of Nest here — the package does not force Nest as a dependency. The only runtime
+ * dependencies are RxJS's `of`/`tap` operators (present in any Nest app).
  */
 
 interface CacheInterceptorOptions {
-    /** 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: {
         method: string;
         url: string;
     }) => string;
 }
 /**
- * Interceptor NestJS que cacheia o valor retornado pelos handlers. Num HIT,
- * devolve o valor do cache sem executar o handler.
+ * NestJS interceptor that caches the value returned by handlers. On a HIT, it
+ * returns the cached value without running the handler.
  */
 declare class CacheInterceptor implements NestInterceptor {
     private readonly cache;

package/dist/nestjs.js

@@ -43,10 +43,11 @@ var CacheInterceptor = class {
     }
     return next.handle().pipe(
       (0, import_rxjs.tap)((body) => {
-        if (body !== void 0 && body !== null) {
-          this.cache.set(
+        const json = toJson(body);
+        if (json !== void 0 && json !== "null") {
+          this.cache.setJson(
             key,
-            body,
+            json,
             this.ttlSeconds ? { ttlSeconds: this.ttlSeconds } : void 0
           );
         }
@@ -54,6 +55,13 @@ var CacheInterceptor = class {
     );
   }
 };
+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 = {
   CacheInterceptor

package/dist/nestjs.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../js/nestjs.ts"],"sourcesContent":["/**\n * Integração com NestJS: interceptor de cache de respostas.\n *\n * Uso:\n *   import { Cache } from \"rust-node-cache\";\n *   import { CacheInterceptor } from \"rust-node-cache/nestjs\";\n *\n *   const cache = new Cache();\n *   app.useGlobalInterceptors(new CacheInterceptor({ cache, ttlSeconds: 60 }));\n *\n * Usamos `import type` para `@nestjs/common`, ou seja, NÃO há import em runtime\n * do Nest aqui — o pacote não força o Nest como dependência. A única dependência\n * de runtime são os operadores `of`/`tap` do RxJS (presentes em qualquer app Nest).\n */\n\nimport type {\n  CallHandler,\n  ExecutionContext,\n  NestInterceptor,\n} from \"@nestjs/common\";\nimport type { Observable } from \"rxjs\";\nimport { of, tap } from \"rxjs\";\nimport type { Cache } from \"./index\";\n\nexport interface CacheInterceptorOptions {\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: { method: string; url: string }) => string;\n}\n\n/**\n * Interceptor NestJS que cacheia o valor retornado pelos handlers. Num HIT,\n * devolve o valor do cache sem executar o handler.\n */\nexport class CacheInterceptor implements NestInterceptor {\n  private readonly cache: Cache;\n  private readonly ttlSeconds?: number;\n  private readonly methods: string[];\n  private readonly keyGenerator: (req: {\n    method: string;\n    url: string;\n  }) => string;\n\n  constructor(options: CacheInterceptorOptions) {\n    this.cache = options.cache;\n    this.ttlSeconds = options.ttlSeconds;\n    this.methods = options.methods ?? [\"GET\"];\n    this.keyGenerator =\n      options.keyGenerator ?? ((req) => `${req.method}:${req.url}`);\n  }\n\n  intercept(\n    context: ExecutionContext,\n    next: CallHandler,\n  ): Observable<unknown> {\n    const req = context.switchToHttp().getRequest<{\n      method: string;\n      url: string;\n    }>();\n\n    if (!this.methods.includes(req.method)) {\n      return next.handle();\n    }\n\n    const key = this.keyGenerator(req);\n    const cached = this.cache.get(key);\n    if (cached !== null) {\n      return of(cached);\n    }\n\n    return next.handle().pipe(\n      tap((body) => {\n        if (body !== undefined && body !== null) {\n          this.cache.set(\n            key,\n            body,\n            this.ttlSeconds ? { ttlSeconds: this.ttlSeconds } : undefined,\n          );\n        }\n      }),\n    );\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAqBA,kBAAwB;AAkBjB,IAAM,mBAAN,MAAkD;AAAA,EASvD,YAAY,SAAkC;AAC5C,SAAK,QAAQ,QAAQ;AACrB,SAAK,aAAa,QAAQ;AAC1B,SAAK,UAAU,QAAQ,WAAW,CAAC,KAAK;AACxC,SAAK,eACH,QAAQ,iBAAiB,CAAC,QAAQ,GAAG,IAAI,MAAM,IAAI,IAAI,GAAG;AAAA,EAC9D;AAAA,EAEA,UACE,SACA,MACqB;AACrB,UAAM,MAAM,QAAQ,aAAa,EAAE,WAGhC;AAEH,QAAI,CAAC,KAAK,QAAQ,SAAS,IAAI,MAAM,GAAG;AACtC,aAAO,KAAK,OAAO;AAAA,IACrB;AAEA,UAAM,MAAM,KAAK,aAAa,GAAG;AACjC,UAAM,SAAS,KAAK,MAAM,IAAI,GAAG;AACjC,QAAI,WAAW,MAAM;AACnB,iBAAO,gBAAG,MAAM;AAAA,IAClB;AAEA,WAAO,KAAK,OAAO,EAAE;AAAA,UACnB,iBAAI,CAAC,SAAS;AACZ,YAAI,SAAS,UAAa,SAAS,MAAM;AACvC,eAAK,MAAM;AAAA,YACT;AAAA,YACA;AAAA,YACA,KAAK,aAAa,EAAE,YAAY,KAAK,WAAW,IAAI;AAAA,UACtD;AAAA,QACF;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../js/nestjs.ts"],"sourcesContent":["/**\n * NestJS integration: a response caching interceptor.\n *\n * Usage:\n *   import { Cache } from \"rust-node-cache\";\n *   import { CacheInterceptor } from \"rust-node-cache/nestjs\";\n *\n *   const cache = new Cache();\n *   app.useGlobalInterceptors(new CacheInterceptor({ cache, ttlSeconds: 60 }));\n *\n * `@nestjs/common` is imported with `import type`, so there is NO runtime import\n * of Nest here — the package does not force Nest as a dependency. The only runtime\n * dependencies are RxJS's `of`/`tap` operators (present in any Nest app).\n */\n\nimport type {\n  CallHandler,\n  ExecutionContext,\n  NestInterceptor,\n} from \"@nestjs/common\";\nimport type { Observable } from \"rxjs\";\nimport { of, tap } from \"rxjs\";\nimport type { Cache } from \"./index\";\n\nexport interface CacheInterceptorOptions {\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: { method: string; url: string }) => string;\n}\n\n/**\n * NestJS interceptor that caches the value returned by handlers. On a HIT, it\n * returns the cached value without running the handler.\n */\nexport class CacheInterceptor implements NestInterceptor {\n  private readonly cache: Cache;\n  private readonly ttlSeconds?: number;\n  private readonly methods: string[];\n  private readonly keyGenerator: (req: {\n    method: string;\n    url: string;\n  }) => string;\n\n  constructor(options: CacheInterceptorOptions) {\n    this.cache = options.cache;\n    this.ttlSeconds = options.ttlSeconds;\n    this.methods = options.methods ?? [\"GET\"];\n    this.keyGenerator =\n      options.keyGenerator ?? ((req) => `${req.method}:${req.url}`);\n  }\n\n  intercept(\n    context: ExecutionContext,\n    next: CallHandler,\n  ): Observable<unknown> {\n    const req = context.switchToHttp().getRequest<{\n      method: string;\n      url: string;\n    }>();\n\n    if (!this.methods.includes(req.method)) {\n      return next.handle();\n    }\n\n    const key = this.keyGenerator(req);\n    const cached = this.cache.get(key);\n    if (cached !== null) {\n      return of(cached);\n    }\n\n    return next.handle().pipe(\n      tap((body) => {\n        // Store the body as Nest will send it (JSON), so a HIT returns the\n        // same data as the MISS did (a `Date` becomes its ISO string).\n        const json = toJson(body);\n        if (json !== undefined && json !== \"null\") {\n          this.cache.setJson(\n            key,\n            json,\n            this.ttlSeconds ? { ttlSeconds: this.ttlSeconds } : undefined,\n          );\n        }\n      }),\n    );\n  }\n}\n\n/** The body as JSON text, 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: left for Nest to report.\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAqBA,kBAAwB;AAkBjB,IAAM,mBAAN,MAAkD;AAAA,EASvD,YAAY,SAAkC;AAC5C,SAAK,QAAQ,QAAQ;AACrB,SAAK,aAAa,QAAQ;AAC1B,SAAK,UAAU,QAAQ,WAAW,CAAC,KAAK;AACxC,SAAK,eACH,QAAQ,iBAAiB,CAAC,QAAQ,GAAG,IAAI,MAAM,IAAI,IAAI,GAAG;AAAA,EAC9D;AAAA,EAEA,UACE,SACA,MACqB;AACrB,UAAM,MAAM,QAAQ,aAAa,EAAE,WAGhC;AAEH,QAAI,CAAC,KAAK,QAAQ,SAAS,IAAI,MAAM,GAAG;AACtC,aAAO,KAAK,OAAO;AAAA,IACrB;AAEA,UAAM,MAAM,KAAK,aAAa,GAAG;AACjC,UAAM,SAAS,KAAK,MAAM,IAAI,GAAG;AACjC,QAAI,WAAW,MAAM;AACnB,iBAAO,gBAAG,MAAM;AAAA,IAClB;AAEA,WAAO,KAAK,OAAO,EAAE;AAAA,UACnB,iBAAI,CAAC,SAAS;AAGZ,cAAM,OAAO,OAAO,IAAI;AACxB,YAAI,SAAS,UAAa,SAAS,QAAQ;AACzC,eAAK,MAAM;AAAA,YACT;AAAA,YACA;AAAA,YACA,KAAK,aAAa,EAAE,YAAY,KAAK,WAAW,IAAI;AAAA,UACtD;AAAA,QACF;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AACF;AAGA,SAAS,OAAO,MAAmC;AACjD,MAAI;AACF,WAAO,KAAK,UAAU,IAAI;AAAA,EAC5B,QAAQ;AACN,WAAO;AAAA,EACT;AACF;","names":[]}