@laravel/stream-react 0.2.0 → 0.3.0

package/README.md

@@ -7,7 +7,7 @@
 <a href="https://www.npmjs.com/package/@laravel/stream-react"><img src="https://img.shields.io/npm/l/@laravel/stream-react" alt="License"></a>
 </p>
 
-Easily consume [Server-Sent Events (SSE)](https://laravel.com/docs/responses#event-streams) in your React application.
+Easily consume streams in your React application.
 
 ## Installation
 
@@ -15,17 +15,148 @@ Easily consume [Server-Sent Events (SSE)](https://laravel.com/docs/responses#eve
 npm install @laravel/stream-react
 ```
 
-## Usage
+## Streaming Responses
 
-Provide your stream URL and the hook will automatically update the `message` with the concatenated response as messages are returned from your server:
+> [!IMPORTANT]
+> The `useStream` hook is currently in Beta, the API is subject to change prior to the v1.0.0 release. All notable changes will be documented in the [changelog](./../../CHANGELOG.md).
+
+The `useStream` hook allows you to seamlessly consume [streamed responses](https://laravel.com/docs/responses#streamed-responses) in your React application.
+
+Provide your stream URL and the hook will automatically update `data` with the concatenated response as data is returned from your server:
+
+```tsx
+import { useStream } from "@laravel/stream-react";
+
+function App() {
+    const { data, isFetching, isStreaming, send } = useStream("chat");
+
+    const sendMessage = () => {
+        send({
+            message: `Current timestamp: ${Date.now()}`,
+        });
+    };
+
+    return (
+        <div>
+            <div>{data}</div>
+            {isFetching && <div>Connecting...</div>}
+            {isStreaming && <div>Generating...</div>}
+            <button onClick={sendMessage}>Send Message</button>
+        </div>
+    );
+}
+```
+
+When sending data back to the stream, the active connection to the stream is canceled before sending the new data. All requests are sent as JSON `POST` requests.
+
+The second argument given to `useStream` is an options object that you may use to customize the stream consumption behavior. The default values for this object are shown below:
+
+```tsx
+import { useStream } from "@laravel/stream-react";
+
+function App() {
+    const { data } = useStream("chat", {
+        id: undefined,
+        initialInput: undefined,
+        headers: undefined,
+        csrfToken: undefined,
+        onResponse: (response: Response) => void,
+        onData: (data: string) => void,
+        onCancel: () => void,
+        onFinish: () => void,
+        onError: (error: Error) => void,
+    });
+
+    return <div>{data}</div>;
+}
+```
+
+`onResponse` is triggered after a successful initial response from the stream and the raw [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) is passed to the callback.
+
+`onData` is called as each chunk is received, the current chunk is passed to the callback.
+
+`onFinish` is called when a stream has finished and when an error is thrown during the fetch/read cycle.
+
+By default, a request is not made the to stream on initialization. You may pass an initial payload to the stream by using the `initialInput` option:
+
+```tsx
+import { useStream } from "@laravel/stream-react";
+
+function App() {
+    const { data } = useStream("chat", {
+        initialInput: {
+            message: "Introduce yourself.",
+        },
+    });
+
+    return <div>{data}</div>;
+}
+```
+
+To cancel a stream manually, you may use the `cancel` method returned from the hook:
+
+```tsx
+import { useStream } from "@laravel/stream-react";
+
+function App() {
+    const { data, cancel } = useStream("chat");
+
+    return (
+        <div>
+            <div>{data}</div>
+            <button onClick={cancel}>Cancel</button>
+        </div>
+    );
+}
+```
+
+Each time the `useStream` hook is used, a random `id` is generated to identify the stream. This is sent back to the server with each request in the `X-STREAM-ID` header.
+
+When consuming the same stream from multiple components, you can read and write to the stream by providing your own `id`:
+
+```tsx
+// App.tsx
+import { useStream } from "@laravel/stream-react";
+
+function App() {
+    const { data, id } = useStream("chat");
+
+    return (
+        <div>
+            <div>{data}</div>
+            <StreamStatus id={id} />
+        </div>
+    );
+}
+
+// StreamStatus.tsx
+import { useStream } from "@laravel/stream-react";
+
+function StreamStatus({ id }) {
+    const { isFetching, isStreaming } = useStream("chat", { id });
+
+    return (
+        <div>
+            {isFetching && <div>Connecting...</div>}
+            {isStreaming && <div>Generating...</div>}
+        </div>
+    );
+}
+```
+
+## Event Streams (SSE)
+
+The `useEventStream` hook allows you to seamlessly consume [Server-Sent Events (SSE)](https://laravel.com/docs/responses#event-streams) in your React application.
+
+Provide your stream URL and the hook will automatically update `message` with the concatenated response as messages are returned from your server:
 
 ```tsx
 import { useEventStream } from "@laravel/stream-react";
 
 function App() {
-  const { message } = useEventStream("/stream");
+    const { message } = useEventStream("/stream");
 
-  return <div>{message}</div>;
+    return <div>{message}</div>;
 }
 ```
 
@@ -35,15 +166,36 @@ You also have access to the array of message parts:
 import { useEventStream } from "@laravel/stream-react";
 
 function App() {
-  const { messageParts } = useEventStream("/stream");
-
-  return (
-    <ul>
-      {messageParts.forEach((message) => (
-        <li>{message}</li>
-      ))}
-    </ul>
-  );
+    const { messageParts } = useEventStream("/stream");
+
+    return (
+        <ul>
+            {messageParts.forEach((message) => (
+                <li>{message}</li>
+            ))}
+        </ul>
+    );
+}
+```
+
+If you'd like to listen to multiple events:
+
+```tsx
+import { useEventStream } from "@laravel/stream-react";
+
+function App() {
+    useEventStream("/stream", {
+        eventName: ["update", "create"],
+        onMessage: (event) => {
+            if (event.type === "update") {
+                // Handle update
+            } else {
+                // Handle create
+            }
+        },
+    });
+
+    return null;
 }
 ```
 
@@ -53,22 +205,23 @@ The second parameter is an options object where all properties are optional (def
 import { useEventStream } from "@laravel/stream-react";
 
 function App() {
-  const { message } = useEventStream("/stream", {
-    event: "update",
-    onMessage: (message) => {
-      //
-    },
-    onError: (error) => {
-      //
-    },
-    onComplete: () => {
-      //
-    },
-    endSignal: "</stream>",
-    glue: " ",
-  });
-
-  return <div>{message}</div>;
+    const { message } = useEventStream("/stream", {
+        event: "update",
+        onMessage: (message) => {
+            //
+        },
+        onError: (error) => {
+            //
+        },
+        onComplete: () => {
+            //
+        },
+        endSignal: "</stream>",
+        glue: " ",
+        replace: false,
+    });
+
+    return <div>{message}</div>;
 }
 ```
 
@@ -79,15 +232,15 @@ import { useEventStream } from "@laravel/stream-react";
 import { useEffect } from "react";
 
 function App() {
-  const { message, close } = useEventStream("/stream");
+    const { message, close } = useEventStream("/stream");
 
-  useEffect(() => {
-    setTimeout(() => {
-      close();
-    }, 3000);
-  }, []);
+    useEffect(() => {
+        setTimeout(() => {
+            close();
+        }, 3000);
+    }, []);
 
-  return <div>{message}</div>;
+    return <div>{message}</div>;
 }
 ```
 
@@ -98,15 +251,15 @@ import { useEventStream } from "@laravel/stream-react";
 import { useEffect } from "react";
 
 function App() {
-  const { message, clearMessage } = useEventStream("/stream");
+    const { message, clearMessage } = useEventStream("/stream");
 
-  useEffect(() => {
-    setTimeout(() => {
-      clearMessage();
-    }, 3000);
-  }, []);
+    useEffect(() => {
+        setTimeout(() => {
+            clearMessage();
+        }, 3000);
+    }, []);
 
-  return <div>{message}</div>;
+    return <div>{message}</div>;
 }
 ```
 

package/dist/index.d.ts

@@ -1,19 +1,32 @@
-declare type Options = {
-    eventName?: string;
+declare type EventStreamOptions = {
+    eventName?: string | string[];
     endSignal?: string;
     glue?: string;
+    replace?: boolean;
     onMessage?: (event: MessageEvent) => void;
     onComplete?: () => void;
     onError?: (error: Event) => void;
 };
 
-declare type StreamResult = {
+declare type EventStreamResult = {
     message: string;
     messageParts: string[];
     close: (resetMessage?: boolean) => void;
     clearMessage: () => void;
 };
 
+declare type StreamOptions = {
+    id?: string;
+    initialInput?: Record<string, any>;
+    headers?: Record<string, string>;
+    csrfToken?: string;
+    onResponse?: (response: Response) => void;
+    onData?: (data: string) => void;
+    onCancel?: () => void;
+    onFinish?: () => void;
+    onError?: (error: Error) => void;
+};
+
 /**
  * Hook for handling server-sent event (SSE) streams
  *
@@ -24,6 +37,15 @@ declare type StreamResult = {
  *
  * @returns StreamResult object containing the accumulated response, close, and reset functions
  */
-export declare const useEventStream: (url: string, { eventName, endSignal, glue, onMessage, onComplete, onError, }?: Options) => StreamResult;
+export declare const useEventStream: (url: string, { eventName, endSignal, glue, replace, onMessage, onComplete, onError, }?: EventStreamOptions) => EventStreamResult;
+
+export declare const useStream: (url: string, options?: StreamOptions) => {
+    data: string;
+    isFetching: boolean;
+    isStreaming: boolean;
+    id: string;
+    send: (body: Record<string, any>) => void;
+    cancel: () => void;
+};
 
 export { }

package/dist/index.es.js

@@ -1,38 +1,169 @@
-import { useRef as p, useState as L, useCallback as c, useEffect as C } from "react";
-const l = "data: ", j = (d, {
-  eventName: t = "update",
-  endSignal: i = "</stream>",
-  glue: f = " ",
-  onMessage: P = () => null,
-  onComplete: R = () => null,
-  onError: S = () => null
+import { useRef as b, useMemo as x, useState as y, useCallback as d, useEffect as C } from "react";
+const I = "data: ", J = (r, {
+  eventName: e = "update",
+  endSignal: c = "</stream>",
+  glue: o = " ",
+  replace: k = !1,
+  onMessage: v = () => null,
+  onComplete: D = () => null,
+  onError: w = () => null
 } = {}) => {
-  const r = p(null), s = p([]), [b, g] = L(""), [x, E] = L([]), n = c(() => {
-    s.current = [], g(""), E([]);
-  }, []), u = c(
-    (e) => {
-      if ([i, `${l}${i}`].includes(e.data)) {
-        a(), R();
+  const l = b(null), f = b([]), m = x(
+    () => Array.isArray(e) ? e : [e],
+    Array.isArray(e) ? e : [e]
+  ), [i, g] = y(""), [A, R] = y([]), h = d(() => {
+    f.current = [], g(""), R([]);
+  }, []), n = d(
+    (t) => {
+      if ([c, `${I}${c}`].includes(t.data)) {
+        a(), D();
         return;
       }
-      s.current.push(
-        e.data.startsWith(l) ? e.data.substring(l.length) : e.data
-      ), g(s.current.join(f)), E(s.current), P(e);
+      k && h(), f.current.push(
+        t.data.startsWith(I) ? t.data.substring(I.length) : t.data
+      ), g(f.current.join(o)), R(f.current), v(t);
     },
-    [t, f]
-  ), o = c((e) => {
-    S(e), a();
-  }, []), a = c((e = !1) => {
-    var m, h, M;
-    (m = r.current) == null || m.removeEventListener(t, u), (h = r.current) == null || h.removeEventListener("error", o), (M = r.current) == null || M.close(), r.current = null, e && n();
+    [m, o]
+  ), s = d((t) => {
+    w(t), a();
+  }, []), a = d((t = !1) => {
+    var u, S;
+    m.forEach((L) => {
+      var E;
+      (E = l.current) == null || E.removeEventListener(L, n);
+    }), (u = l.current) == null || u.removeEventListener("error", s), (S = l.current) == null || S.close(), l.current = null, t && h();
   }, []);
-  return C(() => (n(), r.current = new EventSource(d), r.current.addEventListener(t, u), r.current.addEventListener("error", o), a), [d, t, u, o, n]), {
-    message: b,
-    messageParts: x,
+  return C(() => (h(), l.current = new EventSource(r), m.forEach((t) => {
+    var u;
+    (u = l.current) == null || u.addEventListener(t, n);
+  }), l.current.addEventListener("error", s), a), [r, m, n, s, h]), {
+    message: i,
+    messageParts: A,
     close: a,
-    clearMessage: n
+    clearMessage: h
+  };
+}, O = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
+let j = (r = 21) => {
+  let e = "", c = crypto.getRandomValues(new Uint8Array(r |= 0));
+  for (; r--; )
+    e += O[c[r] & 63];
+  return e;
+};
+const T = /* @__PURE__ */ new Map(), F = /* @__PURE__ */ new Map(), M = (r) => {
+  const e = T.get(r);
+  return e || (T.set(r, {
+    controller: new AbortController(),
+    data: "",
+    isFetching: !1,
+    isStreaming: !1
+  }), T.get(r));
+}, P = (r) => (F.has(r) || F.set(r, []), F.get(r)), q = (r, e) => (P(r).push(e), () => {
+  F.set(
+    r,
+    P(r).filter((c) => c !== e)
+  );
+}), K = (r, e = {}) => {
+  const c = b(e.id ?? j()), o = b(M(c.current)), k = b(
+    (() => {
+      var a;
+      const n = {
+        "Content-Type": "application/json",
+        "X-STREAM-ID": c.current
+      }, s = e.csrfToken ?? ((a = document.querySelector('meta[name="csrf-token"]')) == null ? void 0 : a.getAttribute("content"));
+      return s && (n["X-CSRF-TOKEN"] = s), n;
+    })()
+  ), [v, D] = y(o.current.data), [w, l] = y(o.current.isFetching), [f, m] = y(o.current.isStreaming), i = d((n) => {
+    var a;
+    T.set(c.current, {
+      ...M(c.current),
+      ...n
+    });
+    const s = M(c.current);
+    (a = F.get(c.current)) == null || a.forEach((t) => t(s));
+  }, []), g = d(() => {
+    var n;
+    o.current.controller.abort(), (w || f) && ((n = e.onCancel) == null || n.call(e)), i({
+      isFetching: !1,
+      isStreaming: !1
+    });
+  }, [w, f]), A = d(
+    (n = {}) => {
+      const s = new AbortController();
+      i({
+        isFetching: !0,
+        controller: s
+      }), fetch(r, {
+        method: "POST",
+        signal: s.signal,
+        headers: {
+          ...k.current,
+          ...e.headers ?? {}
+        },
+        body: JSON.stringify(n)
+      }).then(async (a) => {
+        var t;
+        if (!a.ok) {
+          const u = await a.text();
+          throw new Error(u);
+        }
+        if (!a.body)
+          throw new Error(
+            "ReadableStream not yet supported in this browser."
+          );
+        return (t = e.onResponse) == null || t.call(e, a), i({
+          isFetching: !1,
+          isStreaming: !0
+        }), h(a.body.getReader());
+      }).catch((a) => {
+        var t, u;
+        i({
+          isFetching: !1,
+          isStreaming: !1
+        }), (t = e.onError) == null || t.call(e, a), (u = e.onFinish) == null || u.call(e);
+      });
+    },
+    [r]
+  ), R = d((n) => {
+    g(), A(n), i({
+      data: ""
+    });
+  }, []), h = d(
+    (n, s = "") => n.read().then(({ done: a, value: t }) => {
+      var L, E;
+      const u = new TextDecoder("utf-8").decode(t), S = s + u;
+      return (L = e.onData) == null || L.call(e, u), a ? (i({
+        data: S,
+        isStreaming: !1
+      }), (E = e.onFinish) == null || E.call(e), "") : (i({
+        data: S
+      }), h(n, S));
+    }),
+    []
+  );
+  return C(() => {
+    const n = q(
+      c.current,
+      (s) => {
+        o.current = M(c.current), l(s.isFetching), m(s.isStreaming), D(s.data);
+      }
+    );
+    return () => {
+      n();
+    };
+  }, []), C(() => (window.addEventListener("beforeunload", g), () => {
+    window.removeEventListener("beforeunload", g);
+  }), [g]), C(() => {
+    e.initialInput && A(e.initialInput);
+  }, []), {
+    data: v,
+    isFetching: w,
+    isStreaming: f,
+    id: c.current,
+    send: R,
+    cancel: g
   };
 };
 export {
-  j as useEventStream
+  J as useEventStream,
+  K as useStream
 };

package/dist/index.umd.js

@@ -1 +1 @@
-(function(s,e){typeof exports=="object"&&typeof module<"u"?e(exports,require("react")):typeof define=="function"&&define.amd?define(["exports","react"],e):(s=typeof globalThis<"u"?globalThis:s||self,e(s.LaravelStreamReact={},s.React))})(this,function(s,e){"use strict";const c="data: ",b=(d,{eventName:n="update",endSignal:f="</stream>",glue:g=" ",onMessage:M=()=>null,onComplete:R=()=>null,onError:C=()=>null}={})=>{const r=e.useRef(null),u=e.useRef([]),[L,m]=e.useState(""),[P,p]=e.useState([]),a=e.useCallback(()=>{u.current=[],m(""),p([])},[]),l=e.useCallback(t=>{if([f,`${c}${f}`].includes(t.data)){o(),R();return}u.current.push(t.data.startsWith(c)?t.data.substring(c.length):t.data),m(u.current.join(g)),p(u.current),M(t)},[n,g]),i=e.useCallback(t=>{C(t),o()},[]),o=e.useCallback((t=!1)=>{var E,h,S;(E=r.current)==null||E.removeEventListener(n,l),(h=r.current)==null||h.removeEventListener("error",i),(S=r.current)==null||S.close(),r.current=null,t&&a()},[]);return e.useEffect(()=>(a(),r.current=new EventSource(d),r.current.addEventListener(n,l),r.current.addEventListener("error",i),o),[d,n,l,i,a]),{message:L,messageParts:P,close:o,clearMessage:a}};s.useEventStream=b,Object.defineProperty(s,Symbol.toStringTag,{value:"Module"})});
+(function(d,t){typeof exports=="object"&&typeof module<"u"?t(exports,require("react")):typeof define=="function"&&define.amd?define(["exports","react"],t):(d=typeof globalThis<"u"?globalThis:d||self,t(d.LaravelStreamReact={},d.React))})(this,function(d,t){"use strict";const L="data: ",D=(r,{eventName:e="update",endSignal:c="</stream>",glue:o=" ",replace:M=!1,onMessage:T=()=>null,onComplete:v=()=>null,onError:w=()=>null}={})=>{const i=t.useRef(null),g=t.useRef([]),S=t.useMemo(()=>Array.isArray(e)?e:[e],Array.isArray(e)?e:[e]),[f,h]=t.useState(""),[k,F]=t.useState([]),m=t.useCallback(()=>{g.current=[],h(""),F([])},[]),s=t.useCallback(n=>{if([c,`${L}${c}`].includes(n.data)){a(),v();return}M&&m(),g.current.push(n.data.startsWith(L)?n.data.substring(L.length):n.data),h(g.current.join(o)),F(g.current),T(n)},[S,o]),u=t.useCallback(n=>{w(n),a()},[]),a=t.useCallback((n=!1)=>{var l,b;S.forEach(A=>{var y;(y=i.current)==null||y.removeEventListener(A,s)}),(l=i.current)==null||l.removeEventListener("error",u),(b=i.current)==null||b.close(),i.current=null,n&&m()},[]);return t.useEffect(()=>(m(),i.current=new EventSource(r),S.forEach(n=>{var l;(l=i.current)==null||l.addEventListener(n,s)}),i.current.addEventListener("error",u),a),[r,S,s,u,m]),{message:f,messageParts:k,close:a,clearMessage:m}},I="useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";let j=(r=21)=>{let e="",c=crypto.getRandomValues(new Uint8Array(r|=0));for(;r--;)e+=I[c[r]&63];return e};const R=new Map,E=new Map,C=r=>{const e=R.get(r);return e||(R.set(r,{controller:new AbortController,data:"",isFetching:!1,isStreaming:!1}),R.get(r))},P=r=>(E.has(r)||E.set(r,[]),E.get(r)),x=(r,e)=>(P(r).push(e),()=>{E.set(r,P(r).filter(c=>c!==e))}),O=(r,e={})=>{const c=t.useRef(e.id??j()),o=t.useRef(C(c.current)),M=t.useRef((()=>{var a;const s={"Content-Type":"application/json","X-STREAM-ID":c.current},u=e.csrfToken??((a=document.querySelector('meta[name="csrf-token"]'))==null?void 0:a.getAttribute("content"));return u&&(s["X-CSRF-TOKEN"]=u),s})()),[T,v]=t.useState(o.current.data),[w,i]=t.useState(o.current.isFetching),[g,S]=t.useState(o.current.isStreaming),f=t.useCallback(s=>{var a;R.set(c.current,{...C(c.current),...s});const u=C(c.current);(a=E.get(c.current))==null||a.forEach(n=>n(u))},[]),h=t.useCallback(()=>{var s;o.current.controller.abort(),(w||g)&&((s=e.onCancel)==null||s.call(e)),f({isFetching:!1,isStreaming:!1})},[w,g]),k=t.useCallback((s={})=>{const u=new AbortController;f({isFetching:!0,controller:u}),fetch(r,{method:"POST",signal:u.signal,headers:{...M.current,...e.headers??{}},body:JSON.stringify(s)}).then(async a=>{var n;if(!a.ok){const l=await a.text();throw new Error(l)}if(!a.body)throw new Error("ReadableStream not yet supported in this browser.");return(n=e.onResponse)==null||n.call(e,a),f({isFetching:!1,isStreaming:!0}),m(a.body.getReader())}).catch(a=>{var n,l;f({isFetching:!1,isStreaming:!1}),(n=e.onError)==null||n.call(e,a),(l=e.onFinish)==null||l.call(e)})},[r]),F=t.useCallback(s=>{h(),k(s),f({data:""})},[]),m=t.useCallback((s,u="")=>s.read().then(({done:a,value:n})=>{var A,y;const l=new TextDecoder("utf-8").decode(n),b=u+l;return(A=e.onData)==null||A.call(e,l),a?(f({data:b,isStreaming:!1}),(y=e.onFinish)==null||y.call(e),""):(f({data:b}),m(s,b))}),[]);return t.useEffect(()=>{const s=x(c.current,u=>{o.current=C(c.current),i(u.isFetching),S(u.isStreaming),v(u.data)});return()=>{s()}},[]),t.useEffect(()=>(window.addEventListener("beforeunload",h),()=>{window.removeEventListener("beforeunload",h)}),[h]),t.useEffect(()=>{e.initialInput&&k(e.initialInput)},[]),{data:T,isFetching:w,isStreaming:g,id:c.current,send:F,cancel:h}};d.useEventStream=D,d.useStream=O,Object.defineProperty(d,Symbol.toStringTag,{value:"Module"})});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laravel/stream-react",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Laravel streaming hooks for React",
   "keywords": [
     "laravel",
@@ -47,10 +47,11 @@
     "@vitejs/plugin-vue": "^5.0.0",
     "eslint": "^9.0.0",
     "jsdom": "^26.0.0",
+    "msw": "^2.8.2",
     "prettier": "^3.5.3",
     "typescript": "^5.3.0",
-    "vite-plugin-dts": "^4.5.3",
     "vite": "^5.1.0",
+    "vite-plugin-dts": "^4.5.3",
     "vitest": "^3.1.1"
   },
   "peerDependencies": {