@nxtedition/cache 1.0.2 → 1.0.5

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,133 @@
+# @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>` | Function to fetch a value on cache miss       |
+| `keySelector`   | `(...args) => string`          | Function to derive a cache key from arguments |
+| `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.
+
+#### `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>`
+
+Triggers a fetch via `valueSelector` regardless of cache state. If a fetch for the same key is already in-flight (from a prior `get()` or `refresh()`), the existing promise is returned instead of starting a new one.
+
+#### `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

@@ -23,13 +23,12 @@ export type CacheResult<V> = {
 };
 export declare class AsyncCache<V = unknown, A extends unknown[] = unknown[]> {
     #private;
-    constructor(location: string, valueSelector?: (...args: A) => V | Promise<V>, keySelector?: (...args: A) => string, opts?: AsyncCacheOptions<V>);
+    constructor(location: string, valueSelector: (...args: A) => V | Promise<V>, keySelector: (...args: A) => string, opts?: AsyncCacheOptions<V>);
     close(): void;
     get(...args: A): CacheResult<V>;
     peek(...args: A): CacheResult<V>;
-    refresh(...args: A): Promise<V> | undefined;
+    refresh(...args: A): Promise<V>;
     delete(key: string): void;
-    set(key: string, value: V): void;
     purgeStale(): void;
 }
 export {};

package/lib/index.js

@@ -64,7 +64,7 @@ const MAX_DURATION = 365000000e3
 
 export class AsyncCache                                               {
   #lru                                        
-  #valueSelector                                              
+  #valueSelector                                
   #keySelector                        
   #dedupe = new Map                    ()
 
@@ -80,27 +80,23 @@ export class AsyncCache                                               {
 
   constructor(
     location        ,
-    valueSelector                                 ,
-    keySelector                         ,
+    valueSelector                                ,
+    keySelector                        ,
     opts                       ,
   ) {
-    if (typeof location === 'string') {
-      // Do nothing...
-    } else {
-      throw new TypeError('location must be undefined or a string')
+    if (typeof location !== 'string') {
+      throw new TypeError('location must be a string')
     }
 
-    if (typeof valueSelector === 'function' || valueSelector === undefined) {
-      this.#valueSelector = valueSelector
-    } else {
+    if (typeof valueSelector !== 'function') {
       throw new TypeError('valueSelector must be a function')
     }
+    this.#valueSelector = valueSelector
 
-    if (typeof keySelector === 'function' || keySelector === undefined) {
-      this.#keySelector = keySelector ?? ((...args   ) => JSON.stringify(args))
-    } else {
+    if (typeof keySelector !== 'function') {
       throw new TypeError('keySelector must be a function')
     }
+    this.#keySelector = keySelector
 
     if (typeof opts?.ttl === 'number' || opts?.ttl === undefined) {
       const ttl = opts?.ttl ?? Number.MAX_SAFE_INTEGER
@@ -196,7 +192,7 @@ export class AsyncCache                                               {
     return this.#load(args, false)
   }
 
-  refresh(...args   )                         {
+  refresh(...args   )             {
     return this.#refresh(args)
   }
 
@@ -204,10 +200,6 @@ export class AsyncCache                                               {
     this.#delete(key)
   }
 
-  set(key        , value   )       {
-    this.#set(key, value)
-  }
-
   purgeStale()       {
     try {
       this.#lru?.purgeStale()
@@ -276,31 +268,34 @@ export class AsyncCache                                               {
       : { value: promise, async: true }
   }
 
-  #refresh(args   , key = this.#keySelector(...args))                         {
+  #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)) {
-            this.#set(key, value)
-          }
-          return value
-        },
-        (err) => {
-          this.#delete(key)
-          throw err
-        },
-      )
-      promise.catch(noop)
-      this.#dedupe.set(key, promise)
+    const existing = this.#dedupe.get(key)
+    if (existing !== undefined) {
+      return existing
     }
 
+    // eslint-disable-next-line: no-unsafe-argument
+    const promise = Promise.resolve(this.#valueSelector(...args)).then(
+      (value) => {
+        if (this.#dedupe.get(key) === promise) {
+          this.#dedupe.delete(key)
+          this.#set(key, value)
+        }
+        return value
+      },
+      (err) => {
+        this.#dedupe.delete(key)
+        throw err
+      },
+    )
+    promise.catch(noop)
+    this.#dedupe.set(key, promise)
+
     return promise
   }
 
@@ -309,6 +304,8 @@ export class AsyncCache                                               {
       throw new TypeError('key must be a non-empty string')
     }
 
+    this.#dedupe.delete(key)
+
     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')
@@ -358,6 +355,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.2",
+  "version": "1.0.5",
   "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": "1bcd9e44bf750ac6fb478967c46e784e14ea63c5"
+  "gitHead": "284d1bf697548d0bda69df9a240268da019b626f"
 }