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 - prefer getLiveTimeline().getState(EventTimeline.FORWARDS).
Private Readonly filteredPrivate getPrivate getOptional lastPrivate 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 - prefer getLiveTimeline().getState(EventTimeline.BACKWARDS).
Private oldestPrivate Readonly optsConfiguration options
Private Optional Readonly pendingReadonly pollsReadonly reReadonly relationsReadonly roomRequired. The ID of this room.
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
The live event timeline for this room, with the oldest event at index 0. Present for backwards compatibility - prefer getLiveTimeline().getEvents()
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
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
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
Private addInternal
Add an event to the end of this room's live timelines. Will fire "Room.timeline".
Fires Timeline
Event to be added
addLiveEvent options
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.
If duplicateStrategy is not falsey, 'replace' or 'ignore'.
A list of events to add.
Optional addLiveEventOptions: IAddLiveEventOptionsaddLiveEvent options
In favor of the overload with IAddLiveEventOptions
Optional duplicateStrategy: DuplicateStrategyOptional fromCache: booleanAdd 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
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.
if the event doesn't have status SENDING, or we aren't given a unique transaction id.
Fires LocalEchoUpdated
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
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 calculated room name.
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.
Private checkPrivate cleanupPrivate 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
Rest ...args: Parameters<RoomEventHandlerMap[T]>Rest ...args: Parameters<RoomEventHandlerMap[T]>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
the given event, or undefined if unknown
event ID to look for
Find the predecessor of this room.
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).
if true, look for an m.room.predecessor state event and use it if found (MSC3946).
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 account_data event in question
the type of account_data event to be accessed
Get the avatar URL for a room if one was set.
the avatar URL or null.
The homeserver base URL. See 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)
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 we have received no read receipts from them.
ID of the latest event that the given user has read, or null.
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.
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 most recent unthreaded receipt for a given 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).
the MxID of the User
Get the live unfiltered timeline for this room.
live timeline
Get a member from the current room state.
The member or null.
The user ID of the member.
Get all currently loaded members from the current room state.
Room members
Get a list of members with given membership state.
A list of members with the given membership state.
The membership state.
Add a timelineSet for this room with the given filter
The timelineSet
The filter to be applied to this timelineSet
Configuration options
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 latest receipts of the chosen type for the chosen user
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
Get a list of receipts for the given event.
A list of receipts with a userId, type and data keys or an empty list.
the event to get receipts for
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 notification count, or undefined if there is no count for this type.
The type of notification count to get. default: 'total'
Private getGet one of the notification counts for a thread
The notification count, or undefined if there is no count for this type.
the root event ID
The type of notification count to get. default: 'total'
Get the timeline which contains the given event from the unfiltered set, if any
timeline containing the given event, or null if unknown
event ID to look for
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 notification count, or undefined if there is no count for this type.
The type of notification count to get. default: 'total'
Get a list of user IDs who have read up to the given event.
A list of user IDs.
the event to get read receipts for.
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.
Fires LocalEchoUpdated
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
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.
True if the user has read the event, false otherwise.
The user ID to check the read state of.
The event ID to check if the user read.
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
Private onPrivate onPrivate 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"
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 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().
Optional event: EventEmitterEvents | RoomEmittedEventsReset 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.
Fires LocalEchoUpdated
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.