@tanstack/solid-query 6.0.0-rc.0 → 6.0.0-rc.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/solid-query",
-  "version": "6.0.0-rc.0",
+  "version": "6.0.0-rc.2",
   "description": "Primitives for managing, caching and syncing asynchronous and remote data in Solid",
   "author": "tannerlinsley",
   "license": "MIT",
@@ -46,22 +46,23 @@
     "!src/__tests__"
   ],
   "dependencies": {
-    "@tanstack/query-core": "5.101.0"
+    "@tanstack/query-core": "5.101.4"
   },
   "devDependencies": {
     "@babel/core": "^7.28.0",
     "@babel/preset-typescript": "^7.18.6",
     "@solidjs/testing-library": "^0.8.10",
     "@solidjs/vite-plugin": "^3.0.0-next.27",
-    "@solidjs/web": "^2.0.0-rc.0",
-    "babel-preset-solid": "^2.0.0-rc.0",
+    "@solidjs/web": "^2.0.0-rc.6",
+    "babel-preset-solid": "^2.0.0-rc.2",
     "npm-run-all2": "^5.0.0",
-    "solid-js": "^2.0.0-rc.0",
+    "solid-js": "^2.0.0-rc.6",
     "tsup-preset-solid": "^2.2.0",
     "@tanstack/query-test-utils": "0.0.0"
   },
   "peerDependencies": {
-    "solid-js": ">=2.0.0-rc.0 <3.0.0"
+    "@solidjs/web": ">=2.0.0-rc.6 <3.0.0",
+    "solid-js": ">=2.0.0-rc.6 <3.0.0"
   },
   "scripts": {
     "clean": "premove ./build ./coverage ./dist-ts",

package/src/QueryClient.ts

@@ -9,63 +9,42 @@ import type {
   QueryKey,
 } from '@tanstack/query-core'
 
-export interface QueryObserverOptions<
+/**
+ * Core observer options pass through unchanged. The old adapter omitted
+ * `structuralSharing` and replaced it with a store-level `reconcile`
+ * option; with reads derived directly from cache state, core's
+ * cache-level structural sharing is exactly what keeps the data memo
+ * referentially stable, so it is exposed again and `reconcile` is gone.
+ */
+export type QueryObserverOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
   TData = TQueryFnData,
   TQueryData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
   TPageParam = never,
-> extends OmitKeyof<
-  QueryCoreObserverOptions<
-    TQueryFnData,
-    TError,
-    TData,
-    TQueryData,
-    TQueryKey,
-    TPageParam
-  >,
-  'structuralSharing'
-> {
-  /**
-   * Set this to a reconciliation key to enable reconciliation between query results.
-   * Set this to `false` to disable reconciliation between query results.
-   * Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom reconciliation logic.
-   * Defaults reconciliation to false.
-   */
-  reconcile?:
-    | string
-    | false
-    | ((oldData: TData | undefined, newData: TData) => TData)
-}
+> = QueryCoreObserverOptions<
+  TQueryFnData,
+  TError,
+  TData,
+  TQueryData,
+  TQueryKey,
+  TPageParam
+>
 
-export interface InfiniteQueryObserverOptions<
+export type InfiniteQueryObserverOptions<
   TQueryFnData = unknown,
   TError = DefaultError,
   TData = TQueryFnData,
   TQueryKey extends QueryKey = QueryKey,
   TPageParam = unknown,
-> extends OmitKeyof<
-  QueryCoreInfiniteQueryObserverOptions<
-    TQueryFnData,
-    TError,
-    TData,
-    TQueryKey,
-    TPageParam
-  >,
-  'structuralSharing'
-> {
-  /**
-   * Set this to a reconciliation key to enable reconciliation between query results.
-   * Set this to `false` to disable reconciliation between query results.
-   * Set this to a function which accepts the old and new data and returns resolved data of the same type to implement custom reconciliation logic.
-   * Defaults reconciliation to false.
-   */
-  reconcile?:
-    | string
-    | false
-    | ((oldData: TData | undefined, newData: TData) => TData)
-}
+> = QueryCoreInfiniteQueryObserverOptions<
+  TQueryFnData,
+  TError,
+  TData,
+  TQueryKey,
+  TPageParam
+>
 
 export interface DefaultOptions<
   TError = DefaultError,

package/src/QueryClientProvider.tsx

@@ -1,21 +1,43 @@
-import {
-  createContext,
-  createRenderEffect,
-  createSignal,
-  onCleanup,
-  useContext,
-} from 'solid-js'
-import {
-  HydrationCoordinatorContext,
-  createHydrationCoordinator,
-  createServerDehydrationChannel,
-} from './hydrationChannel'
-import type { DehydrationChannelYield } from './hydrationChannel'
+import { createContext, onCleanup, sharedConfig, useContext } from 'solid-js'
+import { hydrate } from '@tanstack/query-core'
+import { subscribeFlightData } from '@solidjs/web/server-functions'
+import type { DehydratedState, Query } from '@tanstack/query-core'
 import type { QueryClient } from './QueryClient'
 import type { JSX } from '@solidjs/web'
 
 const isServer = typeof window === 'undefined'
 
+/**
+ * Namespace prefix for cache entries in Solid's hydration registry — the
+ * registry is shared with positional node ids and other libraries'
+ * content-addressed keys (Solid Router uses its own cache keys), so query
+ * hashes get their own prefix.
+ */
+export const HYDRATION_KEY_PREFIX = 'sq:'
+
+/**
+ * The query cache's single-flight source id. Mutation responses can fold
+ * fresh data for multiple caches at once (Solid's multi-source
+ * single-flight protocol); this is the slice the query cache claims — the
+ * provider subscribes its consumer under it, and server collectors
+ * register under it to produce the data:
+ *
+ * ```ts
+ * import { registerFlightDataSource } from '@solidjs/web/server-functions/server'
+ * import { FLIGHT_DATA_SOURCE, dehydrate } from '@tanstack/solid-query'
+ *
+ * registerFlightDataSource(FLIGHT_DATA_SOURCE, async (event, outcome) => {
+ *   // rebuild the data for outcome.targetUrl into a QueryClient, then
+ *   return dehydrate(queryClient)
+ * })
+ * ```
+ *
+ * The slice's payload is a `DehydratedState`; the provider consumes it
+ * with `hydrate()`, so every mounted query on those keys updates before
+ * the mutation's promise resolves — no follow-up refetches.
+ */
+export const FLIGHT_DATA_SOURCE = 'sq'
+
 export const QueryClientContext = createContext<(() => QueryClient) | null>(
   null,
 )
@@ -38,59 +60,115 @@ export type QueryClientProviderProps = {
   children?: JSX.Element
 }
 
+/**
+ * Server side of hydration: serialize every query the request touches into
+ * Solid's hydration registry, content-addressed by query hash (the Solid
+ * Router `query()` pattern). Serialization happens at fetch-DISPATCH time —
+ * synchronously, while the request's serialization context is live — by
+ * handing seroval the fetch promise; it streams the `{ data, t }` payload
+ * whenever the fetch settles. Settled entries (initialData, setQueryData,
+ * loader prefetches that already landed) serialize their value directly.
+ *
+ * Content addressing is what makes this cover MORE than rendered
+ * components: a query prefetched in a loader and never read by any
+ * component still transfers, and any client hook (hydrating or mounted
+ * long after) finds it by hash. One entry per hash regardless of how many
+ * hooks read it; the payload object is the same reference the data nodes
+ * serialize, so seroval's cross-reference dedupe emits it once.
+ */
+function serializeCacheOnServer(client: QueryClient): void {
+  const ctx = (
+    sharedConfig as unknown as {
+      context?: {
+        async?: boolean
+        noHydrate?: boolean
+        serialize: (key: string, value: unknown) => void
+      }
+    }
+  ).context
+  if (!ctx || !ctx.async || ctx.noHydrate) return
+
+  const cache = client.getQueryCache()
+  // The standard dehydrate filter gates the wire here too, so apps keep
+  // sensitive or oversized queries out of the HTML with the same option
+  // they'd pass any other transport.
+  const shouldDehydrateQuery =
+    client.getDefaultOptions().dehydrate?.shouldDehydrateQuery
+  const seen = new Set<string>()
+  const serializeQuery = (query: Query<any, any, any, any>) => {
+    if (seen.has(query.queryHash)) return
+    // Consulted per cache event until it passes, so a filter that rejects
+    // pending queries (e.g. the core default) still admits the settled
+    // value if it lands while the request's serialization context is live.
+    if (shouldDehydrateQuery && !shouldDehydrateQuery(query)) return
+    const state = query.state
+    if (state.status === 'success') {
+      seen.add(query.queryHash)
+      ctx.serialize(HYDRATION_KEY_PREFIX + query.queryHash, {
+        data: state.data,
+        t: state.dataUpdatedAt,
+      })
+    } else if (state.fetchStatus !== 'idle') {
+      // Serialize the PROMISE now, while the context is live — the settle
+      // event fires from IO, where no request context exists anymore.
+      const promise = query.promise as Promise<unknown> | undefined
+      if (!promise) return
+      seen.add(query.queryHash)
+      ctx.serialize(
+        HYDRATION_KEY_PREFIX + query.queryHash,
+        promise.then(() => ({
+          data: query.state.data,
+          t: query.state.dataUpdatedAt,
+        })),
+      )
+    }
+  }
+
+  for (const query of cache.getAll()) serializeQuery(query)
+  onCleanup(cache.subscribe((event) => serializeQuery(event.query)))
+}
+
+/**
+ * Provides the QueryClient and manages its mount lifecycle. On the server
+ * it also registers the cache serializer above; on the client, hooks prime
+ * the cache from their hash-keyed registry entries themselves (see
+ * `useBaseQuery`) and the provider subscribes the cache's single-flight
+ * consumer: mutation responses carrying a `FLIGHT_DATA_SOURCE` slice (a
+ * `DehydratedState` produced by a server collector registered under the
+ * same id) hydrate this client before the mutation's promise resolves.
+ * Subscribing is inert when no server collector exists — the server just
+ * folds nothing — so it is unconditional. One consumer per source: with
+ * nested providers, the innermost mounted one owns the slice.
+ */
 export const QueryClientProvider = (
   props: QueryClientProviderProps,
 ): JSX.Element => {
   props.client.mount()
   onCleanup(() => props.client.unmount())
-
-  // Library-owned serialization channel for SSR dehydration.
-  //
-  // Server: the computation's value IS the channel's async iterable, so
-  // Solid serializes it through its normal per-computation signal path:
-  // the server runtime tees the iterator into the hydration serializer
-  // (`ctx.serialize(id, tapped)` in solid-js' `processResult`) and
-  // seroval streams each cumulative dehydrated-cache snapshot to the
-  // client as a chunk riding the SSR stream, with the entry objects
-  // inside deduplicated by reference against everything else in the
-  // payload. Nothing reads the signal during SSR, so it never suspends
-  // anything.
-  //
-  // Client, hydrating: Solid replays the serialized iterable through the
-  // per-computation signal path (`hydrateSignalFromAsyncIterable`).
-  // Yields that were still buffered when hydration began are conflated
-  // to the LATEST yield (`normalizeIterator`) — lossless here because
-  // every yield is a cumulative snapshot — and live yields after that
-  // apply one at a time. Requires a solid-js build with the buffered
-  // async-iterable replay conflation fix (> 2.0.0-beta.32): before it,
-  // the replay dropped every buffered yield after the first, including
-  // the terminal `done` snapshot. The render effect below hands each
-  // signal value to the coordinator, which primes the QueryClient via
-  // query-core hydrate() (newer-wins) and unblocks `useBaseQuery`
-  // subscribers waiting on their query's entry.
-  //
-  // Client, fresh mount: the compute returns undefined and the effect
-  // never fires.
-  const [channelValue] = createSignal<DehydrationChannelYield | undefined>(
-    () => (isServer ? createServerDehydrationChannel(props.client) : undefined),
-  )
-  const coordinator = isServer
-    ? null
-    : createHydrationCoordinator(() => props.client)
-  createRenderEffect(
-    () => (isServer ? undefined : channelValue()),
-    (value) => {
-      if (value && coordinator) {
-        coordinator.applyYield(value)
-      }
-    },
-  )
+  if (isServer) {
+    serializeCacheOnServer(props.client)
+    // Render disposal ends the request: abort what's still in flight and
+    // drop the cache so user-configured finite gcTime timers can't pin
+    // the per-request client (and whatever its queries closed over) until
+    // they fire. Serialized promises are already in seroval's hands, so
+    // clearing here can't affect the streamed payload.
+    onCleanup(() => {
+      props.client.cancelQueries().catch(() => undefined)
+      props.client.clear()
+    })
+  } else {
+    // Client-only: the server's consumer registry is module state shared
+    // across requests — registering there would leak between them.
+    onCleanup(
+      subscribeFlightData<DehydratedState>(FLIGHT_DATA_SOURCE, (data) => {
+        hydrate(props.client, data)
+      }),
+    )
+  }
 
   return (
     <QueryClientContext value={() => props.client}>
-      <HydrationCoordinatorContext value={coordinator}>
-        {props.children}
-      </HydrationCoordinatorContext>
+      {props.children}
     </QueryClientContext>
   )
 }

package/src/cacheAggregate.ts

@@ -0,0 +1,90 @@
+import {
+  createEffect,
+  createOptimistic,
+  createSignal,
+  onCleanup,
+  sharedConfig,
+  untrack,
+} from 'solid-js'
+import type { Accessor } from 'solid-js'
+
+const isServer = typeof window === 'undefined'
+
+/**
+ * Shared reactive core for the cross-cache aggregate hooks — `useIsFetching`,
+ * `useIsMutating`, `useMutationState` — which all reduce to "a value derived
+ * from a whole cache, refreshed on its events". Two invariants live here so
+ * each hook doesn't restate them:
+ *
+ * Dual write. Cache events can fire inside an action transaction
+ * (`useMutation` rides core `action`; an onSuccess invalidation dispatches
+ * refetches mid-action), where a plain signal write is held until settle —
+ * the in-flight value would be invisible. An optimistic override alone fails
+ * the other way: outside a transaction, overrides drop at batch end. So a
+ * durable signal carries committed state and an optimistic node tracks it as
+ * its base; in-transaction values surface through the override, and the held
+ * durable write becomes the base when the settle lands.
+ *
+ * Hydration. A cross-cache aggregate is not tied to a single async source,
+ * so it cannot ride the boundary contract per-query meta uses (suspend until
+ * settled). Its contract is fixed by construction instead: a hydrating
+ * client can only ever observe the empty value at claim time — its own
+ * fetches are held inside the hydration window, channel-primed entries are
+ * settled, and mutations do not transfer across SSR. So the server
+ * serializes the empty value, and a hydrated mount latches there until its
+ * window closes: the subscription and first sync run from an effect half,
+ * deferred past hydration — the earliest globally-safe moment for a
+ * cross-cache read to go live (on a streamed page, an already-hydrated
+ * region's refetch can be in flight while this region is still claiming).
+ *
+ * Every node here is created on the server too, where it is never read or
+ * written: hydration id assignment is positional, so both sides must create
+ * the same reactive nodes or every id downstream shifts and the subtree
+ * key-misses.
+ */
+export function createCacheAggregate<T>(
+  subscribe: (onEvent: () => void) => () => void,
+  read: (prev: T) => T,
+  empty: T,
+): Accessor<T> {
+  const hydratedMount =
+    !isServer && (sharedConfig as { hydrating?: boolean }).hydrating === true
+
+  // Cast: createSignal's value overload excludes functions (a function
+  // argument means a compute); aggregate values are counts and arrays.
+  const [durable, setDurable] = createSignal<T>(
+    (hydratedMount || isServer ? empty : untrack(() => read(empty))) as Exclude<
+      T,
+      Function
+    >,
+    { ownedWrite: true },
+  )
+  const [value, setValue] = createOptimistic(() => durable(), {
+    ownedWrite: true,
+  })
+
+  const sync = () => {
+    const next = untrack(() => read(untrack(durable)))
+    setDurable(() => next)
+    setValue(() => next)
+  }
+  let unsubscribe: (() => void) | null = null
+  const attach = () => {
+    unsubscribe ??= untrack(() => subscribe(sync))
+  }
+  onCleanup(() => unsubscribe?.())
+
+  createEffect(
+    () => undefined,
+    () => {
+      if (hydratedMount) {
+        attach()
+        sync()
+      }
+    },
+  )
+
+  if (isServer) return () => empty
+  if (!hydratedMount) attach()
+  return value
+}

package/src/dehydrateSettled.ts

@@ -0,0 +1,42 @@
+import { dehydrate } from '@tanstack/query-core'
+import type { DehydrateOptions, DehydratedState } from '@tanstack/query-core'
+import type { QueryClient } from './QueryClient'
+
+/**
+ * Waits for every fetch the client has in flight to settle, then
+ * dehydrates. This is the extraction half of a single-flight collector:
+ * after route data functions run for the mutation's target URL, loaders
+ * commonly kick off prefetches without awaiting them — plain
+ * `dehydrate()` would snapshot those mid-fetch and ship nothing.
+ *
+ * ```ts
+ * registerFlightDataSource(FLIGHT_DATA_SOURCE, (event, outcome) =>
+ *   loadFlightTarget({
+ *     router,
+ *     event,
+ *     outcome,
+ *     collect: () => dehydrateSettled(queryClient),
+ *   }),
+ * )
+ * ```
+ *
+ * Settling is chased to quiescence — awaiting one batch of fetches can
+ * dispatch more (dependent queries keyed off a first result) — so an
+ * unconditionally self-refetching query would keep this pending; that's
+ * an app bug mirrored, not guarded.
+ */
+export async function dehydrateSettled(
+  client: QueryClient,
+  options?: DehydrateOptions,
+): Promise<DehydratedState> {
+  const cache = client.getQueryCache()
+  for (;;) {
+    const pending = cache
+      .getAll()
+      .filter((query) => query.state.fetchStatus !== 'idle')
+      .map((query) => query.promise)
+    if (pending.length === 0) break
+    await Promise.allSettled(pending)
+  }
+  return dehydrate(client, options)
+}

package/src/index.ts

@@ -1,10 +1,5 @@
 /* istanbul ignore file */
 
-import { useQuery } from './useQuery'
-import { useInfiniteQuery } from './useInfiniteQuery'
-import { useMutation } from './useMutation'
-import { useQueries } from './useQueries'
-
 // Re-export core
 export * from '@tanstack/query-core'
 
@@ -23,27 +18,11 @@ export type {
   UseBaseQueryResult,
   UseInfiniteQueryOptions,
   UseInfiniteQueryResult,
-  UseMutateAsyncFunction,
   UseMutateFunction,
   UseMutationOptions,
   UseMutationResult,
   UseQueryOptions,
   UseQueryResult,
-  // Aliases (create* and use* are both supported)
-  UseBaseQueryOptions as CreateBaseQueryOptions,
-  UseBaseQueryResult as CreateBaseQueryResult,
-  UseInfiniteQueryOptions as CreateInfiniteQueryOptions,
-  UseInfiniteQueryResult as CreateInfiniteQueryResult,
-  UseMutateAsyncFunction as CreateMutateAsyncFunction,
-  UseMutateFunction as CreateMutateFunction,
-  UseMutationOptions as CreateMutationOptions,
-  UseMutationResult as CreateMutationResult,
-  UseBaseMutationResult as CreateBaseMutationResult,
-  UseQueryOptions as CreateQueryOptions,
-  UseQueryResult as CreateQueryResult,
-  DefinedUseBaseQueryResult as DefinedCreateBaseQueryResult,
-  DefinedUseInfiniteQueryResult as DefinedCreateInfiniteQueryResult,
-  DefinedUseQueryResult as DefinedCreateQueryResult,
 } from './types'
 
 export { QueryClient } from './QueryClient'
@@ -54,22 +33,21 @@ export type {
   InfiniteQueryObserverOptions,
 } from './QueryClient'
 export { useQuery } from './useQuery'
-export const createQuery = useQuery
 export { queryOptions } from './queryOptions'
 export type {
   DefinedInitialDataOptions,
   UndefinedInitialDataOptions,
 } from './queryOptions'
 export {
+  FLIGHT_DATA_SOURCE,
   QueryClientContext,
   QueryClientProvider,
   useQueryClient,
 } from './QueryClientProvider'
 export type { QueryClientProviderProps } from './QueryClientProvider'
+export { dehydrateSettled } from './dehydrateSettled'
 export { useIsFetching } from './useIsFetching'
-export { useIsFetching as createIsFetching } from './useIsFetching'
-export { useInfiniteQuery }
-export const createInfiniteQuery = useInfiniteQuery
+export { useInfiniteQuery } from './useInfiniteQuery'
 export { infiniteQueryOptions } from './infiniteQueryOptions'
 export type {
   DefinedInitialDataInfiniteOptions,
@@ -77,11 +55,7 @@ export type {
 } from './infiniteQueryOptions'
 export { useMutation } from './useMutation'
 export { mutationOptions } from './mutationOptions'
-export const createMutation = useMutation
 export { useIsMutating } from './useIsMutating'
-export { useIsMutating as createIsMutating } from './useIsMutating'
 export { useMutationState } from './useMutationState'
-export { useMutationState as createMutationState } from './useMutationState'
 export { useQueries } from './useQueries'
-export const createQueries = useQueries
 export { useIsRestoring, IsRestoringContext } from './isRestoring'