@useavalon/avalon 0.1.23 → 0.1.25

package/dist/src/nitro/error-handler.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Nitro Error Handler for Avalon
+ *
+ * This module provides error handling utilities for the Nitro integration,
+ * including support for custom error pages (404, 500, _error).
+ *
+ * Custom error pages are discovered from the pages directory:
+ * - src/pages/404.tsx → Custom 404 page
+ * - src/pages/500.tsx → Custom 500 page
+ * - src/pages/_error.tsx → Generic error page (fallback)
+ *
+ * Requirements: 10.1, 10.2, 10.3, 10.4, 10.5
+ */
+import type { PageModule, NitroRenderContext, AvalonRuntimeConfig } from "./types.ts";
+import type { H3Event } from "h3";
+import { HttpError } from "./types.ts";
+/**
+ * Error page props passed to custom error page components
+ */
+export interface ErrorPageProps {
+    /** HTTP status code */
+    statusCode: number;
+    /** Error message */
+    message: string;
+    /** Error object (development only) */
+    error?: Error;
+    /** Stack trace (development only) */
+    stack?: string;
+    /** Request URL that caused the error */
+    url?: string;
+}
+/**
+ * Options for error handling
+ */
+export interface ErrorHandlerOptions {
+    /** Whether running in development mode */
+    isDev?: boolean;
+    /** Avalon runtime configuration */
+    avalonConfig?: AvalonRuntimeConfig;
+    /** Custom page module loader */
+    loadPageModule?: (filePath: string) => Promise<PageModule>;
+    /** Pages directory path */
+    pagesDir?: string;
+}
+/**
+ * Cache for discovered error pages
+ */
+interface ErrorPageCache {
+    /** Custom 404 page module */
+    notFound?: PageModule | null;
+    /** Custom 500 page module */
+    serverError?: PageModule | null;
+    /** Generic error page module */
+    genericError?: PageModule | null;
+    /** Whether cache has been initialized */
+    initialized: boolean;
+}
+/**
+ * Clears the error page cache
+ * Call this during development when error pages change
+ */
+export declare function clearErrorPageCache(): void;
+/**
+ * Discovers and caches custom error pages from the pages directory
+ *
+ * @param options - Error handler options
+ * @returns Object containing discovered error page modules
+ */
+export declare function discoverErrorPages(options: ErrorHandlerOptions): Promise<ErrorPageCache>;
+/**
+ * Gets the appropriate error page module for a status code
+ *
+ * @param statusCode - HTTP status code
+ * @param cache - Error page cache
+ * @returns Error page module or null if no custom page exists
+ */
+export declare function getErrorPageModule(statusCode: number, cache: ErrorPageCache): PageModule | null;
+/**
+ * Creates error page props from an error
+ *
+ * @param error - The error that occurred
+ * @param url - Request URL
+ * @param isDev - Whether running in development mode
+ * @returns Error page props
+ */
+export declare function createErrorPageProps(error: Error | HttpError, url?: string, isDev?: boolean): ErrorPageProps;
+/**
+ * Renders a custom error page to HTML
+ *
+ * @param pageModule - The error page module
+ * @param props - Error page props
+ * @param context - Render context
+ * @param isDev - Whether running in development mode
+ * @returns Rendered HTML string
+ */
+export declare function renderErrorPage(pageModule: PageModule, props: ErrorPageProps, context: NitroRenderContext, isDev: boolean): Promise<string>;
+/**
+ * Generates a default error page when no custom page is available
+ *
+ * @param statusCode - HTTP status code
+ * @param message - Error message
+ * @param isDev - Whether running in development mode
+ * @param stack - Stack trace (development only)
+ * @returns HTML string
+ */
+export declare function generateDefaultErrorPage(statusCode: number, message: string, isDev: boolean, stack?: string): string;
+/**
+ * Handles a render error and returns an appropriate response
+ *
+ * This function:
+ * 1. Discovers custom error pages if available
+ * 2. Renders the appropriate error page (custom or default)
+ * 3. Returns a Response with the correct status code
+ *
+ * Requirements: 10.1, 10.2, 10.3, 10.4, 10.5
+ *
+ * @param error - The error that occurred
+ * @param event - H3 event
+ * @param options - Error handler options
+ * @returns Response with error page
+ */
+export declare function handleRenderError(error: Error | HttpError, event: H3Event, options: ErrorHandlerOptions): Promise<Response>;
+/**
+ * Handles an API error and returns an appropriate JSON response
+ *
+ * Requirements: 10.1, 10.2, 10.4
+ *
+ * @param error - The error that occurred
+ * @param options - Error handler options
+ * @returns Response with JSON error
+ */
+export declare function handleApiError(error: Error | HttpError, options: ErrorHandlerOptions): Response;
+/**
+ * Creates a 404 Not Found response
+ *
+ * @param pathname - The requested path
+ * @param event - H3 event
+ * @param options - Error handler options
+ * @returns Response with 404 error page
+ */
+export declare function handleNotFound(pathname: string, event: H3Event, options: ErrorHandlerOptions): Promise<Response>;
+/**
+ * Creates a 500 Internal Server Error response
+ *
+ * @param error - The original error
+ * @param event - H3 event
+ * @param options - Error handler options
+ * @returns Response with 500 error page
+ */
+export declare function handleInternalError(error: Error, event: H3Event, options: ErrorHandlerOptions): Promise<Response>;
+export {};

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

@@ -0,0 +1,15 @@
+/**
+ * Nitro Integration Module for Avalon
+ *
+ * This module provides the Nitro server runtime integration for Avalon,
+ * enabling universal deployment through Nitro presets while maintaining
+ * Avalon's multi-framework SSR and islands architecture.
+ */
+export { createNitroConfig, isValidPreset, mergeRouteRules, createDefaultStaticAssetRouteRules, DEFAULT_NITRO_CONFIG, DEFAULT_STATIC_ASSETS_CONFIG, type AvalonNitroConfig, type CacheOptions, type RouteRule, type NitroConfigOutput, type AvalonRuntimeConfig, type StaticAssetsConfig, } from "./config.ts";
+export { type H3Event, type NitroRenderContext, type LayoutContext, type DiscoveredRoute, type NitroRouteConfig, type SSRRenderOptions, type SSRRenderResult, type AvalonEventContext, type IslandEntry, type IslandManifest, type PageModule, type PageMetadata, type ErrorResponse, HttpError, isHttpError, createNotFoundError, createMethodNotAllowedError, createInternalError, type DevServerOptions, type BuildOptions, } from "./types.ts";
+export { createNitroRenderer, createNitroCatchAllRenderer, createRenderContext, renderPage, renderPageStream, createStreamingResponse, injectHydrationScript, validateHydrationMarkers, extractIslandMarkers, ensureHydrationMarkers, processHydrationRequirements, createErrorResponse, getRequestURL as getRendererRequestURL, toRequest as rendererToRequest, setResponseHeader, type RenderHandlerOptions, type ResolvedPageRoute, type StreamingSSROptions, type IslandMarker, type NitroCatchAllOptions, } from "./renderer.ts";
+export { createMiddlewareContext, storeMiddlewareContext, getMiddlewareContext, getOrCreateMiddlewareContext, setMiddlewareState, getMiddlewareState, setMiddlewareLocal, getMiddlewareLocal, hasAvalonContext, ensureAvalonContext, getRequestURL as getMiddlewareRequestURL, getRequestHeaders as getMiddlewareRequestHeaders, toRequest as middlewareToRequest, getRouterParams as getMiddlewareRouterParams, type MiddlewareContextOptions, } from "./middleware-adapter.ts";
+export { discoverPageRoutes, filePathToPattern, isPrivateFile, calculateRouteSpecificity, sortRoutesBySpecificity, validateRoutePattern, extractParamsFromPattern, matchRoutePattern, PAGE_EXTENSIONS, type PageDiscoveryOptions, type FilePathPatternResult, } from "./route-discovery.ts";
+export { createClientBuildConfig, createServerBuildConfig, createCombinedBuildConfig, createNitroBuildPlugin, getPresetOutputConfig, presetSupportsStreaming, validateBuildConfig, createSourceMapConfig, createSourceMapPlugin, getViteSourceMapOption, DEFAULT_BUILD_CONFIG, DEFAULT_SOURCEMAP_CONFIG, PRESET_OUTPUT_CONFIGS, type BuildMode, type PresetOutputConfig, type AvalonBuildConfig, type SourceMapConfig, } from "./build-config.ts";
+export { createIslandManifestPlugin, createIslandEntry, detectIslandFramework, generateContentHash, extractIslandDependencies, generatePreloadHints, generatePreloadTags, loadIslandManifest, getIslandAssetPath, getPageCssAssets, DEFAULT_MANIFEST_OPTIONS, type BuildIslandEntry, type BuildIslandManifest, type PreloadHint, type IslandManifestOptions, type AssetMetadata, } from "./island-manifest.ts";
+export { discoverErrorPages, getErrorPageModule, renderErrorPage, generateDefaultErrorPage, createErrorPageProps, clearErrorPageCache, handleRenderError, handleApiError, handleNotFound, handleInternalError, type ErrorPageProps, type ErrorHandlerOptions, } from "./error-handler.ts";

package/dist/src/nitro/island-manifest.d.ts

@@ -0,0 +1,191 @@
+/**
+ * Island Manifest Generation Module for Nitro
+ *
+ * This module provides island manifest generation during production builds.
+ * The manifest contains information about all discovered islands, their
+ * compiled asset paths, and framework metadata for client-side hydration.
+ *
+ * ## Build Output
+ *
+ * During production build, this module generates:
+ * - `island-manifest.json` in the build output directory
+ * - Contains metadata for all islands (src, framework, css, preload)
+ * - Includes build timestamp and content hashes for cache busting
+ * - Generates preload hints for critical assets
+ *
+ * ## Nitro Integration
+ *
+ * The manifest is used by Nitro's renderer to:
+ * - Resolve compiled island paths for hydration scripts
+ * - Inject CSS assets for islands used on a page
+ * - Generate preload tags for critical resources
+ *
+ * ## Asset Metadata
+ *
+ * Each island entry includes:
+ * - `src`: Compiled JavaScript path (e.g., `/islands/Counter.abc123.js`)
+ * - `framework`: Detected framework (react, preact, vue, svelte, solid, lit)
+ * - `css`: Associated CSS files
+ * - `contentHash`: Hash for cache busting
+ * - `preloadDeps`: Dependencies to preload
+ *
+ * @module nitro/island-manifest
+ */
+import type { Plugin } from "vite";
+import type { ResolvedAvalonConfig } from "../vite-plugin/types.ts";
+import type { IslandManifest, IslandEntry } from "./types.ts";
+/**
+ * Extended island entry with build-time metadata
+ */
+export interface BuildIslandEntry extends IslandEntry {
+    /** Original source file path */
+    sourcePath: string;
+    /** Compiled JavaScript chunk name */
+    chunkName: string;
+    /** Content hash for cache busting */
+    contentHash: string;
+    /** Dependencies that need to be preloaded */
+    preloadDeps: string[];
+    /** Whether the island uses streaming */
+    usesStreaming: boolean;
+}
+/**
+ * Asset metadata for Nitro's asset manifest format
+ * This matches Nitro's expected asset metadata structure
+ */
+export interface AssetMetadata {
+    /** MIME type of the asset */
+    type: string;
+    /** ETag for cache validation */
+    etag: string;
+    /** Last modification time (ISO string) */
+    mtime: string;
+    /** File size in bytes */
+    size: number;
+}
+/**
+ * Build-time island manifest with additional metadata
+ */
+export interface BuildIslandManifest extends IslandManifest {
+    /** Build timestamp */
+    buildTime: number;
+    /** Build version/hash */
+    buildHash: string;
+    /** Avalon version */
+    avalonVersion: string;
+    /** All CSS assets to inject */
+    cssAssets: string[];
+    /** Preload hints for critical assets */
+    preloadHints: PreloadHint[];
+    /** Framework-specific bundles */
+    frameworkBundles: Record<string, string>;
+    /** Asset metadata for cache headers (Nitro format) */
+    assetMetadata?: Record<string, AssetMetadata>;
+}
+/**
+ * Preload hint for resource optimization
+ */
+export interface PreloadHint {
+    /** Resource URL */
+    href: string;
+    /** Resource type (script, style, font, etc.) */
+    as: "script" | "style" | "font" | "image";
+    /** MIME type */
+    type?: string;
+    /** Cross-origin setting */
+    crossorigin?: "anonymous" | "use-credentials";
+}
+/**
+ * Options for island manifest generation
+ */
+export interface IslandManifestOptions {
+    /** Output path for the manifest file */
+    outputPath?: string;
+    /** Include source maps in manifest */
+    includeSourceMaps?: boolean;
+    /** Generate preload hints */
+    generatePreloadHints?: boolean;
+    /** Verbose logging */
+    verbose?: boolean;
+}
+/**
+ * Default manifest generation options
+ */
+export declare const DEFAULT_MANIFEST_OPTIONS: Required<IslandManifestOptions>;
+/**
+ * Detects the framework used by an island based on file content and extension
+ *
+ * @param filePath - Path to the island file
+ * @param content - File content
+ * @returns Detected framework name
+ */
+export declare function detectIslandFramework(filePath: string, content: string): string;
+/**
+ * Generates a content hash for cache busting
+ *
+ * @param content - Content to hash
+ * @returns Short hash string
+ */
+export declare function generateContentHash(content: string): Promise<string>;
+/**
+ * Extracts dependencies from island file content
+ *
+ * @param content - File content
+ * @returns Array of dependency names
+ */
+export declare function extractIslandDependencies(content: string): string[];
+/**
+ * Creates an island entry from discovered island information
+ *
+ * @param name - Island name
+ * @param sourcePath - Source file path
+ * @param content - File content
+ * @param compiledPath - Compiled asset path
+ * @returns Island entry
+ */
+export declare function createIslandEntry(name: string, sourcePath: string, content: string, compiledPath: string): Promise<BuildIslandEntry>;
+/**
+ * Generates preload hints for critical assets
+ *
+ * @param manifest - Island manifest
+ * @returns Array of preload hints
+ */
+export declare function generatePreloadHints(manifest: Partial<BuildIslandManifest>): PreloadHint[];
+/**
+ * Creates a Vite plugin for island manifest generation
+ *
+ * @param avalonConfig - Resolved Avalon configuration
+ * @param options - Manifest generation options
+ * @returns Vite plugin
+ */
+export declare function createIslandManifestPlugin(avalonConfig: ResolvedAvalonConfig, options?: IslandManifestOptions): Plugin;
+/**
+ * Loads an existing island manifest from disk
+ *
+ * @param manifestPath - Path to the manifest file
+ * @returns Loaded manifest or null if not found
+ */
+export declare function loadIslandManifest(manifestPath?: string): Promise<BuildIslandManifest | null>;
+/**
+ * Gets the compiled asset path for an island
+ *
+ * @param islandName - Name of the island
+ * @param manifest - Island manifest
+ * @returns Compiled asset path or null if not found
+ */
+export declare function getIslandAssetPath(islandName: string, manifest: BuildIslandManifest | null): string | null;
+/**
+ * Gets all CSS assets that should be injected for a page
+ *
+ * @param islandNames - Names of islands used on the page
+ * @param manifest - Island manifest
+ * @returns Array of CSS asset paths
+ */
+export declare function getPageCssAssets(islandNames: string[], manifest: BuildIslandManifest | null): string[];
+/**
+ * Generates HTML preload tags for critical assets
+ *
+ * @param manifest - Island manifest
+ * @returns HTML string with preload tags
+ */
+export declare function generatePreloadTags(manifest: BuildIslandManifest): string;

package/dist/src/nitro/middleware-adapter.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Nitro Middleware Adapter for Avalon
+ *
+ * This module provides utilities for creating and managing middleware context
+ * in Nitro's h3 middleware system. Nitro handles middleware ordering and execution
+ * automatically via the middleware/ directory with numbered prefixes.
+ *
+ * Key responsibilities:
+ * - Create MiddlewareContext from H3 events
+ * - Store/retrieve context in event.context.avalon for downstream handlers
+ * - Provide utilities for middleware to access request data
+ *
+ * Requirements: 6.1, 6.2, 6.3, 6.4
+ */
+import type { AvalonEventContext } from './types.ts';
+import type { H3Event } from 'h3';
+/**
+ * Context object passed through the middleware chain
+ */
+export interface MiddlewareContext {
+    request: Request;
+    url: URL;
+    params: Record<string, string>;
+    query: Record<string, string | string[]>;
+    state: Map<string, unknown>;
+    locals: Record<string, unknown>;
+}
+/**
+ * Options for middleware context creation
+ */
+export interface MiddlewareContextOptions {
+    /** Whether running in development mode */
+    isDev?: boolean;
+    /** Enable detailed logging */
+    enableLogging?: boolean;
+}
+/**
+ * Gets the request URL from an H3 event
+ * Requirements: 6.3
+ */
+export declare function getRequestURL(event: H3Event): URL;
+/**
+ * Gets request headers from an H3 event
+ */
+export declare function getRequestHeaders(event: H3Event): Headers;
+/**
+ * Converts an H3 event to a standard Request object
+ * Requirements: 6.3
+ */
+export declare function toRequest(event: H3Event): Request;
+/**
+ * Extracts route parameters from an H3 event
+ * Uses Nitro's built-in parameter extraction via event.context.params
+ * Requirements: 6.3
+ */
+export declare function getRouterParams(event: H3Event): Record<string, string>;
+/**
+ * Creates a MiddlewareContext from an H3 event
+ * Requirements: 6.3, 6.4
+ *
+ * This context is used by downstream handlers to access request data
+ * and any state set by middleware.
+ *
+ * @param event - The H3 event
+ * @param options - Optional configuration
+ * @returns MiddlewareContext for use in handlers
+ */
+export declare function createMiddlewareContext(event: H3Event, options?: MiddlewareContextOptions): MiddlewareContext;
+/**
+ * Stores the middleware context in the H3 event for downstream handlers
+ * Requirements: 6.3, 6.4
+ *
+ * This allows API handlers and page renderers to access the middleware context
+ * that was created during middleware execution.
+ *
+ * @param event - The H3 event
+ * @param context - The middleware context to store
+ */
+export declare function storeMiddlewareContext(event: H3Event, context: MiddlewareContext): void;
+/**
+ * Retrieves the middleware context from an H3 event
+ * Requirements: 6.3, 6.4
+ *
+ * @param event - The H3 event
+ * @returns The stored middleware context or undefined
+ */
+export declare function getMiddlewareContext(event: H3Event): MiddlewareContext | undefined;
+/**
+ * Gets or creates a middleware context for an H3 event
+ * Requirements: 6.3, 6.4
+ *
+ * This is a convenience function that retrieves an existing context
+ * or creates a new one if none exists.
+ *
+ * @param event - The H3 event
+ * @param options - Optional configuration for context creation
+ * @returns The middleware context
+ */
+export declare function getOrCreateMiddlewareContext(event: H3Event, options?: MiddlewareContextOptions): MiddlewareContext;
+/**
+ * Updates the middleware context state
+ * Requirements: 6.3, 6.4
+ *
+ * Allows middleware to set state that can be accessed by downstream handlers.
+ *
+ * @param event - The H3 event
+ * @param key - The state key
+ * @param value - The state value
+ */
+export declare function setMiddlewareState(event: H3Event, key: string, value: unknown): void;
+/**
+ * Gets a value from the middleware context state
+ * Requirements: 6.3, 6.4
+ *
+ * @param event - The H3 event
+ * @param key - The state key
+ * @returns The state value or undefined
+ */
+export declare function getMiddlewareState<T = unknown>(event: H3Event, key: string): T | undefined;
+/**
+ * Sets a local value in the middleware context
+ * Requirements: 6.3, 6.4
+ *
+ * Locals are similar to state but use a plain object for simpler access.
+ *
+ * @param event - The H3 event
+ * @param key - The local key
+ * @param value - The local value
+ */
+export declare function setMiddlewareLocal(event: H3Event, key: string, value: unknown): void;
+/**
+ * Gets a local value from the middleware context
+ * Requirements: 6.3, 6.4
+ *
+ * @param event - The H3 event
+ * @param key - The local key
+ * @returns The local value or undefined
+ */
+export declare function getMiddlewareLocal<T = unknown>(event: H3Event, key: string): T | undefined;
+/**
+ * Type guard to check if avalon context exists on an event
+ */
+export declare function hasAvalonContext(event: H3Event): boolean;
+/**
+ * Ensures the avalon context is initialized on an event
+ * Requirements: 6.3
+ *
+ * @param event - The H3 event
+ * @returns The avalon context
+ */
+export declare function ensureAvalonContext(event: H3Event): AvalonEventContext;