@useavalon/avalon 0.1.0

package/src/types/tests/layout-types.test.ts

@@ -0,0 +1,197 @@
+import { describe, it, expect } from 'vitest';
+import {
+	LayoutContextSchema,
+	LayoutDataSchema,
+	LayoutRouteSchema,
+	LayoutHandlerSchema,
+	LayoutPropsSchema,
+	LayoutDiscoveryOptionsSchema,
+	LayoutConfigSchema,
+	ResolvedLayoutSchema,
+} from '../../schemas/layout.ts';
+import { validators, safeValidators } from '../../schemas/index.ts';
+import type {
+	LayoutContext,
+	LayoutData,
+	LayoutRoute,
+	LayoutHandler,
+	LayoutProps,
+	LayoutDiscoveryOptions,
+	LayoutConfig,
+	ResolvedLayout,
+} from '../layout.ts';
+
+describe('Layout System Types and Schemas', () => {
+	it('LayoutContext - should validate valid layout context', () => {
+		const mockRequest = new Request('https://example.com/test');
+		const mockParams = { id: '123' };
+		const mockQuery = new URLSearchParams('?page=1');
+		const mockState = new Map();
+
+		const validContext: LayoutContext = {
+			request: mockRequest,
+			params: mockParams,
+			query: mockQuery,
+			state: mockState,
+		};
+
+		const result = safeValidators.layoutContext(validContext);
+		expect(result.success).toEqual(true);
+	});
+
+	it('LayoutContext - should reject invalid layout context', () => {
+		const invalidContext = {
+			request: 'not-a-request',
+			params: 'not-an-object',
+			query: 'not-urlsearchparams',
+			state: 'not-a-map',
+		};
+
+		const result = safeValidators.layoutContext(invalidContext);
+		expect(result.success).toEqual(false);
+	});
+
+	it('LayoutData - should validate layout data as record', () => {
+		const validData: LayoutData = {
+			user: { name: 'John', id: 123 },
+			settings: { theme: 'dark' },
+			items: [1, 2, 3],
+		};
+
+		const result = safeValidators.layoutData(validData);
+		expect(result.success).toEqual(true);
+	});
+
+	it('LayoutData - should accept empty layout data', () => {
+		const emptyData: LayoutData = {};
+
+		const result = safeValidators.layoutData(emptyData);
+		expect(result.success).toEqual(true);
+	});
+
+	it('LayoutHandler - should validate valid layout handler', () => {
+		const validHandler = {
+			component: () => null,
+			path: '/src/pages/blog/_layout.tsx',
+			priority: 10,
+		};
+
+		const result = safeValidators.layoutHandler(validHandler);
+		expect(result.success).toEqual(true);
+	});
+
+	it('LayoutDiscoveryOptions - should validate with defaults', () => {
+		const options = {
+			baseDirectory: '/src/pages',
+		};
+
+		const result = safeValidators.layoutDiscoveryOptions(options);
+		expect(result.success).toEqual(true);
+		if (result.success) {
+			expect(result.data.filePattern).toEqual('_layout.tsx');
+			expect(result.data.excludeDirectories).toEqual([]);
+			expect(result.data.enableWatching).toEqual(false);
+			expect(result.data.developmentMode).toEqual(false);
+		}
+	});
+
+	it('LayoutDiscoveryOptions - should validate with custom options', () => {
+		const options: LayoutDiscoveryOptions = {
+			baseDirectory: '/src/pages',
+			filePattern: 'layout.tsx',
+			excludeDirectories: ['node_modules', '.git'],
+			enableWatching: true,
+			developmentMode: true,
+		};
+
+		const result = safeValidators.layoutDiscoveryOptions(options);
+		expect(result.success).toEqual(true);
+		if (result.success) {
+			expect(result.data.filePattern).toEqual('layout.tsx');
+			expect(result.data.excludeDirectories).toEqual(['node_modules', '.git']);
+			expect(result.data.enableWatching).toEqual(true);
+			expect(result.data.developmentMode).toEqual(true);
+		}
+	});
+
+	it('LayoutConfig - should validate layout config with all options', () => {
+		const config: LayoutConfig = {
+			skipLayouts: ['root', 'admin'],
+			replaceLayout: true,
+			onlyLayouts: ['custom'],
+			customLayout: '/custom/layout.tsx',
+		};
+
+		const result = safeValidators.layoutConfig(config);
+		expect(result.success).toEqual(true);
+	});
+
+	it('LayoutConfig - should validate empty layout config', () => {
+		const config: LayoutConfig = {};
+
+		const result = safeValidators.layoutConfig(config);
+		expect(result.success).toEqual(true);
+	});
+
+	it('ResolvedLayout - should validate complete resolved layout', () => {
+		const resolvedLayout: ResolvedLayout = {
+			handlers: [],
+			dataLoaders: [],
+			errorBoundaries: [],
+			streamingComponents: [],
+			metadata: {
+				totalLayouts: 2,
+				resolutionTime: 15.5,
+				cacheHit: false,
+			},
+		};
+
+		const result = safeValidators.resolvedLayout(resolvedLayout);
+		expect(result.success).toEqual(true);
+	});
+
+	it('ResolvedLayout - should require all metadata fields', () => {
+		const incompleteLayout = {
+			handlers: [],
+			dataLoaders: [],
+			errorBoundaries: [],
+			streamingComponents: [],
+			metadata: {
+				totalLayouts: 2,
+			},
+		};
+
+		const result = safeValidators.resolvedLayout(incompleteLayout);
+		expect(result.success).toEqual(false);
+	});
+
+	it('Type compatibility - should ensure TypeScript types match Zod schemas', () => {
+		const mockRequest = new Request('https://example.com');
+		const layoutContext: LayoutContext = {
+			request: mockRequest,
+			params: { id: '123' },
+			query: new URLSearchParams(),
+			state: new Map(),
+		};
+
+		const validatedContext = validators.layoutContext(layoutContext);
+		expect(validatedContext).toBeDefined();
+		expect(validatedContext.request).toEqual(mockRequest);
+	});
+
+	it('Error handling - should provide meaningful error messages', () => {
+		const invalidData = {
+			request: null,
+			params: null,
+			query: null,
+			state: null,
+		};
+
+		const result = safeValidators.layoutContext(invalidData);
+		expect(result.success).toEqual(false);
+		if (!result.success) {
+			expect(result.error.message).toContain('Invalid layout context');
+			expect(result.error.getFormattedErrors().length > 0).toEqual(true);
+		}
+	});
+});

package/src/types/types.ts

@@ -0,0 +1,5 @@
+export type ImportConfig = { names: string[]; from: string };
+export type CleanupFunction = () => void;
+
+// Re-export layout types for convenience
+export * from './layout.ts';

package/src/types/urlpattern.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Global URLPattern type declaration.
+ * URLPattern is available at runtime in Node 22+, Bun, and Deno,
+ * but TypeScript's lib.dom.d.ts may not include it in all configurations.
+ */
+declare class URLPattern {
+	constructor(init?: URLPatternInit | string, baseURL?: string);
+	readonly protocol: string;
+	readonly username: string;
+	readonly password: string;
+	readonly hostname: string;
+	readonly port: string;
+	readonly pathname: string;
+	readonly search: string;
+	readonly hash: string;
+	test(input?: URLPatternInput, baseURL?: string): boolean;
+	exec(input?: URLPatternInput, baseURL?: string): URLPatternResult | null;
+}
+
+interface URLPatternInit {
+	baseURL?: string;
+	username?: string;
+	password?: string;
+	hostname?: string;
+	port?: string;
+	pathname?: string;
+	search?: string;
+	hash?: string;
+	protocol?: string;
+}
+
+type URLPatternInput = URLPatternInit | string;
+
+interface URLPatternComponentResult {
+	input: string;
+	groups: Record<string, string | undefined>;
+}
+
+interface URLPatternResult {
+	inputs: [URLPatternInput, string?];
+	protocol: URLPatternComponentResult;
+	username: URLPatternComponentResult;
+	password: URLPatternComponentResult;
+	hostname: URLPatternComponentResult;
+	port: URLPatternComponentResult;
+	pathname: URLPatternComponentResult;
+	search: URLPatternComponentResult;
+	hash: URLPatternComponentResult;
+}

package/src/types/vite-env.d.ts

@@ -0,0 +1,11 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+	readonly VITE_APP_TITLE: string;
+	// more env variables...
+}
+
+interface ImportMeta {
+	readonly env: ImportMetaEnv;
+	readonly hot?: import('vite/types/hot').ViteHotContext;
+}

package/src/utils/dev-logger.ts

@@ -0,0 +1,299 @@
+/**
+ * Dev-Only Logging Utilities
+ * 
+ * These functions provide environment-aware logging that only outputs in development mode.
+ * In production (NODE_ENV=production), all logging is suppressed for better performance.
+ * 
+ * @module dev-logger
+ */
+
+// ============================================================================
+// Environment Detection
+// ============================================================================
+
+/**
+ * Check if we're in development mode
+ * Returns true if NODE_ENV is not set to "production"
+ */
+export function isDev(): boolean {
+  try {
+    return process.env.NODE_ENV !== "production";
+  } catch {
+    return true; // Default to dev mode if we can't check
+  }
+}
+
+/**
+ * Check if verbose logging is enabled
+ * Returns true only if AVALON_VERBOSE=1 is set
+ */
+export function isVerbose(): boolean {
+  try {
+    return process.env.AVALON_VERBOSE === "1";
+  } catch {
+    return false;
+  }
+}
+
+// ============================================================================
+// Dev-Only Logging Functions
+// ============================================================================
+
+/**
+ * Log a message only in development mode AND when AVALON_VERBOSE=1 is set.
+ * By default this is a no-op — set AVALON_VERBOSE=1 to enable diagnostic output.
+ * 
+ * @param args - Arguments to pass to console.log
+ */
+export function devLog(...args: unknown[]): void {
+  if (isDev() && isVerbose()) {
+    console.log(...args);
+  }
+}
+
+/**
+ * Log a warning only in development mode
+ * In production, this is a no-op for performance
+ * 
+ * @param args - Arguments to pass to console.warn
+ */
+export function devWarn(...args: unknown[]): void {
+  if (isDev()) {
+    console.warn(...args);
+  }
+}
+
+/**
+ * Log an error only in development mode
+ * In production, this is a no-op for performance
+ * 
+ * @param args - Arguments to pass to console.error
+ */
+export function devError(...args: unknown[]): void {
+  if (isDev()) {
+    console.error(...args);
+  }
+}
+
+// ============================================================================
+// Performance Tracking
+// ============================================================================
+
+/** Default threshold for slow render warnings (in milliseconds) */
+const DEFAULT_SLOW_RENDER_THRESHOLD = 100;
+
+/**
+ * Log render timing information for an island component
+ * Only logs in development mode AND when AVALON_VERBOSE=1 is set
+ * Warns when render time exceeds the threshold
+ * 
+ * @param src - The island source path
+ * @param durationMs - The render duration in milliseconds
+ * @param threshold - Optional threshold for slow render warning (default: 100ms)
+ */
+export function logRenderTiming(
+  src: string, 
+  durationMs: number, 
+  threshold: number = DEFAULT_SLOW_RENDER_THRESHOLD
+): void {
+  if (!isDev() || !isVerbose()) return;
+  
+  if (durationMs > threshold) {
+    console.warn(`⚠️ Slow island render: ${src} took ${durationMs.toFixed(2)}ms`);
+  } else {
+    console.log(`🏝️ ${src} rendered in ${durationMs.toFixed(2)}ms`);
+  }
+}
+
+/**
+ * Log a cache hit event (dev mode only)
+ * 
+ * @param cacheType - The type of cache (e.g., 'analysis', 'path', 'framework')
+ * @param key - The cache key that was hit
+ */
+export function logCacheHit(cacheType: string, key: string): void {
+  if (!isDev() || !isVerbose()) return;
+  console.log(`📦 Cache HIT [${cacheType}]: ${key}`);
+}
+
+/**
+ * Log a cache miss event (dev mode only)
+ * 
+ * @param cacheType - The type of cache (e.g., 'analysis', 'path', 'framework')
+ * @param key - The cache key that was missed
+ */
+export function logCacheMiss(cacheType: string, key: string): void {
+  if (!isDev() || !isVerbose()) return;
+  console.log(`📭 Cache MISS [${cacheType}]: ${key}`);
+}
+
+// ============================================================================
+// DevLogger Class (for Development Server UI)
+// ============================================================================
+
+const AVALON_ASCII = `
+ █████╗ ██╗   ██╗ █████╗ ██╗      ██████╗ ███╗   ██╗
+██╔══██╗██║   ██║██╔══██╗██║     ██╔═══██╗████╗  ██║
+███████║██║   ██║███████║██║     ██║   ██║██╔██╗ ██║
+██╔══██║╚██╗ ██╔╝██╔══██║██║     ██║   ██║██║╚██╗██║
+██║  ██║ ╚████╔╝ ██║  ██║███████╗╚██████╔╝██║ ╚████║
+╚═╝  ╚═╝  ╚═══╝  ╚═╝  ╚═╝╚══════╝ ╚═════╝ ╚═╝  ╚═══╝
+`;
+
+const COLORS = {
+  reset: '\x1b[0m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  gray: '\x1b[90m',
+  bold: '\x1b[1m',
+};
+
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+
+interface DevTask {
+  name: string;
+  status: 'pending' | 'running' | 'done';
+  startTime?: number;
+}
+
+export class DevLogger {
+  private readonly tasks: Map<string, DevTask> = new Map();
+  private spinnerInterval?: ReturnType<typeof setInterval>;
+  private currentFrame = 0;
+  private readonly startTime = Date.now();
+  private readonly originalConsoleLog: typeof console.log;
+  private readonly originalConsoleWarn: typeof console.warn;
+  private readonly originalConsoleError: typeof console.error;
+  private readonly suppressedLogs: string[] = [];
+  private readonly headerLines: number = 0;
+
+  constructor() {
+    this.originalConsoleLog = console.log;
+    this.originalConsoleWarn = console.warn;
+    this.originalConsoleError = console.error;
+    
+    this.suppressConsole();
+    
+    // Clear screen once at start
+    process.stdout.write('\x1b[2J\x1b[H');
+    
+    const header = COLORS.cyan + AVALON_ASCII + COLORS.reset + '\n' +
+                   COLORS.gray + '  Development Server' + COLORS.reset + '\n\n';
+    this.headerLines = AVALON_ASCII.split('\n').length + 2;
+    
+    process.stdout.write(header);
+  }
+
+  private suppressConsole() {
+    console.log = (...args: unknown[]) => {
+      this.suppressedLogs.push(args.map(String).join(' '));
+    };
+    console.warn = (...args: unknown[]) => {
+      this.suppressedLogs.push('[WARN] ' + args.map(String).join(' '));
+    };
+    console.error = this.originalConsoleError;
+  }
+
+  restoreConsole() {
+    console.log = this.originalConsoleLog;
+    console.warn = this.originalConsoleWarn;
+    console.error = this.originalConsoleError;
+  }
+
+
+
+  addTask(id: string, name: string) {
+    this.tasks.set(id, { name, status: 'pending' });
+    this.render();
+  }
+
+  startTask(id: string) {
+    const task = this.tasks.get(id);
+    if (task) {
+      task.status = 'running';
+      task.startTime = Date.now();
+      this.render();
+    }
+  }
+
+  completeTask(id: string) {
+    const task = this.tasks.get(id);
+    if (task) {
+      task.status = 'done';
+      this.render();
+    }
+  }
+
+
+  private render() {
+    let currentTask: DevTask | null = null;
+    for (const task of this.tasks.values()) {
+      if (task.status === 'running') {
+        currentTask = task;
+        break;
+      }
+    }
+    
+    // Use carriage return to overwrite the same line
+    let output = '\r'; // Return to start of line
+    
+    if (currentTask) {
+      const spinner = COLORS.cyan + SPINNER_FRAMES[this.currentFrame] + COLORS.reset;
+      output += `${spinner} ${currentTask.name}`;
+    } else {
+      output += `${COLORS.gray}Initializing...${COLORS.reset}`;
+    }
+    
+    // Clear to end of line
+    output += '\x1b[K';
+    
+    process.stdout.write(output);
+  }
+
+  startSpinner() {
+    this.spinnerInterval = setInterval(() => {
+      this.currentFrame = (this.currentFrame + 1) % SPINNER_FRAMES.length;
+      this.render();
+    }, 100);
+  }
+
+  stopSpinner() {
+    if (this.spinnerInterval) {
+      clearInterval(this.spinnerInterval);
+    }
+  }
+
+  finish(serverUrl: string, viteUrl?: string, hmrUrl?: string) {
+    this.stopSpinner();
+    
+    // Clear the status line
+    let output = `\x1b[${this.headerLines + 1};0H`;
+    output += '\x1b[J'; // Clear from cursor down
+    process.stdout.write(output);
+    
+    const elapsed = ((Date.now() - this.startTime) / 1000).toFixed(1);
+    
+    this.originalConsoleLog('');
+    this.originalConsoleLog(COLORS.green + COLORS.bold + '✨ Server ready!' + COLORS.reset);
+    this.originalConsoleLog('');
+    this.originalConsoleLog(COLORS.cyan + '  ➜  ' + COLORS.reset + COLORS.bold + 'Local:   ' + COLORS.reset + COLORS.cyan + serverUrl + COLORS.reset);
+    
+    if (viteUrl) {
+      this.originalConsoleLog(COLORS.cyan + '  ➜  ' + COLORS.reset + COLORS.bold + 'Vite:    ' + COLORS.reset + COLORS.gray + viteUrl + COLORS.reset);
+    }
+    
+    if (hmrUrl) {
+      this.originalConsoleLog(COLORS.cyan + '  ➜  ' + COLORS.reset + COLORS.bold + 'HMR:     ' + COLORS.reset + COLORS.gray + hmrUrl + COLORS.reset);
+    }
+    
+    this.originalConsoleLog('');
+    this.originalConsoleLog(COLORS.gray + `  Ready in ${elapsed}s` + COLORS.reset);
+    this.originalConsoleLog('');
+    this.originalConsoleLog(COLORS.gray + '  Press Ctrl+C to stop' + COLORS.reset);
+    this.originalConsoleLog('');
+    
+  }
+}

package/src/utils/fs.ts

@@ -0,0 +1,151 @@
+/**
+ * Filesystem utilities for Avalon.
+ * Provides Node.js-compatible implementations of common filesystem
+ * functions used throughout the codebase.
+ */
+
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+export interface WalkEntry {
+  path: string;
+  name: string;
+  isFile: boolean;
+  isDirectory: boolean;
+  isSymlink: boolean;
+}
+
+export interface WalkOptions {
+  maxDepth?: number;
+  includeFiles?: boolean;
+  includeDirs?: boolean;
+  includeSymlinks?: boolean;
+  match?: RegExp[];
+  skip?: RegExp[];
+  exts?: string[];
+}
+
+/**
+ * Walks a directory tree yielding entries, compatible with @std/fs walk().
+ */
+export async function* walk(
+  root: string,
+  options: WalkOptions = {},
+): AsyncIterableIterator<WalkEntry> {
+  const {
+    maxDepth = Infinity,
+    includeFiles = true,
+    includeDirs = true,
+    exts,
+    match,
+    skip,
+  } = options;
+
+  yield* walkSync(root, 0, { maxDepth, includeFiles, includeDirs, exts, match, skip });
+}
+
+interface WalkSyncState {
+  maxDepth: number;
+  includeFiles: boolean;
+  includeDirs: boolean;
+  exts?: string[];
+  match?: RegExp[];
+  skip?: RegExp[];
+}
+
+function matchesFile(name: string, fullPath: string, opts: WalkSyncState): boolean {
+  if (opts.exts && !opts.exts.some((ext) => name.endsWith(ext))) return false;
+  if (opts.match && !opts.match.some((r) => r.test(fullPath))) return false;
+  return true;
+}
+
+function matchesDir(fullPath: string, match?: RegExp[]): boolean {
+  return !match || match.some((r) => r.test(fullPath));
+}
+
+function* walkSync(
+  dir: string,
+  depth: number,
+  opts: WalkSyncState,
+): Generator<WalkEntry> {
+  if (depth > opts.maxDepth) return;
+
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+
+    if (opts.skip?.some((r) => r.test(fullPath))) continue;
+
+    const walkEntry: WalkEntry = {
+      path: fullPath,
+      name: entry.name,
+      isFile: entry.isFile(),
+      isDirectory: entry.isDirectory(),
+      isSymlink: entry.isSymbolicLink(),
+    };
+
+    if (entry.isDirectory()) {
+      if (opts.includeDirs && matchesDir(fullPath, opts.match)) {
+        yield walkEntry;
+      }
+      yield* walkSync(fullPath, depth + 1, opts);
+    } else if (entry.isFile() && opts.includeFiles && matchesFile(entry.name, fullPath, opts)) {
+      yield walkEntry;
+    }
+  }
+}
+
+/**
+ * Ensures a directory exists, creating it recursively if needed.
+ */
+export async function ensureDir(dir: string): Promise<void> {
+  const { mkdirSync } = await import("node:fs");
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch {
+    // Directory already exists
+  }
+}
+
+/**
+ * Check if a file or directory exists.
+ */
+export function exists(path: string): Promise<boolean> {
+  try {
+    statSync(path);
+    return Promise.resolve(true);
+  } catch {
+    return Promise.resolve(false);
+  }
+}
+
+/**
+ * Synchronous check if a file or directory exists.
+ */
+export function existsSync(path: string): boolean {
+  try {
+    statSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Empties a directory by removing all contents.
+ */
+export async function emptyDir(dir: string): Promise<void> {
+  const { rmSync, mkdirSync } = await import("node:fs");
+  try {
+    rmSync(dir, { recursive: true, force: true });
+  } catch {
+    // Directory doesn't exist
+  }
+  mkdirSync(dir, { recursive: true });
+}