@effect-app/vue 4.0.0-beta.180 → 4.0.0-beta.182

package/src/commander.ts

@@ -6,7 +6,7 @@ import { SupportedErrors } from "effect-app/client"
 import { OperationFailure, OperationSuccess } from "effect-app/Operations"
 import { isGeneratorFunction, wrapEffect } from "effect-app/utils"
 import { type Refinement } from "effect/Predicate"
-import { type AsyncResult } from "effect/unstable/reactivity/AsyncResult"
+import type * as AsyncResult from "effect/unstable/reactivity/AsyncResult"
 import { type FormatXMLElementFn, type PrimitiveType } from "intl-messageformat"
 import { computed, type ComputedRef, reactive, ref, toRaw } from "vue"
 import { Confirm } from "./confirm.js"
@@ -14,7 +14,53 @@ import { I18n } from "./intl.js"
 import { WithToast } from "./withToast.js"
 
 type IntlRecord = Record<string, PrimitiveType | FormatXMLElementFn<string, string>>
-type FnOptions<Id extends string, I18nCustomKey extends string, State extends IntlRecord | undefined> = {
+
+/**
+ * Progress information surfaced by a stream command. Either a plain text label
+ * or a `{ text, percentage }` pair when concrete progress is known.
+ */
+export type Progress = string | { readonly text: string; readonly percentage: number }
+
+/**
+ * Options accepted when calling a stream mutation factory.
+ * Supplying `progress` causes the resulting command to expose `running`
+ * (the live AsyncResult ref) and `progress` (formatted loading info).
+ * When omitted, neither is exposed on the command.
+ */
+export type StreamMutationCallOptions<A, E> = {
+  progress?: (result: AsyncResult.AsyncResult<A, E>) => Progress | undefined
+}
+
+/**
+ * The result of invoking a `mutateStream` factory: the `execute` function (or
+ * `Effect`, when the request takes no input) carries `id`, plus `running` and
+ * `progress` when the factory was called with a `progress` formatter. Pass
+ * directly to `Command.fn` / `Command.wrap` / `Command.wrapStream`, or invoke
+ * to run the stream.
+ */
+type StreamMutationCallable<Id extends string, Arg, A, E, R> =
+  & (((arg: Arg) => Effect.Effect<any, E, R>) | Effect.Effect<any, E, R>)
+  & {
+    readonly id: Id
+    readonly _streamCallable: true
+    readonly running?: ComputedRef<AsyncResult.AsyncResult<A, E>>
+    readonly progress?: ComputedRef<Progress | undefined>
+  }
+
+type StreamMutationFactory<Id extends string, Arg, A, E, R> =
+  & ((options?: StreamMutationCallOptions<A, E>) => StreamMutationCallable<Id, Arg, A, E, R>)
+  & { readonly id: Id; readonly _streamFactory: true }
+
+const isStreamFactory = (x: unknown): x is StreamMutationFactory<string, any, any, any, any> =>
+  typeof x === "function" && (x as any)._streamFactory === true
+
+const isStreamCallable = (x: unknown): x is StreamMutationCallable<string, any, any, any, any> =>
+  x !== null && x !== undefined && (x as any)._streamCallable === true
+type FnOptions<
+  Id extends string,
+  I18nCustomKey extends string,
+  State extends IntlRecord | undefined
+> = {
   i18nCustomKey?: I18nCustomKey
   /**
    * passed to the i18n formatMessage calls so you can use it in translation messagee
@@ -139,7 +185,19 @@ export declare namespace Commander {
     /** reactive */
     label: string
     /** reactive */
-    result: AsyncResult<A, E>
+    result: AsyncResult.AsyncResult<A, E>
+    /**
+     * reactive – set when the command wraps a stream (`wrapStream` / `wrap` with `mutateStream`)
+     * or when the `progress` option is provided to `fn`.
+     * Reflects the live AsyncResult of the underlying stream.
+     */
+    running: AsyncResult.AsyncResult<any, any> | undefined
+    /**
+     * reactive – formatted progress info computed from `running` via the
+     * `progress` option. Useful as the loading state on a `CommandButton`.
+     * Undefined when no `progress` formatter was supplied.
+     */
+    progress: Progress | undefined
     /** reactive */
     waiting: boolean
     /** reactive */
@@ -1983,7 +2041,11 @@ const unregisterWait = (id: string) => {
   }
 }
 
-const getStateValues = <const Id extends string, const I18nKey extends string, State extends IntlRecord | undefined>(
+const getStateValues = <
+  const Id extends string,
+  const I18nKey extends string,
+  State extends IntlRecord | undefined
+>(
   options?: FnOptions<Id, I18nKey, State>
 ): ComputedRef<State> => {
   const state_ = options?.state
@@ -2035,11 +2097,17 @@ export class CommanderImpl<RT, RTHooks> {
   readonly makeCommand = <
     const Id extends string,
     const State extends IntlRecord | undefined,
-    const I18nKey extends string = Id
+    const I18nKey extends string = Id,
+    RunningA = unknown,
+    RunningE = unknown
   >(
     id_: Id | { id: Id },
     options?: FnOptions<Id, I18nKey, State>,
-    errorDef?: Error
+    errorDef?: Error,
+    streamMeta?: {
+      running?: ComputedRef<AsyncResult.AsyncResult<RunningA, RunningE>> | undefined
+      progress?: ComputedRef<Progress | undefined> | undefined
+    }
   ) => {
     const id = typeof id_ === "string" ? id_ : id_.id
     const state = getStateValues(options)
@@ -2224,6 +2292,12 @@ export class CommanderImpl<RT, RTHooks> {
 
           /** reactive */
           result,
+          /** reactive – live AsyncResult of the underlying stream, exposed only when
+           * the stream factory was called with a `progress` formatter */
+          running: streamMeta?.running,
+          /** reactive – formatted progress info for current `running` state, when `progress`
+           * formatter was supplied to the stream factory */
+          progress: streamMeta?.progress,
           /** reactive */
           waiting,
           /** reactive */
@@ -2325,14 +2399,41 @@ export class CommanderImpl<RT, RTHooks> {
   fn = <
     const Id extends string,
     const State extends IntlRecord = IntlRecord,
-    const I18nKey extends string = Id
+    const I18nKey extends string = Id,
+    RunningA = unknown,
+    RunningE = unknown
   >(
-    id: Id | { id: Id },
+    id:
+      | Id
+      | { id: Id }
+      | StreamMutationCallable<Id, any, RunningA, RunningE, any>
+      | StreamMutationFactory<Id, any, RunningA, RunningE, any>,
     options?: FnOptions<Id, I18nKey, State>
   ): Commander.Gen<RT | RTHooks, Id, I18nKey, State> & Commander.NonGen<RT | RTHooks, Id, I18nKey, State> & {
     state: Context.Service<`Commander.Command.${Id}.state`, State>
-  } =>
-    Object.assign(
+  } => {
+    // Resolve id and (optionally) per-build stream metadata.
+    const resolvedId: Id = typeof id === "string" ? id : (id as { id: Id }).id
+    const factory = isStreamFactory(id)
+    const callable = !factory && isStreamCallable(id)
+    const resolveStreamMeta = ():
+      | {
+        running?: ComputedRef<AsyncResult.AsyncResult<RunningA, RunningE>> | undefined
+        progress?: ComputedRef<Progress | undefined> | undefined
+      }
+      | undefined =>
+    {
+      if (factory) {
+        const c = id()
+        return { running: c.running, progress: c.progress }
+      }
+      if (callable) {
+        const c = id as StreamMutationCallable<Id, any, RunningA, RunningE, any>
+        return { running: c.running, progress: c.progress }
+      }
+      return undefined
+    }
+    return Object.assign(
       (
         fn: any,
         ...combinators: any[]
@@ -2343,7 +2444,9 @@ export class CommanderImpl<RT, RTHooks> {
         const errorDef = new Error()
         Error.stackTraceLimit = limit
 
-        return this.makeCommand(id, options, errorDef)(
+        const streamMeta = resolveStreamMeta()
+
+        return this.makeCommand(resolvedId, options, errorDef, streamMeta)(
           Effect.fnUntraced(
             // fnUntraced only supports generators as first arg, so we convert to generator if needed
             isGeneratorFunction(fn) ? fn : function*(...args) {
@@ -2353,13 +2456,14 @@ export class CommanderImpl<RT, RTHooks> {
           ) as any
         )
       },
-      makeBaseInfo(typeof id === "string" ? id : id.id, options),
+      makeBaseInfo(resolvedId, options),
       {
         state: Context.Service<`Commander.Command.${Id}.state`, State>(
-          `Commander.Command.${typeof id === "string" ? id : id.id}.state`
+          `Commander.Command.${resolvedId}.state`
         )
       }
     )
+  }
 
   /** @deprecated */
   alt2: <
@@ -2464,10 +2568,28 @@ export class CommanderImpl<RT, RTHooks> {
   >(
     mutation:
       | { mutate: (arg: Arg) => Effect.Effect<A, E, R>; id: Id }
-      | ((arg: Arg) => Effect.Effect<A, E, R>) & { id: Id },
+      | ((arg: Arg) => Effect.Effect<A, E, R>) & { id: Id }
+      | StreamMutationFactory<Id, Arg, A, E, R>
+      | {
+        id: Id
+        mutateStream:
+          | StreamMutationFactory<Id, Arg, A, E, R>
+          | StreamMutationCallable<Id, Arg, A, E, R>
+      }
+      | StreamMutationCallable<Id, Arg, A, E, R>,
     options?: FnOptions<Id, I18nKey, State>
-  ): Commander.CommanderWrap<RT | RTHooks, Id, I18nKey, State, Arg, A, E, R> =>
-    Object.assign(
+  ): Commander.CommanderWrap<RT | RTHooks, Id, I18nKey, State, Arg, A, E, R> => {
+    if (mutation !== null && typeof mutation === "object" && "mutateStream" in mutation) {
+      return this.wrapStream(mutation as any, options) as any
+    }
+    if (isStreamCallable(mutation) || isStreamFactory(mutation)) {
+      return this.wrapStream(mutation as any, options) as any
+    }
+    // At this point mutation is either { mutate, id } or (fn & { id })
+    const callMutation = mutation as
+      | { mutate: (arg: Arg) => Effect.Effect<A, E, R>; id: Id }
+      | (((arg: Arg) => Effect.Effect<A, E, R>) & { id: Id })
+    return Object.assign(
       (
         ...combinators: any[]
       ): any => {
@@ -2476,9 +2598,11 @@ export class CommanderImpl<RT, RTHooks> {
         Error.stackTraceLimit = 2
         const errorDef = new Error()
         Error.stackTraceLimit = limit
-        const mutate = "mutate" in mutation ? mutation.mutate : mutation
+        const mutate = "mutate" in callMutation
+          ? callMutation.mutate
+          : callMutation
 
-        return this.makeCommand(mutation.id, options, errorDef)(
+        return this.makeCommand(callMutation.id, options, errorDef)(
           Effect.fnUntraced(
             // fnUntraced only supports generators as first arg, so we convert to generator if needed
             isGeneratorFunction(mutate) ? mutate : function*(arg: Arg) {
@@ -2488,13 +2612,107 @@ export class CommanderImpl<RT, RTHooks> {
           ) as any
         )
       },
-      makeBaseInfo(mutation.id, options),
+      makeBaseInfo(callMutation.id, options),
       {
         state: Context.Service<`Commander.Command.${Id}.state`, State>(
-          `Commander.Command.${mutation.id}.state`
+          `Commander.Command.${callMutation.id}.state`
         )
       }
     )
+  }
+
+  /**
+   * Define a Command from a stream-type mutation (`mutateStream` factory).
+   * The stream's reactive `AsyncResult` ref is exposed as `running` for independent progress tracking.
+   * The command's own `result` reflects the execution outcome of the `execute` function.
+   * Supports the same combinator pipeline as `wrap` (e.g. `withDefaultToast`).
+   *
+   * Each invocation of the resulting wrap call produces a fresh `[ref, execute]` pair
+   * (the `mutateStream` factory is called once per build), so independent commands
+   * don't share progress state.
+   *
+   * Accepts either:
+   * - An object with `id` and `mutateStream` factory (e.g. a client entry)
+   * - The `mutateStream` factory directly (callable, with `id`)
+   * - An already-called factory result (`[resultRef, execute] & { id }`) — shared ref across builds
+   *
+   * @example
+   * ```ts
+   * // Via client entry (recommended):
+   * const exportCmd = Command.wrapStream(client.myExport)()
+   *
+   * // Via factory directly:
+   * const exportCmd = Command.wrapStream(client.myExport.mutateStream)()
+   *
+   * // Via already-called factory (shared ref):
+   * const stream = client.myExport.mutateStream()
+   * const exportCmd = Command.wrapStream(stream)()
+   * ```
+   */
+  wrapStream = <
+    const Id extends string,
+    Arg,
+    A,
+    E,
+    R,
+    const State extends IntlRecord = IntlRecord,
+    const I18nKey extends string = Id
+  >(
+    mutation:
+      | {
+        id: Id
+        mutateStream:
+          | StreamMutationFactory<Id, Arg, A, E, R>
+          | StreamMutationCallable<Id, Arg, A, E, R>
+      }
+      | StreamMutationFactory<Id, Arg, A, E, R>
+      | StreamMutationCallable<Id, Arg, A, E, R>,
+    options?: FnOptions<Id, I18nKey, State>
+  ): Commander.CommanderWrap<RT | RTHooks, Id, I18nKey, State, Arg, A, E, R> => {
+    const id = mutation.id
+    // Resolve `source` to the factory or already-invoked callable.
+    const source: StreamMutationFactory<Id, Arg, A, E, R> | StreamMutationCallable<Id, Arg, A, E, R> =
+      mutation !== null && typeof mutation === "object" && "mutateStream" in mutation
+        ? (mutation.mutateStream as any)
+        : (mutation as any)
+    const resolveCallable = (): StreamMutationCallable<Id, Arg, A, E, R> =>
+      (isStreamFactory(source)
+        ? (source as StreamMutationFactory<Id, Arg, A, E, R>)()
+        : source) as StreamMutationCallable<Id, Arg, A, E, R>
+    return Object.assign(
+      (...combinators: any[]): any => {
+        // we capture the definition stack here, so we can append it to later stack traces
+        const limit = Error.stackTraceLimit
+        Error.stackTraceLimit = 2
+        const errorDef = new Error()
+        Error.stackTraceLimit = limit
+
+        // Fresh per build: invoke the factory once per command instance so each
+        // wrap call gets its own state + execute pair. `running`/`progress`
+        // are only surfaced when the factory was called with a `progress` formatter.
+        const callable = resolveCallable()
+        const mutate: (_arg: Arg) => Effect.Effect<any, E, R> = Effect.isEffect(callable)
+          ? (_arg: Arg) => callable
+          : callable as (arg: Arg) => Effect.Effect<any, E, R>
+        const streamMeta = { running: callable.running, progress: callable.progress }
+
+        return this.makeCommand(id, options, errorDef, streamMeta)(
+          Effect.fnUntraced(
+            isGeneratorFunction(mutate) ? mutate : function*(arg: Arg) {
+              return yield* mutate(arg)
+            },
+            ...combinators as [any]
+          ) as any
+        )
+      },
+      makeBaseInfo(id, options),
+      {
+        state: Context.Service<`Commander.Command.${Id}.state`, State>(
+          `Commander.Command.${id}.state`
+        )
+      }
+    )
+  }
 }
 
 // @effect-diagnostics-next-line missingEffectServiceDependency:off

package/src/makeClient.ts

@@ -8,8 +8,8 @@ import type { InvalidationCallback } from "effect-app/client/makeClient"
 import type * as ExitResult from "effect/Exit"
 import { type Fiber } from "effect/Fiber"
 import * as AsyncResult from "effect/unstable/reactivity/AsyncResult"
-import { type ComputedRef, onBeforeUnmount, ref, type WatchSource } from "vue"
-import { type Commander, CommanderStatic } from "./commander.js"
+import { computed, type ComputedRef, onBeforeUnmount, ref, type WatchSource } from "vue"
+import { type Commander, CommanderStatic, type Progress } from "./commander.js"
 import { type I18n } from "./intl.js"
 import { type CommanderResolved, makeUseCommand } from "./makeUseCommand.js"
 import { makeMutation, makeStreamMutation, type MutationOptionsBase, useMakeMutation } from "./mutate.js"
@@ -225,16 +225,71 @@ export type MutationWithExtensions<RT, Req> = Req extends
   : never
 
 /**
- * The `mutateStream` tuple for a stream-type request handler:
- * `[resultRef, execute]` where `execute` updates the ref live with each emitted value.
- * When the request declares a `final` schema, `execute` resolves with the last emitted value
- * typed as `Final`; otherwise it resolves with `void`.
+ * Options for invoking a `mutateStream` factory. Supplying `progress` produces
+ * a tuple-with-id that carries `running` (the live AsyncResult ref) and
+ * `progress` (a `ComputedRef<Progress | undefined>` formatted from each value),
+ * which `Command.fn` / `Command.wrapStream` surface as the command's `running`
+ * and `progress`. When omitted, the resulting command exposes neither.
+ */
+export type MutateStreamCallOptions<A, E> = {
+  progress?: (result: AsyncResult.AsyncResult<A, E>) => Progress | undefined
+}
+
+/**
+ * The `mutateStream` factory for a stream-type request handler. Always invoke
+ * (optionally with `{ progress }`) to get a fresh callable `execute` — each call
+ * produces a new state + execute pair so independent invocations don't share
+ * state. The callable updates its underlying ref live with each emitted value
+ * and carries `id`, plus `running` and `progress` when the factory was called
+ * with a `progress` formatter. When the request declares a `final` schema,
+ * the callable resolves with the last emitted value typed as `Final`; otherwise
+ * it resolves with the success type. The factory itself carries the request
+ * `id` so it can be passed to `Command.fn` / `Command.wrapStream` directly.
  */
 export type StreamMutationWithExtensions<Req> = Req extends
-  RequestStreamHandlerWithInput<infer I, infer A, infer E, infer R, infer _Request, infer _Id, infer Final>
-  ? readonly [ComputedRef<AsyncResult.AsyncResult<A, E>>, (input: I) => Effect.Effect<Final, never, R>]
-  : Req extends RequestStreamHandler<infer A, infer E, infer R, infer _Request, infer _Id, infer Final>
-    ? readonly [ComputedRef<AsyncResult.AsyncResult<A, E>>, Effect.Effect<Final, never, R>]
+  RequestStreamHandlerWithInput<infer I, infer A, infer E, infer R, infer _Request, infer Id, infer Final> ?
+    & ((options?: MutateStreamCallOptions<A, E>) =>
+      & ((input: I) => Effect.Effect<Final, E, R>)
+      & {
+        readonly id: Id
+        readonly _streamCallable: true
+        readonly running?: ComputedRef<AsyncResult.AsyncResult<A, E>>
+        readonly progress?: ComputedRef<Progress | undefined>
+      })
+    & { readonly id: Id; readonly _streamFactory: true }
+  : Req extends RequestStreamHandler<infer A, infer E, infer R, infer _Request, infer Id, infer Final> ?
+      & ((options?: MutateStreamCallOptions<A, E>) =>
+        & Effect.Effect<Final, E, R>
+        & {
+          readonly id: Id
+          readonly _streamCallable: true
+          readonly running?: ComputedRef<AsyncResult.AsyncResult<A, E>>
+          readonly progress?: ComputedRef<Progress | undefined>
+        })
+      & { readonly id: Id; readonly _streamFactory: true }
+  : never
+
+/**
+ * The pre-built `wrapStream` CommanderWrap for a stream-type request handler.
+ * The command's `result` and `running` are the live stream ref.
+ * Callable like `wrap`: `client.myExport.wrapStream()` returns the CommandOut.
+ */
+export type StreamCommandWithExtensions<RT, Req> = Req extends
+  RequestStreamHandlerWithInput<infer I, infer A, infer E, infer R, infer _Request, infer Id, infer _Final>
+  ? Commander.CommanderWrap<RT, Id, Id, undefined, I, A, E, R>
+  : Req extends RequestStreamHandler<infer A, infer E, infer R, infer _Request, infer Id, infer _Final>
+    ? Commander.CommanderWrap<RT, Id, Id, undefined, void, A, E, R>
+  : never
+
+/**
+ * The `fn` builder for a stream-type request handler — identical to calling
+ * `Command.fn(id)` where `id` comes from the request.
+ */
+export type StreamFnExtension<RT, Req> = Req extends
+  RequestStreamHandlerWithInput<infer _I, infer _A, infer _E, infer _R, infer _Request, infer Id, infer _Final>
+  ? Commander.CommanderFn<RT, Id, Id, undefined>
+  : Req extends RequestStreamHandler<infer _A, infer _E, infer _R, infer _Request, infer Id, infer _Final>
+    ? Commander.CommanderFn<RT, Id, Id, undefined>
   : never
 
 // we don't really care about the RT, as we are in charge of ensuring runtime safety anyway
@@ -767,6 +822,7 @@ export const makeClient = <RT_, RTHooks>(
     queryInvalidation?: (client: ClientFrom<M>) => QueryInvalidation<M>,
     invalidationResources?: InvalidationResourcesFor<M>
   ) => {
+    const Command = useCommand()
     const streamMutation = useStreamMutation()
     const invalidation = queryInvalidation?.(client)
     const queryResources = makeQueryResources(invalidationResources)
@@ -786,14 +842,36 @@ export const makeClient = <RT_, RTHooks>(
             })))
           : undefined
         const mergedInvalidation = mergeInvalidation(fromRequest, invalidation?.[key])
-        ;(acc as any)[camelCase(key) + "Stream"] = streamMutation(client[key] as any, mergedInvalidation)
+        const smFactory = Object.assign(
+          (opts?: { progress?: (result: AsyncResult.AsyncResult<any, any>) => Progress | undefined }) => {
+            const [resultRef, execute] = streamMutation(client[key] as any, mergedInvalidation)
+            const extras: {
+              id: string
+              _streamCallable: true
+              running?: ComputedRef<AsyncResult.AsyncResult<any, any>>
+              progress?: ComputedRef<Progress | undefined>
+            } = { id: client[key].id, _streamCallable: true }
+            if (opts?.progress) {
+              const fmt = opts.progress
+              extras.running = resultRef
+              extras.progress = computed(() => fmt(resultRef.value))
+            }
+            return Object.assign(execute, extras)
+          },
+          { id: client[key].id, _streamFactory: true as const }
+        )
+        ;(acc as any)[camelCase(key) + "Stream"] = Object.assign(smFactory, {
+          fn: Command.fn(client[key].id)
+        })
         return acc
       },
       {} as {
         [
           Key in keyof typeof client as StreamHandler<typeof client[Key]> extends never ? never
             : `${ToCamel<string & Key>}Stream`
-        ]: StreamMutationWithExtensions<StreamHandler<typeof client[Key]>>
+        ]:
+          & StreamMutationWithExtensions<StreamHandler<typeof client[Key]>>
+          & { fn: StreamFnExtension<RT | RTHooks, StreamHandler<typeof client[Key]>> }
       }
     )
     return streams
@@ -862,10 +940,30 @@ export const makeClient = <RT_, RTHooks>(
                   })))
                 : undefined
               const mergedInvalidation = mergeInvalidation(fromRequest, invalidation?.[key])
+              const streamMutFactory = Object.assign(
+                (opts?: { progress?: (result: AsyncResult.AsyncResult<any, any>) => Progress | undefined }) => {
+                  const [resultRef, execute] = streamMutation(client[key] as any, mergedInvalidation)
+                  const extras: {
+                    id: string
+                    _streamCallable: true
+                    running?: ComputedRef<AsyncResult.AsyncResult<any, any>>
+                    progress?: ComputedRef<Progress | undefined>
+                  } = { id: client[key].id, _streamCallable: true }
+                  if (opts?.progress) {
+                    const fmt = opts.progress
+                    extras.running = resultRef
+                    extras.progress = computed(() => fmt(resultRef.value))
+                  }
+                  return Object.assign(execute, extras)
+                },
+                { id: client[key].id, _streamFactory: true as const }
+              )
               return {
                 ...client[key],
                 request: h_,
-                mutateStream: streamMutation(client[key] as any, mergedInvalidation)
+                mutateStream: streamMutFactory,
+                wrapStream: Command.wrapStream(streamMutFactory),
+                fn: Command.fn(client[key].id)
               }
             })()
             : {
@@ -927,7 +1025,11 @@ export const makeClient = <RT_, RTHooks>(
           & (CommandHandler<typeof client[Key]> extends never ? {}
             : { mutate: MutationWithExtensions<RT | RTHooks, CommandHandler<typeof client[Key]>> })
           & (StreamHandler<typeof client[Key]> extends never ? {}
-            : { mutateStream: StreamMutationWithExtensions<StreamHandler<typeof client[Key]>> })
+            : {
+              mutateStream: StreamMutationWithExtensions<StreamHandler<typeof client[Key]>>
+              wrapStream: StreamCommandWithExtensions<RT | RTHooks, StreamHandler<typeof client[Key]>>
+              fn: StreamFnExtension<RT | RTHooks, StreamHandler<typeof client[Key]>>
+            })
           & { Input: typeof client[Key] extends RequestHandlerWithInput<infer I, any, any, any, any, any> ? I : never }
       }
     )
@@ -988,6 +1090,7 @@ export const makeClient = <RT_, RTHooks>(
       // delay initialisation until first use...
       fn: (...args: [any]) => useCommand().fn(...args),
       wrap: (...args: [any]) => useCommand().wrap(...args),
+      wrapStream: (...args: [any]) => useCommand().wrapStream(...args),
       alt: (...args: [any]) => useCommand().alt(...args),
       alt2: (...args: [any]) => useCommand().alt2(...args)
     } as ReturnType<typeof useCommand>,
@@ -1025,6 +1128,8 @@ export interface CommandBase<I = void, A = void> {
   allowed: boolean
   action: string
   label: string
+  /** formatted progress info for current `running` state, when `progress` was supplied */
+  progress?: Progress | undefined
 }
 
 export interface EffectCommand<I = void, A = unknown, E = unknown> extends CommandBase<I, Fiber<A, E>> {}

package/src/makeUseCommand.ts

@@ -5,7 +5,7 @@ type X<X> = X
 
 // helps retain JSDoc
 export interface CommanderResolved<RT, RTHooks>
-  extends X<typeof CommanderStatic>, Pick<CommanderImpl<RT, RTHooks>, "fn" | "wrap" | "alt" | "alt2">
+  extends X<typeof CommanderStatic>, Pick<CommanderImpl<RT, RTHooks>, "fn" | "wrap" | "wrapStream" | "alt" | "alt2">
 {
 }
 

package/src/mutate.ts

@@ -420,7 +420,8 @@ export const useMakeMutation = () => {
  * success or failure.
  *
  * When the request declares a `final` schema, `execute` resolves with the last emitted value
- * typed as `Final`; otherwise it resolves with `void`.
+ * typed as `Final`; otherwise it resolves with the last emitted value typed as the success type.
+ * Stream failures bubble through the execute effect's typed error channel `E`.
  *
  * Must be called inside a Vue setup context (uses `useQueryClient` internally).
  */
@@ -437,7 +438,7 @@ export const makeStreamMutation = () => {
   ) => {
     const state = shallowRef<AsyncResult.AsyncResult<any, any>>(AsyncResult.initial())
 
-    const runStream = (stream: Stream.Stream<any, any, any>, input?: unknown): Effect.Effect<any, never, any> => {
+    const runStream = (stream: Stream.Stream<any, any, any>, input?: unknown): Effect.Effect<any, any, any> => {
       const invCache = buildInvalidateCache(queryClient, self, mergedInvalidation)
       const keysRef = Ref.makeUnsafe<ReadonlyArray<InvalidationKey>>([])
       // V3: pass onAdded so each mid-stream metadata chunk triggers query
@@ -476,11 +477,14 @@ export const makeStreamMutation = () => {
                 const lastValue = AsyncResult.isSuccess(current) ? current.value : undefined
                 const invExit = exit._tag === "Success" ? Exit.succeed(lastValue) : exit
                 const serverKeys = Ref.getUnsafe(keysRef)
-                // Note: when the stream fails, `lastValue` is undefined. The failure is
-                // communicated via the reactive `state` ref (AsyncResult.failure). The
-                // execute effect always resolves successfully; callers should inspect the
-                // ref to distinguish success from failure.
-                return invCache(input, invExit, serverKeys).pipe(Effect.as(lastValue))
+                // Stream failures bubble through the execute effect's typed error
+                // channel. The reactive `state` ref still mirrors the failure as
+                // `AsyncResult.failure` for live progress UI.
+                return invCache(input, invExit, serverKeys).pipe(
+                  Effect.flatMap(() =>
+                    exit._tag === "Success" ? Effect.succeed(lastValue) : Effect.failCause(exit.cause)
+                  )
+                )
               })
             )
           )