@stacksjs/stx/dist/streaming.d.ts

A performant UI Framework. Powered by Bun.

import type { CustomDirective, StreamRenderer, StxOptions } from './types';
/**
 * Stream a template with data using chunked transfer encoding.
 *
 * This implements actual progressive streaming by:
 * 1. Sending the shell (content before suspense) immediately
 * 2. Processing suspense boundaries in parallel
 * 3. Streaming each resolved suspense content as it completes
 * 4. Using out-of-order streaming with client-side reordering
 *
 * @param templatePath Path to the template
 * @param data Data to render with the template
 * @param options stx options
 */
export declare function streamTemplate(templatePath: string, data?: Record<string, any>, options?: StxOptions): Promise<ReadableStream<string>>;
/**
 * Stream a template with data (simple version without suspense).
 * Returns full content in chunks based on buffer size.
 *
 * @param templatePath Path to the template
 * @param data Data to render with the template
 * @param options stx options
 */
export declare function streamTemplateSimple(templatePath: string, data?: Record<string, any>, options?: StxOptions): Promise<ReadableStream<string>>;
/**
 * Create a stream renderer for progressive loading
 * @param templatePath Path to the template
 * @param options stx options
 */
export declare function createStreamRenderer(templatePath: string, options?: StxOptions): Promise<StreamRenderer>;
/**
 * Register streaming and hydration directives
 */
export declare function registerStreamingDirectives(options?: StxOptions): CustomDirective[];
/**
 * Process section directives
 * @param content Template content
 * @param context Data context
 * @param filePath Template file path
 * @param _options stx options
 */
export declare function processSectionDirectives(content: string, context: Record<string, any>, filePath: string, _options?: StxOptions): Promise<string>;
/**
 * Wrap a ReadableStream<string> in a proper Response with chunked transfer encoding headers.
 *
 * Makes it trivial to use streaming from a Bun server handler:
 *
 * @example
 * ```typescript
 * const server = Bun.serve({
 *   async fetch(req) {
 *     const stream = await streamTemplate('index.stx', { title: 'Home' })
 *     return streamToResponse(stream)
 *   }
 * })
 * ```
 *
 * @param stream - The template ReadableStream
 * @param init - Optional additional ResponseInit (headers, status, etc.)
 * @returns A Response with proper streaming headers
 */
export declare function streamToResponse(stream: ReadableStream<string>, init?: ResponseInit): Response;
/**
 * Generate client-side hydration runtime script.
 *
 * This script handles:
 * - Finding islands in the DOM
 * - Loading island components based on priority
 * - Hydrating islands with their props
 *
 * Usage: Include the generated script in your page, then call
 * `window.__stx.hydrate()` when ready.
 *
 * @example
 * ```html
 * <script>
 *   {{ generateHydrationRuntime({ mode: 'full' }) }}
 * </script>
 * ```
 */
export declare function generateHydrationRuntime(config?: HydrationRuntimeConfig): string;
/**
 * Custom directive for marking suspense boundaries in streaming templates.
 *
 * Usage:
 * ```html
 * @suspense('heavy-content')
 *   <div>This content will stream after the shell</div>
 * @endsuspense
 * ```
 *
 * The content inside suspense boundaries will be:
 * 1. Replaced with a placeholder in the initial shell
 * 2. Processed in parallel with other suspense boundaries
 * 3. Streamed to the client as it resolves
 * 4. Injected into the placeholder via client-side JavaScript
 */
export declare const streamingSuspenseDirective: CustomDirective;
/**
 * Custom directive for creating islands (for partial hydration)
 */
export declare const islandDirective: CustomDirective;
/**
 * Configuration for hydration runtime generation
 */
export declare interface HydrationRuntimeConfig {
  mode: 'full' | 'loader'
  components?: Record<string, string>
  dynamicImports?: boolean
}