@nxtedition/cache 1.0.4 → 1.0.5

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
 
@@ -73,19 +73,15 @@ type CacheResult<V> =
   | { value: Promise<V> | null; async: true } // cache miss
 ```
 
-When `async: true`, `value` is a Promise that resolves once the `valueSelector` completes. If no `valueSelector` was provided, `value` is `undefined`.
+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> | undefined`
+#### `cache.refresh(...args): Promise<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.
-
-#### `cache.set(key, value): void`
-
-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

@@ -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,32 +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.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.5",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -31,5 +31,5 @@
   "dependencies": {
     "lru-cache": "^11.2.6"
   },
-  "gitHead": "f3a0afdf05d4d395ba8bdb45c48f619da7491d28"
+  "gitHead": "284d1bf697548d0bda69df9a240268da019b626f"
 }