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 { sendEmail } = proxyActivities<typeof activities>({
  startToCloseTimeout: '1 minute',
});

export async function sampleWorkflow(): Promise<string> {
 await sendEmail("to@example.com","Hello, Temporal!");
}

Updates, Signals and Queries

Use setHandler to set handlers for Updates, Signals, and Queries.

Update and Signal handlers can be either async or non-async functions. Update handlers may return a value, but signal handlers may not (return void or Promise<void>). You may use Activities, Timers, child Workflows, etc in Update and Signal handlers, but this should be done cautiously: for example, note that if you await async operations such as these in an Update or Signal handler, then you are responsible for ensuring that the workflow does not complete first.

Query handlers may not be async functions, and may not mutate any variables or use Activities, Timers, child Workflows, etc.

Implementation

export const incrementSignal = wf.defineSignal<[number]>('increment');
export const getValueQuery = wf.defineQuery<number>('getValue');
export const incrementAndGetValueUpdate = wf.defineUpdate<number, [number]>('incrementAndGetValue');

export async function counterWorkflow(initialValue: number): Promise<void> {
  let count = initialValue;
  wf.setHandler(incrementSignal, (arg: number) => {
    count += arg;
  });
  wf.setHandler(getValueQuery, () => count);
  wf.setHandler(incrementAndGetValueUpdate, (arg: number): number => {
    count += arg;
    return count;
  });
  await wf.condition(() => false);
}

Classes

Interfaces

References

Headers

Re-exports Headers

IllegalStateError

Re-exports IllegalStateError

NamespaceNotFoundError

Re-exports NamespaceNotFoundError

Re-exports Next

Payload

Re-exports Payload

PayloadConverter

Re-exports PayloadConverter

PayloadConverterError

Re-exports PayloadConverterError

QueryDefinition

Re-exports QueryDefinition

RetryPolicy

Re-exports RetryPolicy

SearchAttributeValue

Re-exports SearchAttributeValue

SearchAttributes

Re-exports SearchAttributes

ServerFailure

Re-exports ServerFailure

SignalDefinition

Re-exports SignalDefinition

TemporalFailure

Re-exports TemporalFailure

TerminatedFailure

Re-exports TerminatedFailure

TimeoutFailure

Re-exports TimeoutFailure

UntypedActivities

Re-exports UntypedActivities

ValueError

Re-exports ValueError

WithWorkflowArgs

Re-exports WithWorkflowArgs

Workflow

Re-exports Workflow

WorkflowDurationOptions

Re-exports WorkflowDurationOptions

WorkflowIdConflictPolicy

Re-exports WorkflowIdConflictPolicy

WorkflowIdReusePolicy

Re-exports WorkflowIdReusePolicy

WorkflowNotFoundError

Re-exports WorkflowNotFoundError

WorkflowQueryOptions

Re-exports WorkflowQueryOptions

WorkflowQueryType

Re-exports WorkflowQueryType

WorkflowResultType

Re-exports WorkflowResultType

WorkflowReturnType

Re-exports WorkflowReturnType

WorkflowSignalOptions

Re-exports WorkflowSignalOptions

WorkflowSignalType

Re-exports WorkflowSignalType

WorkflowTypeOptions

Re-exports WorkflowTypeOptions

decodeWorkflowIdConflictPolicy

Re-exports decodeWorkflowIdConflictPolicy

decodeWorkflowIdReusePolicy

Re-exports decodeWorkflowIdReusePolicy

defaultPayloadConverter

Re-exports defaultPayloadConverter

encodeWorkflowIdConflictPolicy

Re-exports encodeWorkflowIdConflictPolicy

encodeWorkflowIdReusePolicy

Re-exports encodeWorkflowIdReusePolicy

extractWorkflowType

Re-exports extractWorkflowType

extractWorkflowTypeAndConfig

Re-exports extractWorkflowTypeAndConfig

rootCause

Re-exports rootCause

Type Aliases

ActivityFunctionWithOptions

Ƭ ActivityFunctionWithOptions<T>: T & { executeWithOptions: (options: ActivityOptions, args: Parameters<T>) => Promise<Awaited<ReturnType<T>>> }

Type parameters

Name	Type
`T`	extends `ActivityFunction`

ActivityInterfaceFor

Ƭ ActivityInterfaceFor<T>: { [K in keyof T]: T[K] extends ActivityFunction ? ActivityFunctionWithOptions<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`

ChildWorkflowCancellationType

Ƭ ChildWorkflowCancellationType: typeof ChildWorkflowCancellationType[keyof typeof ChildWorkflowCancellationType]

ConcludeActivationOutput

Ƭ ConcludeActivationOutput: ConcludeActivationInput

Output for WorkflowInternalsInterceptor.concludeActivation

ContinueAsNewInputOptions

Ƭ ContinueAsNewInputOptions: ContinueAsNewOptions & Required<Pick<ContinueAsNewOptions, "workflowType">>

Input for WorkflowOutboundCallsInterceptor.continueAsNew.

GetLogAttributesInput

Ƭ GetLogAttributesInput: Record<string, unknown>

Input for WorkflowOutboundCallsInterceptor.getLogAttributes.

GetMetricTagsInput

Ƭ GetMetricTagsInput: MetricTags

Input for WorkflowOutboundCallsInterceptor.getMetricTags.

LocalActivityFunctionWithOptions

Ƭ LocalActivityFunctionWithOptions<T>: T & { executeWithOptions: (options: LocalActivityOptions, args: Parameters<T>) => Promise<Awaited<ReturnType<T>>> }

Type parameters

Name	Type
`T`	extends `ActivityFunction`

LocalActivityInterfaceFor

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

The local activity counterpart to ActivityInterfaceFor

Type parameters

Name
`T`

NexusOperationCancellationType

Ƭ NexusOperationCancellationType: typeof NexusOperationCancellationType[keyof typeof NexusOperationCancellationType]

ParentClosePolicy

Ƭ ParentClosePolicy: typeof ParentClosePolicy[keyof typeof ParentClosePolicy]

SignalWithStartWorkflowRequest

Ƭ SignalWithStartWorkflowRequest<WorkflowFn, SignalValue, SignalArgs>: ReplaceSignalWithStartWorkflowRequest<{ args?: ReadonlyArray<unknown> | Readonly<Parameters<WorkflowFn>> ; cronSchedule?: string ; executionTimeout?: Duration ; headers?: Record<string, unknown> ; id: string ; idConflictPolicy?: WorkflowIdConflictPolicy ; idReusePolicy?: WorkflowIdReusePolicy ; memo?: Record<string, unknown> ; namespace: string ; priority?: Priority ; retryPolicy?: RetryPolicy ; runTimeout?: Duration ; searchAttributes?: TypedSearchAttributes ; signal: string | SignalValue ; signalArgs?: ReadonlyArray<unknown> | Readonly<SignalArgs> ; startDelay?: Duration ; staticDetails?: string ; staticSummary?: string ; taskQueue: string ; taskTimeout?: Duration ; versioningOverride?: VersioningOverride ; workflow: string | WorkflowFn }, { args?: ReadonlyArray<unknown> ; workflow: string } | { workflow: WorkflowFn } & Parameters<WorkflowFn> extends [any, ...(...)[]] ? { args: Parameters<...> | Readonly<...> } : { args?: Parameters<...> | Readonly<...> } & { signal: string ; signalArgs?: ReadonlyArray<unknown> } | { signal: SignalValue } & SignalArgs extends [any, ...(...)[]] ? { signalArgs: SignalArgs | Readonly<...> } : { signalArgs?: SignalArgs | Readonly<...> }>

This API is experimental and subject to change.

Type parameters

Name	Type
`WorkflowFn`	extends (...`args`: `any`[]) => `Promise`<`any`> = (...`args`: `any`[]) => `Promise`<`any`>
`SignalValue`	extends `SignalDefinition`<`any`[]> = `SignalDefinition`<`any`[]>
`SignalArgs`	extends `any`[] = `SignalValue` extends `SignalDefinition`<infer Args, `any`> ? `Args` : `never`

Sink

Ƭ Sink: Record<string, SinkFunction>

A mapping of name to function, defines a single sink (e.g. logger)

SinkFunction

Ƭ SinkFunction: (...args: any[]) => 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).

Type declaration

▸ (...args): void

Parameters

Name	Type
`...args`	`any`[]

Returns

void

Sinks

Ƭ Sinks: Record<string, Sink>

Workflow Sink are a mapping of name to Sink

WorkflowInterceptorsFactory

Ƭ WorkflowInterceptorsFactory: () => WorkflowInterceptors

A function that instantiates WorkflowInterceptors.

Workflow interceptor modules should export an interceptors function of this type.

Example

export function interceptors(): WorkflowInterceptors {
  return {
    inbound: [],   // Populate with list of inbound interceptor implementations
    outbound: [],  // Populate with list of outbound interceptor implementations
    internals: [], // Populate with list of internals interceptor implementations
  };
}

Type declaration

▸ (): WorkflowInterceptors

Returns

WorkflowInterceptors

Variables

AsyncLocalStorage

• Const AsyncLocalStorage: <T>() => ALS<T>

Type declaration

• <T>(): ALS<T>

Type parameters

Name
`T`

Returns

ALS<T>

ChildWorkflowCancellationType

• Const ChildWorkflowCancellationType: Object

Determines:

whether cancellation requests should be propagated from the Parent Workflow to the Child, and
whether and when should the Child's cancellation be reported back to the Parent Workflow (i.e. at which moment should the executeChild's or ChildWorkflowHandle.result's promise fail with a ChildWorkflowFailure, with cause set to a CancelledFailure).

Note that this setting only applies to cancellation originating from an external request for the Parent Workflow itself, or from internal cancellation of the CancellationScope in which the Child Workflow call was made. Eventual Cancellation of a Child Workflow on completion of the Parent Workflow is controlled by the ParentClosePolicy setting.

Default

ChildWorkflowCancellationType.WAIT_CANCELLATION_COMPLETED

Type declaration

Name	Type	Description
`ABANDON`	`"ABANDON"`	Do not propagate cancellation requests to the Child, and immediately report cancellation to the caller.
`TRY_CANCEL`	`"TRY_CANCEL"`	Propagate cancellation request from the Parent Workflow to the Child, yet immediately report cancellation to the caller, i.e. without waiting for the server to confirm the cancellation request. Note that this cancellation type provides no guarantee, from the Parent-side, that the cancellation request will actually be atomically added to the Child workflow's history. In particular, the Child may complete (either successfully or uncessfully) before the cancellation is delivered, resulting in a situation where the Parent workflow thinks its child was cancelled, but the child actually completed successfully. To guarantee that the Child will eventually be notified of the cancellation request, use WAIT_CANCELLATION_REQUESTED.
`WAIT_CANCELLATION_COMPLETED`	`"WAIT_CANCELLATION_COMPLETED"`	Propagate cancellation request from the Parent Workflow to the Child, then wait for completion of the Child Workflow. The Child may respect cancellation, in which case the Parent's `executeChild` or `ChildWorkflowHandle.result` promise will fail with a `ChildWorkflowFailure`, with `cause` set to a `CancelledFailure`. On the other hand, the Child may ignore the cancellation request, in which case the corresponding promise will either resolve with a result (if Child completed successfully) or reject with a different cause (if Child completed uncessfully). `Default` `ts`
`WAIT_CANCELLATION_REQUESTED`	`"WAIT_CANCELLATION_REQUESTED"`	Propagate cancellation request from the Parent Workflow to the Child, then wait for the server to confirm that the Child Workflow cancellation request was recorded in its history. This cancellation type guarantees that the Child will eventually be notified of the cancellation request (that is, unless the Child terminates inbetween due to unexpected causes).

NexusOperationCancellationType

• Const NexusOperationCancellationType: Object

Determines:

whether cancellation requests should be propagated from the Workflow to the Nexus Operation
whether and when should the Operation's cancellation be reported back to the Workflow (i.e. at which moment should the operation's result promise fail with a NexusOperationFailure, with cause set to a CancelledFailure).

Note that this setting only applies to cancellation originating from an external request for the Workflow itself, or from internal cancellation of the CancellationScope in which the Operation call was made.

Type declaration

Name	Type	Description
`ABANDON`	`"ABANDON"`	Do not propagate cancellation requests to the Nexus Operation, and immediately report cancellation to the caller.
`TRY_CANCEL`	`"TRY_CANCEL"`	Initiate a cancellation request for the Nexus operation and immediately report cancellation to the caller. Note that it doesn't guarantee that cancellation is delivered to the operation if calling workflow exits before the delivery is done. If you want to ensure that cancellation is delivered to the operation, use WAIT_CANCELLATION_REQUESTED. Propagate cancellation request from the Workflow to the Operation, yet immediately report cancellation to the caller, i.e. without waiting for the server to confirm the cancellation request. Note that this cancellation type provides no guarantee, from the Workflow-side, that the cancellation request will be delivered to the Operation Handler. In particular, either the Operation or the Workflow may complete (either successfully or uncessfully) before the cancellation request is delivered, resulting in a situation where the Operation completed successfully, but the Workflow thinks it was cancelled. To guarantee that the Operation will eventually be notified of the cancellation request, use WAIT_CANCELLATION_REQUESTED.
`WAIT_CANCELLATION_COMPLETED`	`"WAIT_CANCELLATION_COMPLETED"`	Propagate cancellation request from the Workflow to the Operation, then wait for completion of the Operation.
`WAIT_CANCELLATION_REQUESTED`	`"WAIT_CANCELLATION_REQUESTED"`	Propagate cancellation request from the Workflow to the Operation, then wait for the server to confirm that the Operation cancellation request was delivered to the Operation Handler.

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

ParentClosePolicy

• Const ParentClosePolicy: Object

How a Child Workflow reacts to the Parent Workflow reaching a Closed state.

See

Parent Close Policy

Type declaration

Name	Type	Description
`ABANDON`	`"ABANDON"`	When the Parent is Closed, nothing is done to the Child.
`PARENT_CLOSE_POLICY_ABANDON`	`"ABANDON"`	When the Parent is Closed, nothing is done to the Child. `Deprecated` Use ParentClosePolicy.ABANDON instead.
`PARENT_CLOSE_POLICY_REQUEST_CANCEL`	`"REQUEST_CANCEL"`	When the Parent is Closed, the Child is Cancelled. `Deprecated` Use ParentClosePolicy.REQUEST_CANCEL instead.
`PARENT_CLOSE_POLICY_TERMINATE`	`"TERMINATE"`	When the Parent is Closed, the Child is Terminated. `Deprecated` Use ParentClosePolicy.TERMINATE instead.
`PARENT_CLOSE_POLICY_UNSPECIFIED`	`undefined`	If a `ParentClosePolicy` is set to this, or is not set at all, the server default value will be used. `Deprecated` Either leave property `undefined`, or set an explicit policy instead.
`REQUEST_CANCEL`	`"REQUEST_CANCEL"`	When the Parent is Closed, the Child is Cancelled.
`TERMINATE`	`"TERMINATE"`	When the Parent is Closed, the Child is Terminated. `Default` `ts`

enhancedStackTraceQuery

• Const enhancedStackTraceQuery: QueryDefinition<EnhancedStackTrace, [], string>

log

• Const log: WorkflowLogger

Default workflow logger.

This logger is replay-aware and will omit log messages on workflow replay. Messages emitted by this logger are funnelled through a sink that forwards them to the logger registered on Runtime.logger.

Attributes from the current Workflow Execution context are automatically included as metadata on every log entries. An extra sdkComponent metadata attribute is also added, with value workflow; this can be used for fine-grained filtering of log entries further downstream.

To customize log attributes, register a WorkflowOutboundCallsInterceptor that intercepts the getLogAttributes() method.

Notice that since sinks are used to power this logger, any log attributes must be transferable via the postMessage API.

NOTE: Specifying a custom logger through defaultSink or by manually registering a sink named defaultWorkerLogger has been deprecated. Please use Runtime.logger instead.

metricMeter

• Const metricMeter: MetricMeter

A MetricMeter that can be used to emit metrics from within a Workflow.

The Metric API is an experimental feature and may be subject to change.

stackTraceQuery

• Const stackTraceQuery: QueryDefinition<string, [], string>

workflowMetadataQuery

• Const workflowMetadataQuery: QueryDefinition<IWorkflowMetadata, [], string>

workflowRandom

• Const workflowRandom: WorkflowRandomStream

The default deterministic random stream for the current workflow execution.

This exposes the same underlying sequence used by workflow-level Math.random() when no named override is active. It can be useful for plugin/interceptor code that wants an explicit handle to the main workflow random stream, including from inside a temporary named scope established by another WorkflowRandomStream.

This API may be removed or changed in the future.

Functions

addDefaultWorkflowOptions

▸ addDefaultWorkflowOptions<T>(opts): ChildWorkflowOptionsWithDefaults

Adds default values of workflowId and cancellationType to given workflow options.

Type parameters

Name	Type
`T`	extends `Workflow`

Parameters

Name	Type
`opts`	`WithWorkflowArgs`<`T`, `ChildWorkflowOptions`>

Returns

ChildWorkflowOptionsWithDefaults

allHandlersFinished

▸ allHandlersFinished(): boolean

Whether update and signal handlers have finished executing.

Consider waiting on this condition before workflow return or continue-as-new, to prevent interruption of in-progress handlers by workflow exit:

await workflow.condition(workflow.allHandlersFinished)

Returns

boolean

true if there are no in-progress update or signal handler executions.

condition

▸ condition(fn, timeout, options): Promise<boolean>

Returns a Promise that resolves when fn evaluates to true or timeout expires, providing options to configure the timer (i.e. provide metadata)

Parameters

Name	Type	Description
`fn`	() => `boolean`	-
`timeout`	`Duration`	number of milliseconds or ms-formatted string
`options`	`TimerOptions`	-

Returns

Promise<boolean>

a boolean indicating whether the condition was true before the timeout expires

TimerOptions is a new addition and subject to change

▸ 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`	`Duration`	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.)

Type parameters

Name	Type
`F`	extends `Workflow`

Parameters

Name	Type
`...args`	`Parameters`<`F`>

Returns

Promise<never>

Example

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

export async function myWorkflow(n: number): Promise<void> {
  // ... Workflow logic
  await continueAsNew<typeof myWorkflow>(n + 1);
}

createEventGroup

▸ createEventGroup(id, options?): EventGroup

Create an Event Group that can be attached to commands scheduled by this Workflow.

Attach the returned group via command eventGroups options, or via EventGroup.withScope.

Parameters

Name	Type	Description
`id`	`string`	non-empty group identity. Commands with the same `id` belong to the same group. The user-provided ID is stored as plain text in the workflow history and should therefore not contain sensitive information.
`options?`	`Object`	-
`options.label?`	`string`	optional non-empty display text for the UI / CLI. If provided, it is persisted to history as a codec-encoded Payload. Event Groups is an experimental API and may change without notice.

Returns

EventGroup

createNexusServiceClient

▸ createNexusServiceClient<T>(options): NexusServiceClient<T>

Create a Nexus client for invoking Nexus Operations from a Workflow.

Type parameters

Name	Type
`T`	extends `ServiceDefinition`<`OperationMap`>

Parameters

Name	Type
`options`	`NexusServiceClientOptions`<`T`>

Returns

NexusServiceClient<T>

currentUpdateInfo

▸ currentUpdateInfo(): UpdateInfo | undefined

Get information about the current update if any.

Returns

UpdateInfo | undefined

Info for the current update handler the code calling this is executing within if any.

defineQuery

▸ defineQuery<Ret, Args, Name>(name, options?): QueryDefinition<Ret, Args, Name>

Define a query method for a Workflow.

A definition is used to register a handler in the Workflow via setHandler and to query a Workflow using a WorkflowHandle. A definition can be reused in multiple Workflows.

Type parameters

Name	Type
`Ret`	`Ret`
`Args`	extends `any`[] = []
`Name`	extends `string` = `string`

Parameters

Name	Type
`name`	`Name`
`options?`	`QueryDefinitionOptions`

Returns

QueryDefinition<Ret, Args, Name>

defineSignal

▸ defineSignal<Args, Name>(name, options?): SignalDefinition<Args, Name>

Define a signal method for a Workflow.

A definition is used to register a handler in the Workflow via setHandler and to signal a Workflow using a WorkflowHandle, ChildWorkflowHandle or ExternalWorkflowHandle. A definition can be reused in multiple Workflows.

Type parameters

Name	Type
`Args`	extends `any`[] = []
`Name`	extends `string` = `string`

Parameters

Name	Type	Description
`name`	`Name`	-
`options?`	`SignalDefinitionOptions`	optional type information used to convert Signal arguments

Returns

SignalDefinition<Args, Name>

defineUpdate

▸ defineUpdate<Ret, Args, Name>(name, options?): UpdateDefinition<Ret, Args, Name>

Define an update method for a Workflow.

A definition is used to register a handler in the Workflow via setHandler and to update a Workflow using a WorkflowHandle, ChildWorkflowHandle or ExternalWorkflowHandle. A definition can be reused in multiple Workflows.

Type parameters

Name	Type
`Ret`	`Ret`
`Args`	extends `any`[] = []
`Name`	extends `string` = `string`

Parameters

Name	Type
`name`	`Name`
`options?`	`UpdateDefinitionOptions`

Returns

UpdateDefinition<Ret, Args, Name>

defineWorkflowOptions

▸ defineWorkflowOptions<A, RT>(fn, config): void

Attach per-execution options and static metadata to a Workflow function.

Static options are available before the Workflow function's arguments are decoded.

Type parameters

Name	Type
`A`	extends `any`[]
`RT`	`RT`

Parameters

Name	Type
`fn`	(...`args`: `A`) => `Promise`<`RT`>
`config`	`WorkflowDefinitionConfig`

Returns

void

deprecatePatch

▸ deprecatePatch(patchId, options?): 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.
`options?`	`EventGroupsOptions`	-

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>(workflowFunc, 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
`workflowFunc`	`T`
`options`	`WithWorkflowArgs`<`T`, `ChildWorkflowDefinitionOptions`>

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.

getCurrentDetails

▸ getCurrentDetails(): string

Returns

string

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

getRandomStream

▸ getRandomStream(name): WorkflowRandomStream

Get a named deterministic random stream for the current workflow execution.

Named streams are derived from the workflow seed and a stable stream name, without consuming the workflow's default Math.random() stream. Repeated calls with the same name within a workflow execution refer to the same logical stream state, including across activations.

This is the preferred entry point for workflow plugins and interceptors that need their own deterministic entropy. Use stable package- or module-style names so the stream identity remains replay-safe, then keep the returned WorkflowRandomStream around and call its methods directly.

This API may be removed or changed in the future.

Parameters

Name	Type
`name`	`string`

Returns

WorkflowRandomStream

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, options?): 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.
`options?`	`EventGroupsOptions`	-

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.

Type parameters

Name	Type
`A`	`UntypedActivities`

Parameters

Name	Type
`options`	`ActivityProxyOptions`<`A`>

Returns

ActivityInterfaceFor<A>

a Proxy for which each attribute is a callable Activity function

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

// Use activities with default options
const result1 = await httpGet('http://example.com');

// Override options for specific activity calls
const result2 = await httpGet.executeWithOptions({
  staticSummary: 'Fetches data from external API',
  scheduleToCloseTimeout: '5m'
}, ['http://api.example.com']);

const result3 = await otherActivity.executeWithOptions({
  staticSummary: 'Processes the fetched data',
  taskQueue: 'special-task-queue'
}, [data]);

// 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");
  // Or with custom options:
  const response2 = await httpGetFromJava.executeWithOptions({
    staticSummary: 'Java HTTP call with timeout override',
    startToCloseTimeout: '2m'
  }, ["http://fast-api.example.com"]);
  // ...
}

proxyLocalActivities

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

Configure Local Activity functions with given LocalActivityOptions.

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

Type parameters

Name	Type
`A`	`UntypedActivities`

Parameters

Name	Type
`options`	`LocalActivityProxyOptions`<`A`>

Returns

LocalActivityInterfaceFor<A>

a Proxy for which each attribute is a callable Activity function

See

proxyActivities for examples

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.

Type parameters

Name	Type
`T`	extends `Sinks`

Returns

T

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

setCurrentDetails

▸ setCurrentDetails(details): void

Parameters

Name	Type
`details`	`string`

Returns

void

setDefaultQueryHandler

▸ setDefaultQueryHandler(handler): void

Set a query handler function that will handle query calls for non-registered query names.

Queries are dispatched to the default query handler in the order that they were accepted by the server.

If this function is called multiple times for a given query name the last handler will overwrite any previous calls.

Parameters

Name	Type	Description
`handler`	`undefined` \| `DefaultQueryHandler`	a function that will handle queries for non-registered query names, or `undefined` to unset the handler.

Returns

void

setDefaultSignalHandler

▸ setDefaultSignalHandler(handler): void

Set a signal handler function that will handle signals calls for non-registered signal names.

Signals are dispatched to the default signal handler in the order that they were accepted by the server.

If this function is called multiple times for a given signal name the last handler will overwrite any previous calls.

Parameters

Name	Type	Description
`handler`	`undefined` \| `DefaultSignalHandler`	a function that will handle signals for non-registered signal names, or `undefined` to unset the handler.

Returns

void

setDefaultUpdateHandler

▸ setDefaultUpdateHandler(handler): void

Set a update handler function that will handle updates calls for non-registered update names.

Updates are dispatched to the default update handler in the order that they were accepted by the server.

If this function is called multiple times for a given update name the last handler will overwrite any previous calls.

Parameters

Name	Type	Description
`handler`	`undefined` \| `DefaultUpdateHandler`	a function that will handle updates for non-registered update names, or `undefined` to unset the handler.

Returns

void

setHandler

▸ setHandler<Ret, Args, T>(def, handler, options?): void

Set a handler function for a Workflow update, signal, or query.

If this function is called multiple times for a given update, signal, or query name the last handler will overwrite any previous calls.

Type parameters

Name	Type
`Ret`	`Ret`
`Args`	extends `any`[]
`T`	extends `QueryDefinition`<`Ret`, `Args`, `string`>

Parameters

Name	Type	Description
`def`	`T`	an UpdateDefinition, SignalDefinition, or QueryDefinition as returned by defineUpdate, defineSignal, or defineQuery respectively.
`handler`	`undefined` \| `Handler`<`Ret`, `Args`, `T`>	a compatible handler function for the given definition or `undefined` to unset the handler.
`options?`	`QueryHandlerOptions`	an optional `description` of the handler and an optional update `validator` function.

Returns

void

▸ setHandler<Ret, Args, T>(def, handler, options?): void

Type parameters

Name	Type
`Ret`	`Ret`
`Args`	extends `any`[]
`T`	extends `SignalDefinition`<`Args`, `string`>

Parameters

Name	Type
`def`	`T`
`handler`	`undefined` \| `Handler`<`Ret`, `Args`, `T`>
`options?`	`SignalHandlerOptions`

Returns

void

▸ setHandler<Ret, Args, T>(def, handler, options?): void

Type parameters

Name	Type
`Ret`	`Ret`
`Args`	extends `any`[]
`T`	extends `UpdateDefinition`<`Ret`, `Args`, `string`>

Parameters

Name	Type
`def`	`T`
`handler`	`undefined` \| `Handler`<`Ret`, `Args`, `T`>
`options?`	`UpdateHandlerOptions`<`Args`>

Returns

void

setWorkflowOptions

▸ setWorkflowOptions<A, RT>(options, fn): void

Can be used to alter workflow functions with certain options specified at definition time.

Prefer defineWorkflowOptions for new code, especially when setting static workflow metadata such as type information.

Type parameters

Name	Type
`A`	extends `any`[]
`RT`	`RT`

Parameters

Name	Type	Description
`options`	`WorkflowDefinitionOptionsOrGetter`	Options for the workflow defintion, or a function that returns options. If a function is provided, it will be called once just before the workflow function is called for the first time. It is safe to call workflowInfo inside such a function.
`fn`	(...`args`: `A`) => `Promise`<`RT`>	The workflow function.

Returns

void

Example

For example:

setWorkflowOptions({
  versioningBehavior: 'PINNED',
  failureExceptionTypes: [CustomWorkflowError]
}, myWorkflow);
export async function myWorkflow(): Promise<string> {
  // Workflow code here
  return "hi";
}

Example

To annotate a default or dynamic workflow:

export default async function (): Promise<string> {
  // Workflow code here
  return "hi";
}
setWorkflowOptions({
  versioningBehavior: 'PINNED',
  failureExceptionTypes: [CustomWorkflowError]
}, module.exports.default);

signalWithStartWorkflow

▸ signalWithStartWorkflow<WorkflowFn, SignalValue>(requestInput): Promise<ExternalWorkflowHandle>

Signal a workflow, starting it first if needed.

Type parameters

Name	Type
`WorkflowFn`	extends (...`args`: `any`[]) => `Promise`<`any`> = (...`args`: `any`[]) => `Promise`<`any`>
`SignalValue`	extends `SignalDefinition`<`any`[], `string`> = `SignalDefinition`<`any`[], `string`>

Parameters

Name	Type
`requestInput`	`SignalWithStartWorkflowInput`<`WorkflowFn`, `SignalValue`>

Returns

Promise<ExternalWorkflowHandle>

A workflow handle to the started workflow. This API is experimental and subject to change.

sleep

▸ sleep(ms, options?): Promise<void>

Asynchronous sleep.

Schedules a timer on the Temporal service.

Parameters

Name	Type	Description
`ms`	`Duration`	sleep duration - number of milliseconds or ms-formatted string. If given a negative number or 0, value will be set to 1.
`options?`	`TimerOptions`	optional timer options for additional configuration

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`, `ChildWorkflowDefinitionOptions`>

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

upsertMemo

▸ upsertMemo(memo, options?): void

Updates this Workflow's Memos by merging the provided memo with existing Memos (as returned by workflowInfo().memo).

New memo is merged by replacing properties of the same name at the first level only. Setting a property to value undefined or null clears that key from the Memo.

For example:

upsertMemo({
  key1: value,
  key3: { subkey1: value }
  key4: value,
});
upsertMemo({
  key2: value
  key3: { subkey2: value }
  key4: undefined,
});

would result in the Workflow having these Memo:

{
  key1: value,
  key2: value,
  key3: { subkey2: value }  // Note this object was completely replaced
  // Note that key4 was completely removed
}

Parameters

Name	Type	Description
`memo`	`Record`<`string`, `unknown`>	The Record to merge.
`options?`	`EventGroupsOptions`	-

Returns

void

upsertSearchAttributes

▸ upsertSearchAttributes(searchAttributes, options?): void

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

Search attributes can be upserted using either SearchAttributes (deprecated) or SearchAttributeUpdatePair[] (preferred)

Upserting a workflow's search attributes using SearchAttributeUpdatePair[]:

const intKey = defineSearchKey('CustomIntField', 'INT');
const boolKey = defineSearchKey('CustomBoolField', 'BOOL');
const keywordListKey = defineSearchKey('CustomKeywordField', 'KEYWORD_LIST');

upsertSearchAttributes([
 defineSearchAttribute(intKey, 1),
 defineSearchAttribute(boolKey, true)
]);
upsertSearchAttributes([
 defineSearchAttribute(intKey, 42),
 defineSearchAttribute(keywordListKey, ['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`	`SearchAttributeUpdatePair`[] \| `SearchAttributes`	The Record to merge. If using SearchAttributeUpdatePair[] (preferred), set a value to null to remove the search attribute. If using SearchAttributes (deprecated), set a value to undefined or an empty list to remove the search attribute.
`options?`	`EventGroupsOptions`	-

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.

WARNING: This function returns a frozen copy of WorkflowInfo, at the point where this method has been called. Changes happening at later point in workflow execution will not be reflected in the returned object.

For this reason, we recommend calling workflowInfo() on every access to WorkflowInfo's fields, rather than caching the WorkflowInfo object (or part of it) in a local variable. For example:

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

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

Returns

WorkflowInfo

Usage​

Timers​

Activities​

Updates, Signals and Queries​

Implementation​

More​

Classes​

Interfaces​

References​

ActivityCancellationType​

ActivityFailure​

ActivityFunction​

ActivityInterface​

ActivityTypeInfoMap​

ApplicationFailure​

BaseWorkflowHandle​

BaseWorkflowOptions​

CancelledFailure​

ChildWorkflowFailure​

CommonWorkflowOptions​

CompleteAsyncError​

ExternalStorageDriverError​

ExternalStorageError​

ExternalStorageNotConfiguredError​

ExternalStorageReferenceError​

ExternalStorageUnregisteredDriverError​

Headers​

IllegalStateError​

NamespaceNotFoundError​

Next​

Payload​

PayloadConverter​

PayloadConverterError​

QueryDefinition​

RetryPolicy​

SearchAttributeValue​

SearchAttributes​

ServerFailure​

SignalDefinition​

TemporalFailure​

TerminatedFailure​

TimeoutFailure​

UntypedActivities​

ValueError​

WithWorkflowArgs​

Workflow​

WorkflowDurationOptions​

WorkflowIdConflictPolicy​

WorkflowIdReusePolicy​

WorkflowNotFoundError​

WorkflowQueryOptions​

WorkflowQueryType​

WorkflowResultType​

WorkflowReturnType​

WorkflowSignalOptions​

WorkflowSignalType​

WorkflowTypeOptions​

decodeWorkflowIdConflictPolicy​

decodeWorkflowIdReusePolicy​

defaultPayloadConverter​

encodeWorkflowIdConflictPolicy​

encodeWorkflowIdReusePolicy​

extractWorkflowType​

extractWorkflowTypeAndConfig​

rootCause​

Type Aliases​

ActivityFunctionWithOptions​

Type parameters​

ActivityInterfaceFor​

Type parameters​

ChildWorkflowCancellationType​

ConcludeActivationOutput​

ContinueAsNewInputOptions​

GetLogAttributesInput​

GetMetricTagsInput​

LocalActivityFunctionWithOptions​

Type parameters​

LocalActivityInterfaceFor​

Type parameters​

NexusOperationCancellationType​

Usage

Timers

Activities

Updates, Signals and Queries

Implementation

More

Classes

Interfaces

References

ActivityCancellationType

ActivityFailure

ActivityFunction

ActivityInterface

ActivityTypeInfoMap

ApplicationFailure

BaseWorkflowHandle

BaseWorkflowOptions

CancelledFailure

ChildWorkflowFailure

CommonWorkflowOptions

CompleteAsyncError

ExternalStorageDriverError

ExternalStorageError

ExternalStorageNotConfiguredError

ExternalStorageReferenceError

ExternalStorageUnregisteredDriverError

Headers

IllegalStateError

NamespaceNotFoundError

Next

Payload

PayloadConverter

PayloadConverterError

QueryDefinition

RetryPolicy

SearchAttributeValue

SearchAttributes

ServerFailure

SignalDefinition

TemporalFailure

TerminatedFailure

TimeoutFailure

UntypedActivities

ValueError

WithWorkflowArgs

Workflow

WorkflowDurationOptions

WorkflowIdConflictPolicy

WorkflowIdReusePolicy

WorkflowNotFoundError

WorkflowQueryOptions

WorkflowQueryType

WorkflowResultType

WorkflowReturnType

WorkflowSignalOptions

WorkflowSignalType

WorkflowTypeOptions

decodeWorkflowIdConflictPolicy

decodeWorkflowIdReusePolicy

defaultPayloadConverter

encodeWorkflowIdConflictPolicy

encodeWorkflowIdReusePolicy

extractWorkflowType

extractWorkflowTypeAndConfig

rootCause

Type Aliases

ActivityFunctionWithOptions

Type parameters

ActivityInterfaceFor

Type parameters

ChildWorkflowCancellationType

ConcludeActivationOutput

ContinueAsNewInputOptions

GetLogAttributesInput

GetMetricTagsInput

LocalActivityFunctionWithOptions

Type parameters

LocalActivityInterfaceFor

Type parameters

NexusOperationCancellationType