Skip to main content

Interface: IWorkflowProxy<T>

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

Typed proxy interface for interacting with a specific workflow type.

T must be a Temporal workflow function type (e.g. typeof myWorkflow). All method signatures are inferred from T — no any, no unknown[] at the call site.

Example​

constructor(
  @Inject(ORDER_WORKFLOW)
  private readonly orderProxy: IWorkflowProxy<typeof orderWorkflow>,
) {}

// start — args are typed as Parameters<typeof orderWorkflow>
await this.orderProxy.start([orderId, customerId], { workflowId: `order-${orderId}` });

// signal — TArgs inferred from the SignalDefinition
await this.orderProxy.signal(workflowId, approveSignal, reason);

// query — return type inferred from the QueryDefinition
const status: OrderStatus = await this.orderProxy.query(workflowId, statusQuery);

Type Parameters​

T​

T extends Workflow

A Temporal Workflow function type

Methods​

getHandle()​

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

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

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

query()​

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

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

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

queryByName()​

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

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

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

signal()​

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

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

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

signalByName()​

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

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

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']);

signalWithStart()​

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

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

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

start()​

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

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

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 }

update()​

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

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

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

updateByName()​

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

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

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],
);