Workflow Client

/**
 * Client for starting and interacting with workflows
 */
class WorkflowClient extends BaseClient {
  /** Start new workflow execution */
  start<T extends Workflow>(
    workflowTypeOrFunc: string | T,
    options: WorkflowStartOptions<T>
  ): Promise<WorkflowHandleWithFirstExecutionRunId<T>>;

  /** Start workflow and wait for result */
  execute<T extends Workflow>(
    workflowTypeOrFunc: string | T,
    options: WorkflowStartOptions<T>
  ): Promise<WorkflowResultType<T>>;

  /** Get workflow execution result */
  result<T extends Workflow>(
    workflowId: string,
    runId?: string,
    opts?: WorkflowResultOptions
  ): Promise<WorkflowResultType<T>>;

  /** Start workflow with initial signal */
  signalWithStart<T extends Workflow, SignalArgs extends any[]>(
    workflowTypeOrFunc: string,
    options: WorkflowSignalWithStartOptions<SignalArgs>
  ): Promise<WorkflowHandleWithSignaledRunId<WorkflowResultType<T>>>;

  /** Execute workflow update and wait for result */
  executeUpdateWithStart<T extends Workflow, Ret, Args extends any[]>(
    workflowTypeOrFunc: string,
    updateOptions: WorkflowUpdateWithStartOptions<Ret, Args>
  ): Promise<Ret>;

  /** Start workflow update and return handle */
  startUpdateWithStart<T extends Workflow, Ret, Args extends any[]>(
    workflowTypeOrFunc: string,
    updateOptions: WorkflowUpdateWithStartOptions<Ret, Args>
  ): Promise<WorkflowUpdateHandle<Ret>>;

  /** Get handle to existing workflow */
  getHandle<T extends Workflow>(
    workflowId: string,
    runId?: string,
    options?: GetWorkflowHandleOptions
  ): WorkflowHandle<WorkflowResultType<T>>;

  /** List workflow executions */
  list(options?: ListOptions): AsyncWorkflowListIterable;

  /** Count workflow executions */
  count(query?: string): Promise<CountWorkflowExecution>;

  /** Raw gRPC access to WorkflowService */
  readonly workflowService: WorkflowService;
}

interface WorkflowClientOptions extends BaseClientOptions {
  namespace?: string;
  dataConverter?: DataConverter;
  interceptors?: WorkflowClientInterceptor[];
}

interface WorkflowHandleWithFirstExecutionRunId<T = any> extends WorkflowHandle<T> {
  readonly firstExecutionRunId: string;
}

interface WorkflowHandleWithSignaledRunId<T = any> extends WorkflowHandle<T> {
  readonly signaledRunId: string;
}

interface CountWorkflowExecution {
  count: number;
}

import { WorkflowClient } from "@temporalio/client";

const client = new WorkflowClient();

// Start workflow
const handle = await client.start('processOrder', {
  args: [{ orderId: '12345', customerId: 'cust-456' }],
  taskQueue: 'order-processing',
  workflowId: 'order-12345',
});

// Start and wait for result
const result = await client.execute('calculateTotal', {
  args: [100, 0.08],
  taskQueue: 'math-operations',
  workflowId: 'calc-' + Date.now(),
});

// Get existing workflow handle
const existingHandle = client.getHandle('order-12345');
const orderResult = await existingHandle.result();

/**
 * Handle to single workflow instance
 */
interface WorkflowHandle<T> {
  /** Workflow identifier */
  readonly workflowId: string;
  /** Run identifier (undefined for workflow started via signalWithStart) */
  readonly runId: string | undefined;
  /** First execution run identifier */
  readonly firstExecutionRunId: string;
  /** Reference to WorkflowClient */
  readonly client: WorkflowClient;

  /** Execute workflow update and wait for result */
  executeUpdate<Ret, Args extends any[]>(
    def: UpdateDefinition<Ret, Args> | string,
    options?: WorkflowUpdateOptions,
    ...args: Args
  ): Promise<Ret>;

  /** Start workflow update and return handle */
  startUpdate<Ret, Args extends any[]>(
    def: UpdateDefinition<Ret, Args> | string,
    options?: WorkflowUpdateOptions,
    ...args: Args
  ): Promise<WorkflowUpdateHandle<Ret>>;

  /** Get handle to existing update */
  getUpdateHandle<Ret>(updateId: string): WorkflowUpdateHandle<Ret>;

  /** Query workflow */
  query<Ret, Args extends any[]>(
    def: QueryDefinition<Ret, Args> | string,
    ...args: Args
  ): Promise<Ret>;

  /** Send signal to workflow */
  signal<Args extends any[]>(
    def: SignalDefinition<Args> | string,
    ...args: Args
  ): Promise<void>;

  /** Terminate workflow execution */
  terminate(reason?: string): Promise<void>;

  /** Cancel workflow execution */
  cancel(): Promise<void>;

  /** Get workflow description */
  describe(): Promise<WorkflowExecutionDescription>;

  /** Fetch workflow history */
  fetchHistory(options?: FetchHistoryOptions): AsyncIterable<HistoryEvent>;

  /** Get workflow execution result */
  result(): Promise<T>;
}

interface WorkflowHandleWithFirstExecutionRunId<T>
  extends WorkflowHandle<T> {
  readonly firstExecutionRunId: string;
}

interface WorkflowHandleWithSignaledRunId<T> extends WorkflowHandle<T> {
  readonly signaledRunId: string;
}

// Query workflow state
const status = await handle.query('getCurrentStatus');

// Send signal
await handle.signal('processPayment', { amount: 100, paymentMethod: 'credit' });

// Execute update
const updatedValue = await handle.executeUpdate('updateConfiguration', {
  waitForStage: WorkflowUpdateStage.COMPLETED,
}, { setting1: 'value1' });

// Cancel workflow
await handle.cancel();

// Get workflow description
const description = await handle.describe();
console.log('Workflow status:', description.status);

/**
 * Handle to workflow update operation
 */
interface WorkflowUpdateHandle<Ret> {
  /** Update identifier */
  readonly updateId: string;
  /** Workflow identifier */
  readonly workflowId: string;
  /** Workflow run identifier */
  readonly workflowRunId: string;

  /** Get update result */
  result(): Promise<Ret>;
}

/**
 * Defines workflow to start with update operations
 */
class WithStartWorkflowOperation<T> {
  /** Get promise to workflow handle */
  workflowHandle(): Promise<WorkflowHandle<T>>;
}

/**
 * Options for starting workflows
 */
type WorkflowStartOptions<T extends Workflow> = WorkflowOptions & {
  /** Arguments to pass to workflow */
  args: Parameters<T>;
  /** Workflow identifier (must be unique per namespace) */
  workflowId: string;
};

interface WorkflowOptions {
  /** Task queue name for workflow execution */
  taskQueue: string;
  /** Workflow execution timeout */
  workflowExecutionTimeout?: string | number;
  /** Workflow run timeout */
  workflowRunTimeout?: string | number;
  /** Workflow task timeout */
  workflowTaskTimeout?: string | number;
  /** Retry policy for workflow */
  retry?: RetryPolicy;
  /** Cron schedule expression */
  cronSchedule?: string;
  /** Memo for workflow execution */
  memo?: Record<string, unknown>;
  /** Search attributes for workflow */
  searchAttributes?: SearchAttributes;
  /** Start delay before first workflow task */
  startDelay?: string | number;
}

/**
 * Options for workflow updates
 */
interface WorkflowUpdateOptions {
  /** Update identifier (optional) */
  updateId?: string;
  /** Stage to wait for before returning */
  waitForStage?: WorkflowUpdateStage;
  /** First execution run ID for validation */
  firstExecutionRunId?: string;
}

/**
 * Options for signal with start operations
 */
type WorkflowSignalWithStartOptions<SignalArgs extends any[]> = WorkflowStartOptions<any> & {
  /** Signal definition or name */
  signal: SignalDefinition<SignalArgs> | string;
  /** Signal arguments */
  signalArgs: SignalArgs;
};

/**
 * Options for getting workflow results
 */
interface WorkflowResultOptions {
  /** Workflow identifier */
  workflowId: string;
  /** Run identifier (optional) */
  runId?: string;
  /** Follow runs if workflow continues as new */
  followRuns?: boolean;
}

/**
 * Options for getting workflow handles
 */
interface GetWorkflowHandleOptions {
  /** First execution run ID for validation */
  firstExecutionRunId?: string;
}

/**
 * Compiled workflow options with protobuf types
 */
interface CompiledWorkflowOptions {
  workflowExecutionTimeout?: Duration;
  workflowRunTimeout?: Duration;
  workflowTaskTimeout?: Duration;
  retryPolicy?: RetryPolicy;
  workflowIdReusePolicy?: WorkflowIdReusePolicy;
}

/**
 * Options for listing workflows
 */
interface ListOptions {
  /** Search query expression */
  query?: string;
  /** Maximum number of executions to return */
  pageSize?: number;
  /** Namespace to search in */
  namespace?: string;
}

/**
 * Options for converting list to histories
 */
interface IntoHistoriesOptions {
  /** Maximum number of events per history */
  maxHistorySize?: number;
  /** Filter histories by status */
  statusFilter?: WorkflowExecutionStatus[];
}

/**
 * Iterable of workflow executions
 */
interface AsyncWorkflowListIterable extends AsyncIterable<WorkflowExecutionInfo> {
  /** Convert to histories */
  intoHistories(options?: IntoHistoriesOptions): AsyncIterable<HistoryAndWorkflowId>;
}

/**
 * Count workflow executions request
 */
interface CountWorkflowExecutions {
  /** Search query expression */
  query?: string;
}