@ahoo-wang/fetcher-react 3.3.8 → 3.4.0

package/README.md

@@ -40,11 +40,16 @@ robust data fetching capabilities.
 - [useEventSubscription Hook](#useeventsubscription-hook)
 - [useKeyStorage Hook](#usekeystorage-hook)
   - [useImmerKeyStorage Hook](#useimmerkeystorage-hook)
-  - [Wow Query Hooks](#wow-query-hooks)
+- [Wow Query Hooks](#wow-query-hooks)
   - [useListQuery Hook](#uselistquery-hook)
   - [usePagedQuery Hook](#usepagedquery-hook)
   - [useSingleQuery Hook](#usesinglequery-hook)
   - [useCountQuery Hook](#usecountquery-hook)
+  - [useFetcherCountQuery Hook](#usefetchercountquery-hook)
+  - [useFetcherPagedQuery Hook](#usefetcherpagedquery-hook)
+  - [useFetcherListQuery Hook](#usefetcherlistquery-hook)
+  - [useFetcherListStreamQuery Hook](#usefetcherliststreamquery-hook)
+  - [useFetcherSingleQuery Hook](#usefetchersinglequery-hook)
   - [useListStreamQuery Hook](#useliststreamquery-hook)
 - [Best Practices](#best-practices)
 - [API Reference](#api-reference)
@@ -1129,6 +1134,447 @@ const MyComponent = () => {
 };
 ```
 
+### useFetcherCountQuery Hook
+
+The `useFetcherCountQuery` hook is a specialized React hook for performing count queries using the Fetcher library. It is designed for scenarios where you need to retrieve the count of records that match a specific condition, returning a number representing the count.
+
+```typescript jsx
+import { useFetcherCountQuery } from '@ahoo-wang/fetcher-react';
+import { all } from '@ahoo-wang/fetcher-wow';
+function UserCountComponent() {
+  const { data: count, loading, error, execute } = useFetcherCountQuery({
+    url: '/api/users/count',
+    initialQuery: all(),
+    autoExecute: true,
+  });
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  return (
+    <div>
+      <div>Total active users: {count}</div>
+      <button onClick={execute}>Refresh Count</button>
+    </div>
+  );
+}
+```
+
+#### Auto Execute Example
+
+```typescript jsx
+import { useFetcherCountQuery } from '@ahoo-wang/fetcher-react';
+const MyComponent = () => {
+  const { data: count, loading, error, execute } = useFetcherCountQuery({
+    url: '/api/users/count',
+    initialQuery: { status: 'active' },
+    autoExecute: true, // Automatically execute on component mount
+  });
+  // The query will execute automatically when the component mounts
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  return (
+    <div>
+      <p>Total active users: {count}</p>
+    </div>
+  );
+};
+```
+
+### useFetcherPagedQuery Hook
+
+The `useFetcherPagedQuery` hook is a specialized React hook for performing paged queries using the Fetcher library. It is designed for scenarios where you need to retrieve paginated data that matches a query condition, returning a PagedList containing the items for the current page along with pagination metadata.
+
+```typescript jsx
+import { useFetcherPagedQuery } from '@ahoo-wang/fetcher-react';
+import { pagedQuery, contains, pagination, desc } from '@ahoo-wang/fetcher-wow';
+
+interface User {
+  id: number;
+  name: string;
+  email: string;
+}
+
+function UserListComponent() {
+  const {
+    data: pagedList,
+    loading,
+    error,
+    execute,
+    setQuery,
+    getQuery
+  } = useFetcherPagedQuery<User, keyof User>({
+    url: '/api/users/paged',
+    initialQuery: pagedQuery({
+      condition: contains('name', 'John'),
+      sort: [desc('createdAt')],
+      pagination: pagination({ index: 1, size: 10 })
+    }),
+    autoExecute: true,
+  });
+
+  const goToPage = (page: number) => {
+    const currentQuery = getQuery();
+    setQuery({
+      ...currentQuery,
+      pagination: { ...currentQuery.pagination, index: page }
+    });
+  };
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <h2>Users</h2>
+      <ul>
+        {pagedList.list.map(user => (
+          <li key={user.id}>{user.name} - {user.email}</li>
+        ))}
+      </ul>
+      <div>
+        <span>Total: {pagedList.total} users</span>
+        <button onClick={() => goToPage(1)} disabled={pagedList.pagination.index === 1}>
+          First
+        </button>
+        <button onClick={() => goToPage(pagedList.pagination.index - 1)} disabled={pagedList.pagination.index === 1}>
+          Previous
+        </button>
+        <span>Page {pagedList.pagination.index}</span>
+        <button onClick={() => goToPage(pagedList.pagination.index + 1)}>
+          Next
+        </button>
+      </div>
+    </div>
+  );
+}
+```
+
+#### Auto Execute Example
+
+```typescript jsx
+import { useFetcherPagedQuery } from '@ahoo-wang/fetcher-react';
+
+const MyComponent = () => {
+  const { data: pagedList, loading, error, execute } = useFetcherPagedQuery({
+    url: '/api/products/paged',
+    initialQuery: {
+      condition: { category: 'electronics' },
+      pagination: { index: 1, size: 20 },
+      projection: {},
+      sort: []
+    },
+    autoExecute: true, // Automatically execute on component mount
+  });
+
+  // The query will execute automatically when the component mounts
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <h2>Products</h2>
+      <div>Total: {pagedList.total}</div>
+      <ul>
+        {pagedList.list.map(product => (
+          <li key={product.id}>{product.name}</li>
+        ))}
+      </ul>
+    </div>
+  );
+};
+```
+
+### useFetcherListQuery Hook
+
+The `useFetcherListQuery` hook is a specialized React hook for performing list queries using the Fetcher library. It is designed for fetching lists of items with support for filtering, sorting, and pagination through the ListQuery type, returning an array of results.
+
+```typescript jsx
+import { useFetcherListQuery } from '@ahoo-wang/fetcher-react';
+import { listQuery, contains, desc } from '@ahoo-wang/fetcher-wow';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  createdAt: string;
+}
+
+function UserListComponent() {
+  const {
+    loading,
+    result: users,
+    error,
+    execute,
+    setQuery,
+    getQuery,
+  } = useFetcherListQuery<User, keyof User>({
+    url: '/api/users/list',
+    initialQuery: listQuery({
+      condition: contains('name', 'John'),
+      sort: [desc('createdAt')],
+      limit: 10,
+    }),
+    autoExecute: true,
+  });
+
+  const loadMore = () => {
+    const currentQuery = getQuery();
+    setQuery({
+      ...currentQuery,
+      limit: (currentQuery.limit || 10) + 10,
+    });
+  };
+
+  if (loading) return <div>Loading users...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <h2>Users ({users?.length || 0})</h2>
+      <ul>
+        {users?.map(user => (
+          <li key={user.id}>
+            {user.name} - {user.email}
+          </li>
+        ))}
+      </ul>
+      <button onClick={loadMore}>Load More</button>
+      <button onClick={execute}>Refresh list</button>
+    </div>
+  );
+}
+```
+
+#### Auto Execute Example
+
+```typescript jsx
+import { useFetcherListQuery } from '@ahoo-wang/fetcher-react';
+
+const MyComponent = () => {
+  const { result: products, loading, error, execute } = useFetcherListQuery({
+    url: '/api/products/list',
+    initialQuery: {
+      condition: { category: 'electronics' },
+      projection: {},
+      sort: [],
+      limit: 20
+    },
+    autoExecute: true, // Automatically execute on component mount
+  });
+
+  // The query will execute automatically when the component mounts
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <h2>Products</h2>
+      <ul>
+        {products?.map(product => (
+          <li key={product.id}>{product.name}</li>
+        ))}
+      </ul>
+    </div>
+  );
+};
+```
+
+### useFetcherListStreamQuery Hook
+
+The `useFetcherListStreamQuery` hook is a specialized React hook for performing list stream queries using the Fetcher library with server-sent events. It is designed for scenarios where you need to retrieve a stream of data that matches a list query condition, returning a ReadableStream of JSON server-sent events for real-time data streaming.
+
+```typescript jsx
+import { useFetcherListStreamQuery } from '@ahoo-wang/fetcher-react';
+import { listQuery, contains } from '@ahoo-wang/fetcher-wow';
+import { JsonServerSentEvent } from '@ahoo-wang/fetcher-eventstream';
+import { useEffect, useRef } from 'react';
+
+interface User {
+  id: number;
+  name: string;
+}
+
+function UserStreamComponent() {
+  const { data: stream, loading, error, execute } = useFetcherListStreamQuery<User, 'id' | 'name'>({
+    url: '/api/users/stream',
+    initialQuery: listQuery({
+      condition: contains('name', 'John'),
+      limit: 10,
+    }),
+    autoExecute: true,
+  });
+
+  const messagesRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (stream) {
+      const reader = stream.getReader();
+      const readStream = async () => {
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            // Process the JsonServerSentEvent<User>
+            const newUser = value.data;
+            if (messagesRef.current) {
+              const div = document.createElement('div');
+              div.textContent = `New user: ${newUser.name}`;
+              messagesRef.current.appendChild(div);
+            }
+          }
+        } catch (err) {
+          console.error('Stream error:', err);
+        }
+      };
+      readStream();
+    }
+  }, [stream]);
+
+  if (loading) return <div>Loading stream...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <div ref={messagesRef}></div>
+      <button onClick={execute}>Restart Stream</button>
+    </div>
+  );
+}
+```
+
+#### Auto Execute Example
+
+```typescript jsx
+import { useFetcherListStreamQuery } from '@ahoo-wang/fetcher-react';
+import { useEffect, useRef } from 'react';
+
+const MyComponent = () => {
+  const { data: stream, loading, error, execute } = useFetcherListStreamQuery({
+    url: '/api/notifications/stream',
+    initialQuery: {
+      condition: { type: 'important' },
+      limit: 50
+    },
+    autoExecute: true, // Automatically execute on component mount
+  });
+
+  const notificationsRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (stream) {
+      const reader = stream.getReader();
+      const processStream = async () => {
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+
+            const notification = value.data;
+            if (notificationsRef.current) {
+              const notificationDiv = document.createElement('div');
+              notificationDiv.textContent = `Notification: ${notification.message}`;
+              notificationsRef.current.appendChild(notificationDiv);
+            }
+          }
+        } catch (err) {
+          console.error('Stream processing error:', err);
+        }
+      };
+      processStream();
+    }
+  }, [stream]);
+
+  // The stream will start automatically when the component mounts
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+
+  return (
+    <div>
+      <h2>Live Notifications</h2>
+      <div ref={notificationsRef}></div>
+    </div>
+  );
+};
+```
+
+### useFetcherSingleQuery Hook
+
+The `useFetcherSingleQuery` hook is a specialized React hook for performing single item queries using the Fetcher library. It is designed for fetching a single item with support for filtering and sorting through the SingleQuery type, returning a single result item.
+
+```typescript jsx
+import { useFetcherSingleQuery } from '@ahoo-wang/fetcher-react';
+import { singleQuery, eq } from '@ahoo-wang/fetcher-wow';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  createdAt: string;
+}
+
+function UserProfileComponent({ userId }: { userId: string }) {
+  const {
+    loading,
+    result: user,
+    error,
+    execute,
+  } = useFetcherSingleQuery<User, keyof User>({
+    url: `/api/users/${userId}`,
+    initialQuery: singleQuery({
+      condition: eq('id', userId),
+    }),
+    autoExecute: true,
+  });
+
+  if (loading) return <div>Loading user...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  if (!user) return <div>User not found</div>;
+
+  return (
+    <div>
+      <h2>{user.name}</h2>
+      <p>Email: {user.email}</p>
+      <p>Created: {user.createdAt}</p>
+      <button onClick={execute}>Refresh</button>
+    </div>
+  );
+}
+```
+
+#### Auto Execute Example
+
+```typescript jsx
+import { useFetcherSingleQuery } from '@ahoo-wang/fetcher-react';
+
+const MyComponent = () => {
+  const { result: product, loading, error, execute } = useFetcherSingleQuery({
+    url: '/api/products/featured',
+    initialQuery: {
+      condition: { featured: true },
+      projection: {},
+      sort: []
+    },
+    autoExecute: true, // Automatically execute on component mount
+  });
+
+  // The query will execute automatically when the component mounts
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  if (!product) return <div>Product not found</div>;
+
+  return (
+    <div>
+      <h2>Featured Product</h2>
+      <div>{product.name}</div>
+      <div>{product.description}</div>
+    </div>
+  );
+};
+```
+
 ### useListStreamQuery Hook
 
 The `useListStreamQuery` hook manages list stream queries that return a readable stream of server-sent events.
@@ -2242,6 +2688,156 @@ A React hook for managing count queries with state management for conditions.
 
 An object containing promise state, execute function, and setter for condition.
 
+### useFetcherCountQuery
+
+```typescript
+function useFetcherCountQuery<FIELDS extends string = string, E = FetcherError>(
+  options: UseFetcherCountQueryOptions<FIELDS, E>,
+): UseFetcherCountQueryReturn<FIELDS, E>;
+```
+
+A React hook for performing count queries using the Fetcher library. It wraps the useFetcherQuery hook and specializes it for count operations, returning a number representing the count.
+
+**Type Parameters:**
+
+- `FIELDS`: A string union type representing the fields that can be used in the condition
+- `E`: The type of error that may be thrown (defaults to `FetcherError`)
+
+**Parameters:**
+
+- `options`: Configuration options for the count query, including the condition, fetcher instance, and other query settings
+  - `url`: The URL to fetch the count from
+  - `initialQuery`: The initial condition for the count query
+  - `autoExecute`: Whether to automatically execute the query on component mount (defaults to false)
+
+**Returns:**
+
+An object containing the query result (count as a number), loading state, error state, and utility functions.
+
+### useFetcherPagedQuery
+
+```typescript
+function useFetcherPagedQuery<
+  R,
+  FIELDS extends string = string,
+  E = FetcherError,
+>(
+  options: UseFetcherPagedQueryOptions<R, FIELDS, E>,
+): UseFetcherPagedQueryReturn<R, FIELDS, E>;
+```
+
+A React hook for performing paged queries using the Fetcher library. It wraps the useFetcherQuery hook and specializes it for paged operations, returning a PagedList containing items and pagination metadata.
+
+**Type Parameters:**
+
+- `R`: The type of the resource or entity contained in each item of the paged list
+- `FIELDS`: A string union type representing the fields that can be used in the paged query
+- `E`: The type of error that may be thrown (defaults to `FetcherError`)
+
+**Parameters:**
+
+- `options`: Configuration options for the paged query, including the paged query parameters, fetcher instance, and other query settings
+  - `url`: The URL to fetch the paged data from
+  - `initialQuery`: The initial paged query configuration
+  - `autoExecute`: Whether to automatically execute the query on component mount (defaults to false)
+
+**Returns:**
+
+An object containing the query result (PagedList with items and pagination info), loading state, error state, and utility functions.
+
+### useFetcherListQuery
+
+```typescript
+function useFetcherListQuery<
+  R,
+  FIELDS extends string = string,
+  E = FetcherError,
+>(
+  options: UseFetcherListQueryOptions<R, FIELDS, E>,
+): UseFetcherListQueryReturn<R, FIELDS, E>;
+```
+
+A React hook for executing list queries using the fetcher library within the wow framework. It wraps the useFetcherQuery hook and specializes it for list operations, returning an array of results with support for filtering, sorting, and pagination.
+
+**Type Parameters:**
+
+- `R`: The type of individual items in the result array (e.g., User, Product)
+- `FIELDS`: The fields available for filtering, sorting, and pagination in the list query
+- `E`: The type of error that may be thrown (defaults to `FetcherError`)
+
+**Parameters:**
+
+- `options`: Configuration options for the list query, including the list query parameters, fetcher instance, and other query settings
+  - `url`: The URL to fetch the list data from
+  - `initialQuery`: The initial list query configuration
+  - `autoExecute`: Whether to automatically execute the query on component mount (defaults to false)
+
+**Returns:**
+
+An object containing the query result (array of items), loading state, error state, and utility functions.
+
+### useFetcherListStreamQuery
+
+```typescript
+function useFetcherListStreamQuery<
+  R,
+  FIELDS extends string = string,
+  E = FetcherError,
+>(
+  options: UseFetcherListStreamQueryOptions<R, FIELDS, E>,
+): UseFetcherListStreamQueryReturn<R, FIELDS, E>;
+```
+
+A React hook for performing list stream queries using the Fetcher library with server-sent events. It wraps the useFetcherQuery hook and specializes it for streaming operations, returning a ReadableStream of JSON server-sent events for real-time data streaming.
+
+**Type Parameters:**
+
+- `R`: The type of the resource or entity contained in each event in the stream
+- `FIELDS`: The fields available for filtering, sorting, and pagination in the list query
+- `E`: The type of error that may be thrown (defaults to `FetcherError`)
+
+**Parameters:**
+
+- `options`: Configuration options for the list stream query, including the list query parameters, fetcher instance, and other query settings
+  - `url`: The URL to fetch the stream data from
+  - `initialQuery`: The initial list query configuration
+  - `autoExecute`: Whether to automatically execute the query on component mount (defaults to false)
+
+**Returns:**
+
+An object containing the query result (ReadableStream of JSON server-sent events), loading state, error state, and utility functions.
+
+### useFetcherSingleQuery
+
+```typescript
+function useFetcherSingleQuery<
+  R,
+  FIELDS extends string = string,
+  E = FetcherError,
+>(
+  options: UseFetcherSingleQueryOptions<R, FIELDS, E>,
+): UseFetcherSingleQueryReturn<R, FIELDS, E>;
+```
+
+A React hook for executing single item queries using the fetcher library within the wow framework. It wraps the useFetcherQuery hook and specializes it for single item operations, returning a single result item with support for filtering and sorting.
+
+**Type Parameters:**
+
+- `R`: The type of the result item (e.g., User, Product)
+- `FIELDS`: The fields available for filtering and sorting in the single query
+- `E`: The type of error that may be thrown (defaults to `FetcherError`)
+
+**Parameters:**
+
+- `options`: Configuration options for the single query, including the single query parameters, fetcher instance, and other query settings
+  - `url`: The URL to fetch the single item from
+  - `initialQuery`: The initial single query configuration
+  - `autoExecute`: Whether to automatically execute the query on component mount (defaults to false)
+
+**Returns:**
+
+An object containing the query result (single item), loading state, error state, and utility functions.
+
 ### useListStreamQuery
 
 ```typescript