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. Before its first request, every method shares lazy Server protocol negotiation. The constructor performs no I/O. This SDK requires protocol 4. After an incompatible Server answers, every later call fails with a new Error that has the same message. A transport failure during negotiation rejects with the usual DexServiceError and is retried on the next call. Wait methods with a request timeout bound negotiation by that timeout and reject with RequestTimeoutError.

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 gRPC connection, plaintext unless options.flowServiceTls is set.
Parameters
- registry: Registry
  Flow definitions used for validation and routing.
- blobCache: BlobCache
  Open cache used to hydrate large response values.
- options: ClientOptions = {}
  Service address, optional bearer credential, and optional TLS settings.
Returns Client
Throws
When flowServiceTls is set and the address or TLS settings are invalid.

Properties

`Readonly`blobCache

blobCache: BlobCache

Open cache used to hydrate large response values.

`Readonly`options

options: ClientOptions = {}

Service address, optional bearer credential, and optional TLS settings.

`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.

getAttributes

getAttributes<
    Reads extends readonly [AttributeRead<unknown>, AttributeRead<unknown>],
>(
    flowId: string,
    ...reads: Reads,
): Promise<AttributeReadValues<Reads>>
Reads committed Attribute and AttributeMap instance values from the current or latest Flow run.

Use getAttributes to read Flow state from outside the Flow without defining an RPC. Pass one read per value: a singleton Attribute, or an AttributeMap instance selected with AttributeMap.instance. The returned Promise resolves to a tuple with one element per read, in read order. Each element has the read's value type, or undefined when that Attribute or AttributeMap instance is not set. Writing null or undefined deletes an Attribute, so it then reads as undefined. A stored value that its codec decodes to null stays null. Falsy values such as "", 0n, and false are set values.

The Client sends all keys in one FlowService request, so every value comes from the same committed state. No Worker runs. The read targets the current run, or the latest run when no run is open. A closed run stays readable until Dex purges it. The call sees only committed state. It does not see writes staged by an RPC or Step that is still running, unlike an Attribute read inside an RPC handler.

Hard-delete Attributes from Attribute.hardDeleteOnNull are supported; Dex returns their current stored values. The Client hydrates large values through LoadBlobs and its BlobCache, then decodes every value with its definition's codec. The Promise resolves only after every value decodes. On any error it rejects and returns no values.

Every definition must be registered by some Flow in this Client's Registry. Registered means the exact definition object returned by that Flow's getPersistenceSchema. A different object with the same name, such as one with another codec or one created by calling hardDeleteOnNull() again, is rejected. The definition need not belong to the target Flow's type; Dex reads the key by name. A same-named Attribute with another value type in the target Flow fails to decode.

The reads parameter requires at least one read at compile time. A plain array can be empty, so spreading it alone does not compile. Pass its first read separately, as in client.getAttributes(flowId, first, ...rest). The result then has one element for first, followed by one element per read in rest.
Type Parameters
- Reads extends readonly [AttributeRead<unknown>, AttributeRead<unknown>]
  Tuple of reads. TypeScript infers it from the arguments, and the result tuple maps each read to its value type or undefined.
Parameters
- flowId: string
  Non-empty Flow ID.
- ...reads: Reads
  At least one Attribute or AttributeMap instance selection. Two reads of the same Attribute or AttributeMap instance are rejected.
Returns Promise<AttributeReadValues<Reads>>
A tuple with one decoded value or undefined per read, in read order.
Example
```
type Note = { readonly text: string };
const orderStatus = new Attribute("order-status", stringCodec);
const notes = new AttributeMap("notes", jsonCodec<Note>());
// Register orderStatus and notes in a Flow's getPersistenceSchema.

try {
  const [status, note] = await client.getAttributes(
    "order-42",
    orderStatus,
    notes.instance("n1"),
  );
  console.log(status ?? "new", note?.text ?? "no note yet");
} catch (error) {
  if (error instanceof FlowNotFoundError) {
    console.log(`order ${error.flowId} does not exist`);
  } else {
    throw error;
  }
}
```
Throws
TypeError before any request when flowId is empty, no read is passed, a read is not an Attribute or AttributeMap instance selection, or two reads select the same value.

Throws
FlowDefinitionError before any request when a definition is not registered by a Flow in the Client's Registry, or differs from the registered definition object.

Throws
FlowNotFoundError when the Flow does not exist or its latest run is being purged.

Throws
ValueMappingError when a value cannot be hydrated or decoded with its codec.

Throws
DexServiceError for other FlowService failures, including a failed LoadBlobs request. The error keeps the gRPC code and the server detail, and its operation is loadBlobs for a LoadBlobs failure.

Throws
Error when Dex returns an invalid response, or the BlobCache fails while large values are hydrated. Every error message names the Flow ID. An error about one read or value also names its Attribute name or physical key.

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 is incompatible with required protocol version 4.

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

Throws

Properties

ReadonlyblobCache

Readonlyoptions

Readonlyregistry

Methods

close

Returns Promise<void>

describeFlow

Parameters

Returns Promise<FlowInfo>

getAttributes

Type Parameters

Parameters

Returns Promise<AttributeReadValues<Reads>>

Example

Throws

Throws

Throws

Throws

Throws

Throws

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

`Readonly`blobCache

`Readonly`options

`Readonly`registry