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 workflowService and 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 (localhost:7233)
  const connection = await Connection.connect();
  // 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, {
    // type inference works! args: [name: string]
    args: ['Temporal'],
    taskQueue: 'hello-world',
    // 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​

DataConverter​

Re-exports DataConverter

Headers​

Re-exports Headers

Next​

Re-exports Next

defaultPayloadConverter​

Re-exports defaultPayloadConverter

Type Aliases​

ActivityInterface​

Ƭ ActivityInterface: Record<string, ActivityFunction>

Mapping of Activity name to function

Deprecated

not required anymore, for untyped activities use UntypedActivities

AsyncCompletionClientOptions​

Ƭ AsyncCompletionClientOptions: BaseClientOptions

Options used to configure AsyncCompletionClient

CommonWorkflowOptions​

Ƭ CommonWorkflowOptions: BaseWorkflowOptions & WorkflowDurationOptions

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">> & { 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>

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

Payload​

Ƭ Payload: IPayload

ProtoFailure​

Ƭ ProtoFailure: IFailure

RawWorkflowExecutionInfo​

Ƭ RawWorkflowExecutionInfo: IWorkflowExecutionInfo

RequestCancelWorkflowExecutionResponse​

Ƭ RequestCancelWorkflowExecutionResponse: IRequestCancelWorkflowExecutionResponse

ScheduleDescription​

Ƭ ScheduleDescription: Object

A detailed description of an exisiting Schedule, as returned by 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 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 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 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 describe and list

ScheduleSummaryAction​

Ƭ ScheduleSummaryAction: ScheduleSummaryStartWorkflowAction

ScheduleUpdateOptions​

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

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

Type parameters​

NameType
Aextends ScheduleOptionsAction = ScheduleOptionsAction

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.

StartWorkflowExecutionRequest​

Ƭ StartWorkflowExecutionRequest: IStartWorkflowExecutionRequest

TerminateWorkflowExecutionResponse​

Ƭ TerminateWorkflowExecutionResponse: ITerminateWorkflowExecutionResponse

UntypedActivities​

Ƭ UntypedActivities: Record<string, ActivityFunction>

Mapping of Activity name to function

WithCompiledWorkflowOptions​

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

Type parameters​

NameType
Textends CommonWorkflowOptions

WithWorkflowArgs​

Ƭ WithWorkflowArgs<W, T>: T & Parameters<W> extends [any, ...any[]] ? { args: Parameters<W> } : { args?: Parameters<W> }

Type parameters​

NameType
Wextends Workflow
TT

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​
NameType
...argsany[]
Returns​

WorkflowReturnType

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"

WorkflowQueryType​

Ƭ WorkflowQueryType: (...args: any[]) => any

Type declaration​

▸ (...args): any

Parameters​
NameType
...argsany[]
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​

NameType
Wextends Workflow

WorkflowReturnType​

Ƭ WorkflowReturnType: Promise<any>

Type that can be returned from a Workflow execute function

WorkflowService​

Ƭ WorkflowService: WorkflowService

WorkflowSignalType​

Ƭ WorkflowSignalType: (...args: any[]) => Promise<void> | void

Type declaration​

▸ (...args): Promise<void> | void

Parameters​
NameType
...argsany[]
Returns​

Promise<void> | void

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

WorkflowService​

• WorkflowService: typeof WorkflowService

Functions​

compileWorkflowOptions​

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

Type parameters​

NameType
Textends CommonWorkflowOptions

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

isRetryableError​

▸ isRetryableError(status): boolean

Parameters​

NameType
statusStatusObject

Returns​

boolean

isServerErrorResponse​

▸ isServerErrorResponse(err): err is ServerErrorResponse

Type assertion helper, assertion is mostly empty because any additional properties are optional.

Parameters​

NameType
errunknown

Returns​

err is ServerErrorResponse

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