@useavalon/avalon 0.1.23 → 0.1.24

package/dist/src/nitro/renderer.d.ts

@@ -0,0 +1,342 @@
+/**
+ * Nitro SSR Renderer Handler for Avalon
+ *
+ * This module provides the main SSR renderer for Nitro integration.
+ * It handles page rendering using Avalon's existing SSR pipeline while
+ * integrating with Nitro's h3 event handling system.
+ *
+ * The renderer acts as a catch-all handler for Nitro - it receives requests
+ * that don't match any API routes or static files, and renders the appropriate
+ * page using Avalon's SSR pipeline.
+ *
+ * Key design principle: This renderer relies on Nitro's built-in file-system
+ * routing for route matching. Custom route matching logic has been removed
+ * in favor of Nitro's native capabilities.
+ *
+ * Middleware Integration:
+ * - Global middleware runs first (handled by Nitro's middleware/ directory)
+ * - Route-scoped middleware runs after global middleware, before page rendering
+ * - If global middleware terminates, route-scoped middleware does not run
+ *
+ * Custom Error Pages:
+ * - Supports custom 404 page (src/pages/404.tsx)
+ * - Supports custom 500 page (src/pages/500.tsx)
+ * - Supports generic error page (src/pages/_error.tsx)
+ *
+ * Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 5.1, 5.3, 9.1, 9.2, 9.3, 9.4, 10.5
+ */
+import type { NitroRenderContext, SSRRenderOptions, SSRRenderResult, PageModule, AvalonRuntimeConfig, HttpError } from './types.ts';
+import type { H3Event } from 'h3';
+/**
+ * Resolved page route information
+ */
+export interface ResolvedPageRoute {
+    /** File path to the page module */
+    filePath: string;
+    /** Route pattern that matched */
+    pattern: string;
+    /** Extracted route parameters */
+    params: Record<string, string>;
+    /** Layout files to apply (outermost first) */
+    layouts?: string[];
+}
+/**
+ * Render handler options
+ *
+ * Simplified for Nitro's catch-all pattern - route resolution is now
+ * handled by Nitro's file-system routing, so custom resolvers are optional
+ * and primarily used for development/testing scenarios.
+ */
+export interface RenderHandlerOptions {
+    /** Avalon runtime configuration */
+    avalonConfig: AvalonRuntimeConfig;
+    /** Whether running in development mode */
+    isDev?: boolean;
+    /** Vite dev server URL for development */
+    viteServerUrl?: string;
+    /**
+     * Custom page resolver function (optional)
+     * In production, Nitro handles route resolution via file-system routing.
+     * This is primarily used for development with Vite's SSR module loading.
+     */
+    resolvePageRoute?: (pathname: string, pagesDir: string) => Promise<ResolvedPageRoute | null>;
+    /**
+     * Custom page module loader (optional)
+     * In production, modules are loaded from the build output.
+     * In development, Vite's ssrLoadModule is used.
+     */
+    loadPageModule?: (filePath: string) => Promise<PageModule>;
+    /** Custom layout resolver */
+    resolveLayouts?: (routePath: string, config: AvalonRuntimeConfig) => Promise<string[]>;
+    /**
+     * Enable custom error pages (404.tsx, 500.tsx, _error.tsx)
+     * When enabled, the renderer will look for custom error pages in the pages directory
+     * Requirements: 10.5
+     */
+    enableCustomErrorPages?: boolean;
+}
+/**
+ * Creates a render context from an H3 event
+ *
+ * @param event - The H3 event from Nitro
+ * @param params - Route parameters extracted from the URL
+ * @returns NitroRenderContext for use in rendering
+ */
+export declare function createRenderContext(event: H3Event, params?: Record<string, string>): NitroRenderContext;
+/**
+ * Gets the request URL from an H3 event
+ */
+export declare function getRequestURL(event: H3Event): URL;
+/**
+ * Converts an H3 event to a standard Request object
+ */
+export declare function toRequest(event: H3Event): Request;
+/**
+ * Gets request headers from an H3 event
+ */
+export declare function getRequestHeaders(event: H3Event): Headers;
+/**
+ * Sets a response header on an H3 event
+ */
+export declare function setResponseHeader(event: H3Event, name: string, value: string): void;
+/**
+ * Creates an error response
+ */
+export declare function createErrorResponse(error: Error | HttpError, isDev: boolean): Response;
+/**
+ * Island hydration marker information
+ */
+export interface IslandMarker {
+    /** Framework identifier (react, vue, svelte, etc.) */
+    framework: string;
+    /** Source path to the island module */
+    src: string;
+    /** Serialized props for the island */
+    props?: string;
+    /** Hydration strategy (load, idle, visible, media) */
+    hydrate?: string;
+}
+/**
+ * Extracts island markers from HTML
+ * Requirements: 9.1, 9.2, 9.3
+ *
+ * @param html - The rendered HTML string
+ * @returns Array of island markers found in the HTML
+ */
+export declare function extractIslandMarkers(html: string): IslandMarker[];
+/**
+ * Ensures all required hydration markers are present on an island element
+ * Requirements: 9.1, 9.2, 9.3
+ *
+ * @param element - The island element HTML string
+ * @param marker - The island marker data to ensure
+ * @returns The element with all required markers
+ */
+export declare function ensureHydrationMarkers(element: string, marker: Partial<IslandMarker>): string;
+/**
+ * Injects the client hydration script into HTML
+ * Requirements: 2.6, 9.4
+ *
+ * This function:
+ * 1. Checks if there are islands that need hydration
+ * 2. Injects the client script before </body> if not already present
+ * 3. Supports both development and production script paths
+ *
+ * @param html - The rendered HTML string
+ * @param isDev - Whether running in development mode
+ * @param options - Additional injection options
+ * @returns HTML with hydration script injected
+ */
+export declare function injectHydrationScript(html: string, isDev: boolean, options?: {
+    /** Custom script path override */
+    scriptPath?: string;
+    /** Additional scripts to inject */
+    additionalScripts?: string[];
+    /** Whether to force injection even without islands */
+    forceInject?: boolean;
+}): string;
+/**
+ * Validates that hydration markers are present in the HTML
+ * Requirements: 2.3, 9.1, 9.2, 9.3
+ *
+ * @param html - The rendered HTML string
+ * @returns Object with validation results
+ */
+export declare function validateHydrationMarkers(html: string): {
+    hasFrameworkAttr: boolean;
+    hasSrcAttr: boolean;
+    hasPropsAttr: boolean;
+    islandCount: number;
+    islands: IslandMarker[];
+    hasClientScript: boolean;
+    isValid: boolean;
+};
+/**
+ * Processes HTML to ensure all hydration requirements are met
+ * Requirements: 2.3, 2.6, 9.1, 9.2, 9.3, 9.4
+ *
+ * This is a convenience function that:
+ * 1. Validates existing hydration markers
+ * 2. Injects the client script if needed
+ * 3. Returns the processed HTML
+ *
+ * @param html - The rendered HTML string
+ * @param isDev - Whether running in development mode
+ * @returns Processed HTML with all hydration requirements met
+ */
+export declare function processHydrationRequirements(html: string, isDev: boolean): {
+    html: string;
+    validation: ReturnType<typeof validateHydrationMarkers>;
+};
+/**
+ * Renders a page to HTML string (non-streaming)
+ * Requirements: 2.1, 2.2
+ *
+ * @param pageModule - The page module to render
+ * @param context - The render context
+ * @param options - Render options
+ * @returns SSR render result
+ */
+export declare function renderPage(pageModule: PageModule, context: NitroRenderContext, options?: SSRRenderOptions): Promise<SSRRenderResult>;
+/**
+ * Extended streaming options with additional callbacks
+ */
+export interface StreamingSSROptions extends SSRRenderOptions {
+    /** Callback when shell rendering fails before streaming starts */
+    onShellError?: (error: Error) => void;
+    /** Timeout for shell ready in milliseconds */
+    shellReadyTimeout?: number;
+    /** Timeout for all content ready in milliseconds */
+    allReadyTimeout?: number;
+}
+/**
+ * Renders a page to a streaming response
+ * Requirements: 2.4
+ *
+ * This function implements streaming SSR with proper shell/content separation:
+ * 1. Shell (DOCTYPE, html, head, body opening) is sent first
+ * 2. onShellReady callback is invoked when shell is ready
+ * 3. Page content is streamed progressively
+ * 4. onAllReady callback is invoked when all content is complete
+ *
+ * @param pageModule - The page module to render
+ * @param context - The render context
+ * @param options - Render options including streaming callbacks
+ * @returns ReadableStream of HTML chunks
+ */
+export declare function renderPageStream(pageModule: PageModule, context: NitroRenderContext, options?: StreamingSSROptions): Promise<ReadableStream<Uint8Array>>;
+/**
+ * Creates a streaming response with proper headers
+ * Requirements: 2.4
+ *
+ * @param stream - The ReadableStream to wrap
+ * @param options - Additional response options
+ * @returns Response object with streaming body
+ */
+export declare function createStreamingResponse(stream: ReadableStream<Uint8Array>, options?: {
+    status?: number;
+    headers?: Record<string, string>;
+}): Response;
+/**
+ * Creates the main Nitro renderer handler
+ *
+ * This is the catch-all handler for Nitro that renders pages not matched
+ * by API routes or static files. It integrates with Nitro's routing system:
+ *
+ * 1. Nitro's file-system routing handles API routes (api/ directory)
+ * 2. Nitro's static asset handling serves files from public/
+ * 3. This renderer catches all remaining requests for SSR page rendering
+ *
+ * Middleware execution order:
+ * 1. Global middleware (from middleware/ directory) - handled by Nitro
+ * 2. Route-scoped middleware (from _middleware.ts files) - handled here
+ * 3. Page rendering
+ *
+ * If global middleware terminates the chain, this handler is not called.
+ * If route-scoped middleware terminates, page rendering is skipped.
+ *
+ * The renderer relies on Nitro's event context for route information when
+ * available, falling back to pathname-based resolution for development.
+ *
+ * Requirements: 2.1, 2.2, 2.4, 5.1, 5.3, 10.5
+ *
+ * @param options - Render handler options
+ * @returns Handler function for Nitro
+ */
+export declare function createNitroRenderer(options: RenderHandlerOptions): (event: H3Event) => Promise<Response>;
+/**
+ * Options for the Nitro catch-all renderer
+ */
+export interface NitroCatchAllOptions {
+    /** Avalon runtime configuration */
+    avalonConfig: AvalonRuntimeConfig;
+    /** Whether running in development mode */
+    isDev?: boolean;
+    /**
+     * Page module loader function
+     * In development, this should use Vite's ssrLoadModule
+     * In production, this imports from the build output
+     */
+    loadPageModule: (filePath: string) => Promise<PageModule>;
+    /** Optional layout resolver */
+    resolveLayouts?: (routePath: string, config: AvalonRuntimeConfig) => Promise<string[]>;
+    /**
+     * Enable custom error pages (404.tsx, 500.tsx, _error.tsx)
+     * When enabled, the renderer will look for custom error pages in the pages directory
+     * Requirements: 10.5
+     */
+    enableCustomErrorPages?: boolean;
+}
+/**
+ * Creates a Nitro catch-all renderer handler
+ *
+ * This is the recommended way to create a renderer for Nitro's catch-all pattern.
+ * It's designed to work with Nitro's file-system routing where:
+ *
+ * 1. API routes are handled by files in the api/ directory
+ * 2. Static assets are served from public/
+ * 3. This catch-all handles all remaining requests for SSR
+ *
+ * Middleware execution order:
+ * 1. Global middleware (from middleware/ directory) - handled by Nitro
+ * 2. Route-scoped middleware (from _middleware.ts files) - handled here
+ * 3. Page rendering
+ *
+ * The handler expects Nitro to provide route information via event.context:
+ * - event.context.params: Route parameters from dynamic segments
+ * - event.context.route: Optional resolved route information
+ *
+ * Usage in Nitro routes/[...slug].ts:
+ * ```ts
+ * import { createNitroCatchAllRenderer } from '@useavalon/nitro/renderer';
+ *
+ * export default createNitroCatchAllRenderer({
+ *   avalonConfig: useRuntimeConfig().avalon,
+ *   isDev: import.meta.dev,
+ *   loadPageModule: async (filePath) => {
+ *     return await import(filePath);
+ *   }
+ * });
+ * ```
+ *
+ * Requirements: 2.1, 2.2, 2.6, 5.1, 5.3, 10.5
+ *
+ * @param options - Catch-all renderer options
+ * @returns Nitro event handler function
+ */
+export declare function createNitroCatchAllRenderer(options: NitroCatchAllOptions): (event: H3Event) => Promise<Response>;
+/**
+ * Re-export middleware cache clearing for hot reload support
+ *
+ * Call this function when middleware files change during development
+ * to ensure the latest version is loaded on the next request.
+ *
+ * @example
+ * ```ts
+ * // In your HMR handler
+ * if (file.endsWith('_middleware.ts')) {
+ *   clearRendererMiddlewareCache();
+ * }
+ * ```
+ */
+export { clearMiddlewareCache as clearRendererMiddlewareCache } from '../middleware/index.ts';

package/dist/src/nitro/route-discovery.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Route Discovery Module for Nitro
+ *
+ * This module provides minimal route discovery for Avalon's SSR pages.
+ *
+ * IMPORTANT: This module is simplified to complement Nitro's native routing:
+ * - API routes: Handled by Nitro's auto-discovery from `api/` directory
+ * - Page routes: Discovered here for SSR rendering (pages are components, not h3 handlers)
+ * - Middleware: Handled by Nitro's auto-discovery from `middleware/` directory
+ *
+ * The page discovery is needed because Avalon pages are React/Vue/Svelte components
+ * that require SSR rendering, which is different from Nitro's h3 route handlers.
+ *
+ * @module nitro/route-discovery
+ */
+import type { DiscoveredRoute } from "./types.ts";
+/**
+ * Supported page file extensions
+ */
+export declare const PAGE_EXTENSIONS: string[];
+/**
+ * Options for page route discovery
+ */
+export interface PageDiscoveryOptions {
+    /** Pages directory path (absolute or relative to project root) */
+    pagesDir: string;
+    /** Enable development mode logging */
+    developmentMode?: boolean;
+    /** Directories to exclude from scanning */
+    excludeDirectories?: string[];
+}
+/**
+ * Result of file path to pattern conversion
+ */
+export interface FilePathPatternResult {
+    /** Route pattern (e.g., /users/:id) */
+    pattern: string;
+    /** Extracted parameter names */
+    params: string[];
+}
+/**
+ * Discovers page routes from multiple directories with route prefixes
+ *
+ * This supports modular architecture where pages can be in different modules,
+ * each with their own route prefix.
+ *
+ * @param pageDirs - Array of page directories with their route prefixes
+ * @param options - Discovery options
+ * @returns Array of discovered page routes
+ */
+export declare function discoverPageRoutesFromMultipleDirs(pageDirs: Array<{
+    dir: string;
+    prefix: string;
+}>, options?: Pick<PageDiscoveryOptions, "developmentMode" | "excludeDirectories">): Promise<DiscoveredRoute[]>;
+/**
+ * Discovers page routes from the pages directory for SSR rendering
+ *
+ * NOTE: This is specifically for page components that need SSR rendering.
+ * API routes should be placed in the `api/` directory and are auto-discovered
+ * by Nitro's native file-system routing.
+ *
+ * @param pagesDir - Path to the pages directory
+ * @param options - Discovery options
+ * @returns Array of discovered page routes
+ *
+ * @example
+ * ```ts
+ * const routes = await discoverPageRoutes('src/pages', {
+ *   developmentMode: true,
+ * });
+ * ```
+ */
+export declare function discoverPageRoutes(pagesDir: string, options?: Pick<PageDiscoveryOptions, "developmentMode" | "excludeDirectories">): Promise<DiscoveredRoute[]>;
+/**
+ * Converts a file path to a route pattern
+ *
+ * Handles:
+ * - Index files (index.tsx -> /)
+ * - Dynamic segments ([param] -> :param)
+ * - Catch-all segments ([...slug] -> **)
+ * - Route groups ((group) -> removed from path)
+ *
+ * @param filePath - Relative file path from pages directory
+ * @returns Pattern and extracted parameter names
+ *
+ * @example
+ * ```ts
+ * filePathToPattern('users/[id].tsx')
+ * // { pattern: '/users/:id', params: ['id'] }
+ *
+ * filePathToPattern('blog/[...slug].tsx')
+ * // { pattern: '/blog/**', params: ['slug'] }
+ * ```
+ */
+export declare function filePathToPattern(filePath: string): FilePathPatternResult;
+/**
+ * Checks if a file is in a private folder (starts with _)
+ *
+ * @param relativePath - Relative file path
+ * @returns True if the file is private
+ */
+export declare function isPrivateFile(relativePath: string): boolean;
+/**
+ * Calculates route specificity score for sorting
+ * Lower score = more specific = higher priority
+ *
+ * @param route - Discovered route
+ * @returns Specificity score
+ */
+export declare function calculateRouteSpecificity(route: DiscoveredRoute): number;
+/**
+ * Sorts routes by specificity (most specific first)
+ *
+ * @param routes - Array of discovered routes
+ * @returns Sorted array of routes
+ */
+export declare function sortRoutesBySpecificity(routes: DiscoveredRoute[]): DiscoveredRoute[];
+/**
+ * Validates a route pattern for correctness
+ *
+ * @param pattern - Route pattern to validate
+ * @returns Array of validation errors (empty if valid)
+ */
+export declare function validateRoutePattern(pattern: string): string[];
+/**
+ * Extracts parameter names from a route pattern
+ *
+ * @param pattern - Route pattern (e.g., /users/:id/posts/:postId)
+ * @returns Array of parameter names
+ */
+export declare function extractParamsFromPattern(pattern: string): string[];
+/**
+ * Checks if a route pattern matches a given URL path
+ *
+ * @param pattern - Route pattern
+ * @param path - URL path to match
+ * @returns True if the pattern matches the path
+ */
+export declare function matchRoutePattern(pattern: string, path: string): {
+    matches: boolean;
+    params: Record<string, string>;
+};