@voltro/client 0.9.0 → 0.11.0

package/dist/index.d.ts

@@ -384,6 +384,14 @@ export declare interface ClientTraceEvent {
 
 declare type ClientTraceListener = (event: ClientTraceEvent) => void;
 
+/** A compensation that itself failed. Surfaced rather than swallowed: the app
+ *  now has an orphan it may need to reconcile, and hiding that is how orphans
+ *  become permanent. */
+export declare interface CompensationFailure {
+    readonly step: string;
+    readonly error: unknown;
+}
+
 /** Pure virtualization math: scroll position → the row window to fetch +
  *  the spacer heights. `total` (when known) caps the window + sizes the bottom
  *  spacer; without it, infinite-scroll (bottomSpacer 0). */
@@ -1115,6 +1123,31 @@ export declare class RpcErrorBus {
 
 export declare type RpcErrorListener = (event: RpcError) => void;
 
+/**
+ * Run a sequence. Resolves with a discriminated result rather than rejecting —
+ * the same "handled" semantics `useMutation`/`useAction` use, so the call site
+ * loses its try/catch without losing the failure.
+ */
+export declare const runSequence: <Ctx>(builder: SequenceBuilder<Ctx>, options?: RunSequenceOptions) => Promise<SequenceResult<Ctx>>;
+
+export declare interface RunSequenceOptions {
+    /** Called once, with the original failure. The whole point of the primitive:
+     *  one handler for the sequence instead of a try/catch per step. */
+    readonly onError?: (error: unknown, detail: {
+        readonly failedStep: string;
+        readonly compensated: ReadonlyArray<string>;
+        readonly compensationFailures: ReadonlyArray<CompensationFailure>;
+        readonly compensationCovered: ReadonlyArray<string>;
+        readonly compensationUncertain: ReadonlyArray<{
+            readonly step: string;
+            readonly coveredBy: string;
+        }>;
+    }) => void;
+    /** Skip compensation entirely. For a sequence whose steps are all idempotent
+     *  upserts, undoing is churn rather than cleanup. */
+    readonly compensate?: boolean;
+}
+
 /**
  * Derive table COLUMNS from a query's output `Schema` — an
  * `Schema.Array(Schema.Struct({...}))`. Drills into the array's element and maps
@@ -1137,6 +1170,52 @@ export declare interface SeqElement<E> {
     readonly event: E;
 }
 
+/** Start a sequence. Pure and React-free, so it is testable on its own. */
+export declare const sequence: () => SequenceBuilder<Record<never, never>>;
+
+/**
+ * A sequence under construction. Each `.step()` widens the context type, so a
+ * later step reads earlier results by name with real types — `linkThread` can
+ * see both `ctx.ticket` and `ctx.thread` without threading them by hand.
+ */
+export declare interface SequenceBuilder<Ctx> {
+    /** A CONDITIONAL step. `Result | undefined` in the context, because it may not
+     *  have run — later steps have to say what they do about that. */
+    step<Name extends string, Result>(name: Name, run: (ctx: Ctx) => Result | Promise<Result>, options: StepOptions<Ctx, Result> & {
+        readonly when: (ctx: Ctx) => boolean;
+    }): SequenceBuilder<Ctx & {
+        readonly [K in Name]: Result | undefined;
+    }>;
+    step<Name extends string, Result>(name: Name, run: (ctx: Ctx) => Result | Promise<Result>, options?: StepOptions<Ctx, Result>): SequenceBuilder<Ctx & {
+        readonly [K in Name]: Result;
+    }>;
+    /* Excluded from this release type: steps */
+}
+
+export declare type SequenceResult<Ctx> = {
+    readonly ok: true;
+    readonly data: Ctx;
+} | {
+    readonly ok: false;
+    /** The step whose `run` threw. Its `undo` was NOT called — see the header. */
+    readonly failedStep: string;
+    /** The original failure. Never replaced by a compensation error. */
+    readonly error: unknown;
+    /** Names of the steps whose `undo` ran, newest first. */
+    readonly compensated: ReadonlyArray<string>;
+    /** Undos that threw. Non-empty means something is left over upstream. */
+    readonly compensationFailures: ReadonlyArray<CompensationFailure>;
+    /** Steps whose `undo` was skipped because a later step's `covers` names
+     *  them and that undo SUCCEEDED. They are reversed; nothing to do. */
+    readonly compensationCovered: ReadonlyArray<string>;
+    /** Steps whose covering undo FAILED. Neither reversed nor known to be —
+     *  the honest third answer, and the one worth reconciling. */
+    readonly compensationUncertain: ReadonlyArray<{
+        readonly step: string;
+        readonly coveredBy: string;
+    }>;
+};
+
 /** Register (or clear) the app-wide notifier that `notify:` routes to. Call once
  *  at boot, next to your toast provider. */
 export declare const setMutationNotifier: (notifier: MutationNotifier | undefined) => void;
@@ -1191,6 +1270,58 @@ export declare const stableKey: (key: ReadonlyArray<unknown>) => string;
  */
 export declare const startMutation: (args: Pick<MutationEvent, "id" | "apiName" | "tag" | "input">) => void;
 
+declare interface Step {
+    readonly name: string;
+    readonly run: (ctx: Record<string, unknown>) => unknown | Promise<unknown>;
+    readonly undo: StepUndo<never> | undefined;
+    readonly covers: ReadonlyArray<string>;
+    readonly when: ((ctx: Record<string, unknown>) => boolean) | undefined;
+}
+
+export declare interface StepOptions<Ctx, Result> {
+    /** How to reverse this step if a LATER step fails. Omit when the step has no
+     *  externally visible effect worth reversing.
+     *
+     *  **Your undo may be called while an earlier step's undo also runs.** They
+     *  are independent by default — see `covers` when one already reverses the
+     *  other, and the module header for why the runner cannot infer it. */
+    readonly undo?: StepUndo<Result>;
+    /**
+     * Earlier steps this step's `undo` ALREADY reverses. Their undos are skipped.
+     *
+     * The case that produced this: `deleteJiraDraftTicket` deletes the issue AND
+     * discards the draft, so the earlier `discardDraft` undo ran a second time.
+     * That was harmless only because discarding is idempotent — for a refund or a
+     * cancellation email the double-run is a real defect, and the runner has no
+     * way to know which kind it is looking at.
+     *
+     *     .step('draft', createDraft, { undo: discardDraft })
+     *     .step('jira',  createTicket, { undo: deleteJiraDraftTicket, covers: ['draft'] })
+     *
+     * If the covering undo FAILS, the covered steps are neither run nor claimed:
+     * whether the cascade got that far is genuinely unknown, and guessing either
+     * way is wrong. They come back in `compensationUncertain` so the app can
+     * reconcile instead of finding out later.
+     */
+    readonly covers?: ReadonlyArray<keyof Ctx & string>;
+    /**
+     * Run this step only when the predicate holds. A skipped step contributes
+     * `undefined` to the context (the type says so) and gets no `undo`.
+     *
+     * Narrow on purpose: this is for a sequence that is linear EXCEPT for one
+     * optional step — "save, then schedule the summary only if the set changed",
+     * `if (assigneeKey) assign else unassign`. Loops and real branches still keep
+     * their `try/catch`; an optional step is a different shape from either, and
+     * without this the whole flow fell back even though the rest was a clean
+     * pipeline.
+     */
+    readonly when?: (ctx: Ctx) => boolean;
+}
+
+/** One step's compensation. Receives the step's OWN result, which is the point:
+ *  `undo: (created) => remove.run({ id: created.id })`. */
+export declare type StepUndo<Result> = (result: Result) => unknown | Promise<unknown>;
+
 /** Subscribe to client errors. Returns an unsubscribe fn. */
 export declare const subscribeClientErrors: (listener: ClientErrorListener) => (() => void);
 
@@ -1350,6 +1481,34 @@ export declare interface SubscriptionCacheOptions {
     readonly errorBus?: RpcErrorBus;
 }
 
+/**
+ * Deliberately NOT subscribed — `skip: true`.
+ *
+ * This state exists because `loading` was answering two different questions
+ * with one boolean: "waiting for the first snapshot" and "not asking at all".
+ * A skipped subscription used to report `loading: true` forever, so the blessed
+ * pattern
+ *
+ *     if (loading) return <Skeleton/>
+ *
+ * rendered a permanent skeleton for a query the app had consciously switched
+ * off — and `skip: !currentUser?.id` / `skip: !open` are among the most common
+ * things anyone writes. Call sites only survived it by carrying a redundant
+ * `if (!currentUser) return null` in front, which is the very check `loading`
+ * was supposed to replace.
+ *
+ * `loading` is `false` here: nothing is in flight. `data` is `undefined`,
+ * which is why this state is only handed to callers that actually pass a
+ * dynamic `skip` — see the overloads. Everyone else keeps the two-state union
+ * where `!loading` still proves `data` is present.
+ */
+export declare interface SubscriptionIdle extends SubscriptionMeta {
+    readonly data: undefined;
+    readonly loading: false;
+    readonly isEmpty: false;
+    readonly idle: true;
+}
+
 /** The fields that mean the same thing in every subscription state. */
 export declare interface SubscriptionMeta {
     /** Server revision counter; -1 before first snapshot. */
@@ -1407,6 +1566,9 @@ export declare interface SubscriptionOptions<T = unknown> {
 export declare interface SubscriptionPending extends SubscriptionMeta {
     readonly data: undefined;
     readonly loading: true;
+    /** Always `false` — this subscription IS asking, it just has no answer yet.
+     *  See {@link SubscriptionIdle} for the deliberately-not-asking case. */
+    readonly idle: false;
     /** Always `false` while pending. "Empty" is a statement about data that
      *  ARRIVED; before then it would be a guess, and rendering an empty state on
      *  that guess is the flash-of-empty-state bug. */
@@ -1417,6 +1579,8 @@ export declare interface SubscriptionPending extends SubscriptionMeta {
 export declare interface SubscriptionSettled<T> extends SubscriptionMeta {
     readonly data: T;
     readonly loading: false;
+    /** Always `false` — data arrived. */
+    readonly idle: false;
     /** The data that arrived is empty — an empty array, or a null value. */
     readonly isEmpty: boolean;
 }
@@ -1451,6 +1615,10 @@ export declare type SubscriptionState<T> = SubscriptionPending | SubscriptionSet
 export declare interface SubscriptionStateWithFallback<T> extends SubscriptionMeta {
     readonly data: T;
     readonly loading: boolean;
+    /** True when `skip` is on. `data` is the fallback, and no request is in
+     *  flight — distinguishes "showing the fallback because we chose not to ask"
+     *  from "…because the answer has not arrived". */
+    readonly idle: boolean;
     readonly isEmpty: boolean;
 }
 
@@ -1854,11 +2022,54 @@ export declare interface UseResourceCanState {
 
 export declare const useResumableAgentStream: <E = unknown>(apiName: string, rpcTag: string, options?: ResumableAgentStreamOptions<E>) => ResumableAgentStreamControls<E>;
 
+/**
+ * @param options Sequence-wide defaults — most usefully `onError`, which fires
+ *                once per failed sequence instead of once per step.
+ *
+ * ```tsx
+ * const seq = useSequence({ onError: (e) => notify.error(String(e)) })
+ *
+ * const attach = async (file: File) => {
+ *   const result = await seq.run(
+ *     sequence()
+ *       .step('upload', () => upload.run({ file }), {
+ *         undo: (r) => removeObject.run({ id: r.id }),   // the created id, right here
+ *       })
+ *       .step('attach', (c) => createAttachment.run({ refId: c.upload.id })),
+ *   )
+ *   if (result.ok) setAttachmentId(result.data.attach.id)
+ * }
+ * ```
+ *
+ * Compensation is best-effort and tab-bound — see `sequence.ts`. When the
+ * rollback has to survive a closed tab, move the sequence into a workflow.
+ */
+export declare const useSequence: (options?: RunSequenceOptions) => UseSequenceResult;
+
+export declare interface UseSequenceResult {
+    /** Run a built sequence. Resolves with the discriminated result; it does not
+     *  reject, which is what removes the try/catch. */
+    readonly run: <Ctx>(builder: SequenceBuilder<Ctx>, options?: RunSequenceOptions) => Promise<SequenceResult<Ctx>>;
+    /** True while a sequence is in flight. */
+    readonly pending: boolean;
+    /** The last sequence's original failure, or `undefined` after a success. */
+    readonly error: unknown | undefined;
+    /** The step that failed last time, for a targeted message ("couldn't create
+     *  the ticket") rather than a generic one. */
+    readonly failedStep: string | undefined;
+}
+
 export declare function useSubscription<T = unknown>(apiName: string, rpcTag: string, input: Readonly<Record<string, unknown>>, options: SubscriptionOptions<T> & {
     readonly fallback: T;
 }): SubscriptionStateWithFallback<T>;
 
-export declare function useSubscription<T = unknown>(apiName: string, rpcTag: string, input?: Readonly<Record<string, unknown>>, options?: SubscriptionOptions<T>): SubscriptionState<T>;
+export declare function useSubscription<T = unknown>(apiName: string, rpcTag: string, input?: Readonly<Record<string, unknown>>, options?: SubscriptionOptions<T> & {
+    readonly skip?: false;
+}): SubscriptionState<T>;
+
+export declare function useSubscription<T = unknown>(apiName: string, rpcTag: string, input: Readonly<Record<string, unknown>>, options: SubscriptionOptions<T> & {
+    readonly skip?: boolean;
+}): SubscriptionState<T> | SubscriptionIdle;
 
 /** The column shape a `<DataTable query=…>` will render — from the query's
  *  output Schema. */
@@ -2012,11 +2223,11 @@ export declare interface WorkflowClientMessages {
     }>>;
 }
 
-export declare type WorkflowDomainEventsState = SubscriptionState<ReadonlyArray<WorkflowDomainEventRow>> & {
+export declare type WorkflowDomainEventsState = (SubscriptionState<ReadonlyArray<WorkflowDomainEventRow>> | SubscriptionIdle) & {
     readonly events: ReadonlyArray<WorkflowDomainEventRow>;
 };
 
-export declare type WorkflowEventDeliveriesState = SubscriptionState<ReadonlyArray<WorkflowEventDeliveryRow>> & {
+export declare type WorkflowEventDeliveriesState = (SubscriptionState<ReadonlyArray<WorkflowEventDeliveryRow>> | SubscriptionIdle) & {
     readonly deliveries: ReadonlyArray<WorkflowEventDeliveryRow>;
 };
 
@@ -2029,7 +2240,7 @@ export declare interface WorkflowRunError {
 
 export { WorkflowRunEventRow }
 
-export declare type WorkflowRunEventsState = SubscriptionState<ReadonlyArray<WorkflowRunEventRow>> & {
+export declare type WorkflowRunEventsState = (SubscriptionState<ReadonlyArray<WorkflowRunEventRow>> | SubscriptionIdle) & {
     readonly events: ReadonlyArray<WorkflowRunEventRow>;
 };
 
@@ -2041,11 +2252,16 @@ export declare interface WorkflowRunsFilter {
     readonly limit?: number;
 }
 
-export declare type WorkflowRunsState = SubscriptionState<ReadonlyArray<WorkflowRunRow>> & {
+export declare type WorkflowRunsState = (SubscriptionState<ReadonlyArray<WorkflowRunRow>> | SubscriptionIdle) & {
     readonly runs: ReadonlyArray<WorkflowRunRow>;
 };
 
-export declare type WorkflowRunState = SubscriptionState<ReadonlyArray<WorkflowRunRow>> & {
+/** `SubscriptionIdle` is in the union because `id === undefined` skips: asking
+ *  for "the run with no id" is not a pending request, it is no request. Before
+ *  the idle state existed this reported `loading: true` forever, so a caller
+ *  following the blessed `if (loading) return <Skeleton/>` rendered a permanent
+ *  skeleton whenever nothing was selected. */
+export declare type WorkflowRunState = (SubscriptionState<ReadonlyArray<WorkflowRunRow>> | SubscriptionIdle) & {
     readonly run: WorkflowRunRow | undefined;
 };
 
@@ -2075,7 +2291,7 @@ export { WorkflowRunStatus }
 
 export { WorkflowRunStepRow }
 
-export declare type WorkflowRunStepsState = SubscriptionState<ReadonlyArray<WorkflowRunStepRow>> & {
+export declare type WorkflowRunStepsState = (SubscriptionState<ReadonlyArray<WorkflowRunStepRow>> | SubscriptionIdle) & {
     readonly steps: ReadonlyArray<WorkflowRunStepRow>;
 };