Thread loader
createChatThreadLoader: the first window, paging, opening and closing gap fill, single messages on demand, without React; the read methods ChatThreadSource and the read state.
Thread loader
Exports of the @openmaxai/chat-store root entry point for the thread loader. Status, wiring it into a host and an index of every export are on the Overview.
The thread loader fetches from the backend on behalf of whoever reads the store: the first window, paging back and forward, opening and closing gap fill, single messages outside the window, and the window around a message being jumped to, and it tracks what is in flight and what failed per conversation. It does not depend on React and does not touch the DOM; fetched data always goes back through the store's write entry point, and the read state is derived from the store snapshot and those records. The hooks of the React binding only subscribe to it and call it; pages without React use it directly.
chat-thread-loader.ts
import {
createChatGapFillScheduler,
createChatStore,
createChatThreadLoader,
} from "@openmaxai/chat-store";
// One per host (per signed-in user).
const store = createChatStore();
const gapFill = createChatGapFillScheduler({ store, source: host.messaging });
const loader = createChatThreadLoader({ store, source: host.messaging, gapFill });
// Entering a conversation: the first reader fetches the latest window (or just fills the gap); returns the function to call on leaving.
const leave = loader.openThread(conversationId);
const unsubscribe = loader.subscribeThread(conversationId, () => {
const { messages, status, error, hasOlder } = loader.getThread(conversationId);
render(messages, status, error, hasOlder);
});
// Paging back, retrying a failure.
await loader.loadOlder(conversationId);
loader.retry(conversationId);
// Leaving the conversation: gap fill is closed when the last reader leaves.
unsubscribe();
leave();
Reconnects, returning to the foreground and messages signals are still yours to hand to the gap-fill scheduler (gapFill.reconnected() and so on), see Overview · Using it in a host.
createChatThreadLoader
function createChatThreadLoader(options: ChatThreadLoaderOptions): ChatThreadLoader;
Creates a thread loader. One per store (per host); ChatStoreProvider creates its own from its props. Throws TypeError when options.store was not created by createChatStore.
ChatThreadLoaderOptions
interface ChatThreadLoaderOptions {
store: ChatStore;
source: ChatThreadSource;
gapFill?: ChatGapFillScheduler;
requestCache?: ChatRequestCache;
newerPageLimit?: number;
}
| Field | Description |
|---|---|
store |
The store read and written. |
source |
The read methods, see ChatThreadSource. |
gapFill |
The gap-fill scheduler, which must be created on the same store. Its open is called when a conversation is opened, and close when the last reader leaves; when several loaders share one gap-fill scheduler, readers are counted per conversation across all of them, and close is called only once every loader's readers have left. Without it there is no gap fill. |
requestCache |
The request result cache that keeps fetched single messages, under the key ["@openmaxai/chat-store", "message", conversationId, messageId]. Without it the loader creates its own. |
newerPageLimit |
How many messages loadNewer asks for when it pages forward by newerCursor, passed to source.loadThread as options.limit. Without it no limit is passed and the read methods pick the page size. Not used when there is no cursor and it goes forward by seq (the stretch on the device, loadThreadSince). |
ChatThreadLoader
interface ChatThreadLoader {
openThread(conversationId: string): () => void;
getThread(conversationId: string): ChatThreadReadState;
subscribeThread(conversationId: string, listener: () => void): () => void;
loadOlder(conversationId: string): Promise<void>;
loadNewer(conversationId: string): Promise<void>;
retry(conversationId: string): void;
openMessage(conversationId: string, messageId: string): () => void;
getMessage(conversationId: string, messageId: string): ChatMessageReadState;
subscribeMessage(conversationId: string, messageId: string, listener: () => void): () => void;
retryMessage(conversationId: string, messageId: string): void;
openMessageByClientId(conversationId: string, clientMessageId: string): () => void;
getMessageByClientId(conversationId: string, clientMessageId: string): ChatMessageReadState;
subscribeMessageByClientId(conversationId: string, clientMessageId: string, listener: () => void): () => void;
retryMessageByClientId(conversationId: string, clientMessageId: string): void;
jumpTo(conversationId: string, target: ChatMessageTarget, options?: ChatJumpOptions): Promise<ChatJumpResult>;
}
| Method | Description |
|---|---|
openThread |
A reader starts reading the conversation; returns the function to call on leaving (calling it again is harmless). The first reader opens it: if the store has no range for the conversation yet, a window is swapped in first, then the gap-fill scheduler's open is called; with a range already there, open is called directly. The window swapped in: when the store's local data is open, the device has this conversation, and the gap can be filled (a gap-fill scheduler was given and the source has loadThreadSince), it is the newest page of the stretch on the device (at most 50 messages), and gap fill continues from its end; otherwise source.loadThread fetches the latest window. When reading the device fails, or the stretch is dropped (see Writing to the device) or the user switches while reading, the latest window is fetched just the same. When the read methods have a change log (loadChangesSince and getMessagesByIds) but the stretch on the device has no change watermark (it was stored before the change log existed), the stretch is dropped and the latest window fetched: there is no telling which changes it already has. After fetching new messages the gap-fill scheduler goes on to catch up on changes; a failed catch-up counts as the gap-fill step failing, and retry runs it again. When the last reader leaves, close is called and conversationClosed goes through the write entry point: the conversation's messages leave memory and only the watermark stays; opening it again swaps a window in again (from the device when it has it). Several loaders reading one store count readers per conversation together and close only when all have left. Leaving is decided in a microtask, so a reader that comes right after leaving (StrictMode's unmount and mount again) carries on, without closing and reopening. Once closed, the conversation is no longer gap-filled, and retry after a failed gap fill does nothing. A window that arrives after all readers left is still written to the store and then closed at once. Several readers of the same conversation swap in one window and fill one gap. |
getThread / subscribeThread |
The conversation's read state right now (see ChatThreadReadState) and notification of its changes. No openThread is needed first: a conversation already in the store is ready at once. |
loadOlder |
When there is more that is older, fetches a page and attaches it to the front of the window (olderLoaded). With an olderCursor, calls loadThread with it; without a cursor (the older end was unloaded, or the window was read from the device) it goes back by seq from the earliest message of the range: from the stretch on the device when it has them (at most 50), otherwise loadThread(conversationId, undefined, { aroundSeq }) fetches the window around the earliest message of the range and keeps the part before it, and paging continues from that window's nextCursor. Rejects when the source does not honor aroundSeq (the window it returns has no newerCursor and does not reach the earliest message of the range). Rejects on failure, leaving the messages as they are. |
loadNewer |
When the window does not reach the latest, fetches a forward page with loadThread by newerCursor if there is one (passing limit when newerPageLimit is given); otherwise goes forward by seq from the end of the range: from the stretch on the device when it has them, otherwise with loadThreadSince. Attaches it to the end of the window (newerLoaded). A page read from the device always says there is more after it; the step that reaches the latest is always the backend's. Rejects when there is no cursor, the source has no loadThreadSince and the device has nothing. When the gap-fill scheduler has latestWindowOnGap and keeps a latest window aside that does not connect yet (see Gap-fill), it is checked against the end of the range first: if it connects it is appended on the spot without a request; otherwise one page is loaded as usual and it is checked again after that page. Appending it is followed by another gap-fill. |
retry |
Redoes the step that failed (window fetch, gap fill, paging back or forward); does nothing when nothing failed. A redo that fails again is only recorded, not rejected. After the last reader leaves, gap fill has stopped: when the failed step was gap fill, calling it does nothing until the next openThread. |
openMessage |
A reader starts reading the message; returns the function to call on leaving. When the message is not in the conversation's in-memory window, calls source.loadMessage once; if the message leaves the window while being read, fetches again. The fetched message is kept in the request result cache (one fetch per message) and is not written into the store: the store's write entry point only takes messages that connect to the loaded range. |
getMessage / subscribeMessage |
The message's read state right now (see ChatMessageReadState) and notification of its changes. |
retryMessage |
Fetches again when the message is not in the window and the last fetch failed; does nothing otherwise. The request result cache caches failures too (while not invalidated, load rejects with the cached reason), so it first invalidates the message in the cache and then fetches; calling it again while that fetch is in flight joins it instead of sending a second request. |
openMessageByClientId |
A reader starts reading a message you sent, by client_msg_id; returns the function to call on leaving. Nothing is fetched while it has not been replaced by the server's copy (your local copy is in the store); once replaced, when the server's copy is not in the window, it is fetched by its id as with openMessage. |
getMessageByClientId / subscribeMessageByClientId |
The read state of the message you sent right now, and notification of its changes; see Reading one by client_msg_id below. |
retryMessageByClientId |
Once replaced by the server's copy, fetches that one again as with retryMessage; does nothing otherwise. |
jumpTo |
Jumps to a message: brings it into the conversation's window; see Jumping to a message below. |
Per conversation, at most one latest-window fetch, one page back and one page forward are in flight at a time; repeated calls get the same promise. For jumps, see Jumping to a message below.
Nothing is retried automatically after a failure: only retry, retryMessage, the conversation's next opening or the message's next openMessage (and the message leaving the window while being read) fetch again; when the last fetch of a single message failed, each of these first invalidates the message in the request result cache and then fetches, while a message fetched successfully is still served from the cache. Notifications (including the message being invalidated in the request result cache) never trigger a fetch, so re-reading state on every notification cannot turn into a retry loop.
Jumping to a message
jumpTo(conversationId, target, options?) is the window the viewport controller needs when it receives jump (a request to scroll to a given message): when the target is in the loaded window nothing is fetched, otherwise the window around it is swapped in. The source is not limited to clicks inside the message list (replies, @mentions): a module outside the chat that needs to locate a message (for example jumping from an agent run to the message that triggered it) calls it too. The target is either the server's id or the client_msg_id of a message you sent (one just sent, with no server id yet, works too); see ChatMessageTarget.
- In the window (in
getSnapshot(conversationId).messages): nothing is fetched; the result isfoundstraight away. seqknown (target.seq, only a hint): the window around it is swapped in. When the store's local data is open, the stretch on the device covers thatseq, the window read has the message, and the source hasloadThreadSince, up to 25 messages at and before it and up to 25 after it are read from the stretch, with no request; otherwiseloadThread(conversationId, undefined, { aroundSeq })is called. When the source has a change log but the stretch has no change watermark, the device is not used (as withopenThread).sequnknown, or the window fetched by the hintedseqdoes not have it:loadMessagefetches it first (sharing the request result cache withopenMessage, so a message fetched before is not fetched again), then the window around itsseqis swapped in. WhenloadMessagereturnsundefinedor the source has no such method, the result isnotFound.- A message you sent: once replaced by the server's copy, the jump goes to the server's copy (when that copy did not bring back
client_msg_id, it is found through the mapping the store keeps, up to the latest 500). While it is still your local copy: one sending, or confirmed but not matched yet, sits after the latest message, so when the window does not reach the latest the latest window is swapped in and gap fill carries on as usual; a failed or blocked one has its own position, and the window there is swapped in. - The window swapped in is written by the rules of
windowLoaded: at most 500 messages; when it does not reach the latest there is no gap fill and nothing is written to the device, andmessagessignals only count; paging back and forward then continues by cursor orseq, as withloadOlderandloadNewer; a page in flight when the window is swapped was fetched against the old window and is dropped when it arrives, and the firstloadOlderorloadNewerafter the swap does not reuse it but fetches against the new window; however the dropped one ends, it is not recorded in the read state (a failure leaves noerrorandretrydoes not page again for it; a success does not clear the new one's failure), while the promise its caller got still settles as it did. A deleted message isnotFoundstraight away, with no fetch.
While a jump to the same target is in flight and it is the latest jump, the same promise is returned (when jumping A → B → A in a row, the third one fetches on its own instead of reusing the A that B superseded). When the target changes (including a jump whose target is already in the window and needs no fetch), the one in flight is no longer written to the store and resolves to superseded; so does a first window fetch in flight (the window openThread swaps in), which no longer overwrites the window jumped to. When the latest jump settles without swapping in a window (notFound, or it failed) while the conversation has a reader but no window yet, the latest window is swapped in as openThread does (a first window fetch still in flight is swapped in when it comes back), so the thread does not stay loading. When the source rejects, jumpTo rejects, the messages stay as they are, and the step is recorded as failed: retry jumps again to the target of the latest jump, error stays until a jump succeeds, a later jump (including one whose target is already in the window and needs no fetch) replaces this failure, clearing error so that retry no longer jumps for it, and when the store has no range for the conversation yet status is error until the window above is swapped in; when that fetch fails too, it is recorded as a failed window fetch and retry fetches the latest window again. When the conversation has no reader, the window fetched is closed at once (as with openThread), so call openThread first and then jumpTo. The loader does not read the clock: the caller decides its own timeout for fetching the window and aborts options.signal when it runs out (see ChatJumpOptions): that call resolves to aborted at once while the fetch carries on, and a window that arrives late is written to the store by the rules above; a signal already aborted before the call starts no jump.
Reading one by client_msg_id
getMessageByClientId(conversationId, clientMessageId) reads a message you sent: the send entry point hands back only client_msg_id, and once your local copy is replaced by the server's copy the id changes, which getMessage (reading by id) cannot follow.
- While it has not been replaced by the server's copy,
messageis your local copy (delivery_statusis sending, failed or blocked, or confirmed but not matched yet) andstatusisready; it is given even when the window does not reach the latest and it is not in the snapshot. - Once replaced, the server's copy is read as with
getMessage: the one in the store when it is in the window, otherwise the one fetched by its id (that needs a reader,openMessageByClientId). When the server's copy did not bring backclient_msg_id, it is found through the mapping the store keeps (up to the latest 500, still kept after the conversation closes). - When the store has no such
client_msg_id, or the copy it was replaced by has been deleted,statusisreadyandmessageisundefined.
ChatThreadReadState
interface ChatThreadReadState {
readonly messages: readonly ChatMessage[];
readonly status: ChatReadStatus;
readonly error: unknown;
readonly isFetching: boolean;
readonly hasOlder: boolean;
readonly hasNewer: boolean;
}
A conversation's read state; the same object while nothing changed (it can go straight into useSyncExternalStore).
| Field | Description |
|---|---|
messages |
The conversation's in-memory window, the same as getSnapshot(conversationId).messages. Unchanged messages stay the same object. |
status |
See ChatReadStatus. It is error only when the very first window fetch (or jump) failed and the store has no range for the conversation; it goes back to loading while that is retried. |
error |
The reason of the latest failure; cleared only once that step later succeeds. When gap fill or paging fails with data present, the data stays and status is still ready. |
isFetching |
A fetch issued through this loader is running: the first load, the gap fill on opening, paging, jumping. Gap fills triggered by reconnects, the foreground or messages signals go straight from the caller to the gap-fill scheduler and are not counted. Always true while status is loading. |
hasOlder |
There is more that is older. |
hasNewer |
The window does not reach the latest. |
error is the raw value the read method rejected with; the store package does not wrap it. When @openmaxai/chat-sdk/react re-exports these hooks, the SDK wraps it into the SDK's error type; that step is not in this package. The same holds for the error of ChatMessageReadState.
ChatMessageReadState
interface ChatMessageReadState {
readonly message: ChatMessage | undefined;
readonly status: ChatReadStatus;
readonly error: unknown;
readonly isFetching: boolean;
}
A message's read state; the same object while nothing changed. When the message is in the window, message is the store's copy and status is ready; otherwise it is the fetched copy, which does not follow live updates, and once the message enters the window the store's copy is used instead. When loadMessage returns undefined (deleted, no access) or the source has no such method, status is ready and message is undefined. error is the reason of the latest failed fetch.
ChatReadStatus
type ChatReadStatus =
| "loading"
| "ready"
| "error";
| Value | Meaning |
|---|---|
loading |
The store does not have the data yet; it is being fetched. |
ready |
There is data (gap fill may still be running in the background). |
error |
The very first fetch failed; there is no data. |
ChatThreadSource
interface ChatThreadSource extends ChatGapFillSource {
loadThread(conversationId: string, cursor?: string, options?: {
direction?: "older" | "newer";
aroundSeq?: number;
limit?: number;
}): Promise<ChatThreadSourcePage>;
loadMessage?(conversationId: string, messageId: string): Promise<ChatMessage | undefined>;
}
The read methods the thread loader fetches with, injected by the caller. They are shaped like the host's messaging, so you can pass the host's messaging in directly; it is also a ChatGapFillSource, so the same object can go to the gap-fill scheduler.
| Method | Description |
|---|---|
loadThread |
Fetches a page. Without cursor, the latest window; with cursor, options.direction omitted or "older" pages back (cursor is the previous page's nextCursor), "newer" pages forward (cursor is newerCursor). Without cursor and with options.aroundSeq, the window around that seq, the same option as the host's messaging.loadThread; loadOlder uses it when there is no cursor. options.limit is an upper bound on how many messages the page should hold, used only when paging forward and for the latest window (the same as the host's ChatThreadLoadOptions.limit): the read methods may ignore it or return fewer, and the loader goes only by the returned cursors to tell whether there is more. |
loadThreadSince |
Fetches forward from a seq, as for the gap-fill scheduler. loadNewer uses it when the window has no forward cursor. |
loadMessage |
Fetches one message by id; returns undefined when it cannot be had. Without it, only what is in the store is read. |
The two change-log methods loadChangesSince and getMessagesByIds come from ChatGapFillSource; the gap-fill scheduler uses them to catch up on changes. When the same object goes to both the thread loader and the scheduler, the thread loader uses them to decide whether the stretch on the device can be used.
ChatThreadSourcePage
interface ChatThreadSourcePage extends ChatGapFillLatestPage {
newerCursor?: string;
}
A page fetched by loadThread, the same as the return value of the host's messaging.loadThread. nextCursor present means there is more that is older; newerCursor present means this page does not reach the latest (a window around a message, or a forward page not at the end yet). headChangeSeq (from ChatGapFillLatestPage) is the change number of the same snapshot: a window swapped in takes it as the change watermark, and an older or newer page attached to the range moves the change watermark back when it is older.
ChatMessageTarget
type ChatMessageTarget =
| {
messageId: string;
seq?: number;
}
| {
clientMessageId: string;
};
Which message jumpTo jumps to: the server's id (seq is only a hint for fetching the window and may be left out), or the client_msg_id of a message you sent (one just sent with no server id and seq yet, or one already replaced by the server's copy). The field is named clientMessageId; it is the same value as client_msg_id on the message and clientMsgId in the write entry point's events.
ChatJumpResult
type ChatJumpResult =
| {
outcome: "found";
messageId: string;
}
| {
outcome: "notFound";
}
| {
outcome: "superseded";
}
| {
outcome: "aborted";
};
The result of one jumpTo.
outcome |
Meaning |
|---|---|
found |
The target is in the conversation's messages right now. messageId is that row's id: for a local message not yet replaced by the server's copy it is its client_msg_id; once replaced, the server's id. |
notFound |
There is no such message: the server says it is not there (deleted, not visible), the store has deleted it, or its seq could not be had. The window that was to be fetched is swapped in all the same, landing where it used to be. |
superseded |
Before it finished, another jumpTo came for this conversation; this one's result is no longer written to the store. |
aborted |
The caller's signal was aborted before the result came. The fetch carries on and a window that arrives late is still written to the store; the caller uses this to not land on the target. |
ChatJumpOptions
interface ChatJumpOptions {
signal?: AbortSignal;
}
Options for jumpTo. Once signal is aborted that call resolves to aborted at once; a signal already aborted before the call starts no jump. The fetch itself carries on.
