emitty

Determine the inheritance of template and style files.

What is it? or what is problem?

Most HTML and CSS preprocessors use a synchronous API to access file system and don't use cache for already read files. It degrades performance and increases the time required to compile the code.

Also, when your project is very large and has a large number of dependencies between blocks (e.g. many mixins) — compiles all files of a project may take seconds or even minutes. This is unacceptable if you are working with a "watch" mode.

Solution?

This module allows you to compile only those files that depend on the changed file and require compilation.

For example, if you have the following files:

• templates/
  • a.pug — depends on b.pug
  • b.pug
  • c.pug

If you change the c.pug file, then will be compiled only it. If you change the b.pug file, then will be compiled a.pug file.

Install

$ npm i -D emitty

Why?

• See «What is it? or what is problem?» section.
• This solution does not use redundant modules such as Pug parser and Glob.
• Sufficiently flexible.

Usage

const emitty = require('emitty').setup('templates', 'jade');

emitty.scan().then(() => {
  console.log(emitty.storage());
  // {
  //   'a.pug': {
  //     dependencies: ['components/b.pug'],
  //     ctime: new Date()
  //   },
  //   'components/b.pug': {
  //     dependencies: [],
  //     ctime: new Date()
  //   }
  // }
  }
});

Setup

setup(directory, language, [options])

Creates API for emitty.

API

const emitty = require('emitty').setup('templates', 'pug');

storage()

Returns a snapshot of the Storage.

console.log(emitty.storage());
// {
//   'a.pug': {
//     dependencies: ['components/b.pug'],
//     ctime: new Date()
//   },
//   'components/b.pug': {
//     dependencies: [],
//     ctime: new Date()
//   }
// }

keys()

Returns the keys of the Storage.

console.log(emitty.keys());
// ['a.pug', 'components/b.pug']

load(snapshot)

Clears the Storage and loads the new data.

emitty.load({
  'c.pug': {
    dependencies: ['nope.pug'],
    ctime: new Date()
  }
});
// console.log(emitty.keys());
// ['c.pug']

scan([filepath], [stats]) => Promise

Scans directory and updates the Storage. If you specify a filepath, then only that file will be scanned. Also you can specify stats of file (to avoid doing unnecessary actions inside emitty).

emitty.scan().then(() => {
  // console.log(emitty.keys());
  // ['a.pug', 'b.pug']
});

resolver

getDependencies(filepath)

Returns all files that depends on the specified file.

emitty.scan().then(() => {
  console.log(emitty.getDependencies('a.pug'));
  // ['components/b.pug']
});

checkDependencies(a, b)

Returns True if A depends on B.

emitty.scan().then(() => {
  console.log(emitty.getDependencies('a.pug'));
  // ['components/b.pug']
  console.log(emitty.checkDependencies('a.pug', 'components/b.pug'));
  // true
  console.log(emitty.checkDependencies('a.pug', 'nope.pug'));
  // false
});

stream([filepath], [stats]) => TransformStream

Is scan method, but for Stream and combines scan + resolver.

Scans directory or file and updates the Storage. Then, if file in stream depends on the changed file — pass it further. Else skip it.

Warning

If you do not specify the filepath to the changed file, it will be the last file that has changed since the last scan.

const stream = emitty.stream();
stream.on('end', () => {
  // console.log(emitty.keys());
  // ['a.pug', 'b.pug']
});

stream.end();

filter(filepath) => TransformStream

Passes continue to stream only those files that need to be compiled.

Options

Language

Built-in configs

The emitty contains built-in configs for the following instruments:

• jade — now it's Pug
• pug
• nunjucks
• posthtml — with posthtml-include and/or posthtml-extend plugin.
• sugarml — with posthtml-include and/or posthtml-extend plugin.
• less
• stylus — indent based syntax
• sass
• scss

You can use them when you configure emitty:

const emitty = require('emitty');
const emittyJade = emitty.setup('templates', 'pug');
const emittySugarml = emitty.setup('templates', 'sugarml');
// ...

Your own config

Instead of use built-in config you can specify your own config.

For example, config for Slm:

const emitty = require('emitty').setup('templates', {
  extensions: ['.slm'],
  matcher: /=?=\s(?:partial|extend)\(['"]([^'"]+)['"].*?\)/,
  comments: {
    start: '/',
    end: ''
  },
  indentBased: true
});

How to use with Gulp

• Minimal
• Basic
• Advanced
• Performance (recommended)
• Ninja

Changelog

See the Releases section of our GitHub project for changelogs for each release version.

License

This software is released under the terms of the MIT license.