Permalink
Browse files

README.md

  • Loading branch information...
0 parents commit 64ab77aa3d06d6e7c083ec0b863f551b8fa3d893 @isaacs committed Aug 10, 2012
Showing with 64 additions and 0 deletions.
  1. +64 −0 README.md
@@ -0,0 +1,64 @@
+# async-cache
+
+Cache your async lookups and don't fetch the same thing more than
+necessary.
+
+## Example
+
+Let's say you have to look up stat info from paths. But you are ok
+with only looking up the stat info once every 10 minutes (since it
+doesn't change that often), and you want to limit your cache size to
+1000 objects, and never have two stat calls for the same file
+happening at the same time (since that's silly and unnecessary).
+
+You can do this:
+
+```javascript
+var stats = new AsyncCache({
+ // options passed directly to the internal lru cache
+ max: 1000,
+ maxAge: 1000 * 60 * 10,
+ // method to load a thing if it's not in the cache.
+ // key must be unique in the context of this cache.
+ load: function (key, cb) {
+ // the key can be something like the path, or fd+path, or whatever.
+ // something that will be unique.
+ // this method will only be called if it's not already in cache, and will
+ // cache the result in the lru.
+ getTheStatFromTheKey(key, cb)
+ }
+})
+
+// then later..
+stats.get(fd + ':' + path, function (er, stat) {
+ // maybe loaded from cache, maybe just fetched
+})
+```
+
+Except for the `load` method, all the options are passed unmolested to
+the internal [lru-cache](http://npm.im/lru-cache).
+
+### Differences from [lru-cache](http://npm.im/lru-cache)
+
+Since values are fetched asynchronously, the `get` method takes a
+callback, rather than returning the value synchronously.
+
+While there is a `set(k,v)` method to manually seed the cache,
+typically you'll just call `get` and let the load function fetch the
+key for you.
+
+Keys must uniquely identify a single object, and must contain all the
+information required to fetch an object, and must be strings.
+
+## Methods
+
+* `get(key, cb)` If the key is in the cache, then calls `cb(null,
+ cached)` on nextTick. Otherwise, calls the `load` function that was
+ supplied in the options object. If it doesn't return an error, then
+ cache the result. Multiple `get` calls with the same key will only
+ ever have a single `load` call at the same time.
+
+* `set(key, val)` Seed the cache. This doesn't have to be done, but
+ can be convenient if you know that something will be fetched soon.
+
+* `reset()` Drop all the items in the cache.

0 comments on commit 64ab77a

Please sign in to comment.