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

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

@@ -1,508 +0,0 @@
-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

@@ -1,162 +0,0 @@
-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}`;
-	}
-}