Inspection API
The read-only inspection API @openmaxai/chat-store/inspect: inspection snapshots per conversation and global (storage, realtime signals), and the stream of store events. Devtools is built on it.
Inspection API
The exports of the @openmaxai/chat-store/inspect entry point: the read-only inspection API. Status, wiring it into a host and an index of every export are on the overview.
The inspection API lets code outside the store see the store's internal state right now: a conversation's window, gaps, the progress of gap-fill and change catch-up, local messages, which local storage is in use, and every change in the order it happened: writes through dispatch, and the ones that do not go through it (a local write finishing, catch-up writing back, gap-fill queueing, a conversation opening or closing, a realtime signal arriving). It is read-only and changes nothing about how the store behaves. Devtools is built on it; you can also use it for your own diagnostics or to attach the state to an error report.
It is an entry point of its own, with no dependency on React or on any other chat package. Neither the exports of the root entry point @openmaxai/chat-store nor the ChatStore interface change because of it, and an app that does not use the inspection API changes no code.
inspect-example.ts
import { inspectChatStore } from "@openmaxai/chat-store/inspect";
const inspector = inspectChatStore(store);
// One conversation right now
const c = inspector.getConversation(conversationId);
console.log(c.window.fromSeq, c.window.toSeq, c.window.gaps, c.gapFill.running);
// Global: local storage, realtime signals
console.log(inspector.getGlobal().storage.inUse);
// The stream of store events
const unsubscribe = inspector.subscribe((record) => {
if (record.kind === "event") console.debug(record.event.type, record.change);
});
Guarantees
- Read-only. The inspector has no method that writes. Snapshots, and the arrays and objects inside them, are frozen copies; when nothing changed,
getConversationandgetGlobalreturn the same object, and in a snapshot that did change, the parts that did not are still the same objects. Theeventin the stream is the very object passed todispatch, andchangethe very object subscribers got; do not modify them. - Does not change how the store behaves. The inspector never calls
ChatStorage, never enters the local-data read/write queue, sends no request, does not change how many notifications subscribers get or in which order, and does not change the results the gap-fill scheduler returns (gapFill.last.resultis a frozen copy).estimateStorageonly calls the browser'snavigator.storage.estimate(). - Every change to a snapshot has a record. Whenever any field returned by
getConversationorgetGlobalchanges, exactly one record in the stream announces it: the record of the operation itself (theeventof adispatch, thegapFillof a gap-fill starting or ending, thelocalDataof local data), or, for changes that take none of these paths, akind: "snapshot"record (seeChatStoreInspectRecord). One operation that changes several fields gives one record; conversely some records change nothing (aneventwhosechangeisundefined, say). Records are sent synchronously after the change takes effect, so handingsubscribeandgetConversation/getGlobaltouseSyncExternalStoreis safe: no change is missed, and an unchanged snapshot is the same object and does not re-render. Storage fields that change halfway through opening or clearing local data (switching users first closes the previous user's database) are announced by the record sent when that operation finishes. - Next to no cost when nobody is looking. Until
inspectChatStoreis first called on a store, the store always keeps just one item: the reason the IndexedDB storage fell back to memory (that happens inopenLocalData, usually before inspection starts; an enum). Beyond that it records nothing extra for inspection and reads no clock. After that it keeps a few items per conversation (the last gap-fill and catch-up results, the server's latest change number) and a few global counters; it reads the clock when it keeps a time (a gap-fill starting and ending, a catch-up ending, a realtime signal, a failed write) and once per record; records for the event stream are created only while someone is subscribed. Reading a snapshot costs in proportion to the number of local messages, changes in flight and change numbers that arrived early, not to the number of messages in the window. - The events are the ones the store receives. Every
dispatchcall (including those gap-fill, the thread loader and read-back from local data make inside the package) gives exactly onekind: "event"record, in call order (also when a subscriber callback dispatches again), also when nothing changed (changeisundefined). A rejected event (one for whichdispatchthrows aTypeError) gets a record too, witherror, and the exception is still thrown to the caller. - Delivered synchronously; a broken callback does not hurt the store. Callbacks run synchronously once that
dispatchhas changed the data and notified the store's subscribers. An exception thrown by a callback is caught and handed toreportErrorin the next macrotask (rethrown when there is none); it does not affect thatdispatchor the other callbacks. Do not calldispatchfrom a callback.
inspectChatStore
function inspectChatStore(store: ChatStore): ChatStoreInspector;
Gets the inspector of store and from this moment starts recording what inspection needs (see Guarantees). Calling it again on the same store returns the same inspector. store must be made by createChatStore; otherwise it throws a TypeError.
ChatStoreInspector
interface ChatStoreInspector {
getConversation(conversationId: string): ChatStoreConversationInspection;
getGlobal(): ChatStoreGlobalInspection;
subscribe(listener: ChatStoreInspectListener): () => void;
estimateStorage(): Promise<ChatStoreStorageEstimate | undefined>;
}
| Method | Description |
|---|---|
getConversation(conversationId) |
The inspection snapshot of one conversation right now. When the store does not have the conversation, loaded is false and the other fields are empty (open is false too); a conversation that did not change (including one never loaded) returns the same object every time |
getGlobal() |
The global inspection snapshot |
subscribe(listener) |
Subscribes to the event stream; returns the unsubscribe function, which is safe to call twice. Only records after subscribing arrive: the store keeps no backlog, so subscribe early to see what happened before |
estimateStorage() |
The browser's estimate of storage usage and quota. undefined when the browser has no navigator.storage.estimate or it fails; never rejects |
When to read the snapshots again: after any record arrives (see Guarantees: every change to a snapshot has a record). getConversation and getGlobal return the same object when nothing changed, so read again after a record and compare by reference; the inspector's methods do not depend on this, so they can be passed on their own. In React you can write it directly:
use-inspection.ts
const conversation = useSyncExternalStore(inspector.subscribe, () =>
inspector.getConversation(conversationId),
);
ChatStoreConversationInspection
interface ChatStoreConversationInspection {
readonly conversationId: string;
readonly loaded: boolean;
readonly open: boolean;
readonly window: ChatStoreWindowInspection;
readonly gapFill: ChatStoreGapFillInspection;
readonly changeLog: ChatStoreChangeLogInspection;
readonly sends: readonly ChatStoreSendInspection[];
readonly patches: readonly ChatStorePatchInspection[];
readonly local: ChatStoreLocalSegmentInspection;
}
| Field | Description |
|---|---|
loaded |
The store has this conversation (it was loaded, or a message was sent in it) |
open |
A gap-fill scheduler has it marked open (after open, before close) |
window |
The range in memory, see ChatStoreWindowInspection |
gapFill |
Gap-fill progress, see ChatStoreGapFillInspection |
changeLog |
The change watermark and catch-up progress, see ChatStoreChangeLogInspection |
sends |
Local messages, in the order they were sent, see ChatStoreSendInspection |
patches |
Changes in flight, in the order they started, see ChatStorePatchInspection |
local |
The local segment, see ChatStoreLocalSegmentInspection |
ChatStoreWindowInspection
interface ChatStoreWindowInspection {
readonly count: number;
readonly limit: number;
readonly fromSeq: number | undefined;
readonly toSeq: number | undefined;
readonly hasOlder: boolean;
readonly hasNewer: boolean;
readonly watermark: number | undefined;
readonly catchingUp: boolean;
readonly gaps: readonly ChatStoreGap[];
}
| Field | Description |
|---|---|
count, limit |
Server messages in the range, and the limit (500). Local messages do not count |
fromSeq, toSeq |
The seq range the range covers. Deleting messages does not narrow it; gone once the conversation is closed |
hasOlder, hasNewer, watermark |
As in the conversation snapshot |
catchingUp |
Halfway through filling from the watermark: the server said there is more, and gap-fill will go on from the watermark. hasNewer is true then as well |
gaps |
seq stretches the store knows it does not have, see ChatStoreGap. An empty array when there are none |
There are no gaps inside the loaded range: a missing number there is a deleted message, and the store counts it as deleted.
ChatStoreGap
interface ChatStoreGap {
readonly kind: "behindWatermark" | "pendingPush";
readonly afterSeq: number;
readonly throughSeq: number;
}
A seq stretch the store does not have, afterSeq exclusive and throughSeq inclusive. behindWatermark: the range was told it reached the latest but ends below the watermark, so toSeq up to the watermark is missing; pendingPush: a push newer than the watermark arrived and could not be attached, so the watermark up to that push is missing (counted from the end of the range while there is no watermark yet).
ChatStoreGapFillInspection
interface ChatStoreGapFillInspection {
readonly running: boolean;
readonly rerunQueued: boolean;
readonly last: ChatStoreGapFillRun | undefined;
}
| Field | Description |
|---|---|
running |
A gap-fill scheduler is filling this conversation |
rerunQueued |
Another trigger came in while it was running; one more run follows this one |
last |
The last finished run, see ChatStoreGapFillRun. Absent until a run has finished since inspection started; a run that started before inspection started is not kept when it finishes (its start was not recorded) |
ChatStoreGapFillRun
interface ChatStoreGapFillRun {
readonly trigger: ChatGapFillTrigger;
readonly result: ChatGapFillResult;
readonly startedAt: number;
readonly settledAt: number;
}
A finished gap-fill run: which moment triggered it, the result (a frozen copy), and when it started and ended (millisecond timestamps). When triggers come in while it runs, the run that follows is a run of its own.
ChatGapFillTrigger
type ChatGapFillTrigger =
| "open"
| "reconnected"
| "foreground"
| "catchUp"
| "messages"
| "sent"
| "changes";
The moment that triggered a gap-fill: the method of the same name on the gap-fill scheduler. Triggers that come in during a run merge into the run that follows, which records the first of them.
ChatStoreChangeLogInspection
interface ChatStoreChangeLogInspection {
readonly watermark: number | undefined;
readonly serverHead: number | undefined;
readonly ahead: readonly number[];
readonly lastCatchUp: ChatStoreCatchUpRun | undefined;
}
| Field | Description |
|---|---|
watermark |
The change watermark: every change numbered at or below it has been applied in the range. Absent when this conversation does not catch up on changes |
serverHead |
The latest change number last read from the server (the headChangeSeq on a window, a page, a batch, a change-log page or a batch fetched by id; read-backs from local data do not count). Absent until one has been read since inspection started |
ahead |
Change numbers above the change watermark plus one that were already written, ascending: numbers are still missing in between |
lastCatchUp |
The last catch-up, see ChatStoreCatchUpRun |
ChatStoreCatchUpRun
interface ChatStoreCatchUpRun {
readonly outcome: ChatGapFillChangesOutcome;
readonly rounds: number;
readonly fetched: number;
readonly missing: number;
readonly tooOld: boolean;
readonly at: number;
}
The last catch-up: the outcome, how many change-log rounds, how many messages were fetched by id, how many were gone (summed over the rounds), whether the server said too old (tooOld; also when more than 10 pages would be needed), and when it ended. Without change-log read methods there is no catch-up and none of this.
ChatStoreSendInspection
interface ChatStoreSendInspection {
readonly clientMsgId: string;
readonly status: ChatMessageDeliveryStatus;
readonly messageId: string;
readonly serverId: string | undefined;
}
| Field | Description |
|---|---|
clientMsgId |
The client_msg_id of this local message |
status |
Its delivery_status right now: sending, failed, blocked, or confirmed but not yet matched with the server's copy |
messageId |
This message's id in the snapshot |
serverId |
The id of the server's copy, from the send response or a push; absent until known |
No message text. For the text, look messageId up in getSnapshot.
ChatStorePatchInspection
interface ChatStorePatchInspection {
readonly patchId: string;
readonly messageId: string;
readonly committed: boolean;
}
| Field | Description |
|---|---|
patchId |
This change's patchId (from patchStarted); a message with several changes in flight gets one row each |
messageId |
The message it changes |
committed |
The change's request succeeded, waiting for the server's copy to bring the new content |
ChatStoreLocalSegmentInspection
interface ChatStoreLocalSegmentInspection {
readonly writing: boolean;
readonly fromSeq: number | undefined;
readonly toSeq: number | undefined;
}
| Field | Description |
|---|---|
writing |
The range is aligned with the local segment, and changes to the range are written locally one by one (see Writing to the device) |
fromSeq, toSeq |
The seq range of the local segment while aligned |
ChatStoreGlobalInspection
interface ChatStoreGlobalInspection {
readonly conversations: readonly string[];
readonly openConversations: readonly string[];
readonly storage: ChatStoreStorageInspection;
readonly realtime: ChatStoreRealtimeInspection;
}
| Field | Description |
|---|---|
conversations |
The conversations the store has |
openConversations |
The conversations a gap-fill scheduler has marked open, in the order they were opened (by the earliest when several schedulers opened the same one) |
storage |
Local storage, see ChatStoreStorageInspection |
realtime |
Realtime signals, see ChatStoreRealtimeInspection |
ChatStoreStorageInspection
interface ChatStoreStorageInspection {
readonly configured: "memory" | "indexedDb" | "custom";
readonly inUse: "memory" | "indexedDb" | "custom" | undefined;
readonly fallbackReason: "lockHeld" | "noWebLocks" | "noIndexedDb" | "openFailed" | undefined;
readonly tabLock: "held" | "notHeld" | "notApplicable";
readonly encrypted: boolean;
readonly state: "closed" | "opening" | "open";
readonly userId: string | undefined;
readonly pendingWrites: number;
readonly lastWriteError: ChatStoreWriteError | undefined;
readonly evictedConversations: number;
}
| Field | Description |
|---|---|
configured |
What localData.storage was given: createMemoryStorage() (also when nothing was given), createIndexedDbStorage(), or a ChatStorage of your own (spreading the package's storage into an object of your own makes it your own too) |
inUse |
What is actually in use. With IndexedDB configured it can be memory, and fallbackReason says why: lockHeld another tab holds the lock, noWebLocks the browser has no Web Locks (or requesting the lock failed), noIndexedDb there is no IndexedDB, openFailed the database would not open; once it falls back the storage stays in memory until the page reloads. Absent while local data is not open |
tabLock |
Whether this tab holds the lock on local data; notApplicable for storage other than IndexedDB |
encrypted |
localData.encryption is set and the database in use encrypts |
state, userId |
Whether local data is closed, opening or open (opening from the moment openLocalData is called until it is done), and whose it is (the id given to openLocalData) |
pendingWrites |
Writes queued on local data and not done yet (those queued since inspection started) |
lastWriteError |
The last failed write, see ChatStoreWriteError |
evictedConversations |
Conversations evicted for quota since inspection started |
ChatStoreWriteError
interface ChatStoreWriteError {
readonly at: number;
readonly name: string;
readonly message: string;
}
When a write failed, the error name (such as QuotaExceededError) and the message; when what was thrown is not an error object, the name is Error and the message its string form. A failed write does not affect the data in memory; the next write rewrites the whole segment.
ChatStoreRealtimeInspection
interface ChatStoreRealtimeInspection {
readonly lastSignal: ChatStoreSignal | undefined;
}
The realtime connection itself (whether it is up, when its last frame arrived) is not in the store; the store does not own the connection. With the SDK they come from @openmaxai/chat-sdk, see Devtools · Realtime.
ChatStoreSignal
interface ChatStoreSignal {
readonly trigger: "messages" | "reconnected" | "changes";
readonly conversationId: string | undefined;
readonly at: number;
}
The last realtime signal the gap-fill scheduler got: messages, reconnected or changes (the scheduler's methods of the same name, whether or not they started a gap-fill; coming back to the foreground does not count), for which conversation (none for reconnected), and when.
ChatStoreInspectRecord
type ChatStoreInspectRecord =
| {
readonly kind: "event";
readonly id: number;
readonly at: number;
readonly event: ChatStoreEvent;
readonly source: ChatStoreEventSource;
readonly change: ChatStoreChange | undefined;
readonly error?: unknown;
}
| {
readonly kind: "gapFill";
readonly id: number;
readonly at: number;
readonly conversationId: string;
readonly trigger: ChatGapFillTrigger;
readonly phase: "started" | "settled";
readonly result?: ChatGapFillResult;
}
| {
readonly kind: "localData";
readonly id: number;
readonly at: number;
readonly op: "opening" | "opened" | "clearing" | "cleared" | "fellBack" | "writeFailed" | "evicted" | "conversationCleared";
readonly userId?: string;
readonly conversationId?: string;
readonly error?: unknown;
}
| {
readonly kind: "snapshot";
readonly id: number;
readonly at: number;
readonly area: ChatStoreSnapshotArea;
readonly conversationId: string | undefined;
};
One entry of the event stream, frozen. id counts up from 1 per store (only records that were created take a number); at is a millisecond timestamp.
kind |
When | Description |
|---|---|---|
event |
Every dispatch |
event is the event passed to dispatch; source is who sent it, see ChatStoreEventSource; change is the ChatStoreChange subscribers got, undefined when nothing changed; error is what was thrown when it was rejected |
gapFill |
A gap-fill run starts or ends | trigger as in ChatGapFillTrigger; result when it ends (the same frozen copy as gapFill.last.result). When triggers come in during a run, each round gets its own start and end (the next round's start announces rerunQueued dropping back to false); the last round's end is sent only once the conversation is no longer being filled, and announces running turning false |
localData |
Local data starts opening (opening, when openLocalData is called), opened (opened), starts clearing (clearing, when clearLocalData is called), cleared (cleared), fell back to memory (fellBack, before opened), failed to write (writeFailed), evicted a conversation for quota (evicted), cleared one conversation (conversationCleared, when clearConversation is called; deleting the local copy is a local write, whose localWrite follows when done) |
opening, opened and fellBack carry userId; clearing and cleared carry userId when it is known whose data it is; evicted carries the evicted conversationId, conversationCleared the cleared one (one record per evicted conversation); writeFailed carries error and the conversationId of that write (the localWrite of that write follows) |
snapshot |
A snapshot changed, but not through one of the three operations above | area says which part, see ChatStoreSnapshotArea. conversationId is the conversation changed; undefined when only global state changed, or several conversations at once (a scheduler being disposed) |
ChatStoreSnapshotArea
type ChatStoreSnapshotArea =
| "localWrite"
| "gapFillQueue"
| "changeLog"
| "openConversations"
| "realtimeSignal"
| "localSegment";
area |
When | What changed |
|---|---|---|
localWrite |
A queued local write finished or failed (when it failed, a localData record writeFailed carrying the change comes first, and this one follows, changing nothing more; also for writes queued before inspection started); when a whole-segment write merges with a segment whose change watermark is lower, one more is sent the moment the change watermark is lowered, without waiting for the write to finish |
storage.pendingWrites, storage.lastWriteError; local when the local segment stopped lining up during the write, and changeLog.watermark and changeLog.ahead when merging segments lowered the change watermark |
gapFillQueue |
A trigger came in while gap-fill was running; or a run ended without a gapFill end record (one that started before inspection started, or one ended by a store subscriber's callback throwing while writing back) |
gapFill.rerunQueued, gapFill.running |
changeLog |
Catch-up wrote fetched messages back into the store (not through dispatch, so there is no event record), a new server head was read, or a catch-up ended |
Messages, changeLog |
openConversations |
A gap-fill scheduler opened or closed a conversation, or was disposed (the record for opening comes before the gapFill start record) |
open, openConversations; on dispose also gapFill.running |
realtimeSignal |
The gap-fill scheduler got a realtime signal, including those that start no gap-fill | realtime.lastSignal |
localSegment |
A conversation's local segment was dropped (catch-up was told the change log is too old, or the thread loader found a read-back segment without a change watermark), sent synchronously, before the next network round trip | local cleared; when the change log was too old, the change watermark and changeLog.ahead cleared too; storage.pendingWrites up by one |
ChatStoreEventSource
type ChatStoreEventSource =
| "caller"
| "gapFill"
| "threadLoader"
| "localData";
Who sent a dispatch: caller your code, gapFill the gap-fill scheduler, threadLoader the thread loader, localData a read-back from local data (whoever read it).
ChatStoreInspectListener
type ChatStoreInspectListener = (record: ChatStoreInspectRecord) => void;
The event stream's callback; see subscribe and Guarantees. Subscribing the same function twice makes two subscriptions, each getting its own copy and unsubscribed on its own.
ChatStoreStorageEstimate
interface ChatStoreStorageEstimate {
readonly usageBytes: number;
readonly quotaBytes: number;
readonly scope: "origin";
}
The browser's estimate for the whole site (origin): not only chat data, and not only this user's. The numbers are approximate and each browser computes them differently; a number the browser leaves out counts as 0.
How Devtools uses it
Devtools reads the store only through the API on this page:
- On mount it calls
inspectChatStore(store), so the store starts recording from then on; then it callssubscribe, puts every record into a 50-entry ring buffer (the event log) and schedules a redraw for the next frame. While closed it keeps recording but does not redraw. - On redraw it reads
getGlobal(): the conversation picker listsopenConversations, the storage section readsstorage; then it readsgetConversation(id)for the selected conversation and draws the window, the change log, sends and the local segment. Both snapshots are the same object when nothing changed, so the panel skips the sections that did not change. - When opened it calls
estimateStorage()once; "Approximate size" shows the result. - The realtime section: the connection state and the last frame come from the SDK (or, without the SDK, from the connection state the host hands the panel), the last signal from
realtime.lastSignal.
The panel calls no store method outside this page, so it cannot do anything this page does not allow.
