@ndlib/ndlib-cdk2 1.0.19 → 1.0.20

package/lib/internal-lambdas/sourceWatcherLambda/src/node_modules/lru-cache/README.md

@@ -31,9 +31,11 @@ npm install lru-cache --save
 
 ```js
 // hybrid module, either works
-import LRUCache from 'lru-cache'
+import { LRUCache } from 'lru-cache'
 // or:
-const LRUCache = require('lru-cache')
+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.
@@ -70,7 +72,11 @@ const options = {
 
   // async method to use for cache.fetch(), for
   // stale-while-revalidate type of behavior
-  fetchMethod: async (key, staleValue, { options, signal }) => {},
+  fetchMethod: async (
+    key,
+    staleValue,
+    { options, signal, context }
+  ) => {},
 }
 
 const cache = new LRUCache(options)
@@ -93,11 +99,34 @@ assert.equal(cache.get({ a: 1 }), undefined)
 cache.clear() // empty the cache
 ```
 
-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
 TTL pruning or explicit deletions). Note that fewer items may be
@@ -110,7 +139,7 @@ must be a positive integer if set.
 **It is strongly recommended to set a `max` to prevent unbounded
 growth of the cache.** See "Storage Bounds Safety" below.
 
-### `maxSize`
+### `maxSize` (read only)
 
 Set to a positive integer to track the sizes of items added to
 the cache, and automatically evict items in order to stay below
@@ -160,9 +189,7 @@ If the `size` (or return value of `sizeCalculation`) for a given
 entry is greater than `maxEntrySize`, then the item will not be
 added to the cache.
 
-Deprecated alias: `length`
-
-### `fetchMethod`
+### `fetchMethod` (read only)
 
 Function that is used to make background asynchronous fetches.
 Called with `fetchMethod(key, staleValue, { signal, options,
@@ -171,9 +198,6 @@ context })`. May return a Promise.
 If `fetchMethod` is not provided, then `cache.fetch(key)` is
 equivalent to `Promise.resolve(cache.get(key))`.
 
-The `signal` object is an `AbortSignal` if that's available in
-the global object, otherwise it's a pretty close polyfill.
-
 If at any time, `signal.aborted` is set to `true`, or if the
 `signal.onabort` method is called, or if it emits an `'abort'`
 event which you can listen to with `addEventListener`, then that
@@ -197,18 +221,6 @@ For example, a DNS cache may update the TTL based on the value
 returned from a remote DNS server by changing `options.ttl` in
 the `fetchMethod`.
 
-### `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`
 
 If a `fetchMethod` throws an error or returns a rejected promise,
@@ -252,8 +264,32 @@ Set to true to return a stale value from the cache when the
 event, whether user-triggered, or due to internal cache behavior.
 
 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`
 
@@ -301,7 +337,7 @@ AbortSignals.
 This may be overridden on the `fetch()` call or in the
 `fetchMethod` itself.
 
-### `dispose`
+### `dispose` (read only)
 
 Function that is called on items when they are dropped from the
 cache, as `this.dispose(value, key, reason)`.
@@ -316,10 +352,7 @@ the `dispose()` function call, it will break things in subtle and
 weird ways.
 
 Unlike several other options, this may _not_ be overridden by
-passing an option to `set()`, for performance reasons. If
-disposal functions may vary between cache entries, then the
-entire list must be scanned on every cache swap, even if no
-disposal function is in use.
+passing an option to `set()`, for performance reasons.
 
 The `reason` will be one of the following strings, corresponding
 to the reason for the item's deletion:
@@ -336,7 +369,7 @@ and deletes of in-flight asynchronous fetches, you must use the
 
 Optional, must be a function.
 
-### `disposeAfter`
+### `disposeAfter` (read only)
 
 The same as `dispose`, but called _after_ the entry is completely
 removed and the cache is once again in a clean state.
@@ -391,8 +424,7 @@ set a `max` to prevent unbounded growth of the cache.** See
 If ttl tracking is enabled, and `max` and `maxSize` are not set,
 and `ttlAutopurge` is not set, then a warning will be emitted
 cautioning about the potential for unbounded memory consumption.
-
-Deprecated alias: `maxAge`
+(The TypeScript definitions will also discourage this.)
 
 ### `noUpdateTTL`
 
@@ -455,8 +487,6 @@ This may be overridden by passing an options object to
 
 Boolean, default false, only relevant if `ttl` is set.
 
-Deprecated alias: `stale`
-
 ### `noDeleteOnStaleGet`
 
 When using time-expiring entries with `ttl`, by default stale
@@ -500,11 +530,17 @@ Boolean, default false, only relevant if `ttl` is set.
 
 ## API
 
-### `new LRUCache(options)`
+### `new LRUCache<K, V, FC = unknown>(options)`
 
 Create a new LRUCache. All options are documented above, and are
 on the cache as public members.
 
+The `K` and `V` types define the key and value types,
+respectively. The optional `FC` type defines the type of the
+`context` object passed to `cache.fetch()`.
+
+Keys and values **must not** be `null` or `undefined`.
+
 ### `cache.max`, `cache.maxSize`, `cache.allowStale`,
 
 `cache.noDisposeOnSet`, `cache.sizeCalculation`, `cache.dispose`,
@@ -556,20 +592,36 @@ Returns the cache object.
 For the usage of the `status` option, see **Status Tracking**
 below.
 
+If the value is `undefined`, then this is an alias for
+`cache.delete(key)`. `undefined` is never stored in the cache.
+See **Storing Undefined Values** below.
+
 ### `get(key, { updateAgeOnGet, allowStale, status } = {}) => value`
 
 Return a value from the cache.
 
 Will update the recency of the cache entry found.
 
-If the key is not found, `get()` will return `undefined`. This
-can be confusing when setting values specifically to `undefined`,
-as in `cache.set(key, undefined)`. Use `cache.has()` to
-determine whether a key is present in the cache at all.
+If the key is not found, `get()` will return `undefined`.
 
 For the usage of the `status` option, see **Status Tracking**
 below.
 
+### `info(key) => Entry | undefined`
+
+Return an `Entry` object containing the currently cached value,
+as well as ttl and size information if available. Returns
+undefined if the key is not found in the cache.
+
+Unlike `dump()` (which is designed to be portable and survive
+serialization), the `start` value is always the current
+timestamp, and the `ttl` is a calculated remaining time to live
+(negative if expired).
+
+Note that stale values are always returned, rather than being
+pruned and treated as if they were not in the cache. If you wish
+to exclude stale entries, guard against a negative `ttl` value.
+
 ### `async fetch(key, options = {}) => Promise`
 
 The following options are supported:
@@ -587,8 +639,8 @@ The following options are supported:
   a different object, because it must also respond to internal
   cache state changes, but aborting this signal will abort the
   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`.
 
 If the value is in the cache and not stale, then the returned
 Promise resolves to the value.
@@ -629,6 +681,39 @@ If a `signal` is passed to the `fetch()` call, then aborting the
 signal will abort the fetch and cause the `fetch()` promise to
 reject with the reason provided.
 
+#### 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 resolve on the same
+promise<sup>1</sup>,
+_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.
+
+**1**: Ie, they're not the "same Promise", but they resolve at
+the same time, because they're both waiting on the same
+underlying fetchMethod response.
+
 ### `peek(key, { allowStale } = {}) => value`
 
 Like `get()` but doesn't update recency or delete stale items.
@@ -643,7 +728,7 @@ use. Age is updated if `updateAgeOnHas` is set to `true` in
 either the options or the constructor.
 
 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
 `has` field.
 
@@ -660,8 +745,6 @@ Returns `true` if the key was deleted, `false` otherwise.
 
 Clear the cache entirely, throwing away all values.
 
-Deprecated alias: `reset()`
-
 ### `keys()`
 
 Return a generator yielding the keys in the cache, in order from
@@ -731,8 +814,6 @@ available.
 Delete any stale entries. Returns `true` if anything was
 removed, `false` otherwise.
 
-Deprecated alias: `prune`
-
 ### `getRemainingTTL(key)`
 
 Return the number of ms left in the item's TTL. If item is not
@@ -760,68 +841,11 @@ Evict the least recently used item, returning its value.
 
 Returns `undefined` if cache is empty.
 
-### Internal Methods and Properties
-
-In order to optimize performance as much as possible, "private"
-members and methods are exposed on the object as normal
-properties, rather than being accessed via Symbols, private
-members, or closure variables.
-
-**Do not use or rely on these.** They will change or be removed
-without notice. They will cause undefined behavior if used
-inappropriately. There is no need or reason to ever call them
-directly.
-
-This documentation is here so that it is especially clear that
-this not "undocumented" because someone forgot; it _is_
-documented, and the documentation is telling you not to do it.
-
-**Do not report bugs that stem from using these properties.**
-They will be ignored.
-
-- `initializeTTLTracking()` Set up the cache for tracking TTLs
-- `updateItemAge(index)` Called when an item age is updated, by
-  internal ID
-- `setItemTTL(index)` Called when an item ttl is updated, by
-  internal ID
-- `isStale(index)` Called to check an item's staleness, by
-  internal ID
-- `initializeSizeTracking()` Set up the cache for tracking item
-  size. Called automatically when a size is specified.
-- `removeItemSize(index)` Updates the internal size calculation
-  when an item is removed or modified, by internal ID
-- `addItemSize(index)` Updates the internal size calculation when
-  an item is added or modified, by internal ID
-- `indexes()` An iterator over the non-stale internal IDs, from
-  most recently to least recently used.
-- `rindexes()` An iterator over the non-stale internal IDs, from
-  least recently to most recently used.
-- `newIndex()` Create a new internal ID, either reusing a deleted
-  ID, evicting the least recently used ID, or walking to the end
-  of the allotted space.
-- `evict()` Evict the least recently used internal ID, returning
-  its ID. Does not do any bounds checking.
-- `connect(p, n)` Connect the `p` and `n` internal IDs in the
-  linked list.
-- `moveToTail(index)` Move the specified internal ID to the most
-  recently used position.
-- `keyMap` Map of keys to internal IDs
-- `keyList` List of keys by internal ID
-- `valList` List of values by internal ID
-- `sizes` List of calculated sizes by internal ID
-- `ttls` List of TTL values by internal ID
-- `starts` List of start time values by internal ID
-- `next` Array of "next" pointers by internal ID
-- `prev` Array of "previous" pointers by internal ID
-- `head` Internal ID of least recently used item
-- `tail` Internal ID of most recently used item
-- `free` Stack of deleted internal IDs
-
 ## Status Tracking
 
 Occasionally, it may be useful to track the internal behavior of
 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.
 
 The `status` option should be a plain JavaScript object.
@@ -1036,6 +1060,38 @@ const cache = {
 If that isn't to your liking, check out
 [@isaacs/ttlcache](http://npm.im/@isaacs/ttlcache).
 
+## Storing Undefined Values
+
+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.
+
+You may call `cache.set(key, undefined)`, but this is just an
+an alias for `cache.delete(key)`. Note that this has the effect
+that `cache.has(key)` will return _false_ after setting it to
+undefined.
+
+```js
+cache.set(myKey, undefined)
+cache.has(myKey) // false!
+```
+
+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
+}
+```
+
 ## Performance
 
 As of January 2022, version 7 of this library is one of the most
@@ -1092,13 +1148,24 @@ If performance matters to you:
    [mnemonist's
    LRUCache](https://yomguithereal.github.io/mnemonist/lru-cache)
    which uses an Object as its data store.
+
 2. Failing that, if at all possible, use short non-numeric
    strings (ie, less than 256 characters) as your keys, and use
    [mnemonist's
    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
    ttl behavior, unless absolutely needed. These features are
    convenient, and necessary in some use cases, and every attempt
@@ -1114,4 +1181,24 @@ performance, albeit with some subtle changes as a result.
 If you were relying on the internals of LRUCache in version 6 or
 before, it probably will not work in version 7 and above.
 
+## 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 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.
+
+## Changes in Version 9
+
+- Named export only, no default export.
+- AbortController polyfill returned, albeit with a warning when
+  used.
+
 For more info, see the [change log](CHANGELOG.md).