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

package/src/services/assets/asset-processing-service/asset-processing.service.ts

@@ -0,0 +1,345 @@
+import path from 'node:path';
+import { RESOLVED_ASSETS_DIR } from '../../../config/constants.ts';
+import { appLogger } from '../../../global/app-logger.ts';
+import type { EcoPagesAppConfig, IHmrManager } from '../../../types/internal-types.ts';
+import { fileSystem } from '@ecopages/file-system';
+import type { AssetDefinition, AssetKind, AssetSource, ProcessedAsset } from './assets.types.ts';
+import { deduplicateAssetDependencies, getAssetDependencyKey } from './asset-dependency-keys.ts';
+import {
+	partitionGroupedContentScriptDependencies,
+	processGroupedDependencyBundles,
+} from './grouped-content-bundles.ts';
+import { isHmrAware } from './processor.interface.ts';
+import { ProcessorRegistry } from './processor.registry.ts';
+import { processUngroupedDependency } from './ungrouped-dependency-processing.ts';
+import {
+	ContentScriptProcessor,
+	ContentStylesheetProcessor,
+	FileScriptProcessor,
+	FileStylesheetProcessor,
+	NodeModuleScriptProcessor,
+} from './processors/index.ts';
+
+/**
+ * Processes declared component and page asset dependencies for one app instance.
+ *
+ * @remarks
+ * This service is the shared bridge between dependency declarations and emitted
+ * runtime-ready assets. It owns deduplication, processor dispatch, cache reuse,
+ * output URL normalization, and production gzip preparation so route rendering
+ * and HMR flows do not need to understand processor-specific behavior.
+ */
+export class AssetProcessingService {
+	static readonly RESOLVED_ASSETS_DIR = RESOLVED_ASSETS_DIR;
+	private registry = new ProcessorRegistry();
+	private hmrManager?: IHmrManager;
+	private cache = new Map<string, { asset: ProcessedAsset }>();
+	private readonly config: EcoPagesAppConfig;
+
+	/**
+	 * Creates the asset-processing service bound to one finalized app config.
+	 */
+	constructor(config: EcoPagesAppConfig) {
+		this.config = config;
+	}
+
+	/**
+	 * Set the HMR manager for the asset processing service.
+	 * @param hmrManager The HMR manager to set.
+	 */
+	setHmrManager(hmrManager: IHmrManager) {
+		this.hmrManager = hmrManager;
+
+		for (const processor of this.registry.getAllProcessors().values()) {
+			if (isHmrAware(processor)) {
+				processor.setHmrManager(hmrManager);
+			}
+		}
+	}
+
+	getHmrManager(): IHmrManager | undefined {
+		return this.hmrManager;
+	}
+
+	/**
+	 * Register a processor for a specific asset kind and source.
+	 * @param kind The asset kind.
+	 * @param variant The asset source.
+	 * @param processor The processor to register.
+	 */
+	registerProcessor(kind: AssetKind, variant: AssetSource, processor: any): void {
+		if (this.hmrManager && isHmrAware(processor)) {
+			processor.setHmrManager(this.hmrManager);
+		}
+		this.registry.register(kind, variant, processor);
+	}
+
+	/**
+	 * Processes one dependency list into normalized emitted assets.
+	 *
+	 * @remarks
+	 * Dependencies are deduplicated before processor execution so repeated
+	 * declarations across the render tree reuse the same emitted outputs and cache
+	 * entries.
+	 */
+	async processDependencies(deps: AssetDefinition[], key: string): Promise<ProcessedAsset[]> {
+		const depsDir = path.join(this.config.absolutePaths.distDir, RESOLVED_ASSETS_DIR);
+		fileSystem.ensureDir(depsDir);
+
+		const dedupedDeps = deduplicateAssetDependencies(deps);
+		const results = await this.processDependenciesParallel(dedupedDeps, key);
+
+		await this.optimizeDependencies(results);
+		return results;
+	}
+
+	/**
+	 * Processes deduplicated dependencies grouped by processor type.
+	 *
+	 * @remarks
+	 * Grouping keeps cache and processor behavior isolated by asset kind/source
+	 * pair, while still allowing the overall dependency set to resolve in
+	 * parallel.
+	 */
+	private async processDependenciesParallel(deps: AssetDefinition[], key: string): Promise<ProcessedAsset[]> {
+		const grouped = this.groupDependenciesByType(deps);
+		const groupPromises = Object.entries(grouped).map(async ([, typeDeps]) => {
+			const { groupedBundleDeps, ungroupedDeps } = partitionGroupedContentScriptDependencies(typeDeps);
+
+			const typePromises = ungroupedDeps.map((dep) =>
+				processUngroupedDependency({
+					dep,
+					key,
+					depKey: getAssetDependencyKey(dep),
+					getCachedAsset: (assetDep, depKey) => this.getCachedAsset(assetDep, depKey),
+					getProcessor: (assetDep) => this.registry.getProcessor(assetDep.kind, assetDep.source),
+					resolveProcessedAssetSrcUrl: (processed) => this.resolveProcessedAssetSrcUrl(processed),
+					setCachedAsset: (assetDep, depKey, processed) =>
+						this.setCachedAsset(assetDep, depKey, processed),
+					logMissingProcessor: (assetDep) => {
+						appLogger.error(`No processor found for ${assetDep.kind}/${assetDep.source}`);
+					},
+					logMissingFile: (assetDep) => {
+						appLogger.warn(`Skipping missing ${assetDep.kind} file: ${assetDep.filepath}`);
+					},
+					logProcessingError: (assetDep, error) => {
+						appLogger.error(
+							`Failed to process dependency: ${
+								error instanceof Error ? error.message : String(error)
+							} for ${assetDep.kind}/${assetDep.source}`,
+						);
+						appLogger.debug(error as Error);
+					},
+				}),
+			);
+
+			const groupedResults = await processGroupedDependencyBundles({
+				bundles: Array.from(groupedBundleDeps.values()),
+				key,
+				getCachedAsset: (dep, depKey) => this.getCachedAsset(dep, depKey),
+				getDependencyKey: getAssetDependencyKey,
+				getGroupedProcessor: () =>
+					this.registry.getProcessor('script', 'content') as {
+						processGrouped?: (deps: AssetDefinition[]) => Promise<ProcessedAsset[]>;
+					},
+				resolveProcessedAssetSrcUrl: (processed) => this.resolveProcessedAssetSrcUrl(processed),
+				setCachedAsset: (dep, depKey, processed) => this.setCachedAsset(dep, depKey, processed),
+				logError: (error) => {
+					appLogger.error(
+						`Failed to process grouped dependency bundle: ${
+							error instanceof Error ? error.message : String(error)
+						}`,
+					);
+					appLogger.debug(error as Error);
+				},
+			});
+
+			const typeResults = await Promise.all(typePromises);
+			const processedTypeResults = typeResults.flatMap((result) => {
+				if (!result) {
+					return [];
+				}
+
+				return Array.isArray(result) ? result : [result];
+			});
+
+			return [...processedTypeResults, ...groupedResults];
+		});
+
+		const allTypeResults = await Promise.all(groupPromises);
+		return allTypeResults.flat();
+	}
+
+	/**
+	 * Groups dependencies by processor bucket.
+	 */
+	private groupDependenciesByType(deps: AssetDefinition[]): Record<string, AssetDefinition[]> {
+		return deps.reduce(
+			(acc, dep) => {
+				const key = `${dep.kind}_${dep.source}`;
+				if (!acc[key]) acc[key] = [];
+				acc[key].push(dep);
+				return acc;
+			},
+			{} as Record<string, AssetDefinition[]>,
+		);
+	}
+
+	/**
+	 * Converts a dist-local file path into its public URL.
+	 */
+	private getSrcUrl(filepath: string): string | undefined {
+		const distDir = this.config.absolutePaths.distDir;
+		if (!filepath.startsWith(distDir)) return undefined;
+
+		const relativePath = filepath.slice(distDir.length);
+		const urlPath = relativePath.startsWith('/') ? relativePath : `/${relativePath}`;
+		return urlPath.replace(/\\/g, '/');
+	}
+
+	/**
+	 * Normalizes the public source URL for one processed asset.
+	 */
+	private resolveProcessedAssetSrcUrl(processed: ProcessedAsset): string | undefined {
+		if (processed.srcUrl) {
+			if (this.isFilesystemPath(processed.srcUrl)) {
+				const srcUrlFromPath = this.getSrcUrl(processed.srcUrl);
+				if (srcUrlFromPath) return srcUrlFromPath;
+			} else {
+				return processed.srcUrl;
+			}
+		}
+
+		if (processed.filepath) {
+			return this.getSrcUrl(processed.filepath);
+		}
+
+		return undefined;
+	}
+
+	/**
+	 * Returns whether a value should be interpreted as a filesystem path instead
+	 * of an already-public URL.
+	 */
+	private isFilesystemPath(value: string): boolean {
+		if (value.startsWith('http://') || value.startsWith('https://') || value.startsWith('//')) {
+			return false;
+		}
+
+		if (value.startsWith(this.config.absolutePaths.distDir)) {
+			return true;
+		}
+
+		const rootDir = this.config.rootDir;
+		if (rootDir && value.startsWith(rootDir)) {
+			return true;
+		}
+
+		return /^[A-Za-z]:\\/.test(value);
+	}
+
+	/**
+	 * Applies post-processing for emitted production assets.
+	 *
+	 * @remarks
+	 * Current optimization is intentionally conservative: only generated CSS and
+	 * JavaScript files inside the app dist directory are gzipped.
+	 */
+	private async optimizeDependencies(processedAssets: ProcessedAsset[]): Promise<void> {
+		if (process.env.NODE_ENV !== 'production') {
+			return;
+		}
+
+		const filesToGzip = new Set<string>();
+
+		for (const asset of processedAssets) {
+			if (!asset.filepath) {
+				continue;
+			}
+
+			if (!asset.filepath.startsWith(this.config.absolutePaths.distDir)) {
+				continue;
+			}
+
+			const extension = path.extname(asset.filepath).slice(1);
+			if (extension === 'css' || extension === 'js') {
+				filesToGzip.add(asset.filepath);
+			}
+		}
+
+		for (const filePath of filesToGzip) {
+			if (fileSystem.exists(filePath)) {
+				fileSystem.gzipFile(filePath);
+			}
+		}
+	}
+
+	/**
+	 * Returns the cached processed asset for a dependency key when available.
+	 */
+	private getCachedAsset(dep: AssetDefinition, depKey: string): ProcessedAsset | null {
+		if (process.env.NODE_ENV !== 'production' && dep.source === 'file' && dep.kind === 'stylesheet') {
+			return null;
+		}
+
+		const cached = this.cache.get(depKey);
+		if (!cached) {
+			return null;
+		}
+
+		if (cached.asset.filepath && !fileSystem.exists(cached.asset.filepath)) {
+			this.cache.delete(depKey);
+			return null;
+		}
+
+		return cached.asset;
+	}
+
+	/**
+	 * Stores one processed asset in the dependency cache.
+	 */
+	private setCachedAsset(dep: AssetDefinition, depKey: string, asset: ProcessedAsset): void {
+		this.cache.set(depKey, { asset });
+	}
+
+	/**
+	 * Clears all cached processed assets.
+	 */
+	clearCache(): void {
+		this.cache.clear();
+	}
+
+	/**
+	 * Removes cached assets that were produced from the given file path.
+	 */
+	invalidateCacheForFile(filepath: string): void {
+		for (const [key, value] of this.cache.entries()) {
+			if (value.asset.filepath === filepath) {
+				this.cache.delete(key);
+			}
+		}
+	}
+
+	/**
+	 * Creates a service prewired with the default core processors.
+	 */
+	static createWithDefaultProcessors(appConfig: EcoPagesAppConfig): AssetProcessingService {
+		const service = new AssetProcessingService(appConfig);
+
+		service.registerProcessor('script', 'content', new ContentScriptProcessor({ appConfig }));
+		service.registerProcessor('script', 'file', new FileScriptProcessor({ appConfig }));
+		service.registerProcessor('script', 'node-module', new NodeModuleScriptProcessor({ appConfig }));
+
+		service.registerProcessor('stylesheet', 'content', new ContentStylesheetProcessor({ appConfig }));
+		service.registerProcessor('stylesheet', 'file', new FileStylesheetProcessor({ appConfig }));
+
+		return service;
+	}
+
+	/**
+	 * Returns the processor registry owned by this service.
+	 */
+	getRegistry(): ProcessorRegistry {
+		return this.registry;
+	}
+}

package/src/services/assets/asset-processing-service/asset.factory.test.ts

@@ -0,0 +1,63 @@
+import { expect, test } from 'vitest';
+import { AssetFactory } from './asset.factory';
+
+test('AssetFactory - createInlineScriptAsset', () => {
+	const asset = AssetFactory.createInlineContentScript({
+		content: 'console.log("test")',
+	});
+	expect(asset.kind).toBe('script');
+	expect(asset.source).toBe('content');
+	expect(asset.inline).toBe(true);
+	expect(asset.position).toBe('body');
+});
+
+test('AssetFactory - createSrcScriptAsset', () => {
+	const asset = AssetFactory.createFileScript({
+		filepath: 'https://test.com/script.js',
+	});
+	expect(asset.kind).toBe('script');
+	expect(asset.source).toBe('file');
+});
+
+test('AssetFactory - createJsonAssetScript', () => {
+	const asset = AssetFactory.createJsonScript({
+		content: '{"test": true}',
+	});
+	expect(asset.kind).toBe('script');
+	expect(asset.source).toBe('content');
+	expect(asset.attributes?.type).toBe('application/json');
+});
+
+test('AssetFactory - createInlineStylesheetAsset', () => {
+	const asset = AssetFactory.createInlineContentStylesheet({
+		content: 'body { color: red; }',
+	});
+	expect(asset.kind).toBe('stylesheet');
+	expect(asset.source).toBe('content');
+	expect(asset.position).toBe('head');
+});
+
+test('AssetFactory - createContentScript', () => {
+	const asset = AssetFactory.createContentScript({
+		content: 'console.log("test")',
+	});
+	expect(asset.kind).toBe('script');
+	expect(asset.source).toBe('content');
+	expect(asset.position).toBe('body');
+});
+
+test('AssetFactory - createInlineContentScript', () => {
+	const asset = AssetFactory.createInlineContentScript({
+		content: 'console.log("test")',
+	});
+	expect(asset.inline).toBe(true);
+	expect(asset.source).toBe('content');
+});
+
+test('AssetFactory - createFileScript', () => {
+	const asset = AssetFactory.createFileScript({
+		filepath: '/path/to/script.js',
+	});
+	expect(asset.kind).toBe('script');
+	expect(asset.source).toBe('file');
+});

package/src/services/assets/asset-processing-service/asset.factory.ts

@@ -0,0 +1,105 @@
+import { RESOLVED_ASSETS_DIR, RESOLVED_ASSETS_VENDORS_DIR } from '../../../config/constants.ts';
+import { deepMerge } from '../../../utils/deep-merge.ts';
+import type {
+	ContentScriptAsset,
+	ContentStylesheetAsset,
+	FileScriptAsset,
+	FileStylesheetAsset,
+	InlineContentScriptAsset,
+	InlineContentStylesheetAsset,
+	InlineFileScriptAsset,
+	JsonScriptAsset,
+	NodeModuleScriptAsset,
+} from './assets.types.ts';
+
+type CreateAssetOptions<T> = Omit<T, 'kind' | 'source' | 'inline'>;
+
+export class AssetFactory {
+	static readonly RESOLVED_ASSETS_DIR = RESOLVED_ASSETS_DIR;
+	static readonly RESOLVED_ASSETS_VENDORS_DIR = RESOLVED_ASSETS_VENDORS_DIR;
+
+	static createContentScript(options: CreateAssetOptions<ContentScriptAsset>): ContentScriptAsset {
+		return {
+			kind: 'script',
+			source: 'content',
+			position: options.position || 'body',
+			...options,
+		};
+	}
+
+	static createInlineContentScript(options: CreateAssetOptions<InlineContentScriptAsset>): InlineContentScriptAsset {
+		return {
+			...AssetFactory.createContentScript(options),
+			inline: true,
+		};
+	}
+
+	static createFileScript(options: CreateAssetOptions<FileScriptAsset>): FileScriptAsset {
+		return {
+			kind: 'script',
+			source: 'file',
+			position: options.position || 'body',
+			...options,
+		};
+	}
+
+	static createInlineFileScript(options: CreateAssetOptions<InlineFileScriptAsset>): InlineFileScriptAsset {
+		return {
+			...AssetFactory.createFileScript(options),
+			inline: true,
+		};
+	}
+
+	static createNodeModuleScript(options: CreateAssetOptions<NodeModuleScriptAsset>): NodeModuleScriptAsset {
+		return {
+			kind: 'script',
+			source: 'node-module',
+			position: options.position || 'body',
+			...options,
+		};
+	}
+
+	static createInlineNodeModuleScript(options: CreateAssetOptions<NodeModuleScriptAsset>): NodeModuleScriptAsset {
+		return {
+			...AssetFactory.createNodeModuleScript(options),
+			inline: true,
+		};
+	}
+
+	static createJsonScript(options: CreateAssetOptions<JsonScriptAsset>): JsonScriptAsset {
+		return {
+			kind: 'script',
+			source: 'content',
+			attributes: deepMerge(options.attributes, { type: 'application/json' }),
+			position: options.position || 'body',
+			...options,
+		};
+	}
+
+	static createContentStylesheet(options: CreateAssetOptions<ContentStylesheetAsset>): ContentStylesheetAsset {
+		return {
+			kind: 'stylesheet',
+			source: 'content',
+			position: 'head',
+			...options,
+		};
+	}
+
+	static createInlineContentStylesheet(
+		options: CreateAssetOptions<InlineContentStylesheetAsset>,
+	): InlineContentStylesheetAsset {
+		return {
+			...AssetFactory.createContentStylesheet(options),
+			inline: true,
+		};
+	}
+
+	static createFileStylesheet(options: CreateAssetOptions<FileStylesheetAsset>): FileStylesheetAsset {
+		return {
+			kind: 'stylesheet',
+			source: 'file',
+			position: options.position || 'head',
+			...options,
+		};
+	}
+}

package/src/services/assets/asset-processing-service/assets.types.ts

@@ -0,0 +1,125 @@
+import type { EcoBuildPlugin } from '../../../build/build-types.ts';
+
+export type AssetSource = 'content' | 'file' | 'node-module';
+export type AssetKind = 'script' | 'stylesheet';
+export type AssetPosition = 'head' | 'body';
+export type AssetPackageRole = 'page-script' | 'page-style' | 'runtime' | 'keep-separate' | 'dynamic-chunk';
+
+export type GroupedScriptBundle = {
+	id: string;
+	entryName: string;
+};
+
+export interface BaseAsset {
+	kind: AssetKind;
+	source: AssetSource;
+	attributes?: Record<string, string>;
+	position?: AssetPosition;
+	packageRole?: AssetPackageRole;
+}
+
+export interface ScriptAsset extends BaseAsset {
+	kind: 'script';
+	inline?: boolean;
+	bundle?: boolean;
+	groupedBundle?: GroupedScriptBundle;
+	bundleOptions?: {
+		define?: Record<string, string>;
+		minify?: boolean;
+		external?: string[];
+		splitting?: boolean;
+		excludeAppBuildPlugins?: string[];
+		naming?: string;
+		plugins?: EcoBuildPlugin[];
+	};
+	/**
+	 * Whether to exclude this asset from the HTML output.
+	 * @default false
+	 */
+	excludeFromHtml?: boolean;
+}
+
+export interface StylesheetAsset extends BaseAsset {
+	kind: 'stylesheet';
+	inline?: boolean;
+}
+
+export interface ContentScriptAsset extends ScriptAsset {
+	source: 'content';
+	content: string;
+	name?: string;
+}
+
+export interface InlineContentScriptAsset extends ContentScriptAsset {
+	inline: true;
+}
+
+export interface ContentStylesheetAsset extends StylesheetAsset {
+	source: 'content';
+	content: string;
+}
+
+export interface InlineContentStylesheetAsset extends ContentStylesheetAsset {
+	inline: true;
+}
+
+export interface FileScriptAsset extends ScriptAsset {
+	source: 'file';
+	filepath: string;
+	name?: string;
+}
+
+export interface InlineFileScriptAsset extends FileScriptAsset {
+	inline: true;
+}
+
+export interface FileStylesheetAsset extends StylesheetAsset {
+	source: 'file';
+	filepath: string;
+	name?: string;
+}
+
+export interface InlineFileStylesheetAsset extends FileStylesheetAsset {
+	inline: true;
+}
+
+export interface NodeModuleScriptAsset extends ScriptAsset {
+	kind: 'script';
+	source: 'node-module';
+	importPath: string;
+	name?: string;
+}
+
+export interface InlineNodeModuleScriptAsset extends NodeModuleScriptAsset {
+	inline: true;
+}
+
+export interface InlineNodeModuleScriptAsset extends NodeModuleScriptAsset {
+	inline: true;
+}
+
+export interface JsonScriptAsset extends ScriptAsset {
+	source: 'content';
+	content: string;
+}
+
+export type ProcessedAsset = {
+	filepath?: string;
+	srcUrl?: string;
+	content?: string;
+	kind: AssetKind;
+	position?: AssetPosition;
+	attributes?: Record<string, string>;
+	inline?: boolean;
+	excludeFromHtml?: boolean;
+	packageRole?: AssetPackageRole;
+	groupedBundle?: GroupedScriptBundle;
+};
+
+export type AssetDefinition =
+	| ContentScriptAsset
+	| FileScriptAsset
+	| NodeModuleScriptAsset
+	| JsonScriptAsset
+	| ContentStylesheetAsset
+	| FileStylesheetAsset;

package/src/services/assets/asset-processing-service/browser-runtime-asset.factory.test.ts

@@ -0,0 +1,74 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { test } from 'vitest';
+import {
+	BROWSER_RUNTIME_SCRIPT_ATTRIBUTES,
+	buildBrowserRuntimeAssetUrl,
+	createBrowserRuntimeModuleAsset,
+	createBrowserRuntimeScriptAsset,
+} from './browser-runtime-asset.factory.ts';
+
+test('buildBrowserRuntimeAssetUrl uses the vendors asset directory', () => {
+	assert.equal(buildBrowserRuntimeAssetUrl('react.js'), '/assets/vendors/react.js');
+});
+
+test('createBrowserRuntimeScriptAsset creates a hidden head runtime bundle asset', () => {
+	const plugin = { name: 'runtime-plugin', setup() {} };
+	const asset = createBrowserRuntimeScriptAsset({
+		importPath: '/tmp/react-entry.mjs',
+		name: 'react',
+		fileName: 'react.js',
+		bundleOptions: {
+			plugins: [plugin],
+		},
+	});
+
+	assert.deepEqual(asset, {
+		kind: 'script',
+		source: 'node-module',
+		position: 'head',
+		importPath: '/tmp/react-entry.mjs',
+		name: 'react',
+		packageRole: 'runtime',
+		excludeFromHtml: true,
+		bundleOptions: {
+			naming: 'react.js',
+			plugins: [plugin],
+		},
+		attributes: BROWSER_RUNTIME_SCRIPT_ATTRIBUTES,
+	});
+});
+
+test('createBrowserRuntimeModuleAsset creates an entry module and hidden runtime asset together', () => {
+	const rootDir = fs.mkdtempSync(path.join(os.tmpdir(), 'eco-browser-runtime-asset-'));
+	fs.writeFileSync(path.join(rootDir, 'package.json'), '{}', 'utf8');
+	fs.mkdirSync(path.join(rootDir, 'node_modules', 'runtime-a'), { recursive: true });
+	fs.writeFileSync(
+		path.join(rootDir, 'node_modules', 'runtime-a', 'index.js'),
+		"module.exports = { default: 'runtime-a', alpha: 'a' };",
+		'utf8',
+	);
+
+	try {
+		const asset = createBrowserRuntimeModuleAsset({
+			rootDir,
+			cacheDirName: 'ecopages-browser-runtime-test',
+			modules: [{ specifier: 'runtime-a', defaultExport: true }],
+			name: 'runtime-a',
+			fileName: 'runtime-a.js',
+		});
+
+		assert.equal(asset.source, 'node-module');
+		assert.equal(
+			asset.importPath.endsWith(path.join('ecopages-browser-runtime-test', 'runtime-a-entry.mjs')),
+			true,
+		);
+		assert.equal(asset.bundleOptions?.naming, 'runtime-a.js');
+		assert.equal(asset.excludeFromHtml, true);
+		assert.equal(asset.packageRole, 'runtime');
+	} finally {
+		fs.rmSync(rootDir, { recursive: true, force: true });
+	}
+});