@useavalon/avalon 0.1.0

package/src/core/modules/framework-module-resolver.ts

@@ -0,0 +1,273 @@
+/**
+ * Framework-aware module resolver for handling framework-specific path transformations
+ * and MIME type resolution during hydration and module serving.
+ */
+
+export interface ModuleResolutionConfig {
+	framework: string;
+	baseUrl: string;
+	extensions: string[];
+	transformPath: (path: string) => string;
+	mimeType: string;
+}
+
+export interface ResolvedModule {
+	originalPath: string;
+	resolvedPath: string;
+	framework: string;
+	shouldTransform: boolean;
+	mimeType: string;
+	url: string;
+}
+
+export interface FrameworkModuleConfig {
+	extensions: string[];
+	hydrationExtension: string;
+	mimeType: string;
+	transformPath: (path: string, mode: 'development' | 'production') => string;
+}
+
+/**
+ * Framework-specific module configurations
+ */
+const FRAMEWORK_MODULE_CONFIGS: Record<string, FrameworkModuleConfig> = {
+	solid: {
+		extensions: ['.tsx', '.jsx'],
+		hydrationExtension: '.js',
+		mimeType: 'application/javascript',
+		transformPath: (path: string, mode: 'development' | 'production') => {
+			// For Solid, transform .tsx to .js for hydration
+			if (path.endsWith('.tsx')) {
+				return path.replace(/\.tsx$/, '.js');
+			}
+			if (path.endsWith('.jsx')) {
+				return path.replace(/\.jsx$/, '.js');
+			}
+			return path;
+		},
+	},
+	preact: {
+		extensions: ['.tsx', '.jsx'],
+		hydrationExtension: '.js',
+		mimeType: 'application/javascript',
+		transformPath: (path: string, mode: 'development' | 'production') => {
+			// For Preact, transform .tsx/.jsx to .js for hydration
+			if (path.endsWith('.tsx')) {
+				return path.replace(/\.tsx$/, '.js');
+			}
+			if (path.endsWith('.jsx')) {
+				return path.replace(/\.jsx$/, '.js');
+			}
+			return path;
+		},
+	},
+	vue: {
+		extensions: ['.vue'],
+		hydrationExtension: '.js',
+		mimeType: 'application/javascript',
+		transformPath: (path: string, mode: 'development' | 'production') => {
+			// Vue components are typically compiled to .js
+			if (path.endsWith('.vue')) {
+				return path.replace(/\.vue$/, '.js');
+			}
+			return path;
+		},
+	},
+	svelte: {
+		extensions: ['.svelte'],
+		hydrationExtension: '.js',
+		mimeType: 'application/javascript',
+		transformPath: (path: string, mode: 'development' | 'production') => {
+			// Svelte components are compiled to .js
+			if (path.endsWith('.svelte')) {
+				return path.replace(/\.svelte$/, '.js');
+			}
+			return path;
+		},
+	},
+	qwik: {
+		extensions: ['.tsx', '.jsx'],
+		hydrationExtension: '.js',
+		mimeType: 'application/javascript',
+		transformPath: (path: string, mode: 'development' | 'production') => {
+			// Qwik components are compiled to .js via the Qwik optimizer
+			if (path.endsWith('.tsx')) {
+				return path.replace(/\.tsx$/, '.js');
+			}
+			if (path.endsWith('.jsx')) {
+				return path.replace(/\.jsx$/, '.js');
+			}
+			return path;
+		},
+	},
+};
+
+export class FrameworkModuleResolver {
+	private mode: 'development' | 'production';
+	private baseUrl: string;
+
+	constructor(mode: 'development' | 'production' = 'development', baseUrl = '') {
+		this.mode = mode;
+		this.baseUrl = baseUrl;
+	}
+
+	/**
+	 * Resolve a module path for a specific framework
+	 */
+	resolveModule(
+		originalPath: string,
+		framework: string,
+		options: {
+			forHydration?: boolean;
+			baseUrl?: string;
+		} = {}
+	): ResolvedModule {
+		const config = FRAMEWORK_MODULE_CONFIGS[framework];
+		if (!config) {
+			throw new Error(`Unknown framework: ${framework}`);
+		}
+
+		const { forHydration = false, baseUrl = this.baseUrl } = options;
+
+		let resolvedPath = originalPath;
+		let shouldTransform = false;
+		let mimeType = this.getMimeType(originalPath);
+
+		// Apply framework-specific path transformation for hydration
+		if (forHydration) {
+			const transformedPath = config.transformPath(originalPath, this.mode);
+			if (transformedPath !== originalPath) {
+				resolvedPath = transformedPath;
+				shouldTransform = true;
+				mimeType = config.mimeType;
+			}
+		}
+
+		// Generate the full URL
+		const url = this.generateModuleUrl(resolvedPath, baseUrl);
+
+		return {
+			originalPath,
+			resolvedPath,
+			framework,
+			shouldTransform,
+			mimeType,
+			url,
+		};
+	}
+
+	/**
+	 * Check if a path needs transformation for the given framework
+	 */
+	needsTransformation(path: string, framework: string): boolean {
+		const config = FRAMEWORK_MODULE_CONFIGS[framework];
+		if (!config) {
+			return false;
+		}
+
+		const transformedPath = config.transformPath(path, this.mode);
+		return transformedPath !== path;
+	}
+
+	/**
+	 * Get the appropriate MIME type for a file path
+	 */
+	getMimeType(path: string): string {
+		const ext = this.getFileExtension(path);
+
+		switch (ext) {
+			case '.js':
+			case '.mjs':
+				return 'application/javascript';
+			case '.ts':
+			case '.tsx':
+			case '.jsx':
+				return 'application/javascript'; // These are typically compiled to JS
+			case '.css':
+				return 'text/css';
+			case '.json':
+				return 'application/json';
+			case '.vue':
+			case '.svelte':
+				return 'application/javascript'; // Compiled components
+			default:
+				return 'text/plain';
+		}
+	}
+
+	/**
+	 * Generate a module URL for the given path
+	 */
+	generateModuleUrl(path: string, baseUrl = this.baseUrl): string {
+		// Ensure path starts with /
+		const normalizedPath = path.startsWith('/') ? path : `/${path}`;
+
+		if (baseUrl) {
+			return `${baseUrl.replace(/\/$/, '')}${normalizedPath}`;
+		}
+
+		return normalizedPath;
+	}
+
+	/**
+	 * Get supported frameworks
+	 */
+	getSupportedFrameworks(): string[] {
+		return Object.keys(FRAMEWORK_MODULE_CONFIGS);
+	}
+
+	/**
+	 * Get framework configuration
+	 */
+	getFrameworkConfig(framework: string): FrameworkModuleConfig | undefined {
+		return FRAMEWORK_MODULE_CONFIGS[framework];
+	}
+
+	/**
+	 * Check if a framework is supported
+	 */
+	isFrameworkSupported(framework: string): boolean {
+		return framework in FRAMEWORK_MODULE_CONFIGS;
+	}
+
+	/**
+	 * Get file extension from path
+	 */
+	private getFileExtension(path: string): string {
+		const lastDot = path.lastIndexOf('.');
+		return lastDot === -1 ? '' : path.substring(lastDot);
+	}
+
+	/**
+	 * Set the resolver mode (development/production)
+	 */
+	setMode(mode: 'development' | 'production'): void {
+		this.mode = mode;
+	}
+
+	/**
+	 * Get current mode
+	 */
+	getMode(): 'development' | 'production' {
+		return this.mode;
+	}
+
+	/**
+	 * Set base URL for module resolution
+	 */
+	setBaseUrl(baseUrl: string): void {
+		this.baseUrl = baseUrl;
+	}
+
+	/**
+	 * Get current base URL
+	 */
+	getBaseUrl(): string {
+		return this.baseUrl;
+	}
+}
+
+/**
+ * Default instance for common usage
+ */
+export const frameworkModuleResolver = new FrameworkModuleResolver();

package/src/core/modules/tests/framework-module-resolver.test.ts

@@ -0,0 +1,263 @@
+/**
+ * Tests for FrameworkModuleResolver
+ */
+
+import { describe, it, expect } from 'vitest';
+import { FrameworkModuleResolver } from '../framework-module-resolver.ts';
+
+describe('FrameworkModuleResolver - Basic functionality', () => {
+	it('should create resolver with default settings', () => {
+		const resolver = new FrameworkModuleResolver();
+		expect(resolver.getMode()).toEqual('development');
+		expect(resolver.getBaseUrl()).toEqual('');
+	});
+
+	it('should create resolver with custom settings', () => {
+		const resolver = new FrameworkModuleResolver('production', 'https://example.com');
+		expect(resolver.getMode()).toEqual('production');
+		expect(resolver.getBaseUrl()).toEqual('https://example.com');
+	});
+
+	it('should update mode and base URL', () => {
+		const resolver = new FrameworkModuleResolver();
+		resolver.setMode('production');
+		resolver.setBaseUrl('https://test.com');
+		expect(resolver.getMode()).toEqual('production');
+		expect(resolver.getBaseUrl()).toEqual('https://test.com');
+	});
+});
+
+describe('FrameworkModuleResolver - Framework support', () => {
+	const resolver = new FrameworkModuleResolver();
+
+	it('should support known frameworks', () => {
+		expect(resolver.isFrameworkSupported('solid')).toEqual(true);
+		expect(resolver.isFrameworkSupported('preact')).toEqual(true);
+		expect(resolver.isFrameworkSupported('vue')).toEqual(true);
+		expect(resolver.isFrameworkSupported('svelte')).toEqual(true);
+	});
+
+	it('should not support unknown frameworks', () => {
+		expect(resolver.isFrameworkSupported('unknown')).toEqual(false);
+		expect(resolver.isFrameworkSupported('react')).toEqual(false);
+	});
+
+	it('should return supported frameworks list', () => {
+		const frameworks = resolver.getSupportedFrameworks();
+		expect(frameworks.includes('solid')).toEqual(true);
+		expect(frameworks.includes('preact')).toEqual(true);
+		expect(frameworks.includes('vue')).toEqual(true);
+		expect(frameworks.includes('svelte')).toEqual(true);
+	});
+
+	it('should get framework configuration', () => {
+		const solidConfig = resolver.getFrameworkConfig('solid');
+		expect(solidConfig?.extensions.includes('.tsx')).toEqual(true);
+		expect(solidConfig?.hydrationExtension).toEqual('.js');
+		expect(solidConfig?.mimeType).toEqual('application/javascript');
+
+		const unknownConfig = resolver.getFrameworkConfig('unknown');
+		expect(unknownConfig).toEqual(undefined);
+	});
+});
+
+describe('FrameworkModuleResolver - Solid path transformation', () => {
+	const resolver = new FrameworkModuleResolver();
+
+	it('should transform .tsx to .js for Solid hydration', () => {
+		const result = resolver.resolveModule('/src/islands/Counter.tsx', 'solid', {
+			forHydration: true,
+		});
+
+		expect(result.originalPath).toEqual('/src/islands/Counter.tsx');
+		expect(result.resolvedPath).toEqual('/src/islands/Counter.js');
+		expect(result.framework).toEqual('solid');
+		expect(result.shouldTransform).toEqual(true);
+		expect(result.mimeType).toEqual('application/javascript');
+		expect(result.url).toEqual('/src/islands/Counter.js');
+	});
+
+	it('should transform .jsx to .js for Solid hydration', () => {
+		const result = resolver.resolveModule('/src/islands/Counter.jsx', 'solid', {
+			forHydration: true,
+		});
+
+		expect(result.originalPath).toEqual('/src/islands/Counter.jsx');
+		expect(result.resolvedPath).toEqual('/src/islands/Counter.js');
+		expect(result.shouldTransform).toEqual(true);
+	});
+
+	it('should not transform non-hydration requests', () => {
+		const result = resolver.resolveModule('/src/islands/Counter.tsx', 'solid', {
+			forHydration: false,
+		});
+
+		expect(result.originalPath).toEqual('/src/islands/Counter.tsx');
+		expect(result.resolvedPath).toEqual('/src/islands/Counter.tsx');
+		expect(result.shouldTransform).toEqual(false);
+	});
+
+	it('should not transform .js files', () => {
+		const result = resolver.resolveModule('/src/islands/Counter.js', 'solid', {
+			forHydration: true,
+		});
+
+		expect(result.originalPath).toEqual('/src/islands/Counter.js');
+		expect(result.resolvedPath).toEqual('/src/islands/Counter.js');
+		expect(result.shouldTransform).toEqual(false);
+	});
+});
+
+describe('FrameworkModuleResolver - Preact path transformation', () => {
+	const resolver = new FrameworkModuleResolver();
+
+	it('should transform .tsx to .js for Preact hydration', () => {
+		const result = resolver.resolveModule('/src/islands/Counter.tsx', 'preact', {
+			forHydration: true,
+		});
+
+		expect(result.originalPath).toEqual('/src/islands/Counter.tsx');
+		expect(result.resolvedPath).toEqual('/src/islands/Counter.js');
+		expect(result.framework).toEqual('preact');
+		expect(result.shouldTransform).toEqual(true);
+		expect(result.mimeType).toEqual('application/javascript');
+	});
+
+	it('should transform .jsx to .js for Preact hydration', () => {
+		const result = resolver.resolveModule('/src/islands/Counter.jsx', 'preact', {
+			forHydration: true,
+		});
+
+		expect(result.resolvedPath).toEqual('/src/islands/Counter.js');
+		expect(result.shouldTransform).toEqual(true);
+	});
+});
+
+describe('FrameworkModuleResolver - Vue path transformation', () => {
+	const resolver = new FrameworkModuleResolver();
+
+	it('should transform .vue to .js for Vue hydration', () => {
+		const result = resolver.resolveModule('/src/islands/Counter.vue', 'vue', {
+			forHydration: true,
+		});
+
+		expect(result.originalPath).toEqual('/src/islands/Counter.vue');
+		expect(result.resolvedPath).toEqual('/src/islands/Counter.js');
+		expect(result.framework).toEqual('vue');
+		expect(result.shouldTransform).toEqual(true);
+		expect(result.mimeType).toEqual('application/javascript');
+	});
+});
+
+describe('FrameworkModuleResolver - Svelte path transformation', () => {
+	const resolver = new FrameworkModuleResolver();
+
+	it('should transform .svelte to .js for Svelte hydration', () => {
+		const result = resolver.resolveModule('/src/islands/Counter.svelte', 'svelte', {
+			forHydration: true,
+		});
+
+		expect(result.originalPath).toEqual('/src/islands/Counter.svelte');
+		expect(result.resolvedPath).toEqual('/src/islands/Counter.js');
+		expect(result.framework).toEqual('svelte');
+		expect(result.shouldTransform).toEqual(true);
+		expect(result.mimeType).toEqual('application/javascript');
+	});
+});
+
+describe('FrameworkModuleResolver - MIME type detection', () => {
+	const resolver = new FrameworkModuleResolver();
+
+	it('should detect JavaScript MIME types', () => {
+		expect(resolver.getMimeType('/test.js')).toEqual('application/javascript');
+		expect(resolver.getMimeType('/test.mjs')).toEqual('application/javascript');
+		expect(resolver.getMimeType('/test.ts')).toEqual('application/javascript');
+		expect(resolver.getMimeType('/test.tsx')).toEqual('application/javascript');
+		expect(resolver.getMimeType('/test.jsx')).toEqual('application/javascript');
+	});
+
+	it('should detect component MIME types', () => {
+		expect(resolver.getMimeType('/test.vue')).toEqual('application/javascript');
+		expect(resolver.getMimeType('/test.svelte')).toEqual('application/javascript');
+	});
+
+	it('should detect other MIME types', () => {
+		expect(resolver.getMimeType('/test.css')).toEqual('text/css');
+		expect(resolver.getMimeType('/test.json')).toEqual('application/json');
+		expect(resolver.getMimeType('/test.txt')).toEqual('text/plain');
+		expect(resolver.getMimeType('/test.unknown')).toEqual('text/plain');
+	});
+});
+
+describe('FrameworkModuleResolver - URL generation', () => {
+	it('should generate URLs without base URL', () => {
+		const resolver = new FrameworkModuleResolver();
+		expect(resolver.generateModuleUrl('/src/test.js')).toEqual('/src/test.js');
+		expect(resolver.generateModuleUrl('src/test.js')).toEqual('/src/test.js');
+	});
+
+	it('should generate URLs with base URL', () => {
+		const resolver = new FrameworkModuleResolver('development', 'https://example.com');
+		expect(resolver.generateModuleUrl('/src/test.js')).toEqual('https://example.com/src/test.js');
+		expect(resolver.generateModuleUrl('src/test.js')).toEqual('https://example.com/src/test.js');
+	});
+
+	it('should handle base URL with trailing slash', () => {
+		const resolver = new FrameworkModuleResolver('development', 'https://example.com/');
+		expect(resolver.generateModuleUrl('/src/test.js')).toEqual('https://example.com/src/test.js');
+	});
+
+	it('should generate URLs with custom base URL option', () => {
+		const resolver = new FrameworkModuleResolver();
+		const result = resolver.resolveModule('/src/test.tsx', 'solid', {
+			forHydration: true,
+			baseUrl: 'https://custom.com',
+		});
+		expect(result.url).toEqual('https://custom.com/src/test.js');
+	});
+});
+
+describe('FrameworkModuleResolver - Transformation detection', () => {
+	const resolver = new FrameworkModuleResolver();
+
+	it('should detect when transformation is needed', () => {
+		expect(resolver.needsTransformation('/test.tsx', 'solid')).toEqual(true);
+		expect(resolver.needsTransformation('/test.jsx', 'solid')).toEqual(true);
+		expect(resolver.needsTransformation('/test.vue', 'vue')).toEqual(true);
+		expect(resolver.needsTransformation('/test.svelte', 'svelte')).toEqual(true);
+	});
+
+	it('should detect when transformation is not needed', () => {
+		expect(resolver.needsTransformation('/test.js', 'solid')).toEqual(false);
+		expect(resolver.needsTransformation('/test.css', 'solid')).toEqual(false);
+		expect(resolver.needsTransformation('/test.tsx', 'unknown')).toEqual(false);
+	});
+});
+
+describe('FrameworkModuleResolver - Error handling', () => {
+	const resolver = new FrameworkModuleResolver();
+
+	it('should throw error for unknown framework', () => {
+		expect(() => {
+			resolver.resolveModule('/test.tsx', 'unknown');
+		}).toThrow('Unknown framework: unknown');
+	});
+});
+
+describe('FrameworkModuleResolver - Development vs Production mode', () => {
+	it('should handle development mode', () => {
+		const resolver = new FrameworkModuleResolver('development');
+		const result = resolver.resolveModule('/src/test.tsx', 'solid', {
+			forHydration: true,
+		});
+		expect(result.resolvedPath).toEqual('/src/test.js');
+	});
+
+	it('should handle production mode', () => {
+		const resolver = new FrameworkModuleResolver('production');
+		const result = resolver.resolveModule('/src/test.tsx', 'solid', {
+			forHydration: true,
+		});
+		expect(result.resolvedPath).toEqual('/src/test.js');
+	});
+});

package/src/core/modules/tests/module-resolution-integration.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Integration tests for module resolution system
+ */
+
+import { describe, it, expect } from 'vitest';
+import { FrameworkModuleResolver } from '../framework-module-resolver.ts';
+
+describe('Module Resolution Integration - End-to-end flow', () => {
+	it('should resolve Solid .tsx to .js for hydration', () => {
+		const resolver = new FrameworkModuleResolver('development');
+
+		const result = resolver.resolveModule('/src/islands/Counter.tsx', 'solid', {
+			forHydration: true,
+		});
+
+		expect(result.originalPath).toEqual('/src/islands/Counter.tsx');
+		expect(result.resolvedPath).toEqual('/src/islands/Counter.js');
+		expect(result.framework).toEqual('solid');
+		expect(result.shouldTransform).toEqual(true);
+		expect(result.mimeType).toEqual('application/javascript');
+		expect(result.url).toEqual('/src/islands/Counter.js');
+	});
+
+	it('should handle different frameworks correctly', () => {
+		const resolver = new FrameworkModuleResolver('production', 'https://cdn.example.com');
+
+		// Test Preact
+		const preactResult = resolver.resolveModule('/components/Button.jsx', 'preact', {
+			forHydration: true,
+		});
+		expect(preactResult.resolvedPath).toEqual('/components/Button.js');
+		expect(preactResult.url).toEqual('https://cdn.example.com/components/Button.js');
+
+		// Test Vue
+		const vueResult = resolver.resolveModule('/components/Modal.vue', 'vue', {
+			forHydration: true,
+		});
+		expect(vueResult.resolvedPath).toEqual('/components/Modal.js');
+		expect(vueResult.mimeType).toEqual('application/javascript');
+
+		// Test Svelte
+		const svelteResult = resolver.resolveModule('/components/Card.svelte', 'svelte', {
+			forHydration: true,
+		});
+		expect(svelteResult.resolvedPath).toEqual('/components/Card.js');
+	});
+
+	it('should handle development vs production modes', () => {
+		const devResolver = new FrameworkModuleResolver('development');
+		const prodResolver = new FrameworkModuleResolver('production');
+
+		const testPath = '/src/islands/Counter.tsx';
+
+		const devResult = devResolver.resolveModule(testPath, 'solid', { forHydration: true });
+		const prodResult = prodResolver.resolveModule(testPath, 'solid', { forHydration: true });
+
+		expect(devResult.resolvedPath).toEqual(prodResult.resolvedPath);
+		expect(devResult.resolvedPath).toEqual('/src/islands/Counter.js');
+
+		expect(devResolver.getMode()).toEqual('development');
+		expect(prodResolver.getMode()).toEqual('production');
+	});
+});
+
+describe('Module Resolution Integration - Error scenarios', () => {
+	it('should handle unsupported frameworks gracefully', () => {
+		const resolver = new FrameworkModuleResolver();
+
+		expect(() => {
+			resolver.resolveModule('/test.tsx', 'react');
+		}).toThrow('Unknown framework: react');
+	});
+
+	it('should handle invalid paths gracefully', () => {
+		const resolver = new FrameworkModuleResolver();
+
+		const result = resolver.resolveModule('', 'solid', { forHydration: true });
+		expect(result.originalPath).toEqual('');
+		expect(result.resolvedPath).toEqual('');
+	});
+
+	it('should handle MIME type detection for unknown extensions', () => {
+		const resolver = new FrameworkModuleResolver();
+
+		expect(resolver.getMimeType('/test.unknown')).toEqual('text/plain');
+		expect(resolver.getMimeType('/test')).toEqual('text/plain');
+		expect(resolver.getMimeType('')).toEqual('text/plain');
+	});
+});
+
+describe('Module Resolution Integration - Performance considerations', () => {
+	it('should handle multiple resolutions efficiently', () => {
+		const resolver = new FrameworkModuleResolver();
+		const startTime = performance.now();
+
+		for (let i = 0; i < 100; i++) {
+			resolver.resolveModule(`/src/islands/Counter${i}.tsx`, 'solid', {
+				forHydration: true,
+			});
+		}
+
+		const endTime = performance.now();
+		const duration = endTime - startTime;
+
+		expect(duration < 100).toEqual(true);
+	});
+
+	it('should cache framework configurations', () => {
+		const resolver = new FrameworkModuleResolver();
+
+		const config1 = resolver.getFrameworkConfig('solid');
+		const config2 = resolver.getFrameworkConfig('solid');
+
+		expect(config1).toEqual(config2);
+		expect(config1?.extensions.includes('.tsx')).toEqual(true);
+	});
+});