@useavalon/avalon 0.1.0

package/src/layout-system.ts

@@ -0,0 +1,218 @@
+/**
+ * Advanced Layout System - Complete Export Index
+ *
+ * This file provides a comprehensive export index for the entire layout system,
+ * making it easy to import all layout-related functionality from a single location.
+ */
+
+// === Core Layout System ===
+
+// Layout Discovery
+export { LayoutDiscovery } from './core/layout/layout-discovery.ts';
+export type { LayoutDiscoveryOptions, LayoutRoute } from './schemas/layout.ts';
+
+// Layout Data Loading
+export {
+	LayoutDataLoader,
+	LayoutDataLoadingError,
+	loadSingleLayoutData,
+	mergeLayoutData,
+	getParentLayoutData,
+	defaultLayoutDataLoader,
+} from './core/layout/layout-data-loader.ts';
+export type { LayoutDataLoadingResult, LayoutDataLoadingOptions } from './core/layout/layout-data-loader.ts';
+
+// Layout Matching and Conditional Rendering
+export { LayoutMatcher as LayoutMatcherClass, BuiltInLayoutRules } from './core/layout/layout-matcher.ts';
+export type { LayoutRule, RouteInfo } from './schemas/layout.ts';
+
+// Layout Composition Control
+export { LayoutComposer } from './core/layout/layout-composer.ts';
+export type { LayoutConfig } from './schemas/layout.ts';
+
+// Enhanced Layout Resolver
+export {
+	EnhancedLayoutResolver,
+	createEnhancedLayoutResolver,
+	EnhancedLayoutResolverUtils,
+} from './core/layout/enhanced-layout-resolver.ts';
+export type { EnhancedLayoutResolverOptions } from './core/layout/enhanced-layout-resolver.ts';
+
+// === Persistent Islands System ===
+
+export { IslandPersistence, defaultIslandPersistence } from './core/islands/island-persistence.ts';
+export { IslandStateSerializer } from './core/islands/island-state-serializer.ts';
+export {
+	createPersistentIslandContext,
+	usePersistentIslandContext,
+	PersistentIslandProvider,
+} from './core/islands/persistent-island-context.tsx';
+export { PersistentIsland } from './components/PersistentIsland.tsx';
+export type { IslandState, PersistentIslandProps, PersistentIslandContext } from './schemas/layout.ts';
+
+// === Error Boundary System ===
+
+export { LayoutErrorBoundary } from './components/LayoutErrorBoundary.tsx';
+export { LayoutDataErrorBoundary } from './components/LayoutDataErrorBoundary.tsx';
+export { IslandErrorBoundary, withIslandErrorBoundary } from './components/IslandErrorBoundary.tsx';
+export { StreamingErrorBoundary, withStreamingErrorBoundary } from './components/StreamingErrorBoundary.tsx';
+export type { LayoutErrorInfo, LayoutErrorBoundaryProps, ErrorRecoveryStrategy } from './schemas/layout.ts';
+
+// === Streaming System ===
+
+export { StreamingLayout, StreamingSuspense, withStreaming, useStreamingState } from './components/StreamingLayout.tsx';
+export type { StreamingLayoutProps, StreamingComponent } from './schemas/layout.ts';
+
+// === Layout Utilities (Essential Only) ===
+// Debug and performance utilities are available via lazy import from './core/layout/layout-utilities.ts'
+// when needed in development mode
+
+export { LayoutCacheManager } from './core/layout/layout-cache-manager.ts';
+export type {
+	CacheEntry,
+	CacheStats,
+	CacheConfig,
+} from './core/layout/layout-cache-manager.ts';
+
+// === Core Types and Schemas ===
+
+export type {
+	LayoutContext,
+	LayoutData,
+	LayoutHandler,
+	LayoutProps,
+	LayoutLoader,
+	ResolvedLayout,
+	LayoutCache,
+	EnhancedLayoutContext,
+	LayoutMatcherFunction,
+	LayoutErrorHandler,
+	LayoutRetryFunction,
+	LayoutFallbackRenderer,
+	IslandStateSaver,
+	IslandStateLoader,
+	IslandStateClearer,
+	StreamingReadyCheck,
+} from './schemas/layout.ts';
+
+// === Advanced Interface Types ===
+
+export type {
+	ILayoutDiscovery,
+	ILayoutMatcher,
+	ILayoutComposer,
+	IIslandPersistence,
+	ILayoutErrorRecovery,
+	ILayoutStreaming,
+	IEnhancedLayoutResolver,
+	ILayoutComponent,
+	IPersistentIslandComponent,
+	ILayoutErrorBoundaryComponent,
+	IStreamingLayoutComponent,
+	LayoutModule,
+	PageModule,
+	LayoutResolutionContext,
+	LayoutPerformanceMetrics,
+	LayoutDebugInfo,
+	LayoutEventType,
+	LayoutEventData,
+	LayoutEventHandler,
+	ILayoutEventEmitter,
+} from './types/layout.ts';
+
+// === Validation Schemas ===
+
+export {
+	LayoutContextSchema,
+	LayoutDataSchema,
+	LayoutRouteSchema,
+	LayoutHandlerSchema,
+	LayoutPropsSchema,
+	LayoutDiscoveryOptionsSchema,
+	RouteInfoSchema,
+	LayoutRuleSchema,
+	LayoutConfigSchema,
+	IslandStateSchema,
+	PersistentIslandPropsSchema,
+	PersistentIslandContextSchema,
+	LayoutErrorInfoSchema,
+	LayoutErrorBoundaryPropsSchema,
+	ErrorRecoveryStrategySchema,
+	StreamingLayoutPropsSchema,
+	StreamingComponentSchema,
+	ResolvedLayoutSchema,
+	LayoutCacheSchema,
+	EnhancedLayoutContextSchema,
+} from './schemas/layout.ts';
+
+// === Convenience Re-exports ===
+
+// Main layout system class for easy access
+export { EnhancedLayoutResolver as LayoutSystem } from './core/layout/enhanced-layout-resolver.ts';
+
+// Default instances for quick setup
+export { defaultIslandPersistence as defaultPersistence } from './core/islands/island-persistence.ts';
+// Note: defaultLayoutUtilities removed to reduce cold start overhead
+// Import directly from './core/layout/layout-utilities.ts' if needed
+
+// Factory functions for custom setups
+export { createEnhancedLayoutResolver as createLayoutSystem } from './core/layout/enhanced-layout-resolver.ts';
+
+/**
+ * Layout System Version Information
+ */
+export const LAYOUT_SYSTEM_VERSION = '1.0.0';
+
+/**
+ * Layout System Feature Flags
+ */
+export const LAYOUT_SYSTEM_FEATURES = {
+	DISCOVERY: true,
+	DATA_LOADING: true,
+	CONDITIONAL_RENDERING: true,
+	COMPOSITION_CONTROL: true,
+	PERSISTENT_ISLANDS: true,
+	ERROR_BOUNDARIES: true,
+	STREAMING: true,
+	CACHING: true,
+	PERFORMANCE_MONITORING: true,
+	DEBUG_UTILITIES: true,
+} as const;
+
+/**
+ * Layout System Configuration Defaults
+ */
+export const LAYOUT_SYSTEM_DEFAULTS = {
+	DISCOVERY: {
+		baseDirectory: 'src/pages',
+		filePattern: '_layout.tsx',
+		excludeDirectories: ['node_modules', '.git', 'dist'],
+		enableWatching: false,
+		developmentMode: false,
+	},
+	CACHING: {
+		enabled: true,
+		ttl: 300000, // 5 minutes
+		maxSize: 100,
+		cleanupInterval: 60000, // 1 minute
+	},
+	STREAMING: {
+		enabled: true,
+		priority: 'medium' as const,
+		timeout: 5000,
+	},
+	ERROR_BOUNDARIES: {
+		enabled: true,
+		maxRetries: 3,
+		fallbackStrategy: 'component' as const,
+	},
+	PERFORMANCE: {
+		monitoring: true,
+		thresholds: {
+			discoveryTime: 100,
+			dataLoadingTime: 500,
+			renderingTime: 200,
+			totalTime: 1000,
+		},
+	},
+} as const;

package/src/middleware/__tests__/discovery.test.ts

@@ -0,0 +1,107 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { join } from 'node:path';
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { discoverScopedMiddleware, getMatchingMiddleware } from '../discovery.ts';
+
+describe('discoverScopedMiddleware', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'middleware-test-'));
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  it('discovers _middleware.ts files in pages subdirectories', async () => {
+    // Create pages directory structure with middleware files
+    await mkdir(join(tempDir, 'pages', 'admin'), { recursive: true });
+    await mkdir(join(tempDir, 'pages', 'blog'), { recursive: true });
+    await writeFile(join(tempDir, 'pages', 'admin', '_middleware.ts'), 'export default () => {};');
+    await writeFile(join(tempDir, 'pages', 'blog', '_middleware.ts'), 'export default () => {};');
+
+    const routes = await discoverScopedMiddleware({ baseDir: tempDir });
+
+    expect(routes).toHaveLength(2);
+    expect(routes.every(r => r.type === 'pages')).toBe(true);
+    expect(routes.map(r => r.filePath)).toEqual(
+      expect.arrayContaining([
+        join(tempDir, 'pages', 'admin', '_middleware.ts'),
+        join(tempDir, 'pages', 'blog', '_middleware.ts'),
+      ])
+    );
+  });
+
+  it('discovers nested _middleware.ts files with correct priority ordering', async () => {
+    await mkdir(join(tempDir, 'pages', 'admin', 'users'), { recursive: true });
+    await writeFile(join(tempDir, 'pages', 'admin', '_middleware.ts'), 'export default () => {};');
+    await writeFile(join(tempDir, 'pages', 'admin', 'users', '_middleware.ts'), 'export default () => {};');
+
+    const routes = await discoverScopedMiddleware({ baseDir: tempDir });
+
+    expect(routes).toHaveLength(2);
+    // Parent middleware (depth 1) should come before child (depth 2)
+    expect(routes[0].priority).toBeLessThan(routes[1].priority);
+    expect(routes[0].filePath).toContain(join('admin', '_middleware.ts'));
+    expect(routes[1].filePath).toContain(join('admin', 'users', '_middleware.ts'));
+  });
+
+  it('does NOT scan api directory for middleware', async () => {
+    await mkdir(join(tempDir, 'pages', 'admin'), { recursive: true });
+    await mkdir(join(tempDir, 'api', 'admin'), { recursive: true });
+    await writeFile(join(tempDir, 'pages', 'admin', '_middleware.ts'), 'export default () => {};');
+    await writeFile(join(tempDir, 'api', 'admin', '_middleware.ts'), 'export default () => {};');
+
+    const routes = await discoverScopedMiddleware({ baseDir: tempDir });
+
+    expect(routes).toHaveLength(1);
+    expect(routes[0].type).toBe('pages');
+    expect(routes[0].filePath).toContain(join('pages', 'admin', '_middleware.ts'));
+  });
+
+  it('returns empty array when no middleware files exist', async () => {
+    await mkdir(join(tempDir, 'pages'), { recursive: true });
+
+    const routes = await discoverScopedMiddleware({ baseDir: tempDir });
+
+    expect(routes).toHaveLength(0);
+  });
+
+  it('returns empty array when pages directory does not exist', async () => {
+    const routes = await discoverScopedMiddleware({ baseDir: tempDir });
+
+    expect(routes).toHaveLength(0);
+  });
+});
+
+describe('getMatchingMiddleware', () => {
+  it('matches page middleware for page routes', () => {
+    const routes = [
+      {
+        pattern: new URLPattern({ pathname: '/admin{/*}?' }),
+        filePath: '/src/pages/admin/_middleware.ts',
+        priority: 51,
+        type: 'pages' as const,
+      },
+    ];
+
+    const matches = getMatchingMiddleware(routes, new URL('http://localhost/admin/dashboard'));
+    expect(matches).toHaveLength(1);
+  });
+
+  it('does not match page middleware for API routes', () => {
+    const routes = [
+      {
+        pattern: new URLPattern({ pathname: '/*' }),
+        filePath: '/src/pages/_middleware.ts',
+        priority: 50,
+        type: 'pages' as const,
+      },
+    ];
+
+    const matches = getMatchingMiddleware(routes, new URL('http://localhost/api/users'));
+    expect(matches).toHaveLength(0);
+  });
+});

package/src/middleware/discovery.ts

@@ -0,0 +1,268 @@
+/**
+ * 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
+}