@nxtedition/cache 2.1.13 → 2.1.15

package/lib/index.js

@@ -1,235 +1,51 @@
-import { randomUUID } from 'node:crypto'
-import { EventEmitter } from 'node:events'
-import { DatabaseSync,                                        } from 'node:sqlite'
-import { setTimeout as delay } from 'node:timers/promises'
-
-import xxhash from 'xxhash-wasm'
-
-import { getOrCreate } from '@nxtedition/shared'
-
-import { MemoryCache,                                           } from "./memory.js"
-
-                                                
-
-function noop() {}
-
-function maybeToBuffer(value                          )                  {
-  return ArrayBuffer.isView(value)
-    ? Buffer.from(value.buffer, value.byteOffset, value.byteLength)
-    : value
+import { EventEmitter } from 'node:events';
+import { DatabaseSync } from 'node:sqlite';
+import xxhash from 'xxhash-wasm';
+import { getOrCreate } from '@nxtedition/shared';
+import { MemoryCache } from "./memory.js";
+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'
+function isThenable(value) {
+    return value != null && typeof value.then === 'function';
 }
-
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-const dbs = new Set                 ()
-
-                         
-             
-               
-          
- 
-
-                       
-                          
-             
-               
- 
-
-                                  
-                  
-                  
- 
-
-                              
-                     
-                     
- 
-
-                                
-                                                       
-                                           
- 
-
+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) {
-    // eslint-disable-next-line typescript-eslint/no-unsafe-argument
-    return ArrayBuffer.isView(data) ? data : JSON.parse(data)
-  },
-}
-
-                                  
-                                                    
-                                                      
-                                   
-                                       
-                                           
-                            
- 
-
-                            
-                                          
-                                      
-
-                
-                                    
-                                                       
- 
-
-const VERSION = 5
-const MAX_DURATION = 365000000e3
-const HASHER = await xxhash()
-
-export class Cache                                              extends EventEmitter {
-  #memory                       
-  #dedupe = new Map                    ()
-  #closed = false
-
-  #valueSelector                                    
-  #keySelector                        
-
-  #ttl                                 
-  #stale                                 
-  #serializer               
-
-  #lockId                = null
-  #lockArray                    = null
-  #lockSet                    
-  #lockVar = 0
-  #lockMean         = 5
-  #lockTimeout         = 10
-  #lockMinTimeout         = 1
-  #lockMaxTimeout         = 1_000
-
-  #flushHandle                          = null
-  #location        
-  #databaseTimeout         = 20
-  #database                      = null
-  #getQuery                       = null
-  #delQuery                       = null
-  #purgeStaleQuery                       = null
-  #evictQuery                       = null
-  #lockAcquireQuery                       = null
-  #lockStealQuery                       = null
-  #lockGetQuery                       = null
-  #lockPurgeQuery                       = null
-  #pageCountQuery                       = null
-  #pageSizeQuery                       = null
-  #setQuery                       = null
-  #setBatch                                                                                        =
-    []
-
-  #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')
-    }
-    this.#location = location
-
-    if (valueSelector !== undefined && typeof valueSelector !== 'function') {
-      throw new TypeError('valueSelector must be a function')
-    }
-    this.#valueSelector = valueSelector ?? (() => undefined                )
-
-    if (keySelector !== undefined && typeof keySelector !== 'function') {
-      throw new TypeError('keySelector must be a function')
-    }
-    this.#keySelector = keySelector ?? ((...args   ) => JSON.stringify(args))
-
-    if (typeof opts?.ttl === 'number' || opts?.ttl === undefined) {
-      const ttl = opts?.ttl ?? Number.MAX_SAFE_INTEGER
-      this.#ttl = (_val   , _key        ) => ttl
-    } else if (typeof opts?.ttl === 'function') {
-      this.#ttl = opts.ttl
-    } else {
-      throw new TypeError('ttl must be a undefined, number or a function')
-    }
-
-    if (typeof opts?.stale === 'number' || opts?.stale === undefined) {
-      const stale = opts?.stale ?? Number.MAX_SAFE_INTEGER
-      this.#stale = (_val   , _key        ) => stale
-    } else if (typeof opts?.stale === 'function') {
-      this.#stale = opts.stale
-    } else {
-      throw new TypeError('stale must be a undefined, number or a function')
-    }
-
-    if (opts?.lock === false || opts?.lock === null) {
-      this.#lockId = null
-      this.#lockArray = null
-      this.#lockSet = null
-      this.#lockMinTimeout = -1
-      this.#lockTimeout = -1
-      this.#lockMean = -1
-    } else {
-      if (opts?.lock !== undefined) {
-        if (typeof opts.lock !== 'object' || opts.lock === null) {
-          throw new TypeError('lock must be an object')
-        }
-        if (opts.lock.minTimeout !== undefined) {
-          if (typeof opts.lock.minTimeout !== 'number') {
-            throw new TypeError('lock.minTimeout must be a number')
-          }
-          this.#lockMinTimeout = Math.max(0, opts.lock.minTimeout)
-          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)
-        }
-      }
-
-      this.#lockId = randomUUID()
-      this.#lockArray = new Int32Array(getOrCreate(`__@nxtedition/cache/${location}`, 8 + 1024))
-      this.#lockSet = new Set()
-    }
-
-    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)
-
-    for (let n = 0; opts?.database !== null && opts?.database !== false; n++) {
-      try {
-        const maxSize = opts?.database?.maxSize ?? 128 * 1024 * 1024
-        this.#databaseTimeout = opts?.database?.timeout ?? 20
-
-        this.#database ??= new DatabaseSync(location, { timeout: this.#databaseTimeout })
-
-        this.#database.exec(`
+const defaultSerializer = {
+    serialize(value) {
+        return ArrayBuffer.isView(value) ? value : JSON.stringify(value);
+    },
+    deserialize(data) {
+        // eslint-disable-next-line typescript-eslint/no-unsafe-argument
+        return ArrayBuffer.isView(data) ? data : JSON.parse(data);
+    },
+};
+const VERSION = 5;
+const MAX_DURATION = 365000000e3;
+const HASHER = await xxhash();
+class DatabaseShard {
+    location;
+    databaseTimeout = 20;
+    database = null;
+    getQuery = null;
+    delQuery = null;
+    purgeStaleQuery = null;
+    evictQuery = null;
+    pageCountQuery = null;
+    pageSizeQuery = null;
+    setQuery = null;
+    setBatch = [];
+    constructor(location, opts) {
+        this.location = location;
+        for (let n = 0; true; n++) {
+            try {
+                const maxSize = opts?.maxSize ?? 128 * 1024 * 1024;
+                this.databaseTimeout = opts?.timeout ?? 20;
+                this.database ??= new DatabaseSync(location, { timeout: this.databaseTimeout });
+                this.database.exec(`
           PRAGMA journal_mode = WAL;
           PRAGMA synchronous = OFF;
           PRAGMA wal_autocheckpoint = 10000;
@@ -246,697 +62,565 @@ export class Cache                                              extends EventEmi
           ) WITHOUT ROWID;
 
           CREATE INDEX IF NOT EXISTS cache_v${VERSION}_stale_idx ON cache_v${VERSION}(stale);
-        `)
-
-        this.#getQuery = this.#database.prepare(
-          `SELECT val, ttl, stale FROM cache_v${VERSION} WHERE key = ? AND stale > ?`,
-        )
-        this.#setQuery = this.#database.prepare(
-          `INSERT OR REPLACE INTO cache_v${VERSION} (key, val, ttl, stale) VALUES (?, ?, ?, ?)`,
-        )
-        this.#delQuery = this.#database.prepare(`DELETE FROM cache_v${VERSION} WHERE key = ?`)
-        this.#purgeStaleQuery = this.#database.prepare(
-          `DELETE FROM cache_v${VERSION} WHERE stale <= ?`,
-        )
-        this.#evictQuery = this.#database.prepare(
-          `DELETE FROM cache_v${VERSION} WHERE key IN (SELECT key FROM cache_v${VERSION} ORDER BY stale ASC LIMIT ?)`,
-        )
-
-        if (this.#lockId != null) {
-          this.#database.exec(`
-            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
-            );
-          `)
-
-          // 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 = ?`,
-          )
-          // 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) {
-        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100)
-
-        if (n >= 16) {
-          this.#database?.close()
-          this.#database = null
-
-          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.#pageCountQuery = null
-          this.#pageSizeQuery = null
-
-          this.#emitError(err         )
-          break
+        `);
+                this.getQuery = this.database.prepare(`SELECT val, ttl, stale FROM cache_v${VERSION} WHERE key = ? AND stale > ?`);
+                this.setQuery = this.database.prepare(`INSERT OR REPLACE INTO cache_v${VERSION} (key, val, ttl, stale) VALUES (?, ?, ?, ?)`);
+                this.delQuery = this.database.prepare(`DELETE FROM cache_v${VERSION} WHERE key = ?`);
+                this.purgeStaleQuery = this.database.prepare(`DELETE FROM cache_v${VERSION} WHERE stale <= ?`);
+                this.evictQuery = this.database.prepare(`DELETE FROM cache_v${VERSION} WHERE key IN (SELECT key FROM cache_v${VERSION} ORDER BY stale ASC LIMIT ?)`);
+                this.pageCountQuery = this.database.prepare('PRAGMA page_count');
+                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[Symbol.dispose]();
+                    throw err;
+                }
+            }
         }
-      }
-    }
-
-    dbs.add(this)
-
-    globalThis.__nxt_cache ??= []
-    globalThis.__nxt_cache.push(new WeakRef(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:
-        this.#lockTimeout >= 0
-          ? {
-              timeout: this.#lockTimeout,
-              mean: this.#lockMean,
-              stddev: Math.sqrt(this.#lockVar),
-            }
-          : undefined,
-      dedupe: { size: this.#dedupe.size },
-      memory: this.#memory?.stats,
-      database,
-    }
-  }
-
-  [Symbol.dispose]() {
-    this.close()
-  }
-
-  close()       {
-    while (this.#flushHandle) {
-      clearImmediate(this.#flushHandle)
-      this.#flush()
-    }
-
-    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.#pageCountQuery = null
-    this.#pageSizeQuery = null
-    this.#database?.close()
-    this.#database = null
-
-    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)
-    }
-  }
-
-  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   )       {
-    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')
-    }
-    this.#memory?.purgeStale(Date.now())
-    this.#database?.exec('PRAGMA busy_timeout = 5000')
-    try {
-      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         )
-      }
-    }
-  }
-
-  #load(args   , refresh         )                 {
-    const key = this.#keySelector(...args)
-
-    if (typeof key !== 'string' || key.length === 0) {
-      throw new TypeError('keySelector must return a non-empty string')
-    }
-
-    const now = Date.now()
-
-    let cached                            = this.#memory?.get(key)
-
-    if (cached === undefined) {
-      try {
-        const row = this.#getQuery?.get(key, now)                           
-        if (row !== undefined) {
-          const entry = this.#loadRow(key, row)
-          this.#memory?.set(key, entry)
-          cached = entry
-        }
-      } catch (err) {
-        this.#emitError(err         )
-      }
-    }
-
-    if (cached !== undefined) {
-      if (now < cached.ttl) {
-        return { value: cached.value, async: false }
-      }
-
-      if (now >= cached.stale) {
-        // stale-while-revalidate has expired, purge cached value.
-        this.#memory?.delete(key)
-        cached = undefined
-      }
-    }
-
-    if (!refresh) {
-      // peek: return stale value if available, undefined if expired or missing
-      return { value: cached?.value, async: false }
-    }
-
-    {
-      const pending = this.#dedupe.get(key)
-      if (pending !== undefined) {
-        return { async: true, value: pending }
-      }
-    }
-
-    let result                
-    try {
-      result = this.#refresh(args, key)
-    } catch (err) {
-      if (cached !== undefined) {
-        this.#emitError(err         )
-        return { value: cached.value, async: false }
-      }
-      throw err
-    }
-
-    if (result.async && cached !== undefined) {
-      return { value: cached.value, async: false }
-    }
-
-    return result
-  }
-
-  #refresh(args   , key         = this.#keySelector(...args))                 {
-    if (typeof key !== 'string' || key.length === 0) {
-      throw new TypeError('keySelector must return a non-empty string')
-    }
-
-    if (this.#lockId != null) {
-      // 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.
-      let lockIdx = -1
-      let lockVal = 0
-      if (this.#lockArray) {
-        lockIdx = HASHER.h32(key) % this.#lockArray.length
-        lockVal = Atomics.load(this.#lockArray, lockIdx)
-      }
-
-      const lockRes = this.#tryAcquireLock(key, lockIdx)
-
-      if (typeof lockRes === 'number') {
-        const { promise, resolve, reject } = Promise.withResolvers   ()
-        promise.catch(noop)
-        this.#dedupe.set(key, promise)
-        this.#waitForValue(args, key, lockIdx, lockVal, lockRes, promise).then(resolve, reject)
-        return { async: true, value: promise }
-      }
-    }
-
-    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 { async: true, value: promise }
     }
-
-    this.#set(key, res.value)
-    return res
-  }
-
-  #fetch(args   )                                                                  {
-    const startTime = performance.now()
-    const value = this.#valueSelector(...args)
-
-    if (isThenable(value)) {
-      const promise = Promise.resolve(value)
-
-      if (this.#lockId != null) {
-        promise
-          .then(() => {
-            this.#updateLockTimeout(performance.now() - startTime)
-          })
-          .catch(this.#emitError)
-      }
-
-      return {
-        async: true,
-        value: promise,
-      }
+    [Symbol.dispose]() {
+        this.getQuery = null;
+        this.setQuery = null;
+        this.delQuery = null;
+        this.purgeStaleQuery = null;
+        this.evictQuery = null;
+        this.pageCountQuery = null;
+        this.pageSizeQuery = null;
+        this.database?.close();
+        this.database = null;
     }
-
-    if (this.#lockId != null) {
-      this.#updateLockTimeout(performance.now() - startTime)
+}
+export class Cache extends EventEmitter {
+    #memory;
+    #dedupe = new Map();
+    #closed = false;
+    #valueSelector;
+    #keySelector;
+    #ttl;
+    #stale;
+    #serializer;
+    #lockArray;
+    #flushHandle = null;
+    #location;
+    #shards = 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');
+        }
+        this.#location = location;
+        if (valueSelector !== undefined && typeof valueSelector !== 'function') {
+            throw new TypeError('valueSelector must be a function');
+        }
+        this.#valueSelector = valueSelector ?? (() => undefined);
+        if (keySelector !== undefined && typeof keySelector !== 'function') {
+            throw new TypeError('keySelector must be a function');
+        }
+        this.#keySelector = keySelector ?? ((...args) => JSON.stringify(args));
+        if (typeof opts?.ttl === 'number' || opts?.ttl === undefined) {
+            const ttl = opts?.ttl ?? Number.MAX_SAFE_INTEGER;
+            this.#ttl = (_val, _key) => ttl;
+        }
+        else if (typeof opts?.ttl === 'function') {
+            this.#ttl = opts.ttl;
+        }
+        else {
+            throw new TypeError('ttl must be a undefined, number or a function');
+        }
+        if (typeof opts?.stale === 'number' || opts?.stale === undefined) {
+            const stale = opts?.stale ?? Number.MAX_SAFE_INTEGER;
+            this.#stale = (_val, _key) => stale;
+        }
+        else if (typeof opts?.stale === 'function') {
+            this.#stale = opts.stale;
+        }
+        else {
+            throw new TypeError('stale must be a undefined, number or a function');
+        }
+        if (opts?.lock !== undefined && opts.lock !== false && opts.lock !== null) {
+            throw new TypeError('lock must be false, null, or undefined');
+        }
+        if (opts?.lock === false || opts?.lock === null || location === ':memory:') {
+            this.#lockArray = null;
+        }
+        else {
+            this.#lockArray = new Int32Array(getOrCreate(`__@nxtedition/cache/${location}`, 64 * 1024));
+        }
+        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);
+        if (opts?.database === false || opts?.database === null) {
+            this.#shards = null;
+        }
+        else {
+            this.#shards = [];
+            try {
+                if (location === ':memory:') {
+                    this.#shards.push(new DatabaseShard(location, opts?.database));
+                }
+                else {
+                    const count = opts?.database?.shards ?? 4;
+                    for (let n = 0; n < count; n++) {
+                        this.#shards.push(new DatabaseShard(count === 1 ? location : location + '.' + n, {
+                            ...opts?.database,
+                            maxSize: Math.ceil((opts?.database?.maxSize ?? 128 * 1024 * 1024) / count),
+                        }));
+                    }
+                }
+            }
+            catch (err) {
+                for (const shard of this.#shards) {
+                    shard[Symbol.dispose]();
+                }
+                this.#shards = null;
+                this.#emitError(err);
+            }
+        }
+        dbs.add(this);
+        globalThis.__nxt_cache ??= [];
+        globalThis.__nxt_cache.push(new WeakRef(this));
+    }
+    get stats() {
+        let database;
+        if (this.#shards) {
+            let size = 0;
+            try {
+                for (const shard of this.#shards) {
+                    const { page_count } = shard.pageCountQuery.get();
+                    const { page_size } = shard.pageSizeQuery.get();
+                    size += page_count * page_size;
+                }
+            }
+            catch (err) {
+                size = undefined;
+                this.#emitError(err);
+            }
+            database = { location: this.#location, size };
+        }
+        return {
+            dedupe: { size: this.#dedupe.size },
+            memory: this.#memory?.stats,
+            database,
+        };
+    }
+    [Symbol.dispose]() {
+        this.close();
+    }
+    close() {
+        while (this.#flushHandle) {
+            clearImmediate(this.#flushHandle);
+            this.#memory?.cork();
+            this.#flush();
+        }
+        this.#closed = true;
+        this.#dedupe.clear();
+        dbs.delete(this);
+        for (const shard of this.#shards ?? []) {
+            shard[Symbol.dispose]();
+        }
+        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);
+        }
     }
-
-    return { async: false, value }
-  }
-
-  #set(key        , value               )       {
-    if (typeof key !== 'string' || key.length === 0) {
-      throw new TypeError('key must be a non-empty string')
+    get(...args) {
+        if (this.#closed) {
+            throw new Error('cache is closed');
+        }
+        return this.#load(args, true);
     }
-
-    this.#dedupe.delete(key)
-
-    if (value === undefined) {
-      // Slow path... Should not be common...
-      this.#memory?.delete(key)
-      this.#setBatch = this.#setBatch.filter((item) => item.key !== key)
-      try {
-        this.#delQuery?.run(key)
-      } catch (err) {
-        this.#emitError(err         )
-      }
-      return
+    peek(...args) {
+        if (this.#closed) {
+            throw new Error('cache is closed');
+        }
+        return this.#load(args, false);
     }
-
-    const ttlValue = Math.min(MAX_DURATION, this.#ttl(value, key) ?? Infinity)
-    if (!Number.isFinite(ttlValue) || ttlValue < 0) {
-      throw new TypeError('ttl must be undefined, null, or a non-negative finite number')
+    refresh(...args) {
+        if (this.#closed) {
+            throw new Error('cache is closed');
+        }
+        const key = this.#keySelector(...args);
+        if (typeof key !== 'string' || key.length === 0) {
+            throw new TypeError('keySelector must return a non-empty string');
+        }
+        const hash = HASHER.h32(key);
+        if (this.#lockArray) {
+            const idx = hash % this.#lockArray.length;
+            if (Atomics.add(this.#lockArray, idx, 1) >= 0xfffffff) {
+                // Roll back the increment before throwing so we don't leak the slot.
+                if (Atomics.sub(this.#lockArray, idx, 1) === 1) {
+                    Atomics.notify(this.#lockArray, idx);
+                }
+                throw new Error('lock counter overflow');
+            }
+        }
+        return this.#refresh(args, key, hash);
     }
-
-    const staleValue = Math.min(MAX_DURATION, this.#stale(value, key) ?? Infinity)
-    if (!Number.isFinite(staleValue) || staleValue < 0) {
-      throw new TypeError('stale must be undefined, null, or a non-negative finite number')
+    delete(...args) {
+        if (this.#closed) {
+            throw new Error('cache is closed');
+        }
+        const key = this.#keySelector(...args);
+        if (typeof key !== 'string' || key.length === 0) {
+            throw new TypeError('key must be a non-empty string');
+        }
+        const hash = HASHER.h32(key);
+        this.#set(key, undefined, hash);
     }
-
-    const now = Date.now()
-    const ttl = now + ttlValue
-    const stale = ttl + staleValue
-
-    if (stale <= now) {
-      return
+    purgeStale() {
+        if (this.#closed) {
+            throw new Error('cache is closed');
+        }
+        this.#memory?.purgeStale(Date.now());
+        for (const shard of this.#shards ?? []) {
+            shard.database?.exec('PRAGMA busy_timeout = 5000');
+            try {
+                try {
+                    shard.purgeStaleQuery?.run(Date.now());
+                }
+                catch (err) {
+                    this.#emitError(err);
+                }
+                try {
+                    shard.database?.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+                }
+                catch (err) {
+                    this.#emitError(err);
+                }
+                try {
+                    shard.database?.exec('PRAGMA optimize');
+                }
+                catch (err) {
+                    this.#emitError(err);
+                }
+            }
+            finally {
+                try {
+                    shard.database?.exec(`PRAGMA busy_timeout = ${shard.databaseTimeout}`);
+                }
+                catch (err) {
+                    this.#emitError(err);
+                }
+            }
+        }
     }
-
-    const data = this.#serializer.serialize(value)
-    const entry = this.#createEntry(
-      key,
-      value,
-      ttl,
-      stale,
-      ArrayBuffer.isView(data) ? data.byteLength : data.length * 2,
-    )
-    this.#memory?.set(key, entry)
-
-    if (!this.#flushHandle) {
-      this.#memory?.cork()
-      this.#flushHandle = setImmediate(this.#flush)
-    } else if (this.#setBatch.length > 512) {
-      clearImmediate(this.#flushHandle)
-      this.#flush()
+    #load(args, refresh) {
+        const key = this.#keySelector(...args);
+        if (typeof key !== 'string' || key.length === 0) {
+            throw new TypeError('keySelector must return a non-empty string');
+        }
+        const now = Date.now();
+        const hash = HASHER.h32(key);
+        let cached = this.#memory?.get(key);
+        if (cached === undefined) {
+            try {
+                const shard = this.#shards ? this.#shards[hash % this.#shards.length] : null;
+                const row = shard?.getQuery?.get(key, now);
+                if (row !== undefined) {
+                    const entry = this.#loadRow(key, row);
+                    this.#memory?.set(key, entry);
+                    cached = entry;
+                }
+            }
+            catch (err) {
+                this.#emitError(err);
+            }
+        }
+        if (cached !== undefined) {
+            if (now < cached.ttl) {
+                return { value: cached.value, async: false };
+            }
+            if (now >= cached.stale) {
+                // stale-while-revalidate has expired, purge cached value.
+                this.#memory?.delete(key);
+                cached = undefined;
+            }
+        }
+        if (!refresh) {
+            // peek: return stale value if available, undefined if expired or missing
+            return { value: cached?.value, async: false };
+        }
+        {
+            const pending = this.#dedupe.get(key);
+            if (pending !== undefined) {
+                return { async: true, value: pending };
+            }
+        }
+        const idx = this.#lockArray ? hash % this.#lockArray.length : -1;
+        if (cached !== undefined) {
+            try {
+                const val = this.#lockArray ? Atomics.compareExchange(this.#lockArray, idx, 0, 1) : 0;
+                if (val === 0) {
+                    const result = this.#refresh(args, key, hash);
+                    if (!result.async) {
+                        return result;
+                    }
+                    else {
+                        result.value.catch((err) => {
+                            this.#emitError(err);
+                        });
+                    }
+                }
+            }
+            catch (err) {
+                this.#emitError(err);
+            }
+            return { async: false, value: cached.value };
+        }
+        while (this.#lockArray) {
+            const val = Atomics.compareExchange(this.#lockArray, idx, 0, 1);
+            if (val === 0) {
+                break;
+            }
+            const { async, value } = Atomics.waitAsync(this.#lockArray, idx, val, 1e3);
+            if (async) {
+                return {
+                    async: true,
+                    value: value.then(() => this.#load(args, true).value),
+                };
+            }
+        }
+        return this.#refresh(args, key, hash);
     }
-
-    this.#setBatch.push({ key, data, ttl, stale, hash: this.#lockArray ? HASHER.h32(key) : -1 })
-  }
-
-  #flush = () => {
-    this.#flushHandle = null
-
-    if (this.#setBatch.length === 0 || this.#closed || this.#database == null) {
-      this.#setBatch.length = 0
-      this.#memory?.uncork()
-      return
+    #release(hash) {
+        if (!this.#lockArray) {
+            return;
+        }
+        const idx = hash % this.#lockArray.length;
+        if (Atomics.sub(this.#lockArray, idx, 1) === 1) {
+            Atomics.notify(this.#lockArray, idx);
+        }
     }
-
-    try {
-      const startTime = performance.now()
-      for (let retryCount = 0; true; retryCount++) {
-        let n = 0
+    #refresh(args, key, hash = HASHER.h32(key)) {
+        let value;
         try {
-          this.#database.exec('BEGIN')
-          while (n < this.#setBatch.length) {
-            const { key, data, ttl, stale, hash } = this.#setBatch[n++]
-            if (data != null) {
-              this.#setQuery?.run(key, data, ttl, stale)
-            } else {
-              this.#delQuery?.run(key)
+            value = this.#valueSelector(...args);
+        }
+        catch (err) {
+            this.#release(hash);
+            throw err;
+        }
+        if (!isThenable(value)) {
+            try {
+                this.#set(key, value, hash);
             }
-
-            if (this.#lockSet && this.#lockArray && hash >= 0) {
-              this.#lockSet.add(hash % this.#lockArray.length)
+            finally {
+                this.#release(hash);
             }
-
-            if ((n & 0xf) === 0 && performance.now() - startTime > 10) {
-              break
+            return { async: false, value };
+        }
+        // Store the chained promise (with #set + lock-release wired in) in #dedupe
+        // so concurrent get() callers see the same Promise instance as the original
+        // caller — required for promise-identity-based dedupe semantics.
+        const promise = Promise.resolve(value).then((value) => {
+            // finally guarantees lock release even if #set throws (user-supplied
+            // serializer / ttl / stale functions can throw); otherwise the slot
+            // would stay at 1 forever and deadlock the key.
+            try {
+                // Identity check: if delete() or another refresh replaced our dedupe
+                // entry, skip the write so we don't resurrect a deleted key or
+                // overwrite a newer value. #set itself clears dedupe on entry.
+                if (this.#dedupe.get(key) === promise) {
+                    this.#set(key, value, hash);
+                }
             }
-          }
-          this.#database.exec('COMMIT')
-          this.#setBatch.splice(0, n)
-
-          if (this.#lockSet && this.#lockArray) {
-            for (const idx of this.#lockSet) {
-              Atomics.add(this.#lockArray, idx, 1)
-              Atomics.notify(this.#lockArray, idx)
-            }
-            this.#lockSet.clear()
-          }
-          break
-        } catch (err) {
-          // ROLLBACK is required: a failed statement leaves the connection with
-          // an open transaction; without it the next BEGIN would throw.
-          // On SQLITE_FULL, SQLite automatically rolls back the transaction, so
-          // the explicit ROLLBACK may fail with "no transaction is active" — ignore it.
-          try {
-            this.#database.exec('ROLLBACK')
-          } catch {
-            // already rolled back automatically
-            // TODO (fix): Check that the error is what we expect (something like "no transaction is active")...
-          }
-
-          if (
-            (err                        )?.errcode === 13 /* SQLITE_FULL */ &&
-            retryCount < 3 &&
-            this.#evictQuery != null
-          ) {
-            this.#evictQuery.run(256)
-          } else {
-            // Intentional: drop the rolled-back items from the batch and surface
-            // the error via #emitError below. The corresponding entries remain in
-            // #memory until natural eviction/TTL, which is fine for cache semantics
-            // — callers already accept that cache values can disappear at any time.
-            // Do NOT flag this as silent data loss (see closed issue #167).
-            this.#setBatch.splice(0, n)
-            throw err
-          }
-        }
-      }
-    } catch (err) {
-      this.#emitError(err         )
-    }
-
-    if (this.#setBatch.length > 0) {
-      // If we weren't able to flush the entire batch within the time limit, schedule another flush.
-      this.#flushHandle = setImmediate(this.#flush)
-    } else {
-      this.#memory?.uncork()
-    }
-  }
-
-  #createEntry(
-    key        ,
-    value   ,
-    ttl        ,
-    stale        ,
-    size        ,
-  )                      {
-    return {
-      ttl,
-      stale,
-      value,
-      key,
-      size,
-      index: -1,
-      counter: -1,
-    }
-  }
-
-  #loadRow(key        , row             )                      {
-    const value = this.#serializer.deserialize(maybeToBuffer(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        , lockIdx        )                                      {
-    if (this.#lockAcquireQuery === null || this.#lockId == null) {
-      return 'unavailable'
-    }
-
-    const now = Date.now()
-
-    try {
-      const row = this.#lockAcquireQuery.get(key, now, this.#lockId)   
-                                                       
-                   
-
-      if (row === undefined) {
-        return 'unavailable'
-      }
-
-      if (row.lock_owner === this.#lockId) {
-        if (this.#lockArray) {
-          Atomics.add(this.#lockArray, lockIdx, 1)
+            finally {
+                this.#release(hash);
+            }
+            return value;
+        }, (err) => {
+            try {
+                if (this.#dedupe.get(key) === promise) {
+                    this.#dedupe.delete(key);
+                }
+            }
+            finally {
+                this.#release(hash);
+            }
+            throw err;
+        });
+        this.#dedupe.set(key, promise);
+        return { async: true, value: promise };
+    }
+    #set(key, value, hash = HASHER.h32(key)) {
+        if (typeof key !== 'string' || key.length === 0) {
+            throw new TypeError('key must be a non-empty string');
         }
-        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) {
-          if (this.#lockArray) {
-            Atomics.add(this.#lockArray, lockIdx, 1)
-          }
-          return 'acquired'
+        // Drop any in-flight dedupe entry so an async refresh that resolves after
+        // this call cannot resurrect a deleted key or overwrite a newer value —
+        // the async path's onFulfilled identity-checks before calling #set.
+        this.#dedupe.delete(key);
+        const shard = this.#shards ? this.#shards[hash % this.#shards.length] : null;
+        if (value === undefined) {
+            // Slow path... Should not be common...
+            this.#memory?.delete(key);
+            if (shard) {
+                shard.setBatch = shard.setBatch.filter((item) => item.key !== key);
+                try {
+                    shard.delQuery?.run(key);
+                }
+                catch (err) {
+                    this.#emitError(err);
+                }
+            }
+            return;
         }
-
-        // 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
+        const ttlValue = Math.min(MAX_DURATION, this.#ttl(value, key) ?? Infinity);
+        if (!Number.isFinite(ttlValue) || ttlValue < 0) {
+            throw new TypeError('ttl must be undefined, null, or a non-negative finite number');
         }
-      }
-
-      return lockedAt
-    } catch (err) {
-      this.#emitError(err         )
-      return 'unavailable'
-    }
-  }
-
-  #updateLockTimeout(duration        )       {
-    // EMA of mean and variance (Welford-style), clamped to [10ms, 1s].
-    // Timeout = mean + 3 * stddev to accommodate timing variability.
-    // Winsorize input at mean + 5σ so a single extreme outlier can't blow up the stats.
-    // Floor the stddev at 20% of the mean so the window never collapses to zero
-    // when variance decays (all observations near the mean).
-    const alpha = 0.2
-    const stddev = Math.max(this.#lockMean * 0.2, 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)
-    this.#lockTimeout = Math.max(
-      this.#lockMinTimeout,
-      Math.min(this.#lockMaxTimeout, Math.ceil(this.#lockMean + 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        ,
-    lockIdx        ,
-    lockVal        ,
-    lockedAt        ,
-    selfPromise            ,
-  )             {
-    // Wait for estimated completion: locked_at + our EMA-based timeout.
-    // Loop: wait for lock holder to write a value, retry if lock was stolen by another process.
-    for (let retryCount = 0; this.#dedupe.get(key) === selfPromise; retryCount++) {
-      // Add 5% jitter to reduce thundering herd on contention
-      const waitTime = Math.ceil(
-        Math.max(0, lockedAt + this.#lockTimeout - Date.now()) * (1 + Math.random() * 0.05),
-      )
-
-      if (this.#lockArray != null && lockIdx >= 0) {
-        const { async, value } = Atomics.waitAsync(this.#lockArray, lockIdx, lockVal, waitTime)
-        if (async) {
-          await value
-        }
-      } else {
-        await delay(waitTime, 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) {
-        this.#emitError(err         )
-      }
-
-      // Try to acquire lock for takeover
-      const lockRes = this.#tryAcquireLock(key, lockIdx)
-      if (typeof lockRes === 'number') {
-        // Another process holds the lock — wait for them
-        lockedAt = lockRes
-      } else {
-        // We acquired the lock or lock is unavailable — do the work
-        break
-      }
-
-      if (retryCount > 1) {
-        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
+        const staleValue = Math.min(MAX_DURATION, this.#stale(value, key) ?? Infinity);
+        if (!Number.isFinite(staleValue) || staleValue < 0) {
+            throw new TypeError('stale must be undefined, null, or a non-negative finite number');
+        }
+        const now = Date.now();
+        const ttl = now + ttlValue;
+        const stale = ttl + staleValue;
+        if (stale <= now) {
+            return;
+        }
+        const data = this.#serializer.serialize(value);
+        const entry = this.#createEntry(key, value, ttl, stale, ArrayBuffer.isView(data) ? data.byteLength : data.length * 2);
+        this.#memory?.set(key, entry);
+        if (!shard) {
+            return;
+        }
+        if (!this.#flushHandle) {
+            this.#memory?.cork();
+            this.#flushHandle = setImmediate(this.#flush);
+        }
+        else if (shard.setBatch.length > 512) {
+            clearImmediate(this.#flushHandle);
+            this.#flush();
+        }
+        shard.setBatch.push({ key, data, ttl, stale });
+    }
+    #flush = () => {
+        this.#flushHandle = null;
+        const startTime = performance.now();
+        const len = this.#shards?.length ?? 0;
+        const idx = Math.floor(Math.random() * len);
+        for (let k = 0; k < len; k++) {
+            const shard = this.#shards[(idx + k) % len];
+            try {
+                for (let retryCount = 0; true; retryCount++) {
+                    if (!shard.database || shard.setBatch.length === 0) {
+                        break;
+                    }
+                    let n = 0;
+                    try {
+                        shard.database.exec('BEGIN');
+                        while (n < shard.setBatch.length) {
+                            const { key, data, ttl, stale } = shard.setBatch[n++];
+                            if (data != null) {
+                                shard.setQuery?.run(key, data, ttl, stale);
+                            }
+                            else {
+                                shard.delQuery?.run(key);
+                            }
+                        }
+                        shard.database.exec('COMMIT');
+                        shard.setBatch.splice(0, n);
+                        break;
+                    }
+                    catch (err) {
+                        // ROLLBACK is required: a failed statement leaves the connection with
+                        // an open transaction; without it the next BEGIN would throw.
+                        // On SQLITE_FULL, SQLite automatically rolls back the transaction, so
+                        // the explicit ROLLBACK may fail with "no transaction is active" — ignore it.
+                        try {
+                            shard.database.exec('ROLLBACK');
+                        }
+                        catch {
+                            // already rolled back automatically
+                            // TODO (fix): Check that the error is what we expect (something like "no transaction is active")...
+                        }
+                        if (err?.errcode === 13 /* SQLITE_FULL */ &&
+                            retryCount < 3 &&
+                            shard.evictQuery != null) {
+                            shard.evictQuery.run(256);
+                        }
+                        else {
+                            // Intentional: drop the rolled-back items from the batch and surface
+                            // the error via #emitError below. The corresponding entries remain in
+                            // #memory until natural eviction/TTL, which is fine for cache semantics
+                            // — callers already accept that cache values can disappear at any time.
+                            // Do NOT flag this as silent data loss (see closed issue #167).
+                            shard.setBatch.splice(0, n);
+                            throw err;
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                shard.setBatch.length = 0;
+                this.#emitError(err);
+            }
+            if (performance.now() - startTime > 10) {
+                this.#flushHandle = setImmediate(this.#flush);
+                return;
+            }
+        }
+        this.#memory?.uncork();
+    };
+    #createEntry(key, value, ttl, stale, size) {
+        return {
+            ttl,
+            stale,
+            value,
+            key,
+            size,
+            index: -1,
+            counter: -1,
+        };
+    }
+    #loadRow(key, row) {
+        const value = this.#serializer.deserialize(maybeToBuffer(row.val));
+        return this.#createEntry(key, value, row.ttl, row.stale, ArrayBuffer.isView(row.val) ? row.val.byteLength : row.val.length * 2);
     }
-  }
 }
-
 {
-  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         )
-        }
-      }
-    }
-  }
+    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. */
-                                                  
+export const AsyncCache = Cache;
+//# sourceMappingURL=index.js.map