@nxtedition/cache 2.0.0 → 2.0.2

package/README.md

@@ -14,9 +14,9 @@ An async cache with SQLite persistence, in-memory LRU, stale-while-revalidate, a
 ## Usage
 
 ```ts
-import { AsyncCache } from '@nxtedition/cache'
+import { Cache } from '@nxtedition/cache'
 
-const cache = new AsyncCache(
+const cache = new Cache(
   './my-cache.db', // SQLite file path, or ':memory:'
   async (id: string) => {
     // fetch the value for this key
@@ -43,14 +43,14 @@ if (result.async) {
 
 ## API
 
-### `new AsyncCache(location, valueSelector, keySelector, opts?)`
+### `new Cache(location, valueSelector, keySelector, opts?)`
 
 | Parameter       | Type                           | Description                                   |
 | --------------- | ------------------------------ | --------------------------------------------- |
 | `location`      | `string`                       | SQLite database path, or `':memory:'`         |
 | `valueSelector` | `(...args) => V \| Promise<V>` | Function to fetch a value on cache miss       |
 | `keySelector`   | `(...args) => string`          | Function to derive a cache key from arguments |
-| `opts`          | `AsyncCacheOptions<V>`         | Optional configuration                        |
+| `opts`          | `CacheOptions<V>`              | Optional configuration                        |
 
 #### Options
 

package/lib/index.d.ts

@@ -4,7 +4,7 @@ export interface DatabaseOptions {
     timeout?: number;
     maxSize?: number;
 }
-export interface AsyncCacheOptions<V> {
+export interface CacheOptions<V> {
     ttl?: number | ((value: V, key: string) => number);
     stale?: number | ((value: V, key: string) => number);
     memory?: MemoryOptions | false | null;
@@ -17,9 +17,9 @@ export type CacheResult<V> = {
     value: Promise<V>;
     async: true;
 };
-export declare class AsyncCache<V = unknown, A extends unknown[] = unknown[]> {
+export declare class Cache<V = unknown, A extends unknown[] = unknown[]> {
     #private;
-    constructor(location: string, valueSelector: (...args: A) => V | Promise<V>, keySelector: (...args: A) => string, opts?: AsyncCacheOptions<V>);
+    constructor(location: string, valueSelector: (...args: A) => V | PromiseLike<V>, keySelector: (...args: A) => string, opts?: CacheOptions<V>);
     close(): void;
     get(...args: A): CacheResult<V>;
     peek(...args: A): CacheResult<V>;
@@ -27,3 +27,7 @@ export declare class AsyncCache<V = unknown, A extends unknown[] = unknown[]> {
     delete(...args: A): void;
     purgeStale(): void;
 }
+/** @deprecated Use `Cache` instead. */
+export declare const AsyncCache: typeof Cache;
+/** @deprecated Use `CacheOptions` instead. */
+export type AsyncCacheOptions<V> = CacheOptions<V>;

package/lib/index.js

@@ -1,22 +1,16 @@
+import { randomUUID } from 'node:crypto'
 import { DatabaseSync,                                        } from 'node:sqlite'
+import { setTimeout as delay } from 'node:timers/promises'
 import { MemoryCache,                                           } from "./memory.js"
 
                                                 
 
-let fastNowTime = 0
+function noop() {}
 
-function fastNow()         {
-  if (fastNowTime === 0) {
-    fastNowTime = Math.floor(Date.now() / 1e3) * 1e3
-    setInterval(() => {
-      fastNowTime = Math.floor(Date.now() / 1e3) * 1e3
-    }, 1e3).unref()
-  }
-  return fastNowTime
+function isThenable(value         )                                {
+  return value != null && typeof (value                        ).then === 'function'
 }
 
-function noop() {}
-
 const dbs = new Set                            ()
 
 {
@@ -50,7 +44,7 @@ const dbs = new Set                            ()
                   
  
 
-                                       
+                                  
                                                     
                                                       
                                        
@@ -61,31 +55,41 @@ const dbs = new Set                            ()
                                           
                                       
 
-const VERSION = 2
+const VERSION = 4
 const MAX_DURATION = 365000000e3
 
-export class AsyncCache                                               {
+export class Cache                                               {
   #memory                       
   #dedupe = new Map                    ()
+  #closed = false
 
-  #valueSelector                                
+  #valueSelector                                    
   #keySelector                        
 
   #ttl                                 
   #stale                                 
 
+  #lockMean = 5
+  #lockVar = 0
+  #lockTimeout = 10
+  #lockId = randomUUID()
+
   #database                      = null
   #getQuery                       = null
   #setQuery                       = null
   #delQuery                       = null
   #purgeStaleQuery                       = null
   #evictQuery                       = null
+  #lockAcquireQuery                       = null
+  #lockStealQuery                       = null
+  #lockGetQuery                       = null
+  #lockPurgeQuery                       = null
 
   constructor(
     location        ,
-    valueSelector                                ,
+    valueSelector                                    ,
     keySelector                        ,
-    opts                       ,
+    opts                  ,
   ) {
     if (typeof location !== 'string') {
       throw new TypeError('location must be a string')
@@ -141,6 +145,12 @@ export class AsyncCache                                               {
             ttl INTEGER NOT NULL,
             stale INTEGER NOT NULL
           );
+
+          CREATE TABLE IF NOT EXISTS cache_lock_v${VERSION} (
+            key TEXT PRIMARY KEY NOT NULL,
+            lock_acquired INTEGER NOT NULL,
+            lock_owner TEXT NOT NULL
+          );
         `)
 
         {
@@ -163,6 +173,22 @@ export class AsyncCache                                               {
         this.#evictQuery = this.#database.prepare(
           `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,
+        // 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`,
+        )
+        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.
+        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 <= ?`,
+        )
         break
       } catch (err) {
         if (n >= 16) {
@@ -174,6 +200,10 @@ export class AsyncCache                                               {
           this.#delQuery = null
           this.#purgeStaleQuery = null
           this.#evictQuery = null
+          this.#lockAcquireQuery = null
+          this.#lockStealQuery = null
+          this.#lockGetQuery = null
+          this.#lockPurgeQuery = null
 
           process.emitWarning(err         )
           break
@@ -185,36 +215,59 @@ export class AsyncCache                                               {
   }
 
   close()       {
+    this.#closed = true
+    this.#dedupe.clear()
     dbs.delete(this)
+
     this.#getQuery = null
     this.#setQuery = null
     this.#delQuery = null
     this.#purgeStaleQuery = null
     this.#evictQuery = null
+    this.#lockAcquireQuery = null
+    this.#lockStealQuery = null
+    this.#lockGetQuery = null
+    this.#lockPurgeQuery = null
     this.#database?.close()
     this.#database = null
   }
 
   get(...args   )                 {
+    if (this.#closed) {
+      throw new Error('cache is closed')
+    }
     return this.#load(args, true)
   }
 
   peek(...args   )                 {
+    if (this.#closed) {
+      throw new Error('cache is closed')
+    }
     return this.#load(args, false)
   }
 
   refresh(...args   )                 {
+    if (this.#closed) {
+      throw new Error('cache is closed')
+    }
     return this.#refresh(args)
   }
 
   delete(...args   )       {
-    this.#delete(this.#keySelector(...args))
+    if (this.#closed) {
+      throw new Error('cache is closed')
+    }
+    this.#set(this.#keySelector(...args), undefined)
   }
 
   purgeStale()       {
+    if (this.#closed) {
+      throw new Error('cache is closed')
+    }
     try {
-      this.#memory?.purgeStale(fastNow())
-      this.#purgeStaleQuery?.run(fastNow())
+      this.#memory?.purgeStale(Date.now())
+      this.#purgeStaleQuery?.run(Date.now())
+      this.#lockPurgeQuery?.run(Date.now() - 3_600_000)
     } catch (err) {
       process.emitWarning(err         )
     }
@@ -227,7 +280,7 @@ export class AsyncCache                                               {
       throw new TypeError('keySelector must return a non-empty string')
     }
 
-    const now = fastNow()
+    const now = Date.now()
 
     let cached                            = this.#memory?.get(key)
 
@@ -235,24 +288,8 @@ export class AsyncCache                                               {
       try {
         const row = this.#getQuery?.get(key, now)                           
         if (row !== undefined) {
-          const entry                      = {
-            ttl: row.ttl,
-            stale: row.stale,
-            value: ArrayBuffer.isView(row.val)
-              ? (Buffer.from(
-                  row.val.buffer,
-                  row.val.byteOffset,
-                  row.val.byteLength,
-                )                )
-              : JSON.parse(row.val),
-            key,
-            size:
-              (ArrayBuffer.isView(row.val) ? row.val.byteLength : row.val.length) + key.length + 64,
-            index: -1,
-            counter: -1,
-          }
+          const entry = this.#loadRow(key, row)
           this.#memory?.set(key, entry)
-
           cached = entry
         }
       } catch (err) {
@@ -278,7 +315,19 @@ export class AsyncCache                                               {
       }
     }
 
-    const result = refresh ? this.#refresh(args, key) : ({ value: undefined, 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
+      }
+    } else {
+      result = { value: undefined, async: false }
+    }
 
     if (result.async && cached !== undefined) {
       return { value: cached.value, async: false }
@@ -292,68 +341,94 @@ export class AsyncCache                                               {
       throw new TypeError('keySelector must return a non-empty string')
     }
 
-    // TODO (fix): cross process/thread dedupe...
     const existing = this.#dedupe.get(key)
     if (existing !== undefined) {
       return { async: true, value: existing }
     }
 
-    const value = this.#valueSelector(...args)
-
-    if (!(value instanceof Promise)) {
-      this.#dedupe.delete(key)
-      if (value === undefined) {
-        this.#delete(key)
-      } else {
-        this.#set(key, value)
-      }
-      return { async: false, value }
+    // Another process holds the lock — wait for the value instead of calling valueSelector.
+    // Use deferred pattern so #waitForValue can check promise identity to detect delete+get races.
+    const lockResult = this.#tryAcquireLock(key)
+    if (typeof lockResult === 'number') {
+      const { promise, resolve, reject } = Promise.withResolvers   ()
+      promise.catch(noop)
+      this.#dedupe.set(key, promise)
+      this.#waitForValue(args, key, lockResult, promise).then(resolve, reject)
+      return { async: true, value: promise }
     }
 
-    // eslint-disable-next-line: no-unsafe-argument
-    const promise = value.then(
-      (value) => {
-        if (this.#dedupe.get(key) === promise) {
-          this.#dedupe.delete(key)
-          if (value === undefined) {
-            this.#delete(key)
-          } else {
+    const res = this.#fetch(args)
+
+    if (res.async) {
+      const promise = res.value.then(
+        (value) => {
+          if (this.#dedupe.get(key) === promise) {
             this.#set(key, value)
           }
-        }
-        return value
-      },
-      (err) => {
-        if (this.#dedupe.get(key) === promise) {
-          this.#dedupe.delete(key)
-        }
-        throw err
-      },
-    )
-    promise.catch(noop)
-    this.#dedupe.set(key, promise)
+          return value
+        },
+        (err) => {
+          if (this.#dedupe.get(key) === promise) {
+            this.#dedupe.delete(key)
+          }
+          throw err
+        },
+      )
+      promise.catch(noop)
+      this.#dedupe.set(key, promise)
+      return { async: true, value: promise }
+    }
 
-    return { async: true, value: promise }
+    this.#set(key, res.value)
+    return res
   }
 
-  #set(key        , value   )       {
+  #fetch(args   )                                                                  {
+    const startTime = performance.now()
+    const value = this.#valueSelector(...args)
+
+    if (isThenable(value)) {
+      return {
+        async: true,
+        value: Promise.resolve(value).then((value) => {
+          this.#updateLockTimeout(performance.now() - startTime)
+          return value
+        }),
+      }
+    }
+
+    this.#updateLockTimeout(performance.now() - startTime)
+    return { async: false, value }
+  }
+
+  #set(key        , value               )       {
     if (typeof key !== 'string' || key.length === 0) {
       throw new TypeError('key must be a non-empty string')
     }
 
     this.#dedupe.delete(key)
 
+    if (value === undefined) {
+      this.#memory?.delete(key)
+      try {
+        this.#delQuery?.run(key)
+      } catch (err) {
+        process.emitWarning(err         )
+      }
+      return
+    }
+
     const ttlValue = Math.min(MAX_DURATION, this.#ttl(value, key) ?? Infinity)
     if (!Number.isFinite(ttlValue) || ttlValue < 0) {
       throw new TypeError('ttl must be nully or a positive integer')
     }
 
-    const staleValue = Math.min(MAX_DURATION, this.#stale(value, key) ?? 0)
+    const staleValue = Math.min(MAX_DURATION, this.#stale(value, key) ?? Number.MAX_SAFE_INTEGER)
     if (!Number.isFinite(staleValue) || staleValue < 0) {
       throw new TypeError('stale must be nully or a positive integer')
     }
 
-    const now = fastNow()
+    const now = Date.now()
     const ttl = now + ttlValue
     const stale = ttl + staleValue
 
@@ -361,21 +436,16 @@ export class AsyncCache                                               {
       return
     }
 
-    const data                           = ArrayBuffer.isView(value)
-      ? value
-      : JSON.stringify(value           )
+    const data = ArrayBuffer.isView(value) ? value : JSON.stringify(value           )
 
-    this.#memory?.set(key, {
+    const entry = this.#createEntry(
+      key,
+      value,
       ttl,
       stale,
-      value: ArrayBuffer.isView(value)
-        ? (Buffer.from(value.buffer, value.byteOffset, value.byteLength)                )
-        : value,
-      key,
-      size: (ArrayBuffer.isView(data) ? data.byteLength : data.length) + key.length + 64,
-      index: -1,
-      counter: -1,
-    })
+      ArrayBuffer.isView(data) ? data.byteLength : data.length * 2,
+    )
+    this.#memory?.set(key, entry)
 
     try {
       this.#setQuery?.run(key, data                 , ttl, stale)
@@ -393,17 +463,163 @@ export class AsyncCache                                               {
     }
   }
 
-  #delete(key        )       {
-    if (typeof key !== 'string' || key.length === 0) {
-      throw new TypeError('key must be a non-empty string')
+  #createEntry(
+    key        ,
+    value   ,
+    ttl        ,
+    stale        ,
+    size        ,
+  )                      {
+    return {
+      ttl,
+      stale,
+      value: ArrayBuffer.isView(value)
+        ? (Buffer.from(value.buffer, value.byteOffset, value.byteLength)                )
+        : value,
+      key,
+      size,
+      index: -1,
+      counter: -1,
     }
+  }
+
+  #loadRow(key        , row             )                      {
+    const value = (ArrayBuffer.isView(row.val) ? row.val : JSON.parse(row.val))     
+    return this.#createEntry(
+      key,
+      value,
+      row.ttl,
+      row.stale,
+      ArrayBuffer.isView(row.val) ? row.val.byteLength : row.val.length * 2,
+    )
+  }
+
+  // Returns lock_acquired timestamp (number) when contended, or a string status.
+  #tryAcquireLock(key        )                                      {
+    if (this.#lockAcquireQuery === null) {
+      return 'unavailable'
+    }
+
+    const now = Date.now()
 
-    this.#dedupe.delete(key)
-    this.#memory?.delete(key)
     try {
-      this.#delQuery?.run(key)
+      const row = this.#lockAcquireQuery.get(key, now, this.#lockId)   
+                                                       
+                   
+
+      if (row === undefined) {
+        return 'unavailable'
+      }
+
+      if (row.lock_owner === this.#lockId) {
+        return 'acquired'
+      }
+
+      const lockedAt = row.lock_acquired
+      if (now - lockedAt > this.#lockTimeout * 3) {
+        // Lock is stale (3x the EMA-based timeout) — attempt to steal atomically.
+        // The WHERE clause matches the exact lock_acquired we observed, so only one
+        // process wins if multiple try to steal concurrently.
+        const stealResult = this.#lockStealQuery .run(now, this.#lockId, key, lockedAt)
+        if (stealResult.changes === 1) {
+          return 'acquired'
+        }
+
+        // Steal failed — another process won the race. Read the winner's lock_acquired
+        // so the caller waits the right amount of time instead of using the stale timestamp.
+        const current = this.#lockGetQuery .get(key)                                         
+        if (current !== undefined) {
+          return current.lock_acquired
+        }
+      }
+
+      return lockedAt
     } catch (err) {
       process.emitWarning(err         )
+      return 'unavailable'
+    }
+  }
+
+  #updateLockTimeout(duration        )       {
+    // EMA of mean and variance (Welford-style), clamped to [10ms, 1s].
+    // Timeout = mean * 1.2 + 3 * stddev: 20% base margin plus 3 standard
+    // deviations to accommodate timing variability.
+    const alpha = 0.2
+    const diff = duration - this.#lockMean
+    this.#lockMean += alpha * diff
+    this.#lockVar = (1 - alpha) * (this.#lockVar + alpha * diff * diff)
+    this.#lockTimeout = Math.max(
+      10,
+      Math.min(1_000, Math.ceil(this.#lockMean * 1.2 + Math.sqrt(this.#lockVar) * 3)),
+    )
+  }
+
+  // Wait for another process to complete, then check for their result.
+  // If no result found, take over by calling valueSelector ourselves.
+  // selfPromise is the exact promise stored in #dedupe, used for identity checks
+  // to avoid double valueSelector calls after delete()+get() races.
+  async #waitForValue(args   , key        , lockedAt        , selfPromise            )             {
+    // Loop: wait for lock holder to write a value, retry if lock was stolen by another process.
+    for (let retries = 0; retries < 2 && this.#dedupe.get(key) === selfPromise; retries++) {
+      // Wait for estimated completion: locked_at + our EMA-based timeout.
+      const waitTime = Math.max(0, lockedAt + this.#lockTimeout - Date.now())
+      if (waitTime > 0) {
+        // Add 20% jitter to reduce thundering herd on contention
+        await delay(waitTime + Math.floor(Math.random() * waitTime * 0.2), undefined, {
+          ref: false,
+        })
+      }
+
+      // Check if the lock holder wrote a value
+      try {
+        const row = this.#getQuery?.get(key, Date.now())                           
+        if (row !== undefined) {
+          if (this.#dedupe.get(key) === selfPromise) {
+            this.#dedupe.delete(key)
+          }
+          const entry = this.#loadRow(key, row)
+          this.#memory?.set(key, entry)
+          return entry.value
+        }
+      } catch (err) {
+        process.emitWarning(err         )
+      }
+
+      // Try to acquire lock for takeover
+      const lockResult = this.#tryAcquireLock(key)
+      if (typeof lockResult === 'number') {
+        // Another process holds the lock — wait for them
+        lockedAt = lockResult
+      } else {
+        // We acquired the lock or lock is unavailable — do the work
+        break
+      }
+    }
+
+    {
+      const promise = this.#dedupe.get(key)
+      if (promise !== undefined && promise !== selfPromise) {
+        return promise
+      }
+    }
+
+    try {
+      const res = this.#fetch(args)
+      const value = res.async ? await res.value : res.value
+      if (this.#dedupe.get(key) === selfPromise) {
+        this.#set(key, value)
+      }
+      return value
+    } catch (err) {
+      if (this.#dedupe.get(key) === selfPromise) {
+        this.#dedupe.delete(key)
+      }
+      throw 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.0",
+  "version": "2.0.2",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -17,16 +17,18 @@
     "build": "rimraf lib && tsc && amaroc ./src/index.ts && mv src/index.js lib/ && amaroc ./src/memory.ts && mv src/memory.js lib/",
     "prepublishOnly": "yarn build",
     "typecheck": "tsc --noEmit",
-    "test": "node --test && yarn build",
-    "test:ci": "node --test && yarn build",
-    "test:coverage": "node --test --experimental-test-coverage --test-coverage-include=src/index.ts --test-coverage-include=src/memory.ts --test-coverage-lines=90 --test-coverage-branches=90 --test-coverage-functions=100"
+    "test": "node --test '**/*.test.js' && yarn build",
+    "test:ci": "node --test '**/*.test.js' && yarn build",
+    "test:types": "tsd",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-include=src/index.ts --test-coverage-include=src/memory.ts --test-coverage-lines=90 --test-coverage-branches=90 --test-coverage-functions=100 '**/*.test.js'"
   },
   "devDependencies": {
     "@types/node": "^25.2.3",
     "amaroc": "^1.0.1",
     "oxlint-tsgolint": "^0.13.0",
     "rimraf": "^6.1.3",
+    "tsd": "^0.33.0",
     "typescript": "^5.9.3"
   },
-  "gitHead": "05f9f940c3b262e4c5431c953ac93bc159ade0a0"
+  "gitHead": "f6592f0be62fecc161237610ae6454ec6585548b"
 }