1 | # lru cache
|
2 |
|
3 | A cache object that deletes the least-recently-used items.
|
4 |
|
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)
|
6 |
|
7 | ## Installation:
|
8 |
|
9 | ```javascript
|
10 | npm install lru-cache --save
|
11 | ```
|
12 |
|
13 | ## Usage:
|
14 |
|
15 | ```javascript
|
16 | var LRU = require("lru-cache")
|
17 | , options = { max: 500
|
18 | , length: function (n, key) { return n * 2 + key.length }
|
19 | , dispose: function (key, n) { n.close() }
|
20 | , maxAge: 1000 * 60 * 60 }
|
21 | , cache = new LRU(options)
|
22 | , otherCache = new LRU(50) // sets just the max size
|
23 |
|
24 | cache.set("key", "value")
|
25 | cache.get("key") // "value"
|
26 |
|
27 | // non-string keys ARE fully supported
|
28 | // but note that it must be THE SAME object, not
|
29 | // just a JSON-equivalent object.
|
30 | var someObject = { a: 1 }
|
31 | cache.set(someObject, 'a value')
|
32 | // Object keys are not toString()-ed
|
33 | cache.set('[object Object]', 'a different value')
|
34 | assert.equal(cache.get(someObject), 'a value')
|
35 | // A similar object with same keys/values won't work,
|
36 | // because it's a different object identity
|
37 | assert.equal(cache.get({ a: 1 }), undefined)
|
38 |
|
39 | cache.reset() // empty the cache
|
40 | ```
|
41 |
|
42 | If you put more stuff in it, then items will fall out.
|
43 |
|
44 | If you try to put an oversized thing in it, then it'll fall out right
|
45 | away.
|
46 |
|
47 | ## Options
|
48 |
|
49 | * `max` The maximum size of the cache, checked by applying the length
|
50 | function to all values in the cache. Not setting this is kind of
|
51 | silly, since that's the whole purpose of this lib, but it defaults
|
52 | to `Infinity`. Setting it to a non-number or negative number will
|
53 | throw a `TypeError`. Setting it to 0 makes it be `Infinity`.
|
54 | * `maxAge` Maximum age in ms. Items are not pro-actively pruned out
|
55 | as they age, but if you try to get an item that is too old, it'll
|
56 | drop it and return undefined instead of giving it to you.
|
57 | Setting this to a negative value will make everything seem old!
|
58 | Setting it to a non-number will throw a `TypeError`.
|
59 | * `length` Function that is used to calculate the length of stored
|
60 | items. If you're storing strings or buffers, then you probably want
|
61 | to do something like `function(n, key){return n.length}`. The default is
|
62 | `function(){return 1}`, which is fine if you want to store `max`
|
63 | like-sized things. The item is passed as the first argument, and
|
64 | the key is passed as the second argumnet.
|
65 | * `dispose` Function that is called on items when they are dropped
|
66 | from the cache. This can be handy if you want to close file
|
67 | descriptors or do other cleanup tasks when items are no longer
|
68 | accessible. Called with `key, value`. It's called *before*
|
69 | actually removing the item from the internal cache, so if you want
|
70 | to immediately put it back in, you'll have to do that in a
|
71 | `nextTick` or `setTimeout` callback or it won't do anything.
|
72 | * `stale` By default, if you set a `maxAge`, it'll only actually pull
|
73 | stale items out of the cache when you `get(key)`. (That is, it's
|
74 | not pre-emptively doing a `setTimeout` or anything.) If you set
|
75 | `stale:true`, it'll return the stale value before deleting it. If
|
76 | you don't set this, then it'll return `undefined` when you try to
|
77 | get a stale entry, as if it had already been deleted.
|
78 | * `noDisposeOnSet` By default, if you set a `dispose()` method, then
|
79 | it'll be called whenever a `set()` operation overwrites an existing
|
80 | key. If you set this option, `dispose()` will only be called when a
|
81 | key falls out of the cache, not when it is overwritten.
|
82 | * `updateAgeOnGet` When using time-expiring entries with `maxAge`,
|
83 | setting this to `true` will make each item's effective time update
|
84 | to the current time whenever it is retrieved from cache, causing it
|
85 | to not expire. (It can still fall out of cache based on recency of
|
86 | use, of course.)
|
87 |
|
88 | ## API
|
89 |
|
90 | * `set(key, value, maxAge)`
|
91 | * `get(key) => value`
|
92 |
|
93 | Both of these will update the "recently used"-ness of the key.
|
94 | They do what you think. `maxAge` is optional and overrides the
|
95 | cache `maxAge` option if provided.
|
96 |
|
97 | If the key is not found, `get()` will return `undefined`.
|
98 |
|
99 | The key and val can be any value.
|
100 |
|
101 | * `peek(key)`
|
102 |
|
103 | Returns the key value (or `undefined` if not found) without
|
104 | updating the "recently used"-ness of the key.
|
105 |
|
106 | (If you find yourself using this a lot, you *might* be using the
|
107 | wrong sort of data structure, but there are some use cases where
|
108 | it's handy.)
|
109 |
|
110 | * `del(key)`
|
111 |
|
112 | Deletes a key out of the cache.
|
113 |
|
114 | * `reset()`
|
115 |
|
116 | Clear the cache entirely, throwing away all values.
|
117 |
|
118 | * `has(key)`
|
119 |
|
120 | Check if a key is in the cache, without updating the recent-ness
|
121 | or deleting it for being stale.
|
122 |
|
123 | * `forEach(function(value,key,cache), [thisp])`
|
124 |
|
125 | Just like `Array.prototype.forEach`. Iterates over all the keys
|
126 | in the cache, in order of recent-ness. (Ie, more recently used
|
127 | items are iterated over first.)
|
128 |
|
129 | * `rforEach(function(value,key,cache), [thisp])`
|
130 |
|
131 | The same as `cache.forEach(...)` but items are iterated over in
|
132 | reverse order. (ie, less recently used items are iterated over
|
133 | first.)
|
134 |
|
135 | * `keys()`
|
136 |
|
137 | Return an array of the keys in the cache.
|
138 |
|
139 | * `values()`
|
140 |
|
141 | Return an array of the values in the cache.
|
142 |
|
143 | * `length`
|
144 |
|
145 | Return total length of objects in cache taking into account
|
146 | `length` options function.
|
147 |
|
148 | * `itemCount`
|
149 |
|
150 | Return total quantity of objects currently in cache. Note, that
|
151 | `stale` (see options) items are returned as part of this item
|
152 | count.
|
153 |
|
154 | * `dump()`
|
155 |
|
156 | Return an array of the cache entries ready for serialization and usage
|
157 | with 'destinationCache.load(arr)`.
|
158 |
|
159 | * `load(cacheEntriesArray)`
|
160 |
|
161 | Loads another cache entries array, obtained with `sourceCache.dump()`,
|
162 | into the cache. The destination cache is reset before loading new entries
|
163 |
|
164 | * `prune()`
|
165 |
|
166 | Manually iterates over the entire cache proactively pruning old entries
|