@ecopages/core 0.2.0-alpha.5 → 0.2.0-alpha.7

package/src/services/module-loading/page-module-import.service.test.ts

@@ -0,0 +1,253 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import assert from 'node:assert/strict';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, it } from 'vitest';
+import type { BuildResult } from '../../build/build-adapter.js';
+import { PageModuleImportService, type PageModuleImportDependencies } from './page-module-import.service.ts';
+
+function createBuildResult(overrides?: Partial<BuildResult>): BuildResult {
+	return {
+		success: true,
+		logs: [],
+		outputs: [],
+		...overrides,
+	};
+}
+
+function createFakeDependencies(): {
+	dependencies: PageModuleImportDependencies;
+	calls: {
+		hashFile: string[];
+		buildModule: Array<{
+			options: Parameters<PageModuleImportDependencies['buildModule']>[0];
+			buildExecutor: Parameters<PageModuleImportDependencies['buildModule']>[1];
+		}>;
+	};
+	setNextBuildResult(result: BuildResult): void;
+} {
+	const calls = {
+		hashFile: [] as string[],
+		buildModule: [] as Array<{
+			options: Parameters<PageModuleImportDependencies['buildModule']>[0];
+			buildExecutor: Parameters<PageModuleImportDependencies['buildModule']>[1];
+		}>,
+	};
+	let nextBuildResult = createBuildResult();
+
+	return {
+		dependencies: {
+			hashFile(filePath: string): string {
+				calls.hashFile.push(filePath);
+				return 'hash123';
+			},
+			async buildModule(options, buildExecutor): Promise<BuildResult> {
+				calls.buildModule.push({ options, buildExecutor });
+				return nextBuildResult;
+			},
+		},
+		calls,
+		setNextBuildResult(result: BuildResult): void {
+			nextBuildResult = result;
+		},
+	};
+}
+
+describe('PageModuleImportService', () => {
+	let service: PageModuleImportService;
+	let fakeDependencies: ReturnType<typeof createFakeDependencies>;
+
+	beforeEach(() => {
+		fakeDependencies = createFakeDependencies();
+		service = new PageModuleImportService(fakeDependencies.dependencies);
+	});
+
+	afterEach(() => {
+		service.clearImportCache();
+		delete process.env.NODE_ENV;
+	});
+
+	it('should import the transpiled output in node runtimes', async () => {
+		const tempDir = mkdtempSync(join(tmpdir(), 'ecopages-page-module-import-'));
+		const compiledOutput = join(tempDir, 'page-hash123.js');
+		writeFileSync(compiledOutput, 'export const value = 42; export default { ok: true };', 'utf8');
+		fakeDependencies.setNextBuildResult(createBuildResult({ outputs: [{ path: compiledOutput }] }));
+
+		try {
+			const result = await service.importModule<{ default: { ok: boolean }; value: number }>({
+				filePath: '/app/pages/page.tsx',
+				rootDir: '/app',
+				outdir: tempDir,
+			});
+
+			assert.deepEqual(result.default, { ok: true });
+			assert.equal(result.value, 42);
+			assert.deepEqual(fakeDependencies.calls.hashFile, ['/app/pages/page.tsx']);
+			assert.deepEqual(fakeDependencies.calls.buildModule, [
+				{
+					options: {
+						entrypoints: ['/app/pages/page.tsx'],
+						root: '/app',
+						outdir: tempDir,
+						target: 'node',
+						format: 'esm',
+						sourcemap: 'none',
+						splitting: true,
+						minify: false,
+						naming: 'page-hash123.js',
+						externalPackages: true,
+						plugins: undefined,
+					},
+					buildExecutor: undefined,
+				},
+			]);
+		} finally {
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	it('should throw the provided transpile error when the build fails', async () => {
+		fakeDependencies.setNextBuildResult(
+			createBuildResult({
+				success: false,
+				logs: [{ message: 'Unexpected token' }],
+				outputs: [],
+			}),
+		);
+
+		await assert.rejects(
+			service.importModule({
+				filePath: '/app/pages/page.tsx',
+				rootDir: '/app',
+				outdir: '/tmp/out',
+				transpileErrorMessage: (details) => `transpile failed: ${details}`,
+			}),
+			/transpile failed: Unexpected token/,
+		);
+	});
+
+	it('should keep a stable node module path in development for unchanged files', async () => {
+		process.env.NODE_ENV = 'development';
+		const tempDir = mkdtempSync(join(tmpdir(), 'ecopages-page-module-import-dev-'));
+		const compiledOutput = join(tempDir, 'page-hash123.js');
+		writeFileSync(compiledOutput, 'export default { ok: true };', 'utf8');
+		fakeDependencies.setNextBuildResult(createBuildResult({ outputs: [{ path: compiledOutput }] }));
+
+		try {
+			await service.importModule({
+				filePath: '/app/pages/page.tsx',
+				rootDir: '/app',
+				outdir: tempDir,
+			});
+
+			assert.equal(fakeDependencies.calls.buildModule.length, 1);
+			assert.equal(fakeDependencies.calls.buildModule[0]?.options.naming, 'page-hash123.js');
+			assert.equal(fakeDependencies.calls.buildModule[0]?.options.splitting, true);
+			assert.equal(fakeDependencies.calls.buildModule[0]?.options.externalPackages, true);
+		} finally {
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	it('should allow callers to opt back into bundled node imports explicitly', async () => {
+		process.env.NODE_ENV = 'development';
+		const tempDir = mkdtempSync(join(tmpdir(), 'ecopages-page-module-import-bundled-'));
+		const compiledOutput = join(tempDir, 'page-hash123.js');
+		writeFileSync(compiledOutput, 'export default { ok: true };', 'utf8');
+		fakeDependencies.setNextBuildResult(createBuildResult({ outputs: [{ path: compiledOutput }] }));
+
+		try {
+			await service.importModule({
+				filePath: '/app/pages/page.tsx',
+				rootDir: '/app',
+				outdir: tempDir,
+				externalPackages: false,
+			});
+
+			assert.equal(fakeDependencies.calls.buildModule.length, 1);
+			assert.equal(fakeDependencies.calls.buildModule[0]?.options.externalPackages, false);
+		} finally {
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	it('should allow callers to disable code splitting explicitly', async () => {
+		const tempDir = mkdtempSync(join(tmpdir(), 'ecopages-page-module-import-unsplit-'));
+		const compiledOutput = join(tempDir, 'page-hash123.js');
+		writeFileSync(compiledOutput, 'export default { ok: true };', 'utf8');
+		fakeDependencies.setNextBuildResult(createBuildResult({ outputs: [{ path: compiledOutput }] }));
+
+		try {
+			await service.importModule({
+				filePath: '/app/pages/page.tsx',
+				rootDir: '/app',
+				outdir: tempDir,
+				splitting: false,
+			});
+
+			assert.equal(fakeDependencies.calls.buildModule.length, 1);
+			assert.equal(fakeDependencies.calls.buildModule[0]?.options.splitting, false);
+		} finally {
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	it('should reuse cached node modules across different output directories', async () => {
+		const tempDir = mkdtempSync(join(tmpdir(), 'ecopages-page-module-import-cache-'));
+		const compiledOutput = join(tempDir, 'page-hash123.js');
+		writeFileSync(compiledOutput, 'export default { ok: true };', 'utf8');
+		fakeDependencies.setNextBuildResult(createBuildResult({ outputs: [{ path: compiledOutput }] }));
+
+		try {
+			const first = await service.importModule<{ default: { ok: boolean } }>({
+				filePath: '/app/pages/page.tsx',
+				rootDir: '/app',
+				outdir: join(tempDir, 'meta'),
+			});
+
+			const second = await service.importModule<{ default: { ok: boolean } }>({
+				filePath: '/app/pages/page.tsx',
+				rootDir: '/app',
+				outdir: join(tempDir, 'render'),
+			});
+
+			assert.deepEqual(first.default, { ok: true });
+			assert.deepEqual(second.default, { ok: true });
+			assert.equal(fakeDependencies.calls.buildModule.length, 1);
+		} finally {
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+
+	it('should reload the same node module path after development graph invalidation', async () => {
+		process.env.NODE_ENV = 'development';
+		const tempDir = mkdtempSync(join(tmpdir(), 'ecopages-page-module-import-invalidate-'));
+		const compiledOutput = join(tempDir, 'page-hash123.js');
+		writeFileSync(compiledOutput, 'export const version = 1; export default { ok: true };', 'utf8');
+		fakeDependencies.setNextBuildResult(createBuildResult({ outputs: [{ path: compiledOutput }] }));
+
+		try {
+			const first = await service.importModule<{ version: number }>({
+				filePath: '/app/pages/page.tsx',
+				rootDir: '/app',
+				outdir: tempDir,
+			});
+
+			writeFileSync(compiledOutput, 'export const version = 2; export default { ok: true };', 'utf8');
+			service.invalidateDevelopmentGraph();
+			fakeDependencies.setNextBuildResult(createBuildResult({ outputs: [{ path: compiledOutput }] }));
+
+			const second = await service.importModule<{ version: number }>({
+				filePath: '/app/pages/page.tsx',
+				rootDir: '/app',
+				outdir: tempDir,
+			});
+
+			assert.equal(first.version, 1);
+			assert.equal(second.version, 2);
+			assert.equal(fakeDependencies.calls.buildModule.length, 2);
+		} finally {
+			rmSync(tempDir, { recursive: true, force: true });
+		}
+	});
+});

package/src/services/module-loading/page-module-import.service.ts

@@ -0,0 +1,200 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { fileSystem } from '@ecopages/file-system';
+import { build, type BuildExecutor, type BuildResult } from '../../build/build-adapter.ts';
+import type { EcoBuildPlugin } from '../../build/build-types.ts';
+
+export interface PageModuleImportOptions {
+	filePath: string;
+	rootDir: string;
+	outdir: string;
+	buildExecutor?: BuildExecutor;
+	invalidationVersion?: number;
+	splitting?: boolean;
+	externalPackages?: boolean;
+	plugins?: EcoBuildPlugin[];
+	transpileErrorMessage?: (details: string) => string;
+	noOutputMessage?: (filePath: string) => string;
+}
+
+/**
+ * Minimal runtime dependencies required to load page modules.
+ *
+ * @remarks
+ * This service owns cache and runtime import policy. Hashing and build
+ * execution are injected so tests can provide explicit fakes without module
+ * interception.
+ */
+export interface PageModuleImportDependencies {
+	hashFile(filePath: string): string;
+	buildModule(options: Parameters<typeof build>[0], buildExecutor?: BuildExecutor): Promise<BuildResult>;
+}
+
+/**
+ * Loads source page modules in a runtime-agnostic way.
+ *
+ * This service centralizes the Bun-vs-Node import strategy used by route
+ * scanning, page data loading, and request-time page inspection. In Bun it can
+ * import source files directly; in Node it transpiles the file into a dedicated
+ * output directory first and then imports the generated module.
+ *
+ * Keeping this logic in one place prevents subtle drift in cache-busting,
+ * transpilation settings, and error semantics across the different callers.
+ */
+export class PageModuleImportService {
+	private readonly dependencies: PageModuleImportDependencies;
+	private readonly importCache = new Map<string, Promise<unknown>>();
+	private developmentInvalidationVersion = 0;
+
+	constructor(dependencies?: Partial<PageModuleImportDependencies>) {
+		this.dependencies = {
+			hashFile: dependencies?.hashFile ?? ((filePath) => fileSystem.hash(filePath)),
+			buildModule: dependencies?.buildModule ?? ((options, buildExecutor) => build(options, buildExecutor)),
+		};
+	}
+
+	/**
+	 * Clears the shared import cache used by framework-owned page-module loads.
+	 */
+	clearImportCache(): void {
+		this.importCache.clear();
+	}
+
+	/**
+	 * Invalidates all previously imported modules in development by clearing the
+	 * import cache and incrementing the invalidation version included in cache keys.
+	 *
+	 * This forces all modules to be reloaded on the next import, even if their
+	 * source content hasn't changed. This is necessary to ensure that changes to
+	 * non-content aspects of modules (e.g. dependencies, transpilation output)
+	 * are picked up during development.
+	 */
+	invalidateDevelopmentGraph(): void {
+		this.clearImportCache();
+		this.developmentInvalidationVersion += 1;
+	}
+
+	/**
+	 * Imports a page-like module from source.
+	 *
+	 * The caller controls the output directory and error wording so different
+	 * subsystems can reuse the same loading mechanism while preserving their
+	 * current diagnostics. Module identities stay stable for unchanged files and
+	 * roll forward automatically when the source hash changes during watch mode.
+	 *
+	 * @typeParam T Expected module shape.
+	 * @param options Runtime-specific import settings.
+	 * @returns The loaded module.
+	 */
+	async importModule<T = unknown>(options: PageModuleImportOptions): Promise<T> {
+		const { filePath, rootDir, externalPackages, splitting } = options;
+		const invalidationVersion = options.invalidationVersion ?? this.developmentInvalidationVersion;
+
+		const fileHash = this.dependencies.hashFile(filePath);
+		const runtime = typeof Bun !== 'undefined' ? 'bun' : 'node';
+		const cacheKey = [
+			runtime,
+			filePath,
+			rootDir,
+			splitting ?? 'default',
+			externalPackages ?? 'default',
+			fileHash,
+			invalidationVersion,
+		].join('::');
+		const cachedModule = this.importCache.get(cacheKey);
+
+		if (cachedModule) {
+			return (await cachedModule) as T;
+		}
+
+		const importPromise = this.loadModule<T>({
+			...options,
+			fileHash,
+		});
+
+		this.importCache.set(cacheKey, importPromise);
+
+		try {
+			return await importPromise;
+		} catch (error) {
+			this.importCache.delete(cacheKey);
+			throw error;
+		}
+	}
+
+	private async loadModule<T = unknown>(
+		options: PageModuleImportOptions & {
+			fileHash: string;
+		},
+	): Promise<T> {
+		/**
+		 * Runtime-specific module loading stays centralized here so callers can share
+		 * one cache-key and invalidation model while still diverging between Bun's
+		 * direct source imports and Node's transpile-then-import path.
+		 */
+		const {
+			filePath,
+			rootDir,
+			outdir,
+			invalidationVersion = this.developmentInvalidationVersion,
+			splitting,
+			externalPackages,
+			transpileErrorMessage = (details) => `Error transpiling page module: ${details}`,
+			noOutputMessage = (targetFilePath) => `No transpiled output generated for page module: ${targetFilePath}`,
+			fileHash,
+		} = options;
+
+		if (typeof Bun !== 'undefined') {
+			const moduleUrl = pathToFileURL(filePath);
+
+			if (process.env.NODE_ENV === 'development') {
+				moduleUrl.searchParams.set('update', `${fileHash}-${invalidationVersion}`);
+			}
+
+			return (await import(moduleUrl.href)) as T;
+		}
+
+		const fileBaseName = path.basename(filePath, path.extname(filePath));
+		const outputFileName = `${fileBaseName}-${fileHash}.js`;
+
+		const buildResult = await this.dependencies.buildModule(
+			{
+				entrypoints: [filePath],
+				root: rootDir,
+				outdir,
+				target: 'node',
+				format: 'esm',
+				sourcemap: 'none',
+				splitting: splitting ?? true,
+				minify: false,
+				naming: outputFileName,
+				externalPackages: true,
+				plugins: options.plugins,
+				...(externalPackages !== undefined ? { externalPackages } : {}),
+			},
+			options.buildExecutor,
+		);
+
+		if (!buildResult.success) {
+			const details = buildResult.logs.map((log) => log.message).join(' | ');
+			throw new Error(transpileErrorMessage(details));
+		}
+
+		const preferredOutputPath = path.join(outdir, outputFileName);
+		const compiledOutput =
+			buildResult.outputs.find((output) => output.path === preferredOutputPath)?.path ??
+			buildResult.outputs.find((output) => output.path.endsWith('.js'))?.path;
+
+		if (!compiledOutput) {
+			throw new Error(noOutputMessage(filePath));
+		}
+
+		const compiledOutputUrl = pathToFileURL(compiledOutput);
+
+		if (process.env.NODE_ENV === 'development') {
+			compiledOutputUrl.searchParams.set('update', `${fileHash}-${invalidationVersion}`);
+		}
+
+		return (await import(compiledOutputUrl.href)) as T;
+	}
+}

package/src/services/module-loading/server-loader.service.test.ts

@@ -0,0 +1,161 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'vitest';
+import type { BuildResult } from '../../build/build-adapter.js';
+import {
+	TranspilerServerLoader,
+	type ServerLoaderDependencyFactory,
+	type ServerLoaderTranspilerDependency,
+} from './server-loader.service.ts';
+import type { ServerModuleTranspilerBootstrapArgs } from './server-module-transpiler.service.ts';
+
+function createBuildResult(): BuildResult {
+	return {
+		success: true,
+		logs: [],
+		outputs: [],
+	};
+}
+
+function createFakeTranspilerFactory(): {
+	factory: ServerLoaderDependencyFactory;
+	constructorArgs: ServerModuleTranspilerBootstrapArgs[];
+	importCalls: Array<unknown>;
+	invalidateCalls: Array<string[] | undefined>;
+	disposeCalls: number;
+	setNextImportResult(result: unknown): void;
+} {
+	const constructorArgs: ServerModuleTranspilerBootstrapArgs[] = [];
+	const importCalls: Array<unknown> = [];
+	const invalidateCalls: Array<string[] | undefined> = [];
+	let disposeCalls = 0;
+	let nextImportResult: unknown = undefined;
+
+	return {
+		factory: {
+			createTranspiler(context): ServerLoaderTranspilerDependency {
+				constructorArgs.push(context);
+
+				return {
+					async importModule<T = unknown>(
+						options: Parameters<ServerLoaderTranspilerDependency['importModule']>[0],
+					): Promise<T> {
+						importCalls.push(options);
+						return nextImportResult as T;
+					},
+					invalidate(changedFiles?: string[]): void {
+						invalidateCalls.push(changedFiles);
+					},
+					async dispose(): Promise<void> {
+						disposeCalls += 1;
+					},
+				};
+			},
+		},
+		constructorArgs,
+		importCalls,
+		invalidateCalls,
+		get disposeCalls() {
+			return disposeCalls;
+		},
+		setNextImportResult(result: unknown): void {
+			nextImportResult = result;
+		},
+	};
+}
+
+describe('TranspilerServerLoader', () => {
+	it('loads config through the bootstrap transpiler context', async () => {
+		const fakeFactory = createFakeTranspilerFactory();
+		const buildExecutor = { build: async () => createBuildResult() };
+		fakeFactory.setNextImportResult({ default: { ok: true } });
+
+		const loader = new TranspilerServerLoader(
+			{
+				rootDir: '/bootstrap-app',
+				getBuildExecutor: () => buildExecutor,
+			},
+			fakeFactory.factory,
+		);
+
+		await loader.loadConfig({
+			filePath: '/bootstrap-app/eco.config.ts',
+			outdir: '/bootstrap-app/.eco/.server-config',
+		});
+
+		assert.deepEqual(fakeFactory.constructorArgs, [
+			{
+				rootDir: '/bootstrap-app',
+				getBuildExecutor: fakeFactory.constructorArgs[0]?.getBuildExecutor,
+			},
+		]);
+		assert.deepEqual(fakeFactory.constructorArgs[0]?.getBuildExecutor(), buildExecutor);
+		assert.deepEqual(fakeFactory.importCalls, [
+			{
+				filePath: '/bootstrap-app/eco.config.ts',
+				outdir: '/bootstrap-app/.eco/.server-config',
+			},
+		]);
+	});
+
+	it('rebinding app context routes app loads through a new transpiler instance', async () => {
+		const fakeFactory = createFakeTranspilerFactory();
+		const bootstrapBuildExecutor = { build: async () => createBuildResult() };
+		const appBuildExecutor = { build: async () => createBuildResult() };
+		fakeFactory.setNextImportResult({});
+
+		const loader = new TranspilerServerLoader(
+			{
+				rootDir: '/bootstrap-app',
+				getBuildExecutor: () => bootstrapBuildExecutor,
+			},
+			fakeFactory.factory,
+		);
+
+		loader.rebindAppContext({
+			rootDir: '/app',
+			getBuildExecutor: () => appBuildExecutor,
+		});
+
+		await loader.loadApp({
+			filePath: '/app/app.ts',
+			outdir: '/app/.eco/.server-entry',
+		});
+
+		assert.equal(fakeFactory.constructorArgs.length, 2);
+		assert.equal(fakeFactory.constructorArgs[0]?.rootDir, '/bootstrap-app');
+		assert.equal(fakeFactory.constructorArgs[1]?.rootDir, '/app');
+		assert.deepEqual(fakeFactory.constructorArgs[0]?.getBuildExecutor(), bootstrapBuildExecutor);
+		assert.deepEqual(fakeFactory.constructorArgs[1]?.getBuildExecutor(), appBuildExecutor);
+		assert.deepEqual(fakeFactory.importCalls, [
+			{
+				filePath: '/app/app.ts',
+				outdir: '/app/.eco/.server-entry',
+			},
+		]);
+	});
+
+	it('forwards invalidate and dispose to owned transpiler instances', async () => {
+		const fakeFactory = createFakeTranspilerFactory();
+		const bootstrapBuildExecutor = { build: async () => createBuildResult() };
+		const appBuildExecutor = { build: async () => createBuildResult() };
+
+		const loader = new TranspilerServerLoader(
+			{
+				rootDir: '/bootstrap-app',
+				getBuildExecutor: () => bootstrapBuildExecutor,
+			},
+			fakeFactory.factory,
+		);
+
+		loader.rebindAppContext({
+			rootDir: '/app',
+			getBuildExecutor: () => appBuildExecutor,
+		});
+
+		loader.invalidate();
+		await loader.dispose();
+
+		assert.deepEqual(fakeFactory.invalidateCalls, [undefined, undefined]);
+		assert.equal(fakeFactory.disposeCalls, 2);
+	});
+});