CachedFs

Wrap node.js' fs module in a cached read-only version that exposes the same interface. Can speed up things if you're reading the same files and directories multiple times, and things don't change on disc.

Doesn't expose the functions that write to disc, so no cache invalidation is ever performed internally.

var CachedFs = require('cachedfs'),
    fs = new CachedFs();
 
fs.readFile('foo.txt', function (err, contents) {
    fs.readFile('foo.txt', function (err, contentsAgain) {
        // Much faster this time!
    });
});

You can also patch the built-in fs module or a compatible one in-place (this should be considered a bit experimental):

require('cachedfs').patchInPlace();
 
require('fs').readFile('foo.txt', function (err, contents) {
    // Yup, this will be cached!
});

The CachedFs constructor and CachedFs.patchInPlace support an options object with the following properties:

• fs: The fs module to wrap. Defaults to require('fs'), but could also be used with something like gitfakefs.

• cache: An existing node-lru instance to use for the cached data. The default is to create a new one (exposed via cachedFs.cache).

• cacheKeyPrefix: Defaults to a session-unique number so that multiple CachedFs instances can be backed by the same lru-cache instance. You can override this to explicitly force two CachedFs instances to share the same cached data for some reason.

• skipUnimplemented: Don't add "not implemented" stubs that throw exceptions. Mostly useful when patching an existing fs implementation in-place. Defaults to false.

• debug: Log when methods are called. Defaults to false.

• context: The context to call the wrapped fs functions in. (Probably not useful except internally). Defaults to the wrapped fs module.

• max, maxAge, length, dispose, stale : Passed to the lru-cache constructor unless the cache option is specified. See the lru-cache README for details.

If you don't specify a length option, it will default to a function that approximates the number of bytes occupied by the cached values. That means you can use the max option to set an upper limit on the memory usage in bytes:

var CachedFs = require('cachedfs'),
    cachedFs = new CachedFs({max: 104857600});

or when patching the built-in fs module in-place:

var CachedFs = require('cachedfs');
 
CachedFs.patchInPlace({max: 104857600});

An instantiated CachedFs has the following properties:

• cacheKeyPrefix: The string prefix of all keys stored in the cache.

• cache: The lru-cache instance. Useful for checking cache.length, cache.itemCount, or purging all cached items via cache.reset(), etc. See the lru-cache README.

• argumentsStringifier: Function that turns an array of arguments for a fs method into a cache key. Mostly exposed so it doesn't have to be duplicated in the test suite.

Supported methods:

• stat, statSync
• lstat, lstatSync
• readlink, readlinkSync
• realpath, realpathSync
• readdir, readdirSync
• readFile, readFileSync
• exists, existsSync
• createReadStream

Bonus features:

• File names are absolutified and normalized before being used in a cache key, so you'll get cache hits even if you refer to the same file with different syntaxes, eg. a relative and an absolute path.
• Errors are also cached.
• Even if the underlying fs implementation doesn't support a given sync method, it will produce the correct result if the CachedFs instance happens to have a cached copy of the async method's result.

Installation

Make sure you have node.js and npm installed, then run:

npm install cachedfs

License

3-clause BSD license -- see the LICENSE file for details.