rust-node-cache 0.1.1 → 0.2.1

package/dist/index.d.mts

@@ -1,49 +1,63 @@
 /**
- * rust-node-cache — API pública (TypeScript).
+ * rust-node-cache — public API (TypeScript).
  *
  * "Ultra-fast in-memory cache powered by Rust."
  *
- * 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.
+ * This layer is a thin, typed wrapper over the native `Cache` class generated
+ * by Rust/napi-rs. Why wrap it instead of re-exporting it directly?
+ *  - it allows ergonomic **generics**: `cache.get<User>("user:1")`;
+ *  - it normalizes `undefined`/`null` so a miss always returns `null`;
+ *  - it gives one place for the JSDoc and for evolving the API without breaking the Rust core.
  *
- * 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.
+ * The cost is one extra function call per operation — negligible next to the
+ * real work (serialization + DashMap access) done in Rust.
  */
-/** Opções do construtor do cache. */
+/** Eviction strategy when `maxSize` is reached. */
+type EvictionPolicy = "reject" | "lru";
+/** Cache constructor options. */
 interface CacheOptions {
     /**
-     * Limite máximo de chaves. Ao ser atingido, `set` de uma chave **nova**
-     * retorna `false` (sobrescrever chave existente continua permitido).
-     * Sem valor => cache ilimitado.
+     * Maximum number of keys. What happens when it is reached depends on
+     * `evictionPolicy`. No value => unlimited cache.
      */
     maxSize?: number;
+    /**
+     * 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;
+    /**
+     * When set (> 0), starts a thread that sweeps expired entries every N
+     * seconds (background expiration, on top of the lazy one on access).
+     */
+    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. 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;
-    /** Número de chaves armazenadas agora. */
+    /** Total entries removed by eviction (LRU policy when `maxSize` is reached). */
+    evicted: number;
+    /** 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 with a Rust core (DashMap + atomic counters). Thread-safe,
+ * with an optional TTL per entry.
  *
  * @example
  * ```ts
@@ -55,37 +69,39 @@ interface CacheStats {
  * ```
  */
 declare class Cache {
-    /** Instância da classe nativa (Rust). */
+    /** Instance of the native (Rust) class. */
     private readonly native;
     constructor(options?: CacheOptions);
+    /** 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. The value is serialized as JSON in the core.
      *
-     * @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.
      */
     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.
      *
-     * @returns o valor desserializado, ou `null` se ausente/expirado.
+     * @returns the deserialized value, or `null` if missing or expired.
      */
     get<T = unknown>(key: string): T | null;
-    /** Remove uma chave. Retorna `true` se ela existia. */
+    /** 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). */
     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;
 }
 
-export { Cache, type CacheOptions, type CacheStats, type SetOptions };
+export { Cache, type CacheOptions, type CacheStats, type EvictionPolicy, type SetOptions };

package/dist/index.d.ts

@@ -1,49 +1,63 @@
 /**
- * rust-node-cache — API pública (TypeScript).
+ * rust-node-cache — public API (TypeScript).
  *
  * "Ultra-fast in-memory cache powered by Rust."
  *
- * 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.
+ * This layer is a thin, typed wrapper over the native `Cache` class generated
+ * by Rust/napi-rs. Why wrap it instead of re-exporting it directly?
+ *  - it allows ergonomic **generics**: `cache.get<User>("user:1")`;
+ *  - it normalizes `undefined`/`null` so a miss always returns `null`;
+ *  - it gives one place for the JSDoc and for evolving the API without breaking the Rust core.
  *
- * 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.
+ * The cost is one extra function call per operation — negligible next to the
+ * real work (serialization + DashMap access) done in Rust.
  */
-/** Opções do construtor do cache. */
+/** Eviction strategy when `maxSize` is reached. */
+type EvictionPolicy = "reject" | "lru";
+/** Cache constructor options. */
 interface CacheOptions {
     /**
-     * Limite máximo de chaves. Ao ser atingido, `set` de uma chave **nova**
-     * retorna `false` (sobrescrever chave existente continua permitido).
-     * Sem valor => cache ilimitado.
+     * Maximum number of keys. What happens when it is reached depends on
+     * `evictionPolicy`. No value => unlimited cache.
      */
     maxSize?: number;
+    /**
+     * 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;
+    /**
+     * When set (> 0), starts a thread that sweeps expired entries every N
+     * seconds (background expiration, on top of the lazy one on access).
+     */
+    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. 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;
-    /** Número de chaves armazenadas agora. */
+    /** Total entries removed by eviction (LRU policy when `maxSize` is reached). */
+    evicted: number;
+    /** 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 with a Rust core (DashMap + atomic counters). Thread-safe,
+ * with an optional TTL per entry.
  *
  * @example
  * ```ts
@@ -55,37 +69,39 @@ interface CacheStats {
  * ```
  */
 declare class Cache {
-    /** Instância da classe nativa (Rust). */
+    /** Instance of the native (Rust) class. */
     private readonly native;
     constructor(options?: CacheOptions);
+    /** 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. The value is serialized as JSON in the core.
      *
-     * @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.
      */
     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.
      *
-     * @returns o valor desserializado, ou `null` se ausente/expirado.
+     * @returns the deserialized value, or `null` if missing or expired.
      */
     get<T = unknown>(key: string): T | null;
-    /** Remove uma chave. Retorna `true` se ela existia. */
+    /** 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). */
     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;
 }
 
-export { Cache, type CacheOptions, type CacheStats, type SetOptions };
+export { Cache, type CacheOptions, type CacheStats, type EvictionPolicy, type SetOptions };

package/dist/index.js

@@ -36,50 +36,59 @@ module.exports = __toCommonJS(index_exports);
 var native = __toESM(require("../binding.js"));
 var Cache2 = class {
   constructor(options = {}) {
-    this.native = options.maxSize !== void 0 ? new native.Cache({ maxSize: options.maxSize }) : new native.Cache();
+    const hasOptions = options.maxSize !== void 0 || options.evictionPolicy !== void 0 || options.cleanupIntervalSeconds !== void 0;
+    this.native = hasOptions ? new native.Cache({
+      maxSize: options.maxSize,
+      evictionPolicy: options.evictionPolicy,
+      cleanupIntervalSeconds: options.cleanupIntervalSeconds
+    }) : new native.Cache();
+  }
+  /** 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. The value is serialized as JSON in the core.
    *
-   * @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.
    */
   set(key, value, options) {
     return this.native.set(key, 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.
    *
-   * @returns o valor desserializado, ou `null` se ausente/expirado.
+   * @returns the deserialized value, or `null` if missing or expired.
    */
   get(key) {
     const value = this.native.get(key);
     return value === null || value === void 0 ? null : value;
   }
-  /** 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). */
   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/** Opções do construtor do cache. */\nexport interface CacheOptions {\n  /**\n   * Limite máximo de chaves. Ao ser atingido, `set` de uma chave **nova**\n   * retorna `false` (sobrescrever chave existente continua permitido).\n   * Sem valor => cache ilimitado.\n   */\n  maxSize?: 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  /** 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 o objeto de opções ao Rust quando há algo relevante.\n    this.native =\n      options.maxSize !== undefined\n        ? new native.Cache({ maxSize: options.maxSize })\n        : new native.Cache();\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;AA+CjB,IAAMA,SAAN,MAAY;AAAA,EAIjB,YAAY,UAAwB,CAAC,GAAG;AAEtC,SAAK,SACH,QAAQ,YAAY,SAChB,IAAW,aAAM,EAAE,SAAS,QAAQ,QAAQ,CAAC,IAC7C,IAAW,aAAM;AAAA,EACzB;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"],"sourcesContent":["/**\n * rust-node-cache — public API (TypeScript).\n *\n * \"Ultra-fast in-memory cache powered by Rust.\"\n *\n * This layer is a thin, typed wrapper over the native `Cache` class generated\n * by Rust/napi-rs. Why wrap it instead of re-exporting it directly?\n *  - it allows ergonomic **generics**: `cache.get<User>(\"user:1\")`;\n *  - it normalizes `undefined`/`null` so a miss always returns `null`;\n *  - it gives one place for the JSDoc and for evolving the API without breaking the Rust core.\n *\n * The cost is one extra function call per operation — negligible next to the\n * real work (serialization + DashMap access) done in Rust.\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\";\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. What happens when it is reached depends on\n   * `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   */\n  cleanupIntervalSeconds?: number;\n}\n\n/** Per-write options. */\nexport interface SetOptions {\n  /** Time to live in seconds. Absent => the entry does not expire by time. */\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 with a Rust core (DashMap + atomic counters). Thread-safe,\n * with an optional TTL per entry.\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  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. The value is serialized as JSON in the core.\n   *\n   * @returns `true` on success; `false` if `maxSize` was reached and the key is new.\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   * Reads a value. Applies lazy expiration: expired keys count as a miss.\n   *\n   * @returns the deserialized value, or `null` if missing or expired.\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  /** Removes a key. Returns `true` if it existed. */\n  delete(key: string): boolean {\n    return this.native.delete(key);\n  }\n\n  /** Whether the key exists and is still valid (not expired). */\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"],"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"]}

package/dist/index.mjs

@@ -2,50 +2,59 @@
 import * as native from "../binding.js";
 var Cache2 = class {
   constructor(options = {}) {
-    this.native = options.maxSize !== void 0 ? new native.Cache({ maxSize: options.maxSize }) : new native.Cache();
+    const hasOptions = options.maxSize !== void 0 || options.evictionPolicy !== void 0 || options.cleanupIntervalSeconds !== void 0;
+    this.native = hasOptions ? new native.Cache({
+      maxSize: options.maxSize,
+      evictionPolicy: options.evictionPolicy,
+      cleanupIntervalSeconds: options.cleanupIntervalSeconds
+    }) : new native.Cache();
+  }
+  /** 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. The value is serialized as JSON in the core.
    *
-   * @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.
    */
   set(key, value, options) {
     return this.native.set(key, 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.
    *
-   * @returns o valor desserializado, ou `null` se ausente/expirado.
+   * @returns the deserialized value, or `null` if missing or expired.
    */
   get(key) {
     const value = this.native.get(key);
     return value === null || value === void 0 ? null : value;
   }
-  /** 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). */
   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/** Opções do construtor do cache. */\nexport interface CacheOptions {\n  /**\n   * Limite máximo de chaves. Ao ser atingido, `set` de uma chave **nova**\n   * retorna `false` (sobrescrever chave existente continua permitido).\n   * Sem valor => cache ilimitado.\n   */\n  maxSize?: 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  /** 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 o objeto de opções ao Rust quando há algo relevante.\n    this.native =\n      options.maxSize !== undefined\n        ? new native.Cache({ maxSize: options.maxSize })\n        : new native.Cache();\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;AA+CjB,IAAMA,SAAN,MAAY;AAAA,EAIjB,YAAY,UAAwB,CAAC,GAAG;AAEtC,SAAK,SACH,QAAQ,YAAY,SAChB,IAAW,aAAM,EAAE,SAAS,QAAQ,QAAQ,CAAC,IAC7C,IAAW,aAAM;AAAA,EACzB;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"],"sourcesContent":["/**\n * rust-node-cache — public API (TypeScript).\n *\n * \"Ultra-fast in-memory cache powered by Rust.\"\n *\n * This layer is a thin, typed wrapper over the native `Cache` class generated\n * by Rust/napi-rs. Why wrap it instead of re-exporting it directly?\n *  - it allows ergonomic **generics**: `cache.get<User>(\"user:1\")`;\n *  - it normalizes `undefined`/`null` so a miss always returns `null`;\n *  - it gives one place for the JSDoc and for evolving the API without breaking the Rust core.\n *\n * The cost is one extra function call per operation — negligible next to the\n * real work (serialization + DashMap access) done in Rust.\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\";\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. What happens when it is reached depends on\n   * `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   */\n  cleanupIntervalSeconds?: number;\n}\n\n/** Per-write options. */\nexport interface SetOptions {\n  /** Time to live in seconds. Absent => the entry does not expire by time. */\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 with a Rust core (DashMap + atomic counters). Thread-safe,\n * with an optional TTL per entry.\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  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. The value is serialized as JSON in the core.\n   *\n   * @returns `true` on success; `false` if `maxSize` was reached and the key is new.\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   * Reads a value. Applies lazy expiration: expired keys count as a miss.\n   *\n   * @returns the deserialized value, or `null` if missing or expired.\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  /** Removes a key. Returns `true` if it existed. */\n  delete(key: string): boolean {\n    return this.native.delete(key);\n  }\n\n  /** Whether the key exists and is still valid (not expired). */\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"],"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"]}

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;