Calling tasks with React hooks
Most of the time, our task-backed components can handle
automatically executing and populating components with the output of a task or runbook. However, you
might want to directly execute a task or runbook in the following situations:
- When using a component that is not task backed (e.g. a
Dialog
orTypography
). - When using a custom, non-Airplane component.
- When you want to do something more custom with a task output than just populate a component. e.g. show different components depending on the output of a task.
We allow direct task execution through the
useTaskQuery
and
useTaskMutation
hooks. When you
use these hooks, you are in charge of populating components with data as well as handling loading
and error states.Usage
useTaskQuery
should be used for tasks that query for data. It has intelligent behavior for queries
like caching and automatically refetching to keep the task output fresh.If you want to control when
useTaskQuery
executes its task, set enabled
to false
and call the
task using the returned refetch
function.useTaskMutation
should be used for tasks that create, update, or delete data.useRunbookMutation
works similarly to useTaskMutation, but is used for executing runbooks instead
of tasks.If a task doesn't require any parameters or special options, you can just pass the task slug:
useTaskQuery("my_task")
or an AirplaneFunc
—the return value of airplane.task()
:
useTaskMutation(myTask)
.API Reference
useTaskQuery
Options
fn: AirplaneFunc
- One of fn or slug are required
- The task to execute. This is the return value of
airplane.task()
. - Example:
useTaskQuery({ fn: MyTask })
slug: string
- One of fn or slug are required
- The slug of the task to execute.
params: object
- Optional
- The params of the task to execute.
enabled: boolean
- Optional
- Defaults to
true
- By default, the task is executed automatically. If set to
false
, the task will not be executed automatically. To execute a disabled task, use the returnedrefetch
function.
refetchInterval: number
- Optional
- If set, the task will be re-exeuted, or refetched, every
refetchInterval
milliseconds.
onSuccess: (output: TOutput, runID: string) => void
- Optional
- Callback on successful task execution.
onError: (output: TOutput | undefined, error: ExecuteError, runID?: string) => void
- Optional
- Callback on failed task execution.
executeOnMount: boolean
- Optional
- Defaults to
true
- If set to
true
, the task will be executed on mount.
executeOnWindowFocus: boolean
- Optional
- Defaults to
true
- If set to
true
, the task will be executed on window focus.
executeOnReconnect: boolean
- Optional
- Defaults to
true
- If set to
true
, the task will be executed on reconnect.
Returns
output: TOutput
- Defaults to
undefined
- The output of the last executed task.
- Defaults to
loading: boolean
- Defaults to
undefined
- Will be
true
when the task is currently executing
- Defaults to
error: { message: string; type: "AIRPLANE_INTERNAL" | "FAILED" }
- Defaults to
undefined
- The error message if the task failed to execute. The type indicates whether the error is due to Airplane failing to execute the task, or due to the task itself failing.
- Defaults to
refetch: () => Promise<{ data: TOutput }>
- Defaults to
undefined
- A function that refetches, or re-executes, the task. This function can also be used to execute a
task manually after the component loads in conjunction with the
enabled
option.
- Defaults to
useTaskMutation
Options
fn: AirplaneFunc
- One of fn or slug are required
- The task to execute. This is the return value of
airplane.task()
. - Example:
useTaskQuery({ fn: MyTask })
slug: string
- One of fn or slug are required
- The slug of the task to execute.
params: object
- Optional
- The params of the task to execute.
refetchTasks: RefetchQuery | RefetchQuery[]
- Optional
- A
RefetchQuery
is either a task slug, anAirplaneFunc
or an object of{ slug?: string; fn: AirplaneFunc?; params?: object }
representing a task. - If set, the provided tasks will be refetched on success.
- This can be useful if you expect the task mutation to invalidate data.
- See refetchTasks on a mutaiton for more information.
onSuccess: (output: TOutput, runID: string) => void
- Optional
- Callback on successful task execution.
onError: (output: TOutput | undefined, error: ExecuteError, runID?: string) => void
- Optional
- Callback on failed task execution.
Returns
output: TOutput
- Defaults to
undefined
- The output of the last executed task.
- Defaults to
loading: boolean
- Defaults to
undefined
- Will be
true
when the task is currently executing
- Defaults to
error: { message: string; type: "AIRPLANE_INTERNAL" | "FAILED" }
- Defaults to
undefined
- The error message if the task failed to execute. The type indicates whether the error is due to Airplane failing to execute the task, or due to the task itself failing.
- Defaults to
mutate: () => void
- A function that executes the task.
useRunbookMutation
Options
slug: string
- Required
- The slug of the runbook to execute.
params: object
- Optional
- The params of the runbook to execute.
refetchTasks: RefetchQuery | RefetchQuery[]
- Optional
- A
RefetchQuery
is either a task slug or an object of{ slug: string; params: object }
representing a task. - If set, the provided tasks will be refetched on success.
- This can be useful if you expect the runbook mutation to invalidate data.
onSuccess: (sessionID: string) => void
- Optional
- Callback on successful runbook execution.
onError: (error: ExecuteError, sessionID?: string) => void
- Optional
- Callback on failed runbook execution.
Returns
loading: boolean
- Defaults to
undefined
- Will be
true
when the runbook is currently executing
- Defaults to
error: { message: string; type: "AIRPLANE_INTERNAL" | "FAILED" }
- Defaults to
undefined
- The error message if the runbook failed to execute. The type indicates whether the error is due to Airplane failing to execute the runbook, or due to the runbook itself failing.
- Defaults to
mutate: () => void
- A function that executes the runbook.
Note that unlike tasks, runbooks do not have outputs.