From e42960acab3ad4e8f598aa5c814e1ef77757fed9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=9A=D0=BE=D1=81=D1=82=D1=8F=20=D0=A2=D1=80=D0=B5=D1=82?= =?UTF-8?q?=D1=8F=D0=BA?= Date: Thu, 19 Jan 2017 00:30:06 +0200 Subject: [PATCH] Update declarations for 'lru-cache'. (#14096) --- lru-cache/index.d.ts | 119 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 117 insertions(+), 2 deletions(-) diff --git a/lru-cache/index.d.ts b/lru-cache/index.d.ts index c7b30e3551..b9216d3159 100644 --- a/lru-cache/index.d.ts +++ b/lru-cache/index.d.ts @@ -1,4 +1,4 @@ -// Type definitions for lru-cache v2.5.0 +// Type definitions for lru-cache v4.0 // Project: https://github.com/isaacs/node-lru-cache // Definitions by: Bart van der Schoor // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped @@ -9,26 +9,141 @@ declare function LRU(max: number): LRU.Cache; declare namespace LRU { interface Options { + /** + * The maximum size of the cache, checked by applying the length + * function to all values in the cache. Not setting this is kind of silly, + * since that's the whole purpose of this lib, but it defaults to `Infinity`. + */ max?: number; + + /** + * Maximum age in ms. Items are not pro-actively pruned out as they age, + * but if you try to get an item that is too old, it'll drop it and return + * undefined instead of giving it to you. + */ maxAge?: number; + + /** + * Function that is used to calculate the length of stored items. + * If you're storing strings or buffers, then you probably want to do + * something like `function(n, key){return n.length}`. The default + * is `function(){return 1}`, which is fine if you want to store + * `max` like-sized things. The item is passed as the first argument, + * and the key is passed as the second argumnet. + */ length?: (value: T) => number; + + /** + * Function that is called on items when they are dropped from the cache. + * This can be handy if you want to close file descriptors or do other + * cleanup tasks when items are no longer accessible. Called with `key, value`. + * It's called before actually removing the item from the internal cache, + * so if you want to immediately put it back in, you'll have to do that in + * a `nextTick` or `setTimeout` callback or it won't do anything. + */ dispose?: (key: any, value: T) => void; + + /** + * By default, if you set a `maxAge`, it'll only actually pull stale items + * out of the cache when you `get(key)`. (That is, it's not pre-emptively + * doing a `setTimeout` or anything.) If you set `stale:true`, it'll return + * the stale value before deleting it. If you don't set this, then it'll + * return `undefined` when you try to get a stale entry, + * as if it had already been deleted. + */ stale?: boolean; } interface Cache { + /** + * Will update the "recently used"-ness of the key. They do what you think. + * `maxAge` is optional and overrides the cache `maxAge` option if provided. + */ set(key: any, value: T, maxAge?: number): void; + + /** + * Will update the "recently used"-ness of the key. They do what you think. + * `maxAge` is optional and overrides the cache `maxAge` option if provided. + * + * If the key is not found, will return `undefined`. + */ get(key: any): T; + + /** + * Returns the key value (or `undefined` if not found) without updating + * the "recently used"-ness of the key. + * + * (If you find yourself using this a lot, you might be using the wrong + * sort of data structure, but there are some use cases where it's handy.) + */ peek(key: any): T; + + /** + * Check if a key is in the cache, without updating the recent-ness + * or deleting it for being stale. + */ has(key: any): boolean + + /** + * Deletes a key out of the cache. + */ del(key: any): void; + + /** + * Clear the cache entirely, throwing away all values. + */ reset(): void; + + /** + * Manually iterates over the entire cache proactively pruning old entries. + */ prune(): void; + + /** + * Just like `Array.prototype.forEach`. Iterates over all the keys in the cache, + * in order of recent-ness. (Ie, more recently used items are iterated over first.) + */ forEach(iter: (value: T, key: any, cache: Cache) => void, thisp?: any): void; + + /** + * The same as `cache.forEach(...)` but items are iterated over in reverse order. + * (ie, less recently used items are iterated over first.) + */ + rforEach(iter: (value: T, key: any, cache: Cache) => void, thisp?: any): void; + + /** + * Return total quantity of objects currently in cache. Note, + * that `stale` (see options) items are returned as part of this item count. + */ itemCount: number; - length: number + + /** + * Return total length of objects in cache taking into account `length` options function. + */ + length: number; + + /** + * Return an array of the keys in the cache. + */ keys(): any[]; + + /** + * Return an array of the values in the cache. + */ values(): T[]; + + /** + * Return an array of the cache entries ready for serialization and usage with `destinationCache.load(arr)`. + */ + dump(): T[]; + + /** + * Loads another cache entries array, obtained with `sourceCache.dump()`, + * into the cache. The destination cache is reset before loading new entries + * + * @param cacheEntries Obtained from `sourceCache.dump()` + */ + load(cacheEntries: T[]): void; } }