@nxtedition/cache 1.0.6 → 1.0.9

package/README.md

@@ -54,21 +54,35 @@ if (result.async) {
 
 #### 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                                 |
+| 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. |
+| `memory`   | `MemoryOptions \| false \| null`   | `{ maxSize: 16MB, maxCount: 16384 }` | In-memory cache options, or `false`/`null` to disable in-memory caching.                 |
+| `database` | `DatabaseOptions \| false \| null` | `{ timeout: 20, maxSize: 256MB }`    | SQLite options, or `false`/`null` to disable persistence.                                |
+
+#### `MemoryOptions`
+
+| Option     | Type     | Default                    | Description                                    |
+| ---------- | -------- | -------------------------- | ---------------------------------------------- |
+| `maxSize`  | `number` | `16 * 1024 * 1024` (16 MB) | Maximum total size in bytes of cached entries. |
+| `maxCount` | `number` | `16 * 1024` (16384)        | Maximum number of entries in memory.           |
+
+#### `DatabaseOptions`
+
+| Option    | Type     | Default                      | Description                                                       |
+| --------- | -------- | ---------------------------- | ----------------------------------------------------------------- |
+| `timeout` | `number` | `20`                         | SQLite busy timeout in milliseconds.                              |
+| `maxSize` | `number` | `256 * 1024 * 1024` (256 MB) | Maximum database file size. Oldest entries are evicted when full. |
 
 ### `CacheResult<V>`
 
 Both `get()` and `peek()` return a `CacheResult<V>`, a discriminated union on the `async` property:
 
-| `async` | `value`                   | Meaning                                                                                                                                                       |
-| ------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `false` | `V`                       | Cache hit — the value is available synchronously. Also returned for stale entries (a background refresh is triggered automatically).                          |
-| `true`  | `Promise<V> \| undefined` | Cache miss — `value` is a `Promise` that resolves when the `valueSelector` completes, or `undefined` when called via `peek()` (which never triggers a fetch). |
+| `async` | `value`          | Meaning                                                                                                                                                                             |
+| ------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `false` | `V \| undefined` | Cache hit — the value is available synchronously. Also returned for stale entries (a background refresh is triggered automatically). `undefined` when `peek()` has no cached entry. |
+| `true`  | `Promise<V>`     | Cache miss — `value` is a `Promise` that resolves when the `valueSelector` completes.                                                                                               |
 
 ```ts
 const result = cache.get('key')
@@ -90,19 +104,19 @@ Returns a cached value or triggers a fetch on cache miss.
 
 #### `cache.peek(...args): CacheResult<V>`
 
-Same as `get()` but does **not** trigger a refresh on cache miss. Returns `{ value: undefined, async: true }` for missing entries.
+Same as `get()` but does **not** trigger a refresh on cache miss. Returns `{ value: undefined, async: false }` 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`
+#### `cache.delete(...args): 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.
+Remove an entry from the cache. The cache key is derived from `args` via the `keySelector`, just like `get()` and `refresh()`. 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.
+Remove all expired entries from both the in-memory cache and SQLite.
 
 #### `cache.close(): void`
 

package/lib/index.d.ts

@@ -1,24 +1,21 @@
-import { LRUCache } from 'lru-cache';
-interface CacheEntry<V> {
-    ttl: number;
-    stale: number;
-    value: V;
-}
-export interface AsyncCacheDbOptions {
+import { type MemoryOptions } from './memory.ts';
+export type { MemoryOptions, MemoryCacheEntry } from './memory.ts';
+export { MemoryCache } from './memory.ts';
+export interface DatabaseOptions {
     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 | false | null;
+    memory?: MemoryOptions | false | null;
+    database?: DatabaseOptions | false | null;
 }
 export type CacheResult<V> = {
-    value: V;
+    value: V | undefined;
     async: false;
 } | {
-    value: Promise<V> | undefined;
+    value: Promise<V>;
     async: true;
 };
 export declare class AsyncCache<V = unknown, A extends unknown[] = unknown[]> {
@@ -28,7 +25,6 @@ export declare class AsyncCache<V = unknown, A extends unknown[] = unknown[]> {
     get(...args: A): CacheResult<V>;
     peek(...args: A): CacheResult<V>;
     refresh(...args: A): Promise<V>;
-    delete(key: string): void;
+    delete(...args: A): void;
     purgeStale(): void;
 }
-export {};

package/lib/index.js

@@ -1,5 +1,8 @@
 import { DatabaseSync,                    } from 'node:sqlite'
-import { LRUCache } from 'lru-cache'
+import { MemoryCache,                                           } from "./memory.js"
+
+                                                                  
+export { MemoryCache } from './memory.ts'
 
 let fastNowTime = 0
 
@@ -37,13 +40,13 @@ const dbs = new Set                            ()
           
  
 
-                 
+                       
                           
              
                
  
 
-                                      
+                                  
                   
                   
  
@@ -51,27 +54,28 @@ const dbs = new Set                            ()
                                        
                                                     
                                                       
-                                                                       
-                                         
+                                       
+                                           
  
 
                             
-                              
-                                                  
+                                          
+                                      
 
 const VERSION = 2
 const MAX_DURATION = 365000000e3
 
 export class AsyncCache                                               {
-  #lru                                        
+  #memory                       
+  #dedupe = new Map                    ()
+
   #valueSelector                                
   #keySelector                        
-  #dedupe = new Map                    ()
 
   #ttl                                 
   #stale                                 
 
-  #db                      = null
+  #database                      = null
   #getQuery                       = null
   #setQuery                       = null
   #delQuery                       = null
@@ -116,15 +120,17 @@ export class AsyncCache                                               {
       throw new TypeError('stale must be a undefined, number or a function')
     }
 
-    this.#lru =
-      opts?.lru === false || opts?.lru === null ? null : new LRUCache({ max: 4096, ...opts?.lru })
+    this.#memory =
+      opts?.memory === false || opts?.memory === null ? null : new MemoryCache(opts?.memory)
 
-    for (let n = 0; opts?.db !== null && opts?.db !== false; n++) {
+    for (let n = 0; opts?.database !== null && opts?.database !== false; n++) {
       try {
-        const { maxSize = 256 * 1024 * 1024, timeout = 20 } = opts?.db ?? {}
-        this.#db ??= new DatabaseSync(location, { timeout })
+        const maxSize = opts?.database?.maxSize ?? 256 * 1024 * 1024
+        const timeout = opts?.database?.timeout ?? 20
+
+        this.#database ??= new DatabaseSync(location, { timeout })
 
-        this.#db.exec(`
+        this.#database.exec(`
           PRAGMA journal_mode = WAL;
           PRAGMA synchronous = NORMAL;
           PRAGMA temp_store = memory;
@@ -139,26 +145,30 @@ export class AsyncCache                                               {
         `)
 
         {
-          const { page_size } = this.#db.prepare('PRAGMA page_size').get()                         
-          this.#db.exec(`PRAGMA max_page_count = ${Math.ceil(maxSize / page_size)}`)
+          const { page_size } = this.#database.prepare('PRAGMA page_size').get()     
+                             
+           
+          this.#database.exec(`PRAGMA max_page_count = ${Math.ceil(maxSize / page_size)}`)
         }
 
-        this.#getQuery = this.#db.prepare(
+        this.#getQuery = this.#database.prepare(
           `SELECT val, ttl, stale FROM cache_v${VERSION} WHERE key = ? AND stale > ?`,
         )
-        this.#setQuery = this.#db.prepare(
+        this.#setQuery = this.#database.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(
+        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 ?)`,
         )
         break
       } catch (err) {
-        if (n >= 8) {
-          this.#db?.close()
-          this.#db = null
+        if (n >= 16) {
+          this.#database?.close()
+          this.#database = null
 
           this.#getQuery = null
           this.#setQuery = null
@@ -180,8 +190,8 @@ export class AsyncCache                                               {
     this.#delQuery = null
     this.#purgeStaleQuery = null
     this.#evictQuery = null
-    this.#db?.close()
-    this.#db = null
+    this.#database?.close()
+    this.#database = null
   }
 
   get(...args   )                 {
@@ -196,13 +206,13 @@ export class AsyncCache                                               {
     return this.#refresh(args)
   }
 
-  delete(key        )       {
-    this.#delete(key)
+  delete(...args   )       {
+    this.#delete(this.#keySelector(...args))
   }
 
   purgeStale()       {
     try {
-      this.#lru?.purgeStale()
+      this.#memory?.purgeStale(fastNow())
       this.#purgeStaleQuery?.run(fastNow())
     } catch {}
   }
@@ -216,13 +226,13 @@ export class AsyncCache                                               {
 
     const now = fastNow()
 
-    let cached                            = this.#lru?.get(key)
+    let cached                            = this.#memory?.get(key)
 
     if (cached === undefined) {
       try {
-        const row = this.#getQuery?.get(key, now)                     
+        const row = this.#getQuery?.get(key, now)                           
         if (row !== undefined) {
-          cached = {
+          const entry                      = {
             ttl: row.ttl,
             stale: row.stale,
             value: ArrayBuffer.isView(row.val)
@@ -232,11 +242,15 @@ export class AsyncCache                                               {
                   row.val.byteLength,
                 )                )
               : JSON.parse(row.val),
+            key,
+            size:
+              (ArrayBuffer.isView(row.val) ? row.val.byteLength : row.val.length) + key.length + 64,
+            index: -1,
+            counter: -1,
           }
-        }
+          this.#memory?.set(key, entry)
 
-        if (cached !== undefined) {
-          this.#lru?.set(key, cached)
+          cached = entry
         }
       } catch (err) {
         process.emitWarning(err         )
@@ -250,7 +264,7 @@ export class AsyncCache                                               {
 
       if (now > cached.stale) {
         // stale-while-revalidate has expired, purge cached value.
-        this.#lru?.delete(key)
+        this.#memory?.delete(key)
         try {
           this.#delQuery?.run(key)
         } catch {
@@ -263,12 +277,18 @@ export class AsyncCache                                               {
 
     const promise = refresh ? this.#refresh(args, key) : undefined
 
-    return cached !== undefined
-      ? { value: cached.value, async: false }
-      : { value: promise, async: true }
+    if (cached !== undefined) {
+      return { value: cached.value, async: false }
+    }
+
+    if (promise !== undefined) {
+      return { value: promise, async: true }
+    }
+
+    return { value: undefined, async: false }
   }
 
-  #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')
     }
@@ -284,7 +304,11 @@ export class AsyncCache                                               {
       (value) => {
         if (this.#dedupe.get(key) === promise) {
           this.#dedupe.delete(key)
-          this.#set(key, value)
+          if (value === undefined) {
+            this.#delete(key)
+          } else {
+            this.#set(key, value)
+          }
         }
         return value
       },
@@ -324,16 +348,22 @@ export class AsyncCache                                               {
       return
     }
 
-    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
       : JSON.stringify(value           )
 
+    this.#memory?.set(key, {
+      ttl,
+      stale,
+      value: ArrayBuffer.isView(value)
+        ? (Buffer.from(value.buffer, value.byteOffset, value.byteLength)                )
+        : value,
+      key,
+      size: (ArrayBuffer.isView(data) ? data.byteLength : data.length) + key.length + 64,
+      index: -1,
+      counter: -1,
+    })
+
     try {
       this.#setQuery?.run(key, data          , ttl, stale)
     } catch (err) {
@@ -356,7 +386,7 @@ export class AsyncCache                                               {
     }
 
     this.#dedupe.delete(key)
-    this.#lru?.delete(key)
+    this.#memory?.delete(key)
     try {
       this.#delQuery?.run(key)
     } catch (err) {

package/lib/memory.d.ts

@@ -0,0 +1,21 @@
+export interface MemoryOptions {
+    maxSize?: number;
+    maxCount?: number;
+}
+export interface MemoryCacheEntry<V> {
+    ttl: number;
+    stale: number;
+    value: V;
+    key: string;
+    index: number;
+    size: number;
+    counter: number;
+}
+export declare class MemoryCache<V> {
+    #private;
+    constructor(opts?: MemoryOptions);
+    set(key: string, entry: MemoryCacheEntry<V>): void;
+    get(key: string): MemoryCacheEntry<V> | undefined;
+    delete(key: string): void;
+    purgeStale(now: number): void;
+}

package/lib/memory.js

@@ -0,0 +1,103 @@
+                                
+                  
+                   
+ 
+
+                                      
+             
+               
+          
+             
+               
+              
+                 
+ 
+
+export class MemoryCache    {
+  #map                                   = new Map()
+  #arr                             = []
+
+  #maxSize
+  #maxCount
+
+  #size = 0
+  #count = 0
+
+  #counter = 0
+
+  constructor(opts                ) {
+    if (opts?.maxSize != null && (!Number.isInteger(opts.maxSize) || opts.maxSize < 1)) {
+      throw new Error('maxSize must be a positive integer')
+    }
+
+    if (opts?.maxCount != null && (!Number.isInteger(opts.maxCount) || opts.maxCount < 1)) {
+      throw new Error('maxCount must be a positive integer')
+    }
+
+    this.#maxSize = opts?.maxSize ?? 16 * 1024 * 1024
+    this.#maxCount = opts?.maxCount ?? 16 * 1024
+  }
+
+  set(key        , entry                     ) {
+    const existing = this.#map.get(key)
+    if (existing != null) {
+      this.#delete(existing)
+    }
+
+    this.#map.set(key, entry)
+    entry.key = key
+    entry.index = this.#arr.push(entry) - 1
+    entry.counter = this.#counter++
+
+    this.#size += entry.size ?? 0
+    this.#count += 1
+
+    this.#prune()
+  }
+
+  get(key        ) {
+    const entry = this.#map.get(key)
+    if (entry != null) {
+      entry.counter = this.#counter++
+    }
+    return entry
+  }
+
+  delete(key        ) {
+    const entry = this.#map.get(key)
+    if (entry != null) {
+      this.#delete(entry)
+    }
+  }
+
+  #delete(entry                     ) {
+    this.#map.delete(entry.key)
+
+    this.#size -= entry.size
+    this.#count -= 1
+
+    const tmp = this.#arr.pop() 
+    if (tmp !== entry) {
+      this.#arr[entry.index] = tmp
+      this.#arr[entry.index].index = entry.index
+    }
+  }
+
+  purgeStale(now        ) {
+    for (let i = this.#arr.length - 1; i >= 0; i--) {
+      const entry = this.#arr[i]
+      if (now > entry.stale) {
+        this.#delete(entry)
+      }
+    }
+  }
+
+  #prune() {
+    while (this.#size > this.#maxSize || this.#count > this.#maxCount) {
+      const e1 = this.#arr[(Math.random() * this.#arr.length) | 0]
+      const e2 = this.#arr[(Math.random() * this.#arr.length) | 0]
+      const e = e2.counter > e1.counter ? e1 : e2
+      this.#delete(e)
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxtedition/cache",
-  "version": "1.0.6",
+  "version": "1.0.9",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -14,12 +14,12 @@
     "access": "public"
   },
   "scripts": {
-    "build": "rimraf lib && tsc && amaroc ./src/index.ts && mv src/index.js lib/",
+    "build": "rimraf lib && tsc && amaroc ./src/index.ts && mv src/index.js lib/ && amaroc ./src/memory.ts && mv src/memory.js lib/",
     "prepublishOnly": "yarn build",
     "typecheck": "tsc --noEmit",
-    "test": "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"
+    "test": "node --test && yarn build",
+    "test:ci": "node --test && yarn build",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-include=src/index.ts --test-coverage-include=src/memory.ts --test-coverage-lines=90 --test-coverage-branches=90 --test-coverage-functions=100"
   },
   "devDependencies": {
     "@types/node": "^25.2.3",
@@ -28,8 +28,5 @@
     "rimraf": "^6.1.2",
     "typescript": "^5.9.3"
   },
-  "dependencies": {
-    "lru-cache": "^11.2.6"
-  },
-  "gitHead": "5c8b45723e68c527888e75a1536569479da7e4c5"
+  "gitHead": "0dd08f59b4d41fc8b3038386cfbd5adf970863c7"
 }