Construct a new Room.
For a room, we store 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. 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.
Required. The ID of this room.
Required. The client, used to lazy load members.
Required. The ID of the syncing user.
Configuration options
accountData Dict of per-room account_data events; the keys are the event type and the values are the events.
ReadonlycachedReadonlyclientRequired. The client, used to lazy load members.
currentState The state of the room at the time of the newest event in the timeline.
ReadonlymyRequired. The ID of the syncing user.
The human-readable display name for this room.
The un-homoglyphed name for this room.
oldState The state of the room at the time of the oldest event in the live timeline.
ReadonlypollsReadonlyreReadonlyrelationsReadonlyroomRequired. The ID of this room.
The room summary.
Dict of room tags; the keys are the tag name and the values
are any metadata associated with the tag - e.g. { "fav" : { order: 1 } }
ReadonlythreadsEmpty array if the timeline sets have not been initialised. After initialisation: 0: All threads 1: Threads the current user has participated in
the notification count type for all the threads in the room
The live event timeline for this room, with the oldest event at index 0.
Update the account_data events for this room, overwriting events of the same type.
an array of account_data events to add
Adds/handles ephemeral events such as typing notifications and read receipts.
A list of events to process
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: stringtoken for the next batch of events
Fires RoomEvent.Timeline
Alias for on.
Add some events to this room. This can include state events, message events and typing notifications. These events are treated as "live" so they will go to the end of the timeline.
A list of events to add.
OptionaladdLiveEventOptions: IAddLiveEventOptionsaddLiveEvent options
Add a temporary local-echo receipt to the room to reflect in the client the fact that we've sent one.
The user ID if the receipt sender
The event that is to be acknowledged
The type of receipt
the receipt is unthreaded
Add a pending outgoing event to this room.
The event is added to either the pendingEventList, or the live timeline, depending on the setting of opts.pendingEventOrdering.
This is an internal method, intended for use by MatrixClient.
The event to add.
Transaction id for this outgoing event
Add a receipt event to the room.
The m.receipt event.
True if this event is implicit.
Update the room-tag event for the room. The previous one is overwritten.
the m.tag event
Add a new timeline to this room's unfiltered timeline set
newly-created timeline
Determine the order of two events in this room.
In principle this should use the same order as the server, but in practice this is difficult for events that were not received over the Sync API. See MSC4033 for details.
This implementation leans on the order of events within their timelines, and falls back to comparing event timestamps when they are in different timelines.
See https://github.com/matrix-org/matrix-js-sdk/issues/3325 for where we are tracking the work to fix this.
the id of the first event
the id of the second event
-1 if left < right, 1 if left > right, 0 if left == right, null if we can't tell (because we can't find the events).
Bulk decrypt critical events in a room
Critical events represents the minimal set of events to decrypt for a typical UI to function properly
Signals when all events have been decrypted
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<RoomEventHandlerMap[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<RoomEventHandlerMap[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<RoomEventHandlerMap[T]>Arguments to pass to the listener
true if the event had listeners, false otherwise.
Rest...args: Parameters<RoomEventHandlerMap[T]>Determine which timeline(s) a given event should live in Thread roots live in both the main timeline and their corresponding thread timeline Relations, redactions, replies to thread relation events live only in the thread timeline Relations (other than m.thread), redactions, replies to a thread root live only in the main timeline Relations, redactions, replies where the parent cannot be found live in no timelines but should be aggregated regardless. Otherwise, the event lives in the main timeline only.
Note: when a redaction is applied, the redacted event, events relating to it, and the redaction event itself, will all move to the main thread. This method classifies them as inside the thread of the redacted event. They are moved later as part of makeRedacted. This will change if MSC3389 is merged.
Optionalevents: MatrixEvent[]Optionalroots: Set<string>OptionalthreadGet an event which is stored in our unfiltered timeline set, or in a thread
event ID to look for
the given event, or undefined if unknown
Find the predecessor of this room.
if true, look for an m.room.predecessor state event and use it if found (MSC3946).
null if this room has no predecessor. Otherwise, returns the roomId, last eventId and viaServers of the predecessor room.
If msc3946ProcessDynamicPredecessor is true, use m.predecessor events as well as m.room.create events to find predecessors.
Note: if an m.predecessor event is used, eventId may be undefined since last_known_event_id is optional.
Note: viaServers may be undefined, and will definitely be undefined if this predecessor comes from a RoomCreate event (rather than a RoomPredecessor, which has the optional via_servers property).
Optionalevent: MatrixEventThis issue should also be addressed on synapse's side and is tracked as part of https://github.com/matrix-org/synapse/issues/14837
We consider a room fully read if the current user has sent the last event in the live timeline of that context and if the read receipt we have on record matches. This also detects all unread threads and applies the same logic to those contexts
Access account_data event of given event type for this room
the type of account_data event to be accessed
the account_data event in question
Get the avatar URL for a room if one was set.
The homeserver base URL. See MatrixClient#getHomeserverUrl.
The desired width of the thumbnail.
The desired height of the thumbnail.
The thumbnail resize method to use, either "crop" or "scale".
True to allow an identicon for this room if an avatar URL wasn't explicitly set. Default: true. (Deprecated)
the avatar URL or null.
Get the default room name (i.e. what a given user would see if the room had no m.room.name)
The userId from whose perspective we want to calculate the default name
The default room name
Get a list of members we should be encrypting for in this room
A list of members who we should encrypt messages for in this room.
Get the ID of the event that a given user has read up to, or null if:
(The event might not exist if it is not loaded, and the thread ID might not match if the event has moved thread because it was redacted.)
The user ID to get read receipt event ID for
If true, return only receipts that have been sent by the server, not implicit ones generated by the JS SDK.
ID of the latest existing event that the given user has read, or null.
Returns the history visibility based on the m.room.history_visibility state event, defaulting to shared.
the history_visibility applied to this room
Returns the history visibility based on the m.room.history_visibility state event, defaulting to shared.
the history_visibility applied to this room
Returns the number of joined members in this room This method caches the result. This is a wrapper around the method of the same name in roomState, returning its result for the room's current state.
The number of members in this room whose membership is 'join'
Get a list of members whose membership state is "join".
A list of currently joined members.
Returns the last live event of this room. "last" means latest timestamp. Instead of using timestamps, it would be better to do the comparison based on the order of the homeserver DAG. Unfortunately, this information is currently not available in the client. See https://github.com/matrix-org/matrix-js-sdk/issues/3325. "live of this room" means from all live timelines: the room and the threads.
MatrixEvent if there is a last event; else undefined.
Returns the last thread of this room. "last" means latest timestamp of the last thread event. Instead of using timestamps, it would be better to do the comparison based on the order of the homeserver DAG. Unfortunately, this information is currently not available in the client. See https://github.com/matrix-org/matrix-js-sdk/issues/3325.
the thread with the most recent event in its live time line. undefined if there is no thread.
Returns the most recent unthreaded receipt for a given user
the MxID of the User
an unthreaded Receipt. Can be undefined if receipts have been disabled or a user chooses to use private read receipts (or we have simply not received a receipt from this user yet).
Get the live unfiltered timeline for this room.
live timeline
Get a member from the current room state.
The user ID of the member.
The member or null.
Get all currently loaded members from the current room state.
Room members
Get a list of members with given membership state.
The membership state.
A list of members with the given membership state.
Add a timelineSet for this room with the given filter
The filter to be applied to this timelineSet
Configuration options
The timelineSet
Get a specific event from the pending event list, if configured, null otherwise.
The event ID to check for.
Get the list of pending sent events for this room
A list of the sent events waiting for remote echo.
Gets the latest receipt for a given user in the room
The id of the user for which we want the receipt
Whether to ignore synthesized receipts or not
Optional. The type of the receipt we want to get
the latest receipts of the chosen type for the chosen user
Get a list of receipts for the given event.
the event to get receipts for
A list of receipts with a userId, type and data keys or an empty list.
Determines the recommended room version for the room. This returns an
object with 3 properties: version as the new version the
room should be upgraded to (may be the same as the current version);
needsUpgrade to indicate if the room actually can be
upgraded (ie: does the current version not match?); and urgent
to indicate if the new version patches a vulnerability in a previous
version.
Resolves to the version the room should be upgraded to.
Get one of the notification counts for this room
The type of notification count to get. default: 'total'
The notification count, or undefined if there is no count for this type.
Get one of the notification counts for a thread
the root event ID
The type of notification count to get. default: 'total'
The notification count, or undefined if there is no count for this type.
Get the timeline which contains the given event from the unfiltered set, if any
event ID to look for
timeline containing the given event, or null if unknown
Return the timeline sets for this room.
array of timeline sets for this room
Helper to return the main unfiltered timeline set for this room
room's unfiltered timeline set
Get the notification for the event context (room or thread timeline)
Get one of the notification counts for this room
The type of notification count to get. default: 'total'
The notification count, or undefined if there is no count for this type.
Get a list of user IDs who have read up to the given event.
the event to get read receipts for.
A list of user IDs.
InternalDeal with the echo of a message we sent.
We move the event to the live timeline if it isn't there already, and update it.
The event received from /sync
The local echo, which should be either in the pendingEventList or the timeline.
Determines if the given user has read a particular event ID with the known history of the room. This is not a definitive check as it relies only on what is available to the room at the time of execution.
The user ID to check the read state of.
The event ID to check if the user read.
true if the user has read the event, false otherwise.
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.
Preloads the member list in case lazy loading of memberships is in use. Can be called multiple times, it will only preload once.
when preloading is done and accessing the members on the room will take all members in the room into account
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.
Process a list of poll events.
List of events
Adds events to a thread's timeline. Will fire "Thread.update"
Takes the given thread root events and creates threads for them.
Returns a copy of the array of listeners for the event named eventName,
including any wrappers (such as those created by .once()).
Recalculate various aspects of the room, including the room name and room summary. Call this any time the room's current state is modified. May fire "Room.name" if the room name is updated.
Fires RoomEvent.Name
Empty out the current live timeline and re-request it. This is used when
historical messages are imported into the room via MSC2716 /batch_send
because the client may already have that section of the timeline loaded.
We need to force the client to throw away their current timeline so that
when they back paginate over the area again with the historical messages
in between, it grabs the newly imported messages. We can listen for
UNSTABLE_MSC2716_MARKER, in order to tell when historical messages are ready
to be discovered in the room and the timeline needs a refresh. The SDK
emits a RoomEvent.HistoryImportedWithinTimeline event when we detect a
valid marker and can check the needs refresh status via
room.getTimelineNeedsRefresh().
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 | RoomEmittedEventsThe name of the event. If undefined, all listeners everywhere are removed.
a reference to the EventEmitter, so that calls can be chained.
Forget the timelineSet for this room with the given filter
the filter whose timelineSet is to be forgotten
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 of all timelineSets, and start new ones.
This is used when /sync returns a 'limited' timeline.
OptionalbackPaginationToken: null | stringtoken for back-paginating the new timeline
OptionalforwardPaginationToken: null | stringtoken for forward-paginating the old live timeline, if absent or null, all timelines are reset, removing old ones (including the previous live timeline which would otherwise be unable to paginate forwards without this token). Removing just the old live timeline whilst preserving previous ones is not supported.
Resets the total thread notifications for all threads in this room to zero,
excluding any threads whose IDs are given in exceptThreadIds.
If the room is not encrypted, also resets the highlight notification count to zero for the same set of threads.
This is intended for use from the sync code since we calculate highlight notification counts locally from decrypted messages. We want to partially trust the total from the server such that we clear notifications when read receipts arrive. The weird name is intended to reflect this. You probably do not want to use this.
The thread IDs to exclude from the reset.
Swet one of the notification count for a thread
the root event ID
The type of notification count to get. default: 'total'
Set one of the notification counts for this room
The type of notification count to set.
The new count
Update the status / event id on a pending event, to reflect its transmission progress.
This is an internal method.
local echo event
status to assign
OptionalnewEventId: stringnew event id to assign. Ignored unless newStatus == EventStatus.SENT.
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?