@effect-app/vue 2.77.7 → 2.77.9

package/src/experimental/commander.ts

@@ -90,12 +90,31 @@ export const wrapEmit = <A, Event extends string>(
 (value: A) => new Promise<void>((resolve) => emit(event, value, resolve))
 
 export declare namespace Commander {
+  export type CommanderBase<RT, Id extends string, I18nKey extends string, State> =
+    & Commander.Gen<RT, Id, I18nKey>
+    & Commander.NonGen<RT, Id, I18nKey>
+    & Commander.CommandContextLocal<Id, I18nKey>
+    & {
+      state: Context.Tag<`Commander.Command.${Id}.state`, State>
+    }
+
+  export type CommanderFn<RT, Id extends string, I18nKey extends string, State> = CommanderBase<RT, Id, I18nKey, State>
+
+  export type CommanderWrap<RT, Id extends string, I18nCustomKey extends string, State, I extends any[], A, E, R> =
+    & CommandContextLocal<Id, I18nCustomKey>
+    & GenWrap<RT, Id, I18nCustomKey, I, A, E, R>
+    & NonGenWrap<RT, Id, I18nCustomKey, I, A, E, R>
+    & {
+      state: Context.Tag<`Commander.Command.${Id}.state`, State>
+    }
+
   export interface CommandContextLocal<Id extends string, I18nKey extends string> {
     id: Id
     i18nKey: I18nKey
     namespace: `action.${I18nKey}`
     namespaced: <K extends string>(k: K) => `action.${I18nKey}.${K}`
   }
+
   export interface CommandProps<A, E, Id extends string, I18nKey extends string>
     extends CommandContextLocal<Id, I18nKey>
   {
@@ -1538,6 +1557,11 @@ export class CommanderImpl<RT> {
    *
    * @param id The internal identifier for the action. Used as a tracing span and to lookup
    *                   the user-facing name via internationalization (`action.${id}`).
+   * @param options Optional configuration for internationalization and state.
+   * @param options.i18nCustomKey Custom i18n key to use instead of `id` (e.g., for grouping similar actions)
+   * @param options.state Optional reactive state object (or function returning one) that is
+   *                     made available to the command effects and can be used for i18n interpolation.
+   *                     The state is captured at the start of each command execution and remains stable throughout.
    * @returns A function that executes the command when called (e.g., directly in `@click` handlers).
    *          Built-in error reporting handles failures automatically.
    *
@@ -1549,6 +1573,8 @@ export class CommanderImpl<RT> {
    * - `result`: The command result state
    * - `waiting`: Boolean indicating if the command is in progress (shorthand for `result.waiting`)
    * - `handle`: Function to execute the command
+   * - `exec`: The raw Effect that will be executed when calling `handle` (for advanced use cases)
+   * - `i18nKey`, `namespace`, `namespaced`: Helpers for internationalization keys
    *
    * **User Feedback**: Use the `withDefaultToast` helper for status notifications, or render
    * the `result` inline for custom UI feedback.
@@ -1653,7 +1679,33 @@ export class CommanderImpl<RT> {
       handler: (...args: Args) => Effect.Effect<A, E, R>
     ) => Commander.CommandOut<Args, A, E, R, Id, I18nKey>)
 
-  /** @experimental */
+  /**
+   * Define a Command for handling user actions with built-in error reporting and state management.
+   *
+   * @param mutation The mutation function to take the identifier and initial handler from. Used as a tracing span and to lookup
+   *                   the user-facing name via internationalization (`action.${id}`).
+   * @param options Optional configuration for internationalization and state.
+   * @param options.i18nCustomKey Custom i18n key to use instead of `id` (e.g., for grouping similar actions)
+   * @param options.state Optional reactive state object (or function returning one) that is
+   *                     made available to the command effects and can be used for i18n interpolation.
+   *                     The state is captured at the start of each command execution and remains stable throughout.
+   * @returns A function that executes the command when called (e.g., directly in `@click` handlers).
+   *          Built-in error reporting handles failures automatically.
+   *
+   * **Effect Context**: Effects have access to the `CommandContext` service, which provides
+   * the user-facing action name.
+   *
+   * **Returned Properties**:
+   * - `action`: User-facing action name from intl messages (useful for button labels)
+   * - `result`: The command result state
+   * - `waiting`: Boolean indicating if the command is in progress (shorthand for `result.waiting`)
+   * - `handle`: Function to execute the command
+   * - `exec`: The raw Effect that will be executed when calling `handle` (for advanced use cases)
+   * - `i18nKey`, `namespace`, `namespaced`: Helpers for internationalization keys
+   *
+   * **User Feedback**: Use the `withDefaultToast` helper for status notifications, or render
+   * the `result` inline for custom UI feedback.
+   */
   wrap = <
     const Id extends string,
     Args extends Array<unknown>,
@@ -1667,31 +1719,36 @@ export class CommanderImpl<RT> {
       | { mutate: (...args: Args) => Effect.Effect<A, E, R>; id: Id }
       | ((...args: Args) => Effect.Effect<A, E, R>) & { id: Id },
     options?: FnOptions<I18nKey, State>
-  ):
-    & Commander.CommandContextLocal<Id, I18nKey>
-    & Commander.GenWrap<RT, Id, I18nKey, Args, A, E, R>
-    & Commander.NonGenWrap<RT, Id, I18nKey, Args, A, E, R> =>
-    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
-
-      const mutate = "mutate" in mutation ? mutation.mutate : mutation
-
-      return this.makeCommand(mutation.id, options, errorDef)(
-        Effect.fnUntraced(
-          // fnUntraced only supports generators as first arg, so we convert to generator if needed
-          isGeneratorFunction(mutate) ? mutate : function*(...args: Args) {
-            return yield* mutate(...args)
-          },
-          ...combinators as [any]
-        ) as any
-      )
-    }, makeBaseInfo(mutation.id, options))
+  ): Commander.CommanderWrap<RT, Id, I18nKey, State, Args, A, E, R> =>
+    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
+
+        const mutate = "mutate" in mutation ? mutation.mutate : mutation
+
+        return this.makeCommand(mutation.id, options, errorDef)(
+          Effect.fnUntraced(
+            // fnUntraced only supports generators as first arg, so we convert to generator if needed
+            isGeneratorFunction(mutate) ? mutate : function*(...args: Args) {
+              return yield* mutate(...args)
+            },
+            ...combinators as [any]
+          ) as any
+        )
+      },
+      makeBaseInfo(mutation.id, options),
+      {
+        state: Context.GenericTag<`Commander.Command.${Id}.state`, State>(
+          `Commander.Command.${mutation.id}.state`
+        )
+      }
+    )
 }
 
 // @effect-diagnostics-next-line missingEffectServiceDependency:off

package/src/makeClient.ts

@@ -27,6 +27,55 @@ const mapHandler = <A, E, R, I = void, A2 = A, E2 = E, R2 = R>(
   map: (self: Effect.Effect<A, E, R>, i: I) => Effect.Effect<A2, E2, R2>
 ) => Effect.isEffect(handler) ? map(handler, undefined as any) : (i: I) => map(handler(i), i)
 
+export interface MutationExtensions<RT, Id extends string, I extends any[], A, E, R> {
+  /** @see Command.wrap */
+  wrap: Commander.CommanderWrap<RT, Id, Id, undefined, I, A, E, R>
+  /** @see Command.fn */
+  fn: Commander.CommanderFn<RT, Id, Id, undefined>
+}
+
+/** my other doc */
+export interface MutationExtWithInput<
+  RT,
+  Id extends string,
+  I extends any[],
+  A,
+  E,
+  R
+> extends Commander.CommandContextLocal<Id, Id>, MutationExtensions<RT, Id, I, A, E, R> {
+  /**
+   * Call the endpoint with input
+   */
+  (i: I): Effect.Effect<A, E, R>
+}
+
+/** my other doc */
+export interface MutationExt<
+  RT,
+  Id extends string,
+  A,
+  E,
+  R
+> extends
+  Commander.CommandContextLocal<Id, Id>,
+  Commander.CommanderWrap<RT, Id, Id, undefined, [], A, E, R>,
+  MutationExtensions<RT, Id, [], A, E, R>,
+  Effect.Effect<A, E, R>
+{
+}
+
+export type MutationWithExtensions<RT, Req> =
+  & (Req extends RequestHandlerWithInput<infer _I, infer _A, infer _E, infer _R, infer _Request, infer Id>
+    ? Commander.CommandContextLocal<Id, Id>
+    : Req extends RequestHandler<infer _A, infer _E, infer _R, infer _Request, infer Id>
+      ? Commander.CommandContextLocal<Id, Id>
+    : never)
+  & (Req extends RequestHandlerWithInput<infer I, infer A, infer E, infer R, infer _Request, infer Id>
+    ? MutationExtWithInput<RT, Id, [I], A, E, R>
+    : Req extends RequestHandler<infer A, infer E, infer R, infer _Request, infer Id>
+      ? MutationExtWithInput<RT, Id, [], A, E, R>
+    : never)
+
 /**
  * Use this after handling an error yourself, still continueing on the Error track, but the error will not be reported.
  */
@@ -1155,14 +1204,12 @@ export const makeClient = <RT>(
     client: ClientFrom<M>
   ) => {
     const Command = useCommand()
-    const wrap_ = Command.wrap
-    const fn_ = Command.fn
     const mutation = useMutation()
     const mutations = Struct.keys(client).reduce(
       (acc, key) => {
         const mut = mutation(client[key] as any)
-        const fn = fn_(client[key].id)
-        const wrap = wrap_(mut)
+        const fn = Command.fn(client[key].id)
+        const wrap = Command.wrap(mut)
         ;(acc as any)[camelCase(key) + "Mutation"] = Object.assign(
           mut,
           { wrap, fn },
@@ -1171,51 +1218,10 @@ export const makeClient = <RT>(
         return acc
       },
       {} as {
-        [Key in keyof typeof client as `${ToCamel<string & Key>}Mutation`]:
-          & (typeof client[Key] extends
-            RequestHandlerWithInput<infer I, infer A, infer E, infer R, infer Request, infer Id> ?
-              & ReturnType<typeof mutation<I, E, A, R, Request, Id>>
-              & (typeof client[Key] extends
-                RequestHandlerWithInput<infer _I, infer _A, infer _E, infer _R, infer _Request, infer Id>
-                ? Commander.CommandContextLocal<Id, Id>
-                : typeof client[Key] extends RequestHandler<infer _A, infer _E, infer _R, infer _Request, infer Id>
-                  ? Commander.CommandContextLocal<Id, Id>
-                : never)
-            : typeof client[Key] extends RequestHandler<infer A, infer E, infer R, infer Request, infer Id> ?
-                & ReturnType<typeof mutation<E, A, R, Request, Id>>
-                & (typeof client[Key] extends
-                  RequestHandlerWithInput<infer _I, infer _A, infer _E, infer _R, infer _Request, infer Id>
-                  ? Commander.CommandContextLocal<Id, Id>
-                  : typeof client[Key] extends RequestHandler<infer _A, infer _E, infer _R, infer _Request, infer Id>
-                    ? Commander.CommandContextLocal<Id, Id>
-                  : never)
-            : never)
-          & (typeof client[Key] extends
-            RequestHandlerWithInput<infer _I, infer _A, infer _E, infer _R, infer _Request, infer Id>
-            ? Commander.CommandContextLocal<Id, Id>
-            : typeof client[Key] extends RequestHandler<infer _A, infer _E, infer _R, infer _Request, infer Id>
-              ? Commander.CommandContextLocal<Id, Id>
-            : never)
-          & (typeof client[Key] extends
-            RequestHandlerWithInput<infer I, infer A, infer E, infer R, infer Request, infer Id>
-            ? ReturnType<typeof mutation<I, E, A, R, Request, Id>>
-            : typeof client[Key] extends RequestHandler<infer A, infer E, infer R, infer Request, infer Id>
-              ? ReturnType<typeof mutation<E, A, R, Request, Id>>
-            : never)
-          & {
-            wrap: typeof client[Key] extends
-              RequestHandlerWithInput<infer I, infer A, infer E, infer _R, infer _Request, infer Id>
-              ? ReturnType<typeof wrap_<Id, [I], A, E, never>> & Commander.CommandContextLocal<Id, Id>
-              : typeof client[Key] extends RequestHandler<infer A, infer E, infer _R, infer _Request, infer Id>
-                ? ReturnType<typeof wrap_<Id, [], A, E, never>> & Commander.CommandContextLocal<Id, Id>
-              : never
-            fn: typeof client[Key] extends
-              RequestHandlerWithInput<infer _I, infer _A, infer _E, infer _R, infer _Request, infer Id>
-              ? ReturnType<typeof fn_<Id>> & Commander.CommandContextLocal<Id, Id>
-              : typeof client[Key] extends RequestHandler<infer _A, infer _E, infer _R, infer _Request, infer Id>
-                ? ReturnType<typeof fn_<Id>> & Commander.CommandContextLocal<Id, Id>
-              : never
-          }
+        [Key in keyof typeof client as `${ToCamel<string & Key>}Mutation`]: MutationWithExtensions<
+          RT,
+          typeof client[Key]
+        >
       }
     )
     return mutations
@@ -1231,12 +1237,10 @@ export const makeClient = <RT>(
   ) => {
     const Command = useCommand()
     const mutation = useMutation()
-    const wrap = Command.wrap
-    const fn_ = Command.fn
     const invalidation = queryInvalidation?.(client)
     const extended = Struct.keys(client).reduce(
       (acc, key) => {
-        const fn = fn_(client[key].id)
+        const fn = Command.fn(client[key].id)
         const awesome = {
           ...client[key],
           ...fn,
@@ -1247,44 +1251,12 @@ export const makeClient = <RT>(
           client[key] as any,
           invalidation?.[key] ? { queryInvalidation: invalidation[key] } : undefined
         )
-        ;(acc as any)[key] = Object.assign(mutate, { wrap: wrap({ mutate, id: awesome.id }), fn }, awesome, fn)
+        ;(acc as any)[key] = Object.assign(mutate, { wrap: Command.wrap({ mutate, id: awesome.id }), fn }, awesome, fn)
         return acc
       },
       {} as {
         [Key in keyof typeof client]:
-          & (typeof client[Key] extends
-            RequestHandlerWithInput<infer _I, infer _A, infer _E, infer _R, infer _Request, infer Id>
-            ? Commander.CommandContextLocal<Id, Id>
-            : typeof client[Key] extends RequestHandler<infer _A, infer _E, infer _R, infer _Request, infer Id>
-              ? Commander.CommandContextLocal<Id, Id>
-            : never)
-          & (typeof client[Key] extends
-            RequestHandlerWithInput<infer _I, infer _A, infer _E, infer _R, infer _Request, infer Id>
-            ? Commander.CommandContextLocal<Id, Id>
-            : typeof client[Key] extends RequestHandler<infer _A, infer _E, infer _R, infer _Request, infer Id>
-              ? Commander.CommandContextLocal<Id, Id>
-            : never)
-          & (typeof client[Key] extends
-            RequestHandlerWithInput<infer I, infer A, infer E, infer R, infer Request, infer Id>
-            ? ReturnType<typeof mutation<I, E, A, R, Request, Id>>
-            : typeof client[Key] extends RequestHandler<infer A, infer E, infer R, infer Request, infer Id>
-              ? ReturnType<typeof mutation<E, A, R, Request, Id>>
-            : never)
-          & {
-            wrap: typeof client[Key] extends
-              RequestHandlerWithInput<infer I, infer A, infer E, infer _R, infer _Request, infer Id>
-              ? ReturnType<typeof wrap<Id, [I], A, E, never>> & Commander.CommandContextLocal<Id, Id>
-              : typeof client[Key] extends RequestHandler<infer A, infer E, infer _R, infer _Request, infer Id>
-                ? ReturnType<typeof wrap<Id, [], A, E, never>> & Commander.CommandContextLocal<Id, Id>
-              : never
-            fn: typeof client[Key] extends
-              RequestHandlerWithInput<infer _I, infer _A, infer _E, infer _R, infer _Request, infer Id>
-              ? ReturnType<typeof fn_<Id>> & Commander.CommandContextLocal<Id, Id>
-              : typeof client[Key] extends RequestHandler<infer _A, infer _E, infer _R, infer _Request, infer Id>
-                ? ReturnType<typeof fn_<Id>> & Commander.CommandContextLocal<Id, Id>
-              : never
-          }
-          & typeof client[Key]
+          & MutationWithExtensions<RT, typeof client[Key]>
           & {
             query: typeof client[Key] extends
               RequestHandlerWithInput<infer I, infer A, infer E, infer _R, infer Request, infer Id>