Runnables

Runnables in the Hatchet TypeScript SDK are things that can be run, namely tasks and workflows. The two main types of runnables you’ll encounter are:

• WorkflowDeclaration, returned by hatchet.workflow(...), which lets you define tasks and call run(), schedule(), cron(), etc.
• TaskWorkflowDeclaration, returned by hatchet.task(...), which is a single standalone task that exposes the same execution helpers as a workflow.

TaskWorkflowDeclaration

A standalone task declaration that can be run like a workflow.

TaskWorkflowDeclaration is returned by hatchet.task(...) and wraps a single task definition while exposing the same execution helpers as workflows, such as run(), runNoWait(), schedule(), and cron() (inherited from BaseWorkflowDeclaration).

Example:

const greet = hatchet.task<{ name: string }, { message: string }>({
  name: "greet",
  fn: async (input) => ({ message: `Hello, ${input.name}!` }),
});
 
await greet.run({ name: "World" });
const ref = await greet.runNoWait({ name: "World" });

Template

MiddlewareBefore

Extra fields added to the task fn input by pre-middleware hooks.

Methods

cron()

Creates a cron schedule for the task.

Parameters

Returns

Promise<CronWorkflows>

A promise that resolves with the cron workflow details.

Overrides

BaseWorkflowDeclaration.cron;

delay()

Schedules the task to run after a specified delay.

Parameters

Returns

Promise<ScheduledWorkflows>

A promise that resolves with the scheduled workflow details.

Overrides

BaseWorkflowDeclaration.delay;

run()

Triggers a task run and waits for the result.

Parameters

Returns

Promise<O & Resolved<GlobalOutput, MiddlewareAfter>>

A promise that resolves with the task output merged with post-middleware fields.

Overrides

BaseWorkflowDeclaration.run;

runAndWait()

Triggers a task run and waits for the result.

Parameters

Returns

Promise<O & Resolved<GlobalOutput, MiddlewareAfter>>

A promise that resolves with the task output merged with post-middleware fields.

Overrides

BaseWorkflowDeclaration.runAndWait;

runMany()

Triggers many task runs and waits for all results.

Parameters

Returns

Promise<O & Resolved<…, …>[]>

A promise that resolves with ordered task outputs.

Overrides

BaseWorkflowDeclaration.runMany;

runManyNoWait()

Triggers many task runs without waiting for completion.

Parameters

Returns

Promise<WorkflowRunRef<… & …>[]>

WorkflowRunRef values for each scheduled run.

Overrides

BaseWorkflowDeclaration.runManyNoWait;

runNoWait()

Triggers a task run without waiting for completion.

Parameters

Returns

Promise<WorkflowRunRef<O & Resolved<…, …>>>

A WorkflowRunRef containing the run ID and methods to get results.

Overrides

BaseWorkflowDeclaration.runNoWait;

Triggers a task run without waiting for completion.

Parameters

Returns

Promise<WorkflowRunRef<… & …>[]>

A WorkflowRunRef containing the run ID and methods to get results.

Overrides

BaseWorkflowDeclaration.runNoWait;

schedule()

Schedules the task to run at a specific date and time.

Parameters

Returns

Promise<ScheduledWorkflows>

A promise that resolves with the scheduled workflow details.

Overrides

BaseWorkflowDeclaration.schedule;

WorkflowDeclaration

A Hatchet workflow, which lets you define tasks and perform actions on the workflow.

Workflows in Hatchet represent coordinated units of work that can be triggered, scheduled, or run on a cron schedule. Each workflow can contain multiple tasks that can be arranged in dependencies (DAGs), with customized retry behavior, timeouts, concurrency controls, and more.

Example:

import { hatchet } from "./hatchet-client";
 
type MyInput = { name: string };
 
const workflow = hatchet.workflow<MyInput>({
  name: "my-workflow",
});
 
workflow.task({
  name: "greet",
  fn: async (input) => {
    return { message: `Hello, ${input.name}!` };
  },
});
 
// Run the workflow
await workflow.run({ name: "World" });

Workflows support various execution patterns, including:

• One-time execution with run() and runNoWait()
• Scheduled execution with schedule()
• Cron-based recurring execution with cron()
• Bulk execution by passing an array input to run() and runNoWait()
• Per-run bulk execution options with runMany() and runManyNoWait()

Tasks within workflows can be defined with workflow.task() or workflow.durableTask() and arranged into complex dependency patterns.

Methods

batchTask()

Adds a batch task to the workflow. Batch tasks buffer concurrent runs until Hatchet flushes the batch (size reached or flush interval), then invoke the handler once with all buffered inputs keyed by each run’s task-run external id. The handler must return a Record mapping each id to its output, or set batch.broadcastOutput to return the same result to all callers. retries is always forced to 0 for batch tasks.

Preview: batch tasks are in beta and may change in future releases.

Parameters

Returns

CreateWorkflowTaskOpts<TI, TO>

The task options that were added.

durableTask()

Adds a durable task to the workflow. The return type will be either the property on O that corresponds to the task name, or if there is no matching property, the inferred return type of the function.

Parameters

Returns

CreateWorkflowDurableTaskOpts<I, TO>

The task options that were added.

onFailure()

Adds an onFailure task to the workflow. This will only run if any task in the workflow fails.

Parameters

Returns

CreateWorkflowTaskOpts<I, TaskOutputType<O, Name, L>>

The task options that were added.

onSuccess()

Adds an onSuccess task to the workflow. This will only run if all tasks in the workflow complete successfully.

Parameters

Returns

CreateWorkflowTaskOpts<I, TaskOutputType<O, Name, L>>

The task options that were added.

task()

Adds a task to the workflow. The return type will be either the property on O that corresponds to the task name, or if there is no matching property, the inferred return type of the function.

Parameters

Returns

CreateWorkflowTaskOpts<I, TO>

The task options that were added.

Type Aliases

CreateBatchTaskWorkflowOpts

type CreateBatchTaskWorkflowOpts<I, O> = CreateBaseWorkflowOpts &
  CreateBaseTaskOpts<I, O, BatchTaskFn<I, O>> &
  object;

Options for creating a batch task workflow. Batch tasks buffer concurrent runs and dispatch them together as a single execution; fn receives a Record keyed by each buffered run’s task-run external id.

Preview: batch tasks are in beta and may change in future releases.

Type Declaration

Functions

CreateBatchTaskWorkflow()

Creates a new batch task workflow declaration, with the handler’s single return value broadcast to every member of the batch.

Parameters

Returns

TaskWorkflowDeclaration<I, O>

A new TaskWorkflowDeclaration with inferred types.

Preview: batch tasks are in beta and may change in future releases.

Creates a new batch task workflow declaration. The handler receives a Record keyed by batch member id and must return a Record with the exact same key set.

Parameters

Returns

TaskWorkflowDeclaration<I, O>

A new TaskWorkflowDeclaration with inferred types.

Preview: batch tasks are in beta and may change in future releases.

CreateDurableTaskWorkflow()

Creates a new durable task workflow declaration with types inferred from the function parameter.

Parameters

Returns

TaskWorkflowDeclaration<I, O>

A new TaskWorkflowDeclaration with inferred types.

CreateTaskWorkflow()

Creates a new task workflow declaration with types inferred from the function parameter.

Parameters

Returns

TaskWorkflowDeclaration<I, O>

A new TaskWorkflowDeclaration with inferred types.

CreateWorkflow()

Creates a new workflow instance.

Parameters

Returns

WorkflowDeclaration<I, O>

A new Workflow instance.