@ecopages/core 0.2.0-alpha.23 → 0.2.0-alpha.24

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

@@ -0,0 +1,252 @@
+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';
+import type { SourceModuleLoaderFactory } from './module-loading-types.ts';
+import { supportsSourceModuleLoading } from './source-module-support.ts';
+
+export interface PageModuleImportOptions {
+	filePath: string;
+	rootDir: string;
+	outdir: string;
+	bypassCache?: boolean;
+	cacheScope?: 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>;
+	canLoadSourceModuleFromHost(filePath: string): boolean;
+	getHostModuleLoader: SourceModuleLoaderFactory;
+}
+
+/**
+ * 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)),
+			canLoadSourceModuleFromHost: dependencies?.canLoadSourceModuleFromHost ?? supportsSourceModuleLoading,
+			getHostModuleLoader: dependencies?.getHostModuleLoader ?? (() => undefined),
+		};
+	}
+
+	/**
+	 * 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 hostModuleLoader =
+			typeof Bun === 'undefined' &&
+			process.env.NODE_ENV === 'development' &&
+			this.dependencies.canLoadSourceModuleFromHost(filePath)
+				? this.dependencies.getHostModuleLoader()
+				: undefined;
+
+		if (hostModuleLoader) {
+			const sourceModuleUrl = createRuntimeModuleUrl(filePath, fileHash, invalidationVersion, options.cacheScope);
+			return (await hostModuleLoader(sourceModuleUrl.href)) as T;
+		}
+
+		if (options.bypassCache) {
+			this.developmentInvalidationVersion += 1;
+			return await this.loadModule<T>({
+				...options,
+				invalidationVersion: this.developmentInvalidationVersion,
+				fileHash,
+			});
+		}
+
+		const runtime = typeof Bun !== 'undefined' ? 'bun' : 'node-build';
+		const cacheKey = [
+			runtime,
+			filePath,
+			rootDir,
+			splitting ?? 'default',
+			externalPackages ?? 'default',
+			options.cacheScope ?? '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> {
+		const {
+			filePath,
+			rootDir,
+			outdir,
+			invalidationVersion = this.developmentInvalidationVersion,
+			splitting,
+			externalPackages,
+			cacheScope,
+			transpileErrorMessage = (details) => `Error transpiling page module: ${details}`,
+			noOutputMessage = (targetFilePath) => `No transpiled output generated for page module: ${targetFilePath}`,
+			fileHash,
+		} = options;
+		const sourceModuleUrl = createRuntimeModuleUrl(filePath, fileHash, invalidationVersion, cacheScope);
+
+		if (typeof Bun !== 'undefined') {
+			return (await import(/* @vite-ignore */ sourceModuleUrl.href)) as T;
+		}
+
+		const fileBaseName = path.basename(filePath, path.extname(filePath));
+		const cacheScopeSuffix = cacheScope ? `-${sanitizeCacheScope(cacheScope)}` : '';
+		const outputFileName = `${fileBaseName}-${fileHash}${cacheScopeSuffix}.js`;
+
+		const buildResult = await this.dependencies.buildModule(
+			{
+				entrypoints: [filePath],
+				root: rootDir,
+				outdir,
+				target: 'es2022',
+				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' || cacheScope) {
+			compiledOutputUrl.searchParams.set(
+				'update',
+				[fileHash, invalidationVersion, cacheScope ? sanitizeCacheScope(cacheScope) : undefined]
+					.filter((value) => value !== undefined)
+					.join('-'),
+			);
+		}
+
+		return (await import(/* @vite-ignore */ compiledOutputUrl.href)) as T;
+	}
+}
+
+function createRuntimeModuleUrl(
+	filePath: string,
+	fileHash: string,
+	invalidationVersion: number,
+	cacheScope?: string,
+): URL {
+	const moduleUrl = pathToFileURL(filePath);
+
+	if (process.env.NODE_ENV === 'development' || cacheScope) {
+		moduleUrl.searchParams.set(
+			'update',
+			[fileHash, invalidationVersion, cacheScope ? sanitizeCacheScope(cacheScope) : undefined]
+				.filter((value) => value !== undefined)
+				.join('-'),
+		);
+	}
+
+	return moduleUrl;
+}
+
+function sanitizeCacheScope(cacheScope: string): string {
+	return cacheScope.replace(/[^a-zA-Z0-9_-]+/g, '-');
+}
+

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

@@ -0,0 +1,243 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'vitest';
+import type { BuildResult } from '../../build/build-adapter.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import { CounterServerInvalidationState } from '../runtime-state/server-invalidation-state.service.ts';
+import { getAppModuleLoader, setAppHostModuleLoader } from './app-server-module-transpiler.service.ts';
+import { ServerModuleTranspiler, type ServerModuleImportDependency } from './server-module-transpiler.service.ts';
+
+function createBuildResult(): BuildResult {
+	return {
+		success: true,
+		logs: [],
+		outputs: [],
+	};
+}
+
+function createFakeImportService(): {
+	dependency: ServerModuleImportDependency;
+	calls: {
+		importModule: Array<unknown>;
+		invalidateDevelopmentGraph: number;
+	};
+	setResult(result: unknown): void;
+} {
+	const calls = {
+		importModule: [] as Array<unknown>,
+		invalidateDevelopmentGraph: 0,
+	};
+	let nextResult: unknown = undefined;
+
+	return {
+		dependency: {
+			async importModule<T = unknown>(
+				options: Parameters<ServerModuleImportDependency['importModule']>[0],
+			): Promise<T> {
+				calls.importModule.push(options);
+				return nextResult as T;
+			},
+			invalidateDevelopmentGraph(): void {
+				calls.invalidateDevelopmentGraph += 1;
+			},
+		},
+		calls,
+		setResult(result: unknown): void {
+			nextResult = result;
+		},
+	};
+}
+
+describe('ServerModuleTranspiler', () => {
+	it('injects app root dir and build executor into page module imports', async () => {
+		const buildExecutor = { build: async () => createBuildResult() };
+		const fakeImportService = createFakeImportService();
+		fakeImportService.setResult({ default: { ok: true } });
+
+		const service = new ServerModuleTranspiler({
+			rootDir: '/app',
+			getBuildExecutor: () => buildExecutor,
+			pageModuleImportService: fakeImportService.dependency,
+		});
+
+		await service.importModule({
+			filePath: '/app/src/pages/index.tsx',
+			outdir: '/app/.eco/.server-modules',
+		});
+
+		assert.deepEqual(fakeImportService.calls.importModule, [
+			{
+				filePath: '/app/src/pages/index.tsx',
+				outdir: '/app/.eco/.server-modules',
+				rootDir: '/app',
+				buildExecutor,
+				invalidationVersion: undefined,
+			},
+		]);
+	});
+
+	it('supports explicit bootstrap root and executor without a full app config', async () => {
+		const buildExecutor = { build: async () => createBuildResult() };
+		const fakeImportService = createFakeImportService();
+		fakeImportService.setResult({ default: { ok: true } });
+
+		const service = new ServerModuleTranspiler({
+			rootDir: '/bootstrap-app',
+			getBuildExecutor: () => buildExecutor,
+			pageModuleImportService: fakeImportService.dependency,
+		});
+
+		await service.importModule({
+			filePath: '/bootstrap-app/eco.config.ts',
+			outdir: '/bootstrap-app/.eco/.server-modules',
+		});
+
+		assert.deepEqual(fakeImportService.calls.importModule, [
+			{
+				filePath: '/bootstrap-app/eco.config.ts',
+				outdir: '/bootstrap-app/.eco/.server-modules',
+				rootDir: '/bootstrap-app',
+				buildExecutor,
+				invalidationVersion: undefined,
+			},
+		]);
+	});
+
+	it('invalidates the owned import graph when no app invalidation callback is provided', () => {
+		const fakeImportService = createFakeImportService();
+
+		const service = new ServerModuleTranspiler({
+			rootDir: '/bootstrap-app',
+			getBuildExecutor: () => ({ build: async () => createBuildResult() }),
+			pageModuleImportService: fakeImportService.dependency,
+		});
+
+		service.invalidate(['/bootstrap-app/src/pages/index.tsx']);
+
+		assert.equal(fakeImportService.calls.invalidateDevelopmentGraph, 1);
+	});
+
+	it('forwards an abstract host module loader into the default page import service', () => {
+		const hostModuleLoader = async (_id: string) => ({ default: { ok: true } });
+		const service = new ServerModuleTranspiler({
+			rootDir: '/bootstrap-app',
+			getBuildExecutor: () => ({ build: async () => createBuildResult() }),
+			getHostModuleLoader: () => hostModuleLoader,
+		});
+
+		const internal = service as unknown as {
+			pageModuleImportService: { dependencies: { getHostModuleLoader: () => unknown } };
+		};
+
+		assert.equal(internal.pageModuleImportService.dependencies.getHostModuleLoader(), hostModuleLoader);
+	});
+
+	it('reuses one app-owned module loader per app config', () => {
+		const appConfig = {
+			rootDir: '/app',
+			absolutePaths: {
+				pagesDir: '/app/src/pages',
+				includesDir: '/app/src/includes',
+				layoutsDir: '/app/src/layouts',
+				componentsDir: '/app/src/components',
+			},
+			templatesExt: ['.tsx'],
+			runtime: {},
+		} as unknown as EcoPagesAppConfig;
+
+		const firstLoader = getAppModuleLoader(appConfig);
+		const secondLoader = getAppModuleLoader(appConfig);
+
+		assert.equal(firstLoader, secondLoader);
+		assert.equal(firstLoader.owner, 'bun');
+	});
+
+	it('reflects host ownership on the app-owned module loader after runtime wiring changes', () => {
+		const appConfig = {
+			rootDir: '/app',
+			absolutePaths: {
+				pagesDir: '/app/src/pages',
+				includesDir: '/app/src/includes',
+				layoutsDir: '/app/src/layouts',
+				componentsDir: '/app/src/components',
+			},
+			templatesExt: ['.tsx'],
+			runtime: {},
+		} as unknown as EcoPagesAppConfig;
+		const moduleLoader = getAppModuleLoader(appConfig);
+
+		setAppHostModuleLoader(appConfig, async () => ({ default: { ok: true } }));
+
+		assert.equal(moduleLoader.owner, 'host');
+	});
+
+	it('applies the app invalidation version to app-owned module imports', async () => {
+		const calls: Array<unknown> = [];
+		const buildExecutor = { build: async () => createBuildResult() };
+		const appConfig = {
+			rootDir: '/app',
+			absolutePaths: {
+				pagesDir: '/app/src/pages',
+				includesDir: '/app/src/includes',
+				layoutsDir: '/app/src/layouts',
+				componentsDir: '/app/src/components',
+			},
+			templatesExt: ['.tsx'],
+			runtime: {
+				buildExecutor,
+				serverInvalidationState: new CounterServerInvalidationState(),
+			},
+		} as unknown as EcoPagesAppConfig;
+
+		const moduleLoader = getAppModuleLoader(appConfig) as unknown as {
+			pageModuleImportService: {
+				importModule: <T = unknown>(options: unknown) => Promise<T>;
+			};
+		};
+
+		const originalImportModule = moduleLoader.pageModuleImportService.importModule.bind(
+			moduleLoader.pageModuleImportService,
+		);
+		moduleLoader.pageModuleImportService.importModule = async <T = unknown>(options: unknown): Promise<T> => {
+			calls.push(options);
+			return { default: { ok: true } } as T;
+		};
+
+		appConfig.runtime!.serverInvalidationState!.invalidateServerModules(['/app/src/includes/seo.kita.tsx']);
+
+		await getAppModuleLoader(appConfig).importModule({
+			filePath: '/app/src/includes/html.kita.tsx',
+			rootDir: '/app',
+			outdir: '/app/.eco/.server-modules',
+		});
+
+		moduleLoader.pageModuleImportService.importModule = originalImportModule;
+
+		assert.equal(calls.length, 1);
+		const importOptions = calls[0] as {
+			buildExecutor: unknown;
+			filePath: string;
+			invalidationVersion: number;
+			outdir: string;
+			plugins?: Array<{ name: string }>;
+			rootDir: string;
+		};
+
+		assert.deepEqual(
+			{
+				buildExecutor: importOptions.buildExecutor,
+				filePath: importOptions.filePath,
+				invalidationVersion: importOptions.invalidationVersion,
+				outdir: importOptions.outdir,
+				rootDir: importOptions.rootDir,
+			},
+			{
+				filePath: '/app/src/includes/html.kita.tsx',
+				rootDir: '/app',
+				outdir: '/app/.eco/.server-modules',
+				buildExecutor,
+				invalidationVersion: 1,
+			},
+		);
+		assert.equal(importOptions.plugins?.[0]?.name, 'node-bootstrap-plugin');
+	});
+});

package/src/services/module-loading/server-module-transpiler.service.ts

@@ -0,0 +1,104 @@
+import type { BuildExecutor } from '../../build/build-adapter.ts';
+import type { EcoBuildPlugin } from '../../build/build-types.ts';
+import type { AppModuleLoader } from './app-module-loader.service.ts';
+import { PageModuleImportService, type PageModuleImportOptions } from './page-module-import.service.ts';
+import type { SourceModuleLoaderFactory } from './module-loading-types.ts';
+
+export type ServerModuleTranspilerOptions = Omit<PageModuleImportOptions, 'rootDir' | 'buildExecutor'>;
+
+export type ServerModuleImportDependency = Pick<AppModuleLoader, 'importModule' | 'invalidateDevelopmentGraph'>;
+
+/**
+ * Immutable execution context for one server-transpiler instance.
+ *
+ * @remarks
+ * Callers own when and why a new transpiler is created. This service only owns
+ * applying the supplied root/build-executor pair consistently to every module
+ * load that passes through it.
+ */
+export type ServerModuleTranspilerBootstrapArgs = {
+	rootDir: string;
+	getBuildExecutor?: () => BuildExecutor | undefined;
+	canLoadSourceModuleFromHost?: (filePath: string) => boolean;
+	getHostModuleLoader?: SourceModuleLoaderFactory;
+	getInvalidationVersion?: () => number;
+	invalidateModules?: (changedFiles?: string[]) => void;
+	pageModuleImportService?: ServerModuleImportDependency;
+	/** Factory evaluated on each importModule call to produce plugins applied to every load. */
+	getDefaultPlugins?: () => EcoBuildPlugin[];
+};
+
+/**
+ * App-owned boundary for server-side source module loading.
+ *
+ * @remarks
+ * This service centralizes server-side module transpilation and import behind
+ * an explicit caller-owned root and build executor.
+ */
+export class ServerModuleTranspiler {
+	private readonly pageModuleImportService: ServerModuleImportDependency;
+	private readonly getRootDir: () => string;
+	private readonly getBuildExecutor: () => BuildExecutor | undefined;
+	private readonly getInvalidationVersion: () => number | undefined;
+	private readonly invalidateModules: (changedFiles?: string[]) => void;
+	private readonly getDefaultPlugins: () => EcoBuildPlugin[];
+
+	/**
+	 * Creates one explicit server-transpiler boundary for a given execution
+	 * context.
+	 */
+	constructor(args: ServerModuleTranspilerBootstrapArgs) {
+		this.pageModuleImportService =
+			args.pageModuleImportService ??
+			new PageModuleImportService({
+				canLoadSourceModuleFromHost: args.canLoadSourceModuleFromHost,
+				getHostModuleLoader: args.getHostModuleLoader,
+			});
+		this.getRootDir = () => args.rootDir;
+		this.getBuildExecutor = args.getBuildExecutor ?? (() => undefined);
+		this.getInvalidationVersion = () => args.getInvalidationVersion?.();
+		this.getDefaultPlugins = args.getDefaultPlugins ?? (() => []);
+		this.invalidateModules = (changedFiles) => {
+			if (args.invalidateModules) {
+				args.invalidateModules(changedFiles);
+				return;
+			}
+
+			this.pageModuleImportService.invalidateDevelopmentGraph();
+		};
+	}
+
+	/**
+	 * Loads a server-side source module through the caller-owned transpile
+	 * context.
+	 */
+	async importModule<T = unknown>(options: ServerModuleTranspilerOptions): Promise<T> {
+		const mergedPlugins = [...this.getDefaultPlugins(), ...(options.plugins ?? [])];
+		const { plugins: _plugins, ...baseOptions } = options;
+		return await this.pageModuleImportService.importModule<T>({
+			...baseOptions,
+			...(mergedPlugins.length > 0 ? { plugins: mergedPlugins } : {}),
+			rootDir: this.getRootDir(),
+			buildExecutor: this.getBuildExecutor(),
+			invalidationVersion: this.getInvalidationVersion(),
+		});
+	}
+
+	/**
+	 * Invalidates cached module state for development reloads.
+	 */
+	invalidate(changedFiles?: string[]): void {
+		this.invalidateModules(changedFiles);
+	}
+
+	/**
+	 * Releases transpiler-owned resources.
+	 *
+	 * @remarks
+	 * The current implementation delegates cache ownership to lower-level module
+	 * loading services, so disposal is intentionally a no-op for now.
+	 */
+	async dispose(): Promise<void> {
+		return;
+	}
+}

package/src/services/module-loading/source-module-support.ts

@@ -0,0 +1,19 @@
+import path from 'node:path';
+
+/**
+ * Returns whether a source module can be loaded directly by the host runtime without
+ * first going through the transpile/import pipeline.
+ */
+export function supportsSourceModuleLoading(filePath: string): boolean {
+	const extension = path.extname(filePath);
+	return (
+		extension === '.js' ||
+		extension === '.jsx' ||
+		extension === '.ts' ||
+		extension === '.tsx' ||
+		extension === '.mjs' ||
+		extension === '.mts' ||
+		extension === '.cjs' ||
+		extension === '.cts'
+	);
+}