@superdurable/dex 0.1.3 → 0.1.5

package/README.md

@@ -26,7 +26,7 @@ class ApproveOrder implements Step<string> {
   }
 
   waitFor(_context: Context, _orderId: string): Wait {
-    return Wait.allOf(Timer.byDuration(1_000));
+    return Wait.until(Timer.byDuration(1_000));
   }
 
   execute(_context: Context, orderId: string): StepDecision {
@@ -59,9 +59,42 @@ heterogeneous Steps with `.otherSteps(...)`. Use
 Non-starting Steps may use unrelated input types. `Flow` defaults to `void` for
 Flows without a start input.
 
+`Worker.start()` synchronizes every registered Indexed Attribute with Dex
+Server before binding its listener. Existing indexes return immediately;
+failure or the default 120-second deadline aborts startup. An indexed
+`AttributeMap` must provide one fixed `indexKey`.
+
 `StepOptions.waitForMethodTimeoutMs` and `executeMethodTimeoutMs` bound the two
 handler calls. Timer and channel conditions determine how long a Step waits.
 
+Opt an Attribute or AttributeMap into Attribute Store synchronization, then
+select the Server-configured Store for the Flow:
+
+```typescript
+const email = new Attribute("customer-email", stringCodec)
+  .syncToAttributeStore();
+const config: FlowConfig = { attributeStoreName: "profiles" };
+```
+
+The Store is an asynchronous latest-state projection. Deletion writes SQL
+`NULL`, and projection failures do not roll back Flow Attributes. Omitting
+`attributeStoreName` preserves the current target; `attributeStoreName: ""`
+disables future synchronization while retaining protocol presence.
+
+### Waiting and map inspection
+
+`Wait.allOf` and `Wait.anyOf` may contain unnamed Conditions and send empty
+Condition IDs. Every Condition in `Wait.anyCombinationOf` needs a non-empty
+user ID; the same Condition object may be reused across combinations.
+
+`Client.waitForAttributeEqual` and `waitForAttributeMapEqual` target the current
+run and accept only string, boolean, integer, or double wire values. JSON,
+bytes, and null reject before transport. `AttributeMap.getMapSize` and
+`getAllInstanceKeys` include buffered sets and deletes. The matching
+`ChannelMap` methods are RPC-only, include buffered publishes, and omit empty
+instances. Keys are decoded and sorted. Use
+`forceCompleteIfChannelsEmpty(...)` for conditional completion.
+
 ### Async handlers
 
 `Step.execute`, `Step.waitFor`, and RPC methods may be `async` and return a
@@ -93,6 +126,33 @@ Every TypeScript Flow and Step must return an explicit durable name from
 `getFlowType()` or `getStepType()`. Class names are never used as fallbacks
 because bundlers and minifiers may rename them.
 
+## Errors
+
+Client calls reject with concrete `DexServiceError` subclasses. Existing-Flow
+reads (`getAttribute`, `describeFlow`, `waitForFlow`, and `resetFlow`) use
+`FlowNotFoundError`; operations that require a running Flow use
+`FlowNotActiveError`. Start conflicts, worker failures, RPC lock contention,
+and long-poll timeouts use `FlowAlreadyStartedError`,
+`WorkerInvocationError`, `RpcLockConflictError`, and `LongPollTimeoutError`.
+
+```typescript
+try {
+  await client.publish(flowId, orders.approved, orderId);
+} catch (error) {
+  if (error instanceof FlowNotActiveError) {
+    // The Flow is missing or already closed.
+  } else {
+    throw error;
+  }
+}
+```
+
+Every service error retains `code`, `subStatus`, `detail`, `operation`,
+`flowId`, and the original gRPC error as `cause`. `WorkerInvocationError` also
+retains `workerCode`, `workerErrorType`, and `workerErrorDetail`. Registration,
+serialization, and invalid handler returns use `FlowDefinitionError`,
+`ValueMappingError`, and `InvalidStepResultError` instead of transport errors.
+
 ## Source layout
 
 Public contracts are grouped by domain under `src/`. The root `src/index.ts`
@@ -113,8 +173,14 @@ continue importing only from `@superdurable/dex`.
 - `gen/`: checked-in protobuf and grpc-js bindings
 
 Run `npm run build:native` once to stage the DXBC Node addon for the current
-platform, then `npm test` for runtime contracts and `npm run typecheck` for
-strict static contracts. Run `./run-integration-tests.sh` for all 58 IWF
+platform, then `npm test` for runtime contracts, `npm run typecheck` for strict
+static contracts, and `npm run docs:check` for public API documentation. The
+documentation check follows the actual exports of `src/index.ts` and requires
+JSDoc for every public class, interface, type, overload, member, object-style
+enum value, type parameter, input, and output; generated sources are excluded.
+The comments appear in TypeScript language-service and IDE hovers.
+
+Run `./run-integration-tests.sh` for all 58 IWF
 compatibility scenarios against an isolated `dexcli dev` environment. Run
 `npm run generate:proto` after changing `protos/dex.proto`; `protoc` and its
 standard protobuf includes must be installed.

package/dist/src/attribute-store-sync.d.ts

@@ -0,0 +1,5 @@
+import type { AttributeSyncConfig } from "./gen/dex.js";
+import type { FlowConfig } from "./options.js";
+export declare function markAttributeStoreSynced<Definition extends object>(definition: Definition): Definition;
+export declare function mapAttributeStoreSync(definition: object): AttributeSyncConfig | undefined;
+export declare function mapAttributeStoreName(config: FlowConfig | undefined): string | undefined;

package/dist/src/attribute-store-sync.js

@@ -0,0 +1,19 @@
+// Copyright (c) 2026 Super Durable, Inc.
+//
+// Licensed under the Super Durable Source License 1.0.
+// You may not use this file except in compliance with the License.
+// See the LICENSE file in the repository root.
+//
+// SPDX-License-Identifier: LicenseRef-Super-Durable-1.0
+const syncedDefinitions = new WeakSet();
+export function markAttributeStoreSynced(definition) {
+    syncedDefinitions.add(definition);
+    return definition;
+}
+export function mapAttributeStoreSync(definition) {
+    return syncedDefinitions.has(definition) ? { enabled: true } : undefined;
+}
+export function mapAttributeStoreName(config) {
+    return config?.attributeStoreName;
+}
+//# sourceMappingURL=attribute-store-sync.js.map

package/dist/src/attribute-store-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribute-store-sync.js","sourceRoot":"","sources":["../../src/attribute-store-sync.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,uDAAuD;AACvD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,wDAAwD;AAKxD,MAAM,iBAAiB,GAAG,IAAI,OAAO,EAAU,CAAC;AAEhD,MAAM,UAAU,wBAAwB,CACtC,UAAsB;IAEtB,iBAAiB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAClC,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,UAAkB;IAElB,OAAO,iBAAiB,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,MAA8B;IAClE,OAAO,MAAM,EAAE,kBAAkB,CAAC;AACpC,CAAC"}

package/dist/src/blob-cache.d.ts

@@ -1,14 +1,50 @@
+/** Configures the local persistent cache for large Dex values. */
 export interface BlobCacheConfig {
+    /** Writable directory used for cache payloads and metadata. */
     readonly directory: string;
+    /** Positive maximum on-disk payload size in bytes. */
     readonly maxBytes: number;
+    /** Admission-policy counter count; zero or `undefined` uses the native default. */
     readonly frequencyCounters?: number;
 }
+/** Provides concurrent, bounded storage for content-addressed Dex blobs. */
 export interface BlobCache {
+    /** Effective configuration used by this cache. */
     readonly config: BlobCacheConfig;
+    /**
+     * Reads a cached payload without contacting Dex.
+     * @param blobId - Opaque server-assigned blob identifier.
+     * @returns A copied payload, or `undefined` when absent.
+     */
     get(blobId: string): Uint8Array | undefined;
+    /**
+     * Offers a payload to the bounded cache.
+     * @param blobId - Opaque server-assigned blob identifier.
+     * @param payload - Bytes copied into native storage.
+     * @returns `true` when admitted or `false` when rejected by policy.
+     */
     put(blobId: string, payload: Uint8Array): boolean;
+    /**
+     * Deletes one cached payload when present.
+     * @param blobId - Opaque identifier to remove.
+     */
     delete(blobId: string): void;
+    /** Deletes every payload while keeping the cache open. */
     deleteAll(): void;
+    /** Flushes metadata and releases native resources; repeated calls are safe. */
     close(): void;
 }
+/**
+ * Opens or creates a native BlobCache owned by the caller.
+ *
+ * @example
+ * ```ts
+ * const cache = openBlobCache({ directory: ".dex-cache", maxBytes: 64 * 1024 ** 2 });
+ * try { cache.put("blob-1", new Uint8Array([1, 2])); } finally { cache.close(); }
+ * ```
+ * @param config - Directory, positive byte capacity, and optional counter count.
+ * @returns An open cache that must be closed at application shutdown.
+ * @throws {@link TypeError} when the directory is empty.
+ * @throws {@link RangeError} when a numeric setting is invalid.
+ */
 export declare function openBlobCache(config: BlobCacheConfig): BlobCache;

package/dist/src/blob-cache.js

@@ -10,6 +10,19 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 const require = createRequire(import.meta.url);
 let nativeModule;
+/**
+ * Opens or creates a native BlobCache owned by the caller.
+ *
+ * @example
+ * ```ts
+ * const cache = openBlobCache({ directory: ".dex-cache", maxBytes: 64 * 1024 ** 2 });
+ * try { cache.put("blob-1", new Uint8Array([1, 2])); } finally { cache.close(); }
+ * ```
+ * @param config - Directory, positive byte capacity, and optional counter count.
+ * @returns An open cache that must be closed at application shutdown.
+ * @throws {@link TypeError} when the directory is empty.
+ * @throws {@link RangeError} when a numeric setting is invalid.
+ */
 export function openBlobCache(config) {
     if (config.directory.length === 0) {
         throw new TypeError("blob cache directory is required");

package/dist/src/blob-cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"blob-cache.js","sourceRoot":"","sources":["../../src/blob-cache.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"blob-cache.js","sourceRoot":"","sources":["../../src/blob-cache.ts"],"names":[],"mappings":"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"}

package/dist/src/client.d.ts

@@ -6,33 +6,234 @@ import { type ClientOptions, type FlowConfig, type FlowInfo, type ResetFlowOptio
 import { AttributeMap, type Attribute } from "./persistence.js";
 import type { RPCResult } from "./rpc.js";
 import { ChannelMap, type Channel } from "./wait.js";
+/**
+ * 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
+ * ```ts
+ * const client = new Client(registry, cache);
+ * try {
+ *   const runId = await client.startFlow(orders, "order-42", input);
+ *   const result = await client.waitForFlow("order-42", orderResultCodec);
+ * } finally { await client.close(); }
+ * ```
+ */
 export declare class Client {
     readonly registry: Registry;
     readonly blobCache: BlobCache;
     readonly options: ClientOptions;
     private readonly service;
     private readonly hydrator;
+    /**
+     * Constructs a Client and lazy plaintext gRPC connection.
+     * @param registry - Flow definitions used for validation and routing.
+     * @param blobCache - Open cache used to hydrate large response values.
+     * @param options - Service address and default Worker target.
+     */
     constructor(registry: Registry, blobCache: BlobCache, options?: ClientOptions);
+    /**
+     * Starts a Flow and returns after Dex accepts it.
+     * @typeParam StartInput - Starting Step input type.
+     * @param flow - Exact Flow instance registered with this Client.
+     * @param flowId - Non-empty application ID stable across runs.
+     * @param input - Starting Step input, or `undefined` when no start Step exists.
+     * @param options - Timeout, reuse, retry, configuration, and initial state.
+     * @returns The server-assigned run ID.
+     * @throws {@link FlowAlreadyStartedError} when reuse policy rejects the Flow ID.
+     * @throws {@link FlowDefinitionError} when `flow` is not registered.
+     */
     startFlow<StartInput>(flow: Flow<StartInput>, flowId: string, input: StartInput, options?: StartFlowOptions): Promise<string>;
-    invokeRPC<Input, Output>(rpcMethod: (context: Context, input: Input) => RPCResult<Output>, flowId: string, input: Input, runId?: string): Promise<Output>;
-    invokeRPC<Output>(rpcMethod: (context: Context) => RPCResult<Output>, flowId: string, runId?: string): Promise<Output>;
-    invokeRPC<Input>(rpcMethod: (context: Context, input: Input) => void, flowId: string, input: Input, runId?: string): Promise<void>;
-    invokeRPC(rpcMethod: (context: Context) => void, flowId: string, runId?: string): Promise<void>;
+    /**
+     * Invokes an RPC with typed input and output.
+     * @typeParam Input - RPC input type.
+     * @typeParam Output - RPC output type.
+     * @param rpcMethod - Bound method decorated with `rpc` on the registered Flow.
+     * @param flowId - Non-empty target Flow ID.
+     * @param input - Typed handler input.
+     * @param runId - Optional exact run; targets the active run when omitted.
+     * @returns The decoded RPCResult output.
+     */
+    invokeRPC<Input, Output>(rpcMethod: (context: Context, input: Input) => RPCResult<Output> | Promise<RPCResult<Output>>, flowId: string, input: Input, runId?: string): Promise<Output>;
+    /**
+     * Invokes an input-free RPC with typed output.
+     * @typeParam Output - RPC output type.
+     * @param rpcMethod - Bound method decorated with `rpc` on the registered Flow.
+     * @param flowId - Non-empty target Flow ID.
+     * @param runId - Optional exact run; targets the active run when omitted.
+     * @returns The decoded RPCResult output.
+     */
+    invokeRPC<Output>(rpcMethod: (context: Context) => RPCResult<Output> | Promise<RPCResult<Output>>, flowId: string, runId?: string): Promise<Output>;
+    /**
+     * Invokes a typed-input RPC that returns no output.
+     * @typeParam Input - RPC input type.
+     * @param rpcMethod - Bound method decorated with `rpc` on the registered Flow.
+     * @param flowId - Non-empty target Flow ID.
+     * @param input - Typed handler input.
+     * @param runId - Optional exact run; targets the active run when omitted.
+     * @returns A promise resolved after successful handler completion.
+     */
+    invokeRPC<Input>(rpcMethod: (context: Context, input: Input) => void | Promise<void>, flowId: string, input: Input, runId?: string): Promise<void>;
+    /**
+     * Invokes an input-free, output-free RPC.
+     * @param rpcMethod - Bound method decorated with `rpc` on the registered Flow.
+     * @param flowId - Non-empty target Flow ID.
+     * @param runId - Optional exact run; targets the active run when omitted.
+     * @returns A promise resolved after successful handler completion.
+     */
+    invokeRPC(rpcMethod: (context: Context) => void | Promise<void>, flowId: string, runId?: string): Promise<void>;
+    /**
+     * Reads a singleton Attribute.
+     * @typeParam T - Attribute value type.
+     * @param flowId - Non-empty existing Flow ID.
+     * @param attribute - Typed singleton Attribute definition.
+     * @param runId - Optional exact run; targets the current run when omitted.
+     * @returns The decoded value, or `undefined` when unset.
+     */
     getAttribute<T>(flowId: string, attribute: Attribute<T>, runId?: string): Promise<T | undefined>;
+    /**
+     * Reads one AttributeMap instance.
+     * @typeParam T - Attribute value type.
+     * @param flowId - Non-empty existing Flow ID.
+     * @param attribute - Typed AttributeMap definition.
+     * @param instance - Non-empty logical map key.
+     * @param runId - Optional exact run; targets the current run when omitted.
+     * @returns The decoded value, or `undefined` when unset.
+     */
     getAttribute<T>(flowId: string, attribute: AttributeMap<T>, instance: string, runId?: string): Promise<T | undefined>;
+    /**
+     * Writes a singleton Attribute on an active Flow.
+     * @typeParam T - Attribute value type.
+     * @param flowId - Non-empty active Flow ID.
+     * @param attribute - Typed singleton Attribute definition.
+     * @param value - Value encoded by the Attribute codec.
+     * @param runId - Optional exact run; targets the active run when omitted.
+     * @returns A promise resolved after Dex applies the write.
+     */
     setAttribute<T>(flowId: string, attribute: Attribute<T>, value: T, runId?: string): Promise<void>;
+    /**
+     * Writes one AttributeMap instance on an active Flow.
+     * @typeParam T - Attribute value type.
+     * @param flowId - Non-empty active Flow ID.
+     * @param attribute - Typed AttributeMap definition.
+     * @param instance - Non-empty logical map key.
+     * @param value - Value encoded by the Attribute codec.
+     * @param runId - Optional exact run; targets the active run when omitted.
+     * @returns A promise resolved after Dex applies the write.
+     */
     setAttribute<T>(flowId: string, attribute: AttributeMap<T>, instance: string, value: T, runId?: string): Promise<void>;
+    /**
+     * Publishes one or more values to a singleton Channel.
+     * @typeParam T - Channel element type.
+     * @param flowId - Non-empty active Flow ID.
+     * @param channel - Typed singleton Channel definition.
+     * @param values - Values appended in argument order.
+     * @returns A promise resolved after Dex accepts the batch.
+     */
     publish<T>(flowId: string, channel: Channel<T>, ...values: readonly T[]): Promise<void>;
+    /**
+     * Publishes one or more values to a ChannelMap instance.
+     * @typeParam T - Channel element type.
+     * @param flowId - Non-empty active Flow ID.
+     * @param channel - Typed ChannelMap definition.
+     * @param instance - Non-empty logical map key.
+     * @param values - Values appended in argument order.
+     * @returns A promise resolved after Dex accepts the batch.
+     */
     publish<T>(flowId: string, channel: ChannelMap<T>, instance: string, ...values: readonly T[]): Promise<void>;
+    /**
+     * Waits for successful Flow completion without decoding output.
+     * @param flowId - Non-empty existing Flow ID.
+     * @returns A promise resolved on successful completion.
+     */
     waitForFlow(flowId: string): Promise<void>;
+    /**
+     * Waits for successful Flow completion and decodes the latest Step output.
+     * @typeParam Output - Expected completion output type.
+     * @param flowId - Non-empty existing Flow ID.
+     * @param outputCodec - Codec for the expected output.
+     * @param timeoutMs - Optional server-side long-poll duration in milliseconds.
+     * @returns The decoded latest completed Step output.
+     */
     waitForFlow<Output>(flowId: string, outputCodec: Codec<Output>, timeoutMs?: number): Promise<Output>;
+    /**
+     * Requests cancellation, termination, or failure of an active Flow.
+     * The promise resolves after acceptance and does not await terminal status.
+     * @param flowId - Non-empty active Flow ID.
+     * @param options - Stop mode and optional recorded reason.
+     */
     stopFlow(flowId: string, options?: StopFlowOptions): Promise<void>;
+    /**
+     * Returns summary metadata for the current or latest Flow run.
+     * @param flowId - Non-empty existing Flow ID.
+     * @returns Flow ID, run ID, type, status, and UTC start time.
+     */
     describeFlow(flowId: string): Promise<FlowInfo>;
+    /**
+     * Returns one page of Flow runs matching a visibility query.
+     * @param query - Dex visibility query; empty uses server defaults.
+     * @param pageSize - Non-negative requested maximum result count.
+     * @param nextPageToken - Opaque token from the preceding page, or empty first.
+     * @returns Server-ordered entries and the next-page token.
+     */
     searchFlows(query: string, pageSize: number, nextPageToken?: string): Promise<SearchFlowsPage>;
     private mapSearchEntry;
+    /**
+     * Creates a new run from a selected point in existing Flow history.
+     * @param flowId - Non-empty Flow ID whose history is reset.
+     * @param options - Reset selector, reason, and replay controls.
+     * @returns The new server-assigned run ID; the Flow ID remains unchanged.
+     */
     resetFlow(flowId: string, options: ResetFlowOptions): Promise<string>;
+    /**
+     * Makes one waiting Timer condition immediately ready.
+     * @param flowId - Non-empty active Flow ID.
+     * @param stepExecutionId - Step type and positive execution number.
+     * @param timerId - Exactly one Timer condition ID or zero-based index.
+     */
     skipTimer(flowId: string, stepExecutionId: StepExecutionId, timerId: TimerId): Promise<void>;
+    /**
+     * Long-polls until one Step execution completes.
+     * @param flowId - Non-empty active Flow ID.
+     * @param stepExecutionId - Step type and positive execution number.
+     * @param timeoutMs - Non-negative server-side wait duration in milliseconds.
+     * @throws {@link LongPollTimeoutError} when completion is not observed in time.
+     */
     waitForStepCompletion(flowId: string, stepExecutionId: StepExecutionId, timeoutMs: number): Promise<void>;
+    /**
+     * Waits until a scalar Attribute in the current run equals the expected value.
+     * Generates a request ID and rejects JSON, bytes, and null before transport.
+     * @typeParam T - Attribute value type.
+     * @param flowId - Non-empty active Flow ID.
+     * @param attribute - Registered scalar Attribute to observe.
+     * @param expected - String, boolean, integer, or number value to await.
+     * @param timeoutMs - Non-negative server-side wait duration in milliseconds.
+     */
+    waitForAttributeEqual<T>(flowId: string, attribute: Attribute<T>, expected: T, timeoutMs: number): Promise<void>;
+    /**
+     * Waits until one scalar AttributeMap instance in the current run matches.
+     * Scalar restrictions and timeout errors match `waitForAttributeEqual`.
+     * @typeParam T - AttributeMap value type.
+     * @param flowId - Non-empty active Flow ID.
+     * @param attribute - Registered AttributeMap to observe.
+     * @param instance - Non-empty logical map key to observe.
+     * @param expected - String, boolean, integer, or number value to await.
+     * @param timeoutMs - Non-negative server-side wait duration in milliseconds.
+     */
+    waitForAttributeMapEqual<T>(flowId: string, attribute: AttributeMap<T>, instance: string, expected: T, timeoutMs: number): Promise<void>;
+    private waitForAttributeValue;
+    /**
+     * Replaces mutable configuration for an active Flow.
+     * The update affects later decisions and does not recall dispatched work.
+     * @param flowId - Non-empty active Flow ID.
+     * @param config - New optional Flow configuration fields.
+     */
     updateFlowConfig(flowId: string, config: FlowConfig): Promise<void>;
+    /**
+     * Closes the owned FlowService connection.
+     * Registry and BlobCache ownership remains with the caller.
+     */
     close(): Promise<void>;
 }