Getting started

Introduction

Atlas Queue is a small library for running background jobs with retries, delays and clear failure reports.

What it does

You describe work as a named job with a payload. Atlas Queue stores it, hands it to a worker, retries it on failure and tells you when it has finally given up. There is no server to run: queues live in a single file or in any store that implements the adapter interface.

Why use it

• It has no runtime dependencies and installs in under a second.
• Every job has a visible state: waiting, active, done or failed.
• Retries use exponential backoff by default, with jitter.

Who it is for

Teams that need dependable background work without adopting a full message broker. If you send fewer than a few thousand jobs a minute, this is probably enough.

Getting started

Installation

Add the package and choose where queues are stored.

Requirements

Node 20 or newer. The default file store needs write access to a single directory.

Install the package

npm install atlas-queue

Choose a store

The file store is the easiest way to begin. Pass a directory and Atlas Queue creates it on first use.

import { createQueue } from "atlas-queue";

export const queue = createQueue("emails", {
  store: "./.queues",
  retries: 5
});

Environment variables

Set ATLAS_STORE to override the store path without changing code, which is handy for tests.

Getting started

Quickstart

Send your first job and process it in five minutes.

1. Create a queue

Queues are cheap. Create one per kind of work so retries and limits stay independent.

import { createQueue } from "atlas-queue";
const queue = createQueue("welcome-emails");

2. Start a worker

A worker is a function that receives the job and either returns or throws. Throwing counts as a failed attempt.

queue.work(async (job) => {
  await sendEmail(job.data.to, job.data.subject);
  return { sent: true };
});

3. Add a job

const job = await queue.add({
  to: "sam@example.com",
  subject: "Welcome aboard"
}, { delay: 5000 });

// job.id is stable across restarts
console.log(job.id, job.state);

Check the result

Call queue.get(job.id) at any time to read the job state, attempt count and last error.

Core concepts

Queues and workers

How jobs move from waiting to done, and what happens when they fail.

Job states

Retries and backoff

A failed attempt is retried after a delay that doubles each time, with a small random jitter so many failures do not retry in lockstep.

createQueue("reports", {
  retries: 4,
  backoff: { type: "exponential", base: 2000, jitter: 0.2 }
});

Concurrency

Each worker handles one job at a time unless you pass concurrency. Raise it for I/O-bound work and keep it low for heavy computation.

Reference

API reference

Every function and option in Atlas Queue 2.4.

createQueue(name, options)

Returns a queue handle. Creating a queue with an existing name reconnects to it.

queue.add(data, options)

Stores a job and returns it. Use delay in milliseconds to schedule it later, or id to make adding idempotent.

await queue.add({ userId: 42 }, { id: "digest-42", delay: 60000 });

queue.work(handler)

Registers a handler and starts polling. The handler receives job with id, data and attempt. Returns a function that stops the worker.

queue.get(id) and queue.remove(id)

get returns the job or null. remove deletes a waiting job and returns whether anything was removed.