@tsed/sse 8.0.0 → 8.0.2

package/package.json

@@ -2,7 +2,7 @@
   "name": "@tsed/sse",
   "description": "Server-sent events package for Ts.ED framework",
   "type": "module",
-  "version": "8.0.0",
+  "version": "8.0.2",
   "keywords": [
     "tsed",
     "server-sent events",
@@ -16,6 +16,7 @@
   "typings": "./lib/types/index.d.ts",
   "exports": {
     ".": {
+      "@tsed/source": "./src/index.ts",
       "types": "./lib/types/index.d.ts",
       "import": "./lib/esm/index.js",
       "default": "./lib/esm/index.js"
@@ -33,27 +34,27 @@
     "tslib": "2.7.0"
   },
   "devDependencies": {
-    "@tsed/barrels": "8.0.0",
-    "@tsed/core": "8.0.0",
-    "@tsed/di": "8.0.0",
-    "@tsed/json-mapper": "8.0.0",
-    "@tsed/openspec": "8.0.0",
-    "@tsed/platform-http": "8.0.0",
-    "@tsed/platform-middlewares": "8.0.0",
-    "@tsed/schema": "8.0.0",
-    "@tsed/socketio-testing": "8.0.0",
-    "@tsed/typescript": "8.0.0",
+    "@tsed/barrels": "8.0.2",
+    "@tsed/core": "8.0.2",
+    "@tsed/di": "8.0.2",
+    "@tsed/json-mapper": "8.0.2",
+    "@tsed/openspec": "8.0.2",
+    "@tsed/platform-http": "8.0.2",
+    "@tsed/platform-middlewares": "8.0.2",
+    "@tsed/schema": "8.0.2",
+    "@tsed/socketio-testing": "8.0.2",
+    "@tsed/typescript": "8.0.2",
     "eslint": "9.12.0",
     "express": "^4.21.0",
     "typescript": "5.4.5",
     "vitest": "2.1.2"
   },
   "peerDependencies": {
-    "@tsed/di": "8.0.0",
-    "@tsed/json-mapper": "8.0.0",
+    "@tsed/di": "8.0.2",
+    "@tsed/json-mapper": "8.0.2",
     "@tsed/logger": ">=6.7.5",
-    "@tsed/platform-middlewares": "8.0.0",
-    "@tsed/schema": "8.0.0"
+    "@tsed/platform-middlewares": "8.0.2",
+    "@tsed/schema": "8.0.2"
   },
   "peerDependenciesMeta": {
     "@tsed/di": {

package/src/__snapshots__/sse.integration.spec.ts.snap

@@ -0,0 +1,171 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`SSE integration > should generate the swagger spec 1`] = `
+{
+  "components": {
+    "schemas": {
+      "Model": {
+        "properties": {
+          "id": {
+            "type": "string",
+          },
+        },
+        "type": "object",
+      },
+    },
+  },
+  "paths": {
+    "/sse/scenario1": {
+      "get": {
+        "operationId": "myCtrlScenario1",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "content": {
+              "*/*": {
+                "schema": {
+                  "type": "object",
+                },
+              },
+            },
+            "headers": {
+              "Content-Type": {
+                "example": "text/event-stream",
+                "schema": {
+                  "type": "string",
+                },
+              },
+            },
+          },
+        },
+        "tags": [
+          "MyCtrl",
+        ],
+      },
+    },
+    "/sse/scenario2": {
+      "get": {
+        "operationId": "myCtrlScenario2",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "content": {
+              "*/*": {
+                "schema": {
+                  "type": "object",
+                },
+              },
+            },
+            "headers": {
+              "Content-Type": {
+                "example": "text/event-stream",
+                "schema": {
+                  "type": "string",
+                },
+              },
+            },
+          },
+        },
+        "tags": [
+          "MyCtrl",
+        ],
+      },
+    },
+    "/sse/scenario3": {
+      "get": {
+        "operationId": "myCtrlScenario3",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "content": {
+              "*/*": {
+                "schema": {
+                  "type": "object",
+                },
+              },
+            },
+            "headers": {
+              "Content-Type": {
+                "example": "text/event-stream",
+                "schema": {
+                  "type": "string",
+                },
+              },
+            },
+          },
+        },
+        "tags": [
+          "MyCtrl",
+        ],
+      },
+    },
+    "/sse/scenario4": {
+      "get": {
+        "operationId": "myCtrlScenario4",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "content": {
+              "*/*": {
+                "schema": {
+                  "type": "object",
+                },
+              },
+            },
+            "headers": {
+              "Content-Type": {
+                "example": "text/event-stream",
+                "schema": {
+                  "type": "string",
+                },
+              },
+            },
+          },
+        },
+        "tags": [
+          "MyCtrl",
+        ],
+      },
+    },
+    "/sse/scenario5": {
+      "get": {
+        "operationId": "myCtrlScenario5",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "content": {
+              "*/*": {
+                "schema": {
+                  "type": "object",
+                },
+              },
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Model",
+                },
+              },
+            },
+            "description": "Success",
+            "headers": {
+              "Content-Type": {
+                "example": "text/event-stream",
+                "schema": {
+                  "type": "string",
+                },
+              },
+            },
+          },
+        },
+        "tags": [
+          "MyCtrl",
+        ],
+      },
+    },
+  },
+  "tags": [
+    {
+      "name": "MyCtrl",
+    },
+  ],
+}
+`;

package/src/decorators/eventStream.ts

@@ -0,0 +1,19 @@
+import {StoreSet, useDecorators} from "@tsed/core";
+import {Use} from "@tsed/platform-middlewares";
+import {AcceptMime, Header} from "@tsed/schema";
+
+import {EventStreamMiddleware} from "../middlewares/EventStreamMiddleware.js";
+
+export interface EventStreamOpts {
+  headers?: Record<string, string>;
+  event?: string;
+}
+
+export function EventStream(opts: EventStreamOpts = {}) {
+  return useDecorators(
+    StoreSet(EventStreamMiddleware, opts),
+    Use(EventStreamMiddleware),
+    AcceptMime("text/event-stream"),
+    Header("Content-Type", "text/event-stream")
+  );
+}

package/src/decorators/eventStreamCtx.ts

@@ -0,0 +1,9 @@
+import {Context} from "@tsed/platform-params";
+
+import type {EventStreamContext} from "../domain/EventStreamContext.js";
+
+export type EventStreamCtx = EventStreamContext;
+
+export function EventStreamCtx() {
+  return Context("EventStreamContext");
+}

package/src/domain/EventStreamContext.ts

@@ -0,0 +1,133 @@
+import {isBoolean, isDate, isNumber, isString} from "@tsed/core";
+import {PlatformContext} from "@tsed/platform-http";
+import {PlatformResponseFilter} from "@tsed/platform-response-filter";
+import type {EventEmitter} from "events";
+import type {Observable} from "rxjs";
+
+import type {EventStreamOpts} from "../decorators/eventStream.js";
+
+export type EventStreamContextOptions = {
+  $ctx: PlatformContext;
+} & EventStreamOpts;
+
+export class EventStreamContext {
+  private $ctx: PlatformContext;
+  private opts: EventStreamOpts;
+  private responseFilter: PlatformResponseFilter;
+  #isDone = false;
+
+  constructor({$ctx, ...opts}: EventStreamContextOptions) {
+    this.$ctx = $ctx;
+
+    this.opts = opts;
+    this.responseFilter = this.$ctx.injector.get<PlatformResponseFilter>(PlatformResponseFilter)!;
+  }
+
+  writeHead(headers: Record<string, string> = {}) {
+    console.log("this.$ctx", this.$ctx);
+    this.on("end", () => {
+      this.$ctx.logger.info({
+        event: "SSE_ENDED"
+      });
+      this.$ctx.getRes().end();
+      this.#isDone = true;
+    });
+
+    this.on("close", () => {
+      this.$ctx.logger.info({
+        event: "SSE_CLOSED_BY_CLIENT"
+      });
+      this.$ctx.getRes().end();
+      this.#isDone = true;
+    });
+
+    this.$ctx.getRes().writeHead(200, {
+      ...this.opts.headers,
+      ...headers,
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache",
+      Connection: "keep-alive"
+    });
+  }
+
+  on(event: string, listener: (...args: any[]) => void): this {
+    this.$ctx.getRes().on(event, listener);
+    return this;
+  }
+
+  subscribe(observable: Observable<unknown>) {
+    observable.subscribe((data) => {
+      this.emit(this.opts.event, data);
+    });
+    return this;
+  }
+
+  stream(stream: NodeJS.ReadableStream | EventEmitter) {
+    const listener = (data: unknown) => {
+      if (this.isDone()) {
+        stream.off("data", listener);
+      } else {
+        this.emit(this.opts.event, data);
+      }
+    };
+
+    stream.on("data", listener);
+  }
+
+  emit(event: string | undefined, data: unknown) {
+    if (this.isDone()) {
+      return;
+    }
+    const {$ctx} = this;
+    if (data === undefined) {
+      return this;
+    }
+
+    if (Buffer.isBuffer(data)) {
+      data = data.toString("utf8");
+    }
+
+    if (isBoolean(data) || isNumber(data) || isString(data) || isDate(data) || data === null) {
+      this.write({
+        event: event || "",
+        data: JSON.stringify(data)
+      });
+      return this;
+    }
+
+    this.responseFilter
+      .serialize(data, $ctx as any)
+      .then((data: unknown) => {
+        return this.responseFilter.transform(data, $ctx as any);
+      })
+      .then((data: unknown) => {
+        data = JSON.stringify(data);
+
+        this.write({
+          event: event || "",
+          data: data as string
+        });
+      });
+
+    return this;
+  }
+
+  write(obj: Record<string, string>) {
+    const values = Object.entries(obj)
+      .map(([key, value]) => {
+        return `${key}: ${value}`;
+      })
+      .join("\n");
+
+    this.$ctx.getRes().write(`${values}\n\n`);
+  }
+
+  isDone() {
+    return this.#isDone;
+  }
+
+  end() {
+    this.#isDone = true;
+    this.$ctx.getRes().end();
+  }
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @file Automatically generated by @tsed/barrels.
+ */
+export * from "./decorators/eventStream.js";
+export * from "./decorators/eventStreamCtx.js";
+export * from "./domain/EventStreamContext.js";
+export * from "./interceptors/EventStreamInterceptor.js";
+export * from "./middlewares/EventStreamMiddleware.js";

package/src/interceptors/EventStreamInterceptor.ts

@@ -0,0 +1,34 @@
+import {isObservable, isStream} from "@tsed/core";
+import type {InterceptorContext, InterceptorMethods} from "@tsed/di";
+import {Injectable, InjectContext} from "@tsed/di";
+import type {PlatformContext} from "@tsed/platform-http";
+import type {Observable} from "rxjs";
+
+import {EventStreamContext} from "../domain/EventStreamContext.js";
+
+@Injectable()
+export class EventStreamInterceptor implements InterceptorMethods {
+  @InjectContext()
+  protected $ctx: PlatformContext;
+
+  async intercept(context: InterceptorContext): Promise<unknown> {
+    const result = await context.next();
+    const eventStream = this.$ctx.get<EventStreamContext>("EventStreamContext");
+
+    if (eventStream) {
+      if (isObservable(result)) {
+        eventStream.subscribe(result as Observable<unknown>);
+
+        return;
+      }
+
+      if (isStream(result)) {
+        eventStream.stream(result as NodeJS.ReadableStream);
+
+        return;
+      }
+    }
+
+    return result;
+  }
+}

package/src/middlewares/EventStreamMiddleware.ts

@@ -0,0 +1,25 @@
+import {PlatformContext} from "@tsed/platform-http";
+import {Middleware} from "@tsed/platform-middlewares";
+import {Context} from "@tsed/platform-params";
+
+import {EventStreamContext} from "../domain/EventStreamContext.js";
+
+@Middleware()
+export class EventStreamMiddleware {
+  use(@Context() $ctx: PlatformContext) {
+    const opts = $ctx.endpoint.store.get(EventStreamMiddleware, {});
+
+    // Enable stream logs
+    $ctx.logger.flush();
+    $ctx.logger.maxStackSize = 0;
+
+    const eventStream = new EventStreamContext({
+      $ctx,
+      ...opts
+    });
+
+    $ctx.set("EventStreamContext", eventStream);
+
+    eventStream.writeHead();
+  }
+}

package/src/sse.integration.spec.ts

@@ -0,0 +1,207 @@
+import {Controller} from "@tsed/di";
+import {PlatformContext} from "@tsed/platform-http";
+import {PlatformTest} from "@tsed/platform-http/testing";
+import {Context} from "@tsed/platform-params";
+import {Get, getSpec, JsonEntityStore, Name, Returns} from "@tsed/schema";
+
+import {EventStream} from "./decorators/eventStream.js";
+import {EventStreamCtx} from "./decorators/eventStreamCtx.js";
+import {EventStreamContext} from "./domain/EventStreamContext.js";
+
+function make(eventStream: EventStreamCtx, cb: () => any) {
+  let intervalId: ReturnType<typeof setInterval>;
+
+  eventStream.on("close", () => {
+    clearInterval(intervalId);
+  });
+
+  eventStream.on("end", () => {
+    clearInterval(intervalId);
+  });
+
+  intervalId = setInterval(() => {
+    // Ts.ED support Model serialization using json-mapper here
+    eventStream.emit("event", cb());
+  }, 200);
+}
+
+class Model {
+  @Name("id")
+  _id: string;
+}
+
+@Controller("/sse")
+export class MyCtrl {
+  @Get("/scenario1")
+  @EventStream()
+  scenario1(@EventStreamCtx() eventStream: EventStreamCtx) {
+    make(eventStream, () => new Date());
+  }
+
+  @Get("/scenario2")
+  @EventStream()
+  scenario2(@EventStreamCtx() eventStream: EventStreamCtx) {
+    make(eventStream, () => false);
+  }
+
+  @Get("/scenario3")
+  @EventStream()
+  scenario3(@EventStreamCtx() eventStream: EventStreamCtx) {
+    make(eventStream, () => 0);
+  }
+
+  @Get("/scenario4")
+  @EventStream()
+  scenario4(@EventStreamCtx() eventStream: EventStreamCtx) {
+    make(eventStream, () => ({
+      date: new Date(),
+      message: "Hello"
+    }));
+  }
+
+  @Get("/scenario5")
+  @EventStream()
+  @(Returns(200).Type(Model))
+  scenario5(@EventStreamCtx() eventStream: EventStreamCtx, @Context() $ctx: PlatformContext) {
+    make(eventStream, () => {
+      const model = new Model();
+      model._id = new Date().toISOString();
+
+      return model;
+    });
+  }
+}
+
+async function getControllerFixture(scenario: string) {
+  const controller = await PlatformTest.invoke<MyCtrl>(MyCtrl);
+
+  const endpoint = JsonEntityStore.fromMethod(MyCtrl, scenario);
+  const $ctx = PlatformTest.createRequestContext({
+    endpoint
+  });
+  const eventStream = new EventStreamContext({
+    $ctx
+  });
+
+  return {controller, endpoint, eventStream, $ctx};
+}
+
+describe("SSE integration", () => {
+  beforeEach(() => PlatformTest.create());
+  afterEach(() => PlatformTest.reset());
+  beforeEach(() => {
+    vi.useFakeTimers({
+      toFake: ["Date"],
+      now: new Date("2025-01-01T00:00:00Z").getTime()
+    });
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+  it("should generate the swagger spec", () => {
+    expect(getSpec(MyCtrl)).toMatchSnapshot();
+  });
+
+  describe("Scenario1 - Date/String", () => {
+    it("should pass the new EventStreamContext to function and process message", async () => {
+      const {controller, eventStream} = await getControllerFixture("scenario1");
+
+      controller.scenario1(eventStream);
+
+      // Wait for the first message
+      const result = await new Promise((resolve) => {
+        eventStream.on("data", resolve);
+      });
+
+      expect(result).toEqual("event: event\ndata: " + JSON.stringify(new Date()) + "\n\n");
+
+      // stop the interval
+      eventStream.end();
+    });
+  });
+
+  describe("Scenario2 - Boolean", () => {
+    it("should pass the new EventStreamContext to function and process message", async () => {
+      const {controller, eventStream} = await getControllerFixture("scenario2");
+
+      controller.scenario2(eventStream);
+
+      // Wait for the first message
+      const result = await new Promise((resolve) => {
+        eventStream.on("data", resolve);
+      });
+
+      expect(result).toEqual("event: event\ndata: false\n\n");
+
+      // stop the interval
+      eventStream.end();
+    });
+  });
+
+  describe("Scenario3 - Number", () => {
+    it("should pass the new EventStreamContext to function and process message", async () => {
+      const {controller, eventStream} = await getControllerFixture("scenario3");
+
+      controller.scenario3(eventStream);
+
+      // Wait for the first message
+      const result = await new Promise((resolve) => {
+        eventStream.on("data", resolve);
+      });
+
+      expect(result).toEqual("event: event\ndata: 0\n\n");
+
+      // stop the interval
+      eventStream.end();
+    });
+  });
+
+  describe("Scenario4 - Object", () => {
+    it("should pass the new EventStreamContext to function and process message", async () => {
+      const {controller, eventStream} = await getControllerFixture("scenario4");
+
+      controller.scenario4(eventStream);
+
+      // Wait for the first message
+      const result = await new Promise((resolve) => {
+        eventStream.on("data", resolve);
+      });
+
+      expect(result).toEqual(
+        "event: event\ndata: " +
+          JSON.stringify({
+            date: "2025-01-01T00:00:00.000Z",
+            message: "Hello"
+          }) +
+          "\n\n"
+      );
+
+      // stop the interval
+      eventStream.end();
+    });
+  });
+
+  describe("Scenario5 - Model", () => {
+    it("should pass the new EventStreamContext to function and process message", async () => {
+      const {controller, eventStream, $ctx} = await getControllerFixture("scenario5");
+
+      controller.scenario5(eventStream, $ctx);
+
+      // Wait for the first message
+      const result = await new Promise((resolve) => {
+        eventStream.on("data", resolve);
+      });
+
+      expect(result).toEqual(
+        "event: event\ndata: " +
+          JSON.stringify({
+            id: "2025-01-01T00:00:00.000Z"
+          }) +
+          "\n\n"
+      );
+
+      // stop the interval
+      eventStream.end();
+    });
+  });
+});