ts-cache-mongoose 2.0.0 → 2.2.0

package/README.md

@@ -12,22 +12,28 @@ Cache query and aggregate in mongoose using in-memory or redis
 [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=ilovepixelart_ts-cache-mongoose&metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=ilovepixelart_ts-cache-mongoose)
 [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=ilovepixelart_ts-cache-mongoose&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=ilovepixelart_ts-cache-mongoose)
 [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=ilovepixelart_ts-cache-mongoose&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=ilovepixelart_ts-cache-mongoose)
+\
+[![Socket Badge](https://badge.socket.dev/npm/package/ts-cache-mongoose)](https://socket.dev/npm/package/ts-cache-mongoose)
+[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/ilovepixelart/ts-cache-mongoose/badge)](https://securityscorecards.dev/viewer/?uri=github.com/ilovepixelart/ts-cache-mongoose)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12484/badge?v=1)](https://www.bestpractices.dev/en/projects/12484)
 
 ## Motivation
 
 ts-cache-mongoose is a plugin for mongoose
 \
-Caching queries is a good way to improve performance of your application
+I need a way to cache mongoose queries and aggregations to improve application performance. It should support both in-memory and Redis cache engines, work with all major Node.js frameworks, and be easy to use with a simple `.cache()` method on queries and aggregations.
 
 ## Supports and tested with
 
 ```json
 {
   "node": "20.x || 22.x || 24.x",
-  "mongoose": ">=6.6.x || 7.x || 8.x || 9.x",
+  "mongoose": ">=6.6.0 <10"
 }
 ```
 
+CI tests against mongoose `6.12.2`, `7.6.4`, `8.23.0`, and `9.4.1`.
+
 ## Features
 
 - In-memory caching
@@ -42,22 +48,13 @@ Caching queries is a good way to improve performance of your application
 
 ## Installation
 
-- Locally inside your project
-
-```bash
-npm install ts-cache-mongoose
-pnpm add ts-cache-mongoose
-yarn add ts-cache-mongoose
-bun add ts-cache-mongoose
-```
-
-- This plugin requires `mongoose` to be installed as a peer dependency
+`mongoose` is a peer dependency — install it alongside `ts-cache-mongoose`.
 
 ```bash
-npm install mongoose
-pnpm add mongoose
-yarn add mongoose
-bun add mongoose
+npm install ts-cache-mongoose mongoose
+pnpm add ts-cache-mongoose mongoose
+yarn add ts-cache-mongoose mongoose
+bun add ts-cache-mongoose mongoose
 ```
 
 ## Example
@@ -105,6 +102,53 @@ const books = await Book.aggregate([
 ]).cache('1 minute').exec()
 ```
 
+### Bounded in-memory cache
+
+The in-memory engine is unbounded by default. For workloads where query keys are driven by user input (search, filters, pagination), cap the cache so a caller generating unique cache keys cannot grow the map without limit. Two bounds are available and can be combined — eviction is LRU, and whichever bound is hit first triggers it:
+
+```typescript
+cache.init(mongoose, {
+  engine: 'memory',
+  defaultTTL: '60 seconds',
+  maxEntries: 10_000,          // cap by entry count
+  maxBytes: 50 * 1024 * 1024,  // cap by serialized bytes (50 MB)
+})
+```
+
+`maxBytes` measures entry size via `node:v8.serialize(value).byteLength` by default — handles circular references (mongoose `populate` parent-refs), single C++ call per `set`, works on Node / Bun / Deno. Provide your own `sizeCalculation` callback if you want an O(1) estimate instead:
+
+```typescript
+cache.init(mongoose, {
+  engine: 'memory',
+  maxBytes: 50 * 1024 * 1024,
+  sizeCalculation: (value) => {
+    if (Array.isArray(value)) return value.length * 512
+    return 512
+  },
+})
+```
+
+Eviction is soft: the just-written entry is never dropped, even if its own size exceeds `maxBytes`. Everything older gets evicted until both bounds are satisfied (or only the new entry remains).
+
+Both options are ignored for the Redis engine — use Redis's own `maxmemory` + `maxmemory-policy` instead.
+
+### Custom error handling
+
+By default, cache engine failures (Redis disconnects, serialization errors, etc.) are logged via `console.error` and the query falls through to the database. Pass an `onError` callback to route them somewhere else — e.g. a structured logger, Sentry, or a metric counter:
+
+```typescript
+cache.init(mongoose, {
+  engine: 'redis',
+  defaultTTL: '60 seconds',
+  engineOptions: { host: 'localhost', port: 6379 },
+  onError: (error) => {
+    logger.warn({ err: error }, 'cache engine failure')
+  },
+})
+```
+
+The callback receives the raw `Error`. Cache reads and writes never throw — a failing engine degrades to a cache miss.
+
 ### Cache invalidation
 
 ```typescript
@@ -164,6 +208,14 @@ export class SomeService {
 }
 ```
 
+## Contributing
+
+Check [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details
+
 ## Check my other projects
 
 - [ts-migrate-mongoose](https://github.com/ilovepixelart/ts-migrate-mongoose) - Migration framework for mongoose

package/dist/index.cjs

@@ -1,5 +1,6 @@
 'use strict';
 
+var node_v8 = require('node:v8');
 var bson = require('bson');
 var IORedis = require('ioredis');
 var mongoose = require('mongoose');
@@ -11,89 +12,119 @@ const h = m * 60;
 const d = h * 24;
 const w = d * 7;
 const y = d * 365.25;
-const RE = /^(-?(?:\d+)?\.?\d+)\s*(milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d|weeks?|w|years?|yrs?|y)?$/i;
+const mo = y / 12;
 const UNITS = {
-  years: y,
-  year: y,
-  yrs: y,
-  yr: y,
-  y,
-  weeks: w,
-  week: w,
-  w,
-  days: d,
-  day: d,
-  d,
-  hours: h,
-  hour: h,
-  hrs: h,
-  hr: h,
-  h,
-  minutes: m,
-  minute: m,
-  mins: m,
-  min: m,
-  m,
+  milliseconds: 1,
+  millisecond: 1,
+  msecs: 1,
+  msec: 1,
+  ms: 1,
   seconds: s,
   second: s,
   secs: s,
   sec: s,
   s,
-  milliseconds: 1,
-  millisecond: 1,
-  msecs: 1,
-  msec: 1,
-  ms: 1
+  minutes: m,
+  minute: m,
+  mins: m,
+  min: m,
+  m,
+  hours: h,
+  hour: h,
+  hrs: h,
+  hr: h,
+  h,
+  days: d,
+  day: d,
+  d,
+  weeks: w,
+  week: w,
+  w,
+  months: mo,
+  month: mo,
+  mo,
+  years: y,
+  year: y,
+  yrs: y,
+  yr: y,
+  y
 };
+const unitPattern = Object.keys(UNITS).sort((a, b) => b.length - a.length).join("|");
+const RE = new RegExp(String.raw`^(-?(?:\d+)?\.?\d+)\s*(${unitPattern})?$`, "i");
 const ms = (val) => {
   const str = String(val);
-  if (str.length > 100) return 0;
+  if (str.length > 100) return Number.NaN;
   const match = RE.exec(str);
-  if (!match) return 0;
+  if (!match) return Number.NaN;
   const n = Number.parseFloat(match[1] ?? "");
   const type = (match[2] ?? "ms").toLowerCase();
   return n * (UNITS[type] ?? 0);
 };
 
-var __typeError$3 = (msg) => {
-  throw TypeError(msg);
-};
-var __accessCheck$3 = (obj, member, msg) => member.has(obj) || __typeError$3("Cannot " + msg);
-var __privateGet$3 = (obj, member, getter) => (__accessCheck$3(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
-var __privateAdd$3 = (obj, member, value) => member.has(obj) ? __typeError$3("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
-var __privateSet$3 = (obj, member, value, setter) => (__accessCheck$3(obj, member, "write to private field"), member.set(obj, value), value);
-var _cache;
+const defaultSizer = (value) => node_v8.serialize(value).byteLength;
 class MemoryCacheEngine {
-  constructor() {
-    __privateAdd$3(this, _cache);
-    __privateSet$3(this, _cache, /* @__PURE__ */ new Map());
+  #cache;
+  #maxEntries;
+  #maxBytes;
+  #sizeOf;
+  #totalBytes;
+  constructor(options) {
+    this.#cache = /* @__PURE__ */ new Map();
+    this.#maxEntries = options?.maxEntries != null && options.maxEntries > 0 ? options.maxEntries : Number.POSITIVE_INFINITY;
+    this.#maxBytes = options?.maxBytes != null && options.maxBytes > 0 ? options.maxBytes : Number.POSITIVE_INFINITY;
+    this.#sizeOf = options?.sizeCalculation ?? defaultSizer;
+    this.#totalBytes = 0;
+  }
+  get totalBytes() {
+    return this.#totalBytes;
+  }
+  get size() {
+    return this.#cache.size;
   }
   get(key) {
-    const item = __privateGet$3(this, _cache).get(key);
-    if (!item || item.expiresAt < Date.now()) {
-      this.del(key);
+    const item = this.#cache.get(key);
+    if (!item) return void 0;
+    if (item.expiresAt < Date.now()) {
+      this.#cache.delete(key);
+      this.#totalBytes -= item.bytes;
       return void 0;
     }
+    this.#cache.delete(key);
+    this.#cache.set(key, item);
     return item.value;
   }
   set(key, value, ttl) {
-    const givenTTL = typeof ttl === "string" ? ms(ttl) : ttl;
+    const givenTTL = ttl == null ? void 0 : ms(ttl);
     const actualTTL = givenTTL ?? Number.POSITIVE_INFINITY;
-    __privateGet$3(this, _cache).set(key, {
-      value,
-      expiresAt: Date.now() + actualTTL
-    });
+    const existing = this.#cache.get(key);
+    if (existing) {
+      this.#cache.delete(key);
+      this.#totalBytes -= existing.bytes;
+    }
+    const bytes = this.#sizeOf(value);
+    this.#cache.set(key, { value, expiresAt: Date.now() + actualTTL, bytes });
+    this.#totalBytes += bytes;
+    while ((this.#cache.size > this.#maxEntries || this.#totalBytes > this.#maxBytes) && this.#cache.size > 1) {
+      const oldestKey = this.#cache.keys().next().value;
+      if (oldestKey === void 0 || oldestKey === key) break;
+      const oldest = this.#cache.get(oldestKey);
+      this.#cache.delete(oldestKey);
+      if (oldest) this.#totalBytes -= oldest.bytes;
+    }
   }
   del(key) {
-    __privateGet$3(this, _cache).delete(key);
+    const item = this.#cache.get(key);
+    if (!item) return;
+    this.#cache.delete(key);
+    this.#totalBytes -= item.bytes;
   }
   clear() {
-    __privateGet$3(this, _cache).clear();
+    this.#cache.clear();
+    this.#totalBytes = 0;
   }
   close() {
   }
 }
-_cache = new WeakMap();
 
 const isMongooseLessThan7 = Number.parseInt(mongoose.version, 10) < 7;
 const convertToObject = (value) => {
@@ -108,120 +139,120 @@ const convertToObject = (value) => {
   return value;
 };
 
-var __typeError$2 = (msg) => {
-  throw TypeError(msg);
-};
-var __accessCheck$2 = (obj, member, msg) => member.has(obj) || __typeError$2("Cannot " + msg);
-var __privateGet$2 = (obj, member, getter) => (__accessCheck$2(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
-var __privateAdd$2 = (obj, member, value) => member.has(obj) ? __typeError$2("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
-var __privateSet$2 = (obj, member, value, setter) => (__accessCheck$2(obj, member, "write to private field"), member.set(obj, value), value);
-var _client;
 class RedisCacheEngine {
-  constructor(options) {
-    __privateAdd$2(this, _client);
+  #client;
+  #onError;
+  constructor(options, onError) {
     options.keyPrefix ??= "cache-mongoose:";
-    __privateSet$2(this, _client, new IORedis(options));
+    this.#client = new IORedis(options);
+    this.#onError = onError;
   }
   async get(key) {
     try {
-      const value = await __privateGet$2(this, _client).get(key);
+      const value = await this.#client.get(key);
       if (value === null) {
         return void 0;
       }
       return bson.EJSON.parse(value);
     } catch (err) {
-      console.error(err);
+      this.#onError(err);
       return void 0;
     }
   }
   async set(key, value, ttl) {
     try {
-      const givenTTL = typeof ttl === "string" ? ms(ttl) : ttl;
+      const converted = convertToObject(value);
+      if (converted === void 0) {
+        return;
+      }
+      const givenTTL = ttl == null ? void 0 : ms(ttl);
       const actualTTL = givenTTL ?? Number.POSITIVE_INFINITY;
-      const serializedValue = bson.EJSON.stringify(convertToObject(value));
-      await __privateGet$2(this, _client).setex(key, Math.ceil(actualTTL / 1e3), serializedValue);
+      const serializedValue = bson.EJSON.stringify(converted);
+      await this.#client.setex(key, Math.ceil(actualTTL / 1e3), serializedValue);
     } catch (err) {
-      console.error(err);
+      this.#onError(err);
     }
   }
   async del(key) {
-    await __privateGet$2(this, _client).del(key);
+    await this.#client.del(key);
   }
   async clear() {
-    await __privateGet$2(this, _client).flushdb();
+    await this.#client.flushdb();
   }
   async close() {
-    await __privateGet$2(this, _client).quit();
+    await this.#client.quit();
   }
 }
-_client = new WeakMap();
 
-var __typeError$1 = (msg) => {
-  throw TypeError(msg);
-};
-var __accessCheck$1 = (obj, member, msg) => member.has(obj) || __typeError$1("Cannot " + msg);
-var __privateGet$1 = (obj, member, getter) => (__accessCheck$1(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
-var __privateAdd$1 = (obj, member, value) => member.has(obj) ? __typeError$1("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
-var __privateSet$1 = (obj, member, value, setter) => (__accessCheck$1(obj, member, "write to private field"), member.set(obj, value), value);
-var _engine, _defaultTTL, _debug, _engines;
 class Cache {
+  #engine;
+  #defaultTTL;
+  #debug;
+  #onError;
+  #engines = ["memory", "redis"];
   constructor(cacheOptions) {
-    __privateAdd$1(this, _engine);
-    __privateAdd$1(this, _defaultTTL);
-    __privateAdd$1(this, _debug);
-    __privateAdd$1(this, _engines, ["memory", "redis"]);
-    if (!__privateGet$1(this, _engines).includes(cacheOptions.engine)) {
+    if (!this.#engines.includes(cacheOptions.engine)) {
       throw new Error(`Invalid engine name: ${cacheOptions.engine}`);
     }
     if (cacheOptions.engine === "redis" && !cacheOptions.engineOptions) {
       throw new Error(`Engine options are required for ${cacheOptions.engine} engine`);
     }
     cacheOptions.defaultTTL ??= "1 minute";
-    __privateSet$1(this, _defaultTTL, typeof cacheOptions.defaultTTL === "string" ? ms(cacheOptions.defaultTTL) : cacheOptions.defaultTTL);
+    this.#defaultTTL = ms(cacheOptions.defaultTTL);
+    this.#onError = cacheOptions.onError ?? console.error;
     if (cacheOptions.engine === "redis" && cacheOptions.engineOptions) {
-      __privateSet$1(this, _engine, new RedisCacheEngine(cacheOptions.engineOptions));
+      this.#engine = new RedisCacheEngine(cacheOptions.engineOptions, this.#onError);
     }
     if (cacheOptions.engine === "memory") {
-      __privateSet$1(this, _engine, new MemoryCacheEngine());
+      this.#engine = new MemoryCacheEngine({
+        maxEntries: cacheOptions.maxEntries,
+        maxBytes: cacheOptions.maxBytes,
+        sizeCalculation: cacheOptions.sizeCalculation
+      });
     }
-    __privateSet$1(this, _debug, cacheOptions.debug === true);
+    this.#debug = cacheOptions.debug === true;
+  }
+  get onError() {
+    return this.#onError;
   }
   async get(key) {
-    const cacheEntry = await __privateGet$1(this, _engine).get(key);
-    if (__privateGet$1(this, _debug)) {
+    const cacheEntry = await this.#engine.get(key);
+    if (this.#debug) {
       const cacheHit = cacheEntry == null ? "MISS" : "HIT";
       console.log(`[ts-cache-mongoose] GET '${key}' - ${cacheHit}`);
     }
     return cacheEntry;
   }
   async set(key, value, ttl) {
-    const givenTTL = typeof ttl === "string" ? ms(ttl) : ttl;
-    const actualTTL = givenTTL ?? __privateGet$1(this, _defaultTTL);
-    await __privateGet$1(this, _engine).set(key, value, actualTTL);
-    if (__privateGet$1(this, _debug)) {
+    const givenTTL = ttl == null ? null : ms(ttl);
+    const actualTTL = givenTTL ?? this.#defaultTTL;
+    if (Number.isNaN(actualTTL) || actualTTL <= 0) {
+      if (this.#debug) {
+        console.log(`[ts-cache-mongoose] SET '${key}' - skipped (non-positive ttl: ${String(actualTTL)} ms)`);
+      }
+      return;
+    }
+    await this.#engine.set(key, value, actualTTL);
+    if (this.#debug) {
       console.log(`[ts-cache-mongoose] SET '${key}' - ttl: ${actualTTL.toFixed(0)} ms`);
     }
   }
   async del(key) {
-    await __privateGet$1(this, _engine).del(key);
-    if (__privateGet$1(this, _debug)) {
+    await this.#engine.del(key);
+    if (this.#debug) {
       console.log(`[ts-cache-mongoose] DEL '${key}'`);
     }
   }
   async clear() {
-    await __privateGet$1(this, _engine).clear();
-    if (__privateGet$1(this, _debug)) {
+    await this.#engine.clear();
+    if (this.#debug) {
       console.log("[ts-cache-mongoose] CLEAR");
     }
   }
   async close() {
-    return __privateGet$1(this, _engine).close();
+    return this.#engine.close();
   }
 }
-_engine = new WeakMap();
-_defaultTTL = new WeakMap();
-_debug = new WeakMap();
-_engines = new WeakMap();
 
 const isPlainObject = (value) => {
   if (typeof value !== "object" || value === null) return false;
@@ -273,7 +304,7 @@ function extendAggregate(mongoose, cache) {
       pipeline: this.pipeline()
     });
   };
-  mongoose.Aggregate.prototype.getCacheTTL = function() {
+  mongoose.Aggregate.prototype.getDuration = function() {
     return this._ttl;
   };
   mongoose.Aggregate.prototype.cache = function(ttl, customKey) {
@@ -282,20 +313,20 @@ function extendAggregate(mongoose, cache) {
     return this;
   };
   mongoose.Aggregate.prototype.exec = async function(...args) {
-    if (!Object.prototype.hasOwnProperty.call(this, "_ttl")) {
+    if (!Object.hasOwn(this, "_ttl")) {
       return mongooseExec.apply(this, args);
     }
     const key = this.getCacheKey();
-    const ttl = this.getCacheTTL();
+    const ttl = this.getDuration();
     const resultCache = await cache.get(key).catch((err) => {
-      console.error(err);
+      cache.onError(err);
     });
     if (resultCache) {
       return resultCache;
     }
     const result = await mongooseExec.call(this);
     await cache.set(key, result, ttl).catch((err) => {
-      console.error(err);
+      cache.onError(err);
     });
     return result;
   };
@@ -322,7 +353,7 @@ function extendQuery(mongoose, cache) {
       _conditions: this._conditions
     });
   };
-  mongoose.Query.prototype.getCacheTTL = function() {
+  mongoose.Query.prototype.getDuration = function() {
     return this._ttl;
   };
   mongoose.Query.prototype.cache = function(ttl, customKey) {
@@ -331,17 +362,17 @@ function extendQuery(mongoose, cache) {
     return this;
   };
   mongoose.Query.prototype.exec = async function(...args) {
-    if (!Object.prototype.hasOwnProperty.call(this, "_ttl")) {
+    if (!Object.hasOwn(this, "_ttl")) {
       return mongooseExec.apply(this, args);
     }
     const key = this.getCacheKey();
-    const ttl = this.getCacheTTL();
+    const ttl = this.getDuration();
     const mongooseOptions = this.mongooseOptions();
     const isCount = this.op?.includes("count") ?? false;
     const isDistinct = this.op === "distinct";
     const model = this.model.modelName;
     const resultCache = await cache.get(key).catch((err) => {
-      console.error(err);
+      cache.onError(err);
     });
     if (resultCache) {
       if (isCount || isDistinct || mongooseOptions.lean) {
@@ -357,32 +388,26 @@ function extendQuery(mongoose, cache) {
     }
     const result = await mongooseExec.call(this);
     await cache.set(key, result, ttl).catch((err) => {
-      console.error(err);
+      cache.onError(err);
     });
     return result;
   };
 }
 
-var __typeError = (msg) => {
-  throw TypeError(msg);
-};
-var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
-var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
-var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
-var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), member.set(obj, value), value);
-var _instance;
-const _CacheMongoose = class _CacheMongoose {
+class CacheMongoose {
+  static #instance;
+  cache;
   constructor() {
   }
   static init(mongoose, cacheOptions) {
-    if (!__privateGet(_CacheMongoose, _instance)) {
-      __privateSet(_CacheMongoose, _instance, new _CacheMongoose());
-      __privateGet(_CacheMongoose, _instance).cache = new Cache(cacheOptions);
-      const cache = __privateGet(_CacheMongoose, _instance).cache;
+    if (!CacheMongoose.#instance) {
+      CacheMongoose.#instance = new CacheMongoose();
+      CacheMongoose.#instance.cache = new Cache(cacheOptions);
+      const cache = CacheMongoose.#instance.cache;
       extendQuery(mongoose, cache);
       extendAggregate(mongoose, cache);
     }
-    return __privateGet(_CacheMongoose, _instance);
+    return CacheMongoose.#instance;
   }
   async clear(customKey) {
     if (customKey == null) {
@@ -394,9 +419,6 @@ const _CacheMongoose = class _CacheMongoose {
   async close() {
     await this.cache.close();
   }
-};
-_instance = new WeakMap();
-__privateAdd(_CacheMongoose, _instance);
-let CacheMongoose = _CacheMongoose;
+}
 
 module.exports = CacheMongoose;