@flight-framework/core 0.0.3 → 0.2.0

package/dist/rsc/renderer.d.ts

@@ -0,0 +1,160 @@
+import { FlightChunk, ServerComponentChunk, ClientReferenceChunk } from './payload.js';
+import { ServerContext } from './context.js';
+
+/**
+ * @flight-framework/core - Server Component Renderer
+ *
+ * Renders Server Components to FlightChunks.
+ * Framework-agnostic rendering engine that works with adapters.
+ *
+ * @module @flight-framework/core/rsc/renderer
+ */
+
+/**
+ * UI Framework adapter for rendering
+ */
+interface UIAdapter {
+    /** Adapter name */
+    name: string;
+    /** Check if value is a framework element */
+    isElement(value: unknown): boolean;
+    /** Get element type info */
+    getElementType(element: unknown): ElementTypeInfo;
+    /** Get element props */
+    getProps(element: unknown): Record<string, unknown>;
+    /** Get element children */
+    getChildren(element: unknown): unknown[];
+    /** Get element key */
+    getKey(element: unknown): string | number | undefined;
+    /** Check if component is a client boundary */
+    isClientBoundary(component: unknown): boolean;
+    /** Render element to HTML string (for SSR fallback) */
+    renderToString?(element: unknown): Promise<string>;
+}
+type ElementTypeInfo = {
+    kind: 'host';
+    tag: string;
+} | {
+    kind: 'component';
+    fn: ComponentFn;
+    name: string;
+} | {
+    kind: 'fragment';
+} | {
+    kind: 'suspense';
+    fallback?: unknown;
+} | {
+    kind: 'provider';
+    value?: unknown;
+} | {
+    kind: 'context';
+} | {
+    kind: 'text';
+    value: string;
+} | {
+    kind: 'null';
+};
+/**
+ * Component function type
+ */
+type ComponentFn = (props: Record<string, unknown>, ctx?: ServerContext) => unknown | Promise<unknown>;
+/**
+ * Render options
+ */
+interface RenderOptions {
+    /** Include SSR fallbacks for client components */
+    includeSSRFallbacks?: boolean;
+    /** Error handler */
+    onError?: (error: Error, componentName?: string) => void;
+    /** Dev mode (include extra debug info) */
+    dev?: boolean;
+    /** Max render depth to prevent infinite loops */
+    maxDepth?: number;
+}
+/**
+ * Render result with metadata
+ */
+interface RenderResult {
+    /** All chunks generated */
+    chunks: FlightChunk[];
+    /** Root chunk */
+    root: ServerComponentChunk;
+    /** Client references found */
+    clientRefs: ClientReferenceChunk[];
+    /** Timing info */
+    timing: {
+        startTime: number;
+        endTime: number;
+        duration: number;
+    };
+}
+/**
+ * Flight Server Component Renderer
+ */
+declare class FlightRenderer {
+    private adapter;
+    private options;
+    private chunks;
+    private clientRefs;
+    private pendingPromises;
+    private depth;
+    constructor(adapter: UIAdapter, options?: RenderOptions);
+    /**
+     * Render a component tree to Flight chunks
+     */
+    render(element: unknown, ctx: ServerContext): Promise<RenderResult>;
+    /**
+     * Render as async generator (for streaming)
+     */
+    renderStreaming(element: unknown, ctx: ServerContext): AsyncGenerator<FlightChunk>;
+    /**
+     * Render an element to FlightElement
+     */
+    private renderElement;
+    /**
+     * Render a framework-specific element
+     */
+    private renderFrameworkElement;
+    /**
+     * Render a host element (div, span, etc.)
+     */
+    private renderHostElement;
+    /**
+     * Render a component (server or client)
+     */
+    private renderComponent;
+    /**
+     * Render a client boundary
+     */
+    private renderClientBoundary;
+    /**
+     * Render a Suspense boundary
+     */
+    private renderSuspense;
+    /**
+     * Render an async boundary (promise thrown from component)
+     */
+    private renderAsyncBoundary;
+    /**
+     * Render a Client Reference directly
+     */
+    private renderClientReference;
+    /**
+     * Resolve all pending async chunks
+     */
+    private resolvePendingChunks;
+}
+/**
+ * Create a renderer with adapter
+ */
+declare function createRenderer(adapter: UIAdapter, options?: RenderOptions): FlightRenderer;
+/**
+ * Render a server component tree
+ */
+declare function renderServerComponent<P>(component: ComponentFn, props: P, ctx: ServerContext, adapter: UIAdapter, options?: RenderOptions): Promise<RenderResult>;
+/**
+ * Render server component as streaming chunks
+ */
+declare function renderServerComponentStreaming<P>(component: ComponentFn, props: P, ctx: ServerContext, adapter: UIAdapter, options?: RenderOptions): AsyncGenerator<FlightChunk>;
+
+export { type ComponentFn, type ElementTypeInfo, FlightRenderer, type RenderOptions, type RenderResult, type UIAdapter, createRenderer, renderServerComponent, renderServerComponentStreaming };

package/dist/rsc/renderer.js

@@ -0,0 +1,5 @@
+export { FlightRenderer, createRenderer, renderServerComponent, renderServerComponentStreaming } from '../chunk-4F77J5TY.js';
+import '../chunk-K2CQZPCG.js';
+import '../chunk-CLZSB5QD.js';
+//# sourceMappingURL=renderer.js.map
+//# sourceMappingURL=renderer.js.map

package/dist/rsc/renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"renderer.js"}

package/dist/rsc/stream.d.ts

@@ -0,0 +1,129 @@
+import { FlightChunk, ServerComponentChunk, ErrorBoundaryChunk } from './payload.js';
+
+/**
+ * @flight-framework/core - Flight Stream
+ *
+ * Protocolo de streaming para Server Components.
+ * Usa NDJSON (Newline Delimited JSON) para máxima debuggabilidad.
+ *
+ * Filosofía Flight:
+ * - Formato abierto y documentado
+ * - Works con cualquier runtime (Node, Deno, Bun, Edge)
+ * - Fácil de debuggear (text-based)
+ * - Sin dependencias
+ *
+ * @module @flight-framework/core/rsc/stream
+ */
+
+/**
+ * Opciones para crear un FlightStream
+ */
+interface FlightStreamOptions {
+    /** Incluir timestamps en chunks */
+    timestamps?: boolean;
+    /** Prefix para IDs generados */
+    idPrefix?: string;
+    /** Callback cuando un chunk es enviado */
+    onChunk?: (chunk: FlightChunk) => void;
+    /** Callback cuando el stream termina */
+    onComplete?: () => void;
+    /** Callback en caso de error */
+    onError?: (error: Error) => void;
+}
+/**
+ * Resultado del parsing de un FlightStream
+ */
+interface FlightStreamResult {
+    /** Chunks recibidos */
+    chunks: FlightChunk[];
+    /** Componente raíz */
+    root?: ServerComponentChunk;
+    /** Errores encontrados */
+    errors: ErrorBoundaryChunk[];
+    /** Tiempo total de streaming en ms */
+    duration: number;
+}
+/**
+ * Crea un ReadableStream desde un AsyncIterable de chunks
+ *
+ * @example
+ * ```typescript
+ * async function* renderApp() {
+ *   yield createServerChunk('root', tree);
+ *   yield createClientChunk('counter', './Counter', 'default', { initial: 0 });
+ * }
+ *
+ * const stream = createFlightStream(renderApp());
+ * return new Response(stream, { headers: { 'Content-Type': 'text/x-flight' } });
+ * ```
+ */
+declare function createFlightStream(chunks: AsyncIterable<FlightChunk>, options?: FlightStreamOptions): ReadableStream<Uint8Array>;
+/**
+ * Crea un FlightStream desde un array de chunks
+ */
+declare function createFlightStreamFromArray(chunks: FlightChunk[], options?: FlightStreamOptions): ReadableStream<Uint8Array>;
+/**
+ * Parsea un FlightStream a chunks individuales
+ *
+ * @example
+ * ```typescript
+ * // En el cliente
+ * const response = await fetch('/page');
+ * const chunks = parseFlightStream(response.body!);
+ *
+ * for await (const chunk of chunks) {
+ *   handleChunk(chunk);
+ * }
+ * ```
+ */
+declare function parseFlightStream(stream: ReadableStream<Uint8Array>): AsyncGenerator<FlightChunk>;
+/**
+ * Parsea un string completo de FlightStream
+ */
+declare function parseFlightStreamSync(data: string): FlightChunk[];
+/**
+ * Consume un FlightStream y retorna todos los chunks
+ */
+declare function consumeFlightStream(stream: ReadableStream<Uint8Array>): Promise<FlightStreamResult>;
+/**
+ * Crea una Response con Flight payload
+ */
+declare function createFlightResponse(chunks: AsyncIterable<FlightChunk>, options?: FlightResponseOptions): Response;
+interface FlightResponseOptions {
+    status?: number;
+    headers?: Record<string, string>;
+}
+/**
+ * Crea una Response HTML con streaming SSR + Flight payload embebido
+ */
+declare function createHybridResponse(htmlStream: ReadableStream<Uint8Array>, flightChunks: FlightChunk[], options?: FlightResponseOptions): Response;
+/**
+ * Crea un stream controller para enviar chunks progresivamente
+ */
+declare function createStreamController(): {
+    stream: ReadableStream<Uint8Array>;
+    enqueue: (chunk: FlightChunk) => void;
+    error: (error: Error) => void;
+    close: () => void;
+};
+/**
+ * Merge múltiples streams en uno solo (para rendering paralelo)
+ */
+declare function mergeFlightStreams(...streams: ReadableStream<Uint8Array>[]): ReadableStream<Uint8Array>;
+/**
+ * Pipe a flight stream through a transform
+ */
+declare function transformFlightStream(stream: ReadableStream<Uint8Array>, transform: (chunk: FlightChunk) => FlightChunk | null | Promise<FlightChunk | null>): ReadableStream<Uint8Array>;
+/**
+ * Pretty print Flight chunks para debugging
+ */
+declare function prettyPrintChunks(chunks: FlightChunk[]): string;
+/**
+ * Error durante parsing de FlightStream
+ */
+declare class FlightStreamError extends Error {
+    readonly rawData?: string | undefined;
+    constructor(message: string, rawData?: string | undefined);
+}
+
+export { type FlightResponseOptions, FlightStreamError, type FlightStreamOptions, type FlightStreamResult, consumeFlightStream, createFlightResponse, createFlightStream, createFlightStreamFromArray, createHybridResponse, createStreamController, mergeFlightStreams, parseFlightStream, parseFlightStreamSync, prettyPrintChunks, transformFlightStream };

package/dist/rsc/stream.js

@@ -0,0 +1,3 @@
+export { FlightStreamError, consumeFlightStream, createFlightResponse, createFlightStream, createFlightStreamFromArray, createHybridResponse, createStreamController, mergeFlightStreams, parseFlightStream, parseFlightStreamSync, prettyPrintChunks, transformFlightStream } from '../chunk-T3S5YC7L.js';
+//# sourceMappingURL=stream.js.map
+//# sourceMappingURL=stream.js.map

package/dist/rsc/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"stream.js"}

package/dist/rsc/vite-plugin.d.ts

@@ -0,0 +1,78 @@
+import { Plugin } from 'vite';
+
+/**
+ * @flight-framework/vite-plugin-rsc
+ *
+ * Vite plugin for Flight Server Components.
+ * Transforms 'use client' and 'use server' directives at build time.
+ *
+ * Philosophy:
+ * - Zero config for common cases
+ * - Full control when needed
+ * - Works with any Vite project
+ * - No Next.js dependencies
+ *
+ * @module @flight-framework/vite-plugin-rsc
+ */
+
+/**
+ * Plugin configuration
+ */
+interface FlightRSCPluginOptions {
+    /** Include patterns (glob) */
+    include?: string[];
+    /** Exclude patterns (glob) */
+    exclude?: string[];
+    /** Server actions endpoint */
+    actionsEndpoint?: string;
+    /** Client manifest output path */
+    clientManifest?: string;
+    /** Server manifest output path */
+    serverManifest?: string;
+    /** Enable dev mode features */
+    dev?: boolean;
+    /** Custom transforms */
+    transforms?: {
+        /** Transform client components */
+        client?: (code: string, id: string) => string | null;
+        /** Transform server actions */
+        server?: (code: string, id: string) => string | null;
+    };
+}
+/**
+ * Client manifest entry
+ */
+interface ClientManifestEntry {
+    id: string;
+    file: string;
+    exports: string[];
+    chunks?: string[];
+}
+/**
+ * Server manifest entry
+ */
+interface ServerManifestEntry {
+    id: string;
+    file: string;
+    actions: string[];
+}
+/**
+ * Flight RSC Vite Plugin
+ *
+ * @example
+ * ```typescript
+ * // vite.config.ts
+ * import { flightRSC } from '@flight-framework/core/rsc/vite-plugin';
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     flightRSC({
+ *       actionsEndpoint: '/_flight/action',
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare function flightRSC(options?: FlightRSCPluginOptions): Plugin[];
+
+export { type ClientManifestEntry, type FlightRSCPluginOptions, type ServerManifestEntry, flightRSC as default, flightRSC };

package/dist/rsc/vite-plugin.js

@@ -0,0 +1,4 @@
+export { vite_plugin_default as default, flightRSC } from '../chunk-MRLCNFSD.js';
+import '../chunk-CLZSB5QD.js';
+//# sourceMappingURL=vite-plugin.js.map
+//# sourceMappingURL=vite-plugin.js.map

package/dist/rsc/vite-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"vite-plugin.js"}

package/dist/streaming/adapters/index.d.ts

@@ -0,0 +1,223 @@
+import { StreamingRenderOptions, StreamingRenderResult } from '../index.js';
+
+/**
+ * @flight-framework/core - Multi-Framework Streaming Adapters
+ *
+ * Streaming SSR adapters for React, Vue, Svelte, Solid, and HTMX.
+ * Uses dependency injection pattern for optional framework dependencies.
+ *
+ * Best Practices 2026:
+ * - Dependency injection for optional peer dependencies
+ * - Support both Node.js and Edge runtimes
+ * - Progressive hydration support
+ * - Error boundary integration
+ *
+ * @example
+ * ```typescript
+ * // React adapter with your imports
+ * import { renderToReadableStream } from 'react-dom/server';
+ *
+ * const adapter = createReactStreamAdapter({
+ *     renderToReadableStream,
+ *     bootstrapModules: ['/client.js'],
+ * });
+ * ```
+ */
+
+/**
+ * Framework-specific streaming adapter
+ */
+interface StreamingAdapter<TComponent = unknown> {
+    /** Adapter name */
+    readonly name: string;
+    /** Framework version support */
+    readonly framework: string;
+    /** Runtime support */
+    readonly runtime: 'universal' | 'node' | 'edge';
+    /**
+     * Create a streaming response from a component
+     */
+    stream(component: TComponent, options?: StreamingRenderOptions): Promise<StreamingRenderResult>;
+    /**
+     * Render to static string (for comparison/fallback)
+     */
+    renderToString?(component: TComponent): Promise<string>;
+}
+/**
+ * Common adapter options
+ */
+interface AdapterOptions {
+    /** Enable streaming (default: true) */
+    streaming?: boolean;
+    /** Scripts to bootstrap on client */
+    bootstrapScripts?: string[];
+    /** Modules to bootstrap on client */
+    bootstrapModules?: string[];
+    /** Error handling strategy */
+    onError?: (error: Error) => void;
+    /** Shell ready callback */
+    onShellReady?: () => void;
+    /** All content ready callback */
+    onAllReady?: () => void;
+}
+/**
+ * React streaming adapter options with required dependencies
+ */
+interface ReactAdapterOptions extends AdapterOptions {
+    /** React's renderToReadableStream (for Edge) */
+    renderToReadableStream?: (element: unknown, options?: {
+        bootstrapScripts?: string[];
+        bootstrapModules?: string[];
+        identifierPrefix?: string;
+        signal?: AbortSignal;
+        onError?: (error: unknown) => void;
+    }) => Promise<ReadableStream<Uint8Array> & {
+        allReady: Promise<void>;
+    }>;
+    /** React's renderToString (for static fallback) */
+    renderToString?: (element: unknown) => string;
+    /** Custom identifier prefix */
+    identifierPrefix?: string;
+    /** Abort signal */
+    signal?: AbortSignal;
+}
+/**
+ * Create a React streaming adapter
+ *
+ * @example
+ * ```typescript
+ * import { renderToReadableStream, renderToString } from 'react-dom/server';
+ *
+ * const adapter = createReactStreamAdapter({
+ *     renderToReadableStream,
+ *     renderToString,
+ *     bootstrapModules: ['/client.js'],
+ * });
+ *
+ * const result = await adapter.stream(<App />);
+ * ```
+ */
+declare function createReactStreamAdapter(options: ReactAdapterOptions): StreamingAdapter;
+/**
+ * Vue streaming adapter options
+ */
+interface VueAdapterOptions extends AdapterOptions {
+    /** Vue's renderToWebStream */
+    renderToWebStream?: (app: unknown, context?: Record<string, unknown>) => ReadableStream;
+    /** Vue's renderToString */
+    renderToString?: (app: unknown) => Promise<string>;
+    /** Vue app context */
+    context?: Record<string, unknown>;
+}
+/**
+ * Create a Vue 3 streaming adapter
+ *
+ * @example
+ * ```typescript
+ * import { renderToWebStream, renderToString } from 'vue/server-renderer';
+ *
+ * const adapter = createVueStreamAdapter({
+ *     renderToWebStream,
+ *     renderToString,
+ * });
+ *
+ * const result = await adapter.stream(createSSRApp(App));
+ * ```
+ */
+declare function createVueStreamAdapter(options: VueAdapterOptions): StreamingAdapter;
+/**
+ * Solid streaming adapter options
+ */
+interface SolidAdapterOptions extends AdapterOptions {
+    /** Solid's renderToStream */
+    renderToStream?: (fn: () => unknown, options?: {
+        nonce?: string;
+        onCompleteShell?: () => void;
+        onCompleteAll?: () => void;
+    }) => {
+        pipeTo: (writable: WritableStream) => void;
+    };
+    /** Solid's renderToString */
+    renderToString?: (fn: () => unknown) => string;
+    /** Nonce for CSP */
+    nonce?: string;
+}
+/**
+ * Create a Solid.js streaming adapter
+ *
+ * @example
+ * ```typescript
+ * import { renderToStream, renderToString } from 'solid-js/web';
+ *
+ * const adapter = createSolidStreamAdapter({
+ *     renderToStream,
+ *     renderToString,
+ * });
+ *
+ * const result = await adapter.stream(() => <App />);
+ * ```
+ */
+declare function createSolidStreamAdapter(options: SolidAdapterOptions): StreamingAdapter;
+/**
+ * Svelte streaming adapter options
+ */
+interface SvelteAdapterOptions extends AdapterOptions {
+    /** Svelte's render function */
+    render?: (component: unknown, options?: {
+        props?: Record<string, unknown>;
+    }) => {
+        body: string;
+        head?: string;
+    };
+    /** Props for the component */
+    props?: Record<string, unknown>;
+}
+/**
+ * Create a Svelte 5 streaming adapter
+ * Note: Svelte's SSR is primarily string-based, streaming is simulated
+ *
+ * @example
+ * ```typescript
+ * import { render } from 'svelte/server';
+ *
+ * const adapter = createSvelteStreamAdapter({
+ *     render,
+ *     props: { name: 'World' },
+ * });
+ *
+ * const result = await adapter.stream(App);
+ * ```
+ */
+declare function createSvelteStreamAdapter(options: SvelteAdapterOptions): StreamingAdapter;
+/**
+ * HTMX streaming adapter options
+ */
+interface HTMXAdapterOptions extends AdapterOptions {
+    /** Event name for SSE */
+    eventName?: string;
+    /** Retry interval for SSE */
+    retryMs?: number;
+}
+/**
+ * Create an HTMX SSE streaming adapter
+ * Uses Server-Sent Events for progressive updates
+ *
+ * @example
+ * ```typescript
+ * const adapter = createHTMXStreamAdapter({
+ *     eventName: 'update',
+ *     retryMs: 3000,
+ * });
+ *
+ * const result = await adapter.stream(['<div>Part 1</div>', '<div>Part 2</div>']);
+ * ```
+ */
+declare function createHTMXStreamAdapter(options?: HTMXAdapterOptions): StreamingAdapter<string[]>;
+type FrameworkType = 'react' | 'vue' | 'solid' | 'svelte' | 'htmx';
+/**
+ * Create a streaming adapter for any supported framework
+ * Note: For react, vue, solid, svelte you need to pass the required dependencies
+ */
+declare function createStreamAdapter(framework: FrameworkType, options?: AdapterOptions & Record<string, unknown>): StreamingAdapter;
+
+export { type AdapterOptions, type FrameworkType, type HTMXAdapterOptions, type ReactAdapterOptions, type SolidAdapterOptions, type StreamingAdapter, type SvelteAdapterOptions, type VueAdapterOptions, createHTMXStreamAdapter, createReactStreamAdapter, createSolidStreamAdapter, createStreamAdapter, createSvelteStreamAdapter, createVueStreamAdapter };

package/dist/streaming/adapters/index.js

@@ -0,0 +1,3 @@
+export { createHTMXStreamAdapter, createReactStreamAdapter, createSolidStreamAdapter, createStreamAdapter, createSvelteStreamAdapter, createVueStreamAdapter } from '../../chunk-MQQLYWZZ.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/streaming/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}