@nxtedition/cache 2.0.2 → 2.0.4

package/lib/index.d.ts

@@ -1,14 +1,20 @@
+import { EventEmitter } from 'node:events';
 import { type MemoryOptions } from './memory.ts';
 export type { MemoryOptions } from './memory.ts';
 export interface DatabaseOptions {
     timeout?: number;
     maxSize?: number;
 }
+export interface Serializer<V> {
+    serialize: (value: V) => Buffer | Uint8Array | string;
+    deserialize: (data: Buffer | string) => V;
+}
 export interface CacheOptions<V> {
     ttl?: number | ((value: V, key: string) => number);
     stale?: number | ((value: V, key: string) => number);
     memory?: MemoryOptions | false | null;
     database?: DatabaseOptions | false | null;
+    serializer?: Serializer<V>;
 }
 export type CacheResult<V> = {
     value: V | undefined;
@@ -17,9 +23,34 @@ export type CacheResult<V> = {
     value: Promise<V>;
     async: true;
 };
-export declare class Cache<V = unknown, A extends unknown[] = unknown[]> {
+declare global {
+    var __nxt_cache: {
+        stats: Cache['stats'];
+    }[];
+}
+export declare class Cache<V = unknown, A extends unknown[] = unknown[]> extends EventEmitter {
     #private;
     constructor(location: string, valueSelector: (...args: A) => V | PromiseLike<V>, keySelector: (...args: A) => string, opts?: CacheOptions<V>);
+    get stats(): {
+        lock: {
+            timeout: number;
+            mean: number;
+            stddev: number;
+        };
+        dedupe: {
+            size: number;
+        };
+        memory: {
+            size: number;
+            maxSize: number;
+            count: number;
+            maxCount: number;
+        } | undefined;
+        database: {
+            location: string;
+            size: number | undefined;
+        } | undefined;
+    };
     close(): void;
     get(...args: A): CacheResult<V>;
     peek(...args: A): CacheResult<V>;

package/lib/index.js

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto'
+import { EventEmitter } from 'node:events'
 import { DatabaseSync,                                        } from 'node:sqlite'
 import { setTimeout as delay } from 'node:timers/promises'
 import { MemoryCache,                                           } from "./memory.js"
@@ -7,25 +8,18 @@ import { MemoryCache,                                           } from "./memory
 
 function noop() {}
 
+function maybeToBuffer(value                          )                  {
+  return ArrayBuffer.isView(value)
+    ? Buffer.from(value.buffer, value.byteOffset, value.byteLength)
+    : value
+}
+
 function isThenable(value         )                                {
   return value != null && typeof (value                        ).then === 'function'
 }
 
-const dbs = new Set                            ()
-
-{
-  const offPeakBC = new BroadcastChannel('nxt:offPeak')
-  offPeakBC.unref()
-  offPeakBC.onmessage = () => {
-    for (const db of dbs) {
-      try {
-        db.purgeStale()
-      } catch (err) {
-        process.emitWarning(err         )
-      }
-    }
-  }
-}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const dbs = new Set                 ()
 
                          
              
@@ -44,21 +38,42 @@ const dbs = new Set                            ()
                   
  
 
+                                
+                                                       
+                                           
+ 
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const defaultSerializer                  = {
+  serialize(value) {
+    return ArrayBuffer.isView(value) ? (value              ) : JSON.stringify(value)
+  },
+  deserialize(data) {
+    return ArrayBuffer.isView(data) ? data : JSON.parse(data)
+  },
+}
+
                                   
                                                     
                                                       
                                        
                                            
+                            
  
 
                             
                                           
                                       
 
-const VERSION = 4
+                
+                                    
+                                              
+ 
+
+const VERSION = 5
 const MAX_DURATION = 365000000e3
 
-export class Cache                                               {
+export class Cache                                               extends EventEmitter {
   #memory                       
   #dedupe = new Map                    ()
   #closed = false
@@ -68,12 +83,14 @@ export class Cache                                               {
 
   #ttl                                 
   #stale                                 
+  #serializer               
 
   #lockMean = 5
   #lockVar = 0
   #lockTimeout = 10
   #lockId = randomUUID()
 
+  #location        
   #database                      = null
   #getQuery                       = null
   #setQuery                       = null
@@ -84,6 +101,16 @@ export class Cache                                               {
   #lockStealQuery                       = null
   #lockGetQuery                       = null
   #lockPurgeQuery                       = null
+  #pageCountQuery                       = null
+  #pageSizeQuery                       = null
+
+  #emitError(err       )       {
+    if (this.listenerCount('error') > 0) {
+      this.emit('error', err)
+    } else {
+      process.emitWarning(err)
+    }
+  }
 
   constructor(
     location        ,
@@ -91,9 +118,11 @@ export class Cache                                               {
     keySelector                        ,
     opts                  ,
   ) {
+    super()
     if (typeof location !== 'string') {
       throw new TypeError('location must be a string')
     }
+    this.#location = location
 
     if (typeof valueSelector !== 'function') {
       throw new TypeError('valueSelector must be a function')
@@ -123,6 +152,19 @@ export class Cache                                               {
       throw new TypeError('stale must be a undefined, number or a function')
     }
 
+    if (opts?.serializer !== undefined) {
+      if (typeof opts.serializer !== 'object' || opts.serializer === null) {
+        throw new TypeError('serializer must be an object')
+      }
+      if (typeof opts.serializer.serialize !== 'function') {
+        throw new TypeError('serializer.serialize must be a function')
+      }
+      if (typeof opts.serializer.deserialize !== 'function') {
+        throw new TypeError('serializer.deserialize must be a function')
+      }
+    }
+    this.#serializer = opts?.serializer ?? defaultSerializer
+
     this.#memory =
       opts?.memory === false || opts?.memory === null ? null : new MemoryCache(opts?.memory)
 
@@ -137,6 +179,9 @@ export class Cache                                               {
           PRAGMA journal_mode = WAL;
           PRAGMA synchronous = NORMAL;
           PRAGMA temp_store = memory;
+          PRAGMA cache_size = -${Math.ceil(maxSize / 1024 / 8)};
+          PRAGMA mmap_size = ${maxSize};
+          PRAGMA max_page_count = ${Math.ceil(maxSize / 4096)};
           PRAGMA optimize;
 
           CREATE TABLE IF NOT EXISTS cache_v${VERSION} (
@@ -144,7 +189,9 @@ export class Cache                                               {
             val BLOB NOT NULL,
             ttl INTEGER NOT NULL,
             stale INTEGER NOT NULL
-          );
+          ) WITHOUT ROWID;
+
+          CREATE INDEX IF NOT EXISTS cache_v${VERSION}_stale_idx ON cache_v${VERSION}(stale);
 
           CREATE TABLE IF NOT EXISTS cache_lock_v${VERSION} (
             key TEXT PRIMARY KEY NOT NULL,
@@ -153,13 +200,6 @@ export class Cache                                               {
           );
         `)
 
-        {
-          const { page_size } = this.#database.prepare('PRAGMA page_size').get()     
-                             
-           
-          this.#database.exec(`PRAGMA max_page_count = ${Math.ceil(maxSize / page_size)}`)
-        }
-
         this.#getQuery = this.#database.prepare(
           `SELECT val, ttl, stale FROM cache_v${VERSION} WHERE key = ? AND stale > ?`,
         )
@@ -174,7 +214,7 @@ export class Cache                                               {
           `DELETE FROM cache_v${VERSION} WHERE key IN (SELECT key FROM cache_v${VERSION} ORDER BY stale ASC LIMIT ?)`,
         )
 
-        // Bug A fix: ON CONFLICT refreshes lock_acquired when we are the owner,
+        // ON CONFLICT refreshes lock_acquired when we are the owner,
         // preventing other processes from stealing our still-active lock.
         this.#lockAcquireQuery = this.#database.prepare(
           `INSERT INTO cache_lock_v${VERSION} (key, lock_acquired, lock_owner) VALUES (?, ?, ?) ON CONFLICT(key) DO UPDATE SET lock_acquired = CASE WHEN lock_owner = excluded.lock_owner THEN excluded.lock_acquired ELSE lock_acquired END RETURNING lock_acquired, lock_owner`,
@@ -182,13 +222,15 @@ export class Cache                                               {
         this.#lockStealQuery = this.#database.prepare(
           `UPDATE cache_lock_v${VERSION} SET lock_acquired = ?, lock_owner = ? WHERE key = ? AND lock_acquired = ?`,
         )
-        // Bug B fix: read the current lock state after a failed steal to get the winner's timestamp.
+        // Read the current lock state after a failed steal to get the winner's timestamp.
         this.#lockGetQuery = this.#database.prepare(
           `SELECT lock_acquired FROM cache_lock_v${VERSION} WHERE key = ?`,
         )
         this.#lockPurgeQuery = this.#database.prepare(
           `DELETE FROM cache_lock_v${VERSION} WHERE lock_acquired <= ?`,
         )
+        this.#pageCountQuery = this.#database.prepare('PRAGMA page_count')
+        this.#pageSizeQuery = this.#database.prepare('PRAGMA page_size')
         break
       } catch (err) {
         if (n >= 16) {
@@ -204,14 +246,45 @@ export class Cache                                               {
           this.#lockStealQuery = null
           this.#lockGetQuery = null
           this.#lockPurgeQuery = null
+          this.#pageCountQuery = null
+          this.#pageSizeQuery = null
 
-          process.emitWarning(err         )
+          this.#emitError(err         )
           break
         }
       }
     }
 
     dbs.add(this)
+
+    globalThis.__nxt_cache ??= []
+    globalThis.__nxt_cache.push(this)
+  }
+
+  get stats() {
+    let database                                                            
+    if (this.#database) {
+      let size                    
+      try {
+        const { page_count } = this.#pageCountQuery .get()                          
+        const { page_size } = this.#pageSizeQuery .get()                         
+        size = page_count * page_size
+      } catch (err) {
+        this.#emitError(err         )
+      }
+      database = { location: this.#location, size }
+    }
+
+    return {
+      lock: {
+        timeout: this.#lockTimeout,
+        mean: this.#lockMean,
+        stddev: Math.sqrt(this.#lockVar),
+      },
+      dedupe: { size: this.#dedupe.size },
+      memory: this.#memory?.stats,
+      database,
+    }
   }
 
   close()       {
@@ -228,8 +301,15 @@ export class Cache                                               {
     this.#lockStealQuery = null
     this.#lockGetQuery = null
     this.#lockPurgeQuery = null
+    this.#pageCountQuery = null
+    this.#pageSizeQuery = null
     this.#database?.close()
     this.#database = null
+
+    const idx = globalThis.__nxt_cache?.indexOf(this) ?? -1
+    if (idx !== -1) {
+      globalThis.__nxt_cache.splice(idx, 1)
+    }
   }
 
   get(...args   )                 {
@@ -269,7 +349,7 @@ export class Cache                                               {
       this.#purgeStaleQuery?.run(Date.now())
       this.#lockPurgeQuery?.run(Date.now() - 3_600_000)
     } catch (err) {
-      process.emitWarning(err         )
+      this.#emitError(err         )
     }
   }
 
@@ -293,7 +373,7 @@ export class Cache                                               {
           cached = entry
         }
       } catch (err) {
-        process.emitWarning(err         )
+        this.#emitError(err         )
       }
     }
 
@@ -315,18 +395,20 @@ export class Cache                                               {
       }
     }
 
+    if (!refresh) {
+      // peek: return stale value if available, undefined if expired or missing
+      return { value: cached?.value, async: false }
+    }
+
     let result                
-    if (refresh) {
-      try {
-        result = this.#refresh(args, key)
-      } catch (err) {
-        if (cached !== undefined) {
-          return { value: cached.value, async: false }
-        }
-        throw err
+    try {
+      result = this.#refresh(args, key)
+    } catch (err) {
+      if (cached !== undefined) {
+        this.#emitError(err         )
+        return { value: cached.value, async: false }
       }
-    } else {
-      result = { value: undefined, async: false }
+      throw err
     }
 
     if (result.async && cached !== undefined) {
@@ -413,7 +495,7 @@ export class Cache                                               {
       try {
         this.#delQuery?.run(key)
       } catch (err) {
-        process.emitWarning(err         )
+        this.#emitError(err         )
       }
       return
     }
@@ -436,7 +518,7 @@ export class Cache                                               {
       return
     }
 
-    const data = ArrayBuffer.isView(value) ? value : JSON.stringify(value           )
+    const data = this.#serializer.serialize(value)
 
     const entry = this.#createEntry(
       key,
@@ -454,11 +536,11 @@ export class Cache                                               {
         try {
           this.#evictQuery?.run(256)
           this.#setQuery?.run(key, data                 , ttl, stale)
-        } catch {
-          process.emitWarning(err         )
+        } catch (evictErr) {
+          this.#emitError(evictErr         )
         }
       } else {
-        process.emitWarning(err         )
+        this.#emitError(err         )
       }
     }
   }
@@ -473,9 +555,7 @@ export class Cache                                               {
     return {
       ttl,
       stale,
-      value: ArrayBuffer.isView(value)
-        ? (Buffer.from(value.buffer, value.byteOffset, value.byteLength)                )
-        : value,
+      value,
       key,
       size,
       index: -1,
@@ -484,7 +564,7 @@ export class Cache                                               {
   }
 
   #loadRow(key        , row             )                      {
-    const value = (ArrayBuffer.isView(row.val) ? row.val : JSON.parse(row.val))     
+    const value = this.#serializer.deserialize(maybeToBuffer(row.val))
     return this.#createEntry(
       key,
       value,
@@ -535,7 +615,7 @@ export class Cache                                               {
 
       return lockedAt
     } catch (err) {
-      process.emitWarning(err         )
+      this.#emitError(err         )
       return 'unavailable'
     }
   }
@@ -582,7 +662,7 @@ export class Cache                                               {
           return entry.value
         }
       } catch (err) {
-        process.emitWarning(err         )
+        this.#emitError(err         )
       }
 
       // Try to acquire lock for takeover
@@ -619,6 +699,24 @@ export class Cache                                               {
   }
 }
 
+{
+  const offPeakBC = new BroadcastChannel('nxt:offPeak')
+  offPeakBC.unref()
+  offPeakBC.onmessage = () => {
+    for (const db of dbs) {
+      try {
+        db.purgeStale()
+      } catch (err) {
+        if (db.listenerCount('error') > 0) {
+          db.emit('error', err)
+        } else {
+          process.emitWarning(err         )
+        }
+      }
+    }
+  }
+}
+
 /** @deprecated Use `Cache` instead. */
 export const AsyncCache = Cache
 /** @deprecated Use `CacheOptions` instead. */

package/lib/memory.d.ts

@@ -18,4 +18,10 @@ export declare class MemoryCache<V> {
     get(key: string): MemoryCacheEntry<V> | undefined;
     delete(key: string): void;
     purgeStale(now: number): void;
+    get stats(): {
+        size: number;
+        maxSize: number;
+        count: number;
+        maxCount: number;
+    };
 }

package/lib/memory.js

@@ -97,6 +97,15 @@ export class MemoryCache    {
     }
   }
 
+  get stats() {
+    return {
+      size: this.#size,
+      maxSize: this.#maxSize,
+      count: this.#count,
+      maxCount: this.#maxCount,
+    }
+  }
+
   #prune() {
     while (this.#size > this.#maxSize || this.#count > this.#maxCount) {
       const e1 = this.#arr[(Math.random() * this.#arr.length) | 0]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxtedition/cache",
-  "version": "2.0.2",
+  "version": "2.0.4",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -30,5 +30,5 @@
     "tsd": "^0.33.0",
     "typescript": "^5.9.3"
   },
-  "gitHead": "f6592f0be62fecc161237610ae6454ec6585548b"
+  "gitHead": "9b8156711c1909480df222a003871e2d9cded24c"
 }