3 A cache object that deletes the least-recently-used items.
5 [![Build Status](https://travis-ci.org/isaacs/node-lru-cache.svg?branch=master)](https://travis-ci.org/isaacs/node-lru-cache) [![Coverage Status](https://coveralls.io/repos/isaacs/node-lru-cache/badge.svg?service=github)](https://coveralls.io/github/isaacs/node-lru-cache)
10 var LRU = require("lru-cache")
11 , options = { max: 500
12 , length: function (n, key) { return n * 2 + key.length }
13 , dispose: function (key, n) { n.close() }
14 , maxAge: 1000 * 60 * 60 }
15 , cache = LRU(options)
16 , otherCache = LRU(50) // sets just the max size
18 cache.set("key", "value")
19 cache.get("key") // "value"
21 // non-string keys ARE fully supported
23 cache.set(someObject, 'a value')
24 cache.set('[object Object]', 'a different value')
25 assert.equal(cache.get(someObject), 'a value')
27 cache.reset() // empty the cache
30 If you put more stuff in it, then items will fall out.
32 If you try to put an oversized thing in it, then it'll fall out right
37 * `max` The maximum size of the cache, checked by applying the length
38 function to all values in the cache. Not setting this is kind of
39 silly, since that's the whole purpose of this lib, but it defaults
41 * `maxAge` Maximum age in ms. Items are not pro-actively pruned out
42 as they age, but if you try to get an item that is too old, it'll
43 drop it and return undefined instead of giving it to you.
44 * `length` Function that is used to calculate the length of stored
45 items. If you're storing strings or buffers, then you probably want
46 to do something like `function(n, key){return n.length}`. The default is
47 `function(){return 1}`, which is fine if you want to store `max`
48 like-sized things. They item is passed as the first argument, and
49 the key is passed as the second argumnet.
50 * `dispose` Function that is called on items when they are dropped
51 from the cache. This can be handy if you want to close file
52 descriptors or do other cleanup tasks when items are no longer
53 accessible. Called with `key, value`. It's called *before*
54 actually removing the item from the internal cache, so if you want
55 to immediately put it back in, you'll have to do that in a
56 `nextTick` or `setTimeout` callback or it won't do anything.
57 * `stale` By default, if you set a `maxAge`, it'll only actually pull
58 stale items out of the cache when you `get(key)`. (That is, it's
59 not pre-emptively doing a `setTimeout` or anything.) If you set
60 `stale:true`, it'll return the stale value before deleting it. If
61 you don't set this, then it'll return `undefined` when you try to
62 get a stale entry, as if it had already been deleted.
66 * `set(key, value, maxAge)`
69 Both of these will update the "recently used"-ness of the key.
70 They do what you think. `maxAge` is optional and overrides the
71 cache `maxAge` option if provided.
73 If the key is not found, `get()` will return `undefined`.
75 The key and val can be any value.
79 Returns the key value (or `undefined` if not found) without
80 updating the "recently used"-ness of the key.
82 (If you find yourself using this a lot, you *might* be using the
83 wrong sort of data structure, but there are some use cases where
88 Deletes a key out of the cache.
92 Clear the cache entirely, throwing away all values.
96 Check if a key is in the cache, without updating the recent-ness
97 or deleting it for being stale.
99 * `forEach(function(value,key,cache), [thisp])`
101 Just like `Array.prototype.forEach`. Iterates over all the keys
102 in the cache, in order of recent-ness. (Ie, more recently used
103 items are iterated over first.)
105 * `rforEach(function(value,key,cache), [thisp])`
107 The same as `cache.forEach(...)` but items are iterated over in
108 reverse order. (ie, less recently used items are iterated over
113 Return an array of the keys in the cache.
117 Return an array of the values in the cache.
121 Return total length of objects in cache taking into account
122 `length` options function.
126 Return total quantity of objects currently in cache. Note, that
127 `stale` (see options) items are returned as part of this item
132 Return an array of the cache entries ready for serialization and usage
133 with 'destinationCache.load(arr)`.
135 * `load(cacheEntriesArray)`
137 Loads another cache entries array, obtained with `sourceCache.dump()`,
138 into the cache. The destination cache is reset before loading new entries
142 Manually iterates over the entire cache proactively pruning old entries