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.

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

More

• Deterministic built-ins
• Cancellation and scopes
  • CancellationScope
  • Trigger
• Sinks
  • Sinks

Enumerations

• ChildWorkflowCancellationType
• ParentClosePolicy
• WorkflowIdReusePolicy

Classes

• CancellationScope
• ContinueAsNew
• DeterminismViolationError
• IllegalStateError
• PayloadConverterError
• Trigger
• ValueError
• WorkflowError
• WorkflowExecutionAlreadyStartedError
• WorkflowNotFoundError

Interfaces

• ActivateInput
• ActivityInput
• BaseWorkflowHandle
• BaseWorkflowOptions
• CancellationScopeOptions
• ChildWorkflowHandle
• ChildWorkflowOptions
• ConcludeActivationInput
• ContinueAsNewInput
• ContinueAsNewOptions
• DisposeInput
• EnhancedStackTrace
• ExternalWorkflowHandle
• FileLocation
• FileSlice
• LocalActivityInput
• ParentWorkflowInfo
• QueryDefinition
• QueryInput
• SDKInfo
• SignalDefinition
• SignalInput
• SignalWorkflowInput
• SinkCall
• StackTrace
• 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

---

LoggerSinks

Re-exports LoggerSinks

---

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

---

UntypedActivities

Re-exports UntypedActivities

---

defaultPayloadConverter

Re-exports defaultPayloadConverter

---

rootCause

Re-exports rootCause

Type Aliases

ActivityInterfaceFor

Ƭ ActivityInterfaceFor<T>: { [K in keyof T]: T[K] extends ActivityFunction ? T[K] : typeof NotAnActivityMethod }

Type helper that takes a type T and transforms attributes that are not ActivityFunction to NotAnActivityMethod.

Example

Used by proxyActivities to get this compile-time error:

interface MyActivities {
  valid(input: number): Promise<number>;
  invalid(input: number): number;
}

const act = proxyActivities<MyActivities>({ startToCloseTimeout: '5m' });

await act.valid(true);
await act.invalid();
// ^ TS complains with:
// (property) invalidDefinition: typeof NotAnActivityMethod
// This expression is not callable.
// Type 'Symbol' has no call signatures.(2349)

Type parameters

Name
T

---

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>

---

Payload

Ƭ Payload: IPayload

---

SearchAttributeValue

Ƭ SearchAttributeValue: string[] | number[] | boolean[] | Date[]

---

SearchAttributes

Ƭ SearchAttributes: Record<string, SearchAttributeValue | undefined>

If another SDK creates a Search Attribute that's not an array, we wrap it in an array.

Dates are serialized as ISO strings.

---

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

---

WithCompiledWorkflowOptions

Ƭ WithCompiledWorkflowOptions<T>: Replace<T, { workflowExecutionTimeout?: IDuration ; workflowRunTimeout?: IDuration ; workflowTaskTimeout?: IDuration }>

Type parameters

Name	Type
T	extends CommonWorkflowOptions

---

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

WorkflowReturnType

---

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

WorkflowInterceptors

---

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

---

NotAnActivityMethod

• Const NotAnActivityMethod: unique symbol

Symbol used in the return type of proxy methods to mark that an attribute on the source type is not a method.

See

• ActivityInterfaceFor
• proxyActivities
• proxyLocalActivities

---

ROOT_SCOPE

• Const ROOT_SCOPE: RootCancellationScope

There can only be one of these

---

enhancedStackTraceQuery

• Const enhancedStackTraceQuery: QueryDefinition<EnhancedStackTrace, []>

---

stackTraceQuery

• Const stackTraceQuery: QueryDefinition<string, []>

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): WithCompiledWorkflowOptions<T>

Type parameters

Name	Type
T	extends CommonWorkflowOptions

Parameters

Name	Type
options	T

Returns

WithCompiledWorkflowOptions<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	number of milliseconds or ms-formatted string

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-As-New the current Workflow Execution with default options.

Shorthand for makeContinueAsNewFunc<F>()(...args). (See: makeContinueAsNewFunc.)

Example

import { continueAsNew } from '@temporalio/workflow';

export async function myWorkflow(n: number): Promise<void> {
 // ... 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<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.
• 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<WorkflowResultType<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

ExternalWorkflowHandle

---

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

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): ActivityInterfaceFor<A>

Configure Activity functions with given ActivityOptions.

This method may be called multiple times to setup Activities with different options.

Example

import { proxyActivities } 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 {
  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
A	UntypedActivities

Parameters

Name	Type
options	ActivityOptions

Returns

ActivityInterfaceFor<A>

a Proxy for which each attribute is a callable Activity function

---

proxyLocalActivities

▸ proxyLocalActivities<A>(options): ActivityInterfaceFor<A>

Configure Local Activity functions with given LocalActivityOptions.

This method may be called multiple times to setup Activities with different options.

See

proxyActivities for examples

Type parameters

Name	Type
A	UntypedActivities

Parameters

Name	Type
options	LocalActivityOptions

Returns

ActivityInterfaceFor<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 - number of milliseconds or ms-formatted string. If given a negative number or 0, 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>>

---

upsertSearchAttributes

▸ upsertSearchAttributes(searchAttributes): void

Updates this Workflow's Search Attributes by merging the provided searchAttributes with the existing Search Attributes, workflowInfo().searchAttributes.

For example, this Workflow code:

upsertSearchAttributes({
  CustomIntField: [1, 2, 3],
  CustomBoolField: [true]
});
upsertSearchAttributes({
  CustomIntField: [42],
  CustomKeywordField: ['durable code', 'is great']
});

would result in the Workflow having these Search Attributes:

{
  CustomIntField: [42],
  CustomBoolField: [true],
  CustomKeywordField: ['durable code', 'is great']
}

Parameters

Name	Type	Description
searchAttributes	SearchAttributes	The Record to merge. Use a value of [] to clear a Search Attribute.

Returns

void

---

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.

⚠️ We recommend calling workflowInfo() whenever accessing WorkflowInfo fields. Some WorkflowInfo fields change during the lifetime of an Execution—like historyLength and searchAttributes—and some may be changeable in the future—like taskQueue.

// GOOD
function myWorkflow() {
  doSomething(workflowInfo().searchAttributes)
  ...
  doSomethingElse(workflowInfo().searchAttributes)
}

// BAD
function myWorkflow() {
  const attributes = workflowInfo().searchAttributes
  doSomething(attributes)
  ...
  doSomethingElse(attributes)
}

#### Returns

[`WorkflowInfo`](../interfaces/workflow.WorkflowInfo.md)