Skip to main content

Class: WorkflowProxy<T>

Defined in: src/workflow-proxy/workflow-proxy.ts:199

Concrete implementation of IWorkflowProxy<T>.

Plain class — not @Injectable. Instances are created by WorkflowProxyFactory and registered as NestJS providers via createWorkflowProvider().

Type Parameters​

T​

T extends Workflow

Implements​

Constructors​

Constructor​

new WorkflowProxy<T>(clientService, config): WorkflowProxy<T>

Defined in: src/workflow-proxy/workflow-proxy.ts:200

Parameters​

clientService​

TemporalClientService

config​

WorkflowProxyConfig

Returns​

WorkflowProxy<T>

Methods​

getHandle()​

getHandle(workflowId, runId?): Promise<WorkflowHandle<T>>

Defined in: src/workflow-proxy/workflow-proxy.ts:217

Get a typed handle to an existing workflow execution. result() on the handle returns Promise<WorkflowResultType<T>>.

Parameters​

workflowId​

string

runId?​

string

Returns​

Promise<WorkflowHandle<T>>

Example​

const handle = await this.orderProxy.getHandle('order-42');
const result = await handle.result(); // typed as the workflow's return type

Implementation of​

IWorkflowProxy.getHandle

query()​

query<TResult, TArgs>(workflowId, queryDef, ...args): Promise<TResult>

Defined in: src/workflow-proxy/workflow-proxy.ts:238

Query the workflow using a typed QueryDefinition created with defineQuery. TResult and TArgs are both inferred from the definition.

Type Parameters​

TResult​

TResult

TArgs​

TArgs extends unknown[] = []

Parameters​

workflowId​

string

queryDef​

QueryDefinition<TResult, TArgs>

args​

...TArgs

Returns​

Promise<TResult>

Example​

// in workflow file: export const statusQuery = defineQuery<OrderStatus>('getStatus');
const status = await this.orderProxy.query('order-42', statusQuery); // typed: OrderStatus

// query with args:
// export const itemQuery = defineQuery<Item, [string]>('getItem');
const item = await this.orderProxy.query('order-42', itemQuery, 'item-id');

Implementation of​

IWorkflowProxy.query

queryByName()​

queryByName<TResult>(workflowId, queryName, args?): Promise<TResult>

Defined in: src/workflow-proxy/workflow-proxy.ts:246

Query by string name. Use when a QueryDefinition is unavailable. Caller must supply TResult explicitly (e.g. queryByName<OrderStatus>(...)).

Type Parameters​

TResult​

TResult

Parameters​

workflowId​

string

queryName​

string

args?​

readonly unknown[]

Returns​

Promise<TResult>

Example​

const status = await this.orderProxy.queryByName<OrderStatus>(
  'order-42',
  'getStatus',
);

Implementation of​

IWorkflowProxy.queryByName

signal()​

signal<TArgs>(workflowId, signalDef, ...args): Promise<void>

Defined in: src/workflow-proxy/workflow-proxy.ts:222

Send a typed signal using a SignalDefinition created with defineSignal. TypeScript infers TArgs from the definition — call site is fully type-checked.

Type Parameters​

TArgs​

TArgs extends unknown[]

Parameters​

workflowId​

string

signalDef​

SignalDefinition<TArgs>

args​

...TArgs

Returns​

Promise<void>

Example​

// in workflow file: export const approveSignal = defineSignal<[string]>('approve');
await this.orderProxy.signal('order-42', approveSignal, 'manager-approval');

Implementation of​

IWorkflowProxy.signal

signalByName()​

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

Defined in: src/workflow-proxy/workflow-proxy.ts:230

Send a signal by string name. Use when a SignalDefinition is unavailable. Args are readonly unknown[] — no implicit any.

Parameters​

workflowId​

string

signalName​

string

args?​

readonly unknown[]

Returns​

Promise<void>

Example​

await this.orderProxy.signalByName('order-42', 'approve', ['manager-approval']);

Implementation of​

IWorkflowProxy.signalByName

signalWithStart()​

signalWithStart<TSignalArgs>(signalDef, signalArgs, workflowArgs, options?): Promise<WorkflowHandleWithMetadata<T>>

Defined in: src/workflow-proxy/workflow-proxy.ts:270

Atomically start the workflow and send a signal. If the workflow is already running, only the signal is delivered (no duplicate start). Both signalArgs and workflowArgs are fully typed via the respective definitions.

Type Parameters​

TSignalArgs​

TSignalArgs extends unknown[]

Parameters​

signalDef​

SignalDefinition<TSignalArgs>

signalArgs​

TSignalArgs

workflowArgs​

Parameters<T>

options?​

WorkflowStartOptions

Returns​

Promise<WorkflowHandleWithMetadata<T>>

Example​

Idempotent "ensure running + signal"

// export const addItemSignal = defineSignal<[CartItem]>('addItem');
await this.cartProxy.signalWithStart(
  addItemSignal,
  [{ sku: 'SKU-123', qty: 2 }],   // signalArgs — typed
  [userId],                        // workflowArgs — typed as Parameters<cartWorkflow>
  { workflowId: `cart-${userId}`, taskQueue: 'carts' },
);

Implementation of​

IWorkflowProxy.signalWithStart

start()​

start(args, options?): Promise<WorkflowHandleWithMetadata<T>>

Defined in: src/workflow-proxy/workflow-proxy.ts:205

Start a new execution of this workflow. Args are typed as Parameters<T> — TypeScript enforces the workflow's signature.

Parameters​

args​

Parameters<T>

options?​

WorkflowStartOptions

Returns​

Promise<WorkflowHandleWithMetadata<T>>

Example​

// orderWorkflow: (orderId: string, customerId: number) => Promise<{ status: string }>
const handle = await this.orderProxy.start(
  ['order-42', 7],
  { workflowId: 'order-42', workflowIdReusePolicy: 'ALLOW_DUPLICATE' },
);
const { status } = await handle.result(); // typed: { status: string }

Implementation of​

IWorkflowProxy.start

update()​

update<TResult, TArgs>(workflowId, updateDef, ...args): Promise<TResult>

Defined in: src/workflow-proxy/workflow-proxy.ts:254

Send a typed update using an UpdateDefinition created with defineUpdate, and wait for it to complete. Updates can mutate workflow state and return a result. TypeScript infers TResult/TArgs from the definition — call site is fully type-checked.

Type Parameters​

TResult​

TResult

TArgs​

TArgs extends unknown[] = []

Parameters​

workflowId​

string

updateDef​

UpdateDefinition<TResult, TArgs>

args​

...TArgs

Returns​

Promise<TResult>

Example​

// in workflow file: export const depositUpdate = defineUpdate<number, [number]>('deposit');
const newBalance = await this.accountProxy.update('account-42', depositUpdate, 100);

Implementation of​

IWorkflowProxy.update

updateByName()​

updateByName<TResult>(workflowId, updateName, args?): Promise<TResult>

Defined in: src/workflow-proxy/workflow-proxy.ts:262

Send an update by string name. Use when an UpdateDefinition is unavailable. Caller must supply TResult explicitly (e.g. updateByName<number>(...)).

Type Parameters​

TResult​

TResult

Parameters​

workflowId​

string

updateName​

string

args?​

readonly unknown[]

Returns​

Promise<TResult>

Example​

const newBalance = await this.accountProxy.updateByName<number>(
  'account-42',
  'deposit',
  [100],
);

Implementation of​

IWorkflowProxy.updateByName