Du kannst nicht mehr als 25 Themen auswählen Themen müssen mit entweder einem Buchstaben oder einer Ziffer beginnen. Sie können Bindestriche („-“) enthalten und bis zu 35 Zeichen lang sein.

index.d.ts 26KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869
  1. // Project: https://github.com/isaacs/node-lru-cache
  2. // Based initially on @types/lru-cache
  3. // https://github.com/DefinitelyTyped/DefinitelyTyped
  4. // used under the terms of the MIT License, shown below.
  5. //
  6. // DefinitelyTyped license:
  7. // ------
  8. // MIT License
  9. //
  10. // Copyright (c) Microsoft Corporation.
  11. //
  12. // Permission is hereby granted, free of charge, to any person obtaining a
  13. // copy of this software and associated documentation files (the "Software"),
  14. // to deal in the Software without restriction, including without limitation
  15. // the rights to use, copy, modify, merge, publish, distribute, sublicense,
  16. // and/or sell copies of the Software, and to permit persons to whom the
  17. // Software is furnished to do so, subject to the following conditions:
  18. //
  19. // The above copyright notice and this permission notice shall be included
  20. // in all copies or substantial portions of the Software.
  21. //
  22. // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  23. // EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  24. // MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  25. // IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  26. // CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  27. // TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  28. // SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE
  29. // ------
  30. //
  31. // Changes by Isaac Z. Schlueter released under the terms found in the
  32. // LICENSE file within this project.
  33. /**
  34. * Integer greater than 0, representing some number of milliseconds, or the
  35. * time at which a TTL started counting from.
  36. */
  37. declare type LRUMilliseconds = number
  38. /**
  39. * An integer greater than 0, reflecting the calculated size of items
  40. */
  41. declare type LRUSize = number
  42. /**
  43. * An integer greater than 0, reflecting a number of items
  44. */
  45. declare type LRUCount = number
  46. declare class LRUCache<K, V> implements Iterable<[K, V]> {
  47. constructor(options: LRUCache.Options<K, V>)
  48. /**
  49. * Number of items in the cache.
  50. * Alias for {@link size}
  51. *
  52. * @deprecated since 7.0 use {@link size} instead
  53. */
  54. public readonly length: LRUCount
  55. public readonly max: LRUCount
  56. public readonly maxSize: LRUSize
  57. public readonly maxEntrySize: LRUSize
  58. public readonly sizeCalculation:
  59. | LRUCache.SizeCalculator<K, V>
  60. | undefined
  61. public readonly dispose: LRUCache.Disposer<K, V>
  62. /**
  63. * @since 7.4.0
  64. */
  65. public readonly disposeAfter: LRUCache.Disposer<K, V> | null
  66. public readonly noDisposeOnSet: boolean
  67. public readonly ttl: LRUMilliseconds
  68. public readonly ttlResolution: LRUMilliseconds
  69. public readonly ttlAutopurge: boolean
  70. public readonly allowStale: boolean
  71. public readonly updateAgeOnGet: boolean
  72. /**
  73. * @since 7.11.0
  74. */
  75. public readonly noDeleteOnStaleGet: boolean
  76. /**
  77. * @since 7.6.0
  78. */
  79. public readonly fetchMethod: LRUCache.Fetcher<K, V> | null
  80. /**
  81. * The total number of items held in the cache at the current moment.
  82. */
  83. public readonly size: LRUCount
  84. /**
  85. * The total size of items in cache when using size tracking.
  86. */
  87. public readonly calculatedSize: LRUSize
  88. /**
  89. * Add a value to the cache.
  90. */
  91. public set(
  92. key: K,
  93. value: V,
  94. options?: LRUCache.SetOptions<K, V>
  95. ): this
  96. /**
  97. * Return a value from the cache. Will update the recency of the cache entry
  98. * found.
  99. *
  100. * If the key is not found, {@link get} will return `undefined`. This can be
  101. * confusing when setting values specifically to `undefined`, as in
  102. * `cache.set(key, undefined)`. Use {@link has} to determine whether a key is
  103. * present in the cache at all.
  104. */
  105. public get(key: K, options?: LRUCache.GetOptions<V>): V | undefined
  106. /**
  107. * Like {@link get} but doesn't update recency or delete stale items.
  108. * Returns `undefined` if the item is stale, unless {@link allowStale} is set
  109. * either on the cache or in the options object.
  110. */
  111. public peek(key: K, options?: LRUCache.PeekOptions): V | undefined
  112. /**
  113. * Check if a key is in the cache, without updating the recency of use.
  114. * Will return false if the item is stale, even though it is technically
  115. * in the cache.
  116. *
  117. * Will not update item age unless {@link updateAgeOnHas} is set in the
  118. * options or constructor.
  119. */
  120. public has(key: K, options?: LRUCache.HasOptions<V>): boolean
  121. /**
  122. * Deletes a key out of the cache.
  123. * Returns true if the key was deleted, false otherwise.
  124. */
  125. public delete(key: K): boolean
  126. /**
  127. * Clear the cache entirely, throwing away all values.
  128. */
  129. public clear(): void
  130. /**
  131. * Delete any stale entries. Returns true if anything was removed, false
  132. * otherwise.
  133. */
  134. public purgeStale(): boolean
  135. /**
  136. * Find a value for which the supplied fn method returns a truthy value,
  137. * similar to Array.find(). fn is called as fn(value, key, cache).
  138. */
  139. public find(
  140. callbackFn: (
  141. value: V,
  142. key: K,
  143. cache: this
  144. ) => boolean | undefined | void,
  145. options?: LRUCache.GetOptions<V>
  146. ): V | undefined
  147. /**
  148. * Call the supplied function on each item in the cache, in order from
  149. * most recently used to least recently used. fn is called as
  150. * fn(value, key, cache). Does not update age or recenty of use.
  151. */
  152. public forEach<T = this>(
  153. callbackFn: (this: T, value: V, key: K, cache: this) => void,
  154. thisArg?: T
  155. ): void
  156. /**
  157. * The same as {@link forEach} but items are iterated over in reverse
  158. * order. (ie, less recently used items are iterated over first.)
  159. */
  160. public rforEach<T = this>(
  161. callbackFn: (this: T, value: V, key: K, cache: this) => void,
  162. thisArg?: T
  163. ): void
  164. /**
  165. * Return a generator yielding the keys in the cache,
  166. * in order from most recently used to least recently used.
  167. */
  168. public keys(): Generator<K, void, void>
  169. /**
  170. * Inverse order version of {@link keys}
  171. *
  172. * Return a generator yielding the keys in the cache,
  173. * in order from least recently used to most recently used.
  174. */
  175. public rkeys(): Generator<K, void, void>
  176. /**
  177. * Return a generator yielding the values in the cache,
  178. * in order from most recently used to least recently used.
  179. */
  180. public values(): Generator<V, void, void>
  181. /**
  182. * Inverse order version of {@link values}
  183. *
  184. * Return a generator yielding the values in the cache,
  185. * in order from least recently used to most recently used.
  186. */
  187. public rvalues(): Generator<V, void, void>
  188. /**
  189. * Return a generator yielding `[key, value]` pairs,
  190. * in order from most recently used to least recently used.
  191. */
  192. public entries(): Generator<[K, V], void, void>
  193. /**
  194. * Inverse order version of {@link entries}
  195. *
  196. * Return a generator yielding `[key, value]` pairs,
  197. * in order from least recently used to most recently used.
  198. */
  199. public rentries(): Generator<[K, V], void, void>
  200. /**
  201. * Iterating over the cache itself yields the same results as
  202. * {@link entries}
  203. */
  204. public [Symbol.iterator](): Generator<[K, V], void, void>
  205. /**
  206. * Return an array of [key, entry] objects which can be passed to
  207. * cache.load()
  208. */
  209. public dump(): Array<[K, LRUCache.Entry<V>]>
  210. /**
  211. * Reset the cache and load in the items in entries in the order listed.
  212. * Note that the shape of the resulting cache may be different if the
  213. * same options are not used in both caches.
  214. */
  215. public load(
  216. cacheEntries: ReadonlyArray<[K, LRUCache.Entry<V>]>
  217. ): void
  218. /**
  219. * Evict the least recently used item, returning its value or `undefined`
  220. * if cache is empty.
  221. */
  222. public pop(): V | undefined
  223. /**
  224. * Deletes a key out of the cache.
  225. *
  226. * @deprecated since 7.0 use delete() instead
  227. */
  228. public del(key: K): boolean
  229. /**
  230. * Clear the cache entirely, throwing away all values.
  231. *
  232. * @deprecated since 7.0 use clear() instead
  233. */
  234. public reset(): void
  235. /**
  236. * Manually iterates over the entire cache proactively pruning old entries.
  237. *
  238. * @deprecated since 7.0 use purgeStale() instead
  239. */
  240. public prune(): boolean
  241. /**
  242. * Make an asynchronous cached fetch using the {@link fetchMethod} function.
  243. *
  244. * If multiple fetches for the same key are issued, then they will all be
  245. * coalesced into a single call to fetchMethod.
  246. *
  247. * Note that this means that handling options such as
  248. * {@link allowStaleOnFetchAbort}, {@link signal}, and
  249. * {@link allowStaleOnFetchRejection} will be determined by the FIRST fetch()
  250. * call for a given key.
  251. *
  252. * This is a known (fixable) shortcoming which will be addresed on when
  253. * someone complains about it, as the fix would involve added complexity and
  254. * may not be worth the costs for this edge case.
  255. *
  256. * since: 7.6.0
  257. */
  258. public fetch(
  259. key: K,
  260. options?: LRUCache.FetchOptions<K, V>
  261. ): Promise<V>
  262. /**
  263. * since: 7.6.0
  264. */
  265. public getRemainingTTL(key: K): LRUMilliseconds
  266. }
  267. declare namespace LRUCache {
  268. type DisposeReason = 'evict' | 'set' | 'delete'
  269. type SizeCalculator<K, V> = (value: V, key: K) => LRUSize
  270. type Disposer<K, V> = (
  271. value: V,
  272. key: K,
  273. reason: DisposeReason
  274. ) => void
  275. type Fetcher<K, V> = (
  276. key: K,
  277. staleValue: V | undefined,
  278. options: FetcherOptions<K, V>
  279. ) => Promise<V | void | undefined> | V | void | undefined
  280. interface DeprecatedOptions<K, V> {
  281. /**
  282. * alias for ttl
  283. *
  284. * @deprecated since 7.0 use options.ttl instead
  285. */
  286. maxAge?: LRUMilliseconds
  287. /**
  288. * alias for {@link sizeCalculation}
  289. *
  290. * @deprecated since 7.0 use {@link sizeCalculation} instead
  291. */
  292. length?: SizeCalculator<K, V>
  293. /**
  294. * alias for allowStale
  295. *
  296. * @deprecated since 7.0 use options.allowStale instead
  297. */
  298. stale?: boolean
  299. }
  300. interface LimitedByCount {
  301. /**
  302. * The number of most recently used items to keep.
  303. * Note that we may store fewer items than this if maxSize is hit.
  304. */
  305. max: LRUCount
  306. }
  307. type MaybeMaxEntrySizeLimit<K, V> =
  308. | {
  309. /**
  310. * The maximum allowed size for any single item in the cache.
  311. *
  312. * If a larger item is passed to {@link set} or returned by a
  313. * {@link fetchMethod}, then it will not be stored in the cache.
  314. */
  315. maxEntrySize: LRUSize
  316. sizeCalculation?: SizeCalculator<K, V>
  317. }
  318. | {}
  319. interface LimitedBySize<K, V> {
  320. /**
  321. * If you wish to track item size, you must provide a maxSize
  322. * note that we still will only keep up to max *actual items*,
  323. * if max is set, so size tracking may cause fewer than max items
  324. * to be stored. At the extreme, a single item of maxSize size
  325. * will cause everything else in the cache to be dropped when it
  326. * is added. Use with caution!
  327. *
  328. * Note also that size tracking can negatively impact performance,
  329. * though for most cases, only minimally.
  330. */
  331. maxSize: LRUSize
  332. /**
  333. * Function to calculate size of items. Useful if storing strings or
  334. * buffers or other items where memory size depends on the object itself.
  335. *
  336. * Items larger than {@link maxEntrySize} will not be stored in the cache.
  337. *
  338. * Note that when {@link maxSize} or {@link maxEntrySize} are set, every
  339. * item added MUST have a size specified, either via a `sizeCalculation` in
  340. * the constructor, or `sizeCalculation` or {@link size} options to
  341. * {@link set}.
  342. */
  343. sizeCalculation?: SizeCalculator<K, V>
  344. }
  345. interface LimitedByTTL {
  346. /**
  347. * Max time in milliseconds for items to live in cache before they are
  348. * considered stale. Note that stale items are NOT preemptively removed
  349. * by default, and MAY live in the cache, contributing to its LRU max,
  350. * long after they have expired.
  351. *
  352. * Also, as this cache is optimized for LRU/MRU operations, some of
  353. * the staleness/TTL checks will reduce performance, as they will incur
  354. * overhead by deleting items.
  355. *
  356. * Must be an integer number of ms, defaults to 0, which means "no TTL"
  357. */
  358. ttl: LRUMilliseconds
  359. /**
  360. * Boolean flag to tell the cache to not update the TTL when
  361. * setting a new value for an existing key (ie, when updating a value
  362. * rather than inserting a new value). Note that the TTL value is
  363. * _always_ set (if provided) when adding a new entry into the cache.
  364. *
  365. * @default false
  366. * @since 7.4.0
  367. */
  368. noUpdateTTL?: boolean
  369. /**
  370. * Minimum amount of time in ms in which to check for staleness.
  371. * Defaults to 1, which means that the current time is checked
  372. * at most once per millisecond.
  373. *
  374. * Set to 0 to check the current time every time staleness is tested.
  375. * (This reduces performance, and is theoretically unnecessary.)
  376. *
  377. * Setting this to a higher value will improve performance somewhat
  378. * while using ttl tracking, albeit at the expense of keeping stale
  379. * items around a bit longer than their TTLs would indicate.
  380. *
  381. * @default 1
  382. * @since 7.1.0
  383. */
  384. ttlResolution?: LRUMilliseconds
  385. /**
  386. * Preemptively remove stale items from the cache.
  387. * Note that this may significantly degrade performance,
  388. * especially if the cache is storing a large number of items.
  389. * It is almost always best to just leave the stale items in
  390. * the cache, and let them fall out as new items are added.
  391. *
  392. * Note that this means that {@link allowStale} is a bit pointless,
  393. * as stale items will be deleted almost as soon as they expire.
  394. *
  395. * Use with caution!
  396. *
  397. * @default false
  398. * @since 7.1.0
  399. */
  400. ttlAutopurge?: boolean
  401. /**
  402. * Return stale items from {@link get} before disposing of them.
  403. * Return stale values from {@link fetch} while performing a call
  404. * to the {@link fetchMethod} in the background.
  405. *
  406. * @default false
  407. */
  408. allowStale?: boolean
  409. /**
  410. * Update the age of items on {@link get}, renewing their TTL
  411. *
  412. * @default false
  413. */
  414. updateAgeOnGet?: boolean
  415. /**
  416. * Do not delete stale items when they are retrieved with {@link get}.
  417. * Note that the {@link get} return value will still be `undefined` unless
  418. * allowStale is true.
  419. *
  420. * @default false
  421. * @since 7.11.0
  422. */
  423. noDeleteOnStaleGet?: boolean
  424. /**
  425. * Update the age of items on {@link has}, renewing their TTL
  426. *
  427. * @default false
  428. */
  429. updateAgeOnHas?: boolean
  430. }
  431. type SafetyBounds<K, V> =
  432. | LimitedByCount
  433. | LimitedBySize<K, V>
  434. | LimitedByTTL
  435. // options shared by all three of the limiting scenarios
  436. interface SharedOptions<K, V> {
  437. /**
  438. * Function that is called on items when they are dropped from the cache.
  439. * This can be handy if you want to close file descriptors or do other
  440. * cleanup tasks when items are no longer accessible. Called with `key,
  441. * value`. It's called before actually removing the item from the
  442. * internal cache, so it is *NOT* safe to re-add them.
  443. * Use {@link disposeAfter} if you wish to dispose items after they have
  444. * been full removed, when it is safe to add them back to the cache.
  445. */
  446. dispose?: Disposer<K, V>
  447. /**
  448. * The same as dispose, but called *after* the entry is completely
  449. * removed and the cache is once again in a clean state. It is safe to
  450. * add an item right back into the cache at this point.
  451. * However, note that it is *very* easy to inadvertently create infinite
  452. * recursion this way.
  453. *
  454. * @since 7.3.0
  455. */
  456. disposeAfter?: Disposer<K, V>
  457. /**
  458. * Set to true to suppress calling the dispose() function if the entry
  459. * key is still accessible within the cache.
  460. * This may be overridden by passing an options object to {@link set}.
  461. *
  462. * @default false
  463. */
  464. noDisposeOnSet?: boolean
  465. /**
  466. * Function that is used to make background asynchronous fetches. Called
  467. * with `fetchMethod(key, staleValue, { signal, options, context })`.
  468. *
  469. * If `fetchMethod` is not provided, then {@link fetch} is
  470. * equivalent to `Promise.resolve(cache.get(key))`.
  471. *
  472. * The `fetchMethod` should ONLY return `undefined` in cases where the
  473. * abort controller has sent an abort signal.
  474. *
  475. * @since 7.6.0
  476. */
  477. fetchMethod?: LRUCache.Fetcher<K, V>
  478. /**
  479. * Set to true to suppress the deletion of stale data when a
  480. * {@link fetchMethod} throws an error or returns a rejected promise
  481. *
  482. * This may be overridden in the {@link fetchMethod}.
  483. *
  484. * @default false
  485. * @since 7.10.0
  486. */
  487. noDeleteOnFetchRejection?: boolean
  488. /**
  489. * Set to true to allow returning stale data when a {@link fetchMethod}
  490. * throws an error or returns a rejected promise. Note that this
  491. * differs from using {@link allowStale} in that stale data will
  492. * ONLY be returned in the case that the fetch fails, not any other
  493. * times.
  494. *
  495. * This may be overridden in the {@link fetchMethod}.
  496. *
  497. * @default false
  498. * @since 7.16.0
  499. */
  500. allowStaleOnFetchRejection?: boolean
  501. /**
  502. *
  503. * Set to true to ignore the `abort` event emitted by the `AbortSignal`
  504. * object passed to {@link fetchMethod}, and still cache the
  505. * resulting resolution value, as long as it is not `undefined`.
  506. *
  507. * When used on its own, this means aborted {@link fetch} calls are not
  508. * immediately resolved or rejected when they are aborted, and instead take
  509. * the full time to await.
  510. *
  511. * When used with {@link allowStaleOnFetchAbort}, aborted {@link fetch}
  512. * calls will resolve immediately to their stale cached value or
  513. * `undefined`, and will continue to process and eventually update the
  514. * cache when they resolve, as long as the resulting value is not
  515. * `undefined`, thus supporting a "return stale on timeout while
  516. * refreshing" mechanism by passing `AbortSignal.timeout(n)` as the signal.
  517. *
  518. * **Note**: regardless of this setting, an `abort` event _is still emitted
  519. * on the `AbortSignal` object_, so may result in invalid results when
  520. * passed to other underlying APIs that use AbortSignals.
  521. *
  522. * This may be overridden in the {@link fetchMethod} or the call to
  523. * {@link fetch}.
  524. *
  525. * @default false
  526. * @since 7.17.0
  527. */
  528. ignoreFetchAbort?: boolean
  529. /**
  530. * Set to true to return a stale value from the cache when the
  531. * `AbortSignal` passed to the {@link fetchMethod} dispatches an `'abort'`
  532. * event, whether user-triggered, or due to internal cache behavior.
  533. *
  534. * Unless {@link ignoreFetchAbort} is also set, the underlying
  535. * {@link fetchMethod} will still be considered canceled, and its return
  536. * value will be ignored and not cached.
  537. *
  538. * This may be overridden in the {@link fetchMethod} or the call to
  539. * {@link fetch}.
  540. *
  541. * @default false
  542. * @since 7.17.0
  543. */
  544. allowStaleOnFetchAbort?: boolean
  545. /**
  546. * Set to any value in the constructor or {@link fetch} options to
  547. * pass arbitrary data to the {@link fetchMethod} in the {@link context}
  548. * options field.
  549. *
  550. * @since 7.12.0
  551. */
  552. fetchContext?: any
  553. }
  554. type Options<K, V> = SharedOptions<K, V> &
  555. DeprecatedOptions<K, V> &
  556. SafetyBounds<K, V> &
  557. MaybeMaxEntrySizeLimit<K, V>
  558. /**
  559. * options which override the options set in the LRUCache constructor
  560. * when making calling {@link set}.
  561. */
  562. interface SetOptions<K, V> {
  563. /**
  564. * A value for the size of the entry, prevents calls to
  565. * {@link sizeCalculation}.
  566. *
  567. * Items larger than {@link maxEntrySize} will not be stored in the cache.
  568. *
  569. * Note that when {@link maxSize} or {@link maxEntrySize} are set, every
  570. * item added MUST have a size specified, either via a `sizeCalculation` in
  571. * the constructor, or {@link sizeCalculation} or `size` options to
  572. * {@link set}.
  573. */
  574. size?: LRUSize
  575. /**
  576. * Overrides the {@link sizeCalculation} method set in the constructor.
  577. *
  578. * Items larger than {@link maxEntrySize} will not be stored in the cache.
  579. *
  580. * Note that when {@link maxSize} or {@link maxEntrySize} are set, every
  581. * item added MUST have a size specified, either via a `sizeCalculation` in
  582. * the constructor, or `sizeCalculation` or {@link size} options to
  583. * {@link set}.
  584. */
  585. sizeCalculation?: SizeCalculator<K, V>
  586. ttl?: LRUMilliseconds
  587. start?: LRUMilliseconds
  588. noDisposeOnSet?: boolean
  589. noUpdateTTL?: boolean
  590. status?: Status<V>
  591. }
  592. /**
  593. * options which override the options set in the LRUCAche constructor
  594. * when calling {@link has}.
  595. */
  596. interface HasOptions<V> {
  597. updateAgeOnHas?: boolean
  598. status: Status<V>
  599. }
  600. /**
  601. * options which override the options set in the LRUCache constructor
  602. * when calling {@link get}.
  603. */
  604. interface GetOptions<V> {
  605. allowStale?: boolean
  606. updateAgeOnGet?: boolean
  607. noDeleteOnStaleGet?: boolean
  608. status?: Status<V>
  609. }
  610. /**
  611. * options which override the options set in the LRUCache constructor
  612. * when calling {@link peek}.
  613. */
  614. interface PeekOptions {
  615. allowStale?: boolean
  616. }
  617. /**
  618. * Options object passed to the {@link fetchMethod}
  619. *
  620. * May be mutated by the {@link fetchMethod} to affect the behavior of the
  621. * resulting {@link set} operation on resolution, or in the case of
  622. * {@link noDeleteOnFetchRejection}, {@link ignoreFetchAbort}, and
  623. * {@link allowStaleOnFetchRejection}, the handling of failure.
  624. */
  625. interface FetcherFetchOptions<K, V> {
  626. allowStale?: boolean
  627. updateAgeOnGet?: boolean
  628. noDeleteOnStaleGet?: boolean
  629. size?: LRUSize
  630. sizeCalculation?: SizeCalculator<K, V>
  631. ttl?: LRUMilliseconds
  632. noDisposeOnSet?: boolean
  633. noUpdateTTL?: boolean
  634. noDeleteOnFetchRejection?: boolean
  635. allowStaleOnFetchRejection?: boolean
  636. ignoreFetchAbort?: boolean
  637. allowStaleOnFetchAbort?: boolean
  638. status?: Status<V>
  639. }
  640. /**
  641. * Status object that may be passed to {@link fetch}, {@link get},
  642. * {@link set}, and {@link has}.
  643. */
  644. interface Status<V> {
  645. /**
  646. * The status of a set() operation.
  647. *
  648. * - add: the item was not found in the cache, and was added
  649. * - update: the item was in the cache, with the same value provided
  650. * - replace: the item was in the cache, and replaced
  651. * - miss: the item was not added to the cache for some reason
  652. */
  653. set?: 'add' | 'update' | 'replace' | 'miss'
  654. /**
  655. * the ttl stored for the item, or undefined if ttls are not used.
  656. */
  657. ttl?: LRUMilliseconds
  658. /**
  659. * the start time for the item, or undefined if ttls are not used.
  660. */
  661. start?: LRUMilliseconds
  662. /**
  663. * The timestamp used for TTL calculation
  664. */
  665. now?: LRUMilliseconds
  666. /**
  667. * the remaining ttl for the item, or undefined if ttls are not used.
  668. */
  669. remainingTTL?: LRUMilliseconds
  670. /**
  671. * The calculated size for the item, if sizes are used.
  672. */
  673. size?: LRUSize
  674. /**
  675. * A flag indicating that the item was not stored, due to exceeding the
  676. * {@link maxEntrySize}
  677. */
  678. maxEntrySizeExceeded?: true
  679. /**
  680. * The old value, specified in the case of `set:'update'` or
  681. * `set:'replace'`
  682. */
  683. oldValue?: V
  684. /**
  685. * The results of a {@link has} operation
  686. *
  687. * - hit: the item was found in the cache
  688. * - stale: the item was found in the cache, but is stale
  689. * - miss: the item was not found in the cache
  690. */
  691. has?: 'hit' | 'stale' | 'miss'
  692. /**
  693. * The status of a {@link fetch} operation.
  694. * Note that this can change as the underlying fetch() moves through
  695. * various states.
  696. *
  697. * - inflight: there is another fetch() for this key which is in process
  698. * - get: there is no fetchMethod, so {@link get} was called.
  699. * - miss: the item is not in cache, and will be fetched.
  700. * - hit: the item is in the cache, and was resolved immediately.
  701. * - stale: the item is in the cache, but stale.
  702. * - refresh: the item is in the cache, and not stale, but
  703. * {@link forceRefresh} was specified.
  704. */
  705. fetch?: 'get' | 'inflight' | 'miss' | 'hit' | 'stale' | 'refresh'
  706. /**
  707. * The {@link fetchMethod} was called
  708. */
  709. fetchDispatched?: true
  710. /**
  711. * The cached value was updated after a successful call to fetchMethod
  712. */
  713. fetchUpdated?: true
  714. /**
  715. * The reason for a fetch() rejection. Either the error raised by the
  716. * {@link fetchMethod}, or the reason for an AbortSignal.
  717. */
  718. fetchError?: Error
  719. /**
  720. * The fetch received an abort signal
  721. */
  722. fetchAborted?: true
  723. /**
  724. * The abort signal received was ignored, and the fetch was allowed to
  725. * continue.
  726. */
  727. fetchAbortIgnored?: true
  728. /**
  729. * The fetchMethod promise resolved successfully
  730. */
  731. fetchResolved?: true
  732. /**
  733. * The fetchMethod promise was rejected
  734. */
  735. fetchRejected?: true
  736. /**
  737. * The status of a {@link get} operation.
  738. *
  739. * - fetching: The item is currently being fetched. If a previous value is
  740. * present and allowed, that will be returned.
  741. * - stale: The item is in the cache, and is stale.
  742. * - hit: the item is in the cache
  743. * - miss: the item is not in the cache
  744. */
  745. get?: 'stale' | 'hit' | 'miss'
  746. /**
  747. * A fetch or get operation returned a stale value.
  748. */
  749. returnedStale?: true
  750. }
  751. /**
  752. * options which override the options set in the LRUCache constructor
  753. * when calling {@link fetch}.
  754. *
  755. * This is the union of GetOptions and SetOptions, plus
  756. * {@link noDeleteOnFetchRejection}, {@link allowStaleOnFetchRejection},
  757. * {@link forceRefresh}, and {@link fetchContext}
  758. */
  759. interface FetchOptions<K, V> extends FetcherFetchOptions<K, V> {
  760. forceRefresh?: boolean
  761. fetchContext?: any
  762. signal?: AbortSignal
  763. status?: Status<V>
  764. }
  765. interface FetcherOptions<K, V> {
  766. signal: AbortSignal
  767. options: FetcherFetchOptions<K, V>
  768. /**
  769. * Object provided in the {@link fetchContext} option
  770. */
  771. context: any
  772. }
  773. interface Entry<V> {
  774. value: V
  775. ttl?: LRUMilliseconds
  776. size?: LRUSize
  777. start?: LRUMilliseconds
  778. }
  779. }
  780. export = LRUCache