OpenMax
Free Trial

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, getConversation and getGlobal return the same object, and in a snapshot that did change, the parts that did not are still the same objects. The event in the stream is the very object passed to dispatch, and change the 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.result is a frozen copy). estimateStorage only calls the browser's navigator.storage.estimate().
  • Every change to a snapshot has a record. Whenever any field returned by getConversation or getGlobal changes, exactly one record in the stream announces it: the record of the operation itself (the event of a dispatch, the gapFill of a gap-fill starting or ending, the localData of local data), or, for changes that take none of these paths, a kind: "snapshot" record (see ChatStoreInspectRecord). One operation that changes several fields gives one record; conversely some records change nothing (an event whose change is undefined, say). Records are sent synchronously after the change takes effect, so handing subscribe and getConversation / getGlobal to useSyncExternalStore is 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 inspectChatStore is first called on a store, the store always keeps just one item: the reason the IndexedDB storage fell back to memory (that happens in openLocalData, 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 dispatch call (including those gap-fill, the thread loader and read-back from local data make inside the package) gives exactly one kind: "event" record, in call order (also when a subscriber callback dispatches again), also when nothing changed (change is undefined). A rejected event (one for which dispatch throws a TypeError) gets a record too, with error, and the exception is still thrown to the caller.
  • Delivered synchronously; a broken callback does not hurt the store. Callbacks run synchronously once that dispatch has changed the data and notified the store's subscribers. An exception thrown by a callback is caught and handed to reportError in the next macrotask (rethrown when there is none); it does not affect that dispatch or the other callbacks. Do not call dispatch from 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:

  1. On mount it calls inspectChatStore(store), so the store starts recording from then on; then it calls subscribe, 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.
  2. On redraw it reads getGlobal(): the conversation picker lists openConversations, the storage section reads storage; then it reads getConversation(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.
  3. When opened it calls estimateStorage() once; "Approximate size" shows the result.
  4. 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.