0
# Client & Connection Management
1

2
Core client functionality for establishing connections to Temporal Server and accessing specialized sub-clients for different operations.
3

4
## Capabilities
5

6
### Main Client
7

8
The `Client` class is the primary entry point that aggregates specialized sub-clients and provides context control methods.
9

10
```typescript { .api }
11
/**
12
 * High-level SDK client that aggregates sub-clients for different functionalities
13
 */
14
class Client {
15
  constructor(options: ClientOptions);
16

17
  /** WorkflowClient instance for workflow operations */
18
  readonly workflow: WorkflowClient;
19
  /** AsyncCompletionClient instance for manual activity completion */
20
  readonly activity: AsyncCompletionClient;
21
  /** ScheduleClient instance for schedule operations */
22
  readonly schedule: ScheduleClient;
23
  /** TaskQueueClient instance for task queue operations */
24
  readonly taskQueue: TaskQueueClient;
25
  /** Raw gRPC access to WorkflowService */
26
  readonly workflowService: WorkflowService;
27

28
  /** Execute function with deadline applied to all operations */
29
  withDeadline<R>(deadline: number | Date, fn: () => Promise<R>): Promise<R>;
30
  /** Execute function with abort signal applied to all operations */
31
  withAbortSignal<R>(signal: AbortSignal, fn: () => Promise<R>): Promise<R>;
32
  /** Execute function with metadata applied to all operations */
33
  withMetadata<R>(metadata: Metadata, fn: () => Promise<R>): Promise<R>;
34
}
35

36
interface ClientOptions {
37
  /** Connection to Temporal Server (optional, creates default if not provided) */
38
  connection?: ConnectionLike;
39
  /** Temporal namespace (default: 'default') */
40
  namespace?: string;
41
  /** Data converter for serialization (optional) */
42
  dataConverter?: DataConverter;
43
  /** Client interceptors for custom behavior */
44
  interceptors?: ClientInterceptors;
45
  /** Workflow client configuration */
46
  workflow?: {
47
    /** Should a query be rejected by closed and failed workflows */
48
    queryRejectCondition?: QueryRejectCondition;
49
  };
50
}
51

52
type LoadedClientOptions = Required<ClientOptions>;
53
```
54

55
**Usage Examples:**
56

57
```typescript
58
import { Client, Connection } from "@temporalio/client";
59

60
// Basic client with default connection
61
const client = new Client();
62

63
// Client with custom connection
64
const connection = await Connection.connect({ address: 'temporal.example.com:7233' });
65
const client = new Client({
66
  connection,
67
  namespace: 'production',
68
});
69

70
// Using sub-clients
71
await client.workflow.start('myWorkflow', {
72
  args: ['arg1'],
73
  taskQueue: 'my-task-queue',
74
  workflowId: 'workflow-1',
75
});
76

77
// Context control - execute operation with deadline
78
await client.withDeadline(new Date(Date.now() + 30000), async () => {
79
  return await client.workflow.start('myWorkflow', options);
80
});
81
```
82

83
### Connection Management
84

85
The `Connection` class manages the gRPC connection to Temporal Server with support for TLS, authentication, and connection pooling.
86

87
```typescript { .api }
88
/**
89
 * Client connection to Temporal Server with gRPC service access
90
 */
91
class Connection {
92
  /** Create and verify connection to Temporal Server */
93
  static connect(options: ConnectionOptions): Promise<Connection>;
94
  /** Create lazy connection (connects on first use) */
95
  static lazy(options: ConnectionOptions): Connection;
96

97
  /** Ensure connection is established */
98
  ensureConnected(): Promise<void>;
99
  /** Close connection and cleanup resources */
100
  close(): Promise<void>;
101

102
  /** Execute function with deadline applied to requests */
103
  withDeadline<R>(deadline: number | Date, fn: () => Promise<R>): Promise<R>;
104
  /** Execute function with abort signal applied to requests */
105
  withAbortSignal<R>(signal: AbortSignal, fn: () => Promise<R>): Promise<R>;
106
  /** Execute function with metadata applied to requests */
107
  withMetadata<R>(metadata: Metadata, fn: () => Promise<R>): Promise<R>;
108
  /** Execute function with API key applied to requests */
109
  withApiKey<R>(apiKey: string, fn: () => Promise<R>): Promise<R>;
110
  /** Set persistent API key for all requests */
111
  setApiKey(apiKey: string): void;
112

113
  /** Raw gRPC access to WorkflowService */
114
  readonly workflowService: WorkflowService;
115
  /** Raw gRPC access to OperatorService */
116
  readonly operatorService: OperatorService;
117
  /** Raw gRPC access to TestService */
118
  readonly testService: TestService;
119
  /** Raw gRPC access to HealthService */
120
  readonly healthService: HealthService;
121
}
122

123
interface ConnectionOptions {
124
  /** Temporal Server address (default: 'localhost:7233') */
125
  address?: string;
126
  /** TLS configuration or boolean to enable TLS */
127
  tls?: TLSConfig | boolean;
128
  /** gRPC channel credentials */
129
  credentials?: ChannelCredentials;
130
  /** Call-level credentials */
131
  callCredentials?: CallCredentials[];
132
  /** gRPC channel arguments */
133
  channelArgs?: object;
134
  /** gRPC interceptors */
135
  interceptors?: Interceptor[];
136
  /** Default metadata for all requests */
137
  metadata?: Metadata;
138
  /** API key for Temporal Cloud */
139
  apiKey?: string;
140
  /** Connection timeout in milliseconds or duration string */
141
  connectTimeout?: string | number;
142
}
143

144
type ConnectionOptionsWithDefaults = ConnectionOptions & {
145
  address: string;
146
  tls: boolean | TLSConfig;
147
};
148

149
/** Default localhost target for local development */
150
const LOCAL_TARGET: string;
151
```
152

153
**Usage Examples:**
154

155
```typescript
156
import { Connection, TLSConfig } from "@temporalio/client";
157

158
// Connect to local Temporal server
159
const connection = await Connection.connect();
160

161
// Connect to Temporal Cloud
162
const cloudConnection = await Connection.connect({
163
  address: 'namespace.account.tmprl.cloud:7233',
164
  tls: true,
165
  apiKey: 'your-api-key',
166
});
167

168
// Custom TLS configuration
169
const tlsConfig: TLSConfig = {
170
  clientCertPair: {
171
    crt: clientCert,
172
    key: clientKey,
173
  },
174
  serverNameOverride: 'temporal.example.com',
175
};
176

177
const secureConnection = await Connection.connect({
178
  address: 'temporal.example.com:7233',
179
  tls: tlsConfig,
180
});
181

182
// Lazy connection (connects on first use)
183
const lazyConnection = Connection.lazy({ address: 'remote-temporal:7233' });
184

185
// Connection with timeout
186
const timedConnection = await Connection.connect({
187
  address: 'temporal.example.com:7233',
188
  connectTimeout: '10s',
189
});
190

191
// Access raw gRPC services
192
const healthResponse = await connection.healthService.check({});
193

194
// Context control examples
195
await connection.withDeadline(new Date(Date.now() + 30000), async () => {
196
  return await connection.workflowService.getSystemInfo({});
197
});
198

199
await connection.withMetadata({ 'custom-header': 'value' }, async () => {
200
  return await connection.workflowService.describeNamespace({ name: 'default' });
201
});
202

203
await connection.withApiKey('api-key', async () => {
204
  return await connection.workflowService.listNamespaces({});
205
});
206
```
207

208
### Connection Abstraction
209

210
Interface for connection-like objects that can be used with the Client.
211

212
```typescript { .api }
213
interface ConnectionLike {
214
  workflowService: WorkflowService;
215
  withDeadline<R>(deadline: number | Date, fn: () => Promise<R>): Promise<R>;
216
  withAbortSignal<R>(signal: AbortSignal, fn: () => Promise<R>): Promise<R>;
217
  withMetadata<R>(metadata: Metadata, fn: () => Promise<R>): Promise<R>;
218
}
219
```
220

221
### Base Client Infrastructure
222

223
Base class providing common functionality for all specialized clients.
224

225
```typescript { .api }
226
/**
227
 * Base class for all client implementations
228
 */
229
class BaseClient {
230
  /** Underlying connection instance */
231
  readonly connection: ConnectionLike;
232

233
  /** Execute function with deadline applied to operations */
234
  withDeadline<R>(deadline: number | Date, fn: () => Promise<R>): Promise<R>;
235
  /** Execute function with abort signal applied to operations */
236
  withAbortSignal<R>(signal: AbortSignal, fn: () => Promise<R>): Promise<R>;
237
  /** Execute function with metadata applied to operations */
238
  withMetadata<R>(metadata: Metadata, fn: () => Promise<R>): Promise<R>;
239
}
240

241
interface BaseClientOptions {
242
  connection: ConnectionLike;
243
}
244

245
/** Default client configuration */
246
function defaultBaseClientOptions(): BaseClientOptions;
247
```
248

249
### Context Control Types
250

251
Types for managing request context and gRPC metadata.
252

253
```typescript { .api }
254
/** gRPC metadata mapping */
255
type Metadata = Record<string, string | Buffer | string[] | Buffer[]>;
256

257
/** gRPC call context */
258
interface CallContext {
259
  deadline?: Date;
260
  abortSignal?: AbortSignal;
261
}
262
```