@khalyomede/fang v0.2.0

Fang

Parallelized task runner. Inspired from Gulp.js

Summary

• Installation
• Usage
• Official plugins
• Community plugins
• Fang API
• CLI-API

Installation

With npm

npm install --global @khalyomede/fang@0.*

With yarn

yarn global add @khalyomede/fang@0.*

Usage

• Compressing your assets
• Restrict the number of core to use
• Moving the fang task file in another place
• Create your fang plugin

Compressing your assets

In this example, we will compress (e.g. uglifying) our HTML, Javascript and CSS files.

1. Create a fang.js file on your root directory.
2. Add your tasks on your fang file.

fang.js

const fang = require('fang');
const htmlMinifier = require('fang-html-minifier');
const uglify = require('fang-uglify-es');
const cleanCss = require('fang-clean-css');

const html = () => fang.from('src/**/*.html')
  .do(htmlMinifier())
  .save('dist');

const css = () => fang.from('src/css/**/*.css')
  .do(cleanCss())
  .save('dist/css');

const js = () => fang.from('src/js/**/*.js')
  .do(uglify())
  .save('dist/js');

const build = [html, js, css];

export.modules = { build }

3. On your package.json, create a shortcut for your build command.

package.json

{
  ...,
  "scripts": {
    "build": "fang build"
  }
}

4. On your root directory, run the following command.

npm run build

Restrict the number of core to use

In this example, you will see how you can reduce the number of core used by fang, with the --max-core option. By default, fang will use the maximum of core available.

fang --max-core 2 build

Moving the fang task file in another place

in progress

Create your fang plugin

In this example, you will be able to use a vendor library like sass, or pug to make it support fang.

1. Create a project and initialize it with git and npm (or yarn).
2. In your main file (could be index.js, or main.js), enter this starter code.

lib/main.js

const fangBabel = options => fang => {
  fang.files.map(file => {
    // your logic here

    return file;
  });

  return fang;
};

module.exports = fangBabel;

3. Add your logic, in our case we will support babel.

lib/main.js

const babel = require('@babel/core');

const fangBabel = options => fang => {
  fang.files.map(file => {
    const transpiled = babel.transformSync(file.content.toString(), options).code;

    file.content = Buffer.from(transpiled);

    return file;
  });

  return fang;
};

module.exports = fangBabel;

As you can see, the files are stored in a form of a Buffer. So you will need to use a .toString() to get back the raw content, and use Buffer.from(string) to put it back on the file.content.

You are free to do whatever process you need, since you stick with this architecture.

4. Publish, and use it.

fang.js

const fang = require('fang');
const babel = require('fang-babel');

const js = () => fang.from('src/js/**/*.js')
  .do(babel())
  .save('dist/js');

const build = [js];

export.modules = { build };

fang build

Official plugins

• pug

Community plugins

None.

Fang API

• properties
  • baseDirectory
  • files
  • options
• methods
  • from
  • do
  • save
• types
  • File

baseDirectory

Contains the base directory for each files catched by the glob. The glob is the path you specified when using Fang.from().

type string

Fang.baseDirectory: string;

files

Contains the files passed during the task process.

type Array<File>

Fang.files: array<object>;
Fang.files[0].path: string;
Fang.files[0].content: Buffer;

options

The options specified on the command line.

Fang.options.debug: boolean; // dsplays additional information on console or not.
Fang.options.maxCore: number; // The number of core to use.
Fang.options.tasksPath: string; // The path to the fang tasks configuration file.
Fang.options.taskName: string; // The name of the task being ran.

type object

from

Set the files to use by the processes. The path supports globs.

Fang.from(path: string): Fang

variables

• path: string - The glob to scope the desired files.

throws

Nothing.

do

Perform a task of the files.

Fang.do(callable: Function): Fang

variables

• callable: Function - The function that will transform the files contents.

throws

Nothing.

save

Save all the files to their respective paths.

Fang.save(): void

variables

None.

throws

Nothing.

File

Represents a file, its path and its content.

type object

interface File {
    path: string;
    content: Buffer;
}

CLI API

• arguments
  • task
• options
  • --debug
  • --list
  • --max-core

task

type string

The task name. It corresponds to one of the variables that you exported in your task file.

For example, if your task file contains:

// ...

module.exports = { build, img };

It means you have access to 2 tasks: build and img.

debug

The plugins that implement well this option will display more information on console.

list

Get a list of runnable tasks.

fang --list
fang -l

max-core

type integer

The number of core to use for the task. By default, fang will use as much cores as possible (e.g. the maximum).

Fang will perform one sub task per cores. For example, if your computer dispose of 8 cores, and you are running a task that contains 4 sub tasks, only 4 cores will be used, one core for each tasK.

However, if your task is composed of 12 sub tasks, only 8 tasks can be ran simultaneously, and the 4 remaining tasks will "wait their turn" until one sub task finishes its process and frees a core, and so on until no more sub task need to be processed (the end of the task).

fang --max-core 4 build
fang -c 4 build