@flightdev/core 0.6.7

package/dist/rsc/payload.d.ts

@@ -0,0 +1,262 @@
+/**
+ * @flightdev/core - Flight Payload System
+ *
+ * Formato de serialización agnóstico para Server Components.
+ * Diseñado para máxima debuggabilidad y compatibilidad multi-framework.
+ *
+ * Filosofía Flight:
+ * - Formato documentado y abierto (NDJSON)
+ * - No depende de internals de React
+ * - Extensible para cualquier UI framework
+ * - Zero vendor lock-in
+ *
+ * @module @flightdev/core/rsc/payload
+ */
+/**
+ * Union type de todos los chunks que pueden enviarse en un FlightStream
+ */
+type FlightChunk = ServerComponentChunk | ClientReferenceChunk | ServerReferenceChunk | ErrorBoundaryChunk | HintChunk | MetaChunk;
+/**
+ * Chunk de Server Component renderizado
+ * Contiene el árbol virtual de elementos
+ */
+interface ServerComponentChunk {
+    /** Discriminator */
+    readonly type: 'S';
+    /** Unique chunk ID */
+    readonly id: string;
+    /** Virtual element tree */
+    readonly tree: FlightElement;
+    /** IDs de chunks que este depende (para streaming ordenado) */
+    readonly awaiting?: readonly string[];
+    /** Timestamp para debugging/observability */
+    readonly ts?: number;
+}
+/**
+ * Referencia a un Client Component
+ * El cliente cargará el módulo y lo hidratará
+ */
+interface ClientReferenceChunk {
+    /** Discriminator */
+    readonly type: 'C';
+    /** Reference ID */
+    readonly id: string;
+    /** Module specifier (relativo al manifest) */
+    readonly module: string;
+    /** Export name */
+    readonly export: string;
+    /** Serialized props */
+    readonly props: SerializedValue;
+    /** Fallback HTML para SSR (opcional) */
+    readonly fallback?: string;
+}
+/**
+ * Referencia a una Server Function (Action)
+ * El cliente la invocará via RPC
+ */
+interface ServerReferenceChunk {
+    /** Discriminator */
+    readonly type: 'A';
+    /** Action ID */
+    readonly id: string;
+    /** Bound arguments (pre-bound via .bind()) */
+    readonly bound?: readonly SerializedValue[];
+}
+/**
+ * Error en un boundary específico
+ */
+interface ErrorBoundaryChunk {
+    /** Discriminator */
+    readonly type: 'E';
+    /** Boundary ID where error occurred */
+    readonly boundary: string;
+    /** Safe error message for client */
+    readonly message: string;
+    /** Error digest for server-side correlation */
+    readonly digest: string;
+    /** Component stack for development */
+    readonly stack?: string;
+}
+/**
+ * Hints para el cliente (preload, prefetch, etc.)
+ */
+interface HintChunk {
+    /** Discriminator */
+    readonly type: 'H';
+    /** Hint type */
+    readonly hint: 'preload' | 'prefetch' | 'dns-prefetch' | 'preconnect' | 'modulepreload';
+    /** Resource URL */
+    readonly href: string;
+    /** Resource type (for preload) */
+    readonly as?: 'script' | 'style' | 'image' | 'font' | 'fetch';
+    /** Crossorigin attribute */
+    readonly crossorigin?: 'anonymous' | 'use-credentials';
+}
+/**
+ * Metadata chunk (para SSR head injection)
+ */
+interface MetaChunk {
+    /** Discriminator */
+    readonly type: 'M';
+    /** Meta type */
+    readonly meta: 'title' | 'description' | 'og' | 'twitter' | 'link' | 'script';
+    /** Content */
+    readonly content: string | Record<string, string>;
+}
+/**
+ * Virtual element que puede representar cualquier UI framework
+ */
+type FlightElement = FlightHostElement | FlightTextElement | FlightFragmentElement | FlightSuspenseElement | FlightClientElement | FlightLazyElement | FlightNullElement;
+/**
+ * Host element (div, span, etc.)
+ */
+interface FlightHostElement {
+    readonly $$type: 'host';
+    readonly tag: string;
+    readonly key?: string | number;
+    readonly props: Readonly<Record<string, SerializedValue>>;
+    readonly children: readonly FlightElement[];
+}
+/**
+ * Text node
+ */
+interface FlightTextElement {
+    readonly $$type: 'text';
+    readonly value: string;
+}
+/**
+ * Fragment (multiple children, no wrapper)
+ */
+interface FlightFragmentElement {
+    readonly $$type: 'fragment';
+    readonly children: readonly FlightElement[];
+}
+/**
+ * Suspense boundary
+ */
+interface FlightSuspenseElement {
+    readonly $$type: 'suspense';
+    readonly id: string;
+    readonly fallback: FlightElement;
+    readonly children: readonly FlightElement[];
+}
+/**
+ * Client component reference
+ */
+interface FlightClientElement {
+    readonly $$type: 'client';
+    /** Reference to ClientReferenceChunk ID */
+    readonly ref: string;
+    /** Pre-rendered fallback HTML */
+    readonly ssr?: string;
+}
+/**
+ * Lazy/async element (pending resolution)
+ */
+interface FlightLazyElement {
+    readonly $$type: 'lazy';
+    readonly id: string;
+    readonly fallback?: FlightElement;
+}
+/**
+ * Null/empty element
+ */
+interface FlightNullElement {
+    readonly $$type: 'null';
+}
+/**
+ * Valores que pueden cruzar el boundary server/client
+ */
+type SerializedValue = string | number | boolean | null | undefined | readonly SerializedValue[] | {
+    readonly [key: string]: SerializedValue;
+} | SerializedSpecialValue;
+/**
+ * Tipos especiales que requieren serialización custom
+ */
+interface SerializedSpecialValue {
+    readonly $$flight: SpecialValueType;
+    readonly value: string | readonly unknown[];
+}
+type SpecialValueType = 'date' | 'bigint' | 'map' | 'set' | 'undefined' | 'symbol' | 'regexp' | 'url' | 'error' | 'formdata' | 'blob' | 'arraybuffer';
+/**
+ * Serializa un valor para transmisión a través de FlightStream
+ */
+declare function serialize(value: unknown): SerializedValue;
+/**
+ * Deserializa un valor recibido de FlightStream
+ */
+declare function deserialize<T = unknown>(value: SerializedValue): T;
+/**
+ * Create a host element
+ */
+declare function h(tag: string, props: Record<string, unknown> | null, ...children: unknown[]): FlightHostElement;
+/**
+ * Create a text element
+ */
+declare function text(value: string): FlightTextElement;
+/**
+ * Create a fragment
+ */
+declare function fragment(...children: unknown[]): FlightFragmentElement;
+/**
+ * Create a suspense boundary
+ */
+declare function suspense(id: string, fallback: FlightElement, children: FlightElement[]): FlightSuspenseElement;
+/**
+ * Create a client component reference
+ */
+declare function clientRef(refId: string, ssrHtml?: string): FlightClientElement;
+/**
+ * Convert any value to a FlightElement
+ */
+declare function toFlightElement(value: unknown): FlightElement;
+/**
+ * Type guard for FlightElement
+ */
+declare function isFlightElement(value: unknown): value is FlightElement;
+/**
+ * Generate unique chunk ID
+ */
+declare function generateChunkId(prefix?: string): string;
+/**
+ * Reset chunk ID counter (for testing)
+ */
+declare function resetChunkIdCounter(): void;
+/**
+ * Create a server component chunk
+ */
+declare function createServerChunk(id: string, tree: FlightElement, awaiting?: string[]): ServerComponentChunk;
+/**
+ * Create a client reference chunk
+ */
+declare function createClientChunk(id: string, module: string, exportName: string, props: unknown, fallback?: string): ClientReferenceChunk;
+/**
+ * Create a server reference (action) chunk
+ */
+declare function createActionChunk(id: string, boundArgs?: unknown[]): ServerReferenceChunk;
+/**
+ * Create an error chunk
+ */
+declare function createErrorChunk(boundary: string, error: Error, includeStack?: boolean): ErrorBoundaryChunk;
+/**
+ * Create a hint chunk
+ */
+declare function createHintChunk(hint: HintChunk['hint'], href: string, options?: {
+    as?: HintChunk['as'];
+    crossorigin?: HintChunk['crossorigin'];
+}): HintChunk;
+/**
+ * Error thrown during serialization
+ */
+declare class FlightSerializationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown during payload processing
+ */
+declare class FlightPayloadError extends Error {
+    readonly chunk?: FlightChunk | undefined;
+    constructor(message: string, chunk?: FlightChunk | undefined);
+}
+
+export { type ClientReferenceChunk, type ErrorBoundaryChunk, type FlightChunk, type FlightClientElement, type FlightElement, type FlightFragmentElement, type FlightHostElement, type FlightLazyElement, type FlightNullElement, FlightPayloadError, FlightSerializationError, type FlightSuspenseElement, type FlightTextElement, type HintChunk, type MetaChunk, type SerializedSpecialValue, type SerializedValue, type ServerComponentChunk, type ServerReferenceChunk, type SpecialValueType, clientRef, createActionChunk, createClientChunk, createErrorChunk, createHintChunk, createServerChunk, deserialize, fragment, generateChunkId, h, isFlightElement, resetChunkIdCounter, serialize, suspense, text, toFlightElement };

package/dist/rsc/payload.js

@@ -0,0 +1,3 @@
+export { FlightPayloadError, FlightSerializationError, clientRef, createActionChunk, createClientChunk, createErrorChunk, createHintChunk, createServerChunk, deserialize, fragment, generateChunkId, h, isFlightElement, resetChunkIdCounter, serialize, suspense, text, toFlightElement } from '../chunk-7CNW24MQ.js';
+//# sourceMappingURL=payload.js.map
+//# sourceMappingURL=payload.js.map

package/dist/rsc/payload.js.map

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

package/dist/rsc/plugins/esbuild.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @flightdev/core - esbuild Plugin for RSC
+ *
+ * esbuild plugin for Flight Server Components.
+ * Transforms 'use client' and 'use server' directives at build time.
+ *
+ * Philosophy: Zero lock-in - esbuild is optional, user decides bundler.
+ *
+ * @module @flightdev/core/rsc/plugins/esbuild
+ */
+/**
+ * esbuild Plugin interface (minimal)
+ * We define our own to avoid requiring esbuild as dependency
+ */
+interface EsbuildPlugin {
+    name: string;
+    setup: (build: EsbuildBuild) => void | Promise<void>;
+}
+interface EsbuildBuild {
+    initialOptions: EsbuildBuildOptions;
+    onStart: (callback: () => void | Promise<void>) => void;
+    onEnd: (callback: (result: EsbuildResult) => void | Promise<void>) => void;
+    onResolve: (options: {
+        filter: RegExp;
+        namespace?: string;
+    }, callback: (args: EsbuildResolveArgs) => EsbuildResolveResult | null | undefined | Promise<EsbuildResolveResult | null | undefined>) => void;
+    onLoad: (options: {
+        filter: RegExp;
+        namespace?: string;
+    }, callback: (args: EsbuildLoadArgs) => EsbuildLoadResult | null | undefined | Promise<EsbuildLoadResult | null | undefined>) => void;
+}
+interface EsbuildBuildOptions {
+    outdir?: string;
+    write?: boolean;
+    metafile?: boolean;
+}
+interface EsbuildResult {
+    errors: unknown[];
+    warnings: unknown[];
+    metafile?: unknown;
+}
+interface EsbuildResolveArgs {
+    path: string;
+    importer: string;
+    namespace: string;
+    resolveDir: string;
+    kind: string;
+}
+interface EsbuildResolveResult {
+    path?: string;
+    external?: boolean;
+    namespace?: string;
+    suffix?: string;
+    pluginData?: unknown;
+    errors?: unknown[];
+    warnings?: unknown[];
+    watchFiles?: string[];
+    watchDirs?: string[];
+}
+interface EsbuildLoadArgs {
+    path: string;
+    namespace: string;
+    suffix: string;
+    pluginData: unknown;
+}
+interface EsbuildLoadResult {
+    contents?: string;
+    loader?: 'js' | 'jsx' | 'ts' | 'tsx' | 'json' | 'text' | 'css';
+    resolveDir?: string;
+    errors?: unknown[];
+    warnings?: unknown[];
+    watchFiles?: string[];
+    watchDirs?: string[];
+}
+/**
+ * Plugin configuration
+ */
+interface FlightEsbuildPluginOptions {
+    /** Include patterns (regex) */
+    include?: RegExp;
+    /** Exclude patterns (regex) */
+    exclude?: RegExp;
+    /** Server actions endpoint */
+    actionsEndpoint?: string;
+    /** Output directory for manifests */
+    manifestDir?: string;
+    /** Is this for SSR build? */
+    ssr?: boolean;
+    /** Dev mode (include extra debug info) */
+    dev?: boolean;
+}
+/**
+ * Manifest entry
+ */
+interface ManifestEntry {
+    id: string;
+    file: string;
+    exports: string[];
+}
+/**
+ * Flight RSC esbuild Plugin
+ *
+ * @example
+ * ```typescript
+ * // build.js
+ * import * as esbuild from 'esbuild';
+ * import { flightRSCEsbuild } from '@flightdev/core/rsc/plugins/esbuild';
+ *
+ * await esbuild.build({
+ *   entryPoints: ['src/index.tsx'],
+ *   bundle: true,
+ *   outdir: 'dist',
+ *   plugins: [
+ *     flightRSCEsbuild({
+ *       actionsEndpoint: '/_flight/action',
+ *       ssr: true,
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare function flightRSCEsbuild(options?: FlightEsbuildPluginOptions): EsbuildPlugin;
+
+export { type EsbuildBuild, type EsbuildBuildOptions, type EsbuildLoadArgs, type EsbuildLoadResult, type EsbuildPlugin, type EsbuildResolveArgs, type EsbuildResolveResult, type EsbuildResult, type FlightEsbuildPluginOptions, type ManifestEntry, flightRSCEsbuild as default, flightRSCEsbuild };

package/dist/rsc/plugins/esbuild.js

@@ -0,0 +1,4 @@
+export { esbuild_default as default, flightRSCEsbuild } from '../../chunk-MCL2MCA2.js';
+import '../../chunk-AP5NLUSB.js';
+//# sourceMappingURL=esbuild.js.map
+//# sourceMappingURL=esbuild.js.map

package/dist/rsc/plugins/esbuild.js.map

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

package/dist/rsc/plugins/index.d.ts

@@ -0,0 +1,4 @@
+export { ClientManifestEntry, FlightRSCPluginOptions as FlightVitePluginOptions, ServerManifestEntry, default as flightRSCVite } from '../vite-plugin.js';
+export { EsbuildBuild, EsbuildLoadArgs, EsbuildLoadResult, EsbuildPlugin, EsbuildResolveArgs, EsbuildResolveResult, FlightEsbuildPluginOptions, ManifestEntry, default as flightRSCEsbuild } from './esbuild.js';
+export { FlightRollupPluginOptions, RollupPlugin, RollupPluginContext, default as flightRSCRollup } from './rollup.js';
+import 'vite';

package/dist/rsc/plugins/index.js

@@ -0,0 +1,6 @@
+export { flightRSCEsbuild } from '../../chunk-MCL2MCA2.js';
+export { flightRSCRollup } from '../../chunk-7WIEAUJT.js';
+export { flightRSC as flightRSCVite } from '../../chunk-63LWTEDQ.js';
+import '../../chunk-AP5NLUSB.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/rsc/plugins/index.js.map

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

package/dist/rsc/plugins/rollup.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @flightdev/core - Rollup Plugin for RSC
+ *
+ * Rollup plugin for Flight Server Components.
+ * Transforms 'use client' and 'use server' directives at build time.
+ *
+ * Philosophy: Zero lock-in - Rollup is optional, user decides bundler.
+ *
+ * @module @flightdev/core/rsc/plugins/rollup
+ */
+/**
+ * Rollup Plugin interface (minimal)
+ * We define our own to avoid requiring rollup as dependency
+ */
+interface RollupPlugin {
+    name: string;
+    buildStart?: (options: unknown) => void | Promise<void>;
+    resolveId?: (source: string, importer: string | undefined, options: {
+        isEntry: boolean;
+    }) => string | null | undefined | {
+        id: string;
+        external?: boolean;
+    } | Promise<string | null | undefined | {
+        id: string;
+        external?: boolean;
+    }>;
+    load?: (id: string) => string | null | undefined | {
+        code: string;
+        map?: unknown;
+    } | Promise<string | null | undefined | {
+        code: string;
+        map?: unknown;
+    }>;
+    transform?: (code: string, id: string) => string | null | undefined | {
+        code: string;
+        map?: unknown;
+    } | Promise<string | null | undefined | {
+        code: string;
+        map?: unknown;
+    }>;
+    generateBundle?: (options: unknown, bundle: Record<string, unknown>) => void | Promise<void>;
+    buildEnd?: (error?: Error) => void | Promise<void>;
+}
+interface RollupPluginContext {
+    emitFile: (file: {
+        type: 'asset' | 'chunk';
+        fileName?: string;
+        source?: string;
+        id?: string;
+    }) => string;
+    warn: (message: string) => void;
+    error: (message: string) => never;
+}
+/**
+ * Plugin configuration
+ */
+interface FlightRollupPluginOptions {
+    /** Include patterns (regex or function) */
+    include?: RegExp | ((id: string) => boolean);
+    /** Exclude patterns (regex or function) */
+    exclude?: RegExp | ((id: string) => boolean);
+    /** Server actions endpoint */
+    actionsEndpoint?: string;
+    /** Client manifest filename */
+    clientManifest?: string;
+    /** Server manifest filename */
+    serverManifest?: string;
+    /** Is this for SSR build? */
+    ssr?: boolean;
+    /** Dev mode */
+    dev?: boolean;
+}
+/**
+ * Manifest entry
+ */
+interface ManifestEntry {
+    id: string;
+    file: string;
+    exports: string[];
+}
+/**
+ * Flight RSC Rollup Plugin
+ *
+ * @example
+ * ```typescript
+ * // rollup.config.js
+ * import { flightRSCRollup } from '@flightdev/core/rsc/plugins/rollup';
+ *
+ * export default {
+ *   input: 'src/index.tsx',
+ *   output: { dir: 'dist', format: 'esm' },
+ *   plugins: [
+ *     flightRSCRollup({
+ *       ssr: true,
+ *       actionsEndpoint: '/_flight/action',
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+declare function flightRSCRollup(options?: FlightRollupPluginOptions): RollupPlugin;
+
+export { type FlightRollupPluginOptions, type ManifestEntry, type RollupPlugin, type RollupPluginContext, flightRSCRollup as default, flightRSCRollup };

package/dist/rsc/plugins/rollup.js

@@ -0,0 +1,4 @@
+export { rollup_default as default, flightRSCRollup } from '../../chunk-7WIEAUJT.js';
+import '../../chunk-AP5NLUSB.js';
+//# sourceMappingURL=rollup.js.map
+//# sourceMappingURL=rollup.js.map

package/dist/rsc/plugins/rollup.js.map

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

package/dist/rsc/renderer.d.ts

@@ -0,0 +1,162 @@
+import { FlightChunk, ServerComponentChunk, ClientReferenceChunk } from './payload.js';
+import { ServerContext } from './context.js';
+
+/**
+ * @flightdev/core - Server Component Renderer
+ *
+ * Renders Server Components to FlightChunks.
+ * Framework-agnostic rendering engine that works with adapters.
+ *
+ * @module @flightdev/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;
+    /**
+     * Create a framework-specific element
+     * This abstracts away React's Symbol.for('react.element'), Vue's VNode, etc.
+     */
+    createElement(component: ComponentFn, props: Record<string, unknown>): unknown;
+    /** 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>;
+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 };