@vkontakte/graph-cache

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, file Buffer 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.