feat(search): adapt debounce to query length and cancel superseded requests

[oliverlaz]

CLA

• I have signed the Stream CLA (required).
• Code changes are tested

Description of the changes, What, Why and How?

Short search queries (1-2 characters) have low selectivity, so the backend search and QueryChannels endpoints are slow or time out on them. Two things made that worse than it needed to be:

1. The debounce did not adapt to query length. debounce() was built once in the constructor with a fixed 300ms, so a 1-character query fired just as eagerly as a precise one.
2. Nothing was ever cancelled. cancelScheduledQuery() only cancelled a scheduled call. An already-dispatched request ran to completion and wrote its result into state via a finally block. Worse, canExecuteQuery had a hard !this.isLoading guard, so a new search string typed while a request was in flight was silently dropped and the UI kept showing stale results.

Dynamic debounce

debounce() in src/utils.ts now accepts a function for its timeout, resolved on every call right before setTimeout. That is the whole switching mechanism: each keystroke clears the pending timer and reschedules using the delay computed from that call's arguments.

Option	Default	Applies to
shortQueryDebounceMs	500	queries of at most shortQueryMaxLength characters
longQueryDebounceMs	300	longer queries
shortQueryMaxLength	2	the boundary, inclusive

Typing a -> ab -> abc schedules at 500ms, 500ms, then 300ms, and only the last runs. An explicit debounceMs applies to both buckets, so anyone who already tuned it (say debounceMs: 800) keeps exactly their interval rather than being sped up to 500ms on short queries.

Request cancellation

Each source holds one AbortController, aborted at the top of every dispatch. The state write stays in finally but is skipped when the signal is aborted, so a late response cannot clobber the newer query. cancelScheduledQuery() and resetState() abort as well.

I did not use withCancellation from src/utils/concurrency.ts: it serializes same-tag callbacks, which would make the new query queue behind the aborted one. A per-instance AbortController is a few lines and has no such coupling.

The signal reaches axios through a new optional trailing ApiRequestOptions on search, queryUsers, queryChannels (via the non-serialized ChannelStateOptions), searchRoles, searchUserGroups and channel.queryMembers, plus an optional config argument on client.get/post, which were previously dropping any axios config. axios.isCancel errors are no longer logged or counted toward the token-refresh backoff.

Applies to

MessageSearchSource, ChannelSearchSource, UserSearchSource, ChannelMemberSearchSource and MentionsSearchSource all inherit this from the two base classes. $autocomplete / $q filter generation is unchanged. CommandSearchSource resolves locally, so it gets the dynamic debounce but no cancellation.

Short queries are not blocked, only debounced harder.

Behaviour changes worth calling out for downstream SDKs

• Queries of at most 2 characters now wait 500ms instead of 300ms.
• canExecuteQuery semantics changed: a new search query now preempts an in-flight request instead of being dropped. Pagination still waits. This is a public method that stream-chat-react and custom sources both call and override.
• Custom query() implementations with their own try/catch will start seeing CanceledError.

All additions are optional parameters or widened optional fields, so this is a minor release, not a breaking one.

Verification

yarn lint, yarn types, yarn test (3064 passing, 77 files) and yarn build are clean. 22 new tests cover the threshold switch in both directions, the config resolution rules including legacy debounceMs, stale-response discard, isLoading release on cancel, and the signal reaching axios.

Changelog

• Search sources debounce short, low-selectivity queries harder than long ones, configurable via shortQueryDebounceMs, longQueryDebounceMs and shortQueryMaxLength
• A new search cancels the in-flight request instead of letting it finish, and no longer gets dropped while one is loading
• search, queryUsers, queryChannels, searchRoles, searchUserGroups and channel.queryMembers accept an abort signal

[oliverlaz]

Naming and the config.params hazard are both addressed; summary of what changed since review, since the branch history shows an intermediate name that did not survive.

Thread	Outcome
config.params duplication	Fixed in 5b1ec13. It was worse than duplication: _enrichAxiosOptions spreads config after the enriched params, so a config.params replaced the whole object and dropped api_key, user_id and connection_id. Verified on the branch before the fix (api_key present? false). Applied your Omit<AxiosRequestConfig, 'params'> to get, and to post for the same reason.
config not on AxiosRequestConfig	No change needed, it comes from the intersection on doAxiosRequest's own parameter (client.ts:1275-1277). The awkward shape predates this PR; happy to open a follow-up to flatten it.
ApiRequestOptions naming	Split in d25f63d into SearchQueryOptions for query() and RequestOptions for the client/channel methods. See the thread for why one name could not cover both.

yarn lint, yarn types, yarn test (3064 passing) and yarn build are clean.

[szuperaz]

Didn't review the code as I've seen there are comments already, but tested with RN and was wokring fine for me.

[stream-ci-bot]

🎉 This PR is included in version 9.51.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀