Skip to content
Source
Sign inSign up
TanStack/ai
Open History to see the last commit

client-persistor.ts

406 lines13.1 KB

1import { getChunkRunId } from './connection-adapters'
2import type { StreamChunk } from '@tanstack/ai/client'
3import type {
4 ChatClientPersistence,
5 ChatPersistedState,
6 ChatResumeSnapshot,
7 UIMessage,
8} from './types'
9​
10/** Normalize a raw `getItem` result (legacy bare array or combined record). */
11function normalizePersistedState(
12 raw: ChatPersistedState | Array<UIMessage> | null | undefined,
13): ChatPersistedState | undefined {
14 if (Array.isArray(raw)) return { messages: raw }
15 if (raw && Array.isArray(raw.messages)) return raw
16 return undefined
18​
19// `StreamChunk` is a discriminated union; `toolCallId` / `messageId` /
20// `parentMessageId` exist on only some members. Narrow with `in` (matching
21// `getChunkRunId`) instead of asserting a shape, so the field's real type is
22// preserved and a protocol rename can't be read past silently.
23function getChunkToolCallId(chunk: StreamChunk): string | undefined {
24 return 'toolCallId' in chunk && typeof chunk.toolCallId === 'string'
25 ? chunk.toolCallId
26 : undefined
28​
29function getChunkMessageId(chunk: StreamChunk): string | undefined {
30 return 'messageId' in chunk && typeof chunk.messageId === 'string'
31 ? chunk.messageId
32 : undefined
34​
35function getChunkParentMessageId(chunk: StreamChunk): string | undefined {
36 return 'parentMessageId' in chunk && typeof chunk.parentMessageId === 'string'
37 ? chunk.parentMessageId
38 : undefined
40​
41/**
42 * Encapsulates everything persistence-related for `ChatClient` so the client
43 * itself stays focused on streaming and message state.
44 *
45 * Two responsibilities live here:
46 *
47 * 1. **Storage orchestration** — hydrate from `getItem(id)` on creation, save a
48 * combined `{ messages, resume? }` record via `setItem` on every change
49 * through an ordered write queue, and `removeItem(id)` on clear (or when
50 * both the transcript and resume pointer are empty). A generation counter
51 * discards stale writes when a removal or a newer conversation supersedes
52 * an in-flight async operation.
53 * 2. **Clear-during-stream suppression** — when a conversation is cleared while a
54 * stream is still producing, late chunks for the cleared run(s) must not
55 * repopulate the now-empty state. The persistor tracks the cleared ids and
56 * decides, per chunk, whether the client should ignore it.
57 *
58 * All adapter calls are best-effort: a throwing or rejecting adapter is swallowed
59 * so storage problems never break the chat.
60 */
61export class ChatPersistor {
62 // --- storage queue state ---
63 private skipNextPersist = false
64 private generation = 0
65 private queue: Promise<void> = Promise.resolve()
66 private queuePending = false
67 // Bumped on every message change; lets an in-flight async hydration detect
68 // that the message list moved on and avoid clobbering it.
69 private messagesGeneration = 0
70 // Latest messages + resume snapshot, written together as one combined record
71 // so a full page reload restores both from a single adapter key.
72 private lastMessages: Array<UIMessage> = []
73 private lastResume: ChatResumeSnapshot | null = null
74​
75 // --- clear-during-stream suppression state ---
76 private readonly clearedMessageIds = new Set<string>()
77 private readonly clearedRunIds = new Set<string>()
78 private readonly ignoredActiveRunIds = new Set<string>()
79 private readonly clearedToolCallIds = new Set<string>()
80 private currentRunlessRunId: string | null = null
81​
82 constructor(
83 private readonly adapter: ChatClientPersistence,
84 private readonly id: string,
85 private readonly applyMessages: (messages: Array<UIMessage>) => void,
86 private readonly applyResume?: (snapshot: ChatResumeSnapshot) => void,
87 ) {}
88​
89 /** Persist the current state as one combined `{ messages, resume? }` record. */
90 private writeState(): void {
91 const messages = [...this.lastMessages]
92 // Nothing to persist (no transcript, no resume pointer): remove the key
93 // rather than writing an empty `{ messages: [] }`, so a cleared
94 // conversation does not leave a stale record behind.
95 if (messages.length === 0 && !this.lastResume) {
96 const generation = this.generation
97 this.runOperation(() => {
98 if (generation !== this.generation) {
99 return
100 }
101 return this.adapter.removeItem(this.id)
102 })
103 return
104 }
105 const generation = this.generation
106 const state: ChatPersistedState = {
107 messages,
108 ...(this.lastResume ? { resume: this.lastResume } : {}),
109 }
110 this.runOperation(() => {
111 if (generation !== this.generation) {
112 return
113 }
114 return this.adapter.setItem(this.id, state)
115 })
116 }
117​
118 // ---------------------------------------------------------------------------
119 // Storage orchestration
120 // ---------------------------------------------------------------------------
121​
122 /**
123 * Synchronously read the persisted state for constructor-time hydration.
124 * Returns the normalized combined record, or a promise of it for async stores.
125 */
126 readInitial():
127 | ChatPersistedState
128 | undefined
129 | Promise<ChatPersistedState | undefined> {
130 try {
131 const raw = this.adapter.getItem(this.id)
132 if (raw instanceof Promise) {
133 return raw.then(normalizePersistedState).catch(() => undefined)
134 }
135 const state = normalizePersistedState(raw)
136 if (state) {
137 this.lastMessages = state.messages
138 this.lastResume = state.resume ?? null
139 }
140 return state
141 } catch {
142 return undefined
143 }
144 }
145​
146 /**
147 * Apply state from an async `getItem` once it resolves, unless the message
148 * list has already changed since hydration began.
149 */
150 hydrateAsync(
151 persistedState:
152 | ChatPersistedState
153 | undefined
154 | Promise<ChatPersistedState | undefined>,
155 ): void {
156 if (!(persistedState instanceof Promise)) {
157 return
158 }
159​
160 const hydrationGeneration = this.messagesGeneration
161 persistedState
162 .then((state) => {
163 if (!state || this.messagesGeneration !== hydrationGeneration) {
164 return
165 }
166 this.lastResume = state.resume ?? null
167 this.lastMessages = state.messages
168 this.applyMessages(state.messages)
169 if (state.resume && this.applyResume) {
170 this.applyResume(state.resume)
171 }
172 })
173 .catch(() => {
174 // Persistence adapters are best-effort and must not break chat setup.
175 })
176 }
177​
178 /**
179 * Record a message-list change and queue a combined write for it. Skips a
180 * single write after {@link beginClear} so the clear's empty snapshot isn't
181 * persisted between `clearMessages()` and {@link remove}.
182 */
183 notifyMessagesChanged(messages: Array<UIMessage>): void {
184 this.messagesGeneration++
185 this.lastMessages = [...messages]
186 if (this.skipNextPersist) {
187 this.skipNextPersist = false
188 return
189 }
190 this.writeState()
191 }
192​
193 /**
194 * Record the current resume snapshot (which run to rejoin / which interrupts
195 * are pending) and persist it alongside the messages. Pass `null` to clear it
196 * once the run reaches a non-interrupt terminal.
197 */
198 persistResumeSnapshot(snapshot: ChatResumeSnapshot | null): void {
199 this.lastResume = snapshot
200 if (this.skipNextPersist) {
201 return
202 }
203 this.writeState()
204 }
205​
206 /** Remove the persisted conversation. Invalidates any queued writes. */
207 remove(): void {
208 this.lastMessages = []
209 this.lastResume = null
210 const generation = ++this.generation
211 this.runOperation(() => {
212 if (generation !== this.generation) {
213 return
214 }
215 return this.adapter.removeItem(this.id)
216 })
217 }
218​
219 private runOperation(operation: () => void | Promise<void>): void {
220 if (this.queuePending) {
221 const queued = this.queue.then(operation).catch(() => {
222 // Persistence adapters are best-effort and must not break chat updates.
223 })
224 this.queue = queued
225 void queued.finally(() => {
226 if (this.queue === queued) {
227 this.queuePending = false
228 }
229 })
230 return
231 }
232​
233 try {
234 const result = operation()
235 if (result instanceof Promise) {
236 this.queuePending = true
237 const queued = result.catch(() => {
238 // Persistence adapters are best-effort and must not break chat updates.
239 })
240 this.queue = queued
241 void queued.finally(() => {
242 if (this.queue === queued) {
243 this.queuePending = false
244 }
245 })
246 }
247 } catch {
248 // Persistence adapters are best-effort and must not break chat updates.
249 }
250 }
251​
252 // ---------------------------------------------------------------------------
253 // Clear-during-stream suppression
254 // ---------------------------------------------------------------------------
255​
256 /**
257 * Capture the message/run ids that exist at the moment of a clear so chunks
258 * still arriving for them can be ignored.
259 */
260 snapshotClear(context: {
261 messages: Array<UIMessage>
262 activeRunIds: Set<string>
263 currentRunId: string | null
264 }): void {
265 for (const message of context.messages) {
266 this.clearedMessageIds.add(message.id)
267 }
268 for (const runId of context.activeRunIds) {
269 this.clearedRunIds.add(runId)
270 this.ignoredActiveRunIds.add(runId)
271 }
272 if (context.currentRunId) {
273 this.clearedRunIds.add(context.currentRunId)
274 this.ignoredActiveRunIds.add(context.currentRunId)
275 }
276 }
277​
278 /** Mark that the next persisted message change (the clear itself) is skipped. */
279 beginClear(): void {
280 this.skipNextPersist = true
281 }
282​
283 /** Whether a chunk belongs to cleared state and should not be processed. */
284 shouldIgnoreChunk(chunk: StreamChunk): boolean {
285 const runId = getChunkRunId(chunk)
286 if (runId && this.clearedRunIds.has(runId)) {
287 if (chunk.type === 'RUN_STARTED') {
288 this.ignoredActiveRunIds.add(runId)
289 this.currentRunlessRunId = runId
290 }
291 this.markIgnoredChunkIds(chunk)
292 return true
293 }
294​
295 if (runId && this.ignoredActiveRunIds.has(runId)) {
296 this.markIgnoredChunkIds(chunk)
297 return true
298 }
299​
300 if (this.isRunlessChunkFromIgnoredRun(chunk)) {
301 this.markIgnoredChunkIds(chunk)
302 return true
303 }
304​
305 const toolCallId = getChunkToolCallId(chunk)
306 if (toolCallId && this.clearedToolCallIds.has(toolCallId)) {
307 return true
308 }
309​
310 const parentMessageId = getChunkParentMessageId(chunk)
311 if (parentMessageId && this.clearedMessageIds.has(parentMessageId)) {
312 if (toolCallId) {
313 this.clearedToolCallIds.add(toolCallId)
314 }
315 return true
316 }
317​
318 const messageId = getChunkMessageId(chunk)
319 if (!messageId) {
320 return false
321 }
322 if (this.clearedMessageIds.has(messageId)) {
323 return true
324 }
325​
326 return false
327 }
328​
329 /**
330 * The owning client calls this when a run starts so runless content chunks
331 * (adapters that omit `runId` on content events) can be attributed to it.
332 */
333 onRunStarted(runId: string): void {
334 this.currentRunlessRunId = runId
335 }
336​
337 /** Forget a settled run, advancing the runless pointer to another ignored run. */
338 onRunSettled(runId: string): void {
339 this.ignoredActiveRunIds.delete(runId)
340 this.clearedRunIds.delete(runId)
341 if (this.currentRunlessRunId === runId) {
342 this.currentRunlessRunId =
343 this.ignoredActiveRunIds.values().next().value ?? null
344 }
345 }
346​
347 /** A session-level (runId-less) RUN_ERROR clears all ignored-run tracking. */
348 onSessionRunError(): void {
349 this.ignoredActiveRunIds.clear()
350 this.currentRunlessRunId = null
351 }
352​
353 /** Clear the ignored-active-run markers (mirrors a session-generating reset). */
354 resetIgnored(): void {
355 this.ignoredActiveRunIds.clear()
356 }
357​
358 /**
359 * Consume the current runless run id (if any), forgetting it. Used when an
360 * ignored, runId-less RUN_ERROR drains the run the client is still tracking.
361 */
362 takeRunlessRunId(): string | null {
363 const runId = this.currentRunlessRunId
364 if (!runId) return null
365 this.ignoredActiveRunIds.delete(runId)
366 this.clearedRunIds.delete(runId)
367 // Advance to another still-ignored run (mirroring `onRunSettled`) so that
368 // when two cleared runs drain concurrently, draining one via a runId-less
369 // RUN_ERROR doesn't stop suppressing the other's runless content.
370 this.currentRunlessRunId =
371 this.ignoredActiveRunIds.values().next().value ?? null
372 return runId
373 }
374​
375 private markIgnoredChunkIds(chunk: StreamChunk): void {
376 const messageId = getChunkMessageId(chunk)
377 if (messageId) {
378 this.clearedMessageIds.add(messageId)
379 }
380 const toolCallId = getChunkToolCallId(chunk)
381 if (toolCallId) {
382 this.clearedToolCallIds.add(toolCallId)
383 }
384 }
385​
386 private isRunlessChunkFromIgnoredRun(chunk: StreamChunk): boolean {
387 const runId = getChunkRunId(chunk)
388 if (runId || !this.currentRunlessRunId) return false
389 if (
390 !this.ignoredActiveRunIds.has(this.currentRunlessRunId) &&
391 !this.clearedRunIds.has(this.currentRunlessRunId)
392 ) {
393 return false
394 }
395 return (
396 chunk.type === 'TEXT_MESSAGE_START' ||
397 chunk.type === 'TEXT_MESSAGE_CONTENT' ||
398 chunk.type === 'TOOL_CALL_START' ||
399 chunk.type === 'TOOL_CALL_ARGS' ||
400 chunk.type === 'TOOL_CALL_END' ||
401 chunk.type === 'TOOL_CALL_RESULT' ||
402 chunk.type === 'MESSAGES_SNAPSHOT' ||
403 chunk.type === 'RUN_ERROR'
404 )
405 }