stream-chat 9.50.3 → 9.51.0

package/src/search/BaseSearchSource.ts

@@ -9,10 +9,24 @@ import type {
 import type { APIError } from '../errors';
 import { isAPIError, isErrorRetryable } from '../errors';
 
+/**
+ * Passed to a search source's `query()`. Carries a cancellation handle and makes no
+ * claim that the query performs a request: a source may resolve from local data and
+ * ignore the signal. Where a source does issue requests, forward this straight through
+ * as the request options.
+ */
+export type SearchQueryOptions = {
+  /** Aborted once a newer query supersedes this one. */
+  signal?: AbortSignal;
+};
+
 export type DebounceOptions = {
-  debounceMs: number;
+  /** Applies to both short and long queries unless overridden by the options below. */
+  debounceMs?: number;
+  shortQueryDebounceMs?: number;
+  longQueryDebounceMs?: number;
+  shortQueryMaxLength?: number;
 };
-type DebouncedExecQueryFunction = DebouncedFunc<(searchString?: string) => Promise<void>>;
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 interface ISearchSource<T = any> {
@@ -54,18 +68,44 @@ export interface SearchSourceSync<T = any> extends ISearchSource<T> {
   search(text?: string): void;
 }
 
-const DEFAULT_SEARCH_SOURCE_OPTIONS: Required<SearchSourceOptions> = {
-  debounceMs: 300,
+// Debounce defaults are resolved by resolveDebounceOptions, not here.
+const DEFAULT_SEARCH_SOURCE_OPTIONS: Required<
+  Omit<SearchSourceOptions, keyof DebounceOptions>
+> = {
   pageSize: 10,
   allowEmptySearchString: false,
   resetOnNewSearchQuery: true,
 } as const;
 
-abstract class BaseSearchSourceBase<T> implements ISearchSource<T> {
+/**
+ * An explicit `debounceMs` applies to both buckets, so integrators who already tuned it
+ * keep exactly their configured interval. Only when it is absent do the 500/300 defaults
+ * kick in.
+ */
+const resolveDebounceOptions = ({
+  debounceMs,
+  shortQueryDebounceMs,
+  longQueryDebounceMs,
+  shortQueryMaxLength,
+}: DebounceOptions) => ({
+  shortQueryDebounceMs: shortQueryDebounceMs ?? debounceMs ?? 500,
+  longQueryDebounceMs: longQueryDebounceMs ?? debounceMs ?? 300,
+  shortQueryMaxLength: shortQueryMaxLength ?? 2,
+});
+
+abstract class BaseSearchSourceBase<
+  T,
+  R extends void | Promise<void>,
+> implements ISearchSource<T> {
   state: StateStore<SearchSourceState<T>>;
   pageSize: number;
   protected allowEmptySearchString: boolean;
   protected resetOnNewSearchQuery: boolean;
+  // assigned by setDebounceOptions, which the constructor always calls
+  protected shortQueryDebounceMs!: number;
+  protected longQueryDebounceMs!: number;
+  protected shortQueryMaxLength!: number;
+  protected searchDebounced!: DebouncedFunc<(searchString?: string) => R>;
   abstract readonly type: SearchSourceType;
 
   protected constructor(options?: SearchSourceOptions) {
@@ -77,8 +117,44 @@ abstract class BaseSearchSourceBase<T> implements ISearchSource<T> {
     this.allowEmptySearchString = allowEmptySearchString;
     this.resetOnNewSearchQuery = resetOnNewSearchQuery;
     this.state = new StateStore<SearchSourceState<T>>(this.initialState);
+    // Field initializers run before this body, so setDebounceOptions is already
+    // assigned; it only captures getDebounceMs lazily.
+    this.setDebounceOptions(options ?? {});
+  }
+
+  abstract executeQuery(newSearchString?: string): R;
+
+  setDebounceOptions = (options: DebounceOptions = {}) => {
+    const resolved = resolveDebounceOptions(options);
+    this.shortQueryDebounceMs = resolved.shortQueryDebounceMs;
+    this.longQueryDebounceMs = resolved.longQueryDebounceMs;
+    this.shortQueryMaxLength = resolved.shortQueryMaxLength;
+    this.searchDebounced = debounce(this.executeQuery.bind(this), (searchString) =>
+      this.getDebounceMs(searchString),
+    );
+  };
+
+  /**
+   * Short queries match too much and are slow server-side, so they get a longer debounce.
+   * Resolved per call, which is what lets the interval switch as the user keeps typing.
+   */
+  protected getDebounceMs = (searchString?: string) => {
+    const { length } = searchString ?? this.searchQuery;
+    return length <= this.shortQueryMaxLength
+      ? this.shortQueryDebounceMs
+      : this.longQueryDebounceMs;
+  };
+
+  /**
+   * A new search query preempts an in-flight one; pagination waits for it to finish
+   * and needs a next page to fetch.
+   */
+  protected canDispatchQuery(hasNewSearchQuery: boolean) {
+    return hasNewSearchQuery || (!this.isLoading && this.hasNext);
   }
 
+  search = (searchQuery?: string) => this.searchDebounced(searchQuery);
+
   get lastQueryError() {
     return this.state.getLatestValue().lastQueryError;
   }
@@ -99,7 +175,7 @@ abstract class BaseSearchSourceBase<T> implements ISearchSource<T> {
     return this.state.getLatestValue().isLoading;
   }
 
-  get initialState() {
+  get initialState(): SearchSourceState<T> {
     return {
       hasNext: true,
       isActive: false,
@@ -143,8 +219,7 @@ abstract class BaseSearchSourceBase<T> implements ISearchSource<T> {
     const searchString = newSearchString ?? this.searchQuery;
     return !!(
       this.isActive &&
-      !this.isLoading &&
-      (this.hasNext || hasNewSearchQuery) &&
+      this.canDispatchQuery(hasNewSearchQuery) &&
       (this.allowEmptySearchString || searchString)
     );
   };
@@ -217,34 +292,48 @@ abstract class BaseSearchSourceBase<T> implements ISearchSource<T> {
 }
 
 export abstract class BaseSearchSource<T>
-  extends BaseSearchSourceBase<T>
+  extends BaseSearchSourceBase<T, Promise<void>>
   implements SearchSource<T>
 {
-  protected searchDebounced!: DebouncedExecQueryFunction;
+  /** Aborts the in-flight request, if any, once a newer query is dispatched. */
+  protected queryAbortController: AbortController | null = null;
 
-  constructor(options?: SearchSourceOptions) {
-    const { debounceMs } = { ...DEFAULT_SEARCH_SOURCE_OPTIONS, ...options };
-    super(options);
-    this.setDebounceOptions({ debounceMs });
-  }
-
-  protected abstract query(searchQuery: string): Promise<QueryReturnValue<T>>;
+  protected abstract query(
+    searchQuery: string,
+    options?: SearchQueryOptions,
+  ): Promise<QueryReturnValue<T>>;
 
   protected abstract filterQueryResults(items: T[]): T[] | Promise<T[]>;
 
-  setDebounceOptions = ({ debounceMs }: DebounceOptions) => {
-    this.searchDebounced = debounce(this.executeQuery.bind(this), debounceMs);
-  };
+  /** Aborts the in-flight request, if any. Returns true when one was aborted. */
+  protected abortInFlightQuery() {
+    if (!this.queryAbortController) return false;
+    this.queryAbortController.abort();
+    this.queryAbortController = null;
+    return true;
+  }
+
+  resetState() {
+    // otherwise an in-flight response would repopulate the state we just cleared
+    this.abortInFlightQuery();
+    super.resetState();
+  }
 
   async executeQuery(newSearchString?: string) {
+    // Checked before anything is dispatched, so that the abort below always has a
+    // successor that will clear isLoading.
     if (!this.canExecuteQuery(newSearchString)) return;
 
+    // cancel the previous request before dispatching the new one
+    this.abortInFlightQuery();
+    const { signal } = (this.queryAbortController = new AbortController());
+
     const { hasNewSearchQuery, searchString } =
       this.prepareStateForQuery(newSearchString);
 
     let stateUpdate: Partial<SearchSourceState<T>> = {};
     try {
-      const results = await this.query(searchString);
+      const results = await this.query(searchString, { signal });
       if (!results) return;
 
       const { items } = results;
@@ -256,37 +345,34 @@ export abstract class BaseSearchSource<T>
         stateUpdate.hasNext = false;
       }
     } finally {
-      this.state.next(this.getStateAfterQuery(stateUpdate, hasNewSearchQuery));
+      // A newer query owns the state now - publishing here would clobber it with a
+      // stale result (and with the abort error).
+      if (!signal.aborted) {
+        this.state.next(this.getStateAfterQuery(stateUpdate, hasNewSearchQuery));
+      }
     }
   }
 
-  search = (searchQuery?: string) => this.searchDebounced(searchQuery);
-
   cancelScheduledQuery() {
     this.searchDebounced.cancel();
+    // Nothing will dispatch a successor query, so release the loading state the
+    // aborted query owned - its own finally block skips the state write.
+    if (this.abortInFlightQuery() && this.isLoading) {
+      this.state.partialNext({ isLoading: false });
+    }
   }
 }
 
+// Queries are resolved locally, so there is nothing to cancel here - only the
+// dynamic debounce applies.
 export abstract class BaseSearchSourceSync<T>
-  extends BaseSearchSourceBase<T>
+  extends BaseSearchSourceBase<T, void>
   implements SearchSourceSync<T>
 {
-  protected searchDebounced!: DebouncedExecQueryFunction;
-
-  constructor(options?: SearchSourceOptions) {
-    const { debounceMs } = { ...DEFAULT_SEARCH_SOURCE_OPTIONS, ...options };
-    super(options);
-    this.setDebounceOptions({ debounceMs });
-  }
-
   protected abstract query(searchQuery: string): QueryReturnValue<T>;
 
   protected abstract filterQueryResults(items: T[]): T[];
 
-  setDebounceOptions = ({ debounceMs }: DebounceOptions) => {
-    this.searchDebounced = debounce(this.executeQuery.bind(this), debounceMs);
-  };
-
   executeQuery(newSearchString?: string) {
     if (!this.canExecuteQuery(newSearchString)) return;
 
@@ -311,8 +397,6 @@ export abstract class BaseSearchSourceSync<T>
     }
   }
 
-  search = (searchQuery?: string) => this.searchDebounced(searchQuery);
-
   cancelScheduledQuery() {
     this.searchDebounced.cancel();
   }

package/src/search/ChannelMemberSearchSource.ts

@@ -1,4 +1,4 @@
-import { BaseSearchSource } from './BaseSearchSource';
+import { BaseSearchSource, type SearchQueryOptions } from './BaseSearchSource';
 import { FilterBuilder, type FilterBuilderOptions } from '../pagination';
 import type { Channel } from '../channel';
 import type {
@@ -15,6 +15,13 @@ export type ChannelMemberSearchSourceFilterBuilderContext<
   C extends CustomContext = CustomContext,
 > = { searchQuery?: string } & C;
 
+export type ChannelMemberSearchSourceOptions = SearchSourceOptions & {
+  /** Static base filters merged under the dynamically generated ones. */
+  filters?: MemberFilters;
+  sort?: MemberSort;
+  searchOptions?: Omit<QueryMembersOptions, 'limit' | 'offset'>;
+};
+
 export class ChannelMemberSearchSource<
   TFilterContext extends CustomContext = CustomContext,
 > extends BaseSearchSource<ChannelMemberResponse> {
@@ -30,14 +37,19 @@ export class ChannelMemberSearchSource<
 
   constructor(
     channel: Channel,
-    options?: SearchSourceOptions,
+    options?: ChannelMemberSearchSourceOptions,
     filterBuilderOptions: FilterBuilderOptions<
       MemberFilters,
       ChannelMemberSearchSourceFilterBuilderContext<TFilterContext>
     > = {},
   ) {
-    super(options);
+    const { filters, sort, searchOptions, ...restOptions } = options || {};
+    // members are listed with an empty query, so the initial load must be allowed
+    super({ ...restOptions, allowEmptySearchString: true });
     this.channel = channel;
+    this.filters = filters;
+    this.sort = sort;
+    this.searchOptions = searchOptions;
     this.filterBuilder = new FilterBuilder<
       MemberFilters,
       ChannelMemberSearchSourceFilterBuilderContext<TFilterContext>
@@ -60,13 +72,7 @@ export class ChannelMemberSearchSource<
     });
   }
 
-  canExecuteQuery = (newSearchString?: string) => {
-    const hasNewSearchQuery = typeof newSearchString !== 'undefined';
-
-    return this.isActive && !this.isLoading && (this.hasNext || hasNewSearchQuery);
-  };
-
-  protected async query(searchQuery: string) {
+  protected async query(searchQuery: string, queryOptions: SearchQueryOptions = {}) {
     const filters = this.filterBuilder.buildFilters({
       baseFilters: this.filters,
       context: {
@@ -75,7 +81,12 @@ export class ChannelMemberSearchSource<
     });
     const sort = this.sort ?? [];
     const options = { ...this.searchOptions, limit: this.pageSize, offset: this.offset };
-    const { members } = await this.channel.queryMembers(filters ?? {}, sort, options);
+    const { members } = await this.channel.queryMembers(
+      filters ?? {},
+      sort,
+      options,
+      queryOptions,
+    );
     return { items: members };
   }
 

package/src/search/ChannelSearchSource.ts

@@ -1,4 +1,4 @@
-import { BaseSearchSource } from './BaseSearchSource';
+import { BaseSearchSource, type SearchQueryOptions } from './BaseSearchSource';
 import type { FilterBuilderOptions } from '../pagination';
 import { FilterBuilder } from '../pagination';
 import type { Channel } from '../channel';
@@ -12,6 +12,13 @@ export type ChannelSearchSourceFilterBuilderContext<
   C extends CustomContext = CustomContext,
 > = { searchQuery?: string } & C;
 
+export type ChannelSearchSourceOptions = SearchSourceOptions & {
+  /** Static base filters merged under the dynamically generated ones. */
+  filters?: ChannelFilters;
+  sort?: ChannelSort;
+  searchOptions?: Omit<ChannelOptions, 'limit' | 'offset'>;
+};
+
 export class ChannelSearchSource<
   TFilterContext extends CustomContext = CustomContext,
 > extends BaseSearchSource<Channel> {
@@ -27,14 +34,18 @@ export class ChannelSearchSource<
 
   constructor(
     client: StreamChat,
-    options?: SearchSourceOptions,
+    options?: ChannelSearchSourceOptions,
     filterBuilderOptions: FilterBuilderOptions<
       ChannelFilters,
       ChannelSearchSourceFilterBuilderContext<TFilterContext>
     > = {},
   ) {
-    super(options);
+    const { filters, sort, searchOptions, ...restOptions } = options || {};
+    super(restOptions);
     this.client = client;
+    this.filters = filters;
+    this.sort = sort;
+    this.searchOptions = searchOptions;
     this.filterBuilder = new FilterBuilder<
       ChannelFilters,
       ChannelSearchSourceFilterBuilderContext<TFilterContext>
@@ -51,7 +62,7 @@ export class ChannelSearchSource<
     });
   }
 
-  protected async query(searchQuery: string) {
+  protected async query(searchQuery: string, queryOptions: SearchQueryOptions = {}) {
     const filters = this.filterBuilder.buildFilters({
       baseFilters: {
         ...(this.client.userID ? { members: { $in: [this.client.userID] } } : {}),
@@ -63,7 +74,7 @@ export class ChannelSearchSource<
     });
     const sort = this.sort ?? {};
     const options = { ...this.searchOptions, limit: this.pageSize, offset: this.offset };
-    const items = await this.client.queryChannels(filters, sort, options);
+    const items = await this.client.queryChannels(filters, sort, options, queryOptions);
     return { items };
   }
 

package/src/search/MessageSearchSource.ts

@@ -1,4 +1,4 @@
-import { BaseSearchSource } from './BaseSearchSource';
+import { BaseSearchSource, type SearchQueryOptions } from './BaseSearchSource';
 import type {
   ChannelFilters,
   ChannelOptions,
@@ -54,6 +54,18 @@ export type MessageSearchSourceFilterBuilderOptions<
   >;
 }>;
 
+export type MessageSearchSourceOptions = SearchSourceOptions & {
+  /** Static base filters for the channel scope of the message search. */
+  messageSearchChannelFilters?: ChannelFilters;
+  /** Static base filters for the message search itself. */
+  messageSearchFilters?: MessageFilters;
+  messageSearchSort?: SearchMessageSort;
+  /** Static base filters for the follow-up query that hydrates unknown channels. */
+  channelQueryFilters?: ChannelFilters;
+  channelQuerySort?: ChannelSort;
+  channelQueryOptions?: Omit<ChannelOptions, 'limit' | 'offset'>;
+};
+
 export class MessageSearchSource<
   TContexts extends MessageSearchSourceContexts = {},
 > extends BaseSearchSource<MessageResponse> {
@@ -86,11 +98,26 @@ export class MessageSearchSource<
 
   constructor(
     client: StreamChat,
-    options?: SearchSourceOptions,
+    options?: MessageSearchSourceOptions,
     filterBuilderOptions?: MessageSearchSourceFilterBuilderOptions<TContexts>,
   ) {
-    super(options);
+    const {
+      messageSearchChannelFilters,
+      messageSearchFilters,
+      messageSearchSort,
+      channelQueryFilters,
+      channelQuerySort,
+      channelQueryOptions,
+      ...restOptions
+    } = options || {};
+    super(restOptions);
     this.client = client;
+    this.messageSearchChannelFilters = messageSearchChannelFilters;
+    this.messageSearchFilters = messageSearchFilters;
+    this.messageSearchSort = messageSearchSort;
+    this.channelQueryFilters = channelQueryFilters;
+    this.channelQuerySort = channelQuerySort;
+    this.channelQueryOptions = channelQueryOptions;
 
     this.messageSearchChannelFilterBuilder = new FilterBuilder<
       ChannelFilters,
@@ -129,7 +156,7 @@ export class MessageSearchSource<
     });
   }
 
-  protected async query(searchQuery: string) {
+  protected async query(searchQuery: string, queryOptions: SearchQueryOptions = {}) {
     if (!this.client.userID || this.next === null) return { items: [] };
 
     const channelFilters = this.messageSearchChannelFilterBuilder.buildFilters({
@@ -170,9 +197,13 @@ export class MessageSearchSource<
       channelFilters,
       messageFilters,
       options,
+      queryOptions,
     );
     const items = results.map(({ message }) => message);
 
+    // a newer query already replaced this one - skip the cid scan and the hydration request
+    if (queryOptions.signal?.aborted) return { items, next };
+
     const cids = Array.from(
       items.reduce((acc, message) => {
         if (message.cid && !this.client.activeChannels[message.cid]) acc.add(message.cid);
@@ -194,6 +225,7 @@ export class MessageSearchSource<
           ...this.channelQuerySort,
         },
         this.channelQueryOptions,
+        queryOptions,
       );
     }
 

package/src/search/UserSearchSource.ts

@@ -1,4 +1,4 @@
-import { BaseSearchSource } from './BaseSearchSource';
+import { BaseSearchSource, type SearchQueryOptions } from './BaseSearchSource';
 import { FilterBuilder, type FilterBuilderOptions } from '../pagination';
 import type { StreamChat } from '../client';
 import type { UserFilters, UserOptions, UserResponse, UserSort } from '../types';
@@ -10,6 +10,13 @@ export type UserSearchSourceFilterBuilderContext<
   C extends CustomContext = CustomContext,
 > = { searchQuery?: string } & C;
 
+export type UserSearchSourceOptions = SearchSourceOptions & {
+  /** Static base filters merged under the dynamically generated ones. */
+  filters?: UserFilters;
+  sort?: UserSort;
+  searchOptions?: Omit<UserOptions, 'limit' | 'offset'>;
+};
+
 export class UserSearchSource<
   TFilterContext extends CustomContext = CustomContext,
 > extends BaseSearchSource<UserResponse> {
@@ -25,14 +32,18 @@ export class UserSearchSource<
 
   constructor(
     client: StreamChat,
-    options?: SearchSourceOptions,
+    options?: UserSearchSourceOptions,
     filterBuilderOptions: FilterBuilderOptions<
       UserFilters,
       UserSearchSourceFilterBuilderContext<TFilterContext>
     > = {},
   ) {
-    super(options);
+    const { filters, sort, searchOptions, ...restOptions } = options || {};
+    super(restOptions);
     this.client = client;
+    this.filters = filters;
+    this.sort = sort;
+    this.searchOptions = searchOptions;
     this.filterBuilder = new FilterBuilder<
       UserFilters,
       UserSearchSourceFilterBuilderContext<TFilterContext>
@@ -55,7 +66,7 @@ export class UserSearchSource<
     });
   }
 
-  protected async query(searchQuery: string) {
+  protected async query(searchQuery: string, queryOptions: SearchQueryOptions = {}) {
     const filters = this.filterBuilder.buildFilters({
       baseFilters: this.filters,
       context: { searchQuery } as UserSearchSourceFilterBuilderContext<TFilterContext>,
@@ -68,7 +79,7 @@ export class UserSearchSource<
       sort = { id: 1, ...this.sort };
     }
     const options = { ...this.searchOptions, limit: this.pageSize, offset: this.offset };
-    const { users } = await this.client.queryUsers(filters, sort, options);
+    const { users } = await this.client.queryUsers(filters, sort, options, queryOptions);
     return { items: users };
   }
 

package/src/search/types.ts

@@ -11,8 +11,21 @@ export type SearchSourceState<T = any> = {
 };
 
 export type SearchSourceOptions = {
-  /** The number of milliseconds to debounce the search query. The default interval is 300ms. */
+  /**
+   * Legacy single debounce interval. When set, it applies to both short and long queries,
+   * unless overridden by `shortQueryDebounceMs` / `longQueryDebounceMs`.
+   */
   debounceMs?: number;
+  /**
+   * Debounce interval for queries no longer than `shortQueryMaxLength`. Such queries have
+   * low selectivity and are expensive server-side, so they are debounced harder.
+   * Defaults to 500ms.
+   */
+  shortQueryDebounceMs?: number;
+  /** Debounce interval for queries longer than `shortQueryMaxLength`. Defaults to 300ms. */
+  longQueryDebounceMs?: number;
+  /** Query length (inclusive) that still counts as short. Defaults to 2. */
+  shortQueryMaxLength?: number;
   pageSize?: number;
   /** When true, the source can execute queries with an empty search string. Defaults to false. */
   allowEmptySearchString?: boolean;

package/src/types.ts

@@ -1189,7 +1189,13 @@ export type ChannelQueryOptions = {
   watchers?: PaginationOptions;
 };
 
-export type ChannelStateOptions = {
+/**
+ * Composed with RequestOptions because `queryChannels` carries the abort signal in this
+ * bag; neither the state flags nor the signal are serialized into the request. Declaring
+ * the composition keeps passing a RequestOptions here intentional rather than incidental
+ * structural compatibility.
+ */
+export type ChannelStateOptions = RequestOptions & {
   offlineMode?: boolean;
   skipInitialization?: string[];
   skipHydration?: boolean;
@@ -1573,6 +1579,12 @@ export type SearchOptions = {
   sort?: SearchMessageSort;
 };
 
+/** Per-request options that are never part of the serialized request payload. */
+export type RequestOptions = {
+  /** Aborts the request. See AbortController. */
+  signal?: AbortSignal;
+};
+
 export type StreamChatOptions = AxiosRequestConfig & {
   /**
    * Used to disable warnings that are triggered by using connectUser or connectAnonymousUser server-side.

package/src/utils.ts

@@ -723,11 +723,13 @@ export interface DebouncedFunc<T extends (...args: any[]) => any> {
   flush(): ReturnType<T> | undefined;
 }
 
-// works exactly the same as lodash.debounce
+// works exactly the same as lodash.debounce, except that the timeout can also be
+// a function of the call arguments, resolved on every call (e.g. to debounce short,
+// low-selectivity search queries harder than long ones)
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const debounce = <T extends (...args: any[]) => any>(
   fn: T,
-  timeout = 0,
+  timeout: number | ((...args: Parameters<T>) => number) = 0,
   { leading = false, trailing = true }: { leading?: boolean; trailing?: boolean } = {},
 ): DebouncedFunc<T> => {
   let runningTimeout: null | NodeJS.Timeout = null;
@@ -750,7 +752,8 @@ export const debounce = <T extends (...args: any[]) => any>(
       runningTimeout = null;
     };
 
-    runningTimeout = setTimeout(timeoutHandler, timeout);
+    const delay = typeof timeout === 'function' ? timeout(...args) : timeout;
+    runningTimeout = setTimeout(timeoutHandler, delay);
     return lastResult;
   };