river.ts

Easy, Composable, and type-safe Server-Sent Events (SSE)

Server-Side Events
Bewinxed/river.tsriver.ts

README

00171-1636846244

🌊 river.ts | ✨ Composable, Typesafe SSE Events


river.ts is a Based library for handling server-sent events (SSE) in TypeScript. It allows you to build a common interface for events, then call it from one place Both on server and client.
Currently compatible with express-like backends.

🌟 Features

- 💡 Easy-to-use API for subscribing to and handling events
- 🔄 Automatic reconnection with configurable delay
- 🔌 Works with GET & Other HTTP Methods along with custom headers, body, etc...
- 🛠️ Event listeners for events, with typesafe event handlers.

📦 Installation

Bun

  1. ```bash
  2. bun install river.ts
  3. ```

NPM (why tho)

  1. ```bash
  2. npm install river.ts
  3. ```

🚀 Usage

🏗 Build your event map

Chain commands together to build a map of events, you can add the types as type arguments or function arguments.
  1. ```typescript
  2. import { RiverEvents } from 'river.ts';

  4. const events = new RiverEvents()
  5. .map_event("ping", {
  6.   message: "pong",
  7. })
  8. .map_event("payload", {
  9.   data: [
  10.    { id: 1, name: "Alice" },
  11.    { id: 2, name: "Bob" },
  12.   ],
  13. }).build()
  14. ```

🌠 On the Server

  1. ```typescript
  2. import { RiverEmitter } from 'river.ts/server';
  3. import {events} from './events';

  5. // init the server
  6. const server = RiverEmitter.init(events)

  8. // Then, use .stream() as body init it using the `Response` object of your framework
  9. function GET(req: Request) {
  10. return new Response(
  11.   server.stream((emitter) => {
  12.    // do stuff
  13.    // emit simple text message
  14.    emitter.emit_event("ping", { message: "pong" });

  16.    // do more stuff
  17.    // emit complex json data
  18.    emitter.emit_event("payload", {
  19.     // type safe data
  20.     data: [
  21.      { id: 1, name: "Alice" },
  22.      { id: 2, name: "Bob" },
  23.     ],
  24.    });
  25.   }),
  26.   {
  27.    // convenience method to set headers for text/event-stream
  28.    headers:
  29.     server.headers(
  30.      // optional, set your headers
  31.     ),
  32.   },
  33. );
  34. }
  35. ```

🚀 On the client

  1. ```typescript
  2. import { RiverClient } from 'river.ts/client';
  3. import {events} from './events';

  5. // On the client
  6. const client = RiverClient.init(events)

  8. await client
  9. // add url, method, headers, etc (GET/POST/Etc, all work)
  10. .prepare("http://localhost:3000/events", {
  11.   // custom headers
  12.   method: "POST",
  13.   body: JSON.stringify({}),
  14. })
  15. // add event listeners
  16. .on("ping", (res) => {
  17.   console.log("on data", res);
  18.   // typeof res
  19.   // {
  20.   //  message: string;
  21.   //  type: "ping";
  22.   // }
  23. })
  24. // add more event listeners
  25. .on("payload", (res) => {
  26.   console.log("on data", res);
  27.   // typeof res
  28.   // {
  29.   //  data: {
  30.   //   id: number;
  31.   //   name: string;
  32.   //  }[];
  33.   //  type: "payload";
  34.   // };
  35.   if (!res.data) {
  36.    // you can close it anytime if you assign it to a constant beforehand
  37.    client.close();
  38.   }
  39. })
  40. // start the stream
  41. .stream();
  42. ```

🔍 Type Safety

After building the event map, You can either use typeof events.{event} or use the type InferEventType with the event name
  1. ```typescript
  2. import { InferEventType } from 'river.ts';

  4. const events = ....build()
  5. type Events = typeof events
  6. type PingEvent = InferEventType<Events, "ping">;
  7. // {
  8. //  message: string;
  9. //  type: "ping";
  10. // }

  12. const events: PingEvent[] = []

  14. // then you can push to it if you want and the types will be ok
  15. events.push({
  16. message: "pong",
  17. type: "ping",
  18. })
  19. ```

🎉 Contributing

Contributions are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request.

📄 License

Don't be a bozo