|
| 1 | +/* |
| 2 | +Copyright 2020 The Matrix.org Foundation C.I.C. |
| 3 | +
|
| 4 | +Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | +you may not use this file except in compliance with the License. |
| 6 | +You may obtain a copy of the License at |
| 7 | +
|
| 8 | + http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | +
|
| 10 | +Unless required by applicable law or agreed to in writing, software |
| 11 | +distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | +See the License for the specific language governing permissions and |
| 14 | +limitations under the License. |
| 15 | +*/ |
| 16 | + |
| 17 | +import { DefaultTagID, TagID } from "../models"; |
| 18 | +import { Room } from "matrix-js-sdk/src/models/room"; |
| 19 | +import { isNullOrUndefined } from "matrix-js-sdk/src/utils"; |
| 20 | +import { EffectiveMembership, splitRoomsByMembership } from "../membership"; |
| 21 | + |
| 22 | +export enum SortAlgorithm { |
| 23 | + Manual = "MANUAL", |
| 24 | + Alphabetic = "ALPHABETIC", |
| 25 | + Recent = "RECENT", |
| 26 | +} |
| 27 | + |
| 28 | +export enum ListAlgorithm { |
| 29 | + // Orders Red > Grey > Bold > Idle |
| 30 | + Importance = "IMPORTANCE", |
| 31 | + |
| 32 | + // Orders however the SortAlgorithm decides |
| 33 | + Natural = "NATURAL", |
| 34 | +} |
| 35 | + |
| 36 | +export interface ITagSortingMap { |
| 37 | + // @ts-ignore - TypeScript really wants this to be [tagId: string] but we know better. |
| 38 | + [tagId: TagID]: SortAlgorithm; |
| 39 | +} |
| 40 | + |
| 41 | +export interface ITagMap { |
| 42 | + // @ts-ignore - TypeScript really wants this to be [tagId: string] but we know better. |
| 43 | + [tagId: TagID]: Room[]; |
| 44 | +} |
| 45 | + |
| 46 | +// TODO: Add locking support to avoid concurrent writes? |
| 47 | +// TODO: EventEmitter support? Might not be needed. |
| 48 | + |
| 49 | +export abstract class Algorithm { |
| 50 | + protected cached: ITagMap = {}; |
| 51 | + protected sortAlgorithms: ITagSortingMap; |
| 52 | + protected rooms: Room[] = []; |
| 53 | + protected roomsByTag: { |
| 54 | + // @ts-ignore - TS wants this to be a string but we know better |
| 55 | + [tagId: TagID]: Room[]; |
| 56 | + } = {}; |
| 57 | + |
| 58 | + protected constructor() { |
| 59 | + } |
| 60 | + |
| 61 | + /** |
| 62 | + * Asks the Algorithm to regenerate all lists, using the tags given |
| 63 | + * as reference for which lists to generate and which way to generate |
| 64 | + * them. |
| 65 | + * @param {ITagSortingMap} tagSortingMap The tags to generate. |
| 66 | + * @returns {Promise<*>} A promise which resolves when complete. |
| 67 | + */ |
| 68 | + public async populateTags(tagSortingMap: ITagSortingMap): Promise<any> { |
| 69 | + if (!tagSortingMap) throw new Error(`Map cannot be null or empty`); |
| 70 | + this.sortAlgorithms = tagSortingMap; |
| 71 | + return this.setKnownRooms(this.rooms); |
| 72 | + } |
| 73 | + |
| 74 | + /** |
| 75 | + * Gets an ordered set of rooms for the all known tags. |
| 76 | + * @returns {ITagMap} The cached list of rooms, ordered, |
| 77 | + * for each tag. May be empty, but never null/undefined. |
| 78 | + */ |
| 79 | + public getOrderedRooms(): ITagMap { |
| 80 | + return this.cached; |
| 81 | + } |
| 82 | + |
| 83 | + /** |
| 84 | + * Seeds the Algorithm with a set of rooms. The algorithm will discard all |
| 85 | + * previously known information and instead use these rooms instead. |
| 86 | + * @param {Room[]} rooms The rooms to force the algorithm to use. |
| 87 | + * @returns {Promise<*>} A promise which resolves when complete. |
| 88 | + */ |
| 89 | + public async setKnownRooms(rooms: Room[]): Promise<any> { |
| 90 | + if (isNullOrUndefined(rooms)) throw new Error(`Array of rooms cannot be null`); |
| 91 | + if (!this.sortAlgorithms) throw new Error(`Cannot set known rooms without a tag sorting map`); |
| 92 | + |
| 93 | + this.rooms = rooms; |
| 94 | + |
| 95 | + const newTags: ITagMap = {}; |
| 96 | + for (const tagId in this.sortAlgorithms) { |
| 97 | + // noinspection JSUnfilteredForInLoop |
| 98 | + newTags[tagId] = []; |
| 99 | + } |
| 100 | + |
| 101 | + // If we can avoid doing work, do so. |
| 102 | + if (!rooms.length) { |
| 103 | + await this.generateFreshTags(newTags); // just in case it wants to do something |
| 104 | + this.cached = newTags; |
| 105 | + return; |
| 106 | + } |
| 107 | + |
| 108 | + // Split out the easy rooms first (leave and invite) |
| 109 | + const memberships = splitRoomsByMembership(rooms); |
| 110 | + for (const room of memberships[EffectiveMembership.Invite]) { |
| 111 | + console.log(`[DEBUG] "${room.name}" (${room.roomId}) is an Invite`); |
| 112 | + newTags[DefaultTagID.Invite].push(room); |
| 113 | + } |
| 114 | + for (const room of memberships[EffectiveMembership.Leave]) { |
| 115 | + console.log(`[DEBUG] "${room.name}" (${room.roomId}) is Historical`); |
| 116 | + newTags[DefaultTagID.Archived].push(room); |
| 117 | + } |
| 118 | + |
| 119 | + // Now process all the joined rooms. This is a bit more complicated |
| 120 | + for (const room of memberships[EffectiveMembership.Join]) { |
| 121 | + const tags = Object.keys(room.tags || {}); |
| 122 | + |
| 123 | + let inTag = false; |
| 124 | + if (tags.length > 0) { |
| 125 | + for (const tag of tags) { |
| 126 | + if (!isNullOrUndefined(newTags[tag])) { |
| 127 | + console.log(`[DEBUG] "${room.name}" (${room.roomId}) is tagged as ${tag}`); |
| 128 | + newTags[tag].push(room); |
| 129 | + inTag = true; |
| 130 | + } |
| 131 | + } |
| 132 | + } |
| 133 | + |
| 134 | + if (!inTag) { |
| 135 | + // TODO: Determine if DM and push there instead |
| 136 | + newTags[DefaultTagID.Untagged].push(room); |
| 137 | + console.log(`[DEBUG] "${room.name}" (${room.roomId}) is Untagged`); |
| 138 | + } |
| 139 | + } |
| 140 | + |
| 141 | + await this.generateFreshTags(newTags); |
| 142 | + |
| 143 | + this.cached = newTags; |
| 144 | + } |
| 145 | + |
| 146 | + /** |
| 147 | + * Called when the Algorithm believes a complete regeneration of the existing |
| 148 | + * lists is needed. |
| 149 | + * @param {ITagMap} updatedTagMap The tag map which needs populating. Each tag |
| 150 | + * will already have the rooms which belong to it - they just need ordering. Must |
| 151 | + * be mutated in place. |
| 152 | + * @returns {Promise<*>} A promise which resolves when complete. |
| 153 | + */ |
| 154 | + protected abstract generateFreshTags(updatedTagMap: ITagMap): Promise<any>; |
| 155 | + |
| 156 | + /** |
| 157 | + * Called when the Algorithm wants a whole tag to be reordered. Typically this will |
| 158 | + * be done whenever the tag's scope changes (added/removed rooms). |
| 159 | + * @param {TagID} tagId The tag ID which changed. |
| 160 | + * @param {Room[]} rooms The rooms within the tag, unordered. |
| 161 | + * @returns {Promise<Room[]>} Resolves to the ordered rooms in the tag. |
| 162 | + */ |
| 163 | + protected abstract regenerateTag(tagId: TagID, rooms: Room[]): Promise<Room[]>; |
| 164 | + |
| 165 | + /** |
| 166 | + * Asks the Algorithm to update its knowledge of a room. For example, when |
| 167 | + * a user tags a room, joins/creates a room, or leaves a room the Algorithm |
| 168 | + * should be told that the room's info might have changed. The Algorithm |
| 169 | + * may no-op this request if no changes are required. |
| 170 | + * @param {Room} room The room which might have affected sorting. |
| 171 | + * @returns {Promise<boolean>} A promise which resolve to true or false |
| 172 | + * depending on whether or not getOrderedRooms() should be called after |
| 173 | + * processing. |
| 174 | + */ |
| 175 | + // TODO: Take a ReasonForChange to better predict the behaviour? |
| 176 | + // TODO: Intercept here and handle tag changes automatically |
| 177 | + public abstract handleRoomUpdate(room: Room): Promise<boolean>; |
| 178 | +} |
0 commit comments