@laravel/stream-vue 0.2.0 → 0.3.0

package/README.md

@@ -7,7 +7,7 @@
 <a href="https://www.npmjs.com/package/@laravel/stream-vue"><img src="https://img.shields.io/npm/l/@laravel/stream-vue" alt="License"></a>
 </p>
 
-Easily consume [Server-Sent Events (SSE)](https://laravel.com/docs/responses#event-streams) in your Vue application.
+Easily consume streams in your Vue application.
 
 ## Installation
 
@@ -15,7 +15,149 @@ Easily consume [Server-Sent Events (SSE)](https://laravel.com/docs/responses#eve
 npm install @laravel/stream-vue
 ```
 
-## Usage
+## Streaming Responses
+
+> [!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 Vue application.
+
+Provide your stream URL and the hook will automatically update `data` with the concatenated response as data is returned from your server:
+
+```vue
+<script setup lang="ts">
+import { useStream } from "@laravel/stream-vue";
+
+const { data, isFetching, isStreaming, send } = useStream("chat");
+
+const sendMessage = () => {
+    send({
+        message: `Current timestamp: ${Date.now()}`,
+    });
+};
+</script>
+
+<template>
+    <div>
+        <div>{{ data }}</div>
+        <div v-if="isFetching">Connecting...</div>
+        <div v-if="isStreaming">Generating...</div>
+        <button @click="sendMessage">Send Message</button>
+    </div>
+</template>
+```
+
+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:
+
+```vue
+<script setup lang="ts">
+import { useStream } from "@laravel/stream-vue";
+
+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,
+});
+</script>
+
+<template>
+    <div>{{ data }}</div>
+</template>
+```
+
+`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:
+
+```vue
+<script setup lang="ts">
+import { useStream } from "@laravel/stream-vue";
+
+const { data } = useStream("chat", {
+    initialInput: {
+        message: "Introduce yourself.",
+    },
+});
+</script>
+
+<template>
+    <div>{{ data }}</div>
+</template>
+```
+
+To cancel a stream manually, you may use the `cancel` method returned from the hook:
+
+```vue
+<script setup lang="ts">
+import { useStream } from "@laravel/stream-vue";
+
+const { data, cancel } = useStream("chat");
+</script>
+
+<template>
+    <div>
+        <div>{{ data }}</div>
+        <button @click="cancel">Cancel</button>
+    </div>
+</template>
+```
+
+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`:
+
+```vue
+<!-- App.vue -->
+<script setup lang="ts">
+import { useStream } from "@laravel/stream-vue";
+import StreamStatus from "./StreamStatus.vue";
+
+const { data, id } = useStream("chat");
+</script>
+
+<template>
+    <div>
+        <div>{{ data }}</div>
+        <StreamStatus :id="id" />
+    </div>
+</template>
+```
+
+```vue
+<!-- StreamStatus.vue -->
+<script setup lang="ts">
+import { useStream } from "@laravel/stream-vue";
+
+const props = defineProps<{
+    id: string;
+}>();
+
+const { isFetching, isStreaming } = useStream("chat", { id: props.id });
+</script>
+
+<template>
+    <div>
+        <div v-if="isFetching">Connecting...</div>
+        <div v-if="isStreaming">Generating...</div>
+    </div>
+</template>
+```
+
+## Event Streams (SSE)
+
+The `useEventStream` hook allows you to seamlessly consume [Server-Sent Events (SSE)](https://laravel.com/docs/responses#event-streams) in your Vue application.
 
 Provide your stream URL and the hook will automatically update the `message` with the concatenated response as messages are returned from your server:
 
@@ -27,7 +169,7 @@ const { message } = useEventStream("/stream");
 </script>
 
 <template>
-  <div>{{ message }}</div>
+    <div>{{ message }}</div>
 </template>
 ```
 
@@ -41,14 +183,33 @@ const { messageParts } = useEventStream("/stream");
 </script>
 
 <template>
-  <ul>
-    <li v-for="message in messageParts">
-      {{ message }}
-    </li>
-  </ul>
+    <ul>
+        <li v-for="message in messageParts">
+            {{ message }}
+        </li>
+    </ul>
 </template>
 ```
 
+If you'd like to listen to multiple events:
+
+```vue
+<script setup lang="ts">
+import { useEventStream } from "@laravel/stream-vue";
+
+useEventStream("/stream", {
+    eventName: ["update", "create"],
+    onMessage: (event) => {
+        if (event.type === "update") {
+            // Handle update
+        } else {
+            // Handle create
+        }
+    },
+});
+</script>
+```
+
 The second parameter is an options object where all properties are optional (defaults are shown below):
 
 ```vue
@@ -56,18 +217,19 @@ The second parameter is an options object where all properties are optional (def
 import { useEventStream } from "@laravel/stream-vue";
 
 const { message } = useEventStream("/stream", {
-  event: "update",
-  onMessage: (message) => {
-    //
-  },
-  onError: (error) => {
-    //
-  },
-  onComplete: () => {
-    //
-  },
-  endSignal: "</stream>",
-  glue: " ",
+    event: "update",
+    onMessage: (message) => {
+        //
+    },
+    onError: (error) => {
+        //
+    },
+    onComplete: () => {
+        //
+    },
+    endSignal: "</stream>",
+    glue: " ",
+    replace: false,
 });
 </script>
 ```
@@ -82,14 +244,14 @@ import { onMounted } from "vue";
 const { message, close } = useEventStream("/stream");
 
 onMounted(() => {
-  setTimeout(() => {
-    close();
-  }, 3000);
+    setTimeout(() => {
+        close();
+    }, 3000);
 });
 </script>
 
 <template>
-  <div>{{ message }}</div>
+    <div>{{ message }}</div>
 </template>
 ```
 
@@ -103,14 +265,14 @@ import { onMounted } from "vue";
 const { message, clearMessage } = useEventStream("/stream");
 
 onMounted(() => {
-  setTimeout(() => {
-    clearMessage();
-  }, 3000);
+    setTimeout(() => {
+        clearMessage();
+    }, 3000);
 });
 </script>
 
 <template>
-  <div>{{ message }}</div>
+    <div>{{ message }}</div>
 </template>
 ```
 

package/dist/index.d.ts

@@ -1,21 +1,34 @@
 import { Ref } from 'vue';
 
-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: Readonly<Ref<string>>;
     messageParts: Readonly<Ref<readonly 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;
+};
+
 /**
  * Composable for handling server-sent events (SSE) streams
  *
@@ -26,6 +39,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: Readonly<Ref<string, string>>;
+    isFetching: Readonly<Ref<boolean, boolean>>;
+    isStreaming: Readonly<Ref<boolean, boolean>>;
+    id: string;
+    send: (body: Record<string, any>) => void;
+    cancel: () => void;
+};
 
 export { }

package/dist/index.es.js

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

package/dist/index.umd.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@laravel/stream-vue",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Laravel streaming hooks for Vue",
   "keywords": [
     "laravel",
@@ -44,6 +44,7 @@
     "@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": "^5.4.19",
@@ -53,6 +54,9 @@
   "peerDependencies": {
     "vue": "^3.0.0"
   },
+  "dependencies": {
+    "nanoid": "^5.1.5"
+  },
   "scripts": {
     "build": "vite build",
     "lint": "eslint --config eslint.config.mjs \"src/**/*.ts\"",