TaskGraph

TaskGraph is a task runner for Node.js that facilitates the creation of CLI utilities and build tools. It allows you to define tasks and their dependencies, ensuring that all required tasks are executed in the correct order.

How to use

Installing

npm install @subeeshb/taskgraph

Task

The basic unit of work is a Task. A Task is a distinct action that users of your CLI tool can invoke. To define a Task, create a class that extends the Task class and define the getCommand(), getDescription() and run() methods:

import { Task } from '@subeeshb/taskgraph';

class BuildWebApp extends Task {
  getCommand() {
    return 'build-web';
  }

  getDescription() {
    return 'Builds the web app';
  }

  async run() {
    // Do something here...
  }
}

Params and flags

You can define any required params and optional flags using the getParams() and getFlags() methods. To access the values of a flag or param when the task is being run, call the getParam(name) or getFlag(name) method.

import { Task } from '@subeeshb/taskgraph';

class BuildWebApp extends Task {
  getCommand() {
    return 'build-web';
  }

  getDescription() {
    return 'Builds the web app';
  }

  getFlags() {
    return [
      { name: 'minify', description: 'Whether to minify the source code' },
    ];
  }

  getParams() {
    return ['folder_name'];
  }

  async run() {
    const minify = this.getFlag('minify');
    const folderName = this.getParam('folder_name');

    // Do something here...
  }
}

Dependencies

You can define any pre-requisite tasks using the getDependencies() method. Any params or flags set when invoking the CLI tool will be passed to each task executed as a dependency. You can choose to override the params for a dependency by setting the paramsOverride property.

Note that dependencies are executed in parallel, not in the order they're defined in.

import { Task } from '@subeeshb/taskgraph';

class BuildCSS extends Task {
  // ... Implements the "build-css" command.
}

class BuildJS extends Task {
  // ... Implements the "build-js" command.
}

class BuildWebApp extends Task {
  getCommand() {
    return 'build-web';
  }

  getDescription() {
    return 'Builds the web app';
  }

  getDependencies() {
    return [
      { command: 'build-css', paramsOverride: ['scss'] },
      { command: 'build-js' },
    ];
  }

  getFlags() {
    return [
      { name: 'minify', description: 'Whether to minify the source code' },
    ];
  }

  getParams() {
    return ['folder_name'];
  }

  async run() {
    const minify = this.getFlag('minify');
    const folderName = this.getParam('folder_name');

    // Do something here...
  }
}

Internal tasks

You can create a task extending the InternalTask class to define a non-user-callable task. These tasks cannot be explicitly invoked by the user, but can be referenced as dependencies by other tasks. When extending InternalTask, you do not need to implement the getDescription() method.

Reference

Here's a reference of other useful methods and properties in the Task class:

| Method | Description | | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | getTaskLabel(label: string) | Sets a label to be shown next to the progress spinner identifying the task. If not specified, the task's command will be shown instead. | | setResult(result: RunResult) | Sets the outcome of the task. Set this to either RunResult.Success or RunResult.Failed. | | setProgressText(text: string) | Sets the text to be shown on the progress spinner. Use this to update the progress of the task. |

| Property | Description | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | dependencyExecutionMode | How dependencies should be executed - in parallel (default) or serially one after another. Set this to either ExecutionMode.Parallel (default) or ExecutionMode.Serial | | failRunIfTaskFails | Whether the entire run should terminate if this task ends with a failed result. |

TaskRunner

To create a CLI tool that executes your tasks, use the TaskRunner class. Create an instance of this class, register your tasks, then call the run() method.

const runner = new TaskRunner('Example CLI');

runner.registerTask(BuildWebApp);
runner.registerTask(BuildJS);
runner.registerTask(BuildCSS);

await runner.run();