Class WorkflowHandleService

Handle to a running or completed workflow execution. Returned by client.workflow.start() and client.workflow.getHandle().

Example

const handle = await client.workflow.start({
  args: ['order-123'],
  taskQueue: 'orders',
  workflowName: 'orderWorkflow',
  workflowId: Durable.guid(),
});

// Await the final result
const result = await handle.result();

// Or interact while running
await handle.signal('approval', { approved: true });
await handle.cancel();

Properties

hotMesh workflowId workflowTopic

Methods

cancel export exportExecution queryState result signal state status terminate

Properties

hotMesh

hotMesh: HotMesh

workflowId

workflowId: string

workflowTopic

workflowTopic: string

Methods

cancel

  • cancel(): Promise<void>

  • Requests cooperative cancellation of the workflow. Unlike terminate() (which terminates immediately), cancel() sets a durable flag that the workflow detects at its next durable operation (sleep, proxyActivities, executeChild, etc.). The workflow receives a CancelledFailure error that it can catch to perform cleanup before exiting.

    const handle = await client.workflow.start({ ... });
    await handle.cancel();
    // Workflow will throw CancelledFailure at its next durable operation

    Returns Promise<void>

export

  • export(options?): Promise<DurableJobExport>

  • Export the raw workflow state as a DurableJobExport with five sections:

    • data — workflow input arguments
    • state — done flag, response, error, timestamps
    • status — semaphore (0 = complete, > 0 = pending, < 0 = error)
    • timeline — ordered idempotent markers for activities, children, sleeps, signals
    • transitions — per-activity execution timestamps by dimension

    Use allow / block to limit sections and values: false to strip payloads.

    Parameters

    Returns Promise<DurableJobExport>

    Example

    const raw = await handle.export();
    console.log(raw.state);    // { done: true, response: '...' }
    console.log(raw.timeline); // [{ key: '-proxy-1-', value: {...} }, ...]

    // Lightweight export: timeline keys only, no payloads
    const slim = await handle.export({ allow: ['timeline'], values: false });

exportExecution

  • exportExecution(options?): Promise<WorkflowExecution>

  • Export the workflow as a structured event history (WorkflowExecution).

    Returns a chronologically ordered event list with Temporal-style typed events, back-references between scheduled/completed pairs, and a summary with counts.

    Event types: activity_task_scheduled/completed/failed, child_workflow_execution_started/completed/failed, timer_started/fired, workflow_execution_started/completed/failed/signaled

    Modes:

    • sparse (default) — single query, transforms timeline markers into events
    • verbose — recursively fetches child workflows as nested children

    Options: exclude_system, omit_results, enrich_inputs, allow_direct_query

    Parameters

    Returns Promise<WorkflowExecution>

    Example

    const exec = await handle.exportExecution({ exclude_system: true });
    for (const event of exec.events) {
      console.log(event.event_type, event.attributes);
    }
    console.log(exec.summary); // { activities: { total: 5, ... }, timers: 1, ... }

queryState

  • queryState(fields): Promise<Record<string, any>>

  • Returns key-value pairs previously written via Durable.workflow.search() or Durable.workflow.enrich().

    Parameters

    • fields: string[]

      The field names to retrieve.

    Returns Promise<Record<string, any>>

result

  • result<T>(config?): Promise<StreamError | T>

  • Blocks until the workflow completes and returns the result. If the workflow failed, the error is rethrown (with stack trace) unless throwOnError: false is set, in which case the error object is returned directly.

    Type Parameters

    • T

      The workflow's return type.

    Parameters

    • Optionalconfig: {
          state?: boolean;
          throwOnError?: boolean;
      }
      • Optionalstate?: boolean
      • OptionalthrowOnError?: boolean

    Returns Promise<StreamError | T>

signal

  • signal(signalId, data, expire?): Promise<void>

  • Delivers a named signal to the workflow. If the workflow is paused on Durable.workflow.condition(signalId), it resumes with the provided data.

    If the signal arrives before the workflow has registered its hook (race condition under load), it is buffered as a pending signal for up to expire (default 10 minutes). Use a longer duration when signaling "early on purpose" (e.g., depositing a payload hours before the workflow starts).

    Parameters

    • signalId: string

      Matches the signalId passed to condition().

    • data: Record<any, any>

      Payload delivered to the waiting workflow.

    • Optionalexpire: string

      Optional pending signal TTL (e.g., '1h', '30d'). Default '10m'.

    Returns Promise<void>

state

  • state(metadata?): Promise<Record<string, any>>

  • Returns the current workflow state. For a completed workflow this is the final output; for a running workflow it reflects the latest persisted state (may change as activities complete).

    Parameters

    • metadata: boolean = false

      If true, returns the full job envelope including internal metadata alongside the data.

    Returns Promise<Record<string, any>>

status

  • status(): Promise<number>

  • Returns the workflow's numeric status code: 0 = completed, positive = still running, negative = interrupted/errored.

    Returns Promise<number>

terminate

  • terminate(options?): Promise<string>

  • Immediately terminates the workflow. The job is marked as interrupted, subscribers are notified, and the job hash is expired. Unlike cancel, this does not give the workflow a chance to run cleanup code.

    Parameters

    Returns Promise<string>

Settings

Member Visibility

On This Page

Properties
Methods