@pyreon/query 0.0.1

package/src/use-infinite-query.ts

@@ -0,0 +1,138 @@
+import { onUnmount } from '@pyreon/core'
+import { signal, effect, batch } from '@pyreon/reactivity'
+import type { Signal } from '@pyreon/reactivity'
+import { InfiniteQueryObserver } from '@tanstack/query-core'
+import type {
+  DefaultError,
+  InfiniteData,
+  InfiniteQueryObserverOptions,
+  InfiniteQueryObserverResult,
+  QueryKey,
+  QueryObserverResult,
+} from '@tanstack/query-core'
+import { useQueryClient } from './query-client'
+
+export interface UseInfiniteQueryResult<TQueryFnData, TError = DefaultError> {
+  /** Raw signal — full observer result. */
+  result: Signal<
+    InfiniteQueryObserverResult<InfiniteData<TQueryFnData>, TError>
+  >
+  data: Signal<InfiniteData<TQueryFnData> | undefined>
+  error: Signal<TError | null>
+  status: Signal<'pending' | 'error' | 'success'>
+  isPending: Signal<boolean>
+  isLoading: Signal<boolean>
+  isFetching: Signal<boolean>
+  isFetchingNextPage: Signal<boolean>
+  isFetchingPreviousPage: Signal<boolean>
+  isError: Signal<boolean>
+  isSuccess: Signal<boolean>
+  hasNextPage: Signal<boolean>
+  hasPreviousPage: Signal<boolean>
+  fetchNextPage: () => Promise<
+    InfiniteQueryObserverResult<InfiniteData<TQueryFnData>, TError>
+  >
+  fetchPreviousPage: () => Promise<
+    InfiniteQueryObserverResult<InfiniteData<TQueryFnData>, TError>
+  >
+  refetch: () => Promise<
+    QueryObserverResult<InfiniteData<TQueryFnData>, TError>
+  >
+}
+
+/**
+ * Subscribe to a paginated / infinite-scroll query.
+ * Returns fine-grained reactive signals plus `fetchNextPage`, `fetchPreviousPage`,
+ * `hasNextPage` and `hasPreviousPage`.
+ *
+ * @example
+ * const query = useInfiniteQuery(() => ({
+ *   queryKey: ['posts'],
+ *   queryFn: ({ pageParam }) => fetchPosts(pageParam as number),
+ *   initialPageParam: 0,
+ *   getNextPageParam: (lastPage) => lastPage.nextCursor,
+ * }))
+ * // query.data()?.pages  — array of pages
+ * // h('button', { onClick: () => query.fetchNextPage() }, 'Load more')
+ */
+export function useInfiniteQuery<
+  TQueryFnData = unknown,
+  TError = DefaultError,
+  TQueryKey extends QueryKey = QueryKey,
+  TPageParam = unknown,
+>(
+  options: () => InfiniteQueryObserverOptions<
+    TQueryFnData,
+    TError,
+    InfiniteData<TQueryFnData>,
+    TQueryKey,
+    TPageParam
+  >,
+): UseInfiniteQueryResult<TQueryFnData, TError> {
+  const client = useQueryClient()
+  const observer = new InfiniteQueryObserver<
+    TQueryFnData,
+    TError,
+    InfiniteData<TQueryFnData>,
+    TQueryKey,
+    TPageParam
+  >(client, options())
+  const initial = observer.getCurrentResult()
+
+  const resultSig = signal(initial)
+  const dataSig = signal<InfiniteData<TQueryFnData> | undefined>(initial.data)
+  const errorSig = signal<TError | null>(initial.error ?? null)
+  const statusSig = signal(initial.status)
+  const isPending = signal(initial.isPending)
+  const isLoading = signal(initial.isLoading)
+  const isFetching = signal(initial.isFetching)
+  const isFetchingNextPage = signal(initial.isFetchingNextPage)
+  const isFetchingPreviousPage = signal(initial.isFetchingPreviousPage)
+  const isError = signal(initial.isError)
+  const isSuccess = signal(initial.isSuccess)
+  const hasNextPage = signal(initial.hasNextPage)
+  const hasPreviousPage = signal(initial.hasPreviousPage)
+
+  const unsub = observer.subscribe((r) => {
+    batch(() => {
+      resultSig.set(r)
+      dataSig.set(r.data)
+      errorSig.set(r.error ?? null)
+      statusSig.set(r.status)
+      isPending.set(r.isPending)
+      isLoading.set(r.isLoading)
+      isFetching.set(r.isFetching)
+      isFetchingNextPage.set(r.isFetchingNextPage)
+      isFetchingPreviousPage.set(r.isFetchingPreviousPage)
+      isError.set(r.isError)
+      isSuccess.set(r.isSuccess)
+      hasNextPage.set(r.hasNextPage)
+      hasPreviousPage.set(r.hasPreviousPage)
+    })
+  })
+
+  effect(() => {
+    observer.setOptions(options())
+  })
+
+  onUnmount(() => unsub())
+
+  return {
+    result: resultSig,
+    data: dataSig,
+    error: errorSig,
+    status: statusSig,
+    isPending,
+    isLoading,
+    isFetching,
+    isFetchingNextPage,
+    isFetchingPreviousPage,
+    isError,
+    isSuccess,
+    hasNextPage,
+    hasPreviousPage,
+    fetchNextPage: () => observer.fetchNextPage(),
+    fetchPreviousPage: () => observer.fetchPreviousPage(),
+    refetch: () => observer.refetch(),
+  }
+}

package/src/use-is-fetching.ts

@@ -0,0 +1,44 @@
+import { onUnmount } from '@pyreon/core'
+import { signal } from '@pyreon/reactivity'
+import type { Signal } from '@pyreon/reactivity'
+import type { MutationFilters, QueryFilters } from '@tanstack/query-core'
+import { useQueryClient } from './query-client'
+
+/**
+ * Returns a signal that tracks how many queries are currently in-flight.
+ * Useful for global loading indicators.
+ *
+ * @example
+ * const fetching = useIsFetching()
+ * // h('span', null, () => fetching() > 0 ? 'Loading…' : '')
+ */
+export function useIsFetching(filters?: QueryFilters): Signal<number> {
+  const client = useQueryClient()
+  const count = signal(client.isFetching(filters))
+
+  const unsub = client.getQueryCache().subscribe(() => {
+    count.set(client.isFetching(filters))
+  })
+  onUnmount(() => unsub())
+
+  return count
+}
+
+/**
+ * Returns a signal that tracks how many mutations are currently in-flight.
+ *
+ * @example
+ * const mutating = useIsMutating()
+ * // h('span', null, () => mutating() > 0 ? 'Saving…' : '')
+ */
+export function useIsMutating(filters?: MutationFilters): Signal<number> {
+  const client = useQueryClient()
+  const count = signal(client.isMutating(filters))
+
+  const unsub = client.getMutationCache().subscribe(() => {
+    count.set(client.isMutating(filters))
+  })
+  onUnmount(() => unsub())
+
+  return count
+}

package/src/use-mutation.ts

@@ -0,0 +1,117 @@
+import { onUnmount } from '@pyreon/core'
+import { signal, batch } from '@pyreon/reactivity'
+import type { Signal } from '@pyreon/reactivity'
+import { MutationObserver } from '@tanstack/query-core'
+import type {
+  DefaultError,
+  MutateFunction,
+  MutationObserverOptions,
+  MutationObserverResult,
+} from '@tanstack/query-core'
+import { useQueryClient } from './query-client'
+
+export interface UseMutationResult<
+  TData,
+  TError = DefaultError,
+  TVariables = void,
+  TContext = unknown,
+> {
+  /** Raw signal — full observer result. Fine-grained accessors below are preferred. */
+  result: Signal<MutationObserverResult<TData, TError, TVariables, TContext>>
+  data: Signal<TData | undefined>
+  error: Signal<TError | null>
+  status: Signal<'idle' | 'pending' | 'success' | 'error'>
+  isPending: Signal<boolean>
+  isSuccess: Signal<boolean>
+  isError: Signal<boolean>
+  isIdle: Signal<boolean>
+  /** Fire the mutation (fire-and-forget). Errors are captured in the error signal. */
+  mutate: (
+    variables: TVariables,
+    options?: Parameters<
+      MutateFunction<TData, TError, TVariables, TContext>
+    >[1],
+  ) => void
+  /** Like mutate but returns a promise — use for try/catch error handling. */
+  mutateAsync: MutateFunction<TData, TError, TVariables, TContext>
+  /** Reset the mutation state back to idle. */
+  reset: () => void
+}
+
+/**
+ * Run a mutation (create / update / delete). Returns reactive signals for
+ * pending / success / error state plus `mutate` and `mutateAsync` functions.
+ *
+ * @example
+ * const mutation = useMutation({
+ *   mutationFn: (data: CreatePostInput) =>
+ *     fetch('/api/posts', { method: 'POST', body: JSON.stringify(data) }).then(r => r.json()),
+ *   onSuccess: () => client.invalidateQueries({ queryKey: ['posts'] }),
+ * })
+ * // h('button', { onClick: () => mutation.mutate({ title: 'New' }) }, 'Create')
+ */
+export function useMutation<
+  TData = unknown,
+  TError = DefaultError,
+  TVariables = void,
+  TContext = unknown,
+>(
+  options: MutationObserverOptions<TData, TError, TVariables, TContext>,
+): UseMutationResult<TData, TError, TVariables, TContext> {
+  const client = useQueryClient()
+  const observer = new MutationObserver<TData, TError, TVariables, TContext>(
+    client,
+    options,
+  )
+  const initial = observer.getCurrentResult()
+
+  // Fine-grained signals: each field is independent so only effects that read
+  // e.g. `mutation.isPending()` re-run when isPending changes, not on every update.
+  const resultSig =
+    signal<MutationObserverResult<TData, TError, TVariables, TContext>>(initial)
+  const dataSig = signal<TData | undefined>(initial.data)
+  const errorSig = signal<TError | null>(initial.error ?? null)
+  const statusSig = signal<'idle' | 'pending' | 'success' | 'error'>(
+    initial.status,
+  )
+  const isPending = signal(initial.isPending)
+  const isSuccess = signal(initial.isSuccess)
+  const isError = signal(initial.isError)
+  const isIdle = signal(initial.isIdle)
+
+  // batch() coalesces all signal updates into one notification flush.
+  const unsub = observer.subscribe((r) => {
+    batch(() => {
+      resultSig.set(r)
+      dataSig.set(r.data)
+      errorSig.set(r.error ?? null)
+      statusSig.set(r.status)
+      isPending.set(r.isPending)
+      isSuccess.set(r.isSuccess)
+      isError.set(r.isError)
+      isIdle.set(r.isIdle)
+    })
+  })
+
+  onUnmount(() => unsub())
+
+  return {
+    result: resultSig,
+    data: dataSig,
+    error: errorSig,
+    status: statusSig,
+    isPending,
+    isSuccess,
+    isError,
+    isIdle,
+    mutate: (vars, callbackOptions) => {
+      observer.mutate(vars, callbackOptions).catch(() => {
+        // Error is already captured in the error signal via the observer subscription.
+        // This catch prevents an unhandled promise rejection for fire-and-forget callers.
+      })
+    },
+    mutateAsync: (vars, callbackOptions) =>
+      observer.mutate(vars, callbackOptions),
+    reset: () => observer.reset(),
+  }
+}

package/src/use-queries.ts

@@ -0,0 +1,61 @@
+import { onUnmount } from '@pyreon/core'
+import { signal, effect } from '@pyreon/reactivity'
+import type { Signal } from '@pyreon/reactivity'
+import { QueriesObserver } from '@tanstack/query-core'
+import type {
+  DefaultError,
+  QueryKey,
+  QueryObserverOptions,
+  QueryObserverResult,
+} from '@tanstack/query-core'
+import { useQueryClient } from './query-client'
+
+export type UseQueriesOptions<TQueryKey extends QueryKey = QueryKey> =
+  QueryObserverOptions<unknown, DefaultError, unknown, unknown, TQueryKey>
+
+/**
+ * Subscribe to multiple queries in parallel. Returns a single signal containing
+ * the array of results — index-aligned with the `queries` array.
+ *
+ * `queries` is a reactive function so signal-based keys trigger re-evaluation
+ * automatically.
+ *
+ * @example
+ * const userIds = signal([1, 2, 3])
+ * const results = useQueries(() =>
+ *   userIds().map(id => ({
+ *     queryKey: ['user', id],
+ *     queryFn: () => fetchUser(id),
+ *   }))
+ * )
+ * // results() — QueryObserverResult[]
+ * // results()[0].data — first user
+ */
+export function useQueries(
+  queries: () => UseQueriesOptions[],
+): Signal<QueryObserverResult[]> {
+  const client = useQueryClient()
+  const observer = new QueriesObserver(client, queries())
+
+  const resultSig = signal(
+    observer.getCurrentResult() as readonly QueryObserverResult[],
+  ) as Signal<QueryObserverResult[]>
+
+  const unsub = observer.subscribe(
+    (results: readonly QueryObserverResult[]) => {
+      resultSig.set(results as QueryObserverResult[])
+    },
+  )
+
+  // When signals inside queries() change, update the observer.
+  effect(() => {
+    observer.setQueries(queries())
+  })
+
+  onUnmount(() => {
+    unsub()
+    observer.destroy()
+  })
+
+  return resultSig
+}

package/src/use-query-error-reset-boundary.ts

@@ -0,0 +1,95 @@
+import {
+  createContext,
+  pushContext,
+  popContext,
+  onUnmount,
+  useContext,
+} from '@pyreon/core'
+import type { VNodeChild, VNode } from '@pyreon/core'
+import type { Props } from '@pyreon/core'
+import { useQueryClient } from './query-client'
+
+// ─── Context ────────────────────────────────────────────────────────────────
+
+interface ErrorResetBoundaryValue {
+  reset: () => void
+}
+
+const QueryErrorResetBoundaryContext =
+  createContext<ErrorResetBoundaryValue | null>(null)
+
+// ─── QueryErrorResetBoundary ─────────────────────────────────────────────────
+
+export interface QueryErrorResetBoundaryProps extends Props {
+  children?: VNodeChild
+}
+
+/**
+ * Wraps a subtree so that `useQueryErrorResetBoundary()` descendants can reset
+ * all errored queries within this boundary.
+ *
+ * Pair with Pyreon's `ErrorBoundary` to retry failed queries when the user
+ * dismisses the error fallback:
+ *
+ * @example
+ * h(QueryErrorResetBoundary, null,
+ *   h(ErrorBoundary, {
+ *     fallback: (err, boundaryReset) => {
+ *       const { reset } = useQueryErrorResetBoundary()
+ *       return h('button', {
+ *         onClick: () => { reset(); boundaryReset() },
+ *       }, 'Retry')
+ *     },
+ *   }, h(MyComponent, null)),
+ * )
+ */
+export function QueryErrorResetBoundary(
+  props: QueryErrorResetBoundaryProps,
+): VNode {
+  const client = useQueryClient()
+
+  const value: ErrorResetBoundaryValue = {
+    reset: () => {
+      // Reset all active queries that are in error state so they refetch.
+      client.refetchQueries({
+        predicate: (query) => query.state.status === 'error',
+      })
+    },
+  }
+
+  const frame = new Map([[QueryErrorResetBoundaryContext.id, value]])
+  pushContext(frame)
+  onUnmount(() => popContext())
+
+  const ch = props.children
+  return (typeof ch === 'function' ? (ch as () => VNodeChild)() : ch) as VNode
+}
+
+// ─── useQueryErrorResetBoundary ──────────────────────────────────────────────
+
+/**
+ * Returns the `reset` function provided by the nearest `QueryErrorResetBoundary`.
+ * If called outside a boundary, falls back to resetting all errored queries
+ * on the current `QueryClient`.
+ *
+ * @example
+ * // Inside an ErrorBoundary fallback:
+ * const { reset } = useQueryErrorResetBoundary()
+ * h('button', { onClick: () => { reset(); boundaryReset() } }, 'Retry')
+ */
+export function useQueryErrorResetBoundary(): ErrorResetBoundaryValue {
+  const boundary = useContext(QueryErrorResetBoundaryContext)
+  // Always call useQueryClient to respect hook ordering rules
+  const client = useQueryClient()
+
+  if (boundary) return boundary
+
+  // Fallback: no explicit boundary — use the QueryClient directly.
+  return {
+    reset: () => {
+      client.refetchQueries({
+        predicate: (query) => query.state.status === 'error',
+      })
+    },
+  }
+}

package/src/use-query.ts

@@ -0,0 +1,106 @@
+import { onUnmount } from '@pyreon/core'
+import { signal, effect, batch } from '@pyreon/reactivity'
+import type { Signal } from '@pyreon/reactivity'
+import { QueryObserver } from '@tanstack/query-core'
+import type {
+  DefaultError,
+  QueryKey,
+  QueryObserverOptions,
+  QueryObserverResult,
+} from '@tanstack/query-core'
+import { useQueryClient } from './query-client'
+
+export interface UseQueryResult<TData, TError = DefaultError> {
+  /** Raw signal — the full observer result. Fine-grained accessors below are preferred. */
+  result: Signal<QueryObserverResult<TData, TError>>
+  data: Signal<TData | undefined>
+  error: Signal<TError | null>
+  status: Signal<'pending' | 'error' | 'success'>
+  isPending: Signal<boolean>
+  isLoading: Signal<boolean>
+  isFetching: Signal<boolean>
+  isError: Signal<boolean>
+  isSuccess: Signal<boolean>
+  /** Manually trigger a refetch. */
+  refetch: () => Promise<QueryObserverResult<TData, TError>>
+}
+
+/**
+ * Subscribe to a query. Returns fine-grained reactive signals for data,
+ * error and status — each signal only notifies effects that depend on it.
+ *
+ * `options` is a function so it can read Pyreon signals — when a signal changes
+ * (e.g. a reactive query key), the observer is updated and refetches automatically.
+ *
+ * @example
+ * const userId = signal(1)
+ * const query = useQuery(() => ({
+ *   queryKey: ['user', userId()],
+ *   queryFn: () => fetch(`/api/users/${userId()}`).then(r => r.json()),
+ * }))
+ * // In template: () => query.data()?.name
+ */
+export function useQuery<
+  TData = unknown,
+  TError = DefaultError,
+  TKey extends QueryKey = QueryKey,
+>(
+  options: () => QueryObserverOptions<TData, TError, TData, TData, TKey>,
+): UseQueryResult<TData, TError> {
+  const client = useQueryClient()
+  const observer = new QueryObserver<TData, TError, TData, TData, TKey>(
+    client,
+    options(),
+  )
+  const initial = observer.getCurrentResult()
+
+  // Fine-grained signals: each field is independent so only effects that read
+  // e.g. `query.data()` re-run when data changes, not when isFetching flips.
+  const resultSig = signal<QueryObserverResult<TData, TError>>(initial)
+  const dataSig = signal<TData | undefined>(initial.data)
+  const errorSig = signal<TError | null>(initial.error ?? null)
+  const statusSig = signal<'pending' | 'error' | 'success'>(initial.status)
+  const isPending = signal(initial.isPending)
+  const isLoading = signal(initial.isLoading)
+  const isFetching = signal(initial.isFetching)
+  const isError = signal(initial.isError)
+  const isSuccess = signal(initial.isSuccess)
+
+  // Subscribe synchronously — data flows before mount (correct for SSR pre-population).
+  // batch() coalesces all signal updates into one notification flush.
+  const unsub = observer.subscribe((r) => {
+    batch(() => {
+      resultSig.set(r)
+      dataSig.set(r.data)
+      errorSig.set(r.error ?? null)
+      statusSig.set(r.status)
+      isPending.set(r.isPending)
+      isLoading.set(r.isLoading)
+      isFetching.set(r.isFetching)
+      isError.set(r.isError)
+      isSuccess.set(r.isSuccess)
+    })
+  })
+
+  // Track reactive options: when signals inside options() change, update the observer.
+  // effect() is auto-registered in the component's EffectScope → auto-disposed on unmount.
+  effect(() => {
+    observer.setOptions(options())
+  })
+
+  // Unsubscribe the observer on unmount (effect disposal is handled by EffectScope).
+  onUnmount(() => unsub())
+
+  return {
+    result: resultSig,
+    data: dataSig,
+    error: errorSig,
+    status: statusSig,
+    isPending,
+    isLoading,
+    isFetching,
+    isError,
+    isSuccess,
+    refetch: () => observer.refetch(),
+  }
+}