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

devtools-noop.ts

212 lines7.2 KB

1// No-op devtools bridge implementations + factories. The chat / generation /
2// video clients import the real bridge classes as types only and accept a
3// factory in options; when no factory is supplied they fall back to the
4// no-op factories here, which never touch `aiEventClient` or any of the
5// heavy preview/fixture machinery in `./devtools`. This keeps `./devtools`
6// outside the main-entry import graph — consumers opt into functional
7// devtools via `@tanstack/ai-client/devtools` (see `package.json#exports`).
8import { ChatClientEventEmitter } from './events'
9import type {
10 AIDevtoolsToolFixture,
11 ChatDevtoolsBridge,
12 ChatDevtoolsBridgeOptions,
13 GenerationDevtoolsBridge,
14 GenerationDevtoolsBridgeOptions,
15 VideoDevtoolsBridge,
16 VideoDevtoolsBridgeOptions,
17} from './devtools'
18import type { StreamChunk } from '@tanstack/ai/client'
19import type {
20 ChatClientEventContext,
21 ChatClientRunEventContext,
22} from './events'
23​
24export type ChatDevtoolsBridgeFactory = (
25 options: ChatDevtoolsBridgeOptions,
26) => ChatDevtoolsBridge
27​
28export type GenerationDevtoolsBridgeFactory = <TOutput>(
29 options: GenerationDevtoolsBridgeOptions<TOutput>,
30) => GenerationDevtoolsBridge<TOutput>
31​
32export type VideoDevtoolsBridgeFactory = <TOutput>(
33 options: VideoDevtoolsBridgeOptions<TOutput>,
34) => VideoDevtoolsBridge<TOutput>
35​
36// ===========================================================================
37// No-op event emitter — extends the abstract base so it satisfies the type
38// without dragging in any of the event-bus runtime cost.
39// ===========================================================================
40​
41class NoOpChatClientEventEmitter extends ChatClientEventEmitter {
42 protected emitEvent(): void {
43 // intentionally empty
44 }
46​
47// ===========================================================================
48// No-op bridges. Methods exist to satisfy the structural shape of the real
49// classes; every emit/record call short-circuits.
50// ===========================================================================
51​
52export class NoOpChatDevtoolsBridge {
53 readonly events: ChatClientEventEmitter
54​
55 constructor(options: ChatDevtoolsBridgeOptions) {
56 this.events = new NoOpChatClientEventEmitter(options.clientId)
57 }
58​
59 // base bridge surface
60 emitRegistered(): void {}
61 emitUpdated(): void {}
62 emitSnapshot(): void {}
63 emitToolsRegistered(): void {}
64 emitRunLifecycle(
65 _eventType: unknown,
66 _runId: string,
67 _status: unknown,
68 _options?: { error?: string },
69 ): void {}
70 deactivate(): void {}
71 supersede(): void {}
72 dispose(): void {}
73​
74 // chat-specific surface
75 mountWithTools(_initialMessageCount: number): void {}
76 notifyToolsChanged(): void {}
77 setCurrentStreamId(_streamId: string | null): void {}
78 recordStreamId(_streamId: string): void {}
79 getCurrentStreamId(): string | null {
80 return null
81 }
82 getLastStreamId(): string | null {
83 return null
84 }
85 resolveStreamId(): string {
86 return ''
87 }
88 observeChunk(_chunk: StreamChunk): void {}
89 recordMemoryState(_value: unknown): void {}
90 beginRun(_runId: string, _threadId: string): void {}
91 getCurrentRunEventContext(): ChatClientRunEventContext | undefined {
92 return undefined
93 }
94 getCurrentOrLastRunEventContext(): ChatClientRunEventContext | undefined {
95 return undefined
96 }
97 findToolCallContext(toolCallId: string): ChatClientEventContext {
98 return { toolCallId }
99 }
100 async applyFixture(_fixture: AIDevtoolsToolFixture): Promise<void> {
101 // intentionally empty
102 }
104​
105export class NoOpGenerationDevtoolsBridge<TOutput> {
106 constructor(_options: GenerationDevtoolsBridgeOptions<TOutput>) {}
107​
108 // base bridge surface
109 emitRegistered(): void {}
110 emitUpdated(): void {}
111 emitSnapshot(): void {}
112 emitToolsRegistered(): void {}
113 emitRunLifecycle(): void {}
114 deactivate(): void {}
115 supersede(): void {}
116 dispose(): void {}
117​
118 // generation-specific surface
119 beginRun(_input: unknown): string {
120 // Real factories supply a stable id; the no-op still returns a
121 // unique value because the generation client passes this run id to
122 // the adapter's RunAgentInputContext.
123 return `noop-run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
124 }
125 ensureRunStarted(_runId: string): void {}
126 finishRun(
127 _runId: string,
128 _eventType: 'run:completed' | 'run:errored' | 'run:cancelled',
129 _status: 'completed' | 'errored' | 'cancelled',
130 _error?: string,
131 ): void {}
132 getActiveRunId(): string | null {
133 return null
134 }
135 resetRuns(): void {}
136 recordResultChange(): void {}
137 recordLoadingChange(): void {}
138 recordErrorChange(_error: Error | undefined): void {}
139 recordStatusChange(): void {}
140 recordProgressChange(): void {}
141 emitState(): void {}
143​
144export class NoOpVideoDevtoolsBridge<
145 TOutput,
146> extends NoOpGenerationDevtoolsBridge<TOutput> {
147 constructor(options: VideoDevtoolsBridgeOptions<TOutput>) {
148 super(options)
149 }
150​
151 recordJobIdChange(): void {}
152 recordVideoStatusChange(): void {}
154​
155// Compile-time parity checks. If a public method is added to the real
156// bridge class without a matching stub on the no-op, the corresponding
157// `Exclude<...>` resolves to a non-`never` union, which violates the
158// `extends never` constraint below and fails the build — surfacing the
159// drift at build time instead of as a runtime TypeError later.
160type AssertBridgeParity<TMissing extends never> = TMissing
161type _ChatBridgeMissing = Exclude<
162 keyof ChatDevtoolsBridge,
163 keyof NoOpChatDevtoolsBridge
165type _GenerationBridgeMissing = Exclude<
166 keyof GenerationDevtoolsBridge<unknown>,
167 keyof NoOpGenerationDevtoolsBridge<unknown>
169type _VideoBridgeMissing = Exclude<
170 keyof VideoDevtoolsBridge<unknown>,
171 keyof NoOpVideoDevtoolsBridge<unknown>
173const _bridgeParity:
174 | [
175 AssertBridgeParity<_ChatBridgeMissing>,
176 AssertBridgeParity<_GenerationBridgeMissing>,
177 AssertBridgeParity<_VideoBridgeMissing>,
178 ]
179 | undefined = undefined
180void _bridgeParity
181​
182// ===========================================================================
183// Factories — these are what the clients call when no real factory was
184// supplied in options.
185// ===========================================================================
186​
187// Casts use `unknown` because the no-op classes don't `extend` the real bridge
188// (that would pull the real implementation into the main-entry import graph).
189// Structural parity is enforced by the `_*BridgeMissing` checks above.
190​
191export const createNoOpChatDevtoolsBridge: ChatDevtoolsBridgeFactory = (
192 options,
193) =>
194 // oxlint-disable-next-line eslint-js/no-restricted-syntax -- see comment above
195 new NoOpChatDevtoolsBridge(options) as unknown as ChatDevtoolsBridge
196​
197export const createNoOpGenerationDevtoolsBridge: GenerationDevtoolsBridgeFactory =
198 <TOutput>(options: GenerationDevtoolsBridgeOptions<TOutput>) =>
199 // oxlint-disable-next-line eslint-js/no-restricted-syntax -- see comment above
200 new NoOpGenerationDevtoolsBridge<TOutput>(
201 options,
202 ) as unknown as GenerationDevtoolsBridge<TOutput>
203​
204export const createNoOpVideoDevtoolsBridge: VideoDevtoolsBridgeFactory = <
205 TOutput,
206>(
207 options: VideoDevtoolsBridgeOptions<TOutput>,
208) =>
209 // oxlint-disable-next-line eslint-js/no-restricted-syntax -- see comment above
210 new NoOpVideoDevtoolsBridge<TOutput>(
211 options,
212 ) as unknown as VideoDevtoolsBridge<TOutput>