# task-graph-processor

> A reference task-runner for the [watch-task-protocol](../watch-task-protocol/readme.md) including reference implementations for popular build tools like `TypeScript`.

Latest version **0.4.0** (published 2023-11-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install task-graph-processor
pnpm add task-graph-processor
yarn add task-graph-processor
bun add task-graph-processor
```

Provides the command `tgp`.

## Health

**Score 20/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.4.0 |
| Published | 2023-11-23 |
| First published | 2023-01-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 11 |
| Unpacked size | 27.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Patrik Stutz |
| Maintainers | vancoding, patrik.stutz |

## Links

- npm: https://www.npmjs.com/package/task-graph-processor
- npm.io page: https://npm.io/package/task-graph-processor

## Dependencies (11)

- [zod](https://npm.io/package/zod.md) ^3.19.1
- [chalk](https://npm.io/package/chalk.md) ^5.2.0
- [cmd-ts](https://npm.io/package/cmd-ts.md) ^0.11.0
- [remeda](https://npm.io/package/remeda.md) ^1.3.0
- [split2](https://npm.io/package/split2.md) ^4.1.0
- [chokidar](https://npm.io/package/chokidar.md) ^3.5.3
- [commondir](https://npm.io/package/commondir.md) ^1.0.1
- [npm-run-path](https://npm.io/package/npm-run-path.md) ^5.1.0
- [typed-signals](https://npm.io/package/typed-signals.md) ^2.5.0
- [distinct-colors](https://npm.io/package/distinct-colors.md) ^3.0.0
- [watch-task-protocol](https://npm.io/package/watch-task-protocol.md) 0.3.0

## Recent versions

- 0.4.0 (latest) — 2023-11-23
- 0.3.1 — 2023-02-23
- 0.3.0 — 2023-02-23
- 0.2.3 — 2023-02-15
- 0.2.2 — 2023-02-09
- 0.2.1 — 2023-02-08
- 0.1.0 — 2023-01-30

## README

# task-graph-processor

A reference task-runner for the [watch-task-protocol](../watch-task-protocol/readme.md) including reference implementations for popular build tools like `TypeScript`.

## taskfiles

Your tasks are declared in so-called "taskfiles". A taskfile can contain multiple tasks and you can also have as many taskfiles as you wish.
Tasks can depend on tasks from other taskfiles.

Example:

```js
// frontend/taskfile.json
{
  "build": {
    "command": "tsc",
    "dependencies": ["../lib:build"]
  }
}

// backend/taskfile.json
{
  "build": {
    "command": "tsc",
    "dependencies": ["../lib:build"]
  }
}

// lib/taskfile.json
{
  "build": {
    "command": "tsc"
  }
}
```

Running `tgp build:frontend build:backend` will then first build the project `lib` and then the projects `frontend` and `backend` in parallel.
If the task `build` of `lib` fails, then it won't attempt building `frontend` or `backend`.

## watch mode

The whole point of this project is correctly supporting & orchestrating the watch mode of build tools. If all your build tools support the [watch-task-protocol](../watch-task-protocol/readme.md) you can just run `tgp taskname --watch` and it will automatically re-run your task-graph correctly.

If you have tools that don't support the [watch-task-protocol](../watch-task-protocol/readme.md) you have the following options:

### let the task runner watch files

Instead of starting your build tool in watch-mode, you can tell the task-runner which files to watch, and to restart the task when changes are detected. For this, just specify your glob patterns in an array to the `watch` property of the task.

An example taskfile could then look like this:

```js
{
  "build": {
    "command": "tsc",
    "watch": ["src/**/*.ts"]
  }
}
```

### create a wrapper

If the tool also has a library-interface, we may be able to build a wrapper around it that does support the protocol. Until we get a broad adoption of the protocol, we welcome such wrappers in this repository. You can find them in the [build-tools](../build-tools/) directory. Currently the following build tools are supported:

- TypeScript

### request support for a restart-trigger

You might be able to convince the authors of the build-tool to give us some way to tell it to only re-run a task if it gets a message from the outside of the process (for example a STDIN-input or a http-request). Detecting a finished or failed task can usually be achieved by parsing the STDOUT of the process and usually does not require a change.

If the tool finally supports the features we need, although not in a protocol-conformant way, we can tell the `task-graph-processor` how to handle it. This can be done through the following task properties:

#### **triggerStart**:

An object of the following stucture:

```js
{ "stdin": "START_MESSAGE"}
```

where `START_MESSAGE` is the text that should be written to STDIN of the process to trigger the restart. In the future, we might support different channels than STDIN, like for example HTTP.

When not specified, it defaults to the [watch-task-protocol](../watch-task-protocol/readme.md):

```js
{ "stdin": "WATCH_TASK_PROTOCOL:START" }
```

#### **detectEnd**:

An object of the following structure:

```js
{ "stdout": {
  "success": "SUCCESS_MESSAGE",
  "failure": "FAILURE_MESSAGE"
}}
```

In this configuration, the task is considered successful as soon as `SUCCESS_MESSAGE` is received via STDOUT and it is considered as failed when `FAILURE_MESSAGE` is received. In the future, we might support different channels than STDOUT.

When not specified, it defaults to the [watch-task-protocol](../watch-task-protocol/readme.md):

```js
{ "stdout": {
  "success": "WATCH_TASK_PROTOCOL:SUCCEEDED",
  "failure": "WATCH_TASK_PROTOCOL:FAILED"
}}
```

#### **detectChanges**:

An object of the following structure:

```js
{ "stdout": "CHANGE_MESSAGE" }
```

In this configuration, the the task runner will schedula a re-run as soon as `CHANGE_MESSAGE` is received via STDOUT. In the future, we might support different channels than STDOUT.

When not specified, it defaults to the [watch-task-protocol](../watch-task-protocol/readme.md):

```js
{ "stdout": "WATCH_TASK_PROTOCOL:DETECTED_CHANGES" }
```

---
_Source: https://npm.io/package/task-graph-processor · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._