@nxtedition/cache 1.0.5 → 1.0.6

package/README.md

@@ -61,23 +61,36 @@ 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>`
 

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[]> {

package/lib/index.js

@@ -57,7 +57,7 @@ const dbs = new Set                            ()
 
                             
                               
-                                                         
+                                                  
 
 const VERSION = 2
 const MAX_DURATION = 365000000e3
@@ -261,7 +261,7 @@ 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 }

package/package.json

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