This commit is contained in:
2026-08-14 16:03:47 +01:00
parent fd53e3f4fb
commit dfdc3b2840
2463 changed files with 186456 additions and 111315 deletions
+96 -10
View File
@@ -215,9 +215,95 @@ const myGet = (key, value) => {
}
```
## 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
},
})
```
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 January 2022, version 7 of this library is one of the most
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
@@ -272,9 +358,9 @@ If performance matters to you:
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
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
@@ -286,14 +372,14 @@ If performance matters to you:
(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).
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, 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.
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
@@ -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"}
@@ -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"]}
@@ -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
@@ -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
File diff suppressed because it is too large Load Diff
File diff suppressed because one or more lines are too long
File diff suppressed because it is too large Load Diff
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@@ -0,0 +1,12 @@
/**
* this provides the default Perf object source, either the
* `performance` global, or the `Date` constructor.
*
* it can be passed in via configuration to override it
* for a single LRU object.
*/
export type Perf = {
now: () => number;
};
export declare const defaultPerf: Perf;
//# sourceMappingURL=perf.d.ts.map
@@ -0,0 +1 @@
{"version":3,"file":"perf.d.ts","sourceRoot":"","sources":["../../../src/perf.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,IAAI,GAAG;IAAE,GAAG,EAAE,MAAM,MAAM,CAAA;CAAE,CAAA;AACxC,eAAO,MAAM,WAAW,EAAE,IAQG,CAAA"}
@@ -0,0 +1,10 @@
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.defaultPerf = void 0;
exports.defaultPerf = (typeof performance === 'object' &&
performance &&
typeof performance.now === 'function') ?
/* c8 ignore start - this gets covered, but c8 gets confused */
performance
: /* c8 ignore stop */ Date;
//# sourceMappingURL=perf.js.map
@@ -0,0 +1 @@
{"version":3,"file":"perf.js","sourceRoot":"","sources":["../../../src/perf.ts"],"names":[],"mappings":";;;AAQa,QAAA,WAAW,GACtB,CACE,OAAO,WAAW,KAAK,QAAQ;IAC/B,WAAW;IACX,OAAO,WAAW,CAAC,GAAG,KAAK,UAAU,CACtC,CAAC,CAAC;IACD,+DAA+D;IAC/D,WAAW;IACb,CAAC,CAAC,oBAAoB,CAAC,IAAI,CAAA","sourcesContent":["/**\n * this provides the default Perf object source, either the\n * `performance` global, or the `Date` constructor.\n *\n * it can be passed in via configuration to override it\n * for a single LRU object.\n */\nexport type Perf = { now: () => number }\nexport const defaultPerf: Perf =\n (\n typeof performance === 'object' &&\n performance &&\n typeof performance.now === 'function'\n ) ?\n /* c8 ignore start - this gets covered, but c8 gets confused */\n performance\n : /* c8 ignore stop */ Date\n"]}
@@ -0,0 +1 @@
{"version":3,"file":"diagnostics-channel-cjs.cjs","sourceRoot":"","sources":["../../src/diagnostics-channel-cjs.cts"],"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 CJS environments that do NOT follow the 'node' 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"]}
@@ -0,0 +1 @@
{"version":3,"file":"diagnostics-channel-cjs.d.cts","sourceRoot":"","sources":["../../src/diagnostics-channel-cjs.cts"],"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"}
@@ -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-cjs.d.cts.map
@@ -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-cjs.cjs.map
+109 -32
View File
@@ -1,9 +1,8 @@
/**
* @module LRUCache
*/
export type Perf = {
now: () => number;
};
import type { Perf } from './perf.js';
export type { Perf } from './perf.js';
declare const TYPE: unique symbol;
export type PosInt = number & {
[TYPE]: 'Positive Integer';
@@ -119,8 +118,16 @@ export declare namespace LRUCache {
*
* The `status` option should be a plain JavaScript object. The following
* fields will be set on it appropriately, depending on the situation.
*
* These objects are also the context objects passed to listeners on the
* `lru-cache:metrics` diagnostic channel, and the `lru-cache` tracing
* channels, in platforms that support them.
*/
interface Status<V> {
interface Status<K, V, FC = unknown> {
/**
* The operation being performed
*/
op?: 'get' | 'set' | 'memo' | 'fetch' | 'delete' | 'has' | 'peek';
/**
* The status of a set() operation.
*
@@ -129,7 +136,37 @@ export declare namespace LRUCache {
* - replace: the item was in the cache, and replaced
* - miss: the item was not added to the cache for some reason
*/
set?: 'add' | 'update' | 'replace' | 'miss';
set?: 'add' | 'update' | 'replace' | 'miss' | 'deleted';
/**
* The status of a delete() operation.
*/
delete?: LRUCache.DisposeReason;
/**
* The result of a peek() operation
*
* - hit: the item was found and returned
* - stale: the item is in the cache, but past its ttl and not returned
* - miss: item not in the cache
*/
peek?: 'hit' | 'miss' | 'stale';
/**
* The status of a memo() operation.
*
* - 'hit': the item was found in the cache and returned
* - 'miss': the `memoMethod` function was called
*/
memo?: 'hit' | 'miss';
/**
* The `context` option provided to a memo or fetch operation
*
* In practice, of course, this will be the same type as the `FC`
* fetch context param used to instantiate the LRUCache, but the
* convolutions of threading that through would get quite complicated,
* and preclude forcing/forbidding the passing of a `context` param
* where it is/isn't expected, which is more valuable for error
* prevention.
*/
context?: unknown;
/**
* the ttl stored for the item, or undefined if ttls are not used.
*/
@@ -160,8 +197,15 @@ export declare namespace LRUCache {
*/
maxEntrySizeExceeded?: true;
/**
* The old value, specified in the case of `set:'update'` or
* `set:'replace'`
* The key that was set or retrieved
*/
key?: K;
/**
* The value that was set
*/
value?: V;
/**
* The old value, specified in the case of `set:'replace'`
*/
oldValue?: V;
/**
@@ -187,6 +231,10 @@ export declare namespace LRUCache {
* {@link FetchOptions.forceRefresh} was specified.
*/
fetch?: 'get' | 'inflight' | 'miss' | 'hit' | 'stale' | 'refresh';
/**
* `forceRefresh` option was used for either a fetch or memo operation
*/
forceRefresh?: boolean;
/**
* The {@link OptionsBase.fetchMethod} was called
*/
@@ -208,7 +256,7 @@ export declare namespace LRUCache {
fetchAborted?: true;
/**
* The abort signal received was ignored, and the fetch was allowed to
* continue.
* continue in the background.
*/
fetchAbortIgnored?: true;
/**
@@ -224,15 +272,27 @@ export declare namespace LRUCache {
*
* - fetching: The item is currently being fetched. If a previous value
* is present and allowed, that will be returned.
* - stale: The item is in the cache, and is stale.
* - stale: The item is in the cache, and is stale. If it was returned,
* then the `returnedStale` flag will be set.
* - stale-fetching: The value is being fetched in the background, but is
* currently stale. If the stale value was returned, then the
* `returnedStale` flag will be set.
* - hit: the item is in the cache
* - miss: the item is not in the cache
*/
get?: 'stale' | 'hit' | 'miss';
get?: 'stale' | 'hit' | 'miss' | 'fetching' | 'stale-fetching';
/**
* A fetch or get operation returned a stale value.
*/
returnedStale?: true;
/**
* A tracingChannel trace was started for this operation
*/
trace?: boolean;
/**
* A reference to the cache instance associated with this operation
*/
cache?: LRUCache<K & {}, V & {}, FC>;
}
/**
* options which override the options set in the LRUCache constructor
@@ -250,7 +310,7 @@ export declare namespace LRUCache {
* the fetchMethod is called.
*/
interface FetcherFetchOptions<K, V, FC = unknown> extends Pick<OptionsBase<K, V, FC>, 'allowStale' | 'updateAgeOnGet' | 'noDeleteOnStaleGet' | 'sizeCalculation' | 'ttl' | 'noDisposeOnSet' | 'noUpdateTTL' | 'noDeleteOnFetchRejection' | 'allowStaleOnFetchRejection' | 'ignoreFetchAbort' | 'allowStaleOnFetchAbort'> {
status?: Status<V>;
status?: Status<K, V, FC>;
size?: Size;
}
/**
@@ -272,7 +332,7 @@ export declare namespace LRUCache {
*/
context?: FC;
signal?: AbortSignal;
status?: Status<V>;
status?: Status<K, V, FC>;
}
/**
* Options provided to {@link LRUCache#fetch} when the FC type is something
@@ -285,8 +345,8 @@ export declare namespace LRUCache {
* Options provided to {@link LRUCache#fetch} when the FC type is
* `undefined` or `void`
*/
interface FetchOptionsNoContext<K, V> extends FetchOptions<K, V, undefined> {
context?: undefined;
interface FetchOptionsNoContext<K, V, FC extends undefined | void = undefined> extends FetchOptions<K, V, FC> {
context?: FC;
}
interface MemoOptions<K, V, FC = unknown> extends Pick<OptionsBase<K, V, FC>, 'allowStale' | 'updateAgeOnGet' | 'noDeleteOnStaleGet' | 'sizeCalculation' | 'ttl' | 'noDisposeOnSet' | 'noUpdateTTL' | 'noDeleteOnFetchRejection' | 'allowStaleOnFetchRejection' | 'ignoreFetchAbort' | 'allowStaleOnFetchAbort'> {
/**
@@ -303,7 +363,7 @@ export declare namespace LRUCache {
* be required.
*/
context?: FC;
status?: Status<V>;
status?: Status<K, V, FC>;
}
/**
* Options provided to {@link LRUCache#memo} when the FC type is something
@@ -316,8 +376,8 @@ export declare namespace LRUCache {
* Options provided to {@link LRUCache#memo} when the FC type is
* `undefined` or `void`
*/
interface MemoOptionsNoContext<K, V> extends MemoOptions<K, V, undefined> {
context?: undefined;
interface MemoOptionsNoContext<K, V, FC extends undefined | void = undefined> extends MemoOptions<K, V, FC> {
context?: FC;
}
/**
* Options provided to the
@@ -345,7 +405,7 @@ export declare namespace LRUCache {
* the memoMethod is called.
*/
interface MemoizerMemoOptions<K, V, FC = unknown> extends Pick<OptionsBase<K, V, FC>, 'allowStale' | 'updateAgeOnGet' | 'noDeleteOnStaleGet' | 'sizeCalculation' | 'ttl' | 'noDisposeOnSet' | 'noUpdateTTL'> {
status?: Status<V>;
status?: Status<K, V, FC>;
size?: Size;
start?: Milliseconds;
}
@@ -353,18 +413,19 @@ export declare namespace LRUCache {
* Options that may be passed to the {@link LRUCache#has} method.
*/
interface HasOptions<K, V, FC> extends Pick<OptionsBase<K, V, FC>, 'updateAgeOnHas'> {
status?: Status<V>;
status?: Status<K, V, FC>;
}
/**
* Options that may be passed to the {@link LRUCache#get} method.
*/
interface GetOptions<K, V, FC> extends Pick<OptionsBase<K, V, FC>, 'allowStale' | 'updateAgeOnGet' | 'noDeleteOnStaleGet'> {
status?: Status<V>;
status?: Status<K, V, FC>;
}
/**
* Options that may be passed to the {@link LRUCache#peek} method.
*/
interface PeekOptions<K, V, FC> extends Pick<OptionsBase<K, V, FC>, 'allowStale'> {
status?: Status<K, V, FC>;
}
/**
* Options that may be passed to the {@link LRUCache#set} method.
@@ -385,7 +446,7 @@ export declare namespace LRUCache {
* method is in use.
*/
start?: Milliseconds;
status?: Status<V>;
status?: Status<K, V, FC>;
}
/**
* The type signature for the {@link OptionsBase.fetchMethod} option.
@@ -638,6 +699,20 @@ export declare namespace LRUCache {
* though for most cases, only minimally.
*/
maxSize?: Size;
/**
* The effective size for background fetch promises.
*
* This has no effect unless `maxSize` and `sizeCalculation` are used,
* and a {@link LRUCache.OptionsBase.fetchMethod} is provided to
* support {@link LRUCache#fetch}.
*
* If a stale value is present in the cache, then the effective size of
* the background fetch is the size of the stale item it will eventually
* replace. If not, then this value is used as its effective size.
*
* @default 1
*/
backgroundFetchSize?: number;
/**
* The maximum allowed size for any single item in the cache.
*
@@ -940,6 +1015,8 @@ export declare class LRUCache<K extends {}, V extends {}, FC = unknown> {
* {@link LRUCache.OptionsBase.ignoreFetchAbort}
*/
ignoreFetchAbort: boolean;
/** {@link LRUCache.OptionsBase.backgroundFetchSize} */
backgroundFetchSize: number;
/**
* Do not call this method unless you need to inspect the
* inner workings of the cache. If anything returned by this
@@ -962,8 +1039,8 @@ export declare class LRUCache<K extends {}, V extends {}, FC = unknown> {
readonly head: Index;
readonly tail: Index;
free: StackLike;
isBackgroundFetch: (p: any) => p is BackgroundFetch<V>;
backgroundFetch: (k: K, index: number | undefined, options: LRUCache.FetchOptions<K, V, FC>, context: any) => BackgroundFetch<V>;
isBackgroundFetch: (p: unknown) => p is BackgroundFetch<V>;
backgroundFetch: (k: K, index: number | undefined, options: LRUCache.FetchOptions<K, V, FC>, context: unknown) => BackgroundFetch<V>;
moveToTail: (index: number) => void;
indexes: (options?: {
allowStale: boolean;
@@ -1075,12 +1152,12 @@ export declare class LRUCache<K extends {}, V extends {}, FC = unknown> {
*
* Does not update age or recenty of use, or iterate over stale values.
*/
forEach(fn: (v: V, k: K, self: LRUCache<K, V, FC>) => any, thisp?: any): void;
forEach(fn: (v: V, k: K, self: LRUCache<K, V, FC>) => unknown, thisp?: unknown): void;
/**
* The same as {@link LRUCache.forEach} but items are iterated over in
* reverse order. (ie, less recently used items are iterated over first.)
*/
rforEach(fn: (v: V, k: K, self: LRUCache<K, V, FC>) => any, thisp?: any): void;
rforEach(fn: (v: V, k: K, self: LRUCache<K, V, FC>) => unknown, thisp?: unknown): void;
/**
* Delete any stale entries. Returns true if anything was removed,
* false otherwise.
@@ -1153,7 +1230,7 @@ export declare class LRUCache<K extends {}, V extends {}, FC = unknown> {
* If the value is `undefined`, then this is an alias for
* `cache.delete(key)`. `undefined` is never stored in the cache.
*/
set(k: K, v: V | BackgroundFetch<V> | undefined, setOptions?: LRUCache.SetOptions<K, V, FC>): this;
set(k: K, v: V | undefined, setOptions?: LRUCache.SetOptions<K, V, FC>): this;
/**
* Evict the least recently used item, returning its value or
* `undefined` if cache is empty.
@@ -1269,8 +1346,8 @@ export declare class LRUCache<K extends {}, V extends {}, FC = unknown> {
* the same time, because they're both waiting on the same
* underlying fetchMethod response.
*/
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<undefined | 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<undefined | V>;
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<undefined | 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<undefined | V>;
/**
* In some cases, `cache.fetch()` may resolve to `undefined`, either because
* a {@link LRUCache.OptionsBase#fetchMethod} was not provided (turning
@@ -1284,8 +1361,8 @@ export declare class LRUCache<K extends {}, V extends {}, FC = unknown> {
* cumbersome, but testing for `undefined` can also be annoying, this method
* can be used, which will reject if `this.fetch()` resolves to undefined.
*/
forceFetch(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<V>;
forceFetch(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<V>;
forceFetch(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<V>;
forceFetch(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<V>;
/**
* If the key is found in the cache, then this is equivalent to
* {@link LRUCache#get}. If not, in the cache, then calculate the value using
@@ -1300,8 +1377,8 @@ export declare class LRUCache<K extends {}, V extends {}, FC = unknown> {
* relevant in the course of fetching the data. It is only relevant for the
* course of a single `memo()` operation, and discarded afterwards.
*/
memo(k: K, memoOptions: unknown extends FC ? LRUCache.MemoOptions<K, V, FC> : FC extends undefined | void ? LRUCache.MemoOptionsNoContext<K, V> : LRUCache.MemoOptionsWithContext<K, V, FC>): V;
memo(k: unknown extends FC ? K : FC extends undefined | void ? K : never, memoOptions?: unknown extends FC ? LRUCache.MemoOptions<K, V, FC> : FC extends undefined | void ? LRUCache.MemoOptionsNoContext<K, V> : never): V;
memo(k: K, memoOptions: unknown extends FC ? LRUCache.MemoOptions<K, V, FC> : FC extends undefined | void ? LRUCache.MemoOptionsNoContext<K, V, FC> : LRUCache.MemoOptionsWithContext<K, V, FC>): V;
memo(k: unknown extends FC ? K : FC extends undefined | void ? K : never, memoOptions?: unknown extends FC ? LRUCache.MemoOptions<K, V, FC> : FC extends undefined | void ? LRUCache.MemoOptionsNoContext<K, V, FC> : never): V;
/**
* Return a value from the cache. Will update the recency of the cache
* entry found.
File diff suppressed because one or more lines are too long
+334 -197
View File
@@ -4,75 +4,27 @@
*/
Object.defineProperty(exports, "__esModule", { value: true });
exports.LRUCache = void 0;
const defaultPerf = (typeof performance === 'object' &&
performance &&
typeof performance.now === 'function') ?
performance
: Date;
const diagnostics_channel_js_1 = require("./diagnostics-channel.js");
const perf_js_1 = require("./perf.js");
const hasSubscribers = () => diagnostics_channel_js_1.metrics.hasSubscribers || diagnostics_channel_js_1.tracing.hasSubscribers;
const warned = new Set();
/* c8 ignore start */
const PROCESS = (typeof process === 'object' && !!process ?
process
: {});
/* c8 ignore start */
const emitWarning = (msg, type, code, fn) => {
typeof PROCESS.emitWarning === 'function' ?
PROCESS.emitWarning(msg, type, code, fn)
: console.error(`[${code}] ${type}: ${msg}`);
};
let AC = globalThis.AbortController;
let AS = globalThis.AbortSignal;
/* c8 ignore start */
if (typeof AC === 'undefined') {
//@ts-ignore
AS = class AbortSignal {
onabort;
_onabort = [];
reason;
aborted = false;
addEventListener(_, fn) {
this._onabort.push(fn);
}
};
//@ts-ignore
AC = class AbortController {
constructor() {
warnACPolyfill();
}
signal = new AS();
abort(reason) {
if (this.signal.aborted)
return;
//@ts-ignore
this.signal.reason = reason;
//@ts-ignore
this.signal.aborted = true;
//@ts-ignore
for (const fn of this.signal._onabort) {
fn(reason);
}
this.signal.onabort?.(reason);
}
};
let printACPolyfillWarning = PROCESS.env?.LRU_CACHE_IGNORE_AC_WARNING !== '1';
const warnACPolyfill = () => {
if (!printACPolyfillWarning)
return;
printACPolyfillWarning = false;
emitWarning('AbortController is not defined. If using lru-cache in ' +
'node 14, load an AbortController polyfill from the ' +
'`node-abort-controller` package. A minimal polyfill is ' +
'provided for use by LRUCache.fetch(), but it should not be ' +
'relied upon in other contexts (eg, passing it to other APIs that ' +
'use AbortController/AbortSignal might have undesirable effects). ' +
'You may disable this with LRU_CACHE_IGNORE_AC_WARNING=1 in the env.', 'NO_ABORT_CONTROLLER', 'ENOTSUP', warnACPolyfill);
};
}
/* c8 ignore stop */
const emitWarning = (msg, type, code, fn) => {
if (typeof PROCESS.emitWarning === 'function') {
PROCESS.emitWarning(msg, type, code, fn);
}
else {
//oxlint-disable-next-line no-console
console.error(`[${code}] ${type}: ${msg}`);
}
};
const shouldWarn = (code) => !warned.has(code);
const TYPE = Symbol('type');
const isPosInt = (n) => n && n === Math.floor(n) && n > 0 && isFinite(n);
/* c8 ignore start */
const isPosInt = (n) => !!n && n === Math.floor(n) && n > 0 && isFinite(n);
// This is a little bit ridiculous, tbh.
// The maximum array length is 2^32-1 or thereabouts on most JS impls.
// And well before that point, you're caching the entire world, I mean,
@@ -81,6 +33,7 @@ const isPosInt = (n) => n && n === Math.floor(n) && n > 0 && isFinite(n);
// zeroes at init time is brutal when you get that big.
// But why not be complete?
// Maybe in the future, these limits will have expanded.
/* c8 ignore start */
const getUintArray = (max) => !isPosInt(max) ? null
: max <= Math.pow(2, 8) ? Uint8Array
: max <= Math.pow(2, 16) ? Uint16Array
@@ -95,7 +48,9 @@ class ZeroArray extends Array {
}
}
class Stack {
/* c8 ignore start - not sure why this is showing up uncovered?? */
heap;
/* c8 ignore stop */
length;
// private constructor
static #constructing = false;
@@ -215,6 +170,8 @@ class LRUCache {
* {@link LRUCache.OptionsBase.ignoreFetchAbort}
*/
ignoreFetchAbort;
/** {@link LRUCache.OptionsBase.backgroundFetchSize} */
backgroundFetchSize;
// computed properties
#size;
#calculatedSize;
@@ -325,13 +282,14 @@ class LRUCache {
return this.#disposeAfter;
}
constructor(options) {
const { max = 0, ttl, ttlResolution = 1, ttlAutopurge, updateAgeOnGet, updateAgeOnHas, allowStale, dispose, onInsert, disposeAfter, noDisposeOnSet, noUpdateTTL, maxSize = 0, maxEntrySize = 0, sizeCalculation, fetchMethod, memoMethod, noDeleteOnFetchRejection, noDeleteOnStaleGet, allowStaleOnFetchRejection, allowStaleOnFetchAbort, ignoreFetchAbort, perf, } = options;
const { max = 0, ttl, ttlResolution = 1, ttlAutopurge, updateAgeOnGet, updateAgeOnHas, allowStale, dispose, onInsert, disposeAfter, noDisposeOnSet, noUpdateTTL, maxSize = 0, maxEntrySize = 0, sizeCalculation, fetchMethod, memoMethod, noDeleteOnFetchRejection, noDeleteOnStaleGet, allowStaleOnFetchRejection, allowStaleOnFetchAbort, ignoreFetchAbort, backgroundFetchSize = 1, perf, } = options;
this.backgroundFetchSize = backgroundFetchSize;
if (perf !== undefined) {
if (typeof perf?.now !== 'function') {
throw new TypeError('perf option must have a now() method if specified');
}
}
this.#perf = perf ?? defaultPerf;
this.#perf = perf ?? perf_js_1.defaultPerf;
if (max !== 0 && !isPosInt(max)) {
throw new TypeError('max option must be a nonnegative integer');
}
@@ -361,8 +319,8 @@ class LRUCache {
this.#fetchMethod = fetchMethod;
this.#hasFetchMethod = !!fetchMethod;
this.#keyMap = new Map();
this.#keyList = new Array(max).fill(undefined);
this.#valList = new Array(max).fill(undefined);
this.#keyList = Array.from({ length: max }).fill(undefined);
this.#valList = Array.from({ length: max }).fill(undefined);
this.#next = new UintArray(max);
this.#prev = new UintArray(max);
this.#head = 0;
@@ -446,44 +404,55 @@ class LRUCache {
this.#ttls = ttls;
this.#starts = starts;
const purgeTimers = this.ttlAutopurge ?
new Array(this.#max)
Array.from({
length: this.#max,
})
: undefined;
this.#autopurgeTimers = purgeTimers;
this.#setItemTTL = (index, ttl, start = this.#perf.now()) => {
starts[index] = ttl !== 0 ? start : 0;
ttls[index] = ttl;
// clear out the purge timer if we're setting TTL to 0, and
// previously had a ttl purge timer running, so it doesn't
// fire unnecessarily.
if (purgeTimers?.[index]) {
clearTimeout(purgeTimers[index]);
purgeTimers[index] = undefined;
}
if (ttl !== 0 && purgeTimers) {
const t = setTimeout(() => {
if (this.#isStale(index)) {
this.#delete(this.#keyList[index], 'expire');
}
}, ttl + 1);
// unref() not supported on all platforms
/* c8 ignore start */
if (t.unref) {
t.unref();
}
/* c8 ignore stop */
purgeTimers[index] = t;
}
setPurgetTimer(index, ttl);
};
this.#updateItemAge = index => {
starts[index] = ttls[index] !== 0 ? this.#perf.now() : 0;
setPurgetTimer(index, ttls[index]);
};
// clear out the purge timer if we're setting TTL to 0, and
// previously had a ttl purge timer running, so it doesn't
// fire unnecessarily. Don't need to do this if we're not doing
// autopurge.
const setPurgetTimer = !this.ttlAutopurge ?
() => { }
: (index, ttl) => {
if (purgeTimers?.[index]) {
clearTimeout(purgeTimers[index]);
purgeTimers[index] = undefined;
}
if (ttl && ttl !== 0 && purgeTimers) {
const t = setTimeout(() => {
if (this.#isStale(index)) {
this.#delete(this.#keyList[index], 'expire');
}
}, ttl + 1);
// unref() not supported on all platforms
/* c8 ignore start */
if (t.unref) {
t.unref();
}
/* c8 ignore stop */
purgeTimers[index] = t;
}
};
this.#statusTTL = (status, index) => {
if (ttls[index]) {
const ttl = ttls[index];
const start = starts[index];
/* c8 ignore next */
if (!ttl || !start)
/* c8 ignore start */
if (!ttl || !start) {
return;
}
/* c8 ignore stop */
status.ttl = ttl;
status.start = start;
status.now = cachedNow || getNow();
@@ -542,12 +511,15 @@ class LRUCache {
sizes[index] = 0;
};
this.#requireSize = (k, v, size, sizeCalculation) => {
// provisionally accept background fetches.
// actual value size will be checked when they return.
if (this.#isBackgroundFetch(v)) {
return 0;
}
if (!isPosInt(size)) {
// provisionally accept background fetches.
// actual value size will be checked when they return.
if (this.#isBackgroundFetch(v)) {
// NB: this cannot occur if v.__staleWhileFetching is set,
// because in that case, it would take on the size of the
// existing entry that it temporarily replaces.
return this.backgroundFetchSize;
}
if (sizeCalculation) {
if (typeof sizeCalculation !== 'function') {
throw new TypeError('sizeCalculation must be a function');
@@ -590,10 +562,7 @@ class LRUCache {
};
*#indexes({ allowStale = this.allowStale } = {}) {
if (this.#size) {
for (let i = this.#tail; true;) {
if (!this.#isValidIndex(i)) {
break;
}
for (let i = this.#tail; this.#isValidIndex(i);) {
if (allowStale || !this.#isStale(i)) {
yield i;
}
@@ -608,10 +577,7 @@ class LRUCache {
}
*#rindexes({ allowStale = this.allowStale } = {}) {
if (this.#size) {
for (let i = this.#head; true;) {
if (!this.#isValidIndex(i)) {
break;
}
for (let i = this.#head; this.#isValidIndex(i);) {
if (allowStale || !this.#isStale(i)) {
yield i;
}
@@ -732,7 +698,7 @@ class LRUCache {
if (value === undefined)
continue;
if (fn(value, this.#keyList[i], this)) {
return this.get(this.#keyList[i], getOptions);
return this.#get(this.#keyList[i], getOptions);
}
}
}
@@ -805,7 +771,7 @@ class LRUCache {
const value = this.#isBackgroundFetch(v) ? v.__staleWhileFetching : v;
if (value === undefined)
return undefined;
/* c8 ignore end */
/* c8 ignore stop */
const entry = { value };
if (this.#ttls && this.#starts) {
const ttl = this.#ttls[i];
@@ -879,7 +845,7 @@ class LRUCache {
const age = Date.now() - entry.start;
entry.start = this.#perf.now() - age;
}
this.set(key, entry.value, entry);
this.#set(key, entry.value, entry);
}
}
/**
@@ -913,22 +879,43 @@ class LRUCache {
* `cache.delete(key)`. `undefined` is never stored in the cache.
*/
set(k, v, setOptions = {}) {
const { status = diagnostics_channel_js_1.metrics.hasSubscribers ? {} : undefined } = setOptions;
setOptions.status = status;
if (status) {
status.op = 'set';
status.key = k;
if (v !== undefined)
status.value = v;
status.cache = this;
}
const result = this.#set(k, v, setOptions);
if (status && diagnostics_channel_js_1.metrics.hasSubscribers) {
diagnostics_channel_js_1.metrics.publish(status);
}
return result;
}
#set(k, v, setOptions, bf) {
const { ttl = this.ttl, start, noDisposeOnSet = this.noDisposeOnSet, sizeCalculation = this.sizeCalculation, status, } = setOptions;
const isBF = this.#isBackgroundFetch(v);
if (v === undefined) {
if (status)
status.set = 'deleted';
this.delete(k);
return this;
}
const { ttl = this.ttl, start, noDisposeOnSet = this.noDisposeOnSet, sizeCalculation = this.sizeCalculation, status, } = setOptions;
let { noUpdateTTL = this.noUpdateTTL } = setOptions;
const size = this.#requireSize(k, v, setOptions.size || 0, sizeCalculation);
if (status && !isBF)
status.value = v;
const size = this.#requireSize(k, v, setOptions.size || 0, sizeCalculation, status);
// if the item doesn't fit, don't do anything
// NB: maxEntrySize set to maxSize by default
if (this.maxEntrySize && size > this.maxEntrySize) {
// have to delete, in case something is there already.
this.#delete(k, 'set');
if (status) {
status.set = 'miss';
status.maxEntrySizeExceeded = true;
}
// have to delete, in case something is there already.
this.#delete(k, 'set');
return this;
}
let index = this.#size === 0 ? undefined : this.#keyMap.get(k);
@@ -949,52 +936,68 @@ class LRUCache {
if (status)
status.set = 'add';
noUpdateTTL = false;
if (this.#hasOnInsert) {
if (this.#hasOnInsert && !isBF) {
this.#onInsert?.(v, k, 'add');
}
}
else {
// update
// might be updating a background fetch!
this.#moveToTail(index);
const oldVal = this.#valList[index];
if (v !== oldVal) {
if (this.#hasFetchMethod && this.#isBackgroundFetch(oldVal)) {
oldVal.__abortController.abort(new Error('replaced'));
const { __staleWhileFetching: s } = oldVal;
if (s !== undefined && !noDisposeOnSet) {
if (!noDisposeOnSet) {
if (this.#isBackgroundFetch(oldVal)) {
if (oldVal !== bf) {
// setting over a background fetch, not merely resolving it.
oldVal.__abortController.abort(new Error('replaced'));
}
const { __staleWhileFetching: s } = oldVal;
if (s !== undefined && s !== v) {
if (this.#hasDispose) {
this.#dispose?.(s, k, 'set');
}
if (this.#hasDisposeAfter) {
this.#disposed?.push([s, k, 'set']);
}
}
}
else {
if (this.#hasDispose) {
this.#dispose?.(s, k, 'set');
this.#dispose?.(oldVal, k, 'set');
}
if (this.#hasDisposeAfter) {
this.#disposed?.push([s, k, 'set']);
this.#disposed?.push([oldVal, k, 'set']);
}
}
}
else if (!noDisposeOnSet) {
if (this.#hasDispose) {
this.#dispose?.(oldVal, k, 'set');
}
if (this.#hasDisposeAfter) {
this.#disposed?.push([oldVal, k, 'set']);
}
}
this.#removeItemSize(index);
this.#addItemSize(index, size, status);
this.#valList[index] = v;
if (status) {
status.set = 'replace';
if (!isBF) {
const oldValue = oldVal && this.#isBackgroundFetch(oldVal) ?
oldVal.__staleWhileFetching
: oldVal;
if (oldValue !== undefined)
status.oldValue = oldValue;
const setType = oldValue === undefined ? 'add'
: v !== oldValue ? 'replace'
: 'update';
if (status) {
status.set = setType;
if (oldValue !== undefined)
status.oldValue = oldValue;
}
if (this.#hasOnInsert) {
this.onInsert?.(v, k, setType);
}
}
}
else if (status) {
status.set = 'update';
}
if (this.#hasOnInsert) {
this.onInsert?.(v, k, v === oldVal ? 'update' : 'replace');
else if (!isBF) {
if (status) {
status.set = 'update';
}
if (this.#hasOnInsert) {
this.onInsert?.(v, k, 'update');
}
}
}
if (ttl !== 0 && !this.#ttls) {
@@ -1049,15 +1052,18 @@ class LRUCache {
const head = this.#head;
const k = this.#keyList[head];
const v = this.#valList[head];
if (this.#hasFetchMethod && this.#isBackgroundFetch(v)) {
const isBF = this.#isBackgroundFetch(v);
if (isBF) {
v.__abortController.abort(new Error('evicted'));
}
else if (this.#hasDispose || this.#hasDisposeAfter) {
const oldValue = isBF ? v.__staleWhileFetching : v;
if ((this.#hasDispose || this.#hasDisposeAfter) &&
oldValue !== undefined) {
if (this.#hasDispose) {
this.#dispose?.(v, k, 'evict');
this.#dispose?.(oldValue, k, 'evict');
}
if (this.#hasDisposeAfter) {
this.#disposed?.push([v, k, 'evict']);
this.#disposed?.push([oldValue, k, 'evict']);
}
}
this.#removeItemSize(head);
@@ -1099,6 +1105,19 @@ class LRUCache {
* {@link LRUCache.OptionsBase.updateAgeOnHas} is set.
*/
has(k, hasOptions = {}) {
const { status = diagnostics_channel_js_1.metrics.hasSubscribers ? {} : undefined } = hasOptions;
hasOptions.status = status;
if (status) {
status.op = 'has';
status.key = k;
status.cache = this;
}
const result = this.#has(k, hasOptions);
if (diagnostics_channel_js_1.metrics.hasSubscribers)
diagnostics_channel_js_1.metrics.publish(status);
return result;
}
#has(k, hasOptions = {}) {
const { updateAgeOnHas = this.updateAgeOnHas, status } = hasOptions;
const index = this.#keyMap.get(k);
if (index !== undefined) {
@@ -1135,21 +1154,46 @@ class LRUCache {
* {@link LRUCache.OptionsBase.allowStale} is set.
*/
peek(k, peekOptions = {}) {
const { allowStale = this.allowStale } = peekOptions;
const { status = hasSubscribers() ? {} : undefined } = peekOptions;
if (status) {
status.op = 'peek';
status.key = k;
status.cache = this;
}
peekOptions.status = status;
const result = this.#peek(k, peekOptions);
if (diagnostics_channel_js_1.metrics.hasSubscribers) {
diagnostics_channel_js_1.metrics.publish(status);
}
return result;
}
#peek(k, peekOptions) {
const { status, allowStale = this.allowStale } = peekOptions;
const index = this.#keyMap.get(k);
if (index === undefined || (!allowStale && this.#isStale(index))) {
return;
if (status)
status.peek = index === undefined ? 'miss' : 'stale';
return undefined;
}
const v = this.#valList[index];
// either stale and allowed, or forcing a refresh of non-stale value
return this.#isBackgroundFetch(v) ? v.__staleWhileFetching : v;
const val = this.#isBackgroundFetch(v) ? v.__staleWhileFetching : v;
if (status) {
if (val !== undefined) {
status.peek = 'hit';
status.value = val;
}
else {
status.peek = 'miss';
}
}
return val;
}
#backgroundFetch(k, index, options, context) {
const v = index === undefined ? undefined : this.#valList[index];
if (this.#isBackgroundFetch(v)) {
return v;
}
const ac = new AC();
const ac = new AbortController();
const { signal } = options;
// when/if our AC signals, then stop listening to theirs.
signal?.addEventListener('abort', () => ac.abort(signal.reason), {
@@ -1185,7 +1229,7 @@ class LRUCache {
// cache and ignore the abort, or if it's still pending on this specific
// background request, then write it to the cache.
const vl = this.#valList[index];
if (vl === p || (ignoreAbort && updateCache && vl === undefined)) {
if (vl === p || (vl === undefined && ignoreAbort && updateCache)) {
if (v === undefined) {
if (bf.__staleWhileFetching !== undefined) {
this.#valList[index] = bf.__staleWhileFetching;
@@ -1197,7 +1241,7 @@ class LRUCache {
else {
if (options.status)
options.status.fetchUpdated = true;
this.set(k, v, fetchOpts.options);
this.#set(k, v, fetchOpts.options, bf);
}
}
return v;
@@ -1219,8 +1263,7 @@ class LRUCache {
if (this.#valList[index] === p) {
// if we allow stale on fetch rejections, then we need to ensure that
// the stale value is not removed from the cache when the fetch fails.
const del = !noDelete ||
!proceed && bf.__staleWhileFetching === undefined;
const del = !noDelete || (!proceed && bf.__staleWhileFetching === undefined);
if (del) {
this.#delete(k, 'fetch');
}
@@ -1244,9 +1287,6 @@ class LRUCache {
};
const pcall = (res, rej) => {
const fmp = this.#fetchMethod?.(k, v, fetchOpts);
if (fmp && fmp instanceof Promise) {
fmp.then(v => res(v === undefined ? undefined : v), rej);
}
// ignored, we go until we finish, regardless.
// defer check until we are actually aborting,
// so fetchMethod can override.
@@ -1259,6 +1299,12 @@ class LRUCache {
}
}
});
if (fmp && fmp instanceof Promise) {
fmp.then(v => res(v === undefined ? undefined : v), rej);
}
else if (fmp !== undefined) {
res(fmp);
}
};
if (options.status)
options.status.fetchDispatched = true;
@@ -1270,10 +1316,14 @@ class LRUCache {
});
if (index === undefined) {
// internal, don't expose status.
this.set(k, bf, { ...fetchOpts.options, status: undefined });
this.#set(k, bf, { ...fetchOpts.options, status: undefined });
index = this.#keyMap.get(k);
}
else {
// do not call #set, because we do not want to adjust its place
// in the lru queue, as it has not yet been "used". Also, we don't
// need to worry about evicting for size, because a background fetch
// over a stale value is treated as the same size as its stale value.
this.#valList[index] = bf;
}
return bf;
@@ -1285,9 +1335,23 @@ class LRUCache {
return (!!b &&
b instanceof Promise &&
b.hasOwnProperty('__staleWhileFetching') &&
b.__abortController instanceof AC);
b.__abortController instanceof AbortController);
}
async fetch(k, fetchOptions = {}) {
fetch(k, fetchOptions = {}) {
const ths = diagnostics_channel_js_1.tracing.hasSubscribers;
const { status = hasSubscribers() ? {} : undefined } = fetchOptions;
fetchOptions.status = status;
if (status && fetchOptions.context) {
status.context = fetchOptions.context;
}
const p = this.#fetch(k, fetchOptions);
if (status && ths) {
status.trace = true;
diagnostics_channel_js_1.tracing.tracePromise(() => p, status).catch(() => { });
}
return p;
}
async #fetch(k, fetchOptions = {}) {
const {
// get options
allowStale = this.allowStale, updateAgeOnGet = this.updateAgeOnGet, noDeleteOnStaleGet = this.noDeleteOnStaleGet,
@@ -1295,10 +1359,17 @@ class LRUCache {
ttl = this.ttl, noDisposeOnSet = this.noDisposeOnSet, size = 0, sizeCalculation = this.sizeCalculation, noUpdateTTL = this.noUpdateTTL,
// fetch exclusive options
noDeleteOnFetchRejection = this.noDeleteOnFetchRejection, allowStaleOnFetchRejection = this.allowStaleOnFetchRejection, ignoreFetchAbort = this.ignoreFetchAbort, allowStaleOnFetchAbort = this.allowStaleOnFetchAbort, context, forceRefresh = false, status, signal, } = fetchOptions;
if (status) {
status.op = 'fetch';
status.key = k;
if (forceRefresh)
status.forceRefresh = true;
status.cache = this;
}
if (!this.#hasFetchMethod) {
if (status)
status.fetch = 'get';
return this.get(k, {
return this.#get(k, {
allowStale,
updateAgeOnGet,
noDeleteOnStaleGet,
@@ -1367,26 +1438,68 @@ class LRUCache {
return staleVal ? p.__staleWhileFetching : (p.__returned = p);
}
}
async forceFetch(k, fetchOptions = {}) {
const v = await this.fetch(k, fetchOptions);
forceFetch(k, fetchOptions = {}) {
const ths = diagnostics_channel_js_1.tracing.hasSubscribers;
const { status = hasSubscribers() ? {} : undefined } = fetchOptions;
fetchOptions.status = status;
if (status && fetchOptions.context) {
status.context = fetchOptions.context;
}
const p = this.#forceFetch(k, fetchOptions);
if (status && ths) {
status.trace = true;
diagnostics_channel_js_1.tracing.tracePromise(() => p, status).catch(() => { });
}
return p;
}
async #forceFetch(k, fetchOptions = {}) {
const v = await this.#fetch(k, fetchOptions);
if (v === undefined)
throw new Error('fetch() returned undefined');
return v;
}
memo(k, memoOptions = {}) {
const { status = diagnostics_channel_js_1.metrics.hasSubscribers ? {} : undefined } = memoOptions;
memoOptions.status = status;
if (status) {
status.op = 'memo';
status.key = k;
if (memoOptions.context) {
status.context = memoOptions.context;
}
status.cache = this;
}
const result = this.#memo(k, memoOptions);
if (status)
status.value = result;
if (diagnostics_channel_js_1.metrics.hasSubscribers)
diagnostics_channel_js_1.metrics.publish(status);
return result;
}
#memo(k, memoOptions = {}) {
const memoMethod = this.#memoMethod;
if (!memoMethod) {
throw new Error('no memoMethod provided to constructor');
}
const { context, forceRefresh, ...options } = memoOptions;
const v = this.get(k, options);
if (!forceRefresh && v !== undefined)
const { context, status, forceRefresh, ...options } = memoOptions;
if (status && forceRefresh)
status.forceRefresh = true;
const v = this.#get(k, options);
const refresh = forceRefresh || v === undefined;
if (status) {
status.memo = refresh ? 'miss' : 'hit';
if (!refresh)
status.value = v;
}
if (!refresh)
return v;
const vv = memoMethod(k, v, {
options,
context,
});
this.set(k, vv, options);
if (status)
status.value = vv;
this.#set(k, vv, options);
return vv;
}
/**
@@ -1396,55 +1509,71 @@ class LRUCache {
* If the key is not found, get() will return `undefined`.
*/
get(k, getOptions = {}) {
const { status = diagnostics_channel_js_1.metrics.hasSubscribers ? {} : undefined } = getOptions;
getOptions.status = status;
if (status) {
status.op = 'get';
status.key = k;
status.cache = this;
}
const result = this.#get(k, getOptions);
if (status) {
if (result !== undefined)
status.value = result;
if (diagnostics_channel_js_1.metrics.hasSubscribers)
diagnostics_channel_js_1.metrics.publish(status);
}
return result;
}
#get(k, getOptions = {}) {
const { allowStale = this.allowStale, updateAgeOnGet = this.updateAgeOnGet, noDeleteOnStaleGet = this.noDeleteOnStaleGet, status, } = getOptions;
const index = this.#keyMap.get(k);
if (index !== undefined) {
const value = this.#valList[index];
const fetching = this.#isBackgroundFetch(value);
if (index === undefined) {
if (status)
this.#statusTTL(status, index);
if (this.#isStale(index)) {
status.get = 'miss';
return undefined;
}
const value = this.#valList[index];
const fetching = this.#isBackgroundFetch(value);
if (status)
this.#statusTTL(status, index);
if (this.#isStale(index)) {
// delete only if not an in-flight background fetch
if (!fetching) {
if (!noDeleteOnStaleGet) {
this.#delete(k, 'expire');
}
if (status)
status.get = 'stale';
// delete only if not an in-flight background fetch
if (!fetching) {
if (!noDeleteOnStaleGet) {
this.#delete(k, 'expire');
}
if (status && allowStale)
if (allowStale) {
if (status)
status.returnedStale = true;
return allowStale ? value : undefined;
}
else {
if (status &&
allowStale &&
value.__staleWhileFetching !== undefined) {
status.returnedStale = true;
}
return allowStale ? value.__staleWhileFetching : undefined;
return value;
}
return undefined;
}
else {
if (status)
status.get = 'stale-fetching';
if (allowStale && value.__staleWhileFetching !== undefined) {
if (status)
status.get = 'hit';
// if we're currently fetching it, we don't actually have it yet
// it's not stale, which means this isn't a staleWhileRefetching.
// If it's not stale, and fetching, AND has a __staleWhileFetching
// value, then that means the user fetched with {forceRefresh:true},
// so it's safe to return that value.
if (fetching) {
return value.__staleWhileFetching;
}
this.#moveToTail(index);
if (updateAgeOnGet) {
this.#updateItemAge(index);
}
return value;
status.returnedStale = true;
return value.__staleWhileFetching;
}
return undefined;
}
else if (status) {
status.get = 'miss';
// not stale
if (status)
status.get = fetching ? 'fetching' : 'hit';
// if we're currently fetching it, we don't actually have it yet
// it's not stale, which means this isn't a staleWhileRefetching.
// If it's not stale, and fetching, AND has a __staleWhileFetching
// value, then that means the user fetched with {forceRefresh:true},
// so it's safe to return that value.
this.#moveToTail(index);
if (updateAgeOnGet) {
this.#updateItemAge(index);
}
return fetching ? value.__staleWhileFetching : value;
}
#connect(p, n) {
this.#prev[n] = p;
@@ -1479,6 +1608,14 @@ class LRUCache {
return this.#delete(k, 'delete');
}
#delete(k, reason) {
if (diagnostics_channel_js_1.metrics.hasSubscribers) {
diagnostics_channel_js_1.metrics.publish({
op: 'delete',
delete: reason,
key: k,
cache: this,
});
}
let deleted = false;
if (this.#size !== 0) {
const index = this.#keyMap.get(k);
@@ -1557,7 +1694,7 @@ class LRUCache {
}
}
this.#keyMap.clear();
this.#valList.fill(undefined);
void this.#valList.fill(undefined);
this.#keyList.fill(undefined);
if (this.#ttls && this.#starts) {
this.#ttls.fill(0);
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@@ -0,0 +1 @@
{"version":3,"file":"diagnostics-channel-node.d.ts","sourceRoot":"","sources":["../../../src/diagnostics-channel-node.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AACvE,YAAY,EAAE,cAAc,EAAE,OAAO,EAAE,CAAA;AACvC,eAAO,MAAM,OAAO,EAAE,OAAO,CAAC,OAAO,CAAgC,CAAA;AACrE,eAAO,MAAM,OAAO,EAAE,cAAc,CAAC,OAAO,CAA+B,CAAA"}
@@ -0,0 +1 @@
{"version":3,"file":"diagnostics-channel-node.js","sourceRoot":"","sources":["../../../src/diagnostics-channel-node.ts"],"names":[],"mappings":";;;AAAA,qDAAqD;AACrD,mEAAmE;AACnE,uEAAkE;AAGrD,QAAA,OAAO,GAAqB,IAAA,kCAAO,EAAC,mBAAmB,CAAC,CAAA;AACxD,QAAA,OAAO,GAA4B,IAAA,yCAAc,EAAC,WAAW,CAAC,CAAA","sourcesContent":["// simple node version that imports from node builtin\n// this is built to both ESM and CommonJS on the 'node' import path\nimport { tracingChannel, channel } from 'node:diagnostics_channel'\nimport type { TracingChannel, Channel } from 'node:diagnostics_channel'\nexport type { TracingChannel, Channel }\nexport const metrics: Channel<unknown> = channel('lru-cache:metrics')\nexport const tracing: TracingChannel<unknown> = tracingChannel('lru-cache')\n"]}
@@ -0,0 +1,5 @@
import type { TracingChannel, Channel } from 'node:diagnostics_channel';
export type { TracingChannel, Channel };
export declare const metrics: Channel<unknown>;
export declare const tracing: TracingChannel<unknown>;
//# sourceMappingURL=diagnostics-channel-node.d.ts.map
@@ -0,0 +1,9 @@
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.tracing = exports.metrics = void 0;
// simple node version that imports from node builtin
// this is built to both ESM and CommonJS on the 'node' import path
const node_diagnostics_channel_1 = require("node:diagnostics_channel");
exports.metrics = (0, node_diagnostics_channel_1.channel)('lru-cache:metrics');
exports.tracing = (0, node_diagnostics_channel_1.tracingChannel)('lru-cache');
//# sourceMappingURL=diagnostics-channel-node.js.map
File diff suppressed because it is too large Load Diff
File diff suppressed because one or more lines are too long
File diff suppressed because it is too large Load Diff
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@@ -0,0 +1,12 @@
/**
* this provides the default Perf object source, either the
* `performance` global, or the `Date` constructor.
*
* it can be passed in via configuration to override it
* for a single LRU object.
*/
export type Perf = {
now: () => number;
};
export declare const defaultPerf: Perf;
//# sourceMappingURL=perf.d.ts.map
@@ -0,0 +1 @@
{"version":3,"file":"perf.d.ts","sourceRoot":"","sources":["../../../src/perf.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,IAAI,GAAG;IAAE,GAAG,EAAE,MAAM,MAAM,CAAA;CAAE,CAAA;AACxC,eAAO,MAAM,WAAW,EAAE,IAQG,CAAA"}
@@ -0,0 +1,10 @@
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.defaultPerf = void 0;
exports.defaultPerf = (typeof performance === 'object' &&
performance &&
typeof performance.now === 'function') ?
/* c8 ignore start - this gets covered, but c8 gets confused */
performance
: /* c8 ignore stop */ Date;
//# sourceMappingURL=perf.js.map
@@ -0,0 +1 @@
{"version":3,"file":"perf.js","sourceRoot":"","sources":["../../../src/perf.ts"],"names":[],"mappings":";;;AAQa,QAAA,WAAW,GACtB,CACE,OAAO,WAAW,KAAK,QAAQ;IAC/B,WAAW;IACX,OAAO,WAAW,CAAC,GAAG,KAAK,UAAU,CACtC,CAAC,CAAC;IACD,+DAA+D;IAC/D,WAAW;IACb,CAAC,CAAC,oBAAoB,CAAC,IAAI,CAAA","sourcesContent":["/**\n * this provides the default Perf object source, either the\n * `performance` global, or the `Date` constructor.\n *\n * it can be passed in via configuration to override it\n * for a single LRU object.\n */\nexport type Perf = { now: () => number }\nexport const defaultPerf: Perf =\n (\n typeof performance === 'object' &&\n performance &&\n typeof performance.now === 'function'\n ) ?\n /* c8 ignore start - this gets covered, but c8 gets confused */\n performance\n : /* c8 ignore stop */ Date\n"]}
@@ -0,0 +1,12 @@
/**
* this provides the default Perf object source, either the
* `performance` global, or the `Date` constructor.
*
* it can be passed in via configuration to override it
* for a single LRU object.
*/
export type Perf = {
now: () => number;
};
export declare const defaultPerf: Perf;
//# sourceMappingURL=perf.d.ts.map
@@ -0,0 +1 @@
{"version":3,"file":"perf.d.ts","sourceRoot":"","sources":["../../src/perf.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,IAAI,GAAG;IAAE,GAAG,EAAE,MAAM,MAAM,CAAA;CAAE,CAAA;AACxC,eAAO,MAAM,WAAW,EAAE,IAQG,CAAA"}
+10
View File
@@ -0,0 +1,10 @@
"use strict";
Object.defineProperty(exports, "__esModule", { value: true });
exports.defaultPerf = void 0;
exports.defaultPerf = (typeof performance === 'object' &&
performance &&
typeof performance.now === 'function') ?
/* c8 ignore start - this gets covered, but c8 gets confused */
performance
: /* c8 ignore stop */ Date;
//# sourceMappingURL=perf.js.map
@@ -0,0 +1 @@
{"version":3,"file":"perf.js","sourceRoot":"","sources":["../../src/perf.ts"],"names":[],"mappings":";;;AAQa,QAAA,WAAW,GACtB,CACE,OAAO,WAAW,KAAK,QAAQ;IAC/B,WAAW;IACX,OAAO,WAAW,CAAC,GAAG,KAAK,UAAU,CACtC,CAAC,CAAC;IACD,+DAA+D;IAC/D,WAAW;IACb,CAAC,CAAC,oBAAoB,CAAC,IAAI,CAAA","sourcesContent":["/**\n * this provides the default Perf object source, either the\n * `performance` global, or the `Date` constructor.\n *\n * it can be passed in via configuration to override it\n * for a single LRU object.\n */\nexport type Perf = { now: () => number }\nexport const defaultPerf: Perf =\n (\n typeof performance === 'object' &&\n performance &&\n typeof performance.now === 'function'\n ) ?\n /* c8 ignore start - this gets covered, but c8 gets confused */\n performance\n : /* c8 ignore stop */ Date\n"]}
@@ -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"}
@@ -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;AACvC,MAAM,CAAC,MAAM,OAAO,GAAG,KAAyB,CAAA;AAChD,MAAM,CAAC,MAAM,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"]}
@@ -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
@@ -0,0 +1,4 @@
const dummy = { hasSubscribers: false };
export const metrics = dummy;
export const tracing = dummy;
//# sourceMappingURL=diagnostics-channel-browser.js.map
File diff suppressed because it is too large Load Diff
File diff suppressed because one or more lines are too long
File diff suppressed because it is too large Load Diff
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@@ -0,0 +1,12 @@
/**
* this provides the default Perf object source, either the
* `performance` global, or the `Date` constructor.
*
* it can be passed in via configuration to override it
* for a single LRU object.
*/
export type Perf = {
now: () => number;
};
export declare const defaultPerf: Perf;
//# sourceMappingURL=perf.d.ts.map
@@ -0,0 +1 @@
{"version":3,"file":"perf.d.ts","sourceRoot":"","sources":["../../../src/perf.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,IAAI,GAAG;IAAE,GAAG,EAAE,MAAM,MAAM,CAAA;CAAE,CAAA;AACxC,eAAO,MAAM,WAAW,EAAE,IAQG,CAAA"}
@@ -0,0 +1,7 @@
export const defaultPerf = (typeof performance === 'object' &&
performance &&
typeof performance.now === 'function') ?
/* c8 ignore start - this gets covered, but c8 gets confused */
performance
: /* c8 ignore stop */ Date;
//# sourceMappingURL=perf.js.map
@@ -0,0 +1 @@
{"version":3,"file":"perf.js","sourceRoot":"","sources":["../../../src/perf.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,WAAW,GACtB,CACE,OAAO,WAAW,KAAK,QAAQ;IAC/B,WAAW;IACX,OAAO,WAAW,CAAC,GAAG,KAAK,UAAU,CACtC,CAAC,CAAC;IACD,+DAA+D;IAC/D,WAAW;IACb,CAAC,CAAC,oBAAoB,CAAC,IAAI,CAAA","sourcesContent":["/**\n * this provides the default Perf object source, either the\n * `performance` global, or the `Date` constructor.\n *\n * it can be passed in via configuration to override it\n * for a single LRU object.\n */\nexport type Perf = { now: () => number }\nexport const defaultPerf: Perf =\n (\n typeof performance === 'object' &&\n performance &&\n typeof performance.now === 'function'\n ) ?\n /* c8 ignore start - this gets covered, but c8 gets confused */\n performance\n : /* c8 ignore stop */ Date\n"]}
@@ -0,0 +1 @@
{"version":3,"file":"diagnostics-channel-esm.d.mts","sourceRoot":"","sources":["../../src/diagnostics-channel-esm.mts"],"names":[],"mappings":"AAIA,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,cAAc,EACpB,MAAM,0BAA0B,CAAA;AACjC,YAAY,EAAE,cAAc,EAAE,OAAO,EAAE,CAAA;AAavC,eAAO,IAAI,OAAO,EAAY,OAAO,CAAC,OAAO,CAAC,CAAA;AAC9C,eAAO,IAAI,OAAO,EAAY,cAAc,CAAC,OAAO,CAAC,CAAA"}
@@ -0,0 +1 @@
{"version":3,"file":"diagnostics-channel-esm.mjs","sourceRoot":"","sources":["../../src/diagnostics-channel-esm.mts"],"names":[],"mappings":"AAUA;;;;;GAKG;AAEH,uEAAuE;AACvE,4EAA4E;AAC5E,oBAAoB;AACpB,MAAM,KAAK,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,CAAA;AACvC,MAAM,CAAC,IAAI,OAAO,GAAG,KAAyB,CAAA;AAC9C,MAAM,CAAC,IAAI,OAAO,GAAG,KAAgC,CAAA;AACrD,MAAM,CAAC,0BAA0B,CAAC;KAC/B,IAAI,CAAC,EAAE,CAAC,EAAE;IACT,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAA;IACzC,OAAO,GAAG,EAAE,CAAC,cAAc,CAAC,WAAW,CAAC,CAAA;AAC1C,CAAC,CAAC;KACD,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA","sourcesContent":["// This is used in ESM environments that do NOT follow the 'node' or 'browser'\n// import conditions. So, `node:diagnostics_channel` MAY be present.\n// Note that this is overridden in 'browser' conditional branch, because the\n// dynamic import can confound bundlers and cause CSP violations in browsers.\nimport {\n type Channel,\n type TracingChannel,\n} from 'node:diagnostics_channel'\nexport type { TracingChannel, Channel }\n\n/**\n * no-op polyfills for non-node environments. tries to load the actual\n * diagnostics_channel module on platforms that support it, but fails\n * gracefully if not found. This means that the first tick of metrics\n * and tracing will be missed, but that probably doesn't matter much.\n */\n\n// conditionally import from diagnostic_channel, fall back to dummyfill\n// all we actually have to mock is the hasSubscribers, since we always check\n/* v8 ignore next */\nconst dummy = { hasSubscribers: false }\nexport let metrics = dummy as Channel<unknown>\nexport let tracing = dummy as TracingChannel<unknown>\nimport('node:diagnostics_channel')\n .then(dc => {\n metrics = dc.channel('lru-cache:metrics')\n tracing = dc.tracingChannel('lru-cache')\n })\n .catch(() => {})\n"]}
@@ -0,0 +1,5 @@
import { type Channel, type TracingChannel } from 'node:diagnostics_channel';
export type { TracingChannel, Channel };
export declare let metrics: Channel<unknown>;
export declare let tracing: TracingChannel<unknown>;
//# sourceMappingURL=diagnostics-channel-esm.d.mts.map
@@ -0,0 +1,19 @@
/**
* no-op polyfills for non-node environments. tries to load the actual
* diagnostics_channel module on platforms that support it, but fails
* gracefully if not found. This means that the first tick of metrics
* and tracing will be missed, but that probably doesn't matter much.
*/
// conditionally import from diagnostic_channel, fall back to dummyfill
// all we actually have to mock is the hasSubscribers, since we always check
/* v8 ignore next */
const dummy = { hasSubscribers: false };
export let metrics = dummy;
export let tracing = dummy;
import('node:diagnostics_channel')
.then(dc => {
metrics = dc.channel('lru-cache:metrics');
tracing = dc.tracingChannel('lru-cache');
})
.catch(() => { });
//# sourceMappingURL=diagnostics-channel-esm.mjs.map
+109 -32
View File
@@ -1,9 +1,8 @@
/**
* @module LRUCache
*/
export type Perf = {
now: () => number;
};
import type { Perf } from './perf.js';
export type { Perf } from './perf.js';
declare const TYPE: unique symbol;
export type PosInt = number & {
[TYPE]: 'Positive Integer';
@@ -119,8 +118,16 @@ export declare namespace LRUCache {
*
* The `status` option should be a plain JavaScript object. The following
* fields will be set on it appropriately, depending on the situation.
*
* These objects are also the context objects passed to listeners on the
* `lru-cache:metrics` diagnostic channel, and the `lru-cache` tracing
* channels, in platforms that support them.
*/
interface Status<V> {
interface Status<K, V, FC = unknown> {
/**
* The operation being performed
*/
op?: 'get' | 'set' | 'memo' | 'fetch' | 'delete' | 'has' | 'peek';
/**
* The status of a set() operation.
*
@@ -129,7 +136,37 @@ export declare namespace LRUCache {
* - replace: the item was in the cache, and replaced
* - miss: the item was not added to the cache for some reason
*/
set?: 'add' | 'update' | 'replace' | 'miss';
set?: 'add' | 'update' | 'replace' | 'miss' | 'deleted';
/**
* The status of a delete() operation.
*/
delete?: LRUCache.DisposeReason;
/**
* The result of a peek() operation
*
* - hit: the item was found and returned
* - stale: the item is in the cache, but past its ttl and not returned
* - miss: item not in the cache
*/
peek?: 'hit' | 'miss' | 'stale';
/**
* The status of a memo() operation.
*
* - 'hit': the item was found in the cache and returned
* - 'miss': the `memoMethod` function was called
*/
memo?: 'hit' | 'miss';
/**
* The `context` option provided to a memo or fetch operation
*
* In practice, of course, this will be the same type as the `FC`
* fetch context param used to instantiate the LRUCache, but the
* convolutions of threading that through would get quite complicated,
* and preclude forcing/forbidding the passing of a `context` param
* where it is/isn't expected, which is more valuable for error
* prevention.
*/
context?: unknown;
/**
* the ttl stored for the item, or undefined if ttls are not used.
*/
@@ -160,8 +197,15 @@ export declare namespace LRUCache {
*/
maxEntrySizeExceeded?: true;
/**
* The old value, specified in the case of `set:'update'` or
* `set:'replace'`
* The key that was set or retrieved
*/
key?: K;
/**
* The value that was set
*/
value?: V;
/**
* The old value, specified in the case of `set:'replace'`
*/
oldValue?: V;
/**
@@ -187,6 +231,10 @@ export declare namespace LRUCache {
* {@link FetchOptions.forceRefresh} was specified.
*/
fetch?: 'get' | 'inflight' | 'miss' | 'hit' | 'stale' | 'refresh';
/**
* `forceRefresh` option was used for either a fetch or memo operation
*/
forceRefresh?: boolean;
/**
* The {@link OptionsBase.fetchMethod} was called
*/
@@ -208,7 +256,7 @@ export declare namespace LRUCache {
fetchAborted?: true;
/**
* The abort signal received was ignored, and the fetch was allowed to
* continue.
* continue in the background.
*/
fetchAbortIgnored?: true;
/**
@@ -224,15 +272,27 @@ export declare namespace LRUCache {
*
* - fetching: The item is currently being fetched. If a previous value
* is present and allowed, that will be returned.
* - stale: The item is in the cache, and is stale.
* - stale: The item is in the cache, and is stale. If it was returned,
* then the `returnedStale` flag will be set.
* - stale-fetching: The value is being fetched in the background, but is
* currently stale. If the stale value was returned, then the
* `returnedStale` flag will be set.
* - hit: the item is in the cache
* - miss: the item is not in the cache
*/
get?: 'stale' | 'hit' | 'miss';
get?: 'stale' | 'hit' | 'miss' | 'fetching' | 'stale-fetching';
/**
* A fetch or get operation returned a stale value.
*/
returnedStale?: true;
/**
* A tracingChannel trace was started for this operation
*/
trace?: boolean;
/**
* A reference to the cache instance associated with this operation
*/
cache?: LRUCache<K & {}, V & {}, FC>;
}
/**
* options which override the options set in the LRUCache constructor
@@ -250,7 +310,7 @@ export declare namespace LRUCache {
* the fetchMethod is called.
*/
interface FetcherFetchOptions<K, V, FC = unknown> extends Pick<OptionsBase<K, V, FC>, 'allowStale' | 'updateAgeOnGet' | 'noDeleteOnStaleGet' | 'sizeCalculation' | 'ttl' | 'noDisposeOnSet' | 'noUpdateTTL' | 'noDeleteOnFetchRejection' | 'allowStaleOnFetchRejection' | 'ignoreFetchAbort' | 'allowStaleOnFetchAbort'> {
status?: Status<V>;
status?: Status<K, V, FC>;
size?: Size;
}
/**
@@ -272,7 +332,7 @@ export declare namespace LRUCache {
*/
context?: FC;
signal?: AbortSignal;
status?: Status<V>;
status?: Status<K, V, FC>;
}
/**
* Options provided to {@link LRUCache#fetch} when the FC type is something
@@ -285,8 +345,8 @@ export declare namespace LRUCache {
* Options provided to {@link LRUCache#fetch} when the FC type is
* `undefined` or `void`
*/
interface FetchOptionsNoContext<K, V> extends FetchOptions<K, V, undefined> {
context?: undefined;
interface FetchOptionsNoContext<K, V, FC extends undefined | void = undefined> extends FetchOptions<K, V, FC> {
context?: FC;
}
interface MemoOptions<K, V, FC = unknown> extends Pick<OptionsBase<K, V, FC>, 'allowStale' | 'updateAgeOnGet' | 'noDeleteOnStaleGet' | 'sizeCalculation' | 'ttl' | 'noDisposeOnSet' | 'noUpdateTTL' | 'noDeleteOnFetchRejection' | 'allowStaleOnFetchRejection' | 'ignoreFetchAbort' | 'allowStaleOnFetchAbort'> {
/**
@@ -303,7 +363,7 @@ export declare namespace LRUCache {
* be required.
*/
context?: FC;
status?: Status<V>;
status?: Status<K, V, FC>;
}
/**
* Options provided to {@link LRUCache#memo} when the FC type is something
@@ -316,8 +376,8 @@ export declare namespace LRUCache {
* Options provided to {@link LRUCache#memo} when the FC type is
* `undefined` or `void`
*/
interface MemoOptionsNoContext<K, V> extends MemoOptions<K, V, undefined> {
context?: undefined;
interface MemoOptionsNoContext<K, V, FC extends undefined | void = undefined> extends MemoOptions<K, V, FC> {
context?: FC;
}
/**
* Options provided to the
@@ -345,7 +405,7 @@ export declare namespace LRUCache {
* the memoMethod is called.
*/
interface MemoizerMemoOptions<K, V, FC = unknown> extends Pick<OptionsBase<K, V, FC>, 'allowStale' | 'updateAgeOnGet' | 'noDeleteOnStaleGet' | 'sizeCalculation' | 'ttl' | 'noDisposeOnSet' | 'noUpdateTTL'> {
status?: Status<V>;
status?: Status<K, V, FC>;
size?: Size;
start?: Milliseconds;
}
@@ -353,18 +413,19 @@ export declare namespace LRUCache {
* Options that may be passed to the {@link LRUCache#has} method.
*/
interface HasOptions<K, V, FC> extends Pick<OptionsBase<K, V, FC>, 'updateAgeOnHas'> {
status?: Status<V>;
status?: Status<K, V, FC>;
}
/**
* Options that may be passed to the {@link LRUCache#get} method.
*/
interface GetOptions<K, V, FC> extends Pick<OptionsBase<K, V, FC>, 'allowStale' | 'updateAgeOnGet' | 'noDeleteOnStaleGet'> {
status?: Status<V>;
status?: Status<K, V, FC>;
}
/**
* Options that may be passed to the {@link LRUCache#peek} method.
*/
interface PeekOptions<K, V, FC> extends Pick<OptionsBase<K, V, FC>, 'allowStale'> {
status?: Status<K, V, FC>;
}
/**
* Options that may be passed to the {@link LRUCache#set} method.
@@ -385,7 +446,7 @@ export declare namespace LRUCache {
* method is in use.
*/
start?: Milliseconds;
status?: Status<V>;
status?: Status<K, V, FC>;
}
/**
* The type signature for the {@link OptionsBase.fetchMethod} option.
@@ -638,6 +699,20 @@ export declare namespace LRUCache {
* though for most cases, only minimally.
*/
maxSize?: Size;
/**
* The effective size for background fetch promises.
*
* This has no effect unless `maxSize` and `sizeCalculation` are used,
* and a {@link LRUCache.OptionsBase.fetchMethod} is provided to
* support {@link LRUCache#fetch}.
*
* If a stale value is present in the cache, then the effective size of
* the background fetch is the size of the stale item it will eventually
* replace. If not, then this value is used as its effective size.
*
* @default 1
*/
backgroundFetchSize?: number;
/**
* The maximum allowed size for any single item in the cache.
*
@@ -940,6 +1015,8 @@ export declare class LRUCache<K extends {}, V extends {}, FC = unknown> {
* {@link LRUCache.OptionsBase.ignoreFetchAbort}
*/
ignoreFetchAbort: boolean;
/** {@link LRUCache.OptionsBase.backgroundFetchSize} */
backgroundFetchSize: number;
/**
* Do not call this method unless you need to inspect the
* inner workings of the cache. If anything returned by this
@@ -962,8 +1039,8 @@ export declare class LRUCache<K extends {}, V extends {}, FC = unknown> {
readonly head: Index;
readonly tail: Index;
free: StackLike;
isBackgroundFetch: (p: any) => p is BackgroundFetch<V>;
backgroundFetch: (k: K, index: number | undefined, options: LRUCache.FetchOptions<K, V, FC>, context: any) => BackgroundFetch<V>;
isBackgroundFetch: (p: unknown) => p is BackgroundFetch<V>;
backgroundFetch: (k: K, index: number | undefined, options: LRUCache.FetchOptions<K, V, FC>, context: unknown) => BackgroundFetch<V>;
moveToTail: (index: number) => void;
indexes: (options?: {
allowStale: boolean;
@@ -1075,12 +1152,12 @@ export declare class LRUCache<K extends {}, V extends {}, FC = unknown> {
*
* Does not update age or recenty of use, or iterate over stale values.
*/
forEach(fn: (v: V, k: K, self: LRUCache<K, V, FC>) => any, thisp?: any): void;
forEach(fn: (v: V, k: K, self: LRUCache<K, V, FC>) => unknown, thisp?: unknown): void;
/**
* The same as {@link LRUCache.forEach} but items are iterated over in
* reverse order. (ie, less recently used items are iterated over first.)
*/
rforEach(fn: (v: V, k: K, self: LRUCache<K, V, FC>) => any, thisp?: any): void;
rforEach(fn: (v: V, k: K, self: LRUCache<K, V, FC>) => unknown, thisp?: unknown): void;
/**
* Delete any stale entries. Returns true if anything was removed,
* false otherwise.
@@ -1153,7 +1230,7 @@ export declare class LRUCache<K extends {}, V extends {}, FC = unknown> {
* If the value is `undefined`, then this is an alias for
* `cache.delete(key)`. `undefined` is never stored in the cache.
*/
set(k: K, v: V | BackgroundFetch<V> | undefined, setOptions?: LRUCache.SetOptions<K, V, FC>): this;
set(k: K, v: V | undefined, setOptions?: LRUCache.SetOptions<K, V, FC>): this;
/**
* Evict the least recently used item, returning its value or
* `undefined` if cache is empty.
@@ -1269,8 +1346,8 @@ export declare class LRUCache<K extends {}, V extends {}, FC = unknown> {
* the same time, because they're both waiting on the same
* underlying fetchMethod response.
*/
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<undefined | 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<undefined | V>;
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<undefined | 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<undefined | V>;
/**
* In some cases, `cache.fetch()` may resolve to `undefined`, either because
* a {@link LRUCache.OptionsBase#fetchMethod} was not provided (turning
@@ -1284,8 +1361,8 @@ export declare class LRUCache<K extends {}, V extends {}, FC = unknown> {
* cumbersome, but testing for `undefined` can also be annoying, this method
* can be used, which will reject if `this.fetch()` resolves to undefined.
*/
forceFetch(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<V>;
forceFetch(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<V>;
forceFetch(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<V>;
forceFetch(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<V>;
/**
* If the key is found in the cache, then this is equivalent to
* {@link LRUCache#get}. If not, in the cache, then calculate the value using
@@ -1300,8 +1377,8 @@ export declare class LRUCache<K extends {}, V extends {}, FC = unknown> {
* relevant in the course of fetching the data. It is only relevant for the
* course of a single `memo()` operation, and discarded afterwards.
*/
memo(k: K, memoOptions: unknown extends FC ? LRUCache.MemoOptions<K, V, FC> : FC extends undefined | void ? LRUCache.MemoOptionsNoContext<K, V> : LRUCache.MemoOptionsWithContext<K, V, FC>): V;
memo(k: unknown extends FC ? K : FC extends undefined | void ? K : never, memoOptions?: unknown extends FC ? LRUCache.MemoOptions<K, V, FC> : FC extends undefined | void ? LRUCache.MemoOptionsNoContext<K, V> : never): V;
memo(k: K, memoOptions: unknown extends FC ? LRUCache.MemoOptions<K, V, FC> : FC extends undefined | void ? LRUCache.MemoOptionsNoContext<K, V, FC> : LRUCache.MemoOptionsWithContext<K, V, FC>): V;
memo(k: unknown extends FC ? K : FC extends undefined | void ? K : never, memoOptions?: unknown extends FC ? LRUCache.MemoOptions<K, V, FC> : FC extends undefined | void ? LRUCache.MemoOptionsNoContext<K, V, FC> : never): V;
/**
* Return a value from the cache. Will update the recency of the cache
* entry found.
File diff suppressed because one or more lines are too long
+333 -196
View File
@@ -1,75 +1,27 @@
/**
* @module LRUCache
*/
const defaultPerf = (typeof performance === 'object' &&
performance &&
typeof performance.now === 'function') ?
performance
: Date;
import { metrics, tracing } from './diagnostics-channel.js';
import { defaultPerf } from './perf.js';
const hasSubscribers = () => metrics.hasSubscribers || tracing.hasSubscribers;
const warned = new Set();
/* c8 ignore start */
const PROCESS = (typeof process === 'object' && !!process ?
process
: {});
/* c8 ignore start */
const emitWarning = (msg, type, code, fn) => {
typeof PROCESS.emitWarning === 'function' ?
PROCESS.emitWarning(msg, type, code, fn)
: console.error(`[${code}] ${type}: ${msg}`);
};
let AC = globalThis.AbortController;
let AS = globalThis.AbortSignal;
/* c8 ignore start */
if (typeof AC === 'undefined') {
//@ts-ignore
AS = class AbortSignal {
onabort;
_onabort = [];
reason;
aborted = false;
addEventListener(_, fn) {
this._onabort.push(fn);
}
};
//@ts-ignore
AC = class AbortController {
constructor() {
warnACPolyfill();
}
signal = new AS();
abort(reason) {
if (this.signal.aborted)
return;
//@ts-ignore
this.signal.reason = reason;
//@ts-ignore
this.signal.aborted = true;
//@ts-ignore
for (const fn of this.signal._onabort) {
fn(reason);
}
this.signal.onabort?.(reason);
}
};
let printACPolyfillWarning = PROCESS.env?.LRU_CACHE_IGNORE_AC_WARNING !== '1';
const warnACPolyfill = () => {
if (!printACPolyfillWarning)
return;
printACPolyfillWarning = false;
emitWarning('AbortController is not defined. If using lru-cache in ' +
'node 14, load an AbortController polyfill from the ' +
'`node-abort-controller` package. A minimal polyfill is ' +
'provided for use by LRUCache.fetch(), but it should not be ' +
'relied upon in other contexts (eg, passing it to other APIs that ' +
'use AbortController/AbortSignal might have undesirable effects). ' +
'You may disable this with LRU_CACHE_IGNORE_AC_WARNING=1 in the env.', 'NO_ABORT_CONTROLLER', 'ENOTSUP', warnACPolyfill);
};
}
/* c8 ignore stop */
const emitWarning = (msg, type, code, fn) => {
if (typeof PROCESS.emitWarning === 'function') {
PROCESS.emitWarning(msg, type, code, fn);
}
else {
//oxlint-disable-next-line no-console
console.error(`[${code}] ${type}: ${msg}`);
}
};
const shouldWarn = (code) => !warned.has(code);
const TYPE = Symbol('type');
const isPosInt = (n) => n && n === Math.floor(n) && n > 0 && isFinite(n);
/* c8 ignore start */
const isPosInt = (n) => !!n && n === Math.floor(n) && n > 0 && isFinite(n);
// This is a little bit ridiculous, tbh.
// The maximum array length is 2^32-1 or thereabouts on most JS impls.
// And well before that point, you're caching the entire world, I mean,
@@ -78,6 +30,7 @@ const isPosInt = (n) => n && n === Math.floor(n) && n > 0 && isFinite(n);
// zeroes at init time is brutal when you get that big.
// But why not be complete?
// Maybe in the future, these limits will have expanded.
/* c8 ignore start */
const getUintArray = (max) => !isPosInt(max) ? null
: max <= Math.pow(2, 8) ? Uint8Array
: max <= Math.pow(2, 16) ? Uint16Array
@@ -92,7 +45,9 @@ class ZeroArray extends Array {
}
}
class Stack {
/* c8 ignore start - not sure why this is showing up uncovered?? */
heap;
/* c8 ignore stop */
length;
// private constructor
static #constructing = false;
@@ -212,6 +167,8 @@ export class LRUCache {
* {@link LRUCache.OptionsBase.ignoreFetchAbort}
*/
ignoreFetchAbort;
/** {@link LRUCache.OptionsBase.backgroundFetchSize} */
backgroundFetchSize;
// computed properties
#size;
#calculatedSize;
@@ -322,7 +279,8 @@ export class LRUCache {
return this.#disposeAfter;
}
constructor(options) {
const { max = 0, ttl, ttlResolution = 1, ttlAutopurge, updateAgeOnGet, updateAgeOnHas, allowStale, dispose, onInsert, disposeAfter, noDisposeOnSet, noUpdateTTL, maxSize = 0, maxEntrySize = 0, sizeCalculation, fetchMethod, memoMethod, noDeleteOnFetchRejection, noDeleteOnStaleGet, allowStaleOnFetchRejection, allowStaleOnFetchAbort, ignoreFetchAbort, perf, } = options;
const { max = 0, ttl, ttlResolution = 1, ttlAutopurge, updateAgeOnGet, updateAgeOnHas, allowStale, dispose, onInsert, disposeAfter, noDisposeOnSet, noUpdateTTL, maxSize = 0, maxEntrySize = 0, sizeCalculation, fetchMethod, memoMethod, noDeleteOnFetchRejection, noDeleteOnStaleGet, allowStaleOnFetchRejection, allowStaleOnFetchAbort, ignoreFetchAbort, backgroundFetchSize = 1, perf, } = options;
this.backgroundFetchSize = backgroundFetchSize;
if (perf !== undefined) {
if (typeof perf?.now !== 'function') {
throw new TypeError('perf option must have a now() method if specified');
@@ -358,8 +316,8 @@ export class LRUCache {
this.#fetchMethod = fetchMethod;
this.#hasFetchMethod = !!fetchMethod;
this.#keyMap = new Map();
this.#keyList = new Array(max).fill(undefined);
this.#valList = new Array(max).fill(undefined);
this.#keyList = Array.from({ length: max }).fill(undefined);
this.#valList = Array.from({ length: max }).fill(undefined);
this.#next = new UintArray(max);
this.#prev = new UintArray(max);
this.#head = 0;
@@ -443,44 +401,55 @@ export class LRUCache {
this.#ttls = ttls;
this.#starts = starts;
const purgeTimers = this.ttlAutopurge ?
new Array(this.#max)
Array.from({
length: this.#max,
})
: undefined;
this.#autopurgeTimers = purgeTimers;
this.#setItemTTL = (index, ttl, start = this.#perf.now()) => {
starts[index] = ttl !== 0 ? start : 0;
ttls[index] = ttl;
// clear out the purge timer if we're setting TTL to 0, and
// previously had a ttl purge timer running, so it doesn't
// fire unnecessarily.
if (purgeTimers?.[index]) {
clearTimeout(purgeTimers[index]);
purgeTimers[index] = undefined;
}
if (ttl !== 0 && purgeTimers) {
const t = setTimeout(() => {
if (this.#isStale(index)) {
this.#delete(this.#keyList[index], 'expire');
}
}, ttl + 1);
// unref() not supported on all platforms
/* c8 ignore start */
if (t.unref) {
t.unref();
}
/* c8 ignore stop */
purgeTimers[index] = t;
}
setPurgetTimer(index, ttl);
};
this.#updateItemAge = index => {
starts[index] = ttls[index] !== 0 ? this.#perf.now() : 0;
setPurgetTimer(index, ttls[index]);
};
// clear out the purge timer if we're setting TTL to 0, and
// previously had a ttl purge timer running, so it doesn't
// fire unnecessarily. Don't need to do this if we're not doing
// autopurge.
const setPurgetTimer = !this.ttlAutopurge ?
() => { }
: (index, ttl) => {
if (purgeTimers?.[index]) {
clearTimeout(purgeTimers[index]);
purgeTimers[index] = undefined;
}
if (ttl && ttl !== 0 && purgeTimers) {
const t = setTimeout(() => {
if (this.#isStale(index)) {
this.#delete(this.#keyList[index], 'expire');
}
}, ttl + 1);
// unref() not supported on all platforms
/* c8 ignore start */
if (t.unref) {
t.unref();
}
/* c8 ignore stop */
purgeTimers[index] = t;
}
};
this.#statusTTL = (status, index) => {
if (ttls[index]) {
const ttl = ttls[index];
const start = starts[index];
/* c8 ignore next */
if (!ttl || !start)
/* c8 ignore start */
if (!ttl || !start) {
return;
}
/* c8 ignore stop */
status.ttl = ttl;
status.start = start;
status.now = cachedNow || getNow();
@@ -539,12 +508,15 @@ export class LRUCache {
sizes[index] = 0;
};
this.#requireSize = (k, v, size, sizeCalculation) => {
// provisionally accept background fetches.
// actual value size will be checked when they return.
if (this.#isBackgroundFetch(v)) {
return 0;
}
if (!isPosInt(size)) {
// provisionally accept background fetches.
// actual value size will be checked when they return.
if (this.#isBackgroundFetch(v)) {
// NB: this cannot occur if v.__staleWhileFetching is set,
// because in that case, it would take on the size of the
// existing entry that it temporarily replaces.
return this.backgroundFetchSize;
}
if (sizeCalculation) {
if (typeof sizeCalculation !== 'function') {
throw new TypeError('sizeCalculation must be a function');
@@ -587,10 +559,7 @@ export class LRUCache {
};
*#indexes({ allowStale = this.allowStale } = {}) {
if (this.#size) {
for (let i = this.#tail; true;) {
if (!this.#isValidIndex(i)) {
break;
}
for (let i = this.#tail; this.#isValidIndex(i);) {
if (allowStale || !this.#isStale(i)) {
yield i;
}
@@ -605,10 +574,7 @@ export class LRUCache {
}
*#rindexes({ allowStale = this.allowStale } = {}) {
if (this.#size) {
for (let i = this.#head; true;) {
if (!this.#isValidIndex(i)) {
break;
}
for (let i = this.#head; this.#isValidIndex(i);) {
if (allowStale || !this.#isStale(i)) {
yield i;
}
@@ -729,7 +695,7 @@ export class LRUCache {
if (value === undefined)
continue;
if (fn(value, this.#keyList[i], this)) {
return this.get(this.#keyList[i], getOptions);
return this.#get(this.#keyList[i], getOptions);
}
}
}
@@ -802,7 +768,7 @@ export class LRUCache {
const value = this.#isBackgroundFetch(v) ? v.__staleWhileFetching : v;
if (value === undefined)
return undefined;
/* c8 ignore end */
/* c8 ignore stop */
const entry = { value };
if (this.#ttls && this.#starts) {
const ttl = this.#ttls[i];
@@ -876,7 +842,7 @@ export class LRUCache {
const age = Date.now() - entry.start;
entry.start = this.#perf.now() - age;
}
this.set(key, entry.value, entry);
this.#set(key, entry.value, entry);
}
}
/**
@@ -910,22 +876,43 @@ export class LRUCache {
* `cache.delete(key)`. `undefined` is never stored in the cache.
*/
set(k, v, setOptions = {}) {
const { status = metrics.hasSubscribers ? {} : undefined } = setOptions;
setOptions.status = status;
if (status) {
status.op = 'set';
status.key = k;
if (v !== undefined)
status.value = v;
status.cache = this;
}
const result = this.#set(k, v, setOptions);
if (status && metrics.hasSubscribers) {
metrics.publish(status);
}
return result;
}
#set(k, v, setOptions, bf) {
const { ttl = this.ttl, start, noDisposeOnSet = this.noDisposeOnSet, sizeCalculation = this.sizeCalculation, status, } = setOptions;
const isBF = this.#isBackgroundFetch(v);
if (v === undefined) {
if (status)
status.set = 'deleted';
this.delete(k);
return this;
}
const { ttl = this.ttl, start, noDisposeOnSet = this.noDisposeOnSet, sizeCalculation = this.sizeCalculation, status, } = setOptions;
let { noUpdateTTL = this.noUpdateTTL } = setOptions;
const size = this.#requireSize(k, v, setOptions.size || 0, sizeCalculation);
if (status && !isBF)
status.value = v;
const size = this.#requireSize(k, v, setOptions.size || 0, sizeCalculation, status);
// if the item doesn't fit, don't do anything
// NB: maxEntrySize set to maxSize by default
if (this.maxEntrySize && size > this.maxEntrySize) {
// have to delete, in case something is there already.
this.#delete(k, 'set');
if (status) {
status.set = 'miss';
status.maxEntrySizeExceeded = true;
}
// have to delete, in case something is there already.
this.#delete(k, 'set');
return this;
}
let index = this.#size === 0 ? undefined : this.#keyMap.get(k);
@@ -946,52 +933,68 @@ export class LRUCache {
if (status)
status.set = 'add';
noUpdateTTL = false;
if (this.#hasOnInsert) {
if (this.#hasOnInsert && !isBF) {
this.#onInsert?.(v, k, 'add');
}
}
else {
// update
// might be updating a background fetch!
this.#moveToTail(index);
const oldVal = this.#valList[index];
if (v !== oldVal) {
if (this.#hasFetchMethod && this.#isBackgroundFetch(oldVal)) {
oldVal.__abortController.abort(new Error('replaced'));
const { __staleWhileFetching: s } = oldVal;
if (s !== undefined && !noDisposeOnSet) {
if (!noDisposeOnSet) {
if (this.#isBackgroundFetch(oldVal)) {
if (oldVal !== bf) {
// setting over a background fetch, not merely resolving it.
oldVal.__abortController.abort(new Error('replaced'));
}
const { __staleWhileFetching: s } = oldVal;
if (s !== undefined && s !== v) {
if (this.#hasDispose) {
this.#dispose?.(s, k, 'set');
}
if (this.#hasDisposeAfter) {
this.#disposed?.push([s, k, 'set']);
}
}
}
else {
if (this.#hasDispose) {
this.#dispose?.(s, k, 'set');
this.#dispose?.(oldVal, k, 'set');
}
if (this.#hasDisposeAfter) {
this.#disposed?.push([s, k, 'set']);
this.#disposed?.push([oldVal, k, 'set']);
}
}
}
else if (!noDisposeOnSet) {
if (this.#hasDispose) {
this.#dispose?.(oldVal, k, 'set');
}
if (this.#hasDisposeAfter) {
this.#disposed?.push([oldVal, k, 'set']);
}
}
this.#removeItemSize(index);
this.#addItemSize(index, size, status);
this.#valList[index] = v;
if (status) {
status.set = 'replace';
if (!isBF) {
const oldValue = oldVal && this.#isBackgroundFetch(oldVal) ?
oldVal.__staleWhileFetching
: oldVal;
if (oldValue !== undefined)
status.oldValue = oldValue;
const setType = oldValue === undefined ? 'add'
: v !== oldValue ? 'replace'
: 'update';
if (status) {
status.set = setType;
if (oldValue !== undefined)
status.oldValue = oldValue;
}
if (this.#hasOnInsert) {
this.onInsert?.(v, k, setType);
}
}
}
else if (status) {
status.set = 'update';
}
if (this.#hasOnInsert) {
this.onInsert?.(v, k, v === oldVal ? 'update' : 'replace');
else if (!isBF) {
if (status) {
status.set = 'update';
}
if (this.#hasOnInsert) {
this.onInsert?.(v, k, 'update');
}
}
}
if (ttl !== 0 && !this.#ttls) {
@@ -1046,15 +1049,18 @@ export class LRUCache {
const head = this.#head;
const k = this.#keyList[head];
const v = this.#valList[head];
if (this.#hasFetchMethod && this.#isBackgroundFetch(v)) {
const isBF = this.#isBackgroundFetch(v);
if (isBF) {
v.__abortController.abort(new Error('evicted'));
}
else if (this.#hasDispose || this.#hasDisposeAfter) {
const oldValue = isBF ? v.__staleWhileFetching : v;
if ((this.#hasDispose || this.#hasDisposeAfter) &&
oldValue !== undefined) {
if (this.#hasDispose) {
this.#dispose?.(v, k, 'evict');
this.#dispose?.(oldValue, k, 'evict');
}
if (this.#hasDisposeAfter) {
this.#disposed?.push([v, k, 'evict']);
this.#disposed?.push([oldValue, k, 'evict']);
}
}
this.#removeItemSize(head);
@@ -1096,6 +1102,19 @@ export class LRUCache {
* {@link LRUCache.OptionsBase.updateAgeOnHas} is set.
*/
has(k, hasOptions = {}) {
const { status = metrics.hasSubscribers ? {} : undefined } = hasOptions;
hasOptions.status = status;
if (status) {
status.op = 'has';
status.key = k;
status.cache = this;
}
const result = this.#has(k, hasOptions);
if (metrics.hasSubscribers)
metrics.publish(status);
return result;
}
#has(k, hasOptions = {}) {
const { updateAgeOnHas = this.updateAgeOnHas, status } = hasOptions;
const index = this.#keyMap.get(k);
if (index !== undefined) {
@@ -1132,21 +1151,46 @@ export class LRUCache {
* {@link LRUCache.OptionsBase.allowStale} is set.
*/
peek(k, peekOptions = {}) {
const { allowStale = this.allowStale } = peekOptions;
const { status = hasSubscribers() ? {} : undefined } = peekOptions;
if (status) {
status.op = 'peek';
status.key = k;
status.cache = this;
}
peekOptions.status = status;
const result = this.#peek(k, peekOptions);
if (metrics.hasSubscribers) {
metrics.publish(status);
}
return result;
}
#peek(k, peekOptions) {
const { status, allowStale = this.allowStale } = peekOptions;
const index = this.#keyMap.get(k);
if (index === undefined || (!allowStale && this.#isStale(index))) {
return;
if (status)
status.peek = index === undefined ? 'miss' : 'stale';
return undefined;
}
const v = this.#valList[index];
// either stale and allowed, or forcing a refresh of non-stale value
return this.#isBackgroundFetch(v) ? v.__staleWhileFetching : v;
const val = this.#isBackgroundFetch(v) ? v.__staleWhileFetching : v;
if (status) {
if (val !== undefined) {
status.peek = 'hit';
status.value = val;
}
else {
status.peek = 'miss';
}
}
return val;
}
#backgroundFetch(k, index, options, context) {
const v = index === undefined ? undefined : this.#valList[index];
if (this.#isBackgroundFetch(v)) {
return v;
}
const ac = new AC();
const ac = new AbortController();
const { signal } = options;
// when/if our AC signals, then stop listening to theirs.
signal?.addEventListener('abort', () => ac.abort(signal.reason), {
@@ -1182,7 +1226,7 @@ export class LRUCache {
// cache and ignore the abort, or if it's still pending on this specific
// background request, then write it to the cache.
const vl = this.#valList[index];
if (vl === p || (ignoreAbort && updateCache && vl === undefined)) {
if (vl === p || (vl === undefined && ignoreAbort && updateCache)) {
if (v === undefined) {
if (bf.__staleWhileFetching !== undefined) {
this.#valList[index] = bf.__staleWhileFetching;
@@ -1194,7 +1238,7 @@ export class LRUCache {
else {
if (options.status)
options.status.fetchUpdated = true;
this.set(k, v, fetchOpts.options);
this.#set(k, v, fetchOpts.options, bf);
}
}
return v;
@@ -1216,8 +1260,7 @@ export class LRUCache {
if (this.#valList[index] === p) {
// if we allow stale on fetch rejections, then we need to ensure that
// the stale value is not removed from the cache when the fetch fails.
const del = !noDelete ||
!proceed && bf.__staleWhileFetching === undefined;
const del = !noDelete || (!proceed && bf.__staleWhileFetching === undefined);
if (del) {
this.#delete(k, 'fetch');
}
@@ -1241,9 +1284,6 @@ export class LRUCache {
};
const pcall = (res, rej) => {
const fmp = this.#fetchMethod?.(k, v, fetchOpts);
if (fmp && fmp instanceof Promise) {
fmp.then(v => res(v === undefined ? undefined : v), rej);
}
// ignored, we go until we finish, regardless.
// defer check until we are actually aborting,
// so fetchMethod can override.
@@ -1256,6 +1296,12 @@ export class LRUCache {
}
}
});
if (fmp && fmp instanceof Promise) {
fmp.then(v => res(v === undefined ? undefined : v), rej);
}
else if (fmp !== undefined) {
res(fmp);
}
};
if (options.status)
options.status.fetchDispatched = true;
@@ -1267,10 +1313,14 @@ export class LRUCache {
});
if (index === undefined) {
// internal, don't expose status.
this.set(k, bf, { ...fetchOpts.options, status: undefined });
this.#set(k, bf, { ...fetchOpts.options, status: undefined });
index = this.#keyMap.get(k);
}
else {
// do not call #set, because we do not want to adjust its place
// in the lru queue, as it has not yet been "used". Also, we don't
// need to worry about evicting for size, because a background fetch
// over a stale value is treated as the same size as its stale value.
this.#valList[index] = bf;
}
return bf;
@@ -1282,9 +1332,23 @@ export class LRUCache {
return (!!b &&
b instanceof Promise &&
b.hasOwnProperty('__staleWhileFetching') &&
b.__abortController instanceof AC);
b.__abortController instanceof AbortController);
}
async fetch(k, fetchOptions = {}) {
fetch(k, fetchOptions = {}) {
const ths = tracing.hasSubscribers;
const { status = hasSubscribers() ? {} : undefined } = fetchOptions;
fetchOptions.status = status;
if (status && fetchOptions.context) {
status.context = fetchOptions.context;
}
const p = this.#fetch(k, fetchOptions);
if (status && ths) {
status.trace = true;
tracing.tracePromise(() => p, status).catch(() => { });
}
return p;
}
async #fetch(k, fetchOptions = {}) {
const {
// get options
allowStale = this.allowStale, updateAgeOnGet = this.updateAgeOnGet, noDeleteOnStaleGet = this.noDeleteOnStaleGet,
@@ -1292,10 +1356,17 @@ export class LRUCache {
ttl = this.ttl, noDisposeOnSet = this.noDisposeOnSet, size = 0, sizeCalculation = this.sizeCalculation, noUpdateTTL = this.noUpdateTTL,
// fetch exclusive options
noDeleteOnFetchRejection = this.noDeleteOnFetchRejection, allowStaleOnFetchRejection = this.allowStaleOnFetchRejection, ignoreFetchAbort = this.ignoreFetchAbort, allowStaleOnFetchAbort = this.allowStaleOnFetchAbort, context, forceRefresh = false, status, signal, } = fetchOptions;
if (status) {
status.op = 'fetch';
status.key = k;
if (forceRefresh)
status.forceRefresh = true;
status.cache = this;
}
if (!this.#hasFetchMethod) {
if (status)
status.fetch = 'get';
return this.get(k, {
return this.#get(k, {
allowStale,
updateAgeOnGet,
noDeleteOnStaleGet,
@@ -1364,26 +1435,68 @@ export class LRUCache {
return staleVal ? p.__staleWhileFetching : (p.__returned = p);
}
}
async forceFetch(k, fetchOptions = {}) {
const v = await this.fetch(k, fetchOptions);
forceFetch(k, fetchOptions = {}) {
const ths = tracing.hasSubscribers;
const { status = hasSubscribers() ? {} : undefined } = fetchOptions;
fetchOptions.status = status;
if (status && fetchOptions.context) {
status.context = fetchOptions.context;
}
const p = this.#forceFetch(k, fetchOptions);
if (status && ths) {
status.trace = true;
tracing.tracePromise(() => p, status).catch(() => { });
}
return p;
}
async #forceFetch(k, fetchOptions = {}) {
const v = await this.#fetch(k, fetchOptions);
if (v === undefined)
throw new Error('fetch() returned undefined');
return v;
}
memo(k, memoOptions = {}) {
const { status = metrics.hasSubscribers ? {} : undefined } = memoOptions;
memoOptions.status = status;
if (status) {
status.op = 'memo';
status.key = k;
if (memoOptions.context) {
status.context = memoOptions.context;
}
status.cache = this;
}
const result = this.#memo(k, memoOptions);
if (status)
status.value = result;
if (metrics.hasSubscribers)
metrics.publish(status);
return result;
}
#memo(k, memoOptions = {}) {
const memoMethod = this.#memoMethod;
if (!memoMethod) {
throw new Error('no memoMethod provided to constructor');
}
const { context, forceRefresh, ...options } = memoOptions;
const v = this.get(k, options);
if (!forceRefresh && v !== undefined)
const { context, status, forceRefresh, ...options } = memoOptions;
if (status && forceRefresh)
status.forceRefresh = true;
const v = this.#get(k, options);
const refresh = forceRefresh || v === undefined;
if (status) {
status.memo = refresh ? 'miss' : 'hit';
if (!refresh)
status.value = v;
}
if (!refresh)
return v;
const vv = memoMethod(k, v, {
options,
context,
});
this.set(k, vv, options);
if (status)
status.value = vv;
this.#set(k, vv, options);
return vv;
}
/**
@@ -1393,55 +1506,71 @@ export class LRUCache {
* If the key is not found, get() will return `undefined`.
*/
get(k, getOptions = {}) {
const { status = metrics.hasSubscribers ? {} : undefined } = getOptions;
getOptions.status = status;
if (status) {
status.op = 'get';
status.key = k;
status.cache = this;
}
const result = this.#get(k, getOptions);
if (status) {
if (result !== undefined)
status.value = result;
if (metrics.hasSubscribers)
metrics.publish(status);
}
return result;
}
#get(k, getOptions = {}) {
const { allowStale = this.allowStale, updateAgeOnGet = this.updateAgeOnGet, noDeleteOnStaleGet = this.noDeleteOnStaleGet, status, } = getOptions;
const index = this.#keyMap.get(k);
if (index !== undefined) {
const value = this.#valList[index];
const fetching = this.#isBackgroundFetch(value);
if (index === undefined) {
if (status)
this.#statusTTL(status, index);
if (this.#isStale(index)) {
status.get = 'miss';
return undefined;
}
const value = this.#valList[index];
const fetching = this.#isBackgroundFetch(value);
if (status)
this.#statusTTL(status, index);
if (this.#isStale(index)) {
// delete only if not an in-flight background fetch
if (!fetching) {
if (!noDeleteOnStaleGet) {
this.#delete(k, 'expire');
}
if (status)
status.get = 'stale';
// delete only if not an in-flight background fetch
if (!fetching) {
if (!noDeleteOnStaleGet) {
this.#delete(k, 'expire');
}
if (status && allowStale)
if (allowStale) {
if (status)
status.returnedStale = true;
return allowStale ? value : undefined;
}
else {
if (status &&
allowStale &&
value.__staleWhileFetching !== undefined) {
status.returnedStale = true;
}
return allowStale ? value.__staleWhileFetching : undefined;
return value;
}
return undefined;
}
else {
if (status)
status.get = 'stale-fetching';
if (allowStale && value.__staleWhileFetching !== undefined) {
if (status)
status.get = 'hit';
// if we're currently fetching it, we don't actually have it yet
// it's not stale, which means this isn't a staleWhileRefetching.
// If it's not stale, and fetching, AND has a __staleWhileFetching
// value, then that means the user fetched with {forceRefresh:true},
// so it's safe to return that value.
if (fetching) {
return value.__staleWhileFetching;
}
this.#moveToTail(index);
if (updateAgeOnGet) {
this.#updateItemAge(index);
}
return value;
status.returnedStale = true;
return value.__staleWhileFetching;
}
return undefined;
}
else if (status) {
status.get = 'miss';
// not stale
if (status)
status.get = fetching ? 'fetching' : 'hit';
// if we're currently fetching it, we don't actually have it yet
// it's not stale, which means this isn't a staleWhileRefetching.
// If it's not stale, and fetching, AND has a __staleWhileFetching
// value, then that means the user fetched with {forceRefresh:true},
// so it's safe to return that value.
this.#moveToTail(index);
if (updateAgeOnGet) {
this.#updateItemAge(index);
}
return fetching ? value.__staleWhileFetching : value;
}
#connect(p, n) {
this.#prev[n] = p;
@@ -1476,6 +1605,14 @@ export class LRUCache {
return this.#delete(k, 'delete');
}
#delete(k, reason) {
if (metrics.hasSubscribers) {
metrics.publish({
op: 'delete',
delete: reason,
key: k,
cache: this,
});
}
let deleted = false;
if (this.#size !== 0) {
const index = this.#keyMap.get(k);
@@ -1554,7 +1691,7 @@ export class LRUCache {
}
}
this.#keyMap.clear();
this.#valList.fill(undefined);
void this.#valList.fill(undefined);
this.#keyList.fill(undefined);
if (this.#ttls && this.#starts) {
this.#ttls.fill(0);
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@@ -0,0 +1 @@
{"version":3,"file":"diagnostics-channel-node.d.ts","sourceRoot":"","sources":["../../../src/diagnostics-channel-node.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AACvE,YAAY,EAAE,cAAc,EAAE,OAAO,EAAE,CAAA;AACvC,eAAO,MAAM,OAAO,EAAE,OAAO,CAAC,OAAO,CAAgC,CAAA;AACrE,eAAO,MAAM,OAAO,EAAE,cAAc,CAAC,OAAO,CAA+B,CAAA"}
@@ -0,0 +1 @@
{"version":3,"file":"diagnostics-channel-node.js","sourceRoot":"","sources":["../../../src/diagnostics-channel-node.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,mEAAmE;AACnE,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AAGlE,MAAM,CAAC,MAAM,OAAO,GAAqB,OAAO,CAAC,mBAAmB,CAAC,CAAA;AACrE,MAAM,CAAC,MAAM,OAAO,GAA4B,cAAc,CAAC,WAAW,CAAC,CAAA","sourcesContent":["// simple node version that imports from node builtin\n// this is built to both ESM and CommonJS on the 'node' import path\nimport { tracingChannel, channel } from 'node:diagnostics_channel'\nimport type { TracingChannel, Channel } from 'node:diagnostics_channel'\nexport type { TracingChannel, Channel }\nexport const metrics: Channel<unknown> = channel('lru-cache:metrics')\nexport const tracing: TracingChannel<unknown> = tracingChannel('lru-cache')\n"]}
@@ -0,0 +1,5 @@
import type { TracingChannel, Channel } from 'node:diagnostics_channel';
export type { TracingChannel, Channel };
export declare const metrics: Channel<unknown>;
export declare const tracing: TracingChannel<unknown>;
//# sourceMappingURL=diagnostics-channel-node.d.ts.map
@@ -0,0 +1,6 @@
// simple node version that imports from node builtin
// this is built to both ESM and CommonJS on the 'node' import path
import { tracingChannel, channel } from 'node:diagnostics_channel';
export const metrics = channel('lru-cache:metrics');
export const tracing = tracingChannel('lru-cache');
//# sourceMappingURL=diagnostics-channel-node.js.map
File diff suppressed because it is too large Load Diff
File diff suppressed because one or more lines are too long
File diff suppressed because it is too large Load Diff
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@@ -0,0 +1,12 @@
/**
* this provides the default Perf object source, either the
* `performance` global, or the `Date` constructor.
*
* it can be passed in via configuration to override it
* for a single LRU object.
*/
export type Perf = {
now: () => number;
};
export declare const defaultPerf: Perf;
//# sourceMappingURL=perf.d.ts.map
@@ -0,0 +1 @@
{"version":3,"file":"perf.d.ts","sourceRoot":"","sources":["../../../src/perf.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,IAAI,GAAG;IAAE,GAAG,EAAE,MAAM,MAAM,CAAA;CAAE,CAAA;AACxC,eAAO,MAAM,WAAW,EAAE,IAQG,CAAA"}
@@ -0,0 +1,7 @@
export const defaultPerf = (typeof performance === 'object' &&
performance &&
typeof performance.now === 'function') ?
/* c8 ignore start - this gets covered, but c8 gets confused */
performance
: /* c8 ignore stop */ Date;
//# sourceMappingURL=perf.js.map
@@ -0,0 +1 @@
{"version":3,"file":"perf.js","sourceRoot":"","sources":["../../../src/perf.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,WAAW,GACtB,CACE,OAAO,WAAW,KAAK,QAAQ;IAC/B,WAAW;IACX,OAAO,WAAW,CAAC,GAAG,KAAK,UAAU,CACtC,CAAC,CAAC;IACD,+DAA+D;IAC/D,WAAW;IACb,CAAC,CAAC,oBAAoB,CAAC,IAAI,CAAA","sourcesContent":["/**\n * this provides the default Perf object source, either the\n * `performance` global, or the `Date` constructor.\n *\n * it can be passed in via configuration to override it\n * for a single LRU object.\n */\nexport type Perf = { now: () => number }\nexport const defaultPerf: Perf =\n (\n typeof performance === 'object' &&\n performance &&\n typeof performance.now === 'function'\n ) ?\n /* c8 ignore start - this gets covered, but c8 gets confused */\n performance\n : /* c8 ignore stop */ Date\n"]}
+12
View File
@@ -0,0 +1,12 @@
/**
* this provides the default Perf object source, either the
* `performance` global, or the `Date` constructor.
*
* it can be passed in via configuration to override it
* for a single LRU object.
*/
export type Perf = {
now: () => number;
};
export declare const defaultPerf: Perf;
//# sourceMappingURL=perf.d.ts.map
@@ -0,0 +1 @@
{"version":3,"file":"perf.d.ts","sourceRoot":"","sources":["../../src/perf.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,IAAI,GAAG;IAAE,GAAG,EAAE,MAAM,MAAM,CAAA;CAAE,CAAA;AACxC,eAAO,MAAM,WAAW,EAAE,IAQG,CAAA"}
+7
View File
@@ -0,0 +1,7 @@
export const defaultPerf = (typeof performance === 'object' &&
performance &&
typeof performance.now === 'function') ?
/* c8 ignore start - this gets covered, but c8 gets confused */
performance
: /* c8 ignore stop */ Date;
//# sourceMappingURL=perf.js.map
+1
View File
@@ -0,0 +1 @@
{"version":3,"file":"perf.js","sourceRoot":"","sources":["../../src/perf.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,MAAM,WAAW,GACtB,CACE,OAAO,WAAW,KAAK,QAAQ;IAC/B,WAAW;IACX,OAAO,WAAW,CAAC,GAAG,KAAK,UAAU,CACtC,CAAC,CAAC;IACD,+DAA+D;IAC/D,WAAW;IACb,CAAC,CAAC,oBAAoB,CAAC,IAAI,CAAA","sourcesContent":["/**\n * this provides the default Perf object source, either the\n * `performance` global, or the `Date` constructor.\n *\n * it can be passed in via configuration to override it\n * for a single LRU object.\n */\nexport type Perf = { now: () => number }\nexport const defaultPerf: Perf =\n (\n typeof performance === 'object' &&\n performance &&\n typeof performance.now === 'function'\n ) ?\n /* c8 ignore start - this gets covered, but c8 gets confused */\n performance\n : /* c8 ignore stop */ Date\n"]}
+71 -18
View File
@@ -1,7 +1,7 @@
{
"name": "lru-cache",
"description": "A cache object that deletes the least-recently-used items.",
"version": "11.2.6",
"version": "11.5.1",
"author": "Isaac Z. Schlueter <i@izs.me>",
"keywords": [
"mru",
@@ -11,7 +11,7 @@
"sideEffects": false,
"scripts": {
"build": "npm run prepare",
"prepare": "tshy && bash fixup.sh",
"prepare": "tshy && bash scripts/build.sh",
"pretest": "npm run prepare",
"presnap": "npm run prepare",
"test": "tap",
@@ -25,39 +25,68 @@
"prebenchmark": "npm run prepare",
"benchmark": "make -C benchmark",
"preprofile": "npm run prepare",
"profile": "make -C benchmark profile"
"profile": "make -C benchmark profile",
"lint": "oxlint --fix src test",
"postsnap": "npm run lint",
"postlint": "npm run format"
},
"main": "./dist/commonjs/index.min.js",
"types": "./dist/commonjs/index.d.ts",
"tshy": {
"esmDialects": [
"browser",
"node"
],
"commonjsDialects": [
"browser",
"node"
],
"exports": {
"./raw": "./src/index.ts",
".": {
"import": {
"browser": {
"types": "./dist/esm/browser/index.d.ts",
"default": "./dist/esm/browser/index.min.js"
},
"node": {
"types": "./dist/esm/node/index.d.ts",
"default": "./dist/esm/node/index.min.js"
},
"types": "./dist/esm/index.d.ts",
"default": "./dist/esm/index.min.js"
},
"require": {
"browser": {
"types": "./dist/commonjs/browser/index.d.ts",
"default": "./dist/commonjs/browser/index.min.js"
},
"node": {
"types": "./dist/commonjs/node/index.d.ts",
"default": "./dist/commonjs/node/index.min.js"
},
"types": "./dist/commonjs/index.d.ts",
"default": "./dist/commonjs/index.min.js"
}
}
}
},
"selfLink": false
},
"repository": {
"type": "git",
"url": "git+ssh://git@github.com/isaacs/node-lru-cache.git"
},
"devDependencies": {
"@types/node": "^24.3.0",
"benchmark": "^2.1.4",
"esbuild": "^0.25.9",
"esbuild": "^0.28.0",
"marked": "^4.2.12",
"mkdirp": "^3.0.1",
"prettier": "^3.6.2",
"tap": "^21.1.0",
"tshy": "^3.0.2",
"typedoc": "^0.28.12"
"oxlint": "^1.65.0",
"oxlint-tsgolint": "^0.22.1",
"prettier": "^3.8.3",
"tap": "^21.7.4",
"tshy": "^4.1.2",
"typedoc": "^0.28.19"
},
"license": "BlueOak-1.0.0",
"files": [
@@ -66,31 +95,55 @@
"engines": {
"node": "20 || >=22"
},
"tap": {
"node-arg": [
"--expose-gc"
],
"plugin": [
"@tapjs/clock"
]
},
"exports": {
"./raw": {
"import": {
"browser": {
"types": "./dist/esm/browser/index.d.ts",
"default": "./dist/esm/browser/index.js"
},
"node": {
"types": "./dist/esm/node/index.d.ts",
"default": "./dist/esm/node/index.js"
},
"types": "./dist/esm/index.d.ts",
"default": "./dist/esm/index.js"
},
"require": {
"browser": {
"types": "./dist/commonjs/browser/index.d.ts",
"default": "./dist/commonjs/browser/index.js"
},
"node": {
"types": "./dist/commonjs/node/index.d.ts",
"default": "./dist/commonjs/node/index.js"
},
"types": "./dist/commonjs/index.d.ts",
"default": "./dist/commonjs/index.js"
}
},
".": {
"import": {
"browser": {
"types": "./dist/esm/browser/index.d.ts",
"default": "./dist/esm/browser/index.min.js"
},
"node": {
"types": "./dist/esm/node/index.d.ts",
"default": "./dist/esm/node/index.min.js"
},
"types": "./dist/esm/index.d.ts",
"default": "./dist/esm/index.min.js"
},
"require": {
"browser": {
"types": "./dist/commonjs/browser/index.d.ts",
"default": "./dist/commonjs/browser/index.min.js"
},
"node": {
"types": "./dist/commonjs/node/index.d.ts",
"default": "./dist/commonjs/node/index.min.js"
},
"types": "./dist/commonjs/index.d.ts",
"default": "./dist/commonjs/index.min.js"
}