0
# Workflow Client
1

2
Complete workflow lifecycle management including starting workflows, handling updates, sending signals and queries, and managing workflow execution state.
3

4
## Capabilities
5

6
### WorkflowClient
7

8
Primary client for starting and interacting with workflows.
9

10
```typescript { .api }
11
/**
12
 * Client for starting and interacting with workflows
13
 */
14
class WorkflowClient extends BaseClient {
15
  /** Start new workflow execution */
16
  start<T extends Workflow>(
17
    workflowTypeOrFunc: string | T,
18
    options: WorkflowStartOptions<T>
19
  ): Promise<WorkflowHandleWithFirstExecutionRunId<T>>;
20

21
  /** Start workflow and wait for result */
22
  execute<T extends Workflow>(
23
    workflowTypeOrFunc: string | T,
24
    options: WorkflowStartOptions<T>
25
  ): Promise<WorkflowResultType<T>>;
26

27
  /** Get workflow execution result */
28
  result<T extends Workflow>(
29
    workflowId: string,
30
    runId?: string,
31
    opts?: WorkflowResultOptions
32
  ): Promise<WorkflowResultType<T>>;
33

34
  /** Start workflow with initial signal */
35
  signalWithStart<T extends Workflow, SignalArgs extends any[]>(
36
    workflowTypeOrFunc: string,
37
    options: WorkflowSignalWithStartOptions<SignalArgs>
38
  ): Promise<WorkflowHandleWithSignaledRunId<WorkflowResultType<T>>>;
39

40
  /** Execute workflow update and wait for result */
41
  executeUpdateWithStart<T extends Workflow, Ret, Args extends any[]>(
42
    workflowTypeOrFunc: string,
43
    updateOptions: WorkflowUpdateWithStartOptions<Ret, Args>
44
  ): Promise<Ret>;
45

46
  /** Start workflow update and return handle */
47
  startUpdateWithStart<T extends Workflow, Ret, Args extends any[]>(
48
    workflowTypeOrFunc: string,
49
    updateOptions: WorkflowUpdateWithStartOptions<Ret, Args>
50
  ): Promise<WorkflowUpdateHandle<Ret>>;
51

52
  /** Get handle to existing workflow */
53
  getHandle<T extends Workflow>(
54
    workflowId: string,
55
    runId?: string,
56
    options?: GetWorkflowHandleOptions
57
  ): WorkflowHandle<WorkflowResultType<T>>;
58

59
  /** List workflow executions */
60
  list(options?: ListOptions): AsyncWorkflowListIterable;
61

62
  /** Count workflow executions */
63
  count(query?: string): Promise<CountWorkflowExecution>;
64

65
  /** Raw gRPC access to WorkflowService */
66
  readonly workflowService: WorkflowService;
67
}
68

69
interface WorkflowClientOptions extends BaseClientOptions {
70
  namespace?: string;
71
  dataConverter?: DataConverter;
72
  interceptors?: WorkflowClientInterceptor[];
73
}
74

75
interface WorkflowHandleWithFirstExecutionRunId<T = any> extends WorkflowHandle<T> {
76
  readonly firstExecutionRunId: string;
77
}
78

79
interface WorkflowHandleWithSignaledRunId<T = any> extends WorkflowHandle<T> {
80
  readonly signaledRunId: string;
81
}
82

83
interface CountWorkflowExecution {
84
  count: number;
85
}
86
```
87

88
**Usage Examples:**
89

90
```typescript
91
import { WorkflowClient } from "@temporalio/client";
92

93
const client = new WorkflowClient();
94

95
// Start workflow
96
const handle = await client.start('processOrder', {
97
  args: [{ orderId: '12345', customerId: 'cust-456' }],
98
  taskQueue: 'order-processing',
99
  workflowId: 'order-12345',
100
});
101

102
// Start and wait for result
103
const result = await client.execute('calculateTotal', {
104
  args: [100, 0.08],
105
  taskQueue: 'math-operations',
106
  workflowId: 'calc-' + Date.now(),
107
});
108

109
// Get existing workflow handle
110
const existingHandle = client.getHandle('order-12345');
111
const orderResult = await existingHandle.result();
112
```
113

114
### Workflow Handle
115

116
Handle to interact with a single workflow instance.
117

118
```typescript { .api }
119
/**
120
 * Handle to single workflow instance
121
 */
122
interface WorkflowHandle<T> {
123
  /** Workflow identifier */
124
  readonly workflowId: string;
125
  /** Run identifier (undefined for workflow started via signalWithStart) */
126
  readonly runId: string | undefined;
127
  /** First execution run identifier */
128
  readonly firstExecutionRunId: string;
129
  /** Reference to WorkflowClient */
130
  readonly client: WorkflowClient;
131

132
  /** Execute workflow update and wait for result */
133
  executeUpdate<Ret, Args extends any[]>(
134
    def: UpdateDefinition<Ret, Args> | string,
135
    options?: WorkflowUpdateOptions,
136
    ...args: Args
137
  ): Promise<Ret>;
138

139
  /** Start workflow update and return handle */
140
  startUpdate<Ret, Args extends any[]>(
141
    def: UpdateDefinition<Ret, Args> | string,
142
    options?: WorkflowUpdateOptions,
143
    ...args: Args
144
  ): Promise<WorkflowUpdateHandle<Ret>>;
145

146
  /** Get handle to existing update */
147
  getUpdateHandle<Ret>(updateId: string): WorkflowUpdateHandle<Ret>;
148

149
  /** Query workflow */
150
  query<Ret, Args extends any[]>(
151
    def: QueryDefinition<Ret, Args> | string,
152
    ...args: Args
153
  ): Promise<Ret>;
154

155
  /** Send signal to workflow */
156
  signal<Args extends any[]>(
157
    def: SignalDefinition<Args> | string,
158
    ...args: Args
159
  ): Promise<void>;
160

161
  /** Terminate workflow execution */
162
  terminate(reason?: string): Promise<void>;
163

164
  /** Cancel workflow execution */
165
  cancel(): Promise<void>;
166

167
  /** Get workflow description */
168
  describe(): Promise<WorkflowExecutionDescription>;
169

170
  /** Fetch workflow history */
171
  fetchHistory(options?: FetchHistoryOptions): AsyncIterable<HistoryEvent>;
172

173
  /** Get workflow execution result */
174
  result(): Promise<T>;
175
}
176

177
interface WorkflowHandleWithFirstExecutionRunId<T>
178
  extends WorkflowHandle<T> {
179
  readonly firstExecutionRunId: string;
180
}
181

182
interface WorkflowHandleWithSignaledRunId<T> extends WorkflowHandle<T> {
183
  readonly signaledRunId: string;
184
}
185
```
186

187
**Usage Examples:**
188

189
```typescript
190
// Query workflow state
191
const status = await handle.query('getCurrentStatus');
192

193
// Send signal
194
await handle.signal('processPayment', { amount: 100, paymentMethod: 'credit' });
195

196
// Execute update
197
const updatedValue = await handle.executeUpdate('updateConfiguration', {
198
  waitForStage: WorkflowUpdateStage.COMPLETED,
199
}, { setting1: 'value1' });
200

201
// Cancel workflow
202
await handle.cancel();
203

204
// Get workflow description
205
const description = await handle.describe();
206
console.log('Workflow status:', description.status);
207
```
208

209
### Workflow Update Operations
210

211
Handle to workflow update operations.
212

213
```typescript { .api }
214
/**
215
 * Handle to workflow update operation
216
 */
217
interface WorkflowUpdateHandle<Ret> {
218
  /** Update identifier */
219
  readonly updateId: string;
220
  /** Workflow identifier */
221
  readonly workflowId: string;
222
  /** Workflow run identifier */
223
  readonly workflowRunId: string;
224

225
  /** Get update result */
226
  result(): Promise<Ret>;
227
}
228

229
/**
230
 * Defines workflow to start with update operations
231
 */
232
class WithStartWorkflowOperation<T> {
233
  /** Get promise to workflow handle */
234
  workflowHandle(): Promise<WorkflowHandle<T>>;
235
}
236
```
237

238
### Workflow Options & Configuration
239

240
Configuration options for starting and managing workflows.
241

242
```typescript { .api }
243
/**
244
 * Options for starting workflows
245
 */
246
type WorkflowStartOptions<T extends Workflow> = WorkflowOptions & {
247
  /** Arguments to pass to workflow */
248
  args: Parameters<T>;
249
  /** Workflow identifier (must be unique per namespace) */
250
  workflowId: string;
251
};
252

253
interface WorkflowOptions {
254
  /** Task queue name for workflow execution */
255
  taskQueue: string;
256
  /** Workflow execution timeout */
257
  workflowExecutionTimeout?: string | number;
258
  /** Workflow run timeout */
259
  workflowRunTimeout?: string | number;
260
  /** Workflow task timeout */
261
  workflowTaskTimeout?: string | number;
262
  /** Retry policy for workflow */
263
  retry?: RetryPolicy;
264
  /** Cron schedule expression */
265
  cronSchedule?: string;
266
  /** Memo for workflow execution */
267
  memo?: Record<string, unknown>;
268
  /** Search attributes for workflow */
269
  searchAttributes?: SearchAttributes;
270
  /** Start delay before first workflow task */
271
  startDelay?: string | number;
272
}
273

274
/**
275
 * Options for workflow updates
276
 */
277
interface WorkflowUpdateOptions {
278
  /** Update identifier (optional) */
279
  updateId?: string;
280
  /** Stage to wait for before returning */
281
  waitForStage?: WorkflowUpdateStage;
282
  /** First execution run ID for validation */
283
  firstExecutionRunId?: string;
284
}
285

286
/**
287
 * Options for signal with start operations
288
 */
289
type WorkflowSignalWithStartOptions<SignalArgs extends any[]> = WorkflowStartOptions<any> & {
290
  /** Signal definition or name */
291
  signal: SignalDefinition<SignalArgs> | string;
292
  /** Signal arguments */
293
  signalArgs: SignalArgs;
294
};
295

296
/**
297
 * Options for getting workflow results
298
 */
299
interface WorkflowResultOptions {
300
  /** Workflow identifier */
301
  workflowId: string;
302
  /** Run identifier (optional) */
303
  runId?: string;
304
  /** Follow runs if workflow continues as new */
305
  followRuns?: boolean;
306
}
307

308
/**
309
 * Options for getting workflow handles
310
 */
311
interface GetWorkflowHandleOptions {
312
  /** First execution run ID for validation */
313
  firstExecutionRunId?: string;
314
}
315

316
/**
317
 * Compiled workflow options with protobuf types
318
 */
319
interface CompiledWorkflowOptions {
320
  workflowExecutionTimeout?: Duration;
321
  workflowRunTimeout?: Duration;
322
  workflowTaskTimeout?: Duration;
323
  retryPolicy?: RetryPolicy;
324
  workflowIdReusePolicy?: WorkflowIdReusePolicy;
325
}
326
```
327

328
### Workflow Listing & Search
329

330
Options and types for listing and searching workflows.
331

332
```typescript { .api }
333
/**
334
 * Options for listing workflows
335
 */
336
interface ListOptions {
337
  /** Search query expression */
338
  query?: string;
339
  /** Maximum number of executions to return */
340
  pageSize?: number;
341
  /** Namespace to search in */
342
  namespace?: string;
343
}
344

345
/**
346
 * Options for converting list to histories
347
 */
348
interface IntoHistoriesOptions {
349
  /** Maximum number of events per history */
350
  maxHistorySize?: number;
351
  /** Filter histories by status */
352
  statusFilter?: WorkflowExecutionStatus[];
353
}
354

355
/**
356
 * Iterable of workflow executions
357
 */
358
interface AsyncWorkflowListIterable extends AsyncIterable<WorkflowExecutionInfo> {
359
  /** Convert to histories */
360
  intoHistories(options?: IntoHistoriesOptions): AsyncIterable<HistoryAndWorkflowId>;
361
}
362

363
/**
364
 * Count workflow executions request
365
 */
366
interface CountWorkflowExecutions {
367
  /** Search query expression */
368
  query?: string;
369
}
370
```