rust-node-cache 0.2.1 → 0.3.0

package/dist/index.d.mts

@@ -1,24 +1,22 @@
 /**
  * rust-node-cache — public API (TypeScript).
  *
- * "Ultra-fast in-memory cache powered by Rust."
+ * "In-memory cache for Node.js that keeps your data off the V8 heap."
  *
- * 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.
- *
- * The cost is one extra function call per operation — negligible next to the
- * real work (serialization + DashMap access) done in Rust.
+ * This layer is a typed wrapper over the native `Cache` class generated by
+ * Rust/napi-rs. It does the JSON encoding on the JavaScript side, where V8's
+ * `JSON.stringify`/`JSON.parse` are fastest, and hands Rust plain strings:
+ *  - `set` validates the value (see `./encode`) and stores its JSON text;
+ *  - `get` parses the stored text back, so every read returns a fresh copy;
+ *  - it allows ergonomic **generics**: `cache.get<User>("user:1")`.
  */
 /** Eviction strategy when `maxSize` is reached. */
 type EvictionPolicy = "reject" | "lru";
 /** Cache constructor options. */
 interface CacheOptions {
     /**
-     * Maximum number of keys. What happens when it is reached depends on
-     * `evictionPolicy`. No value => unlimited cache.
+     * Maximum number of keys (a positive integer). What happens when it is
+     * reached depends on `evictionPolicy`. No value => unlimited cache.
      */
     maxSize?: number;
     /**
@@ -30,12 +28,16 @@ interface CacheOptions {
     /**
      * When set (> 0), starts a thread that sweeps expired entries every N
      * seconds (background expiration, on top of the lazy one on access).
+     * Fractions are allowed; `0` or no value leaves it off.
      */
     cleanupIntervalSeconds?: number;
 }
 /** Per-write options. */
 interface SetOptions {
-    /** Time to live in seconds. Absent => the entry does not expire by time. */
+    /**
+     * Time to live in seconds; fractions are allowed (`0.5` = 500 ms, minimum
+     * 1 ms). Absent => the entry does not expire by time.
+     */
     ttlSeconds?: number;
 }
 /** Accumulated cache statistics (plus the current size). */
@@ -56,8 +58,9 @@ interface CacheStats {
     size: number;
 }
 /**
- * In-memory cache with a Rust core (DashMap + atomic counters). Thread-safe,
- * with an optional TTL per entry.
+ * In-memory cache whose entries live in Rust memory, outside the V8 heap.
+ * Exact LRU eviction (O(1)), an optional TTL per entry and an optional
+ * background sweeper.
  *
  * @example
  * ```ts
@@ -71,24 +74,50 @@ interface CacheStats {
 declare class Cache {
     /** Instance of the native (Rust) class. */
     private readonly native;
+    /** @throws if `maxSize`, `evictionPolicy` or `cleanupIntervalSeconds` is invalid. */
     constructor(options?: CacheOptions);
     /** The active eviction policy: `"reject"` or `"lru"`. */
     get evictionPolicy(): EvictionPolicy;
     /**
-     * Stores (or overwrites) a value. The value is serialized as JSON in the 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` on success; `false` if `maxSize` was reached and the key is new.
+     * @throws TypeError naming the offending path if the value holds something
+     *   JSON cannot represent (a `Date`, `Map`, `Set`, `BigInt`, class instance,
+     *   function, `NaN`, `Infinity`, an `undefined` array item, or `undefined`
+     *   itself) — instead of storing a silently different value.
      */
     set<T>(key: string, value: T, options?: SetOptions): boolean;
     /**
      * 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 the deserialized value, or `null` if missing or expired.
+     * @returns the stored value, or `null` if missing or expired.
      */
     get<T = unknown>(key: string): T | null;
+    /**
+     * Stores text that is **already JSON**, as is — no validation, no
+     * re-encoding. Meant for payloads serialized elsewhere, such as an HTTP
+     * response body. Storing text that is not valid JSON makes `get()` throw.
+     *
+     * @returns `true` on success; `false` if `maxSize` was reached and the key is new.
+     */
+    setJson(key: string, json: string, options?: SetOptions): boolean;
+    /**
+     * Reads a value as its JSON text, without parsing it — e.g. to send it as
+     * an HTTP response body directly. Same expiration and stats as `get()`.
+     *
+     * @returns the JSON text, or `null` if missing or expired.
+     */
+    getJson(key: string): string | null;
     /** Removes a key. Returns `true` if it existed. */
     delete(key: string): boolean;
-    /** Whether the key exists and is still valid (not expired). */
+    /**
+     * Whether the key exists and is still valid (not expired). Does not count
+     * as a use for LRU eviction.
+     */
     exists(key: string): boolean;
     /** Empties the cache (does not reset the historical `stats` counters). */
     clear(): void;

package/dist/index.d.ts

@@ -1,24 +1,22 @@
 /**
  * rust-node-cache — public API (TypeScript).
  *
- * "Ultra-fast in-memory cache powered by Rust."
+ * "In-memory cache for Node.js that keeps your data off the V8 heap."
  *
- * 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.
- *
- * The cost is one extra function call per operation — negligible next to the
- * real work (serialization + DashMap access) done in Rust.
+ * This layer is a typed wrapper over the native `Cache` class generated by
+ * Rust/napi-rs. It does the JSON encoding on the JavaScript side, where V8's
+ * `JSON.stringify`/`JSON.parse` are fastest, and hands Rust plain strings:
+ *  - `set` validates the value (see `./encode`) and stores its JSON text;
+ *  - `get` parses the stored text back, so every read returns a fresh copy;
+ *  - it allows ergonomic **generics**: `cache.get<User>("user:1")`.
  */
 /** Eviction strategy when `maxSize` is reached. */
 type EvictionPolicy = "reject" | "lru";
 /** Cache constructor options. */
 interface CacheOptions {
     /**
-     * Maximum number of keys. What happens when it is reached depends on
-     * `evictionPolicy`. No value => unlimited cache.
+     * Maximum number of keys (a positive integer). What happens when it is
+     * reached depends on `evictionPolicy`. No value => unlimited cache.
      */
     maxSize?: number;
     /**
@@ -30,12 +28,16 @@ interface CacheOptions {
     /**
      * When set (> 0), starts a thread that sweeps expired entries every N
      * seconds (background expiration, on top of the lazy one on access).
+     * Fractions are allowed; `0` or no value leaves it off.
      */
     cleanupIntervalSeconds?: number;
 }
 /** Per-write options. */
 interface SetOptions {
-    /** Time to live in seconds. Absent => the entry does not expire by time. */
+    /**
+     * Time to live in seconds; fractions are allowed (`0.5` = 500 ms, minimum
+     * 1 ms). Absent => the entry does not expire by time.
+     */
     ttlSeconds?: number;
 }
 /** Accumulated cache statistics (plus the current size). */
@@ -56,8 +58,9 @@ interface CacheStats {
     size: number;
 }
 /**
- * In-memory cache with a Rust core (DashMap + atomic counters). Thread-safe,
- * with an optional TTL per entry.
+ * In-memory cache whose entries live in Rust memory, outside the V8 heap.
+ * Exact LRU eviction (O(1)), an optional TTL per entry and an optional
+ * background sweeper.
  *
  * @example
  * ```ts
@@ -71,24 +74,50 @@ interface CacheStats {
 declare class Cache {
     /** Instance of the native (Rust) class. */
     private readonly native;
+    /** @throws if `maxSize`, `evictionPolicy` or `cleanupIntervalSeconds` is invalid. */
     constructor(options?: CacheOptions);
     /** The active eviction policy: `"reject"` or `"lru"`. */
     get evictionPolicy(): EvictionPolicy;
     /**
-     * Stores (or overwrites) a value. The value is serialized as JSON in the 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` on success; `false` if `maxSize` was reached and the key is new.
+     * @throws TypeError naming the offending path if the value holds something
+     *   JSON cannot represent (a `Date`, `Map`, `Set`, `BigInt`, class instance,
+     *   function, `NaN`, `Infinity`, an `undefined` array item, or `undefined`
+     *   itself) — instead of storing a silently different value.
      */
     set<T>(key: string, value: T, options?: SetOptions): boolean;
     /**
      * 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 the deserialized value, or `null` if missing or expired.
+     * @returns the stored value, or `null` if missing or expired.
      */
     get<T = unknown>(key: string): T | null;
+    /**
+     * Stores text that is **already JSON**, as is — no validation, no
+     * re-encoding. Meant for payloads serialized elsewhere, such as an HTTP
+     * response body. Storing text that is not valid JSON makes `get()` throw.
+     *
+     * @returns `true` on success; `false` if `maxSize` was reached and the key is new.
+     */
+    setJson(key: string, json: string, options?: SetOptions): boolean;
+    /**
+     * Reads a value as its JSON text, without parsing it — e.g. to send it as
+     * an HTTP response body directly. Same expiration and stats as `get()`.
+     *
+     * @returns the JSON text, or `null` if missing or expired.
+     */
+    getJson(key: string): string | null;
     /** Removes a key. Returns `true` if it existed. */
     delete(key: string): boolean;
-    /** Whether the key exists and is still valid (not expired). */
+    /**
+     * Whether the key exists and is still valid (not expired). Does not count
+     * as a use for LRU eviction.
+     */
     exists(key: string): boolean;
     /** Empties the cache (does not reset the historical `stats` counters). */
     clear(): void;

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({
@@ -48,27 +132,56 @@ var Cache2 = class {
     return this.native.evictionPolicy;
   }
   /**
-   * Stores (or overwrites) a value. The value is serialized as JSON in the 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` 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);
   }
   /**
    * 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 the deserialized value, or `null` if missing or expired.
+   * @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);
   }
   /** Removes a key. Returns `true` if it existed. */
   delete(key) {
     return this.native.delete(key);
   }
-  /** Whether the key exists and is still valid (not expired). */
+  /**
+   * 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);
   }

package/dist/index.js.map

@@ -1 +1 @@
-{"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"]}
+{"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({
@@ -14,27 +98,56 @@ var Cache2 = class {
     return this.native.evictionPolicy;
   }
   /**
-   * Stores (or overwrites) a value. The value is serialized as JSON in the 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` 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);
   }
   /**
    * 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 the deserialized value, or `null` if missing or expired.
+   * @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);
   }
   /** Removes a key. Returns `true` if it existed. */
   delete(key) {
     return this.native.delete(key);
   }
-  /** Whether the key exists and is still valid (not expired). */
+  /**
+   * 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);
   }

package/dist/index.mjs.map

@@ -1 +1 @@
-{"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"]}
+{"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"]}