@vkontakte/graph-cache
v1.1.1
Published
This library provides easy way to build and maintain persistent dependency graph for any type of files/languages. It provides a high-level set of operations on graph to fulfill common use cases, when working with dependency graphs.
Downloads
2
Readme
graph-cache
This library provides easy way to build and maintain persistent dependency graph for any type of files/languages. It provides a high-level set of operations on graph to fulfill common use cases, when working with dependency graphs.
graph-cache
is language agnostic, you can provide a parser for any type of files (JS, LESS, SASS, etc).
This library is built on top of the graphlib npm package.
Use cases
The simplest use case is if you want to build persistent cache for some language that supports importing files from other files.
The reason I created it was that I needed to build persistent cache for LESS
language.
Project I was working on consisted of hundreds of files, and I wanted to recompile only those that changed while deploying code.
Installation
npm install --save graph-cache
Usage
const createGraphCache = require('graph-cache');
const gcache = createGraphCache(parser, sign, {
persistence: false
});
gcache.then((cache) => cache.checkFile(file, name));
API
constructor
const createGraphCache = require('graph-cache');
const gcache = createGraphCache(parser, sign, opts);
- parser — this is a function that takes a
sign function
, fileBuffer
and file name.
parser(sign, file, filename)
Parser
function should return Promise
that resolves into full dependency graph of given file as an instance of graphlib
graph. Example of parser function is graph-cache-less.
- sign — sign function, which takes
Buffer
and returns string (hash), that identifies this file, i.e. md5. - opts — options object
{
persistence: 'test.txt', // string, file name where graph will be stored
g: new Graph({ directed: true }), // initial graph, ignored if persistence is set
targetFs: fs, // if you want to store graph in memory for some reasons
cacheVersion: false, // this is the version, that should match the version stored in cache file,
//if differs, cache will be discarded
}
Returns Promise
, that will resolve into Cache
object.
Cache object
It container cache API.
checkFile(file, filename)
This method allows tou to check whether this file or its deps has changed.
- file —
Buffer
with file contents - filename — file name
Returns Promise
that will resolve into false if file or its dependencies has changed, otherwise it will be resolved into true.
rebuildFromFile(file, filename)
This method allows you to update your cache with file and its dependency subgraph and merge it to existing graph.
Changes won't take effect until you call swapGraphs
.
- file —
Buffer
with file contents - filename — file name
getChangedLeafs(file, filename)
This method allows you to obtain all leaf-files, that depend on the given file.
- file —
Buffer
with file contents - filename — file name
Returns Promise
that will be resolved int list with leaf-file names.
saveGraph()
This method allows you to save graph to disk or target fs.
Returns Promise
when saving is done.
swapGraphs()
When you call rebuildFromFile
resulting graph is not yet used, until you call this method.
This is a way of committing
changes to your dependency graph.
Returns null
visualise(dest)
This method will create HTML-file with your dependency graph visualisation.
- dest — destination for saving file with visualisation
Returns Promise
Testing
This library is tested using Mocha
and Chai
. You can run test suit with npm test
.
You can run npm run test-watch
to rerun tests on file updates.
Contributing
This library is written using ES6 code.
Before pushing run npm run build
to generate ES5 compatible js code.
Issues and PR's are welcomed here.