use-next-sse 0.2.0 → 0.2.2

package/README.md

@@ -1,4 +1,6 @@
 # use-next-sse
+[![Node.js Package](https://github.com/alexanderkasten/use-next-sse/actions/workflows/npm-publish.yml/badge.svg)](https://github.com/alexanderkasten/use-next-sse/actions/workflows/npm-publish.yml)
+
 
 use-next-sse is a lightweight and easy-to-use React hook library for implementing Server-Sent Events (SSE) in Next.js applications, enabling real-time, unidirectional data streaming from server to client.
 
@@ -18,7 +20,7 @@ Create a new file `app/api/sse/route.ts` with the following content:
 import { createSSEHandler } from 'use-next-sse';
 
 export const dynamic = 'force-dynamic';
-export const GET = createSSEHandler(async (send, close) => {
+export const GET = createSSEHandler((send, close) => {
   let count = 0;
   const interval = setInterval(() => {
     send({ count: count++ }, 'counter');

package/dist/cjs/server/sse-server.d.ts

@@ -1,4 +1,4 @@
-import { NextRequest } from 'next/server';
+import type { NextRequest } from 'next/server';
 /**
  * A function that sends data to the client.
  * @param data - The data to send to the client.
@@ -9,12 +9,22 @@ import { NextRequest } from 'next/server';
  * send({ message: 'test' }, 'testEvent');
  */
 type SendFunction = (data: any, eventName?: string) => void;
+/**
+ * A function that cleans up resources when the connection is closed.
+ * @returns void | Promise<void>
+ * @example
+ * return () => {
+ *   console.log('Cleanup');
+ * };
+ */
+type Destructor = (() => void) | Promise<() => void> | (() => Promise<void>);
 /**
  * A function that handles the Server-Sent Events (SSE) connection.
  * @param send - A function to send data to the client.
  * @param close - A function to close the SSE connection.
  * @returns void | Promise<void> | (() => void)
  * The callback can return a cleanup function that will be called when the connection is closed.
+ * **HINT:** See also {@link Destructor}, the createSSEHandler {@link SSEOptions} and {@link SSECallback} context `onClose`.
  */
 type SSECallback = (send: SendFunction, 
 /**
@@ -27,12 +37,23 @@ close: () => void,
 /**
  * An object containing the last event ID received by the client. Not null if the client has been reconnected.
  * @property lastEventId - The last event ID from the client.
+ * @property onClose - A function to set a cleanup function that will be called when the connection is closed. If the cleanup function is already set, a warning will be logged. The cleanup function set by the `onClose` function will be called even if the cleanup function returned by the callback is not called.
  * @example
  * { lastEventId: '12345' }
  */
 context: {
     lastEventId: string | null;
-}) => void | Promise<void> | (() => void);
+    onClose: (destructor: Destructor) => void;
+}) => void | Promise<void> | Destructor;
+/**
+ * An optional object to configure the Server-Sent Events (SSE) handler.
+ * @property onClose - A function that will be called when the connection is closed even if the SSECallback has not been called yet.
+ * @example
+ * { onClose: () => console.log('SSE connection has been closed and cleaned up.') }
+ */
+type SSEOptions = {
+    onClose?: Destructor;
+};
 /**
  * Creates a Server-Sent Events (SSE) handler for Next.js.
  *
@@ -42,6 +63,22 @@ context: {
  *   - `context`: An object containing the last event ID received by the client. Not null if the client has been reconnected.
  *   The callback can return a cleanup function that will be called when the connection is closed.
  *
+ * **HINT:**
+ * Be sure to **NOT** await long running operations in the callback, as this will block the response from being sent initially to the client. Instead wrap your long running operations in a async function to allow the response to be sent to the client first.
+ *
+ * @example
+  ```
+   export const GET = createSSEHandler((send, close) => {
+      const asyncStuff = async () => {
+        // async
+      };
+
+      asyncStuff();
+   });
+```
+ *
+ * @param options - An optional object to configure the handler. {@link SSEOptions}
+ *  - `onClose`: A function that will be called when the connection is closed even if the SSECallback has not been called yet.
  * @returns A function that handles the SSE request. This function takes a `NextRequest` object as an argument.
  *
  * The returned function creates a `ReadableStream` to handle the SSE connection. It sets up the `send` and `close` functions,
@@ -52,5 +89,5 @@ context: {
  * - `Cache-Control`: `no-cache, no-transform`
  * - `Connection`: `keep-alive`
  */
-export declare function createSSEHandler(callback: SSECallback): (request: NextRequest) => Promise<Response>;
+export declare function createSSEHandler(callback: SSECallback, options?: SSEOptions): (request: NextRequest) => Promise<Response>;
 export {};

package/dist/cjs/server/sse-server.js

@@ -10,6 +10,22 @@ exports.createSSEHandler = void 0;
  *   - `context`: An object containing the last event ID received by the client. Not null if the client has been reconnected.
  *   The callback can return a cleanup function that will be called when the connection is closed.
  *
+ * **HINT:**
+ * Be sure to **NOT** await long running operations in the callback, as this will block the response from being sent initially to the client. Instead wrap your long running operations in a async function to allow the response to be sent to the client first.
+ *
+ * @example
+  ```
+   export const GET = createSSEHandler((send, close) => {
+      const asyncStuff = async () => {
+        // async
+      };
+
+      asyncStuff();
+   });
+```
+ *
+ * @param options - An optional object to configure the handler. {@link SSEOptions}
+ *  - `onClose`: A function that will be called when the connection is closed even if the SSECallback has not been called yet.
  * @returns A function that handles the SSE request. This function takes a `NextRequest` object as an argument.
  *
  * The returned function creates a `ReadableStream` to handle the SSE connection. It sets up the `send` and `close` functions,
@@ -20,14 +36,40 @@ exports.createSSEHandler = void 0;
  * - `Cache-Control`: `no-cache, no-transform`
  * - `Connection`: `keep-alive`
  */
-function createSSEHandler(callback) {
+function createSSEHandler(callback, options) {
     return async function (request) {
         const encoder = new TextEncoder();
         let isClosed = false;
-        let cleanup;
+        let cleanup = options === null || options === void 0 ? void 0 : options.onClose;
+        let cleanupSetBy = (options === null || options === void 0 ? void 0 : options.onClose) ? '`onClose` through createSSEHandler options' : '';
         let messageId = 0;
+        let controller;
+        function onClose(destructor) {
+            if (cleanup != null) {
+                if (!isClosed) {
+                    logAlreadySetWarning(cleanupSetBy);
+                }
+            }
+            else {
+                cleanup = destructor;
+                cleanupSetBy = '`onClose` through SSECallback context';
+            }
+        }
+        function close() {
+            if (!isClosed) {
+                isClosed = true;
+                controller === null || controller === void 0 ? void 0 : controller.close();
+                if (typeof cleanup === 'function') {
+                    cleanup();
+                }
+            }
+        }
+        request.signal.addEventListener('abort', () => {
+            close();
+        });
         const stream = new ReadableStream({
-            start(controller) {
+            async start(cntrl) {
+                controller = cntrl;
                 const send = (data, eventName) => {
                     if (!isClosed) {
                         let message = `id: ${messageId}\n`;
@@ -35,26 +77,21 @@ function createSSEHandler(callback) {
                             message += `event: ${eventName}\n`;
                         }
                         message += `data: ${JSON.stringify(data)}\n\n`;
-                        controller.enqueue(encoder.encode(message));
+                        cntrl.enqueue(encoder.encode(message));
                         messageId++;
                     }
                 };
-                function close() {
-                    if (!isClosed) {
-                        isClosed = true;
-                        controller.close();
-                        if (typeof cleanup === 'function') {
-                            cleanup();
+                const result = await callback(send, close, { lastEventId: request.headers.get('Last-Event-ID'), onClose });
+                if (typeof result === 'function') {
+                    if (cleanup != null) {
+                        if (!isClosed) {
+                            logAlreadySetWarning(cleanupSetBy);
                         }
                     }
+                    else {
+                        cleanup = result;
+                    }
                 }
-                const result = callback(send, close, { lastEventId: request.headers.get('Last-Event-ID') });
-                if (typeof result === 'function') {
-                    cleanup = result;
-                }
-                request.signal.addEventListener('abort', () => {
-                    close();
-                });
             },
         });
         return new Response(stream, {
@@ -67,3 +104,10 @@ function createSSEHandler(callback) {
     };
 }
 exports.createSSEHandler = createSSEHandler;
+let warningLogged = false;
+function logAlreadySetWarning(cleanupSetBy) {
+    if (!warningLogged) {
+        console.warn(`[use-next-sse:createSSEHandler]:\tCleanup function already set by ${cleanupSetBy}. Ignoring new cleanup function.`);
+        warningLogged = true;
+    }
+}

package/dist/server/sse-server.d.ts

@@ -1,4 +1,4 @@
-import { NextRequest } from 'next/server';
+import type { NextRequest } from 'next/server';
 /**
  * A function that sends data to the client.
  * @param data - The data to send to the client.
@@ -9,12 +9,22 @@ import { NextRequest } from 'next/server';
  * send({ message: 'test' }, 'testEvent');
  */
 type SendFunction = (data: any, eventName?: string) => void;
+/**
+ * A function that cleans up resources when the connection is closed.
+ * @returns void | Promise<void>
+ * @example
+ * return () => {
+ *   console.log('Cleanup');
+ * };
+ */
+type Destructor = (() => void) | Promise<() => void> | (() => Promise<void>);
 /**
  * A function that handles the Server-Sent Events (SSE) connection.
  * @param send - A function to send data to the client.
  * @param close - A function to close the SSE connection.
  * @returns void | Promise<void> | (() => void)
  * The callback can return a cleanup function that will be called when the connection is closed.
+ * **HINT:** See also {@link Destructor}, the createSSEHandler {@link SSEOptions} and {@link SSECallback} context `onClose`.
  */
 type SSECallback = (send: SendFunction, 
 /**
@@ -27,12 +37,23 @@ close: () => void,
 /**
  * An object containing the last event ID received by the client. Not null if the client has been reconnected.
  * @property lastEventId - The last event ID from the client.
+ * @property onClose - A function to set a cleanup function that will be called when the connection is closed. If the cleanup function is already set, a warning will be logged. The cleanup function set by the `onClose` function will be called even if the cleanup function returned by the callback is not called.
  * @example
  * { lastEventId: '12345' }
  */
 context: {
     lastEventId: string | null;
-}) => void | Promise<void> | (() => void);
+    onClose: (destructor: Destructor) => void;
+}) => void | Promise<void> | Destructor;
+/**
+ * An optional object to configure the Server-Sent Events (SSE) handler.
+ * @property onClose - A function that will be called when the connection is closed even if the SSECallback has not been called yet.
+ * @example
+ * { onClose: () => console.log('SSE connection has been closed and cleaned up.') }
+ */
+type SSEOptions = {
+    onClose?: Destructor;
+};
 /**
  * Creates a Server-Sent Events (SSE) handler for Next.js.
  *
@@ -42,6 +63,22 @@ context: {
  *   - `context`: An object containing the last event ID received by the client. Not null if the client has been reconnected.
  *   The callback can return a cleanup function that will be called when the connection is closed.
  *
+ * **HINT:**
+ * Be sure to **NOT** await long running operations in the callback, as this will block the response from being sent initially to the client. Instead wrap your long running operations in a async function to allow the response to be sent to the client first.
+ *
+ * @example
+  ```
+   export const GET = createSSEHandler((send, close) => {
+      const asyncStuff = async () => {
+        // async
+      };
+
+      asyncStuff();
+   });
+```
+ *
+ * @param options - An optional object to configure the handler. {@link SSEOptions}
+ *  - `onClose`: A function that will be called when the connection is closed even if the SSECallback has not been called yet.
  * @returns A function that handles the SSE request. This function takes a `NextRequest` object as an argument.
  *
  * The returned function creates a `ReadableStream` to handle the SSE connection. It sets up the `send` and `close` functions,
@@ -52,5 +89,5 @@ context: {
  * - `Cache-Control`: `no-cache, no-transform`
  * - `Connection`: `keep-alive`
  */
-export declare function createSSEHandler(callback: SSECallback): (request: NextRequest) => Promise<Response>;
+export declare function createSSEHandler(callback: SSECallback, options?: SSEOptions): (request: NextRequest) => Promise<Response>;
 export {};

package/dist/server/sse-server.js

@@ -7,6 +7,22 @@
  *   - `context`: An object containing the last event ID received by the client. Not null if the client has been reconnected.
  *   The callback can return a cleanup function that will be called when the connection is closed.
  *
+ * **HINT:**
+ * Be sure to **NOT** await long running operations in the callback, as this will block the response from being sent initially to the client. Instead wrap your long running operations in a async function to allow the response to be sent to the client first.
+ *
+ * @example
+  ```
+   export const GET = createSSEHandler((send, close) => {
+      const asyncStuff = async () => {
+        // async
+      };
+
+      asyncStuff();
+   });
+```
+ *
+ * @param options - An optional object to configure the handler. {@link SSEOptions}
+ *  - `onClose`: A function that will be called when the connection is closed even if the SSECallback has not been called yet.
  * @returns A function that handles the SSE request. This function takes a `NextRequest` object as an argument.
  *
  * The returned function creates a `ReadableStream` to handle the SSE connection. It sets up the `send` and `close` functions,
@@ -17,14 +33,40 @@
  * - `Cache-Control`: `no-cache, no-transform`
  * - `Connection`: `keep-alive`
  */
-export function createSSEHandler(callback) {
+export function createSSEHandler(callback, options) {
     return async function (request) {
         const encoder = new TextEncoder();
         let isClosed = false;
-        let cleanup;
+        let cleanup = options === null || options === void 0 ? void 0 : options.onClose;
+        let cleanupSetBy = (options === null || options === void 0 ? void 0 : options.onClose) ? '`onClose` through createSSEHandler options' : '';
         let messageId = 0;
+        let controller;
+        function onClose(destructor) {
+            if (cleanup != null) {
+                if (!isClosed) {
+                    logAlreadySetWarning(cleanupSetBy);
+                }
+            }
+            else {
+                cleanup = destructor;
+                cleanupSetBy = '`onClose` through SSECallback context';
+            }
+        }
+        function close() {
+            if (!isClosed) {
+                isClosed = true;
+                controller === null || controller === void 0 ? void 0 : controller.close();
+                if (typeof cleanup === 'function') {
+                    cleanup();
+                }
+            }
+        }
+        request.signal.addEventListener('abort', () => {
+            close();
+        });
         const stream = new ReadableStream({
-            start(controller) {
+            async start(cntrl) {
+                controller = cntrl;
                 const send = (data, eventName) => {
                     if (!isClosed) {
                         let message = `id: ${messageId}\n`;
@@ -32,26 +74,21 @@ export function createSSEHandler(callback) {
                             message += `event: ${eventName}\n`;
                         }
                         message += `data: ${JSON.stringify(data)}\n\n`;
-                        controller.enqueue(encoder.encode(message));
+                        cntrl.enqueue(encoder.encode(message));
                         messageId++;
                     }
                 };
-                function close() {
-                    if (!isClosed) {
-                        isClosed = true;
-                        controller.close();
-                        if (typeof cleanup === 'function') {
-                            cleanup();
+                const result = await callback(send, close, { lastEventId: request.headers.get('Last-Event-ID'), onClose });
+                if (typeof result === 'function') {
+                    if (cleanup != null) {
+                        if (!isClosed) {
+                            logAlreadySetWarning(cleanupSetBy);
                         }
                     }
+                    else {
+                        cleanup = result;
+                    }
                 }
-                const result = callback(send, close, { lastEventId: request.headers.get('Last-Event-ID') });
-                if (typeof result === 'function') {
-                    cleanup = result;
-                }
-                request.signal.addEventListener('abort', () => {
-                    close();
-                });
             },
         });
         return new Response(stream, {
@@ -63,3 +100,10 @@ export function createSSEHandler(callback) {
         });
     };
 }
+let warningLogged = false;
+function logAlreadySetWarning(cleanupSetBy) {
+    if (!warningLogged) {
+        console.warn(`[use-next-sse:createSSEHandler]:\tCleanup function already set by ${cleanupSetBy}. Ignoring new cleanup function.`);
+        warningLogged = true;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "use-next-sse",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "A lightweight Server-Sent Events (SSE) library for Next.js, enabling real-time, unidirectional data streaming from server to client",
   "main": "dist/cjs/index.js",
   "types": "dist/index.d.ts",