feat!: replace StreamChat.activeChannels with entity item index for loaded channels

[MartinCupela]

Description of the changes, What, Why and How?

Linear: REACT-1062. Design: How stream-chat-js organizes and manages data. This PR implements the channel part of that design; users, messages and relations (its "Nice to have" section) are out of scope. Companion PR: GetStream/stream-chat-react#3310.

Why

client.activeChannels was a plain object keyed by cid that only grew: a channel left it only on deletion, removal or logout, every lookup built its own instance when it missed, and nothing guaranteed one Channel per cid. Channel lists (ChannelPaginator) kept their own references, so a channel could be disconnected while a list still showed it, or stay alive after nothing used it.

What

One Channel per cid, in a channel store. ChannelManager owns channelStore, a class-instance EntityStore<Channel> keyed by cid, the way ThreadManager owns its thread store. It replaces client.activeChannels, which is removed. Read channels with client.channelManager.get(cid) and client.channelManager.values(), and get or create one with client.channelManager.ensure({ type, id?, data? }). client.channel() stays, as a shorthand for ensure() with the same argument forms as in v9. Each channel's data stays in its own channel.state.

EntityStore additions for class instances. Stores that don't use them behave as before:

• getOrCreate(id, create, hydrate?) returns the stored instance (passing it to hydrate) or stores the result of create; a stored instance is never replaced, so every caller gets the same one.
• onRelease(entity) runs when an entry is removed; the channel store uses it to call channel.disconnect().
• changeId(oldId, newId) moves an entry and its holders when a channel created from members gets its real cid.
• replace(entity), remove(id), detach(id) (drops an entry without releasing it), clear(), values(), entries().
• Removals reach the holders: onEntityRemoved(id, entity) lets each list drop a removed channel itself, so after a deletion or logout no list shows a disconnected channel. remove() and clear() finish even when a holder throws.
• releaseOnLastUnlink: false keeps entries when their last link goes; the channel store releases them only when asked (below).

Lists hold their channels in the store. ChannelPaginator builds its StoreBackedItemIndex over the channel store (a store option, defaulting to client.channelManager's) and links each channel on its loaded pages. Every index is its own holder, named after its paginator.

A channel stays stored until it ends, the user logs out, or the app releases it. As in v9, the SDK never releases a channel on its own: it can't see the channels an app keeps in its own state. Known ends (deletion, removal from the channel, notification.channel_deleted) and disconnectUser() remove and disconnect channels right away. To free memory, the app calls client.channelManager.releaseUnusedChannels(), which:

1. removes every stored channel the app disconnected (channel.disconnect(), so pendingDisposal), whatever still holds it;
2. then removes and disconnects every stored channel that is neither watched nor used.

What keeps a channel:

• its own state: watched (watching, or wasWatching until the watch is restored), active (channel.activate() not yet released), or a watch() / query() / create() in flight;
• holders in the store: a channel list links its channels (it needs the store's removal and cid-change notifications), while threads, the message composer cache and an active channel or message search each add one named claim, channelStore.addClaim({ name, heldBy }), which the store asks when it needs to know.

getChannelUsage() reports what keeps each channel, for debugging tools.

Disconnecting a channel. channel.disconnect() (public; it was _disconnect()) stops the instance for good: it stops listening to the client's configuration, releases its loaded messages, and sets pendingDisposal: true and watchStatus: NotWatching. channel.pendingDisposal replaces v9's channel.disconnected: it is read-only (only disconnect() sets it, and nothing sets it back) and lives in channel.state, so it can be followed reactively. It sends no request and doesn't remove the channel from the store, as something may still show it; the next releaseUnusedChannels() does. A disconnected channel throws from getClient(), its query() and watch() reject before the request is sent, activate() warns and does nothing, and the client skips its state handling for events (the channel's own listeners still hear them). Until releaseUnusedChannels() drops it, the SDK treats it as not stored: lists refuse it, an event for its cid gets a live instance through ensure(), and a query that finds it under its cid takes its place instead of being superseded by it. Calling disconnect() again does nothing.

Channels created from members are provisional. ensure({ type, data: { members } }) builds a channel without an id (channel.isProvisional), stored under a temporary cid built from the sorted member ids (type:!members-ann,bob), which is also its channel.cid. Until its query is answered, no other request can be sent for it: typing events and drafts are skipped, any other request throws before it is sent, and nothing is queued for offline replay. Channel lists refuse it until then. The query's response gives it the real id, and the same instance moves to the real cid.

Superseding. If another instance was stored under the real cid meanwhile (by an event or a list), that stored instance stays the one for the cid, as in v9, and takes over the response, the new instance's local messages and, when the new instance is open and the stored one isn't, its composer (messageComposer.transferTo()). The stored instance is marked watched only when that query asked to watch: a query() or create() without watch: true leaves its watch status as it was. The new instance is marked channel.supersededBy (reactive), reports NotWatching, and receives no events. The SDK never disconnects it before logout, as the app may still hold it; the app may call disconnect() on it. Lists never ingest a superseded instance (they take its successor), and ensureWatched() resolves with the successor.

channel.ensureWatched(options?) watches a channel unless it is already watched, and joins a watch already in flight with equal options instead of sending a second request. It resolves with the channel to use: the successor if the channel was superseded. It replaces the internal getChannel() helper; the channel manager uses it for a channel an event brings in and to restore a dropped watch. watch() and query() still always send their request.

Keeping the store consistent.

• channel.data is a getter and setter over channel.state.data, so every server payload reaches subscribers.
• channel.updated and channel.truncated re-insert the channel into its lists, since a channel's sort values change in place.
• channel.initialized is set by any query, so query() and create() set it as watch() does.
• A listener that gets a channel again while its end event is handled keeps the stored instance.

User updates reach what shows them. On user.updated, the client publishes new member, watcher and read objects in one channel.state update (including members and watchers that joined after the query); the read-receipts tracker and poll votes take the updated user too. A presence change no longer rebuilds read receipts or re-renders channel lists.

How

• Channel search queries with watch: false: a result is a preview, and opening it watches it. Message search fetches the channels of its results with watch: false too (unless channelQueryOptions ask for it), and opening a result watches its channel through jumpToMessage(id, { watchChannel: true }). SearchController gains registerSubscriptions(), and dispose() also disposes its sources, so an active search's claim on its results ends with the search. Message search stores every result's channel: those its channel query doesn't return (hidden channels, or ones channelQueryFilters exclude) are stored from the channel data each result carries, unwatched and not loaded until opened. It keeps the channels of its active results in the store.
• channel.activate() and thread.activate() return the function that ends the activation; each call gets its own. (channel.activate() is new in v10.)
• client.hydrateActiveChannels() is renamed to client.hydrateChannels().
• BasePaginator query params take requestOptions passed to query(), and messagePaginator.jumpToMessage(id, { watchChannel: true }) loads the window around a message and watches the channel in one request.
• dispatchEvent isolates each post-listener callback, so one that throws doesn't stop the offline DB write.
• A second ChannelManager for one client is unsupported: the client's own manager owns the channel store.

Breaking changes

Against v9:

BREAKING CHANGE: client.activeChannels is removed; use client.channelManager.get(cid) and client.channelManager.values().
BREAKING CHANGE: client.hydrateActiveChannels() is renamed to client.hydrateChannels().
BREAKING CHANGE: client.getChannelById() and client.getChannelByMembers() are removed; use client.channel() or client.channelManager.ensure({ type, id?, data? }).
BREAKING CHANGE: thread.deactivate() is removed; thread.activate() returns the function that ends the activation.
BREAKING CHANGE: channel._disconnect() is renamed to channel.disconnect().
BREAKING CHANGE: channel.disconnected is removed; read the read-only channel.pendingDisposal instead, which only channel.disconnect() sets.
BREAKING CHANGE: when a channel created from members gets a cid another stored instance already holds, the stored instance stays, as in v9, and the new one is marked channel.supersededBy; if the new one is open and the stored one isn't, its unsent composition moves to the stored one, so UIs holding the new instance should switch to channel.supersededBy.
BREAKING CHANGE: channel.initialized is set by query() and create() too, not only by watch().
BREAKING CHANGE: channel search results are not watched; watch a result when it is opened.
BREAKING CHANGE: MessageSearchSource no longer watches the channels it fetches for its results; watch the channel when a result is opened, e.g. with jumpToMessage(id, { watchChannel: true }).

Both migration guides (v9-to-v10-migration-guide-other.md, -methods.md) cover these, with a checklist item.

Changes for apps on an earlier v10 release candidate

Not breaking against v9, as v9 had neither API:

• channel.deactivate() is removed; call the function returned by channel.activate() instead.
• The channel.pendingDisposal setter is removed; only channel.disconnect() sets it.

Also in this PR

• ThreadManager.ensure() marks a new thread stale only when its parent message has replies, so opening a brand-new thread no longer requests it (404). A thread whose channel isn't watched still loads, as its reply count may be out of date.
• Editing a message no longer writes status and reaction_scores into its custom data. toUpdatedMessagePayload() now treats status as a local field and reaction_scores as a reserved one, for the default updateMessage operation and the composer's edit path alike.
• MessagePaginator seeds a page into a list loaded empty instead of dropping it.
• ChannelPaginator matches fields kept under data.custom, the own user via membership, and the type, id and cid of a channel not yet queried; it sorts and filters disconnected channels without calling getClient().
• disconnectUser() empties the channel lists in one update and finishes even when a holder throws while the channels are cleared.

E2E scenarios tested

Run by hand in examples/vite (stream-chat-react v15 linked to this branch) against a real app. Each check read client.channelManager.getChannelUsage() (what keeps each channel) and the instance identity. The run predates the switch to explicit release: where a row says "the release after recovery", the same check now holds for an explicit releaseUnusedChannels() call. Deletions and removals were dispatched as local events; slow and failing queries came from an axios interceptor; a channel kept by a single reason was isolated by stopping its watch and taking it off the lists. Archive and mute were reversed right after.

#	Scenario	Result	Evidence
A1	First load	✅	20 channels, all watched, channel-paginator (+ active on the open one); a release removed nothing
A2	Switch lists	✅	Archived loaded 2 channels, held by channel-paginator
A3	Load more pages	✅	Default list grew to 20, then 50; every channel kept
B4	Unwatched but listed	✅	notWatching | channel-paginator, survived a release
B5	Unwatched and unused	✅	Torn down (pendingDisposal) and removed at the next release
B6	Interrupted watch	✅	25 channels went wasWatching, all kept by watched
B7	Recovery	✅	Watches restored; the release after recovery removed the one unused channel
B8	Network offline / online	✅	Real socket close: all wasWatching; after reconnect, watched again and the unused channel released
C9	Active, unwatched, unlisted	✅	Kept by active alone
C10	Close it	✅	Nothing kept it; released at the next release
C11	Reopen a released channel	✅	New instance, old one disposed, renders without errors
C12	Reopen a kept channel	✅	Same instance, loaded messages kept
C13	Restore a channel from the URL	✅	Renders; kept by watched, active, channel-paginator
D14	Leaves its list	⚠️ partial	Moving to another list works (D15, D18); "no other list" can't happen in this app, covered with removeItem
D15	Archive / unarchive	✅	Moved to Archived and back as the same instance, never torn down
D16	Channel in two lists	✅	Same instance in default and Unread, one channel-paginator each
D17	Event for an unloaded channel	✅	notification.added_to_channel fetched it: watched, channel-paginator
D18	Mute / unmute	✅	Moved to Muted and back as the same instance
E19	Opened thread	✅	Unwatched, unlisted, closed channel kept by threads alone
E20	Thread list	⚠️ partial	Channels of 42 loaded threads show threads; a reload dropping a thread not run
F21	Inline edit composer	✅	Kept by message-composer-cache alone, also after cancelling the edit
F22	Submit an edit after leaving	⏭ not run	Would change a real message
G23	Search results are previews	✅	Request sent watch: false; results notWatching, channel-search
G24	Listed search result	✅	watched, channel-paginator, channel-search, each once
G25	Close the search	✅	channel-search gone; unopened results released at the next release
G26	Open a search result	✅	Same instance, now watching and active
G27	StrictMode remount	✅	Exactly one channel-search claim after a fresh load
H28	Query in flight	✅	Delayed query: querying-channel, survived a release, then watched
H29	Failed query	✅	After the error nothing kept it; released
I30	Deleted while open	✅	Removed at once, dropped from its list, no errors
I31	Removed from the channel	✅	Removed at once
I32	notification.channel_deleted	✅	Removed at once
I33	Logout	✅	53 → 0 stored, all disposed, lists reset
J34	Channel created from members	✅	Temporary key while active, querying-channel, survived a release, moved to the real cid as the same instance
K35	Several holders	⚠️ partial	Each holder kept a channel on its own (B4, C9, E19, F21, G25); combined removal sequence not run
K36	Quick switching	✅	8 fast switches: one active channel, matching the URL, no duplicates
K37	Reconnects while scrolling	✅	3 offline/online cycles with page loads: no duplicate cid, no torn-down channel in any list

Found during the run and fixed in this PR: holderNames() repeated a claim's name once per listed entity (the threads claim lists a channel once per thread).

Also checked in the app with a local user.updated: the read-receipt tooltip, the poll option voters and the channel list previews show the user's new name and image, and only the previews of channels containing that user change.

Changelog

• Replace client.activeChannels with a channel store on client.channelManager (get, values, ensure); client.channel() is a shorthand for ensure(), and getChannelById() / getChannelByMembers() are removed.
• Add client.channelManager.releaseUnusedChannels() to release channels that are neither watched nor used, and channels the app disconnected.
• Make channel.disconnect() public (was _disconnect()), and replace channel.disconnected with the read-only, reactive channel.pendingDisposal.
• Add channel.ensureWatched(), which joins a watch already in flight and resolves with the channel to use.
• Channels created from members are provisional until their query is answered, and a stored instance supersedes one created meanwhile (channel.supersededBy).
• Channel search results, and the channels message search fetches for its results, are no longer watched; message search stores every result's channel, also those its channel query doesn't return.
• thread.activate() returns a release; thread.deactivate() is removed.
• Add watchChannel to messagePaginator.jumpToMessage().
• EntityStore: getOrCreate, onRelease, changeId, replace, remove, detach, clear, claims (addClaim) and removal notifications for holders.
• Fix read receipts, poll voters, members and watchers keeping a user's old name and image after user.updated.

[stream-ci-bot]

🎉 This PR is included in version 10.0.0-rc.20 🎉

The release is available on:

• GitHub release
• npm package (@rc dist-tag)

Your semantic-release bot 📦🚀