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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/solid-query",
-  "version": "6.0.0-rc.0",
+  "version": "6.0.0-rc.1",
   "description": "Primitives for managing, caching and syncing asynchronous and remote data in Solid",
   "author": "tannerlinsley",
   "license": "MIT",
@@ -46,22 +46,22 @@
     "!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.3",
+    "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.4",
     "tsup-preset-solid": "^2.2.0",
     "@tanstack/query-test-utils": "0.0.0"
   },
   "peerDependencies": {
-    "solid-js": ">=2.0.0-rc.0 <3.0.0"
+    "solid-js": ">=2.0.0-rc.4 <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,18 @@
-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 type { 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:'
+
 export const QueryClientContext = createContext<(() => QueryClient) | null>(
   null,
 )
@@ -38,59 +35,81 @@ 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()
+  const seen = new Set<string>()
+  const serializeQuery = (query: Query<any, any, any, any>) => {
+    if (seen.has(query.queryHash)) 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`.
+ */
 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)
 
   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/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,7 +33,6 @@ export type {
   InfiniteQueryObserverOptions,
 } from './QueryClient'
 export { useQuery } from './useQuery'
-export const createQuery = useQuery
 export { queryOptions } from './queryOptions'
 export type {
   DefinedInitialDataOptions,
@@ -67,9 +45,7 @@ export {
 } from './QueryClientProvider'
 export type { QueryClientProviderProps } from './QueryClientProvider'
 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 +53,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'

package/src/types.ts

@@ -5,7 +5,6 @@ import type {
   DefinedInfiniteQueryObserverResult,
   DefinedQueryObserverResult,
   InfiniteQueryObserverResult,
-  MutateFunction,
   MutationObserverOptions,
   MutationObserverResult,
   OmitKeyof,
@@ -30,18 +29,22 @@ export interface UseBaseQueryOptions<
   'suspense'
 > {
   /**
-   * Only applicable while rendering queries on the server with streaming.
-   * Set `deferStream` to `true` to wait for the query to resolve on the server before flushing the stream.
-   * This can be useful to avoid sending a loading state to the client before the query has resolved.
-   * Defaults to `false`.
+   * Defer the SSR stream flush until this query resolves on the server,
+   * instead of letting the surrounding `<Loading>` boundary render its
+   * fallback into the HTML. Passed through to Solid's own per-computation
+   * `deferStream` option; server-only, ignored on the client.
    */
   deferStream?: boolean
   /**
-   * @deprecated The `suspense` option has been deprecated in v5 and will be removed in the next major version.
-   * The `data` property on useQuery is a SolidJS resource and will automatically suspend when the data is loading.
-   * Setting `suspense` to `false` will be a no-op.
+   * Reconciliation key for the data store. `data` is served as a Solid
+   * store projection: every landing (refetch, invalidation, placeholder
+   * upgrade) reconciles into the existing proxy graph instead of replacing
+   * it, so deep reads are fine-grained and item identity survives across
+   * fetches. This sets the identity key for that reconciliation — a
+   * property name, a key-extraction function, or `null` to merge
+   * positionally. Defaults to `'id'`. Read once at creation.
    */
-  suspense?: boolean
+  reconcile?: string | ((item: NonNullable<any>) => any) | null
 }
 
 export interface QueryOptions<
@@ -66,20 +69,39 @@ export type UseQueryOptions<
 
 /* --- Create Query and Create Base Query  Types --- */
 
+/**
+ * `data` is non-optional: it is a suspending async read. It never returns
+ * `undefined` — a read either suspends into the nearest `<Loading>`
+ * boundary (first fetch in flight, disabled, restoring), returns a value
+ * (committed, placeholder, initial), or throws (`<Errored>` /
+ * `throwOnError`). The v5 `TData | undefined` face existed because reads
+ * could observe the pre-fetch gap; here that gap is suspension.
+ */
 export type UseBaseQueryResult<
   TData = unknown,
   TError = DefaultError,
-> = QueryObserverResult<TData, TError>
+> = Override<
+  OmitKeyof<QueryObserverResult<TData, TError>, 'isInitialLoading'>,
+  { data: TData }
+>
 
 export type UseQueryResult<
   TData = unknown,
   TError = DefaultError,
 > = UseBaseQueryResult<TData, TError>
 
+/**
+ * Distributes an `isInitialLoading` omit over result unions so status
+ * discriminants survive (a plain Omit over a union collapses it).
+ */
+type OmitIsInitialLoading<T> = T extends unknown
+  ? OmitKeyof<T, 'isInitialLoading' & keyof T>
+  : never
+
 export type DefinedUseBaseQueryResult<
   TData = unknown,
   TError = DefaultError,
-> = DefinedQueryObserverResult<TData, TError>
+> = OmitIsInitialLoading<DefinedQueryObserverResult<TData, TError>>
 
 export type DefinedUseQueryResult<
   TData = unknown,
@@ -105,18 +127,16 @@ export interface InfiniteQueryOptions<
 > {
   queryKey: TQueryKey
   /**
-   * Only applicable while rendering queries on the server with streaming.
-   * Set `deferStream` to `true` to wait for the query to resolve on the server before flushing the stream.
-   * This can be useful to avoid sending a loading state to the client before the query has resolved.
-   * Defaults to `false`.
+   * Defer the SSR stream flush until this query resolves on the server —
+   * see {@link UseBaseQueryOptions.deferStream}.
    */
   deferStream?: boolean
   /**
-   * @deprecated The `suspense` option has been deprecated in v5 and will be removed in the next major version.
-   * The `data` property on useInfiniteQuery is a SolidJS resource and will automatically suspend when the data is loading.
-   * Setting `suspense` to `false` will be a no-op.
+   * Reconciliation key for the data store — see
+   * {@link UseBaseQueryOptions.reconcile}. For infinite queries this keys
+   * items within pages; pages themselves merge positionally.
    */
-  suspense?: boolean
+  reconcile?: string | ((item: NonNullable<any>) => any) | null
 }
 
 export type UseInfiniteQueryOptions<
@@ -129,15 +149,19 @@ export type UseInfiniteQueryOptions<
   InfiniteQueryOptions<TQueryFnData, TError, TData, TQueryKey, TPageParam>
 >
 
+/** Non-optional `data` for the same reason as {@link UseBaseQueryResult}. */
 export type UseInfiniteQueryResult<
   TData = unknown,
   TError = DefaultError,
-> = InfiniteQueryObserverResult<TData, TError>
+> = Override<
+  OmitKeyof<InfiniteQueryObserverResult<TData, TError>, 'isInitialLoading'>,
+  { data: TData }
+>
 
 export type DefinedUseInfiniteQueryResult<
   TData = unknown,
   TError = DefaultError,
-> = DefinedInfiniteQueryObserverResult<TData, TError>
+> = OmitIsInitialLoading<DefinedInfiniteQueryObserverResult<TData, TError>>
 
 /* --- Create Mutation Types --- */
 export interface MutationOptions<
@@ -157,23 +181,21 @@ export type UseMutationOptions<
   TOnMutateResult = unknown,
 > = Accessor<MutationOptions<TData, TError, TVariables, TOnMutateResult>>
 
+/**
+ * One `mutate`, returning a safe-to-ignore promise: errors are also routed
+ * into reactive state, and ignoring the promise never surfaces an
+ * unhandled rejection. Call-site callbacks are gone — settle logic that
+ * used to live in `mutate(vars, { onSuccess })` is linear code after
+ * `await mutate(vars)` or a config-level callback.
+ */
 export type UseMutateFunction<
   TData = unknown,
-  TError = DefaultError,
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  _TError = DefaultError,
   TVariables = void,
-  TOnMutateResult = unknown,
-> = (
-  ...args: Parameters<
-    MutateFunction<TData, TError, TVariables, TOnMutateResult>
-  >
-) => void
-
-export type UseMutateAsyncFunction<
-  TData = unknown,
-  TError = DefaultError,
-  TVariables = void,
-  TOnMutateResult = unknown,
-> = MutateFunction<TData, TError, TVariables, TOnMutateResult>
+  // eslint-disable-next-line @typescript-eslint/naming-convention
+  _TOnMutateResult = unknown,
+> = (variables: TVariables) => Promise<TData>
 
 export type UseBaseMutationResult<
   TData = unknown,
@@ -181,16 +203,12 @@ export type UseBaseMutationResult<
   TVariables = unknown,
   TOnMutateResult = unknown,
 > = Override<
-  MutationObserverResult<TData, TError, TVariables, TOnMutateResult>,
+  OmitKeyof<
+    MutationObserverResult<TData, TError, TVariables, TOnMutateResult>,
+    'context'
+  >,
   { mutate: UseMutateFunction<TData, TError, TVariables, TOnMutateResult> }
-> & {
-  mutateAsync: UseMutateAsyncFunction<
-    TData,
-    TError,
-    TVariables,
-    TOnMutateResult
-  >
-}
+>
 
 export type UseMutationResult<
   TData = unknown,