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

package/src/commander.ts

@@ -12,6 +12,7 @@ import { type FormatXMLElementFn, type PrimitiveType } from "intl-messageformat"
 import { computed, type ComputedRef, reactive, ref, toRaw } from "vue"
 import { Confirm } from "./confirm.js"
 import { I18n } from "./intl.js"
+import { CurrentToastId, Toast } from "./toast.js"
 import { WithToast } from "./withToast.js"
 
 type IntlRecord = Record<string, PrimitiveType | FormatXMLElementFn<string, string>>
@@ -33,7 +34,7 @@ export type StreamMutationCallOptions<A, E> = {
 }
 
 /**
- * The result of invoking a `mutateStream` factory: the `execute` function (or
+ * The result of invoking a `mutateToResult` 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
@@ -217,7 +218,7 @@ export declare namespace Commander {
     /** reactive */
     result: AsyncResult.AsyncResult<A, E>
     /**
-     * reactive – set when the command wraps a stream (`wrapStream` / `wrap` with `mutateStream`)
+     * reactive – set when the command wraps a stream (`wrapStream` / `wrap` with `mutateToResult`)
      * or when the `progress` option is provided to `fn`.
      * Reflects the live AsyncResult of the underlying stream.
      */
@@ -2197,6 +2198,167 @@ export const CommanderStatic = {
       )
     }),
 
+  /**
+   * Stream-aware version of `withDefaultToast`. Use this as a combinator inside `streamFn`
+   * (or anywhere a `Stream` needs toast lifecycle handling) instead of `withDefaultToast`.
+   *
+   * Unlike `withDefaultToast` (which only wraps the initial `Effect`), this combinator:
+   * - Shows the "waiting" toast **before** the stream starts
+   * - Shows the "success" toast only **after** the stream drains fully without error
+   * - Shows the "failure" toast if the stream errors or fails
+   *
+   * Accepts either a `Stream<A, E, R>` or an `Effect<Stream<A, E, R>, EE, ER>` as input,
+   * so it works in both the `NonGenStream` and `StreamGen` overloads of `streamFn`.
+   *
+   * @example
+   * ```ts
+   * Command.streamFn("exportData")(
+   *   function*(arg, ctx) { return makeExportStream(arg.id) },
+   *   Command.withDefaultToastStream()
+   * )
+   * ```
+   */
+  withDefaultToastStream: <A, E, R, Args extends Array<unknown>>(
+    options?: {
+      stableToastId?:
+        | undefined
+        | true
+        | string
+        | ((id: string, arg: NoInfer<Args>[0], ctx: NoInfer<Args>[1]) => true | string | undefined)
+      errorRenderer?: (e: E, action: string, arg: NoInfer<Args>[0], ctx: NoInfer<Args>[1]) => string | undefined
+      showSpanInfo?: false
+      onWaiting?:
+        | null
+        | undefined
+        | string
+        | ((id: string, arg: NoInfer<Args>[0], ctx: NoInfer<Args>[1]) => string | null | undefined)
+      onSuccess?:
+        | null
+        | undefined
+        | string
+        | ((a: A, action: string, arg: NoInfer<Args>[0], ctx: NoInfer<Args>[1]) => string | null | undefined)
+    }
+  ) =>
+  (
+    self: Stream.Stream<A, E, R> | Effect.Effect<Stream.Stream<A, E, R>, any, any>,
+    ...args: Args
+  ): Stream.Stream<A, E, R | I18n | Toast | CommandContext> => {
+    const rawStream: Stream.Stream<A, E, R> = Stream.isStream(self)
+      ? self
+      : Stream.unwrap(self)
+
+    return Stream.unwrap(Effect.gen(function*() {
+      const cc = yield* CommandContext
+      const { intl } = yield* I18n
+      const toast = yield* Toast
+
+      const customWaiting = cc.namespaced("waiting")
+      const hasCustomWaiting = !!intl.messages[customWaiting]
+      const customSuccess = cc.namespaced("success")
+      const hasCustomSuccess = !!intl.messages[customSuccess]
+      const customFailure = cc.namespaced("failure")
+      const hasCustomFailure = !!intl.messages[customFailure]
+
+      const stableToastId: string | undefined = options?.stableToastId
+        ? typeof options.stableToastId === "string"
+          ? options.stableToastId
+          : typeof options.stableToastId === "boolean"
+          ? cc.id
+          : typeof options.stableToastId === "function"
+          ? (() => {
+            const r = (options.stableToastId as (...a: any[]) => true | string | undefined)(cc.id, ...args)
+            if (typeof r === "string") return r
+            if (r === true) return cc.id
+            return undefined
+          })()
+          : undefined
+        : undefined
+
+      const baseTimeout = 3_000
+
+      const waitingMsg: string | null = options?.onWaiting === null
+        ? null
+        : typeof options?.onWaiting === "string"
+        ? options.onWaiting
+        : typeof options?.onWaiting === "function"
+        ? (options.onWaiting as (...a: any[]) => string | null | undefined)(cc.id, ...args) ?? null
+        : hasCustomWaiting
+        ? intl.formatMessage({ id: customWaiting }, cc.state)
+        : intl.formatMessage({ id: "handle.waiting" }, { action: cc.action })
+
+      const toastId: string | number | undefined = waitingMsg === null
+        ? stableToastId
+        : yield* toast.info(waitingMsg, { id: stableToastId ?? null })
+
+      const failureHandler = defaultFailureMessageHandler<E, [], never, never>(
+        hasCustomFailure ? intl.formatMessage({ id: customFailure }, cc.state) : cc.action,
+        options?.errorRenderer as ErrorRenderer<E, []> | undefined
+      )
+
+      let lastValue: A | undefined = undefined
+      let didFail = false
+
+      const composed = rawStream.pipe(
+        Stream.tap((v) =>
+          Effect.sync(() => {
+            lastValue = v
+          })
+        ),
+        Stream.tapCause(Effect.fnUntraced(function*(cause) {
+          didFail = true
+          if (Cause.hasInterruptsOnly(cause)) {
+            if (toastId !== undefined) yield* toast.dismiss(toastId)
+            return
+          }
+
+          const spanInfo = options?.showSpanInfo !== false
+            ? yield* Effect.currentSpan.pipe(
+              Effect.map((span) => `\nTrace: ${span.traceId}\nSpan: ${span.spanId}`),
+              Effect.orElseSucceed(() => "")
+            )
+            : ""
+
+          const t = yield* failureHandler(Cause.findErrorOption(cause))
+          const opts = { timeout: baseTimeout * 2 }
+
+          if (typeof t === "object") {
+            const message = t.message + spanInfo
+            yield* t.level === "warn"
+              ? toast.warning(message, toastId !== undefined ? { ...opts, id: toastId } : opts)
+              : toast.error(message, toastId !== undefined ? { ...opts, id: toastId } : opts)
+          } else {
+            yield* toast.error(t + spanInfo, toastId !== undefined ? { ...opts, id: toastId } : opts)
+          }
+        }, Effect.uninterruptible)),
+        Stream.ensuring(Effect.suspend(() => {
+          if (didFail) return Effect.void
+
+          if (options?.onSuccess === null) return Effect.void
+
+          const successMsg: string | null = typeof options?.onSuccess === "string"
+            ? options.onSuccess
+            : typeof options?.onSuccess === "function"
+            ? (options.onSuccess as (...a: any[]) => string | null | undefined)(lastValue, cc.action, ...args) ?? null
+            : hasCustomSuccess
+            ? intl.formatMessage({ id: customSuccess }, cc.state)
+            : intl.formatMessage({ id: "handle.success" }, { action: cc.action })
+              + (S.is(OperationSuccess)(lastValue) && lastValue.message ? "\n" + lastValue.message : "")
+
+          if (successMsg === null) return Effect.void
+
+          return toast.success(
+            successMsg,
+            toastId !== undefined ? { id: toastId, timeout: baseTimeout } : { timeout: baseTimeout }
+          )
+        }))
+      )
+
+      return (toastId !== undefined
+        ? composed.pipe(Stream.provideService(CurrentToastId, CurrentToastId.of({ toastId })))
+        : composed) as unknown as Stream.Stream<A, E, R>
+    }))
+  },
+
   /** borrowing the idea from Families in Effect Atom */
   family: <T extends object, Arg, ArgIn = Arg>(
     maker: (arg: Arg) => T,
@@ -3103,14 +3265,14 @@ export class CommanderImpl<RT, RTHooks> {
       | StreamMutationFactory<Id, Arg, A, E, R>
       | {
         id: Id
-        mutateStream:
+        mutateToResult:
           | 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> => {
-    if (mutation !== null && typeof mutation === "object" && "mutateStream" in mutation) {
+    if (mutation !== null && typeof mutation === "object" && "mutateToResult" in mutation) {
       return this.wrapStream(mutation as any, options) as any
     }
     if (isStreamCallable(mutation) || isStreamFactory(mutation)) {
@@ -3153,18 +3315,18 @@ export class CommanderImpl<RT, RTHooks> {
   }
 
   /**
-   * Define a Command from a stream-type mutation (`mutateStream` factory).
+   * Define a Command from a stream-type mutation (`mutateToResult` 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
+   * (the `mutateToResult` 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 object with `id` and `mutateToResult` factory (e.g. a client entry)
+   * - The `mutateToResult` factory directly (callable, with `id`)
    * - An already-called factory result (`[resultRef, execute] & { id }`) — shared ref across builds
    *
    * @example
@@ -3173,10 +3335,10 @@ export class CommanderImpl<RT, RTHooks> {
    * const exportCmd = Command.wrapStream(client.myExport)()
    *
    * // Via factory directly:
-   * const exportCmd = Command.wrapStream(client.myExport.mutateStream)()
+   * const exportCmd = Command.wrapStream(client.myExport.mutateToResult)()
    *
    * // Via already-called factory (shared ref):
-   * const stream = client.myExport.mutateStream()
+   * const stream = client.myExport.mutateToResult()
    * const exportCmd = Command.wrapStream(stream)()
    * ```
    */
@@ -3192,7 +3354,7 @@ export class CommanderImpl<RT, RTHooks> {
     mutation:
       | {
         id: Id
-        mutateStream:
+        mutateToResult:
           | StreamMutationFactory<Id, Arg, A, E, R>
           | StreamMutationCallable<Id, Arg, A, E, R>
       }
@@ -3203,8 +3365,8 @@ export class CommanderImpl<RT, RTHooks> {
     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 !== null && typeof mutation === "object" && "mutateToResult" in mutation
+        ? (mutation.mutateToResult as any)
         : (mutation as any)
     const resolveCallable = (): StreamMutationCallable<Id, Arg, A, E, R> =>
       (isStreamFactory(source)

package/src/makeClient.ts

@@ -228,7 +228,7 @@ export type MutationWithExtensions<RT, Req> = Req extends
   : never
 
 /**
- * Options for invoking a `mutateStream` factory. Supplying `progress` produces
+ * Options for invoking a `mutateToResult` 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`
@@ -239,7 +239,7 @@ export type MutateStreamCallOptions<A, E> = {
 }
 
 /**
- * The `mutateStream` factory for a stream-type request handler. Always invoke
+ * The `mutateToResult` 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
@@ -306,18 +306,18 @@ export type StreamFnStreamExtension<RT, Req> = Req extends
   : never
 
 /**
- * `mutateStream2` factory — like `mutateStream` but returns `Effect<Stream>` per invocation
- * for use with `streamFn` combinators. Handles invalidation via `Stream.ensuring`.
+ * `mutate` factory — like `mutateToResult` but wraps per-invocation invalidation scaffolding
+ * into the stream itself (via `Stream.unwrap`) for use with `streamFn` combinators.
  */
 export type StreamMutation2WithExtensions<RT, Req> = Req extends
   RequestStreamHandlerWithInput<infer I, infer A, infer E, infer R, infer _Request, infer Id, infer _Final> ?
-    & ((input: I) => Effect.Effect<Stream.Stream<A, E, R>>)
+    & ((input: I) => Stream.Stream<A, E, R>)
     & {
       readonly id: Id
       readonly wrapStream: Commander.StreamGen<RT, Id, Id, undefined> & Commander.NonGenStream<RT, Id, Id, undefined>
     }
   : Req extends RequestStreamHandler<infer A, infer E, infer R, infer _Request, infer Id, infer _Final> ?
-      & Effect.Effect<Stream.Stream<A, E, R>>
+      & Stream.Stream<A, E, R>
       & {
         readonly id: Id
         readonly wrapStream: Commander.StreamGen<RT, Id, Id, undefined> & Commander.NonGenStream<RT, Id, Id, undefined>
@@ -1043,11 +1043,11 @@ export const makeClient = <RT_, RTHooks>(
                 ...client[key],
                 request: h_,
                 streamQuery: useStreamQuery(client[key] as any),
-                mutateStream: streamMutFactory,
+                mutateToResult: streamMutFactory,
                 wrapStream: Command.wrapStream(streamMutFactory),
                 fn: Command.fn(client[key].id),
                 streamFn: useCommand().streamFn(client[key].id as any) as any,
-                mutateStream2: (() => {
+                mutate: (() => {
                   const sm2Act = useStreamMutation2()(client[key] as any, mergedInvalidation)
                   const originalHandler = (client[key] as any).handler
                   const sm2Handler = Stream.isStream(originalHandler)
@@ -1125,11 +1125,11 @@ export const makeClient = <RT_, RTHooks>(
             : { mutate: MutationWithExtensions<RT | RTHooks, CommandHandler<typeof client[Key]>> })
           & (StreamHandler<typeof client[Key]> extends never ? {}
             : {
-              mutateStream: StreamMutationWithExtensions<StreamHandler<typeof client[Key]>>
+              mutateToResult: StreamMutationWithExtensions<StreamHandler<typeof client[Key]>>
               wrapStream: StreamCommandWithExtensions<RT | RTHooks, StreamHandler<typeof client[Key]>>
               fn: StreamFnExtension<RT | RTHooks, StreamHandler<typeof client[Key]>>
               streamFn: StreamFnStreamExtension<RT | RTHooks, StreamHandler<typeof client[Key]>>
-              mutateStream2: StreamMutation2WithExtensions<RT | RTHooks, StreamHandler<typeof client[Key]>>
+              mutate: StreamMutation2WithExtensions<RT | RTHooks, StreamHandler<typeof client[Key]>>
             })
           & { Input: typeof client[Key] extends RequestHandlerWithInput<infer I, any, any, any, any, any> ? I : never }
       }
@@ -1223,7 +1223,7 @@ export type ToCamel<S extends string | number | symbol> = S extends string
   : Uncapitalize<S>
   : never
 
-export interface CommandBase<I = void, A = void> {
+export interface CommandBase<I = void, A = void, RA = unknown, RE = unknown> {
   handle: (input: I) => A
   waiting: boolean
   blocked: boolean
@@ -1233,10 +1233,10 @@ export interface CommandBase<I = void, A = void> {
   /** formatted progress info for current `running` state, when `progress` was supplied */
   progress?: Progress | undefined
   /** reactive result state, available on stream-backed commands */
-  result?: AsyncResult.AsyncResult<any, any>
+  result?: AsyncResult.AsyncResult<RA, RE>
 }
 
-export interface EffectCommand<I = void, A = unknown, E = unknown> extends CommandBase<I, Fiber<A, E>> {}
+export interface EffectCommand<I = void, A = unknown, E = unknown> extends CommandBase<I, Fiber<A, E>, A, E> {}
 
 export interface CommandFromRequest<I extends { readonly make: (...args: any[]) => any }, A = unknown, E = unknown>
   extends EffectCommand<RequestInputFromMake<I>, A, E>

package/src/mutate.ts

@@ -418,7 +418,7 @@ export const useMakeMutation = () => {
  * `[ref, execute]` tuple. The outer Effect sets up per-invocation invalidation scaffolding
  * and returns a stream that triggers query invalidation via `Stream.ensuring` when it completes.
  *
- * Use this with `streamFn` / `Command.streamFn(id)(mutateStream2Handler, ...combinators)` so that
+ * Use this with `streamFn` / `Command.streamFn(id)(mutateHandler, ...combinators)` so that
  * the command manages its own reactive state internally. Unlike `makeStreamMutation`, no external
  * reactive result ref is created.
  *
@@ -457,8 +457,8 @@ export const makeStreamMutation2 = () => {
 
     const handler = self.handler
     const act = Stream.isStream(handler)
-      ? makeInvocationEffect(undefined, handler)
-      : (i: any) => makeInvocationEffect(i, (handler as (i: any) => Stream.Stream<any, any, any>)(i))
+      ? Stream.unwrap(makeInvocationEffect(undefined, handler))
+      : (i: any) => Stream.unwrap(makeInvocationEffect(i, (handler as (i: any) => Stream.Stream<any, any, any>)(i)))
 
     return act
   }

package/test/dist/stubs.d.ts

@@ -2968,7 +2968,7 @@ export declare const useClient: (options?: {
         readonly type: "command" | "query" | "stream";
         readonly "~decodingServices"?: unknown;
     }, infer Id_3 extends string, infer Final_1> ? Request_3["type"] extends "stream" ? import("effect-app/client").RequestStreamHandler<A_3, E_3, R_4, Request_3, Id_3, Final_1> : never : never : never : never) extends never ? {} : {
-        mutateStream: import("../src/makeClient.js").StreamMutationWithExtensions<import("effect-app/client").RequestHandlers<never, never, M, import("effect-app/client").ExtractModuleName<M>>[Key] extends infer T_2 ? T_2 extends import("effect-app/client").RequestHandlers<never, never, M, import("effect-app/client").ExtractModuleName<M>>[Key] ? T_2 extends import("effect-app/client").RequestStreamHandlerWithInput<infer I_2, infer A_2, infer E_2, infer R_3, infer Request_2 extends S.Top & {
+        mutateToResult: import("../src/makeClient.js").StreamMutationWithExtensions<import("effect-app/client").RequestHandlers<never, never, M, import("effect-app/client").ExtractModuleName<M>>[Key] extends infer T_2 ? T_2 extends import("effect-app/client").RequestHandlers<never, never, M, import("effect-app/client").ExtractModuleName<M>>[Key] ? T_2 extends import("effect-app/client").RequestStreamHandlerWithInput<infer I_2, infer A_2, infer E_2, infer R_3, infer Request_2 extends S.Top & {
             readonly make: (...args: any[]) => any;
             _tag: string;
             fields: S.Struct.Fields;
@@ -3068,7 +3068,7 @@ export declare const useClient: (options?: {
             readonly type: "command" | "query" | "stream";
             readonly "~decodingServices"?: unknown;
         }, infer Id_3 extends string, infer Final_1> ? Request_3["type"] extends "stream" ? import("effect-app/client").RequestStreamHandler<A_3, E_3, R_4, Request_3, Id_3, Final_1> : never : never : never : never>;
-        mutateStream2: import("../src/makeClient.js").StreamMutation2WithExtensions<WithToast | (ApiClientFactory | Commander | (I18n | Toast.Toast)), import("effect-app/client").RequestHandlers<never, never, M, import("effect-app/client").ExtractModuleName<M>>[Key] extends infer T_2 ? T_2 extends import("effect-app/client").RequestHandlers<never, never, M, import("effect-app/client").ExtractModuleName<M>>[Key] ? T_2 extends import("effect-app/client").RequestStreamHandlerWithInput<infer I_2, infer A_2, infer E_2, infer R_3, infer Request_2 extends S.Top & {
+        mutate: import("../src/makeClient.js").StreamMutation2WithExtensions<WithToast | (ApiClientFactory | Commander | (I18n | Toast.Toast)), import("effect-app/client").RequestHandlers<never, never, M, import("effect-app/client").ExtractModuleName<M>>[Key] extends infer T_2 ? T_2 extends import("effect-app/client").RequestHandlers<never, never, M, import("effect-app/client").ExtractModuleName<M>>[Key] ? T_2 extends import("effect-app/client").RequestStreamHandlerWithInput<infer I_2, infer A_2, infer E_2, infer R_3, infer Request_2 extends S.Top & {
             readonly make: (...args: any[]) => any;
             _tag: string;
             fields: S.Struct.Fields;

package/test/makeClient.test.ts

@@ -278,8 +278,8 @@ it.skip("stream final type tests", () => {
   const { clientFor } = useClient()
   const client = clientFor(Something, undefined, somethingInvalidationResources)
 
-  const execNoFinal = client.StreamWithoutFinal.mutateStream()
-  const execWithFinal = client.StreamWithFinal.mutateStream()
+  const execNoFinal = client.StreamWithoutFinal.mutateToResult()
+  const execWithFinal = client.StreamWithFinal.mutateToResult()
 
   // Without `final`: execute input is {id: string} and resolves with void
   const _execNoFinalResult: ReturnType<typeof execNoFinal> = execNoFinal({ id: "test" })

package/test/streamFinal.test.ts

@@ -3,7 +3,7 @@
  *
  * The `final` option on a stream request schema lets callers model which type
  * the last emitted stream element is.  When present, the execute effect returned
- * by `mutateStream` resolves with that final value instead of `void`.
+ * by `mutateToResult` resolves with that final value instead of `void`.
  */
 import { expect, it } from "@effect/vitest"
 import { Effect, S } from "effect-app"
@@ -40,14 +40,14 @@ it.live("asStreamResult returns void and updates ref with each element", () =>
   }))
 
 // ---------------------------------------------------------------------------
-// mutateStream with no `final` — execute resolves with void (type-level)
+// mutateToResult with no `final` — execute resolves with void (type-level)
 // ---------------------------------------------------------------------------
 
-it.skip("mutateStream without final: execute resolves void (type-level)", () => {
+it.skip("mutateToResult without final: execute resolves void (type-level)", () => {
   const { clientFor } = useClient()
   const client = clientFor(Something, undefined, somethingInvalidationResources)
 
-  const execute = client.StreamWithoutFinal.mutateStream()
+  const execute = client.StreamWithoutFinal.mutateToResult()
 
   // execute returns void — assigning to ExportComplete Effect should fail
   const result = execute({ id: "test" })
@@ -57,14 +57,14 @@ it.skip("mutateStream without final: execute resolves void (type-level)", () =>
 })
 
 // ---------------------------------------------------------------------------
-// mutateStream with `final` — execute resolves with Final type (type-level)
+// mutateToResult with `final` — execute resolves with Final type (type-level)
 // ---------------------------------------------------------------------------
 
-it.skip("mutateStream with final: execute resolves with ExportComplete (type-level)", () => {
+it.skip("mutateToResult with final: execute resolves with ExportComplete (type-level)", () => {
   const { clientFor } = useClient()
   const client = clientFor(Something, undefined, somethingInvalidationResources)
 
-  const execute = client.StreamWithFinal.mutateStream()
+  const execute = client.StreamWithFinal.mutateToResult()
 
   // execute returns ExportComplete — assignment should compile cleanly
   const result = execute({ id: "test" })