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

package/src/route-renderer/orchestration/render-preparation.service.ts

@@ -0,0 +1,508 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import type {
+	ComponentRenderResult,
+	EcoComponent,
+	EcoComponentConfig,
+	DependencyAttributes,
+	EcoPageComponent,
+	EcoPageFile,
+	EcoPagesElement,
+	GetMetadata,
+	GetStaticProps,
+	HtmlTemplateProps,
+	IntegrationRendererRenderOptions,
+	PageProps,
+	PageMetadataProps,
+	ResolvedLazyTrigger,
+	RouteRendererOptions,
+} from '../../types/public-types.ts';
+import {
+	type AssetProcessingService,
+	AssetFactory,
+	type ProcessedAsset,
+} from '../../services/assets/asset-processing-service/index.ts';
+import { buildGlobalInjectorBootstrapContent, buildGlobalInjectorMapScript } from '../../eco/global-injector-map.ts';
+import { LocalsAccessError } from '../../errors/locals-access-error.ts';
+import { BoundaryPlanningService } from './boundary-planning.service.ts';
+import { PagePackagingService } from './page-packaging.service.ts';
+import { dedupeProcessedAssets } from './processed-asset-dedupe.ts';
+
+type ResolvedPageModule = {
+	Page: EcoPageFile['default'] | EcoPageComponent<any>;
+	getStaticProps?: GetStaticProps<Record<string, unknown>>;
+	getMetadata?: GetMetadata;
+	integrationSpecificProps: Record<string, unknown>;
+};
+
+export interface RenderPreparationCallbacks {
+	resolvePageModule(file: string): Promise<ResolvedPageModule>;
+	getHtmlTemplate(): Promise<EcoComponent<HtmlTemplateProps>>;
+	resolvePageData(
+		pageModule: {
+			getStaticProps?: GetStaticProps<Record<string, unknown>>;
+			getMetadata?: GetMetadata;
+		},
+		routeOptions: RouteRendererOptions,
+	): Promise<{ props: Record<string, unknown>; metadata: PageMetadataProps }>;
+	resolveDependencies(components: (EcoComponent | Partial<EcoComponent>)[]): Promise<ProcessedAsset[]>;
+	buildRouteRenderAssets(file: string): Promise<ProcessedAsset[]> | undefined;
+	shouldRenderPageComponent(input: {
+		Page: EcoComponent;
+		Layout?: EcoComponent;
+		options: RouteRendererOptions;
+	}): boolean;
+	renderPageComponent(input: {
+		component: EcoComponent;
+		props: Record<string, unknown>;
+	}): Promise<ComponentRenderResult>;
+}
+
+export interface RenderPreparationServiceDependencies {
+	boundaryPlanningService?: BoundaryPlanningService;
+	pagePackagingService?: PagePackagingService;
+}
+
+function createPageLocalsProxy(filePath: string): Record<string, never> {
+	const errorMessage = `[ecopages] Request locals are only available during request-time rendering with cache: 'dynamic'. Page: ${filePath}. If you meant to use locals here, set cache: 'dynamic' and provide locals from route middleware/handlers.`;
+
+	return new Proxy(
+		{},
+		{
+			get: () => {
+				throw new LocalsAccessError(errorMessage);
+			},
+			set: () => {
+				throw new LocalsAccessError(errorMessage);
+			},
+			has: () => {
+				throw new LocalsAccessError(errorMessage);
+			},
+			ownKeys: () => {
+				throw new LocalsAccessError(errorMessage);
+			},
+			deleteProperty: () => {
+				throw new LocalsAccessError(errorMessage);
+			},
+			defineProperty: () => {
+				throw new LocalsAccessError(errorMessage);
+			},
+			getOwnPropertyDescriptor: () => {
+				throw new LocalsAccessError(errorMessage);
+			},
+		},
+	);
+}
+
+/**
+ * Prepares the normalized render inputs consumed by `IntegrationRenderer.execute()`.
+ *
+ * This service owns the orchestration that happens before the main HTML render:
+ * page module resolution, data loading, dependency aggregation, page-root
+ * component artifact capture, lazy trigger bootstrap generation, and request
+ * locals policy.
+ */
+export class RenderPreparationService {
+	private appConfig: EcoPagesAppConfig;
+	private assetProcessingService: AssetProcessingService;
+	private readonly boundaryPlanningService: BoundaryPlanningService;
+	private readonly pagePackagingService: PagePackagingService;
+
+	/**
+	 * Creates the render-preparation orchestrator for one app instance.
+	 *
+	 * @remarks
+	 * The service is app-scoped because it depends on finalized config defaults and
+	 * the app-owned asset-processing pipeline while remaining renderer-agnostic.
+	 */
+	constructor(
+		appConfig: EcoPagesAppConfig,
+		assetProcessingService: AssetProcessingService,
+		dependencies: RenderPreparationServiceDependencies = {},
+	) {
+		this.appConfig = appConfig;
+		this.assetProcessingService = assetProcessingService;
+		this.boundaryPlanningService = dependencies.boundaryPlanningService ?? new BoundaryPlanningService(appConfig);
+		this.pagePackagingService = dependencies.pagePackagingService ?? new PagePackagingService();
+	}
+
+	/**
+	 * Builds the final render options object used by the integration-specific
+	 * renderer.
+	 *
+	 * The returned object contains normalized page data, processed dependency
+	 * state, component render artifacts, and the locals contract expected by the
+	 * rest of the pipeline.
+	 *
+	 * @typeParam C Integration render output element type.
+	 * @param routeOptions Route-level render inputs.
+	 * @param currentIntegrationName Active integration name for this preparation pass.
+	 * @param callbacks Renderer-specific hooks used during preparation.
+	 * @returns Normalized render options.
+	 */
+	async prepare<C = EcoPagesElement>(
+		routeOptions: RouteRendererOptions,
+		currentIntegrationName: string,
+		callbacks: RenderPreparationCallbacks,
+	): Promise<IntegrationRendererRenderOptions<C>> {
+		const pageModule = await callbacks.resolvePageModule(routeOptions.file);
+		const { Page, integrationSpecificProps } = pageModule;
+		const HtmlTemplate = await callbacks.getHtmlTemplate();
+		const { props, metadata } = await callbacks.resolvePageData(pageModule, routeOptions);
+		const Layout = Page.config?.layout;
+		const boundaryPlan = this.boundaryPlanningService.buildPlan({
+			routeFile: routeOptions.file,
+			currentIntegrationName,
+			HtmlTemplate,
+			Layout,
+			Page: Page as EcoComponent,
+		});
+
+		const componentsToResolve = Layout ? [HtmlTemplate, Layout, Page] : [HtmlTemplate, Page];
+		const resolvedDependencies = await callbacks.resolveDependencies(componentsToResolve);
+		const usedIntegrationDependencies = this.collectUsedIntegrationDependencies(
+			componentsToResolve,
+			currentIntegrationName,
+		);
+		const pageDeps = (await callbacks.buildRouteRenderAssets(routeOptions.file)) || [];
+		const allDependencies = [...resolvedDependencies, ...usedIntegrationDependencies, ...pageDeps];
+
+		let componentRender: ComponentRenderResult | undefined;
+		if (callbacks.shouldRenderPageComponent({ Page, Layout, options: routeOptions })) {
+			const pageRootRender = await this.renderPageRoot({
+				Page: Page as EcoComponent,
+				props,
+				routeOptions,
+				callbacks,
+			});
+			componentRender = pageRootRender.componentRender;
+
+			if (componentRender.assets?.length) {
+				allDependencies.push(...componentRender.assets);
+			}
+		}
+
+		const triggers = this.collectResolvedTriggers(componentsToResolve);
+		if (triggers.length > 0) {
+			const globalAssets = await this.buildGlobalInjectorAssets(triggers, currentIntegrationName);
+			allDependencies.push(...globalAssets);
+		}
+
+		const eagerSsrLazyAssets = await this.buildEagerSsrLazyAssets(componentsToResolve, currentIntegrationName);
+		if (eagerSsrLazyAssets.length > 0) {
+			allDependencies.push(...eagerSsrLazyAssets);
+		}
+
+		const dedupedDependencies = dedupeProcessedAssets(allDependencies);
+		const pagePackage = this.pagePackagingService.createPagePackage(dedupedDependencies);
+
+		const pageProps = {
+			...props,
+			params: routeOptions.params || {},
+			query: routeOptions.query || {},
+		};
+
+		const cacheStrategy = (Page as EcoPageComponent<any>).cache;
+		const defaultCacheStrategy = this.appConfig.cache?.defaultStrategy ?? 'static';
+		const effectiveCacheStrategy = cacheStrategy ?? defaultCacheStrategy;
+		const localsAvailable = effectiveCacheStrategy === 'dynamic' && routeOptions.locals !== undefined;
+
+		const pageLocals = localsAvailable
+			? routeOptions.locals!
+			: (createPageLocalsProxy(routeOptions.file) as RouteRendererOptions['locals']);
+
+		const locals = localsAvailable ? routeOptions.locals : undefined;
+		const preparedOptions: IntegrationRendererRenderOptions<C> = {
+			...routeOptions,
+			resolvedDependencies,
+			pagePackage,
+			componentRender,
+			HtmlTemplate: HtmlTemplate as EcoComponent<HtmlTemplateProps, C>,
+			Layout,
+			props,
+			Page: Page as EcoComponent<PageProps, C>,
+			metadata,
+			params: routeOptions.params || {},
+			query: routeOptions.query || {},
+			pageProps,
+			locals,
+			pageLocals,
+			cacheStrategy,
+			boundaryPlan,
+		};
+
+		return {
+			...integrationSpecificProps,
+			...preparedOptions,
+		};
+	}
+
+	/**
+	 * Collects resolved lazy trigger metadata from the component tree.
+	 *
+	 * Traversal is depth-first and deduplicated by component identity so shared
+	 * component dependencies do not emit duplicate trigger sets.
+	 *
+	 * @param components Root component set.
+	 * @param seen Internal visited set for shared graphs.
+	 * @returns All resolved lazy triggers reachable from the root set.
+	 */
+	private collectResolvedTriggers(
+		components: (EcoComponent | Partial<EcoComponent>)[],
+		seen = new Set<object>(),
+	): ResolvedLazyTrigger[] {
+		const triggers: ResolvedLazyTrigger[] = [];
+		for (const comp of components) {
+			if (!comp) {
+				continue;
+			}
+
+			const ecoComp = comp as EcoComponent;
+			if (seen.has(ecoComp)) {
+				continue;
+			}
+			seen.add(ecoComp);
+			const ownTriggers = ecoComp.config?._resolvedLazyTriggers;
+			if (ownTriggers?.length) {
+				triggers.push(...ownTriggers);
+			}
+			const nested = ecoComp.config?.dependencies?.components;
+			if (nested?.length) {
+				triggers.push(...this.collectResolvedTriggers(nested, seen));
+			}
+		}
+		return triggers;
+	}
+
+	/**
+	 * Collects global integration dependencies used by nested components belonging
+	 * to integrations other than the current renderer.
+	 *
+	 * @param components Root component set.
+	 * @returns Processed integration dependencies contributed by nested integrations.
+	 */
+	private collectUsedIntegrationDependencies(
+		components: (EcoComponent | Partial<EcoComponent>)[],
+		currentIntegrationName: string,
+	): ProcessedAsset[] {
+		const integrationNames = this.collectIntegrationNames(components);
+		const dependencies: ProcessedAsset[] = [];
+
+		for (const integrationName of integrationNames) {
+			if (integrationName === currentIntegrationName) {
+				continue;
+			}
+
+			const integrationPlugin = this.appConfig.integrations.find(
+				(integration) => integration.name === integrationName,
+			);
+			if (!integrationPlugin || typeof integrationPlugin.getResolvedIntegrationDependencies !== 'function') {
+				continue;
+			}
+
+			dependencies.push(...integrationPlugin.getResolvedIntegrationDependencies());
+		}
+
+		return dependencies;
+	}
+
+	/**
+	 * Discovers integration names referenced by the component dependency graph.
+	 *
+	 * @param components Root component set.
+	 * @param seen Internal visited set for shared graphs.
+	 * @returns Set of integration names found in the graph.
+	 */
+	private collectIntegrationNames(
+		components: (EcoComponent | Partial<EcoComponent>)[],
+		seen = new Set<object>(),
+	): Set<string> {
+		const integrationNames = new Set<string>();
+
+		for (const comp of components) {
+			if (!comp) {
+				continue;
+			}
+
+			const ecoComp = comp as EcoComponent;
+			if (seen.has(ecoComp)) {
+				continue;
+			}
+			seen.add(ecoComp);
+
+			const integrationName = ecoComp.config?.integration ?? ecoComp.config?.__eco?.integration;
+			if (integrationName) {
+				integrationNames.add(integrationName);
+			}
+
+			const nested = ecoComp.config?.dependencies?.components;
+			if (nested?.length) {
+				const nestedNames = this.collectIntegrationNames(nested, seen);
+				for (const nestedName of nestedNames) {
+					integrationNames.add(nestedName);
+				}
+			}
+		}
+
+		return integrationNames;
+	}
+
+	/**
+	 * Renders the page root through the component-level render contract so any
+	 * integration-specific assets and root attributes are available before the main
+	 * document render.
+	 *
+	 * @param input Page root render inputs.
+	 * @returns Structured component render result.
+	 */
+	private async renderPageRoot(input: {
+		Page: EcoComponent;
+		props: Record<string, unknown>;
+		routeOptions: RouteRendererOptions;
+		callbacks: RenderPreparationCallbacks;
+	}): Promise<{ componentRender: ComponentRenderResult }> {
+		return {
+			componentRender: await input.callbacks.renderPageComponent({
+				component: input.Page,
+				props: {
+					...input.props,
+					params: input.routeOptions.params || {},
+					query: input.routeOptions.query || {},
+				},
+			}),
+		};
+	}
+
+	/**
+	 * Builds the runtime assets needed to bootstrap global lazy trigger execution.
+	 *
+	 * @param triggers Fully resolved lazy trigger definitions.
+	 * @returns Processed assets that should be merged into the final dependency set.
+	 */
+	private async buildGlobalInjectorAssets(
+		triggers: ResolvedLazyTrigger[],
+		currentIntegrationName: string,
+	): Promise<ProcessedAsset[]> {
+		const globalInjectorImportPath = createRequire(import.meta.url).resolve('@ecopages/scripts-injector/global');
+
+		const mapScript = AssetFactory.createInlineContentScript({
+			position: 'head',
+			name: 'ecopages-global-injector-map',
+			content: buildGlobalInjectorMapScript(triggers),
+			attributes: { type: 'ecopages/global-injector-map' },
+			packageRole: 'keep-separate',
+			bundle: false,
+		});
+		const bootstrapInlineScript = AssetFactory.createInlineContentScript({
+			position: 'head',
+			name: 'ecopages-global-injector-bootstrap',
+			content: buildGlobalInjectorBootstrapContent(globalInjectorImportPath),
+			attributes: { type: 'module' },
+			packageRole: 'keep-separate',
+			bundle: true,
+		});
+
+		return this.assetProcessingService.processDependencies([mapScript, bootstrapInlineScript], currentIntegrationName);
+	}
+
+	private async buildEagerSsrLazyAssets(
+		components: (EcoComponent | Partial<EcoComponent>)[],
+		currentIntegrationName: string,
+	): Promise<ProcessedAsset[]> {
+		const dependencies = this.collectEagerSsrLazyDependencies(components);
+		if (dependencies.length === 0) {
+			return [];
+		}
+
+		return this.assetProcessingService.processDependencies(dependencies, `${currentIntegrationName}:ssr-lazy`);
+	}
+
+	private collectEagerSsrLazyDependencies(
+		components: (EcoComponent | Partial<EcoComponent>)[],
+	): ReturnType<AssetProcessingService['processDependencies']> extends Promise<infer _>
+		? Parameters<AssetProcessingService['processDependencies']>[0]
+		: never {
+		const dependencies = [] as Parameters<AssetProcessingService['processDependencies']>[0];
+		const visitedConfigs = new Set<EcoComponentConfig>();
+		const seenKeys = new Set<string>();
+
+		const normalizeAttributes = (attributes?: DependencyAttributes) => ({
+			type: 'module',
+			defer: '',
+			...(attributes ?? {}),
+		});
+
+		const collect = (config?: EcoComponentConfig) => {
+			if (!config || visitedConfigs.has(config)) {
+				return;
+			}
+
+			visitedConfigs.add(config);
+
+			const componentFile = config.__eco?.file;
+			if (componentFile) {
+				const componentDir = path.dirname(componentFile);
+				for (const script of config.dependencies?.scripts ?? []) {
+					if (typeof script === 'string' || !script.lazy || script.ssr !== true) {
+						continue;
+					}
+
+					const attributes = normalizeAttributes(script.attributes);
+
+					if (script.content) {
+						const key = `content:${script.content}:${JSON.stringify(attributes)}`;
+						if (seenKeys.has(key)) {
+							continue;
+						}
+
+						seenKeys.add(key);
+						dependencies.push(
+							AssetFactory.createContentScript({
+								position: 'head',
+								content: script.content,
+								attributes,
+								packageRole: 'dynamic-chunk',
+							}),
+						);
+						continue;
+					}
+
+					if (!script.src) {
+						continue;
+					}
+
+					const resolvedPath = path.resolve(componentDir, script.src);
+					const key = `file:${resolvedPath}:${JSON.stringify(attributes)}`;
+					if (seenKeys.has(key)) {
+						continue;
+					}
+
+					seenKeys.add(key);
+					dependencies.push(
+						AssetFactory.createFileScript({
+							filepath: resolvedPath,
+							position: 'head',
+							attributes,
+							packageRole: 'dynamic-chunk',
+						}),
+					);
+				}
+			}
+
+			if (config.layout?.config) {
+				collect(config.layout.config);
+			}
+
+			for (const nestedComponent of config.dependencies?.components ?? []) {
+				collect(nestedComponent?.config);
+			}
+		};
+
+		for (const component of components) {
+			collect(component.config);
+		}
+
+		return dependencies;
+	}
+}

package/src/route-renderer/orchestration/route-shell-composer.service.ts

@@ -0,0 +1,162 @@
+import type {
+	BaseIntegrationContext,
+	ComponentRenderInput,
+	ComponentRenderResult,
+	EcoComponent,
+	HtmlTemplateProps,
+	PageMetadataProps,
+} from '../../types/public-types.ts';
+import type { ProcessedAsset } from '../../services/assets/asset-processing-service/index.ts';
+import type { RenderToResponseContext } from './integration-renderer.ts';
+
+type ShellRendererCache = BaseIntegrationContext['rendererCache'];
+
+export interface RouteShellComposerCallbacks {
+	hasForeignBoundaryDescendants(component: EcoComponent): boolean;
+	createHtmlResponse(body: BodyInit, ctx: RenderToResponseContext): Response;
+	renderComponentBoundary(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+	prepareViewDependencies(view: EcoComponent, layout?: EcoComponent): Promise<ProcessedAsset[]>;
+	getHtmlTemplate(): Promise<EcoComponent<HtmlTemplateProps>>;
+	resolveViewMetadata<P>(view: EcoComponent<P>, props: P): Promise<PageMetadataProps>;
+	appendProcessedDependencies(...assetGroups: Array<readonly ProcessedAsset[] | undefined>): ProcessedAsset[];
+	finalizeResolvedHtml(options: {
+		html: string;
+		partial?: boolean;
+		componentRootAttributes?: Record<string, string>;
+		documentAttributes?: Record<string, string>;
+		transformHtml?: boolean;
+	}): Promise<string>;
+	docType: string;
+}
+
+export class RouteShellComposer {
+	async renderPartialViewResponse<P>(
+		input: {
+			view: EcoComponent<P>;
+			props: P;
+			ctx: RenderToResponseContext;
+			renderInline?: () => Promise<BodyInit>;
+			transformHtml?: (html: string) => string;
+		},
+		callbacks: RouteShellComposerCallbacks,
+	): Promise<Response> {
+		if (input.renderInline && !callbacks.hasForeignBoundaryDescendants(input.view as EcoComponent)) {
+			return callbacks.createHtmlResponse(await input.renderInline(), input.ctx);
+		}
+
+		const rendererCache = new Map<string, unknown>() as ShellRendererCache;
+		const viewRender = await callbacks.renderComponentBoundary({
+			component: input.view as EcoComponent,
+			props: (input.props ?? {}) as Record<string, unknown>,
+			integrationContext: { rendererCache },
+		});
+		const html = input.transformHtml ? input.transformHtml(viewRender.html) : viewRender.html;
+
+		return callbacks.createHtmlResponse(html, input.ctx);
+	}
+
+	async renderViewWithDocumentShell<P>(
+		input: {
+			view: EcoComponent<P>;
+			props: P;
+			ctx: RenderToResponseContext;
+			layout?: EcoComponent;
+		},
+		callbacks: RouteShellComposerCallbacks,
+	): Promise<Response> {
+		const normalizedProps = (input.props ?? {}) as Record<string, unknown>;
+
+		if (input.ctx.partial) {
+			return this.renderPartialViewResponse(input, callbacks);
+		}
+
+		await callbacks.prepareViewDependencies(input.view, input.layout);
+
+		const HtmlTemplate = await callbacks.getHtmlTemplate();
+		const metadata = await callbacks.resolveViewMetadata(input.view, input.props);
+		const rendererCache = new Map<string, unknown>() as ShellRendererCache;
+		const viewRender = await callbacks.renderComponentBoundary({
+			component: input.view as EcoComponent,
+			props: normalizedProps,
+			integrationContext: { rendererCache },
+		});
+		const layoutRender = input.layout
+			? await callbacks.renderComponentBoundary({
+					component: input.layout,
+					props: {},
+					children: viewRender.html,
+					integrationContext: { rendererCache },
+				})
+			: undefined;
+		const documentRender = await callbacks.renderComponentBoundary({
+			component: HtmlTemplate as EcoComponent,
+			props: {
+				metadata,
+				pageProps: normalizedProps,
+			},
+			children: layoutRender?.html ?? viewRender.html,
+			integrationContext: { rendererCache },
+		});
+
+		callbacks.appendProcessedDependencies(viewRender.assets, layoutRender?.assets, documentRender.assets);
+
+		const html = await callbacks.finalizeResolvedHtml({
+			html: `${callbacks.docType}${documentRender.html}`,
+			partial: false,
+		});
+
+		return callbacks.createHtmlResponse(html, input.ctx);
+	}
+
+	async renderPageWithDocumentShell(
+		input: {
+			page: {
+				component: EcoComponent;
+				props: Record<string, unknown>;
+			};
+			layout?: {
+				component: EcoComponent;
+				props?: Record<string, unknown>;
+			};
+			htmlTemplate: EcoComponent;
+			metadata: PageMetadataProps;
+			pageProps: Record<string, unknown>;
+			documentProps?: Record<string, unknown>;
+			transformDocumentHtml?: (html: string) => string;
+		},
+		callbacks: RouteShellComposerCallbacks,
+	): Promise<string> {
+		const rendererCache = new Map<string, unknown>() as ShellRendererCache;
+		const pageRender = await callbacks.renderComponentBoundary({
+			component: input.page.component,
+			props: input.page.props,
+			integrationContext: { rendererCache },
+		});
+		const layoutRender = input.layout
+			? await callbacks.renderComponentBoundary({
+					component: input.layout.component,
+					props: input.layout.props ?? {},
+					children: pageRender.html,
+					integrationContext: { rendererCache },
+				})
+			: undefined;
+		const documentRender = await callbacks.renderComponentBoundary({
+			component: input.htmlTemplate,
+			props: {
+				metadata: input.metadata,
+				pageProps: input.pageProps,
+				...(input.documentProps ?? {}),
+			},
+			children: layoutRender?.html ?? pageRender.html,
+			integrationContext: { rendererCache },
+		});
+
+		callbacks.appendProcessedDependencies(pageRender.assets, layoutRender?.assets, documentRender.assets);
+
+		const documentHtml = input.transformDocumentHtml
+			? input.transformDocumentHtml(documentRender.html)
+			: documentRender.html;
+
+		return `${callbacks.docType}${documentHtml}`;
+	}
+}