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?
Other invalidation mechanisms may be provided in the future
Resources can be proactively refreshed when their cached version expires or is invalidated.
You can provide
reactive option on instanciation. This will automatically
call the resource provider when the cache becomes invalid.
var kaChing = require'ka-ching''/path/to/cache/dir' reactive: true;kaChing'some-resource'thisexpiresin2000;return requestget"";;kaChingon'remove:some-resource'// the provider has already been called for caching;
This is compatible with stale resources as well.
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 an improvement of roughly 30% for the 98-99% percentiles of requests in a HTTP server.
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
- 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) 2015 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.