rust-node-cache 0.1.0 → 0.2.0

package/README.md

@@ -15,6 +15,8 @@ is **no compiler required at install time** on supported platforms.
 ![node](https://img.shields.io/badge/node-%3E%3D18-43853d)
 ![license](https://img.shields.io/badge/license-MIT-blue)
 
+🌐 **Website:** [rust-node-cache.vercel.app](https://rust-node-cache.vercel.app/)
+
 ---
 
 ## Features
@@ -22,8 +24,10 @@ is **no compiler required at install time** on supported platforms.
 - 🦀 **Rust-powered** core for predictable, low-overhead performance
 - 🔒 **Thread-safe** via `DashMap` (lock-sharded concurrent map)
 - ⏱️ **TTL support** per entry (lazy expiration + active cleanup)
+- 🧹 **Background expiration** — optional sweeper thread (`cleanupIntervalSeconds`)
+- 🧠 **LRU eviction** — bound the cache by `maxSize` with `evictionPolicy: "lru"`
 - ⚡ **Fast reads** and **fast writes**
-- 📊 Built-in **statistics** (hits, misses, sets, deletes, expired, size)
+- 📊 Built-in **statistics** (hits, misses, sets, deletes, expired, evicted, size)
 - 🧩 **TypeScript** support with generics out of the box
 - 🌐 **Framework agnostic** — works with Express, Fastify, NestJS, Hono,
   Next.js, or plain Node.js
@@ -140,6 +144,35 @@ an active sweep:
 const removed = cache.cleanupExpired(); // number of entries removed
 ```
 
+Or let the cache sweep for you in the background — set `cleanupIntervalSeconds`
+and a thread reclaims expired entries on its own (no manual `cleanupExpired()`):
+
+```ts
+const cache = new Cache({ cleanupIntervalSeconds: 30 });
+```
+
+The thread is tied to the cache's lifetime: it stops automatically when the cache
+is garbage-collected.
+
+---
+
+## Eviction (maxSize)
+
+Cap the number of keys with `maxSize`. When the cache is full and a **new** key
+is written, `evictionPolicy` decides what happens:
+
+```ts
+// Default: reject the write (set returns false), keep existing entries.
+const a = new Cache({ maxSize: 1000 }); // evictionPolicy: "reject"
+
+// LRU: evict the least-recently-used entry to make room, then insert.
+const b = new Cache({ maxSize: 1000, evictionPolicy: "lru" });
+b.evictionPolicy; // "lru"
+```
+
+LRU recency is tracked per entry (updated on every `get` hit) and the evicted
+count is surfaced in `stats().evicted`. Overwriting an existing key never evicts.
+
 ---
 
 ## Statistics
@@ -157,6 +190,7 @@ Returns:
   sets: 800,
   deletes: 20,
   expired: 15,
+  evicted: 40,
   size: 780
 }
 ```
@@ -206,8 +240,9 @@ Bincode) later without touching the cache logic.
 
 | Method                         | Returns        | Description                                                       |
 | ------------------------------ | -------------- | ----------------------------------------------------------------- |
-| `new Cache(options?)`          | `Cache`        | Create a cache. `options.maxSize` caps the number of keys.        |
+| `new Cache(options?)`          | `Cache`        | Create a cache (`maxSize`, `evictionPolicy`, `cleanupIntervalSeconds`). |
 | `set(key, value, options?)`    | `boolean`      | Store/overwrite a value. `options.ttlSeconds` sets expiration.    |
+| `evictionPolicy` (getter)      | `string`       | The active policy: `"reject"` or `"lru"`.                         |
 | `get<T>(key)`                  | `T \| null`    | Read a value (lazy-expires stale entries).                        |
 | `delete(key)`                  | `boolean`      | Remove a key. `true` if it existed.                               |
 | `exists(key)`                  | `boolean`      | Whether the key exists and is valid.                              |
@@ -221,6 +256,8 @@ Bincode) later without touching the cache logic.
 ```ts
 interface CacheOptions {
   maxSize?: number;
+  evictionPolicy?: "reject" | "lru"; // default "reject"
+  cleanupIntervalSeconds?: number; // enables the background sweeper
 }
 
 interface SetOptions {
@@ -233,6 +270,7 @@ interface CacheStats {
   sets: number;
   deletes: number;
   expired: number;
+  evicted: number;
   size: number;
 }
 ```
@@ -321,15 +359,14 @@ Coming soon.
 
 ## Roadmap
 
-| Version | Feature                  |
-| ------- | ------------------------ |
-| v0.1    | Basic cache              |
-| v0.2    | TTL cleanup thread       |
-| v0.3    | LRU cache                |
-| v0.4    | LFU cache                |
-| v0.5    | Redis synchronization    |
-| v0.6    | Prometheus metrics       |
-| v0.7    | ImmutableLog integration |
+| Version | Feature                  | Status |
+| ------- | ------------------------ | ------ |
+| v0.1    | Basic cache              | ✅     |
+| v0.2    | TTL cleanup thread + LRU eviction | ✅ |
+| v0.3    | LFU cache                | 🔜     |
+| v0.4    | Redis synchronization    | 🔜     |
+| v0.5    | Prometheus metrics       | 🔜     |
+| v0.6    | ImmutableLog integration | 🔜     |
 
 ### Future: ImmutableLog Integration
 

package/binding.d.ts

@@ -3,10 +3,26 @@
 
 /* auto-generated by NAPI-RS */
 
-/** Opções do construtor: `new Cache({ maxSize })`. */
+/**
+ * Opções do construtor:
+ * `new Cache({ maxSize, evictionPolicy, cleanupIntervalSeconds })`.
+ */
 export interface CacheOptions {
-  /** Limite opcional de chaves. Ao atingir, `set` de chave nova retorna `false`. */
+  /**
+   * Limite opcional de chaves. Comportamento ao atingir depende de
+   * `evictionPolicy`.
+   */
   maxSize?: number
+  /**
+   * `"reject"` (padrão) — `set` de chave nova retorna `false` quando cheio;
+   * `"lru"` — remove a entrada menos recentemente usada e prossegue.
+   */
+  evictionPolicy?: string
+  /**
+   * Se definido (> 0), liga uma thread que varre entradas expiradas a cada
+   * N segundos (expiração em background, além da lazy).
+   */
+  cleanupIntervalSeconds?: number
 }
 /** Opções por escrita: `cache.set(key, value, { ttlSeconds })`. */
 export interface SetOptions {
@@ -20,6 +36,7 @@ export interface CacheStatsObject {
   sets: number
   deletes: number
   expired: number
+  evicted: number
   size: number
 }
 /**
@@ -30,8 +47,10 @@ export interface CacheStatsObject {
  * concorrente por dentro, várias chamadas podem rodar em paralelo.
  */
 export declare class Cache {
-  /** `new Cache()` ou `new Cache({ maxSize })`. */
+  /** `new Cache()` ou `new Cache({ maxSize, evictionPolicy, cleanupIntervalSeconds })`. */
   constructor(options?: CacheOptions | undefined | null)
+  /** A política de evicção ativa: `"reject"` ou `"lru"`. */
+  get evictionPolicy(): string
   /**
    * Insere/atualiza uma chave. Retorna `true` em sucesso, `false` se o cache
    * estiver cheio (`maxSize`) e a chave for nova.

package/dist/index.d.mts

@@ -12,14 +12,26 @@
  * 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.
  */
+/** Estratégia de evicção quando `maxSize` é atingido. */
+type EvictionPolicy = "reject" | "lru";
 /** Opções do construtor do cache. */
 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.
+     * Limite máximo de chaves. O que acontece ao atingir depende de
+     * `evictionPolicy`. Sem valor => cache ilimitado.
      */
     maxSize?: number;
+    /**
+     * Política ao atingir `maxSize` numa chave **nova**:
+     * - `"reject"` (padrão): `set` retorna `false` (sobrescrever continua ok);
+     * - `"lru"`: remove a entrada menos recentemente usada e prossegue.
+     */
+    evictionPolicy?: EvictionPolicy;
+    /**
+     * Se definido (> 0), liga uma thread que varre entradas expiradas a cada
+     * N segundos (expiração em background, além da preguiçosa por acesso).
+     */
+    cleanupIntervalSeconds?: number;
 }
 /** Opções por operação de escrita. */
 interface SetOptions {
@@ -38,6 +50,8 @@ interface CacheStats {
     deletes: number;
     /** Total de entradas removidas por expiração. */
     expired: number;
+    /** Total de entradas removidas por evicção (política LRU ao atingir `maxSize`). */
+    evicted: number;
     /** Número de chaves armazenadas agora. */
     size: number;
 }
@@ -58,6 +72,8 @@ declare class Cache {
     /** Instância da classe nativa (Rust). */
     private readonly native;
     constructor(options?: CacheOptions);
+    /** A política de evicção ativa: `"reject"` ou `"lru"`. */
+    get evictionPolicy(): EvictionPolicy;
     /**
      * Armazena (ou sobrescreve) um valor. O valor é serializado como JSON no core.
      *
@@ -88,4 +104,4 @@ declare class Cache {
     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

@@ -12,14 +12,26 @@
  * 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.
  */
+/** Estratégia de evicção quando `maxSize` é atingido. */
+type EvictionPolicy = "reject" | "lru";
 /** Opções do construtor do cache. */
 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.
+     * Limite máximo de chaves. O que acontece ao atingir depende de
+     * `evictionPolicy`. Sem valor => cache ilimitado.
      */
     maxSize?: number;
+    /**
+     * Política ao atingir `maxSize` numa chave **nova**:
+     * - `"reject"` (padrão): `set` retorna `false` (sobrescrever continua ok);
+     * - `"lru"`: remove a entrada menos recentemente usada e prossegue.
+     */
+    evictionPolicy?: EvictionPolicy;
+    /**
+     * Se definido (> 0), liga uma thread que varre entradas expiradas a cada
+     * N segundos (expiração em background, além da preguiçosa por acesso).
+     */
+    cleanupIntervalSeconds?: number;
 }
 /** Opções por operação de escrita. */
 interface SetOptions {
@@ -38,6 +50,8 @@ interface CacheStats {
     deletes: number;
     /** Total de entradas removidas por expiração. */
     expired: number;
+    /** Total de entradas removidas por evicção (política LRU ao atingir `maxSize`). */
+    evicted: number;
     /** Número de chaves armazenadas agora. */
     size: number;
 }
@@ -58,6 +72,8 @@ declare class Cache {
     /** Instância da classe nativa (Rust). */
     private readonly native;
     constructor(options?: CacheOptions);
+    /** A política de evicção ativa: `"reject"` ou `"lru"`. */
+    get evictionPolicy(): EvictionPolicy;
     /**
      * Armazena (ou sobrescreve) um valor. O valor é serializado como JSON no core.
      *
@@ -88,4 +104,4 @@ declare class Cache {
     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,7 +36,16 @@ 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();
+  }
+  /** A política de evicção ativa: `"reject"` ou `"lru"`. */
+  get evictionPolicy() {
+    return this.native.evictionPolicy;
   }
   /**
    * Armazena (ou sobrescreve) um valor. O valor é serializado como JSON no core.

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 — 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"]}

package/dist/index.mjs

@@ -2,7 +2,16 @@
 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();
+  }
+  /** A política de evicção ativa: `"reject"` ou `"lru"`. */
+  get evictionPolicy() {
+    return this.native.evictionPolicy;
   }
   /**
    * Armazena (ou sobrescreve) um valor. O valor é serializado como JSON no core.

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 — 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"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rust-node-cache",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Ultra-fast in-memory cache for Node.js powered by Rust.",
   "keywords": [
     "cache",
@@ -23,7 +23,7 @@
     "type": "git",
     "url": "https://github.com/robertolima-dev/rust-node-cache.git"
   },
-  "homepage": "https://github.com/robertolima-dev/rust-node-cache",
+  "homepage": "https://rust-node-cache.vercel.app",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",