Class: module:models/room

module:models/room

new module:models/room(roomId, optsopt)

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.

Parameters:
Name Type Attributes Description
roomId string Required. The ID of this room.
opts Object <optional>
Configuration options
Properties
Name Type Attributes Default Description
storageToken * Optional. The token which a data store can use to remember the state of the room. What this means is dependent on the store implementation.
pendingEventOrdering String <optional>
Controls where pending messages appear in a room's timeline. If "chronological", messages will appear in the timeline when the call to sendEvent was made. If "detached", pending messages will appear in a separate list, accessbile via module:models/room#getPendingEvents. Default: "chronological".
timelineSupport boolean <optional>
false Set to true to enable improved timeline support.
Properties:
Name Type Description
roomId string The ID of this room.
name string The human-readable display name for this room.
timeline Array.<MatrixEvent> The live event timeline for this room, with the oldest event at index 0. Present for backwards compatibility - prefer getLiveTimeline().getEvents().
tags object 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 } }
accountData object Dict of per-room account_data events; the keys are the event type and the values are the events.
oldState RoomState The state of the room at the time of the oldest event in the live timeline. Present for backwards compatibility - prefer getLiveTimeline().getState(true).
currentState RoomState The state of the room at the time of the newest event in the timeline. Present for backwards compatibility - prefer getLiveTimeline().getState(false).
summary RoomSummary The room summary.
storageToken * A token which a data store can use to remember the state of the room.
Source:

Methods

_addLocalEchoReceipt(userId, e, receiptType)

Add a temporary local-echo receipt to the room to reflect in the client the fact that we've sent one.
Parameters:
Name Type Description
userId string The user ID if the receipt sender
e MatrixEvent The event that is to be acknowledged
receiptType string The type of receipt
Source:

_addReceiptsToStructure(event, receipts)

Add a receipt event to the room.
Parameters:
Name Type Description
event MatrixEvent The m.receipt event.
receipts Object The object to add receipts to
Source:

_buildReceiptCache(receipts) → {Object}

Build and return a map of receipts by event ID
Parameters:
Name Type Description
receipts Object A map of receipts
Source:
Returns:
Map of receipts by event ID
Type
Object

addAccountData(events)

Update the account_data events for this room, overwriting events of the same type.
Parameters:
Name Type Description
events Array.<MatrixEvent> an array of account_data events to add
Source:

addEventsToTimeline(events, toStartOfTimeline, timeline, paginationTokenopt)

Add events to a timeline

Will fire "Room.timeline" for each event added.

Parameters:
Name Type Attributes Description
events Array.<MatrixEvent> A list of events to add.
toStartOfTimeline boolean 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 module:models/event-timeline~EventTimeline timeline to add events to.
paginationToken string <optional>
token for the next batch of events
Source:
Fires:
  • module:client~MatrixClient#event:"Room.timeline"

addLiveEvents(events, duplicateStrategy)

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.
Parameters:
Name Type Description
events Array.<MatrixEvent> A list of events to add.
duplicateStrategy string Optional. Applies to events in the timeline only. If this is 'replace' then if a duplicate is encountered, the event passed to this function will replace the existing event in the timeline. If this is not specified, or is 'ignore', then the event passed to this function will be ignored entirely, preserving the existing event in the timeline. Events are identical based on their event ID only.
Source:
Throws:
If duplicateStrategy is not falsey, 'replace' or 'ignore'.

addPendingEvent(event, txnId)

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.

Parameters:
Name Type Description
event module:models/event.MatrixEvent The event to add.
txnId string Transaction id for this outgoing event
Source:
Fires:
  • module:client~MatrixClient#event:"Room.localEchoUpdated"
Throws:
if the event doesn't have status SENDING, or we aren't given a unique transaction id.

addReceipt(event, fake)

Add a receipt event to the room.
Parameters:
Name Type Description
event MatrixEvent The m.receipt event.
fake Boolean True if this event is implicit
Source:

addTags(event)

Update the room-tag event for the room. The previous one is overwritten.
Parameters:
Name Type Description
event MatrixEvent the m.tag event
Source:

addTimeline() → {module:models/event-timeline~EventTimeline}

Add a new timeline to this room's unfiltered timeline set
Source:
Returns:
newly-created timeline
Type
module:models/event-timeline~EventTimeline

findEventById(eventId) → (nullable) {module:models/event.MatrixEvent}

Get an event which is stored in our unfiltered timeline set
Parameters:
Name Type Description
eventId string event ID to look for
Source:
Returns:
the given event, or undefined if unknown
Type
module:models/event.MatrixEvent

getAccountData(type) → (nullable) {MatrixEvent}

Access account_data event of given event type for this room
Parameters:
Name Type Description
type string the type of account_data event to be accessed
Source:
Returns:
the account_data event in question
Type
MatrixEvent

getAliases() → {array}

Get the aliases this room has according to the room's state The aliases returned by this function may not necessarily still point to this room.
Source:
Returns:
The room's alias as an array of strings
Type
array

getAvatarUrl(baseUrl, width, height, resizeMethod, allowDefault) → (nullable) {string}

Get the avatar URL for a room if one was set.
Parameters:
Name Type Description
baseUrl String The homeserver base URL. See module:client~MatrixClient#getHomeserverUrl.
width Number The desired width of the thumbnail.
height Number The desired height of the thumbnail.
resizeMethod string The thumbnail resize method to use, either "crop" or "scale".
allowDefault boolean True to allow an identicon for this room if an avatar URL wasn't explicitly set. Default: true.
Source:
Returns:
the avatar URL or null.
Type
string

getCanonicalAlias() → (nullable) {string}

Get this room's canonical alias The alias returned by this function may not necessarily still point to this room.
Source:
Returns:
The room's canonical alias, or null if there is none
Type
string

getDefaultRoomName(userId) → {string}

Get the default room name (i.e. what a given user would see if the room had no m.room.name)
Parameters:
Name Type Description
userId string The userId from whose perspective we want to calculate the default name
Source:
Returns:
The default room name
Type
string

getEventReadUpTo(userId, ignoreSynthesized) → {String}

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.
Parameters:
Name Type Description
userId String The user ID to get read receipt event ID for
ignoreSynthesized Boolean If true, return only receipts that have been sent by the server, not implicit ones generated by the JS SDK.
Source:
Returns:
ID of the latest event that the given user has read, or null.
Type
String

getJoinedMembers() → {Array.<RoomMember>}

Get a list of members whose membership state is "join".
Source:
Returns:
A list of currently joined members.
Type
Array.<RoomMember>

getLiveTimeline() → {module:models/event-timeline~EventTimeline}

Get the live unfiltered timeline for this room.
Source:
Returns:
live timeline
Type
module:models/event-timeline~EventTimeline

getMember(userId) → {RoomMember}

Get a member from the current room state.
Parameters:
Name Type Description
userId string The user ID of the member.
Source:
Returns:
The member or null.
Type
RoomMember

getMembersWithMembership(membership) → {Array.<RoomMember>}

Get a list of members with given membership state.
Parameters:
Name Type Description
membership string The membership state.
Source:
Returns:
A list of members with the given membership state.
Type
Array.<RoomMember>

getOrCreateFilteredTimelineSet(filter) → {EventTimelineSet}

Add a timelineSet for this room with the given filter
Parameters:
Name Type Description
filter Filter The filter to be applied to this timelineSet
Source:
Returns:
The timelineSet
Type
EventTimelineSet

getPendingEvents() → {Array.<module:models/event.MatrixEvent>}

Get the list of pending sent events for this room
Source:
Throws:
If opts.pendingEventOrdering was not 'detached'
Returns:
A list of the sent events waiting for remote echo.
Type
Array.<module:models/event.MatrixEvent>

getReceiptsForEvent(event) → {Array.<Object>}

Get a list of receipts for the given event.
Parameters:
Name Type Description
event MatrixEvent the event to get receipts for
Source:
Returns:
A list of receipts with a userId, type and data keys or an empty list.
Type
Array.<Object>

getTimelineForEvent(eventId) → (nullable) {module:models/event-timeline~EventTimeline}

Get the timeline which contains the given event from the unfiltered set, if any
Parameters:
Name Type Description
eventId string event ID to look for
Source:
Returns:
timeline containing the given event, or null if unknown
Type
module:models/event-timeline~EventTimeline

getTimelineSets() → {Array.<EventTimelineSet>}

Return the timeline sets for this room.
Source:
Returns:
array of timeline sets for this room
Type
Array.<EventTimelineSet>

getUnfilteredTimelineSet() → {EventTimelineSet}

Helper to return the main unfiltered timeline set for this room
Source:
Returns:
room's unfiltered timeline set
Type
EventTimelineSet

getUnreadNotificationCount(type) → {Number}

Get one of the notification counts for this room
Parameters:
Name Type Description
type String The type of notification count to get. default: 'total'
Source:
Returns:
The notification count, or undefined if there is no count for this type.
Type
Number

getUsersReadUpTo(event) → {Array.<String>}

Get a list of user IDs who have read up to the given event.
Parameters:
Name Type Description
event MatrixEvent the event to get read receipts for.
Source:
Returns:
A list of user IDs.
Type
Array.<String>

hasMembershipState(userId, membership) → {boolean}

Check if the given user_id has the given membership state.
Parameters:
Name Type Description
userId string The user ID to check.
membership string The membership e.g. 'join'
Source:
Returns:
True if this user_id has the given membership state.
Type
boolean

recalculate(userId)

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.
Parameters:
Name Type Description
userId string The client's user ID.
Source:
Fires:
  • module:client~MatrixClient#event:"Room.name"

removeEvent(eventId) → {bool}

Removes a single event from this room.
Parameters:
Name Type Description
eventId String The id of the event to remove
Source:
Returns:
true if the event was removed from any of the room's timeline sets
Type
bool

removeEvents(event_ids)

Removes events from this room.
Parameters:
Name Type Description
event_ids Array.<String> A list of event_ids to remove.
Source:

removeFilteredTimelineSet(filter)

Forget the timelineSet for this room with the given filter
Parameters:
Name Type Description
filter Filter the filter whose timelineSet is to be forgotten
Source:

resetLiveTimeline(backPaginationTokenopt)

Reset the live timeline of all timelineSets, and start new ones.

This is used when /sync returns a 'limited' timeline.

Parameters:
Name Type Attributes Description
backPaginationToken string <optional>
token for back-paginating the new timeline
Source:

setUnreadNotificationCount(type, count)

Set one of the notification counts for this room
Parameters:
Name Type Description
type String The type of notification count to set.
count Number The new count
Source:

updatePendingEvent(event, newStatus, newEventId)

Update the status / event id on a pending event, to reflect its transmission progress.

This is an internal method.

Parameters:
Name Type Description
event MatrixEvent local echo event
newStatus EventStatus status to assign
newEventId string new event id to assign. Ignored unless newStatus == EventStatus.SENT.
Source:
Fires:
  • module:client~MatrixClient#event:"Room.localEchoUpdated"

(inner) calculateRoomName(room, userId, ignoreRoomNameEvent) → {string}

This is an internal method. Calculates the name of the room from the current room state.
Parameters:
Name Type Description
room Room The matrix room.
userId string The client's user ID. Used to filter room members correctly.
ignoreRoomNameEvent bool Return the implicit room name that we'd see if there was no m.room.name event.
Source:
Returns:
The calculated room name.
Type
string