From 9224456213a7f493ccf88eb011099adf5bde77c9 Mon Sep 17 00:00:00 2001 From: Jack Herrington Date: Fri, 20 Nov 2026 18:45:55 -0800 Subject: [PATCH] refactor: use createServerFn().validator() over deprecated inputValidator() TanStack Start deprecated the `inputValidator` server-fn builder method in favor of `validator` (identical signature). Rename every call site and doc reference across the example apps, the e2e harness, and the JSDoc/skill code samples, so the repo stops teaching the deprecated form. Co-Authored-By: Claude Opus 4.8 (1M context) --- .changeset/validator-jsdoc-rename.md | 6 ++++ docs/media/generations.md | 4 +-- docs/media/transcription-advanced.md | 4 +-- docs/media/video-generation-advanced.md | 4 +-- docs/persistence/generation-persistence.md | 6 ++-- docs/reference/functions/replayRunStream.md | 2 +- docs/transports/server-functions.md | 2 +- .../evaluate/src/lib/server-functions.ts | 2 +- examples/ts-react-chat/src/lib/server-fns.ts | 28 +++++++++---------- .../ts-react-chat/src/lib/use-realtime.ts | 2 +- .../src/lib/server-functions.ts | 12 ++++---- .../src/lib/server-functions.ts | 2 +- .../src/reconstruct-generation.ts | 2 +- .../skills/ai-core/media-generation/SKILL.md | 6 ++-- packages/ai/src/stream-durability.ts | 2 +- testing/e2e/src/lib/server-functions.ts | 10 +++---- 16 files changed, 50 insertions(+), 44 deletions(-) create mode 100644 .changeset/validator-jsdoc-rename.md diff --git a/.changeset/validator-jsdoc-rename.md b/.changeset/validator-jsdoc-rename.md new file mode 100644 index 0000000000..188bb8348c --- /dev/null +++ b/.changeset/validator-jsdoc-rename.md @@ -0,0 +1,6 @@ +--- +'@tanstack/ai': patch +'@tanstack/ai-persistence': patch +--- + +docs: use the non-deprecated `createServerFn().validator()` API in JSDoc examples (was the deprecated `.inputValidator()`) diff --git a/docs/media/generations.md b/docs/media/generations.md index 852857196c..453172f369 100644 --- a/docs/media/generations.md +++ b/docs/media/generations.md @@ -162,7 +162,7 @@ import { generateImage } from '@tanstack/ai' import { openaiImage } from '@tanstack/ai-openai' export const generateImageFn = createServerFn({ method: 'POST' }) - .inputValidator((data: { prompt: string; threadId: string }) => data) + .validator((data: { prompt: string; threadId: string }) => data) .handler(async ({ data }) => { return generateImage({ adapter: openaiImage('gpt-image-2.5-flare'), @@ -202,7 +202,7 @@ import { generateImage, toServerSentEventsResponse } from '@tanstack/ai' import { openaiImage } from '@tanstack/ai-openai' export const generateImageStreamFn = createServerFn({ method: 'POST' }) - .inputValidator((data: { prompt: string; threadId: string }) => data) + .validator((data: { prompt: string; threadId: string }) => data) .handler(({ data }) => { return toServerSentEventsResponse( generateImage({ diff --git a/docs/media/transcription-advanced.md b/docs/media/transcription-advanced.md index 03f1014676..c7bf1b4f8f 100644 --- a/docs/media/transcription-advanced.md +++ b/docs/media/transcription-advanced.md @@ -128,7 +128,7 @@ import { generateTranscription } from '@tanstack/ai' import { openaiTranscription } from '@tanstack/ai-openai' export const transcribeFn = createServerFn({ method: 'POST' }) - .inputValidator( + .validator( (data: { audio: string; language?: string; threadId: string }) => data, ) .handler(async ({ data }) => { @@ -166,7 +166,7 @@ import { generateTranscription, toServerSentEventsResponse } from '@tanstack/ai' import { openaiTranscription } from '@tanstack/ai-openai' export const transcribeStreamFn = createServerFn({ method: 'POST' }) - .inputValidator( + .validator( (data: { audio: string; language?: string; threadId: string }) => data, ) .handler(({ data }) => { diff --git a/docs/media/video-generation-advanced.md b/docs/media/video-generation-advanced.md index 64edfc5174..f87505e921 100644 --- a/docs/media/video-generation-advanced.md +++ b/docs/media/video-generation-advanced.md @@ -92,7 +92,7 @@ import { generateVideo, getVideoJobStatus } from '@tanstack/ai' import { openaiVideo } from '@tanstack/ai-openai' export const generateVideoFn = createServerFn({ method: 'POST' }) - .inputValidator((data: { prompt: string; threadId: string }) => data) + .validator((data: { prompt: string; threadId: string }) => data) .handler(async ({ data }) => { const adapter = openaiVideo('sora-2') const { threadId } = data @@ -141,7 +141,7 @@ import { generateVideo, toServerSentEventsResponse } from '@tanstack/ai' import { openaiVideo } from '@tanstack/ai-openai' export const generateVideoStreamFn = createServerFn({ method: 'POST' }) - .inputValidator((data: { prompt: string; threadId: string }) => data) + .validator((data: { prompt: string; threadId: string }) => data) .handler(({ data }) => { return toServerSentEventsResponse( generateVideo({ diff --git a/docs/persistence/generation-persistence.md b/docs/persistence/generation-persistence.md index acc0a9d8a6..8184bc857b 100644 --- a/docs/persistence/generation-persistence.md +++ b/docs/persistence/generation-persistence.md @@ -247,7 +247,7 @@ import type { ImageGenerateInput } from '@tanstack/ai-client' const persistence = memoryPersistence() export const generateImageFn = createServerFn({ method: 'POST' }) - .inputValidator((data: ImageGenerateInput & { threadId: string }) => data) + .validator((data: ImageGenerateInput & { threadId: string }) => data) .handler(({ data: { threadId, ...input } }) => { if (typeof input.prompt !== 'string') { throw new Error('This endpoint accepts text image prompts only.') @@ -299,7 +299,7 @@ const hydrationSchema = z.object({ }) export const getImageHydrationFn = createServerFn({ method: 'GET' }) - .inputValidator(z.string().min(1)) + .validator(z.string().min(1)) .handler(async ({ data: threadId }) => { // `getGenerationHydration` does no auth. Check the session here, the // way you pass `authorize` to `reconstructGeneration`. @@ -309,7 +309,7 @@ export const getImageHydrationFn = createServerFn({ method: 'GET' }) }) export const joinImageRunFn = createServerFn({ method: 'GET' }) - .inputValidator(z.string().min(1)) + .validator(z.string().min(1)) .handler(({ data: runId }) => // The same SSE envelope that `generateImageFn` returns, so one client-side // decoder covers both. diff --git a/docs/reference/functions/replayRunStream.md b/docs/reference/functions/replayRunStream.md index 608aad95d2..9fe240920a 100644 --- a/docs/reference/functions/replayRunStream.md +++ b/docs/reference/functions/replayRunStream.md @@ -25,7 +25,7 @@ async function* joinImageRun({ data: runId }: { data: string }) { } // Serve it from a server function whose handler is the generator above -// (`createServerFn({ method: 'GET' }).inputValidator(...)`). +// (`createServerFn({ method: 'GET' }).validator(...)`). ``` NOTE: the example deliberately declares the generator separately instead of diff --git a/docs/transports/server-functions.md b/docs/transports/server-functions.md index 5bb006b4ce..c3e4cf1d31 100644 --- a/docs/transports/server-functions.md +++ b/docs/transports/server-functions.md @@ -40,7 +40,7 @@ import { openaiText } from "@tanstack/ai-openai"; import type { UIMessage } from "@tanstack/ai"; export const chatFn = createServerFn({ method: "POST" }) - .inputValidator((data: { messages: Array; threadId: string }) => data) + .validator((data: { messages: Array; threadId: string }) => data) .handler(({ data }) => toServerSentEventsResponse( chat({ diff --git a/examples/react/evaluate/src/lib/server-functions.ts b/examples/react/evaluate/src/lib/server-functions.ts index dc34e29055..a14f6eb51f 100644 --- a/examples/react/evaluate/src/lib/server-functions.ts +++ b/examples/react/evaluate/src/lib/server-functions.ts @@ -47,7 +47,7 @@ export type TicketEvaluateResult = EvaluateResult * each call site keeps the adapter's literal model type. */ export const evaluateTicketFn = createServerFn({ method: 'POST' }) - .inputValidator((data: EvaluateInput) => { + .validator((data: EvaluateInput) => { if (!data.ticket.trim()) throw new Error('Ticket text is required') if (!isProvider(data.provider)) { throw new Error(`Unknown provider: ${data.provider}`) diff --git a/examples/ts-react-chat/src/lib/server-fns.ts b/examples/ts-react-chat/src/lib/server-fns.ts index cab66771bf..d7855934f8 100644 --- a/examples/ts-react-chat/src/lib/server-fns.ts +++ b/examples/ts-react-chat/src/lib/server-fns.ts @@ -129,7 +129,7 @@ function imagePersistenceMiddleware() { // ============================================================================= export const generateImageFn = createServerFn({ method: 'POST' }) - .inputValidator(imageGenerateInputSchema) + .validator(imageGenerateInputSchema) .handler(async ({ data }) => { return generateImage({ adapter: grokImage('grok-imagine-image'), @@ -142,7 +142,7 @@ export const generateImageFn = createServerFn({ method: 'POST' }) }) export const generateSpeechFn = createServerFn({ method: 'POST' }) - .inputValidator( + .validator( z.object({ threadId: z.string().min(1), text: z.string(), @@ -171,7 +171,7 @@ export const generateSpeechFn = createServerFn({ method: 'POST' }) }) export const transcribeFn = createServerFn({ method: 'POST' }) - .inputValidator( + .validator( z.object({ threadId: z.string().min(1), audio: z.string(), @@ -203,7 +203,7 @@ export const transcribeFn = createServerFn({ method: 'POST' }) }) export const generateAudioFn = createServerFn({ method: 'POST' }) - .inputValidator( + .validator( z.object({ threadId: z.string().min(1), prompt: z.string(), @@ -232,7 +232,7 @@ export const generateAudioFn = createServerFn({ method: 'POST' }) }) export const summarizeFn = createServerFn({ method: 'POST' }) - .inputValidator( + .validator( z.object({ threadId: z.string().min(1), text: z.string(), @@ -252,7 +252,7 @@ export const summarizeFn = createServerFn({ method: 'POST' }) }) export const generateVideoFn = createServerFn({ method: 'POST' }) - .inputValidator( + .validator( z.object({ threadId: z.string().min(1), prompt: z.string(), @@ -305,7 +305,7 @@ export const generateVideoFn = createServerFn({ method: 'POST' }) // ============================================================================= export const generateImageStreamFn = createServerFn({ method: 'POST' }) - .inputValidator(imageGenerateInputSchema) + .validator(imageGenerateInputSchema) .handler(({ data }) => { // One run id for the durability log and the run record so join can replay // exactly the run hydration reports. @@ -357,7 +357,7 @@ const generationHydrationSchema = z.object({ /** Mount hydration for image `persistence: true` over a fetcher (no GET route). */ export const getImageHydrationFn = createServerFn({ method: 'GET' }) - .inputValidator(z.string().min(1)) + .validator(z.string().min(1)) .handler(async ({ data: threadId }) => { // No auth in this single-user demo — gate on session in a multi-user app. return generationHydrationSchema.parse( @@ -371,13 +371,13 @@ export const getImageHydrationFn = createServerFn({ method: 'GET' }) * `generateImageStreamFn` does (see `chunksFromSseResponse` on the page). */ export const joinImageRunFn = createServerFn({ method: 'GET' }) - .inputValidator(z.string().min(1)) + .validator(z.string().min(1)) .handler(({ data: runId }) => toServerSentEventsResponse(replayRunStream(memoryStream({ runId }))), ) export const generateSpeechStreamFn = createServerFn({ method: 'POST' }) - .inputValidator( + .validator( z.object({ threadId: z.string().min(1), text: z.string(), @@ -409,7 +409,7 @@ export const generateSpeechStreamFn = createServerFn({ method: 'POST' }) }) export const transcribeStreamFn = createServerFn({ method: 'POST' }) - .inputValidator( + .validator( z.object({ threadId: z.string().min(1), audio: z.string(), @@ -444,7 +444,7 @@ export const transcribeStreamFn = createServerFn({ method: 'POST' }) }) export const summarizeStreamFn = createServerFn({ method: 'POST' }) - .inputValidator( + .validator( z.object({ threadId: z.string().min(1), text: z.string(), @@ -469,7 +469,7 @@ export const summarizeStreamFn = createServerFn({ method: 'POST' }) }) export const generateVideoStreamFn = createServerFn({ method: 'POST' }) - .inputValidator( + .validator( z.object({ threadId: z.string().min(1), prompt: z.string(), @@ -495,7 +495,7 @@ export const generateVideoStreamFn = createServerFn({ method: 'POST' }) // ============================================================================= export const chatFn = createServerFn({ method: 'POST' }) - .inputValidator( + .validator( (data: { messages: Array threadId: string diff --git a/examples/ts-react-chat/src/lib/use-realtime.ts b/examples/ts-react-chat/src/lib/use-realtime.ts index 1441c7aa3d..19e842a1cf 100644 --- a/examples/ts-react-chat/src/lib/use-realtime.ts +++ b/examples/ts-react-chat/src/lib/use-realtime.ts @@ -13,7 +13,7 @@ import { realtimeClientTools } from '@/lib/realtime-tools' type Provider = 'openai' | 'elevenlabs' | 'gemini' | 'grok' const getRealtimeTokenFn = createServerFn({ method: 'POST' }) - .inputValidator((data: { provider: Provider; language?: string }) => { + .validator((data: { provider: Provider; language?: string }) => { if (!data.provider) throw new Error('Provider is required') return data }) diff --git a/examples/ts-react-media/src/lib/server-functions.ts b/examples/ts-react-media/src/lib/server-functions.ts index 06121d0e96..7d78b52871 100644 --- a/examples/ts-react-media/src/lib/server-functions.ts +++ b/examples/ts-react-media/src/lib/server-functions.ts @@ -271,7 +271,7 @@ function isWorldResolution(value: string): value is WorldResolution { } export const generateImageFn = createServerFn({ method: 'POST' }) - .inputValidator((data: { prompt: MediaPrompt; model: string }) => { + .validator((data: { prompt: MediaPrompt; model: string }) => { if (!hasPromptContent(data.prompt)) throw new Error('Prompt is required') if (!data.model) throw new Error('Model is required') return data @@ -701,7 +701,7 @@ async function videoStreamForModel( * through the UI. */ export const generateVideoFn = createServerFn({ method: 'POST' }) - .inputValidator((data: VideoRequest) => { + .validator((data: VideoRequest) => { if (!hasPromptContent(data.prompt)) throw new Error('Prompt is required') if (!data.model) throw new Error('Model is required') return data @@ -736,7 +736,7 @@ interface Model3DRequest { * the one request, so the browser runs no polling loop. */ export const generate3DModelFn = createServerFn({ method: 'POST' }) - .inputValidator((data: Model3DRequest) => { + .validator((data: Model3DRequest) => { if (!hasPromptContent(data.prompt)) throw new Error('Prompt is required') if (!isModel3DModelId(data.model)) { throw new Error(`Unknown 3D model: ${data.model}`) @@ -938,7 +938,7 @@ function seedanceStream(data: SeedanceRequest): AsyncIterable { * to poll with — the server does the waiting and reports status on the wire. */ export const generateSeedanceVideoFn = createServerFn({ method: 'POST' }) - .inputValidator((data: SeedanceRequest) => { + .validator((data: SeedanceRequest) => { if (!hasPromptContent(data.prompt)) throw new Error('Prompt is required') if (!data.model) throw new Error('Model is required') return data @@ -956,7 +956,7 @@ interface LiveVideoRequest { * client (`@reactor-team/js-sdk` or `@fal-ai/client`). There is no job URL. */ export const generateLiveVideoFn = createServerFn({ method: 'POST' }) - .inputValidator((data: LiveVideoRequest) => { + .validator((data: LiveVideoRequest) => { if (typeof data.prompt !== 'string' || data.prompt.trim().length === 0) { throw new Error('Prompt is required') } @@ -1032,7 +1032,7 @@ const WORLDLABS_TIMEOUT_MS = 12 * 60 * 1000 * and waits until the Marble world is ready (about 5 minutes). */ export const generateWorldFn = createServerFn({ method: 'POST' }) - .inputValidator((data: WorldRequest) => { + .validator((data: WorldRequest) => { if (typeof data.prompt !== 'string' || data.prompt.trim().length === 0) { throw new Error('Prompt is required') } diff --git a/examples/ts-react-rerank/src/lib/server-functions.ts b/examples/ts-react-rerank/src/lib/server-functions.ts index 3df9035e9d..de501683c8 100644 --- a/examples/ts-react-rerank/src/lib/server-functions.ts +++ b/examples/ts-react-rerank/src/lib/server-functions.ts @@ -36,7 +36,7 @@ function isCohereRerankModel(model: string): model is CohereRerankModel { * inference. */ export const rerankDocumentsFn = createServerFn({ method: 'POST' }) - .inputValidator((data: RerankInput) => { + .validator((data: RerankInput) => { if (!data.query.trim()) throw new Error('Query is required') if (!isProvider(data.provider)) { throw new Error(`Unknown provider: ${data.provider}`) diff --git a/packages/ai-persistence/src/reconstruct-generation.ts b/packages/ai-persistence/src/reconstruct-generation.ts index f202bf412d..b19acd1ae7 100644 --- a/packages/ai-persistence/src/reconstruct-generation.ts +++ b/packages/ai-persistence/src/reconstruct-generation.ts @@ -126,7 +126,7 @@ export interface GetGenerationHydrationOptions { * ``` * * Wire that body up as the server function's handler — build it with - * `createServerFn({ method: 'GET' })`, add an `inputValidator` that returns + * `createServerFn({ method: 'GET' })`, add a `validator` that returns * the thread id, then hand it the function above. (The chained call is shown * split apart on purpose: Start's server-fn plugin decides which modules to * transform by scanning source text for that call, and a package whose shipped diff --git a/packages/ai/skills/ai-core/media-generation/SKILL.md b/packages/ai/skills/ai-core/media-generation/SKILL.md index 598d1a1501..742232ad22 100644 --- a/packages/ai/skills/ai-core/media-generation/SKILL.md +++ b/packages/ai/skills/ai-core/media-generation/SKILL.md @@ -132,7 +132,7 @@ import { openaiImage } from '@tanstack/ai-openai' import type { OpenAIImageModel } from '@tanstack/ai-openai' export const generateImageStreamFn = createServerFn({ method: 'POST' }) - .inputValidator( + .validator( (data: { prompt: string; model?: OpenAIImageModel; threadId: string }) => data, ) @@ -1120,7 +1120,7 @@ import { generateImage } from '@tanstack/ai' import { openaiImage } from '@tanstack/ai-openai' export const generateImageStreamFn = createServerFn({ method: 'POST' }) - .inputValidator((data: { prompt: string }) => data) + .validator((data: { prompt: string }) => data) .handler(({ data }) => { // BUG: returning raw stream -- client cannot parse this // (also a type error: an AsyncIterable is not a valid server-function return) @@ -1141,7 +1141,7 @@ import { generateImage, toServerSentEventsResponse } from '@tanstack/ai' import { openaiImage } from '@tanstack/ai-openai' export const generateImageStreamFn = createServerFn({ method: 'POST' }) - .inputValidator((data: { prompt: string }) => data) + .validator((data: { prompt: string }) => data) .handler(({ data }) => { return toServerSentEventsResponse( generateImage({ diff --git a/packages/ai/src/stream-durability.ts b/packages/ai/src/stream-durability.ts index 5fa2b4cc9d..f8e7723321 100644 --- a/packages/ai/src/stream-durability.ts +++ b/packages/ai/src/stream-durability.ts @@ -570,7 +570,7 @@ export function memoryStream( * } * * // Serve it from a server function whose handler is the generator above - * // (`createServerFn({ method: 'GET' }).inputValidator(...)`). + * // (`createServerFn({ method: 'GET' }).validator(...)`). * ``` * * NOTE: the example deliberately declares the generator separately instead of diff --git a/testing/e2e/src/lib/server-functions.ts b/testing/e2e/src/lib/server-functions.ts index 6f99b371e9..6543669582 100644 --- a/testing/e2e/src/lib/server-functions.ts +++ b/testing/e2e/src/lib/server-functions.ts @@ -22,7 +22,7 @@ import { } from '@/lib/media-providers' export const generateImageFn = createServerFn({ method: 'POST' }) - .inputValidator( + .validator( (data: { prompt: MediaPrompt provider: Provider @@ -55,7 +55,7 @@ export const generateImageFn = createServerFn({ method: 'POST' }) }) export const generateSpeechFn = createServerFn({ method: 'POST' }) - .inputValidator( + .validator( (data: { text?: string turns?: Array @@ -98,7 +98,7 @@ export const generateSpeechFn = createServerFn({ method: 'POST' }) }) export const generateTranscriptionFn = createServerFn({ method: 'POST' }) - .inputValidator( + .validator( (data: { audio: string language?: string @@ -136,7 +136,7 @@ export const generateTranscriptionFn = createServerFn({ method: 'POST' }) }) export const generateAudioFn = createServerFn({ method: 'POST' }) - .inputValidator( + .validator( (data: { prompt: string provider: Provider @@ -167,7 +167,7 @@ export const generateAudioFn = createServerFn({ method: 'POST' }) }) export const generateVideoFn = createServerFn({ method: 'POST' }) - .inputValidator( + .validator( (data: { prompt: MediaPrompt provider: Provider