better-sse 0.14.0 → 0.15.0

package/build/index.mjs

@@ -1,23 +1,51 @@
 // src/Session.ts
 import {
+  IncomingMessage as Http1ServerRequest,
   ServerResponse as Http1ServerResponse
-} from "http";
+} from "node:http";
+import { Http2ServerRequest, Http2ServerResponse } from "node:http2";
+import { setImmediate } from "node:timers";
 
-// src/lib/serialize.ts
-var serialize = (data) => JSON.stringify(data);
+// src/lib/createPushFromIterable.ts
+var createPushFromIterable = (push) => async (iterable, options = {}) => {
+  const { eventName = "iteration" } = options;
+  for await (const data of iterable) {
+    push(data, eventName);
+  }
+};
 
-// src/lib/sanitize.ts
-var newlineVariantsRegex = /(\r\n|\r|\n)/g;
-var newlineTrailingRegex = /\n+$/g;
-var sanitize = (text) => {
-  let sanitized = text;
-  sanitized = sanitized.replace(newlineVariantsRegex, "\n");
-  sanitized = sanitized.replace(newlineTrailingRegex, "");
-  return sanitized;
+// src/lib/createPushFromStream.ts
+import { Readable as NodeReadableStream } from "node:stream";
+var createPushFromStream = (push) => async (stream, options = {}) => {
+  const { eventName = "stream" } = options;
+  if (stream instanceof NodeReadableStream) {
+    return await new Promise((resolve, reject) => {
+      stream.on("data", (chunk) => {
+        let data;
+        if (Buffer.isBuffer(chunk)) {
+          data = chunk.toString();
+        } else {
+          data = chunk;
+        }
+        push(data, eventName);
+      });
+      stream.once("end", () => resolve(true));
+      stream.once("close", () => resolve(true));
+      stream.once("error", (err) => reject(err));
+    });
+  }
+  for await (const chunk of stream) {
+    if (Buffer.isBuffer(chunk)) {
+      push(chunk.toString(), eventName);
+    } else {
+      push(chunk, eventName);
+    }
+  }
+  return true;
 };
 
 // src/lib/generateId.ts
-import { randomUUID, randomBytes } from "crypto";
+import { randomBytes, randomUUID } from "node:crypto";
 var generateId;
 if (randomUUID) {
   generateId = () => randomUUID();
@@ -25,32 +53,18 @@ if (randomUUID) {
   generateId = () => randomBytes(4).toString("hex");
 }
 
-// src/lib/createPushFromStream.ts
-var createPushFromStream = (push) => async (stream, options = {}) => {
-  const { eventName = "stream" } = options;
-  return await new Promise((resolve, reject) => {
-    stream.on("data", (chunk) => {
-      let data;
-      if (Buffer.isBuffer(chunk)) {
-        data = chunk.toString();
-      } else {
-        data = chunk;
-      }
-      push(data, eventName);
-    });
-    stream.once("end", () => resolve(true));
-    stream.once("close", () => resolve(true));
-    stream.once("error", (err) => reject(err));
-  });
+// src/lib/sanitize.ts
+var newlineVariantsRegex = /(\r\n|\r|\n)/g;
+var newlineTrailingRegex = /\n+$/g;
+var sanitize = (text) => {
+  let sanitized = text;
+  sanitized = sanitized.replace(newlineVariantsRegex, "\n");
+  sanitized = sanitized.replace(newlineTrailingRegex, "");
+  return sanitized;
 };
 
-// src/lib/createPushFromIterable.ts
-var createPushFromIterable = (push) => async (iterable, options = {}) => {
-  const { eventName = "iteration" } = options;
-  for await (const data of iterable) {
-    push(data, eventName);
-  }
-};
+// src/lib/serialize.ts
+var serialize = (data) => JSON.stringify(data);
 
 // src/EventBuffer.ts
 var EventBuffer = class {
@@ -184,8 +198,180 @@ var EventBuffer = class {
   read = () => this.buffer;
 };
 
+// src/lib/applyHeaders.ts
+var applyHeaders = (from, to) => {
+  const fromMap = from instanceof Headers ? Object.fromEntries(from) : from;
+  for (const [key, value] of Object.entries(fromMap)) {
+    if (Array.isArray(value)) {
+      to.delete(key);
+      for (const item of value) {
+        to.append(key, item);
+      }
+    } else if (value === void 0) {
+      to.delete(key);
+    } else {
+      to.set(key, value);
+    }
+  }
+};
+
+// src/lib/constants.ts
+var DEFAULT_REQUEST_HOST = "localhost";
+var DEFAULT_REQUEST_METHOD = "GET";
+var DEFAULT_RESPONSE_CODE = 200;
+var DEFAULT_RESPONSE_HEADERS = {
+  "Content-Type": "text/event-stream",
+  "Cache-Control": "private, no-cache, no-store, no-transform, must-revalidate, max-age=0",
+  Connection: "keep-alive",
+  Pragma: "no-cache",
+  "X-Accel-Buffering": "no"
+};
+
+// src/adapters/FetchConnection.ts
+var FetchConnection = class _FetchConnection {
+  static encoder = new TextEncoder();
+  writer;
+  url;
+  request;
+  response;
+  constructor(request, response, options = {}) {
+    this.url = new URL(request.url);
+    this.request = request;
+    const { readable, writable } = new TransformStream();
+    this.writer = writable.getWriter();
+    this.response = new Response(readable, {
+      status: options.statusCode ?? response?.status ?? DEFAULT_RESPONSE_CODE,
+      headers: DEFAULT_RESPONSE_HEADERS
+    });
+    if (response) {
+      applyHeaders(response.headers, this.response.headers);
+    }
+  }
+  sendHead = () => {
+  };
+  sendChunk = (chunk) => {
+    const encoded = _FetchConnection.encoder.encode(chunk);
+    this.writer.write(encoded);
+  };
+  cleanup = () => {
+    this.writer.close();
+  };
+};
+
+// src/adapters/NodeHttp1Connection.ts
+var NodeHttp1Connection = class {
+  constructor(req, res, options = {}) {
+    this.req = req;
+    this.res = res;
+    this.url = new URL(
+      `http://${req.headers.host ?? DEFAULT_REQUEST_HOST}${req.url}`
+    );
+    this.controller = new AbortController();
+    req.once("close", this.onClose);
+    res.once("close", this.onClose);
+    this.request = new Request(this.url, {
+      method: req.method ?? DEFAULT_REQUEST_METHOD,
+      signal: this.controller.signal
+    });
+    applyHeaders(req.headers, this.request.headers);
+    this.response = new Response(null, {
+      status: options.statusCode ?? res.statusCode ?? DEFAULT_RESPONSE_CODE,
+      headers: DEFAULT_RESPONSE_HEADERS
+    });
+    if (res) {
+      applyHeaders(
+        res.getHeaders(),
+        this.response.headers
+      );
+    }
+  }
+  controller;
+  url;
+  request;
+  response;
+  onClose = () => {
+    this.controller.abort();
+  };
+  sendHead = () => {
+    this.res.writeHead(
+      this.response.status,
+      Object.fromEntries(this.response.headers)
+    );
+  };
+  sendChunk = (chunk) => {
+    this.res.write(chunk);
+  };
+  cleanup = () => {
+    this.req.removeListener("close", this.onClose);
+    this.res.removeListener("close", this.onClose);
+  };
+};
+
+// src/adapters/NodeHttp2CompatConnection.ts
+var NodeHttp2CompatConnection = class {
+  constructor(req, res, options = {}) {
+    this.req = req;
+    this.res = res;
+    this.url = new URL(
+      `http://${req.headers.host ?? DEFAULT_REQUEST_HOST}${req.url}`
+    );
+    this.controller = new AbortController();
+    req.once("close", this.onClose);
+    res.once("close", this.onClose);
+    this.request = new Request(this.url, {
+      method: req.method ?? DEFAULT_REQUEST_METHOD,
+      signal: this.controller.signal
+    });
+    const allowedHeaders = { ...req.headers };
+    for (const header of Object.keys(allowedHeaders)) {
+      if (header.startsWith(":")) {
+        delete allowedHeaders[header];
+      }
+    }
+    applyHeaders(allowedHeaders, this.request.headers);
+    this.response = new Response(null, {
+      status: options.statusCode ?? res.statusCode ?? DEFAULT_RESPONSE_CODE,
+      headers: DEFAULT_RESPONSE_HEADERS
+    });
+    if (res) {
+      applyHeaders(
+        res.getHeaders(),
+        this.response.headers
+      );
+    }
+  }
+  controller;
+  url;
+  request;
+  response;
+  onClose = () => {
+    this.controller.abort();
+  };
+  sendHead = () => {
+    this.res.writeHead(
+      this.response.status,
+      Object.fromEntries(this.response.headers)
+    );
+  };
+  sendChunk = (chunk) => {
+    this.res.write(chunk);
+  };
+  cleanup = () => {
+    this.req.removeListener("close", this.onClose);
+    this.res.removeListener("close", this.onClose);
+  };
+};
+
+// src/lib/SseError.ts
+var SseError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.message = `better-sse: ${message}`;
+  }
+};
+
 // src/lib/TypedEmitter.ts
-import { EventEmitter } from "events";
+import { EventEmitter } from "node:events";
 var TypedEmitter = class extends EventEmitter {
   addListener(event, listener) {
     return super.addListener(event, listener);
@@ -213,14 +399,6 @@ var TypedEmitter = class extends EventEmitter {
   }
 };
 
-// src/lib/SseError.ts
-var SseError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.message = `better-sse: ${message}`;
-  }
-};
-
 // src/Session.ts
 var Session = class extends TypedEmitter {
   /**
@@ -249,70 +427,78 @@ var Session = class extends TypedEmitter {
    */
   state;
   buffer;
-  /**
-   * Raw HTTP request.
-   */
-  req;
-  /**
-   * Raw HTTP response that is the minimal interface needed and forms the
-   * intersection between the HTTP/1.1 and HTTP/2 server response interfaces.
-   */
-  res;
-  serialize;
+  connection;
   sanitize;
-  trustClientEventId;
+  serialize;
   initialRetry;
   keepAliveInterval;
   keepAliveTimer;
-  statusCode;
-  headers;
-  constructor(req, res, options = {}) {
+  constructor(req, res, options) {
     super();
-    this.req = req;
-    this.res = res;
-    const serializer = options.serializer ?? serialize;
-    const sanitizer = options.sanitizer ?? sanitize;
-    this.serialize = serializer;
-    this.sanitize = sanitizer;
-    this.buffer = new EventBuffer({ serializer, sanitizer });
-    this.trustClientEventId = options.trustClientEventId ?? true;
-    this.initialRetry = options.retry === null ? null : options.retry ?? 2e3;
-    this.keepAliveInterval = options.keepAlive === null ? null : options.keepAlive ?? 1e4;
-    this.statusCode = options.statusCode ?? 200;
-    this.headers = options.headers ?? {};
-    this.state = options.state ?? {};
-    this.req.once("close", this.onDisconnected);
-    this.res.once("close", this.onDisconnected);
-    setImmediate(this.initialize);
-  }
-  initialize = () => {
-    const url = `http://${this.req.headers.host}${this.req.url}`;
-    const params = new URL(url).searchParams;
-    if (this.trustClientEventId) {
-      const givenLastEventId = this.req.headers["last-event-id"] ?? params.get("lastEventId") ?? params.get("evs_last_event_id") ?? "";
-      this.lastId = givenLastEventId;
-    }
-    const headers = {};
-    if (this.res instanceof Http1ServerResponse) {
-      headers["Content-Type"] = "text/event-stream";
-      headers["Cache-Control"] = "private, no-cache, no-store, no-transform, must-revalidate, max-age=0";
-      headers["Connection"] = "keep-alive";
-      headers["Pragma"] = "no-cache";
-      headers["X-Accel-Buffering"] = "no";
+    let givenOptions = options ?? {};
+    if (req instanceof Request) {
+      let givenRes = null;
+      if (res) {
+        if (res instanceof Response) {
+          givenRes = res;
+        } else {
+          if (options) {
+            throw new SseError(
+              "When providing a Fetch Request object but no Response object, you may pass options as the second OR third argument to the session constructor, but not to both."
+            );
+          }
+          givenOptions = res;
+        }
+      }
+      this.connection = new FetchConnection(req, givenRes, givenOptions);
+    } else if (req instanceof Http1ServerRequest) {
+      if (res instanceof Http1ServerResponse) {
+        this.connection = new NodeHttp1Connection(req, res, givenOptions);
+      } else {
+        throw new SseError(
+          "When providing a Node IncomingMessage object, a corresponding ServerResponse object must also be provided."
+        );
+      }
+    } else if (req instanceof Http2ServerRequest) {
+      if (res instanceof Http2ServerResponse) {
+        this.connection = new NodeHttp2CompatConnection(req, res, givenOptions);
+      } else {
+        throw new SseError(
+          "When providing a Node HTTP2ServerRequest object, a corresponding HTTP2ServerResponse object must also be provided."
+        );
+      }
     } else {
-      headers["content-type"] = "text/event-stream";
-      headers["cache-control"] = "private, no-cache, no-store, no-transform, must-revalidate, max-age=0";
-      headers["pragma"] = "no-cache";
-      headers["x-accel-buffering"] = "no";
+      throw new SseError(
+        "Malformed request or response objects given to session constructor. Must be one of IncomingMessage/ServerResponse from the Node HTTP/1 API, HTTP2ServerRequest/HTTP2ServerResponse from the Node HTTP/2 Compatibility API, or Request/Response from the Fetch API."
+      );
+    }
+    if (givenOptions.headers) {
+      applyHeaders(givenOptions.headers, this.connection.response.headers);
     }
-    for (const [name, value] of Object.entries(this.headers)) {
-      headers[name] = value ?? "";
+    if (givenOptions.trustClientEventId !== false) {
+      this.lastId = this.connection.request.headers.get("last-event-id") ?? this.connection.url.searchParams.get("lastEventId") ?? this.connection.url.searchParams.get("evs_last_event_id") ?? "";
     }
-    this.res.writeHead(this.statusCode, headers);
-    if (params.has("padding")) {
+    this.state = givenOptions.state ?? {};
+    this.initialRetry = givenOptions.retry === null ? null : givenOptions.retry ?? 2e3;
+    this.keepAliveInterval = givenOptions.keepAlive === null ? null : givenOptions.keepAlive ?? 1e4;
+    this.serialize = givenOptions.serializer ?? serialize;
+    this.sanitize = givenOptions.sanitizer ?? sanitize;
+    this.buffer = new EventBuffer({
+      serializer: this.serialize,
+      sanitizer: this.sanitize
+    });
+    this.connection.request.signal.addEventListener(
+      "abort",
+      this.onDisconnected
+    );
+    setImmediate(this.initialize);
+  }
+  initialize = () => {
+    this.connection.sendHead();
+    if (this.connection.url.searchParams.has("padding")) {
       this.buffer.comment(" ".repeat(2049)).dispatch();
     }
-    if (params.has("evs_preamble")) {
+    if (this.connection.url.searchParams.has("evs_preamble")) {
       this.buffer.comment(" ".repeat(2056)).dispatch();
     }
     if (this.initialRetry !== null) {
@@ -320,80 +506,57 @@ var Session = class extends TypedEmitter {
     }
     this.flush();
     if (this.keepAliveInterval !== null) {
-      this.keepAliveTimer = setInterval(
-        this.keepAlive,
-        this.keepAliveInterval
-      );
+      this.keepAliveTimer = setInterval(this.keepAlive, this.keepAliveInterval);
     }
     this.isConnected = true;
     this.emit("connected");
   };
   onDisconnected = () => {
-    this.req.removeListener("close", this.onDisconnected);
-    this.res.removeListener("close", this.onDisconnected);
+    this.connection.request.signal.removeEventListener(
+      "abort",
+      this.onDisconnected
+    );
+    this.connection.cleanup();
     if (this.keepAliveTimer) {
       clearInterval(this.keepAliveTimer);
     }
     this.isConnected = false;
     this.emit("disconnected");
   };
+  /**
+   * Write an empty comment and flush it to the client.
+   */
   keepAlive = () => {
     this.buffer.comment().dispatch();
     this.flush();
   };
   /**
-   * @deprecated see https://github.com/MatthewWid/better-sse/issues/52
-   */
-  event(type) {
-    this.buffer.event(type);
-    return this;
-  }
-  /**
-   * @deprecated see https://github.com/MatthewWid/better-sse/issues/52
-   */
-  data = (data) => {
-    this.buffer.data(data);
-    return this;
-  };
-  /**
-   * @deprecated see https://github.com/MatthewWid/better-sse/issues/52
-   */
-  id = (id = "") => {
-    this.buffer.id(id);
-    this.lastId = id;
-    return this;
-  };
-  /**
-   * @deprecated see https://github.com/MatthewWid/better-sse/issues/52
-   */
-  retry = (time) => {
-    this.buffer.retry(time);
-    return this;
-  };
-  /**
-   * @deprecated see https://github.com/MatthewWid/better-sse/issues/52
+   * Flush the contents of the internal buffer to the client and clear the buffer.
    */
-  comment = (text) => {
-    this.buffer.comment(text);
-    return this;
+  flush = () => {
+    const contents = this.buffer.read();
+    this.buffer.clear();
+    this.connection.sendChunk(contents);
   };
   /**
-   * @deprecated see https://github.com/MatthewWid/better-sse/issues/52
+   * Get a Request object representing the request of the underlying connection this session manages.
+   *
+   * When using the Fetch API, this will be the original Request object passed to the session constructor.
+   *
+   * When using the Node HTTP APIs, this will be a new Request object with status code and headers copied from the original request.
+   * When the originally given request or response is closed, the abort signal attached to this Request will be triggered.
    */
-  dispatch = () => {
-    this.buffer.dispatch();
-    return this;
-  };
+  getRequest = () => this.connection.request;
   /**
-   * Flush the contents of the internal buffer to the client and clear the buffer.
+   * Get a Response object representing the response of the underlying connection this session manages.
    *
-   * @deprecated see https://github.com/MatthewWid/better-sse/issues/52
+   * When using the Fetch API, this will be a new Response object with status code and headers copied from the original response if given.
+   * Its body will be a ReadableStream that should begin being consumed for the session to consider itself connected.
+   *
+   * When using the Node HTTP APIs, this will be a new Response object with status code and headers copied from the original response.
+   * Its body will be `null`, as data is instead written to the stream of the originally given response object.
    */
-  flush = () => {
-    this.res.write(this.buffer.read());
-    this.buffer.clear();
-    return this;
-  };
+  getResponse = () => this.connection.response;
   /**
    * Push an event to the client.
    *
@@ -401,6 +564,8 @@ var Session = class extends TypedEmitter {
    *
    * If no event ID is given, the event ID (and thus the `lastId` property) is set to a unique string generated using a cryptographic pseudorandom number generator.
    *
+   * If the session has disconnected, an `SseError` will be thrown.
+   *
    * Emits the `push` event with the given data, event name and event ID in that order.
    *
    * @param data - Data to write.
@@ -409,7 +574,9 @@ var Session = class extends TypedEmitter {
    */
   push = (data, eventName = "message", eventId = generateId()) => {
     if (!this.isConnected) {
-      throw new SseError("Cannot push data to a non-active session.");
+      throw new SseError(
+        "Cannot push data to a non-active session. Ensure the session is connected before attempting to push events. If using the Fetch API, the response stream must begin being consumed before the session is considered connected."
+      );
     }
     this.buffer.push(data, eventName, eventId);
     this.flush();
@@ -458,25 +625,54 @@ var Session = class extends TypedEmitter {
    */
   batch = async (batcher) => {
     if (batcher instanceof EventBuffer) {
-      this.res.write(batcher.read());
+      this.connection.sendChunk(batcher.read());
     } else {
       const buffer = new EventBuffer({
         serializer: this.serialize,
         sanitizer: this.sanitize
       });
       await batcher(buffer);
-      this.res.write(buffer.read());
+      this.connection.sendChunk(buffer.read());
     }
   };
 };
 
 // src/createSession.ts
-var createSession = (...args) => new Promise((resolve) => {
+function createSession(req, res, options) {
+  return new Promise((resolve) => {
+    const session = new Session(req, res, options);
+    if (req instanceof Request) {
+      resolve(session);
+    } else {
+      session.once("connected", () => {
+        resolve(session);
+      });
+    }
+  });
+}
+
+// src/createResponse.ts
+function createResponse(request, response, options, callback) {
+  const args = [request, response, options, callback];
+  let givenCallback;
+  for (let index = args.length - 1; index >= 0; --index) {
+    const arg = args.pop();
+    if (arg) {
+      givenCallback = arg;
+      break;
+    }
+  }
+  if (typeof givenCallback !== "function") {
+    throw new SseError(
+      "Last argument given to createResponse must be a callback function."
+    );
+  }
   const session = new Session(...args);
   session.once("connected", () => {
-    resolve(session);
+    givenCallback(session);
   });
-});
+  return session.getResponse();
+}
 
 // src/Channel.ts
 var Channel = class extends TypedEmitter {
@@ -575,5 +771,6 @@ export {
   SseError,
   createChannel,
   createEventBuffer,
+  createResponse,
   createSession
 };

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "better-sse",
-  "description": "Dead simple, dependency-less, spec-compliant server-sent events implementation for Node, written in TypeScript.",
-  "version": "0.14.0",
+  "description": "Dead simple, dependency-less, spec-compliant server-sent events implementation written in TypeScript.",
+  "version": "0.15.0",
   "license": "MIT",
   "author": "Matthew W. <matthew.widdi@gmail.com>",
   "repository": "github:MatthewWid/better-sse",
-  "homepage": "https://github.com/MatthewWid/better-sse",
+  "homepage": "https://matthewwid.github.io/better-sse",
   "bugs": "https://github.com/MatthewWid/better-sse/issues",
   "keywords": [
     "server-sent-events",
@@ -34,18 +34,13 @@
     "pnpm": ">=9"
   },
   "devDependencies": {
+    "@biomejs/biome": "1.9.4",
     "@tsconfig/node20": "^20.1.4",
     "@types/eventsource": "^1.1.15",
     "@types/express": "^5.0.0",
     "@types/node": "^22.7.6",
-    "@typescript-eslint/eslint-plugin": "^8.9.0",
-    "@typescript-eslint/parser": "^8.9.0",
-    "eslint": "^8.57.1",
-    "eslint-plugin-tsdoc": "^0.3.0",
     "eventsource": "^2.0.2",
     "npm-run-all": "^4.1.5",
-    "prettier": "^3.3.3",
-    "ts-node": "^10.9.2",
     "tsup": "^8.3.0",
     "typescript": "^5.6.3",
     "vitest": "^2.1.3"
@@ -53,7 +48,8 @@
   "scripts": {
     "build": "tsup",
     "test": "vitest",
-    "format": "prettier --write ./src/**/*.ts",
-    "lint": "eslint \"./src/**/*.ts\""
+    "format": "biome check --linter-enabled=false --write",
+    "lint": "biome lint --write",
+    "ci": "biome ci"
   }
 }