stream-chat 9.4.0 → 9.5.1

package/src/pagination/BasePaginator.ts

@@ -0,0 +1,184 @@
+import { StateStore } from '../store';
+import { debounce, type DebouncedFunc } from '../utils';
+
+type PaginationDirection = 'next' | 'prev';
+type Cursor = { next: string | null; prev: string | null };
+export type PaginationQueryParams = { direction: PaginationDirection };
+export type PaginationQueryReturnValue<T> = { items: T[] } & {
+  next?: string;
+  prev?: string;
+};
+export type PaginatorDebounceOptions = {
+  debounceMs: number;
+};
+type DebouncedExecQueryFunction = DebouncedFunc<
+  (params: { direction: PaginationDirection }) => Promise<void>
+>;
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type PaginatorState<T = any> = {
+  hasNext: boolean;
+  hasPrev: boolean;
+  isLoading: boolean;
+  items: T[] | undefined;
+  lastQueryError?: Error;
+  cursor?: Cursor;
+  offset?: number;
+};
+
+export type PaginatorOptions = {
+  /** The number of milliseconds to debounce the search query. The default interval is 300ms. */
+  debounceMs?: number;
+  pageSize?: number;
+};
+export const DEFAULT_PAGINATION_OPTIONS: Required<PaginatorOptions> = {
+  debounceMs: 300,
+  pageSize: 10,
+} as const;
+
+export abstract class BasePaginator<T> {
+  state: StateStore<PaginatorState<T>>;
+  protected pageSize: number;
+  protected _executeQueryDebounced!: DebouncedExecQueryFunction;
+  protected _isCursorPagination = false;
+
+  protected constructor(options?: PaginatorOptions) {
+    const { debounceMs, pageSize } = { ...DEFAULT_PAGINATION_OPTIONS, ...options };
+    this.pageSize = pageSize;
+    this.state = new StateStore<PaginatorState<T>>(this.initialState);
+    this.setDebounceOptions({ debounceMs });
+  }
+
+  get lastQueryError() {
+    return this.state.getLatestValue().lastQueryError;
+  }
+
+  get hasNext() {
+    return this.state.getLatestValue().hasNext;
+  }
+
+  get hasPrev() {
+    return this.state.getLatestValue().hasPrev;
+  }
+
+  get hasResults() {
+    return Array.isArray(this.state.getLatestValue().items);
+  }
+
+  get isLoading() {
+    return this.state.getLatestValue().isLoading;
+  }
+
+  get initialState(): PaginatorState {
+    return {
+      hasNext: true,
+      hasPrev: true, //todo: check if optimistic value does not cause problems in UI
+      isLoading: false,
+      items: undefined,
+      lastQueryError: undefined,
+      cursor: undefined,
+      offset: 0,
+    };
+  }
+
+  get items() {
+    return this.state.getLatestValue().items;
+  }
+
+  get cursor() {
+    return this.state.getLatestValue().cursor;
+  }
+
+  get offset() {
+    return this.state.getLatestValue().offset;
+  }
+
+  abstract query(params: PaginationQueryParams): Promise<PaginationQueryReturnValue<T>>;
+
+  abstract filterQueryResults(items: T[]): T[] | Promise<T[]>;
+
+  setDebounceOptions = ({ debounceMs }: PaginatorDebounceOptions) => {
+    this._executeQueryDebounced = debounce(this.executeQuery.bind(this), debounceMs);
+  };
+
+  canExecuteQuery = (direction: PaginationDirection) =>
+    (!this.isLoading && direction === 'next' && this.hasNext) ||
+    (direction === 'prev' && this.hasPrev);
+
+  protected getStateBeforeFirstQuery(): PaginatorState<T> {
+    return {
+      ...this.initialState,
+      isLoading: true,
+    };
+  }
+
+  protected getStateAfterQuery(
+    stateUpdate: Partial<PaginatorState<T>>,
+    isFirstPage: boolean,
+  ): PaginatorState<T> {
+    const current = this.state.getLatestValue();
+    return {
+      ...current,
+      lastQueryError: undefined, // reset lastQueryError that can be overridden by the stateUpdate
+      ...stateUpdate,
+      isLoading: false,
+      items: isFirstPage
+        ? stateUpdate.items
+        : [...(this.items ?? []), ...(stateUpdate.items || [])],
+    };
+  }
+
+  async executeQuery({ direction }: { direction: PaginationDirection }) {
+    if (!this.canExecuteQuery(direction)) return;
+    const isFirstPage = typeof this.items === 'undefined';
+    if (isFirstPage) {
+      this.state.next(this.getStateBeforeFirstQuery());
+    } else {
+      this.state.partialNext({ isLoading: true });
+    }
+
+    const stateUpdate: Partial<PaginatorState<T>> = {};
+    try {
+      const results = await this.query({ direction });
+      if (!results) return;
+      const { items, next, prev } = results;
+      if (isFirstPage && (next || prev)) {
+        this._isCursorPagination = true;
+      }
+
+      if (this._isCursorPagination) {
+        stateUpdate.cursor = { next: next || null, prev: prev || null };
+        stateUpdate.hasNext = !!next;
+        stateUpdate.hasPrev = !!prev;
+      } else {
+        stateUpdate.offset = (this.offset ?? 0) + items.length;
+        stateUpdate.hasNext = items.length === this.pageSize;
+      }
+
+      stateUpdate.items = await this.filterQueryResults(items);
+    } catch (e) {
+      stateUpdate.lastQueryError = e as Error;
+    } finally {
+      this.state.next(this.getStateAfterQuery(stateUpdate, isFirstPage));
+    }
+  }
+
+  cancelScheduledQuery() {
+    this._executeQueryDebounced.cancel();
+  }
+
+  resetState() {
+    this.state.next(this.initialState);
+  }
+
+  next = () => this.executeQuery({ direction: 'next' });
+
+  prev = () => this.executeQuery({ direction: 'prev' });
+
+  nextDebounced = () => {
+    this._executeQueryDebounced({ direction: 'next' });
+  };
+  prevDebounced = () => {
+    this._executeQueryDebounced({ direction: 'prev' });
+  };
+}

package/src/pagination/ReminderPaginator.ts

@@ -0,0 +1,38 @@
+import { BasePaginator } from './BasePaginator';
+import type {
+  PaginationQueryParams,
+  PaginationQueryReturnValue,
+  PaginatorOptions,
+} from './BasePaginator';
+import type { ReminderFilters, ReminderResponse, ReminderSort } from '../types';
+import type { StreamChat } from '../client';
+
+export class ReminderPaginator extends BasePaginator<ReminderResponse> {
+  private client: StreamChat;
+  filters: ReminderFilters | undefined;
+  sort: ReminderSort | undefined;
+
+  constructor(client: StreamChat, options?: PaginatorOptions) {
+    super(options);
+    this.client = client;
+  }
+
+  query = async ({
+    direction,
+  }: PaginationQueryParams): Promise<PaginationQueryReturnValue<ReminderResponse>> => {
+    const cursor = this.cursor?.[direction];
+    const {
+      reminders: items,
+      next,
+      prev,
+    } = await this.client.queryReminders({
+      filter: this.filters,
+      sort: this.sort,
+      limit: this.pageSize,
+      [direction]: cursor,
+    });
+    return { items, next, prev };
+  };
+
+  filterQueryResults = (items: ReminderResponse[]) => items;
+}

package/src/pagination/index.ts

@@ -0,0 +1,2 @@
+export * from './BasePaginator';
+export * from './ReminderPaginator';

package/src/reminders/Reminder.ts

@@ -0,0 +1,89 @@
+import { ReminderTimer } from './ReminderTimer';
+import { StateStore } from '../store';
+import type { ReminderTimerConfig } from './ReminderTimer';
+import type { MessageResponse, ReminderResponseBase, UserResponse } from '../types';
+
+export const timeLeftMs = (remindAt: number) => remindAt - new Date().getTime();
+
+export type ReminderResponseBaseOrResponse = ReminderResponseBase & {
+  user?: UserResponse;
+  message?: MessageResponse;
+};
+
+export type ReminderState = {
+  channel_cid: string;
+  created_at: Date;
+  message: MessageResponse | null;
+  message_id: string;
+  remind_at: Date | null;
+  timeLeftMs: number | null;
+  updated_at: Date;
+  user: UserResponse | null;
+  user_id: string;
+};
+
+export type ReminderOptions = {
+  data: ReminderResponseBaseOrResponse;
+  config?: ReminderTimerConfig;
+};
+
+export class Reminder {
+  state: StateStore<ReminderState>;
+  timer: ReminderTimer;
+  constructor({ data, config }: ReminderOptions) {
+    this.state = new StateStore(Reminder.toStateValue(data));
+    this.timer = new ReminderTimer({ reminder: this, config });
+    this.initTimer();
+  }
+
+  static toStateValue = (data: ReminderResponseBaseOrResponse): ReminderState => ({
+    ...data,
+    created_at: new Date(data.created_at),
+    message: data.message || null,
+    remind_at: data.remind_at ? new Date(data.remind_at) : null,
+    timeLeftMs: data.remind_at ? timeLeftMs(new Date(data.remind_at).getTime()) : null,
+    updated_at: new Date(data.updated_at),
+    user: data.user || null,
+  });
+
+  get id() {
+    return this.state.getLatestValue().message_id;
+  }
+
+  get remindAt() {
+    return this.state.getLatestValue().remind_at;
+  }
+
+  get timeLeftMs() {
+    return this.state.getLatestValue().timeLeftMs;
+  }
+
+  setState = (data: ReminderResponseBaseOrResponse) => {
+    this.state.next((current) => {
+      const newState = { ...current, ...Reminder.toStateValue(data) };
+      if (newState.remind_at) {
+        newState.timeLeftMs = timeLeftMs(newState.remind_at.getTime());
+      }
+      return newState;
+    });
+
+    if (data.remind_at) {
+      this.initTimer();
+    } else if (!data.remind_at) {
+      this.clearTimer();
+    }
+  };
+
+  refreshTimeLeft = () => {
+    if (!this.remindAt) return;
+    this.state.partialNext({ timeLeftMs: timeLeftMs(this.remindAt.getTime()) });
+  };
+
+  initTimer = () => {
+    this.timer.init();
+  };
+
+  clearTimer = () => {
+    this.timer.clear();
+  };
+}

package/src/reminders/ReminderManager.ts

@@ -0,0 +1,284 @@
+import { Reminder } from './Reminder';
+import { StateStore } from '../store';
+import { ReminderPaginator } from '../pagination';
+import { WithSubscriptions } from '../utils/WithSubscriptions';
+import type { ReminderResponseBaseOrResponse } from './Reminder';
+import type { StreamChat } from '../client';
+import type {
+  CreateReminderOptions,
+  Event,
+  EventTypes,
+  LocalMessage,
+  MessageResponse,
+  ReminderResponse,
+} from '../types';
+
+const oneMinute = 60 * 1000;
+const oneHour = 60 * oneMinute;
+const oneDay = 24 * oneHour;
+
+export const DEFAULT_REMINDER_MANAGER_CONFIG: ReminderManagerConfig = {
+  scheduledOffsetsMs: [
+    2 * oneMinute,
+    30 * oneMinute,
+    oneHour,
+    2 * oneHour,
+    8 * oneHour,
+    oneDay,
+  ],
+};
+
+const isReminderExistsError = (error: Error) =>
+  error.message.match('already has reminder created for this message_id');
+
+const isReminderDoesNotExistError = (error: Error) =>
+  error.message.match('reminder does not exist');
+
+type MessageId = string;
+
+export type ReminderEvent = {
+  cid: string;
+  created_at: string;
+  message_id: MessageId;
+  reminder: ReminderResponse;
+  type: EventTypes;
+  user_id: string;
+};
+
+export type ReminderManagerState = {
+  reminders: Map<MessageId, Reminder>;
+};
+
+export type ReminderManagerConfig = {
+  scheduledOffsetsMs: number[];
+  stopTimerRefreshBoundaryMs?: number;
+};
+
+export type ReminderManagerOptions = {
+  client: StreamChat;
+  config?: ReminderManagerConfig;
+};
+
+export class ReminderManager extends WithSubscriptions {
+  private client: StreamChat;
+  configState: StateStore<ReminderManagerConfig>;
+  state: StateStore<ReminderManagerState>;
+  paginator: ReminderPaginator;
+
+  constructor({ client, config }: ReminderManagerOptions) {
+    super();
+    this.client = client;
+    this.configState = new StateStore({
+      scheduledOffsetsMs:
+        config?.scheduledOffsetsMs ?? DEFAULT_REMINDER_MANAGER_CONFIG.scheduledOffsetsMs,
+    });
+    this.state = new StateStore({ reminders: new Map<MessageId, Reminder>() });
+    this.paginator = new ReminderPaginator(client);
+  }
+
+  // Config API START //
+  updateConfig(config: Partial<ReminderManagerConfig>) {
+    this.configState.partialNext(config);
+  }
+
+  get stopTimerRefreshBoundaryMs() {
+    return this.configState.getLatestValue().stopTimerRefreshBoundaryMs;
+  }
+
+  get scheduledOffsetsMs() {
+    return this.configState.getLatestValue().scheduledOffsetsMs;
+  }
+  // Config API END //
+
+  // State API START //
+  get reminders() {
+    return this.state.getLatestValue().reminders;
+  }
+  getFromState(messageId: MessageId) {
+    return this.reminders.get(messageId);
+  }
+
+  upsertToState = ({
+    data,
+    overwrite = true,
+  }: {
+    data: ReminderResponseBaseOrResponse;
+    overwrite?: boolean;
+  }) => {
+    if (!this.client._cacheEnabled()) {
+      return;
+    }
+    const cachedReminder = this.getFromState(data.message_id);
+    if (!cachedReminder) {
+      const reminder = new Reminder({
+        data,
+        config: { stopRefreshBoundaryMs: this.stopTimerRefreshBoundaryMs },
+      });
+      this.state.partialNext({
+        reminders: new Map(this.reminders.set(data.message_id, reminder)),
+      });
+    } else if (overwrite) {
+      cachedReminder.setState(data);
+    }
+    return cachedReminder;
+  };
+
+  removeFromState = (messageId: string) => {
+    const cachedReminder = this.getFromState(messageId);
+    if (!cachedReminder) return;
+    cachedReminder.clearTimer();
+    const reminders = this.reminders;
+    reminders.delete(messageId);
+    this.state.partialNext({ reminders: new Map(reminders) });
+  };
+
+  hydrateState = (messages: MessageResponse[] | LocalMessage[]) => {
+    messages.forEach(({ reminder }) => {
+      if (reminder) {
+        this.upsertToState({ data: reminder });
+      }
+    });
+  };
+  // State API END //
+
+  // Timers API START //
+  initTimers = () => {
+    this.reminders.forEach((reminder) => reminder.initTimer());
+  };
+
+  clearTimers = () => {
+    this.reminders.forEach((reminder) => reminder.clearTimer());
+  };
+  // Timers API END //
+
+  // WS event handling START //
+  static isReminderWsEventPayload = (event: Event): event is ReminderEvent =>
+    !!event.reminder &&
+    (event.type.startsWith('reminder.') || event.type === 'notification.reminder_due');
+
+  public registerSubscriptions = () => {
+    if (this.hasSubscriptions) return;
+    this.addUnsubscribeFunction(this.subscribeReminderCreated());
+    this.addUnsubscribeFunction(this.subscribeReminderUpdated());
+    this.addUnsubscribeFunction(this.subscribeReminderDeleted());
+    this.addUnsubscribeFunction(this.subscribeNotificationReminderDue());
+    this.addUnsubscribeFunction(this.subscribeMessageDeleted());
+    this.addUnsubscribeFunction(this.subscribeMessageUndeleted());
+    this.addUnsubscribeFunction(this.subscribePaginatorStateUpdated());
+    this.addUnsubscribeFunction(this.subscribeConfigStateUpdated());
+  };
+
+  private subscribeReminderCreated = () =>
+    this.client.on('reminder.created', (event) => {
+      if (!ReminderManager.isReminderWsEventPayload(event)) return;
+      const { reminder } = event;
+      this.upsertToState({ data: reminder });
+    }).unsubscribe;
+
+  private subscribeReminderUpdated = () =>
+    this.client.on('reminder.updated', (event) => {
+      if (!ReminderManager.isReminderWsEventPayload(event)) return;
+      const { reminder } = event;
+      this.upsertToState({ data: reminder });
+    }).unsubscribe;
+
+  private subscribeReminderDeleted = () =>
+    this.client.on('reminder.deleted', (event) => {
+      if (!ReminderManager.isReminderWsEventPayload(event)) return;
+      this.removeFromState(event.message_id);
+    }).unsubscribe;
+
+  private subscribeMessageDeleted = () =>
+    this.client.on('message.deleted', (event) => {
+      if (!event.message?.id) return;
+      this.removeFromState(event.message.id);
+    }).unsubscribe;
+
+  private subscribeMessageUndeleted = () =>
+    this.client.on('message.undeleted', (event) => {
+      if (!event.message?.reminder) return;
+      // todo: not sure whether reminder specific event is emitted too and this can be ignored here
+      this.upsertToState({ data: event.message.reminder });
+    }).unsubscribe;
+
+  private subscribeNotificationReminderDue = () =>
+    this.client.on('notification.reminder_due', () => null).unsubscribe; // todo: what should be performed on this event?
+
+  private subscribePaginatorStateUpdated = () =>
+    this.paginator.state.subscribeWithSelector(
+      ({ items }) => [items],
+      ([items]) => {
+        if (!items) return;
+        for (const reminder of items) {
+          this.upsertToState({ data: reminder });
+        }
+      },
+    );
+
+  private subscribeConfigStateUpdated = () =>
+    this.configState.subscribeWithSelector(
+      ({ stopTimerRefreshBoundaryMs }) => ({ stopTimerRefreshBoundaryMs }),
+      ({ stopTimerRefreshBoundaryMs }, previousValue) => {
+        if (
+          typeof stopTimerRefreshBoundaryMs === 'number' &&
+          stopTimerRefreshBoundaryMs !== previousValue?.stopTimerRefreshBoundaryMs
+        ) {
+          this.reminders.forEach((reminder: Reminder) => {
+            if (reminder.timer) {
+              reminder.timer.stopRefreshBoundaryMs = stopTimerRefreshBoundaryMs;
+            }
+          });
+        }
+      },
+    );
+  // WS event handling END //
+
+  // API calls START //
+  upsertReminder = async (options: CreateReminderOptions) => {
+    const { messageId } = options;
+    if (this.getFromState(messageId)) {
+      try {
+        return await this.updateReminder(options);
+      } catch (error) {
+        if (isReminderDoesNotExistError(error as Error)) {
+          return await this.createReminder(options);
+        }
+        throw error;
+      }
+    } else {
+      try {
+        return await this.createReminder(options);
+      } catch (error) {
+        if (isReminderExistsError(error as Error)) {
+          return await this.updateReminder(options);
+        }
+        throw error;
+      }
+    }
+  };
+
+  createReminder = async (options: CreateReminderOptions) => {
+    const { reminder } = await this.client.createReminder(options);
+    return this.upsertToState({ data: reminder, overwrite: false });
+  };
+
+  updateReminder = async (options: CreateReminderOptions) => {
+    const { reminder } = await this.client.updateReminder(options);
+    return this.upsertToState({ data: reminder });
+  };
+
+  deleteReminder = async (messageId: MessageId) => {
+    await this.client.deleteReminder(messageId);
+    this.removeFromState(messageId);
+  };
+
+  queryNextReminders = async () => {
+    await this.paginator.next();
+  };
+
+  queryPreviousReminders = async () => {
+    await this.paginator.prev();
+  };
+
+  // API calls END //
+}

package/src/reminders/ReminderTimer.ts

@@ -0,0 +1,86 @@
+import { timeLeftMs } from './Reminder';
+import type { Reminder } from './Reminder';
+
+const oneMinute = 60 * 1000;
+const oneHour = 60 * oneMinute;
+const oneDay = 24 * oneHour;
+const oneWeek = 7 * oneDay;
+
+const GROUP_BOUNDS = {
+  minute: { lower: oneMinute, upper: oneHour },
+  hour: { lower: oneHour, upper: oneDay },
+  day: { lower: oneDay, upper: oneWeek },
+} as const;
+
+export const DEFAULT_STOP_REFRESH_BOUNDARY_MS = 2 * oneWeek;
+
+export type ReminderTimerConfig = {
+  stopRefreshBoundaryMs?: number;
+};
+
+export class ReminderTimer {
+  reminder: Reminder;
+  timeout: ReturnType<typeof setTimeout> | null = null;
+  stopRefreshBoundaryMs: number = DEFAULT_STOP_REFRESH_BOUNDARY_MS;
+
+  constructor({
+    reminder,
+    config,
+  }: {
+    reminder: Reminder;
+    config?: ReminderTimerConfig;
+  }) {
+    this.reminder = reminder;
+
+    if (typeof config?.stopRefreshBoundaryMs === 'number') {
+      this.stopRefreshBoundaryMs = config.stopRefreshBoundaryMs;
+    }
+  }
+
+  getRefreshIntervalLength = () => {
+    if (!this.reminder.remindAt) return null;
+    const distanceFromDeadlineMs = Math.abs(timeLeftMs(this.reminder.remindAt.getTime()));
+    let refreshInterval: number | null;
+    if (distanceFromDeadlineMs === 0) {
+      refreshInterval = oneMinute;
+    } else if (distanceFromDeadlineMs < GROUP_BOUNDS.minute.lower) {
+      refreshInterval = distanceFromDeadlineMs;
+    } else if (distanceFromDeadlineMs <= GROUP_BOUNDS.minute.upper) {
+      refreshInterval = oneMinute;
+    } else if (distanceFromDeadlineMs <= GROUP_BOUNDS.hour.upper) {
+      refreshInterval = oneHour;
+    } else {
+      refreshInterval = oneDay;
+    }
+    return refreshInterval;
+  };
+
+  init = () => {
+    if (!this.reminder.remindAt) return null;
+    const timeoutLength = this.getRefreshIntervalLength();
+    if (timeoutLength === null) return null;
+
+    const boundaryTimestamp =
+      this.reminder.remindAt?.getTime() + this.stopRefreshBoundaryMs;
+    const timeLeftToBoundary = boundaryTimestamp - Date.now();
+
+    if (timeLeftToBoundary <= 0) {
+      this.timeout = null;
+      return;
+    }
+
+    if (this.timeout) clearTimeout(this.timeout);
+
+    this.timeout = setTimeout(() => {
+      this.reminder.refreshTimeLeft();
+      this.init();
+    }, timeoutLength);
+  };
+
+  clear = () => {
+    if (this.timeout) {
+      clearInterval(this.timeout);
+      this.timeout = null;
+    }
+  };
+}

package/src/reminders/index.ts

@@ -0,0 +1,3 @@
+export * from './Reminder';
+export * from './ReminderManager';
+export * from './ReminderTimer';