@talkjs/core 1.5.1 → 1.5.3

package/dist/talkSession.d.ts

@@ -245,6 +245,8 @@ export declare interface ConversationListActiveState {
  *
  * You can expand this window by calling {@link ConversationListSubscription.loadMore}, which extends the window further into the past.
  *
+ * Remember to `.unsubscribe` the subscription once you are done with it.
+ *
  * @public
  */
 export declare interface ConversationListSubscription {
@@ -287,6 +289,10 @@ export declare interface ConversationListSubscription {
      * @remarks
      * Calling `loadMore` multiple times in parallel will still only load one page of conversations.
      *
+     * Avoid calling `.loadMore` in a loop until you have loaded all conversations.
+     * This is usually unnecessary: any time a conversation receives a message, it appears at the start of the list of conversations.
+     * If you do need to call loadMore in a loop, make sure you set a small upper bound (e.g. 100) on the number of conversations, where the loop will exit.
+     *
      * @param count - The number of additional conversations to load. Must be between 1 and 30. Default 20.
      * @returns A promise that resolves once the additional conversations have loaded
      */
@@ -460,30 +466,43 @@ export declare interface ConversationRef {
      * Subscribes to the messages in the conversation.
      *
      * @remarks
-     * Initially, you will be subscribed to the 30 most recent messages and any new messages.
-     * Call `loadMore` to load additional older messages.
-     *
      * While the subscription is active, `onSnapshot` will be called whenever the message snapshots change.
      * This includes when a message is sent, edited, deleted, and when you load more messages.
      * It also includes when nested data changes, such as when `snapshot[0].referencedMessage.sender.name` changes.
      * `loadedAll` is true when `snapshot` contains all the messages in the conversation, and false if you could load more.
      *
+     * The `snapshot` list is ordered chronologically with the most recent messages at the start.
+     * When a new message is received, it will be added to the start of the list.
+     *
      * The snapshot is null if you are not a participant in the conversation (including when the conversation doesn't exist)
+     *
+     * Initially, you will be subscribed to the 30 most recent messages and any new messages.
+     * Call `loadMore` to load additional older messages. This will trigger `onSnapshot`.
+     *
+     * Tip: If you only care about the most recent message in the conversation, use `ConversationRef.subscribe` or `Session.subscribeConversations`.
+     * Then use the `ConversationSnapshot.lastMessage` property. This is easier to use and slightly more efficient.
+     *
+     * Remember to call `.unsubscribe` on the subscription once you are done with it.
      */
     subscribeMessages(onSnapshot?: (snapshot: MessageSnapshot[] | null, loadedAll: boolean) => void): MessageSubscription;
     /**
      * Subscribes to the participants in the conversation.
      *
      * @remarks
-     * Initially, you will be subscribed to the 10 participants who joined most recently, and any new participants.
-     * Call `loadMore` to load additional older participants.
-     *
      * While the subscription is active, `onSnapshot` will be called whenever the participant snapshots change.
      * This includes when someone joins or leaves, when their participant attributes are edited, and when you load more participants.
      * It also includes when nested data changes, such as when `snapshot[0].user.name` changes.
      * `loadedAll` is true when `snapshot` contains all the participants in the conversation, and false if you could load more.
      *
+     * The `snapshot` list is ordered chronologically with the participants who joined most recently at the start.
+     * When someone joins the conversation, they will be added to the start of the list.
+     *
      * The snapshot is null if you are not a participant in the conversation (including when the conversation doesn't exist)
+     *
+     * Initially, you will be subscribed to the 10 participants who joined most recently, and any new participants.
+     * Call `loadMore` to load additional older participants. This will trigger `onSnapshot`.
+     *
+     * Remember to call `.unsubscribe` on the subscription once you are done with it.
      */
     subscribeParticipants(onSnapshot?: (snapshot: ParticipantSnapshot[] | null, loadedAll: boolean) => void): ParticipantSubscription;
     /**
@@ -494,6 +513,8 @@ export declare interface ConversationRef {
      * This includes changes to nested data. As an extreme example, `onSnapshot` would be called when `snapshot.lastMessage.referencedMessage.sender.name` changes.
      *
      * The snapshot is null if you are not a participant in the conversation (including when the conversation doesn't exist)
+     *
+     * Remember to call `.unsubscribe` on the subscription once you are done with it.
      */
     subscribe(onSnapshot?: (snapshot: ConversationSnapshot | null) => void): ConversationSubscription;
     /**
@@ -505,6 +526,8 @@ export declare interface ConversationRef {
      * You will not be notified when there are already "many" people typing, and another person starts typing, because the snapshot does not change.
      *
      * The snapshot is null if you are not a participant in the conversation (including when the conversation doesn't exist)
+     *
+     * Remember to call `.unsubscribe` on the subscription once you are done with it.
      */
     subscribeTyping(onSnapshot?: (snapshot: TypingSnapshot | null) => void): TypingSubscription;
     /**
@@ -532,7 +555,8 @@ export declare interface ConversationRef {
      *
      *   const now = Date.now();
      *
-     *   // Don't mark as typing more than once every 5s
+     *   // Call `markAsTyping` sparingly - not on every keystroke
+     *   // Only call if it has been at least 5 seconds since last time
      *   if (now - lastMarkedAsTyping > 5000) {
      *     lastMarkedAsTyping = now;
      *     convRef.markAsTyping();
@@ -642,6 +666,8 @@ export declare interface ConversationSnapshot {
  * @remarks
  * Get a ConversationSubscription by calling {@link ConversationRef.subscribe}
  *
+ * Remember to `.unsubscribe` the subscription once you are done with it.
+ *
  * @public
  */
 export declare interface ConversationSubscription {
@@ -1383,6 +1409,8 @@ export declare interface MessageSnapshot {
  *
  * You can expand this window by calling {@link MessageSubscription.loadMore}, which extends the window further into the past.
  *
+ * Remember to `.unsubscribe` the subscription once you are done with it.
+ *
  * @public
  */
 export declare interface MessageSubscription {
@@ -1425,6 +1453,9 @@ export declare interface MessageSubscription {
      * @remarks
      * Calling `loadMore` multiple times in parallel will still only load one page of messages.
      *
+     * Avoid calling `.loadMore` in a loop until you have loaded all messages.
+     * If you do need to call loadMore in a loop, make sure you set an upper bound (e.g. 1000) on the number of messages, where the loop will exit.
+     *
      * @param count - The number of additional messages to load. Must be between 1 and 100. Default 30.
      * @returns A promise that resolves once the additional messages have loaded
      */
@@ -1575,6 +1606,9 @@ export declare interface ParticipantSnapshot {
  * By default, you subscribe to the 10 most recent participants, and any participants who joined after you subscribe.
  *
  * You can expand this window by calling {@link ParticipantSubscription.loadMore}, which extends the window further into the past.
+ * Do not call `.loadMore` in a loop until you have loaded all participants, unless you know that the maximum number of participants is small (under 100).
+ *
+ * Remember to `.unsubscribe` the subscription once you are done with it.
  *
  * @public
  */
@@ -1618,6 +1652,9 @@ export declare interface ParticipantSubscription {
      * @remarks
      * Calling `loadMore` multiple times in parallel will still only load one page of participants.
      *
+     * Avoid calling `.loadMore` in a loop until you have loaded all participants.
+     * If you do need to call loadMore in a loop, make sure you set a small upper bound (e.g. 100) on the number of participants, where the loop will exit.
+     *
      * @param count - The number of additional participants to load. Must be between 1 and 50. Default 10.
      * @returns A promise that resolves once the additional participants have loaded
      */
@@ -2178,18 +2215,27 @@ export declare interface TalkSession {
      * Subscribes to your most recently active conversations.
      *
      * @remarks
-     * The subscription is 'windowed'. Initially, this window contains the 20 most recent conversations.
-     * Conversations are ordered by last activity. The last activity of a conversation is either `joinedAt` or `lastMessage.createdAt`, whichever is higher.
-     *
-     * If an older conversation receives a new message, or you are added to a conversation, it will appear at the start of the list.
-     * Call `loadMore` to load additional older conversations.
-     *
      * While the subscription is active, `onSnapshot` will be called whenever the conversation snapshots change.
      * This includes when you join or leave a conversation, when the conversation attributes change, and when you load more conversations.
      * It also includes when nested data changes, such as when `snapshot[0].lastMessage.referencedMessage.sender.name` changes.
+     * Be careful when doing heavy computation inside `onSnapshot`, and consider caching the result. `onSnapshot` is called extremely often.
      * `loadedAll` is true when `snapshot` contains all your conversations, and false if you could load more.
      *
-     * If the current user does not exist yet, the snapshot will be an empty list.
+     * The `snapshot` list is ordered chronologically with the most recently active conversations at the start.
+     * The last activity of a conversation is either when the last message was sent or when you joined, whichever is later.
+     * In other words, it's the max of `lastMessage.createdAt` and `joinedAt`.
+     * If you join a new conversation, or you receive a message in a conversation, that conversation will appear at the start of the list.
+     *
+     * The snapshot is an empty list if the current user does not exist yet.
+     *
+     * Initially, you will be subscribed to the 20 most recently active conversations and any conversations that have activity after you subscribe.
+     * Call `loadMore` to load additional older conversations. This will trigger `onSnapshot`.
+     *
+     * Tip: `ConversationSnapshot` has a `lastMessage` property. Whenever you are sent a message, that message will be at `snapshot[0].lastMessage`.
+     * If you just want to react to newly received messages, you can use this instead of calling `ConversationRef.subscribeMessages`.
+     * This is much easier and more efficient.
+     *
+     * Remember to call `.unsubscribe` on the subscription once you are done with it.
      */
     subscribeConversations(onSnapshot?: (snapshot: ConversationSnapshot[], loadedAll: boolean) => void): ConversationListSubscription;
     /**
@@ -2402,6 +2448,8 @@ export declare type TypingSnapshot = FewTypingSnapshot | ManyTypingSnapshot;
  * When there are "many" people typing (meaning you received {@link ManyTypingSnapshot}), the next update you receive will be {@link FewTypingSnapshot} once enough people stop typing.
  * Until then, your {@link ManyTypingSnapshot} is still valid and does not need to changed, so `onSnapshot` will not be called.
  *
+ * Remember to `.unsubscribe` the subscription once you are done with it.
+ *
  * @public
  */
 export declare interface TypingSubscription {
@@ -2514,6 +2562,8 @@ export declare interface UserOnlineSnapshot {
  * @remarks
  * Get a UserOnlineSubscription by calling {@link UserRef.subscribeOnline}.
  *
+ * Remember to `.unsubscribe` the subscription once you are done with it.
+ *
  * @public
  */
 export declare interface UserOnlineSubscription {
@@ -2610,6 +2660,8 @@ export declare interface UserRef {
      * @remarks
      * While the subscription is active, `onSnapshot` will be called when the user is created or the snapshot changes.
      *
+     * Remember to call `.unsubscribe` on the subscription once you are done with it.
+     *
      * @returns A subscription to the user
      */
     subscribe(onSnapshot?: (event: UserSnapshot | null) => void): UserSubscription;
@@ -2619,6 +2671,8 @@ export declare interface UserRef {
      * @remarks
      * While the subscription is active, `onSnapshot` will be called when the user is created or the snapshot changes (including changes to the nested UserSnapshot).
      *
+     * Remember to call `.unsubscribe` on the subscription once you are done with it.
+     *
      * @returns A subscription to the user's online status
      */
     subscribeOnline(onSnapshot?: (event: UserOnlineSnapshot | null) => void): UserOnlineSubscription;
@@ -2675,6 +2729,8 @@ export declare interface UserSnapshot {
  * @remarks
  * Get a UserSubscription by calling {@link UserRef.subscribe}
  *
+ * Remember to `.unsubscribe` the subscription once you are done with it.
+ *
  * @public
  */
 export declare interface UserSubscription {