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" });

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;

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()

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

Methods

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.

Functions

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.