@nxtedition/cache 1.0.4 → 1.0.6

package/README.md

@@ -43,14 +43,14 @@ if (result.async) {
 
 ## API
 
-### `new AsyncCache(location, valueSelector?, keySelector?, opts?)`
+### `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                                                                     |
+| 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
 
@@ -61,31 +61,40 @@ 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. If no `valueSelector` was provided, `value` is `undefined`.
+### Methods
 
-#### `cache.peek(...args): CacheResult<V>`
+#### `cache.get(...args): CacheResult<V>`
 
-Same as `get()` but does **not** trigger a refresh on cache miss. Returns `{ value: null, async: true }` for missing entries.
+Returns a cached value or triggers a fetch on cache miss.
 
-#### `cache.refresh(...args): Promise<V> | undefined`
+#### `cache.peek(...args): CacheResult<V>`
 
-Forces a fetch via `valueSelector` regardless of cache state. Returns `undefined` if no `valueSelector` is configured. Concurrent calls for the same key are deduplicated.
+Same as `get()` but does **not** trigger a refresh on cache miss. Returns `{ value: undefined, async: true }` for missing entries.
 
-#### `cache.set(key, value): void`
+#### `cache.refresh(...args): Promise<V>`
 
-Manually set a value in the cache.
+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`
 

package/lib/index.d.ts

@@ -18,18 +18,17 @@ 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[]> {
     #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

@@ -57,14 +57,14 @@ const dbs = new Set                            ()
 
                             
                               
-                                                         
+                                                  
 
 const VERSION = 2
 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()
@@ -269,39 +261,41 @@ 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')
     }
 
     // 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.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)
+    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
   }
 
@@ -310,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')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nxtedition/cache",
-  "version": "1.0.4",
+  "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": "f3a0afdf05d4d395ba8bdb45c48f619da7491d28"
+  "gitHead": "5c8b45723e68c527888e75a1536569479da7e4c5"
 }