@tymber/sse 0.0.1-alpha.0 → 0.0.1

package/LICENSE

@@ -0,0 +1,22 @@
+(The MIT License)
+
+Copyright (c) 2026-present Damien ARRACHEQUESNE
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/endpoints/SSEEndpoint.d.ts

@@ -0,0 +1,17 @@
+import { ConfigService, type HttpContext, INJECT, UserEndpoint } from "@tymber/core";
+import { SSEService } from "../services/SSEService.js";
+/**
+ * Endpoint responsible for managing Server-Sent Events (SSE) connections from authenticated users.
+ *
+ * Reference: https://html.spec.whatwg.org/multipage/server-sent-events.html
+ */
+export declare class SSEEndpoint extends UserEndpoint {
+    static [INJECT]: (typeof SSEService | typeof ConfigService)[];
+    private timerId?;
+    private clients;
+    constructor(sse: SSEService, configService: ConfigService);
+    private schedulePing;
+    private send;
+    close(): void | Promise<void>;
+    protected handle(ctx: HttpContext): import("undici-types").Response;
+}

package/dist/endpoints/SSEEndpoint.js

@@ -0,0 +1,112 @@
+import { ConfigService, INJECT, randomUUID, UserEndpoint, } from "@tymber/core";
+import { SSEService } from "../services/SSEService.js";
+import {} from "node:stream/web";
+function isIncluded(filter, user) {
+    switch (filter.type) {
+        case "all":
+            return true;
+        case "user":
+            return user.id === filter.data.userId;
+        case "role":
+            return user.roles.includes(filter.data.role);
+        case "group":
+            return user.groups.some((group) => group.id === filter.data.groupId);
+        case "group-role":
+            return user.groups.some((group) => group.id === filter.data.groupId && group.role === filter.data.role);
+        default:
+            return false;
+    }
+}
+/**
+ * Endpoint responsible for managing Server-Sent Events (SSE) connections from authenticated users.
+ *
+ * Reference: https://html.spec.whatwg.org/multipage/server-sent-events.html
+ */
+export class SSEEndpoint extends UserEndpoint {
+    static [INJECT] = [SSEService, ConfigService];
+    timerId;
+    clients = new Map();
+    constructor(sse, configService) {
+        super();
+        configService.subscribe({
+            SSE_PING_INTERVAL_IN_SECONDS: {
+                type: "number",
+                minimum: 1,
+                default: 30,
+            },
+        }, (config) => {
+            this.schedulePing(config.SSE_PING_INTERVAL_IN_SECONDS);
+        });
+        sse.onEvent((event) => {
+            // note: no Last-Event-ID support
+            const payload = `event: ${event.type}\ndata: ${event.data !== undefined ? JSON.stringify(event.data) : ""}\n\n`;
+            for (const [id, client] of this.clients.entries()) {
+                if (isIncluded(event.filter, client.user)) {
+                    this.send(id, client, payload);
+                }
+            }
+        });
+    }
+    schedulePing(intervalInSeconds) {
+        if (this.timerId) {
+            clearInterval(this.timerId);
+        }
+        this.timerId = setInterval(() => {
+            for (const [id, client] of this.clients.entries()) {
+                if (client.lastMessage + intervalInSeconds * 1000 < Date.now()) {
+                    this.send(id, client, ": ping\n\n");
+                }
+            }
+        }, intervalInSeconds * 1000);
+    }
+    send(id, client, payload) {
+        try {
+            client.controller.enqueue(payload);
+            client.lastMessage = Date.now();
+        }
+        catch {
+            this.clients.delete(id);
+        }
+    }
+    close() {
+        if (this.timerId) {
+            clearInterval(this.timerId);
+        }
+        for (const [_, client] of this.clients.entries()) {
+            try {
+                client.controller.close();
+            }
+            catch (e) { }
+        }
+        this.clients.clear();
+    }
+    handle(ctx) {
+        const id = randomUUID();
+        const stream = new ReadableStream({
+            start: (controller) => {
+                const client = {
+                    controller,
+                    user: ctx.user,
+                    lastMessage: Date.now(),
+                };
+                this.clients.set(id, client);
+                ctx.signal.addEventListener("abort", () => {
+                    try {
+                        controller.close();
+                    }
+                    catch { }
+                    this.clients.delete(id);
+                });
+                // comment line used to ensure the connection is functional (will not fire on the client)
+                this.send(id, client, ": connected\n\n");
+            },
+        });
+        return new Response(stream, {
+            headers: {
+                "content-type": "text/event-stream",
+                "cache-control": "no-cache",
+                connection: "keep-alive",
+            },
+        });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import type { Module } from "@tymber/core";
+import { SSEService } from "./services/SSEService.js";
+export declare const SSEModule: Module;
+export { SSEService };

package/dist/index.js

@@ -0,0 +1,11 @@
+import { SSEService } from "./services/SSEService.js";
+import { SSEEndpoint } from "./endpoints/SSEEndpoint.js";
+export const SSEModule = {
+    name: "@tymber/sse",
+    version: "0.0.1",
+    init(app) {
+        app.component(SSEService);
+        app.userEndpoint("GET", "/api/events", SSEEndpoint);
+    },
+};
+export { SSEService };

package/dist/services/SSEService.d.ts

@@ -0,0 +1,52 @@
+import { Component, type Context, EventEmitter, type GroupId, type GroupRole, INJECT, PubSubService, type UserId, type UserRole } from "@tymber/core";
+export type Filter = {
+    type: "all";
+} | {
+    type: "user";
+    data: {
+        userId: UserId;
+    };
+} | {
+    type: "role";
+    data: {
+        role: UserRole;
+    };
+} | {
+    type: "group";
+    data: {
+        groupId: GroupId;
+    };
+} | {
+    type: "group-role";
+    data: {
+        groupId: GroupId;
+        role: GroupRole;
+    };
+};
+export interface ServerSentEvent {
+    type: string;
+    data: unknown;
+    filter: Filter;
+}
+export declare class SSEService extends Component {
+    private readonly pubSubService;
+    static [INJECT]: (typeof PubSubService)[];
+    private emitter;
+    constructor(pubSubService: PubSubService);
+    onEvent(listener: (event: ServerSentEvent) => void): void;
+    toUser(userId: UserId): SSEPublisher;
+    toUsersWithRole(role: UserRole): SSEPublisher;
+    toGroup(groupId: GroupId): SSEPublisher;
+    toGroupWithRole(groupId: GroupId, role: GroupRole): SSEPublisher;
+    publish(ctx: Context, type: string, data?: unknown): void;
+}
+declare class SSEPublisher {
+    private readonly emitter;
+    private readonly pubSubService;
+    private readonly filter;
+    constructor(emitter: EventEmitter<{
+        sse: ServerSentEvent;
+    }>, pubSubService: PubSubService, filter: Filter);
+    publish(ctx: Context, type: string, data?: unknown): void;
+}
+export {};

package/dist/services/SSEService.js

@@ -0,0 +1,69 @@
+import { Component, EventEmitter, INJECT, PubSubService, } from "@tymber/core";
+export class SSEService extends Component {
+    pubSubService;
+    static [INJECT] = [PubSubService];
+    emitter = new EventEmitter();
+    constructor(pubSubService) {
+        super();
+        this.pubSubService = pubSubService;
+        pubSubService.subscribe("sse", (event) => {
+            this.emitter.emit("sse", event);
+        });
+    }
+    onEvent(listener) {
+        this.emitter.on("sse", listener);
+    }
+    toUser(userId) {
+        return new SSEPublisher(this.emitter, this.pubSubService, {
+            type: "user",
+            data: { userId },
+        });
+    }
+    toUsersWithRole(role) {
+        return new SSEPublisher(this.emitter, this.pubSubService, {
+            type: "role",
+            data: { role },
+        });
+    }
+    toGroup(groupId) {
+        return new SSEPublisher(this.emitter, this.pubSubService, {
+            type: "group",
+            data: { groupId },
+        });
+    }
+    toGroupWithRole(groupId, role) {
+        return new SSEPublisher(this.emitter, this.pubSubService, {
+            type: "group-role",
+            data: { groupId, role },
+        });
+    }
+    publish(ctx, type, data) {
+        return new SSEPublisher(this.emitter, this.pubSubService, {
+            type: "all",
+        }).publish(ctx, type, data);
+    }
+}
+class SSEPublisher {
+    emitter;
+    pubSubService;
+    filter;
+    constructor(emitter, pubSubService, filter) {
+        this.emitter = emitter;
+        this.pubSubService = pubSubService;
+        this.filter = filter;
+    }
+    publish(ctx, type, data) {
+        // notify connected clients on this instance
+        this.emitter.emit("sse", {
+            type,
+            data,
+            filter: this.filter,
+        });
+        // notify other instances
+        this.pubSubService.publish(ctx, "sse", {
+            type,
+            data,
+            filter: this.filter,
+        });
+    }
+}

package/package.json

@@ -1,7 +1,38 @@
 {
   "name": "@tymber/sse",
-  "version": "0.0.1-alpha.0",
+  "version": "0.0.1",
   "description": "Server-sent events module for the Tymber framework",
   "license": "MIT",
-  "author": "Damien ARRACHEQUESNE"
+  "author": "Damien ARRACHEQUESNE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tymber-framework/tymber.git"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "compile": "rm -rf dist/ && tsc",
+    "format:check": "prettier -c src/ test/",
+    "format:fix": "prettier -w src/ test/",
+    "test": "tsx --test"
+  },
+  "peerDependencies": {
+    "@tymber/core": "*"
+  },
+  "files": [
+    "src/",
+    "dist/"
+  ],
+  "exports": {
+    "node": "./dist/index.js",
+    "bun": "./src/index.ts",
+    "deno": "./src/index.ts"
+  },
+  "keywords": [
+    "tymber",
+    "typescript",
+    "framework",
+    "sse"
+  ]
 }

package/src/endpoints/SSEEndpoint.ts

@@ -0,0 +1,151 @@
+import {
+  ConfigService,
+  type ConnectedUser,
+  type HttpContext,
+  INJECT,
+  randomUUID,
+  UserEndpoint,
+} from "@tymber/core";
+import { type Filter, SSEService } from "../services/SSEService.js";
+import { type ReadableStreamController } from "node:stream/web";
+
+interface Config {
+  SSE_PING_INTERVAL_IN_SECONDS: number;
+}
+
+interface SSEClient {
+  controller: ReadableStreamController<string>;
+  lastMessage: number;
+  user: ConnectedUser;
+}
+
+function isIncluded(filter: Filter, user: ConnectedUser) {
+  switch (filter.type) {
+    case "all":
+      return true;
+    case "user":
+      return user.id === filter.data.userId;
+    case "role":
+      return user.roles.includes(filter.data.role);
+    case "group":
+      return user.groups.some((group) => group.id === filter.data.groupId);
+    case "group-role":
+      return user.groups.some(
+        (group) =>
+          group.id === filter.data.groupId && group.role === filter.data.role,
+      );
+    default:
+      return false;
+  }
+}
+
+/**
+ * Endpoint responsible for managing Server-Sent Events (SSE) connections from authenticated users.
+ *
+ * Reference: https://html.spec.whatwg.org/multipage/server-sent-events.html
+ */
+export class SSEEndpoint extends UserEndpoint {
+  static [INJECT] = [SSEService, ConfigService];
+
+  private timerId?: ReturnType<typeof setInterval>;
+  private clients = new Map<string, SSEClient>();
+
+  constructor(sse: SSEService, configService: ConfigService) {
+    super();
+
+    configService.subscribe<Config>(
+      {
+        SSE_PING_INTERVAL_IN_SECONDS: {
+          type: "number",
+          minimum: 1,
+          default: 30,
+        },
+      },
+      (config) => {
+        this.schedulePing(config.SSE_PING_INTERVAL_IN_SECONDS);
+      },
+    );
+
+    sse.onEvent((event) => {
+      // note: no Last-Event-ID support
+      const payload = `event: ${event.type}\ndata: ${event.data !== undefined ? JSON.stringify(event.data) : ""}\n\n`;
+
+      for (const [id, client] of this.clients.entries()) {
+        if (isIncluded(event.filter, client.user)) {
+          this.send(id, client, payload);
+        }
+      }
+    });
+  }
+
+  private schedulePing(intervalInSeconds: number) {
+    if (this.timerId) {
+      clearInterval(this.timerId);
+    }
+    this.timerId = setInterval(() => {
+      for (const [id, client] of this.clients.entries()) {
+        if (client.lastMessage + intervalInSeconds * 1000 < Date.now()) {
+          this.send(id, client, ": ping\n\n");
+        }
+      }
+    }, intervalInSeconds * 1000);
+  }
+
+  private send(id: string, client: SSEClient, payload: string) {
+    try {
+      client.controller.enqueue(payload);
+      client.lastMessage = Date.now();
+    } catch {
+      this.clients.delete(id);
+    }
+  }
+
+  override close(): void | Promise<void> {
+    if (this.timerId) {
+      clearInterval(this.timerId);
+    }
+
+    for (const [_, client] of this.clients.entries()) {
+      try {
+        client.controller.close();
+      } catch (e) {}
+    }
+
+    this.clients.clear();
+  }
+
+  protected handle(ctx: HttpContext) {
+    const id = randomUUID();
+
+    const stream = new ReadableStream({
+      start: (controller) => {
+        const client: SSEClient = {
+          controller,
+          user: ctx.user as ConnectedUser,
+          lastMessage: Date.now(),
+        };
+
+        this.clients.set(id, client);
+
+        ctx.signal.addEventListener("abort", () => {
+          try {
+            controller.close();
+          } catch {}
+
+          this.clients.delete(id);
+        });
+
+        // comment line used to ensure the connection is functional (will not fire on the client)
+        this.send(id, client, ": connected\n\n");
+      },
+    });
+
+    return new Response(stream, {
+      headers: {
+        "content-type": "text/event-stream",
+        "cache-control": "no-cache",
+        connection: "keep-alive",
+      },
+    });
+  }
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+import type { Module } from "@tymber/core";
+import { SSEService } from "./services/SSEService.js";
+import { SSEEndpoint } from "./endpoints/SSEEndpoint.js";
+
+export const SSEModule: Module = {
+  name: "@tymber/sse",
+  version: "0.0.1",
+
+  init(app) {
+    app.component(SSEService);
+
+    app.userEndpoint("GET", "/api/events", SSEEndpoint);
+  },
+};
+
+export { SSEService };

package/src/services/SSEService.ts

@@ -0,0 +1,126 @@
+import {
+  Component,
+  type Context,
+  EventEmitter,
+  type GroupId,
+  type GroupRole,
+  INJECT,
+  PubSubService,
+  type UserId,
+  type UserRole,
+} from "@tymber/core";
+
+export type Filter =
+  | {
+      type: "all";
+    }
+  | {
+      type: "user";
+      data: {
+        userId: UserId;
+      };
+    }
+  | {
+      type: "role";
+      data: {
+        role: UserRole;
+      };
+    }
+  | {
+      type: "group";
+      data: {
+        groupId: GroupId;
+      };
+    }
+  | {
+      type: "group-role";
+      data: {
+        groupId: GroupId;
+        role: GroupRole;
+      };
+    };
+
+export interface ServerSentEvent {
+  type: string;
+  data: unknown;
+  filter: Filter;
+}
+
+export class SSEService extends Component {
+  static override [INJECT] = [PubSubService];
+
+  private emitter = new EventEmitter<{
+    sse: ServerSentEvent;
+  }>();
+
+  constructor(private readonly pubSubService: PubSubService) {
+    super();
+    pubSubService.subscribe("sse", (event: ServerSentEvent) => {
+      this.emitter.emit("sse", event);
+    });
+  }
+
+  onEvent(listener: (event: ServerSentEvent) => void) {
+    this.emitter.on("sse", listener);
+  }
+
+  toUser(userId: UserId) {
+    return new SSEPublisher(this.emitter, this.pubSubService, {
+      type: "user",
+      data: { userId },
+    });
+  }
+
+  toUsersWithRole(role: UserRole) {
+    return new SSEPublisher(this.emitter, this.pubSubService, {
+      type: "role",
+      data: { role },
+    });
+  }
+
+  toGroup(groupId: GroupId) {
+    return new SSEPublisher(this.emitter, this.pubSubService, {
+      type: "group",
+      data: { groupId },
+    });
+  }
+
+  toGroupWithRole(groupId: GroupId, role: GroupRole) {
+    return new SSEPublisher(this.emitter, this.pubSubService, {
+      type: "group-role",
+      data: { groupId, role },
+    });
+  }
+
+  public publish(ctx: Context, type: string, data?: unknown) {
+    return new SSEPublisher(this.emitter, this.pubSubService, {
+      type: "all",
+    }).publish(ctx, type, data);
+  }
+}
+
+class SSEPublisher {
+  constructor(
+    private readonly emitter: EventEmitter<{
+      sse: ServerSentEvent;
+    }>,
+    private readonly pubSubService: PubSubService,
+    private readonly filter: Filter,
+  ) {}
+
+  public publish(ctx: Context, type: string, data?: unknown) {
+    // notify connected clients on this instance
+    this.emitter.emit("sse", {
+      type,
+      data,
+      filter: this.filter,
+    });
+
+    // notify other instances
+    this.pubSubService.publish(ctx, "sse", {
+      type,
+      data,
+      filter: this.filter,
+    });
+  }
+}