# 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.

<a id="taskworkflowdeclaration"></a>

### 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:

```typescript
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

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

#### Methods

<a id="cron"></a>

##### `cron()`

Creates a cron schedule for the task.

Parameters

| Parameter    | Type                | Description                                                 |
| ------------ | ------------------- | ----------------------------------------------------------- |
| `name`       | `string`            | The name of the cron schedule.                              |
| `expression` | `string`            | The cron expression defining the schedule.                  |
| `input`      | `I` & `GlobalInput` | The input data for the task, including global input fields. |
| `options?`   | `RunOpts`           | Optional configuration for this task run.                   |

Returns

`Promise`\<`CronWorkflows`\>

A promise that resolves with the cron workflow details.

Overrides

```ts
BaseWorkflowDeclaration.cron;
```

<a id="delay"></a>

##### `delay()`

Schedules the task to run after a specified delay.

Parameters

| Parameter  | Type                | Description                                                 |
| ---------- | ------------------- | ----------------------------------------------------------- |
| `duration` | `number`            | The delay in seconds before the task should run.            |
| `input`    | `I` & `GlobalInput` | The input data for the task, including global input fields. |
| `options?` | `RunOpts`           | Optional configuration for this task run.                   |

Returns

`Promise`\<`ScheduledWorkflows`\>

A promise that resolves with the scheduled workflow details.

Overrides

```ts
BaseWorkflowDeclaration.delay;
```

<a id="run"></a>

##### `run()`

Triggers a task run and waits for the result.

Parameters

| Parameter  | Type                | Description                                                 |
| ---------- | ------------------- | ----------------------------------------------------------- |
| `input`    | `I` & `GlobalInput` | The input data for the task, including global input fields. |
| `options?` | `RunOpts`           | Optional configuration for this task run.                   |

Returns

`Promise`\<`O` & `Resolved`\<`GlobalOutput`, `MiddlewareAfter`\>\>

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

Overrides

```ts
BaseWorkflowDeclaration.run;
```

<a id="runandwait"></a>

##### `runAndWait()`

Triggers a task run and waits for the result.

Parameters

| Parameter  | Type                | Description                                                 |
| ---------- | ------------------- | ----------------------------------------------------------- |
| `input`    | `I` & `GlobalInput` | The input data for the task, including global input fields. |
| `options?` | `RunOpts`           | Optional configuration for this task run.                   |

Returns

`Promise`\<`O` & `Resolved`\<`GlobalOutput`, `MiddlewareAfter`\>\>

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

Overrides

```ts
BaseWorkflowDeclaration.runAndWait;
```

<a id="runnowait"></a>

##### `runNoWait()`

Triggers a task run without waiting for completion.

Parameters

| Parameter  | Type                | Description                                                 |
| ---------- | ------------------- | ----------------------------------------------------------- |
| `input`    | `I` & `GlobalInput` | The input data for the task, including global input fields. |
| `options?` | `RunOpts`           | Optional configuration for this task run.                   |

Returns

`Promise`\<`WorkflowRunRef`\<`O` & `Resolved`\<..., ...\>\>\>

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

Overrides

```ts
BaseWorkflowDeclaration.runNoWait;
```

Triggers a task run without waiting for completion.

Parameters

| Parameter  | Type                  | Description                                                 |
| ---------- | --------------------- | ----------------------------------------------------------- |
| `input`    | `I` & `GlobalInput`[] | The input data for the task, including global input fields. |
| `options?` | `RunOpts`             | Optional configuration for this task run.                   |

Returns

`Promise`\<`WorkflowRunRef`\<... & ...\>[]\>

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

Overrides

```ts
BaseWorkflowDeclaration.runNoWait;
```

<a id="schedule"></a>

##### `schedule()`

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

Parameters

| Parameter   | Type                | Description                                                 |
| ----------- | ------------------- | ----------------------------------------------------------- |
| `enqueueAt` | `Date`              | The date when the task should be triggered.                 |
| `input`     | `I` & `GlobalInput` | The input data for the task, including global input fields. |
| `options?`  | `RunOpts`           | Optional configuration for this task run.                   |

Returns

`Promise`\<`ScheduledWorkflows`\>

A promise that resolves with the scheduled workflow details.

Overrides

```ts
BaseWorkflowDeclaration.schedule;
```

---

<a id="workflowdeclaration"></a>

### 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:

```typescript
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

<a id="durabletask"></a>

##### `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

| Parameter | Type                                                               | Description                     |
| --------- | ------------------------------------------------------------------ | ------------------------------- |
| `options` | `Omit`\<`CreateWorkflowTaskOpts`\<`I`, `TO`\>, `"fn"`\> & `object` | The task configuration options. |

Returns

`CreateWorkflowDurableTaskOpts`\<`I`, `TO`\>

The task options that were added.

<a id="onfailure"></a>

##### `onFailure()`

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

Parameters

| Parameter | Type                                                                                                                                                                       | Description                     |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `options` | \| `Omit`\<`CreateOnFailureTaskOpts`\<..., ...\>, `"fn"`\> & `object` \| [`TaskWorkflowDeclaration`](#taskworkflowdeclaration)\<`any`, `any`, \{ \}, \{ \}, \{ \}, \{ \}\> | The task configuration options. |

Returns

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

The task options that were added.

<a id="onsuccess"></a>

##### `onSuccess()`

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

Parameters

| Parameter | Type                                                                                                                                                                       | Description                     |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `options` | \| [`TaskWorkflowDeclaration`](#taskworkflowdeclaration)\<`any`, `any`, \{ \}, \{ \}, \{ \}, \{ \}\> \| `Omit`\<`CreateOnSuccessTaskOpts`\<..., ...\>, `"fn"`\> & `object` | The task configuration options. |

Returns

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

The task options that were added.

<a id="task"></a>

##### `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

| Parameter | Type                                                                                                                                                                   | Description                     |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `options` | \| `Omit`\<`CreateWorkflowTaskOpts`\<..., ...\>, `"fn"`\> & `object` \| [`TaskWorkflowDeclaration`](#taskworkflowdeclaration)\<`I`, `TO`, \{ \}, \{ \}, \{ \}, \{ \}\> | The task configuration options. |

Returns

`CreateWorkflowTaskOpts`\<`I`, `TO`\>

The task options that were added.

## Functions

<a id="createdurabletaskworkflow"></a>

### `CreateDurableTaskWorkflow()`

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

Parameters

| Parameter | Type                                                                     | Description                             |
| --------- | ------------------------------------------------------------------------ | --------------------------------------- |
| `options` | `object` & `Omit`\<`CreateWorkflowDurableTaskOpts`\<`I`, `O`\>, `"fn"`\> | The durable task configuration options. |
| `client?` | `IHatchetClient`                                                         | Optional Hatchet client instance.       |

Returns

[`TaskWorkflowDeclaration`](#taskworkflowdeclaration)\<`I`, `O`\>

A new TaskWorkflowDeclaration with inferred types.

---

<a id="createtaskworkflow"></a>

### `CreateTaskWorkflow()`

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

Parameters

| Parameter | Type                                                              | Description                       |
| --------- | ----------------------------------------------------------------- | --------------------------------- |
| `options` | `object` & `Omit`\<`CreateTaskWorkflowOpts`\<`I`, `O`\>, `"fn"`\> | The task configuration options.   |
| `client?` | `IHatchetClient`                                                  | Optional Hatchet client instance. |

Returns

[`TaskWorkflowDeclaration`](#taskworkflowdeclaration)\<`I`, `O`\>

A new TaskWorkflowDeclaration with inferred types.

---

<a id="createworkflow"></a>

### `CreateWorkflow()`

Creates a new workflow instance.

Parameters

| Parameter | Type                 | Description                                                                                                                             |
| --------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `options` | `CreateWorkflowOpts` | The options for creating the workflow. Optionally include a Zod schema via the `input` field to generate a JSON Schema for the backend. |
| `client?` | `IHatchetClient`     | Optional Hatchet client instance.                                                                                                       |

Returns

[`WorkflowDeclaration`](#workflowdeclaration)\<`I`, `O`\>

A new Workflow instance.
