@spoosh/react 0.11.0 → 0.13.0

package/README.md

@@ -1,6 +1,6 @@
 # @spoosh/react
 
-React hooks for Spoosh - `useRead`, `useWrite`, and `useInfiniteRead`.
+React hooks for Spoosh - `useRead`, `useWrite`, `usePages`, and `useSSE`.
 
 **[Documentation](https://spoosh.dev/docs/react)** · **Requirements:** TypeScript >= 5.0, React >= 18.0
 
@@ -23,7 +23,7 @@ const spoosh = new Spoosh<ApiSchema, Error>("/api").use([
   cachePlugin({ staleTime: 5000 }),
 ]);
 
-export const { useRead, useWrite, useInfiniteRead } = create(spoosh);
+export const { useRead, useWrite, usePages } = create(spoosh);
 ```
 
 ### useRead
@@ -98,7 +98,7 @@ await updateUser.trigger({
 });
 ```
 
-### useInfiniteRead
+### usePages
 
 Bidirectional paginated data fetching with infinite scroll support.
 
@@ -106,7 +106,7 @@ Bidirectional paginated data fetching with infinite scroll support.
 function PostList() {
   const {
     data,
-    allResponses,
+    pages,
     loading,
     canFetchNext,
     canFetchPrev,
@@ -114,26 +114,26 @@ function PostList() {
     fetchPrev,
     fetchingNext,
     fetchingPrev,
-  } = useInfiniteRead(
+  } = usePages(
     (api) => api("posts").GET({ query: { page: 1 } }),
     {
       // Required: Check if next page exists
-      canFetchNext: ({ response }) => response?.meta.hasMore ?? false,
+      canFetchNext: ({ lastPage }) => lastPage?.data?.meta.hasMore ?? false,
 
       // Required: Build request for next page
-      nextPageRequest: ({ response, request }) => ({
-        query: { ...request.query, page: (response?.meta.page ?? 0) + 1 },
+      nextPageRequest: ({ lastPage }) => ({
+        query: { page: (lastPage?.data?.meta.page ?? 0) + 1 },
       }),
 
-      // Required: Merge all responses into items
-      merger: (allResponses) => allResponses.flatMap((r) => r.items),
+      // Required: Merge all pages into items
+      merger: (pages) => pages.flatMap((p) => p.data?.items ?? []),
 
       // Optional: Check if previous page exists
-      canFetchPrev: ({ response }) => (response?.meta.page ?? 1) > 1,
+      canFetchPrev: ({ firstPage }) => (firstPage?.data?.meta.page ?? 1) > 1,
 
       // Optional: Build request for previous page
-      prevPageRequest: ({ response, request }) => ({
-        query: { ...request.query, page: (response?.meta.page ?? 2) - 1 },
+      prevPageRequest: ({ firstPage }) => ({
+        query: { page: (firstPage?.data?.meta.page ?? 2) - 1 },
       }),
     }
   );
@@ -158,6 +158,61 @@ function PostList() {
 }
 ```
 
+### useSSE
+
+Subscribe to real-time data streams using Server-Sent Events (SSE).
+
+```typescript
+import { sse } from "@spoosh/transport-sse";
+
+// Setup with SSE transport
+const spoosh = new Spoosh<ApiSchema, Error>("/api").withTransports([sse()]);
+export const { useSSE } = create(spoosh);
+
+// Basic subscription
+function Notifications() {
+  const { data, isConnected, loading } = useSSE(
+    (api) => api("notifications").GET({ query: { userId: "user-123" } })
+  );
+
+  if (loading) return <div>Connecting...</div>;
+
+  return (
+    <div>
+      <span>{isConnected ? "Connected" : "Disconnected"}</span>
+      {data?.message && <p>{data.message.text}</p>}
+    </div>
+  );
+}
+
+// Subscribe to specific events only
+const { data } = useSSE(
+  (api) => api("notifications").GET({
+    query: { userId: "user-123" },
+  }),
+  { events: ["alert"] }  // Only alert events
+);
+
+// AI streaming with accumulation
+const { data, trigger } = useSSE(
+  (api) => api("chat").POST(),
+  {
+    events: ["chunk", "done"],
+    parse: "json-done",
+    accumulate: {
+      chunk: (prev, curr) => ({
+        ...curr,
+        chunk: (prev?.chunk || "") + curr.chunk,
+      }),
+    },
+    enabled: false,
+  }
+);
+
+// Start streaming on demand
+await trigger({ body: { message: "Hello" } });
+```
+
 ## API Reference
 
 ### useRead(readFn, options?)
@@ -192,41 +247,88 @@ function PostList() {
 | `loading` | `boolean`              | True while mutation is in progress |
 | `abort`   | `() => void`           | Abort current request              |
 
-### useInfiniteRead(readFn, options)
+### usePages(readFn, options)
 
-| Option            | Type                         | Required | Description                     |
-| ----------------- | ---------------------------- | -------- | ------------------------------- |
-| `canFetchNext`    | `(ctx) => boolean`           | Yes      | Check if next page exists       |
-| `nextPageRequest` | `(ctx) => Partial<TRequest>` | Yes      | Build request for next page     |
-| `merger`          | `(allResponses) => TItem[]`  | Yes      | Merge all responses into items  |
-| `canFetchPrev`    | `(ctx) => boolean`           | No       | Check if previous page exists   |
-| `prevPageRequest` | `(ctx) => Partial<TRequest>` | No       | Build request for previous page |
-| `enabled`         | `boolean`                    | No       | Whether to fetch automatically  |
+| Option            | Type                         | Required | Description                                       |
+| ----------------- | ---------------------------- | -------- | ------------------------------------------------- |
+| `merger`          | `(pages) => TItem[]`         | Yes      | Merge all pages into items                        |
+| `canFetchNext`    | `(ctx) => boolean`           | No       | Check if next page exists. Default: `() => false` |
+| `nextPageRequest` | `(ctx) => Partial<TRequest>` | No       | Build request for next page                       |
+| `canFetchPrev`    | `(ctx) => boolean`           | No       | Check if previous page exists                     |
+| `prevPageRequest` | `(ctx) => Partial<TRequest>` | No       | Build request for previous page                   |
+| `enabled`         | `boolean`                    | No       | Whether to fetch automatically                    |
 
 **Context object passed to callbacks:**
 
 ```typescript
-type Context<TData, TRequest> = {
-  response: TData | undefined; // Latest response
-  allResponses: TData[]; // All fetched responses
-  request: TRequest; // Current request options
+// For canFetchNext and nextPageRequest
+type NextContext<TData, TRequest> = {
+  lastPage: InfinitePage<TData> | undefined;
+  pages: InfinitePage<TData>[];
+  request: TRequest;
+};
+
+// For canFetchPrev and prevPageRequest
+type PrevContext<TData, TRequest> = {
+  firstPage: InfinitePage<TData> | undefined;
+  pages: InfinitePage<TData>[];
+  request: TRequest;
+};
+
+// Each page in the pages array
+type InfinitePage<TData> = {
+  status: "pending" | "loading" | "success" | "error" | "stale";
+  data?: TData;
+  error?: TError;
+  meta?: TMeta;
+  input?: { query?; params?; body? };
 };
 ```
 
 **Returns:**
 
-| Property       | Type                   | Description                     |
-| -------------- | ---------------------- | ------------------------------- |
-| `data`         | `TItem[] \| undefined` | Merged items from all responses |
-| `allResponses` | `TData[] \| undefined` | Array of all raw responses      |
-| `loading`      | `boolean`              | True during initial load        |
-| `fetching`     | `boolean`              | True during any fetch           |
-| `fetchingNext` | `boolean`              | True while fetching next page   |
-| `fetchingPrev` | `boolean`              | True while fetching previous    |
-| `canFetchNext` | `boolean`              | Whether next page exists        |
-| `canFetchPrev` | `boolean`              | Whether previous page exists    |
-| `fetchNext`    | `() => Promise<void>`  | Fetch the next page             |
-| `fetchPrev`    | `() => Promise<void>`  | Fetch the previous page         |
-| `refetch`      | `() => Promise<void>`  | Refetch all pages               |
-| `abort`        | `() => void`           | Abort current request           |
-| `error`        | `TError \| undefined`  | Error if request failed         |
+| Property       | Type                          | Description                                     |
+| -------------- | ----------------------------- | ----------------------------------------------- |
+| `data`         | `TItem[] \| undefined`        | Merged items from all pages                     |
+| `pages`        | `InfinitePage<TData>[]`       | Array of all pages with status, data, and meta  |
+| `loading`      | `boolean`                     | True during initial load                        |
+| `fetching`     | `boolean`                     | True during any fetch                           |
+| `fetchingNext` | `boolean`                     | True while fetching next page                   |
+| `fetchingPrev` | `boolean`                     | True while fetching previous                    |
+| `canFetchNext` | `boolean`                     | Whether next page exists                        |
+| `canFetchPrev` | `boolean`                     | Whether previous page exists                    |
+| `fetchNext`    | `() => Promise<void>`         | Fetch the next page                             |
+| `fetchPrev`    | `() => Promise<void>`         | Fetch the previous page                         |
+| `trigger`      | `(options?) => Promise<void>` | Trigger fetch with optional new request options |
+| `abort`        | `() => void`                  | Abort current request                           |
+| `error`        | `TError \| undefined`         | Error if request failed                         |
+
+### useSSE(subFn, options?)
+
+| Option       | Type               | Default     | Description                       |
+| ------------ | ------------------ | ----------- | --------------------------------- |
+| `enabled`    | `boolean`          | `true`      | Whether to connect automatically  |
+| `events`     | `string[]`         | all events  | Subscribe to specific events only |
+| `parse`      | `ParseConfig`      | `"auto"`    | How to parse raw event data       |
+| `accumulate` | `AccumulateConfig` | `"replace"` | How to combine events over time   |
+
+**Returns:**
+
+| Property      | Type                    | Description                    |
+| ------------- | ----------------------- | ------------------------------ |
+| `data`        | `TEvents \| undefined`  | Accumulated event data         |
+| `error`       | `TError \| undefined`   | Error if connection failed     |
+| `loading`     | `boolean`               | True during initial connection |
+| `isConnected` | `boolean`               | True when connected to stream  |
+| `trigger`     | `(options?) => Promise` | Reconnect with new options     |
+| `disconnect`  | `() => void`            | Disconnect from stream         |
+| `reset`       | `() => void`            | Reset accumulated data         |
+
+**Connection Options:**
+
+| Option        | Type                 | Description                                 |
+| ------------- | -------------------- | ------------------------------------------- |
+| `headers`     | `HeadersInit`        | Request headers                             |
+| `credentials` | `RequestCredentials` | Credentials mode                            |
+| `maxRetries`  | `number`             | Max retry attempts (default: 3)             |
+| `retryDelay`  | `number`             | Delay between retries in ms (default: 1000) |