Construct a set of EventTimeline objects, typically on behalf of a given room. A room may have multiple EventTimelineSets for different levels of filtering. The global notification list is also an EventTimelineSet, but lacks a room.
This is an ordered sequence of timelines, which may or may not be continuous. Each timeline lists a series of events, as well as tracking the room state at the start and the end of the timeline (if appropriate). It also tracks forward and backward pagination tokens, as well as containing links to the next timeline in the sequence.
There is one special timeline - the 'live' timeline, which represents the timeline to which events are being added in real-time as they are received from the /sync API. Note that you should not retain references to this timeline - even if it is the current timeline right now, it may not remain so if the server gives us a timeline gap in /sync.
In order that we can find events from their ids later, we also maintain a map from event_id to timeline and index.
Room for this timelineSet. May be null for non-room cases, such as the notification timeline.
Options inherited from Room.
Optionalclient: MatrixClientthe Matrix client which owns this EventTimelineSet, can be omitted if room is specified.
Optionalthread: Threadthe thread to which this timeline set relates.
the type of thread list represented, if any (e.g., All threads or My threads)
ReadonlyrelationsReadonlyroomRoom for this timelineSet. May be null for non-room cases, such as the notification timeline.
Optional Readonlythreadthe thread to which this timeline set relates.
Readonlythreadthe type of thread list represented, if any (e.g., All threads or My threads)
Add events to a timeline
Will fire "Room.timeline" for each event added.
A list of events to add.
True to add these events to the start (oldest) instead of the end (newest) of the timeline. If true, the oldest event will be the last element of 'events'.
timeline to add events to.
OptionalpaginationToken: null | stringtoken for the next batch of events
Fires RoomEvent.Timeline
Add event to the given timeline, and emit Room.timeline. Assumes we have already checked we don't know about this event.
Will fire "Room.timeline" for each event added.
the event to add
the timeline onto which to add it
addEventToTimeline options
Fires RoomEvent.Timeline
OptionalfromCache: booleanOptionalroomState: RoomStateAlias for on.
Add an event to the end of this live timeline.
Event to be added
addLiveEvent options
Add a new timeline to this timeline list
newly-created timeline
Determine whether a given event can sanely be added to this event timeline set,
for timeline sets relating to a thread, only return true for events in the same
thread timeline, for timeline sets not relating to a thread only return true
for events which should be shown in the main room timeline.
Requires the room property to have been set at EventTimelineSet construction time.
the event to check whether it belongs to this timeline set.
whether the event belongs to this timeline set.
Determine where two events appear in the timeline relative to one another
The id of the first event
The id of the second event
-1 if eventId1 precedes eventId2, and +1 eventId1 succeeds eventId2. 0 if they are the same event; null if we can't tell (either because we don't know about one of the events, or because they are in separate timelines which don't join up).
Synchronously calls each of the listeners registered for the event named
event, in the order they were registered, passing the supplied arguments
to each.
The name of the event to emit
Rest...args: Parameters<EventTimelineSetHandlerMap[T]>Arguments to pass to the listener
true if the event had listeners, false otherwise.
Synchronously calls each of the listeners registered for the event namedeventName, in the order they were registered, passing the supplied arguments
to each.
Returns true if the event had listeners, false otherwise.
import EventEmitter from 'node:events';
const myEmitter = new EventEmitter();
// First listener
myEmitter.on('event', function firstListener() {
console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
const parameters = args.join(', ');
console.log(`event with parameters ${parameters} in third listener`);
});
console.log(myEmitter.listeners('event'));
myEmitter.emit('event', 1, 2, 3, 4, 5);
// Prints:
// [
// [Function: firstListener],
// [Function: secondListener],
// [Function: thirdListener]
// ]
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener
Rest...args: Parameters<EventTimelineSetHandlerMap[T]>Similar to emit but calls all listeners within a Promise.all and returns the promise chain
The name of the event to emit
Rest...args: Parameters<EventTimelineSetHandlerMap[T]>Arguments to pass to the listener
true if the event had listeners, false otherwise.
Rest...args: Parameters<EventTimelineSetHandlerMap[T]>Return the timeline (if any) this event is in.
the eventId being sought
timeline
Get an event which is stored in our timelines
event ID to look for
the given event, or undefined if unknown
Get the live timeline for this room.
live timeline
Get the list of pending sent events for this timelineSet's room, filtered by the timelineSet's filter if appropriate.
A list of the sent events waiting for remote echo.
Get the timeline which contains the given event, if any
OptionaleventId: stringevent ID to look for
timeline containing the given event, or null if unknown
Get all the timelines in this set
the timelines in this set
Replaces event with ID oldEventId with one with newEventId, if oldEventId is recognised. Otherwise, add to the live timeline. Used to handle remote echos.
the new event to be added to the timeline
the ID of the original event
the ID of the replacement event
Fires RoomEvent.Timeline
InternalInsert event to the given timeline, and emit Room.timeline. Assumes we have already checked we don't know about this event.
TEMPORARY: until we have recursive relations, we need this function to exist to allow us to insert events in timeline order, which is our best guess for Sync Order. This is a copy of addEventToTimeline above, modified to insert the event after the event it relates to, and before any event with a later timestamp. This is our best guess at Sync Order.
Will fire "Room.timeline" for each event added.
Fires RoomEvent.Timeline
Returns the number of listeners listening to the event named event.
The name of the event being listened for
Returns a copy of the array of listeners for the event named event.
Alias for removeListener
Adds the listener function to the end of the listeners array for the
event named event.
No checks are made to see if the listener has already been added. Multiple calls
passing the same combination of event and listener will result in the listener
being added, and called, multiple times.
By default, event listeners are invoked in the order they are added. The prependListener method can be used as an alternative to add the event listener to the beginning of the listeners array.
The name of the event.
The callback function
a reference to the EventEmitter, so that calls can be chained.
Adds a one-time listener function for the event named event. The
next time event is triggered, this listener is removed and then invoked.
Returns a reference to the EventEmitter, so that calls can be chained.
By default, event listeners are invoked in the order they are added. The prependOnceListener method can be used as an alternative to add the event listener to the beginning of the listeners array.
The name of the event.
The callback function
a reference to the EventEmitter, so that calls can be chained.
Adds the listener function to the beginning of the listeners array for the
event named event.
No checks are made to see if the listener has already been added. Multiple calls
passing the same combination of event and listener will result in the listener
being added, and called, multiple times.
The name of the event.
The callback function
a reference to the EventEmitter, so that calls can be chained.
Adds a one-timelistener function for the event named event to the beginning of the listeners array.
The next time event is triggered, this listener is removed, and then invoked.
The name of the event.
The callback function
a reference to the EventEmitter, so that calls can be chained.
Returns a copy of the array of listeners for the event named eventName,
including any wrappers (such as those created by .once()).
Removes all listeners, or those of the specified event.
It is bad practice to remove listeners added elsewhere in the code,
particularly when the EventEmitter instance was created by some other
component or module (e.g. sockets or file streams).
Optionalevent: EventEmitterEvents | EmittedEventsThe name of the event. If undefined, all listeners everywhere are removed.
a reference to the EventEmitter, so that calls can be chained.
Removes a single event from this room.
The id of the event to remove
the removed event, or null if the event was not found in this room.
Removes the specified listener from the listener array for the event named event.
a reference to the EventEmitter, so that calls can be chained.
Reset the live timeline, and start a new one.
This is used when /sync returns a 'limited' timeline.
OptionalbackPaginationToken: stringtoken for back-paginating the new timeline
OptionalforwardPaginationToken: stringtoken for forward-paginating the old live timeline, if absent or null, all timelines are reset.
Fires RoomEvent.TimelineReset
Set the filter object this timeline set is filtered on (passed to the server when paginating via /messages).
Optionalfilter: Filterthe filter for this timelineSet
Set the live timeline for this room.
live timeline
Typed Event Emitter class which can act as a Base Model for all our model and communication events. This makes it much easier for us to distinguish between events, as we now need to properly type this, so that our events are not stringly-based and prone to silly typos.
Type parameters:
Events- List of all events emitted by thisTypedEventEmitter. Normally an enum type.Arguments- A ListenerMap type providing mappings from event names to listener types.SuperclassArguments- TODO: not really sure. Alternative listener mappings, I think? But only honoured for.emit?