@abxvn/tasks

A priority based task runner which is:

• Type safed
• Extremely fast
• Light-weight
• No dependencies

Table of contents

• Installation
• Usage
  • Add and run tasks
  • Default task priorities
  • Provide task context
  • Custom task type
• Changelog
• Contribution

Installation

Pick one of these commands to install:

pnpm add @abxvn/tasks
yarn add @abxvn/tasks
npm install --save @abxvn/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 '@abxvn/tasks'

const tasks = new TaskEmitter()

// `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()

Default task priorities

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

Provide task context

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

// `execute` is example function
const execute = ({ name }) => console.log(name)
const taskWithContext = { execute, context: { name: 'Hello' } }

tasks.add(taskWithContext)
tasks.next() // console.log 'Hello'

Custom task type

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

import { ITask, EventEmitter } from '@abxvn/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 = (_, taskEmitter) => {
  console.log('task')
  taskEmitter.add({ execute: subtaskExecute })
}

tasks.add({ execute: taskExecute })
tasks.next()
// 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
      // with lower priority
      tasks.add({ ...task, priority: TaskPriority.LOW })
    }
  }
})

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 🍻