138 lines
4.3 KiB
Markdown
138 lines
4.3 KiB
Markdown
|
# lru cache
|
||
|
|
|
||
|
|
A cache object that deletes the least-recently-used items.
|
||
|
|
|
||
|
|
## Usage:
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
var LRU = require("lru-cache")
|
||
|
|
, options = { max: 500
|
||
|
|
, length: function (n) { return n * 2 }
|
||
|
|
, dispose: function (key, n) { n.close() }
|
||
|
|
, maxAge: 1000 * 60 * 60 }
|
||
|
|
, cache = LRU(options)
|
||
|
|
, otherCache = LRU(50) // sets just the max size
|
||
|
|
|
||
|
|
cache.set("key", "value")
|
||
|
|
cache.get("key") // "value"
|
||
|
|
|
||
|
|
cache.reset() // empty the cache
|
||
|
|
```
|
||
|
|
|
||
|
|
If you put more stuff in it, then items will fall out.
|
||
|
|
|
||
|
|
If you try to put an oversized thing in it, then it'll fall out right
|
||
|
|
away.
|
||
|
|
|
||
|
|
## Keys should always be Strings or Numbers
|
||
|
|
|
||
|
|
Note: this module will print warnings to `console.error` if you use a
|
||
|
|
key that is not a String or Number. Because items are stored in an
|
||
|
|
object, which coerces keys to a string, it won't go well for you if
|
||
|
|
you try to use a key that is not a unique string, it'll cause surprise
|
||
|
|
collisions. For example:
|
||
|
|
|
||
|
|
```JavaScript
|
||
|
|
// Bad Example! Dont' do this!
|
||
|
|
var cache = LRU()
|
||
|
|
var a = {}
|
||
|
|
var b = {}
|
||
|
|
cache.set(a, 'this is a')
|
||
|
|
cache.set(b, 'this is b')
|
||
|
|
console.log(cache.get(a)) // prints: 'this is b'
|
||
|
|
```
|
||
|
|
|
||
|
|
## Options
|
||
|
|
|
||
|
|
* `max` The maximum size of the cache, checked by applying the length
|
||
|
|
function to all values in the cache. Not setting this is kind of
|
||
|
|
silly, since that's the whole purpose of this lib, but it defaults
|
||
|
|
to `Infinity`.
|
||
|
|
* `maxAge` Maximum age in ms. Items are not pro-actively pruned out
|
||
|
|
as they age, but if you try to get an item that is too old, it'll
|
||
|
|
drop it and return undefined instead of giving it to you.
|
||
|
|
* `length` Function that is used to calculate the length of stored
|
||
|
|
items. If you're storing strings or buffers, then you probably want
|
||
|
|
to do something like `function(n){return n.length}`. The default is
|
||
|
|
`function(n){return 1}`, which is fine if you want to store `max`
|
||
|
|
like-sized things.
|
||
|
|
* `dispose` Function that is called on items when they are dropped
|
||
|
|
from the cache. This can be handy if you want to close file
|
||
|
|
descriptors or do other cleanup tasks when items are no longer
|
||
|
|
accessible. Called with `key, value`. It's called *before*
|
||
|
|
actually removing the item from the internal cache, so if you want
|
||
|
|
to immediately put it back in, you'll have to do that in a
|
||
|
|
`nextTick` or `setTimeout` callback or it won't do anything.
|
||
|
|
* `stale` By default, if you set a `maxAge`, it'll only actually pull
|
||
|
|
stale items out of the cache when you `get(key)`. (That is, it's
|
||
|
|
not pre-emptively doing a `setTimeout` or anything.) If you set
|
||
|
|
`stale:true`, it'll return the stale value before deleting it. If
|
||
|
|
you don't set this, then it'll return `undefined` when you try to
|
||
|
|
get a stale entry, as if it had already been deleted.
|
||
|
|
|
||
|
|
## API
|
||
|
|
|
||
|
|
* `set(key, value, maxAge)`
|
||
|
|
* `get(key) => value`
|
||
|
|
|
||
|
|
Both of these will update the "recently used"-ness of the key.
|
||
|
|
They do what you think. `max` is optional and overrides the
|
||
|
|
cache `max` option if provided.
|
||
|
|
|
||
|
|
* `peek(key)`
|
||
|
|
|
||
|
|
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.)
|
||
|
|
|
||
|
|
* `del(key)`
|
||
|
|
|
||
|
|
Deletes a key out of the cache.
|
||
|
|
|
||
|
|
* `reset()`
|
||
|
|
|
||
|
|
Clear the cache entirely, throwing away all values.
|
||
|
|
|
||
|
|
* `has(key)`
|
||
|
|
|
||
|
|
Check if a key is in the cache, without updating the recent-ness
|
||
|
|
or deleting it for being stale.
|
||
|
|
|
||
|
|
* `forEach(function(value,key,cache), [thisp])`
|
||
|
|
|
||
|
|
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.)
|
||
|
|
|
||
|
|
* `keys()`
|
||
|
|
|
||
|
|
Return an array of the keys in the cache.
|
||
|
|
|
||
|
|
* `values()`
|
||
|
|
|
||
|
|
Return an array of the values in the cache.
|
||
|
|
|
||
|
|
* `length()`
|
||
|
|
|
||
|
|
Return total length of objects in cache taking into account
|
||
|
|
`length` options function.
|
||
|
|
|
||
|
|
* `itemCount`
|
||
|
|
|
||
|
|
Return total quantity of objects currently in cache. Note, that
|
||
|
|
`stale` (see options) items are returned as part of this item
|
||
|
|
count.
|
||
|
|
|
||
|
|
* `dump()`
|
||
|
|
|
||
|
|
Return an array of the cache entries ready for serialization and usage
|
||
|
|
with 'destinationCache.load(arr)`.
|
||
|
|
|
||
|
|
* `load(cacheEntriesArray)`
|
||
|
|
|
||
|
|
Loads another cache entries array, obtained with `sourceCache.dump()`,
|
||
|
|
into the cache. The destination cache is reset before loading new entries
|