Class TemporalClientService

Temporal Client Service

Provides a clean interface for Temporal client operations including:

Workflow execution (start, terminate, cancel)
Signal and query operations
Workflow handle management
Client health monitoring

Example

// Start a workflow
const handle = await clientService.startWorkflow('myWorkflow', { data: 'example' });

// Send a signal
await clientService.signalWorkflow(handle, 'updateData', 'new data');

// Query workflow state
const result = await clientService.queryWorkflow(handle, 'getStatus');

Implements

OnModuleInit

Constructors

constructor

new TemporalClientService(
temporalClient: Client | null,
options: TemporalOptions,
): TemporalClientService
Parameters
- temporalClient: Client | null
- options: TemporalOptions
Returns TemporalClientService
- Defined in src/services/temporal-client.service.ts:53

Methods

cancelWorkflow

cancelWorkflow(workflowId: string, runId?: string): Promise<void>
Cancel a workflow execution
Parameters
- workflowId: string
- OptionalrunId: string
Returns Promise<void>
- Defined in src/services/temporal-client.service.ts:249

completeActivity

completeActivity(
taskTokenOrFullActivityId: Uint8Array<ArrayBufferLike> | FullActivityId,
result: unknown,
): Promise<void>
Complete an externally-managed Activity, identified by task token or full ID. Use when an Activity signals completion asynchronously (e.g. from another process or a human-in-the-loop step) instead of returning from its handler.
Parameters
- taskTokenOrFullActivityId: Uint8Array<ArrayBufferLike> | FullActivityId
- result: unknown
Returns Promise<void>
Example
```
await clientService.completeActivity(taskToken, { approved: true });
```
- Defined in src/services/temporal-client.service.ts:591

countStandaloneActivities

countStandaloneActivities(query: string): Promise<CountActivityExecutions>
Count Standalone Activity executions matching a visibility query. See https://docs.temporal.io/visibility for query syntax.
Parameters
- query: string
Returns Promise<CountActivityExecutions>

Remarks
Standalone Activities are a Public Preview Temporal server feature; the underlying API may change in future SDK releases.
- Defined in src/services/temporal-client.service.ts:791

executeStandaloneActivity

executeStandaloneActivity<R = unknown>(
activityType: string,
options: StandaloneActivityOptions,
): Promise<R>
Execute a Standalone Activity until completion and return its result.
Type Parameters
- R = unknown
Parameters
- activityType: string
- options: StandaloneActivityOptions
Returns Promise<R>
Remarks
Standalone Activities are a Public Preview Temporal server feature; the underlying API may change in future SDK releases.
Example
```
const result = await clientService.executeStandaloneActivity('sendEmail', {
  id: 'email-123',
  taskQueue: 'emails',
  args: ['user@example.com'],
  startToCloseTimeout: '1m',
});
```
- Defined in src/services/temporal-client.service.ts:736

failActivity

failActivity(
taskTokenOrFullActivityId: Uint8Array<ArrayBufferLike> | FullActivityId,
err: unknown,
): Promise<void>
Fail an externally-managed Activity, identified by task token or full ID.
Parameters
- taskTokenOrFullActivityId: Uint8Array<ArrayBufferLike> | FullActivityId
- err: unknown
Returns Promise<void>
Example
```
await clientService.failActivity(taskToken, new Error('payment declined'));
```
- Defined in src/services/temporal-client.service.ts:614

getHealth

getHealth(): ClientHealthStatus
Get client health status

Returns ClientHealthStatus
- Defined in src/services/temporal-client.service.ts:846

getRawClient

getRawClient(): Client | null
Get raw Temporal client (use with caution)

Returns Client | null
- Defined in src/services/temporal-client.service.ts:866

getStandaloneActivityHandle

getStandaloneActivityHandle<R = unknown>(
activityId: string,
runId?: string,
): ActivityHandle<R>
Get a handle to a Standalone Activity execution by ID.
Type Parameters
- R = unknown
Parameters
- activityId: string
- OptionalrunId: string
Returns ActivityHandle<R>

Remarks
Standalone Activities are a Public Preview Temporal server feature; the underlying API may change in future SDK releases.
- Defined in src/services/temporal-client.service.ts:760

getStatus

getStatus(): ClientServiceStatus
Get client status for monitoring

Returns ClientServiceStatus
- Defined in src/services/temporal-client.service.ts:853

getWorkflowHandle

getWorkflowHandle(
workflowId: string,
runId?: string,
): Promise<WorkflowHandle<Workflow>>
Get handle to an existing workflow
Parameters
- workflowId: string
- OptionalrunId: string
Returns Promise<WorkflowHandle<Workflow>>
- Defined in src/services/temporal-client.service.ts:213

getWorkflowResult

getWorkflowResult<T = unknown>(workflowId: string, runId?: string): Promise<T>
Wait for workflow completion and get result
Type Parameters
- T = unknown
Parameters
- workflowId: string
- OptionalrunId: string
Returns Promise<T>
- Defined in src/services/temporal-client.service.ts:807

heartbeatActivity

heartbeatActivity(
taskTokenOrFullActivityId: Uint8Array<ArrayBufferLike> | FullActivityId,
details?: unknown,
): Promise<void>
Send a heartbeat for an externally-managed Activity, identified by task token or full ID.
Parameters
- taskTokenOrFullActivityId: Uint8Array<ArrayBufferLike> | FullActivityId
- Optionaldetails: unknown
Returns Promise<void>
Example
```
await clientService.heartbeatActivity(taskToken, { progress: 50 });
```
- Defined in src/services/temporal-client.service.ts:639

isHealthy

isHealthy(): boolean
Check if client is available and healthy

Returns boolean
- Defined in src/services/temporal-client.service.ts:823

listStandaloneActivities

listStandaloneActivities(query: string): AsyncIterable<ActivityExecutionInfo>
List Standalone Activity executions matching a visibility query. See https://docs.temporal.io/visibility for query syntax.
Parameters
- query: string
Returns AsyncIterable<ActivityExecutionInfo>

Remarks
Standalone Activities are a Public Preview Temporal server feature; the underlying API may change in future SDK releases.
- Defined in src/services/temporal-client.service.ts:777

onModuleInit

onModuleInit(): Promise<void>
Returns Promise<void>
Implementation of OnModuleInit.onModuleInit
- Defined in src/services/temporal-client.service.ts:65

queryWorkflow

queryWorkflow<T = unknown>(
    workflowId: string,
    queryName: string,
    args?: readonly unknown[],
    runId?: string,
): Promise<T>
Query a workflow for its current state
Type Parameters
- T = unknown
Parameters
- workflowId: string
- queryName: string
- Optionalargs: readonly unknown[]
- OptionalrunId: string
Returns Promise<T>
- Defined in src/services/temporal-client.service.ts:403

queryWorkflowHandle

queryWorkflowHandle<T = unknown>(
    handle: WorkflowHandle,
    queryName: string,
    args?: readonly unknown[],
): Promise<T>
Query a workflow using handle
Type Parameters
- T = unknown
Parameters
- handle: WorkflowHandle
- queryName: string
- Optionalargs: readonly unknown[]
Returns Promise<T>
- Defined in src/services/temporal-client.service.ts:426

reportActivityCancellation

reportActivityCancellation(
taskTokenOrFullActivityId: Uint8Array<ArrayBufferLike> | FullActivityId,
details?: unknown,
): Promise<void>
Report cancellation of an externally-managed Activity, identified by task token or full ID.
Parameters
- taskTokenOrFullActivityId: Uint8Array<ArrayBufferLike> | FullActivityId
- Optionaldetails: unknown
Returns Promise<void>
Example
```
await clientService.reportActivityCancellation(taskToken);
```
- Defined in src/services/temporal-client.service.ts:664

signalWithStart

signalWithStart(
    workflowType: string,
    signalName: string,
    signalArgs: readonly unknown[],
    workflowArgs: readonly unknown[],
    options?: WorkflowStartOptions,
): Promise<WorkflowHandleWithMetadata>
Atomically start a workflow and send a signal to it.

If the workflow is already running, only the signal is delivered. This is Temporal's signalWithStart operation — useful for ensuring a workflow is running before sending a signal without a race condition.
Parameters
- workflowType: string
  Temporal workflow type name
- signalName: string
  Signal name (string) to send
- signalArgs: readonly unknown[]
  Arguments for the signal
- workflowArgs: readonly unknown[]
  Arguments to start the workflow with (used only when starting)
- Optionaloptions: WorkflowStartOptions
  Workflow start options (taskQueue, workflowId, etc.)
Returns Promise<WorkflowHandleWithMetadata>
Example: Ensure a cart workflow is running, then apply an item
```
// Idempotent: starts the cart the first time, signals it every time.
await clientService.signalWithStart(
  'cartWorkflow',
  'addItem',
  [{ sku: 'SKU-123', qty: 2 }],
  [userId],                                 // args passed to cartWorkflow on first start
  { workflowId: `cart-${userId}`, taskQueue: 'carts' },
);
```
Example: With reuse policy and timeouts
```
const handle = await clientService.signalWithStart(
  'orderWorkflow',
  'approve',
  ['manager-approval'],
  [orderId, customerId],
  {
    workflowId: `order-${orderId}`,
    taskQueue: 'orders',
    workflowIdReusePolicy: 'ALLOW_DUPLICATE',
    workflowExecutionTimeout: '1h',
    memo: { source: 'api' },
  },
);
console.log(`Signaled + maybe-started: ${handle.workflowId}`);
```
- Defined in src/services/temporal-client.service.ts:348

signalWorkflow

signalWorkflow(
    workflowId: string,
    signalName: string,
    args?: readonly unknown[],
    runId?: string,
): Promise<void>
Send a signal to a workflow
Parameters
- workflowId: string
- signalName: string
- Optionalargs: readonly unknown[]
- OptionalrunId: string
Returns Promise<void>
- Defined in src/services/temporal-client.service.ts:266

signalWorkflowHandle

signalWorkflowHandle(
    handle: WorkflowHandle,
    signalName: string,
    args?: readonly unknown[],
): Promise<void>
Send a signal using workflow handle
Parameters
- handle: WorkflowHandle
- signalName: string
- Optionalargs: readonly unknown[]
Returns Promise<void>
- Defined in src/services/temporal-client.service.ts:291

startStandaloneActivity

startStandaloneActivity<R = unknown>(
activityType: string,
options: StandaloneActivityOptions,
): Promise<ActivityHandle<R>>
Start a Standalone Activity execution — a durable, retryable Activity run directly by the client with no workflow involved.
Type Parameters
- R = unknown
Parameters
- activityType: string
- options: StandaloneActivityOptions
Returns Promise<ActivityHandle<R>>
Remarks
Standalone Activities are a Public Preview Temporal server feature; the underlying API may change in future SDK releases.
Example
```
const handle = await clientService.startStandaloneActivity('sendEmail', {
  id: 'email-123',
  taskQueue: 'emails',
  args: ['user@example.com'],
  startToCloseTimeout: '1m',
});
const result = await handle.result();
```
- Defined in src/services/temporal-client.service.ts:702

startUpdateWorkflow

startUpdateWorkflow<T = unknown>(
    workflowId: string,
    updateName: string,
    args?: readonly unknown[],
    runId?: string,
): Promise<WorkflowUpdateHandle<T>>
Start an update and return a handle once the update has been accepted by the workflow, without waiting for it to complete. Use WorkflowUpdateHandle.result() to await the outcome.
Type Parameters
- T = unknown
Parameters
- workflowId: string
  Target workflow ID
- updateName: string
  Update name (matches @UpdateMethod or defineUpdate name)
- Optionalargs: readonly unknown[]
  Arguments for the update handler
- OptionalrunId: string
  Optional specific run ID
Returns Promise<WorkflowUpdateHandle<T>>
Example
```
const updateHandle = await clientService.startUpdateWorkflow('account-123', 'deposit', [100]);
const newBalance = await updateHandle.result();
```
- Defined in src/services/temporal-client.service.ts:525

startUpdateWorkflowHandle

startUpdateWorkflowHandle<T = unknown>(
    handle: WorkflowHandle,
    updateName: string,
    args?: readonly unknown[],
): Promise<WorkflowUpdateHandle<T>>
Start an update using an existing handle and return a handle to the update once it has been accepted, without waiting for it to complete.
Type Parameters
- T = unknown
Parameters
- handle: WorkflowHandle
- updateName: string
- Optionalargs: readonly unknown[]
Returns Promise<WorkflowUpdateHandle<T>>
- Defined in src/services/temporal-client.service.ts:559

startWorkflow

startWorkflow(
    workflowType: string,
    args?: readonly unknown[],
    options?: WorkflowStartOptions,
): Promise<WorkflowHandleWithMetadata>
Start a new workflow execution
Parameters
- workflowType: string
- args: readonly unknown[] = []
- Optionaloptions: WorkflowStartOptions
Returns Promise<WorkflowHandleWithMetadata>
- Defined in src/services/temporal-client.service.ts:90

terminateWorkflow

terminateWorkflow(
    workflowId: string,
    reason?: string,
    runId?: string,
): Promise<void>
Terminate a workflow execution
Parameters
- workflowId: string
- Optionalreason: string
- OptionalrunId: string
Returns Promise<void>
- Defined in src/services/temporal-client.service.ts:232

updateWorkflow

updateWorkflow<T = unknown>(
    workflowId: string,
    updateName: string,
    args?: readonly unknown[],
    runId?: string,
): Promise<T>
Send an update to a workflow and wait for it to complete.

Updates combine the strengths of Signals (can mutate workflow state) and Queries (can return a result) into a single request/response operation.
Type Parameters
- T = unknown
Parameters
- workflowId: string
  Target workflow ID
- updateName: string
  Update name (matches @UpdateMethod or defineUpdate name)
- Optionalargs: readonly unknown[]
  Arguments for the update handler
- OptionalrunId: string
  Optional specific run ID
Returns Promise<T>
Example
```
const newBalance = await clientService.updateWorkflow<number>(
  'account-123',
  'deposit',
  [100],
);
```
- Defined in src/services/temporal-client.service.ts:461

updateWorkflowHandle

updateWorkflowHandle<T = unknown>(
    handle: WorkflowHandle,
    updateName: string,
    args?: readonly unknown[],
): Promise<T>
Send an update to a workflow using an existing handle and wait for it to complete.
Type Parameters
- T = unknown
Parameters
- handle: WorkflowHandle
- updateName: string
- Optionalargs: readonly unknown[]
Returns Promise<T>
- Defined in src/services/temporal-client.service.ts:491

Class TemporalClientService

Example

Implements

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns TemporalClientService

Methods

cancelWorkflow

Parameters

Returns Promise<void>

completeActivity

Parameters

Returns Promise<void>

Example

countStandaloneActivities

Parameters

Returns Promise<CountActivityExecutions>

Remarks

executeStandaloneActivity

Type Parameters

Parameters

Returns Promise<R>

Remarks

Example

failActivity

Parameters

Returns Promise<void>

Example

getHealth

Returns ClientHealthStatus

getRawClient

Returns Client | null

getStandaloneActivityHandle

Type Parameters

Parameters

Returns ActivityHandle<R>

Remarks

getStatus

Returns ClientServiceStatus

getWorkflowHandle

Parameters

Returns Promise<WorkflowHandle<Workflow>>

getWorkflowResult

Type Parameters

Parameters

Returns Promise<T>

heartbeatActivity

Parameters

Returns Promise<void>

Example

isHealthy

Returns boolean

listStandaloneActivities

Parameters

Returns AsyncIterable<ActivityExecutionInfo>

Remarks

onModuleInit

Returns Promise<void>

queryWorkflow

Type Parameters

Parameters

Returns Promise<T>

queryWorkflowHandle

Type Parameters

Parameters

Returns Promise<T>

reportActivityCancellation

Parameters

Returns Promise<void>

Example

signalWithStart

Parameters

Returns Promise<WorkflowHandleWithMetadata>

Example: Ensure a cart workflow is running, then apply an item

Example: With reuse policy and timeouts

signalWorkflow