use-next-sse 0.2.1 → 0.2.3

package/README.md

@@ -69,3 +69,70 @@ export default function Home() {
 ```
 
 This example demonstrates a simple counter that updates every second using Server-Sent Events. The server sends updates for 10 seconds before closing the connection.
+
+### Destructor in `createSSEHandler`
+
+When using the `createSSEHandler` function in the `use-next-sse` library, it is important to understand the role of the destructor. The destructor is a cleanup function that is called when the SSE connection is closed. This allows you to perform any necessary cleanup tasks, such as closing database connections, stopping intervals, or clearing resources.
+
+#### Example Usage
+
+```typescript
+import { createSSEHandler } from 'use-next-sse';
+
+const handler = createSSEHandler((send, close) => {
+  // Your SSE logic here
+
+  // Return a destructor function
+  return () => {
+    // Perform cleanup tasks here
+    console.log('SSE connection closed, performing cleanup');
+  };
+});
+
+export default handler;
+```
+
+#### Global Example
+
+This Destructor will be called even though the handler callback is not called yet.
+
+```typescript
+import { createSSEHandler } from 'use-next-sse';
+
+const handler = createSSEHandler(
+  (send, close) => {
+    // Your SSE logic here
+  },
+  {
+    onClose: () => {
+      console.log('SSE connection has been closed and cleaned up.');
+      // Perform additional cleanup tasks here
+    },
+  }
+);
+
+export default handler;
+```
+
+#### Context Example
+
+This Destructor will be called if the SSECallback call is not done yet.
+
+```typescript
+import { createSSEHandler } from 'use-next-sse';
+
+const handler = createSSEHandler(async(send, close, { onClose }) => {
+  // Your SSE logic here
+
+  onClose(() => {
+    console.log('SSE connection closed, performing cleanup.');
+    // Perform additional cleanup tasks here
+  });
+
+
+  // long running task
+  await new Promise((resolve) => setTimeout(resolve, 5000));
+});
+
+export default handler;
+```

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) | Promise<() => void> | (() => Promise<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.
  *
@@ -56,6 +77,8 @@ context: {
    });
 ```
  *
+ * @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,
@@ -66,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

@@ -24,6 +24,8 @@ exports.createSSEHandler = void 0;
    });
 ```
  *
+ * @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,
@@ -34,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({
-            async start(controller) {
+            async start(cntrl) {
+                controller = cntrl;
                 const send = (data, eventName) => {
                     if (!isClosed) {
                         let message = `id: ${messageId}\n`;
@@ -49,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 = await 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, {
@@ -81,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) | Promise<() => void> | (() => Promise<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.
  *
@@ -56,6 +77,8 @@ context: {
    });
 ```
  *
+ * @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,
@@ -66,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

@@ -21,6 +21,8 @@
    });
 ```
  *
+ * @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,
@@ -31,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({
-            async start(controller) {
+            async start(cntrl) {
+                controller = cntrl;
                 const send = (data, eventName) => {
                     if (!isClosed) {
                         let message = `id: ${messageId}\n`;
@@ -46,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 = await 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, {
@@ -77,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.1",
+  "version": "0.2.3",
   "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",
@@ -33,7 +33,7 @@
   "author": "Alexander Kasten",
   "license": "MIT",
   "peerDependencies": {
-    "next": ">13.0.0",
+    "next": ">=13.5.9 >=14.2.25 >=15.2.3",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0"
   },