@laravel/stream-react 0.2.1 → 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,9 +15,140 @@ 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";

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,25 @@ 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;
+    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 +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, replace, 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,48 +1,169 @@
-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 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 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 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;
       }
-      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);
+      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);
     },
-    [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();
+    [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 j(() => (t(), e.current = new EventSource(d), c.forEach((r) => {
+  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: 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;
-    (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
+    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 {
-  w as useEventStream
+  J as useEventStream,
+  K 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(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.1",
+  "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": {