Class Client

Calls Dex FlowService through registered, typed Flow definitions.

Methods perform asynchronous gRPC I/O. A Client owns its service connection but not its Registry or BlobCache; call close during application shutdown.

Example

const client = new Client(registry, cache);
try {
  const runId = await client.startFlow(orders, "order-42", input);
  const result = await client.waitForFlow("order-42");
  const output = result.singleOutput(orderResultCodec);
} finally { await client.close(); }

Constructors

constructor

new Client(
    registry: Registry,
    blobCache: BlobCache,
    options?: ClientOptions,
): Client
Constructs a Client and lazy plaintext gRPC connection.
Parameters
- registry: Registry
  Flow definitions used for validation and routing.
- blobCache: BlobCache
  Open cache used to hydrate large response values.
- options: ClientOptions = {}
  Service address and optional bearer credential.
Returns Client

Properties

`Readonly`blobCache

blobCache: BlobCache

Open cache used to hydrate large response values.

`Readonly`options

options: ClientOptions = {}

Service address and optional bearer credential.

`Readonly`registry

registry: Registry

Flow definitions used for validation and routing.

Methods

close

close(): Promise<void>
Closes the owned FlowService connection. Registry and BlobCache ownership remains with the caller.

Returns Promise<void>

describeFlow

describeFlow(flowId: string): Promise<FlowInfo>
Returns summary metadata for the current or latest Flow run.
Parameters
- flowId: string
  Non-empty existing Flow ID.
Returns Promise<FlowInfo>
Flow ID, run ID, type, status, and UTC start time.

invokeRPC

invokeRPC<Input, Output>(
    rpcMethod: (
        context: Context,
        input: Input,
    ) => RPCResult<Output> | Promise<RPCResult<Output>>,
    flowId: string,
    input: Input,
    runId?: string,
): Promise<Output>
Invokes an RPC with typed input and output. A non-transactional RPC without Attribute locks starts from a backend query. A retained terminal execution can serve it when the handler returns no durable effects. Locks, transactional execution, returned effects, or server policy can require an active execution.
Type Parameters
- Input
  RPC input type.
- Output
  RPC output type.
Parameters
- rpcMethod: (
  context: Context,
  input: Input,
  ) => RPCResult<Output> | Promise<RPCResult<Output>>
  Bound method decorated with rpc on the registered Flow.
- flowId: string
  Non-empty target Flow ID.
- input: Input
  Typed handler input.
- OptionalrunId: string
  Optional exact run; the server resolves the current execution when omitted.
Returns Promise<Output>
The decoded RPCResult output.
invokeRPC<Output>(
    rpcMethod: (
        context: Context,
    ) => RPCResult<Output> | Promise<RPCResult<Output>>,
    flowId: string,
    runId?: string,
): Promise<Output>
Invokes an input-free RPC with typed output. A retained terminal execution can serve a query-only RPC. Other execution paths can require an active execution.
Type Parameters
- Output
  RPC output type.
Parameters
- rpcMethod: (context: Context) => RPCResult<Output> | Promise<RPCResult<Output>>
  Bound method decorated with rpc on the registered Flow.
- flowId: string
  Non-empty target Flow ID.
- OptionalrunId: string
  Optional exact run; the server resolves the current execution when omitted.
Returns Promise<Output>
The decoded RPCResult output.
invokeRPC<Input>(
    rpcMethod: (context: Context, input: Input) => void | Promise<void>,
    flowId: string,
    input: Input,
    runId?: string,
): Promise<void>
Invokes a typed-input RPC that returns no output. A retained terminal execution can serve a query-only RPC. Other execution paths can require an active execution.
Type Parameters
- Input
  RPC input type.
Parameters
- rpcMethod: (context: Context, input: Input) => void | Promise<void>
  Bound method decorated with rpc on the registered Flow.
- flowId: string
  Non-empty target Flow ID.
- input: Input
  Typed handler input.
- OptionalrunId: string
  Optional exact run; the server resolves the current execution when omitted.
Returns Promise<void>
A promise resolved after successful handler completion.
invokeRPC(
    rpcMethod: (context: Context) => void | Promise<void>,
    flowId: string,
    runId?: string,
): Promise<void>
Invokes an input-free, output-free RPC. A retained terminal execution can serve a query-only RPC. Other execution paths can require an active execution.
Parameters
- rpcMethod: (context: Context) => void | Promise<void>
  Bound method decorated with rpc on the registered Flow.
- flowId: string
  Non-empty target Flow ID.
- OptionalrunId: string
  Optional exact run; the server resolves the current execution when omitted.
Returns Promise<void>
A promise resolved after successful handler completion.

invokeRPCWithOptions

invokeRPCWithOptions<Input, Output>(
    rpcMethod: (
        context: Context,
        input: Input,
    ) => RPCResult<Output> | Promise<RPCResult<Output>>,
    flowId: string,
    input: Input,
    options: RPCInvokeOptions,
    runId?: string,
): Promise<Output>
Invokes an input-bearing RPC with additive runtime map-instance selections.
Type Parameters
- Input
  RPC input type.
- Output
  RPC output type.
Parameters
- rpcMethod: (
  context: Context,
  input: Input,
  ) => RPCResult<Output> | Promise<RPCResult<Output>>
  Bound method decorated with rpc on the registered Flow.
- flowId: string
  Non-empty target Flow ID.
- input: Input
  Typed handler input.
- options: RPCInvokeOptions
  Runtime AttributeMap locks and exact map-instance loads.
- OptionalrunId: string
  Optional exact run; the server resolves the current execution when omitted.
Returns Promise<Output>
The decoded RPCResult output.
invokeRPCWithOptions<Output>(
    rpcMethod: (
        context: Context,
    ) => RPCResult<Output> | Promise<RPCResult<Output>>,
    flowId: string,
    options: RPCInvokeOptions,
    runId?: string,
): Promise<Output>
Invokes an input-free RPC with additive runtime map-instance selections.
Type Parameters
- Output
  RPC output type.
Parameters
- rpcMethod: (context: Context) => RPCResult<Output> | Promise<RPCResult<Output>>
  Bound method decorated with rpc on the registered Flow.
- flowId: string
  Non-empty target Flow ID.
- options: RPCInvokeOptions
  Runtime AttributeMap locks and exact map-instance loads.
- OptionalrunId: string
  Optional exact run; the server resolves the current execution when omitted.
Returns Promise<Output>
The decoded RPCResult output.
invokeRPCWithOptions<Input>(
    rpcMethod: (context: Context, input: Input) => void | Promise<void>,
    flowId: string,
    input: Input,
    options: RPCInvokeOptions,
    runId?: string,
): Promise<void>
Invokes an input-bearing, output-free RPC with runtime map-instance selections.
Type Parameters
- Input
  RPC input type.
Parameters
- rpcMethod: (context: Context, input: Input) => void | Promise<void>
  Bound method decorated with rpc on the registered Flow.
- flowId: string
  Non-empty target Flow ID.
- input: Input
  Typed handler input.
- options: RPCInvokeOptions
  Runtime AttributeMap locks and exact map-instance loads.
- OptionalrunId: string
  Optional exact run; the server resolves the current execution when omitted.
Returns Promise<void>
A promise resolved after successful handler completion.
invokeRPCWithOptions(
    rpcMethod: (context: Context) => void | Promise<void>,
    flowId: string,
    options: RPCInvokeOptions,
    runId?: string,
): Promise<void>
Invokes an input-free, output-free RPC with runtime map-instance selections.
Parameters
- rpcMethod: (context: Context) => void | Promise<void>
  Bound method decorated with rpc on the registered Flow.
- flowId: string
  Non-empty target Flow ID.
- options: RPCInvokeOptions
  Runtime AttributeMap locks and exact map-instance loads.
- OptionalrunId: string
  Optional exact run; the server resolves the current execution when omitted.
Returns Promise<void>
A promise resolved after successful handler completion.

listStreamMessages

listStreamMessages<T>(
    flowId: string,
    stream: Stream<T>,
    pageSize: number,
    beforePageToken?: string,
): Promise<StreamMessagesPage<T>>
Returns one newest-first page of retained Stream messages without waiting for writes.

An empty token starts at the retained tail. Pass nextPageToken unchanged to read the next, older page. Stream trimming may remove messages between pages.
Type Parameters
- T
  Stream message type.
Parameters
- flowId: string
  Logical Flow instance ID used as the Stream instance key.
- stream: Stream<T>
  Stream registered in exactly one Flow schema.
- pageSize: number
  Positive maximum count within the server-configured limit.
- beforePageToken: string = ""
  Opaque token from the preceding page, or empty for the first page.
Returns Promise<StreamMessagesPage<T>>
Decoded messages in newest-first order and the next-page token.

readStream

readStream<T>(
    flowId: string,
    stream: Stream<T>,
    resumeToken?: string,
    timeoutMs?: number,
): Promise<StreamMessage<T>>
Returns the next retained Stream message after an opaque resume token.
Type Parameters
- T
  Stream message type.
Parameters
- flowId: string
  Logical Flow instance ID used as the Stream instance key.
- stream: Stream<T>
  Stream registered in exactly one Flow schema.
- resumeToken: string = ""
  Previous message token, or empty to start at the retained head.
- OptionaltimeoutMs: number
  Optional server-side long-poll duration in milliseconds.
Returns Promise<StreamMessage<T>>
Decoded value and resumable metadata for one retained message.

searchFlows

searchFlows(
    query: string,
    pageSize: number,
    nextPageToken?: string,
    options?: SearchFlowsOptions,
): Promise<SearchFlowsPage>
Returns one page of Flow runs matching a visibility query.
Parameters
- query: string
  Dex visibility query; empty uses server defaults.
- pageSize: number
  Non-negative requested maximum result count.
- nextPageToken: string = ""
  Opaque token from the preceding page, or empty first.
- options: SearchFlowsOptions = {}
  Whether to include earlier Continue-as-New runs; defaults to exclusion.
Returns Promise<SearchFlowsPage>
Server-ordered entries and the next-page token.

skipTimer

skipTimer(
    flowId: string,
    stepExecutionId: StepExecutionId,
    timerId: TimerId,
): Promise<void>
Makes one waiting Timer condition immediately ready.
Parameters
- flowId: string
  Non-empty active Flow ID.
- stepExecutionId: StepExecutionId
  Step type and positive execution number.
- timerId: TimerId
  Exactly one Timer condition ID or zero-based index.
Returns Promise<void>

startFlow

startFlow<StartInput>(
    flow: Flow<StartInput>,
    flowId: string,
    input: StartInput,
    options?: StartFlowOptions,
): Promise<string>
Starts a Flow and returns after Dex accepts it.
Type Parameters
- StartInput
  Starting Step input type.
Parameters
- flow: Flow<StartInput>
  Exact Flow instance registered with this Client.
- flowId: string
  Non-empty application ID stable across runs.
- input: StartInput
  Starting Step input, or undefined when no start Step exists.
- options: StartFlowOptions = {}
  Timeout, reuse, retry, configuration, and initial state.
Returns Promise<string>
The server-assigned run ID.

Throws
FlowAlreadyStartedError when reuse policy rejects the Flow ID.

Throws
FlowDefinitionError when flow is not registered.

Throws
TypeError when a hard-delete initial Attribute is not the definition registered with flow.

Throws
ValueMappingError when a hard-delete initial value encodes to a number or Boolean.

Throws
Error when the Server cannot accept hard-delete writes because its protocol version is below 3.

stopFlow

stopFlow(flowId: string, options?: StopFlowOptions): Promise<void>
Requests cancellation, termination, or failure of an active Flow. The promise resolves after acceptance and does not await terminal status.
Parameters
- flowId: string
  Non-empty active Flow ID.
- options: StopFlowOptions = {}
  Stop mode and optional recorded reason.
Returns Promise<void>

timeTravel

timeTravel(flowId: string, options: TimeTravelOptions): Promise<string>
Creates a new run from a selected point in existing Flow history.
Parameters
- flowId: string
  Non-empty Flow ID whose history supplies the new run.
- options: TimeTravelOptions
  Time travel selector, reason, and replay controls.
Returns Promise<string>
The new server-assigned run ID; the Flow ID remains unchanged.

triggerContinueAsNew

triggerContinueAsNew(flowId: string): Promise<void>
Requests that an active Flow roll its history into a new run. The Flow ID stays the same; the request returns after Dex accepts it.
Parameters
- flowId: string
  Non-empty active Flow ID.
Returns Promise<void>

updateFlowConfig

updateFlowConfig(flowId: string, config: FlowConfig): Promise<void>
Updates mutable configuration for an active Flow. The update affects later decisions and does not recall dispatched work. Updates preserve the existing Worker target, including when config is empty.
Parameters
- flowId: string
  Non-empty active Flow ID.
- config: FlowConfig
  New optional Flow configuration fields.
Returns Promise<void>

waitForAttributeMatch

waitForAttributeMatch<T>(
    flowId: string,
    attribute: Attribute<T>,
    match: AttributeMatch<T>,
    options: WaitForAttributeOptions,
): Promise<T>
Waits until a singleton Attribute in the current run satisfies a match. Returns the current value observed by the successful wait operation. The server derives a stable Request ID from the condition when none is supplied. Request timeout covers transport reattachments. Internal handler timeout rolls generations.
Type Parameters
- T
  Attribute value type.
Parameters
- flowId: string
  Non-empty active Flow ID.
- attribute: Attribute<T>
  Registered singleton Attribute to observe.
- match: AttributeMatch<T>
  Scalar predicate whose operand has the Attribute value type.
- options: WaitForAttributeOptions
  Optional Request ID override and request and internal handler timeout controls.
Returns Promise<T>
The matched current Attribute value.

Throws
TypeError when attribute uses Attribute.hardDeleteOnNull; no request is sent.
waitForAttributeMatch<T>(
    flowId: string,
    attribute: AttributeMap<T>,
    instance: string,
    match: AttributeMatch<T>,
    options: WaitForAttributeOptions,
): Promise<T>
Waits until one AttributeMap instance in the current run satisfies a match. Primitive-value restrictions, options, and timeout errors match waitForAttributeMatch.
Type Parameters
- T
  AttributeMap value type.
Parameters
- flowId: string
  Non-empty active Flow ID.
- attribute: AttributeMap<T>
  Registered AttributeMap to observe.
- instance: string
  The map instance to observe. Slash is prohibited because it is a reserved character.
- match: AttributeMatch<T>
  Scalar predicate whose operand has the AttributeMap value type.
- options: WaitForAttributeOptions
  Optional Request ID override and request and internal handler timeout controls.
Returns Promise<T>
The matched current AttributeMap value.

Throws
TypeError when attribute uses AttributeMap.hardDeleteOnNull; no request is sent.

waitForFlow

waitForFlow(flowId: string, timeoutMs?: number): Promise<FlowResult>
Long-polls until a Flow closes and returns every output-bearing completion.
Parameters
- flowId: string
  Non-empty existing Flow ID.
- OptionaltimeoutMs: number
  Optional server-side long-poll duration in milliseconds.
Returns Promise<FlowResult>
Immutable Step completions in server collection order.

Throws
LongPollTimeoutError when the Flow remains open at timeout.

Throws
ValueMappingError when Dex returns malformed blob-backed output.

waitForStepCompletion

waitForStepCompletion(
    flowId: string,
    stepExecutionId: StepExecutionId,
    options: WaitForStepCompletionOptions,
): Promise<void>
Waits until one Step execution completes or its request budget expires. The server derives a stable Request ID from the Step execution when none is supplied.
Parameters
- flowId: string
  Non-empty active Flow ID.
- stepExecutionId: StepExecutionId
  Step type and positive execution number.
- options: WaitForStepCompletionOptions
  Optional Request ID, request timeout, and internal handler timeout.
Returns Promise<void>
Throws
RequestTimeoutError when a positive request timeout expires first.

writeStream

writeStream<T>(
    flowId: string,
    stream: Stream<T>,
    source: string,
    value: T,
): Promise<void>
Appends one typed best-effort Stream message with source metadata.
Type Parameters
- T
  Stream message type.
Parameters
- flowId: string
  Logical Flow instance ID; the Flow need not exist or be active.
- stream: Stream<T>
  Stream registered in exactly one Flow schema.
- source: string
  Non-empty source metadata. Repeated values and # are allowed.
- value: T
  Typed message to append.
Returns Promise<void>

Class Client

Example

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters

Returns Client

Properties

ReadonlyblobCache

Readonlyoptions

Readonlyregistry

Methods

close

Returns Promise<void>

describeFlow

Parameters

Returns Promise<FlowInfo>

invokeRPC

Type Parameters

Parameters

Returns Promise<Output>

Type Parameters

Parameters

Returns Promise<Output>

Type Parameters

Parameters

Returns Promise<void>

Parameters

Returns Promise<void>

invokeRPCWithOptions

Type Parameters

Parameters

Returns Promise<Output>

Type Parameters

Parameters

Returns Promise<Output>

Type Parameters

Parameters

Returns Promise<void>

Parameters

Returns Promise<void>

listStreamMessages

Type Parameters

Parameters

Returns Promise<StreamMessagesPage<T>>

readStream

Type Parameters

Parameters

Returns Promise<StreamMessage<T>>

searchFlows

Parameters

Returns Promise<SearchFlowsPage>

skipTimer

Parameters

Returns Promise<void>

startFlow

Type Parameters

Parameters

Returns Promise<string>

Throws

Throws

Throws

Throws

Throws

stopFlow

Parameters

Returns Promise<void>

timeTravel

Parameters

Returns Promise<string>

triggerContinueAsNew

Parameters

Returns Promise<void>

updateFlowConfig

Parameters

Returns Promise<void>

waitForAttributeMatch

`Readonly`blobCache

`Readonly`options

`Readonly`registry