@tanstack/ai-svelte 0.6.2 → 0.6.4

package/src/create-generate-speech.svelte.ts

@@ -0,0 +1,120 @@
+import { createGeneration } from './create-generation.svelte'
+import type { StreamChunk, TTSResult } from '@tanstack/ai'
+import type {
+  ConnectionAdapter,
+  GenerationClientState,
+  GenerationFetcher,
+  InferGenerationOutput,
+  SpeechGenerateInput,
+} from '@tanstack/ai-client'
+
+/**
+ * Options for the createGenerateSpeech function.
+ *
+ * @template TOutput - The output type after optional transform (defaults to TTSResult)
+ */
+export interface CreateGenerateSpeechOptions<TOutput = TTSResult> {
+  /** Connection adapter for streaming transport (SSE, HTTP stream, custom) */
+  connection?: ConnectionAdapter
+  /** Direct async function for speech generation */
+  fetcher?: GenerationFetcher<SpeechGenerateInput, TTSResult>
+  /** Unique identifier for this generation instance */
+  id?: string
+  /** Additional body parameters to send with ConnectionAdapter requests */
+  body?: Record<string, any>
+  /**
+   * Callback when speech is generated. Can optionally return a transformed value.
+   *
+   * - Return a non-null value to transform and store it as the result
+   * - Return `null` to keep the previous result unchanged
+   * - Return nothing (`void`) to store the raw result as-is
+   */
+  onResult?: (result: TTSResult) => TOutput | null | void
+  /** Callback when an error occurs */
+  onError?: (error: Error) => void
+  /** Callback when progress is reported (0-100) */
+  onProgress?: (progress: number, message?: string) => void
+  /** Callback for each stream chunk (ConnectionAdapter mode only) */
+  onChunk?: (chunk: StreamChunk) => void
+}
+
+/**
+ * Return type for the createGenerateSpeech function.
+ *
+ * @template TOutput - The output type (after optional transform)
+ */
+export interface CreateGenerateSpeechReturn<TOutput = TTSResult> {
+  /** The TTS result containing audio data, or null */
+  readonly result: TOutput | null
+  /** Whether generation is in progress */
+  readonly isLoading: boolean
+  /** Current error, if any */
+  readonly error: Error | undefined
+  /** Current state of the generation */
+  readonly status: GenerationClientState
+  /** Trigger speech generation */
+  generate: (input: SpeechGenerateInput) => Promise<void>
+  /** Abort the current generation */
+  stop: () => void
+  /** Clear result, error, and return to idle */
+  reset: () => void
+  /** Update additional body parameters */
+  updateBody: (body: Record<string, any>) => void
+}
+
+/**
+ * Creates a reactive speech generation (text-to-speech) instance for Svelte 5.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createGenerateSpeech, fetchServerSentEvents } from '@tanstack/ai-svelte'
+ *
+ *   const speech = createGenerateSpeech({
+ *     connection: fetchServerSentEvents('/api/generate/speech'),
+ *   })
+ * </script>
+ *
+ * <div>
+ *   <button onclick={() => speech.generate({ text: 'Hello world', voice: 'alloy' })}>
+ *     Generate Speech
+ *   </button>
+ *   {#if speech.isLoading}
+ *     <p>Generating...</p>
+ *   {/if}
+ *   {#if speech.result}
+ *     <audio src={`data:audio/${speech.result.format};base64,${speech.result.audio}`} controls></audio>
+ *   {/if}
+ * </div>
+ * ```
+ */
+export function createGenerateSpeech<
+  TOnResult extends ((result: TTSResult) => any) | undefined = undefined,
+>(
+  options: Omit<CreateGenerateSpeechOptions, 'onResult'> & {
+    onResult?: TOnResult
+  },
+): CreateGenerateSpeechReturn<InferGenerationOutput<TTSResult, TOnResult>> {
+  const gen = createGeneration<SpeechGenerateInput, TTSResult, TOnResult>(
+    options,
+  )
+
+  return {
+    get result() {
+      return gen.result
+    },
+    get isLoading() {
+      return gen.isLoading
+    },
+    get error() {
+      return gen.error
+    },
+    get status() {
+      return gen.status
+    },
+    generate: gen.generate as (input: SpeechGenerateInput) => Promise<void>,
+    stop: gen.stop,
+    reset: gen.reset,
+    updateBody: gen.updateBody,
+  }
+}

package/src/create-generate-video.svelte.ts

@@ -0,0 +1,220 @@
+import { VideoGenerationClient } from '@tanstack/ai-client'
+import type { StreamChunk } from '@tanstack/ai'
+import type {
+  ConnectionAdapter,
+  GenerationClientState,
+  GenerationFetcher,
+  InferGenerationOutput,
+  VideoGenerateInput,
+  VideoGenerateResult,
+  VideoStatusInfo,
+} from '@tanstack/ai-client'
+
+/**
+ * Options for the createGenerateVideo function.
+ *
+ * @template TOutput - The output type after optional transform (defaults to VideoGenerateResult)
+ */
+export interface CreateGenerateVideoOptions<TOutput = VideoGenerateResult> {
+  /** Connection adapter for streaming transport (server handles polling) */
+  connection?: ConnectionAdapter
+  /** Direct async function that returns a completed video result */
+  fetcher?: GenerationFetcher<VideoGenerateInput, VideoGenerateResult>
+  /** Unique identifier for this generation instance */
+  id?: string
+  /** Additional body parameters to send with ConnectionAdapter requests */
+  body?: Record<string, any>
+  /**
+   * Callback when video generation completes. Can optionally return a transformed value.
+   *
+   * - Return a non-null value to transform and store it as the result
+   * - Return `null` to keep the previous result unchanged
+   * - Return nothing (`void`) to store the raw result as-is
+   */
+  onResult?: (result: VideoGenerateResult) => TOutput | null | void
+  /** Callback when an error occurs */
+  onError?: (error: Error) => void
+  /** Callback when progress is reported (0-100) */
+  onProgress?: (progress: number, message?: string) => void
+  /** Callback when a video job is created */
+  onJobCreated?: (jobId: string) => void
+  /** Callback on each status update */
+  onStatusUpdate?: (status: VideoStatusInfo) => void
+  /** Callback for each stream chunk (ConnectionAdapter mode only) */
+  onChunk?: (chunk: StreamChunk) => void
+}
+
+/**
+ * Return type for the createGenerateVideo function.
+ *
+ * @template TOutput - The output type (after optional transform)
+ */
+export interface CreateGenerateVideoReturn<TOutput = VideoGenerateResult> {
+  /** The final video result (with URL), or null */
+  readonly result: TOutput | null
+  /** The current job ID, or null */
+  readonly jobId: string | null
+  /** Current video generation status info, or null */
+  readonly videoStatus: VideoStatusInfo | null
+  /** Whether generation/polling is in progress */
+  readonly isLoading: boolean
+  /** Current error, if any */
+  readonly error: Error | undefined
+  /** Current state of the generation */
+  readonly status: GenerationClientState
+  /** Trigger video generation */
+  generate: (input: VideoGenerateInput) => Promise<void>
+  /** Abort the current generation/polling */
+  stop: () => void
+  /** Clear all state and return to idle */
+  reset: () => void
+  /** Update additional body parameters */
+  updateBody: (body: Record<string, any>) => void
+}
+
+/**
+ * Creates a reactive video generation instance for Svelte 5.
+ *
+ * Video generation is asynchronous: a job is created, then polled for status
+ * until completion. This function handles the full lifecycle.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createGenerateVideo, fetchServerSentEvents } from '@tanstack/ai-svelte'
+ *
+ *   const video = createGenerateVideo({
+ *     connection: fetchServerSentEvents('/api/generate/video'),
+ *     onStatusUpdate: (status) => console.log(`Progress: ${status.progress}%`),
+ *   })
+ * </script>
+ *
+ * <div>
+ *   <button onclick={() => video.generate({ prompt: 'A flying car over a city' })}>
+ *     Generate Video
+ *   </button>
+ *   {#if video.isLoading && video.videoStatus}
+ *     <p>Status: {video.videoStatus.status} ({video.videoStatus.progress}%)</p>
+ *   {/if}
+ *   {#if video.result}
+ *     <video src={video.result.url} controls></video>
+ *   {/if}
+ * </div>
+ * ```
+ */
+export function createGenerateVideo<
+  TOnResult extends ((result: VideoGenerateResult) => any) | undefined =
+    undefined,
+>(
+  options: Omit<CreateGenerateVideoOptions, 'onResult'> & {
+    onResult?: TOnResult
+  },
+): CreateGenerateVideoReturn<
+  InferGenerationOutput<VideoGenerateResult, TOnResult>
+> {
+  type TOutput = InferGenerationOutput<VideoGenerateResult, TOnResult>
+  const clientId =
+    options.id ||
+    `video-${Date.now()}-${Math.random().toString(36).substring(7)}`
+
+  // Create reactive state using Svelte 5 runes
+  let result = $state<TOutput | null>(null)
+  let jobId = $state<string | null>(null)
+  let videoStatus = $state<VideoStatusInfo | null>(null)
+  let isLoading = $state(false)
+  let error = $state<Error | undefined>(undefined)
+  let status = $state<GenerationClientState>('idle')
+
+  const baseOptions = {
+    id: clientId,
+    body: options.body,
+    onResult: (r: VideoGenerateResult) => options.onResult?.(r),
+    onError: (e: Error) => options.onError?.(e),
+    onProgress: (p: number, m?: string) => options.onProgress?.(p, m),
+    onChunk: (c: StreamChunk) => options.onChunk?.(c),
+    onJobCreated: (id: string) => options.onJobCreated?.(id),
+    onStatusUpdate: (s: VideoStatusInfo) => options.onStatusUpdate?.(s),
+    onResultChange: (r: TOutput | null) => {
+      result = r
+    },
+    onLoadingChange: (l: boolean) => {
+      isLoading = l
+    },
+    onErrorChange: (e: Error | undefined) => {
+      error = e
+    },
+    onStatusChange: (s: GenerationClientState) => {
+      status = s
+    },
+    onJobIdChange: (id: string | null) => {
+      jobId = id
+    },
+    onVideoStatusChange: (s: VideoStatusInfo | null) => {
+      videoStatus = s
+    },
+  }
+
+  let client: VideoGenerationClient<TOutput>
+
+  if (options.connection) {
+    client = new VideoGenerationClient<TOutput>({
+      ...baseOptions,
+      connection: options.connection,
+    })
+  } else if (options.fetcher) {
+    client = new VideoGenerationClient<TOutput>({
+      ...baseOptions,
+      fetcher: options.fetcher,
+    })
+  } else {
+    throw new Error(
+      'createGenerateVideo requires either a connection or fetcher option',
+    )
+  }
+
+  // Note: Cleanup is handled by calling stop() directly when needed.
+  // Unlike React/Vue/Solid, Svelte 5 runes like $effect can only be used
+  // during component initialization, so we don't add automatic cleanup here.
+  // Users should call video.stop() in their component's cleanup if needed.
+
+  const generate = async (input: VideoGenerateInput) => {
+    await client.generate(input)
+  }
+
+  const stop = () => {
+    client.stop()
+  }
+
+  const reset = () => {
+    client.reset()
+  }
+
+  const updateBody = (newBody: Record<string, any>) => {
+    client.updateOptions({ body: newBody })
+  }
+
+  return {
+    get result() {
+      return result
+    },
+    get jobId() {
+      return jobId
+    },
+    get videoStatus() {
+      return videoStatus
+    },
+    get isLoading() {
+      return isLoading
+    },
+    get error() {
+      return error
+    },
+    get status() {
+      return status
+    },
+    generate,
+    stop,
+    reset,
+    updateBody,
+  }
+}

package/src/create-generation.svelte.ts

@@ -0,0 +1,197 @@
+import { GenerationClient } from '@tanstack/ai-client'
+import type { StreamChunk } from '@tanstack/ai'
+import type {
+  ConnectionAdapter,
+  GenerationClientOptions,
+  GenerationClientState,
+  GenerationFetcher,
+  InferGenerationOutput,
+} from '@tanstack/ai-client'
+
+/**
+ * Options for the createGeneration function.
+ *
+ * Accepts either a `connection` (streaming transport) or a `fetcher` (direct async call).
+ *
+ * @template TInput - The input type for the generation request
+ * @template TResult - The result type returned by the generation
+ * @template TOutput - The output type after optional transform (defaults to TResult)
+ */
+export interface CreateGenerationOptions<TInput, TResult, TOutput = TResult> {
+  /** Connection adapter for streaming transport (SSE, HTTP stream, custom) */
+  connection?: ConnectionAdapter
+  /** Direct async function for one-shot generation (no streaming protocol needed) */
+  fetcher?: GenerationFetcher<TInput, TResult>
+  /** Unique identifier for this generation instance */
+  id?: string
+  /** Additional body parameters to send with ConnectionAdapter requests */
+  body?: Record<string, any>
+  /**
+   * Callback when a result is received. Can optionally return a transformed value.
+   *
+   * - Return a non-null value to transform and store it as the result
+   * - Return `null` to keep the previous result unchanged
+   * - Return nothing (`void`) to store the raw result as-is
+   */
+  onResult?: (result: TResult) => TOutput | null | void
+  /** Callback when an error occurs */
+  onError?: (error: Error) => void
+  /** Callback when progress is reported (0-100) */
+  onProgress?: (progress: number, message?: string) => void
+  /** Callback for each stream chunk (ConnectionAdapter mode only) */
+  onChunk?: (chunk: StreamChunk) => void
+}
+
+/**
+ * Return type for the createGeneration function.
+ *
+ * @template TOutput - The output type (after optional transform)
+ */
+export interface CreateGenerationReturn<TOutput> {
+  /** The generation result, or null if not yet generated */
+  readonly result: TOutput | null
+  /** Whether a generation is currently in progress */
+  readonly isLoading: boolean
+  /** Current error, if any */
+  readonly error: Error | undefined
+  /** Current state of the generation client */
+  readonly status: GenerationClientState
+  /** Trigger a generation request */
+  generate: (input: Record<string, any>) => Promise<void>
+  /** Abort the current generation */
+  stop: () => void
+  /** Clear result, error, and return to idle */
+  reset: () => void
+  /** Update additional body parameters */
+  updateBody: (body: Record<string, any>) => void
+}
+
+/**
+ * Creates a reactive generation instance for Svelte 5.
+ *
+ * This is the base function used by `createGenerateImage`, `createGenerateSpeech`,
+ * `createTranscription`, and `createSummarize`. You can also use it directly
+ * for custom generation types.
+ *
+ * @template TInput - The input type for the generation request
+ * @template TResult - The result type returned by the generation
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createGeneration, fetchServerSentEvents } from '@tanstack/ai-svelte'
+ *
+ *   const gen = createGeneration({
+ *     connection: fetchServerSentEvents('/api/generate/custom'),
+ *   })
+ * </script>
+ *
+ * <div>
+ *   <button onclick={() => gen.generate({ prompt: 'Hello' })}>Generate</button>
+ *   {#if gen.isLoading}
+ *     <p>Generating...</p>
+ *   {/if}
+ *   {#if gen.result}
+ *     <p>{JSON.stringify(gen.result)}</p>
+ *   {/if}
+ * </div>
+ * ```
+ */
+export function createGeneration<
+  TInput extends Record<string, any>,
+  TResult,
+  TOnResult extends ((result: TResult) => any) | undefined = undefined,
+>(
+  options: Omit<CreateGenerationOptions<TInput, TResult>, 'onResult'> & {
+    onResult?: TOnResult
+  },
+): CreateGenerationReturn<InferGenerationOutput<TResult, TOnResult>> {
+  type TOutput = InferGenerationOutput<TResult, TOnResult>
+  const clientId =
+    options.id || `gen-${Date.now()}-${Math.random().toString(36).substring(7)}`
+
+  // Create reactive state using Svelte 5 runes
+  let result = $state<TOutput | null>(null)
+  let isLoading = $state(false)
+  let error = $state<Error | undefined>(undefined)
+  let status = $state<GenerationClientState>('idle')
+
+  const clientOptions: GenerationClientOptions<TInput, TResult, TOutput> = {
+    id: clientId,
+    body: options.body,
+    onResult: (r: TResult) => options.onResult?.(r),
+    onError: (e: Error) => options.onError?.(e),
+    onProgress: (p: number, m?: string) => options.onProgress?.(p, m),
+    onChunk: (c: StreamChunk) => options.onChunk?.(c),
+    onResultChange: (r: TOutput | null) => {
+      result = r
+    },
+    onLoadingChange: (l: boolean) => {
+      isLoading = l
+    },
+    onErrorChange: (e: Error | undefined) => {
+      error = e
+    },
+    onStatusChange: (s: GenerationClientState) => {
+      status = s
+    },
+  }
+
+  let client: GenerationClient<TInput, TResult, TOutput>
+
+  if (options.connection) {
+    client = new GenerationClient<TInput, TResult, TOutput>({
+      ...clientOptions,
+      connection: options.connection,
+    })
+  } else if (options.fetcher) {
+    client = new GenerationClient<TInput, TResult, TOutput>({
+      ...clientOptions,
+      fetcher: options.fetcher,
+    })
+  } else {
+    throw new Error(
+      'createGeneration requires either a connection or fetcher option',
+    )
+  }
+
+  // Note: Cleanup is handled by calling stop() directly when needed.
+  // Unlike React/Vue/Solid, Svelte 5 runes like $effect can only be used
+  // during component initialization, so we don't add automatic cleanup here.
+  // Users should call gen.stop() in their component's cleanup if needed.
+
+  const generate = async (input: TInput) => {
+    await client.generate(input)
+  }
+
+  const stop = () => {
+    client.stop()
+  }
+
+  const reset = () => {
+    client.reset()
+  }
+
+  const updateBody = (newBody: Record<string, any>) => {
+    client.updateOptions({ body: newBody })
+  }
+
+  return {
+    get result() {
+      return result
+    },
+    get isLoading() {
+      return isLoading
+    },
+    get error() {
+      return error
+    },
+    get status() {
+      return status
+    },
+    generate: generate as (input: Record<string, any>) => Promise<void>,
+    stop,
+    reset,
+    updateBody,
+  }
+}

package/src/create-summarize.svelte.ts

@@ -0,0 +1,129 @@
+import { createGeneration } from './create-generation.svelte'
+import type { StreamChunk, SummarizationResult } from '@tanstack/ai'
+import type {
+  ConnectionAdapter,
+  GenerationClientState,
+  GenerationFetcher,
+  InferGenerationOutput,
+  SummarizeGenerateInput,
+} from '@tanstack/ai-client'
+
+/**
+ * Options for the createSummarize function.
+ *
+ * @template TOutput - The output type after optional transform (defaults to SummarizationResult)
+ */
+export interface CreateSummarizeOptions<TOutput = SummarizationResult> {
+  /** Connection adapter for streaming transport (SSE, HTTP stream, custom) */
+  connection?: ConnectionAdapter
+  /** Direct async function for summarization */
+  fetcher?: GenerationFetcher<SummarizeGenerateInput, SummarizationResult>
+  /** Unique identifier for this generation instance */
+  id?: string
+  /** Additional body parameters to send with ConnectionAdapter requests */
+  body?: Record<string, any>
+  /**
+   * Callback when summarization is complete. Can optionally return a transformed value.
+   *
+   * - Return a non-null value to transform and store it as the result
+   * - Return `null` to keep the previous result unchanged
+   * - Return nothing (`void`) to store the raw result as-is
+   */
+  onResult?: (result: SummarizationResult) => TOutput | null | void
+  /** Callback when an error occurs */
+  onError?: (error: Error) => void
+  /** Callback when progress is reported (0-100) */
+  onProgress?: (progress: number, message?: string) => void
+  /** Callback for each stream chunk (ConnectionAdapter mode only) */
+  onChunk?: (chunk: StreamChunk) => void
+}
+
+/**
+ * Return type for the createSummarize function.
+ *
+ * @template TOutput - The output type (after optional transform)
+ */
+export interface CreateSummarizeReturn<TOutput = SummarizationResult> {
+  /** The summarization result, or null */
+  readonly result: TOutput | null
+  /** Whether summarization is in progress */
+  readonly isLoading: boolean
+  /** Current error, if any */
+  readonly error: Error | undefined
+  /** Current state of the generation */
+  readonly status: GenerationClientState
+  /** Trigger summarization */
+  generate: (input: SummarizeGenerateInput) => Promise<void>
+  /** Abort the current summarization */
+  stop: () => void
+  /** Clear result, error, and return to idle */
+  reset: () => void
+  /** Update additional body parameters */
+  updateBody: (body: Record<string, any>) => void
+}
+
+/**
+ * Creates a reactive text summarization instance for Svelte 5.
+ *
+ * @example
+ * ```svelte
+ * <script>
+ *   import { createSummarize, fetchServerSentEvents } from '@tanstack/ai-svelte'
+ *
+ *   const summarizer = createSummarize({
+ *     connection: fetchServerSentEvents('/api/summarize'),
+ *   })
+ * </script>
+ *
+ * <div>
+ *   <button onclick={() => summarizer.generate({
+ *     text: 'Long article text...',
+ *     style: 'bullet-points',
+ *     maxLength: 200,
+ *   })}>
+ *     Summarize
+ *   </button>
+ *   {#if summarizer.isLoading}
+ *     <p>Summarizing...</p>
+ *   {/if}
+ *   {#if summarizer.result}
+ *     <p>{summarizer.result.summary}</p>
+ *   {/if}
+ * </div>
+ * ```
+ */
+export function createSummarize<
+  TOnResult extends ((result: SummarizationResult) => any) | undefined =
+    undefined,
+>(
+  options: Omit<CreateSummarizeOptions, 'onResult'> & {
+    onResult?: TOnResult
+  },
+): CreateSummarizeReturn<
+  InferGenerationOutput<SummarizationResult, TOnResult>
+> {
+  const gen = createGeneration<
+    SummarizeGenerateInput,
+    SummarizationResult,
+    TOnResult
+  >(options)
+
+  return {
+    get result() {
+      return gen.result
+    },
+    get isLoading() {
+      return gen.isLoading
+    },
+    get error() {
+      return gen.error
+    },
+    get status() {
+      return gen.status
+    },
+    generate: gen.generate as (input: SummarizeGenerateInput) => Promise<void>,
+    stop: gen.stop,
+    reset: gen.reset,
+    updateBody: gen.updateBody,
+  }
+}