@nxtedition/cache 1.0.0

package/lib/index.d.ts

@@ -0,0 +1,35 @@
+import { LRUCache } from 'lru-cache';
+interface CacheEntry<V> {
+    ttl: number;
+    stale: number;
+    value: V;
+}
+export interface AsyncCacheDbOptions {
+    timeout?: number;
+    maxSize?: number;
+}
+export interface AsyncCacheOptions<V> {
+    ttl?: number | ((value: V, key: string) => number);
+    stale?: number | ((value: V, key: string) => number);
+    lru?: LRUCache.Options<string, CacheEntry<V>, unknown> | false | null;
+    db?: AsyncCacheDbOptions;
+}
+export type CacheResult<V> = {
+    value: V;
+    async: false;
+} | {
+    value: Promise<V> | null | undefined;
+    async: true;
+};
+export declare class AsyncCache<V = unknown> {
+    #private;
+    constructor(location: string, valueSelector?: (...args: unknown[]) => V | Promise<V>, keySelector?: (...args: unknown[]) => string, opts?: AsyncCacheOptions<V>);
+    close(): void;
+    get(...args: unknown[]): CacheResult<V>;
+    peek(...args: unknown[]): CacheResult<V>;
+    refresh(...args: unknown[]): Promise<V> | undefined;
+    delete(key: string): void;
+    set(key: string, value: V): void;
+    purgeStale(): void;
+}
+export {};

package/lib/index.js

@@ -0,0 +1,397 @@
+import { DatabaseSync,                    } from 'node:sqlite'
+import { LRUCache } from 'lru-cache'
+import { doYield } from '@nxtedition/yield'
+
+let fastNowTime = 0
+
+function fastNow()         {
+  if (fastNowTime === 0) {
+    fastNowTime = Math.floor(Date.now() / 1e3) * 1e3
+    setInterval(() => {
+      fastNowTime = Math.floor(Date.now() / 1e3) * 1e3
+    }, 1e3).unref()
+  }
+  return fastNowTime
+}
+
+function noop() {}
+
+const dbs = new Set                            ()
+
+{
+  const offPeakBC = new BroadcastChannel('nxt:offPeak')
+  offPeakBC.unref()
+  offPeakBC.onmessage = () => {
+    for (const db of dbs) {
+      try {
+        db.purgeStale()
+      } catch (err) {
+        process.emitWarning(err         )
+      }
+    }
+  }
+}
+
+                         
+             
+               
+          
+ 
+
+                 
+                          
+             
+               
+ 
+
+                            
+             
+          
+             
+               
+ 
+
+                                      
+                  
+                  
+ 
+
+                                       
+                                                    
+                                                      
+                                                                       
+                          
+ 
+
+                            
+                              
+                                                         
+
+const VERSION = 2
+const MAX_DURATION = 365000000e3
+
+export class AsyncCache              {
+  #lru                                        
+  #valueSelector                                                      
+  #keySelector                                
+  #dedupe = new Map                    ()
+
+  #ttl                                 
+  #stale                                 
+
+  #db                      = null
+  #getQuery                       = null
+  #setQuery                       = null
+  #delQuery                       = null
+  #purgeStaleQuery                       = null
+  #evictQuery                       = null
+
+  #setQueue                     = []
+
+  constructor(
+    location        ,
+    valueSelector                                         ,
+    keySelector                                 ,
+    opts                       ,
+  ) {
+    if (typeof location === 'string') {
+      // Do nothing...
+    } else {
+      throw new TypeError('location must be undefined or a string')
+    }
+
+    if (typeof valueSelector === 'function' || valueSelector === undefined) {
+      this.#valueSelector = valueSelector
+    } else {
+      throw new TypeError('valueSelector must be a function')
+    }
+
+    if (typeof keySelector === 'function' || keySelector === undefined) {
+      this.#keySelector = keySelector ?? ((...args           ) => JSON.stringify(args))
+    } else {
+      throw new TypeError('keySelector must be a function')
+    }
+
+    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')
+    }
+
+    this.#lru =
+      opts?.lru === false || opts?.lru === undefined
+        ? null
+        : new LRUCache({ max: 4096, ...opts?.lru })
+
+    for (let n = 0; true; n++) {
+      try {
+        this.#db ??= new DatabaseSync(location, { timeout: 20, ...opts?.db })
+
+        this.#db.exec(`
+          PRAGMA journal_mode = WAL;
+          PRAGMA synchronous = NORMAL;
+          PRAGMA temp_store = memory;
+          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
+          );
+        `)
+
+        {
+          const maxSize = opts?.db?.maxSize ?? 256 * 1024 * 1024
+          const { page_size } = this.#db.prepare('PRAGMA page_size').get()                         
+          this.#db.exec(`PRAGMA max_page_count = ${Math.ceil(maxSize / page_size)}`)
+        }
+
+        this.#getQuery = this.#db.prepare(
+          `SELECT val, ttl, stale FROM cache_v${VERSION} WHERE key = ? AND stale > ?`,
+        )
+        this.#setQuery = this.#db.prepare(
+          `INSERT OR REPLACE INTO cache_v${VERSION} (key, val, ttl, stale) VALUES (?, ?, ?, ?)`,
+        )
+        this.#delQuery = this.#db.prepare(`DELETE FROM cache_v${VERSION} WHERE key = ?`)
+        this.#purgeStaleQuery = this.#db.prepare(`DELETE FROM cache_v${VERSION} WHERE stale <= ?`)
+        this.#evictQuery = this.#db.prepare(
+          `DELETE FROM cache_v${VERSION} WHERE key IN (SELECT key FROM cache_v${VERSION} ORDER BY stale ASC LIMIT ?)`,
+        )
+        break
+      } catch (err) {
+        if (n >= 8) {
+          this.#db?.close()
+          this.#db = null
+
+          this.#getQuery = null
+          this.#setQuery = null
+          this.#delQuery = null
+
+          process.emitWarning(err         )
+          break
+        }
+      }
+    }
+
+    dbs.add(this)
+  }
+
+  close()       {
+    dbs.delete(this)
+    this.#setQueue.length = 0
+    this.#getQuery = null
+    this.#setQuery = null
+    this.#delQuery = null
+    this.#purgeStaleQuery = null
+    this.#evictQuery = null
+    this.#db?.close()
+    this.#db = null
+  }
+
+  get(...args           )                 {
+    return this.#load(args, true)
+  }
+
+  peek(...args           )                 {
+    return this.#load(args, false)
+  }
+
+  refresh(...args           )                         {
+    return this.#refresh(args)
+  }
+
+  delete(key        )       {
+    this.#delete(key)
+  }
+
+  set(key        , value   )       {
+    this.#set(key, value)
+  }
+
+  purgeStale()       {
+    try {
+      this.#lru?.purgeStale()
+      this.#purgeStaleQuery?.run(fastNow())
+    } catch {}
+  }
+
+  #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 = fastNow()
+
+    let cached                            = this.#lru?.get(key)
+
+    if (cached === undefined) {
+      try {
+        const row = this.#getQuery?.get(key, now)                     
+        if (row !== undefined) {
+          cached = {
+            ttl: row.ttl,
+            stale: row.stale,
+            value: ArrayBuffer.isView(row.val) ? (row.val                ) : JSON.parse(row.val),
+          }
+        } else {
+          const entry = this.#setQueue.findLast((x) => x.key === key)
+          if (entry !== undefined) {
+            cached = {
+              ttl: entry.ttl,
+              stale: entry.stale,
+              value: entry.value,
+            }
+          }
+        }
+
+        if (cached !== undefined) {
+          this.#lru?.set(key, cached)
+        }
+      } catch (err) {
+        process.emitWarning(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.#lru?.delete(key)
+        try {
+          this.#delQuery?.run(key)
+        } catch {
+          // Do nothing...
+        }
+
+        cached = undefined
+      }
+    }
+
+    const promise = refresh ? this.#refresh(args, key) : null
+
+    return cached !== undefined
+      ? { value: cached.value, async: false }
+      : { value: promise, async: true }
+  }
+
+  // eslint-disable-next-line: no-unsafe-argument
+  #refresh(args           , key = this.#keySelector(...args))                         {
+    if (typeof key !== 'string' || key.length === 0) {
+      throw new TypeError('keySelector must return a non-empty string')
+    }
+
+    let promise = this.#dedupe.get(key)
+    if (promise === undefined && this.#valueSelector) {
+      // eslint-disable-next-line: no-unsafe-argument
+      promise = Promise.resolve(this.#valueSelector(...args)).then(
+        (value) => {
+          if (this.#dedupe.delete(key)) {
+            this.#set(key, value)
+          }
+          return value
+        },
+        (err) => {
+          this.#delete(key)
+          throw err
+        },
+      )
+      promise.catch(noop)
+      this.#dedupe.set(key, promise)
+    }
+
+    return promise
+  }
+
+  #set(key        , value   )       {
+    if (typeof key !== 'string' || key.length === 0) {
+      throw new TypeError('key must be a non-empty string')
+    }
+
+    const ttlValue = Math.min(MAX_DURATION, this.#ttl(value, key) ?? Infinity)
+    if (!Number.isFinite(ttlValue) || ttlValue < 0) {
+      throw new TypeError('ttl must be nully or a positive integer')
+    }
+
+    const staleValue = Math.min(MAX_DURATION, this.#stale(value, key) ?? 0)
+    if (!Number.isFinite(staleValue) || staleValue < 0) {
+      throw new TypeError('stale must be nully or a positive integer')
+    }
+
+    const now = fastNow()
+    const ttl = now + ttlValue
+    const stale = ttl + staleValue
+
+    if (stale <= now) {
+      return
+    }
+
+    this.#lru?.set(key, { ttl, stale, value })
+
+    this.#setQueue.push({ key, value, ttl, stale })
+    if (this.#setQueue.length === 1) {
+      doYield(this.#flushSetQueue)
+    }
+  }
+
+  #flushSetQueue = ()       => {
+    for (const { key, value, ttl, stale } of this.#setQueue.splice(0, 64)) {
+      const data                           = ArrayBuffer.isView(value)
+        ? value
+        : JSON.stringify(value           )
+      try {
+        this.#setQuery?.run(key, data          , ttl, stale)
+      } catch (err) {
+        if ((err                                   )?.errcode === 13 /* SQLITE_FULL */) {
+          try {
+            this.#evictQuery?.run(256)
+            this.#setQuery?.run(key, data          , ttl, stale)
+          } catch {
+            process.emitWarning(err         )
+          }
+        } else {
+          process.emitWarning(err         )
+        }
+      }
+    }
+
+    if (this.#setQueue.length > 0) {
+      doYield(this.#flushSetQueue)
+    }
+  }
+
+  #delete(key        )       {
+    if (typeof key !== 'string' || key.length === 0) {
+      throw new TypeError('key must be a non-empty string')
+    }
+
+    this.#lru?.delete(key)
+
+    if (this.#setQueue.some((x) => x.key === key)) {
+      this.#setQueue = this.#setQueue.filter((x) => x.key !== key)
+    }
+
+    try {
+      this.#delQuery?.run(key)
+    } catch (err) {
+      process.emitWarning(err         )
+    }
+  }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@nxtedition/cache",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib"
+  ],
+  "license": "UNLICENSED",
+  "scripts": {
+    "build": "rimraf lib && tsc && amaroc ./src/index.ts && mv src/index.js lib/",
+    "prepublishOnly": "yarn build",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test",
+    "test:ci": "node --test"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "amaroc": "^1.0.1",
+    "oxlint-tsgolint": "^0.12.2",
+    "rimraf": "^6.1.2",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "@nxtedition/yield": "^1.0.7",
+    "lru-cache": "^11.2.6"
+  },
+  "gitHead": "e85766435987febc99140e523cd2d4f5af458892"
+}