Events

Events are an efficient way to send events from Endpoints that clients can handle. This feature, in effect, lets Endpoints call client-side code.

Roli Events are an implementation of Server-Sent-Events.

Event flow: 1 Callable to n Clients

Events are sent from inside Callables to any number of subscribed clients.

Properties

Events can contain any number of JavaScript properties with any name.

Data Types

Most built-in JavaScript property types are supported including:

undefined
null
number
boolean
object
Map
Set
Array
Date
BigInt
types that extend Data
types that extend Endpoint
types that extend Session

Creating a new Event

To create a Event you write a POJO that extends the Event base type in service code. The Event type is imported from the provided roli-runtime library.

// Service code
import {Event} from 'roli-runtime';
export class MyEvent extends Event {
    constructor(public myValue: string) {
        super();
    }
}

This creates an Event that contains a single property. When this Event is fired, its properties go with it to any clients who are subscribed. The constructor can take any number of arguments.

Transient

Events do not have a primaryKey because they’re never stored in the database. They’re meant to be instanciated, sent, and discarded but never saved or persisted.

Firing an Event

You create new Events using the new operator and use the fireEvent function from the roli-runtime library to send the event.

// Service code
import {fireEvent, Event, Endpoint} from 'roli-runtime';
export class MyEvent extends Event {
    constructor(public myValue: string) {
        super();
    }
}
export class MyEndpoint extends Endpoint {
    constructor(key: string) {
        super(key);
    }
    doSomething() {
        fireEvent(this, new MyEvent("foo"));
    }
}

The first argument is the source, this can be either a Data element instance, or a Callable instance. In this example, this is the MyEndpoint instance. The second argument is the Event instance you want to send.

Subscribing to Events

To subscribe to receive events in client-code you use the subscribeEvent RoliClient method.

// Client code
import {MyEndpoint, MyEvent, createRoliClient} from "my-service";
const roli = createRoliClient();
const myEndpoint = roli.getEndpoint(MyEndpoint, "default");
await roli.subscribeEvent(myEndpoint, MyEvent, (msg: MyEvent) => {
        console.log(`${msg.myValue}`);
    });

The first argument is the source. This must match the source passed to the fireEvent call. In this case it’s a MyEndpoint instance. The second argument is the Event derived type you’d like to subscribe to. The third argument is a callback function that takes an instance of the Event derived type that gets called when new events are received.

Event Source

The source argument lets clients listen for Events coming from different Endpoints, Sessions, or Data elements. For instance, if you had two different ApiEndpoint instances (with different primaryKeys), you could listen for MyEvent events from one and not the other by specifying a different source.

Unsubscribing from Events

It’s a good idea to unsubscribe from Events when you no longer need them. A good place to do this in a UI is your page’s tear-down logic.

Unsubscribe from an Event using the unsubscribeEvent RoliClient method.

// Client code
//...
await roli.unsubscribeEvent(myEndpoint, MyEvent);

The first argument is the source. This must match the source used when subscribing. The second argument is the Event dervied type.

Automatic Subscription Cleanup

Roli will automatically delete all your Event subscriptions shortly after the RoliClient object is collected by the client’s Garbage Collector.