lru-cache - npm Package Compare versions

Comparing version 9.1.1 to 9.1.2

dist/cjs/index.d.ts

@@ -244,3 +244,3 @@ /**
      */
-    interface FetchOptionsNoContext<K, V, FC> extends FetchOptions<K, V, FC> {
+    interface FetchOptionsNoContext<K, V> extends FetchOptions<K, V, undefined> {
         context?: undefined;
@@ -482,4 +482,28 @@ }
          * Unless {@link OptionsBase.ignoreFetchAbort} is also set, the underlying
-         * {@link OptionsBase.fetchMethod} will still be considered canceled, and its return
-         * value will be ignored and not cached.
+         * {@link OptionsBase.fetchMethod} will still be considered canceled, and
+         * any value it returns will be ignored and not cached.
+         *
+         * Caveat: since fetches are aborted when a new value is explicitly
+         * set in the cache, this can lead to fetch returning a stale value,
+         * since that was the fallback value _at the moment the `fetch()` was
+         * initiated_, even though the new updated value is now present in
+         * the cache.
+         *
+         * For example:
+         *
+         * ```ts
+         * const cache = new LRUCache<string, any>({
+         *   ttl: 100,
+         *   fetchMethod: async (url, oldValue, { signal }) =>  {
+         *     const res = await fetch(url, { signal })
+         *     return await res.json()
+         *   }
+         * })
+         * cache.set('https://example.com/', { some: 'data' })
+         * // 100ms go by...
+         * const result = cache.fetch('https://example.com/')
+         * cache.set('https://example.com/', { other: 'thing' })
+         * console.log(await result) // { some: 'data' }
+         * console.log(cache.get('https://example.com/')) // { other: 'thing' }
+         * ```
          */
@@ -792,4 +816,4 @@ allowStaleOnFetchAbort?: boolean;
      */
-    fetch(k: K, fetchOptions: unknown extends FC ? LRUCache.FetchOptions<K, V, FC> : FC extends undefined | void ? LRUCache.FetchOptionsNoContext<K, V, FC> : LRUCache.FetchOptionsWithContext<K, V, FC>): Promise<void | V>;
-    fetch(k: unknown extends FC ? K : FC extends undefined | void ? K : never, fetchOptions?: unknown extends FC ? LRUCache.FetchOptions<K, V, FC> : FC extends undefined | void ? LRUCache.FetchOptionsNoContext<K, V, FC> : never): Promise<void | V>;
+    fetch(k: K, fetchOptions: unknown extends FC ? LRUCache.FetchOptions<K, V, FC> : FC extends undefined | void ? LRUCache.FetchOptionsNoContext<K, V> : LRUCache.FetchOptionsWithContext<K, V, FC>): Promise<void | V>;
+    fetch(k: unknown extends FC ? K : FC extends undefined | void ? K : never, fetchOptions?: unknown extends FC ? LRUCache.FetchOptions<K, V, FC> : FC extends undefined | void ? LRUCache.FetchOptionsNoContext<K, V> : never): Promise<void | V>;
     /**
@@ -796,0 +820,0 @@ * Return a value from the cache. Will update the recency of the cache

dist/mjs/index.d.ts

@@ -244,3 +244,3 @@ /**
      */
-    interface FetchOptionsNoContext<K, V, FC> extends FetchOptions<K, V, FC> {
+    interface FetchOptionsNoContext<K, V> extends FetchOptions<K, V, undefined> {
         context?: undefined;
@@ -482,4 +482,28 @@ }
          * Unless {@link OptionsBase.ignoreFetchAbort} is also set, the underlying
-         * {@link OptionsBase.fetchMethod} will still be considered canceled, and its return
-         * value will be ignored and not cached.
+         * {@link OptionsBase.fetchMethod} will still be considered canceled, and
+         * any value it returns will be ignored and not cached.
+         *
+         * Caveat: since fetches are aborted when a new value is explicitly
+         * set in the cache, this can lead to fetch returning a stale value,
+         * since that was the fallback value _at the moment the `fetch()` was
+         * initiated_, even though the new updated value is now present in
+         * the cache.
+         *
+         * For example:
+         *
+         * ```ts
+         * const cache = new LRUCache<string, any>({
+         *   ttl: 100,
+         *   fetchMethod: async (url, oldValue, { signal }) =>  {
+         *     const res = await fetch(url, { signal })
+         *     return await res.json()
+         *   }
+         * })
+         * cache.set('https://example.com/', { some: 'data' })
+         * // 100ms go by...
+         * const result = cache.fetch('https://example.com/')
+         * cache.set('https://example.com/', { other: 'thing' })
+         * console.log(await result) // { some: 'data' }
+         * console.log(cache.get('https://example.com/')) // { other: 'thing' }
+         * ```
          */
@@ -792,4 +816,4 @@ allowStaleOnFetchAbort?: boolean;
      */
-    fetch(k: K, fetchOptions: unknown extends FC ? LRUCache.FetchOptions<K, V, FC> : FC extends undefined | void ? LRUCache.FetchOptionsNoContext<K, V, FC> : LRUCache.FetchOptionsWithContext<K, V, FC>): Promise<void | V>;
-    fetch(k: unknown extends FC ? K : FC extends undefined | void ? K : never, fetchOptions?: unknown extends FC ? LRUCache.FetchOptions<K, V, FC> : FC extends undefined | void ? LRUCache.FetchOptionsNoContext<K, V, FC> : never): Promise<void | V>;
+    fetch(k: K, fetchOptions: unknown extends FC ? LRUCache.FetchOptions<K, V, FC> : FC extends undefined | void ? LRUCache.FetchOptionsNoContext<K, V> : LRUCache.FetchOptionsWithContext<K, V, FC>): Promise<void | V>;
+    fetch(k: unknown extends FC ? K : FC extends undefined | void ? K : never, fetchOptions?: unknown extends FC ? LRUCache.FetchOptions<K, V, FC> : FC extends undefined | void ? LRUCache.FetchOptionsNoContext<K, V> : never): Promise<void | V>;
     /**
@@ -796,0 +820,0 @@ * Return a value from the cache. Will update the recency of the cache

package.json

 {
   "name": "lru-cache",
   "description": "A cache object that deletes the least-recently-used items.",
-  "version": "9.1.1",
+  "version": "9.1.2",
   "author": "Isaac Z. Schlueter <[e-mail]>",
@@ -59,3 +59,3 @@ "keywords": [
     "@size-limit/preset-small-lib": "^7.0.8",
-    "@types/node": "^17.0.31",
+    "@types/node": "^20.2.5",
     "@types/tap": "^15.0.6",
@@ -72,6 +72,6 @@ "benchmark": "^2.1.4",
     "tap": "^16.3.4",
-    "ts-node": "^10.7.0",
+    "ts-node": "^10.9.1",
     "tslib": "^2.4.0",
-    "typedoc": "^0.23.24",
-    "typescript": "^4.6.4"
+    "typedoc": "^0.24.6",
+    "typescript": "^5.0.4"
   },
@@ -100,5 +100,4 @@ "license": "ISC",
       "--expose-gc",
-      "--no-warnings",
-      "--loader",
-      "ts-node/esm"
+      "-r",
+      "ts-node/register"
     ],
@@ -105,0 +104,0 @@ "ts": false

README.md

@@ -267,5 +267,29 @@ # lru-cache
 Unless `ignoreFetchAbort` is also set, the underlying
-`fetchMethod` will still be considered canceled, and its return
-value will be ignored and not cached.
+`fetchMethod` will still be considered canceled, and any value
+it returns will be ignored and not cached.
 
+Caveat: since fetches are aborted when a new value is explicitly
+set in the cache, this can lead to fetch returning a stale value,
+since that was the fallback value _at the moment the `fetch()` was
+initiated_, even though the new updated value is now present in
+the cache.
+
+For example:
+
+```ts
+const cache = new LRUCache<string, any>({
+  ttl: 100,
+  fetchMethod: async (url, oldValue, { signal }) =>  {
+    const res = await fetch(url, { signal })
+    return await res.json()
+  }
+})
+cache.set('https://example.com/', { some: 'data' })
+// 100ms go by...
+const result = cache.fetch('https://example.com/')
+cache.set('https://example.com/', { other: 'thing' })
+console.log(await result) // { some: 'data' }
+console.log(cache.get('https://example.com/')) // { other: 'thing' }
+```
+
 ### `ignoreFetchAbort`
@@ -573,3 +597,3 @@
 If the value is `undefined`, then this is an alias for
-`cache.delete(key)`.  `undefined` is never stored in the cache.
+`cache.delete(key)`. `undefined` is never stored in the cache.
 See **Storing Undefined Values** below.
@@ -1033,3 +1057,3 @@
 You may call `cache.set(key, undefined)`, but this is just an
-an alias for `cache.delete(key)`.  Note that this has the effect
+an alias for `cache.delete(key)`. Note that this has the effect
 that `cache.has(key)` will return _false_ after setting it to
@@ -1036,0 +1060,0 @@ undefined.

No alert changes

Improved metrics

Total package byte prevSize

660095

increased by1.02%

Lines of code

4580

increased by1.06%

Number of lines in readme file

1190

increased by2.06%

No dependency changes