Namespace: workflow
This library provides tools required for authoring workflows.
Usage
See the tutorial for writing your first workflow.
Timers
The recommended way of scheduling timers is by using the sleep function.
We've replaced setTimeout and clearTimeout with deterministic versions so these are also usable but have a limitation that they don't play well with cancellation scopes.
import { sleep } from '@temporalio/workflow';
export async function sleeper(ms = 100): Promise<void> {
await sleep(ms);
console.log('slept');
}
Activities
To schedule Activities, use proxyActivities to obtain an Activity function and call.
import { proxyActivities } from '@temporalio/workflow';
import type * as activities from '../activities';
const { httpGet } = proxyActivities<typeof activities>({
startToCloseTimeout: '1 minute',
});
export async function http(): Promise<string> {
return await httpGet('https://temporal.io');
}
Signals and Queries
To add signal handlers to a Workflow, add a signals property to the exported workflow object.
Signal handlers can return either void or Promise<void>, you may schedule activities and timers from a signal handler.
To add query handlers to a Workflow, add a queries property to the exported workflow object.
Query handlers must not mutate any variables or generate any commands (like Activities or Timers), they run synchronously and thus must return a Promise.
Implementation
import { CancelledFailure, defineQuery, setHandler, condition } from '@temporalio/workflow';
import { unblockSignal } from './definitions';
export const isBlockedQuery = defineQuery<boolean>('isBlocked');
export async function unblockOrCancel(): Promise<void> {
let isBlocked = true;
setHandler(unblockSignal, () => void (isBlocked = false));
setHandler(isBlockedQuery, () => isBlocked);
try {
console.log('Blocked');
await condition(() => !isBlocked);
isBlocked = false;
console.log('Unblocked');
} catch (err) {
if (!(err instanceof CancelledFailure)) {
throw err;
}
console.log('Cancelled');
}
}
Deterministic built-ins
It is safe to call Math.random() and Date() in workflow code as they are replaced with deterministic versions. We also provide a deterministic uuid4 function for convenience.
Cancellation and scopes
Sinks
Enumerations
Classes
Interfaces
- ActivateInput
- ActivityInfo
- ActivityInput
- BaseWorkflowOptions
- CancellationScopeOptions
- ChildWorkflowHandle
- ChildWorkflowOptions
- ConcludeActivationInput
- ContinueAsNewInput
- ContinueAsNewOptions
- DisposeInput
- ExternalWorkflowHandle
- LocalActivityInput
- QueryDefinition
- QueryInput
- SignalDefinition
- SignalInput
- SignalWorkflowInput
- SinkCall
- StartChildWorkflowExecutionInput
- TimerInput
- WorkflowDurationOptions
- WorkflowExecuteInput
- WorkflowInboundCallsInterceptor
- WorkflowInfo
- WorkflowInterceptors
- WorkflowInternalsInterceptor
- WorkflowOutboundCallsInterceptor
References
ActivityCancellationType
Re-exports ActivityCancellationType
ActivityFailure
Re-exports ActivityFailure
ActivityFunction
Re-exports ActivityFunction
ActivityInterface
Re-exports ActivityInterface
ActivityOptions
Re-exports ActivityOptions
ApplicationFailure
Re-exports ApplicationFailure
CancelledFailure
Re-exports CancelledFailure
ChildWorkflowFailure
Re-exports ChildWorkflowFailure
Headers
Re-exports Headers
IllegalStateError
Re-exports IllegalStateError
Next
Re-exports Next
PayloadConverter
Re-exports PayloadConverter
RetryPolicy
Re-exports RetryPolicy
ServerFailure
Re-exports ServerFailure
TemporalFailure
Re-exports TemporalFailure
TerminatedFailure
Re-exports TerminatedFailure
TimeoutFailure
Re-exports TimeoutFailure
ValueError
Re-exports ValueError
WorkflowExecutionAlreadyStartedError
Re-exports WorkflowExecutionAlreadyStartedError
defaultPayloadConverter
Re-exports defaultPayloadConverter
rootCause
Re-exports rootCause
Type aliases
CommonWorkflowOptions
Ƭ CommonWorkflowOptions: BaseWorkflowOptions & WorkflowDurationOptions
ConcludeActivationOutput
Ƭ ConcludeActivationOutput: ConcludeActivationInput
Output for WorkflowInternalsInterceptor.concludeActivation
ContinueAsNewInputOptions
Ƭ ContinueAsNewInputOptions: ContinueAsNewOptions & Required<Pick<ContinueAsNewOptions, "workflowType">>
Same as ContinueAsNewOptions but workflowType must be defined
Handler
Ƭ Handler<Ret, Args, T>: T extends SignalDefinition<infer A> ? (...args: A) => void | Promise<void> : T extends QueryDefinition<infer R, infer A> ? (...args: A) => R : never
A handler function capable of accepting the arguments for a given SignalDefinition or QueryDefinition.
Type parameters
| Name | Type |
|---|---|
Ret | Ret |
Args | extends any[] |
T | extends SignalDefinition<Args> | QueryDefinition<Ret, Args> |
InternalActivityFunction
Ƭ InternalActivityFunction<P, R>: ActivityFunction<P, R> & ActivityInfo
Type parameters
| Name | Type |
|---|---|
P | extends any[] |
R | R |
Sink
Ƭ Sink: Record<string, SinkFunction>
A mapping of name to function, defines a single sink (e.g. logger)
SinkFunction
Ƭ SinkFunction: (...args: any[]) => void
Type declaration
▸ (...args): void
Any function signature can be used for Sink functions as long as the return type is void.
When calling a Sink function, arguments are copied from the Workflow isolate to the Node.js environment using postMessage.
This constrains the argument types to primitives (excluding Symbols).
Parameters
| Name | Type |
|---|---|
...args | any[] |
Returns
void
Sinks
Ƭ Sinks: Record<string, Sink>
Workflow Sink are a mapping of name to Sink
WithCompiledWorkflowDurationOptions
Ƭ WithCompiledWorkflowDurationOptions<T>: Replace<T, { workflowExecutionTimeout?: IDuration ; workflowRunTimeout?: IDuration ; workflowTaskTimeout?: IDuration }>
Type parameters
| Name | Type |
|---|---|
T | extends WorkflowDurationOptions |
WithWorkflowArgs
Ƭ WithWorkflowArgs<W, T>: T & Parameters<W> extends [any, ...any[]] ? { args: Parameters<W> } : { args?: Parameters<W> }
Type parameters
| Name | Type |
|---|---|
W | extends Workflow |
T | T |
Workflow
Ƭ Workflow: (...args: any[]) => WorkflowReturnType
Type declaration
▸ (...args): WorkflowReturnType
Broad Workflow function definition, specific Workflows will typically use a narrower type definition, e.g:
export async function myWorkflow(arg1: number, arg2: string): Promise<string>;
Parameters
| Name | Type |
|---|---|
...args | any[] |
Returns
WorkflowInterceptorsFactory
Ƭ WorkflowInterceptorsFactory: () => WorkflowInterceptors
Type declaration
▸ (): WorkflowInterceptors
A function that returns WorkflowInterceptors and takes no arguments.
Workflow interceptor modules should export an interceptors function of this type.
example
export function interceptors(): WorkflowInterceptors {
return {
inbound: [], // Populate with list of interceptor implementations
outbound: [], // Populate with list of interceptor implementations
internals: [], // Populate with list of interceptor implementations
};
}
Returns
WorkflowQueryType
Ƭ WorkflowQueryType: (...args: any[]) => any
Type declaration
▸ (...args): any
Parameters
| Name | Type |
|---|---|
...args | any[] |
Returns
any
WorkflowResultType
Ƭ WorkflowResultType<W>: ReturnType<W> extends Promise<infer R> ? R : never
Get the "unwrapped" return type (without Promise) of the execute handler from Workflow type W
Type parameters
| Name | Type |
|---|---|
W | extends Workflow |
WorkflowReturnType
Ƭ WorkflowReturnType: Promise<any>
Type that can be returned from a Workflow execute function
WorkflowSignalType
Ƭ WorkflowSignalType: (...args: any[]) => Promise<void> | void
Type declaration
▸ (...args): Promise<void> | void
Parameters
| Name | Type |
|---|---|
...args | any[] |
Returns
Promise<void> | void
Variables
AsyncLocalStorage
• Const AsyncLocalStorage: <T>() => ALS<T>
Type declaration
• <T>()
Type parameters
| Name |
|---|
T |
ROOT_SCOPE
• Const ROOT_SCOPE: RootCancellationScope
There can only be one of these
Functions
addDefaultWorkflowOptions
▸ addDefaultWorkflowOptions<T>(opts): ChildWorkflowOptionsWithDefaults
Adds default values to workflowId and workflowIdReusePolicy to given workflow options.
Type parameters
| Name | Type |
|---|---|
T | extends Workflow |
Parameters
| Name | Type |
|---|---|
opts | WithWorkflowArgs<T, ChildWorkflowOptions> |
Returns
ChildWorkflowOptionsWithDefaults
compileWorkflowOptions
▸ compileWorkflowOptions<T>(options): WithCompiledWorkflowDurationOptions<T>
Type parameters
| Name | Type |
|---|---|
T | extends WorkflowDurationOptions |
Parameters
| Name | Type |
|---|---|
options | T |
Returns
WithCompiledWorkflowDurationOptions<T>
condition
▸ condition(fn, timeout): Promise<boolean>
Returns a Promise that resolves when fn evaluates to true or timeout expires.
Parameters
| Name | Type | Description |
|---|---|---|
fn | () => boolean | - |
timeout | string | number | ms formatted string or number of milliseconds |
Returns
Promise<boolean>
a boolean indicating whether the condition was true before the timeout expires
▸ condition(fn): Promise<void>
Returns a Promise that resolves when fn evaluates to true.
Parameters
| Name | Type |
|---|---|
fn | () => boolean |
Returns
Promise<void>
continueAsNew
▸ continueAsNew<F>(...args): Promise<never>
Continues current Workflow execution as new with default options.
Shorthand for makeContinueAsNewFunc<F>()(...args).
example
import { continueAsNew } from '@temporalio/workflow';
export function myWorkflow(n: number) {
return {
async execute() {
// ... Workflow logic
await continueAsNew<typeof myWorkflow>(n + 1);
}
};
}
Type parameters
| Name | Type |
|---|---|
F | extends Workflow |
Parameters
| Name | Type |
|---|---|
...args | Parameters<F> |
Returns
Promise<never>
defineQuery
▸ defineQuery<Ret, Args>(name): QueryDefinition<Ret, Args>
Define a query method for a Workflow.
Definitions are used to register handler in the Workflow via setHandler and to query Workflows using a WorkflowHandle. Definitions can be reused in multiple Workflows.
Type parameters
| Name | Type |
|---|---|
Ret | Ret |
Args | extends any[] = [] |
Parameters
| Name | Type |
|---|---|
name | string |
Returns
QueryDefinition<Ret, Args>
defineSignal
▸ defineSignal<Args>(name): SignalDefinition<Args>
Define a signal method for a Workflow.
Definitions are used to register handler in the Workflow via setHandler and to signal Workflows using a WorkflowHandle, ChildWorkflowHandle or ExternalWorkflowHandle. Definitions can be reused in multiple Workflows.
Type parameters
| Name | Type |
|---|---|
Args | extends any[] = [] |
Parameters
| Name | Type |
|---|---|
name | string |
Returns
SignalDefinition<Args>
deprecatePatch
▸ deprecatePatch(patchId): void
Indicate that a patch is being phased out.
See docs page for info.
Workflows with this call may be deployed alongside workflows with a patched call, but they must not be deployed while any workers still exist running old code without a patched call, or any runs with histories produced by such workers exist. If either kind of worker encounters a history produced by the other, their behavior is undefined.
Once all live workflow runs have been produced by workers with this call, you can deploy workers which are free of either kind of patch call for this ID. Workers with and without this call may coexist, as long as they are both running the "new" code.
Parameters
| Name | Type | Description |
|---|---|---|
patchId | string | An identifier that should be unique to this patch. It is OK to use multiple calls with the same ID, which means all such calls will always return the same value. |
Returns
void
executeChild
▸ executeChild<T>(workflowType, options): Promise<WorkflowResultType<T>>
Start a child Workflow execution and await its completion.
- By default, a child will be scheduled on the same task queue as its parent.
- This operation is cancellable using CancellationScopes.
Type parameters
| Name | Type |
|---|---|
T | extends Workflow |
Parameters
| Name | Type |
|---|---|
workflowType | string |
options | WithWorkflowArgs<T, ChildWorkflowOptions> |
Returns
Promise<WorkflowResultType<T>>
The result of the child Workflow.
▸ executeChild<T>(workflowType, options): Promise<WorkflowResultType<T>>
Start a child Workflow execution and await its completion.
- By default, a child will be scheduled on the same task queue as its parent.
- Deduces the Workflow type and signature from provided Workflow function.
- This operation is cancellable using CancellationScopes.
Type parameters
| Name | Type |
|---|---|
T | extends Workflow |
Parameters
| Name | Type |
|---|---|
workflowType | T |
options | WithWorkflowArgs<T, ChildWorkflowOptions> |
Returns
Promise<WorkflowResultType<T>>
The result of the child Workflow.
▸ executeChild<T>(workflowType): Promise<WorkflowResultType<T>>
Start a child Workflow execution and await its completion.
Override for Workflows that accept no arguments.
- The child will be scheduled on the same task queue as its parent.
- This operation is cancellable using CancellationScopes.
Type parameters
| Name | Type |
|---|---|
T | extends () => WorkflowReturnType |
Parameters
| Name | Type |
|---|---|
workflowType | string |
Returns
Promise<WorkflowResultType<T>>
The result of the child Workflow.
▸ executeChild<T>(workflowFunc): Promise<ChildWorkflowHandle<T>>
Start a child Workflow execution and await its completion.
Override for Workflows that accept no arguments.
- The child will be scheduled on the same task queue as its parent.
- Deduces the Workflow type and signature from provided Workflow function.
- This operation is cancellable using CancellationScopes.
Type parameters
| Name | Type |
|---|---|
T | extends () => WorkflowReturnType |
Parameters
| Name | Type |
|---|---|
workflowFunc | T |
Returns
Promise<ChildWorkflowHandle<T>>
The result of the child Workflow.
getExternalWorkflowHandle
▸ getExternalWorkflowHandle(workflowId, runId?): ExternalWorkflowHandle
Returns a client-side handle that can be used to signal and cancel an existing Workflow execution. It takes a Workflow ID and optional run ID.
Parameters
| Name | Type |
|---|---|
workflowId | string |
runId? | string |
Returns
inWorkflowContext
▸ inWorkflowContext(): boolean
Returns whether or not code is executing in workflow context
Returns
boolean
isCancellation
▸ isCancellation(err): boolean
Returns whether provided err is caused by cancellation
Parameters
| Name | Type |
|---|---|
err | unknown |
Returns
boolean
makeContinueAsNewFunc
▸ makeContinueAsNewFunc<F>(options?): (...args: Parameters<F>) => Promise<never>
Returns a function f that will cause the current Workflow to ContinueAsNew when called.
f takes the same arguments as the Workflow execute function supplied to typeparam F.
Once f is called, Workflow execution immediately completes.
Type parameters
| Name | Type |
|---|---|
F | extends Workflow |
Parameters
| Name | Type |
|---|---|
options? | ContinueAsNewOptions |
Returns
fn
▸ (...args): Promise<never>
Returns a function f that will cause the current Workflow to ContinueAsNew when called.
f takes the same arguments as the Workflow execute function supplied to typeparam F.
Once f is called, Workflow execution immediately completes.
Parameters
| Name | Type |
|---|---|
...args | Parameters<F> |
Returns
Promise<never>
patched
▸ patched(patchId): boolean
Patch or upgrade workflow code by checking or stating that this workflow has a certain patch.
See docs page for info.
If the workflow is replaying an existing history, then this function returns true if that
history was produced by a worker which also had a patched call with the same patchId.
If the history was produced by a worker without such a call, then it will return false.
If the workflow is not currently replaying, then this call always returns true.
Your workflow code should run the "new" code if this returns true, if it returns false, you should run the "old" code. By doing this, you can maintain determinism.
Parameters
| Name | Type | Description |
|---|---|---|
patchId | string | An identifier that should be unique to this patch. It is OK to use multiple calls with the same ID, which means all such calls will always return the same value. |
Returns
boolean
proxyActivities
▸ proxyActivities<A>(options): A
Configure Activity functions with given ActivityOptions.
This method may be called multiple times to setup Activities with different options.
example
import { proxyActivities, ActivityInterface } from '@temporalio/workflow';
import * as activities from '../activities';
// Setup Activities from module exports
const { httpGet, otherActivity } = proxyActivities<typeof activities>({
startToCloseTimeout: '30 minutes',
});
// Setup Activities from an explicit interface (e.g. when defined by another SDK)
interface JavaActivities extends ActivityInterface {
httpGetFromJava(url: string): Promise<string>
someOtherJavaActivity(arg1: number, arg2: string): Promise<string>;
}
const {
httpGetFromJava,
someOtherJavaActivity
} = proxyActivities<JavaActivities>({
taskQueue: 'java-worker-taskQueue',
startToCloseTimeout: '5m',
});
export function execute(): Promise<void> {
const response = await httpGet('http://example.com');
// ...
}
Type parameters
| Name | Type | Description |
|---|---|---|
A | extends ActivityInterface | An ActivityInterface - mapping of name to function |
Parameters
| Name | Type |
|---|---|
options | ActivityOptions |
Returns
A
a Proxy for which each attribute is a callable Activity function
proxyLocalActivities
▸ proxyLocalActivities<A>(options): A
Configure Local Activity functions with given LocalActivityOptions.
This method may be called multiple times to setup Activities with different options.
experimental
See proxyActivities for examples
Type parameters
| Name | Type | Description |
|---|---|---|
A | extends ActivityInterface | An ActivityInterface - mapping of name to function |
Parameters
| Name | Type |
|---|---|
options | LocalActivityOptions |
Returns
A
a Proxy for which each attribute is a callable Activity function
proxySinks
▸ proxySinks<T>(): T
Get a reference to Sinks for exporting data out of the Workflow.
These Sinks must be registered with the Worker in order for this mechanism to work.
example
import { proxySinks, Sinks } from '@temporalio/workflow';
interface MySinks extends Sinks {
logger: {
info(message: string): void;
error(message: string): void;
};
}
const { logger } = proxySinks<MyDependencies>();
logger.info('setting up');
export function myWorkflow() {
return {
async execute() {
logger.info('hey ho');
logger.error('lets go');
}
};
}
Type parameters
| Name | Type |
|---|---|
T | extends Sinks |
Returns
T
setHandler
▸ setHandler<Ret, Args, T>(def, handler): void
Set a handler function for a Workflow query or signal.
If this function is called multiple times for a given signal or query name the last handler will overwrite any previous calls.
Type parameters
| Name | Type |
|---|---|
Ret | Ret |
Args | extends any[] |
T | extends SignalDefinition<Args> | QueryDefinition<Ret, Args> |
Parameters
| Name | Type | Description |
|---|---|---|
def | T | a SignalDefinition or QueryDefinition as returned by defineSignal or defineQuery respectively. |
handler | undefined | Handler<Ret, Args, T> | a compatible handler function for the given definition or undefined to unset the handler. |
Returns
void
sleep
▸ sleep(ms): Promise<void>
Asynchronous sleep.
Schedules a timer on the Temporal service.
Parameters
| Name | Type | Description |
|---|---|---|
ms | string | number | sleep duration - ms formatted string or number of milliseconds. If given a negative number, value will be set to 1. |
Returns
Promise<void>
startChild
▸ startChild<T>(workflowType, options): Promise<ChildWorkflowHandle<T>>
Start a child Workflow execution
- Returns a client-side handle that implements a child Workflow interface.
- By default, a child will be scheduled on the same task queue as its parent.
A child Workflow handle supports awaiting completion, signaling and cancellation via CancellationScopes. In order to query the child, use a WorkflowClient from an Activity.
Type parameters
| Name | Type |
|---|---|
T | extends Workflow |
Parameters
| Name | Type |
|---|---|
workflowType | string |
options | WithWorkflowArgs<T, ChildWorkflowOptions> |
Returns
Promise<ChildWorkflowHandle<T>>
▸ startChild<T>(workflowFunc, options): Promise<ChildWorkflowHandle<T>>
Start a child Workflow execution
- Returns a client-side handle that implements a child Workflow interface.
- Deduces the Workflow type and signature from provided Workflow function.
- By default, a child will be scheduled on the same task queue as its parent.
A child Workflow handle supports awaiting completion, signaling and cancellation via CancellationScopes. In order to query the child, use a WorkflowClient from an Activity.
Type parameters
| Name | Type |
|---|---|
T | extends Workflow |
Parameters
| Name | Type |
|---|---|
workflowFunc | T |
options | WithWorkflowArgs<T, ChildWorkflowOptions> |
Returns
Promise<ChildWorkflowHandle<T>>
▸ startChild<T>(workflowType): Promise<ChildWorkflowHandle<T>>
Start a child Workflow execution
Override for Workflows that accept no arguments.
- Returns a client-side handle that implements a child Workflow interface.
- The child will be scheduled on the same task queue as its parent.
A child Workflow handle supports awaiting completion, signaling and cancellation via CancellationScopes. In order to query the child, use a WorkflowClient from an Activity.
Type parameters
| Name | Type |
|---|---|
T | extends () => Promise<any> |
Parameters
| Name | Type |
|---|---|
workflowType | string |
Returns
Promise<ChildWorkflowHandle<T>>
▸ startChild<T>(workflowFunc): Promise<ChildWorkflowHandle<T>>
Start a child Workflow execution
Override for Workflows that accept no arguments.
- Returns a client-side handle that implements a child Workflow interface.
- Deduces the Workflow type and signature from provided Workflow function.
- The child will be scheduled on the same task queue as its parent.
A child Workflow handle supports awaiting completion, signaling and cancellation via CancellationScopes. In order to query the child, use a WorkflowClient from an Activity.
Type parameters
| Name | Type |
|---|---|
T | extends () => Promise<any> |
Parameters
| Name | Type |
|---|---|
workflowFunc | T |
Returns
Promise<ChildWorkflowHandle<T>>
uuid4
▸ uuid4(): string
Generate an RFC compliant V4 uuid. Uses the workflow's deterministic PRNG making it safe for use within a workflow. This function is cryptographically insecure. See the stackoverflow discussion.
Returns
string
workflowInfo
▸ workflowInfo(): WorkflowInfo
Get information about the current Workflow