corrade-nucleus-nucleons – Blame information for rev 20

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