stream-chat 8.54.1 → 8.56.0

package/src/channel_manager.ts

@@ -0,0 +1,581 @@
+import type { StreamChat } from './client';
+import type {
+  DefaultGenerics,
+  ExtendableGenerics,
+  Event,
+  ChannelOptions,
+  ChannelStateOptions,
+  ChannelFilters,
+  ChannelSort,
+} from './types';
+import { StateStore, ValueOrPatch, isPatch } from './store';
+import { Channel } from './channel';
+import {
+  extractSortValue,
+  findLastPinnedChannelIndex,
+  getAndWatchChannel,
+  isChannelArchived,
+  isChannelPinned,
+  promoteChannel,
+  shouldConsiderArchivedChannels,
+  shouldConsiderPinnedChannels,
+} from './utils';
+
+export type ChannelManagerPagination<SCG extends ExtendableGenerics = DefaultGenerics> = {
+  filters: ChannelFilters<SCG>;
+  hasNext: boolean;
+  isLoading: boolean;
+  isLoadingNext: boolean;
+  options: ChannelOptions;
+  sort: ChannelSort<SCG>;
+};
+
+export type ChannelManagerState<SCG extends ExtendableGenerics = DefaultGenerics> = {
+  channels: Channel<SCG>[];
+  /**
+   * This value will become true the first time queryChannels is successfully executed and
+   * will remain false otherwise. It's used as a control property regarding whether the list
+   * has been initialized yet (i.e a query has already been done at least once) or not. We do
+   * this to prevent state.channels from being forced to be nullable.
+   */
+  initialized: boolean;
+  pagination: ChannelManagerPagination<SCG>;
+};
+
+export type ChannelSetterParameterType<SCG extends ExtendableGenerics = DefaultGenerics> = ValueOrPatch<
+  ChannelManagerState<SCG>['channels']
+>;
+export type ChannelSetterType<SCG extends ExtendableGenerics = DefaultGenerics> = (
+  arg: ChannelSetterParameterType<SCG>,
+) => void;
+
+export type GenericEventHandlerType<T extends unknown[]> = (
+  ...args: T
+) => void | (() => void) | ((...args: T) => Promise<void>) | Promise<void>;
+export type EventHandlerType<SCG extends ExtendableGenerics = DefaultGenerics> = GenericEventHandlerType<[Event<SCG>]>;
+export type EventHandlerOverrideType<SCG extends ExtendableGenerics = DefaultGenerics> = GenericEventHandlerType<
+  [ChannelSetterType<SCG>, Event<SCG>]
+>;
+
+export type ChannelManagerEventTypes =
+  | 'notification.added_to_channel'
+  | 'notification.message_new'
+  | 'notification.removed_from_channel'
+  | 'message.new'
+  | 'member.updated'
+  | 'channel.deleted'
+  | 'channel.hidden'
+  | 'channel.truncated'
+  | 'channel.visible';
+
+export type ChannelManagerEventHandlerNames =
+  | 'channelDeletedHandler'
+  | 'channelHiddenHandler'
+  | 'channelTruncatedHandler'
+  | 'channelVisibleHandler'
+  | 'newMessageHandler'
+  | 'memberUpdatedHandler'
+  | 'notificationAddedToChannelHandler'
+  | 'notificationNewMessageHandler'
+  | 'notificationRemovedFromChannelHandler';
+
+export type ChannelManagerEventHandlerOverrides<SCG extends ExtendableGenerics = DefaultGenerics> = Partial<
+  Record<ChannelManagerEventHandlerNames, EventHandlerOverrideType<SCG>>
+>;
+
+export const channelManagerEventToHandlerMapping: {
+  [key in ChannelManagerEventTypes]: ChannelManagerEventHandlerNames;
+} = {
+  'channel.deleted': 'channelDeletedHandler',
+  'channel.hidden': 'channelHiddenHandler',
+  'channel.truncated': 'channelTruncatedHandler',
+  'channel.visible': 'channelVisibleHandler',
+  'message.new': 'newMessageHandler',
+  'member.updated': 'memberUpdatedHandler',
+  'notification.added_to_channel': 'notificationAddedToChannelHandler',
+  'notification.message_new': 'notificationNewMessageHandler',
+  'notification.removed_from_channel': 'notificationRemovedFromChannelHandler',
+};
+
+export type ChannelManagerOptions = {
+  /**
+   * Aborts a channels query that is already in progress and runs the new one.
+   */
+  abortInFlightQuery?: boolean;
+  /**
+   * Allows channel promotion to be applied where applicable for channels that are
+   * currently not part of the channel list within the state. A good example of
+   * this would be a channel that is being watched and it receives a new message,
+   * but is not part of the list initially.
+   */
+  allowNotLoadedChannelPromotionForEvent?: {
+    'channel.visible': boolean;
+    'message.new': boolean;
+    'notification.added_to_channel': boolean;
+    'notification.message_new': boolean;
+  };
+  /**
+   * Allows us to lock the order of channels within the list. Any event that would
+   * change the order of channels within the list will do nothing.
+   */
+  lockChannelOrder?: boolean;
+};
+
+export const DEFAULT_CHANNEL_MANAGER_OPTIONS = {
+  abortInFlightQuery: false,
+  allowNotLoadedChannelPromotionForEvent: {
+    'channel.visible': true,
+    'message.new': true,
+    'notification.added_to_channel': true,
+    'notification.message_new': true,
+  },
+  lockChannelOrder: false,
+};
+
+export const DEFAULT_CHANNEL_MANAGER_PAGINATION_OPTIONS = {
+  limit: 10,
+  offset: 0,
+};
+
+/**
+ * A class that manages a list of channels and changes it based on configuration and WS events. The
+ * list of channels is reactive as well as the pagination and it can be subscribed to for state updates.
+ *
+ * @internal
+ */
+export class ChannelManager<SCG extends ExtendableGenerics = DefaultGenerics> {
+  public readonly state: StateStore<ChannelManagerState<SCG>>;
+  private client: StreamChat<SCG>;
+  private unsubscribeFunctions: Set<() => void> = new Set();
+  private eventHandlers: Map<string, EventHandlerType<SCG>> = new Map();
+  private eventHandlerOverrides: Map<string, EventHandlerOverrideType<SCG>> = new Map();
+  private options: ChannelManagerOptions = {};
+  private stateOptions: ChannelStateOptions = {};
+
+  constructor({
+    client,
+    eventHandlerOverrides = {},
+    options = {},
+  }: {
+    client: StreamChat<SCG>;
+    eventHandlerOverrides?: ChannelManagerEventHandlerOverrides<SCG>;
+    options?: ChannelManagerOptions;
+  }) {
+    this.client = client;
+    this.state = new StateStore<ChannelManagerState<SCG>>({
+      channels: [],
+      pagination: {
+        isLoading: false,
+        isLoadingNext: false,
+        hasNext: false,
+        filters: {},
+        sort: {},
+        options: DEFAULT_CHANNEL_MANAGER_PAGINATION_OPTIONS,
+      },
+      initialized: false,
+    });
+    this.setEventHandlerOverrides(eventHandlerOverrides);
+    this.setOptions(options);
+    this.eventHandlers = new Map(
+      Object.entries<EventHandlerType<SCG>>({
+        channelDeletedHandler: this.channelDeletedHandler,
+        channelHiddenHandler: this.channelHiddenHandler,
+        channelVisibleHandler: this.channelVisibleHandler,
+        memberUpdatedHandler: this.memberUpdatedHandler,
+        newMessageHandler: this.newMessageHandler,
+        notificationAddedToChannelHandler: this.notificationAddedToChannelHandler,
+        notificationNewMessageHandler: this.notificationNewMessageHandler,
+        notificationRemovedFromChannelHandler: this.notificationRemovedFromChannelHandler,
+      }),
+    );
+  }
+
+  public setChannels = (valueOrFactory: ChannelSetterParameterType<SCG>) => {
+    this.state.next((current) => {
+      const { channels: currentChannels } = current;
+      const newChannels = isPatch(valueOrFactory) ? valueOrFactory(currentChannels) : valueOrFactory;
+
+      // If the references between the two values are the same, just return the
+      // current state; otherwise trigger a state change.
+      if (currentChannels === newChannels) {
+        return current;
+      }
+      return { ...current, channels: newChannels };
+    });
+  };
+
+  public setEventHandlerOverrides = (eventHandlerOverrides: ChannelManagerEventHandlerOverrides<SCG> = {}) => {
+    const truthyEventHandlerOverrides = Object.entries(eventHandlerOverrides).reduce<
+      Partial<ChannelManagerEventHandlerOverrides<SCG>>
+    >((acc, [key, value]) => {
+      if (value) {
+        acc[key as keyof ChannelManagerEventHandlerOverrides<SCG>] = value;
+      }
+      return acc;
+    }, {});
+    this.eventHandlerOverrides = new Map(Object.entries<EventHandlerOverrideType<SCG>>(truthyEventHandlerOverrides));
+  };
+
+  public setOptions = (options: ChannelManagerOptions = {}) => {
+    this.options = { ...DEFAULT_CHANNEL_MANAGER_OPTIONS, ...options };
+  };
+
+  public queryChannels = async (
+    filters: ChannelFilters<SCG>,
+    sort: ChannelSort<SCG> = [],
+    options: ChannelOptions = {},
+    stateOptions: ChannelStateOptions = {},
+  ) => {
+    const { offset, limit } = { ...DEFAULT_CHANNEL_MANAGER_PAGINATION_OPTIONS, ...options };
+    const {
+      pagination: { isLoading },
+    } = this.state.getLatestValue();
+
+    if (isLoading && !this.options.abortInFlightQuery) {
+      return;
+    }
+
+    try {
+      this.stateOptions = stateOptions;
+      this.state.next((currentState) => ({
+        ...currentState,
+        pagination: {
+          ...currentState.pagination,
+          isLoading: true,
+          isLoadingNext: false,
+          filters,
+          sort,
+          options,
+        },
+      }));
+
+      const channels = await this.client.queryChannels(filters, sort, options, stateOptions);
+      const newOffset = offset + (channels?.length ?? 0);
+      const newOptions = { ...options, offset: newOffset };
+      const { pagination } = this.state.getLatestValue();
+
+      this.state.partialNext({
+        channels,
+        pagination: {
+          ...pagination,
+          hasNext: (channels?.length ?? 0) >= limit,
+          isLoading: false,
+          options: newOptions,
+        },
+        initialized: true,
+      });
+    } catch (error) {
+      this.client.logger('error', (error as Error).message);
+      this.state.next((currentState) => ({
+        ...currentState,
+        pagination: { ...currentState.pagination, isLoading: false },
+      }));
+      throw error;
+    }
+  };
+
+  public loadNext = async () => {
+    const { pagination, channels, initialized } = this.state.getLatestValue();
+    const { filters, sort, options, isLoadingNext, hasNext } = pagination;
+
+    if (!initialized || isLoadingNext || !hasNext) {
+      return;
+    }
+
+    try {
+      const { offset, limit } = { ...DEFAULT_CHANNEL_MANAGER_PAGINATION_OPTIONS, ...options };
+      this.state.partialNext({
+        pagination: { ...pagination, isLoading: false, isLoadingNext: true },
+      });
+      const nextChannels = await this.client.queryChannels(filters, sort, options, this.stateOptions);
+      const newOffset = offset + (nextChannels?.length ?? 0);
+      const newOptions = { ...options, offset: newOffset };
+
+      this.state.partialNext({
+        channels: [...(channels || []), ...nextChannels],
+        pagination: {
+          ...pagination,
+          hasNext: (nextChannels?.length ?? 0) >= limit,
+          isLoading: false,
+          isLoadingNext: false,
+          options: newOptions,
+        },
+      });
+    } catch (error) {
+      this.client.logger('error', (error as Error).message);
+      this.state.next((currentState) => ({
+        ...currentState,
+        pagination: { ...currentState.pagination, isLoadingNext: false },
+      }));
+      throw error;
+    }
+  };
+
+  private notificationAddedToChannelHandler = async (event: Event<SCG>) => {
+    const { id, type, members } = event?.channel ?? {};
+    if (!type || !this.options.allowNotLoadedChannelPromotionForEvent?.['notification.added_to_channel']) {
+      return;
+    }
+    const channel = await getAndWatchChannel({
+      client: this.client,
+      id,
+      members: members?.reduce<string[]>((acc, { user, user_id }) => {
+        const userId = user_id || user?.id;
+        if (userId) {
+          acc.push(userId);
+        }
+        return acc;
+      }, []),
+      type,
+    });
+    const { pagination, channels } = this.state.getLatestValue();
+    if (!channels) {
+      return;
+    }
+
+    const { sort } = pagination ?? {};
+
+    this.setChannels(
+      promoteChannel({
+        channels,
+        channelToMove: channel,
+        sort,
+      }),
+    );
+  };
+
+  private channelDeletedHandler = (event: Event<SCG>) => {
+    const { channels } = this.state.getLatestValue();
+    if (!channels) {
+      return;
+    }
+
+    const newChannels = [...channels];
+    const channelIndex = newChannels.findIndex((channel) => channel.cid === (event.cid || event.channel?.cid));
+
+    if (channelIndex < 0) {
+      return;
+    }
+
+    newChannels.splice(channelIndex, 1);
+    this.setChannels(newChannels);
+  };
+
+  private channelHiddenHandler = this.channelDeletedHandler;
+
+  private newMessageHandler = (event: Event<SCG>) => {
+    const { pagination, channels } = this.state.getLatestValue();
+    if (!channels) {
+      return;
+    }
+    const { filters, sort } = pagination ?? {};
+
+    const channelType = event.channel_type;
+    const channelId = event.channel_id;
+
+    if (!channelType || !channelId) {
+      return;
+    }
+
+    const targetChannel = this.client.channel(channelType, channelId);
+    const targetChannelIndex = channels.indexOf(targetChannel);
+    const targetChannelExistsWithinList = targetChannelIndex >= 0;
+
+    const isTargetChannelPinned = isChannelPinned(targetChannel);
+    const isTargetChannelArchived = isChannelArchived(targetChannel);
+
+    const considerArchivedChannels = shouldConsiderArchivedChannels(filters);
+    const considerPinnedChannels = shouldConsiderPinnedChannels(sort);
+
+    if (
+      // filter is defined, target channel is archived and filter option is set to false
+      (considerArchivedChannels && isTargetChannelArchived && !filters.archived) ||
+      // filter is defined, target channel isn't archived and filter option is set to true
+      (considerArchivedChannels && !isTargetChannelArchived && filters.archived) ||
+      // sort option is defined, target channel is pinned
+      (considerPinnedChannels && isTargetChannelPinned) ||
+      // list order is locked
+      this.options.lockChannelOrder ||
+      // target channel is not within the loaded list and loading from cache is disallowed
+      (!targetChannelExistsWithinList && !this.options.allowNotLoadedChannelPromotionForEvent?.['message.new'])
+    ) {
+      return;
+    }
+
+    this.setChannels(
+      promoteChannel({
+        channels,
+        channelToMove: targetChannel,
+        channelToMoveIndexWithinChannels: targetChannelIndex,
+        sort,
+      }),
+    );
+  };
+
+  private notificationNewMessageHandler = async (event: Event<SCG>) => {
+    const { id, type } = event?.channel ?? {};
+
+    const { channels, pagination } = this.state.getLatestValue();
+    const { filters, sort } = pagination ?? {};
+
+    if (!channels || !id || !type) {
+      return;
+    }
+
+    const channel = await getAndWatchChannel({
+      client: this.client,
+      id,
+      type,
+    });
+
+    const considerArchivedChannels = shouldConsiderArchivedChannels(filters);
+    const isTargetChannelArchived = isChannelArchived(channel);
+
+    if (
+      (considerArchivedChannels && isTargetChannelArchived && !filters.archived) ||
+      (considerArchivedChannels && !isTargetChannelArchived && filters.archived) ||
+      !this.options.allowNotLoadedChannelPromotionForEvent?.['notification.message_new']
+    ) {
+      return;
+    }
+
+    this.setChannels(
+      promoteChannel({
+        channels,
+        channelToMove: channel,
+        sort,
+      }),
+    );
+  };
+
+  private channelVisibleHandler = async (event: Event<SCG>) => {
+    const { channels, pagination } = this.state.getLatestValue();
+    const { sort, filters } = pagination ?? {};
+    const { channel_type: channelType, channel_id: channelId } = event;
+
+    if (!channels || !channelType || !channelId) {
+      return;
+    }
+
+    const channel = await getAndWatchChannel({
+      client: this.client,
+      id: event.channel_id,
+      type: event.channel_type,
+    });
+
+    const considerArchivedChannels = shouldConsiderArchivedChannels(filters);
+    const isTargetChannelArchived = isChannelArchived(channel);
+
+    if (
+      (considerArchivedChannels && isTargetChannelArchived && !filters.archived) ||
+      (considerArchivedChannels && !isTargetChannelArchived && filters.archived) ||
+      !this.options.allowNotLoadedChannelPromotionForEvent?.['channel.visible']
+    ) {
+      return;
+    }
+
+    this.setChannels(
+      promoteChannel({
+        channels,
+        channelToMove: channel,
+        sort,
+      }),
+    );
+  };
+
+  private notificationRemovedFromChannelHandler = this.channelDeletedHandler;
+
+  private memberUpdatedHandler = (event: Event<SCG>) => {
+    const { pagination, channels } = this.state.getLatestValue();
+    const { filters, sort } = pagination;
+    if (
+      !event.member?.user ||
+      event.member.user.id !== this.client.userID ||
+      !event.channel_type ||
+      !event.channel_id
+    ) {
+      return;
+    }
+    const channelType = event.channel_type;
+    const channelId = event.channel_id;
+
+    const considerPinnedChannels = shouldConsiderPinnedChannels(sort);
+    const considerArchivedChannels = shouldConsiderArchivedChannels(filters);
+    const pinnedAtSort = extractSortValue({ atIndex: 0, sort, targetKey: 'pinned_at' });
+
+    if (!channels || (!considerPinnedChannels && !considerArchivedChannels) || this.options.lockChannelOrder) {
+      return;
+    }
+
+    const targetChannel = this.client.channel(channelType, channelId);
+    // assumes that channel instances are not changing
+    const targetChannelIndex = channels.indexOf(targetChannel);
+    const targetChannelExistsWithinList = targetChannelIndex >= 0;
+
+    const isTargetChannelPinned = isChannelPinned(targetChannel);
+    const isTargetChannelArchived = isChannelArchived(targetChannel);
+
+    const newChannels = [...channels];
+
+    if (targetChannelExistsWithinList) {
+      newChannels.splice(targetChannelIndex, 1);
+    }
+
+    // handle archiving (remove channel)
+    if (
+      // When archived filter true, and channel is unarchived
+      (considerArchivedChannels && !isTargetChannelArchived && filters?.archived) ||
+      // When archived filter false, and channel is archived
+      (considerArchivedChannels && isTargetChannelArchived && !filters?.archived)
+    ) {
+      this.setChannels(newChannels);
+      return;
+    }
+
+    // handle pinning
+    let lastPinnedChannelIndex: number | null = null;
+
+    if (pinnedAtSort === 1 || (pinnedAtSort === -1 && !isTargetChannelPinned)) {
+      lastPinnedChannelIndex = findLastPinnedChannelIndex({ channels: newChannels });
+    }
+    const newTargetChannelIndex = typeof lastPinnedChannelIndex === 'number' ? lastPinnedChannelIndex + 1 : 0;
+
+    // skip state update if the position of the channel does not change
+    if (channels[newTargetChannelIndex] === targetChannel) {
+      return;
+    }
+
+    newChannels.splice(newTargetChannelIndex, 0, targetChannel);
+    this.setChannels(newChannels);
+  };
+
+  private subscriptionOrOverride = (event: Event<SCG>) => {
+    const handlerName = channelManagerEventToHandlerMapping[event.type as ChannelManagerEventTypes];
+    const defaultEventHandler = this.eventHandlers.get(handlerName);
+    const eventHandlerOverride = this.eventHandlerOverrides.get(handlerName);
+    if (eventHandlerOverride && typeof eventHandlerOverride === 'function') {
+      eventHandlerOverride(this.setChannels, event);
+      return;
+    }
+
+    if (defaultEventHandler && typeof defaultEventHandler === 'function') {
+      defaultEventHandler(event);
+    }
+  };
+
+  public registerSubscriptions = () => {
+    if (this.unsubscribeFunctions.size) {
+      // Already listening for events and changes
+      return;
+    }
+
+    for (const eventType of Object.keys(channelManagerEventToHandlerMapping)) {
+      this.unsubscribeFunctions.add(this.client.on(eventType, this.subscriptionOrOverride).unsubscribe);
+    }
+  };
+
+  public unregisterSubscriptions = () => {
+    this.unsubscribeFunctions.forEach((cleanupFunction) => cleanupFunction());
+    this.unsubscribeFunctions.clear();
+  };
+}

package/src/client.ts

@@ -18,6 +18,7 @@ import {
   addFileToFormData,
   axiosParamsSerializer,
   chatCodes,
+  generateChannelTempCid,
   isFunction,
   isOnline,
   isOwnUserBaseProperty,
@@ -126,6 +127,7 @@ import {
   Mute,
   MuteUserOptions,
   MuteUserResponse,
+  NewMemberPayload,
   OGAttachment,
   OwnUserResponse,
   PartialMessageUpdate,
@@ -216,6 +218,7 @@ import { Moderation } from './moderation';
 import { ThreadManager } from './thread_manager';
 import { DEFAULT_QUERY_CHANNELS_MESSAGE_LIST_PAGE_SIZE } from './constants';
 import { PollManager } from './poll_manager';
+import { ChannelManager, ChannelManagerEventHandlerOverrides, ChannelManagerOptions } from './channel_manager';
 
 function isString(x: unknown): x is string {
   return typeof x === 'string' || x instanceof String;
@@ -599,6 +602,24 @@ export class StreamChat<StreamChatGenerics extends ExtendableGenerics = DefaultG
     return Promise.resolve();
   };
 
+  /**
+   * Creates an instance of ChannelManager.
+   *
+   * @internal
+   *
+   * @param eventHandlerOverrides - the overrides for event handlers to be used
+   * @param options - the options used for the channel manager
+   */
+  createChannelManager = ({
+    eventHandlerOverrides = {},
+    options = {},
+  }: {
+    eventHandlerOverrides?: ChannelManagerEventHandlerOverrides<StreamChatGenerics>;
+    options?: ChannelManagerOptions;
+  }) => {
+    return new ChannelManager({ client: this, eventHandlerOverrides, options });
+  };
+
   /**
    * Creates a new WebSocket connection with the current user. Returns empty promise, if there is an active connection
    */
@@ -1935,10 +1956,13 @@ export class StreamChat<StreamChatGenerics extends ExtendableGenerics = DefaultG
   getChannelByMembers = (channelType: string, custom: ChannelData<StreamChatGenerics>) => {
     // Check if the channel already exists.
     // Only allow 1 channel object per cid
-    const membersStr = [...(custom.members || [])].sort().join(',');
-    const tempCid = `${channelType}:!members-${membersStr}`;
+    const memberIds = (custom.members ?? []).map((member: string | NewMemberPayload<StreamChatGenerics>) =>
+      typeof member === 'string' ? member : member.user_id ?? '',
+    );
+    const membersStr = memberIds.sort().join(',');
+    const tempCid = generateChannelTempCid(channelType, memberIds);
 
-    if (!membersStr) {
+    if (!tempCid) {
       throw Error('Please specify atleast one member when creating unique conversation');
     }
 

package/src/index.ts

@@ -11,6 +11,7 @@ export * from './moderation';
 export * from './permissions';
 export * from './poll';
 export * from './poll_manager';
+export * from './search_controller';
 export * from './segment';
 export * from './signing';
 export * from './store';
@@ -19,4 +20,5 @@ export type { ThreadState, ThreadReadState, ThreadRepliesPagination, ThreadUserR
 export * from './thread_manager';
 export * from './token_manager';
 export * from './types';
+export * from './channel_manager';
 export { isOwnUser, chatCodes, logChatPromiseExecution, formatMessage } from './utils';