@useavalon/avalon 0.1.10 → 0.1.12

package/src/middleware/discovery.ts

@@ -1,268 +0,0 @@
-/**
- * Simplified Middleware Discovery
- *
- * This module provides a streamlined middleware discovery system that scans
- * for _middleware.ts files in src/pages/ directories.
- *
- * Key features:
- * - Scans src/pages/ for page middleware
- * - Calculates priority based on directory depth (parent before child)
- * - Creates URL patterns for route matching
- *
- * Note: API middleware is handled natively by Nitro and is not scanned here.
- *
- * Requirements: 3.1, 3.2, 3.3, 3.4
- */
-
-import { join, relative, resolve } from 'node:path';
-import { stat as fsStat, readdir } from 'node:fs/promises';
-import type { MiddlewareRoute, MiddlewareDiscoveryOptions } from './types.ts';
-
-/**
- * Default options for middleware discovery
- */
-const DEFAULT_OPTIONS: Required<Omit<MiddlewareDiscoveryOptions, 'baseDir'>> = {
-  filePattern: '_middleware.ts',
-  excludeDirs: ['node_modules', '.git', 'dist', '.output', '.vite'],
-  devMode: false,
-};
-
-/**
- * Base priority values for different middleware types
- * Lower values execute first
- */
-const PRIORITY_BASE = {
-  /** Page middleware base priority */
-  pages: 50,
-} as const;
-
-/**
- * Discovers route-scoped middleware files in the project
- *
- * Scans for _middleware.ts files in:
- * - src/pages/ directory (and subdirectories) for page routes
- *
- * API middleware is handled natively by Nitro and is not scanned here.
- *
- * Middleware files are sorted by priority (directory depth), ensuring
- * parent middleware executes before child middleware.
- *
- * @param options - Discovery options
- * @returns Array of discovered middleware routes, sorted by priority
- *
- * @example
- * ```ts
- * const routes = await discoverScopedMiddleware({
- *   baseDir: 'src',
- *   devMode: true,
- * });
- *
- * // Returns routes like:
- * // [
- * //   { pattern: URLPattern('/blog/*'), filePath: 'src/pages/blog/_middleware.ts', priority: 51, type: 'pages' },
- * // ]
- * ```
- */
-export async function discoverScopedMiddleware(
-  options: MiddlewareDiscoveryOptions
-): Promise<MiddlewareRoute[]> {
-  const {
-    baseDir,
-    filePattern = DEFAULT_OPTIONS.filePattern,
-    excludeDirs = DEFAULT_OPTIONS.excludeDirs,
-    devMode = DEFAULT_OPTIONS.devMode,
-  } = options;
-
-  const resolvedBaseDir = resolve(baseDir);
-  const routes: MiddlewareRoute[] = [];
-
-  // Scan pages directory for page middleware
-  const pagesDir = join(resolvedBaseDir, 'pages');
-  await scanDirectory(pagesDir, 'pages', filePattern, excludeDirs, routes, devMode);
-
-  // Sort by priority (lower numbers execute first)
-  routes.sort((a, b) => a.priority - b.priority);
-
-  if (devMode && routes.length > 0) {
-    console.log(`[middleware] Discovered ${routes.length} route-scoped middleware:`);
-    for (const route of routes) {
-      console.log(`  - ${route.type}: ${route.filePath} (priority: ${route.priority})`);
-    }
-  }
-
-  return routes;
-}
-
-/**
- * Scans a directory recursively for middleware files
- *
- * @param dir - Directory to scan
- * @param type - Middleware type ('pages')
- * @param filePattern - File pattern to match
- * @param excludeDirs - Directories to exclude
- * @param routes - Array to collect discovered routes
- * @param devMode - Whether to log debug information
- */
-async function scanDirectory(
-  dir: string,
-  type: 'pages',
-  filePattern: string,
-  excludeDirs: string[],
-  routes: MiddlewareRoute[],
-  devMode: boolean
-): Promise<void> {
-  try {
-    // Check if directory exists
-    const dirInfo = await fsStat(dir).catch(() => null);
-    if (!dirInfo?.isDirectory()) {
-      return;
-    }
-
-    // Recursively scan directory
-    await scanDirectoryRecursive(dir, dir, type, filePattern, excludeDirs, routes, devMode);
-  } catch (error) {
-    // Directory doesn't exist or can't be read - skip silently
-    if (devMode && (!(error instanceof Error) || (error as NodeJS.ErrnoException).code !== 'ENOENT')) {
-      console.warn(`[middleware] Error scanning ${dir}: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  }
-}
-
-/**
- * Recursively scans a directory for middleware files
- *
- * @param rootDir - Root directory being scanned
- * @param currentDir - Current directory being scanned
- * @param type - Middleware type
- * @param filePattern - File pattern to match
- * @param excludeDirs - Directories to exclude
- * @param routes - Array to collect discovered routes
- * @param devMode - Whether to log debug information
- */
-async function scanDirectoryRecursive(
-  rootDir: string,
-  currentDir: string,
-  type: 'pages',
-  filePattern: string,
-  excludeDirs: string[],
-  routes: MiddlewareRoute[],
-  devMode: boolean
-): Promise<void> {
-  try {
-    const entries = await readdir(currentDir, { withFileTypes: true });
-    for (const entry of entries) {
-      const fullPath = join(currentDir, entry.name);
-
-      // Skip excluded directories
-      if (entry.isDirectory() && excludeDirs.includes(entry.name)) {
-        continue;
-      }
-
-      if (entry.isDirectory()) {
-        // Recursively scan subdirectories
-        await scanDirectoryRecursive(rootDir, fullPath, type, filePattern, excludeDirs, routes, devMode);
-      } else if (entry.name === filePattern) {
-        // Found a middleware file
-        const relativePath = relative(rootDir, currentDir);
-        const route = createMiddlewareRoute(fullPath, relativePath, type);
-        routes.push(route);
-      }
-    }
-  } catch (error) {
-    if (devMode && (!(error instanceof Error) || (error as NodeJS.ErrnoException).code !== 'ENOENT')) {
-      console.warn(`[middleware] Error reading ${currentDir}: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  }
-}
-
-/**
- * Creates a middleware route configuration from a file path
- *
- * @param filePath - Absolute path to the middleware file
- * @param relativePath - Path relative to the pages directory
- * @param type - Middleware type
- * @returns Middleware route configuration
- *
- * @example
- * ```ts
- * // For src/pages/blog/_middleware.ts
- * createMiddlewareRoute('/abs/path/src/pages/blog/_middleware.ts', 'blog', 'pages')
- * // Returns: { pattern: URLPattern('/blog/*'), filePath: '...', priority: 51, type: 'pages' }
- * ```
- */
-function createMiddlewareRoute(
-  filePath: string,
-  relativePath: string,
-  type: 'pages'
-): MiddlewareRoute {
-  // Calculate URL pattern from relative path
-  // relativePath is the directory path relative to pages/
-  // e.g., 'blog' for src/pages/blog/_middleware.ts
-  // e.g., '' for src/pages/_middleware.ts (root middleware)
-
-  // Page middleware: /* or /blog{/*}?
-  // Use {/*}? to match both /blog and /blog/anything
-  const urlPattern = relativePath ? `/${relativePath}{/*}?` : '/*';
-
-  // Calculate priority based on directory depth
-  // Shallower directories have lower priority (execute first)
-  const depth = relativePath ? relativePath.split('/').filter(Boolean).length : 0;
-  const priority = PRIORITY_BASE[type] + depth;
-
-  return {
-    pattern: new URLPattern({ pathname: urlPattern }),
-    filePath,
-    priority,
-    type,
-  };
-}
-
-/**
- * Gets middleware routes that match a given URL
- *
- * Filters discovered routes to only include those that match the URL,
- * respecting type isolation (page middleware doesn't run for API routes
- * and vice versa).
- *
- * @param routes - All discovered middleware routes
- * @param url - URL to match against
- * @returns Matching routes, sorted by priority
- *
- * @example
- * ```ts
- * const allRoutes = await discoverScopedMiddleware({ baseDir: 'src' });
- * const matchingRoutes = getMatchingMiddleware(allRoutes, new URL('http://localhost/blog/post-1'));
- * ```
- */
-export function getMatchingMiddleware(
-  routes: MiddlewareRoute[],
-  url: URL
-): MiddlewareRoute[] {
-  const isApiRoute = url.pathname.startsWith('/api');
-
-  return routes.filter(route => {
-    // Check if pattern matches the URL
-    if (!route.pattern.test(url)) {
-      return false;
-    }
-
-    // Type isolation: page middleware doesn't run for API routes
-    if (route.type === 'pages' && isApiRoute) {
-      return false;
-    }
-
-    return true;
-  });
-}
-
-/**
- * Clears the middleware discovery cache
- *
- * This is a no-op in the simplified discovery module since we don't
- * maintain a persistent cache. The function is provided for API
- * compatibility with the executor module.
- */
-export function clearDiscoveryCache(): void {
-  // No-op: simplified discovery doesn't maintain a persistent cache
-  // Each call to discoverScopedMiddleware scans the file system
-}

package/src/middleware/executor.ts

@@ -1,315 +0,0 @@
-/**
- * Simplified Middleware Executor
- *
- * This module provides a streamlined middleware execution system that aligns
- * with Nitro's conventions while supporting Avalon's route-scoped middleware.
- *
- * Key features:
- * - Nitro-style handler signature: return void to continue, return Response to terminate
- * - Middleware caching for performance
-
- * - Error propagation to Nitro's error handling
- * - Context preservation: event.context modifications persist through the chain
- * - Development logging for context changes
- *
- * Requirements: 1.2, 1.3, 1.4, 2.1, 2.2
- */
-
-import type { H3Event } from 'h3';
-import type { MiddlewareHandler, MiddlewareRoute, MiddlewareFileExport, MiddlewareExecutorOptions } from './types.ts';
-import { getMatchingMiddleware } from './discovery.ts';
-
-/**
- * Captures a snapshot of the event context for comparison
- * Used in development mode to log context changes
- */
-function captureContextSnapshot(context: Record<string, unknown>): Map<string, unknown> {
-	const snapshot = new Map<string, unknown>();
-	for (const key of Object.keys(context)) {
-		snapshot.set(key, context[key]);
-	}
-	return snapshot;
-}
-
-/**
- * Compares two context snapshots and returns the changes
- * Used in development mode to log context modifications
- */
-function getContextChanges(
-	before: Map<string, unknown>,
-	after: Record<string, unknown>,
-): { added: string[]; modified: string[]; removed: string[] } {
-	const added: string[] = [];
-	const modified: string[] = [];
-	const removed: string[] = [];
-
-	for (const key of Object.keys(after)) {
-		if (!before.has(key)) {
-			added.push(key);
-		} else if (before.get(key) !== after[key]) {
-			modified.push(key);
-		}
-	}
-
-	for (const key of before.keys()) {
-		if (!(key in after)) {
-			removed.push(key);
-		}
-	}
-
-	return { added, modified, removed };
-}
-
-/**
- * Logs context changes in development mode
- * Requirements: 2.1, 2.2
- *
- * Note: Intentionally minimal to reduce log noise.
- * Uncomment the body for debugging middleware context issues.
- */
-function logContextChanges(
-	_filePath: string,
-	_changes: { added: string[]; modified: string[]; removed: string[] },
-): void {
-	// Uncomment for debugging middleware context issues:
-	// const hasChanges = _changes.added.length > 0 || _changes.modified.length > 0 || _changes.removed.length > 0;
-	// if (!hasChanges) return;
-	// console.log(`[middleware] Context changes in ${_filePath}: ...`);
-}
-
-/** Default executor options */
-const DEFAULT_OPTIONS: Required<MiddlewareExecutorOptions> = {
-	devMode: false,
-	timeout: 30000,
-};
-
-/** Middleware cache: maps file paths to loaded handlers */
-const middlewareCache = new Map<string, MiddlewareHandler>();
-
-/**
- * Executes a single middleware route handler with context tracking.
- * Returns the Response if the chain should terminate, undefined to continue.
- */
-async function executeMiddlewareRoute(
-	event: H3Event,
-	route: MiddlewareRoute,
-	devMode: boolean,
-	timeout: number,
-): Promise<Response | undefined> {
-	const handler = await loadMiddleware(route.filePath, devMode);
-	if (!handler) return undefined;
-
-	const contextBefore = devMode ? captureContextSnapshot(event.context) : null;
-
-	const result = await executeWithTimeout(() => handler(event), timeout, route.filePath);
-
-	if (devMode && contextBefore) {
-		const changes = getContextChanges(contextBefore, event.context);
-		logContextChanges(route.filePath, changes);
-	}
-
-	const response = handleMiddlewareResult(result, route.filePath, devMode);
-	if (response && devMode) {
-		console.log(`[middleware] Chain terminated by ${route.filePath}`);
-	}
-	return response;
-}
-
-/**
- * Executes route-scoped middleware chain for a request
- *
- * 1. Finds middleware that matches the request URL
- * 2. Executes them in priority order (parent before child)
- * 3. Handles void return (continue) and Response return (terminate)
- * 4. Propagates errors to Nitro's error handling
- * 5. Preserves event.context modifications across the chain
- * 6. Logs context changes in development mode
- *
- * @param event - H3 event object from Nitro
- * @param routes - Discovered middleware routes from discoverScopedMiddleware
- * @param options - Execution options
- * @returns Response if middleware terminated the chain, undefined otherwise
- */
-export async function executeScopedMiddleware(
-	event: H3Event,
-	routes: MiddlewareRoute[],
-	options: MiddlewareExecutorOptions = {},
-): Promise<Response | undefined> {
-	const { devMode, timeout } = { ...DEFAULT_OPTIONS, ...options };
-
-	const url = buildUrlFromEvent(event);
-	const matchingRoutes = getMatchingMiddleware(routes, url);
-
-	if (matchingRoutes.length === 0) {
-		return undefined;
-	}
-
-	for (const route of matchingRoutes) {
-		try {
-			const response = await executeMiddlewareRoute(event, route, devMode, timeout);
-			if (response) return response;
-		} catch (error) {
-			if (devMode) {
-				console.error(`[middleware] Error in ${route.filePath}:`, error);
-			}
-			throw error;
-		}
-	}
-
-	return undefined;
-}
-
-/**
- * Builds a URL object from an H3 event.
- * Supports both h3 v2 (event.url / event.req.url) and the dev-mode mock shape (event.path).
- */
-function buildUrlFromEvent(event: H3Event): URL {
-	const base = 'http://localhost';
-
-	// h3 v2: event.url is a string
-	if (typeof (event as any).url === 'string') {
-		return new URL((event as any).url, base);
-	}
-
-	// h3 v2: event.req is a Web Request
-	if ((event as any).req?.url) {
-		return new URL((event as any).req.url, base);
-	}
-
-	// Dev-mode mock: event.path
-	if ((event as any).path) {
-		return new URL((event as any).path, base);
-	}
-
-	// Legacy h3 v1: event.node.req.url
-	if ((event as any).node?.req?.url) {
-		return new URL((event as any).node.req.url, base);
-	}
-
-	return new URL('/', base);
-}
-
-/**
- * Converts an absolute file path to a valid ESM import specifier.
- * Windows absolute paths (C:\...) are converted to file:// URLs.
- * On Unix, the path is returned as-is (no-op).
- */
-export function toImportSpecifier(filePath: string): string {
-	if (/^[A-Za-z]:[\\/]/.test(filePath)) {
-		return `file:///${filePath.replaceAll('\\', '/')}`;
-	}
-	return filePath;
-}
-
-/**
- * Loads a middleware handler via Vite's ssrLoadModule (dev) or dynamic import (prod/worker).
- */
-async function loadMiddleware(filePath: string, devMode: boolean): Promise<MiddlewareHandler | null> {
-	if (!devMode && middlewareCache.has(filePath)) {
-		return middlewareCache.get(filePath)!;
-	}
-
-	try {
-		let module: MiddlewareFileExport;
-
-		const viteServer = globalThis.__viteDevServer;
-		if (devMode && viteServer) {
-			const viteRoot = viteServer.config.root || '';
-			const vitePath = filePath.startsWith(viteRoot) ? '/' + filePath.slice(viteRoot.length + 1) : filePath;
-			module = (await viteServer.ssrLoadModule(vitePath)) as MiddlewareFileExport;
-		} else {
-			const importPath = toImportSpecifier(filePath);
-			module = (await import(/* @vite-ignore */ importPath)) as MiddlewareFileExport;
-		}
-
-		if (!module.default || typeof module.default !== 'function') {
-			if (devMode) {
-				console.warn(`[middleware] ${filePath} does not export a default function`);
-			}
-			return null;
-		}
-
-		if (!devMode) {
-			middlewareCache.set(filePath, module.default);
-		}
-
-		return module.default;
-	} catch (error) {
-		if (devMode) {
-			console.error(`[middleware] Failed to load ${filePath}:`, error);
-		}
-		return null;
-	}
-}
-
-/**
- * Executes a middleware handler with a timeout
- */
-async function executeWithTimeout<T>(fn: () => T | Promise<T>, timeout: number, filePath: string): Promise<T> {
-	return Promise.race([
-		Promise.resolve(fn()),
-		new Promise<never>((_, reject) => {
-			setTimeout(() => {
-				reject(new Error(`Middleware timeout after ${timeout}ms: ${filePath}`));
-			}, timeout);
-		}),
-	]);
-}
-
-/**
- * Handles the result of a middleware execution.
- * Supports Nitro-style (void/Response) format.
- */
-function handleMiddlewareResult(result: unknown, filePath: string, devMode: boolean): Response | undefined {
-	if (result === undefined || result === null) {
-		return undefined;
-	}
-
-	if (result instanceof Response) {
-		return result;
-	}
-
-	if (devMode) {
-		console.warn(
-			`[middleware] ${filePath} returned unexpected value: ${typeof result}. ` +
-				`Expected void or Response.`,
-		);
-	}
-
-	return undefined;
-}
-
-/** Clears the middleware cache (e.g. during hot reload) */
-export function clearMiddlewareCache(): void {
-	middlewareCache.clear();
-}
-
-/** Removes a specific middleware from the cache */
-export function invalidateMiddleware(filePath: string): boolean {
-	return middlewareCache.delete(filePath);
-}
-
-/** Gets the current size of the middleware cache */
-export function getMiddlewareCacheSize(): number {
-	return middlewareCache.size;
-}
-
-/** Checks if a key exists in event.context */
-export function hasContextValue(event: H3Event, key: string): boolean {
-	return key in event.context;
-}
-
-/** Gets a typed value from event.context */
-export function getContextValue<T>(event: H3Event, key: string): T | undefined {
-	return event.context[key] as T | undefined;
-}
-
-/** Sets a value in event.context with optional development logging */
-export function setContextValue<T>(event: H3Event, key: string, value: T, devMode: boolean = false): void {
-	const isNew = !(key in event.context);
-	event.context[key] = value;
-
-	if (devMode) {
-		console.log(`[middleware] Context ${isNew ? 'set' : 'updated'}: ${key}`);
-	}
-}

package/src/middleware/index.ts

@@ -1,76 +0,0 @@
-/**
- * Avalon Middleware Module
- *
- * This module provides a Nitro-aligned middleware system for Avalon that supports
- * both global middleware (via Nitro's middleware/ directory) and route-scoped
- * middleware (via _middleware.ts files in page/API directories).
- *
- * Key features:
- * - Nitro-compatible handler signature: return void to continue, return Response to terminate
- * - Route-scoped middleware discovery in src/pages/ and src/api/
- * - Priority-based execution order (parent before child)
- * - Type-safe context augmentation for H3 events
- *
- * @example
- * ```ts
- * // Define middleware with proper typing
- * import { defineMiddleware } from 'avalon/middleware';
- * import { getHeader, createError } from 'h3';
- *
- * export default defineMiddleware(async (event) => {
- *   const token = getHeader(event, 'Authorization');
- *   if (!token) {
- *     throw createError({ statusCode: 401, message: 'Unauthorized' });
- *   }
- *   event.context.user = await validateToken(token);
- * });
- * ```
- *
- * @example
- * ```ts
- * // Discover and execute middleware in your server
- * import { discoverScopedMiddleware, executeScopedMiddleware } from 'avalon/middleware';
- *
- * const routes = await discoverScopedMiddleware({ baseDir: 'src', devMode: true });
- * const response = await executeScopedMiddleware(event, routes);
- * if (response) return response;
- * ```
- *
- * Requirements: 4.3
- */
-
-// =============================================================================
-// Type Exports
-// =============================================================================
-
-export type {
-	MiddlewareHandler,
-	MiddlewareFileExport,
-	MiddlewareRoute,
-	MiddlewareDiscoveryOptions,
-	MiddlewareExecutorOptions,
-} from './types.ts';
-
-// =============================================================================
-// Helper Functions (defineMiddleware removed — use defineHandler from 'nitro/h3')
-// =============================================================================
-
-// =============================================================================
-// Discovery Functions
-// =============================================================================
-
-export { discoverScopedMiddleware, getMatchingMiddleware, clearDiscoveryCache } from './discovery.ts';
-
-// =============================================================================
-// Executor Functions
-// =============================================================================
-
-export {
-	executeScopedMiddleware,
-	clearMiddlewareCache,
-	invalidateMiddleware,
-	getMiddlewareCacheSize,
-	hasContextValue,
-	getContextValue,
-	setContextValue,
-} from './executor.ts';