nestjs-temporal-core
    Preparing search index...

    Interface IWorkflowProxy<T>

    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.

    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);
    interface IWorkflowProxy<T extends Workflow> {
        getHandle(
            workflowId: string,
            runId?: string,
        ): Promise<WorkflowHandle<T>>;
        query<TResult, TArgs extends unknown[] = []>(
            workflowId: string,
            queryDef: QueryDefinition<TResult, TArgs>,
            ...args: TArgs,
        ): Promise<TResult>;
        queryByName<TResult>(
            workflowId: string,
            queryName: string,
            args?: readonly unknown[],
        ): Promise<TResult>;
        signal<TArgs extends unknown[]>(
            workflowId: string,
            signalDef: SignalDefinition<TArgs>,
            ...args: TArgs,
        ): Promise<void>;
        signalByName(
            workflowId: string,
            signalName: string,
            args?: readonly unknown[],
        ): Promise<void>;
        signalWithStart<TSignalArgs extends unknown[]>(
            signalDef: SignalDefinition<TSignalArgs>,
            signalArgs: TSignalArgs,
            workflowArgs: Parameters<T>,
            options?: WorkflowStartOptions,
        ): Promise<WorkflowHandleWithMetadata<T>>;
        start(
            args: Parameters<T>,
            options?: WorkflowStartOptions,
        ): Promise<WorkflowHandleWithMetadata<T>>;
    }

    Type Parameters

    • T extends Workflow

      A Temporal Workflow function type

    Implemented by

    Index

    Methods

    getHandle query queryByName signal signalByName signalWithStart start

    Methods

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

      Parameters

      • workflowId: string
      • OptionalrunId: string

      Returns Promise<WorkflowHandle<T>>

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

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

      Type Parameters

      • TResult
      • TArgs extends unknown[] = []

      Parameters

      Returns Promise<TResult>

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

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

      Type Parameters

      • TResult

      Parameters

      • workflowId: string
      • queryName: string
      • Optionalargs: readonly unknown[]

      Returns Promise<TResult>

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

    • 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 extends unknown[]

      Parameters

      • workflowId: string
      • signalDef: SignalDefinition<TArgs>
      • ...args: TArgs

      Returns Promise<void>

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

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

      Parameters

      • workflowId: string
      • signalName: string
      • Optionalargs: readonly unknown[]

      Returns Promise<void>

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

    • 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 extends unknown[]

      Parameters

      Returns Promise<WorkflowHandleWithMetadata<T>>

      // 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 a new execution of this workflow. Args are typed as Parameters<T> — TypeScript enforces the workflow's signature.

      Parameters

      Returns Promise<WorkflowHandleWithMetadata<T>>

      // 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 }

    Settings

    Member Visibility

    On This Page

    Methods