Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

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

​
Prerequisites

  • Read the Durable Jobs overview

​
Workflow

1
Start with a job definition.
2
Think of every execution as a run.
3
Use steps for work that should not repeat after it succeeds.
4
Use queues to control background execution.
5
Use 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. 
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
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.

Using Queues

Use queues for background execution, retry policy, delayed jobs, and concurrency control.

State Store

Use durable state for progress, deduplication, counters, TTL-backed markers, and locks.

Event Waiting + Correlation

Pause a workflow until the right external event arrives, then resume the correct run.

Idempotency

Use idempotency keys so duplicate requests do not create duplicate work.