# SureQ > SureQ is a job queue for Node.js, written in TypeScript. You add jobs to a queue, and workers run them with retries, delays, priorities and schedules. Jobs live in a store: an in-memory store is built in, and other stores plug in through the store contract. Install with `npm install @sureq/core` (Node 22 or newer, ESM and CommonJS). Every page below is plain Markdown; the whole documentation in one file is https://sureq-js.github.io/sureq/llms-full.txt. ## Getting started - [Install SureQ](https://sureq-js.github.io/sureq/getting-started/install.md) - [Your first queue](https://sureq-js.github.io/sureq/getting-started/first-queue.md): This page builds a small email queue. It adds three jobs, runs them, reports each outcome, waits until the queue is empty and then closes it. - [Core concepts](https://sureq-js.github.io/sureq/getting-started/concepts.md): These are the words the rest of the docs use. ## Guides - [Adding jobs](https://sureq-js.github.io/sureq/guides/adding-jobs.md): A job is one piece of work: some JSON data plus options. You add it with `queue.add`, or many at once with `queue.addBulk`. This page adds jobs and reads them back. No worker runs here, so the jobs stay `waiting`. - [Processing jobs](https://sureq-js.github.io/sureq/guides/processing-jobs.md): A worker claims jobs from a queue and runs your handler on each one. You start one with `queue.process(handler, options)`. This page runs three jobs, two at a time, and stops the worker when the queue is empty. - [Retries and failures](https://sureq-js.github.io/sureq/guides/retries-and-failures.md): When a handler throws, SureQ retries the job after a wait, until its attempts are used up. Some errors should never be retried, and you can say so. This page runs one job that succeeds on its third try, one that runs out of attempts and one that fails at once. - [Delays and priorities](https://sureq-js.github.io/sureq/guides/delays-and-priorities.md): A job can wait before it runs: give it a `delay` or a `runAt` time. Among jobs that are ready, a higher `priority` runs first. This page adds five jobs before a worker starts, so you can see the order they run in. - [Schedules](https://sureq-js.github.io/sureq/guides/schedules.md): A schedule makes one job on each tick of its timing: a `cron` rule in a time zone, or a fixed `every` period. It is stored, so every pod sees the same schedules. This page creates a schedule that ticks every second, lets it fire twice, and previews a cron rule. - [Batches](https://sureq-js.github.io/sureq/guides/batches.md): A batch worker hands your handler several jobs at once, for work that is cheaper in bulk. Each job still keeps its own attempts, retries and result. This page sends five emails in batches of up to three, and fails one of them on its own. - [Duplicates and unique ids](https://sureq-js.github.io/sureq/guides/duplicates-and-unique-ids.md): Give a job your own id, and a second add with the same id does not make a second job. You choose what that second add does instead. This page sends one welcome email per user, tries to add it again in several ways, and uses a singleton key. - [Progress and long jobs](https://sureq-js.github.io/sureq/guides/progress-and-long-jobs.md): A handler can report how far it got with `ctx.progress`. Long jobs also need a lease long enough to survive, and maybe a time limit. This page exports files with progress, and gives a second job a timeout it cannot meet. - [Dead letters and redrive](https://sureq-js.github.io/sureq/guides/dead-letters-and-redrive.md): A job that fails for good is kept as a dead letter, with its data, its error and its attempt history. Once you fix the cause, you redrive it: the job goes back to `waiting` and runs again. This page lets two jobs fail while the mail server is down, lists them, then redrives them. - [Pause, cancel and cleanup](https://sureq-js.github.io/sureq/guides/pause-cancel-and-cleanup.md): You can stop a whole queue for a while with `pause()`, stop one job with `cancel(id)`, and delete old jobs with `clean`. Pause and cancel work while workers run, on every pod. This page pauses a queue, cancels one waiting and one running job, resumes, then cleans up. - [Health and metrics](https://sureq-js.github.io/sureq/guides/health-and-metrics.md): A queue tells you how it is doing: `health()` answers liveness and readiness probes, `metrics()` gives numbers for dashboards, and alert rules fire when a threshold is crossed. This page serves `/livez` and `/readyz`, lets jobs pile up until a depth alert fires, and reads the job counts from the metrics. - [Producer-only pods](https://sureq-js.github.io/sureq/guides/producer-only-pods.md): A `Producer` adds and manages jobs but never runs them. Use it in processes that only add jobs, such as an API server or a serverless function, while worker pods run the jobs from the same store. This page adds a job from a producer and lets a worker on the same store run it. - [Graceful shutdown](https://sureq-js.github.io/sureq/guides/graceful-shutdown.md): When a pod stops, its workers should finish what they can and hand the rest back, so no job is lost or left waiting for a lease to run out. `queue.close()` does that, and the queue option `signals` calls it for you on `SIGTERM`. This page sends itself `SIGTERM` while one short and one long job run, and shows what happens to each. - [Handling errors](https://sureq-js.github.io/sureq/guides/handling-errors.md): Errors reach you in three ways: thrown from a call such as `add`, reported as an `error` event, or stored on a job that failed. Every SureQ error has a stable `code`, so check the `code` or use `instanceof`, never the message. This page shows one of each: a rejected add, an unknown id, a failed job, and a listener that throws. - [Testing your jobs](https://sureq-js.github.io/sureq/guides/testing-your-jobs.md): Test a handler by running it through a real queue on a `MemoryStore`: add a job, wait for it to finish, then check the stored job. No fake clock and no mocks are needed, because short retries finish in milliseconds. This page is one test file with two tests: a job that succeeds on its second attempt, and one that fails at once. - [Going to production](https://sureq-js.github.io/sureq/guides/going-to-production.md): A queue that works on your laptop needs a few more settings before it runs real jobs on several pods. Go through this list once per service. Each item says what to check and links to the page with the details. ## Reference - [Queue](https://sureq-js.github.io/sureq/reference/queue.md): A `Queue` holds jobs of one name in one namespace of one store. You add jobs to it, and you start workers on it. - [Job options](https://sureq-js.github.io/sureq/reference/job-options.md): Options for one job, given as the second argument of `queue.add(data, opts)` or as `opts` of an `addBulk` item. An option set to `undefined` counts as not given. - [Retry and backoff](https://sureq-js.github.io/sureq/reference/retry-and-backoff.md): When an attempt fails, SureQ either retries the job after a wait, or fails it for good. This page lists what decides that and how long the wait is. - [Worker options](https://sureq-js.github.io/sureq/reference/worker-options.md): A worker claims jobs from a queue and runs your handler on them. You start one with `queue.process(handler, opts)`. This page lists every option of `WorkerOptions` and the `Worker` it returns. - [Batch worker](https://sureq-js.github.io/sureq/reference/batch-worker.md): A batch worker hands your handler several jobs at once. You start one with `queue.processBatch(handler, opts)`. A batch only groups the delivery: each job keeps its own lease, fencing token, attempt count, retry decision and write. - [Events](https://sureq-js.github.io/sureq/reference/events.md): Queues, workers and producers emit events. Listen with `on`, `once` and `off`. - [Job and context](https://sureq-js.github.io/sureq/reference/job-and-context.md): A handler gets two arguments: the `job` it runs and a `ctx` for this attempt. - [Errors](https://sureq-js.github.io/sureq/reference/errors.md): Every error SureQ itself raises is a `SureQError` with a stable `code`. Check the `code`, or use `instanceof`, to decide what to do. - [Producer](https://sureq-js.github.io/sureq/reference/producer.md): A `Producer` is the add side of a queue, for a process that never runs jobs: an API server, a serverless function, a command-line tool. It adds, reads and manages jobs in a shared store. It runs no worker, sweeper, scheduler, heartbeat, alert loop or timer. - [MemoryStore](https://sureq-js.github.io/sureq/reference/memory-store.md): `MemoryStore` is the built-in store. It keeps every job in this process's memory, so jobs are lost when the process exits. Use it for tests, local work and single-process apps. - [Health and metrics](https://sureq-js.github.io/sureq/reference/health-and-metrics.md): A queue reports on itself in four ways: `health()` for probes, `metrics()` for dashboards, alerts for thresholds, and `getWorkers()` for the live workers of every pod. - [Logging](https://sureq-js.github.io/sureq/reference/logging.md): SureQ writes a few log lines of its own. By default they go to the console at level `warn` and above. Pass the queue option `logger` to send them elsewhere, or `false` to turn them off. - [Schedules](https://sureq-js.github.io/sureq/reference/schedules.md): A schedule is a stored record that makes one job for each tick of its timing: a `cron` rule in a time zone, or a fixed `every` period. - [Admin](https://sureq-js.github.io/sureq/reference/admin.md): Calls that manage jobs in bulk or change how a queue runs: cancel and remove, dead letters and redrive, clean, drain, obliterate, and pause. `Queue` and `Producer` both have them. ## Stores - [Store contract](https://sureq-js.github.io/sureq/stores/store-contract.md): A store is where jobs live. SureQ talks to every store through one interface, `Store`, exported by `@sureq/core`. The built-in MemoryStore implements it, and so does any store adapter for a database. - [Writing your own store](https://sureq-js.github.io/sureq/stores/writing-your-own.md): This page walks you through writing a store adapter: a `Store` over your own database, so that pods in several processes share one set of jobs. You do not need to know SureQ's code. You need the store contract, the store template and the conformance kit. - [Conformance kit](https://sureq-js.github.io/sureq/stores/conformance-kit.md): `@sureq/store-test` is the test suite for SureQ stores. It checks a store against the store contract: claims, leases, fencing tokens, sweeping, release, cancel, pause, the store clock, the duplicate rules, schedules, the worker registry and more. A store that passes it is safe to put under a SureQ queue. ## Operations - [Upgrade notes](https://sureq-js.github.io/sureq/operations/upgrade-notes.md): 1.0 is the first public release of SureQ. No earlier version was published, so there is nothing to migrate. This page is for teams that ran a 0.x build from source, and for rolling deploys from now on. - [Troubleshooting](https://sureq-js.github.io/sureq/operations/troubleshooting.md): Each entry starts with what you see, then says why it happens and what to do. Error codes are listed in Errors. Health warning codes are listed in Health warnings. - [FAQ](https://sureq-js.github.io/sureq/operations/faq.md): Short answers to common questions. Each one links to the page with the details. - [Known limits](https://sureq-js.github.io/sureq/operations/known-limits.md): These are the limits of this release that you should plan around. Most are by design. Some will change in a later release. ## Optional - [npm: @sureq/core](https://www.npmjs.com/package/@sureq/core): the package, its README and versions - [Source on GitHub](https://github.com/sureq-js/sureq): code, CHANGELOG and issues