Dependencies
A Dependency defines an ordering constraint between two tasks. When you add a dependency from task A to task B, Clockwork ensures B cannot start until A reaches the required state — and re-schedules B automatically whenever A's timing changes.
When to use client.dependencies
- Modeling sequential workflows where step N must finish before step N+1 starts
- Expressing parallel branches that converge at a common later task
- Adding lag time between tasks (e.g., "wait 24 hours after sending the email before following up")
- Using start-to-start dependencies for tasks that should begin together
Methods
| Method | Description |
|---|---|
create(input) | Define ordering between two tasks |
get(depId) | Fetch a dependency |
update(depId, input) | Update lag time or dependency type |
delete(depId) | Remove the constraint |
list(opts?) | List dependencies by task |
dependencies.create(input)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
fromTaskId | string | yes | The predecessor task |
toTaskId | string | yes | The successor task |
type | DependencyType | no | Dependency type (default: 'finish_to_start') |
lagMinutes | number | no | Minimum wait between predecessor and successor |
Dependency types
| Type | Meaning |
|---|---|
finish_to_start | B starts after A finishes (most common) |
start_to_start | B starts no earlier than A starts |
finish_to_finish | B finishes no earlier than A finishes |
start_to_finish | B finishes no earlier than A starts |
Example
typescript
// Basic sequential dependency
await client.dependencies.create({
fromTaskId: 'tsk_setup',
toTaskId: 'tsk_training',
})
// With a 24-hour lag (send email, then follow up the next day)
await client.dependencies.create({
fromTaskId: 'tsk_send_email',
toTaskId: 'tsk_follow_up',
type: 'finish_to_start',
lagMinutes: 1440, // 24 hours
})
// Parallel tasks that must start together
await client.dependencies.create({
fromTaskId: 'tsk_kickoff',
toTaskId: 'tsk_design_track',
type: 'start_to_start',
})
await client.dependencies.create({
fromTaskId: 'tsk_kickoff',
toTaskId: 'tsk_engineering_track',
type: 'start_to_start',
})dependencies.update(depId, input)
typescript
await client.dependencies.update('dep_abc123', {
lagMinutes: 2880, // increase to 48 hours
})dependencies.list(opts?)
typescript
// Find all dependencies involving a task (as predecessor or successor)
const { data: deps } = await client.dependencies.list({ taskId: 'tsk_abc123' })Cycle detection
Adding a dependency that would create a cycle throws a ClockworkError with code CYCLE_DETECTED. Always validate your graph structure when building workflows programmatically.
typescript
try {
await client.dependencies.create({ fromTaskId: 'tsk_b', toTaskId: 'tsk_a' })
} catch (err) {
if (err instanceof ClockworkError && err.code === 'CYCLE_DETECTED') {
console.error('This dependency would create a cycle')
}
}Type reference
typescript
type DependencyType = 'finish_to_start' | 'start_to_start' | 'finish_to_finish' | 'start_to_finish'
interface Dependency {
id: string
fromTaskId: string
toTaskId: string
type: DependencyType
lagMinutes: number | null
createdAt: string
}