Scheduling
Deferred start and recurring job patterns.
Deferred Start
Jobs can be scheduled to start at a future time using the schedule option. The chain is created transactionally but its first job isn't processed until the specified time. Pass { at } for a specific time, as this reminder does, or { afterMs } for a delay from now:
src/scheduling.ts
const reminder = await stateAdapter.withTransaction(async (txCtx) =>
client.createChain({
...txCtx,
typeName: "send-reminder",
input: { userId: "user-1", message: "Weekly standup" },
schedule: { at: new Date(Date.now() + 60 * 60 * 1000) },
}),
);The same schedule option works with continueWith for deferred continuations. Starting a trial sends its follow-up a day later:
src/scheduling.ts
"start-trial": {
attemptHandler: async ({ job, complete }) =>
stateAdapter.withTransaction(async (txCtx) =>
complete({
...txCtx,
continueWith: {
typeName: "send-trial-follow-up",
input: { userId: job.input.userId },
schedule: { afterMs: 24 * 60 * 60 * 1000 },
},
}),
),
},Tip
Combine schedule with deduplication: { key, scope } to prevent duplicate future jobs — for example, ensuring only one reminder is queued per user even if the trigger fires multiple times. See Deduplication.
Rescheduling from a Handler
When a handler needs to defer work without treating it as a failure — for example, a rate-limited API saying "come back later" — use complete({ reschedule }). The handler below waits as long as the API asks before calling it again:
src/scheduling.ts
"call-rate-limited-api": {
attemptHandler: async ({ job, complete }) => {
const response = await callApi(job.input.endpoint);
if (response.status === 429) {
return stateAdapter.withTransaction(async (txCtx) =>
complete({ ...txCtx, reschedule: { afterMs: response.retryAfterMs } }),
);
}
return stateAdapter.withTransaction(async (txCtx) =>
complete({ ...txCtx, output: { data: response.data } }),
);
},
},Because complete({ reschedule }) is a normal outcome — not an error — the job keeps a clean slate: no lastAttemptError, no failure event, no error span. The attempt counter still increments, so backoff reflects total attempts if the job later fails for real. reschedule takes the same { afterMs } or { at } as schedule.
Rescheduling Pending Jobs
A scheduled job is just a pending job with a future scheduledAt. Use rescheduleJob (or rescheduleJobs for a batch) to change when it runs. Pass schedule: { at } or { afterMs } to move it to a different time — here the reminder moves to two hours from now:
src/scheduling.ts
const pushedBack = await stateAdapter.withTransaction(async (txCtx) =>
client.rescheduleJob({ ...txCtx, id: reminder.id, schedule: { afterMs: 2 * 60 * 60 * 1000 } }),
);Omit schedule to run it immediately — useful for admin "run now" actions or manually advancing a queued reminder. Past times clamp to now, matching createChain.
src/scheduling.ts
await stateAdapter.withTransaction(async (txCtx) =>
client.rescheduleJob({ ...txCtx, id: reminder.id }),
);rescheduleJob throws JobNotFoundError if the job does not exist and JobNotReschedulableError if it is not pending (blocked, running or completed).
rescheduleJobs validates atomically — if any id in the batch is missing or not pending, the entire call fails and no job is rescheduled. Both methods are mutating and require a transaction context.
Recurring Jobs
Queuert has no cron syntax. For periodic tasks like daily digests, health checks, or billing cycles, start a new independent chain from within the handler instead of using continueWith. This keeps each execution as its own short-lived chain rather than building an ever-growing chain history. The digest below completes its job, then schedules the next digest a day later in the same transaction while the user is still subscribed:
src/scheduling.ts
"daily-digest": {
attemptHandler: async ({ job, complete }) =>
stateAdapter.withTransaction(async (txCtx) => {
sentEmails.push(`digest for ${job.input.userId}`);
const completedJob = await complete({
...txCtx,
output: { sentAt: new Date().toISOString() },
});
if (subscribedUserIds.has(job.input.userId)) {
await client.createChain({
...txCtx,
typeName: "daily-digest",
input: { userId: job.input.userId },
schedule: { afterMs: 24 * 60 * 60 * 1000 },
});
}
return completedJob;
}),
},Each occurrence is its own chain, so the next digest can be pushed back or run now with rescheduleJob like any other scheduled job. To make sure only one occurrence is ever queued, add a deduplication key and keep complete ahead of createChain, as Self-Scheduling Recurring Chains explains.
See examples/guides/src/scheduling.ts for the runnable code. See also Deduplication and Tx Hooks.