A caching module for streams
A caching module for streams
npm install --save ka-ching
Pipe the result of a request to
google.com and cache it to
When the cache is already populated, the given provider is not called and the cached
resource is piped instead.
var kaChing = require'ka-ching''/path/to/cache/dir';var request = require'request';kaChing'my-cached-resource-id'return request'';pipedestination;
kaChingremove'my-cached-resource-id'// called when the file is removed from disk// this will call the provider againvar uncached = kaChing'my-cached-resource-id';
The first subsequent request for this ID will call the provider
When instanciated with the
useStale option, then it is possible
to get stale resources (when available) with the
var kaChing = '/my/dir' useStale: true ;kaChingstale'cached-resource' provider;kaChingremove'cached-resource';kaChingstale'cached-resource'; // calls the provider but gives you the cached version
stale() has the exact same signature as the
kaChing() function and
does exactly the same thing if
useStale is not set.
This is useful when using invalidation as shown below. If your resource becomes invalid but you still want to reply rapidly, you can use a stale version of it.
You can bypass all caching by instanciating
KaChing with the
var kaChing = '/my/dir' disable: true ;kaChing'my-id'return myReadbleStream;///> always call the provider
provider function is called in the context of an object allowing
the user to specify on which factors the current resource should be
A no longer valid resource is
remove()'d from the cache.
expires(date): you can call this method to specify a date at which the resource
is to be invalidated.
If you provide a string, then a new
Date object will be constructed from it.
kaChing'my-resource'var result = getReadableStreamSomehow;thisexpires'2015-01-01T00:00';return result;;
expires.in(ms): invalidate this resource in
kaChing'my-resource'var result = getReadableStreamSomehow;thisexpiresin5 * 60 * 1000;return result;;
depend(emitter) : makes the cached resource depend on this.
emitter is an object
which emits a
'change' event when the resource should be cleared and has a
Would you be surprised if I told you that cache-depend provides exactly this type of objects?
You can provide a
memoryCache option to the
It will in turn also use an
lru-cache for cached resources.
var kaChing = require'ka-ching''/path/to/cache/dir'memoryCache: true;var request = require'request';kaChing'my-cached-resource-id'return request'';pipedestination;
memoryCache is a number instead of a boolean, then its value is used
as the maximum size (in bytes) for the underlying
My personal (and unpublished) benchmarks have shown that this is seldom useful as your OS is probably already doing it with the files that kaChing reads most often. They have however shown some improvement for the 98-99% percentiles in a HTTP server of roughly 30%.
Tests are written with mocha and coverage is made by istanbul.
- Only works with
text/bufferstreams. If you'd like to cache
objectModestreams, you should handle serialisation/deserialisation yourself
- No intelligence whatsoever as to when to invalidate cached data
- Does not play well with concurrent access to the file system
- Cannot recover from file system after restart
These are not necessarily intended and may be handled in the future
Anyone is welcome to submit issues and pull requests at http://github.com/Floby/node-ka-ching
Copyright (c) 2014 Florent Jaby
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.