lru-cache - npm Package Compare versions

Comparing version 7.18.3 to 8.0.0

package.json

 {
   "name": "lru-cache",
   "description": "A cache object that deletes the least-recently-used items.",
-  "version": "7.18.3",
+  "version": "8.0.0",
   "author": "Isaac Z. Schlueter <[e-mail]>",
@@ -14,8 +14,9 @@ "keywords": [
     "build": "npm run prepare",
+    "preprepare": "rm -rf dist",
+    "prepare": "tsc -p tsconfig.json && tsc -p tsconfig-esm.json",
+    "postprepare": "bash fixup.sh",
     "pretest": "npm run prepare",
     "presnap": "npm run prepare",
-    "prepare": "node ./scripts/transpile-to-esm.js",
-    "size": "size-limit",
-    "test": "tap",
-    "snap": "tap",
+    "test": "c8 tap",
+    "snap": "c8 tap",
     "preversion": "npm test",
@@ -25,20 +26,32 @@ "postversion": "npm publish",
     "format": "prettier --write .",
-    "typedoc": "typedoc ./index.d.ts"
+    "typedoc": "typedoc --tsconfig tsconfig-esm.json ./src/*.ts",
+    "prebenchmark": "npm run prepare",
+    "benchmark": "make -C benchmark",
+    "preprofile": "npm run prepare",
+    "profile": "make -C benchmark profile"
   },
-  "type": "commonjs",
-  "main": "./index.js",
-  "module": "./index.mjs",
-  "types": "./index.d.ts",
+  "main": "./dist/cjs/index-cjs.js",
+  "module": "./dist/mjs/index.js",
+  "types": "./dist/mjs/index.d.ts",
   "exports": {
+    "./min": {
+      "import": {
+        "types": "./dist/mjs/index.d.ts",
+        "default": "./dist/mjs/index.min.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index-cjs.min.js"
+      }
+    },
     ".": {
       "import": {
-        "types": "./index.d.ts",
-        "default": "./index.mjs"
+        "types": "./dist/mjs/index.d.ts",
+        "default": "./dist/mjs/index.js"
       },
       "require": {
-        "types": "./index.d.ts",
-        "default": "./index.js"
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index-cjs.js"
       }
-    },
-    "./package.json": "./package.json"
+    }
   },
@@ -53,3 +66,6 @@ "repository": "git://github.com/isaacs/node-lru-cache.git",
     "clock-mock": "^1.0.6",
+    "esbuild": "^0.17.11",
     "eslint-config-prettier": "^8.5.0",
+    "marked": "^4.2.12",
+    "mkdirp": "^2.1.5",
     "prettier": "^2.6.2",
@@ -65,8 +81,6 @@ "size-limit": "^7.0.8",
   "files": [
-    "index.js",
-    "index.mjs",
-    "index.d.ts"
+    "dist"
   ],
   "engines": {
-    "node": ">=12"
+    "node": ">=16.14"
   },
@@ -85,9 +99,8 @@ "prettier": {
   "tap": {
-    "nyc-arg": [
-      "--include=index.js"
-    ],
+    "coverage": false,
     "node-arg": [
       "--expose-gc",
-      "--require",
-      "ts-node/register"
+      "--no-warnings",
+      "--loader",
+      "ts-node/esm"
     ],
@@ -98,5 +111,5 @@ "ts": false
     {
-      "path": "./index.js"
+      "path": "./dist/mjs/index.js"
     }
   ]
 }

README.md

@@ -37,2 +37,4 @@ # lru-cache
 const LRUCache = require('lru-cache')
+// or in minified form for web browsers:
+import LRUCache from 'http://unpkg.com/lru-cache@8/dist/mjs/index.min.mjs'
 
@@ -74,3 +76,7 @@ // At least one of 'max', 'ttl', or 'maxSize' is required, to prevent
   // stale-while-revalidate type of behavior
-  fetchMethod: async (key, staleValue, { options, signal }) => {},
+  fetchMethod: async (
+    key,
+    staleValue,
+    { options, signal, context }
+  ) => {},
 }
@@ -98,8 +104,31 @@
 
-If you put more stuff in it, then items will fall out.
+If you put more stuff in the cache, then less recently used items
+will fall out. That's what an LRU cache is.
 
+## `class LRUCache<K, V, FC = unknown>(options)`
+
+Create a new `LRUCache` object.
+
+When using TypeScript, set the `K` and `V` types to the `key` and
+`value` types, respectively.
+
+The `FC` ("fetch context") generic type defaults to `unknown`.
+If set to a value other than `void` or `undefined`, then any
+calls to `cache.fetch()` _must_ provide a `context` option
+matching the `FC` type. If `FC` is set to `void` or `undefined`,
+then `cache.fetch()` _must not_ provide a `context` option. See
+the documentation on `async fetch()` below.
+
 ## Options
 
-### `max`
+All options are available on the LRUCache instance, making it
+safe to pass an LRUCache instance as the options argument to make
+another empty cache of the same type.
 
+Some options are marked read-only because changing them after
+instantiation is not safe. Changing any of the other options
+will of course only have an effect on subsequent method calls.
+
+### `max` (read only)
+
 The maximum number of items that remain in the cache (assuming no
@@ -116,3 +145,3 @@ TTL pruning or explicit deletions). Note that fewer items may be
 
-### `maxSize`
+### `maxSize` (read only)
 
@@ -169,3 +198,3 @@ Set to a positive integer to track the sizes of items added to
 
-### `fetchMethod`
+### `fetchMethod` (read only)
 
@@ -205,14 +234,2 @@ Function that is used to make background asynchronous fetches.
 
-### `fetchContext`
-
-Arbitrary data that can be passed to the `fetchMethod` as the
-`context` option.
-
-Note that this will only be relevant when the `cache.fetch()`
-call needs to call `fetchMethod()`. Thus, any data which will
-meaningfully vary the fetch response needs to be present in the
-key. This is primarily intended for including `x-request-id`
-headers and the like for debugging purposes, which do not affect
-the `fetchMethod()` response.
-
 ### `noDeleteOnFetchRejection`
@@ -310,3 +327,3 @@
 
-### `dispose`
+### `dispose` (read only)
 
@@ -346,3 +363,3 @@ Function that is called on items when they are dropped from the
 
-### `disposeAfter`
+### `disposeAfter` (read only)
 
@@ -598,4 +615,4 @@ The same as `dispose`, but called _after_ the entry is completely
   one passed to `fetchMethod` as well.
-- `fetchContext` - sets the `context` option passed to the
-  underlying `fetchMethod`.
+- `context` - sets the `context` option passed to the underlying
+  `fetchMethod`.
 
@@ -641,2 +658,30 @@ If the value is in the cache and not stale, then the returned
 
+#### Setting `context`
+
+If an `FC` type is set to a type other than `unknown`, `void`, or
+`undefined` in the LRUCache constructor, then all
+calls to `cache.fetch()` _must_ provide a `context` option. If
+set to `undefined` or `void`, then calls to fetch _must not_
+provide a `context` option.
+
+The `context` param allows you to provide arbitrary data that
+might be relevant in the course of fetching the data. It is only
+relevant for the course of a single `fetch()` operation, and
+discarded afterwards.
+
+#### Note: `fetch()` calls are inflight-unique
+
+If you call `fetch()` multiple times with the same key value,
+then every call after the first will return the same promise,
+_even if they have different settings that would otherwise change
+the behvavior of the fetch_, such as `noDeleteOnFetchRejection` or
+`ignoreFetchAbort`.
+
+In most cases, this is not a problem (in fact, only fetching
+something once is what you probably want, if you're caching in
+the first place). If you are changing the fetch() options
+dramatically between runs, there's a good chance that you might
+be trying to fit divergent semantics into a single object, and
+would be better off with multiple cache instances.
+
 ### `peek(key, { allowStale } = {}) => value`
@@ -656,3 +701,3 @@
 Will return `false` if the item is stale, even though it is
-technically in the cache.  The difference can be determined (if
+technically in the cache. The difference can be determined (if
 it matters) by using a `status` argument, and inspecting the
@@ -835,3 +880,3 @@ `has` field.
 the cache, particularly for logging, debugging, or for behavior
-within the `fetchMethod`.  To do this, you can pass a `status`
+within the `fetchMethod`. To do this, you can pass a `status`
 object to the `get()`, `set()`, `has()`, and `fetch()` methods.
@@ -1107,2 +1152,3 @@
    which uses an Object as its data store.
+
 2. Failing that, if at all possible, use short non-numeric
@@ -1112,5 +1158,15 @@ strings (ie, less than 256 characters) as your keys, and use
    LRUCache](https://yomguithereal.github.io/mnemonist/lru-cache).
-3. If the types of your keys will be long strings, strings that
-   look like floats, `null`, objects, or some mix of types, or if
-   you aren't sure, then this library will work well for you.
+
+3. If the types of your keys will be anything else, especially
+   long strings, strings that look like floats, objects, or some
+   mix of types, or if you aren't sure, then this library will
+   work well for you.
+
+   If you do not need the features that this library provides
+   (like asynchronous fetching, a variety of TTL staleness
+   options, and so on), then [mnemonist's
+   LRUMap](https://yomguithereal.github.io/mnemonist/lru-map) is
+   a very good option, and just slightly faster than this module
+   (since it does considerably less).
+
 4. Do not use a `dispose` function, size tracking, or especially
@@ -1131,2 +1187,16 @@ ttl behavior, unless absolutely needed. These features are
 
+## Breaking Changes in Version 8
+
+- The `fetchContext` option was renamed to `context`, and may no
+  longer be set on the cache instance itself.
+- Rewritten in TypeScript, so pretty much all the types moved
+  around a lot.
+- The AbortController/AbortSignal polyfill is removed. For this
+  reason, **Node version 16.14.0 or higher is now required**.
+- Internal properties were moved to actual private class
+  properties.
+- Keys and values must not be `null` or `undefined`.
+- Minified export available at `'lru-cache/min'`, for both CJS
+  and MJS builds.
+
 For more info, see the [change log](CHANGELOG.md).

New alerts

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

325424

increased by142.99%

Number of package files

19

increased by216.67%

Lines of code

4393

increased by42.17%

Number of lines in readme file

1188

increased by6.26%

Worsened metrics

Dev dependency count

17

increased by21.43%

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes