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

package/src/route-renderer/page-loading/page-dependency-bundling.ts

@@ -0,0 +1,205 @@
+import { existsSync, readFileSync } from 'node:fs';
+import type {
+	AssetDefinition,
+	FileScriptAsset,
+	FileStylesheetAsset,
+} from '../../services/assets/asset-processing-service/index.ts';
+import { AssetFactory } from '../../services/assets/asset-processing-service/index.ts';
+import { rapidhash } from '../../utils/hash.ts';
+
+/**
+ * Returns `true` when the asset attributes match the exact shape required for
+ * safe page-owned bundling.
+ */
+function hasOnlyExpectedAttributes(
+	attributes: Record<string, string> | undefined,
+	expected: Record<string, string>,
+): boolean {
+	const keys = Object.keys(attributes ?? {});
+	const expectedKeys = Object.keys(expected);
+
+	if (keys.length !== expectedKeys.length) {
+		return false;
+	}
+
+	return expectedKeys.every((key) => attributes?.[key] === expected[key]);
+}
+
+function isSafeBundledStylesheetReference(reference: string): boolean {
+	return (
+		reference.startsWith('/') ||
+		reference.startsWith('data:') ||
+		reference.startsWith('http://') ||
+		reference.startsWith('https://') ||
+		reference.startsWith('#')
+	);
+}
+
+/**
+ * Normalizes CSS URL tokens before safety checks so quoted and unquoted forms are treated equally.
+ */
+function normalizeCssReferenceToken(token: string): string {
+	return token.trim().replace(/^['"]|['"]$/g, '');
+}
+
+/**
+ * Rejects stylesheet content that contains relative references which would stop
+ * working once multiple files are collapsed into one page-owned bundle.
+ */
+function isSafeBundledStylesheetContent(content: string): boolean {
+	for (const match of content.matchAll(/@import\s+(?:url\()?['"]?([^'"\)\s]+)['"]?\)?/g)) {
+		const reference = normalizeCssReferenceToken(match[1] ?? '');
+		if (reference && !isSafeBundledStylesheetReference(reference)) {
+			return false;
+		}
+	}
+
+	for (const match of content.matchAll(/url\(([^)]+)\)/g)) {
+		const reference = normalizeCssReferenceToken(match[1] ?? '');
+		if (reference && !isSafeBundledStylesheetReference(reference)) {
+			return false;
+		}
+	}
+
+	return true;
+}
+
+function isBundleableFileStylesheetAsset(dependency: AssetDefinition): dependency is FileStylesheetAsset {
+	return dependency.kind === 'stylesheet' && dependency.source === 'file';
+}
+
+function isBundleableFileScriptAsset(dependency: AssetDefinition): dependency is FileScriptAsset {
+	return dependency.kind === 'script' && dependency.source === 'file';
+}
+
+/**
+ * Returns whether the current integration should collapse eligible page assets into
+ * page-owned bundle entries.
+ */
+export function shouldBundlePageDependencies(integrationName: string): boolean {
+	return integrationName === 'react' || integrationName === 'ecopages-jsx';
+}
+
+/**
+ * Rewrites eligible flat dependency declarations into page-owned stylesheet and script bundles.
+ *
+ * Only assets with the default attribute shape and without explicit packaging roles are
+ * collapsed so integration-specific or lazy behavior keeps its existing ownership model.
+ */
+export function createUnifiedPageDependencies(
+	dependencies: AssetDefinition[],
+	integrationName: string,
+): AssetDefinition[] {
+	if (!shouldBundlePageDependencies(integrationName)) {
+		return dependencies;
+	}
+
+	const bundleableStyles = dependencies.filter((dependency) => {
+		if (dependency.kind !== 'stylesheet' || dependency.inline || dependency.position === 'body') {
+			return false;
+		}
+
+		if (dependency.packageRole || !hasOnlyExpectedAttributes(dependency.attributes, { rel: 'stylesheet' })) {
+			return false;
+		}
+
+		if (dependency.source === 'content') {
+			return isSafeBundledStylesheetContent(dependency.content);
+		}
+
+		if (!existsSync(dependency.filepath)) {
+			return false;
+		}
+
+		return isSafeBundledStylesheetContent(readFileSync(dependency.filepath, 'utf8'));
+	}).filter(isBundleableFileStylesheetAsset);
+
+	const bundleableScripts = dependencies.filter((dependency) => {
+		return (
+			dependency.kind === 'script' &&
+			dependency.source === 'file' &&
+			!dependency.inline &&
+			!dependency.excludeFromHtml &&
+			dependency.position !== 'body' &&
+			!dependency.packageRole &&
+			dependency.bundle !== false &&
+			hasOnlyExpectedAttributes(dependency.attributes, { type: 'module', defer: '' }) &&
+			existsSync(dependency.filepath)
+		);
+	}).filter(isBundleableFileScriptAsset);
+
+	const bundledStylesheet =
+		bundleableStyles.length > 1
+			? AssetFactory.createContentStylesheet({
+					content: bundleableStyles.map((dependency) => readFileSync(dependency.filepath, 'utf8')).join('\n'),
+					position: 'head',
+					attributes: { rel: 'stylesheet' },
+					packageRole: 'page-style',
+				})
+			: undefined;
+
+	const bundleableStyleFilepaths = new Set(bundleableStyles.map((dependency) => dependency.filepath));
+	const pageScriptImports = [...new Set(bundleableScripts.map((dependency) => dependency.filepath))];
+	const bundleableScriptFilepaths = new Set(pageScriptImports);
+
+	const shouldBundlePageScript = pageScriptImports.length > 0 && bundleableScripts.length > 1;
+
+	const bundledScript =
+		shouldBundlePageScript
+			? AssetFactory.createContentScript({
+					name: `${integrationName}-page-${rapidhash(pageScriptImports.join('|')).toString(16)}`,
+					content: pageScriptImports.map((filepath) => `import ${JSON.stringify(filepath)};`).join('\n'),
+					position: 'head',
+					attributes: { type: 'module', defer: '' },
+					packageRole: 'page-script',
+				})
+			: undefined;
+
+	if (!bundledStylesheet && !bundledScript) {
+		return dependencies;
+	}
+
+	const unifiedDependencies: AssetDefinition[] = [];
+	let insertedStylesheet = false;
+	let insertedScript = false;
+
+	for (const dependency of dependencies) {
+		if (
+			bundledStylesheet &&
+			dependency.kind === 'stylesheet' &&
+			dependency.source === 'file' &&
+			bundleableStyleFilepaths.has(dependency.filepath)
+		) {
+			if (!insertedStylesheet) {
+				unifiedDependencies.push(bundledStylesheet);
+				insertedStylesheet = true;
+			}
+			continue;
+		}
+
+		if (
+			bundledScript &&
+			dependency.kind === 'script' &&
+			dependency.source === 'file' &&
+			bundleableScriptFilepaths.has(dependency.filepath)
+		) {
+			if (!insertedScript) {
+				unifiedDependencies.push(bundledScript);
+				insertedScript = true;
+			}
+			continue;
+		}
+
+		unifiedDependencies.push(dependency);
+	}
+
+	if (bundledScript && !insertedScript) {
+		unifiedDependencies.push(bundledScript);
+	}
+
+	if (bundledStylesheet && !insertedStylesheet) {
+		unifiedDependencies.push(bundledStylesheet);
+	}
+
+	return unifiedDependencies;
+}

package/src/route-renderer/page-loading/page-module-loader.test.ts

@@ -0,0 +1,183 @@
+import { describe, expect, it } from 'vitest';
+import { PageModuleLoaderService } from './page-module-loader.ts';
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import type { EcoPageFile } from '../../types/public-types.ts';
+import type { EcoPageComponent } from '../../eco/eco.types.ts';
+import type { AppModuleLoader } from '../../services/module-loading/app-module-loader.service.ts';
+
+describe('PageModuleLoaderService', () => {
+	const appConfig = {
+		rootDir: '/app',
+		defaultMetadata: {
+			title: 'Default title',
+			description: 'Default description',
+		},
+		runtime: {},
+	} as EcoPagesAppConfig;
+
+	it('should resolve static props via getStaticPropsForPage', async () => {
+		const service = new PageModuleLoaderService(appConfig, 'http://localhost:3000');
+		const result = await service.getStaticPropsForPage({
+			getStaticProps: async () => ({
+				props: { title: 'Page title' },
+			}),
+			params: { slug: 'a' },
+		});
+
+		expect(result.props).toEqual({ title: 'Page title' });
+	});
+
+	it('should merge default and dynamic metadata', async () => {
+		const service = new PageModuleLoaderService(appConfig, 'http://localhost:3000');
+		const metadata = await service.getMetadataPropsForPage({
+			getMetadata: async ({ props }) => ({
+				title: String(props.title),
+				description: 'Dynamic description',
+			}),
+			context: {
+				props: { title: 'Dynamic title' },
+				appConfig,
+				params: {},
+				query: {},
+			},
+		});
+
+		expect(metadata).toEqual({
+			title: 'Dynamic title',
+			description: 'Dynamic description',
+		});
+	});
+
+	it('should resolve page module using provided importer and prefer component static exports', async () => {
+		const service = new PageModuleLoaderService(appConfig, 'http://localhost:3000');
+		const Page = (() => 'ok') as EcoPageComponent<any>;
+		Page.staticProps = async () => ({ props: { from: 'component-static' } });
+		Page.metadata = async () => ({
+			title: 'component-metadata',
+			description: 'component-description',
+		});
+
+		const module = {
+			default: Page,
+			getStaticProps: async () => ({ props: { from: 'module-static' } }),
+			getMetadata: async () => ({
+				title: 'module-metadata',
+				description: 'module-description',
+			}),
+			extra: 'integration-value',
+		} satisfies EcoPageFile<{ extra: string }>;
+
+		const result = await service.resolvePageModule({
+			file: '/app/pages/index.tsx',
+			importPageFileFn: async () => module,
+		});
+
+		expect(result.getStaticProps).toBe(Page.staticProps);
+		expect(result.getMetadata).toBe(Page.metadata);
+		expect(result.integrationSpecificProps).toEqual({ extra: 'integration-value' });
+	});
+
+	it('should resolve page data end-to-end', async () => {
+		const service = new PageModuleLoaderService(appConfig, 'http://localhost:3000');
+		const result = await service.resolvePageData({
+			pageModule: {
+				getStaticProps: async () => ({ props: { title: 'From props' } }),
+				getMetadata: async ({ props }) => ({
+					title: String(props.title),
+					description: 'From metadata',
+				}),
+			},
+			routeOptions: {
+				file: '/app/pages/index.tsx',
+				params: {},
+				query: {},
+			},
+		});
+
+		expect(result).toEqual({
+			props: { title: 'From props' },
+			metadata: { title: 'From props', description: 'From metadata' },
+		});
+	});
+
+	it('should import page files through the app-owned module loader', async () => {
+		const calls: Array<unknown> = [];
+		const expectedModule = {
+			default: (() => 'ok') as EcoPageComponent<any>,
+		} as EcoPageFile;
+		const service = new PageModuleLoaderService(
+			{
+				...appConfig,
+				runtime: {
+					appModuleLoader: {
+						owner: 'bun',
+						async importModule<T = unknown>(options: unknown): Promise<T> {
+							calls.push(options);
+							return expectedModule as T;
+						},
+						invalidateDevelopmentGraph(): void {
+							return;
+						},
+					} satisfies AppModuleLoader,
+				},
+			} as EcoPagesAppConfig,
+			'http://localhost:3000',
+		);
+
+		const result = await service.importPageFile('/app/src/pages/index.tsx');
+
+		expect(result).toBe(expectedModule);
+		expect(calls).toEqual([
+			{
+				filePath: '/app/src/pages/index.tsx',
+				rootDir: '/app',
+				outdir: '/app/.eco/.server-modules',
+				bypassCache: undefined,
+				cacheScope: undefined,
+				transpileErrorMessage: expect.any(Function),
+				noOutputMessage: expect.any(Function),
+			},
+		]);
+	});
+
+	it('should forward cache scope options to the app-owned module loader', async () => {
+		const calls: Array<unknown> = [];
+		const expectedModule = {
+			default: (() => 'ok') as EcoPageComponent<any>,
+		} as EcoPageFile;
+		const service = new PageModuleLoaderService(
+			{
+				...appConfig,
+				runtime: {
+					appModuleLoader: {
+						owner: 'bun',
+						async importModule<T = unknown>(options: unknown): Promise<T> {
+							calls.push(options);
+							return expectedModule as T;
+						},
+						invalidateDevelopmentGraph(): void {
+							return;
+						},
+					} satisfies AppModuleLoader,
+				},
+			} as EcoPagesAppConfig,
+			'http://localhost:3000',
+		);
+
+		await service.importPageFile('/app/src/pages/index.tsx', {
+			cacheScope: 'request-metadata',
+		});
+
+		expect(calls).toEqual([
+			{
+				filePath: '/app/src/pages/index.tsx',
+				rootDir: '/app',
+				outdir: '/app/.eco/.server-modules',
+				bypassCache: undefined,
+				cacheScope: 'request-metadata',
+				transpileErrorMessage: expect.any(Function),
+				noOutputMessage: expect.any(Function),
+			},
+		]);
+	});
+});

package/src/route-renderer/page-loading/page-module-loader.ts

@@ -0,0 +1,184 @@
+import { invariant } from '../../utils/invariant.ts';
+import type {
+	EcoPageFile,
+	GetMetadata,
+	GetMetadataContext,
+	GetStaticProps,
+	PageMetadataProps,
+	RouteRendererOptions,
+	EcoPageComponent,
+} from '../../types/public-types.ts';
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import { getAppModuleLoader } from '../../services/module-loading/app-server-module-transpiler.service.ts';
+import type { AppModuleLoader } from '../../services/module-loading/app-module-loader.service.ts';
+import { resolveInternalExecutionDir } from '../../utils/resolve-work-dir.ts';
+
+/**
+ * Loads route page modules and normalizes their data hooks for rendering.
+ *
+ * @remarks
+ * This service keeps the render pipeline from depending directly on raw module
+ * imports. It owns the shared server-module transpiler setup, the precedence
+ * rules between component statics and module exports, and the normalization of
+ * page props and metadata into one renderer-facing shape.
+ */
+export class PageModuleLoaderService {
+	private appModuleLoader: AppModuleLoader;
+	private appConfig: EcoPagesAppConfig;
+	private runtimeOrigin: string;
+
+	/**
+	 * Creates the page-module loader for one app/runtime instance.
+	 *
+	 * @param appConfig Finalized app config that owns build and invalidation state.
+	 * @param runtimeOrigin Runtime origin exposed to page data hooks.
+	 */
+	constructor(appConfig: EcoPagesAppConfig, runtimeOrigin: string) {
+		this.appConfig = appConfig;
+		this.runtimeOrigin = runtimeOrigin;
+		this.appModuleLoader = getAppModuleLoader(appConfig);
+	}
+
+	/**
+	 * Imports one page module through the shared server-side module loading path.
+	 *
+	 * @remarks
+	 * The underlying transpiler keeps Bun and Node aligned on one framework-owned
+	 * loading contract even though the runtime-specific execution transport differs.
+	 */
+	async importPageFile(file: string, options?: { bypassCache?: boolean; cacheScope?: string }): Promise<EcoPageFile> {
+		try {
+			return await this.appModuleLoader.importModule<EcoPageFile>({
+				filePath: file,
+				rootDir: this.appConfig.rootDir,
+				outdir: `${resolveInternalExecutionDir(this.appConfig)}/.server-modules`,
+				bypassCache: options?.bypassCache,
+				cacheScope: options?.cacheScope,
+				transpileErrorMessage: (details) => `Error transpiling page file: ${details}`,
+				noOutputMessage: (targetFilePath) => `No transpiled output generated for page: ${targetFilePath}`,
+			});
+		} catch (error) {
+			invariant(false, `Error importing page file: ${error}`);
+		}
+	}
+
+	/**
+	 * Executes the page's static-props hook with Ecopages runtime context.
+	 *
+	 * @remarks
+	 * Pages without a static-props hook still return a normalized empty props
+	 * object so downstream render preparation does not branch on hook presence.
+	 */
+	async getStaticPropsForPage(options: {
+		getStaticProps?: GetStaticProps<Record<string, unknown>>;
+		params?: RouteRendererOptions['params'];
+	}): Promise<{
+		props: Record<string, unknown>;
+		metadata?: PageMetadataProps;
+	}> {
+		const { getStaticProps, params } = options;
+		return getStaticProps
+			? await getStaticProps({
+					pathname: { params: params ?? {} },
+					appConfig: this.appConfig,
+					runtimeOrigin: this.runtimeOrigin,
+				})
+					.then((data) => data)
+					.catch((err) => {
+						throw new Error(`Error fetching static props: ${err.message}`);
+					})
+			: {
+					props: {},
+					metadata: undefined,
+				};
+	}
+
+	/**
+	 * Builds the final page metadata object for one render request.
+	 *
+	 * @remarks
+	 * App-level default metadata forms the baseline, then page-level metadata is
+	 * overlaid so route-specific fields win without dropping global defaults.
+	 */
+	async getMetadataPropsForPage(options: {
+		getMetadata: GetMetadata | undefined;
+		context: GetMetadataContext;
+	}): Promise<PageMetadataProps> {
+		const { getMetadata, context } = options;
+		let metadata: PageMetadataProps = this.appConfig.defaultMetadata;
+		if (getMetadata) {
+			const dynamicMetadata = await getMetadata({
+				params: context.params,
+				query: context.query,
+				props: context.props,
+				appConfig: this.appConfig,
+			});
+			metadata = { ...metadata, ...dynamicMetadata };
+		}
+		return metadata;
+	}
+
+	/**
+	 * Loads a page module and normalizes integration-facing exports.
+	 * When both component static methods and module exports exist, component statics win.
+	 */
+	async resolvePageModule(options: {
+		file: string;
+		importPageFileFn?: (file: string) => Promise<EcoPageFile>;
+	}): Promise<{
+		Page: EcoPageFile['default'] | EcoPageComponent<any>;
+		getStaticProps?: GetStaticProps<Record<string, unknown>>;
+		getMetadata?: GetMetadata;
+		integrationSpecificProps: Record<string, unknown>;
+	}> {
+		const module = await (options.importPageFileFn ?? ((file) => this.importPageFile(file)))(options.file);
+		const {
+			default: Page,
+			getStaticProps: moduleGetStaticProps,
+			getMetadata: moduleGetMetadata,
+			...integrationSpecificProps
+		} = module;
+
+		return {
+			Page,
+			getStaticProps: Page.staticProps ?? moduleGetStaticProps,
+			getMetadata: Page.metadata ?? moduleGetMetadata,
+			integrationSpecificProps,
+		};
+	}
+
+	/**
+	 * Resolves the page data needed by the render pipeline.
+	 *
+	 * @remarks
+	 * Static props are resolved first because page metadata may depend on those
+	 * props. This preserves the same ordering whether data hooks are declared as
+	 * component statics or module exports.
+	 */
+	async resolvePageData(options: {
+		pageModule: {
+			getStaticProps?: GetStaticProps<Record<string, unknown>>;
+			getMetadata?: GetMetadata;
+		};
+		routeOptions: RouteRendererOptions;
+	}): Promise<{
+		props: Record<string, unknown>;
+		metadata: PageMetadataProps;
+	}> {
+		const { props } = await this.getStaticPropsForPage({
+			getStaticProps: options.pageModule.getStaticProps,
+			params: options.routeOptions.params,
+		});
+
+		const metadata = await this.getMetadataPropsForPage({
+			getMetadata: options.pageModule.getMetadata,
+			context: {
+				props,
+				params: options.routeOptions.params ?? {},
+				query: options.routeOptions.query ?? {},
+			} as GetMetadataContext,
+		});
+
+		return { props, metadata };
+	}
+}

package/src/route-renderer/route-renderer.ts

@@ -0,0 +1,136 @@
+import type { EcoPagesAppConfig } from '../types/internal-types.ts';
+import type { IntegrationPlugin } from '../plugins/integration-plugin.ts';
+import type { EcoPageFile, RouteRenderResult, RouteRendererOptions } from '../types/public-types.ts';
+import { invariant } from '../utils/invariant.ts';
+import { PathUtils } from '../utils/path-utils.module.ts';
+import type { IntegrationRenderer, RouteModuleLoadOptions } from './orchestration/integration-renderer.ts';
+
+/**
+ * Thin wrapper around one initialized integration renderer.
+ *
+ * @remarks
+ * This type exists so higher-level routing code can ask for a route renderer
+ * without depending on the full integration plugin lifecycle. It delegates all
+ * real work to the integration-specific renderer selected by the factory.
+ */
+export class RouteRenderer {
+	private renderer: IntegrationRenderer;
+
+	/**
+	 * Creates a route renderer bound to one integration renderer instance.
+	 */
+	constructor(renderer: IntegrationRenderer) {
+		this.renderer = renderer;
+	}
+
+	/**
+	 * Executes the render pipeline for one matched route.
+	 */
+	async createRoute(options: RouteRendererOptions): Promise<RouteRenderResult> {
+		return this.renderer.execute(options);
+	}
+
+	/**
+	 * Loads the route module through the owning integration renderer.
+	 */
+	async loadPageModule(filePath: string, options?: RouteModuleLoadOptions): Promise<EcoPageFile> {
+		return this.renderer.loadPageModule(filePath, options);
+	}
+}
+
+/**
+ * Selects and caches integration renderers for route files and explicit views.
+ *
+ * @remarks
+ * The factory owns the policy that maps a route file or explicit integration
+ * name to one initialized integration renderer. Renderer instances are cached by
+ * integration name so repeated requests do not rebuild renderer state.
+ */
+export class RouteRendererFactory {
+	private appConfig: EcoPagesAppConfig;
+	runtimeOrigin: string;
+	private rendererModules?: unknown;
+	private rendererCache = new Map<string, IntegrationRenderer>();
+
+	/**
+	 * Creates the route-renderer factory for one app/runtime instance.
+	 */
+	constructor({
+		appConfig,
+		rendererModules,
+		runtimeOrigin,
+	}: {
+		appConfig: EcoPagesAppConfig;
+		rendererModules?: unknown;
+		runtimeOrigin: string;
+	}) {
+		this.appConfig = appConfig;
+		this.rendererModules = rendererModules;
+		this.runtimeOrigin = runtimeOrigin;
+	}
+
+	/**
+	 * Returns a route renderer for the supplied route file.
+	 */
+	createRenderer(filePath: string): RouteRenderer {
+		const integrationRenderer = this.getRouteRendererEngine(filePath);
+		invariant(!!integrationRenderer, `No integration renderer found for file: ${filePath}`);
+		return new RouteRenderer(integrationRenderer);
+	}
+
+	/**
+	 * Get an integration renderer by its name.
+	 * Used for explicit routing where views specify their integration via __eco.integration.
+	 */
+	getRendererByIntegration(integrationName: string): IntegrationRenderer | null {
+		const integrationPlugin = this.appConfig.integrations.find((plugin) => plugin.name === integrationName);
+		if (!integrationPlugin) {
+			return null;
+		}
+
+		const cached = this.rendererCache.get(integrationName);
+		if (cached) {
+			return cached;
+		}
+
+		const renderer = integrationPlugin.initializeRenderer({
+			rendererModules: this.rendererModules,
+		});
+		this.rendererCache.set(integrationName, renderer);
+		return renderer;
+	}
+
+	/**
+	 * Resolves the integration plugin that owns a given route file.
+	 */
+	getIntegrationPlugin(filePath: string): IntegrationPlugin {
+		const templateExtension = PathUtils.getEcoTemplateExtension(filePath);
+		const isIntegrationPlugin = (plugin: IntegrationPlugin): boolean => {
+			return plugin.extensions.some((extension) => templateExtension === extension);
+		};
+		const integrationPlugin = this.appConfig.integrations.find(isIntegrationPlugin);
+		invariant(
+			!!integrationPlugin,
+			`No integration plugin found for template extension: ${templateExtension}, file: ${filePath}`,
+		);
+		return integrationPlugin as IntegrationPlugin;
+	}
+
+	/**
+	 * Returns the cached renderer engine for the file's owning integration,
+	 * creating it on first use.
+	 */
+	private getRouteRendererEngine(filePath: string): IntegrationRenderer {
+		const integrationPlugin = this.getIntegrationPlugin(filePath);
+		const cached = this.rendererCache.get(integrationPlugin.name);
+		if (cached) {
+			return cached;
+		}
+
+		const renderer = integrationPlugin.initializeRenderer({
+			rendererModules: this.rendererModules,
+		});
+		this.rendererCache.set(integrationPlugin.name, renderer);
+		return renderer;
+	}
+}