Documentation

Core Concepts

The vocabulary behind Durable Jobs: jobs, steps, runs, queues, state, events, and idempotency.

Try StackShiftRead the overview

Search Docs

Durable Jobs

Core Concepts

Live

The vocabulary behind Durable Jobs: jobs, steps, runs, queues, state, events, and idempotency.

Goal

Learn the small set of concepts needed to build reliable backend flows.

Current status

Live

This area is documented as current, user-reliable behavior.

Workflow

  1. 1Start with a job definition.
  2. 2Think of every execution as a run.
  3. 3Use steps for work that should not repeat after it succeeds.
  4. 4Use queues to control background execution.
  5. 5Use state, events, and idempotency to make external systems safe.

Jobs and runs

A job is the named unit of work. A run is one execution of that job with a payload, status, attempts, timeline, and result.

Define and start a job

stackshift.job('resizeAvatar', async ({ payload }) => {
  return resizeImage(payload)
})

await stackshift.start('resizeAvatar', { imageId: 'img_123' }, {
  queueName: 'media',
  idempotencyKey: 'resize:img_123',
})

Steps

A step is a named unit inside a job. If a retry happens after a step completes, StackShift reuses the step result instead of running it again.

Remember completed work

ts
await step.run('charge-card', async () => {
  return stripe.paymentIntents.capture(paymentIntentId)
})

await step.run('provision-plan', async () => {
  return provisionWorkspace(userId)
})

Queues, state, events, and idempotency

  • Queues decide where and when background work runs.
  • State stores durable values such as progress, counters, dedupe markers, and locks.
  • Events resume paused workflows when an external signal arrives.
  • Idempotency keys ensure duplicate starts reuse the same logical run instead of doing the work twice.

Expected result

The Durable Jobs API reads as one system instead of separate queue, workflow, and state products.