@nxtedition/cache 1.0.5 → 1.0.7

package/README.md

@@ -61,31 +61,44 @@ if (result.async) {
 | `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
+### `CacheResult<V>`
 
-#### `cache.get(...args): CacheResult<V>`
+Both `get()` and `peek()` return a `CacheResult<V>`, a discriminated union on the `async` property:
 
-Returns the cached value or triggers a fetch via `valueSelector`.
+| `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). |
 
 ```ts
-type CacheResult<V> =
-  | { value: V; async: false } // cache hit
-  | { value: Promise<V> | null; async: true } // cache miss
+const result = cache.get('key')
+
+if (result.async) {
+  // miss — await the fetch
+  const value = await result.value
+} else {
+  // hit (fresh or stale) — use directly
+  const value = result.value
+}
 ```
 
-When `async: true`, `value` is a Promise that resolves once the `valueSelector` completes.
+### Methods
+
+#### `cache.get(...args): CacheResult<V>`
+
+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: null, async: true }` for missing entries.
+Same as `get()` but does **not** trigger a refresh on cache miss. Returns `{ value: undefined, 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`
+#### `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`
 

package/lib/index.d.ts

@@ -18,7 +18,7 @@ export type CacheResult<V> = {
     value: V;
     async: false;
 } | {
-    value: Promise<V> | null | undefined;
+    value: Promise<V> | undefined;
     async: true;
 };
 export declare class AsyncCache<V = unknown, A extends unknown[] = unknown[]> {
@@ -28,7 +28,7 @@ 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

@@ -57,7 +57,7 @@ const dbs = new Set                            ()
 
                             
                               
-                                                         
+                                                  
 
 const VERSION = 2
 const MAX_DURATION = 365000000e3
@@ -196,8 +196,8 @@ export class AsyncCache                                               {
     return this.#refresh(args)
   }
 
-  delete(key        )       {
-    this.#delete(key)
+  delete(...args   )       {
+    this.#delete(args)
   }
 
   purgeStale()       {
@@ -261,14 +261,14 @@ export class AsyncCache                                               {
       }
     }
 
-    const promise = refresh ? this.#refresh(args, key) : null
+    const promise = refresh ? this.#refresh(args, key) : undefined
 
     return cached !== undefined
       ? { value: cached.value, async: false }
       : { 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')
     }
@@ -350,7 +350,7 @@ export class AsyncCache                                               {
     }
   }
 
-  #delete(key        )       {
+  #delete(args   , key         = this.#keySelector(...args))       {
     if (typeof key !== 'string' || key.length === 0) {
       throw new TypeError('key must be a non-empty string')
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxtedition/cache",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -31,5 +31,5 @@
   "dependencies": {
     "lru-cache": "^11.2.6"
   },
-  "gitHead": "284d1bf697548d0bda69df9a240268da019b626f"
+  "gitHead": "a113680af7f36b0262a5de692bbf57409a51b86b"
 }