@unwanted/matrix-sdk-mini 34.12.0-1

package/src/models/typed-event-emitter.ts

@@ -0,0 +1,246 @@
+/*
+Copyright 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.
+*/
+
+// eslint-disable-next-line no-restricted-imports
+import { EventEmitter } from "events";
+
+/** Events emitted by EventEmitter itself */
+export enum EventEmitterEvents {
+    NewListener = "newListener",
+    RemoveListener = "removeListener",
+    Error = "error",
+}
+
+type AnyListener = (...args: any) => any;
+
+/** Base class for types mapping from event name to the type of listeners to that event */
+export type ListenerMap<E extends string> = { [eventName in E]: AnyListener };
+
+type EventEmitterEventListener = (eventName: string, listener: AnyListener) => void;
+type EventEmitterErrorListener = (error: Error) => void;
+
+/**
+ * The expected type of a listener function for a particular event.
+ *
+ * Type parameters:
+ *   * `E` - List of all events emitted by the `TypedEventEmitter`. Normally an enum type.
+ *   * `A` - A type providing mappings from event names to listener types.
+ *   * `T` - The name of the actual event that this listener is for. Normally one of the types in `E` or
+ *           {@link EventEmitterEvents}.
+ */
+export type Listener<E extends string, A extends ListenerMap<E>, T extends E | EventEmitterEvents> = T extends E
+    ? A[T]
+    : T extends EventEmitterEvents
+      ? EventEmitterErrorListener
+      : EventEmitterEventListener;
+
+/**
+ * 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 this `TypedEventEmitter`. Normally an enum type.
+ *  * `Arguments` - A {@link 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`?
+ */
+export class TypedEventEmitter<
+    Events extends string,
+    Arguments extends ListenerMap<Events>,
+    SuperclassArguments extends ListenerMap<any> = Arguments,
+> extends EventEmitter {
+    /**
+     * Alias for {@link on}.
+     */
+    public addListener<T extends Events | EventEmitterEvents>(
+        event: T,
+        listener: Listener<Events, Arguments, T>,
+    ): this {
+        return super.addListener(event, listener);
+    }
+
+    /**
+     * Synchronously calls each of the listeners registered for the event named
+     * `event`, in the order they were registered, passing the supplied arguments
+     * to each.
+     *
+     * @param event - The name of the event to emit
+     * @param args - Arguments to pass to the listener
+     * @returns `true` if the event had listeners, `false` otherwise.
+     */
+    public emit<T extends Events>(event: T, ...args: Parameters<SuperclassArguments[T]>): boolean;
+    public emit<T extends Events>(event: T, ...args: Parameters<Arguments[T]>): boolean;
+    public emit<T extends Events>(event: T, ...args: any[]): boolean {
+        return super.emit(event, ...args);
+    }
+
+    /**
+     * Similar to `emit` but calls all listeners within a `Promise.all` and returns the promise chain
+     * @param event - The name of the event to emit
+     * @param args - Arguments to pass to the listener
+     * @returns `true` if the event had listeners, `false` otherwise.
+     */
+    public async emitPromised<T extends Events>(
+        event: T,
+        ...args: Parameters<SuperclassArguments[T]>
+    ): Promise<boolean>;
+    public async emitPromised<T extends Events>(event: T, ...args: Parameters<Arguments[T]>): Promise<boolean>;
+    public async emitPromised<T extends Events>(event: T, ...args: any[]): Promise<boolean> {
+        const listeners = this.listeners(event);
+        return Promise.allSettled(listeners.map((l) => l(...args))).then(() => {
+            return listeners.length > 0;
+        });
+    }
+
+    /**
+     * Returns the number of listeners listening to the event named `event`.
+     *
+     * @param event - The name of the event being listened for
+     */
+    public listenerCount(event: Events | EventEmitterEvents): number {
+        return super.listenerCount(event);
+    }
+
+    /**
+     * Returns a copy of the array of listeners for the event named `event`.
+     */
+    public listeners(event: Events | EventEmitterEvents): ReturnType<EventEmitter["listeners"]> {
+        return super.listeners(event);
+    }
+
+    /**
+     * Alias for {@link removeListener}
+     */
+    public off<T extends Events | EventEmitterEvents>(event: T, listener: Listener<Events, Arguments, T>): this {
+        return super.off(event, listener);
+    }
+
+    /**
+     * 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
+     * {@link prependListener} method can be used as an alternative to add the
+     * event listener to the beginning of the listeners array.
+     *
+     * @param event - The name of the event.
+     * @param listener - The callback function
+     *
+     * @returns a reference to the `EventEmitter`, so that calls can be chained.
+     */
+    public on<T extends Events | EventEmitterEvents>(event: T, listener: Listener<Events, Arguments, T>): this {
+        return super.on(event, listener);
+    }
+
+    /**
+     * Adds 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 {@link prependOnceListener} method can be used as an alternative to add the
+     * event listener to the beginning of the listeners array.
+     *
+     * @param event - The name of the event.
+     * @param listener - The callback function
+     *
+     * @returns a reference to the `EventEmitter`, so that calls can be chained.
+     */
+    public once<T extends Events | EventEmitterEvents>(event: T, listener: Listener<Events, Arguments, T>): this {
+        return super.once(event, listener);
+    }
+
+    /**
+     * 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.
+     *
+     * @param event - The name of the event.
+     * @param listener - The callback function
+     *
+     * @returns a reference to the `EventEmitter`, so that calls can be chained.
+     */
+    public prependListener<T extends Events | EventEmitterEvents>(
+        event: T,
+        listener: Listener<Events, Arguments, T>,
+    ): this {
+        return super.prependListener(event, listener);
+    }
+
+    /**
+     * Adds a **one-time**`listener` 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.
+     *
+     * @param event - The name of the event.
+     * @param listener - The callback function
+     *
+     * @returns a reference to the `EventEmitter`, so that calls can be chained.
+     */
+    public prependOnceListener<T extends Events | EventEmitterEvents>(
+        event: T,
+        listener: Listener<Events, Arguments, T>,
+    ): this {
+        return super.prependOnceListener(event, listener);
+    }
+
+    /**
+     * 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).
+     *
+     * @param event - The name of the event. If undefined, all listeners everywhere are removed.
+     * @returns a reference to the `EventEmitter`, so that calls can be chained.
+     */
+    public removeAllListeners(event?: Events | EventEmitterEvents): this {
+        // EventEmitter::removeAllListeners uses `arguments.length` to determine undefined case
+        if (event === undefined) {
+            return super.removeAllListeners();
+        }
+        return super.removeAllListeners(event);
+    }
+
+    /**
+     * Removes the specified `listener` from the listener array for the event named `event`.
+     *
+     * @returns a reference to the `EventEmitter`, so that calls can be chained.
+     */
+    public removeListener<T extends Events | EventEmitterEvents>(
+        event: T,
+        listener: Listener<Events, Arguments, T>,
+    ): this {
+        return super.removeListener(event, listener);
+    }
+
+    /**
+     * Returns a copy of the array of listeners for the event named `eventName`,
+     * including any wrappers (such as those created by `.once()`).
+     */
+    public rawListeners(event: Events | EventEmitterEvents): ReturnType<EventEmitter["rawListeners"]> {
+        return super.rawListeners(event);
+    }
+}

package/src/models/user.ts

@@ -0,0 +1,302 @@
+/*
+Copyright 2015 - 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 { MatrixClient } from "../matrix.ts";
+import { MatrixEvent } from "./event.ts";
+import { TypedEventEmitter } from "./typed-event-emitter.ts";
+
+export enum UserEvent {
+    DisplayName = "User.displayName",
+    AvatarUrl = "User.avatarUrl",
+    Presence = "User.presence",
+    CurrentlyActive = "User.currentlyActive",
+    LastPresenceTs = "User.lastPresenceTs",
+}
+
+export type UserEventHandlerMap = {
+    /**
+     * Fires whenever any user's display name changes.
+     * @param event - The matrix event which caused this event to fire.
+     * @param user - The user whose User.displayName changed.
+     * @example
+     * ```
+     * matrixClient.on("User.displayName", function(event, user){
+     *   var newName = user.displayName;
+     * });
+     * ```
+     */
+    [UserEvent.DisplayName]: (event: MatrixEvent | undefined, user: User) => void;
+    /**
+     * Fires whenever any user's avatar URL changes.
+     * @param event - The matrix event which caused this event to fire.
+     * @param user - The user whose User.avatarUrl changed.
+     * @example
+     * ```
+     * matrixClient.on("User.avatarUrl", function(event, user){
+     *   var newUrl = user.avatarUrl;
+     * });
+     * ```
+     */
+    [UserEvent.AvatarUrl]: (event: MatrixEvent | undefined, user: User) => void;
+    /**
+     * Fires whenever any user's presence changes.
+     * @param event - The matrix event which caused this event to fire.
+     * @param user - The user whose User.presence changed.
+     * @example
+     * ```
+     * matrixClient.on("User.presence", function(event, user){
+     *   var newPresence = user.presence;
+     * });
+     * ```
+     */
+    [UserEvent.Presence]: (event: MatrixEvent | undefined, user: User) => void;
+    /**
+     * Fires whenever any user's currentlyActive changes.
+     * @param event - The matrix event which caused this event to fire.
+     * @param user - The user whose User.currentlyActive changed.
+     * @example
+     * ```
+     * matrixClient.on("User.currentlyActive", function(event, user){
+     *   var newCurrentlyActive = user.currentlyActive;
+     * });
+     * ```
+     */
+    [UserEvent.CurrentlyActive]: (event: MatrixEvent | undefined, user: User) => void;
+    /**
+     * Fires whenever any user's lastPresenceTs changes,
+     * ie. whenever any presence event is received for a user.
+     * @param event - The matrix event which caused this event to fire.
+     * @param user - The user whose User.lastPresenceTs changed.
+     * @example
+     * ```
+     * matrixClient.on("User.lastPresenceTs", function(event, user){
+     *   var newlastPresenceTs = user.lastPresenceTs;
+     * });
+     * ```
+     */
+    [UserEvent.LastPresenceTs]: (event: MatrixEvent | undefined, user: User) => void;
+};
+
+export class User extends TypedEventEmitter<UserEvent, UserEventHandlerMap> {
+    private modified = -1;
+
+    /**
+     * The 'displayname' of the user if known.
+     * @privateRemarks
+     * Should be read-only
+     */
+    public displayName?: string;
+    public rawDisplayName?: string;
+    /**
+     * The 'avatar_url' of the user if known.
+     * @privateRemarks
+     * Should be read-only
+     */
+    public avatarUrl?: string;
+    /**
+     * The presence status message if known.
+     * @privateRemarks
+     * Should be read-only
+     */
+    public presenceStatusMsg?: string;
+    /**
+     * The presence enum if known.
+     * @privateRemarks
+     * Should be read-only
+     */
+    public presence = "offline";
+    /**
+     * Timestamp (ms since the epoch) for when we last received presence data for this user.
+     * We can subtract lastActiveAgo from this to approximate an absolute value for when a user was last active.
+     * @privateRemarks
+     * Should be read-only
+     */
+    public lastActiveAgo = 0;
+    /**
+     * The time elapsed in ms since the user interacted proactively with the server,
+     * or we saw a message from the user
+     * @privateRemarks
+     * Should be read-only
+     */
+    public lastPresenceTs = 0;
+    /**
+     * Whether we should consider lastActiveAgo to be an approximation
+     * and that the user should be seen as active 'now'
+     * @privateRemarks
+     * Should be read-only
+     */
+    public currentlyActive = false;
+    /**
+     * The events describing this user.
+     * @privateRemarks
+     * Should be read-only
+     */
+    public events: {
+        /** The m.presence event for this user. */
+        presence?: MatrixEvent;
+        profile?: MatrixEvent;
+    } = {};
+
+    /**
+     * Construct a new User. A User must have an ID and can optionally have extra information associated with it.
+     * @param userId - Required. The ID of this user.
+     * @deprecated use `User.createUser`
+     */
+    public constructor(public readonly userId: string) {
+        super();
+        this.displayName = userId;
+        this.rawDisplayName = userId;
+        this.updateModifiedTime();
+    }
+
+    /**
+     * Construct a new User whose events will also emit on MatrixClient.
+     * A User must have an ID and can optionally have extra information associated with it.
+     * @param userId - Required. The ID of this user.
+     * @param client - An instance of MatrixClient object
+     * @returns User object with reEmitter setup on client
+     */
+    public static createUser(userId: string, client: MatrixClient): User {
+        const user = new User(userId);
+        client.reEmitter.reEmit(user, [
+            UserEvent.AvatarUrl,
+            UserEvent.DisplayName,
+            UserEvent.Presence,
+            UserEvent.CurrentlyActive,
+            UserEvent.LastPresenceTs,
+        ]);
+        return user;
+    }
+
+    /**
+     * Update this User with the given presence event. May fire "User.presence",
+     * "User.avatarUrl" and/or "User.displayName" if this event updates this user's
+     * properties.
+     * @param event - The `m.presence` event.
+     *
+     * @remarks
+     * Fires {@link UserEvent.Presence}
+     * Fires {@link UserEvent.DisplayName}
+     * Fires {@link UserEvent.AvatarUrl}
+     */
+    public setPresenceEvent(event: MatrixEvent): void {
+        if (event.getType() !== "m.presence") {
+            return;
+        }
+        const firstFire = this.events.presence === null;
+        this.events.presence = event;
+
+        const eventsToFire: UserEvent[] = [];
+        if (event.getContent().presence !== this.presence || firstFire) {
+            eventsToFire.push(UserEvent.Presence);
+        }
+        if (event.getContent().avatar_url && event.getContent().avatar_url !== this.avatarUrl) {
+            eventsToFire.push(UserEvent.AvatarUrl);
+        }
+        if (event.getContent().displayname && event.getContent().displayname !== this.displayName) {
+            eventsToFire.push(UserEvent.DisplayName);
+        }
+        if (
+            event.getContent().currently_active !== undefined &&
+            event.getContent().currently_active !== this.currentlyActive
+        ) {
+            eventsToFire.push(UserEvent.CurrentlyActive);
+        }
+
+        this.presence = event.getContent().presence;
+        eventsToFire.push(UserEvent.LastPresenceTs);
+
+        if (event.getContent().status_msg) {
+            this.presenceStatusMsg = event.getContent().status_msg;
+        }
+        if (event.getContent().displayname) {
+            this.displayName = event.getContent().displayname;
+        }
+        if (event.getContent().avatar_url) {
+            this.avatarUrl = event.getContent().avatar_url;
+        }
+        this.lastActiveAgo = event.getContent().last_active_ago;
+        this.lastPresenceTs = Date.now();
+        this.currentlyActive = event.getContent().currently_active;
+
+        this.updateModifiedTime();
+
+        for (const eventToFire of eventsToFire) {
+            this.emit(eventToFire, event, this);
+        }
+    }
+
+    /**
+     * Manually set this user's display name. No event is emitted in response to this
+     * as there is no underlying MatrixEvent to emit with.
+     * @param name - The new display name.
+     */
+    public setDisplayName(name: string): void {
+        const oldName = this.displayName;
+        this.displayName = name;
+        if (name !== oldName) {
+            this.updateModifiedTime();
+        }
+    }
+
+    /**
+     * Manually set this user's non-disambiguated display name. No event is emitted
+     * in response to this as there is no underlying MatrixEvent to emit with.
+     * @param name - The new display name.
+     */
+    public setRawDisplayName(name?: string): void {
+        this.rawDisplayName = name;
+    }
+
+    /**
+     * Manually set this user's avatar URL. No event is emitted in response to this
+     * as there is no underlying MatrixEvent to emit with.
+     * @param url - The new avatar URL.
+     */
+    public setAvatarUrl(url?: string): void {
+        const oldUrl = this.avatarUrl;
+        this.avatarUrl = url;
+        if (url !== oldUrl) {
+            this.updateModifiedTime();
+        }
+    }
+
+    /**
+     * Update the last modified time to the current time.
+     */
+    private updateModifiedTime(): void {
+        this.modified = Date.now();
+    }
+
+    /**
+     * Get the timestamp when this User was last updated. This timestamp is
+     * updated when this User receives a new Presence event which has updated a
+     * property on this object. It is updated <i>before</i> firing events.
+     * @returns The timestamp
+     */
+    public getLastModifiedTime(): number {
+        return this.modified;
+    }
+
+    /**
+     * Get the absolute timestamp when this User was last known active on the server.
+     * It is *NOT* accurate if this.currentlyActive is true.
+     * @returns The timestamp
+     */
+    public getLastActiveTs(): number {
+        return this.lastPresenceTs - this.lastActiveAgo;
+    }
+}