Class: Connection
client.Connection
Client connection to the Temporal Server
⚠️ Connections are expensive to construct and should be reused. Make sure to close any unused connections to avoid leaking resources.
Properties
callContextStorage
• Readonly callContextStorage: AsyncLocalStorage<CallContext>
healthService
• Readonly healthService: Health
Raw gRPC access to the standard gRPC health service.
operatorService
• Readonly operatorService: OperatorService
Raw gRPC access to Temporal Server's Operator service
The Operator Service API defines how Temporal SDKs and other clients interact with the Temporal server to perform administrative functions like registering a search attribute or a namespace.
This Service API is NOT compatible with Temporal Cloud. Attempt to use it against a Temporal
Cloud namespace will result in gRPC unauthorized error.
options
• Readonly options: ConnectionOptionsWithDefaults
plugins
• Readonly plugins: ConnectionPlugin[]
testService
• Readonly testService: undefined | TestService
Raw gRPC access to the Temporal test service.
Will be undefined if connected to a server that does not support the test service.
workflowService
• Readonly workflowService: WorkflowService
Raw gRPC access to Temporal Server's Workflow service
Methods
close
▸ close(): Promise<void>
Close the underlying gRPC client.
Make sure to call this method to ensure proper resource cleanup.
Returns
Promise<void>
ensureConnected
▸ ensureConnected(): Promise<void>
Ensure connection can be established.
Does not need to be called if you use connect.
This method's result is memoized to ensure it runs only once.
Calls proto.temporal.api.workflowservice.v1.WorkflowService.getSystemInfo internally.
Returns
Promise<void>
setApiKey
▸ setApiKey(apiKey): void
Set the ConnectionOptions.apiKey for all subsequent requests. A static string or a callback function may be provided.
Parameters
| Name | Type |
|---|---|
apiKey | string | () => string |
Returns
void
withAbortSignal
▸ withAbortSignal<ReturnType>(abortSignal, fn): Promise<ReturnType>
Set an AbortSignal that, when aborted, cancels any ongoing service requests executed in
fn's scope. This will locally result in the request call throwing a grpc.ServiceError|ServiceError
with code grpc.status.CANCELLED|CANCELLED; see isGrpcCancelledError.
This method is only a convenience wrapper around Connection.withAbortSignal.
Type parameters
| Name |
|---|
ReturnType |
Parameters
| Name | Type |
|---|---|
abortSignal | AbortSignal |
fn | () => Promise<ReturnType> |
Returns
Promise<ReturnType>
value returned from fn
Example
const ctrl = new AbortController();
setTimeout(() => ctrl.abort(), 10_000);
// 👇 throws if incomplete by the timeout.
await conn.withAbortSignal(ctrl.signal, () => client.workflow.execute(myWorkflow, options));
See
https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
withApiKey
▸ withApiKey<ReturnType>(apiKey, fn): Promise<ReturnType>
Set the apiKey for any service requests executed in fn's scope (thus changing the Authorization header).
Type parameters
| Name |
|---|
ReturnType |
Parameters
| Name | Type |
|---|---|
apiKey | string |
fn | () => Promise<ReturnType> |
Returns
Promise<ReturnType>
value returned from fn
Example
const workflowHandle = await conn.withApiKey('secret', () =>
conn.withMetadata({ otherKey: 'set' }, () => client.start(options)))
);
withDeadline
▸ withDeadline<ReturnType>(deadline, fn): Promise<ReturnType>
Set a deadline for any service requests executed in fn's scope.
The deadline is a point in time after which any pending gRPC request will be considered as failed; this will locally result in the request call throwing a grpc.ServiceError|ServiceError with code grpc.status.DEADLINE_EXCEEDED|DEADLINE_EXCEEDED; see isGrpcDeadlineError.
It is strongly recommended to explicitly set deadlines. If no deadline is set, then it is possible for the client to end up waiting forever for a response.
Type parameters
| Name |
|---|
ReturnType |
Parameters
| Name | Type | Description |
|---|---|---|
deadline | number | Date | a point in time after which the request will be considered as failed; either a Date object, or a number of milliseconds since the Unix epoch (UTC). |
fn | () => Promise<ReturnType> | - |
Returns
Promise<ReturnType>
the value returned from fn
See
https://grpc.io/docs/guides/deadlines/
withMetadata
▸ withMetadata<ReturnType>(metadata, fn): Promise<ReturnType>
Set metadata for any service requests executed in fn's scope.
The provided metadata is merged on top of any existing metadata in current scope, including metadata provided in ConnectionOptions.metadata.
Type parameters
| Name |
|---|
ReturnType |
Parameters
| Name | Type |
|---|---|
metadata | Metadata |
fn | () => Promise<ReturnType> |
Returns
Promise<ReturnType>
value returned from fn
Example
const workflowHandle = await conn.withMetadata({ apiKey: 'secret' }, () =>
conn.withMetadata({ otherKey: 'set' }, () => client.start(options)))
);
connect
▸ connect(options?): Promise<Connection>
Establish a connection with the server and return a Connection instance.
This is the preferred method of creating connections as it verifies connectivity by calling ensureConnected.
Parameters
| Name | Type |
|---|---|
options? | ConnectionOptions |
Returns
Promise<Connection>
lazy
▸ lazy(options?): Connection
Create a lazy Connection instance.
This method does not verify connectivity with the server. We recommend using connect instead.
Parameters
| Name | Type |
|---|---|
options? | ConnectionOptions |