@flight-framework/core 0.0.1 → 0.0.2

package/dist/index.d.ts

@@ -2,14 +2,569 @@ export { FlightConfig, FlightUserConfig, defineConfig } from './config/index.js'
 export { Route, RouteMatch, RouteParams, Router, createRouter } from './router/index.js';
 export { FlightServer, RouteHandler, RouteHandlerContext, ServerOptions, ServerRoute, createServer } from './server/index.js';
 export { RenderContext, RenderMode, RenderResult } from './render/index.js';
-export { Cache, CacheOptions, createCache } from './cache/index.js';
+import { CacheOptions, Cache } from './cache/index.js';
+export { createCache } from './cache/index.js';
 export { Middleware, MiddlewareContext, MiddlewareNext, createMiddlewareChain } from './middleware/index.js';
 export { AdapterBuilder, FlightAdapter } from './adapters/index.js';
 export { FileRoute, FileRouter, FileRouterOptions, ScanResult, createFileRouter, loadRoutes, scanRoutes } from './file-router/index.js';
 export { HttpMethod as FileHttpMethod, RouteHandler as FileRouteHandler, RouteHandlerContext as FileRouteHandlerContext, createRouteContext, error, json, parseBody, redirect } from './handlers/index.js';
 export { ActionResult, CookieOptions, RedirectError, ServerAction, redirect as actionRedirect, cookies, executeAction, executeFormAction, getAction, handleActionRequest, isRedirectError, parseFormData, registerAction } from './actions/index.js';
 export { StreamingRenderOptions, StreamingRenderResult, SuspenseBoundaryConfig, createLazyContent, createStreamingResponse, createStreamingSSR, renderWithStreaming, streamParallel, streamSequential } from './streaming/index.js';
-export { ClientComponent, ComponentType as RSCComponentType, RenderContext as RSCRenderContext, ServerComponent, composeComponents, createAsyncComponent, createClientBoundary, createRenderContext, deserializeProps, detectComponentType, executeServerComponent, hasUseClientDirective, hasUseServerDirective, isNotFoundError, isRedirectError as isRscRedirectError, notFound, revalidatePath, revalidateTag, redirect as rscRedirect, serializeProps, serverFetch, withErrorBoundary } from './rsc/index.js';
+export { ClientComponent, ComponentType as RSCComponentType, RenderContext as RSCRenderContext, ServerComponent, composeComponents, createAsyncComponent, createClientBoundary, createRenderContext, deserializeProps, detectComponentType, executeServerComponent, hasUseClientDirective, hasUseServerDirective, isNotFoundError, isRedirectError as isRscRedirectError, notFound, redirect as rscRedirect, revalidatePath as rscRevalidatePath, revalidateTag as rscRevalidateTag, serializeProps, serverFetch, withErrorBoundary } from './rsc/index.js';
+
+/**
+ * @flight-framework/core - Route Rules Configuration
+ *
+ * Nuxt-inspired route rules for per-route rendering configuration.
+ * Define SSR, SSG, ISR, SWR, and caching strategies per route pattern.
+ *
+ * @example
+ * ```typescript
+ * const routeRules: RouteRules = {
+ *     '/': { prerender: true },
+ *     '/blog': { isr: 3600 },
+ *     '/blog/**': { swr: 3600 },
+ *     '/admin/**': { ssr: false },
+ *     '/api/**': { cache: { ttl: 60 } }
+ * };
+ * ```
+ */
+
+/**
+ * Route rule configuration
+ */
+interface RouteRule {
+    /** Pre-render at build time (SSG) */
+    prerender?: boolean;
+    /**
+     * Stale-While-Revalidate caching
+     * - true: use default TTL
+     * - number: TTL in seconds
+     */
+    swr?: number | boolean;
+    /**
+     * Incremental Static Regeneration
+     * - true: regenerate on next deploy
+     * - number: revalidate every N seconds
+     */
+    isr?: number | boolean;
+    /**
+     * Enable/disable SSR for this route
+     * - false: client-side only rendering
+     */
+    ssr?: boolean;
+    /** Custom cache options */
+    cache?: CacheOptions;
+    /** Response headers to add */
+    headers?: Record<string, string>;
+    /** Redirect to another path */
+    redirect?: string | {
+        to: string;
+        statusCode?: 301 | 302 | 307 | 308;
+    };
+    /** CORS headers */
+    cors?: boolean | {
+        origin?: string | string[];
+        methods?: string[];
+        credentials?: boolean;
+    };
+    /** Cache tags for invalidation */
+    tags?: string[];
+}
+/**
+ * Route rules map - patterns to rules
+ * Supports glob patterns: **, *, [param]
+ */
+type RouteRules = Record<string, RouteRule>;
+/**
+ * Match a path against route rules and return the matching rule
+ */
+declare function matchRouteRule(path: string, rules: RouteRules): RouteRule | undefined;
+/**
+ * Merge multiple route rules (later rules override earlier)
+ */
+declare function mergeRouteRules(...rules: (RouteRule | undefined)[]): RouteRule;
+/**
+ * Get effective render mode from route rule
+ */
+declare function getRenderModeFromRule(rule: RouteRule): 'ssr' | 'ssg' | 'isr' | 'csr';
+/**
+ * Get revalidation time from rule (in seconds)
+ */
+declare function getRevalidateTime(rule: RouteRule): number | false;
+/**
+ * Get cache options from rule
+ */
+declare function getCacheOptionsFromRule(rule: RouteRule): CacheOptions | undefined;
+/**
+ * Build cache-control header from rule
+ */
+declare function buildCacheControlHeader(rule: RouteRule): string | undefined;
+/**
+ * Create default route rules
+ */
+declare function createDefaultRouteRules(): RouteRules;
+
+/**
+ * @flight-framework/core - On-Demand Revalidation
+ *
+ * APIs for on-demand cache invalidation and page revalidation.
+ * Similar to Next.js revalidatePath() and revalidateTag().
+ *
+ * @example
+ * ```typescript
+ * // In an API route
+ * import { revalidatePath, revalidateTag } from '@flight-framework/core';
+ *
+ * app.post('/api/revalidate', async (c) => {
+ *     const { path, tag } = await c.req.json();
+ *
+ *     if (path) await revalidatePath(path);
+ *     if (tag) await revalidateTag(tag);
+ *
+ *     return c.json({ revalidated: true });
+ * });
+ * ```
+ */
+
+/**
+ * ISR Cache entry for rendered pages
+ */
+interface ISRCacheEntry {
+    /** Rendered HTML content */
+    html: string;
+    /** HTTP status code */
+    status: number;
+    /** Response headers */
+    headers: Record<string, string>;
+    /** When this entry was generated */
+    generatedAt: number;
+    /** When this entry should be revalidated */
+    revalidateAfter?: number;
+    /** Cache tags for invalidation */
+    tags?: string[];
+}
+/**
+ * ISR Cache adapter interface
+ */
+interface ISRCacheAdapter {
+    /** Get cached page */
+    get(path: string): Promise<ISRCacheEntry | undefined>;
+    /** Set cached page */
+    set(path: string, entry: ISRCacheEntry, options?: CacheOptions): Promise<void>;
+    /** Delete cached page */
+    delete(path: string): Promise<boolean>;
+    /** Invalidate by tag */
+    invalidateTag(tag: string): Promise<void>;
+    /** Get all cached paths */
+    keys?(): Promise<string[]>;
+}
+/**
+ * Revalidation result
+ */
+interface RevalidationResult {
+    /** Whether revalidation was successful */
+    success: boolean;
+    /** Paths that were revalidated */
+    paths?: string[];
+    /** Error if failed */
+    error?: string;
+    /** Timestamp */
+    timestamp: number;
+}
+/**
+ * Set the global ISR cache adapter
+ */
+declare function setISRCache(cache: ISRCacheAdapter): void;
+/**
+ * Get the global ISR cache adapter
+ */
+declare function getISRCache(): ISRCacheAdapter | null;
+/**
+ * Create an in-memory ISR cache
+ */
+declare function createMemoryISRCache(): ISRCacheAdapter;
+/**
+ * Revalidate a specific path
+ * Removes the cached page so next request regenerates it
+ */
+declare function revalidatePath(path: string): Promise<RevalidationResult>;
+/**
+ * Revalidate all paths associated with a tag
+ */
+declare function revalidateTag(tag: string): Promise<RevalidationResult>;
+/**
+ * Revalidate multiple paths
+ */
+declare function revalidatePaths(paths: string[]): Promise<RevalidationResult>;
+interface RevalidateHandlerOptions {
+    /** Secret token for authentication */
+    secret?: string;
+    /** Header name for the secret */
+    headerName?: string;
+}
+/**
+ * Create a revalidation handler for API routes
+ *
+ * @example
+ * ```typescript
+ * import { createRevalidateHandler } from '@flight-framework/core';
+ *
+ * const handler = createRevalidateHandler({
+ *     secret: process.env.REVALIDATE_SECRET
+ * });
+ *
+ * app.post('/api/revalidate', handler);
+ * ```
+ */
+declare function createRevalidateHandler(options?: RevalidateHandlerOptions): (request: Request) => Promise<Response>;
+/**
+ * Create an ISR cache adapter from a Flight Cache instance
+ */
+declare function createISRCacheFromFlightCache(cache: Cache): ISRCacheAdapter;
+
+/**
+ * @flight-framework/core - Build-Time Prerender
+ *
+ * Static site generation build utilities.
+ * Pre-renders routes to HTML files at build time.
+ *
+ * @example
+ * ```typescript
+ * import { prerenderRoutes } from '@flight-framework/core';
+ *
+ * await prerenderRoutes({
+ *     routes: ['/','blog/hello', '/about'],
+ *     outDir: './dist',
+ *     renderFn: async (path) => await renderPage(path),
+ * });
+ * ```
+ */
+/**
+ * Options for prerendering routes
+ */
+interface PrerenderOptions {
+    /** Routes to prerender */
+    routes: string[] | (() => Promise<string[]>);
+    /** Output directory */
+    outDir: string;
+    /** Render function that generates HTML for a path */
+    renderFn: (path: string) => Promise<PrerenderResult>;
+    /** Concurrency limit */
+    concurrency?: number;
+    /** Progress callback */
+    onProgress?: (progress: PrerenderProgress) => void;
+    /** Error callback */
+    onError?: (error: PrerenderError) => void;
+    /** Whether to crawl links from rendered pages */
+    crawlLinks?: boolean;
+}
+/**
+ * Result from rendering a single page
+ */
+interface PrerenderResult {
+    /** HTML content */
+    html: string;
+    /** HTTP status code */
+    status?: number;
+    /** Response headers */
+    headers?: Record<string, string>;
+    /** Links found in the page (for crawling) */
+    links?: string[];
+}
+/**
+ * Progress callback data
+ */
+interface PrerenderProgress {
+    /** Current route being processed */
+    currentRoute: string;
+    /** Number of routes completed */
+    completed: number;
+    /** Total number of routes */
+    total: number;
+    /** Percentage complete */
+    percentage: number;
+}
+/**
+ * Error callback data
+ */
+interface PrerenderError {
+    /** Route that failed */
+    route: string;
+    /** Error message */
+    error: Error;
+}
+/**
+ * Summary of prerender operation
+ */
+interface PrerenderSummary {
+    /** Total routes processed */
+    total: number;
+    /** Successfully rendered routes */
+    success: number;
+    /** Failed routes */
+    failed: number;
+    /** Routes that were discovered via crawling */
+    discovered?: number;
+    /** Time taken in milliseconds */
+    duration: number;
+    /** List of generated files */
+    files: string[];
+    /** List of errors */
+    errors: PrerenderError[];
+}
+/**
+ * Prerender multiple routes to static HTML files
+ */
+declare function prerenderRoutes(options: PrerenderOptions): Promise<PrerenderSummary>;
+/**
+ * Extract internal links from HTML
+ */
+declare function extractLinks(html: string, baseUrl?: string): string[];
+/**
+ * Expand dynamic routes with static params
+ */
+declare function expandDynamicRoutes(routePattern: string, generateParams: () => Promise<Record<string, string | string[]>[]>): Promise<string[]>;
+
+/**
+ * @flight-framework/core - SSR/SSG/ISR Support
+ *
+ * Static site generation and incremental static regeneration.
+ * Similar to Next.js patterns.
+ */
+/**
+ * Static params for dynamic routes
+ */
+interface StaticParams {
+    [key: string]: string | string[];
+}
+/**
+ * Generate static params function signature
+ */
+type GenerateStaticParamsFunction = () => Promise<StaticParams[]> | StaticParams[];
+/**
+ * Page metadata
+ */
+interface PageMetadata {
+    title?: string;
+    description?: string;
+    keywords?: string[];
+    openGraph?: {
+        title?: string;
+        description?: string;
+        images?: string[];
+    };
+}
+/**
+ * Generate metadata function
+ */
+type GenerateMetadataFunction = (params: StaticParams) => Promise<PageMetadata> | PageMetadata;
+/**
+ * Page module exports
+ */
+interface PageModule {
+    default: (props: {
+        params: StaticParams;
+    }) => unknown;
+    generateStaticParams?: GenerateStaticParamsFunction;
+    generateMetadata?: GenerateMetadataFunction;
+    revalidate?: number | false;
+    dynamic?: 'auto' | 'force-dynamic' | 'error' | 'force-static';
+    runtime?: 'nodejs' | 'edge';
+}
+/**
+ * Generate all static paths for a page
+ */
+declare function generateAllStaticPaths(pageModules: Map<string, PageModule>): Promise<Map<string, StaticParams[]>>;
+/**
+ * Get or generate a cached page
+ */
+declare function getOrGeneratePage(path: string, generateFn: () => Promise<string>, revalidate?: number | false): Promise<{
+    html: string;
+    fromCache: boolean;
+}>;
+/**
+ * Purge cached page
+ */
+declare function purgePage(path: string): boolean;
+/**
+ * Purge all cached pages
+ */
+declare function purgeAllPages(): void;
+/**
+ * Check if a page should be dynamically rendered
+ */
+declare function shouldDynamicallyRender(module: PageModule, hasParams: boolean): boolean;
+/**
+ * Create a streaming response
+ */
+declare function createStreamingResponse(stream: ReadableStream<Uint8Array>): Response;
+/**
+ * Create a text encoder stream for HTML
+ */
+declare function createHtmlStream(): {
+    readable: ReadableStream<Uint8Array>;
+    write: (html: string) => void;
+    close: () => void;
+};
+
+/**
+ * @flight-framework/core - Metadata Rendering
+ *
+ * Utilities for rendering SEO metadata to HTML head tags.
+ * Following Next.js Metadata API patterns.
+ *
+ * @example
+ * ```typescript
+ * import { renderMetadataToHead } from '@flight-framework/core';
+ *
+ * const meta = {
+ *     title: 'My Page',
+ *     description: 'Page description',
+ *     openGraph: { title: 'OG Title', images: ['/og.jpg'] }
+ * };
+ *
+ * const headHtml = renderMetadataToHead(meta);
+ * ```
+ */
+/**
+ * Complete metadata interface for SEO
+ */
+interface Metadata {
+    /** Page title */
+    title?: string | {
+        default: string;
+        template?: string;
+    };
+    /** Meta description */
+    description?: string;
+    /** Keywords for SEO */
+    keywords?: string | string[];
+    /** Canonical URL */
+    canonical?: string;
+    /** Robots directives */
+    robots?: string | {
+        index?: boolean;
+        follow?: boolean;
+        nocache?: boolean;
+        googleBot?: {
+            index?: boolean;
+            follow?: boolean;
+            noimageindex?: boolean;
+        };
+    };
+    /** Open Graph metadata */
+    openGraph?: {
+        title?: string;
+        description?: string;
+        url?: string;
+        siteName?: string;
+        images?: string[] | Array<{
+            url: string;
+            width?: number;
+            height?: number;
+            alt?: string;
+        }>;
+        locale?: string;
+        type?: 'website' | 'article' | 'book' | 'profile';
+    };
+    /** Twitter Card metadata */
+    twitter?: {
+        card?: 'summary' | 'summary_large_image' | 'app' | 'player';
+        site?: string;
+        creator?: string;
+        title?: string;
+        description?: string;
+        images?: string[];
+    };
+    /** Favicon and icons */
+    icons?: {
+        icon?: string | string[];
+        apple?: string | string[];
+        shortcut?: string;
+    };
+    /** Alternate languages */
+    alternates?: {
+        canonical?: string;
+        languages?: Record<string, string>;
+    };
+    /** Verification tokens */
+    verification?: {
+        google?: string;
+        yandex?: string;
+        bing?: string;
+    };
+    /** Additional custom meta tags */
+    other?: Record<string, string>;
+}
+/**
+ * Render metadata to HTML head tags
+ */
+declare function renderMetadataToHead(meta: Metadata): string;
+/**
+ * Merge multiple metadata objects (later overrides earlier)
+ */
+declare function mergeMetadata(...metadataList: (Metadata | undefined)[]): Metadata;
+/**
+ * Type for generateMetadata function
+ */
+type GenerateMetadataFn<Params = Record<string, string>> = (props: {
+    params: Params;
+    searchParams?: Record<string, string>;
+}) => Metadata | Promise<Metadata>;
+/**
+ * Resolve metadata from a page module
+ */
+declare function resolveMetadata<Params = Record<string, string>>(pageModule: {
+    metadata?: Metadata;
+    generateMetadata?: GenerateMetadataFn<Params>;
+}, props: {
+    params: Params;
+    searchParams?: Record<string, string>;
+}): Promise<Metadata>;
+
+/**
+ * @flight-framework/core - Local DevTools
+ *
+ * Development-only debugging overlay.
+ * 100% LOCAL - NO telemetry, NO external requests, NO cloud.
+ *
+ * @example
+ * ```typescript
+ * import { injectDevTools } from '@flight-framework/core';
+ *
+ * const html = renderPage() + injectDevTools({ routes, renderTime });
+ * ```
+ */
+interface DevToolsOptions {
+    /** Current route path */
+    route?: string;
+    /** Render time in milliseconds */
+    renderTime?: number;
+    /** Rendering mode used */
+    renderMode?: 'ssr' | 'ssg' | 'isr' | 'csr';
+    /** Whether page is hydrated */
+    hydrated?: boolean;
+    /** Route params */
+    params?: Record<string, string>;
+    /** Cache status */
+    cacheStatus?: 'hit' | 'miss' | 'stale';
+    /** Custom data to display */
+    customData?: Record<string, unknown>;
+}
+/**
+ * Inject DevTools overlay into HTML
+ * Only works in development mode - returns empty string in production
+ */
+declare function injectDevTools(options?: DevToolsOptions): string;
+/**
+ * Check if DevTools should be enabled
+ */
+declare function isDevToolsEnabled(): boolean;
+/**
+ * Create DevTools data from request context
+ */
+declare function createDevToolsData(startTime: number, options?: Partial<DevToolsOptions>): DevToolsOptions;
 
 /**
  * Flight Framework - Core
@@ -20,4 +575,4 @@ export { ClientComponent, ComponentType as RSCComponentType, RenderContext as RS
 
 declare const VERSION = "0.0.1";
 
-export { VERSION };
+export { Cache, CacheOptions, type DevToolsOptions, type GenerateMetadataFn, type GenerateMetadataFunction, type GenerateStaticParamsFunction, type ISRCacheAdapter, type ISRCacheEntry, type Metadata, type PageMetadata, type PageModule, type PrerenderError, type PrerenderOptions, type PrerenderProgress, type PrerenderResult, type PrerenderSummary, type RevalidateHandlerOptions, type RevalidationResult, type RouteRule, type RouteRules, type StaticParams, VERSION, buildCacheControlHeader, createDefaultRouteRules, createDevToolsData, createHtmlStream, createISRCacheFromFlightCache, createMemoryISRCache, createRevalidateHandler, createStreamingResponse as createStaticStreamingResponse, expandDynamicRoutes, extractLinks, generateAllStaticPaths, getCacheOptionsFromRule, getISRCache, getOrGeneratePage, getRenderModeFromRule, getRevalidateTime, injectDevTools, isDevToolsEnabled, matchRouteRule, mergeMetadata, mergeRouteRules, prerenderRoutes, purgeAllPages, purgePage, renderMetadataToHead, resolveMetadata, revalidatePath, revalidatePaths, revalidateTag, setISRCache, shouldDynamicallyRender };