@nxtedition/cache 2.1.14 → 2.1.16

package/lib/index.js

@@ -9,10 +9,33 @@ function maybeToBuffer(value) {
         : value;
 }
 function isThenable(value) {
-    return value != null && typeof value.then === 'function';
+    if (value == null) {
+        return false;
+    }
+    // Accessing `.then` can throw when it's a toxic getter. Without this guard
+    // a user valueSelector returning `{ get then() { throw ... } }` would crash
+    // #refresh on the isThenable check *after* the valueSelector try/catch had
+    // already exited, leaving the lock acquired — subsequent reads on the same
+    // key would hang indefinitely. Treat a throwing `.then` as non-thenable.
+    try {
+        return typeof value.then === 'function';
+    }
+    catch {
+        return false;
+    }
 }
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const dbs = new Set();
+process.on('beforeExit', () => {
+    for (const db of dbs) {
+        try {
+            db.close();
+        }
+        catch (err) {
+            process.emitWarning(err);
+        }
+    }
+});
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const defaultSerializer = {
     serialize(value) {
@@ -23,9 +46,75 @@ const defaultSerializer = {
         return ArrayBuffer.isView(data) ? data : JSON.parse(data);
     },
 };
-const VERSION = 5;
+const VERSION = 6;
 const MAX_DURATION = 365000000e3;
 const HASHER = await xxhash();
+class DatabaseShard {
+    location;
+    databaseTimeout = 20;
+    database;
+    getQuery;
+    delQuery;
+    purgeExpiredQuery;
+    evictQuery;
+    pageCountQuery;
+    pageSizeQuery;
+    setQuery;
+    setBatch = [];
+    constructor(location, opts) {
+        this.location = location;
+        this.databaseTimeout = opts?.timeout ?? 20;
+        for (let n = 0; true; n++) {
+            try {
+                this.database = new DatabaseSync(location, { timeout: this.databaseTimeout });
+                break;
+            }
+            catch (err) {
+                // Check the retry limit BEFORE sleeping so we don't block for 100ms
+                // on the final failure before throwing.
+                if (n >= 16) {
+                    throw err;
+                }
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 100);
+            }
+        }
+        const maxSize = opts?.maxSize ?? 128 * 1024 * 1024;
+        try {
+            this.database.exec(`
+        PRAGMA journal_mode = WAL;
+        PRAGMA synchronous = OFF;
+        PRAGMA wal_autocheckpoint = 10000;
+        PRAGMA cache_size = -${Math.ceil(maxSize / 1024 / 8)};
+        PRAGMA mmap_size = ${maxSize};
+        PRAGMA max_page_count = ${Math.ceil(maxSize / 4096)};
+        PRAGMA optimize;
+
+        CREATE TABLE IF NOT EXISTS cache_v${VERSION} (
+          key TEXT PRIMARY KEY NOT NULL,
+          val BLOB NOT NULL,
+          stale INTEGER NOT NULL,
+          expire INTEGER NOT NULL
+        ) WITHOUT ROWID;
+
+        CREATE INDEX IF NOT EXISTS cache_v${VERSION}_expire_idx ON cache_v${VERSION}(expire);
+      `);
+            this.getQuery = this.database.prepare(`SELECT val, stale, expire FROM cache_v${VERSION} WHERE key = ? AND expire > ?`);
+            this.setQuery = this.database.prepare(`INSERT OR REPLACE INTO cache_v${VERSION} (key, val, stale, expire) VALUES (?, ?, ?, ?)`);
+            this.delQuery = this.database.prepare(`DELETE FROM cache_v${VERSION} WHERE key = ?`);
+            this.purgeExpiredQuery = this.database.prepare(`DELETE FROM cache_v${VERSION} WHERE expire <= ?`);
+            this.evictQuery = this.database.prepare(`DELETE FROM cache_v${VERSION} WHERE key IN (SELECT key FROM cache_v${VERSION} ORDER BY expire ASC LIMIT ?)`);
+            this.pageCountQuery = this.database.prepare('PRAGMA page_count');
+            this.pageSizeQuery = this.database.prepare('PRAGMA page_size');
+        }
+        catch (err) {
+            this.database.close();
+            throw err;
+        }
+    }
+    [Symbol.dispose]() {
+        this.database.close();
+    }
+}
 export class Cache extends EventEmitter {
     #memory;
     #dedupe = new Map();
@@ -38,21 +127,25 @@ export class Cache extends EventEmitter {
     #lockArray;
     #flushHandle = null;
     #location;
-    #databaseTimeout = 20;
-    #database = null;
-    #getQuery = null;
-    #delQuery = null;
-    #purgeStaleQuery = null;
-    #evictQuery = null;
-    #pageCountQuery = null;
-    #pageSizeQuery = null;
-    #setQuery = null;
-    #setBatch = [];
+    #shards = null;
     #emitError = (err) => {
-        if (this.listenerCount('error') > 0) {
-            this.emit('error', err);
+        // emit('error', err) rethrows synchronously if a user listener throws.
+        // #emitError is called from many places that iterate over shards (#flush,
+        // gc, constructor catch, the offPeak BroadcastChannel handler);
+        // a rethrow there would starve the remaining shards and skip cleanup
+        // (e.g. #flush's tail-uncork, gc's busy_timeout restore). Swallow
+        // listener throws and surface them as a warning so diagnostics aren't
+        // silently dropped.
+        try {
+            if (this.listenerCount('error') > 0) {
+                this.emit('error', err);
+            }
+            else {
+                process.emitWarning(err);
+            }
         }
-        else {
+        catch (listenerErr) {
+            process.emitWarning(listenerErr);
             process.emitWarning(err);
         }
     };
@@ -97,7 +190,8 @@ export class Cache extends EventEmitter {
             this.#lockArray = null;
         }
         else {
-            this.#lockArray = new Int32Array(getOrCreate(`__@nxtedition/cache/${location}`, 64 * 1024));
+            const size = 64 * 1024 * Int32Array.BYTES_PER_ELEMENT;
+            this.#lockArray = new Int32Array(getOrCreate(`__@nxtedition/cache/${location}`, size));
         }
         if (opts?.serializer !== undefined) {
             if (typeof opts.serializer !== 'object' || opts.serializer === null) {
@@ -113,53 +207,52 @@ export class Cache extends EventEmitter {
         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++) {
+        if (opts?.database === false || opts?.database === null) {
+            this.#shards = null;
+        }
+        else {
+            // Option-shape validation runs synchronously and throws: these are
+            // programmer errors, not the environmental open failures that the
+            // try/catch below converts to error events. Keeping the two paths
+            // separate matches how other constructor validations (lock, ttl, …)
+            // behave.
+            const count = opts?.database?.shards ?? (location === ':memory:' ? 1 : 4);
+            if (!Number.isInteger(count)) {
+                throw new TypeError('database.shards must be a positive integer');
+            }
+            if (count < 1) {
+                throw new RangeError('database.shards must be a positive integer');
+            }
+            if (location === ':memory:' && count !== 1) {
+                throw new RangeError('in-memory database does not support sharding');
+            }
+            this.#shards = [];
             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(`
-          PRAGMA journal_mode = WAL;
-          PRAGMA synchronous = OFF;
-          PRAGMA wal_autocheckpoint = 10000;
-          PRAGMA cache_size = -${Math.ceil(maxSize / 1024 / 8)};
-          PRAGMA mmap_size = ${maxSize};
-          PRAGMA max_page_count = ${Math.ceil(maxSize / 4096)};
-          PRAGMA optimize;
-
-          CREATE TABLE IF NOT EXISTS cache_v${VERSION} (
-            key TEXT PRIMARY KEY NOT NULL,
-            val BLOB NOT NULL,
-            ttl INTEGER NOT NULL,
-            stale INTEGER NOT NULL
-          ) WITHOUT ROWID;
-
-          CREATE INDEX IF NOT EXISTS cache_v${VERSION}_stale_idx ON cache_v${VERSION}(stale);
-        `);
-                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;
+                if (location === ':memory:') {
+                    this.#shards.push(new DatabaseShard(location, opts?.database));
+                }
+                else {
+                    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) {
-                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.#pageCountQuery = null;
-                    this.#pageSizeQuery = null;
-                    this.#emitError(err);
-                    break;
+                for (const shard of this.#shards) {
+                    // Guard so one bad dispose can't starve the rest and skip the
+                    // nulling + emitError below.
+                    try {
+                        shard[Symbol.dispose]();
+                    }
+                    catch {
+                        // Already failing the cache construction; swallow dispose errors.
+                    }
                 }
+                this.#shards = null;
+                this.#emitError(err);
             }
         }
         dbs.add(this);
@@ -168,14 +261,17 @@ export class Cache extends EventEmitter {
     }
     get stats() {
         let database;
-        if (this.#database) {
-            let size;
+        if (this.#shards) {
+            let size = 0;
             try {
-                const { page_count } = this.#pageCountQuery.get();
-                const { page_size } = this.#pageSizeQuery.get();
-                size = page_count * page_size;
+                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 };
@@ -189,28 +285,41 @@ export class Cache extends EventEmitter {
     [Symbol.dispose]() {
         this.close();
     }
-    close() {
+    flushSync() {
+        if (this.#closed) {
+            return;
+        }
+        // Drain pending flushes. The pending #flushHandle was scheduled by a
+        // prior #set that already corked the memory cache; #flush's tail-uncork
+        // balances that cork when it finishes. Do NOT cork again here — the old
+        // code did, leaving the memory cache in a permanently-corked state
+        // after close (cork() +1 per iteration, uncork() only -1 per completed
+        // flush), which disabled pruning on the now-orphaned MemoryCache.
         while (this.#flushHandle) {
             clearImmediate(this.#flushHandle);
             this.#flush();
         }
+    }
+    close() {
+        if (this.#closed) {
+            return;
+        }
+        this.flushSync();
         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.#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);
+        for (const shard of this.#shards ?? []) {
+            // Guard each dispose so one shard's close failure doesn't starve the
+            // rest and leave #shards as a partially-disposed array.
+            try {
+                shard[Symbol.dispose]();
+            }
+            catch (err) {
+                this.#emitError(err);
+            }
         }
+        this.#shards = null;
+        globalThis.__nxt_cache = globalThis.__nxt_cache?.filter((ref) => ref.deref() != null && ref.deref() !== this);
     }
     get(...args) {
         if (this.#closed) {
@@ -232,320 +341,379 @@ export class Cache extends EventEmitter {
         if (typeof key !== 'string' || key.length === 0) {
             throw new TypeError('keySelector must return a non-empty string');
         }
-        let idx;
-        if (this.#lockArray) {
-            idx = HASHER.h32(key) % this.#lockArray.length;
-            if (Atomics.add(this.#lockArray, idx, 1) >= 0xfffffff) {
-                // Roll back the increment before throwing so we don't leak the slot.
-                // #refresh would normally own the decrement, but we're bailing before
-                // calling it.
-                if (Atomics.sub(this.#lockArray, idx, 1) === 1) {
-                    Atomics.notify(this.#lockArray, idx);
-                }
-                throw new Error('lock counter overflow');
-            }
-        }
-        else {
-            idx = -1;
-        }
-        return this.#refresh(args, key, idx);
+        const hash = HASHER.h32(key);
+        return this.#refresh(args, key, hash);
     }
     delete(...args) {
         if (this.#closed) {
             throw new Error('cache is closed');
         }
-        this.#set(this.#keySelector(...args), undefined);
+        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);
     }
-    purgeStale() {
+    gc() {
         if (this.#closed) {
             throw new Error('cache is closed');
         }
-        this.#memory?.purgeStale(Date.now());
-        this.#database?.exec('PRAGMA busy_timeout = 5000');
-        try {
+        this.#memory?.gc(Date.now());
+        for (const shard of this.#shards ?? []) {
+            // Wrap the initial busy_timeout bump — if exec throws here, the old
+            // code threw out of the whole method, starving the remaining shards
+            // and leaving this shard's timeout unchanged (so the finally-branch
+            // restore wouldn't run either).
             try {
-                this.#purgeStaleQuery?.run(Date.now());
+                shard.database.exec('PRAGMA busy_timeout = 5000');
             }
             catch (err) {
                 this.#emitError(err);
+                continue;
             }
             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}`);
+                try {
+                    shard.purgeExpiredQuery.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);
+                }
             }
-            catch (err) {
-                this.#emitError(err);
+            finally {
+                try {
+                    shard.database.exec(`PRAGMA busy_timeout = ${shard.databaseTimeout}`);
+                }
+                catch (err) {
+                    this.#emitError(err);
+                }
             }
         }
     }
     #load(args, refresh) {
+        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 now = Date.now();
+        const hash = HASHER.h32(key);
         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);
-            }
+            cached = this.#get(key, hash, now);
         }
-        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;
-            }
+        else if (now >= cached.expire) {
+            // stale-while-revalidate has expired, purge cached value.
+            this.#memory?.delete(key);
+            cached = undefined;
+        }
+        if (cached !== undefined && now < cached.stale) {
+            return { value: cached.value, async: false };
         }
         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 ? HASHER.h32(key) % this.#lockArray.length : -1;
+        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, idx);
-                    if (!result.async) {
-                        return result;
-                    }
-                    else {
-                        result.value.catch((err) => {
-                            this.#emitError(err);
-                        });
+            // Stale-while-revalidate: every concurrent caller returns stale sync.
+            // Only the caller that actually wins the lock kicks off a background
+            // refresh — checking #dedupe first avoids redundant in-flight refreshes
+            // from prior callers. Without this, the first caller would return sync
+            // stale while later callers (seeing the pending promise) would
+            // inconsistently return async fresh for the same stale state.
+            if (!this.#dedupe.has(key)) {
+                try {
+                    const val = this.#lockArray ? Atomics.compareExchange(this.#lockArray, idx, 0, 1) : 0;
+                    if (val === 0) {
+                        const result = this.#refresh(args, key, hash, true);
+                        if (!result.async) {
+                            return result;
+                        }
+                        else {
+                            result.value.catch((err) => {
+                                this.#emitError(err);
+                            });
+                        }
                     }
                 }
-            }
-            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;
+        // Fully expired (or never cached): concurrent callers share one pending
+        // refresh via #dedupe.
+        {
+            const pending = this.#dedupe.get(key);
+            if (pending !== undefined) {
+                return { async: true, value: pending };
             }
-            const { async, value } = Atomics.waitAsync(this.#lockArray, idx, val, 1e3);
-            if (async) {
-                return {
-                    async: true,
-                    value: value.then(() => this.#load(args, true).value),
-                };
+        }
+        if (!this.#lockArray) {
+            return this.#refresh(args, key, hash, false);
+        }
+        const val = Atomics.compareExchange(this.#lockArray, idx, 0, 1);
+        if (val === 0) {
+            return this.#refresh(args, key, hash, true);
+        }
+        const { async, value } = Atomics.waitAsync(this.#lockArray, idx, val, 1e3);
+        if (async) {
+            return {
+                async: true,
+                value: value.then(() => this.#getOrRefresh(args, key, hash, now).value),
+            };
+        }
+        return this.#getOrRefresh(args, key, hash, now);
+    }
+    #getOrRefresh(args, key, hash, now) {
+        if (this.#closed) {
+            throw new Error('cache is closed');
+        }
+        const entry = this.#get(key, hash, now);
+        if (entry !== undefined) {
+            return { async: false, value: entry.value };
+        }
+        // The caller that released the lock may have failed to write a new
+        // value due to a database error, or may have written a value that
+        // expired by the time we woke up. In either case, fall back to
+        // refreshing the value ourselves — this is the same path as a
+        // cache miss, so it handles all the same edge cases (concurrent
+        // refreshes, database errors, etc) with the same robustness.
+        // Also note that locks are coarse and we might have been woken
+        // by a different key's release, so we can't assume anything
+        // about the state of the current key, but that's fine.
+        // There is a slight issue of potential thundering herd here if
+        // many callers are all waiting on the same lock and the refreshed
+        // value is always expired or fails to write.
+        return this.#refresh(args, key, hash, false);
+    }
+    #get(key, hash = HASHER.h32(key), now = Date.now()) {
+        try {
+            const shard = this.#shards ? this.#shards[hash % this.#shards.length] : null;
+            const row = shard?.getQuery.get(key, now);
+            if (row === undefined) {
+                return undefined;
             }
+            const entry = this.#loadRow(key, row);
+            this.#memory?.set(key, entry);
+            return entry;
+        }
+        catch (err) {
+            this.#emitError(err);
         }
-        return this.#refresh(args, key, idx);
+        return undefined;
     }
-    #refresh(args, key, idx) {
+    #release(hash) {
+        if (this.#lockArray) {
+            const idx = hash % this.#lockArray.length;
+            Atomics.sub(this.#lockArray, idx, 1);
+            Atomics.notify(this.#lockArray, idx);
+        }
+    }
+    #refresh(args, key, hash = HASHER.h32(key), acquired = false) {
         let value;
         try {
             value = this.#valueSelector(...args);
         }
         catch (err) {
-            if (this.#lockArray && Atomics.sub(this.#lockArray, idx, 1) === 1) {
-                Atomics.notify(this.#lockArray, idx);
+            if (acquired) {
+                this.#release(hash);
             }
             throw err;
         }
         if (!isThenable(value)) {
-            try {
-                this.#set(key, value);
-            }
-            finally {
-                if (this.#lockArray && Atomics.sub(this.#lockArray, idx, 1) === 1) {
-                    Atomics.notify(this.#lockArray, idx);
-                }
-            }
+            this.#set(key, value, hash, acquired);
             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);
-                }
+            // 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, acquired);
             }
-            finally {
-                if (this.#lockArray && Atomics.sub(this.#lockArray, idx, 1) === 1) {
-                    Atomics.notify(this.#lockArray, idx);
-                }
+            else if (acquired) {
+                // Even if we're not going to write the value, we still need to release
+                // the lock so that other callers aren't starved.
+                this.#release(hash);
             }
             return value;
         }, (err) => {
-            try {
-                if (this.#dedupe.get(key) === promise) {
-                    this.#dedupe.delete(key);
-                }
+            if (this.#dedupe.get(key) === promise) {
+                this.#dedupe.delete(key);
             }
-            finally {
-                if (this.#lockArray && Atomics.sub(this.#lockArray, idx, 1) === 1) {
-                    Atomics.notify(this.#lockArray, idx);
-                }
+            if (acquired) {
+                this.#release(hash);
             }
             throw err;
         });
         this.#dedupe.set(key, promise);
         return { async: true, value: promise };
     }
-    #set(key, value) {
-        if (typeof key !== 'string' || key.length === 0) {
-            throw new TypeError('key must be a non-empty string');
-        }
-        // 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);
-        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);
+    #set(key, value, hash = HASHER.h32(key), acquired = false) {
+        try {
+            if (typeof key !== 'string' || key.length === 0) {
+                throw new TypeError('key must be a non-empty string');
+            }
+            // 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) {
+                    for (const item of shard.setBatch.splice(0)) {
+                        if (item.key !== key) {
+                            shard.setBatch.push(item);
+                        }
+                        else if (item.acquired) {
+                            this.#release(item.hash);
+                        }
+                    }
+                    try {
+                        shard.delQuery.run(key);
+                    }
+                    catch (err) {
+                        this.#emitError(err);
+                    }
+                }
+                return;
             }
-            catch (err) {
-                this.#emitError(err);
+            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;
-        }
-        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');
-        }
-        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 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 stale = now + ttlValue;
+            const expire = stale + staleValue;
+            if (expire <= now) {
+                return;
+            }
+            const data = this.#serializer.serialize(value);
+            const entry = this.#createEntry(key, value, stale, expire, 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, stale, expire, hash, acquired });
+            acquired = false;
         }
-        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);
+        finally {
+            if (acquired) {
+                this.#release(hash);
+            }
         }
-        else if (this.#setBatch.length > 512) {
-            clearImmediate(this.#flushHandle);
-            this.#flush();
+    }
+    #releaseBatch(batch, start, deleteCount) {
+        for (const item of batch.splice(start, deleteCount)) {
+            if (item.acquired) {
+                this.#release(item.hash);
+            }
         }
-        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();
-            return;
-        }
-        try {
-            const startTime = performance.now();
-            for (let retryCount = 0; true; retryCount++) {
-                let n = 0;
-                try {
-                    this.#database.exec('BEGIN');
-                    while (n < this.#setBatch.length) {
-                        const { key, data, ttl, stale } = this.#setBatch[n++];
-                        if (data != null) {
-                            this.#setQuery?.run(key, data, ttl, stale);
-                        }
-                        else {
-                            this.#delQuery?.run(key);
-                        }
-                        if ((n & 0xf) === 0 && performance.now() - startTime > 10) {
-                            break;
-                        }
+        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.setBatch.length === 0) {
+                        break;
                     }
-                    this.#database.exec('COMMIT');
-                    this.#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.
+                    let n = 0;
                     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);
+                        shard.database.exec('BEGIN');
+                        while (n < shard.setBatch.length) {
+                            const { key, data, stale, expire } = shard.setBatch[n++];
+                            if (data != null) {
+                                shard.setQuery.run(key, data, stale, expire);
+                            }
+                            else {
+                                shard.delQuery.run(key);
+                            }
+                        }
+                        shard.database.exec('COMMIT');
+                        this.#releaseBatch(shard.setBatch, 0, n);
+                        break;
                     }
-                    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) {
+                        // 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.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.#releaseBatch(shard.setBatch, 0, n);
+                            throw err;
+                        }
                     }
                 }
             }
+            catch (err) {
+                this.#releaseBatch(shard.setBatch, 0, shard.setBatch.length);
+                this.#emitError(err);
+            }
+            if (performance.now() - startTime > 10) {
+                this.#flushHandle = setImmediate(this.#flush);
+                return;
+            }
         }
-        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();
-        }
+        this.#memory?.uncork();
     };
-    #createEntry(key, value, ttl, stale, size) {
+    #createEntry(key, value, stale, expire, size) {
         return {
-            ttl,
             stale,
+            expire,
             value,
             key,
             size,
@@ -555,7 +723,7 @@ export class Cache extends EventEmitter {
     }
     #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);
+        return this.#createEntry(key, value, row.stale, row.expire, ArrayBuffer.isView(row.val) ? row.val.byteLength : row.val.length * 2);
     }
 }
 {
@@ -564,13 +732,21 @@ export class Cache extends EventEmitter {
     offPeakBC.onmessage = () => {
         for (const db of dbs) {
             try {
-                db.purgeStale();
+                db.gc();
             }
             catch (err) {
-                if (db.listenerCount('error') > 0) {
-                    db.emit('error', err);
+                // Match #emitError semantics: don't let a throwing user error
+                // listener starve the remaining caches in `dbs`.
+                try {
+                    if (db.listenerCount('error') > 0) {
+                        db.emit('error', err);
+                    }
+                    else {
+                        process.emitWarning(err);
+                    }
                 }
-                else {
+                catch (listenerErr) {
+                    process.emitWarning(listenerErr);
                     process.emitWarning(err);
                 }
             }