Completing Without a Worker

Complete jobs without a worker for approval workflows.

Jobs can be completed without a worker using completeChain. This enables approval workflows, webhook-triggered completions, and patterns where jobs wait for external events. Deferred start pairs well with this — schedule a job to auto-reject after a timeout, but allow early completion based on user action.

An approval request either continues with process-request or ends the chain with a rejection:

src/workerless-completion.ts

const jobTypes = defineJobTypes<{
  /*
   * await-approval --+--> (approved) --> process-request
   *                  |
   *                  +--> (rejected or timed out) --> output { rejected }
   */
  "await-approval": {
    entry: true;
    input: { requestId: string };
    output: { rejected: true; reason: string };
    continueWith: { typeName: "process-request" };
  };
  "process-request": {
    input: { requestId: string };
    output: { processed: true };
  };
}>();

Create the request with a deferred start, so it waits two hours before a worker can pick it up:

src/workerless-completion.ts

const requestApproval = async (requestId: string) =>
  stateAdapter.withTransaction(async (txCtx) =>
    client.createChain({
      ...txCtx,
      typeName: "await-approval",
      input: { requestId },
      schedule: { afterMs: 2 * 60 * 60 * 1000 },
    }),
  );

The worker handles the timeout case: if nobody decided in time, await-approval runs and rejects the request. It also processes approved requests:

src/workerless-completion.ts

"await-approval": {
  attemptHandler: async ({ complete }) =>
    stateAdapter.withTransaction(async (txCtx) =>
      complete({ ...txCtx, output: { rejected: true, reason: "timeout" } }),
    ),
},
"process-request": {
  attemptHandler: async ({ job, complete }) =>
    stateAdapter.withTransaction(async (txCtx) => {
      processedRequests.push(job.input.requestId);
      return complete({ ...txCtx, output: { processed: true } });
    }),
},

The decision completes the job early without a worker, for example from an API endpoint. Approval continues the chain with process-request, which a worker then runs; rejection completes the chain with an output. A request that has already moved past await-approval is left untouched:

src/workerless-completion.ts

const decideApproval = async (chainId: string, approved: boolean) =>
  stateAdapter.withTransaction(async (txCtx) =>
    client.completeChain({
      ...txCtx,
      id: chainId,
      typeName: "await-approval",
      handler: async ({ job, completeJob }) => {
        if (job.typeName !== "await-approval") return;
        await completeJob(job, async ({ complete }) =>
          approved
            ? complete({
                continueWith: {
                  typeName: "process-request",
                  input: { requestId: job.input.requestId },
                },
              })
            : complete({ output: { rejected: true, reason: "manager denied" } }),
        );
      },
    }),
  );

This pattern lets you interweave external actions with your chains — waiting for user input, third-party callbacks, or manual approval steps.

How It Works

The completeChain method calls your handler with the current job and a completeJob function. Pass the job to completeJob, then call complete with the outcome you want: { output: ... } finishes the chain, { continueWith: {...} } adds the next job.

Your handler can also decline: just return without calling completeJob. The chain stays untouched. Use this when the chain has already moved past the stage you meant to complete.

Over a synchronous state adapter, the handler and the completeJob callback must be synchronous: one that returns a promise throws.

Internally, completeChain locks the current job at the state adapter level, preventing concurrent completion by a worker or another caller. The Redis state adapter keeps workers off the job for at most 60 seconds and makes a second caller run its transaction again instead of waiting; see Locks. The completed job has completedBy: null (no worker identity), distinguishing it from worker-completed jobs.

If a worker is already processing the job when completeChain runs, completeChain takes the job over. The handler's abort signal fires when the notify adapter delivers the attempt-lost notification, and its complete, when it runs, writes nothing and throws JobAlreadyCompletedError, so the handler's transaction rolls back. If the handler is inside a fenced transaction, completeChain waits for it to end; on Redis, the one that commits second runs again instead.

See examples/guides/src/workerless-completion.ts for the runnable code. See also Tx Hooks and Scheduling.

esc

Search guides, integrations and every exported symbol.

↑ ↓ to navigate↵ to open