@effect-app/vue 4.0.0-beta.29 → 4.0.0-beta.291

package/src/query.ts

@@ -2,33 +2,200 @@
 /* eslint-disable @typescript-eslint/no-unsafe-call */
 /* eslint-disable @typescript-eslint/no-unsafe-return */
 /* eslint-disable @typescript-eslint/no-unsafe-assignment */
-import { type DefaultError, type Enabled, type InitialDataFunction, type NonUndefinedGuard, type PlaceholderDataFunction, type QueryKey, type QueryObserverOptions, type QueryObserverResult, type RefetchOptions, useQuery as useTanstackQuery, useQueryClient, type UseQueryDefinedReturnType, type UseQueryReturnType } from "@tanstack/vue-query"
-import { Array, Cause, Effect, Exit, flow, Option, S, type ServiceMap } from "effect-app"
-import { type Req } from "effect-app/client"
-import type { RequestHandler, RequestHandlerWithInput } from "effect-app/client/clientFor"
-import { ServiceUnavailableError } from "effect-app/client/errors"
-import { type Span } from "effect/Tracer"
-import { isHttpClientError } from "effect/unstable/http/HttpClientError"
+/* eslint-disable @typescript-eslint/no-unsafe-member-access */
+import { injectRegistry, useAtomValue } from "@effect/atom-vue"
+import * as Array from "effect-app/Array"
+import { makeQueryKey, type Req } from "effect-app/client"
+import type { ClientForOptions, RequestHandlerWithInput, RequestStreamHandlerWithInput } from "effect-app/client/clientFor"
+import { type CauseException } from "effect-app/client/errors"
+import type * as Context from "effect-app/Context"
+import * as Effect from "effect-app/Effect"
+import * as Option from "effect-app/Option"
+import type * as Cause from "effect/Cause"
+import * as Exit from "effect/Exit"
+import * as Stream from "effect/Stream"
 import * as AsyncResult from "effect/unstable/reactivity/AsyncResult"
-import { computed, type ComputedRef, type MaybeRefOrGetter, ref, shallowRef, watch, type WatchSource } from "vue"
-import { makeQueryKey, reportRuntimeError } from "./lib.js"
+import * as Atom from "effect/unstable/reactivity/Atom"
+import { computed, type ComputedRef, effectScope, type MaybeRefOrGetter, onBeforeUnmount, onMounted, onScopeDispose, ref, toValue, type WatchSource } from "vue"
+import { type AtomClientRuntime, type AtomQueryOptions, awaitAtomResult, buildQueryFamily, buildStreamQueryFamily, disabledQueryAtom, isStaleResult, refreshAtomWithCurrentSpan, staleTimeMsOf, withQueryOptions } from "./atomQuery.ts"
+import { latestDefined } from "./suspense.ts"
 
-// we must use interface extends, or we get the dreaded typescript error of isn't portable blabla @tanstack/vue-query/build/modern/types.js
-// but because how they are dealing with some extends clause, we loose all properties except initialData
-// so we actually reconstruct the interfaces here from the ground up :/
+// --- minimal local types (replacing the former @tanstack/vue-query type imports) ---
+type DefaultError = Error
+type QueryKey = ReadonlyArray<unknown>
+/** Options accepted by `refetch()` — kept for source compatibility; the atom path ignores them. */
+export interface RefetchOptions {
+  readonly cancelRefetch?: boolean
+  readonly throwOnError?: boolean
+}
+/** The 4th tuple element: private atom/registry handle for client helpers. */
+export interface QueryHandle<A = unknown, E = unknown> {
+  readonly awaitResult: () => Effect.Effect<A, E, never>
+  readonly refetch: () => Effect.Effect<A, E, never>
+  readonly refresh: () => void
+  readonly registry: ReturnType<typeof injectRegistry>
+  readonly atom: ComputedRef<Atom.Atom<AsyncResult.AsyncResult<A, E>>>
+}
+export interface QueryView<A, E> extends QueryHandle<A, E> {
+  readonly result: ComputedRef<AsyncResult.AsyncResult<A, E>>
+  readonly data: ComputedRef<A | undefined>
+}
+
+const useScopedSuspenseSetup = <A>(setup: () => A) => {
+  const scope = effectScope()
+  const controller = new AbortController()
+  const value = scope.run(setup)
+  if (value === undefined) {
+    throw new Error("Internal Error: atom suspense setup scope did not initialize")
+  }
+
+  const isMounted = ref(true)
+  let stopped = false
+  const stop = () => {
+    if (stopped) return
+    stopped = true
+    isMounted.value = false
+    controller.abort()
+    scope.stop()
+  }
+  onBeforeUnmount(stop)
+  onScopeDispose(stop)
+
+  return [value, isMounted, controller.signal] as const
+}
+
+export interface QueryCacheUpdater {
+  readonly update: <I, A, E, R, Request extends Req, Name extends string>(
+    registry: ReturnType<typeof injectRegistry>,
+    query: RequestHandlerWithInput<I, A, E, R, Request, Name>,
+    input: I,
+    updater: (data: NoInfer<A>) => NoInfer<A>
+  ) => void
+}
+
+// retained generic aliases so the exported option-interface arity is unchanged for consumers
+export type UseQueryReturnType<A = any, E = any> = QueryHandle<A, E>
+export type UseQueryDefinedReturnType<A = any, E = any> = QueryHandle<A, E>
+export type QueryObserverResult<A = any, _E = any> = AsyncResult.AsyncResult<A, any>
+export type SuspenseQueryTuple<A, E> = readonly [
+  ComputedRef<AsyncResult.AsyncResult<A, E>>,
+  ComputedRef<A>,
+  (options?: RefetchOptions) => Effect.Effect<A, E, never>,
+  QueryHandle<A, E>
+]
+
+export type SuspenseQueryView<A, E> =
+  & Omit<QueryView<A, E>, "data">
+  & {
+    readonly data: ComputedRef<A>
+  }
+  & SuspenseQueryTuple<A, E>
+
+export type QueryAtomFamily<I, A, E> = (input: I) => Atom.Atom<AsyncResult.AsyncResult<A, E>>
+export type StreamQueryAtomFamily<I, A, E> = (input: I) => Atom.Writable<Atom.PullResult<A, E>, void>
+
+interface QueryFamilyDescriptor<I, A, E> {
+  readonly id: string
+  readonly handler: (i: I) => Effect.Effect<A, E, any>
+  readonly options?: ClientForOptions
+  readonly queryKeyProjectionHash?: string
+}
+
+interface StreamQueryFamilyDescriptor<I, A, E> {
+  readonly id: string
+  readonly handler: (i: I) => Stream.Stream<A, E, any>
+  readonly options?: ClientForOptions
+  readonly queryKeyProjectionHash?: string
+}
+
+const queryFamilyCacheKey = (
+  q: { readonly id: string; readonly options?: ClientForOptions; readonly queryKeyProjectionHash?: string }
+) => `${makeQueryKey(q).join("/")}:${q.queryKeyProjectionHash ?? ""}`
+
+// One atom family per request shape, keyed by the stable query key + projection hash (not the
+// handler object — `clientFor` returns a fresh proxy per call, so the object isn't shareable).
+// Module-level + key-indexed => the family is process-global, so the same request+input read
+// the same atom across components/pages => cross-page caching via the global registry.
+const queryFamilyByKey = new Map<string, any>()
+const getQueryFamily = <I, A, E>(
+  rt: AtomClientRuntime,
+  q: QueryFamilyDescriptor<I, A, E>
+): QueryAtomFamily<I, A, E> => {
+  const key = queryFamilyCacheKey(q)
+  let f = queryFamilyByKey.get(key)
+  if (!f) {
+    f = buildQueryFamily(rt, q)
+    queryFamilyByKey.set(key, f)
+  }
+  return f
+}
+
+const streamQueryFamilyByKey = new Map<string, any>()
+const getStreamQueryFamily = <I, A, E>(
+  rt: AtomClientRuntime,
+  q: StreamQueryFamilyDescriptor<I, A, E>
+): StreamQueryAtomFamily<I, A, E> => {
+  const key = queryFamilyCacheKey(q)
+  let f = streamQueryFamilyByKey.get(key)
+  if (!f) {
+    f = buildStreamQueryFamily(rt, q)
+    streamQueryFamilyByKey.set(key, f)
+  }
+  return f
+}
+
+const makeAtomQueryCacheUpdater = (warnIfMissing: boolean): QueryCacheUpdater => ({
+  update: (registry, query, input) => {
+    const family = queryFamilyByKey.get(queryFamilyCacheKey(query))
+    if (!family) {
+      if (warnIfMissing) {
+        console.warn(`Query ${query.id} has not been used yet; nothing to update`)
+      }
+      return
+    }
+    registry.refresh(family(input))
+  }
+})
+
+export const atomQueryCacheUpdater = makeAtomQueryCacheUpdater(true)
+export const optionalAtomQueryCacheUpdater = makeAtomQueryCacheUpdater(false)
+
+export const combineQueryCacheUpdaters = (first: QueryCacheUpdater, second: QueryCacheUpdater): QueryCacheUpdater => ({
+  update: (registry, query, input, updater) => {
+    first.update(registry, query, input, updater)
+    second.update(registry, query, input, updater)
+  }
+})
+
+let activeQueryCacheUpdater = atomQueryCacheUpdater
+
+export const setQueryCacheUpdater = (updater: QueryCacheUpdater) => {
+  activeQueryCacheUpdater = updater
+}
+
+// Atom-engine query options (formerly reconstructed from @tanstack/vue-query types).
+// The generic arity is kept so the exported interface signatures are unchanged for consumers.
 export interface CustomUseQueryOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
   TData = TQueryFnData,
   TQueryData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey
-> extends
-  Omit<
-    QueryObserverOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey>,
-    "queryKey" | "queryFn" | "initialData" | "enabled" | "placeholderData"
-  >
-{
-  enabled?: MaybeRefOrGetter<boolean | undefined> | (() => Enabled<TQueryFnData, TError, TQueryData, TQueryKey>)
+> {
+  readonly enabled?: MaybeRefOrGetter<boolean | undefined>
+  /** stale threshold in ms (or a Duration input) */
+  readonly staleTime?: number
+  /** garbage-collect after idle, ms (or "infinity") */
+  readonly gcTime?: number | "infinity"
+  readonly refetchOnWindowFocus?: boolean
+  readonly structuralSharing?: boolean
+  /** poll: re-fetch every N ms (tanstack refetchInterval) */
+  readonly refetchInterval?: number
+  readonly select?: (data: TQueryFnData) => TData
+  /** accepted for source compatibility; not used by the atom engine */
+  readonly retry?: boolean | number
+  readonly meta?: Record<string, unknown>
+  readonly _phantom?: [TQueryData, TQueryKey, TError]
 }
 
 // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
@@ -41,11 +208,8 @@ export interface CustomUndefinedInitialQueryOptions<
   TQueryData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey
 > extends CustomUseQueryOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey> {
-  initialData?: undefined | InitialDataFunction<NonUndefinedGuard<TQueryFnData>> | NonUndefinedGuard<TQueryFnData>
-  placeholderData?:
-    | undefined
-    | NonFunctionGuard<TQueryData>
-    | PlaceholderDataFunction<NonFunctionGuard<TQueryData>, TError, NonFunctionGuard<TQueryData>, TQueryKey>
+  readonly initialData?: TQueryFnData | (() => TQueryFnData) | undefined
+  readonly placeholderData?: NonFunctionGuard<TQueryData> | ((prev: TQueryData | undefined) => TQueryData) | undefined
 }
 export interface CustomDefinedInitialQueryOptions<
   TQueryFnData = unknown,
@@ -54,11 +218,8 @@ export interface CustomDefinedInitialQueryOptions<
   TQueryData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey
 > extends CustomUseQueryOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey> {
-  initialData: NonUndefinedGuard<TQueryFnData> | (() => NonUndefinedGuard<TQueryFnData>)
-  placeholderData?:
-    | undefined
-    | NonFunctionGuard<TQueryData>
-    | PlaceholderDataFunction<NonFunctionGuard<TQueryData>, TError, NonFunctionGuard<TQueryData>, TQueryKey>
+  readonly initialData: TQueryFnData | (() => TQueryFnData)
+  readonly placeholderData?: NonFunctionGuard<TQueryData> | ((prev: TQueryData | undefined) => TQueryData) | undefined
 }
 
 export interface CustomDefinedPlaceholderQueryOptions<
@@ -68,35 +229,387 @@ export interface CustomDefinedPlaceholderQueryOptions<
   TQueryData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey
 > extends CustomUseQueryOptions<TQueryFnData, TError, TData, TQueryData, TQueryKey> {
-  initialData?: NonUndefinedGuard<TQueryFnData> | (() => NonUndefinedGuard<TQueryFnData>) | undefined
-  placeholderData:
-    | NonFunctionGuard<TQueryData>
-    | PlaceholderDataFunction<NonFunctionGuard<TQueryData>, TError, NonFunctionGuard<TQueryData>, TQueryKey>
+  readonly initialData?: TQueryFnData | (() => TQueryFnData) | undefined
+  readonly placeholderData: NonFunctionGuard<TQueryData> | ((prev: TQueryData | undefined) => TQueryData)
+}
+
+export interface AtomQueryNewOptions<TQueryFnData = unknown, TData = TQueryFnData> {
+  readonly enabled?: MaybeRefOrGetter<boolean | undefined>
+  readonly staleTime?: number
+  readonly idleTTL?: number | "infinity"
+  readonly gcTime?: number | "infinity"
+  readonly revalidateOnFocus?: boolean
+  readonly refetchOnWindowFocus?: boolean
+  readonly structuralSharing?: boolean
+  readonly refreshEvery?: number
+  readonly refetchInterval?: number
+  readonly select?: (data: TQueryFnData) => TData
+}
+
+export interface AtomStreamQueryOptions {
+  readonly staleTime?: number
+  readonly idleTTL?: number | "infinity"
+  readonly gcTime?: number | "infinity"
+  readonly revalidateOnFocus?: boolean
+  readonly refetchOnWindowFocus?: boolean
+  readonly refreshEvery?: number
+  readonly refetchInterval?: number
+}
+
+const normalizeQueryOptions = (options?: {
+  readonly staleTime?: number
+  readonly gcTime?: number | "infinity"
+  readonly idleTTL?: number | "infinity"
+  readonly refetchOnWindowFocus?: boolean
+  readonly revalidateOnFocus?: boolean
+  readonly structuralSharing?: boolean
+  readonly refetchInterval?: number
+  readonly refreshEvery?: number
+}): AtomQueryOptions => {
+  const out: {
+    staleTime?: number
+    gcTime?: number | "infinity"
+    revalidateOnFocus?: boolean
+    structuralSharing?: boolean
+    refetchInterval?: number
+  } = {}
+  if (options?.staleTime !== undefined) out.staleTime = options.staleTime
+  const gcTime = options?.idleTTL ?? options?.gcTime
+  if (gcTime !== undefined) out.gcTime = gcTime
+  const revalidateOnFocus = options?.revalidateOnFocus ?? options?.refetchOnWindowFocus
+  if (revalidateOnFocus !== undefined) out.revalidateOnFocus = revalidateOnFocus
+  if (options?.structuralSharing !== undefined) out.structuralSharing = options.structuralSharing
+  const refetchInterval = options?.refreshEvery ?? options?.refetchInterval
+  if (refetchInterval !== undefined) out.refetchInterval = refetchInterval
+  return out
+}
+
+export const useAtomQuery = <A, E>(
+  atom: () => Atom.Atom<AsyncResult.AsyncResult<A, E>>
+): QueryView<A, E> => {
+  const registry = injectRegistry()
+  const atomRef = computed(atom)
+  const atomResult = useAtomValue(() => atomRef.value)
+  const result = computed(() => atomResult.value)
+  const refresh = () => registry.refresh(atomRef.value)
+  const awaitResult = () => awaitAtomResult(registry, atomRef.value)
+  const refetch = () =>
+    Effect.gen(function*() {
+      yield* refreshAtomWithCurrentSpan(registry, atomRef.value)
+      return yield* awaitResult()
+    })
+  const data = computed(() => Option.getOrUndefined(AsyncResult.value(result.value)))
+
+  return {
+    result,
+    data,
+    awaitResult,
+    refetch,
+    refresh,
+    registry,
+    atom: atomRef
+  }
+}
+
+export const useAtomSuspense = <A, E>(
+  atom: () => Atom.Atom<AsyncResult.AsyncResult<A, E>>
+): Promise<SuspenseQueryView<A, E>> => {
+  const [{ view, data }, isMounted, signal] = useScopedSuspenseSetup(() => {
+    const view = useAtomQuery(atom)
+    const data = latestDefined(() => view.data.value, "atom suspense")
+    return { view, data }
+  })
+
+  const eff = Effect.gen(function*() {
+    const exit = yield* view.awaitResult().pipe(Effect.exit)
+    if (!isMounted.value) {
+      return yield* Effect.interrupt
+    }
+    if (Exit.isFailure(exit)) {
+      return yield* Exit.failCause(exit.cause)
+    }
+
+    const fetch = (_options?: RefetchOptions) => view.refetch()
+    const handle = {
+      awaitResult: view.awaitResult,
+      refetch: view.refetch,
+      refresh: view.refresh,
+      registry: view.registry,
+      atom: view.atom
+    }
+    return Object.assign(
+      [
+        view.result,
+        data,
+        fetch,
+        handle
+      ] as const,
+      {
+        ...view,
+        data
+      }
+    )
+  })
+
+  return Effect.runPromise(eff, { signal })
+}
+
+export type StreamQueryPullValue<A> = {
+  readonly done: boolean
+  readonly items: ReadonlyArray<A>
+}
+
+export interface StreamQueryView<A, E> {
+  readonly result: ComputedRef<Atom.PullResult<A, E>>
+  readonly items: ComputedRef<ReadonlyArray<A>>
+  readonly latest: ComputedRef<A | undefined>
+  readonly done: ComputedRef<boolean>
+  readonly awaitResult: () => Effect.Effect<StreamQueryPullValue<A>, E | Cause.NoSuchElementError, never>
+  readonly pull: () => void
+  readonly pullAndAwait: () => Effect.Effect<StreamQueryPullValue<A>, E | Cause.NoSuchElementError, never>
+  readonly refresh: () => void
+  readonly registry: ReturnType<typeof injectRegistry>
+  readonly atom: ComputedRef<Atom.Writable<Atom.PullResult<A, E>, void>>
+}
+
+export const useAtomStreamQuery = <A, E>(
+  atom: () => Atom.Writable<Atom.PullResult<A, E>, void>
+): StreamQueryView<A, E> => {
+  const registry = injectRegistry()
+  const atomRef = computed(atom)
+  const atomResult = useAtomValue(() => atomRef.value)
+  const result = computed(() => atomResult.value)
+  const pull = () => registry.set(atomRef.value, void 0)
+  const refresh = () => registry.refresh(atomRef.value)
+  const awaitResult = () => awaitAtomResult(registry, atomRef.value)
+  const pullAndAwait = () =>
+    Effect.gen(function*() {
+      pull()
+      return yield* awaitResult()
+    })
+  const items = computed(() =>
+    Option.getOrElse(
+      Option.map(AsyncResult.value(result.value), (_) => _.items),
+      () => []
+    )
+  )
+  const latest = computed(() => items.value.at(-1))
+  const done = computed(() =>
+    Option.getOrElse(
+      Option.map(AsyncResult.value(result.value), (_) => _.done),
+      () => false
+    )
+  )
+
+  return {
+    result,
+    items,
+    latest,
+    done,
+    awaitResult,
+    pull,
+    pullAndAwait,
+    refresh,
+    registry,
+    atom: atomRef
+  }
 }
 
-export class KnownFiberFailure<E> extends Error {
-  readonly error: unknown
-  constructor(public effectCause: Cause.Cause<E>) {
-    super("Query failed with cause: " + Cause.squash(effectCause))
-    this.error = Cause.squash(effectCause)
+const optionValue = <I>(
+  arr: I | WatchSource<I> | undefined | WatchSource<Option.Option<I>>,
+  options?: { readonly mode?: "optional"; readonly enabled?: MaybeRefOrGetter<boolean | undefined> }
+): readonly [{ readonly value: I }, ComputedRef<boolean>] => {
+  if (options?.mode === "optional") {
+    const getOption: () => Option.Option<I> = typeof arr === "function"
+      ? arr as () => Option.Option<I>
+      : () => (arr as { value: Option.Option<I> }).value
+    return [
+      {
+        get value() {
+          return Option.getOrUndefined(getOption()) as I
+        }
+      },
+      computed(() => Option.isSome(getOption()))
+    ] as const
   }
+  const req = !arr
+    ? ({ value: undefined as I })
+    : typeof arr === "function"
+    ? ({
+      get value() {
+        return (arr as any)()
+      }
+    })
+    : (ref(arr) as any)
+  const enabled = options?.enabled
+  return [req, computed(() => enabled === undefined ? true : !!toValue(enabled))] as const
 }
 
-export const makeQuery = <R>(getRuntime: () => ServiceMap.ServiceMap<R>) => {
+const observedAtom = <A, E>(
+  atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>,
+  options?: {
+    readonly staleTime?: number
+    readonly gcTime?: number | "infinity"
+    readonly idleTTL?: number | "infinity"
+    readonly refetchOnWindowFocus?: boolean
+    readonly revalidateOnFocus?: boolean
+    readonly structuralSharing?: boolean
+    readonly refetchInterval?: number
+    readonly refreshEvery?: number
+  }
+): Atom.Atom<AsyncResult.AsyncResult<A, E>> => withQueryOptions(atom, normalizeQueryOptions(options))
+
+const observedStreamAtom = <A, E>(
+  atom: Atom.Writable<Atom.PullResult<A, E>, void>,
+  options?: AtomStreamQueryOptions
+): Atom.Writable<Atom.PullResult<A, E>, void> => {
+  let next = atom
+  const refetchInterval = options?.refreshEvery ?? options?.refetchInterval
+  if (refetchInterval !== undefined) next = Atom.withRefresh(refetchInterval)(next)
+  const gcTime = options?.idleTTL ?? options?.gcTime
+  if (gcTime === "infinity") return Atom.keepAlive(next)
+  if (gcTime !== undefined) return Atom.setIdleTTL(next, gcTime)
+  return next
+}
+
+const queryAtomFor = <I, A, E, TData>(
+  rt: AtomClientRuntime,
+  q: QueryFamilyDescriptor<I, A, E>,
+  arg: I,
+  options?: Omit<AtomQueryNewOptions<A, TData>, "select"> | Omit<CustomUseQueryOptions<A, E, TData>, "select">
+): Atom.Atom<AsyncResult.AsyncResult<A, E>> => {
+  const family = getQueryFamily(rt, q)
+  return observedAtom(family(arg), options)
+}
+
+const makeQueryView = <I, A, E, TData>(
+  getAtomRt: () => AtomClientRuntime,
+  q: QueryFamilyDescriptor<I, A, E>,
+  arg: I | WatchSource<I> | undefined | WatchSource<Option.Option<I>>,
+  options?: (AtomQueryNewOptions<A, TData> | CustomUseQueryOptions<A, E, TData>) & {
+    readonly mode?: "optional"
+  }
+): QueryView<TData, E> => {
+  const atomRt = getAtomRt()
+  const registry = injectRegistry()
+  const [req, enabledRef] = optionValue<I>(arg, options)
+  const family = getQueryFamily(atomRt, q)
+  const atomRef = computed(() => enabledRef.value ? observedAtom(family(req.value), options) : disabledQueryAtom)
+  const rawResult = useAtomValue(() => atomRef.value) as ComputedRef<AsyncResult.AsyncResult<A, E>>
+  const select = options?.select
+  const result = (select
+    ? computed(() => AsyncResult.map(rawResult.value, select))
+    : rawResult) as ComputedRef<AsyncResult.AsyncResult<TData, E>>
+  const refresh = () => registry.refresh(atomRef.value)
+  const awaitResult = () =>
+    select
+      ? awaitAtomResult(registry, atomRef.value).pipe(Effect.map(select))
+      : awaitAtomResult(registry, atomRef.value)
+  const refetch = () =>
+    Effect.gen(function*() {
+      yield* refreshAtomWithCurrentSpan(registry, atomRef.value)
+      return yield* awaitResult()
+    })
+  const staleMs = staleTimeMsOf(normalizeQueryOptions(options))
+  onMounted(() => {
+    if (!enabledRef.value) return
+    if (isStaleResult(registry.get(atomRef.value), staleMs)) refresh()
+  })
+  const data = computed(() => Option.getOrUndefined(AsyncResult.value(result.value)))
+
+  return {
+    result,
+    data,
+    awaitResult,
+    refetch,
+    refresh,
+    registry,
+    atom: atomRef
+  }
+}
+
+export const makeQueryFamily = <R>(_getRuntime: () => Context.Context<R>, getAtomRt: () => AtomClientRuntime) => {
+  const useQueryFamily: {
+    <I, E, A, Request extends Req, Name extends string>(
+      q: RequestHandlerWithInput<I, A, E, R, Request, Name>
+    ): QueryAtomFamily<I, A, E>
+  } = <I, E, A, Request extends Req, Name extends string>(
+    q: RequestHandlerWithInput<I, A, E, R, Request, Name>
+  ) => getQueryFamily(getAtomRt(), q)
+
+  return useQueryFamily
+}
+
+export const makeQueryAtom = <R>(_getRuntime: () => Context.Context<R>, getAtomRt: () => AtomClientRuntime) => {
+  const useQueryAtom: {
+    <I, E, A, Request extends Req, Name extends string>(
+      q: RequestHandlerWithInput<I, A, E, R, Request, Name>
+    ): {
+      <TData = A>(
+        arg: I,
+        options?: Omit<AtomQueryNewOptions<A, TData>, "select">
+      ): Atom.Atom<AsyncResult.AsyncResult<A, E>>
+    }
+  } = <I, E, A, Request extends Req, Name extends string>(
+    q: RequestHandlerWithInput<I, A, E, R, Request, Name>
+  ) =>
+  <TData = A>(
+    arg: I,
+    options?: Omit<AtomQueryNewOptions<A, TData>, "select">
+  ) => queryAtomFor(getAtomRt(), q, arg, options)
+
+  return useQueryAtom
+}
+
+export const makeQueryNew = <R>(_getRuntime: () => Context.Context<R>, getAtomRt: () => AtomClientRuntime) => {
+  const useQueryNew: {
+    <I, E, A, Request extends Req, Name extends string>(
+      q: RequestHandlerWithInput<I, A, E, R, Request, Name>
+    ): {
+      <TData = A>(
+        arg: WatchSource<Option.Option<I>>,
+        options: Omit<AtomQueryNewOptions<A, TData>, "enabled"> & { mode: "optional" }
+      ): QueryView<TData, E>
+
+      <TData = A>(
+        arg: I | WatchSource<I> | undefined,
+        options?: AtomQueryNewOptions<A, TData>
+      ): QueryView<TData, E>
+    }
+  } = <I, E, A, Request extends Req, Name extends string>(
+    q: RequestHandlerWithInput<I, A, E, R, Request, Name>
+  ) =>
+  <TData = A>(
+    arg: I | WatchSource<I> | undefined | WatchSource<Option.Option<I>>,
+    options?: AtomQueryNewOptions<A, TData> & { readonly mode?: "optional" }
+  ) => makeQueryView<I, A, E, TData>(getAtomRt, q, arg, options)
+
+  return useQueryNew
+}
+
+export const makeQuery = <R>(_getRuntime: () => Context.Context<R>, getAtomRt: () => AtomClientRuntime) => {
   const useQuery_: {
     <I, A, E, Request extends Req, Name extends string>(
-      q:
-        | RequestHandlerWithInput<I, A, E, R, Request, Name>
-        | RequestHandler<A, E, R, Request, Name>
+      q: RequestHandlerWithInput<I, A, E, R, Request, Name>
     ): {
+      <TData = A>(
+        arg: WatchSource<Option.Option<I>>,
+        options: Omit<CustomUndefinedInitialQueryOptions<A, E, TData>, "enabled"> & { mode: "optional" }
+      ): readonly [
+        ComputedRef<AsyncResult.AsyncResult<TData, E>>,
+        ComputedRef<TData | undefined>,
+        (options?: RefetchOptions) => Effect.Effect<QueryObserverResult<TData, CauseException<E>>>,
+        UseQueryDefinedReturnType<TData, CauseException<E>>
+      ]
+
       <TData = A>(
         arg: I | WatchSource<I> | undefined,
         options?: CustomUndefinedInitialQueryOptions<A, E, TData>
       ): readonly [
         ComputedRef<AsyncResult.AsyncResult<TData, E>>,
         ComputedRef<TData | undefined>,
-        (options?: RefetchOptions) => Effect.Effect<QueryObserverResult<TData, KnownFiberFailure<E>>, never, never>,
-        UseQueryDefinedReturnType<TData, KnownFiberFailure<E>>
+        (options?: RefetchOptions) => Effect.Effect<QueryObserverResult<TData, CauseException<E>>>,
+        UseQueryDefinedReturnType<TData, CauseException<E>>
       ]
 
       <TData = A>(
@@ -105,8 +618,8 @@ export const makeQuery = <R>(getRuntime: () => ServiceMap.ServiceMap<R>) => {
       ): readonly [
         ComputedRef<AsyncResult.AsyncResult<TData, E>>,
         ComputedRef<TData>,
-        (options?: RefetchOptions) => Effect.Effect<QueryObserverResult<TData, KnownFiberFailure<E>>, never, never>,
-        UseQueryDefinedReturnType<TData, KnownFiberFailure<E>>
+        (options?: RefetchOptions) => Effect.Effect<QueryObserverResult<TData, CauseException<E>>>,
+        UseQueryDefinedReturnType<TData, CauseException<E>>
       ]
 
       <TData = A>(
@@ -115,253 +628,178 @@ export const makeQuery = <R>(getRuntime: () => ServiceMap.ServiceMap<R>) => {
       ): readonly [
         ComputedRef<AsyncResult.AsyncResult<TData, E>>,
         ComputedRef<TData>,
-        (options?: RefetchOptions) => Effect.Effect<QueryObserverResult<TData, KnownFiberFailure<E>>, never, never>,
-        UseQueryDefinedReturnType<TData, KnownFiberFailure<E>>
+        (options?: RefetchOptions) => Effect.Effect<QueryObserverResult<TData, CauseException<E>>>,
+        UseQueryDefinedReturnType<TData, CauseException<E>>
       ]
     }
   } = <I, A, E, Request extends Req, Name extends string>(
-    q:
-      | RequestHandlerWithInput<I, A, E, R, Request, Name>
-      | RequestHandler<A, E, R, Request, Name>
+    q: RequestHandlerWithInput<I, A, E, R, Request, Name>
   ) =>
   <TData = A>(
-    arg: I | WatchSource<I> | undefined,
-    // todo QueryKey type would be [string, ...string[]], but with I it would be [string, ...string[], I]
+    arg: I | WatchSource<I> | undefined | WatchSource<Option.Option<I>>,
     options?: any
-    // TODO
   ) => {
-    // we wrap into KnownFiberFailure because we want to keep the full cause of the failure.
-    const runPromise = flow(Effect.runPromiseExitWith(getRuntime()), (_) =>
-      _.then(
-        Exit.match({
-          onFailure: (cause) => Promise.reject(new KnownFiberFailure(cause)),
-          onSuccess: (value) => Promise.resolve(value)
-        })
-      ))
-    const arr = arg
-    const req: { value: I } = !arg
-      ? undefined
-      : typeof arr === "function"
-      ? ({
-        get value() {
-          return (arr as any)()
-        }
-      } as any)
-      : ref(arg)
-    const queryKey = makeQueryKey(q)
-    const handler = q.handler
-
-    const defaultOptions = {
-      // we do not want to throw errors, because we turn the success and error responses into a Result type
-      // why don't we turn the error/success response into a Result type before returning to tanstack query? because we want to leverage tanstack query's retry and caching mechanism, which relies on throwing errors to trigger retries, and we don't want to interfere with that by catching the errors too early.
-      // but if we allow tanstack query to throw, it will trigger the error boundary in Vue - via a "watcher callback" error - which we currently report and log, which is not what we want.
-      // TODO: we might want to rethink the strategy of how to handle errors that happen after the initial load.
-      // For suspense, the initial load is captured by the suspense boundary.
-      // For subsequent loads (or non suspense use) we currently are required to use the QueryResult component to conditionally render error/loading/etc.
-      throwOnError: false
-    }
+    const view = makeQueryView<I, A, E, TData>(getAtomRt, q, arg, options)
 
-    const r = useTanstackQuery<A, KnownFiberFailure<E>, TData>(
-      Effect.isEffect(handler)
-        ? {
-          ...defaultOptions,
-          ...options,
-          retry: (retryCount, error) => {
-            if (error instanceof KnownFiberFailure) {
-              if (!isHttpClientError(error.error) && !S.is(ServiceUnavailableError)(error.error)) {
-                return false
-              }
-            }
-
-            return retryCount < 5
-          },
-          queryKey,
-          queryFn: ({ meta, signal }) =>
-            runPromise(
-              handler
-                .pipe(
-                  Effect.tapCauseIf(Cause.hasDies, (cause) => reportRuntimeError(cause)),
-                  Effect.withSpan(`query ${q.id}`, {}, { captureStackTrace: false }),
-                  meta?.["span"] ? Effect.withParentSpan(meta["span"] as Span) : (_) => _
-                ),
-              { signal }
-            )
-        }
-        : {
-          ...defaultOptions,
-          ...options,
-          retry: (retryCount, error) => {
-            if (error instanceof KnownFiberFailure) {
-              if (!isHttpClientError(error.error) && !S.is(ServiceUnavailableError)(error.error)) {
-                return false
-              }
-            }
-
-            return retryCount < 5
-          },
-          queryKey: [...queryKey, req],
-          queryFn: ({ meta, signal }) =>
-            runPromise(
-              handler(req.value)
-                .pipe(
-                  Effect.tapCauseIf(Cause.hasDies, (cause) => reportRuntimeError(cause)),
-                  Effect.withSpan(`query ${q.id}`, {}, { captureStackTrace: false }),
-                  meta?.["span"] ? Effect.withParentSpan(meta["span"] as Span) : (_) => _
-                ),
-              { signal }
-            )
-        }
-    )
-
-    const latestSuccess = shallowRef<TData>()
-    const result = computed((): AsyncResult.AsyncResult<TData, E> =>
-      swrToQuery({
-        error: r.error.value ?? undefined,
-        data: r.data.value === undefined ? latestSuccess.value : r.data.value, // we fall back to existing data, as tanstack query might loose it when the key changes
-        isValidating: r.isFetching.value
-      })
-    )
-    // not using `computed` here as we have a circular dependency
-    watch(result, (value) => latestSuccess.value = Option.getOrUndefined(AsyncResult.value(value)), { immediate: true })
+    // 4th element is internal-only; the public `.suspense()` Promise boundary lives in makeClient.
+    const handle = {
+      awaitResult: view.awaitResult,
+      refetch: view.refetch,
+      refresh: view.refresh,
+      registry: view.registry,
+      atom: view.atom
+    }
 
     return [
-      result,
-      computed(() => latestSuccess.value),
-      // one thing to keep in mind is that span will be disconnected as Context does not pass from outside.
-      // TODO: consider how we should handle the Result here which is `QueryObserverResult<A, E>`
-      // and always ends up in the success channel, even when error..
-      (options?: RefetchOptions) =>
-        Effect.currentSpan.pipe(
-          Effect.orElseSucceed(() => null),
-          Effect.flatMap((span) => Effect.promise(() => r.refetch({ ...options, updateMeta: { span } })))
-        ),
-      r
+      view.result,
+      view.data,
+      (_options?: RefetchOptions) => view.refetch(),
+      handle
     ] as any
   }
 
-  function swrToQuery<E, A>(r: {
-    error: KnownFiberFailure<E> | undefined
-    data: A | undefined
-    isValidating: boolean
-  }): AsyncResult.AsyncResult<A, E> {
-    if (r.error !== undefined) {
-      return AsyncResult.failureWithPrevious(
-        r.error.effectCause,
-        {
-          previous: r.data === undefined ? Option.none() : Option.some(AsyncResult.success(r.data)),
-          waiting: r.isValidating
-        }
-      )
-    }
-    if (r.data !== undefined) {
-      return AsyncResult.success<A, E>(r.data, { waiting: r.isValidating })
-    }
-
-    return AsyncResult.initial(r.isValidating)
-  }
-
   const useQuery: {
     /**
      * Effect results are passed to the caller, including errors.
+     * When `I = void` the input argument may be omitted.
      * @deprecated use client helpers instead (.query())
      */
-    <E, A, Request extends Req, Name extends string>(
-      self: RequestHandler<A, E, R, Request, Name>
+    <I, E, A, Request extends Req, Name extends string>(
+      self: RequestHandlerWithInput<I, A, E, R, Request, Name>
     ): {
-      // required options, with initialData
-      /**
-       * Effect results are passed to the caller, including errors.
-       */
       <TData = A>(
-        options: CustomDefinedInitialQueryOptions<A, KnownFiberFailure<E>, TData>
+        arg: WatchSource<Option.Option<I>>,
+        options: Omit<CustomUndefinedInitialQueryOptions<A, CauseException<E>, TData>, "enabled"> & { mode: "optional" }
       ): readonly [
         ComputedRef<AsyncResult.AsyncResult<TData, E>>,
-        ComputedRef<TData>,
-        (options?: RefetchOptions) => Effect.Effect<QueryObserverResult<TData, KnownFiberFailure<E>>>,
+        ComputedRef<TData | undefined>,
+        (options?: RefetchOptions) => Effect.Effect<QueryObserverResult<TData, CauseException<E>>>,
         UseQueryReturnType<any, any>
       ]
       <TData = A>(
-        options: CustomDefinedPlaceholderQueryOptions<A, E, TData>
+        arg: I | WatchSource<I>,
+        options: CustomDefinedInitialQueryOptions<A, CauseException<E>, TData>
       ): readonly [
         ComputedRef<AsyncResult.AsyncResult<TData, E>>,
         ComputedRef<TData>,
-        (options?: RefetchOptions) => Effect.Effect<QueryObserverResult<TData, KnownFiberFailure<E>>, never, never>,
-        UseQueryDefinedReturnType<TData, KnownFiberFailure<E>>
-      ]
-      // optional options, optional A
-      /**
-       * Effect results are passed to the caller, including errors.
-       */
-      <TData = A>(options?: CustomUndefinedInitialQueryOptions<A, KnownFiberFailure<E>, TData>): readonly [
-        ComputedRef<AsyncResult.AsyncResult<A, E>>,
-        ComputedRef<A | undefined>,
-        (options?: RefetchOptions) => Effect.Effect<QueryObserverResult<TData, KnownFiberFailure<E>>>,
+        (options?: RefetchOptions) => Effect.Effect<QueryObserverResult<TData, CauseException<E>>>,
         UseQueryReturnType<any, any>
       ]
-    }
-    /**
-     * Effect results are passed to the caller, including errors.
-     * @deprecated use client helpers instead (.query())
-     */
-    <Arg, E, A, Request extends Req, Name extends string>(
-      self: RequestHandlerWithInput<Arg, A, E, R, Request, Name>
-    ): {
-      // required options, with initialData
-      /**
-       * Effect results are passed to the caller, including errors.
-       */
       <TData = A>(
-        arg: Arg | WatchSource<Arg>,
-        options: CustomDefinedInitialQueryOptions<A, KnownFiberFailure<E>, TData>
+        arg: I | WatchSource<I>,
+        options: CustomDefinedPlaceholderQueryOptions<A, CauseException<E>, TData>
       ): readonly [
         ComputedRef<AsyncResult.AsyncResult<TData, E>>,
         ComputedRef<TData>,
-        (options?: RefetchOptions) => Effect.Effect<QueryObserverResult<TData, KnownFiberFailure<E>>>,
+        (options?: RefetchOptions) => Effect.Effect<QueryObserverResult<TData, CauseException<E>>>,
         UseQueryReturnType<any, any>
       ]
-      // required options, with placeholderData
-      /**
-       * Effect results are passed to the caller, including errors.
-       */
       <TData = A>(
-        arg: Arg | WatchSource<Arg>,
-        options: CustomDefinedPlaceholderQueryOptions<A, KnownFiberFailure<E>, TData>
-      ): readonly [
-        ComputedRef<AsyncResult.AsyncResult<TData, E>>,
-        ComputedRef<TData>,
-        (options?: RefetchOptions) => Effect.Effect<QueryObserverResult<TData, KnownFiberFailure<E>>>,
-        UseQueryReturnType<any, any>
-      ]
-      // optional options, optional A
-      /**
-       * Effect results are passed to the caller, including errors.
-       */
-      <TData = A>(
-        arg: Arg | WatchSource<Arg>,
-        options?: CustomUndefinedInitialQueryOptions<A, KnownFiberFailure<E>, TData>
+        arg: I | WatchSource<I>,
+        options?: CustomUndefinedInitialQueryOptions<A, CauseException<E>, TData>
       ): readonly [
         ComputedRef<AsyncResult.AsyncResult<TData, E>>,
         ComputedRef<TData | undefined>,
-        (options?: RefetchOptions) => Effect.Effect<QueryObserverResult<TData, KnownFiberFailure<E>>>,
+        (options?: RefetchOptions) => Effect.Effect<QueryObserverResult<TData, CauseException<E>>>,
         UseQueryReturnType<any, any>
       ]
     }
-  } = (
+  } = ((
     self: any
   ) => {
     const q = useQuery_(self)
-
-    return (argOrOptions?: any, options?: any) =>
-      Effect.isEffect(self.handler)
-        ? q(undefined, argOrOptions)
-        : q(argOrOptions, options)
-  }
+    return (arg?: any, options?: any) => q(arg, options)
+  }) as any
   return useQuery
 }
 
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface MakeQuery2<R> extends ReturnType<typeof makeQuery<R>> {}
 
+const streamQueryAtomFor = <I, A, E>(
+  rt: AtomClientRuntime,
+  q: StreamQueryFamilyDescriptor<I, A, E>,
+  arg: I,
+  options?: AtomStreamQueryOptions
+): Atom.Writable<Atom.PullResult<A, E>, void> => {
+  const family = getStreamQueryFamily(rt, q)
+  return observedStreamAtom(family(arg), options)
+}
+
+export const makeStreamQueryFamily = <R>(_getRuntime: () => Context.Context<R>, getAtomRt: () => AtomClientRuntime) => {
+  const useStreamQueryFamily: {
+    <I, E, A, Request extends Req, Name extends string>(
+      q: RequestStreamHandlerWithInput<I, A, E, R, Request, Name>
+    ): StreamQueryAtomFamily<I, A, E>
+  } = <I, E, A, Request extends Req, Name extends string>(
+    q: RequestStreamHandlerWithInput<I, A, E, R, Request, Name>
+  ) => getStreamQueryFamily(getAtomRt(), q)
+
+  return useStreamQueryFamily
+}
+
+export const makeStreamQueryAtom = <R>(_getRuntime: () => Context.Context<R>, getAtomRt: () => AtomClientRuntime) => {
+  const useStreamQueryAtom: {
+    <I, E, A, Request extends Req, Name extends string>(
+      q: RequestStreamHandlerWithInput<I, A, E, R, Request, Name>
+    ): (arg: I, options?: AtomStreamQueryOptions) => Atom.Writable<Atom.PullResult<A, E>, void>
+  } = <I, E, A, Request extends Req, Name extends string>(
+    q: RequestStreamHandlerWithInput<I, A, E, R, Request, Name>
+  ) =>
+  (arg: I, options?: AtomStreamQueryOptions) => streamQueryAtomFor(getAtomRt(), q, arg, options)
+
+  return useStreamQueryAtom
+}
+
+export const makeStreamQueryNew = <R>(_getRuntime: () => Context.Context<R>, getAtomRt: () => AtomClientRuntime) => {
+  const useStreamQueryNew: {
+    <I, E, A, Request extends Req, Name extends string>(
+      q: RequestStreamHandlerWithInput<I, A, E, R, Request, Name>
+    ): (arg: MaybeRefOrGetter<I>, options?: AtomStreamQueryOptions) => StreamQueryView<A, E>
+  } = <I, E, A, Request extends Req, Name extends string>(
+    q: RequestStreamHandlerWithInput<I, A, E, R, Request, Name>
+  ) =>
+  (arg: MaybeRefOrGetter<I>, options?: AtomStreamQueryOptions) =>
+    useAtomStreamQuery(() => streamQueryAtomFor(getAtomRt(), q, toValue(arg), options))
+
+  return useStreamQueryNew
+}
+
+type StreamQueryResult<A, E> = readonly [
+  ComputedRef<AsyncResult.AsyncResult<A[], E>>,
+  ComputedRef<A[] | undefined>,
+  (options?: RefetchOptions) => Effect.Effect<QueryObserverResult<A[], CauseException<E>>>,
+  UseQueryReturnType<any, any>
+]
+
+export const makeStreamQuery = <R>(
+  getRuntime: () => Context.Context<R>,
+  getAtomRt: () => AtomClientRuntime
+) => {
+  const query = makeQuery(getRuntime, getAtomRt)
+  // A stream query is an ordinary atom query over an effect that collects the whole stream
+  // into an array (`Stream.runCollect`). It reuses all the atom machinery (family cache, swr,
+  // invalidation, structural sharing). Note: unlike the old tanstack `streamedQuery`, the result
+  // appears once the stream completes, not incrementally (stream queries are not used today).
+  const streamQuery_: {
+    <I, E, A, Request extends Req, Name extends string>(
+      q: RequestStreamHandlerWithInput<I, A, E, R, Request, Name>
+    ): (arg: I | WatchSource<I>) => StreamQueryResult<A, E>
+  } = (q: any) => {
+    const hook = query({
+      id: q.id,
+      options: q.options,
+      handler: (i: any) => Stream.runCollect(q.handler(i)).pipe(Effect.map((chunk) => [...chunk]))
+    } as any)
+    return (arg?: any) => hook(arg) as any
+  }
+
+  return streamQuery_
+}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface MakeStreamQuery2<R> extends ReturnType<typeof makeStreamQuery<R>> {}
+
 function orPrevious<E, A>(result: AsyncResult.AsyncResult<A, E>) {
   return AsyncResult.isFailure(result) && Option.isSome(result.previousSuccess)
     ? AsyncResult.success(result.previousSuccess.value, { waiting: result.waiting })
@@ -409,29 +847,14 @@ export function composeQueries<
 }
 
 export const useUpdateQuery = () => {
-  const queryClient = useQueryClient()
+  const registry = injectRegistry()
 
   const f: {
-    <A>(
-      query: RequestHandler<A, any, any, any, any>,
-      updater: (data: NoInfer<A>) => NoInfer<A>
-    ): void
-    <I, A>(
-      query: RequestHandlerWithInput<I, A, any, any, any, any>,
+    <I, A, E, R, Request extends Req, Name extends string>(
+      query: RequestHandlerWithInput<I, A, E, R, Request, Name>,
       input: I,
       updater: (data: NoInfer<A>) => NoInfer<A>
     ): void
-  } = (query: any, updateOrInput: any, updaterMaybe?: any) => {
-    const updater = updaterMaybe !== undefined ? updaterMaybe : updateOrInput
-    const key = updaterMaybe !== undefined
-      ? [...makeQueryKey(query), updateOrInput]
-      : makeQueryKey(query)
-    const data = queryClient.getQueryData(key)
-    if (data) {
-      queryClient.setQueryData(key, updater)
-    } else {
-      console.warn(`Query data for key ${key} not found`, key)
-    }
-  }
+  } = (query, input, updater) => activeQueryCacheUpdater.update(registry, query, input, updater)
   return f
 }