v0.7.0

Better SSE Version 0.7.0

npm install better-sse@latest

This release adds improved TypeScript typings and makes various improvements (including breaking changes) to the session and channel event push methods to more safely type their arguments.

This release is the precursor to the introduction of the new history API, and the changes here will make the interoperability with existing code and the new API much easier.

Changes

⚠ BREAKING: Session#push and Channel#broadcast arguments re-ordered

The Session push and Channel broadcast method arguments have been re-ordered to place the event data first and the event name second.

This is allows their arguments to be strongly typed, as before you were able to pass a non-serializable object to the event name argument as its type was only unknown, where it is now always string.

In addition, it also allows the Channel broadcast method event name to be an optional argument as the event name can now be differentiated from the event data.

// Before
session.push("Hello there!");
session.push("greeting", "Hello there!");

channel.broadcast("greeting", "Hello there!");

// After
session.push("Hello there!");
session.push("Hello there!", "greeting");

channel.broadcast("Hello there!");
channel.broadcast("Hello there!", "greeting");

⚠ BREAKING: Channel#broadcast filter option now explicitly requires a boolean to be returned

The Channel broadcast method filter option explicitly now requires a boolean to be returned instead of allowing any value with unknown.

Session#state global type interface

The Session State generic argument now defaults to an exported SessionState interface that can be augmented via declaration merging.

This is now the recommended way to add typings for the Session#state property as it works globally across your application, even without a reference to the original session object.

// Before
const channel = createChannel();

...

const session = createSession<{isTrusted: boolean}>(req, res);

session.state.isTrusted = true; // 'boolean'

channel.register(session);

channel.broadcast("A new user joined.", "join-notification", {
	filter: (session) => session.state.isTrusted // Error: Type 'unknown' is not assignable to type 'boolean'
});

// After
declare module "better-sse" {
	interface SessionState {
		isTrusted: boolean;
	}
}

const channel = createChannel();

...

const session = createSession(req, res);

session.state.isTrusted = true; // Still 'boolean'

channel.register(session);

channel.broadcast("A new user joined.", "join-notification", {
	filter: (session) => session.state.isTrusted // Works!
});

Session push custom event ID

You can now specify a custom event ID as an optional third argument to the Session#push method.

Note that it is still recommended to allow the library to generate its own event IDs instead of doing it yourself as their uniqueness is guaranteed. This argument is mostly intended to be used internally, though it is exposed to the user as a matter of convenience if you have a more advanced use-case.

// Before
session.push("Hello there!", "greeting"); // Auto-generated ID

// After
session.push("Hello there!", "greeting", "my-unique-id-1");

New Session push event

Similar to channels, sessions will now emit a push event each time a new event is sent with the push method.

session.on("push", (data: unknown, eventName: string, eventId: string) => {});

Optional Channel#broadcast event name argument

The Channel broadcast method eventName argument is now optional and will default to "message" if not given.

// Before
channel.broadcast("Hello there!"); // Error: Expected 2-3 arguments, but got 1.

// After
channel.broadcast("Hello there!"); // Works!

Full Changelog

Added

• Added the ability to the Session#push method to set a custom event ID.
• Added a new Session push event that is emitted with the event data, name and ID when the Session#push method is called.
• Added the Channel#state property to have a safe namespace for keeping information attached to the channel.

Changed

• Update the arguments for the Session#push and Channel#broadcast methods and their corresponding emitted event callbacks to always have the event data first and event name as an optional argument second.
• Update the Channel#broadcast method options TypeScript typings to explicitly mandate a boolean return-type instead of allowing any truthy or falsy value.
• Update the Channel#broadcast method event name argument to be optional and default to "message" if not given.
• Update the Session#state generic argument to default to a new SessionState interface that can be augmented via declaration merging to override the session state type for all session objects without explicitly providing a generic argument to each reference to Session.
• Rename the Session and Channel Events interfaces to SessionEvents and ChannelEvents respectively and export them publicly allowing the user to properly type non-inlined event handler callback functions.