Quick Start

This page will help you get started with BackgroundJS quickly.

Installation

npm install @backgroundjs/core

Basic Usage

import {InMemoryJobStorage,JobQueue} from "@backgroundjs/core"
import { Hono } from "hono";
import { serve } from "@hono/node-server";

const storage = new InMemoryJobStorage();
const queue = new JobQueue(storage, {
  concurrency: 2,
  maxRetries: 3,
  name: "test-queue",
  processingInterval: 1000,
});

const app = new Hono();

const handler = (data:{message:string}) => {
  await new Promise((resolve) => setTimeout(resolve, 3000));
  console.log("job completed",data.message);
  return data
}

queue.register("send-email", handler)


app.post("/send-email",async(c)=>{
  const data = await c.req.json()
  const job = await queue.add("send-email",data)
  return c.json({message:"Email has been sent!"});
})


queue.start()
["SIGTERM", "SIGINT", "SIGKILL"].forEach((signal) => {
  process.on(signal, () => {
    queue.stop();
  });
});

serve({
  fetch: app.fetch,
  port: 3000,
});

WARNING

In memory JobQueue does not work in a distributed manner, other processes can not see jobs of the other process. If you want a distributed queue, use Redis,MongoDB or PostgreSQL. You can also write your own queue easliy by extending the existing JobQueue.

For writing your own queue, please refer to the extending background.

Setting The Concurrency

You can set the concurrency of the queue by changing the concurrency option in the constructor. The default concurrency is 1 , meaning your queue will do the jobs one by one waiting for each other to finish.

You can set the concurrency as much as you like but be carefull as if you set it too much and you have too many jobs, it can overwhelm your server.

const queue = new JobQueue(storage, {
  concurrency: 10, //It's up to you
  maxRetries: 3,
  name: "test-queue",
  processingInterval: 1000,
});

Processing Interval

Processing interval determines the interval your queue will poll from the storage to process jobs. You can set the processing interval as according to your liking

const queue = new JobQueue(storage, {
  concurrency: 10, //It's up to you
  maxRetries: 3,
  name: "test-queue",
  processingInterval: 20, //It's up to you
});

Enable Intelligent Polling

Background supports intelligent polling. Meaning it can intelligently adjust its polling and concurrency so that it can reduce CPU cycles and DB hits.

const queue = new JobQueue(storage, {
  concurrency: 1,
  processingInterval: 100,
  intelligentPolling: true,
  minInterval: 100,
  maxInterval: 225,
  maxEmptyPolls: 5,
  loadFactor: 0.5,
  maxConcurrency:10
});

You can adjust options about intelligent polling.

• maxEmptyPolls - Amount of empty polls before updating the interval
• maxInterval - Max interval your queue can increase its polling
• minInterval - Minimum amount it can go down to.
• loadFactor - Amount of load for the queue, calculated as concurrency / activeJobs
• maxConcurrency - Max concurrency your queue will process jobs at.