@effect-app/vue 4.0.0-beta.24 → 4.0.0-beta.241

package/src/{experimental/makeUseCommand.ts → makeUseCommand.ts}

@@ -1,26 +1,29 @@
-import { Effect, type Layer } from "effect-app"
+import * as Effect from "effect-app/Effect"
+import type * as Layer from "effect-app/Layer"
 import { Commander, type CommanderImpl, CommanderStatic } from "./commander.js"
 
 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" | "streamWrap" | "streamFn" | "alt" | "alt2">
 {
 }
 
 export const makeUseCommand = Effect.fnUntraced(
   function*<R = never, RTHooks = never>(rtHooks: Layer.Layer<RTHooks, never, R>) {
     const cmndr = yield* Commander
-    const runtime = yield* Effect.services<R>()
+    const runtime = yield* Effect.context<R>()
 
     const comm = cmndr(runtime, rtHooks)
 
-    const command = {
+    const command: CommanderResolved<R, RTHooks> = {
       ...comm,
       ...CommanderStatic
     }
 
-    return command as CommanderResolved<R, RTHooks>
+    return command
   }
 )

package/src/mutate.ts

@@ -1,23 +1,57 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
+import { matchQuery } from "@tanstack/query-core"
 import { type InvalidateOptions, type InvalidateQueryFilters, type QueryClient, useQueryClient } from "@tanstack/vue-query"
-import { type Cause, Effect, type Exit, Option } from "effect-app"
-import { type Req } from "effect-app/client"
-import type { ClientForOptions, RequestHandler, RequestHandlerWithInput } from "effect-app/client/clientFor"
+import { type InvalidationKey, InvalidationKeysFromServer, makeInvalidationKeysService, makeQueryKey, type Req } from "effect-app/client"
+import type { ClientForOptions, RequestHandlerWithInput } from "effect-app/client/clientFor"
+import * as Effect from "effect-app/Effect"
 import { tuple } from "effect-app/Function"
+import * as Option from "effect-app/Option"
+import type * as Cause from "effect/Cause"
+import * as Exit from "effect/Exit"
+import * as Ref from "effect/Ref"
+import * as Stream from "effect/Stream"
 import * as AsyncResult from "effect/unstable/reactivity/AsyncResult"
 import { computed, type ComputedRef, shallowRef } from "vue"
-import { makeQueryKey } from "./lib.js"
 
-export const getQueryKey = (h: { id: string; options?: ClientForOptions }) => {
+export type GetQueryKey = (h: { id: string; options?: ClientForOptions }) => string[]
+
+/**
+ * Default heuristic: invalidate the parent namespace of the action.
+ * e.g. `$project/$configuration.get` -> `["$project"]`
+ * e.g. `$project/$configuration/$something.get` -> `["$project","$configuration"]`
+ */
+export const defaultGetQueryKey: GetQueryKey = (h) => {
   const key = makeQueryKey(h)
   const ns = key.filter((_) => _.startsWith("$"))
-  // we invalidate the parent namespace e.g $project/$configuration.get, we invalidate $project
-  // for $project/$configuration/$something.get, we invalidate $project/$configuration
   const k = ns.length ? ns.length > 1 ? ns.slice(0, ns.length - 1) : ns : undefined
   if (!k) throw new Error("empty query key for: " + h.id)
   return k
 }
 
+let activeGetQueryKey: GetQueryKey = defaultGetQueryKey
+
+/**
+ * Override the default query-key heuristic used by mutations for cache
+ * invalidation. Call once at app bootstrap. Pass `undefined` to restore the
+ * built-in default.
+ *
+ * @example
+ * ```ts
+ * // invalidate the full namespace of the action (no parent collapse)
+ * setDefaultGetQueryKey((h) => {
+ *   const key = makeQueryKey(h)
+ *   const ns = key.filter((_) => _.startsWith("$"))
+ *   if (!ns.length) throw new Error("empty query key for: " + h.id)
+ *   return ns
+ * })
+ * ```
+ */
+export const setDefaultGetQueryKey = (fn: GetQueryKey | undefined) => {
+  activeGetQueryKey = fn ?? defaultGetQueryKey
+}
+
+export const getQueryKey: GetQueryKey = (h) => activeGetQueryKey(h)
+
 export function mutationResultToVue<A, E>(
   mutationResult: AsyncResult.AsyncResult<A, E>
 ): Res<A, E> {
@@ -67,87 +101,142 @@ export function make<A, E, R>(self: Effect.Effect<A, E, R>) {
   return tuple(result, latestSuccess, execute)
 }
 
-export interface MutationOptionsBase {
-  /**
-   * By default we invalidate one level of the query key, e.g $project/$configuration.get, we invalidate $project.
-   * This can be overridden by providing a function that returns an array of filters and options.
-   */
-  queryInvalidation?: (defaultKey: string[], name: string) => {
+/**
+ * An entry for `queryInvalidation`. One of:
+ *  - a raw query key (`string[]`)
+ *  - `{ filters, options }` raw tanstack-query invalidation
+ *  - an RPC handler (`{ id, options? }`) — its query key is derived via `makeQueryKey`
+ */
+export type InvalidationEntry =
+  | ReadonlyArray<string>
+  | {
     filters?: InvalidateQueryFilters | undefined
     options?: InvalidateOptions | undefined
-  }[]
-}
+  }
+  | { id: string; options?: ClientForOptions | undefined }
 
-/** @deprecated prefer more basic @see MutationOptionsBase and separate useMutation from Command.fn */
-export interface MutationOptions<A, E, R, A2 = A, E2 = E, R2 = R, I = void> extends MutationOptionsBase {
+export interface MutationOptionsBase<A = unknown, B = A, E2 = never, R2 = never> {
+  /**
+   * By default we invalidate one level of the query key, e.g $project/$configuration.get, we invalidate $project.
+   * This can be overridden by providing a function that returns an array of filters and options,
+   * or RPC handlers directly (their query keys are derived automatically).
+   *
+   * @example
+   * ```ts
+   * queryInvalidation: (queryKey) => [
+   *   { filters: { queryKey } },
+   *   GetMe,
+   *   PackListIndex
+   * ]
+   * ```
+   */
+  queryInvalidation?: (
+    defaultKey: string[],
+    name: string,
+    input?: unknown,
+    output?: Exit.Exit<unknown, unknown>
+  ) => InvalidationEntry[]
   /**
-   * Map the handler; cache invalidation is already done in this handler.
-   * This is useful for e.g navigating, as you know caches have already updated.
+   * Run an additional Effect after the mutation succeeds. Its output becomes the
+   * final result returned to the caller. Query cache is invalidated once on
+   * mutation exit and again after this Effect completes. Useful for long-running
+   * operations (e.g. polling a background job) where you want the caller to
+   * receive the downstream result and the cache to refresh once it is ready.
    *
-   * @deprecated use `Command.fn` instead of `useMutation*` with `mapHandler` option.
+   * @example
+   * ```ts
+   * useMutation(startExportCommand, {
+   *   select: (result) => pollUntilDone(result.jobId)
+   *   // caller receives the pollUntilDone output, not the original result
+   * })
+   * ```
    */
-  mapHandler?: (handler: Effect.Effect<A, E, R>, input: I) => Effect.Effect<A2, E2, R2>
+  select?: (result: A) => Effect.Effect<B, E2, R2>
 }
 
-// TODO: more efficient invalidation, including args etc
-// return Effect.promise(() => queryClient.invalidateQueries({
-//   predicate: (_) => nses.includes(_.queryKey.filter((_) => _.startsWith("$")).join("/"))
-// }))
-/*
-            // const nses: string[] = []`
-                // for (let i = 0; i < ns.length; i++) {
-                //   nses.push(ns.slice(0, i + 1).join("/"))
-                // }
-                */
-
-export const asResult: {
-  <A, E, R>(
-    handler: Effect.Effect<A, E, R>
-  ): readonly [ComputedRef<AsyncResult.AsyncResult<A, E>>, Effect.Effect<Exit.Exit<A, E>, never, R>]
-  <Args extends readonly any[], A, E, R>(
-    handler: (...args: Args) => Effect.Effect<A, E, R>
-  ): readonly [ComputedRef<AsyncResult.AsyncResult<A, E>>, (...args: Args) => Effect.Effect<Exit.Exit<A, E>, never, R>]
-} = <Args extends readonly any[], A, E, R>(
-  handler: Effect.Effect<A, E, R> | ((...args: Args) => Effect.Effect<A, E, R>)
-) => {
+export const asResult = <Args extends readonly any[], A, E, R>(
+  handler: (...args: Args) => Effect.Effect<A, E, R>
+): readonly [
+  ComputedRef<AsyncResult.AsyncResult<A, E>>,
+  (...args: Args) => Effect.Effect<Exit.Exit<A, E>, never, R>
+] => {
   const state = shallowRef<AsyncResult.AsyncResult<A, E>>(AsyncResult.initial())
 
-  const act = Effect.isEffect(handler)
-    ? Effect
+  const act = (...args: Args) =>
+    Effect
       .sync(() => {
         state.value = AsyncResult.initial(true)
       })
       .pipe(
         Effect.andThen(Effect.suspend(() =>
-          handler.pipe(
+          handler(...args).pipe(
             Effect.exit,
             Effect.tap((exit) => Effect.sync(() => (state.value = AsyncResult.fromExit(exit))))
           )
         ))
       )
-    : (...args: Args) =>
-      Effect
-        .sync(() => {
-          state.value = AsyncResult.initial(true)
-        })
-        .pipe(
-          Effect.andThen(Effect.suspend(() =>
-            handler(...args).pipe(
-              Effect.exit,
-              Effect.tap((exit) => Effect.sync(() => (state.value = AsyncResult.fromExit(exit))))
+
+  return tuple(computed(() => state.value), act) as any
+}
+
+/**
+ * Like `asResult`, but for streams. The ref is updated with each emitted value
+ * (keeping `waiting: true`) and is finalised (with `waiting: false`) once the
+ * stream terminates successfully. Errors are surfaced as `AsyncResult.failure`.
+ */
+export const asStreamResult = <Args extends readonly any[], A, E, R>(
+  handler: (...args: Args) => Stream.Stream<A, E, R>
+): readonly [ComputedRef<AsyncResult.AsyncResult<A, E>>, (...args: Args) => Effect.Effect<void, never, R>] => {
+  const state = shallowRef<AsyncResult.AsyncResult<A, E>>(AsyncResult.initial())
+
+  const runStream = (stream: Stream.Stream<A, E, R>): Effect.Effect<void, never, R> =>
+    Effect
+      .sync(() => {
+        state.value = AsyncResult.initial(true)
+      })
+      .pipe(
+        Effect.andThen(
+          stream.pipe(
+            Stream.runForEach((value) =>
+              Effect.sync(() => {
+                state.value = AsyncResult.success(value, { waiting: true })
+              })
+            ),
+            Effect.exit,
+            Effect.flatMap((exit) =>
+              Effect.sync(() => {
+                if (exit._tag === "Success") {
+                  const current = state.value
+                  if (AsyncResult.isSuccess(current)) {
+                    state.value = AsyncResult.success(current.value, { waiting: false })
+                  } else {
+                    state.value = AsyncResult.initial(false)
+                  }
+                } else {
+                  state.value = AsyncResult.failure(exit.cause)
+                }
+              })
             )
-          ))
+          )
         )
+      )
+
+  const act = (...args: Args) => runStream(handler(...args))
 
   return tuple(computed(() => state.value), act) as any
 }
 
-export const invalidateQueries = (
+const buildInvalidateCache = (
   queryClient: QueryClient,
   self: { id: string; options?: ClientForOptions },
-  options?: MutationOptionsBase["queryInvalidation"]
+  queryInvalidation?: MutationOptionsBase["queryInvalidation"]
 ) => {
-  const invalidateQueries = (
+  type InvalidationTarget = {
+    readonly filters: InvalidateQueryFilters | undefined
+    readonly options: InvalidateOptions | undefined
+  }
+
+  const invalidateQueriesFn = (
     filters?: InvalidateQueryFilters,
     options?: InvalidateOptions
   ) =>
@@ -158,71 +247,160 @@ export const invalidateQueries = (
       )
     )
 
-  const invalidateCache = Effect.suspend(() => {
+  const getClientInvalidationTargets = (
+    input: unknown,
+    output: Exit.Exit<unknown, unknown>
+  ): ReadonlyArray<InvalidationTarget> => {
     const queryKey = getQueryKey(self)
 
-    if (options) {
-      const opts = options(queryKey, self.id)
-      if (!opts.length) {
-        return Effect.void
+    if (queryInvalidation) {
+      return queryInvalidation(queryKey, self.id, input, output).map((entry): InvalidationTarget => {
+        if (Array.isArray(entry)) {
+          return { filters: { queryKey: entry }, options: undefined }
+        }
+        const obj = entry as Exclude<InvalidationEntry, ReadonlyArray<string>>
+        if ("id" in obj) {
+          return {
+            filters: {
+              queryKey: makeQueryKey(obj.options ? { id: obj.id, options: obj.options } : { id: obj.id })
+            },
+            options: undefined
+          }
+        }
+        return { filters: obj.filters, options: obj.options }
+      })
+    }
+
+    if (!queryKey) {
+      return []
+    }
+
+    return [{ filters: { queryKey }, options: undefined }]
+  }
+
+  const invalidateCache = (
+    input: unknown,
+    output: Exit.Exit<unknown, unknown>,
+    serverKeys: ReadonlyArray<InvalidationKey>
+  ) =>
+    Effect.suspend(() => {
+      const clientTargets = getClientInvalidationTargets(input, output)
+      const serverTargets: ReadonlyArray<InvalidationTarget> = serverKeys.map((queryKey) => ({
+        filters: { queryKey },
+        options: undefined
+      }))
+      const allTargets: ReadonlyArray<InvalidationTarget> = [...clientTargets, ...serverTargets]
+
+      if (!allTargets.length) return Effect.void
+
+      // Group targets by refetchType + options so each group can be merged into a single
+      // invalidateQueries call using a predicate, reducing N calls to 1 in the common case.
+      type Group = {
+        targets: Array<InvalidationTarget>
+        refetchType: InvalidateQueryFilters["refetchType"]
+        options: InvalidateOptions | undefined
       }
+      const groups = new Map<string, Group>()
+      for (const target of allTargets) {
+        const key = `${target.filters?.refetchType ?? ""}|${target.options?.cancelRefetch ?? ""}|${
+          target.options?.throwOnError?.toString() ?? ""
+        }`
+        const existing = groups.get(key)
+        if (existing) {
+          existing.targets.push(target)
+        } else {
+          groups.set(key, { targets: [target], refetchType: target.filters?.refetchType, options: target.options })
+        }
+      }
+
       return Effect
         .andThen(
-          Effect.annotateCurrentSpan({ queryKey, opts }),
-          Effect.forEach(opts, (_) => invalidateQueries(_.filters, _.options), { concurrency: "inherit" })
+          Effect.annotateCurrentSpan({ clientTargets, serverKeys }),
+          Effect.forEach(
+            groups.values(),
+            ({ options, refetchType, targets }) =>
+              invalidateQueriesFn(
+                {
+                  ...(refetchType !== undefined ? { refetchType } : {}),
+                  predicate: (query) => targets.some((t) => t.filters ? matchQuery(t.filters, query) : true)
+                },
+                options
+              ),
+            { discard: true, concurrency: "inherit" }
+          )
         )
-        .pipe(Effect.withSpan("client.query.invalidation", {}, { captureStackTrace: false }))
-    }
+        .pipe(
+          Effect.tap(
+            // hand over control back to the event loop so that state can be updated..
+            // TODO: should we do this in general on any mutation, regardless of invalidation?
+            Effect.sleep(0)
+          ),
+          Effect.withSpan("client.query.invalidation", {}, { captureStackTrace: false })
+        )
+    })
 
-    if (!queryKey) return Effect.void
+  return invalidateCache
+}
 
-    return Effect
-      .andThen(
-        Effect.annotateCurrentSpan({ queryKey }),
-        invalidateQueries({ queryKey })
-      )
-      .pipe(
-        Effect.tap(
-          // hand over control back to the event loop so that state can be updated..
-          // TODO: should we do this in general on any mutation, regardless of invalidation?
-          Effect.sleep(0)
-        ),
-        Effect.withSpan("client.query.invalidation", {}, { captureStackTrace: false })
-      )
-  })
+export const invalidateQueries = (
+  queryClient: QueryClient,
+  self: { id: string; options?: ClientForOptions },
+  options?: MutationOptionsBase
+) => {
+  const invalidateCache = buildInvalidateCache(queryClient, self, options?.queryInvalidation)
+
+  const select = options?.select
 
-  const handle = <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.ensuring(self, invalidateCache)
+  const handle = <A, E, R>(eff: Effect.Effect<A, E, R>, input?: unknown) =>
+    Effect.gen(function*() {
+      const keysRef = yield* Ref.make<ReadonlyArray<InvalidationKey>>([])
+      const result = yield* eff.pipe(
+        Effect.provideService(InvalidationKeysFromServer, makeInvalidationKeysService(keysRef)),
+        Effect.onExit((exit) =>
+          Effect.gen(function*() {
+            const serverKeys = yield* Ref.get(keysRef)
+            yield* invalidateCache(input, exit, serverKeys)
+          })
+        )
+      )
+      if (select) {
+        return yield* select(result).pipe(
+          Effect.onExit((exit) =>
+            Effect.gen(function*() {
+              const serverKeys = yield* Ref.get(keysRef)
+              yield* invalidateCache(input, exit, serverKeys)
+            })
+          )
+        )
+      }
+      return result
+    })
 
   return handle
 }
 
+/**
+ * A callable mutation result. When `I = void` the input argument may be omitted.
+ */
+export interface MutationFn<I, A, E, R, Id extends string> {
+  <B = A, E2 = never, R2 = never>(
+    input: I,
+    options?: MutationOptionsBase<A, B, E2, R2>
+  ): Effect.Effect<B, E | E2, R | R2>
+  readonly id: Id
+}
+
 export const makeMutation = () => {
-  const useMutation: {
-    /**
-     * Pass a function that returns an Effect, e.g from a client action
-     * Executes query cache invalidation based on default rules or provided option.
-     */
-    <I, E, A, R, Request extends Req, Id extends string>(
-      self: RequestHandlerWithInput<I, A, E, R, Request, Id>,
-      options?: MutationOptionsBase
-    ): ((i: I) => Effect.Effect<A, E, R>) & { readonly id: Id }
-    /**
-     * Pass an Effect, e.g from a client action
-     * Executes query cache invalidation based on default rules or provided option.
-     */
-    <E, A, R, Request extends Req, Id extends string>(
-      self: RequestHandler<A, E, R, Request, Id>,
-      options?: MutationOptionsBase
-    ): Effect.Effect<A, E, R> & { readonly id: Id }
-  } = <I, E, A, R, Request extends Req, Id extends string>(
-    self: RequestHandlerWithInput<I, A, E, R, Request, Id> | RequestHandler<A, E, R, Request, Id>,
-    options?: MutationOptionsBase
-  ) => {
+  /**
+   * Pass a function that returns an Effect, e.g from a client action.
+   * Executes query cache invalidation based on default rules or provided option.
+   * When `I = void` the input argument may be omitted.
+   */
+  const useMutation = <I, E, A, R, Request extends Req, Id extends string>(
+    self: RequestHandlerWithInput<I, A, E, R, Request, Id>
+  ): MutationFn<I, A, E, R, Id> => {
     const queryClient = useQueryClient()
-    const handle = invalidateQueries(queryClient, self, options?.queryInvalidation)
-    const handler = self.handler
-    const r = Effect.isEffect(handler) ? handle(handler) : (i: I) => handle(handler(i))
-
+    const r = (i: I, options?: MutationOptionsBase) => invalidateQueries(queryClient, self, options)(self.handler(i), i)
     return Object.assign(r, { id: self.id }) as any
   }
   return useMutation
@@ -232,32 +410,61 @@ export const makeMutation = () => {
 export const useMakeMutation = () => {
   const queryClient = useQueryClient()
 
-  const useMutation: {
-    /**
-     * Pass a function that returns an Effect, e.g from a client action
-     * Executes query cache invalidation based on default rules or provided option.
-     */
-    <I, E, A, R, Request extends Req, Id extends string>(
-      self: RequestHandlerWithInput<I, A, E, R, Request, Id>,
-      options?: MutationOptionsBase
-    ): ((i: I) => Effect.Effect<A, E, R>) & { readonly id: Id }
-    /**
-     * Pass an Effect, e.g from a client action
-     * Executes query cache invalidation based on default rules or provided option.
-     */
-    <E, A, R, Request extends Req, Id extends string>(
-      self: RequestHandler<A, E, R, Request, Id>,
-      options?: MutationOptionsBase
-    ): Effect.Effect<A, E, R> & { readonly id: Id }
-  } = <I, E, A, R, Request extends Req, Id extends string>(
-    self: RequestHandlerWithInput<I, A, E, R, Request, Id> | RequestHandler<A, E, R, Request, Id>,
-    options?: MutationOptionsBase
-  ) => {
-    const handle = invalidateQueries(queryClient, self, options?.queryInvalidation)
-    const handler = self.handler
-    const r = Effect.isEffect(handler) ? handle(handler) : (i: I) => handle(handler(i))
-
+  /**
+   * Pass a function that returns an Effect, e.g from a client action.
+   * Executes query cache invalidation based on default rules or provided option.
+   * When `I = void` the input argument may be omitted.
+   */
+  const useMutation = <I, E, A, R, Request extends Req, Id extends string>(
+    self: RequestHandlerWithInput<I, A, E, R, Request, Id>
+  ): MutationFn<I, A, E, R, Id> => {
+    const r = (i: I, options?: MutationOptionsBase) => invalidateQueries(queryClient, self, options)(self.handler(i), i)
     return Object.assign(r, { id: self.id }) as any
   }
   return useMutation
 }
+
+/**
+ * Returns a stream-based mutation factory for use with `streamFn`.
+ * The outer Effect sets up per-invocation invalidation scaffolding
+ * and returns a stream that triggers query invalidation via `Stream.ensuring` when it completes.
+ *
+ * Use with `streamFn` / `Command.streamFn(id)(mutateHandler, ...combinators)` so that
+ * the command manages its own reactive state internally.
+ *
+ * Must be called inside a Vue setup context (uses `useQueryClient` internally).
+ */
+export const makeStreamMutation2 = () => {
+  const queryClient = useQueryClient()
+
+  return (
+    self: {
+      id: string
+      options?: ClientForOptions
+      handler: (i: any) => Stream.Stream<any, any, any>
+    },
+    mergedInvalidation?: MutationOptionsBase["queryInvalidation"]
+  ) => {
+    const invCache = buildInvalidateCache(queryClient, self, mergedInvalidation)
+
+    const makeInvocationEffect = (input: unknown, source: Stream.Stream<any, any, any>) =>
+      Effect.gen(function*() {
+        const keysRef = yield* Ref.make<ReadonlyArray<InvalidationKey>>([])
+        const invKeys = makeInvalidationKeysService(keysRef, (key) => invCache(input, Exit.succeed(undefined), [key]))
+        const lastRef = yield* Ref.make<any>(undefined)
+        return source.pipe(
+          Stream.provideService(InvalidationKeysFromServer, invKeys),
+          Stream.tap((v) => Ref.set(lastRef, v)),
+          Stream.ensuring(
+            Effect.gen(function*() {
+              const lastValue = yield* Ref.get(lastRef)
+              const serverKeys = yield* Ref.get(keysRef)
+              yield* invCache(input, Exit.succeed(lastValue), serverKeys)
+            })
+          )
+        )
+      })
+
+    return (i: any) => Stream.unwrap(makeInvocationEffect(i, self.handler(i)))
+  }
+}