OpenMax
Free Trial

Write events

The ChatStoreEvent the single write entry point takes and its twelve events, including the watermark at request time requestWatermark, optimistic sending and optimistic changes.

Write events

Exports of the @openmaxai/chat-store root entry point for the events the write entry point takes. Status, wiring it into a host and an index of every export are on the Overview.

ChatStoreEvent

type ChatStoreEvent =
  | ChatStoreWindowLoadedEvent
  | ChatStoreOlderLoadedEvent
  | ChatStoreNewerLoadedEvent
  | ChatStoreMessageUpsertedEvent
  | ChatStoreMessageDeletedEvent
  | ChatStoreConversationClosedEvent
  | ChatStoreViewChangedEvent
  | ChatStoreSendStartedEvent
  | ChatStoreSendSettledEvent
  | ChatStoreLocalMessageRemovedEvent
  | ChatStorePatchStartedEvent
  | ChatStorePatchSettledEvent
  | ChatStoreReactionChangedEvent
  | ChatStoreCardChangedEvent;

What the write entry point takes, discriminated by type. Each event is about one conversation. New kinds of writes add members to the union without changing the shape of existing ones.

The four data events other than windowLoaded (olderLoaded, newerLoaded, messageUpserted, messageDeleted) have no effect on a conversation that was never loaded: it has no range to attach to yet. The events for optimistic sending and optimistic changes are in the second half of this page.

ChatStoreWindowLoadedEvent

interface ChatStoreWindowLoadedEvent {
  type: "windowLoaded";
  conversationId: string;
  messages: readonly ChatMessage[];
  hasOlder: boolean;
  olderCursor?: string;
  hasNewer: boolean;
  newerCursor?: string;
  requestWatermark?: number;
  changeSeq?: number;
}

A window arrived and replaces the range: opening a conversation, jumping to a message, going back to the latest.

  • The latest window and a window around some seq both use it; only hasNewer differs. For the latest window it is false and the store moves the watermark to the window's highest seq; for a window around a message that does not reach the latest it is true and the watermark stays. hasNewer can only come from the server, never from counting messages.
  • A latest window that ends below the watermark does not count as reaching the latest: either the store received newer messages after the request was sent and this window is late, or the message at the watermark was deleted on the server. Without requestWatermark the store cannot tell which, so the watermark never moves back: the snapshot has hasNewer true, no newerCursor, and newerPending true; the missing part is fetched by seq forward from the end of the range, and until then pushes are not attached.
  • Messages already in the store are merged by id; one whose content did not change stays the same object. Deleted messages are not written back. The store sorts by seq itself (by id when equal).
  • changeSeq is the window's change watermark; see The change watermark and change numbers below.

The watermark at request time: requestWatermark

The store's watermark when the request was sent (getSnapshot().watermark); leave it out when there was none. It matters only for the latest window (hasNewer: false): the server said "this is the latest" after the store knew this watermark, so every number up to it that is missing from the window has been deleted, and even if the window ends below it, the range counts as covering it and can reach the latest. A value above the current watermark counts as the current watermark.

Without it (when you do not know when the request was sent) the window is treated as late. The gap-fill scheduler always passes it. The field of the same name on newerLoaded means the same.

Assumption: the read methods are not behind the pushes. The store's watermark comes from pushes; if reads lag behind (for example a read replica behind the primary), numbers the server has not seen yet would be taken as deleted, the range would cover them, and gap-fill would not fetch them again.

The change watermark and change numbers: changeSeq

The backend keeps a change log per conversation: every change to an existing message (edit, recall, delete, reaction added or removed, card settled) is one row, numbered upward per conversation. The store keeps a change watermark per conversation: every change numbered at or below it has taken effect on the messages of the range (and of the stretch on the device aligned with it). The gap-fill scheduler fetches the change log forward from it; see Gap fill · Catching up on changes.

  • Set when a window replaces the range. The changeSeq of windowLoaded is the newest number read in the same snapshot as the window (head_change_seq of the list response; for a window read from the device, the one recorded with that stretch). After the window the change watermark is that number, which may be lower than before; without it there is no change watermark, the conversation does not catch up on changes, and numbers on writes are not recorded.
  • A page or batch can only move it back. The changeSeq of olderLoaded and newerLoaded is that page's snapshot number; when it is below the change watermark (the page is older than changes already recorded), the change watermark moves back to it and the next catch-up fetches the messages changed after it again. A higher number changes nothing.
  • A write with a number moves it only when the number is the next one. messageUpserted, messageDeleted, reactionChanged (realtime pushes) and patchSettled (the response of a change request) can all carry changeSeq. Without a change watermark, without a number, or with 0 (no new change), the write applies as usual and the change watermark stays. With a change watermark W:
Number What happens
At or below W, or already received A duplicate: nothing happens (a reaction is not counted twice, and an older whole message does not overwrite a newer one). The exception is a change whose response carried only the number; see below.
W + 1 Applied as usual; W moves to it, and on through numbers that arrived early right after it.
Above W + 1 Applied as usual and the number is remembered; W stays. The missing numbers either arrive soon or are filled by the gap-fill scheduler's changes. At most 100 early numbers are remembered; beyond that a write still applies but its number is not remembered, so W stops just before it and the next catch-up fetches it again.

patchSettled always settles, even with a duplicate number. When it carries message, that change's content is already in, so a later push with the same number is a duplicate; without message (a reaction request returns only the number) W still moves, but the push with the same number is still applied once, folding the change into the server's copy.

ChatStoreOlderLoadedEvent

interface ChatStoreOlderLoadedEvent {
  type: "olderLoaded";
  conversationId: string;
  beforeSeq: number;
  messages: readonly ChatMessage[];
  hasOlder: boolean;
  olderCursor?: string;
  changeSeq?: number;
}

An older page arrived: scrolling up through history, or an older stretch read from local storage. It goes in front of the loaded range. beforeSeq is the seq of the earliest message in the range when the request was sent, and the page holds the messages right before it; if beforeSeq is no longer in the range (the window was replaced meanwhile), the page does not connect and is dropped. changeSeq is the page's snapshot number; when it is below the change watermark, the change watermark moves back to it; see The change watermark and change numbers.

ChatStoreNewerLoadedEvent

interface ChatStoreNewerLoadedEvent {
  type: "newerLoaded";
  conversationId: string;
  afterSeq: number;
  messages: readonly ChatMessage[];
  hasNewer: boolean;
  newerCursor?: string;
  requestWatermark?: number;
  changeSeq?: number;
}

A newer batch arrived: a page while scrolling back down, or a batch fetched forward from the watermark (loadThreadSince). It goes after the loaded range. afterSeq is where the request started; the batch holds the messages right after it by seq.

  • When afterSeq is not above the end of the range (the seq of its newest message, still counted after that message is deleted), the batch connects to the range and new messages go after it. If the batch says it is the end (hasNewer: false) but the range still ends below the watermark, the range stays marked as not reaching the latest, unless requestWatermark is given.
  • When afterSeq is not above the watermark, the batch connects to the watermark, which moves to the batch's highest seq.
  • When it connects to neither, the whole batch is dropped and the watermark stays.
  • hasNewer can only come from the server; give true when unsure.
  • changeSeq is the batch's snapshot number; when the batch connects to the range and the number is below the change watermark, the change watermark moves back to it; see The change watermark and change numbers.

ChatStoreMessageUpsertedEvent

interface ChatStoreMessageUpsertedEvent {
  type: "messageUpserted";
  conversationId: string;
  message: ChatMessage;
  changeSeq?: number;
}

New content for one message: an edit, a recall, a reaction summary, a card result, or a push that carries the body.

  • Already in the store: replaced in place. Older content (smaller content_version, or the store has it recalled or deleted and this one does not) does not overwrite.
  • Deleted earlier by messageDeleted: ignored.
  • Not in the store, exactly the next one after the watermark, and the range reaches the latest: attached at the end, and the watermark moves to it.
  • Not in the store, newer than the watermark but not connecting (something is missing in between, or the window does not reach the latest): kept out of the window; only newerPending is set, for gap-fill.
  • Anything else (older than the watermark and not in the window): ignored.

With changeSeq, the change watermark is checked first: a duplicate does nothing; see The change watermark and change numbers.

ChatStoreMessageDeletedEvent

interface ChatStoreMessageDeletedEvent {
  type: "messageDeleted";
  conversationId: string;
  messageId: string;
  changeSeq?: number;
}

A message is removed from the store (hard delete; a recall is not a delete and goes through messageUpserted). The watermark stays. The store remembers the id: a window, page, batch or push in flight that brings the message back does not write it again. Deleting does not shrink the range the store covers, so after the first or last message is deleted, a page fetched right next to it still connects. When local data is open, the copy on the device is deleted too (also when the conversation is not in memory). With changeSeq, the change watermark is checked first; see The change watermark and change numbers.

ChatStoreConversationClosedEvent

interface ChatStoreConversationClosedEvent {
  type: "conversationClosed";
  conversationId: string;
}

Closes a conversation: the messages in its range leave memory and only the watermark stays. The thread loader sends it when the last reader of a conversation leaves.

  • The snapshot keeps only local messages; hasOlder and hasNewer are false and there are no cursors; watermark and newerPending stay as they were.
  • From then on it is treated like a conversation never loaded: a push does not go into it and only records that there are newer messages (newerPending); a newer batch is not written; the gap-fill scheduler does not fill it; swapping a window in (opening it again) works as usual. Deleted ids are still remembered, so data in flight that brings them back is still dropped. Optimistic changes in flight are discarded.
  • When local data is open, the range's messages were already written to the device one change at a time (see openLocalData) and are read back from there on reopening; when a reaction or edit to one of those messages arrives while it is closed, the stretch on the device is dropped (see openLocalData) and reopening fetches the latest window from the backend. Changes made while the page was closed arrive as no push, so they do not drop the stretch: on reopening the gap-fill scheduler catches up on them from the change watermark recorded with that stretch; see Gap fill · Catching up on changes.
  • Without a range (never loaded, already closed) it does nothing. When it changes data, subscribers get one window.

ChatStoreViewChangedEvent

interface ChatStoreViewChangedEvent {
  type: "viewChanged";
  conversationId: string;
  anchorMessageId?: string;
}

Which message the current view rests near, so that when the memory window is over its limit the store knows which end is farthest from the view. Only a hint: it changes no data, notifies no subscriber, and leaves the snapshot as it is (also for a conversation never loaded; the hint is kept for when the first window arrives). Leaving out anchorMessageId clears the hint; without a hint (or when that message is no longer in the window), going over the limit unloads the end opposite the one just inserted.

ChatStoreSendStartedEvent

interface ChatStoreSendStartedEvent {
  type: "sendStarted";
  conversationId: string;
  message: ChatMessage;
}

You send a message: it is written into the store as sending first, so it shows before the server confirms it. A retry uses it too, sending again with the same client_msg_id.

  • The local message does not enter the loaded range sorted by seq: it takes no seq, does not move the watermark, and gap-fill does not see it; the store ignores message.seq.
  • In the snapshot it comes after the loaded messages (several of them in the order they were sent), and is not shown while the range does not reach the latest (hasNewer is true); its id is the client_msg_id, and delivery_status is sending.
  • A local message with the same client_msg_id is already in the store: a failed or blocked one goes back to sending and keeps its position; a confirmed one is not changed.
  • The loaded range already has a server message carrying this client_msg_id: nothing happens.
  • A missing or empty message.client_msg_id makes dispatch throw TypeError and change nothing. A conversation never loaded can be sent to as well.

ChatStoreSendSettledEvent

type ChatStoreSendSettledEvent =
  | {
      type: "sendSettled";
      conversationId: string;
      clientMsgId: string;
      outcome: "sent";
      message?: ChatMessage;
    }
  | {
      type: "sendSettled";
      conversationId: string;
      clientMsgId: string;
      outcome: "failed";
    }
  | {
      type: "sendSettled";
      conversationId: string;
      clientMsgId: string;
      outcome: "blocked";
      refusalText: string;
      seq?: number;
    };

The result of a send; the local message is found by clientMsgId. When the server message enters the loaded range (through the send response, a push, gap-fill, paging or a window swap) and matches the local one (same client_msg_id, or the id the send response gave), the local message is removed in the same write and its row becomes the server message: there are never two. The store does not guess by sender, body or time.

outcome Meaning
sent The server confirmed it. With the server message (message), it is written by the rules of messageUpserted; when it cannot attach to the range yet (something is missing in between), the local message takes the server content, is marked sent and stays at the end until gap-fill brings it into the range; when it was already deleted before the response arrived (the deletion came first), the local message is removed. Without it, the local message is marked sent and stays at the end until a push or gap-fill brings back the message with the same client_msg_id; when the server never echoes it, call sent() on the gap-fill scheduler. When the local message is no longer in the store, only message is written, as by messageUpserted.
failed The send failed. The local message is marked failed and stays where it was (messages arriving later come after it), waiting for a retry.
blocked Content moderation blocked it; the server did not store it. The local message is marked blocked, carries refusalText, and comes after the message at seq (without seq, it stays where it was). Later gap-fills and window swaps do not wash it away.

failed and blocked only change a local message that is still sending: a confirmed one is never turned back into a failure. When a failed or blocked message's position is outside the current window (after jumping to an older window), it is not shown in that window. An unknown outcome makes dispatch throw TypeError.

ChatStoreLocalMessageRemovedEvent

interface ChatStoreLocalMessageRemovedEvent {
  type: "localMessageRemoved";
  conversationId: string;
  clientMsgId: string;
}

Remove a local message (sending, failed, blocked, or confirmed but not matched yet), for example when the user deletes a message that failed to send. The loaded range and the watermark are not affected; nothing happens when there is no such message.

ChatStorePatchStartedEvent

interface ChatStorePatchStartedEvent {
  type: "patchStarted";
  conversationId: string;
  patchId: string;
  messageId: string;
  apply: (message: ChatMessage) => ChatMessage;
}

You change a message (react, edit, recall): the store changes it first, and patchSettled finishes it when the request ends.

  • The store keeps the version the server gave (the base) and this change; what is shown is the base with the unfinished changes applied in order. When new server content for the message arrives during a change (a whole message by messageUpserted, a window, a page, a batch, or an incremental reactionChanged), it replaces the base and the changes are applied again on top; whether a whole new message is older is judged against the base only.
  • apply receives a frozen message and returns a new, changed object; do not modify the one it receives. It may be called more than once.
  • apply must be idempotent: applied to a base that already contains this change, the result equals the base (reactions: do not add a code you already reacted with, do not remove one you have not; edits: set the content to the new one). The push for your own change can arrive before the request's response and land in the base first; idempotence keeps it from being applied twice.
  • Write other people's reactions into the base with reactionChanged; do not take the message from the snapshot, add the reaction and send messageUpserted: the snapshot's message already has the change applied, and with it as the base the change can no longer be undone on failure.
  • Only messages in the loaded range are affected; nothing happens when the message is not in the range or the patchId is in use. When the message is unloaded, deleted, or left out of a swapped-in window, its changes are dropped.

ChatStorePatchSettledEvent

interface ChatStorePatchSettledEvent {
  type: "patchSettled";
  conversationId: string;
  patchId: string;
  outcome: "succeeded" | "failed";
  message?: ChatMessage;
  changeSeq?: number;
}

The request for a change ended. Nothing happens without such a patchId; an unknown outcome makes dispatch throw TypeError.

outcome Meaning
succeeded With the message the server returned (message), it becomes the new base and this change is dropped. Without it, this change stays applied on top of the base until a whole new server message arrives (the server includes the change by then), or until the base already contains it (applying it changes nothing, for example when the push for your own reaction arrived) and no change still applied comes before it.
failed Drop this change and return to the base (with the other unfinished changes). Server content that arrived through the write entry point in the meantime (whole new messages, reactions written by reactionChanged) is in the base and is not undone: reactions other people added meanwhile stay, and a failed edit returns to the server's content.

changeSeq is the number in the change request's response and matters only for succeeded; 0 means no new change (a repeated reaction, for example). It moves the change watermark as in The change watermark and change numbers, except that a duplicate never stops the settling.

ChatStoreReactionChangedEvent

interface ChatStoreReactionChangedEvent {
  type: "reactionChanged";
  conversationId: string;
  messageId: string;
  reactorId: string;
  code: string;
  added: boolean;
  byMe: boolean;
  unicodeFallback?: string;
  changeSeq?: number;
}

One reaction change on a message (the increment in a realtime signal: who, which code, added or removed), written directly to the version the server gave (the base). byMe means reactorId is the current user; unicodeFallback is the glyph used when this code is created, code when left out.

  • Added: a new entry (count 1) when there is no such code; otherwise the count goes up by 1 and the person is recorded while the list has fewer than 20. Removed: the count goes down by 1 and the person leaves the list; the entry is removed at 0. reacted_by_me follows byMe changes only. content_version is not touched.
  • Idempotent: adding one already recorded (the person is in reactor_ids, or it is yours and reacted_by_me is already true) and removing one not recorded (yours while reacted_by_me is false, or someone else's not in a list that is not truncated) do nothing, so a repeated push, or your own reaction already written by the request's response, is not counted twice. Exception: when the list is truncated (20 names), a repeated add or remove from someone outside the list cannot be recognised as a repeat and is counted again; the server only sends the first 20 people, so the store cannot tell.
  • With changes in flight, the base is what changes and the changes are applied again on top, so this reaction stays when a change fails and is undone.
  • Only messages in the loaded range are affected; nothing happens when the message is not in the range (local messages included): it carries the server's summary the next time it is fetched.
  • With changeSeq, the change watermark is checked first: a push with the same number arriving again does not add or remove a second time, truncated list or not; see The change watermark and change numbers.

ChatStoreCardChangedEvent

interface ChatStoreCardChangedEvent {
  type: "cardChanged";
  conversationId: string;
  messageId: string;
  card: Partial<Pick<ChatMessage, "card_body" | "card_preview" | "card_truncated" | "card_superseded" | "card_expired" | "card_state">>;
  changeSeq?: number;
}

New values for a message's card fields (the settled record returned after your own answer, or card fields read again), written to the server's version (the base) directly.

  • Keys given in card are written; a value of undefined removes that field. Keys not given stay as they are.
  • card_state is the exception: only the first settled record counts, so it is not overwritten when the base already has one, and undefined does not clear it (a read after answering can be sent before the settle and come back after it).
  • Nothing is notified when the result equals what was there. content_version is not touched.
  • With changes in flight, the base is changed and the changes are applied again on top.
  • Only messages in the loaded range are affected; otherwise (including local messages) nothing happens: the message carries the server's card fields the next time it is fetched. When the message is not in memory and the local copy was not updated with it, that local segment is dropped (same as reactionChanged).
  • With changeSeq (the number on the frame for someone else's answer), the change watermark is checked first: a number already seen writes nothing (the card fields were read after the frame, so the store already reflects that change); otherwise the fields are written and the number recorded; see The change watermark and change numbers.