-
-
Notifications
You must be signed in to change notification settings - Fork 284
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
26 changed files
with
1,324 additions
and
64 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,171 @@ | ||
| --- | ||
| meta: | ||
| - name: description | ||
| content: Guide to implement Server-sent events with Ts.ED. | ||
| - name: keywords | ||
| content: ts.ed express typescript sse server-sent events node.js javascript decorators | ||
| --- | ||
|
|
||
| # Server-sent events | ||
|
|
||
| Server-sent events let you push data to the client. It's a simple way to send data from the server to the client. The data is sent as a stream of messages, with an optional event name and id. It's a simple way to send data from the server to the client. | ||
|
|
||
| ## Installation | ||
|
|
||
| Before using the Server-sent events, we need to install the `@tsed/sse` module. | ||
|
|
||
| <Tabs class="-code"> | ||
| <Tab label="npm"> | ||
|
|
||
| ```bash | ||
| npm install --save @tsed/sse | ||
| ``` | ||
|
|
||
| </Tab> | ||
|
|
||
| <Tab label="yarn"> | ||
|
|
||
| ```bash | ||
| yarn add --save @tsed/sse | ||
| ``` | ||
|
|
||
| </Tab> | ||
| <Tab label="pnpm"> | ||
|
|
||
| ```bash | ||
| pnpm add --save @tsed/sse | ||
| ``` | ||
|
|
||
| </Tab> | ||
| <Tab label="bun"> | ||
|
|
||
| ```bash | ||
| bun add --save @tsed/sse | ||
| ``` | ||
|
|
||
| </Tab> | ||
| </Tabs> | ||
|
|
||
| Then add the following configuration in your Server: | ||
|
|
||
| ```typescript | ||
| import {Configuration} from "@tsed/common"; | ||
| import "@tsed/sse"; // import sse Ts.ED module | ||
|
|
||
| @Configuration({ | ||
| acceptMimes: ["application/json", "text/event-stream"] | ||
| }) | ||
| export class Server {} | ||
| ``` | ||
|
|
||
| ::: warning | ||
| There is a known issue with the `compression` middleware. The | ||
| `compression` middleware should be disabled to work correctly with Server-sent events. | ||
| ::: | ||
|
|
||
| ## Features | ||
|
|
||
| - Support decorator usage to enable event-stream on an endpoint, | ||
| - Support Node.js stream like `EventEmmiter` to emit events from your controller to your consumer, | ||
| - Support `Observable` from `rxjs` to emit events from your controller to your consumer. | ||
| - Support `@tsed/json-mapper` to serialize your model before sending it to the client. | ||
| - Gives an API compatible with Express.js and Koa.js. | ||
|
|
||
| ## Enable event-stream | ||
|
|
||
| To enable the event-stream on an endpoint, you need to use the `@EventStream()` decorator on a method of a controller. | ||
|
|
||
| ```typescript | ||
| import {Controller} from "@tsed/di"; | ||
| import {Get} from "@tsed/schema"; | ||
| import {EventStream, EventStreamCtx} from "@tsed/sse"; | ||
|
|
||
| @Controller("/sse") | ||
| export class MyCtrl { | ||
| @Get("/events") | ||
| @EventStream() | ||
| events(@EventStreamCtx() eventStream: EventStreamCtx) { | ||
| 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", new Date()); | ||
| }, 1000); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Stream events | ||
|
|
||
| You can use Node.js stream like `EventEmmiter` to emit events from your controller to your consumer: | ||
|
|
||
| ```ts | ||
| import {EventStream} from "@tsed/sse"; | ||
| import {Controller} from "@tsed/di"; | ||
| import {Get} from "@tsed/schema"; | ||
|
|
||
| @Controller("/sse") | ||
| export class MyCtrl { | ||
| private eventEmitter = new EventEmitter(); | ||
|
|
||
| $onInit() { | ||
| setInterval(() => { | ||
| this.eventEmitter.emit("message", new Date()); | ||
| }, 1000); | ||
| } | ||
|
|
||
| @Get("/events") | ||
| @EventStream() | ||
| events() { | ||
| return this.eventEmitter; | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ### Observable | ||
|
|
||
| You can also use `Observable` from `rxjs` to emit events from your controller to your consumer: | ||
|
|
||
| ```ts | ||
| import {Controller} from "@tsed/di"; | ||
| import {Get} from "@tsed/schema"; | ||
| import {EventStream} from "@tsed/sse"; | ||
| import {Observable} from "rxjs"; | ||
|
|
||
| @Controller("/sse") | ||
| export class MyCtrl { | ||
| @Get("/events") | ||
| @EventStream() | ||
| events() { | ||
| const observable = new Observable((observer) => { | ||
| setInterval(() => { | ||
| observer.next(new Date()); | ||
| }, 1000); | ||
| }); | ||
|
|
||
| return observable; | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Author | ||
|
|
||
| <GithubContributors :users="['Romakita']"/> | ||
|
|
||
| ## Maintainers <Badge text="Help wanted" /> | ||
|
|
||
| <GithubContributors :users="['Romakita']"/> | ||
|
|
||
| <div class="flex items-center justify-center p-5"> | ||
| <Button href="/contributing.html" class="rounded-medium"> | ||
| Become maintainer | ||
| </Button> | ||
| </div> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| { | ||
| "directory": ["./src"], | ||
| "exclude": ["**/__mock__", "**/__mocks__", "**/*.spec.ts", "**/getConfiguration.ts"], | ||
| "exclude": ["**/__mock__", "**/__mocks__", "**/*.spec.ts", "**/getConfiguration.ts", "FakeResponse.ts"], | ||
| "delete": true | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,72 @@ | ||
| import {EventEmitter} from "node:events"; | ||
|
|
||
| export class FakeResponse extends EventEmitter { | ||
| headers: Record<string, unknown> = {}; | ||
| locals: Record<string, unknown> = {}; | ||
| statusCode: number = 200; | ||
| data: any; | ||
|
|
||
| constructor(opts = {}) { | ||
| super(); | ||
|
|
||
| Object.assign(this, opts); | ||
| } | ||
|
|
||
| status(code: number) { | ||
| this.statusCode = code; | ||
| return this; | ||
| } | ||
|
|
||
| contentType(content: string) { | ||
| this.set("content-type", content); | ||
| } | ||
|
|
||
| contentLength(content: number) { | ||
| this.set("content-length", content); | ||
| } | ||
|
|
||
| redirect(status: number, path: string) { | ||
| this.statusCode = status; | ||
| this.set("location", path); | ||
| } | ||
|
|
||
| location(path: string) { | ||
| this.set("location", path); | ||
| } | ||
|
|
||
| get(key: string) { | ||
| return this.headers[key.toLowerCase()]; | ||
| } | ||
|
|
||
| getHeaders() { | ||
| return this.headers; | ||
| } | ||
|
|
||
| set(key: string, value: any) { | ||
| this.headers[key.toLowerCase()] = value; | ||
| return this; | ||
| } | ||
|
|
||
| setHeader(key: string, value: any) { | ||
| this.headers[key.toLowerCase()] = value; | ||
| return this; | ||
| } | ||
|
|
||
| send(data: any) { | ||
| this.data = data; | ||
| } | ||
|
|
||
| json(data: any) { | ||
| this.data = data; | ||
| } | ||
|
|
||
| write(chunk: any) { | ||
| this.emit("data", chunk); | ||
| } | ||
|
|
||
| end(data: any) { | ||
| data !== undefined && (this.data = data); | ||
|
|
||
| this.emit("end"); | ||
| } | ||
| } |
Oops, something went wrong.