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

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

@@ -0,0 +1,96 @@
+import type { EcoBuildPlugin } from '../../../build/build-types.ts';
+import { AssetFactory } from './asset.factory.ts';
+import type { AssetDefinition } from './assets.types.ts';
+import {
+	createBrowserRuntimeEntryModule,
+	type BrowserRuntimeEntryModuleConfig,
+} from './browser-runtime-entry.factory.ts';
+
+export const BROWSER_RUNTIME_SCRIPT_ATTRIBUTES = {
+	type: 'module',
+	defer: '',
+} as const;
+
+/**
+ * Builds the public vendor URL used for generated browser runtime assets.
+ */
+export function buildBrowserRuntimeAssetUrl(fileName: string): string {
+	return `/${AssetFactory.RESOLVED_ASSETS_VENDORS_DIR}/${fileName}`;
+}
+
+/**
+ * Declares a browser runtime script asset backed by one importable module.
+ *
+ * @remarks
+ * Runtime assets are emitted as excluded head scripts because integrations often
+ * need the bundler output and specifier registration without injecting the raw
+ * asset directly into HTML during dependency resolution.
+ */
+export function createBrowserRuntimeScriptAsset(options: {
+	importPath: string;
+	name: string;
+	fileName: string;
+	bundleOptions?: {
+		define?: Record<string, string>;
+		minify?: boolean;
+		external?: string[];
+		naming?: string;
+		plugins?: EcoBuildPlugin[];
+	};
+	attributes?: Record<string, string>;
+}): AssetDefinition {
+	return AssetFactory.createNodeModuleScript({
+		position: 'head',
+		importPath: options.importPath,
+		name: options.name,
+		packageRole: 'runtime',
+		excludeFromHtml: true,
+		bundleOptions: {
+			naming: options.fileName,
+			...options.bundleOptions,
+		},
+		attributes: {
+			...BROWSER_RUNTIME_SCRIPT_ATTRIBUTES,
+			...(options.attributes ?? {}),
+		},
+	});
+}
+
+/**
+ * Creates a browser runtime asset from a generated re-export entry module.
+ *
+ * @remarks
+ * This is the shared "module list -> generated entry file -> runtime asset"
+ * path used by integrations that need browser-side runtime bundles without
+ * owning bespoke entry-file generation logic.
+ */
+export function createBrowserRuntimeModuleAsset(options: {
+	modules: BrowserRuntimeEntryModuleConfig[];
+	name: string;
+	fileName: string;
+	cacheDirName?: string;
+	rootDir?: string;
+	bundleOptions?: {
+		define?: Record<string, string>;
+		minify?: boolean;
+		external?: string[];
+		naming?: string;
+		plugins?: EcoBuildPlugin[];
+	};
+	attributes?: Record<string, string>;
+}): AssetDefinition {
+	const importPath = createBrowserRuntimeEntryModule({
+		modules: options.modules,
+		fileName: `${options.name}-entry.mjs`,
+		rootDir: options.rootDir,
+		cacheDirName: options.cacheDirName,
+	});
+
+	return createBrowserRuntimeScriptAsset({
+		importPath,
+		name: options.name,
+		fileName: options.fileName,
+		bundleOptions: options.bundleOptions,
+		attributes: options.attributes,
+	});
+}

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

@@ -0,0 +1,67 @@
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { tmpdir } from 'node:os';
+import { test } from 'vitest';
+import { createBrowserRuntimeEntryModule } from './browser-runtime-entry.factory.ts';
+
+test('createBrowserRuntimeEntryModule writes a shared runtime entry file', () => {
+	const rootDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-browser-runtime-entry-'));
+	fs.writeFileSync(path.join(rootDir, 'package.json'), '{}', 'utf8');
+
+	try {
+		const filePath = createBrowserRuntimeEntryModule({
+			rootDir,
+			cacheDirName: 'ecopages-react-runtime-test',
+			fileName: 'runtime-entry.mjs',
+			modules: [{ specifier: 'node:path' }, { specifier: 'node:fs' }],
+		});
+
+		assert.equal(path.basename(filePath), 'runtime-entry.mjs');
+		assert.equal(
+			filePath,
+			path.join(rootDir, 'node_modules', '.cache', 'ecopages-react-runtime-test', 'runtime-entry.mjs'),
+		);
+
+		const contents = fs.readFileSync(filePath, 'utf8');
+		assert.match(contents, /export \{ .*basename.* \} from 'node:path';/);
+		assert.match(contents, /export \{ .*readFileSync.* \} from 'node:fs';/);
+	} finally {
+		fs.rmSync(rootDir, { recursive: true, force: true });
+	}
+});
+
+test('createBrowserRuntimeEntryModule preserves a default export and deduplicates named exports', () => {
+	const rootDir = fs.mkdtempSync(path.join(tmpdir(), 'eco-browser-runtime-entry-'));
+	fs.writeFileSync(path.join(rootDir, 'package.json'), '{}', 'utf8');
+	fs.mkdirSync(path.join(rootDir, 'node_modules', 'runtime-a'), { recursive: true });
+	fs.mkdirSync(path.join(rootDir, 'node_modules', 'runtime-b'), { recursive: true });
+	fs.writeFileSync(
+		path.join(rootDir, 'node_modules', 'runtime-a', 'index.js'),
+		"module.exports = { default: 'runtime-a', alpha: 'a', shared: 'shared-a' };",
+		'utf8',
+	);
+	fs.writeFileSync(
+		path.join(rootDir, 'node_modules', 'runtime-b', 'index.js'),
+		"module.exports = { beta: 'b', shared: 'shared-b' };",
+		'utf8',
+	);
+
+	try {
+		const filePath = createBrowserRuntimeEntryModule({
+			rootDir,
+			cacheDirName: 'ecopages-react-runtime-test',
+			fileName: 'runtime-entry.mjs',
+			modules: [{ specifier: 'runtime-a', defaultExport: true }, { specifier: 'runtime-b' }],
+		});
+
+		const contents = fs.readFileSync(filePath, 'utf8');
+		assert.match(contents, /import __ecopages_default_export__ from 'runtime-a';/);
+		assert.match(contents, /export default __ecopages_default_export__;/);
+		assert.match(contents, /export \{ alpha, shared \} from 'runtime-a';/);
+		assert.match(contents, /export \{ beta \} from 'runtime-b';/);
+		assert.doesNotMatch(contents, /export \{ .*shared.* \} from 'runtime-b';/);
+	} finally {
+		fs.rmSync(rootDir, { recursive: true, force: true });
+	}
+});

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

@@ -0,0 +1,78 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+export type BrowserRuntimeEntryModuleConfig = {
+	specifier: string;
+	defaultExport?: boolean;
+};
+
+/**
+ * Creates a generated ESM entry module that re-exports runtime modules through
+ * one stable file.
+ *
+ * @remarks
+ * Integrations use this helper when they need a browser runtime asset composed
+ * from multiple bare specifiers but do not want to own temporary file assembly
+ * logic themselves. The generated file lives under a cache directory inside the
+ * consuming app root so repeated runs can reuse the same location.
+ */
+export function createBrowserRuntimeEntryModule(options: {
+	modules: BrowserRuntimeEntryModuleConfig[];
+	fileName: string;
+	rootDir?: string;
+	cacheDirName?: string;
+}): string {
+	const rootDir = options.rootDir ?? process.cwd();
+	const artifactsDir = path.join(
+		rootDir,
+		'node_modules',
+		'.cache',
+		options.cacheDirName ?? 'ecopages-browser-runtime',
+	);
+	fs.mkdirSync(artifactsDir, { recursive: true });
+
+	const requireFromRoot = createRequire(path.join(rootDir, 'package.json'));
+	const seenExports = new Set<string>();
+	const statements: string[] = [];
+
+	for (const module of options.modules) {
+		if (module.defaultExport) {
+			statements.push(`import __ecopages_default_export__ from '${module.specifier}';`);
+			statements.push('export default __ecopages_default_export__;');
+		}
+
+		const exportNames = getModuleExportNames(module.specifier, requireFromRoot).filter(
+			(name) => !seenExports.has(name),
+		);
+
+		if (exportNames.length > 0) {
+			statements.push(`export { ${exportNames.join(', ')} } from '${module.specifier}';`);
+			for (const exportName of exportNames) {
+				seenExports.add(exportName);
+			}
+		}
+	}
+
+	const filePath = path.join(artifactsDir, options.fileName);
+	fs.writeFileSync(filePath, statements.join('\n'), 'utf-8');
+	return filePath;
+}
+
+/**
+ * Reads the named runtime exports that should be re-exported from a generated
+ * runtime entry module.
+ *
+ * @remarks
+ * Default exports are handled separately because generated runtime entry files
+ * need to emit a synthetic default binding only when the caller explicitly asks
+ * for it.
+ */
+function getModuleExportNames(specifier: string, requireFromRoot: ReturnType<typeof createRequire>): string[] {
+	const moduleExports = requireFromRoot(specifier);
+
+	return Object.keys(moduleExports)
+		.filter((name) => name !== '__esModule' && name !== 'default')
+		.filter((name) => /^[$A-Z_a-z][$\w]*$/.test(name))
+		.sort();
+}

package/src/services/assets/asset-processing-service/grouped-content-bundles.ts

@@ -0,0 +1,104 @@
+import type { AssetDefinition, ProcessedAsset } from './assets.types.ts';
+
+/**
+ * Splits grouped content-script dependencies from ordinary dependencies so callers can
+ * route them through `processGrouped` without changing ordering for the remaining assets.
+ */
+export function partitionGroupedContentScriptDependencies(typeDeps: AssetDefinition[]): {
+	groupedBundleDeps: Map<string, AssetDefinition[]>;
+	ungroupedDeps: AssetDefinition[];
+} {
+	const groupedBundleDeps = new Map<string, AssetDefinition[]>();
+	const ungroupedDeps: AssetDefinition[] = [];
+
+	for (const dep of typeDeps) {
+		if (dep.kind === 'script' && dep.source === 'content' && dep.groupedBundle?.id) {
+			const existing = groupedBundleDeps.get(dep.groupedBundle.id) ?? [];
+			existing.push(dep);
+			groupedBundleDeps.set(dep.groupedBundle.id, existing);
+			continue;
+		}
+
+		ungroupedDeps.push(dep);
+	}
+
+	return {
+		groupedBundleDeps,
+		ungroupedDeps,
+	};
+}
+
+type GroupedBundleProcessor = {
+	processGrouped?: (deps: AssetDefinition[]) => Promise<ProcessedAsset[]>;
+};
+
+type ProcessGroupedDependencyBundlesOptions = {
+	bundles: AssetDefinition[][];
+	key: string;
+	getCachedAsset: (dep: AssetDefinition, depKey: string) => ProcessedAsset | null;
+	getDependencyKey: (dep: AssetDefinition) => string;
+	getGroupedProcessor: () => GroupedBundleProcessor | undefined;
+	resolveProcessedAssetSrcUrl: (processed: ProcessedAsset) => string | undefined;
+	setCachedAsset: (dep: AssetDefinition, depKey: string, processed: ProcessedAsset) => void;
+	logError: (error: unknown) => void;
+};
+
+/**
+ * Processes grouped content-script bundles while preserving per-entry cache keys.
+ *
+ * When every dependency in a bundle already has a cached processed asset, the cached
+ * entries are returned directly and the grouped processor is skipped.
+ */
+export async function processGroupedDependencyBundles(
+	options: ProcessGroupedDependencyBundlesOptions,
+): Promise<ProcessedAsset[]> {
+	const {
+		bundles,
+		key,
+		getCachedAsset,
+		getDependencyKey,
+		getGroupedProcessor,
+		resolveProcessedAssetSrcUrl,
+		setCachedAsset,
+		logError,
+	} = options;
+
+	const groupedPromises = bundles.map(async (bundleDeps) => {
+		const cachedResults = bundleDeps.map((dep) => {
+			const cached = getCachedAsset(dep, getDependencyKey(dep));
+			return cached ? ({ key, ...cached } as ProcessedAsset) : null;
+		});
+
+		if (cachedResults.every((result) => result !== null)) {
+			return cachedResults.filter((result): result is ProcessedAsset => result !== null);
+		}
+
+		const processor = getGroupedProcessor();
+		if (!processor?.processGrouped) {
+			return [];
+		}
+
+		try {
+			const processedResults = await processor.processGrouped(bundleDeps);
+
+			return processedResults.map((processed, index) => {
+				const dep = bundleDeps[index]!;
+				const depKey = getDependencyKey(dep);
+				const srcUrl = resolveProcessedAssetSrcUrl(processed);
+				const processedWithKey = {
+					key,
+					...processed,
+					srcUrl,
+				};
+
+				setCachedAsset(dep, depKey, processedWithKey);
+				return processedWithKey as ProcessedAsset;
+			});
+		} catch (error) {
+			logError(error);
+			return [];
+		}
+	});
+
+	return (await Promise.all(groupedPromises)).flat();
+}

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

@@ -0,0 +1,5 @@
+export * from './asset.factory.ts';
+export * from './asset-processing.service.ts';
+export * from './assets.types.ts';
+export * from './browser-runtime-asset.factory.ts';
+export * from './browser-runtime-entry.factory.ts';

package/src/services/assets/asset-processing-service/{processor.interface.d.ts → processor.interface.ts}

@@ -1,22 +1,27 @@
-import type { IHmrManager } from '../../../types/internal-types.js';
-import type { AssetDefinition, ProcessedAsset } from './assets.types.js';
+import type { IHmrManager } from '../../../types/internal-types.ts';
+import type { AssetDefinition, ProcessedAsset } from './assets.types.ts';
+
 /**
  * Base interface for asset processors.
  * Processors transform asset definitions into processed assets.
  */
 export interface AssetProcessor<T extends AssetDefinition = AssetDefinition> {
-    process(asset: T): Promise<ProcessedAsset>;
+	process(asset: T): Promise<ProcessedAsset>;
 }
+
 /**
  * Interface for processors that support HMR (Hot Module Replacement).
  * These processors can receive an HMR manager to enable hot reloading capabilities.
  */
 export interface HmrAwareProcessor extends AssetProcessor {
-    setHmrManager(hmrManager: IHmrManager): void;
+	setHmrManager(hmrManager: IHmrManager): void;
 }
+
 /**
  * Type guard to check if a processor supports HMR.
  * @param processor - The processor to check
  * @returns True if the processor implements HmrAwareProcessor
  */
-export declare function isHmrAware(processor: AssetProcessor): processor is HmrAwareProcessor;
+export function isHmrAware(processor: AssetProcessor): processor is HmrAwareProcessor {
+	return 'setHmrManager' in processor && typeof (processor as HmrAwareProcessor).setHmrManager === 'function';
+}

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

@@ -0,0 +1,18 @@
+import type { AssetKind, AssetSource } from './assets.types.ts';
+import type { BaseProcessor } from './processors/base/base-processor.ts';
+
+export class ProcessorRegistry {
+	private processors = new Map<`${AssetKind}-${AssetSource}`, BaseProcessor<any>>();
+
+	register(kind: AssetKind, variant: AssetSource, processor: BaseProcessor<any>) {
+		this.processors.set(`${kind}-${variant}`, processor);
+	}
+
+	getProcessor(kind: AssetKind, variant: AssetSource): BaseProcessor<any> | undefined {
+		return this.processors.get(`${kind}-${variant}`);
+	}
+
+	getAllProcessors(): Map<`${AssetKind}-${AssetSource}`, BaseProcessor<any>> {
+		return this.processors;
+	}
+}

package/src/services/assets/asset-processing-service/processors/base/base-processor.test.ts

@@ -0,0 +1,59 @@
+import { afterEach, beforeEach, expect, test, vi } from 'vitest';
+import { fileSystem } from '@ecopages/file-system';
+import type { BaseAsset, ProcessedAsset } from '../../assets.types.ts';
+import { BaseProcessor } from './base-processor.ts';
+
+type TestAsset = BaseAsset & {
+	name: string;
+};
+
+class TestProcessor extends BaseProcessor<TestAsset> {
+	processCalls = 0;
+
+	async process(dep: TestAsset): Promise<ProcessedAsset> {
+		return this.getOrProcess(dep.name, async () => {
+			this.processCalls += 1;
+			return {
+				filepath: `/test/dist/assets/${dep.name}.js`,
+				kind: dep.kind,
+				inline: false,
+			};
+		});
+	}
+}
+
+const originalExists = fileSystem.exists;
+
+beforeEach(() => {
+	fileSystem.exists = vi.fn(() => true);
+});
+
+afterEach(() => {
+	fileSystem.exists = originalExists;
+	vi.restoreAllMocks();
+});
+
+test('BaseProcessor - rebuilds cached outputs when emitted file was deleted', async () => {
+	const existsMock = vi
+		.fn()
+		.mockImplementationOnce(() => false)
+		.mockImplementation(() => true);
+	fileSystem.exists = existsMock;
+
+	const processor = new TestProcessor({
+		appConfig: {
+			absolutePaths: { distDir: '/test/dist' },
+		} as any,
+	});
+
+	const asset: TestAsset = {
+		kind: 'script',
+		source: 'file',
+		name: 'runtime-vendor',
+	};
+
+	await processor.process(asset);
+	await processor.process(asset);
+
+	expect(processor.processCalls).toBe(2);
+});

package/src/services/assets/asset-processing-service/processors/base/base-processor.ts

@@ -0,0 +1,83 @@
+import path from 'node:path';
+import { RESOLVED_ASSETS_DIR } from '../../../../../config/constants.ts';
+import type { EcoPagesAppConfig } from '../../../../../types/internal-types.ts';
+import { rapidhash } from '../../../../../utils/hash.ts';
+import { isDevelopmentRuntime, isProductionRuntime } from '../../../../../utils/runtime.ts';
+import type { BaseAsset, ProcessedAsset } from '../../assets.types.ts';
+import { fileSystem } from '@ecopages/file-system';
+
+export abstract class BaseProcessor<T extends BaseAsset> {
+	protected appConfig: EcoPagesAppConfig;
+	/**
+	 * Cache for processed assets to avoid reprocessing the same asset multiple times.
+	 * The cache key is a combination of the asset name and its hash.
+	 * The cache value is the processed asset.
+	 */
+	protected cache: Map<string, ProcessedAsset> = new Map();
+
+	constructor({ appConfig }: { appConfig: EcoPagesAppConfig }) {
+		this.appConfig = appConfig;
+	}
+
+	get isDevelopment(): boolean {
+		return isDevelopmentRuntime();
+	}
+
+	get isProduction(): boolean {
+		return isProductionRuntime();
+	}
+
+	abstract process(dep: T): Promise<ProcessedAsset>;
+
+	protected getAssetsDir(): string {
+		return path.join(this.appConfig.absolutePaths.distDir, RESOLVED_ASSETS_DIR);
+	}
+
+	protected writeCacheFile(key: string, path: ProcessedAsset): void {
+		this.cache.set(key, path);
+	}
+
+	protected getCacheFile(key: string): ProcessedAsset | undefined {
+		return this.cache.get(key);
+	}
+
+	protected hasCacheFile(key: string): boolean {
+		return this.cache.has(key);
+	}
+
+	protected generateHash(content: string): string {
+		return rapidhash(content).toString();
+	}
+
+	protected buildCacheKey(identifier: string, contentHash: string, dep: T): string {
+		const attrsHash = dep.attributes ? this.generateHash(JSON.stringify(dep.attributes)) : '';
+		const position = dep.position ?? '';
+		const packageRole = dep.packageRole ?? '';
+		return `${identifier}:${contentHash}:${position}:${attrsHash}:${packageRole}`;
+	}
+
+	protected getOrProcess(
+		cacheKey: string,
+		processFn: () => ProcessedAsset | Promise<ProcessedAsset>,
+	): Promise<ProcessedAsset> {
+		if (this.hasCacheFile(cacheKey)) {
+			const cached = this.getCacheFile(cacheKey) as ProcessedAsset;
+			if (!cached.filepath || fileSystem.exists(cached.filepath)) {
+				return Promise.resolve(cached);
+			}
+
+			this.cache.delete(cacheKey);
+		}
+
+		const result = processFn();
+		if (result instanceof Promise) {
+			return result.then((asset) => {
+				this.writeCacheFile(cacheKey, asset);
+				return asset;
+			});
+		}
+
+		this.writeCacheFile(cacheKey, result);
+		return Promise.resolve(result);
+	}
+}