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.
Private Optional blacklistReadonly cachedReadonly clientRequired. The client, used to lazy load members.
currentState The state of the room at the time of the newest event in the timeline.
Present for backwards compatibility. Use getLiveTimeline().getState(EventTimeline.FORWARDS) instead.
Private Readonly filteredPrivate getPrivate getOptional lastThis value is unreliable. It may not contain the last thread. Use Room.getLastThread instead.
Private Optional membersReadonly myRequired. The ID of the syncing user.
The human-readable display name for this room.
The un-homoglyphed name for this room.
Private notificationoldState The state of the room at the time of the oldest event in the live timeline.
Present for backwards compatibility. Use getLiveTimeline().getState(EventTimeline.BACKWARDS) instead
Private oldestPrivate Readonly optsConfiguration options
Private Optional Readonly pendingReadonly pollsReadonly reReadonly relationsReadonly roomRequired. The ID of this room.
Private roomThe latest receipts (synthetic and real) for each user in each thread (and unthreaded).
Private Optional selfThe room summary.
Private summaryDict of room tags; the keys are the tag name and the values
are any metadata associated with the tag - e.g. { "fav" : { order: 1 } }
Private Readonly threadPrivate threadPrivate threadsA collection of events known by the client This is not a comprehensive list of the threads that exist in this room
Private threadsReadonly threadsEmpty array if the timeline sets have not been initialised. After initialisation: 0: All threads 1: Threads the current user has participated in
Private timelinePrivate Readonly timelinePrivate txnPrivate unthreadedA record of the latest unthread receipts per user This is useful in determining whether a user has read a thread or not
Private Experimental visibilityA mapping of eventId to all visibility changes to apply to the event, by chronological order, as per https://github.com/matrix-org/matrix-doc/pull/3531
asVisibilityEvent() returns a non-null IVisibilityChange;eventId, all events
are in relation to eventId.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.
Present for backwards compatibility. Use getLiveTimeline().getEvents() instead
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.
Optional paginationToken: stringtoken for the next batch of events
Fires RoomEvent.Timeline
Alias for TypedEventEmitter#on.
Private addInternal Add an event to the end of this room's live timelines. Will fire "Room.timeline".
Event to be added
addLiveEvent options
Fires RoomEvent.Timeline
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.
Optional addLiveEventOptions: IAddLiveEventOptionsaddLiveEvent options
If duplicateStrategy is not falsey, 'replace' or 'ignore'.
Optional duplicateStrategy: DuplicateStrategyOptional fromCache: booleanIn favor of the overload with IAddLiveEventOptions
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
if the event doesn't have status SENDING, or we aren't given a unique transaction id.
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
Private addAdd a new timeline to this room's unfiltered timeline set
newly-created timeline
Private aggregateUsed to aggregate the local echo for a relation, and also for re-applying a relation after it's redaction has been cancelled, as the local echo for the redaction of the relation would have un-aggregated the relation. Note that this is different from regular messages, which are just kept detached for their local echo.
Also note that live events are aggregated in the live EventTimelineSet.
the relation event that needs to be aggregated.
Private applyWhen we receive a new visibility change event:
Private applyWhen we receive an event whose visibility has been altered by a (more recent) visibility change event, patch the event in place so that clients now not to display it.
Any matrix event. If this event has at least one a pending visibility change event, apply the latest visibility change event.
Private applyPrivate calculateThis is an internal method. Calculates the name of the room from the current room state.
The client's user ID. Used to filter room members correctly.
Return the implicit room name that we'd see if there was no m.room.name event.
The calculated room name.
Private checkPrivate cleanupDetermine 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).
Private createOptional filterType: ThreadFilterTypeBulk 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.
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.
Optional events: MatrixEvent[]Optional roots: Set<string>Optional threadPrivate fetchInternal Fetch a single page of threadlist messages for the specific thread filter
Optional filter: ThreadFilterTypeGet 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).
Optional event: MatrixEventPrivate findGiven some events, find the IDs of all the thread roots that are referred to by them.
Private fixThis 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 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.
If opts.pendingEventOrdering was not 'detached'
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.
Private getGet 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.
Internal Deal 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.
Returns whether there are any devices in the room that are unverified
Note: Callers should first check if crypto is enabled on this device. If it is disabled, then we aren't tracking room devices at all, so we can't answer this, and an error will be thrown.
the result
Not supported under rust crypto. Instead, call Room.getEncryptionTargetMembers, CryptoApi.getUserDeviceInfo, and CryptoApi.getDeviceVerificationStatus.
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.
Private loadPrivate loadPreloads 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 TypedEventEmitter#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 TypedEventEmitter#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.
Private onPrivate onPrivate onAdds 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 TypedEventEmitter#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.
Private processPrivate processProcesses poll events:
If the event has a decryption failure, it will listen for decryption and tries again.
If it is a poll start event (m.poll.start),
it creates and stores a Poll model and emits a PollEvent.New event.
If the event is related to a poll, it will add it to the poll.
Noop for other cases.
Event that could be a poll event
Calls processPollEvent for a list of events.
List of events
Takes the given thread root events and creates threads for them.
Adds events to a thread's timeline. Will fire "Thread.update"
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
Private redactEmpty 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).
Optional event: 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.
Optional backPaginationToken: null | stringtoken for back-paginating the new timeline
Optional forwardPaginationToken: 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.
Private revertPrivate roomPrivate savePersists all pending events to local storage
If the current room is encrypted only encrypted events will be persisted all messages that are not yet encrypted will be discarded
This is because the flow of EVENT_STATUS transition is
queued => sending => encrypting => sending => sent
Steps 3 and 4 are skipped for unencrypted room. It is better to discard an unencrypted message rather than persisting it locally for everyone to read
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
Optional newEventId: stringnew event id to assign. Ignored unless newStatus == EventStatus.SENT.
Private updatePrivate updateGenerated using TypeDoc
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?