Skip to main content

Class: TemporalClientService

Defined in: src/services/temporal-client.service.ts:47

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, options): TemporalClientService

Defined in: src/services/temporal-client.service.ts:54

Parameters​

temporalClient​

Client | null

options​

TemporalOptions

Returns​

TemporalClientService

Methods​

cancelWorkflow()​

cancelWorkflow(workflowId, runId?): Promise<void>

Defined in: src/services/temporal-client.service.ts:251

Cancel a workflow execution

Parameters​

workflowId​

string

runId?​

string

Returns​

Promise<void>

completeActivity()​

completeActivity(taskTokenOrFullActivityId, result): Promise<void>

Defined in: src/services/temporal-client.service.ts:601

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 | FullActivityId

result​

unknown

Returns​

Promise<void>

Example​

await clientService.completeActivity(taskToken, { approved: true });

countStandaloneActivities()​

countStandaloneActivities(query): Promise<CountActivityExecutions>

Defined in: src/services/temporal-client.service.ts:809

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.

executeStandaloneActivity()​

executeStandaloneActivity<R>(activityType, options): Promise<R>

Defined in: src/services/temporal-client.service.ts:753

Execute a Standalone Activity until completion and return its result.

Type Parameters​

R​

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',
});

failActivity()​

failActivity(taskTokenOrFullActivityId, err): Promise<void>

Defined in: src/services/temporal-client.service.ts:627

Fail an externally-managed Activity, identified by task token or full ID.

Parameters​

taskTokenOrFullActivityId​

Uint8Array | FullActivityId

err​

unknown

Returns​

Promise<void>

Example​

await clientService.failActivity(taskToken, new Error('payment declined'));

getHealth()​

getHealth(): ClientHealthStatus

Defined in: src/services/temporal-client.service.ts:865

Get client health status

Returns​

ClientHealthStatus

getRawClient()​

getRawClient(): Client | null

Defined in: src/services/temporal-client.service.ts:885

Get raw Temporal client (use with caution)

Returns​

Client | null

getStandaloneActivityHandle()​

getStandaloneActivityHandle<R>(activityId, runId?): ActivityHandle<R>

Defined in: src/services/temporal-client.service.ts:778

Get a handle to a Standalone Activity execution by ID.

Type Parameters​

R​

R = unknown

Parameters​

activityId​

string

runId?​

string

Returns​

ActivityHandle<R>

Remarks​

Standalone Activities are a Public Preview Temporal server feature; the underlying API may change in future SDK releases.

getStatus()​

getStatus(): ClientServiceStatus

Defined in: src/services/temporal-client.service.ts:872

Get client status for monitoring

Returns​

ClientServiceStatus

getWorkflowHandle()​

getWorkflowHandle(workflowId, runId?): Promise<WorkflowHandle<Workflow>>

Defined in: src/services/temporal-client.service.ts:214

Get handle to an existing workflow

Parameters​

workflowId​

string

runId?​

string

Returns​

Promise<WorkflowHandle<Workflow>>

getWorkflowResult()​

getWorkflowResult<T>(workflowId, runId?): Promise<T>

Defined in: src/services/temporal-client.service.ts:826

Wait for workflow completion and get result

Type Parameters​

T​

T = unknown

Parameters​

workflowId​

string

runId?​

string

Returns​

Promise<T>

heartbeatActivity()​

heartbeatActivity(taskTokenOrFullActivityId, details?): Promise<void>

Defined in: src/services/temporal-client.service.ts:653

Send a heartbeat for an externally-managed Activity, identified by task token or full ID.

Parameters​

taskTokenOrFullActivityId​

Uint8Array | FullActivityId

details?​

unknown

Returns​

Promise<void>

Example​

await clientService.heartbeatActivity(taskToken, { progress: 50 });

isHealthy()​

isHealthy(): boolean

Defined in: src/services/temporal-client.service.ts:842

Check if client is available and healthy

Returns​

boolean

listStandaloneActivities()​

listStandaloneActivities(query): AsyncIterable<ActivityExecutionInfo>

Defined in: src/services/temporal-client.service.ts:795

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.

onModuleInit()​

onModuleInit(): Promise<void>

Defined in: src/services/temporal-client.service.ts:66

Returns​

Promise<void>

Implementation of​

OnModuleInit.onModuleInit

queryWorkflow()​

queryWorkflow<T>(workflowId, queryName, args?, runId?): Promise<T>

Defined in: src/services/temporal-client.service.ts:410

Query a workflow for its current state

Type Parameters​

T​

T = unknown

Parameters​

workflowId​

string

queryName​

string

args?​

readonly unknown[]

runId?​

string

Returns​

Promise<T>

queryWorkflowHandle()​

queryWorkflowHandle<T>(handle, queryName, args?): Promise<T>

Defined in: src/services/temporal-client.service.ts:434

Query a workflow using handle

Type Parameters​

T​

T = unknown

Parameters​

handle​

WorkflowHandle

queryName​

string

args?​

readonly unknown[]

Returns​

Promise<T>

reportActivityCancellation()​

reportActivityCancellation(taskTokenOrFullActivityId, details?): Promise<void>

Defined in: src/services/temporal-client.service.ts:679

Report cancellation of an externally-managed Activity, identified by task token or full ID.

Parameters​

taskTokenOrFullActivityId​

Uint8Array | FullActivityId

details?​

unknown

Returns​

Promise<void>

Example​

await clientService.reportActivityCancellation(taskToken);

signalWithStart()​

signalWithStart(workflowType, signalName, signalArgs, workflowArgs, options?): Promise<WorkflowHandleWithMetadata>

Defined in: src/services/temporal-client.service.ts:352

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)

options?​

WorkflowStartOptions

Workflow start options (taskQueue, workflowId, etc.)

Returns​

Promise<WorkflowHandleWithMetadata>

Examples​

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' },
);

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}`);

signalWorkflow()​

signalWorkflow(workflowId, signalName, args?, runId?): Promise<void>

Defined in: src/services/temporal-client.service.ts:269

Send a signal to a workflow

Parameters​

workflowId​

string

signalName​

string

args?​

readonly unknown[]

runId?​

string

Returns​

Promise<void>

signalWorkflowHandle()​

signalWorkflowHandle(handle, signalName, args?): Promise<void>

Defined in: src/services/temporal-client.service.ts:295

Send a signal using workflow handle

Parameters​

handle​

WorkflowHandle

signalName​

string

args?​

readonly unknown[]

Returns​

Promise<void>

startStandaloneActivity()​

startStandaloneActivity<R>(activityType, options): Promise<ActivityHandle<R>>

Defined in: src/services/temporal-client.service.ts:718

Start a Standalone Activity execution — a durable, retryable Activity run directly by the client with no workflow involved.

Type Parameters​

R​

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();

startUpdateWorkflow()​

startUpdateWorkflow<T>(workflowId, updateName, args?, runId?): Promise<WorkflowUpdateHandle<T>>

Defined in: src/services/temporal-client.service.ts:534

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​

T = unknown

Parameters​

workflowId​

string

Target workflow ID

updateName​

string

Update name (matches @UpdateMethod or defineUpdate name)

args?​

readonly unknown[]

Arguments for the update handler

runId?​

string

Optional specific run ID

Returns​

Promise<WorkflowUpdateHandle<T>>

Example​

const updateHandle = await clientService.startUpdateWorkflow('account-123', 'deposit', [100]);
const newBalance = await updateHandle.result();

startUpdateWorkflowHandle()​

startUpdateWorkflowHandle<T>(handle, updateName, args?): Promise<WorkflowUpdateHandle<T>>

Defined in: src/services/temporal-client.service.ts:569

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​

T = unknown

Parameters​

handle​

WorkflowHandle

updateName​

string

args?​

readonly unknown[]

Returns​

Promise<WorkflowUpdateHandle<T>>

startWorkflow()​

startWorkflow(workflowType, args?, options?): Promise<WorkflowHandleWithMetadata>

Defined in: src/services/temporal-client.service.ts:91

Start a new workflow execution

Parameters​

workflowType​

string

args?​

readonly unknown[] = []

options?​

WorkflowStartOptions

Returns​

Promise<WorkflowHandleWithMetadata>

terminateWorkflow()​

terminateWorkflow(workflowId, reason?, runId?): Promise<void>

Defined in: src/services/temporal-client.service.ts:233

Terminate a workflow execution

Parameters​

workflowId​

string

reason?​

string

runId?​

string

Returns​

Promise<void>

updateWorkflow()​

updateWorkflow<T>(workflowId, updateName, args?, runId?): Promise<T>

Defined in: src/services/temporal-client.service.ts:469

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​

T = unknown

Parameters​

workflowId​

string

Target workflow ID

updateName​

string

Update name (matches @UpdateMethod or defineUpdate name)

args?​

readonly unknown[]

Arguments for the update handler

runId?​

string

Optional specific run ID

Returns​

Promise<T>

Example​

const newBalance = await clientService.updateWorkflow<number>(
  'account-123',
  'deposit',
  [100],
);

updateWorkflowHandle()​

updateWorkflowHandle<T>(handle, updateName, args?): Promise<T>

Defined in: src/services/temporal-client.service.ts:500

Send an update to a workflow using an existing handle and wait for it to complete.

Type Parameters​

T​

T = unknown

Parameters​

handle​

WorkflowHandle

updateName​

string

args?​

readonly unknown[]

Returns​

Promise<T>