Thread and thread manager

A Thread is the client's object for the replies to one message. client.threads, a ThreadManager, keeps the client's threads, the user's thread list and the unread thread count. This page lists the API of both in stream-chat.

What a thread holds is explained on What channels and threads hold. The thread list as a feature is on Replies and threads.

client.threads

The client creates client.threads when it's constructed. It keeps one Thread per parent message id, whether a thread is in the thread list or was opened from a message.

Getting a thread

Don't construct new Thread(), and don't keep the objects the last two return when client.threads.get() doesn't know them: events don't update them.

const thread = client.threads.ensure({ channel, parentMessage: message });

// The user opened the thread. Call release() when they close it.
const release = thread.activate();

State

client.threads.state holds the user's threads as a whole:

The thread list

client.threads.paginator is a ThreadPaginator, a list like the others: its state store has items, isLoading, hasMoreTail and lastQueryError. Channel manager and ChannelPaginator lists what every list has. The thread list differs from the others:

• It loads 25 threads a page, with 10 participants and 10 replies each, and watches their channels.
• It keeps the server's order. There is no client-side sort, so a reply doesn't move a thread: isThreadOrderStale becomes true instead.
• hasMoreTail is false until the first page has loaded, so ThreadPaginator.toTail() does nothing before that.
• ThreadPaginator.reload({ limit }) loads the first page again and replaces the list once the response arrives. The threads stay on screen meanwhile. Only the first load sets isLoading.

Load it through client.threads.reload(), below, rather than through the paginator.

Methods

client.threads.activate() and client.threads.deactivate() are a plain on and off flag, not counted. client.threads.registerSubscriptions() isn't counted either: one client.threads.unregisterSubscriptions() stops it. Code that uses stream-chat alone calls client.threads.registerSubscriptions() itself; the React SDK calls it for you.

The configuration has one setting, connectionRecoveryThrottleMs: the minimum time between reloads after reconnects, 1000 ms by default. It's read when the subscriptions are registered, so a change applies from the next client.threads.registerSubscriptions(). Register it under the client key:

client.config.set({
  client: { threads: { connectionRecoveryThrottleMs: 2000 } },
});

Events

While its subscriptions are registered, client.threads handles these events:

Thread state

A thread's identity and its objects:

thread.state holds these fields. The timestamps are in nanoseconds:

A thread's read state uses camelCase, unlike a channel's:

Two getters read the state once, without subscribing:

• thread.hasStaleState reads isStateStale.
• thread.ownUnreadCount reads the current user's unreadMessageCount, or 0.

This handler runs whenever the reply count or the current user's unread count changes:

const ownUserId = client.userId;

const unsubscribe = thread.state.subscribeWithSelector(
  ({ read, replyCount }) => ({
    replyCount,
    unread: ownUserId ? (read[ownUserId]?.unreadMessageCount ?? 0) : 0,
  }),
  ({ replyCount, unread }) => {
    console.log(`${replyCount} replies, ${unread} unread`);
  },
);

Thread events

A thread doesn't listen to the client itself. client.threads hands it the events about it, as long as the thread is kept and the manager's subscriptions are registered:

A change to the parent message from anywhere, such as a reaction, also updates parentMessage, replyCount, participants and deletedAt.

Thread methods

While a thread is active and its subscriptions are registered:

• a reply that would be unread is marked read instead, through Thread.markRead(), throttled;
• when its state is stale, it reloads.

Thread.reload() rejects when the request fails, except for a thread that has no replies yet: the server doesn't know it, so that answer is ignored. A connection that stays up while the channel stops being watched marks the thread stale. After a reconnect, the client reloads active threads and marks the others stale.

The configuration has one setting, requestHandlers.markReadRequest. It replaces the request Thread.markRead() sends, and is registered under the thread key:

client.config.set({
  thread: {
    requestHandlers: {
      markReadRequest: async ({ options, thread }) => {
        console.log("Marking read", thread.id);
        return await thread.channel.markRead(options);
      },
    },
  },
});

The thread key also holds messagePaginator and messageOperations, which go to the thread's reply list and message operations. See Configuration tree.

Threads also have public methods that client.threads calls to apply events: handleNewReply, handleRepliesRead, handleRepliesUnread, handleThreadUpdated, handleMessageUpdated, handleMessageDeleted, handleReactionChanged, handleUserMessagesDeleted, upsertReplyLocally, deleteReplyLocally, updateParentMessageLocally, updateParentMessageOrReplyLocally and hydrateState. App code doesn't call them. Thread.markAsRead() is a deprecated name for Thread.markRead().

See also

• What channels and threads hold explains a thread's state.
• Read state and unread counts explains thread unread counts.
• Message paginator lists the API of a thread's replies.
• Replies and threads shows the thread list and threads in the UI.