Tasuku

Minimal task runner for Node.js

CLI
privatenumber/tasukutasuku

README


The minimal task runner for Node.js


Features

- Task list with dynamic states
- Parallel & nestable tasks
- Unopinionated
- Type-safe

→ Try it out online

Support this project by starring and sharing it. [Follow me](https://github.com/privatenumber) to see what other cool projects I'm working on.

Install

  1. ```sh
  2. npm i tasuku
  3. ```

About

タスク (Tasuku) is a minimal task runner for Node.js. You can use it to label any task/function so that its loading, success, and error states are rendered in the terminal.

For example, here's a simple script that copies a file from path A to B.

  1. ```ts
  2. import { copyFile } from 'fs/promises'
  3. import task from 'tasuku'

  5. task('Copying file from path A to B', async ({ setTitle }) => {
  6.     await copyFile('/path/A', '/path/B')

  8.     setTitle('Successfully copied file from path A to B!')
  9. })
  10. ```

Running the script will look like this in the terminal:


Usage

Task list

Call task(taskTitle, taskFunction) to start a task and display it in a task list in the terminal.

  1. ```ts
  2. import task from 'tasuku'

  4. task('Task 1', async () => {
  5.     await someAsyncTask()
  6. })

  8. task('Task 2', async () => {
  9.     await someAsyncTask()
  10. })

  12. task('Task 3', async () => {
  13.     await someAsyncTask()
  14. })
  15. ```


Task states

- ◽️ Pending The task is queued and has not started
- 🔅 Loading The task is running
- ⚠️ Warning The task completed with a warning
- ❌ Error The task exited with an error
- ✅ Success The task completed without error


Unopinionated

You can call task() from anywhere. There are no requirements. It is designed to be as unopinionated as possible not to interfere with your code.

The tasks will be displayed in the terminal in a consolidated list.

You can change the title of the task by calling setTitle().
  1. ```ts
  2. import task from 'tasuku'

  4. task('Task 1', async () => {
  5.     await someAsyncTask()
  6. })

  8. // ...

  10. someOtherCode()

  12. // ...

  14. task('Task 2', async ({ setTitle }) => {
  15.     await someAsyncTask()

  17.     setTitle('Task 2 complete')
  18. })
  19. ```


Task return values

The return value of a task will be stored in the output .result property.

If using TypeScript, the type of .result will be inferred from the task function.

  1. ```ts
  2. const myTask = await task('Task 2', async () => {
  3.     await someAsyncTask()

  5.     return 'Success'
  6. })

  8. console.log(myTask.result) // 'Success'
  9. ```

Nesting tasks

Tasks can be nested indefinitely. Nested tasks will be stacked hierarchically in the task list.
  1. ```ts
  2. await task('Do task', async ({ task }) => {
  3.     await someAsyncTask()

  5.     await task('Do another task', async ({ task }) => {
  6.         await someAsyncTask()

  8.         await task('And another', async () => {
  9.             await someAsyncTask()
  10.         })
  11.     })
  12. })
  13. ```


Collapsing nested tasks

Call .clear() on the returned task API to collapse the nested task.
  1. ```ts
  2. await task('Do task', async ({ task }) => {
  3.     await someAsyncTask()

  5.     const nestedTask = await task('Do another task', async ({ task }) => {
  6.         await someAsyncTask()
  7.     })

  9.     nestedTask.clear()
  10. })
  11. ```


Grouped tasks

Tasks can be grouped with task.group(). Pass in a function that returns an array of tasks to run them sequentially.

This is useful for displaying a queue of tasks that have yet to run.

  1. ```ts
  2. const groupedTasks = await task.group(task => [
  3.     task('Task 1', async () => {
  4.         await someAsyncTask()

  6.         return 'one'
  7.     }),

  9.     task('Waiting for Task 1', async ({ setTitle }) => {
  10.         setTitle('Task 2 running...')

  12.         await someAsyncTask()

  14.         setTitle('Task 2 complete')

  16.         return 'two'
  17.     })

  19.     // ...
  20. ])

  22. console.log(groupedTasks) // [{ result: 'one' }, { result: 'two' }]
  23. ```


Running tasks in parallel

You can run tasks in parallel by passing in { concurrency: n } as the second argument in task.group().

  1. ```ts
  2. const api = await task.group(task => [
  3.     task(
  4.         'Task 1',
  5.         async () => await someAsyncTask()
  6.     ),

  8.     task(
  9.         'Task 2',
  10.         async () => await someAsyncTask()
  11.     )

  13.     // ...
  14. ], {
  15.     concurrency: 2 // Number of tasks to run at a time
  16. })

  18. api.clear() // Clear output
  19. ```


Alternatively, you can also use the native Promise.all() if you prefer. The advantage of using task.group() is that you can limit concurrency, displays queued tasks as pending, and it returns an API to easily clear the results.

  1. ```ts
  2. // No API
  3. await Promise.all([
  4.     task(
  5.         'Task 1',
  6.         async () => await someAsyncTask()
  7.     ),

  9.     task(
  10.         'Task 2',
  11.         async () => await someAsyncTask()
  12.     )

  14.     // ...
  15. ])
  16. ```

API


task(taskTitle, taskFunction)


Returns a Promise that resolves with object:
  1. ```ts
  2. type TaskAPI = {
  3.     // Result from taskFunction
  4.     result: any

  6.     // State of the task
  7.     state: 'error' | 'warning' | 'success'

  9.     // Invoke to clear the results from the terminal
  10.     clear: () => void
  11. }
  12. ```

taskTitle

Type: string

Required: true

The name of the task displayed.

taskFunction

Type:
  1. ```ts
  2. type TaskFunction = (taskInnerApi: {
  3.     task: createTask
  4.     setTitle(title: string): void
  5.     setStatus(status?: string): void
  6.     setOutput(output: string | { message: string }): void
  7.     setWarning(warning: Error | string): void
  8.     setError(error: Error | string): void
  9. }) => Promise<any>
  10. ```

Required: true

The task function. The return value will be stored in the .result property of the task() output object.


task

A task function to use for nesting.

setTitle()

Call with a string to change the task title.

setStatus()

Call with a string to set the status of the task. See image below.

setOutput()

Call with a string to set the output of the task. See image below.

setWarning()

Call with a string or Error instance to put the task in a warning state.

setError()

Call with a string or Error instance to put the task in an error state. Tasks automatically go into an error state when it catches an error in the task.



task.group(createTaskFunctions, options)

Returns a Promise that resolves with object:
  1. ```ts
  2. // The results from the taskFunctions
  3. type TaskGroupAPI = {
  4.     // Result from taskFunction
  5.     result: any

  7.     // State of the task
  8.     state: 'error' | 'warning' | 'success'

  10.     // Invoke to clear the task result
  11.     clear: () => void
  12. }[] & {

  14.     // Invoke to clear ALL results
  15.     clear: () => void
  16. }
  17. ```

createTaskFunctions

Type: (task) => Task[]

Required: true

A function that returns all the tasks you want to group in an array.

options


Directly passed into [p-map](https://github.com/sindresorhus/p-map).

concurrency
Type: number (Integer)

Default: 1

Number of tasks to run at a time.

stopOnError
Type: boolean

Default: true

When set to false, instead of stopping when a task fails, it will wait for all the tasks to finish and then reject with an aggregated error containing all the errors from the rejected promises.

FAQ


What does "Tasuku" mean?

_Tasuku_  or タスク is the phonetic Japanese pronounciation of the word "task".


Why did you make this?


For writing scripts or CLI tools. _Tasuku_ is a great way to convey the state of the tasks that are running in your script without being imposing about the way you write your code.

Major shoutout to listr + listr2 for being the motivation and visual inspiration for _Tasuku_, and for being my go-to task runner for a long time. I made _Tasuku_ because I eventually found that they were too structured and declarative for my needs.

Big thanks to ink for doing all the heavy lifting for rendering interfaces in the terminal. Implementing a dynamic task list that doesn't interfere withconsole.logs() wouldn't have been so easy without it.

Doesn't the usage of nested task functions violate ESLint's no-shadow?

Yes, but it should be fine as you don't need access to other task functions aside from the immediate one.

Put task in the allow list:
- "no-shadow": ["error", { "allow": ["task"] }]
- "@typescript-eslint/no-shadow": ["error", { "allow": ["task"] }]