defineQueuedTask

Purpose and behavior

Define a workflow task that enqueues a job for handler, polls it until it settles and returns decode(result.value), adding the job’s usage to the run. The job ID comes from executionId and the task key, so a resumed run waits on the same job; a failed or cancelled job fails the task, with code quota when the handler hit a usage limit. Cancelling the workflow cancels the job.

Complete example and detailed rules.

Parameters and properties

• optionsRequired
  QueuedTaskOptions<T>
  Task definition (key, after, retry and the other task options except perform), plus the queue, handler, input builder, decoder, deadline and poll interval.
• options.retryOptional
  Retry | undefined
  Retry policy for failed attempts; without it the task runs once. A retried attempt repeats its side effects.
• options.cacheOptional
  TaskCacheOptions | undefined
  Result cache: a hit restores the stored lossless JSON value with no attempt, usage or side effects. On a miss, a result that is not lossless JSON fails the task. Rejected on gates, interactions and dispatch-result tasks.
• options.gateOptional
  WorkflowGate | undefined
  Persisted approval or pause definition; execution requires a checkpoint and a matching trusted decision.
• options.keyRequired
  string
  Unique key in the workflow, matching [A-Za-z0-9][A-Za-z0-9._-]*. Records, events and checkpoints identify the task by it.
• options.afterOptional
  readonly Task<unknown>[] | undefined
  Tasks that must be done before this one starts, default none; only these can be read with context.value().
• options.interactionOptional
  TaskInteraction | undefined
  Opt-in durable human-input contract; requires checkpointed scheduling and cannot be combined with a gate.
• options.conditionOptional
  ((context: TaskContext) => boolean | Promise<boolean>) | undefined
  Evaluated with attempt 0 before the task runs, including when a later start() resumes it; false ends the task as skipped, which skips its dependents.
• options.timeoutMsOptional
  number | undefined
  Deadline in milliseconds for each attempt, a positive integer up to 2147483647. Expiry aborts context.signal and fails the attempt, which retry may repeat.
• options.queueRequired
  TaskQueue
  Queue in which the task enqueues its job and polls it.
• options.handlerRequired
  string
  Name of the worker handler that runs the job, 1 to 512 characters.
• options.inputRequired
  (context: TaskContext) => WorkflowJson
  Builds the job’s JSON input from the task context, such as dependency values. Called on each attempt: a different value under the same job ID is rejected.
• options.decodeRequired
  (value: WorkflowJson) => T
  Converts the job’s JSON value into the task’s result; throw to fail the task.
• options.deadlineOptional
  number | undefined
  Job deadline in epoch milliseconds; the job becomes cancelled once it passes.
• options.pollMsOptional
  number | undefined
  Interval between job reads in milliseconds, default 250; must be positive.

Returns

Task<T>

Signature

export declare function defineQueuedTask<T>(
  options: QueuedTaskOptions<T>,
): Task<T>;

Related contracts

• QueuedTaskOptions
• Task