@nxtedition/cache 2.0.3 → 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;
@@ -22,7 +28,7 @@ declare global {
         stats: Cache['stats'];
     }[];
 }
-export declare class Cache<V = unknown, A extends unknown[] = unknown[]> {
+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(): {

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,11 +38,27 @@ 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)
+  },
+}
+
                                   
                                                     
                                                       
                                        
                                            
+                            
  
 
                             
@@ -60,12 +70,10 @@ const dbs = new Set                            ()
                                               
  
 
-const VERSION = 4
+const VERSION = 5
 const MAX_DURATION = 365000000e3
 
-globalThis.__nxt_cache ??= []
-
-export class Cache                                               {
+export class Cache                                               extends EventEmitter {
   #memory                       
   #dedupe = new Map                    ()
   #closed = false
@@ -75,6 +83,7 @@ export class Cache                                               {
 
   #ttl                                 
   #stale                                 
+  #serializer               
 
   #lockMean = 5
   #lockVar = 0
@@ -95,12 +104,21 @@ export class Cache                                               {
   #pageCountQuery                       = null
   #pageSizeQuery                       = null
 
+  #emitError(err       )       {
+    if (this.listenerCount('error') > 0) {
+      this.emit('error', err)
+    } else {
+      process.emitWarning(err)
+    }
+  }
+
   constructor(
     location        ,
     valueSelector                                    ,
     keySelector                        ,
     opts                  ,
   ) {
+    super()
     if (typeof location !== 'string') {
       throw new TypeError('location must be a string')
     }
@@ -134,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)
 
@@ -148,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} (
@@ -155,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,
@@ -164,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 > ?`,
         )
@@ -185,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`,
@@ -193,7 +222,7 @@ 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 = ?`,
         )
@@ -220,7 +249,7 @@ export class Cache                                               {
           this.#pageCountQuery = null
           this.#pageSizeQuery = null
 
-          process.emitWarning(err         )
+          this.#emitError(err         )
           break
         }
       }
@@ -228,6 +257,7 @@ export class Cache                                               {
 
     dbs.add(this)
 
+    globalThis.__nxt_cache ??= []
     globalThis.__nxt_cache.push(this)
   }
 
@@ -240,7 +270,7 @@ export class Cache                                               {
         const { page_size } = this.#pageSizeQuery .get()                         
         size = page_count * page_size
       } catch (err) {
-        process.emitWarning(err         )
+        this.#emitError(err         )
       }
       database = { location: this.#location, size }
     }
@@ -276,7 +306,7 @@ export class Cache                                               {
     this.#database?.close()
     this.#database = null
 
-    const idx = globalThis.__nxt_cache.indexOf(this)
+    const idx = globalThis.__nxt_cache?.indexOf(this) ?? -1
     if (idx !== -1) {
       globalThis.__nxt_cache.splice(idx, 1)
     }
@@ -319,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         )
     }
   }
 
@@ -343,7 +373,7 @@ export class Cache                                               {
           cached = entry
         }
       } catch (err) {
-        process.emitWarning(err         )
+        this.#emitError(err         )
       }
     }
 
@@ -365,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) {
@@ -463,7 +495,7 @@ export class Cache                                               {
       try {
         this.#delQuery?.run(key)
       } catch (err) {
-        process.emitWarning(err         )
+        this.#emitError(err         )
       }
       return
     }
@@ -486,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,
@@ -504,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         )
       }
     }
   }
@@ -523,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,
@@ -534,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,
@@ -585,7 +615,7 @@ export class Cache                                               {
 
       return lockedAt
     } catch (err) {
-      process.emitWarning(err         )
+      this.#emitError(err         )
       return 'unavailable'
     }
   }
@@ -632,7 +662,7 @@ export class Cache                                               {
           return entry.value
         }
       } catch (err) {
-        process.emitWarning(err         )
+        this.#emitError(err         )
       }
 
       // Try to acquire lock for takeover
@@ -669,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxtedition/cache",
-  "version": "2.0.3",
+  "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": "cfc529e921c93a1fb0292018e2026f2b326ec998"
+  "gitHead": "9b8156711c1909480df222a003871e2d9cded24c"
 }