@effect-app/vue 4.0.0-beta.98 → 4.0.0

package/test/makeClient.test.ts

@@ -1,34 +1,313 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { type Effect } from "effect-app"
-import { makeQueryKey } from "../src/lib.js"
+import { expect, expectTypeOf, it } from "@effect/vitest"
+import { configureInvalidation, makeQueryKey } from "effect-app/client"
+import type { HandlerInput } from "effect-app/client/clientFor"
+import * as Effect from "effect-app/Effect"
+import * as S from "effect-app/Schema"
+import * as Exit from "effect/Exit"
+import * as Fiber from "effect/Fiber"
+import * as Atom from "effect/reactivity/Atom"
+import { TestClock } from "effect/testing"
+import type { CommandFromRequest } from "../src/makeClient.js"
+import { combineQueryInvalidators, invalidateQueries } from "../src/mutate.js"
+import { useAtomQuery, useAtomSuspense } from "../src/query.js"
 import { Something, SomethingElse, SomethingElseReq, SomethingReq, useClient, useExperimental } from "./stubs.js"
 
+const somethingInvalidationResources = {
+  Something: {
+    GetSomething2: Something.GetSomething2,
+    GetSomething2WithDependencies: Something.GetSomething2WithDependencies,
+    GetSomething3: Something.GetSomething3,
+    GetSomething4: Something.GetSomething4
+  }
+}
+
 it("TaggedRequestFor .moduleName and request .id / .moduleName", () => {
   expectTypeOf(SomethingReq.moduleName).toEqualTypeOf<"Something">()
   expectTypeOf(SomethingElseReq.moduleName).toEqualTypeOf<"SomethingElse">()
 
   expectTypeOf(Something.GetSomething2.moduleName).toEqualTypeOf<"Something">()
   expectTypeOf(Something.GetSomething2.id).toEqualTypeOf<"Something.GetSomething2">()
+  expectTypeOf(Something.GetSomething2.type).toEqualTypeOf<"query">()
+  expectTypeOf(Something.DoSomething.type).toEqualTypeOf<"command">()
 
   expectTypeOf(SomethingElse.GetSomething2.moduleName).toEqualTypeOf<"SomethingElse">()
   expectTypeOf(SomethingElse.GetSomething2.id).toEqualTypeOf<"SomethingElse.GetSomething2">()
+
+  const invalidates = configureInvalidation<{
+    Something: typeof Something
+    SomethingElse: typeof SomethingElse
+  }>()((queryKey, { Something, SomethingElse }) => [
+    { filters: { queryKey } },
+    { filters: { queryKey: makeQueryKey(Something.GetSomething2) } },
+    { filters: { queryKey: makeQueryKey(SomethingElse.GetSomething2) } }
+  ])
+
+  expectTypeOf(invalidates.invalidatesQueries).toBeFunction()
+  configureInvalidation<{ Something: typeof Something }>()((_queryKey) => [
+    // @ts-expect-error predicate filters are not supported by the atom query engine
+    { filters: { predicate: () => true } }
+  ])
+  configureInvalidation<{ Something: typeof Something }>()((_queryKey, { Something }) => {
+    // @ts-expect-error commands are intentionally excluded from configured resources
+    void Something.DoSomething
+    return []
+  })
+
+  const { clientFor } = useClient()
+  const client = clientFor(
+    Something,
+    undefined,
+    somethingInvalidationResources
+  )
+
+  // only queries, no commands, and no commands who require resources; shouldn't require invalidation resources args!
+  clientFor({ GetSomething: Something.GetSomething2 })
+
+  // @ts-expect-error invalidation resources should be required when any command configures them
+  clientFor(Something)
+
+  // @ts-expect-error invalidation resources for this module reject extra top-level resources
+  clientFor(Something, undefined, { ...somethingInvalidationResources, SomethingElse })
+
+  const doSomethingInvalidation = client.DoSomething.Request.config["invalidatesQueries"]
+  if (doSomethingInvalidation) {
+    const entries = doSomethingInvalidation(
+      ["$Something"],
+      somethingInvalidationResources,
+      { id: "abc" },
+      Exit.succeed(123)
+    )
+    expect(Array.isArray(entries)).toBe(true)
+  }
+
+  const SomethingCommand = SomethingReq.Command
+
+  class TypeInferenceWithSuccess extends SomethingCommand<TypeInferenceWithSuccess>()("TypeInferenceWithSuccess", {
+    id: S.String
+  }, {
+    success: S.FiniteFromString
+  }, (_queryKey, _resources, input, result) => {
+    expectTypeOf(input).toEqualTypeOf<{ readonly id: string }>()
+    expectTypeOf(result).toEqualTypeOf<Exit.Exit<number, never>>()
+    return []
+  }) {}
+  void TypeInferenceWithSuccess
+
+  class TypeInferenceWithoutSuccess extends SomethingCommand<TypeInferenceWithoutSuccess>()(
+    "TypeInferenceWithoutSuccess",
+    {
+      id: S.String
+    },
+    {},
+    (_queryKey, _resources, input, result) => {
+      expectTypeOf(input).toEqualTypeOf<{ readonly id: string }>()
+      expectTypeOf(result).toEqualTypeOf<Exit.Exit<void, never>>()
+      return []
+    }
+  ) {}
+  void TypeInferenceWithoutSuccess
+
+  type MixedResources = {
+    Something: typeof Something
+    Misc: {
+      value: number
+      GetSomething2: typeof Something.GetSomething2
+    }
+  }
+
+  class TypeInferenceResourceFiltering extends SomethingCommand<
+    TypeInferenceResourceFiltering,
+    MixedResources
+  >()("TypeInferenceResourceFiltering", {
+    id: S.String
+  }, {
+    success: S.FiniteFromString
+  }, (_queryKey, resources, _input, _result) => {
+    expectTypeOf(resources.Something.GetSomething2).toEqualTypeOf<typeof Something.GetSomething2>()
+    expectTypeOf(resources.Misc.GetSomething2).toEqualTypeOf<typeof Something.GetSomething2>()
+
+    // @ts-expect-error commands must be filtered from invalidation resources
+    void resources.Something.DoSomething
+    // @ts-expect-error non-query values must be filtered from invalidation resources
+    void resources.Misc.value
+
+    return []
+  }) {}
+  void TypeInferenceResourceFiltering
+
+  type WithSuccessInvalidation = NonNullable<typeof TypeInferenceWithSuccess.config.invalidatesQueries> // @ts-expect-error input should be required when command payload is non-empty
+  ;((_queryKey, _resources) => []) satisfies WithSuccessInvalidation
+})
+
+it("clientFor handler shape — props variants", () => {
+  const { clientFor } = useClient()
+  const client = clientFor(
+    Something,
+    undefined,
+    somethingInvalidationResources
+  )
+  expect(client).toBeDefined()
+
+  // no-props (no fields): handler is (i: void) => Effect — callable without arg
+  expectTypeOf(client.DoNoProps.handler).toBeFunction()
+  client.DoNoProps.handler()
+
+  // no-props: request mirrors handler — (i: void) => Effect, callable without arg
+  expectTypeOf(client.DoNoProps.request).toBeFunction()
+  client.DoNoProps.request()
+  // optional-only: any fields → function handler. Input matches `make`, which for
+  // fully-optional payload is omittable.
+  expectTypeOf(client.DoOptionalOnly.handler).toBeFunction()
+  // arg may be omitted entirely
+  client.DoOptionalOnly.handler()
+  // or supplied with all-optional payload
+  client.DoOptionalOnly.handler({})
+  client.DoOptionalOnly.handler({ name: "x" })
+
+  // required-only: function, `id` required
+  expectTypeOf(client.DoRequiredOnly.handler).toBeFunction()
+  client.DoRequiredOnly.handler({ id: "x" })
+  // @ts-expect-error id is required
+  client.DoRequiredOnly.handler({})
+  // @ts-expect-error arg cannot be omitted
+  client.DoRequiredOnly.handler()
+
+  // mixed: id required, name optional
+  expectTypeOf(client.DoMixed.handler).toBeFunction()
+  client.DoMixed.handler({ id: "x" })
+  client.DoMixed.handler({ id: "x", name: "y" })
+  // @ts-expect-error id required
+  client.DoMixed.handler({ name: "y" })
+})
+
+it.effect("mutation invalidation awaits the injected query invalidator", () =>
+  Effect.gen(function*() {
+    const recorded: Array<readonly [string, ReadonlyArray<unknown>]> = []
+    const keys = [["$Something"], ["$Something", "GetSomething2"]]
+    const queryInvalidator = combineQueryInvalidators(
+      { invalidateAndAwait: (keys) => Effect.sync(() => keys.forEach((key) => recorded.push(["atom", key]))) },
+      { invalidateAndAwait: (keys) => Effect.sync(() => keys.forEach((key) => recorded.push(["tanstack", key]))) }
+    )
+    const mutate = invalidateQueries(
+      { id: "Something.DoSomething" },
+      { queryInvalidation: () => keys },
+      queryInvalidator
+    )
+
+    const fiber = yield* Effect.forkChild(mutate(Effect.succeed(123), { id: "abc" }))
+    yield* TestClock.adjust("1 millis")
+    const result = yield* Fiber.join(fiber)
+
+    expect(result).toBe(123)
+    expect(recorded).toEqual([
+      ["atom", keys[0]],
+      ["atom", keys[1]],
+      ["tanstack", keys[0]],
+      ["tanstack", keys[1]]
+    ])
+  }))
+
+it("client[Key].Input — extracted input type per props variant", () => {
+  const { clientFor } = useClient()
+  const client = clientFor(
+    Something,
+    undefined,
+    somethingInvalidationResources
+  )
+
+  // Input mirrors HandlerInput<typeof Request> — the same type the handler accepts.
+  expectTypeOf(client.GetSomething2.Input).toEqualTypeOf<HandlerInput<typeof Something.GetSomething2>>()
+  expectTypeOf(client.GetSomething3.Input).toEqualTypeOf<HandlerInput<typeof Something.GetSomething3>>()
+  // GetSomething4: no fields → void
+  expectTypeOf(client.GetSomething4.Input).toBeVoid()
+  expectTypeOf(client.GetSomething4.Input).toEqualTypeOf<HandlerInput<typeof Something.GetSomething4>>()
+
+  // commands — props variants
+  expectTypeOf(client.DoNoProps.Input).toBeVoid()
+  expectTypeOf(client.DoNoProps.Input).toEqualTypeOf<HandlerInput<typeof Something.DoNoProps>>()
+  expectTypeOf(client.DoOptionalOnly.Input).toEqualTypeOf<HandlerInput<typeof Something.DoOptionalOnly>>()
+  expectTypeOf(client.DoRequiredOnly.Input).toEqualTypeOf<HandlerInput<typeof Something.DoRequiredOnly>>()
+  expectTypeOf(client.DoMixed.Input).toEqualTypeOf<HandlerInput<typeof Something.DoMixed>>()
+  expectTypeOf(client.DoSomething.Input).toEqualTypeOf<HandlerInput<typeof Something.DoSomething>>()
+
+  // Sanity: a non-trivial handler Input matches the handler's parameter type
+  type HandlerArg = Parameters<typeof client.DoMixed.handler>[0]
+  expectTypeOf<typeof client.DoMixed.Input>().toEqualTypeOf<HandlerArg>()
+
+  // Stream handlers — Input now extracts via RequestStreamHandlerWithInput fallback.
+  expectTypeOf(client.StreamQuery.Input).toEqualTypeOf<{ readonly id: string; readonly _tag?: "StreamQuery" }>()
+  expectTypeOf(client.StreamWithoutFinal.Input).toEqualTypeOf<
+    { readonly id: string; readonly _tag?: "StreamWithoutFinal" }
+  >()
+  expectTypeOf(client.StreamWithFinal.Input).toEqualTypeOf<{ readonly id: string; readonly _tag?: "StreamWithFinal" }>()
+
+  const assertStreamQueryTypes = () => {
+    const streamAtom = client.StreamQuery.atom({ id: "abc" })
+    expectTypeOf(streamAtom).toEqualTypeOf<Atom.Writable<Atom.PullResult<number, never>, void>>()
+    const streamView = client.StreamQuery.queryNew({ id: "abc" })
+    expectTypeOf(streamView.items.value).toEqualTypeOf<ReadonlyArray<number>>()
+    expectTypeOf(streamView.latest.value).toEqualTypeOf<number | undefined>()
+    expectTypeOf(streamView.done.value).toBeBoolean()
+    expectTypeOf(streamView.pull).toBeFunction()
+    expectTypeOf(streamView.pullAndAwait).toBeFunction()
+  }
+  void assertStreamQueryTypes
+})
+
+it("CommandFromRequest input shape — props variants", () => {
+  type NoPropsArg = Parameters<CommandFromRequest<typeof Something.DoNoProps>["handle"]>[0]
+
+  // no-props (no fields) → void input; void parameter is implicitly optional, so handle() works
+  expectTypeOf<NoPropsArg>().toBeVoid()
+
+  // type-only assignability checks for the remaining variants
+  if (false as boolean) {
+    const noProps = null as unknown as CommandFromRequest<typeof Something.DoNoProps>
+    const optOnly = null as unknown as CommandFromRequest<typeof Something.DoOptionalOnly>
+    const reqOnly = null as unknown as CommandFromRequest<typeof Something.DoRequiredOnly>
+    const mixed = null as unknown as CommandFromRequest<typeof Something.DoMixed>
+
+    // no-props → void param, calling without args is fine
+    noProps.handle()
+
+    // optional-only → matches `make` (fully optional, arg omittable)
+    optOnly.handle()
+    optOnly.handle({})
+    optOnly.handle({ name: "x" })
+
+    // required-only → id required
+    reqOnly.handle({ id: "x" })
+    // @ts-expect-error id required
+    reqOnly.handle({})
+
+    // mixed → id required, name optional
+    mixed.handle({ id: "x" })
+    mixed.handle({ id: "x", name: "y" })
+    // @ts-expect-error id required
+    mixed.handle({ name: "y" })
+  }
 })
 
 it.skip("query type tests", () => {
   const { clientFor } = useClient()
-  const client = clientFor(Something, () => ({
-    GetSomething2WithDependencies: (queryKey) => [
-      { filters: { queryKey } },
-      {
-        filters: {
-          queryKey: makeQueryKey(
-            SomethingElse
-              .GetSomething2
-          )
+  const client = clientFor(
+    Something,
+    () => ({
+      GetSomething2WithDependencies: (queryKey) => [
+        { filters: { queryKey } },
+        {
+          filters: {
+            queryKey: makeQueryKey(
+              SomethingElse
+                .GetSomething2
+            )
+          }
         }
-      }
-    ]
-  }))
+      ]
+    }),
+    somethingInvalidationResources
+  )
 
   const q = client.GetSomething2.query
 
@@ -57,37 +336,127 @@ it.skip("query type tests", () => {
   expectTypeOf(val4).toEqualTypeOf<string>()
 })
 
+it("additive atom query api type tests", () => {
+  const { clientFor } = useClient()
+  const client = clientFor(
+    Something,
+    undefined,
+    somethingInvalidationResources
+  )
+
+  if (false as boolean) {
+    const family = client.GetSomething2.family
+    const familyAtom = family({ id: "a" })
+    expectTypeOf<Atom.Success<typeof familyAtom>>().toEqualTypeOf<number>()
+
+    const mappedFamilyAtom = Atom.mapResult(familyAtom, (data) => data.toString())
+    expectTypeOf<Atom.Success<typeof mappedFamilyAtom>>().toEqualTypeOf<string>()
+    expectTypeOf(useAtomQuery(() => mappedFamilyAtom).data.value).toEqualTypeOf<string | undefined>()
+    void useAtomSuspense(() => mappedFamilyAtom).then((view) => {
+      expectTypeOf(view[1].value).toEqualTypeOf<string>()
+      return view
+    })
+
+    const atom = client.GetSomething2.atom({ id: "a" })
+    expectTypeOf<Atom.Success<typeof atom>>().toEqualTypeOf<number>()
+    // @ts-expect-error raw atom exposure does not accept Vue select projections
+    client.GetSomething2.atom({ id: "a" }, { select: (data) => data.toString() })
+
+    const query = client.GetSomething2.queryNew({ id: "a" })
+    expectTypeOf(query.data.value).toEqualTypeOf<number | undefined>()
+
+    const selected = client.GetSomething2.queryNew({ id: "a" }, { select: (data) => data.toString() })
+    expectTypeOf(selected.data.value).toEqualTypeOf<string | undefined>()
+
+    void client.GetSomething2.suspenseNew({ id: "a" }, { select: (data) => data.toString() }).then((view) => {
+      expectTypeOf(view[1].value).toEqualTypeOf<string>()
+      return view
+    })
+
+    const projected = client.GetSomething2.project(S.String)
+    const projectedFamilyAtom = projected.family({ id: "a" })
+    expectTypeOf<Atom.Success<typeof projectedFamilyAtom>>().toEqualTypeOf<string>()
+    const projectedAtom = projected.atom({ id: "a" })
+    expectTypeOf<Atom.Success<typeof projectedAtom>>().toEqualTypeOf<string>()
+    expectTypeOf(projected.queryNew({ id: "a" }).data.value).toEqualTypeOf<string | undefined>()
+    void projected.suspenseNew({ id: "a" }).then((view) => {
+      expectTypeOf(view[1].value).toEqualTypeOf<string>()
+      return view
+    })
+
+    const helperFamilyAtom = client.helpers.getSomething2QueryFamily({ id: "a" })
+    expectTypeOf<Atom.Success<typeof helperFamilyAtom>>().toEqualTypeOf<number>()
+    expectTypeOf(client.helpers.getSomething2QueryNew({ id: "a" }).data.value).toEqualTypeOf<number | undefined>()
+    void client.helpers.getSomething2SuspenseQueryNew({ id: "a" }).then((view) => {
+      expectTypeOf(view[1].value).toEqualTypeOf<number>()
+      return view
+    })
+  }
+
+  expect(true).toBe(true)
+})
+
 it.skip("works", () => {
   const { clientFor } = useClient()
-  const client = clientFor(Something)
+  const client = clientFor(Something, undefined, somethingInvalidationResources)
   const Command = useExperimental()
 
   // just for jsdoc / type testing.
-  const a0 = client.GetSomething2(null as any)
-  const a00 = client.GetSomething2.mutate(null as any)
+  const a0 = client.GetSomething2.request(null as any)
+  const a00 = client.DoSomething.mutate(null as any)
   const a = client.GetSomething2.suspense(null as any)
   const b = client.GetSomething2.query(null as any)
 
+  const de = client.GetSomething3.handler(null as any)
+  const de2 = client.GetSomething3.handler({ id: null })
+
+  const de3 = client.GetSomething4.handler()
+  void client.GetSomething4.handler
+
+  // @ts-expect-error query requests no longer expose command helpers
   const e = client.GetSomething2.wrap(null as any)
+  // @ts-expect-error query requests no longer expose command helpers
   const f = client.GetSomething2.fn(null as any)
 
-  // @ts-expect-error dependencies required that are not provided
-  const e0 = client.GetSomething2WithDependencies.wrap().handle // not available as we require dependencies not provided by the runtime
-  // @ts-expect-error dependencies required that are not provided
-  const e000 = Command.wrap(client.GetSomething2WithDependencies)().handle // not available as we require dependencies not provided by the runtime
-  const e00 = client.GetSomething2WithDependencies.wrap((_) => _ as Effect.Effect<number, never, never>).handle(
-    null as any
-  )
-  const e0000 =
-    Command.wrap(client.GetSomething2WithDependencies)((_) => _ as Effect.Effect<number, never, never>).handle
-  // @ts-expect-error dependencies required that are not provided
+  // @ts-expect-error query requests no longer expose command helpers
+  const e0 = client.GetSomething2WithDependencies.wrap
+  // @ts-expect-error query request does not match Command.wrap mutation signature
+  const e000 = Command.wrap(client.GetSomething2WithDependencies)
+  const e00 = client.GetSomething2WithDependencies.request(null as any)
   const e1 = client.GetSomething2WithDependencies.suspense(null as any)
-  // @ts-expect-error dependencies required that are not provided
   const e2 = client.GetSomething2WithDependencies.query(null as any)
+  // @ts-expect-error query requests no longer expose command helpers
   const f0 = client.GetSomething2WithDependencies.fn(null as any)
 
-  const g = client.GetSomething2.mutate.wrap(null as any)
-  const h = client.GetSomething2.mutate.fn(null as any)
+  const g0 = client.DoSomething.wrap(null as any)
+  const g = client.DoSomething.mutate.wrap(null as any)
+  const g1 = client.DoSomething.mutate.project(S.String)
+  const g2 = g1(null as any)
+  const g3 = g1.wrap(null as any)
+  const g4 = client.helpers.doSomethingMutation.project(S.String)
+  const g5 = g4(null as any)
+  const g6 = g4.wrap(null as any)
+  const h = client.DoSomething.mutate.fn(null as any)
+
+  // projection
+  // GetSomething2 uses FiniteFromString, that means Codec is String -> Number
+  // when we project that to S.String, it should work as the encoded shapes are identical
+  // aka, when we project, we skip decoding with the original codec, and instead use the provided one
+  // we have to make sure the Encoded shape of the provided projection schema matches the Encoded Shape of the original codec.
+  const projected = client.GetSomething2.project(S.String)
+  // @ts-expect-error encoded type mismatch: original encodes to string, S.Number encodes to number
+  client.GetSomething2.project(S.Number)
+  const p0 = projected.request(null as any)
+
+  // struct example: success schema encodes to { a: string | null }
+  // good: projection schema also expects { a: string | null } on the encoded side
+  const projectedStruct = client.GetStructNullable.project(S.Struct({ a: S.NullOr(S.String) }))
+  // bad: { a: S.String } has encoded type { a: string } — does not accept null
+  // @ts-expect-error encoded type mismatch: original encodes to { a: string | null }, projection expects { a: string }
+  client.GetStructNullable.project(S.Struct({ a: S.String }))
+
+  const p00 = projected.query(null as any)
+  const p = projected.suspense(null as any)
 
   expect(true).toBe(true)
   console.log({
@@ -96,15 +465,28 @@ it.skip("works", () => {
     a00,
     b,
     e,
+    de,
+    de2,
+    de3,
     e0,
     e00,
     e000,
-    e0000,
     e1,
     e2,
     f,
     f0,
+    g0,
     g,
-    h
+    g1,
+    g2,
+    g3,
+    g4,
+    g5,
+    g6,
+    h,
+    p0,
+    p00,
+    p,
+    projectedStruct
   })
 })

package/test/query-span.test.ts

@@ -0,0 +1,92 @@
+import { defaultRegistry, registryKey } from "@effect/atom-vue"
+import { QueryClient, VueQueryPlugin } from "@tanstack/vue-query"
+import type { RequestHandlerWithInput } from "effect-app/client/clientFor"
+import * as Context from "effect-app/Context"
+import * as Effect from "effect-app/Effect"
+import * as Layer from "effect-app/Layer"
+import * as Option from "effect-app/Option"
+import type * as Cause from "effect/Cause"
+import * as AsyncResult from "effect/reactivity/AsyncResult"
+import { createApp, effectScope, nextTick } from "vue"
+import { buildQueryFamily, makeAtomClientRuntime } from "../src/atomQuery.js"
+import { makeTanstackQuery } from "../src/internal/tanstackQuery.js"
+import { useAtomQuery } from "../src/query.js"
+
+const fakeHandler = <A, E>(
+  id: string,
+  run: (input: void) => Effect.Effect<A, E, never>
+): RequestHandlerWithInput<void, A, E, never, never, string> => ({
+  id,
+  handler: run,
+  Request: undefined as never
+})
+
+const querySpanParentName = Effect.currentSpan.pipe(
+  Effect.map((span) =>
+    Option.match(span.parent, {
+      onNone: () => "none",
+      onSome: (parent) => parent._tag === "Span" ? parent.name : "external"
+    })
+  )
+)
+
+function makeTanstackContext(queryClient: QueryClient) {
+  const app = createApp({ render: () => null })
+  app.use(VueQueryPlugin, { queryClient })
+  const scope = effectScope(true)
+  const run = <T>(fn: () => T): T => {
+    let out!: T
+    app.runWithContext(() => {
+      scope.run(() => {
+        out = fn()
+      })
+    })
+    return out
+  }
+  return { run, dispose: () => scope.stop() }
+}
+
+it("passes the current parent span through legacy TanStack refetch", async () => {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false, gcTime: Infinity, staleTime: 0 } }
+  })
+  const query = makeTanstackQuery(() => Context.empty(), queryClient)(
+    fakeHandler("Test/TanStackSpan", () => querySpanParentName)
+  )
+  const ctx = makeTanstackContext(queryClient)
+
+  const [, , , handle] = ctx.run(() => query(undefined, {}))
+  await Effect.runPromise(handle.awaitResult())
+
+  const parentName = await Effect.runPromise(handle.refetch().pipe(Effect.withSpan("trigger")))
+
+  expect(parentName).toBe("trigger")
+  ctx.dispose()
+})
+
+it("passes the current parent span through atom query refetch", async () => {
+  defaultRegistry.reset()
+  const rt = makeAtomClientRuntime(() => Layer.empty, Layer.makeMemoMapUnsafe())
+  const family = buildQueryFamily(rt, fakeHandler("Test/AtomSpan", () => querySpanParentName))
+  const atom = family(undefined)
+  let view!: ReturnType<typeof useAtomQuery<string, Cause.NoSuchElementError>>
+  const host = document.createElement("div")
+  const app = createApp({
+    setup() {
+      view = useAtomQuery(() => atom)
+      return () => null
+    }
+  })
+  app.provide(registryKey, defaultRegistry)
+  app.mount(host)
+
+  await Effect.runPromise(view.awaitResult())
+  const parentName = await Effect.runPromise(view.refetch().pipe(Effect.withSpan("trigger")))
+
+  expect(parentName).toBe("trigger")
+  expect(AsyncResult.isSuccess(view.result.value)).toBe(true)
+
+  app.unmount()
+  await nextTick()
+  defaultRegistry.reset()
+})

package/test/queryOptions.test.ts

@@ -0,0 +1,88 @@
+import { expect, it } from "@effect/vitest"
+import * as Cause from "effect/Cause"
+import * as Option from "effect/Option"
+import * as AsyncResult from "effect/reactivity/AsyncResult"
+import { shallowRef } from "vue"
+import { withDataFallback } from "../src/query.js"
+
+it("withDataFallback: returns the raw ref untouched when neither option is set", () => {
+  const raw = shallowRef(AsyncResult.initial<number, never>(false))
+  expect(withDataFallback(raw, undefined)).toBe(raw)
+  expect(withDataFallback(raw, {})).toBe(raw)
+})
+
+it("withDataFallback: placeholderData is provisional (waiting) and dropped once real data exists", () => {
+  const raw = shallowRef<AsyncResult.AsyncResult<number, never>>(AsyncResult.initial(true))
+  const out = withDataFallback(raw, { placeholderData: 1 })
+
+  // while pending with no value, surface the placeholder as provisional
+  expect(out.value).toMatchObject({ _tag: "Success", value: 1, waiting: true })
+
+  // real data replaces the placeholder (display-only — raw was never written)
+  raw.value = AsyncResult.success(2)
+  expect(out.value).toMatchObject({ _tag: "Success", value: 2, waiting: false })
+})
+
+it("withDataFallback: placeholderData function form receives the last seen concrete value", () => {
+  const raw = shallowRef<AsyncResult.AsyncResult<number, never>>(AsyncResult.success(10))
+  const out = withDataFallback(raw, { placeholderData: (prev: number | undefined) => (prev ?? 0) + 1 })
+
+  // concrete value present -> shown as-is, recorded as "previous"
+  expect(out.value).toMatchObject({ _tag: "Success", value: 10 })
+
+  // input changed -> back to Initial: placeholder fn sees the previous value (10)
+  raw.value = AsyncResult.initial(true)
+  expect(out.value).toMatchObject({ _tag: "Success", value: 11, waiting: true })
+})
+
+it("withDataFallback: initialData shows as resolved data while Initial, dropped on real success", () => {
+  const raw = shallowRef<AsyncResult.AsyncResult<number, never>>(AsyncResult.initial(false))
+  const out = withDataFallback(raw, { initialData: 7 })
+
+  expect(out.value).toMatchObject({ _tag: "Success", value: 7, waiting: false })
+
+  const out2 = withDataFallback(raw, { initialData: () => 9 })
+  expect(out2.value).toMatchObject({ _tag: "Success", value: 9 })
+
+  raw.value = AsyncResult.success(42)
+  expect(out.value).toMatchObject({ _tag: "Success", value: 42 })
+})
+
+it("withDataFallback: initialData takes precedence over placeholderData", () => {
+  const raw = shallowRef<AsyncResult.AsyncResult<number, never>>(AsyncResult.initial(false))
+  const out = withDataFallback(raw, { initialData: 1, placeholderData: 99 })
+  expect(out.value).toMatchObject({ _tag: "Success", value: 1 })
+})
+
+it("withDataFallback: select applies to the placeholder when layered after the fallback", () => {
+  // mirrors makeQueryView: fallback pre-select, then AsyncResult.map(select)
+  const raw = shallowRef<AsyncResult.AsyncResult<number, never>>(AsyncResult.initial(true))
+  const fallback = withDataFallback(raw, { placeholderData: 123 })
+  const selected = () => AsyncResult.map(fallback.value, (n) => n.toString())
+
+  expect(selected()).toMatchObject({ _tag: "Success", value: "123", waiting: true })
+
+  raw.value = AsyncResult.success(456)
+  expect(selected()).toMatchObject({ _tag: "Success", value: "456", waiting: false })
+})
+
+it("withDataFallback: does not mask Failure without previousSuccess", () => {
+  const fail = AsyncResult.failure<number, string>(Cause.fail("boom"))
+  const raw = shallowRef<AsyncResult.AsyncResult<number, string>>(fail)
+  const out = withDataFallback(raw, { placeholderData: 1, initialData: 2 })
+
+  // Failure has no value — old gate would have fabricated Success; must pass Failure through
+  expect(out.value).toBe(fail)
+  expect(AsyncResult.isFailure(out.value)).toBe(true)
+})
+
+it("withDataFallback: Failure with previousSuccess still surfaces as Failure", () => {
+  const fail = AsyncResult.failureWithPrevious<number, string>(Cause.fail("boom"), {
+    previous: Option.some(AsyncResult.success(10))
+  })
+  const raw = shallowRef<AsyncResult.AsyncResult<number, string>>(fail)
+  const out = withDataFallback(raw, { placeholderData: 99 })
+
+  expect(out.value).toBe(fail)
+  expect(AsyncResult.isFailure(out.value)).toBe(true)
+})