@pyreon/query 0.9.0 → 0.11.0

package/src/use-mutation.ts

@@ -1,14 +1,14 @@
-import { onUnmount } from '@pyreon/core'
-import type { Signal } from '@pyreon/reactivity'
-import { batch, signal } from '@pyreon/reactivity'
+import { onUnmount } from "@pyreon/core"
+import type { Signal } from "@pyreon/reactivity"
+import { batch, signal } from "@pyreon/reactivity"
 import type {
   DefaultError,
   MutateFunction,
   MutationObserverOptions,
   MutationObserverResult,
-} from '@tanstack/query-core'
-import { MutationObserver } from '@tanstack/query-core'
-import { useQueryClient } from './query-client'
+} from "@tanstack/query-core"
+import { MutationObserver } from "@tanstack/query-core"
+import { useQueryClient } from "./query-client"
 
 export interface UseMutationResult<
   TData,
@@ -20,7 +20,7 @@ export interface UseMutationResult<
   result: Signal<MutationObserverResult<TData, TError, TVariables, TContext>>
   data: Signal<TData | undefined>
   error: Signal<TError | null>
-  status: Signal<'idle' | 'pending' | 'success' | 'error'>
+  status: Signal<"idle" | "pending" | "success" | "error">
   isPending: Signal<boolean>
   isSuccess: Signal<boolean>
   isError: Signal<boolean>
@@ -28,9 +28,7 @@ export interface UseMutationResult<
   /** Fire the mutation (fire-and-forget). Errors are captured in the error signal. */
   mutate: (
     variables: TVariables,
-    options?: Parameters<
-      MutateFunction<TData, TError, TVariables, TContext>
-    >[1],
+    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>
@@ -59,21 +57,15 @@ export function useMutation<
   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 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 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 statusSig = signal<"idle" | "pending" | "success" | "error">(initial.status)
   const isPending = signal(initial.isPending)
   const isSuccess = signal(initial.isSuccess)
   const isError = signal(initial.isError)
@@ -110,8 +102,7 @@ export function useMutation<
         // This catch prevents an unhandled promise rejection for fire-and-forget callers.
       })
     },
-    mutateAsync: (vars, callbackOptions) =>
-      observer.mutate(vars, callbackOptions),
+    mutateAsync: (vars, callbackOptions) => observer.mutate(vars, callbackOptions),
     reset: () => observer.reset(),
   }
 }

package/src/use-queries.ts

@@ -1,17 +1,22 @@
-import { onUnmount } from '@pyreon/core'
-import type { Signal } from '@pyreon/reactivity'
-import { effect, signal } from '@pyreon/reactivity'
+import { onUnmount } from "@pyreon/core"
+import type { Signal } from "@pyreon/reactivity"
+import { effect, signal } from "@pyreon/reactivity"
 import type {
   DefaultError,
   QueryKey,
   QueryObserverOptions,
   QueryObserverResult,
-} from '@tanstack/query-core'
-import { QueriesObserver } from '@tanstack/query-core'
-import { useQueryClient } from './query-client'
+} from "@tanstack/query-core"
+import { QueriesObserver } from "@tanstack/query-core"
+import { useQueryClient } from "./query-client"
 
-export type UseQueriesOptions<TQueryKey extends QueryKey = QueryKey> =
-  QueryObserverOptions<unknown, DefaultError, unknown, unknown, TQueryKey>
+export type UseQueriesOptions<TQueryKey extends QueryKey = QueryKey> = QueryObserverOptions<
+  unknown,
+  DefaultError,
+  unknown,
+  unknown,
+  TQueryKey
+>
 
 /**
  * Subscribe to multiple queries in parallel. Returns a single signal containing
@@ -31,21 +36,17 @@ export type UseQueriesOptions<TQueryKey extends QueryKey = QueryKey> =
  * // results() — QueryObserverResult[]
  * // results()[0].data — first user
  */
-export function useQueries(
-  queries: () => UseQueriesOptions[],
-): Signal<QueryObserverResult[]> {
+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 resultSig = signal(observer.getCurrentResult() as readonly QueryObserverResult[]) as Signal<
+    QueryObserverResult[]
+  >
 
-  const unsub = observer.subscribe(
-    (results: readonly QueryObserverResult[]) => {
-      resultSig.set(results as QueryObserverResult[])
-    },
-  )
+  const unsub = observer.subscribe((results: readonly QueryObserverResult[]) => {
+    resultSig.set(results as QueryObserverResult[])
+  })
 
   // When signals inside queries() change, update the observer.
   effect(() => {

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

@@ -1,6 +1,6 @@
-import type { Props, VNode, VNodeChild } from '@pyreon/core'
-import { createContext, provide, useContext } from '@pyreon/core'
-import { useQueryClient } from './query-client'
+import type { Props, VNode, VNodeChild } from "@pyreon/core"
+import { createContext, provide, useContext } from "@pyreon/core"
+import { useQueryClient } from "./query-client"
 
 // ─── Context ────────────────────────────────────────────────────────────────
 
@@ -8,8 +8,7 @@ interface ErrorResetBoundaryValue {
   reset: () => void
 }
 
-const QueryErrorResetBoundaryContext =
-  createContext<ErrorResetBoundaryValue | null>(null)
+const QueryErrorResetBoundaryContext = createContext<ErrorResetBoundaryValue | null>(null)
 
 // ─── QueryErrorResetBoundary ─────────────────────────────────────────────────
 
@@ -36,16 +35,14 @@ export interface QueryErrorResetBoundaryProps extends Props {
  *   }, h(MyComponent, null)),
  * )
  */
-export function QueryErrorResetBoundary(
-  props: QueryErrorResetBoundaryProps,
-): VNode {
+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',
+        predicate: (query) => query.state.status === "error",
       })
     },
   }
@@ -53,7 +50,7 @@ export function QueryErrorResetBoundary(
   provide(QueryErrorResetBoundaryContext, value)
 
   const ch = props.children
-  return (typeof ch === 'function' ? (ch as () => VNodeChild)() : ch) as VNode
+  return (typeof ch === "function" ? (ch as () => VNodeChild)() : ch) as VNode
 }
 
 // ─── useQueryErrorResetBoundary ──────────────────────────────────────────────
@@ -79,7 +76,7 @@ export function useQueryErrorResetBoundary(): ErrorResetBoundaryValue {
   return {
     reset: () => {
       client.refetchQueries({
-        predicate: (query) => query.state.status === 'error',
+        predicate: (query) => query.state.status === "error",
       })
     },
   }

package/src/use-query.ts

@@ -1,21 +1,21 @@
-import { onUnmount } from '@pyreon/core'
-import type { Signal } from '@pyreon/reactivity'
-import { batch, effect, signal } from '@pyreon/reactivity'
+import { onUnmount } from "@pyreon/core"
+import type { Signal } from "@pyreon/reactivity"
+import { batch, effect, signal } from "@pyreon/reactivity"
 import type {
   DefaultError,
   QueryKey,
   QueryObserverOptions,
   QueryObserverResult,
-} from '@tanstack/query-core'
-import { QueryObserver } from '@tanstack/query-core'
-import { useQueryClient } from './query-client'
+} from "@tanstack/query-core"
+import { QueryObserver } 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'>
+  status: Signal<"pending" | "error" | "success">
   isPending: Signal<boolean>
   isLoading: Signal<boolean>
   isFetching: Signal<boolean>
@@ -40,18 +40,11 @@ export interface UseQueryResult<TData, TError = DefaultError> {
  * }))
  * // In template: () => query.data()?.name
  */
-export function useQuery<
-  TData = unknown,
-  TError = DefaultError,
-  TKey extends QueryKey = QueryKey,
->(
+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 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
@@ -59,7 +52,7 @@ export function useQuery<
   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 statusSig = signal<"pending" | "error" | "success">(initial.status)
   const isPending = signal(initial.isPending)
   const isLoading = signal(initial.isLoading)
   const isFetching = signal(initial.isFetching)

package/src/use-sse.ts

@@ -0,0 +1,266 @@
+import { onUnmount } from "@pyreon/core"
+import type { Signal } from "@pyreon/reactivity"
+import { batch, effect, signal } from "@pyreon/reactivity"
+import type { QueryClient } from "@tanstack/query-core"
+import { useQueryClient } from "./query-client"
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export type SSEStatus = "connecting" | "connected" | "disconnected" | "error"
+
+export interface UseSSEOptions<T = string> {
+  /** EventSource URL — can be a signal for reactive URLs */
+  url: string | (() => string)
+  /** Named event type(s) to listen for — if omitted, listens to generic `message` events */
+  events?: string | string[]
+  /** Parse raw event data — e.g. `JSON.parse` for automatic deserialization */
+  parse?: (raw: string) => T
+  /** Whether the SSE connection is enabled — default: true */
+  enabled?: boolean | (() => boolean)
+  /** Whether to automatically reconnect — default: true */
+  reconnect?: boolean
+  /** Initial reconnect delay in ms — doubles on each retry, default: 1000 */
+  reconnectDelay?: number
+  /** Maximum reconnect attempts — default: 10, 0 = unlimited */
+  maxReconnectAttempts?: number
+  /** Whether to send cookies with the request — default: false */
+  withCredentials?: boolean
+  /** Called when a message is received — use queryClient to invalidate or update cache */
+  onMessage?: (data: T, queryClient: QueryClient) => void
+  /** Called when the EventSource connection opens */
+  onOpen?: (event: Event) => void
+  /** Called when a connection error occurs */
+  onError?: (event: Event) => void
+}
+
+export interface UseSSEResult<T> {
+  /** Last received message data */
+  data: Signal<T | null>
+  /** Current connection status */
+  status: Signal<SSEStatus>
+  /** Last error event */
+  error: Signal<Event | null>
+  /** Last `id` field received from the server (per SSE spec) */
+  lastEventId: () => string
+  /** EventSource readyState: 0=CONNECTING, 1=OPEN, 2=CLOSED */
+  readyState: () => number
+  /** Manually close the connection */
+  close: () => void
+  /** Manually reconnect */
+  reconnect: () => void
+}
+
+// ─── useSSE ─────────────────────────────────────────────────────────────────
+
+/**
+ * Reactive Server-Sent Events hook that integrates with TanStack Query.
+ * Automatically manages connection lifecycle, reconnection, and cleanup.
+ *
+ * Use the `onMessage` callback to invalidate or update query cache
+ * when the server pushes data.
+ *
+ * @example
+ * ```ts
+ * const sse = useSSE({
+ *   url: '/api/events',
+ *   parse: JSON.parse,
+ *   onMessage: (data, queryClient) => {
+ *     if (data.type === 'order-updated') {
+ *       queryClient.invalidateQueries({ queryKey: ['orders'] })
+ *     }
+ *   },
+ * })
+ * // sse.data()    — last received message (parsed)
+ * // sse.status()  — 'connecting' | 'connected' | 'disconnected' | 'error'
+ * // sse.error()   — last error event or null
+ * ```
+ */
+export function useSSE<T = string>(options: UseSSEOptions<T>): UseSSEResult<T> {
+  const queryClient = useQueryClient()
+  const data = signal<T | null>(null)
+  const status = signal<SSEStatus>("disconnected")
+  const error = signal<Event | null>(null)
+  const lastEventId = signal("")
+  const readyState = signal<number>(2) // Start as CLOSED until connected
+
+  let es: EventSource | null = null
+  let reconnectAttempts = 0
+  let reconnectTimer: ReturnType<typeof setTimeout> | null = null
+  let intentionalClose = false
+
+  const reconnectEnabled = options.reconnect !== false
+  const baseDelay = options.reconnectDelay ?? 1000
+  const maxAttempts = options.maxReconnectAttempts ?? 10
+  const eventNames = options.events
+    ? Array.isArray(options.events)
+      ? options.events
+      : [options.events]
+    : null
+
+  function getUrl(): string {
+    return typeof options.url === "function" ? options.url() : options.url
+  }
+
+  function isEnabled(): boolean {
+    if (options.enabled === undefined) return true
+    return typeof options.enabled === "function" ? options.enabled() : options.enabled
+  }
+
+  function handleMessage(event: MessageEvent): void {
+    try {
+      // Track lastEventId from the SSE spec
+      if (event.lastEventId !== undefined && event.lastEventId !== "") {
+        lastEventId.set(event.lastEventId)
+      }
+      const parsed = options.parse ? options.parse(event.data as string) : (event.data as T)
+      batch(() => {
+        data.set(parsed)
+        error.set(null)
+      })
+      options.onMessage?.(parsed, queryClient)
+    } catch {
+      // Message handler errors should not crash the subscription
+    }
+  }
+
+  function attachListeners(source: EventSource): void {
+    if (eventNames) {
+      for (const name of eventNames) {
+        source.addEventListener(name, handleMessage as EventListener)
+      }
+    } else {
+      source.onmessage = handleMessage
+    }
+  }
+
+  function removeListeners(source: EventSource): void {
+    source.onopen = null
+    source.onmessage = null
+    source.onerror = null
+
+    if (eventNames) {
+      for (const name of eventNames) {
+        source.removeEventListener(name, handleMessage as EventListener)
+      }
+    }
+  }
+
+  function handleError(event: Event): void {
+    status.set("error")
+    error.set(event)
+    readyState.set(es?.readyState ?? EventSource.CLOSED)
+    options.onError?.(event)
+
+    // EventSource auto-reconnects for transient errors, but if readyState is CLOSED
+    // the browser has given up and we need to handle reconnection ourselves
+    if (es?.readyState === EventSource.CLOSED) {
+      removeListeners(es)
+      es.close()
+      es = null
+      if (!intentionalClose && reconnectEnabled) {
+        scheduleReconnect()
+      }
+    }
+  }
+
+  function connect(): void {
+    // Clean up existing connection
+    if (es) {
+      removeListeners(es)
+      es.close()
+      es = null
+    }
+
+    if (!isEnabled()) {
+      status.set("disconnected")
+      return
+    }
+
+    status.set("connecting")
+
+    try {
+      es = new EventSource(getUrl(), {
+        withCredentials: options.withCredentials ?? false,
+      })
+      readyState.set(EventSource.CONNECTING)
+    } catch {
+      status.set("error")
+      readyState.set(EventSource.CLOSED)
+      scheduleReconnect()
+      return
+    }
+
+    es.onopen = (event: Event) => {
+      batch(() => {
+        status.set("connected")
+        error.set(null)
+        readyState.set(EventSource.OPEN)
+        reconnectAttempts = 0
+      })
+      options.onOpen?.(event)
+    }
+
+    attachListeners(es)
+    es.onerror = handleError
+  }
+
+  function scheduleReconnect(): void {
+    if (!reconnectEnabled) return
+    if (maxAttempts > 0 && reconnectAttempts >= maxAttempts) return
+
+    const delay = baseDelay * 2 ** reconnectAttempts
+    reconnectAttempts++
+
+    reconnectTimer = setTimeout(() => {
+      reconnectTimer = null
+      if (!intentionalClose && isEnabled()) {
+        connect()
+      }
+    }, delay)
+  }
+
+  function close(): void {
+    intentionalClose = true
+    if (reconnectTimer !== null) {
+      clearTimeout(reconnectTimer)
+      reconnectTimer = null
+    }
+    if (es) {
+      removeListeners(es)
+      es.close()
+      es = null
+    }
+    status.set("disconnected")
+    readyState.set(EventSource.CLOSED)
+  }
+
+  function manualReconnect(): void {
+    intentionalClose = false
+    reconnectAttempts = 0
+    connect()
+  }
+
+  // Track reactive URL and enabled state
+  effect(() => {
+    // Read reactive values to subscribe to changes
+    if (typeof options.url === "function") options.url()
+    if (typeof options.enabled === "function") options.enabled()
+
+    intentionalClose = false
+    reconnectAttempts = 0
+    connect()
+  })
+
+  // Cleanup on unmount
+  onUnmount(() => close())
+
+  return {
+    data,
+    status,
+    error,
+    lastEventId: () => lastEventId(),
+    readyState: () => readyState(),
+    close,
+    reconnect: manualReconnect,
+  }
+}

package/src/use-subscription.ts

@@ -1,16 +1,12 @@
-import { onUnmount } from '@pyreon/core'
-import type { Signal } from '@pyreon/reactivity'
-import { batch, effect, signal } from '@pyreon/reactivity'
-import type { QueryClient } from '@tanstack/query-core'
-import { useQueryClient } from './query-client'
+import { onUnmount } from "@pyreon/core"
+import type { Signal } from "@pyreon/reactivity"
+import { batch, effect, signal } from "@pyreon/reactivity"
+import type { QueryClient } from "@tanstack/query-core"
+import { useQueryClient } from "./query-client"
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
-export type SubscriptionStatus =
-  | 'connecting'
-  | 'connected'
-  | 'disconnected'
-  | 'error'
+export type SubscriptionStatus = "connecting" | "connected" | "disconnected" | "error"
 
 export interface UseSubscriptionOptions {
   /** WebSocket URL — can be a signal for reactive URLs */
@@ -70,11 +66,9 @@ export interface UseSubscriptionResult {
  * // sub.send(JSON.stringify({ type: 'subscribe', channel: 'orders' }))
  * ```
  */
-export function useSubscription(
-  options: UseSubscriptionOptions,
-): UseSubscriptionResult {
+export function useSubscription(options: UseSubscriptionOptions): UseSubscriptionResult {
   const queryClient = useQueryClient()
-  const status = signal<SubscriptionStatus>('disconnected')
+  const status = signal<SubscriptionStatus>("disconnected")
 
   let ws: WebSocket | null = null
   let reconnectAttempts = 0
@@ -86,14 +80,12 @@ export function useSubscription(
   const maxAttempts = options.maxReconnectAttempts ?? 10
 
   function getUrl(): string {
-    return typeof options.url === 'function' ? options.url() : options.url
+    return typeof options.url === "function" ? options.url() : options.url
   }
 
   function isEnabled(): boolean {
     if (options.enabled === undefined) return true
-    return typeof options.enabled === 'function'
-      ? options.enabled()
-      : options.enabled
+    return typeof options.enabled === "function" ? options.enabled() : options.enabled
   }
 
   function connect(): void {
@@ -102,45 +94,44 @@ export function useSubscription(
       ws.onmessage = null
       ws.onclose = null
       ws.onerror = null
-      if (
-        ws.readyState === WebSocket.OPEN ||
-        ws.readyState === WebSocket.CONNECTING
-      ) {
+      if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
         ws.close()
       }
     }
 
     if (!isEnabled()) {
-      status.set('disconnected')
+      status.set("disconnected")
       return
     }
 
-    status.set('connecting')
+    status.set("connecting")
 
     try {
-      ws = options.protocols
-        ? new WebSocket(getUrl(), options.protocols)
-        : new WebSocket(getUrl())
+      ws = options.protocols ? new WebSocket(getUrl(), options.protocols) : new WebSocket(getUrl())
     } catch {
-      status.set('error')
+      status.set("error")
       scheduleReconnect()
       return
     }
 
     ws.onopen = (event) => {
       batch(() => {
-        status.set('connected')
+        status.set("connected")
         reconnectAttempts = 0
       })
       options.onOpen?.(event)
     }
 
     ws.onmessage = (event) => {
-      options.onMessage(event, queryClient)
+      try {
+        options.onMessage(event, queryClient)
+      } catch {
+        // Message handler errors should not crash the subscription
+      }
     }
 
     ws.onclose = (event) => {
-      status.set('disconnected')
+      status.set("disconnected")
       options.onClose?.(event)
 
       if (!intentionalClose && reconnectEnabled) {
@@ -149,7 +140,7 @@ export function useSubscription(
     }
 
     ws.onerror = (event) => {
-      status.set('error')
+      status.set("error")
       options.onError?.(event)
     }
   }
@@ -186,15 +177,12 @@ export function useSubscription(
       ws.onmessage = null
       ws.onclose = null
       ws.onerror = null
-      if (
-        ws.readyState === WebSocket.OPEN ||
-        ws.readyState === WebSocket.CONNECTING
-      ) {
+      if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
         ws.close()
       }
       ws = null
     }
-    status.set('disconnected')
+    status.set("disconnected")
   }
 
   function manualReconnect(): void {
@@ -206,8 +194,8 @@ export function useSubscription(
   // Track reactive URL and enabled state
   effect(() => {
     // Read reactive values to subscribe to changes
-    if (typeof options.url === 'function') options.url()
-    if (typeof options.enabled === 'function') options.enabled()
+    if (typeof options.url === "function") options.url()
+    if (typeof options.enabled === "function") options.enabled()
 
     intentionalClose = false
     reconnectAttempts = 0