stream-chat 8.55.0 → 8.56.0

package/src/types.ts

@@ -2,6 +2,7 @@ import { AxiosRequestConfig, AxiosResponse } from 'axios';
 import { StableWSConnection } from './connection';
 import { EVENT_MAP } from './events';
 import { Role } from './permissions';
+import type { Channel } from './channel';
 
 /**
  * Utility Types
@@ -3796,3 +3797,14 @@ export type VelocityFilterConfig = {
   rules: VelocityFilterConfigRule[];
   async?: boolean;
 };
+
+export type PromoteChannelParams<SCG extends ExtendableGenerics = DefaultGenerics> = {
+  channels: Array<Channel<SCG>>;
+  channelToMove: Channel<SCG>;
+  sort: ChannelSort<SCG>;
+  /**
+   * If the index of the channel within `channels` list which is being moved upwards
+   * (`channelToMove`) is known, you can supply it to skip extra calculation.
+   */
+  channelToMoveIndexWithinChannels?: number;
+};

package/src/utils.ts

@@ -12,7 +12,15 @@ import {
   ReactionGroupResponse,
   MessageSet,
   MessagePaginationOptions,
+  ChannelQueryOptions,
+  QueryChannelAPIResponse,
+  ChannelSort,
+  ChannelFilters,
+  ChannelSortBase,
+  PromoteChannelParams,
 } from './types';
+import { StreamChat } from './client';
+import { Channel } from './channel';
 import { AxiosRequestConfig } from 'axios';
 
 /**
@@ -823,3 +831,275 @@ export const messageSetPagination = <StreamChatGenerics extends ExtendableGeneri
     return messagePaginationLinear(params);
   }
 };
+
+/**
+ * A utility object used to prevent duplicate invocation of channel.watch() to be triggered when
+ * 'notification.message_new' and 'notification.added_to_channel' events arrive at the same time.
+ */
+const WATCH_QUERY_IN_PROGRESS_FOR_CHANNEL: Record<string, Promise<QueryChannelAPIResponse> | undefined> = {};
+
+type GetChannelParams<StreamChatGenerics extends ExtendableGenerics = DefaultGenerics> = {
+  client: StreamChat<StreamChatGenerics>;
+  channel?: Channel<StreamChatGenerics>;
+  id?: string;
+  members?: string[];
+  options?: ChannelQueryOptions<StreamChatGenerics>;
+  type?: string;
+};
+/**
+ * Calls channel.watch() if it was not already recently called. Waits for watch promise to resolve even if it was invoked previously.
+ * If the channel is not passed as a property, it will get it either by its channel.cid or by its members list and do the same.
+ * @param client
+ * @param members
+ * @param options
+ * @param type
+ * @param id
+ * @param channel
+ */
+export const getAndWatchChannel = async <StreamChatGenerics extends ExtendableGenerics = DefaultGenerics>({
+  channel,
+  client,
+  id,
+  members,
+  options,
+  type,
+}: GetChannelParams<StreamChatGenerics>) => {
+  if (!channel && !type) {
+    throw new Error('Channel or channel type have to be provided to query a channel.');
+  }
+
+  // unfortunately typescript is not able to infer that if (!channel && !type) === false, then channel or type has to be truthy
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  const channelToWatch = channel || client.channel(type!, id, { members });
+
+  // need to keep as with call to channel.watch the id can be changed from undefined to an actual ID generated server-side
+  const originalCid = channelToWatch.id
+    ? channelToWatch.cid
+    : members && members.length
+    ? generateChannelTempCid(channelToWatch.type, members)
+    : undefined;
+
+  if (!originalCid) {
+    throw new Error('Channel ID or channel members array have to be provided to query a channel.');
+  }
+
+  const queryPromise = WATCH_QUERY_IN_PROGRESS_FOR_CHANNEL[originalCid];
+
+  if (queryPromise) {
+    await queryPromise;
+  } else {
+    try {
+      WATCH_QUERY_IN_PROGRESS_FOR_CHANNEL[originalCid] = channelToWatch.watch(options);
+      await WATCH_QUERY_IN_PROGRESS_FOR_CHANNEL[originalCid];
+    } finally {
+      delete WATCH_QUERY_IN_PROGRESS_FOR_CHANNEL[originalCid];
+    }
+  }
+
+  return channelToWatch;
+};
+
+/**
+ * Generates a temporary channel.cid for channels created without ID, as they need to be referenced
+ * by an identifier until the back-end generates the final ID. The cid is generated by its member IDs
+ * which are sorted and can be recreated the same every time given the same arguments.
+ * @param channelType
+ * @param members
+ */
+export const generateChannelTempCid = (channelType: string, members: string[]) => {
+  if (!members) return;
+  const membersStr = [...members].sort().join(',');
+  if (!membersStr) return;
+  return `${channelType}:!members-${membersStr}`;
+};
+
+/**
+ * Checks if a channel is pinned or not. Will return true only if channel.state.membership.pinned_at exists.
+ * @param channel
+ */
+export const isChannelPinned = <StreamChatGenerics extends ExtendableGenerics = DefaultGenerics>(
+  channel: Channel<StreamChatGenerics>,
+) => {
+  if (!channel) return false;
+
+  const member = channel.state.membership;
+
+  return !!member?.pinned_at;
+};
+
+/**
+ * Checks if a channel is archived or not. Will return true only if channel.state.membership.archived_at exists.
+ * @param channel
+ */
+export const isChannelArchived = <StreamChatGenerics extends ExtendableGenerics = DefaultGenerics>(
+  channel: Channel<StreamChatGenerics>,
+) => {
+  if (!channel) return false;
+
+  const member = channel.state.membership;
+
+  return !!member?.archived_at;
+};
+
+/**
+ * A utility that tells us whether we should consider archived channels or not based
+ * on filters. Will return true only if filters.archived exists and is a boolean value.
+ * @param filters
+ */
+export const shouldConsiderArchivedChannels = <StreamChatGenerics extends ExtendableGenerics = DefaultGenerics>(
+  filters: ChannelFilters<StreamChatGenerics>,
+) => {
+  if (!filters) return false;
+
+  return typeof filters.archived === 'boolean';
+};
+
+/**
+ * Extracts the value of the sort parameter at a given index, for a targeted key. Can
+ * handle both array and object versions of sort. Will return null if the index/key
+ * combination does not exist.
+ * @param atIndex - the index at which we'll examine the sort value, if it's an array one
+ * @param sort - the sort value - both array and object notations are accepted
+ * @param targetKey - the target key which needs to exist for the sort at a certain index
+ */
+export const extractSortValue = <StreamChatGenerics extends ExtendableGenerics = DefaultGenerics>({
+  atIndex,
+  sort,
+  targetKey,
+}: {
+  atIndex: number;
+  targetKey: keyof ChannelSortBase<StreamChatGenerics>;
+  sort?: ChannelSort<StreamChatGenerics>;
+}) => {
+  if (!sort) return null;
+  let option: null | ChannelSortBase<StreamChatGenerics> = null;
+
+  if (Array.isArray(sort)) {
+    option = sort[atIndex] ?? null;
+  } else {
+    let index = 0;
+    for (const key in sort) {
+      if (index !== atIndex) {
+        index++;
+        continue;
+      }
+
+      if (key !== targetKey) {
+        return null;
+      }
+
+      option = sort;
+
+      break;
+    }
+  }
+
+  return option?.[targetKey] ?? null;
+};
+
+/**
+ * Returns true only if `{ pinned_at: -1 }` or `{ pinned_at: 1 }` option is first within the `sort` array.
+ */
+export const shouldConsiderPinnedChannels = <StreamChatGenerics extends ExtendableGenerics = DefaultGenerics>(
+  sort: ChannelSort<StreamChatGenerics>,
+) => {
+  const value = findPinnedAtSortOrder({ sort });
+
+  if (typeof value !== 'number') return false;
+
+  return Math.abs(value) === 1;
+};
+
+/**
+ * Checks whether the sort value of type object contains a pinned_at value or if
+ * an array sort value type has the first value be an object containing pinned_at.
+ * @param sort
+ */
+export const findPinnedAtSortOrder = <StreamChatGenerics extends ExtendableGenerics = DefaultGenerics>({
+  sort,
+}: {
+  sort: ChannelSort<StreamChatGenerics>;
+}) =>
+  extractSortValue({
+    atIndex: 0,
+    sort,
+    targetKey: 'pinned_at',
+  });
+
+/**
+ * Finds the index of the last consecutively pinned channel, starting from the start of the
+ * array. Will not consider any pinned channels after the contiguous subsequence at the
+ * start of the array.
+ * @param channels
+ */
+export const findLastPinnedChannelIndex = <StreamChatGenerics extends ExtendableGenerics = DefaultGenerics>({
+  channels,
+}: {
+  channels: Channel<StreamChatGenerics>[];
+}) => {
+  let lastPinnedChannelIndex: number | null = null;
+
+  for (const channel of channels) {
+    if (!isChannelPinned(channel)) break;
+
+    if (typeof lastPinnedChannelIndex === 'number') {
+      lastPinnedChannelIndex++;
+    } else {
+      lastPinnedChannelIndex = 0;
+    }
+  }
+
+  return lastPinnedChannelIndex;
+};
+
+/**
+ * A utility used to move a channel towards the beginning of a list of channels (promote it to a higher position). It
+ * considers pinned channels in the process if needed and makes sure to only update the list reference if the list
+ * should actually change. It will try to move the channel as high as it can within the list.
+ * @param channels - the list of channels we want to modify
+ * @param channelToMove - the channel we want to promote
+ * @param channelToMoveIndexWithinChannels - optionally, the index of the channel we want to move if we know it (will skip a manual check)
+ * @param sort - the sort value used to check for pinned channels
+ */
+export const promoteChannel = <StreamChatGenerics extends ExtendableGenerics = DefaultGenerics>({
+  channels,
+  channelToMove,
+  channelToMoveIndexWithinChannels,
+  sort,
+}: PromoteChannelParams<StreamChatGenerics>) => {
+  // get index of channel to move up
+  const targetChannelIndex =
+    channelToMoveIndexWithinChannels ?? channels.findIndex((channel) => channel.cid === channelToMove.cid);
+
+  const targetChannelExistsWithinList = targetChannelIndex >= 0;
+  const targetChannelAlreadyAtTheTop = targetChannelIndex === 0;
+
+  // pinned channels should not move within the list based on recent activity, channels which
+  // receive messages and are not pinned should move upwards but only under the last pinned channel
+  // in the list
+  const considerPinnedChannels = shouldConsiderPinnedChannels(sort);
+  const isTargetChannelPinned = isChannelPinned<StreamChatGenerics>(channelToMove);
+
+  if (targetChannelAlreadyAtTheTop || (considerPinnedChannels && isTargetChannelPinned)) {
+    return channels;
+  }
+
+  const newChannels = [...channels];
+
+  // target channel index is known, remove it from the list
+  if (targetChannelExistsWithinList) {
+    newChannels.splice(targetChannelIndex, 1);
+  }
+
+  // as position of pinned channels has to stay unchanged, we need to
+  // find last pinned channel in the list to move the target channel after
+  let lastPinnedChannelIndex: number | null = null;
+  if (considerPinnedChannels) {
+    lastPinnedChannelIndex = findLastPinnedChannelIndex({ channels: newChannels });
+  }
+
+  // re-insert it at the new place (to specific index if pinned channels are considered)
+  newChannels.splice(typeof lastPinnedChannelIndex === 'number' ? lastPinnedChannelIndex + 1 : 0, 0, channelToMove);
+
+  return newChannels;
+};