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

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

@@ -0,0 +1,150 @@
+import path from 'node:path';
+import type { EcoComponent } from '../../types/public-types.ts';
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import type {
+	AssetProcessingService,
+	ProcessedAsset,
+} from '../../services/assets/asset-processing-service/index.ts';
+import { rapidhash } from '../../utils/hash.ts';
+import { AssetFactory } from '../../services/assets/asset-processing-service/index.ts';
+import {
+	buildResolvedLazyTriggers,
+	type ResolvedLazyGroup,
+} from './lazy-trigger-planning.ts';
+import { collectComponentDependencies } from './component-dependency-collection.ts';
+import { createUnifiedPageDependencies } from './page-dependency-bundling.ts';
+
+export const DEPENDENCY_ERRORS = {
+	INVALID_STYLESHEET_ENTRY: 'Invalid stylesheet dependency entry: expected src or content',
+	INVALID_SCRIPT_ENTRY: 'Invalid script dependency entry: expected src or content',
+	LAZY_SCRIPT_MISSING_SRC: 'Lazy script dependency entry in dependencies.scripts requires a src value',
+} as const;
+
+function resolveLazyScripts(appConfig: EcoPagesAppConfig, componentDir: string, scripts: string[]): string {
+	const getSafeFileName = (filepath: string): string => {
+		const EXTENSIONS_TO_JS = ['ts', 'tsx'];
+		const safe = filepath.replace(new RegExp(`\\.(${EXTENSIONS_TO_JS.join('|')})$`), '.js');
+		return safe.startsWith('./') ? safe.slice(2) : safe;
+	};
+
+	const baseDir = componentDir.split(appConfig.srcDir)[1] ?? '';
+	const resolvedPaths = scripts.map((script) => {
+		const relativePath = [AssetFactory.RESOLVED_ASSETS_DIR, baseDir, getSafeFileName(script)]
+			.filter(Boolean)
+			.join('/')
+			.replace(/\/+/g, '/');
+
+		return `/${relativePath.replace(/^\/+/, '')}`;
+	});
+
+	return resolvedPaths.join(',');
+}
+
+const ECOPAGES_JSX_INTEGRATION_NAME = 'ecopages-jsx';
+
+function isEcopagesJsxIntegration(integrationName: string): boolean {
+	return integrationName === ECOPAGES_JSX_INTEGRATION_NAME;
+}
+
+function createEcopagesJsxLazyEntryName(integrationName: string, key: string): string {
+	return `ecopages-${integrationName}-lazy-${rapidhash(key).toString(16)}`;
+}
+
+export class DependencyResolverService {
+	private appConfig: EcoPagesAppConfig;
+	private assetProcessingService: AssetProcessingService;
+
+	/**
+	 * Creates the dependency resolver used by route and component rendering.
+	 *
+	 * @remarks
+	 * The resolver stays intentionally separate from HTML rendering so component
+	 * dependency collection, lazy trigger grouping, and processed-asset generation
+	 * can evolve without changing renderer implementations.
+	 */
+	constructor(appConfig: EcoPagesAppConfig, assetProcessingService: AssetProcessingService) {
+		this.appConfig = appConfig;
+		this.assetProcessingService = assetProcessingService;
+	}
+
+	/**
+	 * Resolves one dependency path relative to the component that declared it.
+	 */
+	resolveDependencyPath(componentDir: string, pathUrl: string): string {
+		return path.join(componentDir, pathUrl);
+	}
+
+	/**
+	 * Maps lazy script source entries to deterministic fallback public URLs
+	 * used when bundling output URLs are unavailable.
+	 */
+	resolveLazyScripts(componentDir: string, scripts: string[]): string {
+		return resolveLazyScripts(this.appConfig, componentDir, scripts);
+	}
+
+	/**
+	 * Collects and processes component dependencies (styles, scripts, modules, lazy scripts).
+	 * Lazy dependencies are always resolved into global-injector trigger maps.
+	 */
+	async processComponentDependencies(
+		components: Array<EcoComponent | Partial<EcoComponent> | undefined | null>,
+		integrationName: string,
+	): Promise<ProcessedAsset[]> {
+		if (!this.assetProcessingService?.processDependencies) return [];
+		const { dependencies, lazyScriptsByConfig } = collectComponentDependencies({
+			components,
+			integrationName,
+			resolveLazyScripts: (componentDir, scripts) => this.resolveLazyScripts(componentDir, scripts),
+			createEcopagesJsxLazyEntryName,
+			isEcopagesJsxIntegration,
+			errors: {
+				invalidStylesheetEntry: DEPENDENCY_ERRORS.INVALID_STYLESHEET_ENTRY,
+				invalidScriptEntry: DEPENDENCY_ERRORS.INVALID_SCRIPT_ENTRY,
+				lazyScriptMissingSrc: DEPENDENCY_ERRORS.LAZY_SCRIPT_MISSING_SRC,
+			},
+		});
+
+		const unifiedDependencies = createUnifiedPageDependencies(dependencies, integrationName);
+		const hasLazyDependencies = unifiedDependencies.some(
+			(dep) => dep.kind === 'script' && dep.excludeFromHtml === true,
+		);
+
+		const processedDependencies = await this.assetProcessingService.processDependencies(
+			unifiedDependencies,
+			integrationName,
+		);
+		const lazyKeyToOutputUrl = new Map<string, string>();
+
+		for (const dependency of processedDependencies) {
+			if (dependency.kind === 'script' && dependency.srcUrl) {
+				const lazyKey = dependency.attributes?.['data-eco-lazy-key'];
+				if (lazyKey) {
+					lazyKeyToOutputUrl.set(lazyKey, dependency.srcUrl);
+				}
+			}
+		}
+
+		for (const [config, lazyGroupsMap] of lazyScriptsByConfig.entries()) {
+			const rawGroups: ResolvedLazyGroup[] = [];
+
+			for (const group of lazyGroupsMap.values()) {
+				const resolvedUrls = group.scripts
+					.map(({ lazyKey, fallbackUrl }) => lazyKeyToOutputUrl.get(lazyKey) ?? fallbackUrl)
+					.filter((url): url is string => Boolean(url && url.length > 0));
+
+				if (resolvedUrls.length === 0) {
+					continue;
+				}
+
+				rawGroups.push({ lazy: group.lazy, scripts: Array.from(new Set(resolvedUrls)) });
+			}
+
+			if (hasLazyDependencies) {
+				config._resolvedLazyTriggers = buildResolvedLazyTriggers(config, rawGroups);
+				config._resolvedLazyScripts = undefined;
+			}
+		}
+
+		return processedDependencies;
+	}
+}

package/src/route-renderer/page-loading/ecopages-virtual-imports.ts

@@ -0,0 +1,75 @@
+import { readFileSync } from 'node:fs';
+import { parseSync } from 'oxc-parser';
+
+export type EcopagesVirtualImport = {
+	from: string;
+	imports: string[] | undefined;
+};
+
+/**
+ * Extracts runtime `ecopages:` virtual-module imports from a component source file.
+ *
+ * Type-only imports are skipped and bare namespace imports are represented by an
+ * `undefined` import list so downstream module generation can preserve that shape.
+ */
+export function extractEcopagesVirtualImports(file: string): EcopagesVirtualImport[] {
+	let source: string;
+	try {
+		source = readFileSync(file, 'utf-8');
+	} catch {
+		return [];
+	}
+
+	let result;
+	try {
+		result = parseSync(file, source, { sourceType: 'module' });
+	} catch {
+		return [];
+	}
+
+	const found = new Map<string, Set<string> | null>();
+
+	for (const node of result.program.body ?? []) {
+		if (node.type !== 'ImportDeclaration') continue;
+		if (node.importKind === 'type') continue;
+		const specifier: string = node.source?.value ?? '';
+		if (!specifier.startsWith('ecopages:')) continue;
+
+		if (found.get(specifier) === null) {
+			continue;
+		}
+
+		const namedImports: string[] = [];
+		for (const spec of node.specifiers ?? []) {
+			if (spec.type === 'ImportSpecifier') {
+				let importedName = spec.local?.name;
+				if (spec.imported?.type === 'Identifier') {
+					importedName = spec.imported.name;
+				} else if (spec.imported?.type === 'Literal') {
+					importedName = spec.imported.value;
+				}
+				namedImports.push(importedName);
+			}
+		}
+
+		if (namedImports.length === 0) {
+			found.set(specifier, null);
+			continue;
+		}
+
+		const existing = found.get(specifier);
+		if (!existing) {
+			found.set(specifier, new Set(namedImports));
+			continue;
+		}
+
+		for (const imported of namedImports) {
+			existing.add(imported);
+		}
+	}
+
+	return Array.from(found.entries()).map(([from, importsSet]) => ({
+		from,
+		imports: importsSet ? Array.from(importsSet) : undefined,
+	}));
+}

package/src/route-renderer/page-loading/lazy-entry-collection.ts

@@ -0,0 +1,167 @@
+import type { DependencyLazyTrigger, EcoComponentScriptEntry } from '../../types/public-types.ts';
+import type { AssetDefinition } from '../../services/assets/asset-processing-service/index.ts';
+import { AssetFactory } from '../../services/assets/asset-processing-service/index.ts';
+import { rapidhash } from '../../utils/hash.ts';
+import { getLazyTriggerKey } from './lazy-trigger-planning.ts';
+
+type LazyScriptRef = {
+	lazyKey: string;
+	fallbackUrl?: string;
+};
+
+/**
+ * Lazy scripts grouped by one trigger declaration.
+ */
+export type LazyGroup = {
+	lazy: DependencyLazyTrigger;
+	scripts: LazyScriptRef[];
+};
+
+/**
+ * Callback used to record one normalized lazy-script registration.
+ */
+export type RegisterLazyScript = (input: {
+	lazy: DependencyLazyTrigger;
+	lazyKey: string;
+	fallbackUrl?: string;
+}) => void;
+
+type CollectLazyEntriesOptions = {
+	scriptEntries: Array<string | EcoComponentScriptEntry>;
+	componentFile: string;
+	componentDir: string;
+	integrationName: string;
+	dependencies: AssetDefinition[];
+	lazyDependencyKeys: Set<string>;
+	registerLazyScript: RegisterLazyScript;
+	resolveDependencyPath: (componentDir: string, pathUrl: string) => string;
+	resolveLazyScripts: (componentDir: string, scripts: string[]) => string;
+	createModuleScriptAttributes: (attributes?: Record<string, string>) => Record<string, string>;
+	createEcopagesJsxLazyEntryName: (integrationName: string, key: string) => string;
+	pushUniqueDependency: (
+		keys: Set<string>,
+		key: string,
+		dependencies: AssetDefinition[],
+		dependency: AssetDefinition,
+	) => boolean;
+	getLazyScriptMissingSrcMessage: () => string;
+	isEcopagesJsxIntegration: (integrationName: string) => boolean;
+};
+
+function isDependencyEntryObject(entry: string | EcoComponentScriptEntry): entry is EcoComponentScriptEntry {
+	return typeof entry === 'object' && entry !== null;
+}
+
+function getDependencyEntrySrcOrThrow(entry: EcoComponentScriptEntry, errorMessage: string): string {
+	if (!entry.src) {
+		throw new Error(errorMessage);
+	}
+
+	return entry.src;
+}
+
+/**
+ * Collects lazy script dependency entries and emits their hidden bundle inputs.
+ *
+ * This helper also reports the trigger-to-script relationship back to the caller so
+ * later stages can build the lazy-trigger manifest without reparsing dependency config.
+ */
+export function collectLazyScriptEntries(options: CollectLazyEntriesOptions): void {
+	const {
+		scriptEntries,
+		componentFile,
+		componentDir,
+		integrationName,
+		dependencies,
+		lazyDependencyKeys,
+		registerLazyScript,
+		resolveDependencyPath,
+		resolveLazyScripts,
+		createModuleScriptAttributes,
+		createEcopagesJsxLazyEntryName,
+		pushUniqueDependency,
+		getLazyScriptMissingSrcMessage,
+		isEcopagesJsxIntegration,
+	} = options;
+
+	for (const [index, scriptEntry] of scriptEntries.entries()) {
+		if (!isDependencyEntryObject(scriptEntry) || !scriptEntry.lazy) {
+			continue;
+		}
+
+		const lazy = scriptEntry.lazy;
+		const content = scriptEntry.content;
+		const src = scriptEntry.src;
+		const attributes = scriptEntry.attributes;
+
+		if (content) {
+			const lazyKey = `lazy:${rapidhash(`${componentFile}:entry:${index}:${content}`).toString(16)}`;
+			const depKey = `lazy:entry:content:${getLazyTriggerKey(lazy)}:${content}:${JSON.stringify(attributes ?? {})}`;
+			pushUniqueDependency(
+				lazyDependencyKeys,
+				depKey,
+				dependencies,
+				AssetFactory.createContentScript({
+					position: 'head',
+					content,
+					excludeFromHtml: true,
+					attributes: {
+						...createModuleScriptAttributes(attributes),
+						'data-eco-lazy-key': lazyKey,
+					},
+				}),
+			);
+
+			registerLazyScript({
+				lazy,
+				lazyKey,
+			});
+			continue;
+		}
+
+		const script = src ?? getDependencyEntrySrcOrThrow(scriptEntry, getLazyScriptMissingSrcMessage());
+		const resolvedPath = resolveDependencyPath(componentDir, script);
+		const fallbackUrl = resolveLazyScripts(componentDir, [script]).split(',')[0] ?? '';
+		const lazyKey = `lazy:${rapidhash(`${resolvedPath}:${getLazyTriggerKey(lazy)}`).toString(16)}`;
+		const lazyEntryName = createEcopagesJsxLazyEntryName(
+			integrationName,
+			`${resolvedPath}:${getLazyTriggerKey(lazy)}`,
+		);
+		const depKey = `lazy:entry:file:${getLazyTriggerKey(lazy)}:${resolvedPath}:${JSON.stringify(attributes ?? {})}`;
+
+		pushUniqueDependency(
+			lazyDependencyKeys,
+			depKey,
+			dependencies,
+			isEcopagesJsxIntegration(integrationName)
+				? AssetFactory.createContentScript({
+						name: lazyEntryName,
+						position: 'head',
+						content: `import ${JSON.stringify(resolvedPath)};`,
+						excludeFromHtml: true,
+						bundleOptions: {
+							splitting: false,
+						},
+						attributes: {
+							...createModuleScriptAttributes(attributes),
+							'data-eco-lazy-key': lazyKey,
+						},
+					})
+				: AssetFactory.createFileScript({
+						filepath: resolvedPath,
+						position: 'head',
+						excludeFromHtml: true,
+						attributes: {
+							...createModuleScriptAttributes(attributes),
+							'data-eco-lazy-key': lazyKey,
+						},
+					}),
+		);
+
+		registerLazyScript({
+			lazy,
+			lazyKey,
+			fallbackUrl,
+		});
+	}
+}

package/src/route-renderer/page-loading/lazy-trigger-planning.ts

@@ -0,0 +1,74 @@
+import type {
+	DependencyLazyTrigger,
+	EcoComponent,
+	LazyTriggerRule,
+	ResolvedLazyTrigger,
+} from '../../types/public-types.ts';
+import { rapidhash } from '../../utils/hash.ts';
+
+/**
+ * Lazy scripts already normalized onto one trigger and concrete script URL set.
+ */
+export type ResolvedLazyGroup = {
+	lazy: DependencyLazyTrigger;
+	scripts: string[];
+};
+
+/**
+ * Creates a stable grouping key for a lazy trigger declaration.
+ */
+export function getLazyTriggerKey(lazy: DependencyLazyTrigger): string {
+	if ('on:idle' in lazy) {
+		return 'on:idle';
+	}
+
+	if ('on:interaction' in lazy) {
+		return `on:interaction:${lazy['on:interaction']}`;
+	}
+
+	if ('on:visible' in lazy) {
+		const value = lazy['on:visible'];
+		return `on:visible:${value === true ? 'true' : value}`;
+	}
+
+	return JSON.stringify(lazy);
+}
+
+/**
+ * Derives the public lazy-trigger manifest attached to a component config.
+ *
+ * The generated `triggerId` is stable for the same component file and set of
+ * resolved script URLs, independent of declaration order.
+ */
+export function buildResolvedLazyTriggers(
+	config: NonNullable<EcoComponent['config']>,
+	groups: ResolvedLazyGroup[],
+): ResolvedLazyTrigger[] {
+	if (groups.length === 0) return [];
+
+	const componentFile = config.__eco?.file ?? '';
+	const sortedUrls = groups
+		.flatMap((group) => group.scripts)
+		.sort()
+		.join(',');
+	const triggerId = `eco-trigger-${rapidhash(`${componentFile}:${sortedUrls}`).toString(16)}`;
+
+	const rules: LazyTriggerRule[] = groups.map((group) => {
+		const { scripts, lazy } = group;
+
+		if ('on:idle' in lazy) {
+			return { 'on:idle': { scripts } };
+		}
+		if ('on:interaction' in lazy) {
+			return { 'on:interaction': { value: lazy['on:interaction'], scripts } };
+		}
+		if ('on:visible' in lazy) {
+			const visibleSelector = lazy['on:visible'];
+			if (visibleSelector === true) return { 'on:visible': { scripts } };
+			return { 'on:visible': { value: String(visibleSelector), scripts } };
+		}
+		throw new Error(`Unknown lazy trigger kind: ${JSON.stringify(lazy)}`);
+	});
+
+	return [{ triggerId, rules }];
+}

package/src/route-renderer/page-loading/module-declaration-aggregation.ts

@@ -0,0 +1,60 @@
+import { normalizeModuleDeclarations } from '../../eco/module-dependencies.ts';
+import type { EcopagesVirtualImport } from './ecopages-virtual-imports.ts';
+
+type ModuleDeclarationInput = {
+	from: string;
+	imports?: string[];
+};
+
+/**
+ * Narrows arbitrary config input onto the declared module string array shape.
+ */
+function getDeclaredModules(value: unknown): string[] | undefined {
+	if (!Array.isArray(value)) {
+		return undefined;
+	}
+
+	return value.every((entry) => typeof entry === 'string') ? value : undefined;
+}
+
+/**
+ * Merges one module declaration into the aggregated map, preserving the wildcard
+ * import semantics represented by `null`.
+ */
+function mergeModuleDeclaration(
+	modulesMap: Map<string, Set<string> | null>,
+	declaration: ModuleDeclarationInput,
+): void {
+	const existing = modulesMap.get(declaration.from);
+	if (!declaration.imports || declaration.imports.length === 0) {
+		modulesMap.set(declaration.from, null);
+		return;
+	}
+
+	if (existing === null) {
+		return;
+	}
+
+	const merged = existing ?? new Set<string>();
+	for (const imported of declaration.imports) {
+		merged.add(imported);
+	}
+	modulesMap.set(declaration.from, merged);
+}
+
+/**
+ * Combines explicit config module declarations with auto-detected `ecopages:` imports.
+ */
+export function collectModuleDeclarations(
+	modulesMap: Map<string, Set<string> | null>,
+	declaredModules: unknown,
+	autoVirtualImports: EcopagesVirtualImport[],
+): void {
+	for (const declaration of normalizeModuleDeclarations(getDeclaredModules(declaredModules))) {
+		mergeModuleDeclaration(modulesMap, declaration);
+	}
+
+	for (const declaration of autoVirtualImports) {
+		mergeModuleDeclaration(modulesMap, declaration);
+	}
+}

package/src/route-renderer/page-loading/module-declaration-scripts.ts

@@ -0,0 +1,16 @@
+import { rapidhash } from '../../utils/hash.ts';
+
+export function createModuleScriptName(from: string, imports: string[] | undefined): string {
+	const normalizedImports = imports ? [...imports].sort().join(',') : '*';
+	const hash = rapidhash(`${from}|${normalizedImports}`).toString(16);
+	return `module-${hash}`;
+}
+
+export function createNamedImportModuleSource(from: string, imports: string[]): string {
+	const namedImports = [...new Set(imports)].sort().join(', ');
+	return `export { ${namedImports} } from '${from}';`;
+}
+
+export function createNamespaceImportModuleSource(from: string): string {
+	return `export * from '${from}';`;
+}