The minimal task runner for Node.js
Features
- Task list with dynamic states
- Parallel & nestable tasks
- Unopinionated
- Type-safe
Found this package useful? Show your support & appreciation by sponsoring! ❤️
Install
npm i tasukuAbout
タスク (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.
import { copyFile } from 'fs/promises'
import task from 'tasuku'
task('Copying file from path A to B', async ({ setTitle }) => {
await copyFile('/path/A', '/path/B')
setTitle('Successfully copied file from path A to B!')
})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.
import task from 'tasuku'
task('Task 1', async () => {
await someAsyncTask()
})
task('Task 2', async () => {
await someAsyncTask()
})
task('Task 3', async () => {
await someAsyncTask()
})
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().
import task from 'tasuku'
task('Task 1', async () => {
await someAsyncTask()
})
// ...
someOtherCode()
// ...
task('Task 2', async ({ setTitle }) => {
await someAsyncTask()
setTitle('Task 2 complete')
})
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.
const myTask = await task('Task 2', async () => {
await someAsyncTask()
return 'Success'
})
console.log(myTask.result) // 'Success'Nesting tasks
Tasks can be nested indefinitely. Nested tasks will be stacked hierarchically in the task list.
await task('Do task', async ({ task }) => {
await someAsyncTask()
await task('Do another task', async ({ task }) => {
await someAsyncTask()
await task('And another', async () => {
await someAsyncTask()
})
})
})
Collapsing nested tasks
Call .clear() on the returned task API to collapse the nested task.
await task('Do task', async ({ task }) => {
await someAsyncTask()
const nestedTask = await task('Do another task', async ({ task }) => {
await someAsyncTask()
})
nestedTask.clear()
})
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.
const groupedTasks = await task.group(task => [
task('Task 1', async () => {
await someAsyncTask()
return 'one'
}),
task('Waiting for Task 1', async ({ setTitle }) => {
setTitle('Task 2 running...')
await someAsyncTask()
setTitle('Task 2 complete')
return 'two'
})
// ...
])
console.log(groupedTasks) // [{ result: 'one' }, { result: 'two' }]
Running tasks in parallel
You can run tasks in parallel by passing in { concurrency: n } as the second argument in task.group().
const api = await task.group(task => [
task(
'Task 1',
async () => await someAsyncTask()
),
task(
'Task 2',
async () => await someAsyncTask()
)
// ...
], {
concurrency: 2 // Number of tasks to run at a time
})
api.clear() // Clear output
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.
// No API
await Promise.all([
task(
'Task 1',
async () => await someAsyncTask()
),
task(
'Task 2',
async () => await someAsyncTask()
)
// ...
])API
task(taskTitle, taskFunction)
Returns a Promise that resolves with object:
type TaskAPI = {
// Result from taskFunction
result: any
// State of the task
state: 'error' | 'warning' | 'success'
// Invoke to clear the results from the terminal
clear: () => void
}taskTitle
Type: string
Required: true
The name of the task displayed.
taskFunction
Type:
type TaskFunction = (taskInnerApi: {
task: createTask
setTitle(title: string): void
setStatus(status?: string): void
setOutput(output: string | { message: string }): void
setWarning(warning: Error | string): void
setError(error: Error | string): void
}) => Promise<any>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:
// The results from the taskFunctions
type TaskGroupAPI = {
// Result from taskFunction
result: any
// State of the task
state: 'error' | 'warning' | 'success'
// Invoke to clear the task result
clear: () => void
}[] & {
// Invoke to clear ALL results
clear: () => void
}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.
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 with console.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"] }]
Sponsors
