@effect-app/vue 4.0.0-beta.181 → 4.0.0-beta.183

package/src/commander.ts

@@ -1,12 +1,13 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { asResult, deepToRaw, type MissingDependencies, reportRuntimeError } from "@effect-app/vue"
+import { asResult, asStreamResult, deepToRaw, type MissingDependencies, reportRuntimeError } from "@effect-app/vue"
 import { reportMessage } from "@effect-app/vue/errorReporter"
 import { Cause, Context, Effect, type Exit, type Fiber, flow, Layer, Match, MutableHashMap, Option, Predicate, S } from "effect-app"
 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 * as AsyncResult from "effect/unstable/reactivity/AsyncResult"
+import * as Stream from "effect/Stream"
+import * 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"
@@ -31,20 +32,31 @@ export type StreamMutationCallOptions<A, E> = {
   progress?: (result: AsyncResult.AsyncResult<A, E>) => Progress | undefined
 }
 
-type StreamMutationTuple<Id extends string, Arg, A, E, R> =
-  & readonly [
-    ComputedRef<AsyncResult.AsyncResult<A, E>>,
-    ((arg: Arg) => Effect.Effect<any, never, R>) | Effect.Effect<any, never, R>
-  ]
+/**
+ * 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>) => StreamMutationTuple<Id, Arg, A, E, R>)
-  & { readonly id: Id }
+  & ((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,
@@ -114,6 +126,35 @@ export class CommandContext extends Context.Service<CommandContext, {
   "CommandContext"
 ) {}
 
+/**
+ * Service available inside `streamFn` stream handlers that lets you imperatively push
+ * progress updates to the command's reactive `progress` ref.
+ *
+ * Use `Command.mapProgress(fn)` or `Command.updateProgress(progress)` to interact with this service.
+ *
+ * @example
+ * ```ts
+ * // Using mapProgress (recommended) — applied as a stream pipe operator:
+ * const exportCmd = Command.streamFn("exportData")(
+ *   function*(arg, ctx) {
+ *     return makeExportStream(arg.id).pipe(
+ *       Command.mapProgress((r) =>
+ *         AsyncResult.isSuccess(r) && r.value._tag === "OperationProgress"
+ *           ? { text: `${r.value.completed}/${r.value.total}`, percentage: r.value.completed / r.value.total * 100 }
+ *           : undefined
+ *       )
+ *     )
+ *   }
+ * )
+ * // exportCmd.progress is updated for every OperationProgress event
+ * ```
+ */
+export class CommandProgress extends Context.Reference<{
+  readonly update: (progress: Progress | undefined) => Effect.Effect<void>
+}>("Commander.CommandProgress", {
+  defaultValue: () => ({ update: (_progress: Progress | undefined): Effect.Effect<void> => Effect.void })
+}) {}
+
 export type EmitWithCallback<A, Event extends string> = (event: Event, value: A, onDone: () => void) => void
 
 /**
@@ -1705,6 +1746,132 @@ export declare namespace Commander {
       ) => Eff
     ): CommandOutHelper<Arg, Eff, Id, I18nKey, State>
   }
+
+  /**
+   * Type for `streamFn` — generator overload where the body yields Effects and returns a `Stream`.
+   * `waiting` stays `true` while the stream is running, and updates the `result` ref per emitted value.
+   */
+  export type StreamGen<RT, Id extends string, I18nKey extends string, State extends IntlRecord | undefined> = {
+    <
+      Eff extends Effect.Yieldable<any, any, any, RT | CommandContext | `Commander.Command.${Id}.state`>,
+      SA,
+      SE,
+      SR,
+      Arg = void
+    >(
+      body: (
+        arg: Arg,
+        ctx: CommandContextLocal2<Id, I18nKey, State>
+      ) => Generator<Eff, Stream.Stream<SA, SE, SR>, never>
+    ): CommandOut<
+      Arg,
+      SA,
+      | SE
+      | ([Eff] extends [never] ? never
+        : [Eff] extends [Effect.Yieldable<any, infer _A, infer E, infer _R>] ? E
+        : never),
+      | SR
+      | ([Eff] extends [never] ? never
+        : [Eff] extends [Effect.Yieldable<any, infer _A, infer _E, infer R>] ? R
+        : never),
+      Id,
+      I18nKey,
+      State
+    >
+    <
+      Eff extends Effect.Yieldable<any, any, any, RT | CommandContext | `Commander.Command.${Id}.state`>,
+      SA,
+      SE,
+      SR,
+      B,
+      Arg = void
+    >(
+      body: (
+        arg: Arg,
+        ctx: CommandContextLocal2<Id, I18nKey, State>
+      ) => Generator<Eff, Stream.Stream<SA, SE, SR>, never>,
+      a: (
+        _: Effect.Effect<
+          Stream.Stream<SA, SE, SR>,
+          ([Eff] extends [never] ? never
+            : [Eff] extends [Effect.Yieldable<any, infer _A, infer E, infer _R>] ? E
+            : never),
+          ([Eff] extends [never] ? never
+            : [Eff] extends [Effect.Yieldable<any, infer _A, infer _E, infer R>] ? R
+            : never)
+        >,
+        arg: ArgForCombinator<Arg>,
+        ctx: CommandContextLocal2<NoInfer<Id>, NoInfer<I18nKey>, NoInfer<State>>
+      ) => B
+    ): B extends Stream.Stream<infer SA2, infer SE2, infer SR2> ? CommandOut<Arg, SA2, SE2, SR2, Id, I18nKey, State>
+      : B extends Effect.Effect<Stream.Stream<infer SA2, infer SE2, infer SR2>, infer EE2, infer ER2>
+        ? CommandOut<Arg, SA2, SE2 | EE2, SR2 | ER2, Id, I18nKey, State>
+      : never
+  }
+
+  /**
+   * Type for `streamFn` — non-generator overload accepting a function that returns a `Stream` directly,
+   * or an `Effect` that resolves to a `Stream`.
+   */
+  export type NonGenStream<RT, Id extends string, I18nKey extends string, State extends IntlRecord | undefined> = {
+    <
+      SA,
+      SE,
+      SR extends RT | CommandContext | `Commander.Command.${Id}.state`,
+      Arg = void
+    >(
+      body: (arg: Arg, ctx: CommandContextLocal2<Id, I18nKey, State>) => Stream.Stream<SA, SE, SR>
+    ): CommandOut<Arg, SA, SE, SR, Id, I18nKey, State>
+    <
+      SA,
+      SE,
+      SR,
+      A extends Stream.Stream<any, any, RT | CommandContext | `Commander.Command.${Id}.state`>,
+      Arg = void
+    >(
+      body: (arg: Arg, ctx: CommandContextLocal2<Id, I18nKey, State>) => Stream.Stream<SA, SE, SR>,
+      a: (
+        _: Stream.Stream<SA, SE, SR>,
+        arg: ArgForCombinator<Arg>,
+        ctx: CommandContextLocal2<NoInfer<Id>, NoInfer<I18nKey>, NoInfer<State>>
+      ) => A
+    ): CommandOut<Arg, Stream.Success<A>, Stream.Error<A>, Stream.Services<A>, Id, I18nKey, State>
+    <
+      SA,
+      SE,
+      SR,
+      EE,
+      ER extends RT | CommandContext | `Commander.Command.${Id}.state`,
+      Arg = void
+    >(
+      body: (
+        arg: Arg,
+        ctx: CommandContextLocal2<Id, I18nKey, State>
+      ) => Effect.Effect<Stream.Stream<SA, SE, SR>, EE, ER>
+    ): CommandOut<Arg, SA, SE | EE, SR | ER, Id, I18nKey, State>
+    <
+      SA,
+      SE,
+      SR,
+      EE,
+      ER,
+      B,
+      Arg = void
+    >(
+      body: (
+        arg: Arg,
+        ctx: CommandContextLocal2<Id, I18nKey, State>
+      ) => Effect.Effect<Stream.Stream<SA, SE, SR>, EE, ER>,
+      a: (
+        _: Effect.Effect<Stream.Stream<SA, SE, SR>, EE, ER>,
+        arg: ArgForCombinator<Arg>,
+        ctx: CommandContextLocal2<NoInfer<Id>, NoInfer<I18nKey>, NoInfer<State>>
+      ) => B
+    ): B extends Stream.Stream<infer SA2, infer SE2, infer SR2> ? CommandOut<Arg, SA2, SE2, SR2, Id, I18nKey, State>
+      : B extends Effect.Effect<Stream.Stream<infer SA2, infer SE2, infer SR2>, infer EE2, infer ER2>
+        ? CommandOut<Arg, SA2, SE2 | EE2, SR2 | ER2, Id, I18nKey, State>
+      : never
+  }
 }
 
 type ErrorRenderer<E, Args extends readonly any[]> = (e: E, action: string, ...args: Args) => string | undefined
@@ -1827,6 +1994,66 @@ export const CommanderStatic = {
   ) =>
   (self: In, arg: Arg, arg2: Arg2) => cb(arg, arg2)(self),
 
+  /**
+   * Stream pipe operator that maps each emitted value to a `Progress` entry and updates the
+   * command's reactive `progress` ref via the `CommandProgress` service.
+   *
+   * The mapper receives an `AsyncResult<A, E>` (each emitted value wrapped as
+   * `AsyncResult.success(value, { waiting: true })`), matching the same shape used by
+   * `CommandButton`'s `:progress-map` prop.
+   *
+   * Designed to be used inside a `streamFn` handler (either directly with `.pipe()`, or as
+   * a combinator argument):
+   *
+   * @example
+   * ```ts
+   * // Inside the handler body:
+   * Command.streamFn("exportData")(function*(arg, ctx) {
+   *   return makeExportStream(arg.id).pipe(
+   *     Command.mapProgress((r) =>
+   *       AsyncResult.isSuccess(r) && r.value._tag === "OperationProgress"
+   *         ? { text: `${r.value.completed}/${r.value.total}`, percentage: r.value.completed / r.value.total * 100 }
+   *         : undefined
+   *     )
+   *   )
+   * })
+   *
+   * // Or as a stream combinator argument:
+   * Command.streamFn("exportData")(
+   *   function*(arg, ctx) { return makeExportStream(arg.id) },
+   *   (s) => s.pipe(Command.mapProgress((r) => AsyncResult.isSuccess(r) && r.value._tag === "OperationProgress" ? { text: `${r.value.completed}/${r.value.total}` } : undefined))
+   * )
+   * ```
+   */
+  mapProgress:
+    <A, E>(fn: (result: AsyncResult.AsyncResult<A, E>) => Progress | undefined) =>
+    <R>(stream: Stream.Stream<A, E, R>): Stream.Stream<A, E, R> =>
+      stream.pipe(
+        Stream.tap((v) => {
+          const p = fn(AsyncResult.success(v, { waiting: true }))
+          return p !== undefined ? CommandProgress.use((s) => s.update(p)) : Effect.void
+        })
+      ),
+
+  /**
+   * Imperatively push a progress update from inside a `streamFn` handler.
+   * Requires `CommandProgress` to be in context — provided automatically for all `streamFn` streams.
+   *
+   * @example
+   * ```ts
+   * // In a streamFn handler:
+   * stream.pipe(
+   *   Stream.tap((event) =>
+   *     event._tag === "OperationProgress"
+   *       ? Command.updateProgress({ text: `${event.completed}/${event.total}`, percentage: event.completed / event.total * 100 })
+   *       : Effect.void
+   *   )
+   * )
+   * ```
+   */
+  updateProgress: (progress: Progress | undefined): Effect.Effect<void> =>
+    CommandProgress.use((s) => s.update(progress)),
+
   /** Version of @see confirmOrInterrupt that automatically includes the action name in the default messages */
   confirmOrInterrupt: Effect.fnUntraced(function*(
     message: string | undefined = undefined
@@ -2395,7 +2622,7 @@ export class CommanderImpl<RT, RTHooks> {
     id:
       | Id
       | { id: Id }
-      | StreamMutationTuple<Id, any, RunningA, RunningE, any>
+      | 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> & {
@@ -2403,8 +2630,8 @@ export class CommanderImpl<RT, RTHooks> {
   } => {
     // Resolve id and (optionally) per-build stream metadata.
     const resolvedId: Id = typeof id === "string" ? id : (id as { id: Id }).id
-    const isStreamFactory = typeof id === "function" && "id" in id && (id as any).length <= 1
-    const isStreamTuple = Array.isArray(id) && "id" in id
+    const factory = isStreamFactory(id)
+    const callable = !factory && isStreamCallable(id)
     const resolveStreamMeta = ():
       | {
         running?: ComputedRef<AsyncResult.AsyncResult<RunningA, RunningE>> | undefined
@@ -2412,13 +2639,13 @@ export class CommanderImpl<RT, RTHooks> {
       }
       | undefined =>
     {
-      if (isStreamTuple) {
-        const t = id as StreamMutationTuple<Id, any, RunningA, RunningE, any>
-        return { running: t.running, progress: t.progress }
+      if (factory) {
+        const c = id()
+        return { running: c.running, progress: c.progress }
       }
-      if (isStreamFactory) {
-        const t = id()
-        return { running: t.running, progress: t.progress }
+      if (callable) {
+        const c = id as StreamMutationCallable<Id, any, RunningA, RunningE, any>
+        return { running: c.running, progress: c.progress }
       }
       return undefined
     }
@@ -2454,7 +2681,322 @@ export class CommanderImpl<RT, RTHooks> {
     )
   }
 
+  /**
+   * Internal factory for stream-backed commands. Accepts a handler that returns a `Stream` directly.
+   * Services (`CommandContext`, `stateTag`) are provided to the stream via `Stream.provideServiceEffect`.
+   */
+  readonly makeStreamCommand = <
+    const Id extends string,
+    const State extends IntlRecord | undefined,
+    const I18nKey extends string = Id
+  >(
+    id_: Id | { id: Id },
+    options?: FnOptions<Id, I18nKey, State>,
+    errorDef?: Error
+  ) => {
+    const id = typeof id_ === "string" ? id_ : id_.id
+    const state = getStateValues(options)
+
+    return Object.assign(
+      <Arg, SA, SE, SR>(
+        handler: (arg: Arg, ctx: Commander.CommandContextLocal2<Id, I18nKey, State>) => Stream.Stream<SA, SE, SR>
+      ) => {
+        const limit = Error.stackTraceLimit
+        Error.stackTraceLimit = 2
+        const localErrorDef = new Error()
+        Error.stackTraceLimit = limit
+        if (!errorDef) {
+          errorDef = localErrorDef
+        }
+
+        const key = `Commander.Command.${id}.state` as const
+        const stateTag = Context.Service<typeof key, State>(key)
+
+        const makeContext_ = () => this.makeContext(id, { ...options, state: state?.value })
+        const initialContext = makeContext_()
+        const context = computed(() => makeContext_())
+        const action = computed(() => context.value.action)
+        const label = computed(() => context.value.label)
+
+        const currentState = Effect.sync(() => state.value)
+
+        // Reactive ref driven by the CommandProgress service — updated imperatively
+        // from inside the stream via `Command.mapProgress(fn)` or `Command.updateProgress(p)`.
+        const progressRef = ref<Progress | undefined>(undefined)
+        const commandProgressService = {
+          update: (p: Progress | undefined) =>
+            Effect.sync(() => {
+              progressRef.value = p
+            })
+        }
+
+        const streamErrorReporter = <A, E, R>(self: Stream.Stream<A, E, R>) =>
+          self.pipe(
+            Stream.tapCause(
+              Effect.fnUntraced(function*(cause) {
+                if (Cause.hasInterruptsOnly(cause)) {
+                  console.info(`Interrupted while trying to ${id}`)
+                  return
+                }
+
+                const fail = Cause.findErrorOption(cause)
+                if (Option.isSome(fail)) {
+                  const message = `Failure trying to ${id}`
+                  yield* reportMessage(message, {
+                    action: id,
+                    error: fail.value
+                  })
+                  return
+                }
+
+                const ctx = yield* CommandContext
+                const extra = {
+                  action: ctx.action,
+                  message: `Unexpected Error trying to ${id}`
+                }
+                yield* reportRuntimeError(cause, extra)
+              }, Effect.uninterruptible)
+            )
+          )
+
+        const theStreamHandler = (arg: Arg, ctx: Commander.CommandContextLocal2<Id, I18nKey, State>) =>
+          handler(arg, ctx).pipe(
+            streamErrorReporter,
+            Stream.provideService(CommandProgress, commandProgressService),
+            Stream.provideServiceEffect(stateTag, currentState),
+            Stream.provideServiceEffect(CommandContext, Effect.sync(() => makeContext_()))
+          )
+
+        const waitId = options?.waitKey ? options.waitKey(id) : undefined
+        const blockId = options?.blockKey ? options.blockKey(id) : undefined
+
+        const [result, exec_] = asStreamResult(theStreamHandler)
+
+        const exec = Effect
+          .fnUntraced(
+            function*(...args: [any, any]) {
+              if (waitId !== undefined) registerWait(waitId)
+              if (blockId !== undefined && blockId !== waitId) {
+                registerWait(blockId)
+              }
+              return yield* exec_(...args)
+            },
+            Effect.onExit(() =>
+              Effect.sync(() => {
+                if (waitId !== undefined) unregisterWait(waitId)
+                if (blockId !== undefined && blockId !== waitId) {
+                  unregisterWait(blockId)
+                }
+              })
+            )
+          )
+
+        const waiting = waitId !== undefined
+          ? computed(() => result.value.waiting || (waitState.value[waitId] ?? 0) > 0)
+          : computed(() => result.value.waiting)
+
+        const blocked = blockId !== undefined
+          ? computed(() => waiting.value || (waitState.value[blockId] ?? 0) > 0)
+          : computed(() => waiting.value)
+
+        const computeAllowed = options?.allowed
+        const allowed = computeAllowed ? computed(() => computeAllowed(id, state)) : true
+
+        const rt = Effect.context<RT | RTHooks>().pipe(Effect.provide(this.hooks)).pipe(Effect.runSyncWith(this.rt))
+        const runFork = Effect.runForkWith(rt)
+
+        const progress = progressRef
+
+        const handle = Object.assign((arg: Arg) => {
+          arg = toRaw(arg)
+          progressRef.value = undefined // reset progress on new invocation
+          const limit = Error.stackTraceLimit
+          Error.stackTraceLimit = 2
+          const errorCall = new Error()
+          Error.stackTraceLimit = limit
+
+          let cache: false | string = false
+          const captureStackTrace = () => {
+            if (cache !== false) {
+              return cache
+            }
+            if (errorCall.stack) {
+              const stackDef = errorDef!.stack!.trim().split("\n")
+              const stackCall = errorCall.stack.trim().split("\n")
+              let endStackDef = stackDef.slice(2).join("\n").trim()
+              if (!endStackDef.includes(`(`)) {
+                endStackDef = endStackDef.replace(/at (.*)/, "at ($1)")
+              }
+              let endStackCall = stackCall.slice(2).join("\n").trim()
+              if (!endStackCall.includes(`(`)) {
+                endStackCall = endStackCall.replace(/at (.*)/, "at ($1)")
+              }
+              cache = `${endStackDef}\n${endStackCall}`
+              return cache
+            }
+          }
+
+          const command = currentState.pipe(Effect.flatMap((state) => {
+            const rawArg = deepToRaw(arg)
+            const rawState = deepToRaw(state)
+            return Effect.withSpan(
+              exec(arg, { ...context.value, state } as any),
+              id,
+              {
+                captureStackTrace,
+                attributes: {
+                  input: rawArg,
+                  state: rawState,
+                  action: initialContext.action,
+                  label: initialContext.label,
+                  id: initialContext.id,
+                  i18nKey: initialContext.i18nKey
+                }
+              }
+            )
+          }))
+
+          return runFork(command as any)
+        }, { action, label })
+
+        return reactive({
+          id,
+          i18nKey: initialContext.i18nKey,
+          namespace: initialContext.namespace,
+          namespaced: initialContext.namespaced,
+          result,
+          /** always undefined for streamFn commands — `result` already exposes the live stream state */
+          running: undefined,
+          /** reactive – progress driven by `Command.mapProgress` or `Command.updateProgress` inside the stream */
+          progress,
+          waiting,
+          blocked,
+          allowed,
+          action,
+          label,
+          state,
+          handle
+        })
+      },
+      { id }
+    )
+  }
+
+  /**
+   * Define a stream-backed Command for handling user actions.
+   *
+   * Like `fn`, but the body generator (or function) must **return** a `Stream` rather than
+   * an `Effect`. The command's `waiting` state stays `true` while the stream is running and
+   * is set to `false` once it terminates. The reactive `result` ref is updated for every
+   * value emitted by the stream.
+   *
+   * Three handler shapes are accepted:
+   * 1. **Generator returning a Stream** (primary) — may yield Effects freely before returning the stream:
+   *    ```ts
+   *    Command.streamFn("exportData")(
+   *      function*(arg, ctx) {
+   *        const token = yield* getAuthToken
+   *        return Stream.fromEffect(startExport(token, arg.id)).pipe(
+   *          Stream.flatMap((job) => pollProgress(job.id))
+   *        )
+   *      }
+   *    )
+   *    ```
+   * 2. **Function returning a Stream directly**: `(arg, ctx) => Stream.make(1, 2, 3)`
+   * 3. **Function returning `Effect<Stream>`**: `(arg, ctx) => Effect.map(setup, (s) => s.stream)`
+   *
+   * @param id The internal identifier for the action (used for tracing and i18n lookup).
+   * @param options Same options as `fn` (`state`, `blockKey`, `waitKey`, `allowed`, `i18nCustomKey`).
+   *
+   * **Progress** — use `Command.mapProgress(fn)` as a stream pipe operator; the mapper receives
+   * `AsyncResult<A, E>` (each value wrapped as `AsyncResult.success(v, { waiting: true })`),
+   * matching the same shape as CommandButton’s `:progress-map` prop. Or call
+   * `Command.updateProgress(p)` for imperative control:
+   *
+   * ```ts
+   * // mapProgress as a combinator arg (outside the handler):
+   * Command.streamFn("exportData")(
+   *   function*(arg, ctx) { return makeExportStream(arg.id) },
+   *   (s) => s.pipe(Command.mapProgress((r) => AsyncResult.isSuccess(r) && r.value._tag === "OperationProgress" ? { text: `${r.value.completed}/${r.value.total}` } : undefined))
+   * )
+   *
+   * // Or inline inside the handler body:
+   * Command.streamFn("exportData")(function*(arg, ctx) {
+   *   return makeExportStream(arg.id).pipe(Command.mapProgress((r) => AsyncResult.isSuccess(r) ? ... : undefined))
+   * })
+   * ```
+   *
+   * **Pipeable combinators** — the 2nd–Nth args follow the same pattern as `fn`: each combinator
+   * receives `(stream, arg, ctx)` and returns a transformed stream:
+   * ```ts
+   * Command.streamFn("exportData")(
+   *   handler,
+   *   (s, arg, ctx) => s.pipe(Command.mapProgress(fn), Stream.take(100))
+   * )
+   * ```
+   *
+   * **Returned Properties**: `action`, `label`, `result`, `progress`, `waiting`, `blocked`,
+   * `allowed`, `handle`, `i18nKey`, `namespace`, `namespaced`.
+   */
+  streamFn = <
+    const Id extends string,
+    const State extends IntlRecord = IntlRecord,
+    const I18nKey extends string = Id
+  >(
+    id: Id | { id: Id },
+    options?: FnOptions<Id, I18nKey, State>
+  ):
+    & Commander.StreamGen<RT | RTHooks, Id, I18nKey, State>
+    & Commander.NonGenStream<RT | RTHooks, Id, I18nKey, State>
+    & {
+      state: Context.Service<`Commander.Command.${Id}.state`, State>
+    } =>
+  {
+    const resolvedId = typeof id === "string" ? id : id.id
+
+    type StreamOrEffect = Stream.Stream<any, any, any> | Effect.Effect<Stream.Stream<any, any, any>, any, any>
+
+    const toRawHandler = (fn: any): (arg: any, ctx: any) => StreamOrEffect => {
+      if (isGeneratorFunction(fn)) {
+        return Effect.fnUntraced(function*(arg: any, ctx: any) {
+          return yield* (fn as (arg: any, ctx: any) => Generator<any, Stream.Stream<any, any, any>, any>)(arg, ctx)
+        })
+      }
+      return fn
+    }
+
+    const toFinalStream = (value: StreamOrEffect): Stream.Stream<any, any, any> =>
+      Stream.isStream(value) ? value : Stream.unwrap(value as Effect.Effect<Stream.Stream<any, any, any>, any, any>)
+
+    return Object.assign(
+      (fn: any, ...combinators: Array<(s: any, arg: any, ctx: any) => any>): any => {
+        const limit = Error.stackTraceLimit
+        Error.stackTraceLimit = 2
+        const errorDef = new Error()
+        Error.stackTraceLimit = limit
+
+        const rawHandler = toRawHandler(fn)
+        const handler = (arg: any, ctx: any) => {
+          let current: any = rawHandler(arg, ctx)
+          for (const combinator of combinators) {
+            current = combinator(current, arg, ctx)
+          }
+          return toFinalStream(current)
+        }
+
+        return this.makeStreamCommand(id, options, errorDef)(handler)
+      },
+      makeBaseInfo(resolvedId, options),
+      {
+        state: Context.Service<`Commander.Command.${Id}.state`, State>(
+          `Commander.Command.${resolvedId}.state`
+        )
+      }
+    )
+  }
+
   /** @deprecated */
+
   alt2: <
     const Id extends string,
     MutArg,
@@ -2563,18 +3105,15 @@ export class CommanderImpl<RT, RTHooks> {
         id: Id
         mutateStream:
           | StreamMutationFactory<Id, Arg, A, E, R>
-          | StreamMutationTuple<Id, Arg, A, E, R>
+          | StreamMutationCallable<Id, Arg, A, E, R>
       }
-      | StreamMutationTuple<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> => {
     if (mutation !== null && typeof mutation === "object" && "mutateStream" in mutation) {
       return this.wrapStream(mutation as any, options) as any
     }
-    if (Array.isArray(mutation) && "id" in mutation) {
-      return this.wrapStream(mutation as any, options) as any
-    }
-    if (typeof mutation === "function" && "id" in mutation && (mutation as any).length <= 1) {
+    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 })
@@ -2655,19 +3194,22 @@ export class CommanderImpl<RT, RTHooks> {
         id: Id
         mutateStream:
           | StreamMutationFactory<Id, Arg, A, E, R>
-          | StreamMutationTuple<Id, Arg, A, E, R>
+          | StreamMutationCallable<Id, Arg, A, E, R>
       }
       | StreamMutationFactory<Id, Arg, A, E, R>
-      | StreamMutationTuple<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-called tuple.
-    const source: StreamMutationFactory<Id, Arg, A, E, R> | StreamMutationTuple<Id, Arg, A, E, R> =
+    // 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 resolveTuple = (): StreamMutationTuple<Id, Arg, A, E, R> => (typeof source === "function" ? source() : source)
+    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
@@ -2676,15 +3218,14 @@ export class CommanderImpl<RT, RTHooks> {
         const errorDef = new Error()
         Error.stackTraceLimit = limit
 
-        // Fresh per build: call the factory once per command instance so each
-        // wrap call gets its own ComputedRef + execute pair. `running`/`progress`
+        // 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 tuple = resolveTuple()
-        const [, executeRaw] = tuple
-        const mutate: (_arg: Arg) => Effect.Effect<any, never, R> = Effect.isEffect(executeRaw)
-          ? (_arg: Arg) => executeRaw
-          : executeRaw
-        const streamMeta = { running: tuple.running, progress: tuple.progress }
+        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(