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

package/src/useInfiniteQuery.ts

@@ -1,9 +1,12 @@
 import { InfiniteQueryObserver } from '@tanstack/query-core'
 import { createMemo } from 'solid-js'
-import { useBaseQuery } from './useBaseQuery'
+import { useBaseQueryLayer } from './useBaseQuery'
 import type {
   DefaultError,
+  FetchNextPageOptions,
+  FetchPreviousPageOptions,
   InfiniteData,
+  InfiniteQueryObserverResult,
   QueryKey,
   QueryObserver,
 } from '@tanstack/query-core'
@@ -19,6 +22,58 @@ import type {
   UndefinedInitialDataInfiniteOptions,
 } from './infiniteQueryOptions'
 
+/**
+ * Page-boundary checks, mirrored from query-core's `infiniteQueryBehavior`
+ * (they are module-private there — not exported through the package index).
+ * Pure functions of options + cached data; keep byte-compatible with core.
+ */
+interface PageParamsOptions {
+  getNextPageParam: (
+    lastPage: unknown,
+    pages: Array<unknown>,
+    lastPageParam: unknown,
+    pageParams: Array<unknown>,
+  ) => unknown
+  getPreviousPageParam?: (
+    firstPage: unknown,
+    pages: Array<unknown>,
+    firstPageParam: unknown,
+    pageParams: Array<unknown>,
+  ) => unknown
+}
+
+function hasNextPage(
+  options: PageParamsOptions,
+  data?: InfiniteData<unknown>,
+): boolean {
+  if (!data || data.pages.length === 0) return false
+  const lastIndex = data.pages.length - 1
+  return (
+    options.getNextPageParam(
+      data.pages[lastIndex],
+      data.pages,
+      data.pageParams[lastIndex],
+      data.pageParams,
+    ) != null
+  )
+}
+
+function hasPreviousPage(
+  options: PageParamsOptions,
+  data?: InfiniteData<unknown>,
+): boolean {
+  if (!data || data.pages.length === 0 || !options.getPreviousPageParam)
+    return false
+  return (
+    options.getPreviousPageParam(
+      data.pages[0],
+      data.pages,
+      data.pageParams[0],
+      data.pageParams,
+    ) != null
+  )
+}
+
 export function useInfiniteQuery<
   TQueryFnData,
   TError = DefaultError,
@@ -68,9 +123,106 @@ export function useInfiniteQuery<
   >,
   queryClient?: Accessor<QueryClient>,
 ): UseInfiniteQueryResult<TData, TError> {
-  return useBaseQuery(
-    createMemo(() => options()),
+  /**
+   * Pagers ride the same entry as every other read: the base layer owns
+   * the data node, meta projection, and lifecycle observer (an
+   * `InfiniteQueryObserver`, so mount policy and refetches use the
+   * infinite behavior). This layer adds the page surface on top.
+   */
+  const layer = useBaseQueryLayer(
+    // `_type` is how query-core stamps a cache entry as infinite
+    // (`Query.setOptions` → `#queryType`), which makes every fetch attach
+    // `infiniteQueryBehavior`. Core only sets it inside
+    // `InfiniteQueryObserver.setOptions`, but the adapter's pull path can
+    // build and fetch the entry first (reactive key change recomputes the
+    // data memo before the deferred observer effect runs) — without the
+    // stamp that fetch would run as a plain query and corrupt the entry.
+    createMemo(() => ({ ...options(), _type: 'infinite' }) as any),
     InfiniteQueryObserver as typeof QueryObserver,
     queryClient,
-  ) as UseInfiniteQueryResult<TData, TError>
+  )
+  const observer = layer.observer as unknown as InfiniteQueryObserver<
+    TQueryFnData,
+    TError,
+    TData,
+    TQueryKey,
+    TPageParam
+  >
+
+  /** Committed fetch direction — set when a page fetch dispatches,
+   * version-tracked through the layer's query accessor. */
+  const direction = () =>
+    (layer.query().state.fetchMeta as any)?.fetchMore?.direction
+
+  const pageOptions = () =>
+    layer.defaultedOptions() as unknown as PageParamsOptions
+  const infiniteData = () =>
+    layer.query().state.data as InfiniteData<unknown> | undefined
+
+  const isFetchingNextPage = () =>
+    layer.isFetching() && direction() === 'forward'
+  const isFetchingPreviousPage = () =>
+    layer.isFetching() && direction() === 'backward'
+  const isError = () => layer.status() === 'error'
+
+  // The base result's getters transfer as-is; the infinite surface layers
+  // over them, and isRefetching/isRefetchError narrow to exclude page
+  // fetches (matching core's InfiniteQueryObserver result shape).
+  const result = Object.defineProperties(
+    {},
+    {
+      ...Object.getOwnPropertyDescriptors(layer.result),
+      fetchNextPage: {
+        value: (fetchOptions?: FetchNextPageOptions) =>
+          observer.fetchNextPage(fetchOptions),
+        enumerable: true,
+      },
+      fetchPreviousPage: {
+        value: (fetchOptions?: FetchPreviousPageOptions) =>
+          observer.fetchPreviousPage(fetchOptions),
+        enumerable: true,
+      },
+      hasNextPage: {
+        get: () => hasNextPage(pageOptions(), infiniteData()),
+        enumerable: true,
+      },
+      hasPreviousPage: {
+        get: () => hasPreviousPage(pageOptions(), infiniteData()),
+        enumerable: true,
+      },
+      isFetchingNextPage: {
+        get: isFetchingNextPage,
+        enumerable: true,
+      },
+      isFetchingPreviousPage: {
+        get: isFetchingPreviousPage,
+        enumerable: true,
+      },
+      isFetchNextPageError: {
+        get: () => isError() && direction() === 'forward',
+        enumerable: true,
+      },
+      isFetchPreviousPageError: {
+        get: () => isError() && direction() === 'backward',
+        enumerable: true,
+      },
+      isRefetching: {
+        get: () =>
+          layer.isFetching() &&
+          layer.status() !== 'pending' &&
+          !isFetchingNextPage() &&
+          !isFetchingPreviousPage(),
+        enumerable: true,
+      },
+      isRefetchError: {
+        get: () => {
+          const errored = isError() && layer.query().state.dataUpdatedAt !== 0
+          return errored && direction() === undefined
+        },
+        enumerable: true,
+      },
+    },
+  ) as InfiniteQueryObserverResult<TData, TError>
+
+  return result as unknown as UseInfiniteQueryResult<TData, TError>
 }

package/src/useIsFetching.ts

@@ -1,4 +1,5 @@
-import { createMemo, createSignal, onCleanup, untrack } from 'solid-js'
+import { createMemo } from 'solid-js'
+import { createCacheAggregate } from './cacheAggregate'
 import { useQueryClient } from './QueryClientProvider'
 import type { QueryFilters } from '@tanstack/query-core'
 import type { QueryClient } from './QueryClient'
@@ -9,20 +10,9 @@ export function useIsFetching(
   queryClient?: Accessor<QueryClient>,
 ): Accessor<number> {
   const client = createMemo(() => useQueryClient(queryClient?.()))
-  const queryCache = createMemo(() => client().getQueryCache())
-
-  const [fetches, setFetches] = createSignal(
-    untrack(() => client().isFetching(filters?.())),
-    { ownedWrite: true },
-  )
-
-  const unsubscribe = untrack(() =>
-    queryCache().subscribe(() => {
-      setFetches(client().isFetching(filters?.()))
-    }),
+  return createCacheAggregate(
+    (onEvent) => client().getQueryCache().subscribe(onEvent),
+    () => client().isFetching(filters?.()),
+    0,
   )
-
-  onCleanup(unsubscribe)
-
-  return fetches
 }

package/src/useIsMutating.ts

@@ -1,4 +1,5 @@
-import { createMemo, createSignal, onCleanup, untrack } from 'solid-js'
+import { createMemo } from 'solid-js'
+import { createCacheAggregate } from './cacheAggregate'
 import { useQueryClient } from './QueryClientProvider'
 import type { MutationFilters } from '@tanstack/query-core'
 import type { QueryClient } from './QueryClient'
@@ -9,20 +10,9 @@ export function useIsMutating(
   queryClient?: Accessor<QueryClient>,
 ): Accessor<number> {
   const client = createMemo(() => useQueryClient(queryClient?.()))
-  const mutationCache = createMemo(() => client().getMutationCache())
-
-  const [mutations, setMutations] = createSignal(
-    untrack(() => client().isMutating(filters?.())),
-    { ownedWrite: true },
-  )
-
-  const unsubscribe = untrack(() =>
-    mutationCache().subscribe((_result) => {
-      setMutations(client().isMutating(filters?.()))
-    }),
+  return createCacheAggregate(
+    (onEvent) => client().getMutationCache().subscribe(onEvent),
+    () => client().isMutating(filters?.()),
+    0,
   )
-
-  onCleanup(unsubscribe)
-
-  return mutations
 }

package/src/useMutation.ts

@@ -1,14 +1,19 @@
-import { MutationObserver, noop, shouldThrowError } from '@tanstack/query-core'
+import { noop, shouldThrowError } from '@tanstack/query-core'
 import {
+  action,
   createMemo,
+  createOptimistic,
   createRenderEffect,
-  createStore,
+  createSignal,
   onCleanup,
-  runWithOwner,
   untrack,
 } from 'solid-js'
 import { useQueryClient } from './QueryClientProvider'
-import type { DefaultError } from '@tanstack/query-core'
+import type {
+  DefaultError,
+  Mutation,
+  MutationFunctionContext,
+} from '@tanstack/query-core'
 import type { QueryClient } from './QueryClient'
 import type {
   UseMutateFunction,
@@ -17,7 +22,74 @@ import type {
 } from './types'
 import type { Accessor } from 'solid-js'
 
-// HOOK
+const isServer = typeof window === 'undefined'
+
+/**
+ * Durable mutation state: written post-`yield` inside the action's
+ * transaction, so it commits atomically with everything else the settle
+ * carries (invalidation-triggered refetches included).
+ */
+interface SettledState<TData, TError, TVariables> {
+  status: 'idle' | 'success' | 'error'
+  data: TData | undefined
+  error: TError | null
+  variables: TVariables | undefined
+  submittedAt: number
+}
+
+const IDLE: SettledState<any, any, any> = {
+  status: 'idle',
+  data: undefined,
+  error: null,
+  variables: undefined,
+  submittedAt: 0,
+}
+
+/**
+ * Drive the mutation generator without transaction semantics — the server
+ * has no interactive paint to keep atomic. Yielded thenable values are
+ * awaited and their results passed back in, matching what `action` does
+ * minus the transition bookkeeping.
+ */
+async function drain<TReturn>(
+  iterator: AsyncGenerator<unknown, TReturn, unknown>,
+): Promise<TReturn> {
+  let input: unknown
+  for (;;) {
+    const result = await iterator.next(input)
+    if (result.done) return result.value
+    input = result.value != null ? await result.value : undefined
+  }
+}
+
+/**
+ * Mutations ride core `action`: each `mutate()` call is one transaction.
+ *
+ * - Transient flight state (`isPending`, in-flight `variables`) is a
+ *   `createOptimistic` overlay written at the top of the action — visible
+ *   immediately, dropped automatically when the transition settles. The
+ *   engine's revert-on-settle IS the submission state machine.
+ * - `options.onMutate(variables)` runs inside the same window: it is the
+ *   place to apply the caller's own optimistic overlays
+ *   (`createOptimistic` / `createOptimisticStore` writes). No context
+ *   object, no rollback plumbing — reverting is the engine's job.
+ * - The fetch itself goes through query-core:
+ *   `mutationCache.build().execute()` supplies retry/backoff, offline
+ *   pausing, scoped serial execution, and cache-level lifecycle callbacks.
+ *   No `MutationObserver` — the adapter reads the Mutation's state
+ *   directly where flight metadata (failureCount, isPaused) is needed.
+ * - Options-level callbacks are stripped from the built mutation and
+ *   re-run *post-`yield`*, inside the transaction: an
+ *   `onSuccess → invalidateQueries` chain issues version bumps whose
+ *   refetches hold this very transition, so mutation success and fresh
+ *   query data land in one atomic paint (and a single-flight payload has
+ *   already primed the cache by the time `execute` resolves).
+ * - One `mutate`, returning a safe-to-ignore promise: rejection is also
+ *   routed into reactive state, and a no-op catch keeps the ignored
+ *   branch from surfacing as an unhandled rejection. The
+ *   `mutate`/`mutateAsync` split existed for React's callback-vs-promise
+ *   error routing; it has no space here.
+ */
 export function useMutation<
   TData = unknown,
   TError = DefaultError,
@@ -29,74 +101,249 @@ export function useMutation<
 ): UseMutationResult<TData, TError, TVariables, TOnMutateResult> {
   const client = createMemo(() => useQueryClient(queryClient?.()))
 
-  const observer = untrack(
-    () =>
-      new MutationObserver<TData, TError, TVariables, TOnMutateResult>(
-        client(),
-        options(),
-      ),
-  )
+  /** Optimistic overlay: non-null exactly while a mutation is in flight. */
+  const [flight, setFlight] = createOptimistic<{
+    variables: TVariables
+  } | null>(null)
 
-  // Track options changes and update observer
-  createRenderEffect(
-    () => options(),
-    (opts) => {
-      observer.setOptions(opts)
-    },
-  )
+  const [settled, setSettled] = createSignal<
+    SettledState<TData, TError, TVariables>
+  >(IDLE as SettledState<TData, TError, TVariables>)
+
+  /**
+   * Flight metadata (retry failures, offline pause) lives on the Mutation
+   * instance and changes during the await gap; a version bump per cache
+   * event for the active mutation keeps reads current without cloning
+   * observer results.
+   */
+  let activeMutation: Mutation<TData, TError, TVariables> | null = null
+  const [flightVersion, setFlightVersion] = createSignal(0)
+  if (!isServer) {
+    const unsubscribe = client()
+      .getMutationCache()
+      .subscribe((event) => {
+        if ('mutation' in event && event.mutation === activeMutation) {
+          setFlightVersion((v) => v + 1)
+        }
+      })
+    onCleanup(unsubscribe)
+  }
+
+  async function* run(
+    variables: TVariables,
+  ): AsyncGenerator<unknown, TData, unknown> {
+    const opts = untrack(options)
+    const callbackContext: MutationFunctionContext = {
+      client: untrack(client),
+      meta: opts.meta,
+      mutationKey: opts.mutationKey,
+    }
+    // Server render is pure (rc.3 deprecates server setter calls): the
+    // drain path only needs the return value/throw, so all reactive
+    // bookkeeping — flight overlay and durable settle — is client-only.
+    if (!isServer) setFlight({ variables })
+    opts.onMutate?.(variables, callbackContext)
+
+    const mutation = client()
+      .getMutationCache()
+      .build(client(), {
+        ...opts,
+        // Options-level callbacks re-run below, inside the transaction —
+        // executing them here (inside the await gap) would let their
+        // cache writes and invalidations escape the atomic settle.
+        onMutate: undefined,
+        onSuccess: undefined,
+        onError: undefined,
+        onSettled: undefined,
+      }) as unknown as Mutation<TData, TError, TVariables>
+    activeMutation = mutation
+
+    /**
+     * Failure settle, shared by both paths. Callback routing mirrors
+     * query-core's `Mutation.execute` (which never sees these callbacks —
+     * they are stripped from the built mutation and re-run here, inside
+     * the transaction): `onError` and an error-shaped `onSettled` run,
+     * their own failures are reported as unhandled rejections but never
+     * displace `error`, then the durable error state commits and the
+     * mutate promise rejects with `error`.
+     */
+    // Must be an async generator: async `yield` awaits its value in place,
+    // so a rejecting callback promise throws at the yield inside the local
+    // try/catch. A sync generator delegated from an async one gets its
+    // values unwrapped by the async-from-sync adapter *outside* the inner
+    // frame — the rejection would bypass these catches and kill the run.
+    // eslint-disable-next-line @typescript-eslint/require-await -- async for yield-await semantics, not await expressions
+    async function* settleFailure(
+      error: TError,
+    ): AsyncGenerator<unknown, never, unknown> {
+      try {
+        if (opts.onError)
+          yield opts.onError(error, variables, undefined, callbackContext)
+      } catch (callbackError) {
+        void Promise.reject(callbackError)
+      }
+      try {
+        if (opts.onSettled)
+          yield opts.onSettled(
+            undefined,
+            error,
+            variables,
+            undefined,
+            callbackContext,
+          )
+      } catch (callbackError) {
+        void Promise.reject(callbackError)
+      }
+      if (!isServer)
+        setSettled({
+          status: 'error',
+          data: undefined,
+          error,
+          variables,
+          submittedAt: mutation.state.submittedAt,
+        })
+      activeMutation = null
+      throw error
+    }
+
+    let result: TData
+    try {
+      result = await mutation.execute(variables)
+    } catch (error) {
+      yield // re-enter the transaction before writing
+      yield* settleFailure(error as TError)
+      // Unreachable — settleFailure always throws. Explicit for TS's
+      // definite-assignment analysis of `result` (yield* delegation is
+      // not narrowed as never-returning).
+      throw error
+    }
+    yield // re-enter the transaction before writing
+    try {
+      if (opts.onSuccess)
+        yield opts.onSuccess(
+          result,
+          variables,
+          undefined as TOnMutateResult,
+          callbackContext,
+        )
+      if (opts.onSettled)
+        yield opts.onSettled(
+          result,
+          null,
+          variables,
+          undefined,
+          callbackContext,
+        )
+    } catch (callbackError) {
+      // Mirror core: a success-path callback failure fails the mutation —
+      // even though the cache entry committed success, the hook settles
+      // to error with the callback error, and awaiting mutate rejects.
+      yield* settleFailure(callbackError as TError)
+      // Unreachable — settleFailure always throws (see above).
+      throw callbackError
+    }
+    if (!isServer)
+      setSettled({
+        status: 'success',
+        data: result,
+        error: null,
+        variables,
+        submittedAt: mutation.state.submittedAt,
+      })
+    activeMutation = null
+    return result
+  }
+
+  const invoke: (variables: TVariables) => Promise<TData> = isServer
+    ? (variables) => drain(run(variables))
+    : action(run)
 
   const mutate: UseMutateFunction<
     TData,
     TError,
     TVariables,
     TOnMutateResult
-  > = (variables, mutateOptions) => {
-    observer.mutate(variables, mutateOptions).catch(noop)
+  > = (variables) => {
+    const promise = invoke(variables)
+    // Errors also land in reactive state; ignoring the promise must not
+    // surface an unhandled rejection. Awaiting it still rejects.
+    promise.catch(noop)
+    return promise
   }
 
-  const initialResult = untrack(() => observer.getCurrentResult())
-  const [state, setState] = createStore<
-    UseMutationResult<TData, TError, TVariables, TOnMutateResult>
-  >({
-    ...initialResult,
-    mutate,
-    mutateAsync: initialResult.mutate,
-  })
-
-  const unsubscribe = observer.subscribe((result) => {
-    // observer.mutate may be invoked synchronously from an owned scope (e.g.
-    // during render or inside an effect), which triggers this subscriber
-    // synchronously. Store writes inside an owned scope throw in Solid v2, so
-    // escape the owner to allow the setState write — matching useBaseQuery.
-    runWithOwner(null, () => {
-      setState(() => ({
-        ...result,
-        mutate,
-        mutateAsync: result.mutate,
-      }))
-    })
-  })
-
-  onCleanup(unsubscribe)
-
-  // Use createRenderEffect to throw errors when throwOnError is set.
-  // The throw must happen in the compute function (first arg), not the effect
-  // function, so that the error goes through notifyStatus and gets wrapped as
-  // a StatusError with a source — which is required for <Errored> boundaries
-  // to capture it via CollectionQueue.notify.
+  const status = () => (flight() !== null ? 'pending' : settled().status)
+  const isPending = () => flight() !== null
+
+  /**
+   * Errors surface to `<Errored>` when `throwOnError` opts in. The throw
+   * must happen in the compute half so it routes through notifyStatus and
+   * boundary accounting.
+   */
   createRenderEffect(
     () => {
-      const isError = state.isError
-      const error = state.error
+      const state = settled()
       if (
-        isError &&
-        shouldThrowError(observer.options.throwOnError, [error as TError])
+        state.status === 'error' &&
+        shouldThrowError(untrack(options).throwOnError, [state.error as TError])
       ) {
-        throw error
+        throw state.error
       }
     },
     () => {},
   )
 
-  return state
+  const result = {
+    mutate,
+    get data() {
+      return settled().data
+    },
+    get error() {
+      return flight() !== null ? null : settled().error
+    },
+    get variables() {
+      return flight()?.variables ?? settled().variables
+    },
+    get status() {
+      return status()
+    },
+    get isPending() {
+      return isPending()
+    },
+    get isIdle() {
+      return status() === 'idle'
+    },
+    get isSuccess() {
+      return status() === 'success'
+    },
+    get isError() {
+      return status() === 'error'
+    },
+    get submittedAt() {
+      return flight() !== null
+        ? (flightVersion(), activeMutation?.state.submittedAt ?? 0)
+        : settled().submittedAt
+    },
+    get failureCount() {
+      flightVersion()
+      return activeMutation?.state.failureCount ?? 0
+    },
+    get failureReason() {
+      flightVersion()
+      return (activeMutation?.state.failureReason ?? null) as TError | null
+    },
+    get isPaused() {
+      flightVersion()
+      return activeMutation?.state.isPaused ?? false
+    },
+    reset: () => {
+      setSettled(IDLE as SettledState<TData, TError, TVariables>)
+    },
+  }
+
+  return result as unknown as UseMutationResult<
+    TData,
+    TError,
+    TVariables,
+    TOnMutateResult
+  >
 }

package/src/useMutationState.ts

@@ -1,5 +1,6 @@
-import { createMemo, createSignal, onCleanup, untrack } from 'solid-js'
+import { createMemo } from 'solid-js'
 import { replaceEqualDeep } from '@tanstack/query-core'
+import { createCacheAggregate } from './cacheAggregate'
 import { useQueryClient } from './QueryClientProvider'
 import type {
   Mutation,
@@ -32,26 +33,12 @@ export function useMutationState<TResult = MutationState>(
   queryClient?: Accessor<QueryClient>,
 ): Accessor<Array<TResult>> {
   const client = createMemo(() => useQueryClient(queryClient?.()))
-  const mutationCache = createMemo(() => client().getMutationCache())
-
-  const [result, setResult] = createSignal(
-    untrack(() => getResult(mutationCache(), options())),
-    { ownedWrite: true },
-  )
-
-  const unsubscribe = untrack(() =>
-    mutationCache().subscribe(() => {
-      setResult((prev) => {
-        const nextResult = replaceEqualDeep(
-          prev,
-          getResult(mutationCache(), options()),
-        )
-        return prev === nextResult ? prev : nextResult
-      })
-    }),
+  return createCacheAggregate<Array<TResult>>(
+    (onEvent) => client().getMutationCache().subscribe(onEvent),
+    // Structural sharing against the previous committed value keeps
+    // unchanged mutation states referentially stable across syncs.
+    (prev) =>
+      replaceEqualDeep(prev, getResult(client().getMutationCache(), options())),
+    [],
   )
-
-  onCleanup(unsubscribe)
-
-  return result
 }