Reminder manager

client.reminders is the reminder manager, a ReminderManager from stream-chat. It keeps one Reminder per message, talks to the reminders API, and holds the user's reminder list. A reminder with a remind_at time is "remind me"; one without is "save for later". This page lists its API.

How reminders work end to end, with a "Saved for later" list and an alert when a reminder is due, is on Reminders and save for later.

Getting the manager

The client creates the manager when it's constructed, so there is one per client: client.reminders. Don't construct a ReminderManager yourself.

The manager follows events only while its subscriptions run:

The UI layer starts the subscriptions and the timers for you, and stops them when it's done. Code that uses the client without a UI layer calls these itself.

State

The manager's state

client.reminders.state is a store with one field:

The map changes when a reminder is added or removed. A change to an existing reminder, such as a new remind_at, is published on that reminder's own state, not here. So following one message's reminder takes two subscriptions: one to find the Reminder, one to follow it.

const messageId = "message-1";

const unsubscribe = client.reminders.state.subscribeWithSelector(
  ({ reminders }) => ({ reminder: reminders.get(messageId) }),
  ({ reminder }) => {
    const remindAt = reminder?.remindAt;
    console.log(
      remindAt != null
        ? `Due ${nsToDate(remindAt).toLocaleString()}`
        : "No time set",
    );
  },
);

The getters of client.reminders return the value at the moment you read them, and don't tell you when it changes:

Each reminder's state

A Reminder has its own state store, of type ReminderState. The timestamps are unix nanoseconds, as the API sends them: convert them with nsToDate() or nsToMs(), as Data conventions explains.

A Reminder also has:

timeLeftMs(remindAt), exported from stream-chat, computes the same value as the state field for any nanosecond timestamp.

The reminder list

client.reminders.paginator is a ReminderPaginator: the current user's reminders across all channels, loaded page by page. It's one paginator per client. Its state has the fields every paginator in the state layer has (items, isLoading, hasMoreHead, hasMoreTail, lastQueryError), and How pagination works explains them. The base paginator API is on Channel manager and ChannelPaginator.

While the manager's subscriptions run, every page the list loads also goes into the manager's state, so each loaded reminder gets its Reminder. The list itself holds what its queries returned: a reminder created or deleted later changes the manager's state, but not the list until it reloads.

Methods

None of these is optimistic. The manager's state changes once the server answers.

remind_at and expires_at are Date objects in a request, and the methods take an optional third argument with request options. They resolve to the Reminder that was already in the state. For a message that had no reminder yet, they add a new Reminder and resolve to undefined: read it with ReminderManager.getFromState(messageId) afterwards.

// Remind me in an hour
await client.reminders.upsertReminder(
  { message_id: message.id },
  { remind_at: new Date(Date.now() + 60 * 60 * 1000) },
);

const reminder = client.reminders.getFromState(message.id);

These methods write the state without a request. The manager uses them itself, and they don't change anything on the server:

Configuration

The manager has the config, configState and ReminderManager.updateConfig() that every configurable object has, and ReminderManager.initializeConfig(), which the client calls to rebuild the settings from client.config. In client.config, the settings are the reminders group of the client key:

The getters scheduledOffsetsMs and stopTimerRefreshBoundaryMs read the current values. A change to stopTimerRefreshBoundaryMs reaches the timers that are running. Configuration tree lists both, and Configuration explains how to set them.

Whether reminders are offered in a channel is a channel setting: channel.config.userMessageReminders.enabled, which the channel type's user_message_reminders can turn off.

Events

While its subscriptions run, the manager applies these events:

ReminderManager.isReminderWsEventPayload(event) tells whether an event is a reminder.* or notification.reminder_due event that carries a reminder.

Reminders also arrive with messages. A channel query and client.queryChannels() add the reminder of every message they load, with or without subscriptions.

Timers

Each Reminder with a remind_at has a timer that refreshes timeLeftMs in its state. The timer starts when the reminder is created or gets a remind_at, and stops when the reminder is removed or loses it. It refreshes more often the closer the deadline is, before and after it:

Once a reminder is overdue by stopTimerRefreshBoundaryMs, two weeks by default, its timer stops and timeLeftMs stays as it was last set.

A tick changes only that reminder's timeLeftMs. The manager's reminders map doesn't change, and nothing is published elsewhere. When the reminder comes due, the server sends notification.reminder_due, which the manager ignores. To alert the user, listen for that event, as Alerting when a reminder is due shows.

reminder.timer is a ReminderTimer:

See also

• Reminders and save for later: the feature end to end.
• How pagination works: the paginator state the reminder paginator shares.
• Reactive state: subscribing to stores.
• Message reminders in the JavaScript client: the reminders API and the server setting.