Batching with event buffers

While SSE is already performant and bandwidth-efficient, sending many events at a time by repeatedly calling Session#push can be wasteful as every call will initiate a full TCP round trip where the client must send acknowledgement packets back for every event it receives.

Event buffers improve this process by allowing you to batch and send multiple events in a single network transmission, greatly improving performance and lowering overall bandwidth usage.

Using the batch method

To batch and send multiple events at a time, simply invoke Session#batch method and pass a callback that takes an event buffer as its first argument:

server.ts

await session.batch(async (buffer) => {
    await buffer.iterate(["My", "huge", "event", "list"]);
});

You can use the same helper methods as you would with the session itself (push, stream and iterate) with the buffer.

When the callback finishes execution - or resolves if it returns a promise - every event created with the buffer will be sent to the client all at once in a single network transmission.

Note

Events created with event buffers do not use the underlying Session#push method and will not trigger the push event to be emitted on the session instance.

Create your own event buffer

You can also create an event buffer outside of the context of a single session and then write its contents to one or many sessions later on. To do so, create an event buffer and then pass it directly to the batch method:

server.ts

import { createEventBuffer } from "better-sse";

const buffer = createEventBuffer();

buffer.push("One");
buffer.push("Two");
buffer.push("Three");

session.batch(buffer);

Or send the buffer contents to every session on a channel, for example:

server.ts

channel.activeSessions.forEach((session) => {
    session.batch(buffer);
});

Sanitize your data

Keep in mind that, unless you explicitly pass them via the sanitizer and/or serializer constructor arguments, event buffers do not have the same data serializer and sanitizer functions as the session being called.

This does not apply when you use the Session#batch method as it will automatically copy the serializer and sanitizer from the session to the event buffer instance it creates for you.

Send individual event fields

For users needing more fine-grained control over the exact data being sent over the wire, event buffers also allow you to write raw spec-compliant SSE fields into a string that can be read and sent over the wire as-is.

server.ts

import { createEventBuffer } from "better-sse";

const buffer = createEventBuffer();

buffer
  .retry(2400)
  .event("my-event")
  .id("123")
  .data("one")
  .data("two")
  .data("three")
  .dispatch();

res.write(buffer.read());

buffer.clear();

This is an advanced use-case. For most users, you should still stick with using Session by default.