stream-chat 9.50.3 → 10.0.0-rc.2

package/src/pagination/paginators/ReminderPaginator.ts

@@ -0,0 +1,107 @@
+import { BasePaginator, ZERO_PAGE_CURSOR } from './BasePaginator';
+import type {
+  PaginationQueryParams,
+  PaginationQueryReturnValue,
+  PaginatorOptions,
+} from './BasePaginator';
+import type {
+  QueryRemindersOptions,
+  ReminderFilters,
+  ReminderResponseData,
+  ReminderSort,
+} from '../../types';
+import type { StreamChat } from '../../client';
+import { StoreBackedItemIndex } from '../../entityStore/StoreBackedItemIndex';
+import { makeComparator } from '../sortCompiler';
+import { resolveDotPathValue } from '../utility.normalization';
+
+// Reminders are keyed by the message they belong to; used for interval dedup and index addressing.
+const getReminderId = (reminder: ReminderResponseData) => reminder.message_id;
+
+// Fallback order for interval placement when no explicit sort is set. Order is not a pinned contract
+// (ReminderManager stores reminders in a message_id-keyed Map), but interval storage needs a total
+// order, so default to a deterministic one.
+const DEFAULT_SORT: ReminderSort = [{ direction: 1, field: 'created_at' }];
+
+export class ReminderPaginator extends BasePaginator<
+  ReminderResponseData,
+  QueryRemindersOptions
+> {
+  private client: StreamChat;
+  protected _filters: ReminderFilters | undefined;
+  protected _sort: ReminderSort | undefined;
+
+  get filters(): ReminderFilters | undefined {
+    return this._filters;
+  }
+
+  get sort(): ReminderSort | undefined {
+    return this._sort;
+  }
+
+  set filters(filters: ReminderFilters | undefined) {
+    this._filters = filters;
+    this.resetState();
+  }
+
+  set sort(sort: ReminderSort | undefined) {
+    this._sort = sort;
+    this.sortComparator = this.buildSortComparator();
+    this.resetState();
+  }
+
+  constructor(
+    client: StreamChat,
+    options?: PaginatorOptions<ReminderResponseData, QueryRemindersOptions>,
+  ) {
+    super({
+      initialCursor: ZERO_PAGE_CURSOR,
+      itemIndex: new StoreBackedItemIndex<ReminderResponseData>({
+        getEntityId: getReminderId,
+      }),
+      ...options,
+    });
+    this.client = client;
+    this.sortComparator = this.buildSortComparator();
+  }
+
+  getItemId(item: ReminderResponseData): string {
+    return getReminderId(item);
+  }
+
+  // Interval storage needs a total order. Derive it from the requested sort (rebuilt when `sort`
+  // changes, which also resets the accumulated pages), with a message_id tiebreaker.
+  private buildSortComparator() {
+    return makeComparator<ReminderResponseData>({
+      sort: this._sort ?? DEFAULT_SORT,
+      resolvePathValue: resolveDotPathValue,
+      tiebreaker: (l, r) =>
+        l.message_id < r.message_id ? -1 : l.message_id > r.message_id ? 1 : 0,
+    });
+  }
+
+  protected getNextQueryShape({
+    direction,
+  }: Required<
+    Pick<PaginationQueryParams<QueryRemindersOptions>, 'direction'>
+  >): QueryRemindersOptions {
+    const cursor = this.cursor?.[direction];
+    return {
+      filter: this.filters,
+      sort: this.sort,
+      limit: this.pageSize,
+      [direction]: cursor,
+    };
+  }
+
+  query = async ({
+    queryShape,
+  }: PaginationQueryParams<QueryRemindersOptions>): Promise<
+    PaginationQueryReturnValue<ReminderResponseData>
+  > => {
+    const { reminders: items, next, prev } = await this.client.queryReminders(queryShape);
+    return { items, headward: prev, tailward: next };
+  };
+
+  filterQueryResults = (items: ReminderResponseData[]) => items;
+}

package/src/pagination/paginators/UserGroupPaginator.ts

@@ -0,0 +1,127 @@
+import { BasePaginator, ZERO_PAGE_CURSOR } from './BasePaginator';
+import type {
+  PaginationQueryParams,
+  PaginationQueryReturnValue,
+  PaginatorOptions,
+  PaginatorState,
+} from './BasePaginator';
+import type { ListUserGroupsOptions, UserGroupResponse } from '../../types';
+import type { StreamChat } from '../../client';
+import { StoreBackedItemIndex } from '../../entityStore/StoreBackedItemIndex';
+
+type UserGroupListCursor = {
+  created_at_gt: string;
+  id_gt: string;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null;
+
+const decodeCursor = <TCursor extends object>(cursor: string | null | undefined) => {
+  if (!cursor) return undefined;
+
+  try {
+    const parsed = JSON.parse(cursor);
+    return isRecord(parsed) ? (parsed as TCursor) : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+/**
+ * Paginates user-group listing through `/usergroups`.
+ *
+ * This entity only supports forward (tailward) cursor pagination via
+ * `created_at_gt` and `id_gt`. Backward (headward) pagination is not available
+ * because the API does not expose a backward cursor, so the headward cursor is
+ * initialized as exhausted (`null`).
+ */
+export class UserGroupPaginator extends BasePaginator<
+  UserGroupResponse,
+  ListUserGroupsOptions
+> {
+  private client: StreamChat;
+  protected _teamId: string | undefined;
+
+  constructor(
+    client: StreamChat,
+    options?: PaginatorOptions<UserGroupResponse, ListUserGroupsOptions>,
+  ) {
+    super({
+      initialCursor: { ...ZERO_PAGE_CURSOR, headward: null },
+      itemIndex: new StoreBackedItemIndex<UserGroupResponse>({
+        getEntityId: (group) => group.id,
+      }),
+      ...options,
+    });
+    this.client = client;
+    // Interval storage needs a total order for its placement/merge math. The listing is ordered by
+    // the forward cursor (`created_at_gt`, `id_gt`), i.e. ascending `created_at` then `id` — mirror
+    // that here so the visible order matches the server's.
+    this.sortComparator = (a, b) => {
+      if (a.created_at !== b.created_at) return a.created_at < b.created_at ? -1 : 1;
+      return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+    };
+  }
+
+  get initialState(): PaginatorState<UserGroupResponse> {
+    return {
+      ...super.initialState,
+      hasMoreHead: false,
+    };
+  }
+
+  get teamId() {
+    return this._teamId;
+  }
+
+  set teamId(teamId: string | undefined) {
+    if (teamId === this._teamId) return;
+    this._teamId = teamId;
+    this.resetState();
+  }
+
+  private buildNextCursor = (items: UserGroupResponse[]) => {
+    if (items.length < this.pageSize) return undefined;
+    const lastItem = items[items.length - 1];
+    if (!lastItem) return undefined;
+
+    return JSON.stringify({
+      created_at_gt: lastItem.created_at.toISOString(),
+      id_gt: lastItem.id,
+    } satisfies UserGroupListCursor);
+  };
+
+  // The query shape must stay stable across pages: the paginator resets its
+  // accumulated list when the query shape changes ('auto' reset policy), so the
+  // forward cursor is NOT part of the shape — it is applied per request in `query`.
+  protected getNextQueryShape(): ListUserGroupsOptions {
+    return {
+      limit: this.pageSize,
+      ...(this.teamId ? { team_id: this.teamId } : {}),
+    };
+  }
+
+  query = async ({
+    direction,
+    queryShape,
+  }: PaginationQueryParams<ListUserGroupsOptions>): Promise<
+    PaginationQueryReturnValue<UserGroupResponse>
+  > => {
+    if (direction === 'headward') {
+      return { items: [] };
+    }
+
+    const cursor = decodeCursor<UserGroupListCursor>(this.cursor?.tailward);
+    const options: ListUserGroupsOptions = {
+      ...(queryShape ?? this.getNextQueryShape()),
+      ...(cursor?.id_gt ? { id_gt: cursor.id_gt } : {}),
+      ...(cursor?.created_at_gt ? { created_at_gt: cursor.created_at_gt } : {}),
+    };
+
+    const { user_groups: items } = await this.client.listUserGroups(options);
+    return { items, tailward: this.buildNextCursor(items) };
+  };
+
+  filterQueryResults = (items: UserGroupResponse[]) => items;
+}

package/src/pagination/paginators/index.ts

@@ -0,0 +1,7 @@
+export * from './BasePaginator';
+export * from './ChannelPaginator';
+export { MessageIntervalPaginator } from './MessageIntervalPaginator';
+export * from './MessagePaginator';
+export * from './PinnedMessagePaginator';
+export * from './ReminderPaginator';
+export * from './UserGroupPaginator';

package/src/pagination/paginators/stateThrottling.ts

@@ -0,0 +1,31 @@
+/**
+ * Global switch for the message-list `state` publish throttle (see `BasePaginator.scheduleWindowPublish`).
+ *
+ * Auto-disabled under test runners (Vitest / Jest) so the existing unit suites keep their synchronous,
+ * un-throttled behavior with zero per-test changes: with throttling off, every live mutation publishes
+ * to `state` immediately, exactly as before this feature. A dedicated throttle test flips it on
+ * (around fake timers) via {@link setStateThrottlingEnabled} and restores it afterwards.
+ *
+ * Production (an app bundle) defaults ON.
+ */
+const isTestRunner = (): boolean => {
+  try {
+    return (
+      typeof process !== 'undefined' &&
+      !!process.env &&
+      (!!process.env.VITEST ||
+        !!process.env.JEST_WORKER_ID ||
+        process.env.NODE_ENV === 'test')
+    );
+  } catch {
+    return false;
+  }
+};
+
+let enabled = !isTestRunner();
+
+export const isStateThrottlingEnabled = (): boolean => enabled;
+
+export const setStateThrottlingEnabled = (value: boolean): void => {
+  enabled = value;
+};

package/src/pagination/sortCompiler.ts

@@ -0,0 +1,193 @@
+import {
+  compare,
+  resolveDotPathValue as defaultResolvePathValue,
+  normalizeComparedValues,
+} from './utility.normalization';
+import type { SortParamRequest } from '../types';
+import type { Comparator, PathResolver } from './types.normalization';
+
+export type ItemLocation = {
+  currentIndex: number;
+  insertionIndex: number;
+};
+
+/**
+ * Generic binary-search + plateau lookup over an abstract sorted array.
+ *
+ * The array is represented by:
+ *  - its length
+ *  - a getter `getItemAt(index)` that returns the item (or undefined)
+ *
+ * It returns:
+ *  - current: actual index of the item in the array
+ *  - expected: lower-bound position where the item belongs according to compare function
+ */
+export function binarySearch<T>({
+  needle,
+  length,
+  getItemAt,
+  itemIdentityEquals,
+  compare,
+  plateauScan,
+}: {
+  /** Target item in the searched array */
+  needle: T;
+  length: number;
+  /** Retrieves the item from an array. The array could be just an array of reference by id to an index.
+   * Therefore, we do not access the array directly but allow to determine, how the item is constructed.
+   */
+  getItemAt: (index: number) => T | undefined;
+  /** Used to determine identity, not equality based on sort / comparator rules */
+  itemIdentityEquals: (item1: T, item2: T) => boolean;
+  /** Used to determine equality from the sort order point of view. */
+  compare: Comparator<T>;
+  plateauScan?: boolean;
+}): ItemLocation {
+  // empty array
+  if (length === 0) return { currentIndex: -1, insertionIndex: 0 };
+
+  // --- 1) Binary search to find lower bound (insertionIndex) ---
+  let lo = 0;
+  let hi = length;
+
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1; // fast floor((low+high)/2)
+    const midItem = getItemAt(mid);
+    if (!midItem) {
+      // Corruption: we have an ID but no backing item.
+      // Bail out with "not found".
+      return { currentIndex: -1, insertionIndex: -1 };
+    }
+
+    if (itemIdentityEquals(midItem, needle) && mid > 0) {
+      // The probe landed on the needle's own slot, where `compare` is 0 by definition and says
+      // nothing about where it belongs. That matters when relocating an item whose sort value just
+      // changed: the array is sorted EXCEPT at this slot, because items held by reference (a
+      // `Channel` mutated in place before the paginator is told) already carry the new value.
+      // Walking right on that 0 reports "insert just after where you are" — read downstream as
+      // "already in place" — so the item never moves. The left neighbour is the reliable signal;
+      // otherwise fall through, keeping the established end-of-plateau result.
+      const leftItem = getItemAt(mid - 1);
+      if (leftItem && compare(leftItem, needle) > 0) {
+        hi = mid;
+        continue;
+      }
+    }
+
+    if (compare(midItem, needle) <= 0) {
+      // midItem < needle ⇒ go right
+      lo = mid + 1;
+    } else {
+      // midItem ≥ needle ⇒ go left
+      hi = mid;
+    }
+  }
+
+  const insertionIndex = lo;
+
+  // item is located where it is expected to be according to the sort
+  const itemAtExpectedIndex = getItemAt(insertionIndex);
+  if (itemAtExpectedIndex && itemIdentityEquals(itemAtExpectedIndex, needle)) {
+    return { currentIndex: insertionIndex, insertionIndex };
+  }
+
+  if (!plateauScan) {
+    return { currentIndex: -1, insertionIndex };
+  }
+
+  // --- 2) Plateau scan around insertionIndex ---
+
+  const checkSide = (atIndex: number) => {
+    const result = { exhausted: false, found: false };
+    const item = getItemAt(atIndex);
+    if (!item) result.exhausted = true;
+    else if (itemIdentityEquals(item, needle)) result.found = true;
+    return result;
+  };
+
+  // Alternating left/right scan
+  let iLeft = insertionIndex - 1;
+  let iRight = insertionIndex + 1; // we've already checked insertionIndex
+  let leftDone = iLeft < 0;
+  let rightDone = iRight >= length;
+
+  while (!leftDone || !rightDone) {
+    if (!leftDone) {
+      const result = checkSide(iLeft);
+      if (result.found) return { currentIndex: iLeft, insertionIndex };
+      leftDone = result.exhausted || --iLeft < 0;
+    }
+
+    if (!rightDone) {
+      const result = checkSide(iRight);
+      if (result.found) return { currentIndex: iRight, insertionIndex };
+      rightDone = result.exhausted || ++iRight >= length;
+    }
+  }
+
+  // Not found in plateau; insertion index is still the correct lower bound.
+  return { currentIndex: -1, insertionIndex };
+}
+
+/**
+ * Negative number (< 0) → a comes before b
+ *
+ * Zero (0) → leave a and b unchanged relative to each other
+ * (but they can still move relative to others — sort in JS is not guaranteed stable in older engines, though modern V8/Node/Chrome/Firefox make it stable)
+ *
+ * Positive number (> 0) → a comes after b
+ *
+ * @param params - Comparator configuration.
+ * @param params.sort - The sort specification defining fields and directions.
+ * @param params.resolvePathValue - Resolver used to read a field value from an item.
+ * @param params.tiebreaker - Comparator applied when all sort terms are equal.
+ */
+export function makeComparator<T>({
+  sort,
+  resolvePathValue = defaultResolvePathValue,
+  tiebreaker = (a, b) => compare((a as any).cid, (b as any).cid),
+}: {
+  sort: SortParamRequest[];
+  resolvePathValue?: PathResolver<T>;
+  tiebreaker?: Comparator<T>;
+}): Comparator<T> {
+  return (a: T, b: T) => {
+    for (const { field: path, direction } of sort) {
+      const leftValue = resolvePathValue(a, path as string);
+      const rightValue = resolvePathValue(b, path as string);
+      const normalized = normalizeComparedValues(leftValue, rightValue);
+      let comparison: number;
+      switch (normalized.kind) {
+        case 'date':
+        case 'number':
+        case 'string':
+        case 'boolean':
+          comparison = compare(normalized.a, normalized.b);
+          break;
+        default: {
+          // Null/undefined always sort to the tail, INDEPENDENT of `direction`. Return here so the
+          // result bypasses the direction flip below — otherwise a descending sort (e.g.
+          // `{ last_message_at: -1 }`) negates "null last" into "null first" and floats value-less
+          // items (e.g. channels with no last message) to the head of the list.
+          if (leftValue == null && rightValue == null) {
+            comparison = 0; // tie on this term; fall through to the next term / tiebreaker
+            break;
+          }
+          if (leftValue == null) return 1; // a (null) sorts after b
+          if (rightValue == null) return -1; // b (null) sorts after a
+          // Both non-null but not normalizable: deterministic string compare (respects direction).
+          const stringLeftValue = String(leftValue),
+            stringRightValue = String(rightValue);
+          comparison =
+            stringLeftValue === stringRightValue
+              ? 0
+              : stringLeftValue < stringRightValue
+                ? -1
+                : 1;
+        }
+      }
+      if (comparison !== 0) return direction === 1 ? comparison : -comparison;
+    }
+    return tiebreaker ? tiebreaker(a, b) : 0;
+  };
+}

package/src/pagination/types.normalization.ts

@@ -0,0 +1,14 @@
+export type PathResolver<DataSource> = (item: DataSource, field: string) => unknown;
+
+export enum ComparisonResult {
+  A_PRECEDES_B = -1,
+  A_IS_EQUAL_TO_B = 0,
+  A_COMES_AFTER_B = 1,
+}
+
+export type Comparator<T> = (left: T, right: T) => ComparisonResult;
+
+export type FieldToDataResolver<DataSource> = {
+  matchesField: (field: string) => boolean;
+  resolve: PathResolver<DataSource>;
+};

package/src/pagination/utility.normalization.ts

@@ -0,0 +1,106 @@
+export function asArray(v: any): any[] {
+  return Array.isArray(v) ? v : [v];
+}
+
+export function isISODateString(x: any): x is string {
+  return typeof x === 'string' && x.includes('T') && !Number.isNaN(Date.parse(x));
+}
+
+export function toEpochMillis(x: any): number | null {
+  if (x instanceof Date) return x.getTime();
+  if (typeof x === 'number' && Number.isFinite(x)) return x; // treat as epoch ms
+  if (isISODateString(x)) return Date.parse(x);
+  return null;
+}
+
+export function toNumberLike(x: any): number | null {
+  if (typeof x === 'number' && Number.isFinite(x)) return x;
+  if (typeof x === 'string' && x.trim() !== '') {
+    const n = Number(x);
+    if (Number.isFinite(n)) return n;
+  }
+  return null;
+}
+
+export function normalizeComparedValues(a: any, b: any) {
+  const Ad = toEpochMillis(a),
+    Bd = toEpochMillis(b);
+  if (Ad !== null && Bd !== null) return { kind: 'date', a: Ad, b: Bd };
+
+  const An = toNumberLike(a),
+    Bn = toNumberLike(b);
+  if (An !== null && Bn !== null) return { kind: 'number', a: An, b: Bn };
+
+  if (typeof a === 'string' && typeof b === 'string') return { kind: 'string', a, b };
+  if (typeof a === 'boolean' && typeof b === 'boolean') return { kind: 'boolean', a, b };
+
+  return { kind: 'incomparable', a, b };
+}
+
+export function normKey(x: unknown): string {
+  // Use your normalizeComparedValues to coerce pairs; here we need a unary form.
+  // We can piggyback by normalizing x against itself:
+  const n = normalizeComparedValues(x, x);
+  switch (n.kind) {
+    case 'date':
+    case 'number':
+    case 'string':
+    case 'boolean':
+      return `${n.kind}:${String(n.a)}`;
+    default:
+      // fallback: use JSON-like string with type tag for determinism
+      return `other:${String(x)}`;
+  }
+}
+
+export function compare(a: any, b: any): number {
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+}
+
+export function arraysEqualAsSets(aList: unknown[], bList: unknown[]): boolean {
+  // de-duplicate by normalized key
+  const aKeys = new Set(aList.map(normKey));
+  const bKeys = new Set(bList.map(normKey));
+  if (aKeys.size !== bKeys.size) return false;
+  for (const k of aKeys) if (!bKeys.has(k)) return false;
+  return true;
+}
+
+export function normalizeString(s: string): string {
+  return s.normalize('NFKC').toLowerCase().trim();
+}
+
+export function normalizeStringAccentInsensitive(s: string): string {
+  return s
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLowerCase()
+    .trim();
+}
+
+export function tokenize(s: string): string[] {
+  // split on whitespace; keep simple & deterministic
+  return normalizeString(s).split(/\s+/).filter(Boolean);
+}
+
+// dot-path accessor
+export function resolveDotPathValue(obj: any, path: string): unknown[] {
+  return path
+    .split('.')
+    .reduce((reduced, key) => (!reduced ? undefined : reduced[key]), obj);
+}
+
+export function isIterableButNotString(v: unknown): v is Iterable<unknown> {
+  return (
+    v != null &&
+    typeof v !== 'string' &&
+    typeof (v as any)[Symbol.iterator] === 'function'
+  );
+}
+
+export function toIterableArray(v: unknown): unknown[] {
+  if (Array.isArray(v)) return v;
+  if (isIterableButNotString(v)) return Array.from(v as Iterable<unknown>);
+  return [v]; // scalar as a single-element list
+}

package/src/pagination/utility.queryChannel.ts

@@ -0,0 +1,84 @@
+import type { ChannelGetOrCreateRequest, ChannelStateResponse } from '../types';
+import type { StreamChat } from '../client';
+import type { Channel } from '../channel';
+import { generateChannelTempCid } from '../utils';
+
+/**
+ * prevent from duplicate invocation of channel.watch()
+ * when events 'notification.message_new' and 'notification.added_to_channel' arrive at the same time
+ */
+const WATCH_QUERY_IN_PROGRESS_FOR_CHANNEL: Record<
+  string,
+  Promise<ChannelStateResponse> | undefined
+> = {};
+
+type GetChannelParams = {
+  client: StreamChat;
+  channel?: Channel;
+  id?: string;
+  members?: string[];
+  options?: ChannelGetOrCreateRequest;
+  type?: string;
+};
+/**
+ * Watches a channel, coalescing concurrent invocations for the same CID.
+ * If a watch is already in flight, this call waits for it to settle instead of
+ * issuing another network request.
+ *
+ * @param params - The channel query parameters.
+ * @param params.client - The chat client instance.
+ * @param params.members - Member user ids used to construct or identify the channel.
+ * @param params.options - Options forwarded to the underlying channel watch request.
+ * @param params.type - The channel type.
+ * @param params.id - The channel id.
+ * @param params.channel - An existing channel to watch (skips construction from type/id/members).
+ */
+export const getChannel = async ({
+  channel,
+  client,
+  id,
+  members,
+  options,
+  type,
+}: GetChannelParams) => {
+  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
+
+  const theChannel =
+    channel ||
+    // `members` are member IDs; the OpenAPI `ChannelData.members` expects member objects.
+    client.channel(type as string, id, {
+      members: members?.map((user_id) => ({ user_id })),
+    });
+
+  // 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 = theChannel?.id
+    ? theChannel.cid
+    : members && members.length
+      ? generateChannelTempCid(theChannel.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] = theChannel.watch(options);
+      await WATCH_QUERY_IN_PROGRESS_FOR_CHANNEL[originalCid];
+    } finally {
+      delete WATCH_QUERY_IN_PROGRESS_FOR_CHANNEL[originalCid];
+    }
+  }
+
+  return theChannel;
+};