SextantDocs
v2.4latest
v2.4latestv1.9legacy

Switching keeps you on the same page when it exists in the other version.

On this page

Node SDK

Install and use the Node client and worker: creating jobs, paging through lists, handlers with cancellation and error handling.

Updated SDKs Version v2.4

Requires Node 20 or later. The package ships ES modules and TypeScript declarations.

Shell
npm install @sextant/node

Client

client.tsTypeScript
import { Sextant, NotFoundError } from '@sextant/node';

const sextant = new Sextant({
  url: process.env.SEXTANT_URL,
  token: process.env.SEXTANT_TOKEN,
  timeout: 10_000,
});

const job = await sextant.jobs.create({
  queue: 'emails',
  handler: 'send-receipt',
  payload: { orderId: 'ord_4412' },
  idempotencyKey: 'receipt-ord_4412',
});

try {
  await sextant.jobs.cancel(job.id);
} catch (err) {
  if (!(err instanceof NotFoundError)) throw err;
}

Option names are camelCase; the SDK converts them to the API’s snake_case. Dates are Date objects on the way in and out.

Paging

list methods return an async iterable that follows the cursor:

TypeScript
for await (const job of sextant.jobs.list({ state: 'dead', queue: 'emails' })) {
  console.log(job.id, job.lastError?.message);
}

Use .page() to fetch one page and read nextCursor yourself.

Handlers

Register handlers and start a worker in your own process:

worker.tsTypeScript
import { Sextant, defineHandler, PermanentError } from '@sextant/node';

const sextant = new Sextant();

const sendReceipt = defineHandler('send-receipt', async (job, ctx) => {
  const order = await orders.find(job.payload.orderId, { signal: ctx.signal });
  if (!order) throw new PermanentError('order not found');
  await mailer.send(order.email, receipt(order), { signal: ctx.signal });
});

const worker = sextant.worker({ queues: ['emails'], concurrency: 20 });
worker.register(sendReceipt);
await worker.start();

process.on('SIGTERM', () => worker.stop({ timeout: 30_000 }));

ctx.signal is an AbortSignal that fires on cancellation, timeout and shutdown. Pass it to fetch, database drivers and anything else that accepts one.

job.idstring optional
The job id.
job.payloadunknown optional
The JSON payload. Type it with a generic: defineHandler<Payload>(...).
job.attemptnumber optional
Starts at 1.
ctx.signalAbortSignal optional
Aborted on cancel, timeout and shutdown.
ctx.jobsSextant['jobs'] optional
A client bound to this worker’s credentials, for creating follow-up jobs.

Errors

Class HTTP status
ValidationError 422
PermissionError 401, 403
NotFoundError 404
ConflictError 409
RateLimitError 429, with retryAfter in seconds
ServerError 5xx, after retries

Every error has requestId; include it when you report a problem.