Skip to main content

Namespace: client

Client for communicating with Temporal Server.

Most functionality is available through WorkflowClient, but you can also call gRPC methods directly using Connection.workflowService and Connection.operatorService.

Usage

import { Connection, Client } from '@temporalio/client';
import { example } from './workflows';
import { nanoid } from 'nanoid';

async function run() {
// Connect to the default Server location
const connection = await Connection.connect({ address: 'localhost:7233' });
// In production, pass options to configure TLS and other settings:
// {
// address: 'foo.bar.tmprl.cloud',
// tls: {}
// }

const client = new Client({
connection,
// namespace: 'foo.bar', // connects to 'default' namespace if not specified
});

const handle = await client.workflow.start(example, {
taskQueue: 'hello-world',
// type inference works! args: [name: string]
args: ['Temporal'],
// in practice, use a meaningful business ID, like customerId or transactionId
workflowId: 'workflow-' + nanoid(),
});
console.log(`Started workflow ${handle.workflowId}`);

// optional: wait for client result
console.log(await handle.result()); // Hello, Temporal!
}

run().catch((err) => {
console.error(err);
process.exit(1);
});

Enumerations

Classes

Interfaces

References

ActivityFailure

Re-exports ActivityFailure


ActivityFunction

Re-exports ActivityFunction


ActivityInterface

Re-exports ActivityInterface


ApplicationFailure

Re-exports ApplicationFailure


BaseWorkflowHandle

Re-exports BaseWorkflowHandle


BaseWorkflowOptions

Re-exports BaseWorkflowOptions


CancelledFailure

Re-exports CancelledFailure


ChildWorkflowFailure

Re-exports ChildWorkflowFailure


CommonWorkflowOptions

Re-exports CommonWorkflowOptions


DataConverter

Re-exports DataConverter


Headers

Re-exports Headers


HistoryAndWorkflowId

Re-exports HistoryAndWorkflowId


IllegalStateError

Re-exports IllegalStateError


NamespaceNotFoundError

Re-exports NamespaceNotFoundError


Next

Re-exports Next


Payload

Re-exports Payload


PayloadConverterError

Re-exports PayloadConverterError


ProtoFailure

Re-exports ProtoFailure


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


UpdateDefinition

Re-exports UpdateDefinition


ValueError

Re-exports ValueError


WithWorkflowArgs

Re-exports WithWorkflowArgs


Workflow

Re-exports Workflow


WorkflowDurationOptions

Re-exports WorkflowDurationOptions


WorkflowExecutionAlreadyStartedError

Re-exports WorkflowExecutionAlreadyStartedError


WorkflowIdReusePolicy

Re-exports WorkflowIdReusePolicy


WorkflowNotFoundError

Re-exports WorkflowNotFoundError


WorkflowQueryAnnotatedType

Re-exports WorkflowQueryAnnotatedType


WorkflowQueryType

Re-exports WorkflowQueryType


WorkflowResultType

Re-exports WorkflowResultType


WorkflowReturnType

Re-exports WorkflowReturnType


WorkflowSignalAnnotatedType

Re-exports WorkflowSignalAnnotatedType


WorkflowSignalType

Re-exports WorkflowSignalType


WorkflowUpdateAnnotatedType

Re-exports WorkflowUpdateAnnotatedType


WorkflowUpdateType

Re-exports WorkflowUpdateType


WorkflowUpdateValidatorType

Re-exports WorkflowUpdateValidatorType


defaultPayloadConverter

Re-exports defaultPayloadConverter


extractWorkflowType

Re-exports extractWorkflowType

Type Aliases

AsyncCompletionClientOptions

Ƭ AsyncCompletionClientOptions: BaseClientOptions

Options used to configure AsyncCompletionClient


BuildIdOperation

Ƭ BuildIdOperation: AddNewIdInNewDefaultSet | AddNewCompatibleVersion | PromoteSetByBuildId | PromoteBuildIdWithinSet | MergeSets

Operations that can be passed to TaskQueueClient.updateBuildIdCompatibility.


CompiledScheduleAction

Ƭ CompiledScheduleAction: Replace<ScheduleDescriptionAction, { args: unknown[] ; workflowType: string }>


CompiledScheduleOptions

Ƭ CompiledScheduleOptions: Replace<ScheduleOptions, { action: CompiledScheduleAction }>


CompiledScheduleUpdateOptions

Ƭ CompiledScheduleUpdateOptions: Replace<ScheduleUpdateOptions, { action: CompiledScheduleAction }>


ConnectionOptionsWithDefaults

Ƭ ConnectionOptionsWithDefaults: Required<Omit<ConnectionOptions, "tls" | "connectTimeout" | "callCredentials">> & { connectTimeoutMs: number }


CreateScheduleOutput

Ƭ CreateScheduleOutput: Object

Type declaration

NameType
conflictTokenUint8Array

DayOfWeek

Ƭ DayOfWeek: typeof DAYS_OF_WEEK[number]


DescribeWorkflowExecutionResponse

Ƭ DescribeWorkflowExecutionResponse: IDescribeWorkflowExecutionResponse


GetWorkflowExecutionHistoryRequest

Ƭ GetWorkflowExecutionHistoryRequest: IGetWorkflowExecutionHistoryRequest


HealthService

Ƭ HealthService: Health


LoadedAsyncCompletionClientOptions

Ƭ LoadedAsyncCompletionClientOptions: LoadedWithDefaults<AsyncCompletionClientOptions>


LoadedClientOptions

Ƭ LoadedClientOptions: LoadedWithDefaults<ClientOptions>


LoadedScheduleClientOptions

Ƭ LoadedScheduleClientOptions: LoadedWithDefaults<ScheduleClientOptions>


LoadedTaskQueueClientOptions

Ƭ LoadedTaskQueueClientOptions: LoadedWithDefaults<TaskQueueClientOptions>


LoadedWorkflowClientOptions

Ƭ LoadedWorkflowClientOptions: LoadedWithDefaults<WorkflowClientOptions>


LooseRange

Ƭ LooseRange<Unit>: Range<Unit> | { end?: Range<Unit>["end"] ; start: Range<Unit>["start"] ; step?: never } | Unit

A Range definition, with support for loose syntax.

For example:

3 ➡️ 3
{ start: 2 } ➡️ 2
{ start: 2, end: 4 } ➡️ 2, 3, 4
{ start: 2, end: 10, step: 3 } ➡️ 2, 5, 8

Type parameters

Name
Unit

Metadata

Ƭ Metadata: Record<string, grpc.MetadataValue>

Mapping of string to valid gRPC metadata value


Month

Ƭ Month: typeof MONTHS[number]


OperatorService

Ƭ OperatorService: OperatorService


RawWorkflowExecutionInfo

Ƭ RawWorkflowExecutionInfo: IWorkflowExecutionInfo


ReachabilityOptions

Ƭ ReachabilityOptions: RequireAtLeastOne<BaseReachabilityOptions, "buildIds" | "taskQueues">

Options for TaskQueueClient.getReachability


ReachabilityType

Ƭ ReachabilityType: "NEW_WORKFLOWS" | "EXISTING_WORKFLOWS" | "OPEN_WORKFLOWS" | "CLOSED_WORKFLOWS"

There are different types of reachability:

  • NEW_WORKFLOWS: The Build Id might be used by new workflows
  • EXISTING_WORKFLOWS The Build Id might be used by open workflows and/or closed workflows.
  • OPEN_WORKFLOWS The Build Id might be used by open workflows
  • CLOSED_WORKFLOWS The Build Id might be used by closed workflows

ReachabilityTypeResponse

Ƭ ReachabilityTypeResponse: ReachabilityType | "NOT_FETCHED"


RequestCancelWorkflowExecutionResponse

Ƭ RequestCancelWorkflowExecutionResponse: IRequestCancelWorkflowExecutionResponse


ScheduleDescription

Ƭ ScheduleDescription: Object

A detailed description of an exisiting Schedule, as returned by ScheduleHandle.describe.

Type declaration

NameTypeDescription
actionScheduleDescriptionActionThe Action that will be taken.
info{ createdAt: Date ; lastUpdatedAt: Date | undefined ; nextActionTimes: Date[] ; numActionsMissedCatchupWindow: number ; numActionsSkippedOverlap: number ; numActionsTaken: number ; recentActions: ScheduleExecutionResult[] ; runningActions: ScheduleExecutionActionResult[] }-
info.createdAtDate-
info.lastUpdatedAtDate | undefined-
info.nextActionTimesDate[]Next upcoming scheduled times of this Schedule
info.numActionsMissedCatchupWindownumberNumber of times a scheduled Action was skipped due to missing the catchup window.
info.numActionsSkippedOverlapnumberNumber of Actions skipped due to overlap.
info.numActionsTakennumberNumber of Actions taken so far.
info.recentActionsScheduleExecutionResult[]Most recent actions started (including manual triggers), sorted from older start time to newer.
info.runningActionsScheduleExecutionActionResult[]Currently-running workflows started by this schedule. (There might be more than one if the overlap policy allows overlaps.)
memo?Record<string, unknown>Additional non-indexed information attached to the Schedule. The values can be anything that is serializable by the DataConverter.
policies{ catchupWindow: number ; overlap: ScheduleOverlapPolicy ; pauseOnFailure: boolean }-
policies.catchupWindownumberThe Temporal Server might be down or unavailable at the time when a Schedule should take an Action. When the Server comes back up, catchupWindow controls which missed Actions should be taken at that point. It takes those Actions according to the ScheduleOverlapPolicy. An outage that lasts longer than the Catchup Window could lead to missed Actions. (But you can always ScheduleHandle.backfill.) Unit is miliseconds.
policies.overlapScheduleOverlapPolicyControls what happens when an Action would be started by a Schedule at the same time that an older Action is still running.
policies.pauseOnFailurebooleanWhen an Action times out or reaches the end of its Retry Policy, pause. With ScheduleOverlapPolicy.ALLOW_ALL, this pause might not apply to the next Action, because the next Action might have already started previous to the failed one finishing. Pausing applies only to Actions that are scheduled to start after the failed one finishes.
scheduleIdstringThe Schedule Id. We recommend using a meaningful business identifier.
searchAttributesSearchAttributesAdditional indexed information attached to the Schedule. More info: https://docs.temporal.io/docs/typescript/search-attributes Values are always converted using JsonPayloadConverter, even when a custom Data Converter is provided.
specScheduleSpecDescriptionWhen will Actions be taken.
state{ note?: string ; paused: boolean ; remainingActions?: number }-
state.note?stringInformative human-readable message with contextual notes, e.g. the reason a Schedule is paused. The system may overwrite this message on certain conditions, e.g. when pause-on-failure happens.
state.pausedbooleanWhether Schedule is currently paused.
state.remainingActions?numberThe Actions remaining in this Schedule. Once this number hits 0, no further Actions are taken (unless ScheduleHandle.trigger is called). If undefined, then no such limit applies.

ScheduleDescriptionAction

Ƭ ScheduleDescriptionAction: ScheduleDescriptionStartWorkflowAction


ScheduleDescriptionStartWorkflowAction

Ƭ ScheduleDescriptionStartWorkflowAction: ScheduleSummaryStartWorkflowAction & Pick<WorkflowStartOptions<Workflow>, "taskQueue" | "workflowId" | "args" | "memo" | "searchAttributes" | "retry" | "workflowExecutionTimeout" | "workflowRunTimeout" | "workflowTaskTimeout">


ScheduleExecutionActionResult

Ƭ ScheduleExecutionActionResult: ScheduleExecutionStartWorkflowActionResult


ScheduleOptionsAction

Ƭ ScheduleOptionsAction: ScheduleOptionsStartWorkflowAction<Workflow>


ScheduleOptionsStartWorkflowAction

Ƭ ScheduleOptionsStartWorkflowAction<W>: { type: "startWorkflow" ; workflowType: string | W } & Pick<WorkflowStartOptions<W>, "taskQueue" | "args" | "memo" | "searchAttributes" | "retry" | "workflowExecutionTimeout" | "workflowRunTimeout" | "workflowTaskTimeout"> & { workflowId?: string }

Type parameters

NameType
Wextends Workflow

ScheduleSpecDescription

Ƭ ScheduleSpecDescription: Omit<ScheduleSpec, "calendars" | "intervals" | "cronExpressions" | "skip" | "jitter"> & { calendars?: CalendarSpecDescription[] ; intervals?: IntervalSpecDescription[] ; jitter?: number ; skip?: CalendarSpecDescription[] }

The version of ScheduleSpec that you get back from ScheduleHandle.describe and ScheduleClient.list


ScheduleSummaryAction

Ƭ ScheduleSummaryAction: ScheduleSummaryStartWorkflowAction


ScheduleUpdateOptions

Ƭ ScheduleUpdateOptions<A>: Replace<Omit<ScheduleOptions, "scheduleId" | "memo" | "searchAttributes">, { action: A ; state: Omit<ScheduleOptions["state"], "triggerImmediately" | "backfill"> }>

The specification of an updated Schedule, as expected by ScheduleHandle.update.

Type parameters

NameType
Aextends ScheduleOptionsAction = ScheduleOptionsAction

StartWorkflowExecutionRequest

Ƭ StartWorkflowExecutionRequest: IStartWorkflowExecutionRequest


TaskQueueClientOptions

Ƭ TaskQueueClientOptions: BaseClientOptions


TerminateWorkflowExecutionResponse

Ƭ TerminateWorkflowExecutionResponse: ITerminateWorkflowExecutionResponse


UnversionedBuildIdType

Ƭ UnversionedBuildIdType: typeof UnversionedBuildId


WithCompiledWorkflowOptions

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

Type parameters

NameType
Textends WorkflowOptions

WorkflowClientCallsInterceptor

Ƭ WorkflowClientCallsInterceptor: WorkflowClientInterceptor

@deprecated: Use WorkflowClientInterceptor instead


WorkflowExecutionDescription

Ƭ WorkflowExecutionDescription: Replace<WorkflowExecutionInfo, { raw: DescribeWorkflowExecutionResponse }>


WorkflowExecutionStatusName

Ƭ WorkflowExecutionStatusName: "UNSPECIFIED" | "RUNNING" | "COMPLETED" | "FAILED" | "CANCELLED" | "TERMINATED" | "CONTINUED_AS_NEW" | "TIMED_OUT" | "UNKNOWN"


WorkflowService

Ƭ WorkflowService: WorkflowService


WorkflowSignalWithStartOptions

Ƭ WorkflowSignalWithStartOptions<SignalArgs>: SignalArgs extends [any, ...any[]] ? WorkflowSignalWithStartOptionsWithArgs<SignalArgs> : WorkflowSignalWithStartOptionsWithoutArgs<SignalArgs>

Type parameters

NameType
SignalArgsextends any[] = []

WorkflowStartOptions

Ƭ WorkflowStartOptions<T>: WithWorkflowArgs<T, WorkflowOptions>

Options for starting a Workflow

Type parameters

NameType
Textends Workflow = Workflow

Variables

DAYS_OF_WEEK

Const DAYS_OF_WEEK: readonly ["SUNDAY", "MONDAY", "TUESDAY", "WEDNESDAY", "THURSDAY", "FRIDAY", "SATURDAY"]


HealthService

HealthService: typeof Health


LOCAL_TARGET

Const LOCAL_TARGET: "127.0.0.1:7233"


MONTHS

Const MONTHS: readonly ["JANUARY", "FEBRUARY", "MARCH", "APRIL", "MAY", "JUNE", "JULY", "AUGUST", "SEPTEMBER", "OCTOBER", "NOVEMBER", "DECEMBER"]


OperatorService

OperatorService: typeof OperatorService


UnversionedBuildId

Const UnversionedBuildId: unique symbol

A stand-in for a Build Id for unversioned Workers


WorkflowService

WorkflowService: typeof WorkflowService

Functions

compileWorkflowOptions

compileWorkflowOptions<T>(options): WithCompiledWorkflowOptions<T>

Type parameters

NameType
Textends WorkflowOptions

Parameters

NameType
optionsT

Returns

WithCompiledWorkflowOptions<T>


defaultGrpcRetryOptions

defaultGrpcRetryOptions(options?): GrpcRetryOptions

Generates the default retry behavior based on given backoff options

Parameters

NameType
options?Partial<BackoffOptions>

Returns

GrpcRetryOptions


isGrpcServiceError

isGrpcServiceError(err): err is ServiceError

Parameters

NameType
errunknown

Returns

err is ServiceError


isRetryableError

isRetryableError(status): boolean

Parameters

NameType
statusStatusObject

Returns

boolean


isServerErrorResponse

isServerErrorResponse(err): err is ServiceError

Parameters

NameType
errunknown

Returns

err is ServiceError

Deprecated

Use isGrpcServiceError instead


makeGrpcRetryInterceptor

makeGrpcRetryInterceptor(retryOptions): Interceptor

Returns a GRPC interceptor that will perform automatic retries for some types of failed calls

Parameters

NameTypeDescription
retryOptionsGrpcRetryOptionsOptions for the retry interceptor

Returns

Interceptor


reachabilityResponseFromProto

reachabilityResponseFromProto(resp): ReachabilityResponse

Parameters

NameType
respGetWorkerTaskReachabilityResponse

Returns

ReachabilityResponse