@useavalon/avalon 0.1.11 → 0.1.12

package/src/nitro/config.ts

@@ -1,483 +0,0 @@
-/**
- * Nitro Configuration Module for Avalon
- *
- * This module provides configuration interfaces and utilities for integrating
- * Nitro as Avalon's server runtime. It handles preset configuration, route rules,
- * and merging Avalon-specific options with Nitro defaults.
- *
- * ## Static Asset Handling
- *
- * Nitro automatically serves static assets from the `public/` directory at the root path.
- * The configuration supports:
- * - `publicAssets`: Configures directories for static file serving
- * - `routeRules`: Configures cache headers for different asset types
- * - `staticAssets`: Avalon-specific static asset configuration
- *
- * Default route rules for static assets are generated by `createDefaultStaticAssetRouteRules()`:
- * - `/assets/**`, `/islands/**`, `/chunks/**`: Long cache (1 year, immutable)
- * - `/*.woff`, `/*.woff2`: Long cache for fonts
- * - `/*.html`, `/*.css`: Short cache with revalidation
- * - `/favicon.ico`: Medium cache (1 day)
- */
-
-import type { ResolvedAvalonConfig } from "../vite-plugin/types.ts";
-
-/**
- * Cache configuration options for route rules
- */
-export interface CacheOptions {
-  /** Maximum age in seconds for cache validity */
-  maxAge?: number;
-  /** Maximum age in seconds for stale content */
-  staleMaxAge?: number;
-  /** Enable stale-while-revalidate behavior */
-  swr?: boolean;
-}
-
-/**
- * Route rule configuration for caching, redirects, proxying, and headers
- */
-export interface RouteRule {
-  /** Cache configuration or boolean to enable/disable */
-  cache?: CacheOptions | boolean;
-  /** Redirect destination URL */
-  redirect?: string;
-  /** Proxy destination URL */
-  proxy?: string;
-  /** Custom headers to set */
-  headers?: Record<string, string>;
-  /** Enable CORS for this route */
-  cors?: boolean;
-}
-
-/**
- * Static asset serving configuration
- */
-export interface StaticAssetsConfig {
-  /**
-   * Directory containing public static assets
-   * @default "public"
-   */
-  publicDir?: string;
-
-  /**
-   * Directory containing compiled build output
-   * @default "dist"
-   */
-  buildDir?: string;
-
-  /**
-   * Enable serving pre-compressed assets (gzip, brotli)
-   * @default true
-   */
-  compression?: boolean;
-
-  /**
-   * Default cache control header for immutable static assets
-   * @default "public, max-age=31536000, immutable"
-   */
-  cacheControl?: string;
-
-  /**
-   * Cache control header for mutable assets (HTML, etc.)
-   * @default "public, max-age=0, must-revalidate"
-   */
-  mutableCacheControl?: string;
-
-  /**
-   * Custom headers to add to all static asset responses
-   */
-  headers?: Record<string, string>;
-}
-
-/**
- * Avalon-specific Nitro configuration options
- */
-export interface AvalonNitroConfig {
-  /**
-   * Deployment preset (vercel, cloudflare, deno-deploy, node-server, netlify, etc.)
-   * @default "node-server"
-   */
-  preset?: string;
-
-  /**
-   * Directory containing server routes
-   * @default "server"
-   */
-  serverDir?: string;
-
-  /**
-   * Directory containing pages (overrides Avalon config if set)
-   */
-  pagesDir?: string;
-
-  /**
-   * Enable streaming SSR responses
-   * @default true
-   */
-  streaming?: boolean;
-
-  /**
-   * Route rules for caching, redirects, proxying, and headers
-   * Keys are route patterns (e.g., "/api/**", "/static/**")
-   */
-  routeRules?: Record<string, RouteRule>;
-
-  /**
-   * Runtime configuration accessible via useRuntimeConfig()
-   * Can be overridden by NITRO_ prefixed environment variables
-   */
-  runtimeConfig?: Record<string, unknown>;
-
-  /**
-   * Public runtime configuration (exposed to client)
-   */
-  publicRuntimeConfig?: Record<string, unknown>;
-
-  /**
-   * Static asset serving configuration
-   */
-  staticAssets?: StaticAssetsConfig;
-
-  /** Nitro v3: Compatibility date for preset features (YYYY-MM-DD) */
-  compatibilityDate?: string;
-  /** Nitro v3: Dependencies to trace instead of bundle */
-  traceDeps?: string[];
-  /** Nitro v3: Rolldown-specific configuration */
-  rolldownConfig?: Record<string, unknown>;
-  /** Nitro v3: Custom server entry point */
-  serverEntry?: string;
-  /** Nitro v3: Renderer configuration, or false to disable */
-  renderer?: { handler: string } | false;
-  /** Nitro v3: Pre-compress public assets (gzip, brotli, zstd) */
-  compressPublicAssets?: boolean | { gzip?: boolean; brotli?: boolean; zstd?: boolean };
-}
-
-/**
- * Nitro configuration output structure
- * This matches the expected NitroConfig interface from nitro/types
- */
-export interface NitroConfigOutput {
-  /** Deployment preset */
-  preset: string;
-  /** Server directory */
-  serverDir: string;
-  /** Route rules */
-  routeRules: Record<string, RouteRule>;
-  /** Runtime configuration */
-  runtimeConfig: {
-    avalon: AvalonRuntimeConfig;
-    [key: string]: unknown;
-  };
-  /** Public runtime configuration */
-  publicRuntimeConfig?: Record<string, unknown>;
-  /** Renderer configuration, or false to disable */
-  renderer?: {
-    handler: string;
-  } | false;
-  /** Nitro v3: Compatibility date for preset features (YYYY-MM-DD) */
-  compatibilityDate?: string;
-  /** Nitro v3: Dependencies to trace instead of bundle */
-  traceDeps?: string[];
-  /** Nitro v3: Rolldown-specific configuration */
-  rolldownConfig?: Record<string, unknown>;
-  /** Nitro v3: Custom server entry point */
-  serverEntry?: string;
-  /** Nitro v3: Pre-compress public assets (gzip, brotli, zstd) */
-  compressPublicAssets?: boolean | { gzip?: boolean; brotli?: boolean; zstd?: boolean };
-  /** Public assets directory */
-  publicAssets?: Array<{
-    dir: string;
-    baseURL?: string;
-    maxAge?: number;
-  }>;
-  /** Server assets configuration */
-  serverAssets?: Array<{
-    baseName: string;
-    dir: string;
-  }>;
-  /** Static assets configuration */
-  staticAssets?: StaticAssetsConfig;
-}
-
-/**
- * Avalon-specific runtime configuration stored in Nitro's runtimeConfig
- */
-export interface AvalonRuntimeConfig {
-  /** Enable streaming SSR */
-  streaming: boolean;
-  /** Pages directory path */
-  pagesDir: string;
-  /** Layouts directory path */
-  layoutsDir: string;
-}
-
-/**
- * Default static assets configuration
- */
-export const DEFAULT_STATIC_ASSETS_CONFIG: Required<StaticAssetsConfig> = {
-  publicDir: "public",
-  buildDir: "dist",
-  compression: true,
-  cacheControl: "public, max-age=31536000, immutable",
-  mutableCacheControl: "public, max-age=0, must-revalidate",
-  headers: {},
-};
-
-/**
- * All valid Nitro v3 preset names (underscore convention).
- */
-export const VALID_V3_PRESETS: string[] = [
-  "node_server",
-  "node_middleware",
-  "vercel",
-  "cloudflare_module",
-  "cloudflare_pages",
-  "deno_deploy",
-  "deno_server",
-  "netlify_functions",
-  "netlify_edge",
-  "aws_lambda",
-  "azure_swa",
-  "firebase_functions",
-  "render_com",
-  "static",
-  "browser",
-];
-
-/**
- * Validates a preset name against the v3 preset list.
- * Returns the preset name if valid, throws if unrecognized.
- *
- * @param preset - The preset name to validate (must be a v3 name)
- * @returns The validated v3 preset name
- * @throws Error if the preset is not recognized
- */
-export function resolvePresetName(preset: string): string {
-  if (VALID_V3_PRESETS.includes(preset)) return preset;
-  throw new Error(
-    `Unknown Nitro preset: "${preset}". Valid presets: ${VALID_V3_PRESETS.join(", ")}`
-  );
-}
-
-/**
- * Default Nitro configuration values
- */
-export const DEFAULT_NITRO_CONFIG: Required<
-  Pick<AvalonNitroConfig, "preset" | "serverDir" | "streaming">
-> = {
-  preset: "node_server",
-  serverDir: "server",
-  streaming: true,
-};
-
-/**
- * Creates a Nitro configuration from Avalon plugin config and Nitro-specific options
- *
- * This function merges Avalon's resolved configuration with Nitro-specific options
- * to produce a complete Nitro configuration object. Avalon-specific settings are
- * stored in `runtimeConfig.avalon` for access by handlers.
- *
- * @param avalonNitroConfig - Nitro-specific configuration options
- * @param resolvedAvalonConfig - Resolved Avalon plugin configuration
- * @returns Complete Nitro configuration object
- *
- * @example
- * ```ts
- * const nitroConfig = createNitroConfig(
- *   { preset: 'vercel', streaming: true },
- *   resolvedAvalonConfig
- * );
- * ```
- */
-export function createNitroConfig(
-  avalonNitroConfig: AvalonNitroConfig,
-  resolvedAvalonConfig: ResolvedAvalonConfig
-): NitroConfigOutput {
-  // Determine final directory paths (Nitro config overrides Avalon config)
-  const pagesDir = avalonNitroConfig.pagesDir ?? resolvedAvalonConfig.pagesDir;
-  const layoutsDir = resolvedAvalonConfig.layoutsDir;
-
-  // Build Avalon runtime config
-  const avalonRuntimeConfig: AvalonRuntimeConfig = {
-    streaming: avalonNitroConfig.streaming ?? DEFAULT_NITRO_CONFIG.streaming,
-    pagesDir,
-    layoutsDir,
-  };
-
-  // Validate that runtimeConfig does not contain a 'nitro' key (reserved in v3)
-  if (avalonNitroConfig.runtimeConfig && "nitro" in avalonNitroConfig.runtimeConfig) {
-    throw new Error(
-      'The "nitro" key in runtimeConfig is reserved by Nitro v3 and cannot be used.'
-    );
-  }
-
-  // Merge user runtime config with Avalon runtime config
-  const runtimeConfig: NitroConfigOutput["runtimeConfig"] = {
-    avalon: avalonRuntimeConfig,
-    ...avalonNitroConfig.runtimeConfig,
-  };
-
-  // Merge static assets config with defaults
-  const staticAssetsConfig: StaticAssetsConfig = {
-    ...DEFAULT_STATIC_ASSETS_CONFIG,
-    ...avalonNitroConfig.staticAssets,
-  };
-
-  // Create default route rules for static assets
-  const defaultStaticRouteRules = createDefaultStaticAssetRouteRules(staticAssetsConfig);
-
-  // Merge user route rules with default static asset rules
-  const routeRules = mergeRouteRules(
-    defaultStaticRouteRules,
-    avalonNitroConfig.routeRules ?? {}
-  );
-
-  // Configure public assets directories
-  const publicAssets: NitroConfigOutput["publicAssets"] = [
-    {
-      dir: staticAssetsConfig.publicDir ?? DEFAULT_STATIC_ASSETS_CONFIG.publicDir,
-      baseURL: "/",
-      maxAge: 0, // Let route rules handle caching
-    },
-  ];
-
-  // Resolve renderer: support explicit false to disable, otherwise use default handler
-  const renderer: NitroConfigOutput["renderer"] =
-    avalonNitroConfig.renderer === false
-      ? false
-      : (avalonNitroConfig.renderer ?? { handler: "./server/renderer.ts" });
-
-  return {
-    preset: resolvePresetName(avalonNitroConfig.preset ?? DEFAULT_NITRO_CONFIG.preset),
-    serverDir: avalonNitroConfig.serverDir ?? DEFAULT_NITRO_CONFIG.serverDir,
-    routeRules,
-    runtimeConfig,
-    publicRuntimeConfig: avalonNitroConfig.publicRuntimeConfig,
-    renderer,
-    compatibilityDate: avalonNitroConfig.compatibilityDate,
-    traceDeps: avalonNitroConfig.traceDeps,
-    rolldownConfig: avalonNitroConfig.rolldownConfig,
-    serverEntry: avalonNitroConfig.serverEntry,
-    compressPublicAssets: avalonNitroConfig.compressPublicAssets,
-    publicAssets,
-    staticAssets: staticAssetsConfig,
-  };
-}
-
-/**
- * Creates default route rules for static asset caching
- *
- * @param config - Static assets configuration
- * @returns Route rules for static assets
- */
-export function createDefaultStaticAssetRouteRules(
-  config: StaticAssetsConfig
-): Record<string, RouteRule> {
-  const cacheControl = config.cacheControl ?? DEFAULT_STATIC_ASSETS_CONFIG.cacheControl;
-  const mutableCacheControl = config.mutableCacheControl ?? DEFAULT_STATIC_ASSETS_CONFIG.mutableCacheControl;
-
-  return {
-    // Immutable assets with hashed filenames (long cache)
-    "/assets/**": {
-      headers: {
-        "Cache-Control": cacheControl,
-        ...config.headers,
-      },
-    },
-    "/islands/**": {
-      headers: {
-        "Cache-Control": cacheControl,
-        ...config.headers,
-      },
-    },
-    "/chunks/**": {
-      headers: {
-        "Cache-Control": cacheControl,
-        ...config.headers,
-      },
-    },
-    "/_nuxt/**": {
-      headers: {
-        "Cache-Control": cacheControl,
-        ...config.headers,
-      },
-    },
-    // Font files (long cache)
-    "/**/*.woff": {
-      headers: {
-        "Cache-Control": cacheControl,
-        ...config.headers,
-      },
-    },
-    "/**/*.woff2": {
-      headers: {
-        "Cache-Control": cacheControl,
-        ...config.headers,
-      },
-    },
-    // Mutable assets (short cache with revalidation)
-    "/**/*.html": {
-      headers: {
-        "Cache-Control": mutableCacheControl,
-        ...config.headers,
-      },
-    },
-    // Favicon (medium cache)
-    "/favicon.ico": {
-      headers: {
-        "Cache-Control": "public, max-age=86400",
-        ...config.headers,
-      },
-    },
-    // CSS files in public directory (may be mutable)
-    "/**/*.css": {
-      headers: {
-        "Cache-Control": mutableCacheControl,
-        ...config.headers,
-      },
-    },
-  };
-}
-
-/**
- * Validates a Nitro preset name against the v3 preset list
- *
- * @param preset - The preset name to validate
- * @returns True if the preset is a known valid v3 preset
- */
-export function isValidPreset(preset: string): boolean {
-  return VALID_V3_PRESETS.includes(preset);
-}
-
-/**
- * Merges route rules, with later rules taking precedence
- *
- * @param baseRules - Base route rules
- * @param overrideRules - Override route rules
- * @returns Merged route rules
- */
-export function mergeRouteRules(
-  baseRules: Record<string, RouteRule>,
-  overrideRules: Record<string, RouteRule>
-): Record<string, RouteRule> {
-  const merged: Record<string, RouteRule> = { ...baseRules };
-
-  for (const [pattern, rule] of Object.entries(overrideRules)) {
-    if (merged[pattern]) {
-      // Deep merge the rule
-      merged[pattern] = {
-        ...merged[pattern],
-        ...rule,
-        headers: {
-          ...merged[pattern].headers,
-          ...rule.headers,
-        },
-      };
-    } else {
-      merged[pattern] = rule;
-    }
-  }
-
-  return merged;
-}