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

package/package.json

@@ -1,36 +1,33 @@
 {
   "name": "@effect-app/vue",
-  "version": "4.0.0-beta.29",
+  "version": "4.0.0-beta.291",
   "license": "MIT",
   "type": "module",
   "homepage": "https://github.com/effect-ts-app/libs/tree/main/packages/vue",
   "dependencies": {
-    "@formatjs/intl": "^4.1.2",
-    "@tanstack/query-core": "5.83.1",
-    "@tanstack/vue-query": "5.83.1",
-    "@vueuse/core": "^14.2.1",
+    "@formatjs/intl": "^4.1.12",
+    "@tanstack/vue-query": "5.96.2",
+    "@vueuse/core": "^14.3.0",
     "change-case": "^5.4.4",
-    "query-string": "^9.3.1",
-    "effect-app": "4.0.0-beta.29"
+    "query-string": "^9.4.0",
+    "effect-app": "4.0.0-beta.291"
   },
   "peerDependencies": {
-    "@effect/atom-vue": "^4.0.0-beta.37",
-    "@effect/platform-browser": "^4.0.0-beta.37",
-    "@sentry/browser": "^10.42.0",
-    "effect": "^4.0.0-beta.37",
-    "vue": "^3.5.29"
+    "@effect/atom-vue": "^4.0.0-beta.90",
+    "@effect/platform-browser": "^4.0.0-beta.90",
+    "@sentry/browser": "^10.55.0",
+    "effect": "^4.0.0-beta.90",
+    "vue": "^3.5.35"
   },
   "devDependencies": {
-    "@effect/vitest": "^4.0.0-beta.37",
-    "@formatjs/icu-messageformat-parser": "^3.5.1",
-    "@types/node": "25.3.3",
-    "@vitejs/plugin-vue": "^6.0.4",
-    "intl-messageformat": "^11.1.2",
-    "json5": "^2.2.3",
-    "typescript": "~5.9.3",
-    "vite": "^7.3.1",
-    "vitest": "^4.0.18",
-    "@effect-app/eslint-shared-config": "0.5.7-beta.2"
+    "@effect/vitest": "4.0.0-beta.90",
+    "@formatjs/icu-messageformat-parser": "^3.5.10",
+    "@types/node": "25.9.1",
+    "@vitejs/plugin-vue": "^6.0.7",
+    "intl-messageformat": "^11.2.7",
+    "typescript": "~6.0.3",
+    "vite": "^8.0.15",
+    "vitest": "^4.1.7"
   },
   "typesVersions": {
     "*": {
@@ -44,69 +41,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
-    "./errorReporter": {
-      "types": "./dist/errorReporter.d.ts",
-      "default": "./dist/errorReporter.js"
-    },
-    "./experimental/commander": {
-      "types": "./dist/experimental/commander.d.ts",
-      "default": "./dist/experimental/commander.js"
-    },
-    "./experimental/confirm": {
-      "types": "./dist/experimental/confirm.d.ts",
-      "default": "./dist/experimental/confirm.js"
-    },
-    "./experimental/intl": {
-      "types": "./dist/experimental/intl.d.ts",
-      "default": "./dist/experimental/intl.js"
-    },
-    "./experimental/makeUseCommand": {
-      "types": "./dist/experimental/makeUseCommand.d.ts",
-      "default": "./dist/experimental/makeUseCommand.js"
-    },
-    "./experimental/toast": {
-      "types": "./dist/experimental/toast.d.ts",
-      "default": "./dist/experimental/toast.js"
-    },
-    "./experimental/withToast": {
-      "types": "./dist/experimental/withToast.d.ts",
-      "default": "./dist/experimental/withToast.js"
-    },
-    "./form": {
-      "types": "./dist/form.d.ts",
-      "default": "./dist/form.js"
-    },
-    "./lib": {
-      "types": "./dist/lib.d.ts",
-      "default": "./dist/lib.js"
-    },
-    "./makeClient": {
-      "types": "./dist/makeClient.d.ts",
-      "default": "./dist/makeClient.js"
-    },
-    "./makeContext": {
-      "types": "./dist/makeContext.d.ts",
-      "default": "./dist/makeContext.js"
-    },
-    "./makeIntl": {
-      "types": "./dist/makeIntl.d.ts",
-      "default": "./dist/makeIntl.js"
-    },
-    "./mutate": {
-      "types": "./dist/mutate.d.ts",
-      "default": "./dist/mutate.js"
-    },
-    "./query": {
-      "types": "./dist/query.d.ts",
-      "default": "./dist/query.js"
-    },
-    "./routeParams": {
-      "types": "./dist/routeParams.d.ts",
-      "default": "./dist/routeParams.js"
-    },
-    "./runtime": {
-      "types": "./dist/runtime.d.ts",
-      "default": "./dist/runtime.js"
+    "./internal/*": null,
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
     }
   },
   "gitHead": "bd8e27eea3eff97db8739d577d67e7336c078d28",
@@ -120,24 +58,22 @@
   ],
   "scripts": {
     "watch": "pnpm build:tsc -w",
-    "build:tsc": "pnpm clean-dist && effect-app-cli packagejson pnpm check",
-    "check": "tsc --build",
+    "build:tsc": "pnpm clean-dist && pnpm check && node ../../scripts/rewrite-dist-declaration-imports.mjs dist",
+    "check": "tsgo --build",
     "build": "pnpm build:tsc",
-    "watch2": "pnpm clean-dist && NODE_OPTIONS=--max-old-space-size=6144 tsc -w",
+    "watch2": "pnpm clean-dist && NODE_OPTIONS=--max-old-space-size=6144 tsgo -w",
     "clean": "rm -rf dist",
     "clean-dist": "sh ../../scripts/clean-dist.sh",
     "circular": "pnpm circular:src && pnpm circular:dist",
     "circular:src": "madge --circular --ts-config ./tsconfig.json --extensions ts ./src",
     "circular:dist": "madge --circular --extensions js ./dist",
-    "compile": "NODE_OPTIONS=--max-old-space-size=6144 tsc --noEmit",
-    "lint": "NODE_OPTIONS=--max-old-space-size=6144 ESLINT_TS=1 eslint ./src",
-    "lint:watch": "ESLINT_TS=1 esw -w --changed --clear --ext ts,tsx .",
-    "lint-fix": "pnpm lint --fix",
+    "compile": "NODE_OPTIONS=--max-old-space-size=6144 tsgo --noEmit",
+    "lint": "oxlint --quiet --type-aware ./src && pnpm exec dprint check --config ../../dprint.jsonc .",
+    "lint-fix": "oxlint --quiet --type-aware --fix ./src && pnpm exec dprint fmt --config ../../dprint.jsonc .",
     "test": "vitest",
     "test:run": "pnpm run test run --passWithNoTests",
     "testsuite": "pnpm lint && pnpm circular && pnpm run test:run",
     "ncu": "ncu",
-    "pub": "pnpm prepublish && npm publish --access public",
-    "prepublish": "cp -f ./tsconfig.json ./tsconfig.json.bak && node ../../scripts/mergeTsConfig.mjs ./tsconfig.json"
+    "pub": "npm publish --access public"
   }
 }

package/src/atomQuery.ts

@@ -0,0 +1,466 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Shared atom core for the query/mutation engine (used by query.ts + mutate.ts).
+ *
+ * Replaces the @tanstack/vue-query engine with Effect `Atom`, keeping the public
+ * `.query()/.suspense()/.mutate()` contract unchanged:
+ *   - cache identity   = the atom reference (one per [handler, input], via Atom.family)
+ *   - invalidation key = reactivity keys (= the app's existing namespace query keys)
+ *   - SWR + focus      = Atom.swr (+ windowFocusSignal)
+ *   - gcTime           = Atom.setIdleTTL / Atom.keepAlive
+ *   - retry            = Effect.retry inside the atom effect
+ *
+ * Built over the app's RPC client through the existing `RequestHandlerWithInput`
+ * abstraction (mirrors AtomRpc's recipe; see docs/atom-query-plan.md).
+ */
+import { defaultRegistry } from "@effect/atom-vue"
+import { DataDependencies, makeQueryKey } from "effect-app/client"
+import type { ClientForOptions } from "effect-app/client/clientFor"
+import { ServiceUnavailableError } from "effect-app/client/errors"
+import * as Effect from "effect-app/Effect"
+import * as Option from "effect-app/Option"
+import * as S from "effect-app/Schema"
+import * as Cause from "effect/Cause"
+import * as Duration from "effect/Duration"
+import * as Equal from "effect/Equal"
+import * as Hash from "effect/Hash"
+import type * as Layer from "effect/Layer"
+import * as Ref from "effect/Ref"
+import * as Stream from "effect/Stream"
+import type * as Tracer from "effect/Tracer"
+import { isHttpClientError } from "effect/unstable/http/HttpClientError"
+import * as AsyncResult from "effect/unstable/reactivity/AsyncResult"
+import * as Atom from "effect/unstable/reactivity/Atom"
+import * as AtomRegistry from "effect/unstable/reactivity/AtomRegistry"
+import * as Reactivity from "effect/unstable/reactivity/Reactivity"
+import { clearQueryReadDependencies, setQueryReadDependencies } from "./dependencyMetadata.ts"
+import { reportRuntimeError } from "./lib.ts"
+
+/** All non-empty prefixes of a key, longest last. `[a,b,c]` -> `[[a],[a,b],[a,b,c]]`. */
+const prefixesOf = (key: ReadonlyArray<unknown>): ReadonlyArray<ReadonlyArray<unknown>> =>
+  key.map((_, i) => key.slice(0, i + 1))
+
+const uniqueKeys = (keys: ReadonlyArray<ReadonlyArray<unknown>>): ReadonlyArray<ReadonlyArray<unknown>> => {
+  const out: Array<ReadonlyArray<unknown>> = []
+  const seen = new Set<number>()
+  for (const key of keys) {
+    const hash = Hash.hash(key)
+    if (seen.has(hash)) continue
+    seen.add(hash)
+    out.push(key)
+  }
+  return out
+}
+
+// --- awaitable invalidation -------------------------------------------------------------------
+// keyHash -> live query atoms registered under that key. A query atom is tracked while it is alive
+// in the registry (mounted OR cached within idle-ttl) and removed on GC, so invalidation reaches
+// cached-but-unmounted queries too (e.g. a list you navigated away from).
+const keyAtoms = new Map<number, Set<Atom.Atom<AsyncResult.AsyncResult<any, any>>>>()
+
+const trackByKeys =
+  (keys: ReadonlyArray<ReadonlyArray<unknown>>) =>
+  <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>): Atom.Atom<AsyncResult.AsyncResult<A, E>> =>
+    Atom.transform(atom, (get) => {
+      for (const key of keys) {
+        const h = Hash.hash(key)
+        let set = keyAtoms.get(h)
+        if (!set) keyAtoms.set(h, set = new Set())
+        set.add(atom)
+        get.addFinalizer(() => {
+          set.delete(atom)
+          if (set.size === 0) keyAtoms.delete(h)
+        })
+      }
+      return get(atom)
+    }, { initialValueTarget: atom })
+
+const trackWritableByKeys =
+  (keys: ReadonlyArray<ReadonlyArray<unknown>>) =>
+  <A, E, W>(atom: Atom.Writable<AsyncResult.AsyncResult<A, E>, W>): Atom.Writable<AsyncResult.AsyncResult<A, E>, W> => {
+    const tracked = trackByKeys(keys)(atom)
+    return Atom.writable(
+      (get) => get(tracked),
+      (ctx, value) => ctx.set(atom, value),
+      (refresh) => refresh(tracked)
+    )
+  }
+
+/**
+ * Keep a query's recorded read-dependencies registered for as long as it is alive, and drop them when
+ * its atom is GC'd (mirrors `trackByKeys`).
+ *
+ * `recordReads` only stores the deps on an actual fetch. A query that unmounts and later remounts from
+ * cache (within idle-ttl) does NOT re-run the handler, so its registry entry — cleared by the previous
+ * teardown's finalizer — would never be restored, and a subsequent mutation could not derive it as an
+ * invalidation target. Re-asserting the last-known reads on every (re)subscribe closes that gap, so the
+ * registry mirrors the live query even across cache-hit remounts.
+ */
+const trackReadDependencies =
+  (key: ReadonlyArray<unknown>, getReads: () => DataDependencies.DataDependencies) =>
+  <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>): Atom.Atom<AsyncResult.AsyncResult<A, E>> =>
+    Atom.transform(atom, (get) => {
+      const reads = getReads()
+      if (DataDependencies.isNonEmpty(reads)) setQueryReadDependencies(key, reads)
+      get.addFinalizer(() => clearQueryReadDependencies(key))
+      return get(atom)
+    }, { initialValueTarget: atom })
+
+const atomsForKeys = (keys: ReadonlyArray<unknown>): ReadonlyArray<Atom.Atom<AsyncResult.AsyncResult<any, any>>> => {
+  const atoms = new Set<Atom.Atom<AsyncResult.AsyncResult<any, any>>>()
+  for (const key of keys) {
+    const set = keyAtoms.get(Hash.hash(key))
+    if (set) { for (const a of set) atoms.add(a) }
+  }
+  return [...atoms]
+}
+
+/**
+ * Invalidate the given keys and AWAIT the result. The invalidation (refetch trigger) goes through
+ * the built-in `Reactivity` service — the same one query atoms register against via
+ * `factory.withReactivity`, shared via the runtime memoMap. The await uses our own `keyAtoms`
+ * tracking + `awaitAtomResult`, since `Reactivity.invalidate` returns void and can't be awaited.
+ *
+ * Resolves once the affected queries have settled, so a mutation can `yield*` this and know the
+ * affected queries are fresh. (The await reads via the module-global default registry — the one the
+ * vue composables resolve via `injectRegistry`'s fallback.)
+ */
+export const invalidateAndAwait = (keys: ReadonlyArray<unknown>): Effect.Effect<void, never, Reactivity.Reactivity> =>
+  Effect.gen(function*() {
+    const atoms = atomsForKeys(keys)
+    yield* Effect.forEach(atoms, captureAtomQueryParentSpan, { discard: true, concurrency: "inherit" })
+    yield* Reactivity.invalidate(keys) // invalidates everything but only refreshes what's mounted
+    //    for (const a of atoms) defaultRegistry.refresh(a) // refreshes everything even when not mounted
+    if (atoms.length === 0) return
+    yield* Effect.forEach(atoms, (a) => awaitAtomResult(defaultRegistry, a).pipe(Effect.exit))
+  })
+
+const isPlainObject = (o: unknown): o is Record<string, unknown> => {
+  if (typeof o !== "object" || o === null) return false
+  const proto = Object.getPrototypeOf(o)
+  return proto === Object.prototype || proto === null
+}
+
+/**
+ * Structural sharing (tanstack `replaceEqualDeep`): walk `next` against `prev` and reuse `prev`'s
+ * reference for any unchanged array/object sub-tree, so unchanged data keeps referential identity
+ * (Vue skips re-rendering it). Leaves — including decoded Schema CLASS INSTANCES — are compared with
+ * Effect `Equal.equals` (structural), which reuses equal instances that tanstack's `===` could not.
+ */
+export const replaceEqualDeep = (prev: any, next: any): any => {
+  if (prev === next) return prev
+  const bothArrays = Array.isArray(prev) && Array.isArray(next)
+  if (bothArrays || (isPlainObject(prev) && isPlainObject(next))) {
+    const a: Record<PropertyKey, any> = prev
+    const b: Record<PropertyKey, any> = next
+    const copy: Record<PropertyKey, any> = bothArrays ? [] : {}
+    const nextKeys: Array<PropertyKey> = bothArrays ? (b as Array<any>).map((_, i) => i) : Object.keys(b)
+    const nextSize = nextKeys.length
+    const prevSize = bothArrays ? (a as Array<any>).length : Object.keys(a).length
+    let equalItems = 0
+    for (let i = 0; i < nextSize; i++) {
+      const key = nextKeys[i]!
+      copy[key] = replaceEqualDeep(a[key], b[key])
+      if (copy[key] === a[key] && a[key] !== undefined) equalItems++
+    }
+    return prevSize === nextSize && equalItems === prevSize ? prev : copy
+  }
+  return Equal.equals(prev, next) ? prev : next
+}
+
+/** Atom combinator: share each new `Success` value structurally against the previous one. */
+const structuralShare = <A, E>(
+  self: Atom.Atom<AsyncResult.AsyncResult<A, E>>
+): Atom.Atom<AsyncResult.AsyncResult<A, E>> =>
+  Atom.transform(self, (get) => {
+    const next = get(self)
+    if (next._tag !== "Success") return next
+    const prev = Option.flatMap(get.self<AsyncResult.AsyncResult<A, E>>(), AsyncResult.value)
+    if (Option.isNone(prev)) return next
+    const shared = replaceEqualDeep(prev.value, next.value)
+    return shared === next.value
+      ? next
+      : AsyncResult.success(shared, { waiting: next.waiting, timestamp: next.timestamp })
+  }, { initialValueTarget: self })
+
+export interface AtomClientRuntime {
+  readonly runtime: Atom.AtomRuntime<any, never>
+  readonly factory: Atom.RuntimeFactory
+}
+
+/**
+ * Build one AtomRuntime (and its factory) from an already-built app context.
+ * Shares the ManagedRuntime's `memoMap` so layers are not built twice, and so
+ * query-registration and mutation-invalidation resolve the SAME `Reactivity`.
+ */
+export const makeAtomClientRuntime = <R>(
+  getContext: () => Layer.Layer<R, never, never>,
+  memoMap: Layer.MemoMap
+): AtomClientRuntime => {
+  const factory = Atom.context({ memoMap })
+  const runtime = factory((_get) => getContext())
+  return { runtime, factory }
+}
+
+const isRetryable = (e: unknown): boolean =>
+  isHttpClientError(e)
+  || S.is(ServiceUnavailableError)(e)
+  || (typeof e === "object" && e !== null && (e as any)._tag === "RpcClientError")
+
+export interface AtomQueryOptions {
+  /** background-refresh threshold (TanStack staleTime; default 5s) */
+  readonly staleTime?: Duration.Input
+  /** dispose-when-idle (TanStack gcTime; default 5min). "infinity" => keepAlive */
+  readonly gcTime?: Duration.Input | "infinity"
+  /**
+   * Revalidate a stale query on window focus AND on network reconnect (default on, matching
+   * tanstack refetchOnWindowFocus + refetchOnReconnect).
+   */
+  readonly revalidateOnFocus?: boolean
+  /**
+   * Reuse references of unchanged sub-trees across refetches (default on, matching tanstack
+   * structuralSharing). Uses Effect `Equal` so decoded Schema instances share too — more effective
+   * than tanstack's `===`, but a deep compare per refetch (O(rows·fields)). Set `false` for very
+   * large or mostly-changing result sets where the compare costs more than the saved re-renders.
+   */
+  readonly structuralSharing?: boolean
+  /** poll: re-fetch every N ms (tanstack refetchInterval). */
+  readonly refetchInterval?: number
+}
+
+const defaults = { staleTime: Duration.seconds(5), gcTime: Duration.minutes(5) }
+
+export interface AtomQueryMetadata {
+  readonly staleTimeMs: number
+}
+
+const atomQueryMetadata = new WeakMap<Atom.Atom<AsyncResult.AsyncResult<any, any>>, AtomQueryMetadata>()
+const atomQueryParentSpans = new WeakMap<Atom.Atom<AsyncResult.AsyncResult<any, any>>, Tracer.AnySpan>()
+
+const atomSpanTarget = <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => {
+  let target = atom
+  while (target.initialValueTarget !== undefined) {
+    target = target.initialValueTarget
+  }
+  return target
+}
+
+const takeAtomQueryParentSpan = <A, E>(atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>) => {
+  const target = atomSpanTarget(atom)
+  const span = atomQueryParentSpans.get(target)
+  if (span !== undefined) atomQueryParentSpans.delete(target)
+  return span
+}
+
+const setAtomQueryParentSpan = <A, E>(
+  atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>,
+  span: Tracer.AnySpan
+) => {
+  atomQueryParentSpans.set(atomSpanTarget(atom), span)
+}
+
+export const captureAtomQueryParentSpan = <A, E>(
+  atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>
+): Effect.Effect<void> =>
+  Effect.currentParentSpan.pipe(
+    Effect.tap((span) => Effect.sync(() => setAtomQueryParentSpan(atom, span))),
+    Effect.ignore
+  )
+
+export const refreshAtomWithCurrentSpan = <A, E>(
+  registry: AtomRegistry.AtomRegistry,
+  atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>
+): Effect.Effect<void> =>
+  captureAtomQueryParentSpan(atom).pipe(
+    Effect.andThen(Effect.sync(() => registry.refresh(atom)))
+  )
+
+const setAtomQueryMetadata = <A, E>(
+  atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>,
+  opts: AtomQueryOptions = {}
+) => {
+  const staleTimeMs = staleTimeMsOf(opts)
+  const previous = atomQueryMetadata.get(atom)
+  atomQueryMetadata.set(atom, {
+    staleTimeMs: previous === undefined ? staleTimeMs : Math.min(previous.staleTimeMs, staleTimeMs)
+  })
+  return atom
+}
+
+export const getAtomQueryMetadata = <A, E>(
+  atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>
+): AtomQueryMetadata | undefined => atomQueryMetadata.get(atom)
+
+/** Exported so the vue hook can do refetch-on-mount-per-observer with the same rule as swr. */
+export const isStaleResult = (r: AsyncResult.AsyncResult<any, any>, staleTimeMs: number): boolean => {
+  if (r.waiting) return false
+  const ts = r._tag === "Success"
+    ? r.timestamp
+    : r._tag === "Failure"
+    ? Option.getOrUndefined(Option.map(r.previousSuccess, (s) => s.timestamp))
+    : undefined
+  if (ts === undefined) return r._tag !== "Initial"
+  return Date.now() - ts >= staleTimeMs
+}
+
+export const staleTimeMsOf = (opts: AtomQueryOptions): number =>
+  Duration.toMillis(Duration.fromInputUnsafe(opts.staleTime ?? defaults.staleTime))
+
+export const withQueryOptions = <A, E>(
+  self: Atom.Atom<AsyncResult.AsyncResult<A, E>>,
+  opts: AtomQueryOptions = {}
+): Atom.Atom<AsyncResult.AsyncResult<A, E>> => {
+  setAtomQueryMetadata(self, opts)
+  const staleTime: Duration.Input = opts.staleTime ?? defaults.staleTime
+  let atom = self
+  const revalidateOnFocus = opts.revalidateOnFocus ?? true
+  atom = Atom.swr({
+    staleTime,
+    revalidateOnFocus,
+    focusSignal: revalidateOnFocus ? focusOrReconnectSignal : undefined
+  })(atom)
+  if (opts.refetchInterval) atom = Atom.withRefresh(Duration.millis(opts.refetchInterval))(atom)
+  if (opts.structuralSharing ?? true) atom = structuralShare(atom)
+  return atom
+}
+
+/** Constant atom for disabled / `mode:"optional"`-None queries: stays Initial, never fetches. */
+export const disabledQueryAtom: Atom.Atom<AsyncResult.AsyncResult<any, any>> = Atom.readable(() =>
+  AsyncResult.initial(false)
+)
+
+/**
+ * Bumps when the browser regains connectivity (the `online` event) — the tanstack
+ * `refetchOnReconnect` trigger. One shared listener (module-level). SSR-guarded.
+ */
+const onlineSignal: Atom.Atom<number> = Atom.readable((get) => {
+  let count = 0
+  if (typeof window === "undefined") return count
+  const update = () => {
+    if (navigator.onLine) get.setSelf(++count)
+  }
+  window.addEventListener("online", update)
+  get.addFinalizer(() => window.removeEventListener("online", update))
+  return count
+})
+
+/**
+ * Focus OR reconnect, as a single signal for `swr` — both should stale-revalidate a query.
+ * swr takes one `focusSignal`, so we fold window-focus + reconnect into one derived atom;
+ * a bump from either triggers swr's stale check.
+ */
+const focusOrReconnectSignal: Atom.Atom<number> = Atom.make((get) => get(Atom.windowFocusSignal) + get(onlineSignal))
+
+/**
+ * Build the per-input atom family for a request handler — the query CACHE IDENTITY.
+ *
+ * This is the TanStack `queryKey = [handler, input]` equivalent and the piece that makes
+ * caching cross-component: `Atom.family` memoizes one atom per structurally-distinct input
+ * (v4 hashes the input via Hash/Equal), so every component querying the same handler+input
+ * reads the SAME atom instance => one fetch, one shared result in the global registry,
+ * ref-counted and GC'd on idle ttl. (The registry + ttl give lifetime; reactivity keys give
+ * invalidation; the family gives identity/sharing — all three are needed.)
+ *
+ * The family is created once per handler (see query.ts's per-handler cache), so it is shared
+ * process-wide via the registry.
+ *
+ * Invalidation is hierarchical: each atom registers under EVERY prefix of its full key
+ * `[...makeQueryKey(self), input]`. Since reactivity matches keys by exact hash, registering
+ * all prefixes means `invalidate(P)` refreshes every atom whose key starts with `P` — e.g.
+ * `["$X"]` refreshes all inputs, `["$X","$List",input]` only that input. (`makeQueryKey`'s
+ * collapsed form `getQueryKey` — what mutations invalidate by default — is one of the prefixes.)
+ */
+export const buildQueryFamily = <I, A, E>(
+  rt: AtomClientRuntime,
+  self: {
+    readonly id: string
+    readonly handler: (i: I) => Effect.Effect<A, E, any>
+    readonly options?: ClientForOptions
+    readonly queryKeyProjectionHash?: string
+  }
+) => {
+  const baseKey = makeQueryKey(self) // hierarchical, input-independent
+
+  return Atom.family((input: I) => {
+    const fullKey = [...baseKey, input]
+    // Record the repository/server read-dependencies seen while fetching, keyed by `fullKey`, so a
+    // later mutation whose writes intersect them can derive this query as an invalidation target.
+    // The last recorded reads are retained on the (memoized) family atom so `trackReadDependencies`
+    // can re-assert them on a cache-hit remount that never re-runs the handler.
+    let lastReads: DataDependencies.DataDependencies = DataDependencies.empty()
+    let atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>
+    atom = rt.runtime.atom(
+      Effect.suspend(() => {
+        const recordReads = Effect.gen(function*() {
+          const readsRef = yield* Ref.make(DataDependencies.empty())
+          const writesRef = yield* Ref.make(DataDependencies.empty())
+          const recorder = DataDependencies.makeDataDependencyRecorder(readsRef, writesRef)
+          const result = yield* self
+            .handler(input)
+            .pipe(Effect.provideService(DataDependencies.DataDependencyRecorder, recorder))
+          lastReads = yield* Ref.get(readsRef)
+          setQueryReadDependencies(fullKey, lastReads)
+          return result
+        })
+        const effect = recordReads.pipe(
+          Effect.retry({ times: 5, while: isRetryable }),
+          Effect.tapCauseIf(Cause.hasDies, (cause) => reportRuntimeError(cause)),
+          Effect.withSpan(`query ${self.id}`, {}, { captureStackTrace: false })
+        )
+        const parentSpan = takeAtomQueryParentSpan(atom)
+        return parentSpan === undefined
+          ? effect
+          : effect.pipe(Effect.withParentSpan(parentSpan, { captureStackTrace: false }))
+      })
+    )
+    // Register under every prefix of the full key => hierarchical (prefix) invalidation. Two roles:
+    //   - withReactivity: `Reactivity.invalidate(key)` refreshes this atom (the actual refetch).
+    //   - trackByKeys:    records the atom in `keyAtoms` so the mutation can AWAIT its settle.
+    const projectedFullKey = self.queryKeyProjectionHash === undefined
+      ? fullKey
+      : [...baseKey, self.queryKeyProjectionHash, input]
+    const reactivityKeys = uniqueKeys([...prefixesOf(fullKey), ...prefixesOf(projectedFullKey)])
+    atom = rt.factory.withReactivity(reactivityKeys)(atom)
+    atom = trackByKeys(reactivityKeys)(atom)
+    atom = trackReadDependencies(fullKey, () => lastReads)(atom)
+    // gcTime LAST so the whole chain (incl. the registration + tracking) stays alive through the
+    // idle window, letting invalidation reach a cached-but-unmounted query.
+    atom = Atom.setIdleTTL(atom, defaults.gcTime)
+    return setAtomQueryMetadata(Atom.withLabel(`query:${self.id}`)(atom))
+  })
+}
+
+export const buildStreamQueryFamily = <I, A, E>(
+  rt: AtomClientRuntime,
+  self: {
+    readonly id: string
+    readonly handler: (i: I) => Stream.Stream<A, E, any>
+    readonly options?: ClientForOptions
+    readonly queryKeyProjectionHash?: string
+  }
+) => {
+  const baseKey = makeQueryKey(self)
+
+  return Atom.family((input: I) => {
+    let atom = rt.runtime.pull(
+      self.handler(input).pipe(
+        Stream.tapCause((cause) => Cause.hasDies(cause) ? reportRuntimeError(cause) : Effect.void)
+      )
+    )
+    const fullKey = [...baseKey, input]
+    const projectedFullKey = self.queryKeyProjectionHash === undefined
+      ? fullKey
+      : [...baseKey, self.queryKeyProjectionHash, input]
+    const reactivityKeys = uniqueKeys([...prefixesOf(fullKey), ...prefixesOf(projectedFullKey)])
+    atom = rt.factory.withReactivity(reactivityKeys)(atom)
+    atom = trackWritableByKeys(reactivityKeys)(atom)
+    atom = Atom.setIdleTTL(atom, defaults.gcTime)
+    return setAtomQueryMetadata(Atom.withLabel(`stream-query:${self.id}`)(atom))
+  })
+}
+
+/** Await the first resolved (non-Waiting) result of an atom. Failing query results fail the Effect. */
+export const awaitAtomResult = <A, E>(
+  registry: AtomRegistry.AtomRegistry,
+  atom: Atom.Atom<AsyncResult.AsyncResult<A, E>>
+) => AtomRegistry.getResult(registry, atom, { suspendOnWaiting: true })