Nearly Perpendicular Macaroons

    @vkontakte/graph-cache

    1.1.1 • Public • Published

    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.

    Keywords

    none

    Install

    npm i @vkontakte/graph-cache

    DownloadsWeekly Downloads

    5

    Version

    1.1.1

    License

    MIT

    Unpacked Size

    55.3 kB

    Total Files

    30

    Last publish

    Collaborators

    • k.egor.smirnov
    • nekr
    • fedorov.xyz