recache


recache is a file system cache, it watches recursively a directory tree or a
file content and updates the data on changes, optionally it may provide the
content and the stats for each element stored in the cache.

Comparison with fs.watch and fs.watchFile

recache provides a more reliable cross-platform way to deal with file system
watching, subdirectories are being watched recursively. Under the hood recache
uses fs.watch() and fs.watchFile(), but alleviates the different caveats
that node fs watch methods have by checking fs stats.

Comparison with chokidar

In general chokidar and recache solve the same problems related to
unreliable default node fs watching methods. While chokidar is more focused on
watching for fs changes in multiple locations and calling functions on specific
events, recache is about watching a single directory tree or file and also
reading its paths, stats and content directly using only its API. recache is a
pure JS solution and does not require any code compilation on installation.

Installation

npm i recache

API

recache(path[, options, callback])

- path: [ string ] - path for the root element to be cached
- options: [ object ] - cache configuration options, optional
- filter: [ (path: string, stats: fs.Stats) => boolean ] - filter
cached elements, by default all elements are cached
- persistent: [ boolean ] - enable persistence of file system watchers,
default is false
- store: [ boolean ] - enable file content saving, default is false
- callback: [ (cache: recache.Cache) => void ] - function called when
cache is ready

recache will load directories and files provided in the path argument.
Directories are recursively traversed, their content is loaded into the memory
and watched for changes. Following options can be defined for the cache:
- filter - a function which receives two arguments, the absolute path and file
system stats of traversed directories or files, it has to return a boolean
value to filter the elements should be cached, by default all elements from
the provided path are cached
- persistent - a boolean value to define if the process should continue while
the cache is watching for changes, by default the created cache is not
persistent.
- store - a boolean value to enable storing the files content in the cache, by
default files content is not saved in the cache, note that if this option is
enabled files content should not surpass the available memory

The last argument is a callback function which is executed only once, in the
beginning when all the files and directories are loaded in the memory, the same
functionality can be achieved by listening for the ready event.

$3

.data

Metadata about the cache, it is an empty object which should be used by the
user.

.path

The absolute path of the root element of the cache.

.get([location])

location: string

Get the element from the provided relative location. If no location is provided
then the element from the root location is returned. If the required location
was no found then null is returned. Returned element is object that has the
following readonly properties:
- content - the content of the element, for directories it is an array of
strings which represents the name of the contained files or subdirectories,
for files it is a buffer with the content of the file if it was set to be
stored in the options or null otherwise
- data - the metadata of the element, it is an empty object which may be
filled by the user of the cache
- location - the relative location of the element to the root element of the
cache
- path - the absolute path of the element in the file system
- stats - the file system stats of the element

.has(location)

location: string

Checks if the cache has an element on the provided location.

.list([filter])

filter: (location: string, index: number, list: string[]) => boolean

List all possible readable sources with an optional parameter to filter
elements. If no filter parameter is provided then all readable elements of the
cache are returned as an array of strings.

.start([callback])

callback: (cache: recache.Cache) => void

Starts the cache, this method is called automatically when the cache is created,
it is not necessary to call it manually. It may be called only after the cache
was stopped. This method accepts a callback function which is executed only once
when the cache is started.

.stop()

Stops watching the file system for changes, this method is called automatically
when the cache is destroyed, it is not necessary to call it manually.

.destroy()

Destroy the cached data.

$3

- error - (error: Error) - when an error raised, provides the error as the
callback argument
- ready - (cache: recache.Cache) - when all the files and directories are
loaded for the first time
- update - (cache: recache.Cache) - when one or multiple changes were made
inside the cache
- directory - (element: recache.CacheElement) - when a new directory is added
to the cache, provides the directory object as the callback argument
- file - (element: recache.CacheElement) - when a new file is added to the
cache, provides the file object as the callback argument
- change - (element: recache.CacheElement) - when a directory or a file is
changed, provides the element object as the callback argument
- unlink - (element: recache.CacheElement) - when a directory or a file is
removed, provides the element object as the callback argument
- destroy - when the cache is destroyed, no parameter is provided

Example

``js
const recache = require('recache');

const cache = recache('/path/to/files', {
filter: (path, stats) => { // Filter cache elements

// Filter for hidden files
if (stats.isFile()) {
return /^(?!\.).+$/.test(path);
}

return false;
},
persistent: true, // Make persistent cache
store: true // Enable file content storage
}, (cache) => {
console.log('Cache ready!');

// cache.read(...);
});

cache.on('error', (error) => {
console.log('Something unexpected happened');
console.log(error.stack);
});

cache.on('ready', (cache) => {
console.log('Cache ready!');

// cache.read(...);
});

cache.on('update', (cache) => {
console.log('Cache updated!');

// cache.read(...);
});

cache.on('directory', (directory) => {
console.log('new directory added: "' + directory.location + '"');
});

cache.on('file', (file) => {
console.log('new file added: "' + file.location + '"');
});

cache.on('change', (element) => {
if (element.stats.isDirectory()) {
console.log('directory "' + element.location + '" changed');
} else {
console.log('file "' + element.location + '" changed');
}
});

cache.on('unlink', (element) => {
if (element.stats.isDirectory()) {
console.log('directory "' + element.location + '" removed');
} else {
console.log('file "' + element.location + '" removed');
}
});

cache.on('destroy', () => {
console.log('Cache destroyed!');
});

/ List cache elements /
cache.list();
/*
File
=> ['']

Directory
=> ['', '1.txt', '2.txt', '3.txt', ...]
*/

/ Get cache elements /
cache.get();
/*
File
=> {
content: Buffer<00 01 02 ...> // file content
data: {}, // file metadata
location: '/file', // file location
path: '/path/to/file', // file path
stats: { // file stats
atime: ...
ctime: ...
mtime: ...
...
}
}

Directory
=> {
content: ['1.txt', '2.txt', '3.txt', ...], // directory content
data: {}, // directory metadata
location: '/directory', // directory location
path: '/path/to/directory', // directory path
stats: { // directory stats
atime: ...
ctime: ...
mtime: ...
...
}
}
*/
``