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

type-narrowing-test.ts

323 lines10.1 KB

1/**
2 * Type Narrowing Test for Unified Chat API
3 *
4 * This file demonstrates how TypeScript correctly narrows the return type
5 * based on the "as" parameter value.
6 */
7
8import { AI } from "@ts-poc/ai";
9import { OpenAIAdapter } from "@ts-poc/ai-openai";
10import { OllamaAdapter } from "@ts-poc/ai-ollama";
12const ai = new AI({
13 adapters: {
14 openai: new OpenAIAdapter({
15 apiKey: process.env.OPENAI_API_KEY || "",
16 }),
17 ollama: new OllamaAdapter({
18 baseURL: "http://localhost:11434",
19 }),
20 },
21});
23const messages = [{ role: "user" as const, content: "Hello" }];
25// ============================================================================
26// TEST 1: Default (no "as" specified) - Should be Promise<ChatCompletionResult>
27// ============================================================================
28async function testDefault() {
29 const result = ai.chat({
30 adapter: "openai",
31 model: "gpt-4",
32 messages,
33 });
35 // Type check: result should be Promise<ChatCompletionResult>
36 // We can await it
37 const resolved = await result;
39 // These properties should exist on ChatCompletionResult
40 console.log(resolved.content); // ✅ Should work
41 console.log(resolved.role); // ✅ Should work
42 console.log(resolved.usage); // ✅ Should work
44 // @ts-expect-error - body doesn't exist on ChatCompletionResult
45 console.log(resolved.body); // ❌ Should error
47 // @ts-expect-error - headers doesn't exist on ChatCompletionResult
48 console.log(resolved.headers); // ❌ Should error
49}
51// ============================================================================
52// TEST 2: as: "promise" - Should be Promise<ChatCompletionResult>
53// ============================================================================
54async function testPromise() {
55 const result = ai.chat({
56 adapter: "openai",
57 model: "gpt-4",
58 messages,
59 as: "promise",
60 });
62 // Type check: result should be Promise<ChatCompletionResult>
63 const resolved = await result;
65 console.log(resolved.content); // ✅ Should work
66 console.log(resolved.role); // ✅ Should work
67 console.log(resolved.usage); // ✅ Should work
69 // @ts-expect-error - body doesn't exist on ChatCompletionResult
70 console.log(resolved.body); // ❌ Should error
71}
73// ============================================================================
74// TEST 3: as: "stream" - Should be AsyncIterable<StreamChunk>
75// ============================================================================
76async function testStream() {
77 const result = ai.chat({
78 adapter: "openai",
79 model: "gpt-4",
80 messages,
81 as: "stream",
82 });
84 // Type check: result should be AsyncIterable<StreamChunk>
85 // We can use for await...of
86 for await (const chunk of result) { // ✅ Should work
87 console.log(chunk.type); // ✅ Should work
88 console.log(chunk.id); // ✅ Should work
89 console.log(chunk.model); // ✅ Should work
90 }
92 // @ts-expect-error - await result directly doesn't make sense for AsyncIterable
93 // const resolved = await result; // ❌ Should error (or be any)
95 // @ts-expect-error - content doesn't exist on AsyncIterable
96 console.log(result.content); // ❌ Should error
98 // @ts-expect-error - headers doesn't exist on AsyncIterable
99 console.log(result.headers); // ❌ Should error
100}
102// ============================================================================
103// TEST 4: as: "response" - Should be Response
104// ============================================================================
105function testResponse() {
106 const result = ai.chat({
107 adapter: "openai",
108 model: "gpt-4",
109 messages,
110 as: "response",
111 });
113 // Type check: result should be Response
114 console.log(result.headers); // ✅ Should work
115 console.log(result.body); // ✅ Should work
116 console.log(result.status); // ✅ Should work
117 console.log(result.ok); // ✅ Should work
119 // Can call Response methods
120 const contentType = result.headers.get("Content-Type"); // ✅ Should work
122 // @ts-expect-error - content doesn't exist on Response
123 console.log(result.content); // ❌ Should error
125 // @ts-expect-error - role doesn't exist on Response
126 console.log(result.role); // ❌ Should error
128 // @ts-expect-error - usage doesn't exist on Response
129 console.log(result.usage); // ❌ Should error
130}
132// ============================================================================
133// TEST 5: Type narrowing with const - Should infer correctly
134// ============================================================================
135async function testConstNarrowing() {
136 // When using const, TypeScript narrows to the literal type
137 const mode = "stream" as const;
139 const result = ai.chat({
140 adapter: "openai",
141 model: "gpt-4",
142 messages,
143 as: mode, // TypeScript knows this is "stream"
144 });
146 // Should be typed as AsyncIterable<StreamChunk>
147 for await (const chunk of result) {
148 console.log(chunk.type);
149 }
150}
152// ============================================================================
153// TEST 6: Dynamic mode - Should be union type
154// ============================================================================
155async function testDynamicMode(mode: "promise" | "stream" | "response") {
156 const result = ai.chat({
157 adapter: "openai",
158 model: "gpt-4",
159 messages,
160 as: mode,
161 });
163 // Type should be: Promise<ChatCompletionResult> | AsyncIterable<StreamChunk> | Response
164 // This is correct since we don't know which mode at compile time
166 // Type guard needed to narrow
167 if (mode === "promise") {
168 // result is Promise<ChatCompletionResult>
169 const resolved = await result;
170 console.log(resolved.content);
171 } else if (mode === "stream") {
172 // result is AsyncIterable<StreamChunk>
173 for await (const chunk of result as AsyncIterable<any>) {
174 console.log(chunk.type);
175 }
176 } else {
177 // result is Response
178 console.log((result as Response).headers);
179 }
180}
182// ============================================================================
183// TEST 7: With fallbacks - Type narrowing should still work
184// ============================================================================
185async function testWithFallbacks() {
186 // Promise mode with fallbacks
187 const promise = ai.chat({
188 adapter: "openai",
189 model: "gpt-4",
190 messages,
191 as: "promise",
192 fallbacks: [
193 { adapter: "ollama", model: "llama2" }
194 ]
195 });
196 const resolved = await promise;
197 console.log(resolved.content); // ✅ Works
199 // Stream mode with fallbacks
200 const stream = ai.chat({
201 adapter: "openai",
202 model: "gpt-4",
203 messages,
204 as: "stream",
205 fallbacks: [
206 { adapter: "ollama", model: "llama2" }
207 ]
208 });
209 for await (const chunk of stream) {
210 console.log(chunk.type); // ✅ Works
211 }
213 // Response mode with fallbacks
214 const response = ai.chat({
215 adapter: "openai",
216 model: "gpt-4",
217 messages,
218 as: "response",
219 fallbacks: [
220 { adapter: "ollama", model: "llama2" }
221 ]
222 });
223 console.log(response.headers); // ✅ Works
224}
226// ============================================================================
227// TEST 8: Fallback-only mode - Type narrowing should still work
228// ============================================================================
229async function testFallbackOnly() {
230 // Promise mode (default)
231 const promise = ai.chat({
232 messages,
233 fallbacks: [
234 { adapter: "openai", model: "gpt-4" },
235 { adapter: "ollama", model: "llama2" }
236 ]
237 });
238 const resolved = await promise;
239 console.log(resolved.content); // ✅ Works
241 // Stream mode
242 const stream = ai.chat({
243 messages,
244 as: "stream",
245 fallbacks: [
246 { adapter: "openai", model: "gpt-4" },
247 { adapter: "ollama", model: "llama2" }
248 ]
249 });
250 for await (const chunk of stream) {
251 console.log(chunk.type); // ✅ Works
252 }
254 // Response mode
255 const response = ai.chat({
256 messages,
257 as: "response",
258 fallbacks: [
259 { adapter: "openai", model: "gpt-4" },
260 { adapter: "ollama", model: "llama2" }
261 ]
262 });
263 console.log(response.headers); // ✅ Works
264}
266// ============================================================================
267// TEST 9: Return types in API handlers
268// ============================================================================
270// This simulates a TanStack Start API route
271function apiHandler1() {
272 // Return type is inferred as Response
273 return ai.chat({
274 adapter: "openai",
275 model: "gpt-4",
276 messages,
277 as: "response",
278 });
279 // TypeScript knows this function returns Response ✅
280}
282// This would be an error if we tried to return wrong type
283function apiHandler2(): Response {
284 return ai.chat({
285 adapter: "openai",
286 model: "gpt-4",
287 messages,
288 as: "response", // ✅ Correct
289 });
290}
292// This would cause a type error
293function apiHandler3(): Response {
294 // @ts-expect-error - Returns Promise<ChatCompletionResult>, not Response
295 return ai.chat({
296 adapter: "openai",
297 model: "gpt-4",
298 messages,
299 as: "promise", // ❌ Wrong type
300 });
301}
303// ============================================================================
304// Summary
305// ============================================================================
307console.log(`
308Type Narrowing Test Summary:
309============================
311✅ Default (no "as") → Promise<ChatCompletionResult>
312✅ as: "promise" → Promise<ChatCompletionResult>
313✅ as: "stream" → AsyncIterable<StreamChunk>
314✅ as: "response" → Response
316✅ Type narrowing works with fallbacks
317✅ Type narrowing works in fallback-only mode
318✅ Return types are correctly inferred in functions
319✅ TypeScript catches type mismatches at compile time
321This demonstrates that the unified chat API provides
322perfect type safety based on the "as" parameter!
323`);