@flight-framework/core 0.1.0 → 0.2.1

package/dist/rsc/adapters/react.d.ts

@@ -0,0 +1,82 @@
+import * as react from 'react';
+import { ServerContext } from '../context.js';
+import { FlightElement, FlightChunk } from '../payload.js';
+import { UIAdapter } from '../renderer.js';
+
+/**
+ * Create React UI Adapter
+ *
+ * @example
+ * ```typescript
+ * import { createReactAdapter } from '@flight-framework/core/rsc/adapters/react';
+ * import { renderToString } from 'react-dom/server';
+ * import * as React from 'react';
+ *
+ * const adapter = createReactAdapter({
+ *   React,
+ *   renderToString,
+ * });
+ *
+ * const renderer = createRenderer(adapter);
+ * ```
+ */
+declare function createReactAdapter(deps?: {
+    /** React module (optional - for SSR) */
+    React?: {
+        isValidElement: (value: unknown) => boolean;
+        Children: {
+            toArray: (children: unknown) => unknown[];
+        };
+        Fragment: symbol;
+        Suspense: unknown;
+    };
+    /** renderToString function (optional - for SSR fallbacks) */
+    renderToString?: (element: unknown) => string;
+}): UIAdapter;
+/**
+ * Opciones para el consumer de React
+ */
+interface ReactConsumerOptions {
+    /** Registry de client components */
+    registry?: Map<string, () => Promise<unknown>>;
+    /** Callback when hydration completes */
+    onHydrate?: (id: string) => void;
+}
+/**
+ * Create a React client-side consumer for Flight payloads
+ *
+ * This reconstructs React elements from Flight chunks on the client.
+ */
+declare function createReactConsumer(deps: {
+    React: {
+        createElement: (type: unknown, props?: unknown, ...children: unknown[]) => unknown;
+        Suspense: unknown;
+        Fragment: unknown;
+        lazy: (factory: () => Promise<{
+            default: unknown;
+        }>) => unknown;
+    };
+}, options?: ReactConsumerOptions): {
+    /**
+     * Register a client component
+     */
+    register(id: string, loader: () => Promise<unknown>): void;
+    /**
+     * Convert Flight elements to React elements
+     */
+    toReactElement(element: FlightElement): unknown;
+    /**
+     * Process Flight chunks and build React tree
+     */
+    processChunks(chunks: FlightChunk[]): unknown;
+};
+/**
+ * Type helper for React Server Component
+ */
+type ReactServerComponent<P = Record<string, unknown>> = (props: P, ctx: ServerContext) => Promise<ReturnType<typeof react.createElement>> | ReturnType<typeof react.createElement>;
+/**
+ * Mark a component as a client component (for use without bundler transform)
+ */
+declare function markAsClientComponent<T extends (...args: unknown[]) => unknown>(component: T, moduleId: string, exportName?: string): T;
+
+export { type ReactConsumerOptions, type ReactServerComponent, createReactAdapter, createReactConsumer, markAsClientComponent };

package/dist/rsc/adapters/react.js

@@ -0,0 +1,3 @@
+export { createReactAdapter, createReactConsumer, markAsClientComponent } from '../../chunk-6Z2RYHEU.js';
+//# sourceMappingURL=react.js.map
+//# sourceMappingURL=react.js.map

package/dist/rsc/adapters/react.js.map

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

package/dist/rsc/adapters/solid.d.ts

@@ -0,0 +1,84 @@
+import { ServerContext } from '../context.js';
+import { FlightElement, FlightChunk } from '../payload.js';
+import { UIAdapter } from '../renderer.js';
+
+/**
+ * Solid dependencies (user provides these)
+ */
+interface SolidDependencies {
+    /** solid-js module */
+    solid: {
+        createSignal: <T>(value: T) => [() => T, (v: T) => void];
+        createMemo: <T>(fn: () => T) => () => T;
+        createEffect: (fn: () => void) => void;
+        children: (fn: () => unknown) => () => unknown[];
+        splitProps: <T extends object, K extends keyof T>(props: T, ...keys: K[][]) => [Pick<T, K>, Omit<T, K>][];
+        For?: unknown;
+        Show?: unknown;
+        Switch?: unknown;
+        Match?: unknown;
+        Suspense?: unknown;
+        ErrorBoundary?: unknown;
+    };
+    /** solid-js/web module */
+    web: {
+        render?: (code: () => unknown, element: Element) => () => void;
+        hydrate?: (code: () => unknown, element: Element) => () => void;
+        renderToString?: (code: () => unknown) => string;
+        renderToStringAsync?: (code: () => unknown) => Promise<string>;
+        isServer?: boolean;
+        Dynamic?: unknown;
+    };
+}
+/**
+ * Create Solid.js UI Adapter
+ *
+ * @example
+ * ```typescript
+ * import { createSolidAdapter } from '@flight-framework/core/rsc/adapters/solid';
+ * import * as solid from 'solid-js';
+ * import * as web from 'solid-js/web';
+ *
+ * const adapter = createSolidAdapter({ solid, web });
+ * const renderer = createRenderer(adapter);
+ * ```
+ */
+declare function createSolidAdapter(deps?: SolidDependencies): UIAdapter;
+/**
+ * Options for Solid consumer
+ */
+interface SolidConsumerOptions {
+    /** Registry of client components */
+    registry?: Map<string, () => Promise<unknown>>;
+}
+/**
+ * Create a Solid client-side consumer for Flight payloads
+ */
+declare function createSolidConsumer(deps: SolidDependencies, options?: SolidConsumerOptions): {
+    /**
+     * Register a client component
+     */
+    register(id: string, loader: () => Promise<unknown>): void;
+    /**
+     * Convert Flight elements to Solid JSX
+     */
+    toSolidElement(element: FlightElement): unknown;
+    /**
+     * Hydrate Flight payload into DOM
+     */
+    hydrate(chunks: FlightChunk[], container: Element): (() => void) | undefined;
+};
+/**
+ * Type helper for Solid Server Component
+ */
+type SolidServerComponent<P = Record<string, unknown>> = (props: P, ctx: ServerContext) => Promise<unknown> | unknown;
+/**
+ * Mark a Solid component as a client component
+ */
+declare function markAsSolidClientComponent<T extends object>(component: T, moduleId: string, exportName?: string): T;
+/**
+ * Check if running on server (Solid isServer helper)
+ */
+declare function isServer(deps?: SolidDependencies): boolean;
+
+export { type SolidConsumerOptions, type SolidDependencies, type SolidServerComponent, createSolidAdapter, createSolidConsumer, isServer, markAsSolidClientComponent };

package/dist/rsc/adapters/solid.js

@@ -0,0 +1,3 @@
+export { createSolidAdapter, createSolidConsumer, isServer, markAsSolidClientComponent } from '../../chunk-OCVLNLTI.js';
+//# sourceMappingURL=solid.js.map
+//# sourceMappingURL=solid.js.map

package/dist/rsc/adapters/solid.js.map

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

package/dist/rsc/adapters/vue.d.ts

@@ -0,0 +1,80 @@
+import { ServerContext } from '../context.js';
+import { FlightElement } from '../payload.js';
+import { UIAdapter } from '../renderer.js';
+
+/**
+ * Minimal Vue VNode interface
+ */
+interface VueVNode {
+    __v_isVNode?: boolean;
+    type: unknown;
+    props: Record<string, unknown> | null;
+    children: unknown;
+    key: string | number | null;
+    component?: unknown;
+    shapeFlag?: number;
+}
+/**
+ * Vue dependencies (user provides these)
+ */
+interface VueDependencies {
+    /** Vue module */
+    Vue: {
+        h: (type: unknown, props?: unknown, children?: unknown) => VueVNode;
+        isVNode: (value: unknown) => boolean;
+        createSSRApp?: (rootComponent: unknown) => unknown;
+        Fragment?: symbol;
+        Suspense?: unknown;
+        Text?: symbol;
+    };
+    /** renderToString from vue/server-renderer (optional - for SSR) */
+    renderToString?: (app: unknown) => Promise<string>;
+}
+/**
+ * Create Vue UI Adapter
+ *
+ * @example
+ * ```typescript
+ * import { createVueAdapter } from '@flight-framework/core/rsc/adapters/vue';
+ * import * as Vue from 'vue';
+ * import { renderToString } from 'vue/server-renderer';
+ *
+ * const adapter = createVueAdapter({
+ *   Vue,
+ *   renderToString,
+ * });
+ *
+ * const renderer = createRenderer(adapter);
+ * ```
+ */
+declare function createVueAdapter(deps?: VueDependencies): UIAdapter;
+/**
+ * Options for Vue consumer
+ */
+interface VueConsumerOptions {
+    /** Registry of client components */
+    registry?: Map<string, () => Promise<unknown>>;
+}
+/**
+ * Create a Vue client-side consumer for Flight payloads
+ */
+declare function createVueConsumer(deps: VueDependencies, options?: VueConsumerOptions): {
+    /**
+     * Register a client component
+     */
+    register(id: string, loader: () => Promise<unknown>): void;
+    /**
+     * Convert Flight elements to Vue VNodes
+     */
+    toVueElement(element: FlightElement): unknown;
+};
+/**
+ * Type helper for Vue Server Component
+ */
+type VueServerComponent<P = Record<string, unknown>> = (props: P, ctx: ServerContext) => Promise<VueVNode> | VueVNode;
+/**
+ * Mark a Vue component as a client component
+ */
+declare function markAsVueClientComponent<T extends object>(component: T, moduleId: string, exportName?: string): T;
+
+export { type VueConsumerOptions, type VueDependencies, type VueServerComponent, createVueAdapter, createVueConsumer, markAsVueClientComponent };

package/dist/rsc/adapters/vue.js

@@ -0,0 +1,3 @@
+export { createVueAdapter, createVueConsumer, markAsVueClientComponent } from '../../chunk-N3TUOEV4.js';
+//# sourceMappingURL=vue.js.map
+//# sourceMappingURL=vue.js.map

package/dist/rsc/adapters/vue.js.map

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

package/dist/rsc/boundaries.d.ts

@@ -0,0 +1,182 @@
+/**
+ * @flight-framework/core - Component Boundary Detection
+ *
+ * Sistema de detección de boundaries client/server para Server Components.
+ * Soporta directivas 'use client' y 'use server' tanto a nivel de archivo
+ * como inline en funciones.
+ *
+ * Filosofía Flight:
+ * - Detección en build-time (no runtime overhead)
+ * - Soporte para directivas estándar de React
+ * - Extensible para otros frameworks
+ * - Zero dependencies
+ *
+ * @module @flight-framework/core/rsc/boundaries
+ */
+/**
+ * Tipo de boundary de componente
+ */
+type BoundaryType = 'server' | 'client' | 'shared';
+/**
+ * Información de un boundary detectado
+ */
+interface ComponentBoundary {
+    /** Tipo de boundary */
+    type: BoundaryType;
+    /** ID del módulo (path relativo o absoluto) */
+    moduleId: string;
+    /** Nombre del export */
+    exportName: string;
+    /** Línea donde se detectó la directiva */
+    line?: number;
+    /** Es una directiva inline (dentro de función) */
+    inline?: boolean;
+    /** Metadata adicional */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Resultado del análisis de un módulo
+ */
+interface ModuleAnalysis {
+    /** Path del módulo */
+    moduleId: string;
+    /** Directiva a nivel de archivo ('use client' o 'use server') */
+    fileDirective?: 'client' | 'server';
+    /** Boundaries detectados */
+    boundaries: ComponentBoundary[];
+    /** Exports que son Server Actions */
+    serverActions: string[];
+    /** Exports que son Client Components */
+    clientComponents: string[];
+    /** El módulo tiene componentes async */
+    hasAsyncComponents: boolean;
+}
+/**
+ * Referencia a un Client Component
+ */
+interface ClientReference<T = unknown> {
+    $$typeof: symbol;
+    $$id: string;
+    $$async: boolean;
+    __flight_client: true;
+    __flight_module: string;
+    __flight_export: string;
+    (props: T extends (props: infer P) => unknown ? P : unknown): unknown;
+}
+/**
+ * Referencia a una Server Function (Action)
+ */
+interface ServerReference<T extends (...args: unknown[]) => unknown = (...args: unknown[]) => unknown> {
+    $$typeof: symbol;
+    $$id: string;
+    $$bound: unknown[] | null;
+    __flight_server: true;
+    __flight_action: string;
+    (...args: Parameters<T>): Promise<ReturnType<T>>;
+}
+declare const CLIENT_REFERENCE: unique symbol;
+declare const SERVER_REFERENCE: unique symbol;
+/**
+ * Detecta si un archivo tiene la directiva 'use client'
+ */
+declare function hasUseClientDirective(source: string): boolean;
+/**
+ * Detecta si un archivo tiene la directiva 'use server' a nivel de archivo
+ */
+declare function hasUseServerDirective(source: string): boolean;
+/**
+ * Detecta el tipo de componente basado en directivas
+ */
+declare function detectBoundaryType(source: string): BoundaryType;
+/**
+ * Detecta Server Actions inline en el código
+ * Busca funciones que contienen 'use server' dentro de su cuerpo
+ */
+declare function detectInlineServerActions(source: string): string[];
+/**
+ * Detecta componentes async (Server Components potenciales)
+ */
+declare function detectAsyncComponents(source: string): string[];
+/**
+ * Análisis completo de un módulo
+ */
+declare function analyzeModule(source: string, moduleId: string): ModuleAnalysis;
+/**
+ * Crea una referencia a un Client Component
+ * Para uso en build-time (transformación de código)
+ */
+declare function createClientReference<T>(moduleId: string, exportName: string, isAsync?: boolean): ClientReference<T>;
+/**
+ * Crea una referencia a una Server Function (Action)
+ * Para uso en build-time (transformación de código)
+ */
+declare function createServerReference<T extends (...args: unknown[]) => unknown>(actionId: string, boundArgs?: unknown[]): ServerReference<T>;
+/**
+ * Verifica si un valor es una Client Reference
+ */
+declare function isClientReference(value: unknown): value is ClientReference;
+/**
+ * Verifica si un valor es una Server Reference
+ */
+declare function isServerReference(value: unknown): value is ServerReference;
+/**
+ * Obtiene el ID de una referencia
+ */
+declare function getReferenceId(ref: ClientReference | ServerReference): string;
+/**
+ * Registry de boundaries para uso en runtime
+ */
+declare class BoundaryRegistry {
+    private clientModules;
+    private serverActions;
+    /**
+     * Registra un Client Component
+     */
+    registerClient(id: string, loader: () => Promise<unknown>): void;
+    /**
+     * Registra una Server Action
+     */
+    registerServer(id: string, action: (...args: unknown[]) => Promise<unknown>): void;
+    /**
+     * Obtiene un Client Component loader
+     */
+    getClient(id: string): (() => Promise<unknown>) | undefined;
+    /**
+     * Obtiene una Server Action
+     */
+    getServer(id: string): ((...args: unknown[]) => Promise<unknown>) | undefined;
+    /**
+     * Verifica si un client module está registrado
+     */
+    hasClient(id: string): boolean;
+    /**
+     * Verifica si una server action está registrada
+     */
+    hasServer(id: string): boolean;
+    /**
+     * Obtiene todos los IDs de client modules
+     */
+    getClientIds(): string[];
+    /**
+     * Obtiene todos los IDs de server actions
+     */
+    getServerIds(): string[];
+    /**
+     * Limpia el registry
+     */
+    clear(): void;
+}
+/**
+ * Registry global (singleton)
+ */
+declare const globalRegistry: BoundaryRegistry;
+/**
+ * Registra un Client Component en el registry global
+ */
+declare function registerClientComponent(id: string, loader: () => Promise<unknown>): void;
+/**
+ * Registra una Server Action en el registry global
+ */
+declare function registerServerAction(id: string, action: (...args: unknown[]) => Promise<unknown>): void;
+
+export { BoundaryRegistry, type BoundaryType, CLIENT_REFERENCE, type ClientReference, type ComponentBoundary, type ModuleAnalysis, SERVER_REFERENCE, type ServerReference, analyzeModule, createClientReference, createServerReference, detectAsyncComponents, detectBoundaryType, detectInlineServerActions, getReferenceId, globalRegistry, hasUseClientDirective, hasUseServerDirective, isClientReference, isServerReference, registerClientComponent, registerServerAction };

package/dist/rsc/boundaries.js

@@ -0,0 +1,3 @@
+export { BoundaryRegistry, CLIENT_REFERENCE, SERVER_REFERENCE, analyzeModule, createClientReference, createServerReference, detectAsyncComponents, detectBoundaryType, detectInlineServerActions, getReferenceId, globalRegistry, hasUseClientDirective, hasUseServerDirective, isClientReference, isServerReference, registerClientComponent, registerServerAction } from '../chunk-PDW5WCMW.js';
+//# sourceMappingURL=boundaries.js.map
+//# sourceMappingURL=boundaries.js.map

package/dist/rsc/boundaries.js.map

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

package/dist/rsc/context.d.ts

@@ -0,0 +1,201 @@
+/**
+ * @flight-framework/core - Server Context
+ *
+ * API de contexto para Server Components.
+ * Provee acceso a datos del request de forma explícita y type-safe.
+ *
+ * Filosofía Flight:
+ * - Contexto EXPLÍCITO (no magia con AsyncLocalStorage)
+ * - Pasado como argumento (testeable, predecible)
+ * - Extensible con adapters custom
+ * - Inmutable por defecto
+ *
+ * @module @flight-framework/core/rsc/context
+ */
+/**
+ * Contexto del servidor disponible en Server Components
+ */
+interface ServerContext {
+    /** Request actual (Web API Request) */
+    readonly request: Request;
+    /** Parámetros de ruta */
+    readonly params: Readonly<Record<string, string>>;
+    /** Search params de la URL */
+    readonly searchParams: URLSearchParams;
+    /** Headers del request */
+    readonly headers: Headers;
+    /** Accessor de cookies */
+    readonly cookies: CookieAccessor;
+    /** Headers de respuesta (mutables) */
+    readonly responseHeaders: Headers;
+    /** Signal para cancelación */
+    readonly signal: AbortSignal;
+    /** URL parseada */
+    readonly url: URL;
+    /** Método HTTP */
+    readonly method: string;
+    /** Context extensions (para adapters) */
+    readonly extensions: ContextExtensions;
+}
+/**
+ * Accessor para cookies con lazy parsing
+ */
+interface CookieAccessor {
+    /** Obtiene el valor de una cookie */
+    get(name: string): string | undefined;
+    /** Obtiene todas las cookies */
+    getAll(): Readonly<Record<string, string>>;
+    /** Verifica si existe una cookie */
+    has(name: string): boolean;
+}
+/**
+ * Extensiones del contexto para adapters
+ */
+interface ContextExtensions {
+    /** Obtiene una extensión */
+    get<T>(key: string): T | undefined;
+    /** Verifica si existe una extensión */
+    has(key: string): boolean;
+}
+/**
+ * Opciones para crear ServerContext
+ */
+interface ServerContextOptions {
+    /** Parámetros de ruta */
+    params?: Record<string, string>;
+    /** Extensiones custom */
+    extensions?: Record<string, unknown>;
+    /** Headers de respuesta iniciales */
+    responseHeaders?: HeadersInit;
+}
+/**
+ * Crea un ServerContext a partir de un Request
+ *
+ * @example
+ * ```typescript
+ * const ctx = createServerContext(request, {
+ *   params: { id: '123' }
+ * });
+ *
+ * // En un Server Component
+ * async function UserPage(props, ctx: ServerContext) {
+ *   const userId = ctx.params.id;
+ *   const user = await db.users.get(userId);
+ *   return <UserProfile user={user} />;
+ * }
+ * ```
+ */
+declare function createServerContext(request: Request, options?: ServerContextOptions): ServerContext;
+/**
+ * Obtiene un header del request
+ */
+declare function getHeader(ctx: ServerContext, name: string): string | null;
+/**
+ * Obtiene todos los headers como objeto
+ */
+declare function getHeaders(ctx: ServerContext): Record<string, string>;
+/**
+ * Verifica si el request es un POST/PUT/PATCH/DELETE (mutation request)
+ */
+declare function isMutationRequest(ctx: ServerContext): boolean;
+/**
+ * Verifica si el request acepta JSON
+ */
+declare function acceptsJson(ctx: ServerContext): boolean;
+/**
+ * Verifica si el request es AJAX/fetch
+ */
+declare function isAjaxRequest(ctx: ServerContext): boolean;
+/**
+ * Verifica si el request viene de un bot
+ */
+declare function isBotRequest(ctx: ServerContext): boolean;
+/**
+ * Verifica si el cliente soporta streaming
+ */
+declare function supportsStreaming(ctx: ServerContext): boolean;
+/**
+ * Obtiene el idioma preferido del cliente
+ */
+declare function getPreferredLanguage(ctx: ServerContext, available: string[]): string | undefined;
+/**
+ * Sets a cookie in the response
+ */
+declare function setCookie(ctx: ServerContext, name: string, value: string, options?: CookieOptions): void;
+/**
+ * Deletes a cookie
+ */
+declare function deleteCookie(ctx: ServerContext, name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void;
+/**
+ * Cookie options
+ */
+interface CookieOptions {
+    /** Max age in seconds */
+    maxAge?: number;
+    /** Expiration date */
+    expires?: Date;
+    /** Cookie path */
+    path?: string;
+    /** Cookie domain */
+    domain?: string;
+    /** HTTPS only */
+    secure?: boolean;
+    /** Not accessible via JavaScript */
+    httpOnly?: boolean;
+    /** SameSite attribute */
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+/**
+ * Sets cache control headers
+ */
+declare function setCacheControl(ctx: ServerContext, options: CacheControlOptions): void;
+/**
+ * Cache control options
+ */
+interface CacheControlOptions {
+    public?: boolean;
+    private?: boolean;
+    noCache?: boolean;
+    noStore?: boolean;
+    maxAge?: number;
+    sMaxAge?: number;
+    staleWhileRevalidate?: number;
+    staleIfError?: number;
+    mustRevalidate?: boolean;
+    immutable?: boolean;
+}
+/**
+ * Not found error - triggers 404 handling
+ */
+declare function notFound(message?: string): never;
+/**
+ * Check if error is a not found error
+ */
+declare function isNotFoundError(error: unknown): boolean;
+/**
+ * Redirect error - triggers redirect handling
+ */
+declare function redirect(url: string, status?: 301 | 302 | 303 | 307 | 308): never;
+/**
+ * Check if error is a redirect error
+ */
+declare function isRedirectError(error: unknown): error is Error & {
+    __flight_redirect: {
+        url: string;
+        status: number;
+    };
+};
+/**
+ * Get redirect info from error
+ */
+declare function getRedirectInfo(error: Error & {
+    __flight_redirect: {
+        url: string;
+        status: number;
+    };
+}): {
+    url: string;
+    status: number;
+};
+
+export { type CacheControlOptions, type ContextExtensions, type CookieAccessor, type CookieOptions, type ServerContext, type ServerContextOptions, acceptsJson, createServerContext, deleteCookie, getHeader, getHeaders, getPreferredLanguage, getRedirectInfo, isAjaxRequest, isBotRequest, isMutationRequest, isNotFoundError, isRedirectError, notFound, redirect, setCacheControl, setCookie, supportsStreaming };

package/dist/rsc/context.js

@@ -0,0 +1,3 @@
+export { acceptsJson, createServerContext, deleteCookie, getHeader, getHeaders, getPreferredLanguage, getRedirectInfo, isAjaxRequest, isBotRequest, isMutationRequest, isNotFoundError, isRedirectError, notFound, redirect, setCacheControl, setCookie, supportsStreaming } from '../chunk-62C7LX2E.js';
+//# sourceMappingURL=context.js.map
+//# sourceMappingURL=context.js.map

package/dist/rsc/context.js.map

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