@textrp/briij-js-sdk 41.0.0

package/src/models/event-timeline.ts

@@ -0,0 +1,461 @@
+/*
+Copyright 2016 - 2021 The Matrix.org Foundation C.I.C.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+import { type IMarkerFoundOptions, RoomState } from "./room-state.ts";
+import { type EventTimelineSet } from "./event-timeline-set.ts";
+import { type BriijEvent } from "./event.ts";
+import { type Filter } from "../filter.ts";
+import { EventType } from "../@types/event.ts";
+
+export interface IInitialiseStateOptions extends Pick<IMarkerFoundOptions, "timelineWasEmpty"> {
+    // This is a separate interface without any extra stuff currently added on
+    // top of `IMarkerFoundOptions` just because it feels like they have
+    // different concerns. One shouldn't necessarily look to add to
+    // `IMarkerFoundOptions` just because they want to add an extra option to
+    // `initialiseState`.
+}
+
+export interface IAddEventOptions extends Pick<IMarkerFoundOptions, "timelineWasEmpty"> {
+    /** Whether to insert the new event at the start of the timeline where the
+     * oldest events are (timeline is in chronological order, oldest to most
+     * recent) */
+    toStartOfTimeline: boolean;
+    /** The state events to reconcile metadata from */
+    roomState?: RoomState;
+    /** Whether to add timeline events to the state as was done in legacy sync v2.
+     * If true then timeline events will be added to the state.
+     * In sync v2 with org.matrix.msc4222.use_state_after and simplified sliding sync,
+     * all state arrives explicitly and timeline events should not be added. */
+    addToState: boolean;
+}
+
+export enum Direction {
+    Backward = "b",
+    Forward = "f",
+}
+
+export class EventTimeline {
+    /**
+     * Symbolic constant for methods which take a 'direction' argument:
+     * refers to the start of the timeline, or backwards in time.
+     */
+    public static readonly BACKWARDS = Direction.Backward;
+
+    /**
+     * Symbolic constant for methods which take a 'direction' argument:
+     * refers to the end of the timeline, or forwards in time.
+     */
+    public static readonly FORWARDS = Direction.Forward;
+
+    /**
+     * Static helper method to set sender and target properties
+     *
+     * @param event -   the event whose metadata is to be set
+     * @param stateContext -  the room state to be queried
+     * @param toStartOfTimeline -  if true the event's forwardLooking flag is set false
+     */
+    public static setEventMetadata(event: BriijEvent, stateContext: RoomState, toStartOfTimeline: boolean): void {
+        event.setMetadata(stateContext, toStartOfTimeline);
+    }
+
+    private readonly roomId: string | null;
+    private readonly name: string;
+    private events: BriijEvent[] = [];
+    private baseIndex = 0;
+
+    private startState?: RoomState;
+    private endState?: RoomState;
+    // If we have a roomId then we delegate pagination token storage to the room state objects `startState` and
+    // `endState`, but for things like the notification timeline which mix multiple rooms we store the tokens ourselves.
+    private startToken: string | null = null;
+    private endToken: string | null = null;
+
+    private prevTimeline: EventTimeline | null = null;
+    private nextTimeline: EventTimeline | null = null;
+    public paginationRequests: Record<Direction, Promise<boolean> | null> = {
+        [Direction.Backward]: null,
+        [Direction.Forward]: null,
+    };
+
+    /**
+     * Construct a new EventTimeline
+     *
+     * <p>An EventTimeline represents a contiguous sequence of events in a room.
+     *
+     * <p>As well as keeping track of the events themselves, it stores the state of
+     * the room at the beginning and end of the timeline, and pagination tokens for
+     * going backwards and forwards in the timeline.
+     *
+     * <p>In order that clients can meaningfully maintain an index into a timeline,
+     * the EventTimeline object tracks a 'baseIndex'. This starts at zero, but is
+     * incremented when events are prepended to the timeline. The index of an event
+     * relative to baseIndex therefore remains constant.
+     *
+     * <p>Once a timeline joins up with its neighbour, they are linked together into a
+     * doubly-linked list.
+     *
+     * @param eventTimelineSet - the set of timelines this is part of
+     */
+    public constructor(private readonly eventTimelineSet: EventTimelineSet) {
+        this.roomId = eventTimelineSet.room?.roomId ?? null;
+        if (this.roomId) {
+            this.startState = new RoomState(this.roomId);
+            this.endState = new RoomState(this.roomId);
+        }
+
+        // this is used by client.js
+        this.paginationRequests = { b: null, f: null };
+
+        this.name = this.roomId + ":" + new Date().toISOString();
+    }
+
+    /**
+     * Initialise the start and end state with the given events
+     *
+     * <p>This can only be called before any events are added.
+     *
+     * @param stateEvents - list of state events to initialise the
+     * state with.
+     * @throws Error if an attempt is made to call this after addEvent is called.
+     */
+    public initialiseState(stateEvents: BriijEvent[], { timelineWasEmpty }: IInitialiseStateOptions = {}): void {
+        if (this.events.length > 0) {
+            throw new Error("Cannot initialise state after events are added");
+        }
+
+        this.startState?.setStateEvents(stateEvents, { timelineWasEmpty });
+        this.endState?.setStateEvents(stateEvents, { timelineWasEmpty });
+    }
+
+    /**
+     * Forks the (live) timeline, taking ownership of the existing directional state of this timeline.
+     * All attached listeners will keep receiving state updates from the new live timeline state.
+     * The end state of this timeline gets replaced with an independent copy of the current RoomState,
+     * and will need a new pagination token if it ever needs to paginate forwards.
+
+     * @param direction -   EventTimeline.BACKWARDS to get the state at the
+     *   start of the timeline; EventTimeline.FORWARDS to get the state at the end
+     *   of the timeline.
+     *
+     * @returns the new timeline
+     */
+    public forkLive(direction: Direction): EventTimeline {
+        const forkState = this.getState(direction);
+        const timeline = new EventTimeline(this.eventTimelineSet);
+        timeline.startState = forkState?.clone();
+        // Now clobber the end state of the new live timeline with that from the
+        // previous live timeline. It will be identical except that we'll keep
+        // using the same RoomMember objects for the 'live' set of members with any
+        // listeners still attached
+        timeline.endState = forkState;
+        // Firstly, we just stole the current timeline's end state, so it needs a new one.
+        // Make an immutable copy of the state so back pagination will get the correct sentinels.
+        this.endState = forkState?.clone();
+        return timeline;
+    }
+
+    /**
+     * Creates an independent timeline, inheriting the directional state from this timeline.
+     *
+     * @param direction -   EventTimeline.BACKWARDS to get the state at the
+     *   start of the timeline; EventTimeline.FORWARDS to get the state at the end
+     *   of the timeline.
+     *
+     * @returns the new timeline
+     */
+    public fork(direction: Direction): EventTimeline {
+        const forkState = this.getState(direction);
+        const timeline = new EventTimeline(this.eventTimelineSet);
+        timeline.startState = forkState?.clone();
+        timeline.endState = forkState?.clone();
+        return timeline;
+    }
+
+    /**
+     * Get the ID of the room for this timeline
+     * @returns room ID
+     */
+    public getRoomId(): string | null {
+        return this.roomId;
+    }
+
+    /**
+     * Get the filter for this timeline's timelineSet (if any)
+     * @returns filter
+     */
+    public getFilter(): Filter | undefined {
+        return this.eventTimelineSet.getFilter();
+    }
+
+    /**
+     * Get the timelineSet for this timeline
+     * @returns timelineSet
+     */
+    public getTimelineSet(): EventTimelineSet {
+        return this.eventTimelineSet;
+    }
+
+    /**
+     * Get the base index.
+     *
+     * <p>This is an index which is incremented when events are prepended to the
+     * timeline. An individual event therefore stays at the same index in the array
+     * relative to the base index (although note that a given event's index may
+     * well be less than the base index, thus giving that event a negative relative
+     * index).
+     */
+    public getBaseIndex(): number {
+        return this.baseIndex;
+    }
+
+    /**
+     * Get the list of events in this context
+     *
+     * @returns An array of BriijEvents
+     */
+    public getEvents(): BriijEvent[] {
+        return this.events;
+    }
+
+    /**
+     * Get the room state at the start/end of the timeline
+     *
+     * @param direction -   EventTimeline.BACKWARDS to get the state at the
+     *   start of the timeline; EventTimeline.FORWARDS to get the state at the end
+     *   of the timeline.
+     *
+     * @returns state at the start/end of the timeline
+     */
+    public getState(direction: Direction): RoomState | undefined {
+        if (direction == EventTimeline.BACKWARDS) {
+            return this.startState;
+        } else if (direction == EventTimeline.FORWARDS) {
+            return this.endState;
+        } else {
+            throw new Error("Invalid direction '" + direction + "'");
+        }
+    }
+
+    /**
+     * Get a pagination token
+     *
+     * @param direction - EventTimeline.BACKWARDS to get the pagination
+     *   token for going backwards in time; EventTimeline.FORWARDS to get the
+     *   pagination token for going forwards in time.
+     *
+     * @returns pagination token
+     */
+    public getPaginationToken(direction: Direction): string | null {
+        if (this.roomId) {
+            return this.getState(direction)!.paginationToken;
+        } else if (direction === Direction.Backward) {
+            return this.startToken;
+        } else {
+            return this.endToken;
+        }
+    }
+
+    /**
+     * Set a pagination token
+     *
+     * @param token -       pagination token
+     *
+     * @param direction -    EventTimeline.BACKWARDS to set the pagination
+     *   token for going backwards in time; EventTimeline.FORWARDS to set the
+     *   pagination token for going forwards in time.
+     */
+    public setPaginationToken(token: string | null, direction: Direction): void {
+        if (this.roomId) {
+            this.getState(direction)!.paginationToken = token;
+        } else if (direction === Direction.Backward) {
+            this.startToken = token;
+        } else {
+            this.endToken = token;
+        }
+    }
+
+    /**
+     * Get the next timeline in the series
+     *
+     * @param direction - EventTimeline.BACKWARDS to get the previous
+     *   timeline; EventTimeline.FORWARDS to get the next timeline.
+     *
+     * @returns previous or following timeline, if they have been
+     * joined up.
+     */
+    public getNeighbouringTimeline(direction: Direction): EventTimeline | null {
+        if (direction == EventTimeline.BACKWARDS) {
+            return this.prevTimeline;
+        } else if (direction == EventTimeline.FORWARDS) {
+            return this.nextTimeline;
+        } else {
+            throw new Error("Invalid direction '" + direction + "'");
+        }
+    }
+
+    /**
+     * Set the next timeline in the series
+     *
+     * @param neighbour - previous/following timeline
+     *
+     * @param direction - EventTimeline.BACKWARDS to set the previous
+     *   timeline; EventTimeline.FORWARDS to set the next timeline.
+     *
+     * @throws Error if an attempt is made to set the neighbouring timeline when
+     * it is already set.
+     */
+    public setNeighbouringTimeline(neighbour: EventTimeline, direction: Direction): void {
+        if (this.getNeighbouringTimeline(direction)) {
+            throw new Error(
+                "timeline already has a neighbouring timeline - " +
+                    "cannot reset neighbour (direction: " +
+                    direction +
+                    ")",
+            );
+        }
+
+        if (direction == EventTimeline.BACKWARDS) {
+            this.prevTimeline = neighbour;
+        } else if (direction == EventTimeline.FORWARDS) {
+            this.nextTimeline = neighbour;
+        } else {
+            throw new Error("Invalid direction '" + direction + "'");
+        }
+
+        // make sure we don't try to paginate this timeline
+        this.setPaginationToken(null, direction);
+    }
+
+    /**
+     * Add a new event to the timeline, and update the state
+     *
+     * @param event - new event
+     * @param options - addEvent options
+     */
+    public addEvent(
+        event: BriijEvent,
+        { toStartOfTimeline, roomState, timelineWasEmpty, addToState }: IAddEventOptions,
+    ): void {
+        if (!roomState) {
+            roomState = toStartOfTimeline ? this.startState : this.endState;
+        }
+
+        const timelineSet = this.getTimelineSet();
+
+        if (timelineSet.room) {
+            EventTimeline.setEventMetadata(event, roomState!, toStartOfTimeline);
+
+            // modify state but only on unfiltered timelineSets
+            if (addToState && event.isState() && timelineSet.room.getUnfilteredTimelineSet() === timelineSet) {
+                roomState?.setStateEvents([event], { timelineWasEmpty });
+                // it is possible that the act of setting the state event means we
+                // can set more metadata (specifically sender/target props), so try
+                // it again if the prop wasn't previously set. It may also mean that
+                // the sender/target is updated (if the event set was a room member event)
+                // so we want to use the *updated* member (new avatar/name) instead.
+                //
+                // However, we do NOT want to do this on member events if we're going
+                // back in time, else we'll set the .sender value for BEFORE the given
+                // member event, whereas we want to set the .sender value for the ACTUAL
+                // member event itself.
+                if (!event.sender || (event.getType() === EventType.RoomMember && !toStartOfTimeline)) {
+                    EventTimeline.setEventMetadata(event, roomState!, toStartOfTimeline);
+                }
+            }
+        }
+
+        let insertIndex: number;
+
+        if (toStartOfTimeline) {
+            insertIndex = 0;
+        } else {
+            insertIndex = this.events.length;
+        }
+
+        this.events.splice(insertIndex, 0, event); // insert element
+        if (toStartOfTimeline) {
+            this.baseIndex++;
+        }
+    }
+
+    /**
+     * Insert a new event into the timeline, and update the state.
+     *
+     * TEMPORARY: until we have recursive relations, we need this function
+     * to exist to allow us to insert events in timeline order, which is our
+     * best guess for Sync Order.
+     * This is a copy of addEvent above, modified to allow inserting an event at
+     * a specific index.
+     *
+     * @internal
+     */
+    public insertEvent(event: BriijEvent, insertIndex: number, roomState: RoomState, addToState: boolean): void {
+        const timelineSet = this.getTimelineSet();
+
+        if (timelineSet.room) {
+            EventTimeline.setEventMetadata(event, roomState, false);
+
+            // modify state but only on unfiltered timelineSets
+            if (addToState && event.isState() && timelineSet.room.getUnfilteredTimelineSet() === timelineSet) {
+                roomState.setStateEvents([event], {});
+                // it is possible that the act of setting the state event means we
+                // can set more metadata (specifically sender/target props), so try
+                // it again if the prop wasn't previously set. It may also mean that
+                // the sender/target is updated (if the event set was a room member event)
+                // so we want to use the *updated* member (new avatar/name) instead.
+                //
+                // However, we do NOT want to do this on member events if we're going
+                // back in time, else we'll set the .sender value for BEFORE the given
+                // member event, whereas we want to set the .sender value for the ACTUAL
+                // member event itself.
+                if (!event.sender || event.getType() === EventType.RoomMember) {
+                    EventTimeline.setEventMetadata(event, roomState, false);
+                }
+            }
+        }
+
+        this.events.splice(insertIndex, 0, event); // insert element
+    }
+
+    /**
+     * Remove an event from the timeline
+     *
+     * @param eventId -  ID of event to be removed
+     * @returns removed event, or null if not found
+     */
+    public removeEvent(eventId: string): BriijEvent | null {
+        for (let i = this.events.length - 1; i >= 0; i--) {
+            const ev = this.events[i];
+            if (ev.getId() == eventId) {
+                this.events.splice(i, 1);
+                if (i < this.baseIndex) {
+                    this.baseIndex--;
+                }
+                return ev;
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Return a string to identify this timeline, for debugging
+     *
+     * @returns name for this timeline
+     */
+    public toString(): string {
+        return this.name;
+    }
+}