@laravel/stream-react 0.2.1 → 0.3.1

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,9 +15,175 @@ 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>
+    );
+}
+```
+
+The `useJsonStream` hook is identical to the `useStream` hook except that it will attempt to parse the data as JSON once it has finished streaming:
+
+```tsx
+import { useJsonStream } from "@laravel/stream-react";
+
+type User = {
+    id: number;
+    name: string;
+    email: string;
+};
+
+function App() {
+    const { data, send } = useJsonStream<{ users: User[] }>("users");
+
+    const loadUsers = () => {
+        send({
+            query: "taylor",
+        });
+    };
+
+    return (
+        <div>
+            <ul>
+                {data?.users.map((user) => (
+                    <li>
+                        {user.id}: {user.name}
+                    </li>
+                ))}
+            </ul>
+            <button onClick={loadUsers}>Load Users</button>
+        </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";

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-declare type Options = {
+declare type EventStreamOptions = {
     eventName?: string | string[];
     endSignal?: string;
     glue?: string;
@@ -8,13 +8,26 @@ declare type Options = {
     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;
+    json?: boolean;
+    onResponse?: (response: Response) => void;
+    onData?: (data: string) => void;
+    onCancel?: () => void;
+    onFinish?: () => void;
+    onError?: (error: Error) => void;
+};
+
 /**
  * Hook for handling server-sent event (SSE) streams
  *
@@ -25,6 +38,28 @@ declare type StreamResult = {
  *
  * @returns StreamResult object containing the accumulated response, close, and reset functions
  */
-export declare const useEventStream: (url: string, { eventName, endSignal, glue, replace, onMessage, onComplete, onError, }?: Options) => StreamResult;
+export declare const useEventStream: (url: string, { eventName, endSignal, glue, replace, onMessage, onComplete, onError, }?: EventStreamOptions) => EventStreamResult;
+
+export declare const useJsonStream: <TJsonData = null>(url: string, options?: Omit<StreamOptions, "json">) => {
+    isFetching: boolean;
+    isStreaming: boolean;
+    id: string;
+    send: (body: Record<string, any>) => void;
+    cancel: () => void;
+    clearData: () => void;
+    data: TJsonData | null;
+    rawData: string;
+};
+
+export declare const useStream: <TJsonData = null>(url: string, options?: StreamOptions) => {
+    data: string;
+    jsonData: TJsonData | null;
+    isFetching: boolean;
+    isStreaming: boolean;
+    id: string;
+    send: (body: Record<string, any>) => void;
+    cancel: () => void;
+    clearData: () => void;
+};
 
 export { }

package/dist/index.es.js

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

package/dist/index.umd.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laravel/stream-react",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "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": {