stream-chat 9.50.2 → 10.0.0-rc.1

package/src/offline-support/offline_sync_manager.ts

@@ -3,7 +3,10 @@ import type { StreamChat } from '../client';
 import type { AbstractOfflineDB } from './offline_support_api';
 import type { AxiosError } from 'axios';
 import { isAxiosError } from 'axios';
-import type { APIErrorResponse } from '../types';
+import { chatLoggerSystem } from '../logger';
+import type { APIError } from '../types';
+
+const logger = chatLoggerSystem.getLogger('offline-db');
 
 /**
  * Manages synchronization between the local offline database and the Stream backend.
@@ -40,8 +43,8 @@ export class OfflineDBSyncManager {
    */
   public init = async () => {
     try {
-      // If the websocket connection is already active, then call
-      // the sync api straight away and also execute pending api calls.
+      // If the WebSocket connection is already active, then call
+      // the sync API straight away and also execute pending API calls.
       // Otherwise wait for the `connection.changed` event.
       if (this.client.user?.id && this.client.wsConnection?.isHealthy) {
         await this.syncAndExecutePendingTasks();
@@ -69,7 +72,9 @@ export class OfflineDBSyncManager {
         },
       );
     } catch (error) {
-      console.log('Error in DBSyncManager.init: ', error);
+      logger
+        .withExtraTags('init')
+        .error('Failed to initialize the offline DB sync manager.', { error });
     }
   };
 
@@ -159,7 +164,10 @@ export class OfflineDBSyncManager {
           // In that case reset the entire DB and start fresh.
           await this.offlineDb.resetDB();
         } else {
-          const result = await this.client.sync(cids, lastSyncedAtDate.toISOString());
+          const result = await this.client.sync({
+            channel_cids: cids,
+            last_sync_at: lastSyncedAtDate,
+          });
           const queryPromises = result.events.map((event) =>
             this.offlineDb.handleEvent({ event, execute: false }),
           );
@@ -176,14 +184,16 @@ export class OfflineDBSyncManager {
         lastSyncedAt: new Date().toString(),
       });
     } catch (e) {
-      console.log('An error has occurred while syncing the DB.', e);
+      logger
+        .withExtraTags('syncAndExecutePendingTasks')
+        .error('An error occurred while syncing the database.', { error: e });
 
       if (isAxiosError(e) && e.code === 'ECONNABORTED') {
         // If the sync was aborted due to timeout, we can simply return
         return;
       }
 
-      const error = e as AxiosError<APIErrorResponse>;
+      const error = e as AxiosError<APIError>;
 
       if (error.response?.data?.code === 23) {
         return;

package/src/offline-support/types.ts

@@ -1,19 +1,20 @@
 import type {
-  AppSettingsAPIResponse,
-  ChannelAPIResponse,
   ChannelFilters,
   ChannelMemberResponse,
   ChannelOptions,
   ChannelResponse,
   ChannelSort,
+  ChannelStateResponseFields,
   DraftResponse,
+  GetApplicationResponse,
   LocalMessage,
   MessageResponse,
-  PollResponse,
+  PollResponse_old,
+  QueryChannelsRequest,
   ReactionFilters,
   ReactionResponse,
   ReactionSort,
-  ReadResponse,
+  ReadStateResponse,
 } from '../types';
 import type { Channel } from '../channel';
 import type { StreamChat } from '../client';
@@ -26,7 +27,7 @@ export type PrepareBatchDBQueries =
  * Options to insert a reaction into a message.
  */
 export type DBInsertReactionType = {
-  /** Message to which the reaction is applied. */
+  /** MessageRequest to which the reaction is applied. */
   message: MessageResponse | LocalMessage;
   /** The reaction to insert. */
   reaction: ReactionResponse;
@@ -55,7 +56,7 @@ export type DBUpsertCidsForQueryType = {
  */
 export type DBUpsertChannelsType = {
   /** Array of channel API responses. */
-  channels: ChannelAPIResponse[];
+  channels: ChannelStateResponseFields[];
   /** Whether to immediately execute the operation. */
   execute?: boolean;
   /** If true, marks that the latest messages are already set. */
@@ -67,7 +68,7 @@ export type DBUpsertChannelsType = {
  */
 export type DBUpsertAppSettingsType = {
   /** App settings data. */
-  appSettings: AppSettingsAPIResponse;
+  appSettings: GetApplicationResponse;
   /** ID of the user the settings belong to. */
   userId: string;
   /** Whether to immediately execute the operation. */
@@ -91,7 +92,7 @@ export type DBUpsertUserSyncStatusType = {
  */
 export type DBUpsertPollType = {
   /** Poll data to be stored. */
-  poll: PollResponse;
+  poll: PollResponse_old;
   /** Whether to immediately execute the operation. */
   execute?: boolean;
 };
@@ -113,7 +114,7 @@ export type DBUpsertReadsType = {
   /** Channel ID. */
   cid: string;
   /** Array of read statuses. */
-  reads: ReadResponse[];
+  reads: ReadStateResponse[];
   /** Whether to immediately execute the operation. */
   execute?: boolean;
 };
@@ -144,7 +145,7 @@ export type DBUpsertMembersType = {
  * Options to update a reaction.
  */
 export type DBUpdateReactionType = {
-  /** Message associated with the reaction. */
+  /** MessageRequest associated with the reaction. */
   message: MessageResponse | LocalMessage;
   /** The updated reaction. */
   reaction: ReactionResponse;
@@ -156,7 +157,7 @@ export type DBUpdateReactionType = {
  * Options to update a message.
  */
 export type DBUpdateMessageType = {
-  /** Message to update. */
+  /** MessageRequest to update. */
   message: MessageResponse | LocalMessage;
   /** Whether to immediately execute the operation. */
   execute?: boolean;
@@ -179,15 +180,11 @@ export type DBGetChannelsForQueryType = {
   /** ID of the user. */
   userId: string;
   /** Optional filters for channels. */
-  filters?: ChannelFilters;
-  /** Optional full query options for channels. */
-  options?: ChannelOptions;
-  /** Optional sorting for the channels. */
-  sort?: ChannelSort;
+  options?: QueryChannelsRequest;
 };
 
 /**
- * Get the last sync timestamp for a user.
+ * Payload for retrieving the last sync timestamp for a user.
  */
 export type DBGetLastSyncedAtType = {
   /** ID of the user. */
@@ -203,7 +200,7 @@ export type DBGetPendingTasksType = {
 };
 
 /**
- * Get application settings for a user.
+ * Payload for retrieving application settings for a user.
  */
 export type DBGetAppSettingsType = {
   /** ID of the user. */
@@ -217,7 +214,7 @@ export type DBGetReactionsType = {
   /** ID of the message. */
   messageId: string;
   /** Optional filter to apply to reactions. */
-  filters?: Pick<ReactionFilters, 'type'>;
+  filters?: ReactionFilters;
   /** Optional sorting for reactions. */
   sort?: ReactionSort;
   /** Optional maximum number of reactions to return. */
@@ -225,7 +222,7 @@ export type DBGetReactionsType = {
 };
 
 /**
- * Delete a pending task by ID.
+ * Payload for deleting a pending task by ID.
  */
 export type DBDeletePendingTaskType = {
   /** ID of the pending task. */
@@ -233,7 +230,7 @@ export type DBDeletePendingTaskType = {
 };
 
 /**
- * Update a pending task by ID.
+ * Payload for updating a pending task by ID.
  */
 export type DBUpdatePendingTaskType = {
   /** ID of the pending task. */
@@ -305,13 +302,13 @@ export type DBDeleteMessagesForChannelType = {
   /** Channel ID. */
   cid: string;
   /** Timestamp before which messages are deleted. */
-  truncated_at?: string;
+  truncated_at?: Date;
   /** Whether to immediately execute the operation. */
   execute?: boolean;
 };
 
 /**
- * Check if a channel exists by ID.
+ * Payload for checking whether a channel exists by ID.
  */
 export type DBChannelExistsType = {
   /** Channel ID. */
@@ -373,15 +370,15 @@ export interface OfflineDBApi {
   getDraft: (options: DBGetDraftType) => Promise<DraftResponse | null>;
   getChannels: (
     options: DBGetChannelsType,
-  ) => Promise<Omit<ChannelAPIResponse, 'duration'>[] | null>;
+  ) => Promise<Omit<ChannelStateResponseFields, 'duration'>[] | null>;
   getChannelsForQuery: (
     options: DBGetChannelsForQueryType,
-  ) => Promise<Omit<ChannelAPIResponse, 'duration'>[] | null>;
+  ) => Promise<Omit<ChannelStateResponseFields, 'duration'>[] | null>;
   getAllChannelCids: () => Promise<string[]>;
   getLastSyncedAt: (options: DBGetLastSyncedAtType) => Promise<string | undefined>;
   getAppSettings: (
     options: DBGetAppSettingsType,
-  ) => Promise<AppSettingsAPIResponse | null>;
+  ) => Promise<GetApplicationResponse | null>;
   getReactions: (options: DBGetReactionsType) => Promise<ReactionResponse[] | null>;
   executeSqlBatch: (queries: ExecuteBatchDBQueriesType) => Promise<unknown>;
   addPendingTask: (task: PendingTask) => Promise<() => Promise<void>>;

package/src/offline-support/util.ts

@@ -1,4 +1,4 @@
-import type { Attachment, LocalMessage, MessageResponse } from '../types';
+import type { Attachment } from '../types';
 
 export const isLocalUrl = (value: string | undefined) =>
   !!value && !value.startsWith('http');
@@ -11,9 +11,10 @@ export const isAttachmentReplayable = (attachment: Attachment) => {
   return !isLocalUrl(attachment.asset_url) && !isLocalUrl(attachment.image_url);
 };
 
-export const isMessageUpdateReplayable = (
-  message: LocalMessage | Partial<MessageResponse>,
-) => !message.attachments?.some((attachment) => !isAttachmentReplayable(attachment));
+export const isMessageUpdateReplayable = (minimalMessage: {
+  attachments?: Attachment[];
+}) =>
+  !minimalMessage.attachments?.some((attachment) => !isAttachmentReplayable(attachment));
 
 export const getPendingTaskChannelData = (cid?: string) => {
   if (!cid) {

package/src/pagination/FilterBuilder.ts

@@ -31,7 +31,10 @@ export type FilterBuilderGenerators<
   };
 };
 
-export type FilterBuilderOptions<TFilters, TContext extends Record<string, unknown>> = {
+export type FilterBuilderOptions<
+  TFilters,
+  TContext extends Record<string, unknown> = Record<string, unknown>,
+> = {
   initialFilterConfig?: FilterBuilderGenerators<TFilters, TContext>;
   initialContext?: TContext;
 };

package/src/pagination/ItemIndex.ts

@@ -0,0 +1,112 @@
+export type ItemIndexOptions<T> = {
+  getId: (item: T) => string;
+};
+
+/**
+ * The ItemIndex is a canonical, ID-addressable storage layer for domain items.
+ *
+ * It provides a single source of truth for all items managed by one or more
+ * paginators, views, or interval caches. Instead of duplicating objects inside
+ * multiple paginated ranges, every item is stored exactly once in the ItemIndex
+ * and is referenced by ID from interval windows, caches, or UI layers.
+ *
+ * ## Purpose
+ *
+ * Pagination flows (especially those supporting random-access page jumps
+ * or “load-around-anchor” requests) require representing discontinuous windows
+ * of items. Attempting to store full item objects in every interval causes
+ * duplication, inconsistent updates, increased memory usage, and difficult
+ * merging logic.
+ *
+ * The ItemIndex solves this by:
+ *
+ * - Storing each item exactly once.
+ * - Making all intervals store only `itemIds: string[]` in sorted order.
+ * - Making paginators read visible items through `itemIndex.get(id)`.
+ * - Ensuring that any mutation of an item is immediately visible everywhere.
+ *
+ * ## Benefits
+ *
+ * - **Consistency:** Updates propagate automatically because intervals reference
+ *   items by ID. No need to synchronize multiple arrays of objects.
+ * - **Efficiency:** Items are only stored once; intervals are lightweight lists
+ *   of IDs.
+ * - **Scalability:** Supports multiple disjoint intervals (e.g. random jumps),
+ *   merging of ranges, and multiple independent paginators sharing the same
+ *   item set.
+ * - **Clean separation of concerns:** The paginator manages window boundaries;
+ *   the ItemIndex manages object identity and update semantics.
+ *
+ * ## Typical Usage
+ *
+ * 1. A paginator fetches a page of items from the server.
+ * 2. It calls `itemIndex.setMany(fetchedItems)` to update the canonical store.
+ * 3. It constructs or updates an interval using the IDs only:
+ *      `{ itemIds: fetchedItems.map(item => itemIndex.getId(item)) }`
+ * 4. The UI renders the active interval’s items using:
+ *      `interval.itemIds.map(id => itemIndex.get(id))`
+ *
+ * ## Update Semantics
+ *
+ * Updates should always be performed through `setOne()` or `setMany()`.
+ * This ensures that:
+ *
+ * - The item object is replaced (immutable semantics).
+ * - All consumers reading via ID immediately observe the new value.
+ *
+ * The ItemIndex does not automatically re-sort intervals; interval or paginator
+ * logic may reorder their `itemIds` arrays when necessary.
+ *
+ * ## Notes
+ *
+ * - The ItemIndex does not apply filtering or sorting. Those are the paginator’s
+ *   responsibilities.
+ * - The ItemIndex intentionally exposes only minimal CRUD operations to keep it
+ *   predictable and side-effect-free.
+ * - Consumers should treat items as immutable snapshots. If mutation is needed,
+ *   always create a new item instance and pass it to `setOne()`.
+ *
+ * @template T The domain item type managed by the index.
+ */
+export class ItemIndex<T> {
+  private byId = new Map<string, T>();
+  private readonly getId: (item: T) => string;
+
+  constructor(options: ItemIndexOptions<T>) {
+    this.getId = options.getId;
+  }
+
+  setMany(items: T[]) {
+    for (const item of items) {
+      this.byId.set(this.getId(item), item);
+    }
+  }
+
+  setOne(item: T) {
+    this.byId.set(this.getId(item), item);
+  }
+
+  get(id: string): T | undefined {
+    return this.byId.get(id);
+  }
+
+  has(id: string): boolean {
+    return this.byId.has(id);
+  }
+
+  remove(id: string) {
+    this.byId.delete(id);
+  }
+
+  clear() {
+    this.byId.clear();
+  }
+
+  entries() {
+    return [...this.byId.entries()];
+  }
+
+  values() {
+    return [...this.byId.values()];
+  }
+}

package/src/pagination/cursorDerivation/createdAtAroundPaginationFlags.ts

@@ -0,0 +1,73 @@
+import { binarySearch } from '../sortCompiler';
+import type { BasePaginator, CursorDeriveContext, PaginationFlags } from '../paginators';
+import { ComparisonResult } from '../types.normalization';
+
+export const deriveCreatedAtAroundPaginationFlags = <
+  T extends { id: string; created_at: Date },
+  Q extends { created_at_around?: Date | string },
+  P extends BasePaginator<T, Q>,
+>({
+  hasMoreHead,
+  hasMoreTail,
+  interval,
+  page,
+  paginator,
+  queryShape,
+  requestedPageSize,
+}: CursorDeriveContext<T, Q> & { paginator: P }): PaginationFlags => {
+  let flags: PaginationFlags = { hasMoreHead, hasMoreTail };
+  if (!queryShape?.created_at_around) return flags;
+  const createdAtAroundDate = new Date(queryShape.created_at_around);
+  const [firstPageItem, lastPageItem] = [page[0], page.slice(-1)[0]];
+
+  // expect ASC order (from oldest to newest)
+  const isAboveHeadBound =
+    paginator.sortComparator({ created_at: createdAtAroundDate } as T, lastPageItem) ===
+    ComparisonResult.A_PRECEDES_B;
+  const isBelowTailBound =
+    paginator.sortComparator(firstPageItem, { created_at: createdAtAroundDate } as T) ===
+    ComparisonResult.A_PRECEDES_B;
+
+  const requestedPageSizeNotMet =
+    requestedPageSize > interval.itemIds.length && requestedPageSize > page.length;
+  const noMoreMessages =
+    (requestedPageSize > interval.itemIds.length ||
+      interval.itemIds.length >= page.length) &&
+    requestedPageSize > page.length;
+
+  if (isAboveHeadBound) {
+    flags.hasMoreHead = false;
+    if (requestedPageSizeNotMet) {
+      flags.hasMoreTail = false;
+    }
+  } else if (isBelowTailBound) {
+    flags.hasMoreTail = false;
+    if (requestedPageSizeNotMet) {
+      flags.hasMoreHead = false;
+    }
+  } else if (noMoreMessages) {
+    flags = { hasMoreHead: false, hasMoreTail: false };
+  } else {
+    const [firstPageMsgIsFirstInSet, lastPageMsgIsLastInSet] = [
+      firstPageItem?.id && firstPageItem.id === interval.itemIds[0],
+      lastPageItem?.id && lastPageItem.id === interval.itemIds.slice(-1)[0],
+    ];
+
+    const midPointByCount = Math.floor(page.length / 2);
+    const { insertionIndex } = binarySearch({
+      needle: { created_at: createdAtAroundDate } as T,
+      length: page.length,
+      getItemAt: (index) => page[index],
+      compare: (a, b) => a.created_at?.getTime() - b.created_at.getTime(),
+      itemIdentityEquals: (a, b) => a.created_at?.getTime() === b.created_at?.getTime(),
+      plateauScan: false,
+    });
+
+    if (insertionIndex !== -1) {
+      if (firstPageMsgIsFirstInSet) flags.hasMoreTail = midPointByCount <= insertionIndex;
+      if (lastPageMsgIsLastInSet) flags.hasMoreHead = midPointByCount >= insertionIndex;
+    }
+  }
+
+  return flags;
+};

package/src/pagination/cursorDerivation/idAroundPaginationFlags.ts

@@ -0,0 +1,53 @@
+import type { CursorDeriveContext, PaginationFlags } from '../paginators';
+
+export const deriveIdAroundPaginationFlags = <
+  T extends { id: string },
+  Q extends { id_around?: string },
+>({
+  hasMoreHead,
+  hasMoreTail,
+  interval,
+  page,
+  queryShape,
+  requestedPageSize,
+}: CursorDeriveContext<T, Q>): PaginationFlags => {
+  let flags: PaginationFlags = { hasMoreHead, hasMoreTail };
+  if (!queryShape?.id_around) return flags;
+  const { id_around } = queryShape;
+
+  const [firstPageMsg, lastPageMsg] = [page[0], page.slice(-1)[0]];
+  const [firstPageMsgIsFirstInSet, lastPageMsgIsLastInSet] = [
+    firstPageMsg?.id === interval.itemIds[0],
+    lastPageMsg?.id === interval.itemIds.slice(-1)[0],
+  ];
+
+  const midPoint = Math.floor(page.length / 2);
+  const noMoreMessages =
+    (requestedPageSize > interval.itemIds.length ||
+      interval.itemIds.length >= page.length) &&
+    requestedPageSize > page.length;
+
+  if (noMoreMessages) {
+    flags = { hasMoreHead: false, hasMoreTail: false };
+  } else if (!page[midPoint]) {
+    return flags;
+  } else if (page[midPoint].id === id_around) {
+    flags = { hasMoreHead: true, hasMoreTail: true };
+  } else {
+    const halves = [page.slice(0, midPoint), page.slice(midPoint)];
+    if (firstPageMsgIsFirstInSet) {
+      const targetMsg = halves[0].find((message) => message.id === id_around);
+      if (targetMsg) {
+        flags.hasMoreTail = false;
+      }
+    }
+    if (lastPageMsgIsLastInSet) {
+      const targetMsg = halves[1].find((message) => message.id === id_around);
+      if (targetMsg) {
+        flags.hasMoreHead = false;
+      }
+    }
+  }
+
+  return flags;
+};

package/src/pagination/cursorDerivation/index.ts

@@ -0,0 +1 @@
+export * from './createdAtAroundPaginationFlags';

package/src/pagination/cursorDerivation/linearPaginationFlags.ts

@@ -0,0 +1,86 @@
+import type { CursorDeriveContext, PaginationFlags } from '../paginators';
+import type { MessagePaginationOptions, PaginationOptions } from '../../types';
+
+const TAILWARD_QUERY_PROPERTIES: Array<keyof PaginationOptions> = [
+  'created_at_before_or_equal',
+  'created_at_before',
+  'id_lt',
+  'id_lte',
+  'offset',
+];
+
+const HEADWARD_QUERY_PROPERTIES: Array<keyof PaginationOptions> = [
+  'created_at_after_or_equal',
+  'created_at_after',
+  'id_gt',
+  'id_gte',
+];
+export const deriveLinearPaginationFlags = <
+  T extends { id: string; created_at: Date },
+  Q extends PaginationOptions,
+>({
+  direction,
+  hasMoreHead,
+  hasMoreTail,
+  interval,
+  page,
+  queryShape,
+  requestedPageSize,
+}: CursorDeriveContext<T, Q>): PaginationFlags => {
+  const flags: PaginationFlags = { hasMoreHead, hasMoreTail };
+  const [firstPageMsg, lastPageMsg] = [page[0], page.slice(-1)[0]];
+  const [firstPageMsgIsFirstInSet, lastPageMsgIsLastInSet] = [
+    firstPageMsg?.id && firstPageMsg.id === interval.itemIds[0],
+    lastPageMsg?.id && lastPageMsg.id === interval.itemIds.slice(-1)[0],
+  ];
+
+  const containsCursorPaginationProperties =
+    !!queryShape &&
+    HEADWARD_QUERY_PROPERTIES.concat(TAILWARD_QUERY_PROPERTIES).some(
+      (p) => typeof queryShape[p] !== 'undefined',
+    );
+
+  const queriedMessagesTowardsHead =
+    direction === 'headward' ||
+    (!!queryShape &&
+      HEADWARD_QUERY_PROPERTIES.some((p) => typeof queryShape[p] !== 'undefined'));
+
+  const queriedMessagesTowardsTail =
+    direction === 'tailward' ||
+    typeof queryShape === 'undefined' ||
+    TAILWARD_QUERY_PROPERTIES.some((p) => typeof queryShape[p] !== 'undefined');
+
+  const containsNonLinearPaginationProperties =
+    !!(queryShape as MessagePaginationOptions)?.id_around ||
+    !!(queryShape as MessagePaginationOptions)?.created_at_around;
+
+  const containsUnrecognizedOptionsOnly =
+    !queriedMessagesTowardsHead &&
+    !queriedMessagesTowardsTail &&
+    !containsNonLinearPaginationProperties;
+
+  const isFirstPage = !containsCursorPaginationProperties;
+
+  const hasMore = page.length >= requestedPageSize;
+
+  if (
+    typeof queriedMessagesTowardsTail !== 'undefined' ||
+    containsUnrecognizedOptionsOnly
+  ) {
+    // Without the isFirstPage branch, a partial first page (e.g. an
+    // offline prehydrate returning fewer than `requestedPageSize`) latches `hasMoreTail`
+    // to `false` and a subsequent full network first page can never restore it.
+    hasMoreTail = isFirstPage ? hasMore : !hasMoreTail ? false : hasMore;
+  }
+  if (typeof queriedMessagesTowardsHead !== 'undefined') {
+    hasMoreHead = !hasMoreHead || isFirstPage ? false : hasMore;
+  }
+  const pageIsEmpty = page.length === 0;
+
+  if ((firstPageMsgIsFirstInSet || pageIsEmpty) && typeof hasMoreTail !== 'undefined')
+    flags.hasMoreTail = hasMoreTail;
+  if ((lastPageMsgIsLastInSet || pageIsEmpty) && typeof hasMoreHead !== 'undefined')
+    flags.hasMoreHead = hasMoreHead;
+
+  return flags;
+};