task-handler

task-handler

A simple, dependency-free task scheduling manager that makes it easy to handle tasks like a boss.

Install

yarn add task-handler

or

npm install --save task-handler

Coverage

This project provides .flow.js files for Flow to utilize. It also attempts to provide 100% test coverage.

Example

Simple

/* @flow */

import createTaskHandler from "task-handler";

const task = createTaskHandler("simple");

// after timeout
task.after("task:one", 3000, () => log("task:one execute"));

// every interval, execute
task.every("task:two", 3000, () => log("task:two execute"));

// immediately execute on next tick (nextTick, immediate, timeout priority - first found)
task.defer("task:three", () => log("task:three execute"));

// every interval and immediately (defer), execute
task.everyNow("task:four", 3000, () => log("task:four execute"));

// sequentially execute at an interval -
// waits until the function requested to
// finish before scheduling the next
// timeout.
// - NOTE: Awaits promises if returned
//         by the function. Which is not
//         the standard behavior.
task.everySequential("task:five", 100, async () => {
  log("task:five execute");
  await new Promise(resolve => setTimeout(resolve, 3000));
  log("task:five completes");
});

// same as above but adds a deferred execution first
// which occurs on the next tick.
task.everyNowSequential("task:six", 100, async () => {
  log("task:six execute");
  await new Promise(resolve => setTimeout(resolve, 3000));
  log("task:six completes");
});

// schedule an advanced async job with cancellation
task.job(
  "task:seven",
  function TaskFiveHandler(...args) {
    // args resolves to [1, 2, 3]
    // saved context - `this` resolves to the job `ref`
    const ref = this;
    return {
      async start(ref2) {
        // called when the job starts (synchronously)
        //
        // ref is also the first argument given, it is the same as the
        // top level `this` but can be used when using arrow function
        // at the top level.
        // ref.resolve('value');
        // ref.reject('error');
        // ref.cancel();
      },
      async cancelled() {
        // called if the job is cancelled
      },
      async complete() {
        // called when the job is complete (resolved, cancelled, or errored).
      }
    };
  },
  [1, 2, 3]
);

// get the total # of tasks scheduled
task.size; // 7

// cancels each of the given ID's, if they exist
task.cancel("task:one", "task:two");

// clear all tasks, killing the event queue and completing execution
task.after("complete", 10000, () => {
  log("complete - clearing tasks");
  task.clear();
});

Promises

When calling .promise() on the task ref, after and defer return regular promises that resolve to the task ref with a result of the function passed. If no function is passed then the ref.result will be undefined.

task
  .after("afterID", 1000, () => 1)
  .promise()
  .then(ref => {
    console.log("After 1000ms: ", ref.result); // After 1000ms: 1
  });

Interval tasks such as every and everyNow return async iterators when their .promises() function is called. This allows us to utilize the handy for await... of feature of JS.

IMPORTANT: Notice that every and everyNow use .promises() and now .promise(). This is to allow for type safety. These tasks will error if .promise() is called on them.

async function intervalForAwait() {
  for await (const ref of task.every("everyID", 1000).promises()) {
    console.log("Next Tick");
    // based on some logic...
    ref.cancel();
  }
  console.log("After Cancel everyID");
}

// Or using standard async function...
async function intervalAwait() {
  const iter = task.every("everyID", 1000).promises();
  let done = false;
  let ref;
  while (!done) {
    let ref;
    ({ value: ref, done } = await iter.next());
    console.log("Next Tick");
    // based on some logic...
    ref.cancel();
  }
  console.log("After Cancel everyID");
}