robust-tasks

A priority based task runner which is:

• Type safed
• Super lightweight
• Extremely fast
• No dependencies

Continue development of @abxvn/tasks

Installation

Pick one of these commands to install:

pnpm add robust-tasks
yarn add robust-tasks
npm install --save robust-tasks

Usage

Add and run tasks

Tasks can be provided with optional id and context, can be add to the task registry like this:

import { TaskEmitter, TaskPriority } from 'robust-tasks'

// disable autopilot so the queue won't start right away when adding tasks
// for demonstration
const tasks = new TaskEmitter({ autopilot: false })

// `execute` is example function
// if not priority provided, default to TaskPriority.NORMAL
const normalPriorityTask = { execute } 
const lowPriorityTask = { execute, priority: TaskPriority.LOW }
const hightPriorityTask = { execute, priority: TaskPriority.HIGH }

tasks.add(normalPriorityTask)
tasks.add(lowPriorityTask)
tasks.add(hightPriorityTask)

// execute tasks
// execution order will be hightPriorityTask > normalPriorityTask > lowPriorityTask
tasks.next()

Task priorities

These are default tasks priority values:

// From highest to lowest
export const TaskPriority = {
  INSTANT: 1,
  HIGH: 2,
  NORMAL: 3,
  LOW: 4,
  IDLE: 5
} as const

Customized priority values can also be provided, even or custom sort function for tasks. The greater value the sort function returns, the lower priority the task gets.

Provide task context

If a task context is provided, when the time comes, it will be execute with the context

tasks.add({
  context: { name: 'World' },
  // name will be detected as `string` automatically
  execute = ({ name }) => console.log(`Hello ${name}`)
})
// task will be completed with 'Hello World'

Custom task type

You can customize task type, or its context and priority types too:

import { ITask, EventEmitter } from 'robust-tasks`

type ICustomContextType = {...} | undefined
type ICustomPriorityType = {...}

type ICustomTaskType1 = ITask<ICustomContextType>
type ICustomTaskType2 = ITask<ICustomContextType, ICustomPriorityType>
interface ICustomTaskType3 extends ITask { ... }

const tasks1 = new EventEmitter<ICustomTaskType1>()
const tasks2 = new EventEmitter<ICustomTaskType2>()
const tasks2 = new EventEmitter<ICustomTaskType3>()

Introduce sub task after task

New sub tasks can be added into queue inside a task execution

// `execute` is example function
const subtaskExecute = () => console.log('subtask')
// current task emitter can be accessed here too
const taskExecute = ({ tasks }) => {
  console.log('task')
  tasks.add({ execute: subtaskExecute })
}

tasks.add({ execute: taskExecute })
// console.log 'task'
// console.log 'subtask'

Retry a failed task

A failed task can be retried by catching failed tasks. You can implement that logic freely on the way you desire. Here is an example:

const tasks = new TaskEmitter({
  onItemError: (task, error) => {
    if (shouldRetry(task)) { // retry task by re-pushing it back to queue
      tasks.retry(task)
    }
  }
})

Autopilot mode

Autopilot mode automatically start task queue when adding a new task or retrying a task. It's enabled by default. You can disable it by options (but you have to call next after adding tasks)

new TaskEmitter({ autopilot: false })

Changelog

See CHANGELOG.md

Contribution

All PRs and ideas for improvement are welcomed.

If you got any issues using this package, don't hesitate to create new 🐞 Bug report with a proper package:<name> label.

Feel free to clone this project, make changes that your feel necessary and pull request anytime you want.

Install dependencies and run development build:

pnpm install
pnpm start

Working on your first Pull Request?

You can learn how from this free video series: How to Contribute to an Open Source Project on GitHub

To help you get your feet wet and get you familiar with our contribution process, we have a list of good first issues that contain bugs that have a relatively limited scope. This is a great place to get started.

Cheers 🍻