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

GenerationMiddleware.md

181 lines4.1 KB

1---
2id: GenerationMiddleware
3title: GenerationMiddleware
4---
5​
6# Interface: GenerationMiddleware\<TContext\>
7​
8Defined in: [packages/ai/src/activities/middleware/types.ts:145](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L145)
9​
10Activity-agnostic, observe-only middleware.
11​
12A thin lifecycle observer registerable on any activity via its `middleware`
13option. Unlike `ChatMiddleware` (which can also rewrite config, chunks, and
14tool calls), these hooks only observe — the right fit for the single
15request → response shape of media activities. Pass `otelMiddleware()` for
16OpenTelemetry, or implement the hooks directly for a custom backend.
17​
18Hooks are awaited in registration order. A hook that throws PROPAGATES and
19fails the activity — matching `chat()` middleware semantics. Keep them cheap;
20they run inline with the request.
21​
22Exactly one of `onFinish` / `onAbort` / `onError` fires per call.
23​
24## Example
25​
26```ts
27import { generateImage } from '@tanstack/ai'
28import { otelMiddleware } from '@tanstack/ai/middlewares/otel'
29import { openaiImage } from '@tanstack/ai-openai'
30import { trace } from '@opentelemetry/api'
31​
32await generateImage({
33 adapter: openaiImage('gpt-image-1'),
34 prompt: 'A serene mountain landscape at sunset',
35 middleware: [otelMiddleware({ tracer: trace.getTracer('my-app') })],
36})
37```
38​
39## Type Parameters
40​
41### TContext
42​
43`TContext` = `unknown`
44​
45## Properties
46​
47### name?
48​
49```ts
50optional name: string;
51```
52​
53Defined in: [packages/ai/src/activities/middleware/types.ts:147](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L147)
54​
55Optional name, surfaced in diagnostics.
56​
57***
58​
59### onAbort()?
60​
61```ts
62optional onAbort: (ctx, info) => void | Promise<void>;
63```
64​
65Defined in: [packages/ai/src/activities/middleware/types.ts:161](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L161)
66​
67Called when the activity is aborted (e.g. an abandoned stream).
68​
69#### Parameters
70​
71##### ctx
72​
73[`GenerationMiddlewareContext`](GenerationMiddlewareContext.md)\<`TContext`\>
74​
75##### info
76​
77[`GenerationAbortInfo`](GenerationAbortInfo.md)
78​
79#### Returns
80​
81`void` \| `Promise`\<`void`\>
82​
83***
84​
85### onError()?
86​
87```ts
88optional onError: (ctx, info) => void | Promise<void>;
89```
90​
91Defined in: [packages/ai/src/activities/middleware/types.ts:166](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L166)
92​
93Called when the activity throws before completing.
94​
95#### Parameters
96​
97##### ctx
98​
99[`GenerationMiddlewareContext`](GenerationMiddlewareContext.md)\<`TContext`\>
100​
101##### info
102​
103[`GenerationErrorInfo`](GenerationErrorInfo.md)
104​
105#### Returns
106​
107`void` \| `Promise`\<`void`\>
108​
109***
110​
111### onFinish()?
112​
113```ts
114optional onFinish: (ctx, info) => void | Promise<void>;
115```
116​
117Defined in: [packages/ai/src/activities/middleware/types.ts:156](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L156)
118​
119Called after the activity completes successfully.
120​
121#### Parameters
122​
123##### ctx
124​
125[`GenerationMiddlewareContext`](GenerationMiddlewareContext.md)\<`TContext`\>
126​
127##### info
128​
129[`GenerationFinishInfo`](GenerationFinishInfo.md)
130​
131#### Returns
132​
133`void` \| `Promise`\<`void`\>
134​
135***
136​
137### onStart()?
138​
139```ts
140optional onStart: (ctx) => void | Promise<void>;
141```
142​
143Defined in: [packages/ai/src/activities/middleware/types.ts:149](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L149)
144​
145Called before the adapter request begins.
146​
147#### Parameters
148​
149##### ctx
150​
151[`GenerationMiddlewareContext`](GenerationMiddlewareContext.md)\<`TContext`\>
152​
153#### Returns
154​
155`void` \| `Promise`\<`void`\>
156​
157***
158​
159### onUsage()?
160​
161```ts
162optional onUsage: (ctx, usage) => void | Promise<void>;
163```
164​
165Defined in: [packages/ai/src/activities/middleware/types.ts:151](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L151)
166​
167Called when the provider reports usage, before `onFinish`.
168​
169#### Parameters
170​
171##### ctx
172​
173[`GenerationMiddlewareContext`](GenerationMiddlewareContext.md)\<`TContext`\>
174​
175##### usage
176​
177[`GenerationUsageInfo`](GenerationUsageInfo.md)
178​
179#### Returns
180​
181`void` \| `Promise`\<`void`\>