@effect-app/vue 4.0.0-beta.3 → 4.0.0-beta.300

package/src/query.ts

@@ -2,33 +2,210 @@
 /* eslint-disable @typescript-eslint/no-unsafe-call */
 /* eslint-disable @typescript-eslint/no-unsafe-return */
 /* eslint-disable @typescript-eslint/no-unsafe-assignment */
+/* 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 { 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"
-import { computed, type ComputedRef, type MaybeRefOrGetter, ref, shallowRef, watch, type WatchSource } from "vue"
-import { makeQueryKey, reportRuntimeError } from "./lib.js"
-
-// 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 :/
+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"
+
+// --- 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.Writable<AsyncResult.AsyncResult<A, E>, 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: <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>
+  ) => {
+    const family = queryFamilyByKey.get(queryFamilyCacheKey(query))
+    if (!family) {
+      if (warnIfMissing) {
+        console.warn(`Query ${query.id} has not been used yet; nothing to update`)
+      }
+      return
+    }
+    const atom: Atom.Writable<AsyncResult.AsyncResult<A, E>, AsyncResult.AsyncResult<A, E>> = family(input)
+    const current = registry.get(atom)
+    const next = AsyncResult.map(current, updater)
+    registry.set(atom, next)
+  }
+})
+
+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 +218,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 +228,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 +239,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 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)
+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
+  }
+}
+
+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
+}
+
+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 makeQuery = <R>(getRuntime: () => ServiceMap.ServiceMap<R>) => {
+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 +628,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,241 +638,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 r = useTanstackQuery<A, KnownFiberFailure<E>, TData>(
-      Effect.isEffect(handler)
-        ? {
-          ...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 }
-            )
-        }
-        : {
-          ...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 view = makeQueryView<I, A, E, TData>(getAtomRt, q, arg, options)
 
-    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 })
@@ -397,29 +857,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
 }