dep 0.18.2 → 1.0.0

package/node_modules/lru-cache/README.md

@@ -1,28 +1,91 @@
-# lru cache
+# lru-cache
 
 A cache object that deletes the least-recently-used items.
 
-[![Build Status](https://travis-ci.org/isaacs/node-lru-cache.svg?branch=master)](https://travis-ci.org/isaacs/node-lru-cache) [![Coverage Status](https://coveralls.io/repos/isaacs/node-lru-cache/badge.svg?service=github)](https://coveralls.io/github/isaacs/node-lru-cache)
+Specify a max number of the most recently used items that you
+want to keep, and this cache will keep that many of the most
+recently accessed items.
 
-## Installation:
+This is not primarily a TTL cache, and does not make strong TTL
+guarantees. There is no preemptive pruning of expired items by
+default, but you _may_ set a TTL on the cache or on a single
+`set`. If you do so, it will treat expired items as missing, and
+delete them when fetched. If you are more interested in TTL
+caching than LRU caching, check out
+[@isaacs/ttlcache](http://npm.im/@isaacs/ttlcache).
 
-```javascript
-npm install lru-cache --save
-```
+As of version 7, this is one of the most performant LRU
+implementations available in JavaScript, and supports a wide
+diversity of use cases. However, note that using some of the
+features will necessarily impact performance, by causing the
+cache to have to do more work. See the "Performance" section
+below.
 
-## Usage:
+## Installation
 
-```javascript
-var LRU = require("lru-cache")
-  , options = { max: 500
-              , length: function (n, key) { return n * 2 + key.length }
-              , dispose: function (key, n) { n.close() }
-              , maxAge: 1000 * 60 * 60 }
-  , cache = new LRU(options)
-  , otherCache = new LRU(50) // sets just the max size
+```bash
+npm install lru-cache --save
+```
 
-cache.set("key", "value")
-cache.get("key") // "value"
+## Usage
+
+```js
+// hybrid module, either works
+import { LRUCache } from 'lru-cache'
+// or:
+const { LRUCache } = require('lru-cache')
+// or in minified form for web browsers:
+import { LRUCache } from 'http://unpkg.com/lru-cache@9/dist/mjs/index.min.mjs'
+
+// At least one of 'max', 'ttl', or 'maxSize' is required, to prevent
+// unsafe unbounded storage.
+//
+// In most cases, it's best to specify a max for performance, so all
+// the required memory allocation is done up-front.
+//
+// All the other options are optional, see the sections below for
+// documentation on what each one does.  Most of them can be
+// overridden for specific items in get()/set()
+const options = {
+  max: 500,
+
+  // for use with tracking overall storage size
+  maxSize: 5000,
+  sizeCalculation: (value, key) => {
+    return 1
+  },
+
+  // for use when you need to clean up something when objects
+  // are evicted from the cache
+  dispose: (value, key, reason) => {
+    freeFromMemoryOrWhatever(value)
+  },
+
+  // for use when you need to know that an item is being inserted
+  // note that this does NOT allow you to prevent the insertion,
+  // it just allows you to know about it.
+  onInsert: (value, key, reason) => {
+    logInsertionOrWhatever(key, value)
+  },
+
+  // how long to live in ms
+  ttl: 1000 * 60 * 5,
+
+  // return stale items before removing from cache?
+  allowStale: false,
+
+  updateAgeOnGet: false,
+  updateAgeOnHas: false,
+
+  // async method to use for cache.fetch(), for
+  // stale-while-revalidate type of behavior
+  fetchMethod: async (key, staleValue, { options, signal, context }) => {},
+}
+
+const cache = new LRUCache(options)
+
+cache.set('key', 'value')
+cache.get('key') // "value"
 
 // non-string keys ARE fully supported
 // but note that it must be THE SAME object, not
@@ -36,131 +99,371 @@ assert.equal(cache.get(someObject), 'a value')
 // because it's a different object identity
 assert.equal(cache.get({ a: 1 }), undefined)
 
-cache.reset()    // empty the cache
+cache.clear() // empty the cache
 ```
 
-If you put more stuff in it, then items will fall out.
-
-If you try to put an oversized thing in it, then it'll fall out right
-away.
-
-## Options
-
-* `max` The maximum size of the cache, checked by applying the length
-  function to all values in the cache.  Not setting this is kind of
-  silly, since that's the whole purpose of this lib, but it defaults
-  to `Infinity`.  Setting it to a non-number or negative number will
-  throw a `TypeError`.  Setting it to 0 makes it be `Infinity`.
-* `maxAge` Maximum age in ms.  Items are not pro-actively pruned out
-  as they age, but if you try to get an item that is too old, it'll
-  drop it and return undefined instead of giving it to you.
-  Setting this to a negative value will make everything seem old!
-  Setting it to a non-number will throw a `TypeError`.
-* `length` Function that is used to calculate the length of stored
-  items.  If you're storing strings or buffers, then you probably want
-  to do something like `function(n, key){return n.length}`.  The default is
-  `function(){return 1}`, which is fine if you want to store `max`
-  like-sized things.  The item is passed as the first argument, and
-  the key is passed as the second argumnet.
-* `dispose` Function that is called on items when they are dropped
-  from the cache.  This can be handy if you want to close file
-  descriptors or do other cleanup tasks when items are no longer
-  accessible.  Called with `key, value`.  It's called *before*
-  actually removing the item from the internal cache, so if you want
-  to immediately put it back in, you'll have to do that in a
-  `nextTick` or `setTimeout` callback or it won't do anything.
-* `stale` By default, if you set a `maxAge`, it'll only actually pull
-  stale items out of the cache when you `get(key)`.  (That is, it's
-  not pre-emptively doing a `setTimeout` or anything.)  If you set
-  `stale:true`, it'll return the stale value before deleting it.  If
-  you don't set this, then it'll return `undefined` when you try to
-  get a stale entry, as if it had already been deleted.
-* `noDisposeOnSet` By default, if you set a `dispose()` method, then
-  it'll be called whenever a `set()` operation overwrites an existing
-  key.  If you set this option, `dispose()` will only be called when a
-  key falls out of the cache, not when it is overwritten.
-* `updateAgeOnGet` When using time-expiring entries with `maxAge`,
-  setting this to `true` will make each item's effective time update
-  to the current time whenever it is retrieved from cache, causing it
-  to not expire.  (It can still fall out of cache based on recency of
-  use, of course.)
-
-## API
-
-* `set(key, value, maxAge)`
-* `get(key) => value`
-
-    Both of these will update the "recently used"-ness of the key.
-    They do what you think. `maxAge` is optional and overrides the
-    cache `maxAge` option if provided.
-
-    If the key is not found, `get()` will return `undefined`.
-
-    The key and val can be any value.
-
-* `peek(key)`
+If you put more stuff in the cache, then less recently used items
+will fall out. That's what an LRU cache is.
+
+For full description of the API and all options, please see [the
+LRUCache typedocs](https://isaacs.github.io/node-lru-cache/)
+
+## Storage Bounds Safety
+
+This implementation aims to be as flexible as possible, within
+the limits of safe memory consumption and optimal performance.
+
+At initial object creation, storage is allocated for `max` items.
+If `max` is set to zero, then some performance is lost, and item
+count is unbounded. Either `maxSize` or `ttl` _must_ be set if
+`max` is not specified.
+
+If `maxSize` is set, then this creates a safe limit on the
+maximum storage consumed, but without the performance benefits of
+pre-allocation. When `maxSize` is set, every item _must_ provide
+a size, either via the `sizeCalculation` method provided to the
+constructor, or via a `size` or `sizeCalculation` option provided
+to `cache.set()`. The size of every item _must_ be a positive
+integer.
+
+If neither `max` nor `maxSize` are set, then `ttl` tracking must
+be enabled. Note that, even when tracking item `ttl`, items are
+_not_ preemptively deleted when they become stale, unless
+`ttlAutopurge` is enabled. Instead, they are only purged the
+next time the key is requested. Thus, if `ttlAutopurge`, `max`,
+and `maxSize` are all not set, then the cache will potentially
+grow unbounded.
+
+In this case, a warning is printed to standard error. Future
+versions may require the use of `ttlAutopurge` if `max` and
+`maxSize` are not specified.
+
+If you truly wish to use a cache that is bound _only_ by TTL
+expiration, consider using a `Map` object, and calling
+`setTimeout` to delete entries when they expire. It will perform
+much better than an LRU cache.
+
+Here is an implementation you may use, under the same
+[license](./LICENSE) as this package:
+
+```js
+// a storage-unbounded ttl cache that is not an lru-cache
+const cache = {
+  data: new Map(),
+  timers: new Map(),
+  set: (k, v, ttl) => {
+    if (cache.timers.has(k)) {
+      clearTimeout(cache.timers.get(k))
+    }
+    cache.timers.set(
+      k,
+      setTimeout(() => cache.delete(k), ttl),
+    )
+    cache.data.set(k, v)
+  },
+  get: k => cache.data.get(k),
+  has: k => cache.data.has(k),
+  delete: k => {
+    if (cache.timers.has(k)) {
+      clearTimeout(cache.timers.get(k))
+    }
+    cache.timers.delete(k)
+    return cache.data.delete(k)
+  },
+  clear: () => {
+    cache.data.clear()
+    for (const v of cache.timers.values()) {
+      clearTimeout(v)
+    }
+    cache.timers.clear()
+  },
+}
+```
 
-    Returns the key value (or `undefined` if not found) without
-    updating the "recently used"-ness of the key.
+If that isn't to your liking, check out
+[@isaacs/ttlcache](http://npm.im/@isaacs/ttlcache).
 
-    (If you find yourself using this a lot, you *might* be using the
-    wrong sort of data structure, but there are some use cases where
-    it's handy.)
+## Storing Undefined Values
 
-* `del(key)`
+This cache never stores undefined values, as `undefined` is used
+internally in a few places to indicate that a key is not in the
+cache.
 
-    Deletes a key out of the cache.
+You may call `cache.set(key, undefined)`, but this is just
+an alias for `cache.delete(key)`. Note that this has the effect
+that `cache.has(key)` will return _false_ after setting it to
+undefined.
 
-* `reset()`
+```js
+cache.set(myKey, undefined)
+cache.has(myKey) // false!
+```
 
-    Clear the cache entirely, throwing away all values.
+If you need to track `undefined` values, and still note that the
+key is in the cache, an easy workaround is to use a sigil object
+of your own.
+
+```js
+import { LRUCache } from 'lru-cache'
+const undefinedValue = Symbol('undefined')
+const cache = new LRUCache(...)
+const mySet = (key, value) =>
+  cache.set(key, value === undefined ? undefinedValue : value)
+const myGet = (key, value) => {
+  const v = cache.get(key)
+  return v === undefinedValue ? undefined : v
+}
+```
 
-* `has(key)`
+## Tracing and Observability
+
+Most methods can accept a `status` option, which is an
+[`LRUCache.Status`](https://isaacs.github.io/node-lru-cache/interfaces/LRUCache.LRUCache.Status.html)
+object that will be decorated along the operation with
+indications about what was done and why.
+
+Additionally, this library is instrumented using the
+[`node:diagnostics_channel`](https://nodejs.org/api/diagnostics_channel.html)
+module on Node and other platforms that support it. In order to
+get diagnostics metrics, listen on the
+`channel('lru-cache:metrics')`. To get Tracing Channel traces,
+subscribe to the `tracingChannel('lru-cache')`. The
+[`LRUCache.Status`](https://isaacs.github.io/node-lru-cache/interfaces/LRUCache.LRUCache.Status.html)
+objects will be provided as the message context to those channel
+listeners.
+
+For example, you could do the following to get comprehensive
+information about every LRUCache instance in your application:
+
+```ts
+import { tracingChannel, subscribe } from 'node:diagnostics_channel'
+
+subscribe('lru-cache:metrics', (message, name) => {
+  // name will always be 'lru-cache:metrics'
+  // message will be the LRUCache.Status object for whatever
+  // synchronous operation was performed.
+  console.error('LRUCache Metrics', message)
+})
+
+tracingChannel('lru-cache').subscribe({
+  start: status => {
+    // a traced operation is starting
+  },
+  asyncStart: status => {
+    // an async traced operation is starting
+  },
+  asyncEnd: status => {
+    // an async traced operation is ending
+  }
+  error: status => {
+    // a traced operation failed
+  },
+  end: status => {
+    // a traced operation is complete
+  },
+})
+```
 
-    Check if a key is in the cache, without updating the recent-ness
-    or deleting it for being stale.
+The async `cache.fetch()` and `cache.forceFetch` methods are
+covered by `tracingChannels`. All the other operations are
+covered by the `lru-cache:metrics` channel, because they are
+strictly synchronous, and thus don't have an asynchronous
+lifecycle to track.
+
+Note that using `status` objects or using
+`node:diagnostics_channel` listeners _will_ impose a modest
+performance penalty. Creating data objects is not ever free; do
+not believe anyone who tells you otherwise. But it is as small as
+possible.
+
+### Platform Compatibility Caveat
+
+Not all platforms support the `node:diagnostics_channel` module.
+Currently, this is only available in Node, Bun, and Deno, and
+some edge computing platforms that provide a Node compatibility
+layer.
+
+To work around this, if you are loading in a non-Node
+environment, the package.json exports will direct your module
+loader to pull in a version that starts out with a dummy
+implementation, then does a conditional dynamic `import` of the
+`node:diagnostics_channel` module, and then swaps out those
+dummy objects with the real thing if it succeeds. This means that
+cache metrics and tracing channels started in the first load-time
+tick of your application will _not_ be covered, except in
+environments that load using the `require` import
+condition, or both the `node` and `esm` import conditions
+together.
+
+Top-level await _could_ be used to remove this caveat, but that
+feature is dead on arrival, unfortunately. See
+[#397](https://github.com/isaacs/node-lru-cache/issues/397) and
+[#398](https://github.com/isaacs/node-lru-cache/issues/398) for
+more details.
+
+## Performance
+
+As of April 2026, version 11 of this library is one of the most
+performant LRU cache implementations in JavaScript.
+
+Benchmarks can be extremely difficult to get right. In
+particular, the performance of set/get/delete operations on
+objects will vary _wildly_ depending on the type of key used. V8
+is highly optimized for objects with keys that are short strings,
+especially integer numeric strings. Thus any benchmark which
+tests _solely_ using numbers as keys will tend to find that an
+object-based approach performs the best.
+
+Note that coercing _anything_ to strings to use as object keys is
+unsafe, unless you can be 100% certain that no other type of
+value will be used. For example:
+
+```js
+const myCache = {}
+const set = (k, v) => (myCache[k] = v)
+const get = k => myCache[k]
+
+set({}, 'please hang onto this for me')
+set('[object Object]', 'oopsie')
+```
 
-* `forEach(function(value,key,cache), [thisp])`
+Also beware of "Just So" stories regarding performance. Garbage
+collection of large (especially: deep) object graphs can be
+incredibly costly, with several "tipping points" where it
+increases exponentially. As a result, putting that off until
+later can make it much worse, and less predictable. If a library
+performs well, but only in a scenario where the object graph is
+kept shallow, then that won't help you if you are using large
+objects as keys.
+
+In general, when attempting to use a library to improve
+performance (such as a cache like this one), it's best to choose
+an option that will perform well in the sorts of scenarios where
+you'll actually use it.
+
+This library is optimized for repeated gets and minimizing
+eviction time, since that is the expected need of a LRU. Set
+operations are somewhat slower on average than a few other
+options, in part because of that optimization. It is assumed
+that you'll be caching some costly operation, ideally as rarely
+as possible, so optimizing set over get would be unwise.
+
+If performance matters to you:
+
+1. If it's at all possible to use small integer values as keys,
+   and you can guarantee that no other types of values will be
+   used as keys, then do that, and use a cache such as
+   [lru-fast](https://npmjs.com/package/lru-fast), or
+   [mnemonist's
+   LRUCache](https://yomguithereal.github.io/mnemonist/lru-cache)
+   which uses an Object as its data store.
+
+2. Failing that, if you can use short non-numeric strings (ie,
+   less than 256 characters) as your keys, and you do not need
+   any of the other features of this library, use [mnemonist's
+   LRUCache](https://yomguithereal.github.io/mnemonist/lru-cache).
+
+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
+   also 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
+   ttl behavior or observability features, unless absolutely
+   needed. These features are convenient, and necessary in some
+   use cases, and every attempt has been made to make the
+   performance impact minimal, but it isn't nothing.
+
+## Testing
+
+When writing tests that involve TTL-related functionality, note
+that this module creates an internal reference to the global
+`performance` or `Date` objects at import time. If you import it
+statically at the top level, those references cannot be mocked or
+overridden in your test environment.
+
+To avoid this, dynamically import the package within your tests
+so that the references are captured after your mocks are applied.
+For example:
+
+```ts
+// ❌ Not recommended
+import { LRUCache } from 'lru-cache'
+// mocking timers, e.g. jest.useFakeTimers()
+
+// ✅ Recommended for TTL tests
+// mocking timers, e.g. jest.useFakeTimers()
+const { LRUCache } = await import('lru-cache')
+```
 
-    Just like `Array.prototype.forEach`.  Iterates over all the keys
-    in the cache, in order of recent-ness.  (Ie, more recently used
-    items are iterated over first.)
+This ensures that your mocked timers or time sources are
+respected when testing TTL behavior.
 
-* `rforEach(function(value,key,cache), [thisp])`
+Additionally, you can pass in a `perf` option when creating your
+LRUCache instance. This option accepts any object with a `now`
+method that returns a number.
 
-    The same as `cache.forEach(...)` but items are iterated over in
-    reverse order.  (ie, less recently used items are iterated over
-    first.)
+For example, this would be a very bare-bones time-mocking system
+you could use in your tests, without any particular test
+framework:
 
-* `keys()`
+```ts
+import { LRUCache } from 'lru-cache'
 
-    Return an array of the keys in the cache.
+let myClockTime = 0
 
-* `values()`
+const cache = new LRUCache<string>({
+  max: 10,
+  ttl: 1000,
+  perf: {
+    now: () => myClockTime,
+  },
+})
 
-    Return an array of the values in the cache.
+// run tests, updating myClockTime as needed
+```
 
-* `length`
+## Breaking Changes in Version 7
 
-    Return total length of objects in cache taking into account
-    `length` options function.
+This library changed to a different algorithm and internal data
+structure in version 7, yielding significantly better
+performance, albeit with some subtle changes as a result.
 
-* `itemCount`
+If you were relying on the internals of LRUCache in version 6 or
+before, it probably will not work in version 7 and above.
 
-    Return total quantity of objects currently in cache. Note, that
-    `stale` (see options) items are returned as part of this item
-    count.
+## Breaking Changes in Version 8
 
-* `dump()`
+- 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 was 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.
 
-    Return an array of the cache entries ready for serialization and usage
-    with 'destinationCache.load(arr)`.
+## Breaking Changes in Version 9
 
-* `load(cacheEntriesArray)`
+- Named export only, no default export.
+- AbortController polyfill returned, albeit with a warning when
+  used.
 
-    Loads another cache entries array, obtained with `sourceCache.dump()`,
-    into the cache. The destination cache is reset before loading new entries
+## Breaking Changes in Version 10
 
-* `prune()`
+- `cache.fetch()` return type is now `Promise<V | undefined>`
+  instead of `Promise<V | void>`. This is an irrelevant change
+  practically speaking, but can require changes for TypeScript
+  users.
 
-    Manually iterates over the entire cache proactively pruning old entries
+For more info, see the [change log](CHANGELOG.md).

package/node_modules/lru-cache/dist/commonjs/browser/diagnostics-channel-browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics-channel-browser.d.ts","sourceRoot":"","sources":["../../../src/diagnostics-channel-browser.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,cAAc,EACpB,MAAM,0BAA0B,CAAA;AACjC,YAAY,EAAE,cAAc,EAAE,OAAO,EAAE,CAAA;AAGvC,eAAO,MAAM,OAAO,EAAY,OAAO,CAAC,OAAO,CAAC,CAAA;AAChD,eAAO,MAAM,OAAO,EAAY,cAAc,CAAC,OAAO,CAAC,CAAA"}

package/node_modules/lru-cache/dist/commonjs/browser/diagnostics-channel-browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics-channel-browser.js","sourceRoot":"","sources":["../../../src/diagnostics-channel-browser.ts"],"names":[],"mappings":";;;AAQA,MAAM,KAAK,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,CAAA;AAC1B,QAAA,OAAO,GAAG,KAAyB,CAAA;AACnC,QAAA,OAAO,GAAG,KAAgC,CAAA","sourcesContent":["// this is used in ESM environments that follow the 'browser' import\n// condition, to avoid even trying to load node:diagnostics_channel\nimport {\n  type Channel,\n  type TracingChannel,\n} from 'node:diagnostics_channel'\nexport type { TracingChannel, Channel }\n\nconst dummy = { hasSubscribers: false }\nexport const metrics = dummy as Channel<unknown>\nexport const tracing = dummy as TracingChannel<unknown>\n"]}

package/node_modules/lru-cache/dist/commonjs/browser/diagnostics-channel.d.ts

@@ -0,0 +1,5 @@
+import { type Channel, type TracingChannel } from 'node:diagnostics_channel';
+export type { TracingChannel, Channel };
+export declare const metrics: Channel<unknown>;
+export declare const tracing: TracingChannel<unknown>;
+//# sourceMappingURL=diagnostics-channel-browser.d.ts.map

package/node_modules/lru-cache/dist/commonjs/browser/diagnostics-channel.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tracing = exports.metrics = void 0;
+const dummy = { hasSubscribers: false };
+exports.metrics = dummy;
+exports.tracing = dummy;
+//# sourceMappingURL=diagnostics-channel-browser.js.map