Nightly Patch Machine

    @fang/core
    TypeScript icon, indicating that this package has built-in type declarations

    0.2.0 • Public • Published

    @fang/core

    Task runner for Node.JS

    npm NPM Build Status codecov Maintainability Libraries.io dependency status for latest release Known Vulnerabilities

    Summary

    About

    I created this library to help me run faster builds using all my available CPUs. I am a long time Gulp user, and when I saw the gulp.parallel utility, I expected it would allow parallelizing tasks, but it was just using a single CPU to run tasks asynchronously.

    This library is not meant for "small" bundles as the cost of creating forks can be actually worse for build that last less than a few hundreds of milliseconds. For the rest of the developers that have relatively medium to big bundles, Fang might be able to reduce the time spent bundling your project.

    With Fang, each "tasks" is meant to be run in a CPU core. Which means you can leverage building servers with an high amount of CPU cores (like AWS instances for example). Whenever you have more tasks than available CPU cores, the tasks are put in queues until a CPU core frees itself. All methods in a task are run sequentially, so you might want to think differently than you would in Gulp, but this library is quite inspired by this package.

    Features

    Runs tasks in parallel using all the available cores.

    Examples

    1. Run Fang using Node via a script.js

    Create a script wherever you want. For example, at the root of your folder, create a script.js, and add this basic task.

    const { run } = require("@fang/core");
    const save = require("@fang/save");
    
    const robots = {
      name: "robots.txt",
      input: "src/robots.txt",
      tasks: [
        save({
          folder: "dist",
        }),
      ],
    };
    
    const main = async () => {
      await run([robots]);
    };
    
    main();

    Then, install the required dependencies using your favorite package manager. For example, using NPM.

    npm install --save-dev @fang/core @fang/save

    Finally, run your task using node in the command line.

    node script.js

    You should see something like this in your console.

    $ node script.js
    fang: start
    8 CPUs core(s)
    1 tasks to run
    robots.txt: start
    robots.txt: 10.228ms
    fang: 1.223s
    

    Create your Fang plugin

    This tutorial uses Typescript. If you do not feel comfortable with it setting up the required tool for building Typescript files, jump to the end of this section where you can grab a starter project.

    Creating a plugin is very straight forward. There is only a couple of things to know, and you are ready to go!

    • You should export a function
    • It should take in parameter a list of files (more on what is a file below)
    • It should return a function that returns a list of files, or a promise that resolves with a list of files

    And that's it! Now that you have this in mind, let's get started from scratch. If you are lazy, you can jump to the end of this section, where a fang-plugin-starter is ready to be cloned and tweaked.

    1. Install the required dependencies
    yarn add --dev @fang/core
    1. Add fang as a peer dependency in your package.json
    // package.json
    {
      "peerDependencies": {
        "@fang/core": "0.*"
      }
    }

    Use the available version of your choice.

    1. Create your source file with this example
    import { IFile } from "@fang/core";
    
    interface IOptions {
      // to be completed as you need
    }
    
    // src/index.ts
    export default (options: IOptions) => (files: Array<IFile>): Array<IFile> => {
      for (const [index, file] of files.entries()) {
        // do something with file...
        files[index] = file;
      }
    
      return files;
    };

    See IFile for a detail of what you can do with this variable.

    1. Build your project

    I will not cover this section, as you can use whatever you need: Rollup, Gulp, ...

    1. Add your library to the main file in package.json
    {
      "main": "lib/index.js"
    }
    1. Add a "fang-plugin" keyword to your package.json

    This is for the future, where this doc will be hosted in his own website, and I will be able to automatically pull new published packages with this keyword on the plugin section of the documentation.

    {
      "keywords": ["fang-plugin", "..."]
    }
    1. Profit

    That's it! Now others folks can use your package, your task, your plugin, ... whatever :)

    In the future, this section will contain a list of core plugins to help you get some inspirations.

    If you want to get started fast, or you don't want to mess around with installing the required package to transpile, build, test, ... you can clone the fang starter plugin to get started! All the doc is available at https://github.com/khalyomede/fang-starter-plugin.

    Happy coding!

    API

    fang.run

    Runs the tasks in paralell using all the available CPUs.

    const run = async (tasks: Array<ITask>): Promise<void>;

    IFile

    Represents a file.

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

    Credits

    Logo from an original icon by tulpahn from the Noun Project.

    Install

    npm i @fang/core

    DownloadsWeekly Downloads

    0

    Version

    0.2.0

    License

    MIT

    Unpacked Size

    27.4 kB

    Total Files

    13

    Last publish

    Collaborators

    • khalyomede