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.
addLiveEvent 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
Returns whether the given user has permissions to issue an invite for this room.
the ID of the Matrix user to check permissions for
true if the user should be permitted to issue invites for this room.
Removes the lazily loaded members from storage if needed
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
Arguments to pass to the listener
true if the event had listeners, false otherwise.
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
Arguments to pass to the listener
true if the event had listeners, false otherwise.
Similar to emit but calls all listeners within a Promise.all and returns the promise chain
The name of the event to emit
Arguments to pass to the listener
true if the event had listeners, false otherwise.
Similar to emit but calls all listeners within a Promise.all and returns the promise chain
The name of the event to emit
Arguments to pass to the listener
true if the event had listeners, false otherwise.
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>Fetch the bare minimum of room threads required for the thread list to work reliably. With server support that means fetching one page. Without server support that means fetching as much at once as the server allows us to.
Get 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 this room's alternative aliases
The room's alternative aliases, or an empty array
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)
(optional) If true, the caller supports authenticated media and wants an authentication-required URL. Note that server support for authenticated media will not be checked - it is the caller's responsibility to do so before calling this function. Note also that useAuthentication implies allowRedirects. Defaults to false (unauthenticated endpoints).
the avatar URL or null.
Whether to send encrypted messages to devices within this room.
true if blacklisting unverified devices, null if the global value should be used for this room.
Get this room's canonical alias The alias returned by this function may not necessarily still point to this room.
The room's canonical alias, or null if there is none
Gets the creator of the room
The creator of the room, or null if it could not be determined
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
If this room is a DM we're invited to, try to find out who invited us
user id of the inviter
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 invited + joined members in this room
The number of members in this room whose membership is 'invite' or 'join'
Returns the number of invited members in this room
The number of members in this room whose membership is 'invite'
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 join rule based on the m.room.join_rule state event, defaulting to invite.
the join_rule applied to this room
Get the timestamp of the last message in the room
the timestamp of the last message in the room
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 a member from the current room state.
The user ID of the member.
The member or null.
Get a list of members with given membership state.
The membership state.
A list of members with the given membership state.
Get the mxc avatar url for the room, if one was set.
the mxc avatar url or falsy
the membership type (join | leave | invite | knock) for the logged in user
Find when a client has gained thread capabilities by inspecting the oldest threaded receipt
the timestamp of the oldest threaded receipt
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 the instance of the thread associated with the current event
the ID of the current event
a thread instance if known
Get all the known threads in the room
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
Whether the timeline needs to be refreshed in order to pull in new historical messages that were imported.
.
Return the timeline sets for this room.
array of timeline sets for this room
Returns the type of the room from the m.room.create event content or undefined if none is set
the type of the 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.
Gets the version of the room
The version of the room, or null if it could not be determined
Assuming this room is a DM room, tries to guess with which user.
user id of the other member (could be syncing user)
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.
Return true if this room has an m.room.encryption state event.
If this returns true, events sent to this room should be encrypted (and MatrixClient.sendEvent and friends
will encrypt outgoing events).
Check if the given user_id has the given membership state.
The user ID to check.
The membership e.g. 'join'
True if this user_id has the given membership state.
Check whether the pending event list contains a given event by ID. If pending event ordering is not "detached" then this returns false.
The event ID to check for.
Checks if the current room has unread thread notifications
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 whether the room is a call-room as defined by MSC3417.
true if the room's type is RoomType.UnstableCall
Returns whether the room is a video room.
true if the room's type is RoomType.ElementVideo
Returns whether the room is a space-room as defined by MSC1772.
true if the room's type is RoomType.Space
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
Returns whether the syncing user has permission to send a message in the room
true if the user should be permitted to send message events into the room.
Check if loading of out-of-band-members has completed
true if the full membership list of this room has been loaded (including if lazy-loading is disabled). False if the load is not started or is in progress.
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.
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.
Removes a single event from this room.
The id of the event to remove
true if the event was removed from any of the room's timeline sets
Removes events from this room.
A list of eventIds to remove.
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.
Removes a pending event for this room
True if an element was removed.
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.
Whether to send encrypted messages to devices within this room.
true to blacklist unverified devices, null to use the global value for this room.
Swet one of the notification count for a thread
the root event ID
The type of notification count to get. default: 'total'
Whether the timeline needs to be refreshed in order to pull in new historical messages that were imported.
The value to set
Set one of the notification counts for this room
The type of notification count to set.
The new count
Determine whether we should encrypt messages for invited users in this room
if we should encrypt messages for invited users
Sets the membership this room was received as during sync
join | leave | invite
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.
Determines whether the given user is permitted to perform a room upgrade
The ID of the user to test against
True if the given user is permitted to upgrade the room
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?