keepr v1.0.1

Keepr

The simple file caching module for Node.js.
Keepr is handy in those I/O intensive applications where files are read and processed frequently. It caches file content up to a given maximum byte size, while keeping the most frequently used files in memory and purging the least frequently used.

Features

• Caches file content in memory for quick retrieval.
  • Reduces expensive file system I/O calls.
  • Keeps frequently used content readily available.
  • You can set the maximum cache size.
• Keeps the newest, most frequently used files first.
  • Uses a LFU/Oldest First composite algorithm.
  • Retrieve cached contents in any supported encoding or get a safe copy of the buffer contents.
• Safely store file contents in memory
  • Keepr helps prevent heap allocation errors by capping stored file contents to a preset size.
  • If a file is modified or deleted it is uncached automagically.
• 99% Test Coverage

Install

$ npm install keepr --save

Getting Started

var keepr = require('keepr');

// 1st call: file is read and cached.
keepr.get('./some/file.js', function (err, contents) { ... });

// All subsequent calls will return the cached contents.
keepr.get('./some/file.js', function (err, contents) { ... });

// Or wrap the fs.module...
keepr.wrapFS();

// Now fs will use Keepr's cache!
var fs = require('fs');
fs.readFile('./some/file.js', function (err, contents) { ... });

Keepr#get performs async file reads...
Keepr#getSync can be used to perform synchronous file reads (if you feel it's absolutely necessary).

You can also use the aliases: Keepr#read and Keepr#readSync.

fs.readFileSync is also wrapped when you call keepr.wrapFS.

Keepr exports a singleton...

You can require it from any file and the same instance will be returned.
However, if desired, multiple instances of Keepr can be created using the require('keepr').Keepr class.

Contents

1. Install
2. Getting Started
3. Options
   • Size Strings
4. Purging Cache
5. Wrapping The FS Module
6. Other Methods
7. Performance

Options

For most, the default options will suffice, however, you can tweak Keepr with the following options:

var keepr = require('keepr');

// Default settings shown...

keepr.setOptions({
    // The finite maximum size the cache can grow to.
    // If set to < 0, the cache can grow infinitely.
    size: require('v8').getHeapStatistics().total_available_size * 0.75,
    // If true, cache will be invalidated if the file is modified.
    watch: true,
    // Alters the caching algorithm.
    historyFactor: 2,
    // Prints debug messages to the stdout.
    debug: false
});

Keepr#setOptions({Object} options) → {Keepr}

Sets one or more of the following options...

Keepr#getOptions() → {Object}

Returns the current options as an object.

Size Strings

A size string can be used instead of a byte size when setting the maxCacheLimit
A size string must match the following regular expression: /^ *(\d+(?:\.\d+)?) *(b|kb|mb|gb) *$/i. The following strings are valid "size strings" where xxx is a number:

Examples

var keepr = require('keepr');

keepr.setOptions({ size: '5000b' });
keepr.setOptions({ size: '5000kb' });
keepr.setOptions({ size: '200mb' });
keepr.setOptions({ size: '1.5gb' });

Purging Cache

To manually purge the cache call Keepr#purge. However, in most cases, manually purging the cache is unnecessary and should be avoided in favor of performance.

Keepr#purge({...String=} filename) → {Keepr}

// Frees all cache for garbage collection...
keepr.purge();

// You can purge a specific file by passing in a filename.
keepr.purge('./my/file.js');

// ...or multiple files...
keepr.purge('./my/file.js', './my/file2.js');

Wrapping The FS Module

Keepr provides a method to wrap the native Node FS module. This ensures that all calls made to fs.readFile and fs.readFileSync will be cached. Thus, other modules that read from the file system will utilize the Keepr caching system as well.

Keepr#wrapFS() → {Keepr}

var keepr = require('keepr');
    fs    = require('fs');

// Wrap fs.readFile and fs.readFileSync
keepr.wrapFS();

// First call, contents read and cached.
fs.readFile('./my/file.js', function (err, contents) { ... });

// Next call, cached contents returned.
fs.readFile('./my/file.js', function (err, contents) { ... });

// If for any reason you need to un-wrap the file system methods...
keepr.unwrapFS();

If you need to use the vanilla FS methods for a "don't cache" situation after wrapping the fs module, you can use Keepr#noCache or Keepr#noCacheSync

Note, Keepr#wrapFS and Keepr#unwrapFS are available only to the singleton instance returned when required. Newly created instances will not have these methods.

Other Methods

Keepr#noCache()

Always returns the vanilla version of fs.readFile.

Keepr#noCacheSync()

Always returns the vanilla version of fs.readFileSync.

Keepr#dump() → {Object}

Exports a skeleton copy of the the cache content as an object (without the data)

var data = keepr.dump();
// Returns something like:
{
    '/my/file.json:buffer': {
        size: 714,
        source: '/my/file.json',
        called: 0,
        encoding: 'buffer',
        hash: '/my/file.json:buffer'
    },
    '/my/other/file.xml:utf-8': {
        size: 10456,
        source: '/my/other/file.xml',
        called: 1,
        encoding: 'utf-8',
        hash: '/my/other/file:utf-8'
    }
    ...
}

Keepr#isCached({String} filename) → {Boolean}

Returns true if the provided filename exists in the cache, false otherwise.

var isCached = keepr.isCached('./my/file.js'); // -> true or false

Keepr#utiltized() → {Number}

The percentage of the cache that is currently utilized.

var utilized = keepr.utiltized(); // 0 >= x <= 1

Keepr#currentSize() → {Number}

The sum of all cached data in bytes.

var cacheSize = keepr.currentSize(); // 0 >= x <= keepr.getOptions().size;

Keepr#sizeOf({String|Buffer} item) → {Number}

Returns the size of the given argument in bytes.
If the argument isn't a Buffer or string, it will be cast to a string. This is essentially an alias for: Buffer.byteLength.

var sizeOfString = keepr.sizeOf('a string'); // -> 8

Performance

Basically, the test was to read files of various sizes 1, 2, 5, and 20 times in succession, both asynchronously and synchronously.
All tests were performed on a MacBook Pro, 2.8 GHz Intel Core i7, Apple SSD.

The result of each file size is listed below.

Summary

On average, the first file read takes about 30% longer using Keepr compared to the vanilla fs module. However, subsequent reads were much faster using Keepr ranging from 4 to 17,000+ times faster over vanilla fs.

The larger the files, the better Keepr performs.
Async, multiple reads of small files (less than 100kb) are about 5x times faster using Keepr. Larger files can be up to 99.9% faster.

Keepr works better asynchronously.
Keepr outperformed vanilla fs for all file sizes when reading async. For synchronous file reads, fs was faster for files smaller than 50kb. With files larger than 50kb sync, Keepr outperformed... and especially for files larger than 1mb.

The performance test files can be found in the performance directory of this repo.

The Bottom Line

So long as you have heap to spare and files to read, Keepr's a good choice.

Async

The files were read asynchronously using Keepr's fs.readFile wrapper.

0.1KB File

5/16/2016 • Darwin • 17.18GB Memory • 8 CPUS

1.0KB File

5/16/2016 • Darwin • 17.18GB Memory • 8 CPUS

5.0KB File

5/16/2016 • Darwin • 17.18GB Memory • 8 CPUS

50.0KB File

5/16/2016 • Darwin • 17.18GB Memory • 8 CPUS

100.0KB File

5/16/2016 • Darwin • 17.18GB Memory • 8 CPUS

500.4KB File

5/16/2016 • Darwin • 17.18GB Memory • 8 CPUS

1.0MB File

5/16/2016 • Darwin • 17.18GB Memory • 8 CPUS

5.0MB File

5/16/2016 • Darwin • 17.18GB Memory • 8 CPUS

50.0MB File

5/16/2016 • Darwin • 17.18GB Memory • 8 CPUS

100.0MB File

5/16/2016 • Darwin • 17.18GB Memory • 8 CPUS

Sync

The files were read synchronously using Keepr's fs.readFileSync wrapper.
You probably shouldn't use Keepr if you're dealing with a lot of files less than 50kb and reading them synchronously.

0.1KB File

5/16/2016 • Darwin • 17.18GB Memory • 8 CPUS

1.0KB File

5/16/2016 • Darwin • 17.18GB Memory • 8 CPUS

5.0KB File

5/16/2016 • Darwin • 17.18GB Memory • 8 CPUS

50.0KB File

5/16/2016 • Darwin • 17.18GB Memory • 8 CPUS

100.0KB File

5/16/2016 • Darwin • 17.18GB Memory • 8 CPUS

500.4KB File

5/16/2016 • Darwin • 17.18GB Memory • 8 CPUS

1.0MB File

5/16/2016 • Darwin • 17.18GB Memory • 8 CPUS

5.0MB File

5/16/2016 • Darwin • 17.18GB Memory • 8 CPUS

50.0MB File

5/16/2016 • Darwin • 17.18GB Memory • 8 CPUS

100.0MB File

5/16/2016 • Darwin • 17.18GB Memory • 8 CPUS