@nxtedition/cache 2.1.6 → 2.1.8

package/README.md

@@ -1,15 +1,17 @@
 # @nxtedition/cache
 
-An async cache with SQLite persistence, in-memory LRU, stale-while-revalidate, and automatic request deduplication.
+A two-tier async cache with SQLite persistence, in-memory LRU, stale-while-revalidate, cross-process deduplication, and automatic request deduplication.
 
 ## Features
 
-- **Two-tier storage**: In-memory LRU cache backed by SQLite on disk
-- **Stale-while-revalidate**: Serve stale data while refreshing in the background
-- **Request deduplication**: Concurrent fetches for the same key share a single in-flight request
-- **Async value resolution**: Transparently fetches missing values via a user-defined `valueSelector`
-- **Buffer support**: Store and retrieve binary data (Buffer, Uint8Array) alongside JSON values
-- **Size-bounded SQLite**: Configurable max database size with automatic eviction of oldest entries
+- **Two-tier storage** — In-memory LRU cache backed by SQLite on disk
+- **Stale-while-revalidate** — Serve stale data synchronously while refreshing in the background
+- **Request deduplication** — Concurrent fetches for the same key share a single in-flight request
+- **Cross-process locking** — SQLite-based distributed locks prevent redundant work across processes/threads
+- **Async value resolution** — Transparently fetches missing values via a user-defined `valueSelector`
+- **Binary support** — Store and retrieve `Buffer` / `Uint8Array` alongside JSON values
+- **Size-bounded storage** — Configurable max database size with automatic eviction of oldest entries
+- **Custom serialization** — Pluggable `serialize`/`deserialize` for non-JSON value types
 
 ## Usage
 
@@ -19,14 +21,13 @@ import { Cache } from '@nxtedition/cache'
 const cache = new Cache(
   './my-cache.db', // SQLite file path, or ':memory:'
   async (id: string) => {
-    // fetch the value for this key
     const res = await fetch(`https://api.example.com/items/${id}`)
     return res.json()
   },
   (id: string) => id, // keySelector: derive cache key from arguments
   {
-    ttl: 60_000, // 60s before value is considered stale
-    stale: 30_000, // serve stale for 30s while revalidating
+    ttl: 60_000, // 60 s before value is considered stale
+    stale: 30_000, // serve stale for 30 s while revalidating
   },
 )
 
@@ -43,23 +44,25 @@ if (result.async) {
 
 ## API
 
-### `new Cache(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`          | `CacheOptions<V>`              | Optional configuration                        |
+| Parameter       | Type                               | Description                                   |
+| --------------- | ---------------------------------- | --------------------------------------------- |
+| `location`      | `string`                           | SQLite database path, or `':memory:'`         |
+| `valueSelector` | `(...args) => V \| PromiseLike<V>` | Function to fetch a value on cache miss       |
+| `keySelector`   | `(...args) => string`              | Function to derive a cache key from arguments |
+| `opts`          | `CacheOptions<V>`                  | Optional configuration                        |
 
-#### Options
+#### `CacheOptions`
 
-| Option     | Type                               | Default                              | Description                                                                              |
-| ---------- | ---------------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------- |
-| `ttl`      | `number \| (value, key) => number` | `MAX_SAFE_INTEGER`                   | Time-to-live in milliseconds. After this, the entry is stale.                            |
-| `stale`    | `number \| (value, key) => number` | `MAX_SAFE_INTEGER`                   | Stale-while-revalidate window in milliseconds. After `ttl + stale`, the entry is purged. |
-| `memory`   | `MemoryOptions \| false \| null`   | `{ maxSize: 16MB, maxCount: 16384 }` | In-memory cache options, or `false`/`null` to disable in-memory caching.                 |
-| `database` | `DatabaseOptions \| false \| null` | `{ timeout: 20, maxSize: 256MB }`    | SQLite options, or `false`/`null` to disable persistence.                                |
+| Option       | Type                               | Default                               | Description                                                                    |
+| ------------ | ---------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------ |
+| `ttl`        | `number \| (value, key) => number` | `MAX_SAFE_INTEGER`                    | Time-to-live in milliseconds. After this, the entry is stale.                  |
+| `stale`      | `number \| (value, key) => number` | `MAX_SAFE_INTEGER`                    | Stale-while-revalidate window in ms. After `ttl + stale`, the entry is purged. |
+| `memory`     | `MemoryOptions \| false \| null`   | `{ maxSize: 16MB, maxCount: 16384 }`  | In-memory cache config, or `false`/`null` to disable.                          |
+| `database`   | `DatabaseOptions \| false \| null` | `{ timeout: 20, maxSize: 128MB }`     | SQLite config, or `false`/`null` to disable persistence.                       |
+| `lock`       | `LockOptions \| false \| null`     | `{ minTimeout: 1, maxTimeout: 1000 }` | Cross-process lock config, or `false`/`null` to disable.                       |
+| `serializer` | `Serializer<V>`                    | JSON + ArrayBufferView passthrough    | Custom `{ serialize, deserialize }` for value encoding.                        |
 
 #### `MemoryOptions`
 
@@ -73,26 +76,42 @@ if (result.async) {
 | Option    | Type     | Default                      | Description                                                       |
 | --------- | -------- | ---------------------------- | ----------------------------------------------------------------- |
 | `timeout` | `number` | `20`                         | SQLite busy timeout in milliseconds.                              |
-| `maxSize` | `number` | `256 * 1024 * 1024` (256 MB) | Maximum database file size. Oldest entries are evicted when full. |
+| `maxSize` | `number` | `128 * 1024 * 1024` (128 MB) | Maximum database file size. Oldest entries are evicted when full. |
+
+#### `LockOptions`
+
+Cross-process locking prevents multiple processes from computing the same value simultaneously. The lock timeout is adaptive — it uses an exponential moving average (EMA) of `valueSelector` durations to estimate how long to wait before taking over a lock.
+
+| Option       | Type     | Default | Description                                                                |
+| ------------ | -------- | ------- | -------------------------------------------------------------------------- |
+| `minTimeout` | `number` | `1`     | Minimum lock timeout in ms. Also the starting timeout before EMA warms up. |
+| `maxTimeout` | `number` | `1000`  | Maximum lock timeout in ms. Caps the EMA-derived timeout.                  |
+
+#### `Serializer<V>`
+
+| Method        | Signature                                      | Description                 |
+| ------------- | ---------------------------------------------- | --------------------------- |
+| `serialize`   | `(value: V) => Buffer \| Uint8Array \| string` | Encode a value for storage. |
+| `deserialize` | `(data: Buffer \| string) => V`                | Decode a stored value.      |
+
+The default serializer passes `ArrayBufferView` values through as-is and uses `JSON.stringify`/`JSON.parse` for everything else.
 
 ### `CacheResult<V>`
 
 Both `get()` and `peek()` return a `CacheResult<V>`, a discriminated union on the `async` property:
 
-| `async` | `value`          | Meaning                                                                                                                                                                             |
-| ------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `false` | `V \| undefined` | Cache hit — the value is available synchronously. Also returned for stale entries (a background refresh is triggered automatically). `undefined` when `peek()` has no cached entry. |
-| `true`  | `Promise<V>`     | Cache miss — `value` is a `Promise` that resolves when the `valueSelector` completes.                                                                                               |
+| `async` | `value`          | Meaning                                                                                                                                                               |
+| ------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `false` | `V \| undefined` | Cache hit — the value is available synchronously. Also returned for stale entries (a background refresh is triggered). `undefined` when `peek()` has no cached entry. |
+| `true`  | `Promise<V>`     | Cache miss — `value` is a `Promise` that resolves when the `valueSelector` completes.                                                                                 |
 
 ```ts
 const result = cache.get('key')
 
 if (result.async) {
-  // miss — await the fetch
-  const value = await result.value
+  const value = await result.value // miss — await the fetch
 } else {
-  // hit (fresh or stale) — use directly
-  const value = result.value
+  const value = result.value // hit (fresh or stale) — use directly
 }
 ```
 
@@ -100,61 +119,85 @@ if (result.async) {
 
 #### `cache.get(...args): CacheResult<V>`
 
-Returns a cached value or triggers a fetch on cache miss.
+Returns a cached value or triggers a fetch on cache miss. If the entry is stale and the `valueSelector` is async, returns the stale value synchronously while a background refresh runs.
 
 #### `cache.peek(...args): CacheResult<V>`
 
-Same as `get()` but does **not** trigger a refresh on cache miss. Returns `{ value: undefined, async: false }` for missing entries.
+Same as `get()` but does **not** trigger a refresh on cache miss or stale entry. Returns `{ value: undefined, async: false }` for missing/expired entries, or the stale value if within the stale window.
 
-#### `cache.refresh(...args): Promise<V>`
+#### `cache.refresh(...args): CacheResult<V>`
 
-Triggers a fetch via `valueSelector` regardless of cache state. If a fetch for the same key is already in-flight (from a prior `get()` or `refresh()`), the existing promise is returned instead of starting a new one.
+Forces a new fetch via `valueSelector` regardless of cache state. Unlike `get()`, concurrent `refresh()` calls for the same key do **not** deduplicate — each call invokes the `valueSelector`. However, `get()` calls during a pending `refresh()` will return the in-flight promise.
 
 #### `cache.delete(...args): void`
 
-Remove an entry from the cache. The cache key is derived from `args` via the `keySelector`, just like `get()` and `refresh()`. Also cancels any in-flight deduplication for that key, meaning a pending fetch will not write its result to the cache.
+Remove an entry from both memory and SQLite. Also cancels any in-flight deduplication for that key — a pending fetch will still resolve for its callers, but the result is **not** written to the cache.
 
 #### `cache.purgeStale(): void`
 
-Remove all expired entries from both the in-memory cache and SQLite.
+Remove all expired entries (past `ttl + stale`) from both the in-memory cache and SQLite. Also cleans up stale lock rows older than 1 hour and runs `PRAGMA wal_checkpoint(TRUNCATE)` + `PRAGMA optimize`.
 
 #### `cache.close(): void`
 
-Close the SQLite database and release resources.
+Close the SQLite database and release resources. Clears all in-flight deduplication. Operations after `close()` throw.
+
+#### `cache.stats`
+
+Returns runtime statistics:
+
+```ts
+{
+  lock: { timeout, mean, stddev } | undefined,
+  dedupe: { size },
+  memory: { size, maxSize, count, maxCount } | undefined,
+  database: { location, size } | undefined,
+}
+```
 
 ## Deduplication
 
-Concurrent calls to `get()` or `refresh()` for the same key share a single in-flight Promise. The `valueSelector` is called only once, and all callers receive the same resolved value.
+Concurrent calls to `get()` for the same key share a single in-flight `Promise`. The `valueSelector` is called only once:
 
 ```ts
 // valueSelector is called once, both promises resolve to the same value
 const [a, b] = await Promise.all([cache.get('key').value, cache.get('key').value])
 ```
 
-If a fetch fails, the deduplication entry is cleaned up and subsequent calls will retry.
+If a fetch fails, the deduplication entry is cleaned up and subsequent calls retry.
 
 Calling `cache.delete(key)` while a fetch is in-flight invalidates the deduplication entry. The pending promise still resolves for its callers, but the result is **not** written to the cache.
 
+`refresh()` does **not** deduplicate with itself — each call starts a new fetch. However, `get()` calls see the most recent pending promise.
+
 ## Stale-While-Revalidate
 
-When an entry's TTL has expired but is still within the stale window (`ttl + stale`), `get()` returns the stale value synchronously (`async: false`) while triggering a background refresh.
+When an entry's TTL has expired but is still within the stale window, `get()` returns the stale value synchronously (`async: false`) and triggers a background refresh (when the `valueSelector` is async). If the refresh fails, the stale value is preserved.
 
 Once the stale window expires, the entry is purged entirely and the next `get()` returns `async: true`.
 
 ```
 |--- ttl ---|--- stale ---|
      fresh      stale       expired
+       ↓          ↓           ↓
+  sync hit    sync hit     async miss
+              + bg refresh
 ```
 
+## Cross-Process Locking
+
+When multiple processes or threads share the same SQLite database, the lock mechanism prevents redundant `valueSelector` calls. Process A acquires a lock, computes the value, and writes it. Process B sees the lock, waits for the estimated completion time (EMA-based), then reads the value from SQLite.
+
+If the lock holder crashes, the lock becomes stale after `3 × lockTimeout` and another process steals it.
+
 ## Off-Peak Purge
 
-All cache instances listen for messages on the `nxt:offPeak` BroadcastChannel. When a message is received, `purgeStale()` is called on every active instance, allowing coordinated cleanup during low-traffic periods.
+All cache instances listen on the `nxt:offPeak` `BroadcastChannel`. When a message is received, `purgeStale()` is called on every active instance, enabling coordinated cleanup during low-traffic periods.
 
 ## Scripts
 
 ```sh
-npm test                # run tests
-npm run test:coverage   # run tests with branch coverage report (90%+ enforced)
-npm run typecheck       # type-check without emitting
-npm run build           # build for publishing
+yarn test               # run tests
+yarn test:coverage      # run tests with coverage report (90%+ enforced)
+yarn typecheck          # type-check without emitting
+yarn build              # build for publishing
 ```

package/lib/index.d.ts

@@ -7,6 +7,7 @@ export interface DatabaseOptions {
 }
 export interface LockOptions {
     minTimeout?: number;
+    maxTimeout?: number;
 }
 export interface Serializer<V> {
     serialize: (value: V) => Buffer | Uint8Array | string;
@@ -28,9 +29,9 @@ export type CacheResult<V> = {
     async: true;
 };
 declare global {
-    var __nxt_cache: {
+    var __nxt_cache: WeakRef<{
         stats: Cache['stats'];
-    }[];
+    }>[];
 }
 export declare class Cache<V = unknown, A extends unknown[] = [string]> extends EventEmitter {
     #private;
@@ -55,6 +56,7 @@ export declare class Cache<V = unknown, A extends unknown[] = [string]> extends
             size: number | undefined;
         } | undefined;
     };
+    [Symbol.dispose](): void;
     close(): void;
     get(...args: A): CacheResult<V>;
     peek(...args: A): CacheResult<V>;

package/lib/index.js

@@ -39,6 +39,7 @@ const dbs = new Set                 ()
  
 
                               
+                     
                      
  
 
@@ -73,7 +74,7 @@ const defaultSerializer                  = {
 
                 
                                     
-                                              
+                                                       
  
 
 const VERSION = 5
@@ -97,8 +98,9 @@ export class Cache                                              extends EventEmi
   #lockTimeout         = 10
   #lockMinTimeout         = 1
   #lockMaxTimeout         = 1_000
-
+  #flushHandle                          = null
   #location        
+  #databaseTimeout         = 20
   #database                      = null
   #getQuery                       = null
   #delQuery                       = null
@@ -177,6 +179,12 @@ export class Cache                                              extends EventEmi
         this.#lockTimeout = this.#lockMinTimeout
         this.#lockMean = this.#lockTimeout / 1.2
       }
+      if (opts.lock.maxTimeout !== undefined) {
+        if (typeof opts.lock.maxTimeout !== 'number') {
+          throw new TypeError('lock.maxTimeout must be a number')
+        }
+        this.#lockMaxTimeout = Math.max(this.#lockMinTimeout, opts.lock.maxTimeout)
+      }
     }
 
     if (opts?.serializer !== undefined) {
@@ -198,9 +206,9 @@ export class Cache                                              extends EventEmi
     for (let n = 0; opts?.database !== null && opts?.database !== false; n++) {
       try {
         const maxSize = opts?.database?.maxSize ?? 128 * 1024 * 1024
-        const timeout = opts?.database?.timeout ?? 20
+        this.#databaseTimeout = opts?.database?.timeout ?? 20
 
-        this.#database ??= new DatabaseSync(location, { timeout })
+        this.#database ??= new DatabaseSync(location, { timeout: this.#databaseTimeout })
 
         this.#database.exec(`
           PRAGMA journal_mode = WAL;
@@ -260,6 +268,8 @@ export class Cache                                              extends EventEmi
         this.#pageSizeQuery = this.#database.prepare('PRAGMA page_size')
         break
       } catch (err) {
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100)
+
         if (n >= 16) {
           this.#database?.close()
           this.#database = null
@@ -285,7 +295,7 @@ export class Cache                                              extends EventEmi
     dbs.add(this)
 
     globalThis.__nxt_cache ??= []
-    globalThis.__nxt_cache.push(this)
+    globalThis.__nxt_cache.push(new WeakRef(this))
   }
 
   get stats() {
@@ -317,7 +327,16 @@ export class Cache                                              extends EventEmi
     }
   }
 
+  [Symbol.dispose]() {
+    this.close()
+  }
+
   close()       {
+    while (this.#flushHandle) {
+      clearImmediate(this.#flushHandle)
+      this.#flush()
+    }
+
     this.#closed = true
     this.#dedupe.clear()
     dbs.delete(this)
@@ -336,7 +355,8 @@ export class Cache                                              extends EventEmi
     this.#database?.close()
     this.#database = null
 
-    const idx = globalThis.__nxt_cache?.indexOf(this) ?? -1
+    globalThis.__nxt_cache = globalThis.__nxt_cache?.filter((ref) => ref.deref() != null) ?? []
+    const idx = globalThis.__nxt_cache?.findIndex((ref) => ref.deref() === this) ?? -1
     if (idx !== -1) {
       globalThis.__nxt_cache.splice(idx, 1)
     }
@@ -374,14 +394,35 @@ export class Cache                                              extends EventEmi
     if (this.#closed) {
       throw new Error('cache is closed')
     }
+    this.#memory?.purgeStale(Date.now())
+    this.#database?.exec('PRAGMA busy_timeout = 5000')
     try {
-      this.#memory?.purgeStale(Date.now())
-      this.#purgeStaleQuery?.run(Date.now())
-      this.#lockPurgeQuery?.run(Date.now() - 3_600_000)
-      this.#database?.exec('PRAGMA wal_checkpoint(TRUNCATE)')
-      this.#database?.exec('PRAGMA optimize')
-    } catch (err) {
-      this.#emitError(err         )
+      try {
+        this.#purgeStaleQuery?.run(Date.now())
+      } catch (err) {
+        this.#emitError(err         )
+      }
+      try {
+        this.#lockPurgeQuery?.run(Date.now() - 3_600_000)
+      } catch (err) {
+        this.#emitError(err         )
+      }
+      try {
+        this.#database?.exec('PRAGMA wal_checkpoint(TRUNCATE)')
+      } catch (err) {
+        this.#emitError(err         )
+      }
+      try {
+        this.#database?.exec('PRAGMA optimize')
+      } catch (err) {
+        this.#emitError(err         )
+      }
+    } finally {
+      try {
+        this.#database?.exec(`PRAGMA busy_timeout = ${this.#databaseTimeout}`)
+      } catch (err) {
+        this.#emitError(err         )
+      }
     }
   }
 
@@ -534,12 +575,12 @@ export class Cache                                              extends EventEmi
 
     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')
+      throw new TypeError('ttl must be undefined, null, or a non-negative finite number')
     }
 
     const staleValue = Math.min(MAX_DURATION, this.#stale(value, key) ?? Infinity)
     if (!Number.isFinite(staleValue) || staleValue < 0) {
-      throw new TypeError('stale must be nully or a positive integer')
+      throw new TypeError('stale must be undefined, null, or a non-negative finite number')
     }
 
     const now = Date.now()
@@ -560,15 +601,20 @@ export class Cache                                              extends EventEmi
     )
     this.#memory?.set(key, entry)
 
-    if (this.#setBatch.length === 0) {
+    if (!this.#flushHandle) {
       this.#memory?.cork()
-      setImmediate(this.#flush)
+      this.#flushHandle = setImmediate(this.#flush)
+    } else if (this.#setBatch.length > 512) {
+      clearImmediate(this.#flushHandle)
+      this.#flush()
     }
 
     this.#setBatch.push({ key, data, ttl, stale })
   }
 
   #flush = () => {
+    this.#flushHandle = null
+
     if (this.#setBatch.length === 0 || this.#closed || this.#database == null) {
       this.#setBatch.length = 0
       this.#memory?.uncork()
@@ -625,7 +671,7 @@ export class Cache                                              extends EventEmi
 
     if (this.#setBatch.length > 0) {
       // If we weren't able to flush the entire batch within the time limit, schedule another flush.
-      setImmediate(this.#flush)
+      this.#flushHandle = setImmediate(this.#flush)
     } else {
       this.#memory?.uncork()
     }
@@ -711,12 +757,11 @@ export class Cache                                              extends EventEmi
     // Timeout = mean * 1.2 + 3 * stddev: 20% base margin plus 3 standard
     // deviations to accommodate timing variability.
     // Winsorize input at mean + 5σ so a single extreme outlier can't blow up the stats.
+    // Floor the stddev at half the mean so the window never collapses to zero
+    // when variance decays (all observations near the mean).
     const alpha = 0.2
-    const clamped = Math.min(
-      duration,
-      this.#lockMean + 5 * Math.sqrt(this.#lockVar),
-      this.#lockMaxTimeout,
-    )
+    const stddev = Math.max(this.#lockMean * 0.5, Math.sqrt(this.#lockVar))
+    const clamped = Math.min(duration, this.#lockMean + 5 * stddev, this.#lockMaxTimeout)
     const diff = clamped - this.#lockMean
     this.#lockMean += alpha * diff
     this.#lockVar = (1 - alpha) * (this.#lockVar + alpha * diff * diff)

package/lib/memory.js

@@ -13,11 +13,6 @@
                  
  
 
-let fastNow = Date.now()
-setInterval(() => {
-  fastNow = Date.now()
-}, 1e3).unref()
-
 export class MemoryCache    {
   #map                                   = new Map()
   #arr                             = []
@@ -52,7 +47,7 @@ export class MemoryCache    {
     this.#map.set(key, entry)
     entry.key = key
     entry.index = this.#arr.push(entry) - 1
-    entry.counter = fastNow
+    entry.counter = performance.now()
 
     this.#size += entry.size ?? 0
     this.#count += 1
@@ -76,7 +71,7 @@ export class MemoryCache    {
   get(key        ) {
     const entry = this.#map.get(key)
     if (entry != null) {
-      entry.counter = fastNow
+      entry.counter = performance.now()
     }
     return entry
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxtedition/cache",
-  "version": "2.1.6",
+  "version": "2.1.8",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -30,5 +30,5 @@
     "tsd": "^0.33.0",
     "typescript": "^5.9.3"
   },
-  "gitHead": "a7202d8b4d3decaff213576df560e8cd5775db37"
+  "gitHead": "20b962a02ddc295425538b02f1fef1b7b418af70"
 }