@nxtedition/cache 1.0.1 → 1.0.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Robert Nagy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# @nxtedition/cache
+
+An async cache with SQLite persistence, in-memory LRU, stale-while-revalidate, and automatic request deduplication.
+
+## Features
+
+- **Two-tier storage**: In-memory LRU cache backed by SQLite on disk
+- **Stale-while-revalidate**: Serve stale data while refreshing in the background
+- **Request deduplication**: Concurrent fetches for the same key share a single in-flight request
+- **Async value resolution**: Transparently fetches missing values via a user-defined `valueSelector`
+- **Buffer support**: Store and retrieve binary data (Buffer, Uint8Array) alongside JSON values
+- **Size-bounded SQLite**: Configurable max database size with automatic eviction of oldest entries
+
+## Usage
+
+```ts
+import { AsyncCache } from '@nxtedition/cache'
+
+const cache = new AsyncCache(
+  './my-cache.db', // SQLite file path, or ':memory:'
+  async (id: string) => {
+    // fetch the value for this key
+    const res = await fetch(`https://api.example.com/items/${id}`)
+    return res.json()
+  },
+  (id: string) => id, // keySelector: derive cache key from arguments
+  {
+    ttl: 60_000, // 60s before value is considered stale
+    stale: 30_000, // serve stale for 30s while revalidating
+  },
+)
+
+const result = cache.get('item-123')
+
+if (result.async) {
+  // Cache miss — value is being fetched
+  const value = await result.value
+} else {
+  // Cache hit — value returned synchronously
+  const value = result.value
+}
+```
+
+## API
+
+### `new AsyncCache(location, valueSelector?, keySelector?, opts?)`
+
+| Parameter       | Type                           | Description                                                                                |
+| --------------- | ------------------------------ | ------------------------------------------------------------------------------------------ |
+| `location`      | `string`                       | SQLite database path, or `':memory:'`                                                      |
+| `valueSelector` | `(...args) => V \| Promise<V>` | Optional function to fetch a value on cache miss                                           |
+| `keySelector`   | `(...args) => string`          | Optional function to derive a cache key from arguments. Defaults to `JSON.stringify(args)` |
+| `opts`          | `AsyncCacheOptions<V>`         | Optional configuration                                                                     |
+
+#### Options
+
+| Option  | Type                                      | Default                           | Description                                                                              |
+| ------- | ----------------------------------------- | --------------------------------- | ---------------------------------------------------------------------------------------- |
+| `ttl`   | `number \| (value, key) => number`        | `MAX_SAFE_INTEGER`                | Time-to-live in milliseconds. After this, the entry is stale.                            |
+| `stale` | `number \| (value, key) => number`        | `MAX_SAFE_INTEGER`                | Stale-while-revalidate window in milliseconds. After `ttl + stale`, the entry is purged. |
+| `lru`   | `LRUCache.Options \| false \| null`       | `{ max: 4096 }`                   | LRU cache options, or `false`/`null` to disable in-memory caching                        |
+| `db`    | `{ timeout?, maxSize? } \| false \| null` | `{ timeout: 20, maxSize: 256MB }` | SQLite options, or `false`/`null` to disable persistence                                 |
+
+### Methods
+
+#### `cache.get(...args): CacheResult<V>`
+
+Returns the cached value or triggers a fetch via `valueSelector`.
+
+```ts
+type CacheResult<V> =
+  | { value: V; async: false } // cache hit
+  | { value: Promise<V> | null; async: true } // cache miss
+```
+
+When `async: true`, `value` is a Promise that resolves once the `valueSelector` completes. If no `valueSelector` was provided, `value` is `undefined`.
+
+#### `cache.peek(...args): CacheResult<V>`
+
+Same as `get()` but does **not** trigger a refresh on cache miss. Returns `{ value: null, async: true }` for missing entries.
+
+#### `cache.refresh(...args): Promise<V> | undefined`
+
+Forces a fetch via `valueSelector` regardless of cache state. Returns `undefined` if no `valueSelector` is configured. Concurrent calls for the same key are deduplicated.
+
+#### `cache.set(key, value): void`
+
+Manually set a value in the cache.
+
+#### `cache.delete(key): void`
+
+Remove a key from the cache. Also cancels any in-flight deduplication for that key, meaning a pending fetch will not write its result to the cache.
+
+#### `cache.purgeStale(): void`
+
+Remove all expired entries from both the LRU cache and SQLite.
+
+#### `cache.close(): void`
+
+Close the SQLite database and release resources.
+
+## Deduplication
+
+Concurrent calls to `get()` or `refresh()` for the same key share a single in-flight Promise. The `valueSelector` is called only once, and all callers receive the same resolved value.
+
+```ts
+// valueSelector is called once, both promises resolve to the same value
+const [a, b] = await Promise.all([cache.get('key').value, cache.get('key').value])
+```
+
+If a fetch fails, the deduplication entry is cleaned up and subsequent calls will retry.
+
+Calling `cache.delete(key)` while a fetch is in-flight invalidates the deduplication entry. The pending promise still resolves for its callers, but the result is **not** written to the cache.
+
+## Stale-While-Revalidate
+
+When an entry's TTL has expired but is still within the stale window (`ttl + stale`), `get()` returns the stale value synchronously (`async: false`) while triggering a background refresh.
+
+Once the stale window expires, the entry is purged entirely and the next `get()` returns `async: true`.
+
+```
+|--- ttl ---|--- stale ---|
+     fresh      stale       expired
+```
+
+## Off-Peak Purge
+
+All cache instances listen for messages on the `nxt:offPeak` BroadcastChannel. When a message is received, `purgeStale()` is called on every active instance, allowing coordinated cleanup during low-traffic periods.
+
+## Scripts
+
+```sh
+npm test                # run tests
+npm run test:coverage   # run tests with branch coverage report (90%+ enforced)
+npm run typecheck       # type-check without emitting
+npm run build           # build for publishing
+```

package/lib/index.d.ts

@@ -12,7 +12,7 @@ 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;
+    db?: AsyncCacheDbOptions | false | null;
 }
 export type CacheResult<V> = {
     value: V;

package/lib/index.js

@@ -52,7 +52,7 @@ const dbs = new Set                            ()
                                                     
                                                       
                                                                        
-                          
+                                         
  
 
                             
@@ -121,13 +121,12 @@ export class AsyncCache                                               {
     }
 
     this.#lru =
-      opts?.lru === false || opts?.lru === undefined
-        ? null
-        : new LRUCache({ max: 4096, ...opts?.lru })
+      opts?.lru === false || opts?.lru === null ? null : new LRUCache({ max: 4096, ...opts?.lru })
 
-    for (let n = 0; true; n++) {
+    for (let n = 0; opts?.db !== null && opts?.db !== false; n++) {
       try {
-        this.#db ??= new DatabaseSync(location, { timeout: 20, ...opts?.db })
+        const { maxSize = 256 * 1024 * 1024, timeout = 20 } = opts?.db ?? {}
+        this.#db ??= new DatabaseSync(location, { timeout })
 
         this.#db.exec(`
           PRAGMA journal_mode = WAL;
@@ -144,7 +143,6 @@ export class AsyncCache                                               {
         `)
 
         {
-          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)}`)
         }
@@ -278,24 +276,25 @@ export class AsyncCache                                               {
       : { 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')
     }
 
+    // TODO (fix): cross process/thread dedupe...
     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)) {
+          if (this.#dedupe.get(key) === promise) {
+            this.#dedupe.delete(key)
             this.#set(key, value)
           }
           return value
         },
         (err) => {
-          this.#delete(key)
+          this.#dedupe.delete(key)
           throw err
         },
       )
@@ -329,7 +328,11 @@ export class AsyncCache                                               {
       return
     }
 
-    this.#lru?.set(key, { ttl, stale, value })
+    const storedValue = ArrayBuffer.isView(value)
+      ? (Buffer.from(value.buffer, value.byteOffset, value.byteLength)                )
+      : value
+
+    this.#lru?.set(key, { ttl, stale, value: storedValue })
 
     const data                           = ArrayBuffer.isView(value)
       ? value
@@ -356,6 +359,7 @@ export class AsyncCache                                               {
       throw new TypeError('key must be a non-empty string')
     }
 
+    this.#dedupe.delete(key)
     this.#lru?.delete(key)
     try {
       this.#delQuery?.run(key)

package/package.json

@@ -1,19 +1,25 @@
 {
   "name": "@nxtedition/cache",
-  "version": "1.0.1",
+  "version": "1.0.4",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "files": [
-    "lib"
+    "lib",
+    "README.md",
+    "LICENSE"
   ],
-  "license": "UNLICENSED",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
   "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"
+    "test:ci": "node --test",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-include=src/index.ts --test-coverage-lines=90 --test-coverage-branches=90 --test-coverage-functions=100"
   },
   "devDependencies": {
     "@types/node": "^25.2.3",
@@ -25,5 +31,5 @@
   "dependencies": {
     "lru-cache": "^11.2.6"
   },
-  "gitHead": "1833b15a4085a33f85063e3fabf522dfa19c64b7"
+  "gitHead": "f3a0afdf05d4d395ba8bdb45c48f619da7491d28"
 }