qortex-react 0.3.0-beta.4 → 0.3.0-beta.6

package/index.d.ts

@@ -2,9 +2,34 @@ import { Fetcher, QueryKey, QueryOptions, InferFetcherResult, QueryState } from
 export * from 'qortex-core';
 
 /**
- * useQuery hook for React integration with qortex
- * Provides reactive data fetching with automatic re-renders on state changes
- * Enhanced with automatic type inference from fetchers
+ * React hook for reactive data fetching with automatic re-renders on state changes
+ *
+ * @param key - Unique identifier for the query (string or array of primitives)
+ * @param opts - Query configuration options
+ * @param opts.fetcher - Async function that fetches data for this query
+ * @param opts.enabled - Whether the query should be active (default: true)
+ * @param opts.staleTime - Time in ms before data is considered stale (default: 0)
+ * @param opts.equalityStrategy - How to compare data for changes ('shallow' | 'deep')
+ * @param opts.equalityFn - Custom equality function for data comparison
+ * @param opts.refetchOnSubscribe - When to refetch on subscription ('always' | 'stale' | false)
+ * @param opts.placeholderData - Initial data to show while loading
+ * @param opts.usePreviousDataOnError - Keep previous data when error occurs
+ * @param opts.usePlaceholderOnError - Use placeholder data when error occurs
+ * @returns QueryState object with data, error, status, and computed flags
+ *
+ * Returns an object containing:
+ * - data: The current data value
+ * - error: Any error that occurred during fetching
+ * - status: Current status ('idle' | 'fetching' | 'success' | 'error')
+ * - isStale: Whether the data is considered stale
+ * - isLoading: Whether the query is currently loading
+ * - isFetching: Whether a fetch is in progress
+ * - isError: Whether the query is in an error state
+ * - isSuccess: Whether the query completed successfully
+ * - refetch: Function to manually trigger a refetch
+ *
+ * Automatically subscribes to query state changes and triggers re-renders when the state updates.
+ * Enhanced with automatic type inference from fetcher functions. Handles mount logic to potentially start fetching.
  */
 declare function useQuery<F extends Fetcher>(key: QueryKey, opts: QueryOptions<InferFetcherResult<F>> & {
     fetcher: F;
@@ -12,9 +37,25 @@ declare function useQuery<F extends Fetcher>(key: QueryKey, opts: QueryOptions<I
 declare function useQuery<T = any>(key: QueryKey, opts?: QueryOptions<T>): QueryState<T>;
 
 /**
- * useQueryData hook for React integration with qortex
- * Provides reactive data fetching with automatic re-renders on state changes
- * Enhanced with automatic type inference from fetchers
+ * React hook for reactive data fetching that returns only the data value
+ *
+ * @param key - Unique identifier for the query (string or array of primitives)
+ * @param opts - Query configuration options
+ * @param opts.fetcher - Async function that fetches data for this query
+ * @param opts.enabled - Whether the query should be active (default: true)
+ * @param opts.staleTime - Time in ms before data is considered stale (default: 0)
+ * @param opts.equalityStrategy - How to compare data for changes ('shallow' | 'deep')
+ * @param opts.equalityFn - Custom equality function for data comparison
+ * @param opts.refetchOnSubscribe - When to refetch on subscription ('always' | 'stale' | false)
+ * @param opts.placeholderData - Initial data to show while loading
+ * @param opts.usePreviousDataOnError - Keep previous data when error occurs
+ * @param opts.usePlaceholderOnError - Use placeholder data when error occurs
+ * @returns The current data value or undefined if not available
+ *
+ * Similar to useQuery but returns only the data value instead of the full QueryState object.
+ * Returns undefined if the query has never been fetched, is loading, or if an error occurred.
+ * Automatically subscribes to query state changes and triggers re-renders when the data updates.
+ * Enhanced with automatic type inference from fetcher functions. Handles mount logic to potentially start fetching.
  */
 declare function useQueryData<F extends Fetcher>(key: QueryKey, opts: QueryOptions<InferFetcherResult<F>> & {
     fetcher: F;
@@ -22,20 +63,36 @@ declare function useQueryData<F extends Fetcher>(key: QueryKey, opts: QueryOptio
 declare function useQueryData<T = any>(key: QueryKey, opts?: QueryOptions<T>): T | undefined;
 
 /**
- * useQuerySelect hook for React integration with qortex
- * Provides reactive data fetching with automatic re-renders on state changes
- * Enhanced with automatic type inference from fetchers
+ * React hook for reactive data fetching with smart subscription optimization
  *
- * Now includes smart subscription: automatically detects which properties are accessed
- * and only re-renders when those specific properties change, not the entire state.
+ * @param key - Unique identifier for the query (string or array of primitives)
+ * @param opts - Query configuration options
+ * @param opts.fetcher - Async function that fetches data for this query
+ * @param opts.enabled - Whether the query should be active (default: true)
+ * @param opts.staleTime - Time in ms before data is considered stale (default: 0)
+ * @param opts.equalityStrategy - How to compare data for changes ('shallow' | 'deep')
+ * @param opts.equalityFn - Custom equality function for data comparison
+ * @param opts.refetchOnSubscribe - When to refetch on subscription ('always' | 'stale' | false)
+ * @param opts.placeholderData - Initial data to show while loading
+ * @param opts.usePreviousDataOnError - Keep previous data when error occurs
+ * @param opts.usePlaceholderOnError - Use placeholder data when error occurs
+ * @returns QueryState object with data, error, status, and computed flags
  *
- * @example
- * ```tsx
- * const query = useQuerySelect('users', { fetcher: fetchUsers });
+ * Returns an object containing:
+ * - data: The current data value
+ * - error: Any error that occurred during fetching
+ * - status: Current status ('idle' | 'fetching' | 'success' | 'error')
+ * - isStale: Whether the data is considered stale
+ * - isLoading: Whether the query is currently loading
+ * - isFetching: Whether a fetch is in progress
+ * - isError: Whether the query is in an error state
+ * - isSuccess: Whether the query completed successfully
+ * - refetch: Function to manually trigger a refetch
  *
- * // Only re-renders when data or isSuccess changes, not when isError changes
- * return <div>{query.isSuccess ? query.data?.name : 'Loading...'}</div>;
- * ```
+ * Features smart subscription optimization: automatically detects which properties are accessed
+ * during render and only triggers re-renders when those specific properties change, not the entire state.
+ * This prevents unnecessary re-renders when unrelated properties change, improving performance.
+ * Enhanced with automatic type inference from fetcher functions. Handles mount logic to potentially start fetching.
  */
 declare function useQuerySelect<F extends Fetcher>(key: QueryKey, opts: QueryOptions<InferFetcherResult<F>> & {
     fetcher: F;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qortex-react",
-  "version": "0.3.0-beta.4",
+  "version": "0.3.0-beta.6",
   "description": "React hook bridge for qortex runtime",
   "main": "index.js",
   "module": "index.mjs",
@@ -50,7 +50,7 @@
   "author": "Darshan Naik",
   "license": "LGPL-3.0",
   "dependencies": {
-    "qortex-core": "0.3.0-beta.4"
+    "qortex-core": "0.3.0-beta.6"
   },
   "peerDependencies": {
     "react": ">=18"