@ecopages/core 0.2.0-alpha.52 → 0.2.0-alpha.54

package/src/hmr/strategies/js-hmr-strategy.ts

@@ -0,0 +1,307 @@
+/**
+ * JavaScript HMR Strategy
+ *
+ * Handles hot module replacement for JavaScript and TypeScript entrypoints.
+ * Bundles files, inspects the emitted output, and decides whether the browser
+ * can hot-accept the change or must reload.
+ *
+ * @module
+ */
+
+import path from 'node:path';
+import { fileSystem } from '@ecopages/file-system';
+import { HmrStrategy, HmrStrategyType, type HmrAction } from '../hmr-strategy.ts';
+import { appLogger } from '../../global/app-logger.ts';
+import type { EcoBuildPlugin } from '../../build/build-types.ts';
+import type { BrowserBundleExecutor } from '../../services/assets/browser-bundle.service.ts';
+import type { EntrypointDependencyGraph } from '../../services/runtime-state/entrypoint-dependency-graph.service.ts';
+
+/**
+ * Context interface providing access to HmrManager state.
+ * Required for JsHmrStrategy to access registered entrypoints and configuration.
+ */
+export interface JsHmrContext {
+	/**
+	 * Map of registered entrypoints to their output URLs.
+	 */
+	getWatchedFiles(): Map<string, string>;
+
+	getEntrypointDependencyGraph(): EntrypointDependencyGraph;
+
+	/**
+	 * Directory where HMR bundles are written.
+	 */
+	getDistDir(): string;
+
+	/**
+	 * Build plugins to use during bundling.
+	 */
+	getPlugins(): EcoBuildPlugin[];
+
+	/**
+	 * Absolute path to the source directory.
+	 */
+	getSrcDir(): string;
+
+	/**
+	 * Absolute path to the pages directory.
+	 */
+	getPagesDir(): string;
+
+	/**
+	 * Absolute path to the layouts directory.
+	 */
+	getLayoutsDir(): string;
+
+	/**
+	 * All configured route-template extensions across integrations.
+	 */
+	getTemplateExtensions(): string[];
+
+	/**
+	 * Browser bundler used to rebuild changed entrypoints.
+	 */
+	getBrowserBundleService(): BrowserBundleExecutor;
+
+	/**
+	 * Returns whether a watched entrypoint should be rebuilt by the generic JS strategy.
+	 *
+	 * @remarks
+	 * Integrations with higher-priority HMR strategies can use this to keep the
+	 * generic JS strategy from overwriting their emitted entrypoints when a shared
+	 * dependency changes.
+	 */
+	shouldProcessEntrypoint?(entrypointPath: string): boolean;
+}
+
+/**
+ * Strategy for handling JavaScript/TypeScript file changes with hot reloading.
+ *
+ * The processing steps are:
+ * 1. Check if any entrypoints are registered
+ * 2. Rebuild impacted entrypoints, or all watched entrypoints when no runtime
+ *    dependency graph is available
+ * 3. Emit rebuilt entrypoint bundles for browser delivery
+ * 4. Inject generic HMR boilerplate
+ * 5. Broadcast update events for each rebuilt entrypoint
+ *
+ * @remarks
+ * Node can provide dependency-graph metadata, so this strategy can rebuild only
+ * the entrypoints impacted by a changed dependency. Runtimes that do not expose
+ * that metadata intentionally keep the rebuild-all fallback.
+ *
+ * @see https://bun.sh/docs/runtime/transpiler
+ *
+ * @example
+ * ```typescript
+ * const context = {
+ *   getWatchedFiles: () => watchedFilesMap,
+ *   getDistDir: () => '/path/to/dist/_hmr',
+ *   getPlugins: () => [],
+ *   getSrcDir: () => '/path/to/src'
+ * };
+ * const strategy = new JsHmrStrategy(context);
+ * ```
+ */
+export class JsHmrStrategy extends HmrStrategy {
+	readonly type = HmrStrategyType.SCRIPT;
+	private context: JsHmrContext;
+
+	constructor(context: JsHmrContext) {
+		super();
+		this.context = context;
+	}
+
+	/**
+	 * Determines if the file is a JS/TS file that could affect registered entrypoints.
+	 *
+	 * Matches if:
+	 * 1. There are registered entrypoints to rebuild
+	 * 2. The changed file is a JS/TS file in the src directory
+	 *
+	 * @param filePath - Absolute path to the changed file
+	 * @returns True if this file should trigger entrypoint rebuilds
+	 */
+	matches(filePath: string): boolean {
+		const watchedFiles = this.context.getWatchedFiles();
+		const isJsTs = /\.(ts|tsx|js|jsx)$/.test(filePath);
+		const isInSrc = filePath.startsWith(this.context.getSrcDir());
+		const isIntegrationTemplate = this.context
+			.getTemplateExtensions()
+			.some((extension) => filePath.endsWith(extension));
+
+		if (watchedFiles.size === 0) {
+			return false;
+		}
+
+		if (!isJsTs || !isInSrc) {
+			return false;
+		}
+
+		if (isIntegrationTemplate) {
+			return false;
+		}
+
+		if (watchedFiles.has(filePath)) {
+			return true;
+		}
+
+		return true;
+	}
+
+	/**
+	 * Processes a file change by rebuilding affected entrypoints.
+	 *
+	 * @param filePath - Absolute path to the changed file
+	 *
+	 * @remarks
+	 * If runtime-specific dependency graph hooks are unavailable, this strategy
+	 * falls back to rebuilding all watched entrypoints.
+	 * When multiple entrypoints are impacted they are bundled in a single
+	 * invocation to share AST parsing and chunk deduplication.
+	 * @returns Action to broadcast update events
+	 */
+	async process(filePath: string): Promise<HmrAction> {
+		appLogger.debug(`[JsHmrStrategy] Processing ${filePath}`);
+		const watchedFiles = this.context.getWatchedFiles();
+
+		if (watchedFiles.size === 0) {
+			appLogger.debug(`[JsHmrStrategy] No watched files to rebuild`);
+			return { type: 'none' };
+		}
+
+		const dependencyHits = this.context.getEntrypointDependencyGraph().getDependencyEntrypoints(filePath);
+		const hasDependencyHit = dependencyHits.size > 0;
+		const impactedEntrypoints = hasDependencyHit
+			? Array.from(dependencyHits).filter((entrypoint) => watchedFiles.has(entrypoint))
+			: Array.from(watchedFiles.keys());
+		const buildableEntrypoints = impactedEntrypoints.filter(
+			(entrypoint) => this.context.shouldProcessEntrypoint?.(entrypoint) ?? true,
+		);
+
+		if (!hasDependencyHit) {
+			appLogger.debug('[JsHmrStrategy] Dependency graph miss, rebuilding all watched entrypoints');
+		}
+
+		if (buildableEntrypoints.length === 0) {
+			return { type: 'none' };
+		}
+
+		const buildResult = await this.bundleEntrypoints(buildableEntrypoints);
+
+		if (!buildResult.success) {
+			return { type: 'none' };
+		}
+
+		const updates: string[] = [];
+		let reloadRequired = false;
+
+		for (const entrypoint of buildableEntrypoints) {
+			const outputUrl = watchedFiles.get(entrypoint);
+			if (!outputUrl) continue;
+
+			if (buildResult.dependencies) {
+				const entrypointDeps = buildResult.dependencies.get(path.resolve(entrypoint)) ?? [];
+				this.context.getEntrypointDependencyGraph().setEntrypointDependencies(entrypoint, entrypointDeps);
+			}
+
+			const srcDir = this.context.getSrcDir();
+			const relativePath = path.relative(srcDir, entrypoint);
+			const relativePathJs = relativePath.replace(/\.(tsx?|jsx?|mdx?)$/, '.js');
+			const outputPath = path.join(this.context.getDistDir(), relativePathJs);
+
+			const result = await this.processOutput(outputPath, outputUrl);
+			if (result.success) {
+				updates.push(outputUrl);
+				if (result.requiresReload) {
+					reloadRequired = true;
+				}
+			}
+		}
+
+		if (updates.length > 0) {
+			if (reloadRequired) {
+				appLogger.debug(`[JsHmrStrategy] Full reload required (no HMR accept found)`);
+				return {
+					type: 'broadcast',
+					events: [{ type: 'reload' }],
+				};
+			}
+
+			return {
+				type: 'broadcast',
+				events: updates.map((p) => ({
+					type: 'update',
+					path: p,
+					timestamp: Date.now(),
+				})),
+			};
+		}
+
+		return { type: 'none' };
+	}
+
+	/**
+	 * Bundles one or more entrypoints in a single build invocation.
+	 * Uses the source directory as the output base so that the directory structure
+	 * is preserved under the HMR dist folder.
+	 */
+	private async bundleEntrypoints(
+		entrypoints: string[],
+	): Promise<{ success: boolean; dependencies?: Map<string, string[]> }> {
+		try {
+			const result = await this.context.getBrowserBundleService().bundle({
+				profile: 'hmr-entrypoint',
+				entrypoints,
+				outdir: this.context.getDistDir(),
+				outbase: this.context.getSrcDir(),
+				naming: '[dir]/[name]',
+				plugins: this.context.getPlugins(),
+				minify: false,
+			});
+
+			if (!result.success) {
+				appLogger.error('[JsHmrStrategy] Batched build failed:', result.logs);
+				return { success: false };
+			}
+
+			const dependencies = new Map<string, string[]>();
+			if (result.dependencyGraph?.entrypoints) {
+				for (const [entrypoint, deps] of Object.entries(result.dependencyGraph.entrypoints)) {
+					dependencies.set(path.resolve(entrypoint), deps);
+				}
+			}
+
+			return { success: true, dependencies };
+		} catch (error) {
+			appLogger.error('[JsHmrStrategy] Error in batched build:', error as Error);
+			return { success: false };
+		}
+	}
+
+	/**
+	 * Processes bundled output and determines whether the browser can hot-accept
+	 * the update or must fall back to a full reload.
+	 *
+	 * @param filepath - Path to the bundled output file
+	 * @param url - URL path for the bundled file
+	 * @returns True if processing was successful and update should be broadcast
+	 */
+	private async processOutput(filepath: string, url: string): Promise<{ success: boolean; requiresReload: boolean }> {
+		try {
+			const code = await fileSystem.readFile(filepath);
+
+			if (code.includes('/* [ecopages] hmr */')) {
+				return { success: true, requiresReload: !code.includes('import.meta.hot.accept') };
+			}
+
+			appLogger.debug(`[JsHmrStrategy] Processed ${url}`);
+
+			const hasHmrAccept = code.includes('import.meta.hot.accept');
+			return { success: true, requiresReload: !hasHmrAccept };
+		} catch (error) {
+			appLogger.error(`[JsHmrStrategy] Error processing output for ${url}:`, error as Error);
+			return { success: false, requiresReload: false };
+		}
+	}
+}

package/src/index.browser.ts

@@ -0,0 +1,3 @@
+export type * from './types/public-types.ts';
+export type * from './eco/eco.types.ts';
+export { eco } from './eco/eco.browser.ts';

package/src/index.ts

@@ -0,0 +1,15 @@
+export type * from './types/public-types.ts';
+export type * from './eco/eco.types.ts';
+export { eco } from './eco/eco.ts';
+export { defineApiHandler, defineGroupHandler, type GroupHandler } from './adapters/shared/define-api-handler.ts';
+export {
+	createEcoBuildPluginFromSourceTransform,
+	createVitePluginsFromAppSourceTransforms,
+	getAppSourceTransforms,
+	createVitePluginFromSourceTransform,
+	normalizeTransformId,
+	type EcoSourceTransform,
+	type EcoSourceTransformResult,
+	type EcoViteCompatiblePlugin,
+} from './plugins/source-transform.ts';
+export { createEcoComponentMetaTransform } from './plugins/eco-component-meta-plugin.ts';

package/src/integrations/ghtml/ghtml-renderer.test.ts

@@ -0,0 +1,253 @@
+import { describe, expect, it } from 'vitest';
+import HtmlTemplate from '../../../__fixtures__/app/src/includes/html.ghtml.js';
+import { FIXTURE_APP_PROJECT_DIR } from '../../../__fixtures__/constants.js';
+import {
+	eco,
+	type ForeignSubtreeRenderPayload,
+	type EcoComponent,
+	type EcoPagesElement,
+	type HtmlTemplateProps,
+} from '../../index.ts';
+import { ConfigBuilder } from '../../config/config-builder.ts';
+import { IntegrationPlugin } from '../../plugins/integration-plugin.ts';
+import {
+	IntegrationRenderer,
+	type RenderToResponseContext,
+} from '../../route-renderer/orchestration/integration-renderer.ts';
+import { GhtmlRenderer } from './ghtml-renderer.ts';
+
+const appConfig = await new ConfigBuilder().setRootDir(FIXTURE_APP_PROJECT_DIR).build();
+
+const metadata = {
+	title: 'Ecopages',
+	description: 'Ecopages',
+};
+
+const pageBody = '<body>Hello World</body>';
+
+const TestHtmlTemplate: EcoComponent<HtmlTemplateProps> = async ({ children }) => {
+	return `<html><body>${children}</body></html>`;
+};
+
+class TestGhtmlRenderer extends GhtmlRenderer {
+	htmlTemplate: EcoComponent<HtmlTemplateProps> = TestHtmlTemplate;
+
+	protected override async getHtmlTemplate(): Promise<EcoComponent<HtmlTemplateProps>> {
+		return this.htmlTemplate;
+	}
+}
+
+const createRenderer = (config = appConfig) =>
+	new TestGhtmlRenderer({
+		appConfig: config,
+		assetProcessingService: {} as any,
+		runtimeOrigin: 'http://localhost:3000',
+		resolvedIntegrationDependencies: [],
+	});
+
+class DeferredRenderer extends IntegrationRenderer<EcoPagesElement> {
+	name = 'deferred';
+
+	async render(): Promise<string> {
+		return '';
+	}
+
+	override async renderComponent() {
+		return {
+			html: '<button data-testid="deferred-widget">Deferred widget</button>',
+			canAttachAttributes: true,
+			rootTag: 'button',
+			integrationName: this.name,
+		};
+	}
+
+	async renderToResponse<P = Record<string, unknown>>(
+		_view: EcoComponent<P>,
+		_props: P,
+		_ctx: RenderToResponseContext,
+	) {
+		return new Response('');
+	}
+}
+
+class DeferredPlugin extends IntegrationPlugin<EcoPagesElement> {
+	renderer = DeferredRenderer;
+
+	constructor() {
+		super({
+			name: 'deferred',
+			extensions: ['.deferred.ts'],
+		});
+	}
+}
+
+describe('GhtmlRenderer', () => {
+	it('should render the page', async () => {
+		const renderer = createRenderer();
+
+		const body = await renderer.render({
+			params: {},
+			query: {},
+			props: {},
+			file: 'file',
+			metadata,
+			Page: async () => pageBody,
+			resolvedDependencies: [],
+			HtmlTemplate,
+		});
+
+		expect(body).toContain('<!DOCTYPE html>');
+		expect(body).toContain('<body>Hello World</body>');
+		expect(body).toContain('<title>Ecopages</title>');
+		expect(body).toContain('<meta name="description" content="Ecopages" />');
+	});
+
+	it('should throw an error if the page fails to render', async () => {
+		const renderer = createRenderer();
+
+		await expect(
+			renderer.render({
+				params: {},
+				query: {},
+				props: {},
+				file: 'file',
+				resolvedDependencies: [],
+				metadata,
+				Page: async () => {
+					throw new Error('Page failed to render');
+				},
+				HtmlTemplate,
+			}),
+		).rejects.toThrow('Error rendering page: Page failed to render');
+	});
+
+	it('should resolve deferred foreign layout content without unresolved eco-marker artifacts', async () => {
+		const deferredPlugin = new DeferredPlugin();
+		const config = await new ConfigBuilder()
+			.setRootDir(FIXTURE_APP_PROJECT_DIR)
+			.setRobotsTxt({
+				preferences: {
+					'*': [],
+				},
+			})
+			.setIntegrations([deferredPlugin])
+			.setDefaultMetadata(metadata)
+			.setBaseUrl('http://localhost:3000')
+			.build();
+
+		deferredPlugin.setConfig(config);
+		deferredPlugin.setRuntimeOrigin('http://localhost:3000');
+
+		const renderer = createRenderer(config);
+
+		const DeferredWidget = eco.component<{}, string>({
+			integration: 'deferred',
+			render: () => '<button data-testid="deferred-widget">Deferred widget</button>',
+		});
+		DeferredWidget.config = {
+			...DeferredWidget.config,
+			__eco: {
+				id: 'deferred-widget',
+				file: '/app/components/deferred-widget.deferred.ts',
+				integration: 'deferred',
+			},
+		};
+
+		const Layout = eco.layout<string>({
+			dependencies: {
+				components: [DeferredWidget],
+			},
+			render: ({ children }) => `<main class="layout">${children}${DeferredWidget({})}</main>`,
+		});
+
+		const body = await renderer.render({
+			params: {},
+			query: {},
+			props: {},
+			file: 'file',
+			metadata,
+			Page: async () => '<section>Page</section>',
+			Layout,
+			resolvedDependencies: [],
+			HtmlTemplate: TestHtmlTemplate,
+			pageProps: {},
+		});
+
+		expect(body).toContain('<button data-testid="deferred-widget">Deferred widget</button>');
+		expect(body).not.toContain('<eco-marker');
+	});
+
+	it('should expose the compatibility foreign-subtree payload contract', async () => {
+		const renderer = createRenderer();
+		const Component = (async () => '<main>Foreign Subtree</main>') as EcoComponent<Record<string, unknown>>;
+
+		const result = await renderer.renderForeignSubtree({
+			component: Component,
+			props: {},
+		});
+
+		expect(result).toEqual<ForeignSubtreeRenderPayload>({
+			html: '<main>Foreign Subtree</main>',
+			assets: [],
+			rootTag: 'main',
+			rootAttributes: undefined,
+			attachmentPolicy: { kind: 'first-element' },
+			integrationName: 'ghtml',
+		});
+	});
+
+	describe('renderToResponse', () => {
+		it('should render a view with default status 200', async () => {
+			const renderer = createRenderer();
+			const View = (async (props: { title: string }) => `<h1>${props.title}</h1>`) as EcoComponent<{
+				title: string;
+			}>;
+
+			const response = await renderer.renderToResponse(View, { title: 'Hello Ghtml' }, {});
+
+			expect(response.status).toBe(200);
+			expect(response.headers.get('Content-Type')).toBe('text/html; charset=utf-8');
+			await expect(response.text()).resolves.toContain('<h1>Hello Ghtml</h1>');
+		});
+
+		it('should render a partial view without a full html wrapper', async () => {
+			const renderer = createRenderer();
+			const View = (async (props: { content: string }) => `<div>${props.content}</div>`) as EcoComponent<{
+				content: string;
+			}>;
+
+			const response = await renderer.renderToResponse(View, { content: 'Partial' }, { partial: true });
+			const body = await response.text();
+
+			expect(body).toBe('<div>Partial</div>');
+			expect(body).not.toContain('<!DOCTYPE html>');
+		});
+
+		it('should render with layout when not partial', async () => {
+			const renderer = createRenderer();
+			const Layout = (async ({ children }: { children: string }) =>
+				`<main class="layout">${children}</main>`) as EcoComponent<{ children: string }>;
+			const View = (async (props: { message: string }) => `<p>${props.message}</p>`) as EcoComponent<{
+				message: string;
+			}>;
+			View.config = { layout: Layout };
+
+			const response = await renderer.renderToResponse(View, { message: 'With Layout' }, {});
+			const body = await response.text();
+
+			expect(body).toContain('<main class="layout">');
+			expect(body).toContain('<p>With Layout</p>');
+		});
+
+		it('should throw an error if the view fails to render', async () => {
+			const renderer = createRenderer();
+			const View = (async () => {
+				throw new Error('View failed to render');
+			}) as EcoComponent<object>;
+
+			await expect(renderer.renderToResponse(View, {}, {})).rejects.toThrow(
+				'Error rendering view: View failed to render',
+			);
+		});
+	});
+});

package/src/integrations/ghtml/ghtml-renderer.ts

@@ -0,0 +1,87 @@
+/**
+ * This module contains the ghtml renderer
+ * @module
+ */
+
+import type {
+	ComponentRenderInput,
+	ComponentRenderResult,
+	EcoComponent,
+	EcoPagesElement,
+	IntegrationRendererRenderOptions,
+	RouteRendererBody,
+} from '../../types/public-types.ts';
+import {
+	IntegrationRenderer,
+	type RenderToResponseContext,
+} from '../../route-renderer/orchestration/integration-renderer.ts';
+import { GHTML_PLUGIN_NAME } from './ghtml.constants.ts';
+
+type GhtmlViewFn<P> = (props: P) => Promise<EcoPagesElement> | EcoPagesElement;
+type GhtmlLayoutFn = (
+	props: { children: string } & Record<string, unknown>,
+) => Promise<EcoPagesElement> | EcoPagesElement;
+
+/**
+ * A renderer for the ghtml integration.
+ * It renders a page using the HtmlTemplate and Page components.
+ */
+export class GhtmlRenderer extends IntegrationRenderer<EcoPagesElement> {
+	name = GHTML_PLUGIN_NAME;
+
+	override async renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult> {
+		return this.renderStringComponentWithQueuedForeignSubtrees(
+			input,
+			input.component as GhtmlViewFn<Record<string, unknown>>,
+		);
+	}
+
+	async render({
+		params,
+		query,
+		props,
+		locals,
+		pageLocals,
+		metadata,
+		Page,
+		Layout,
+		HtmlTemplate,
+	}: IntegrationRendererRenderOptions): Promise<RouteRendererBody> {
+		try {
+			return await this.renderPageWithDocumentShell({
+				page: {
+					component: Page as EcoComponent,
+					props: { params, query, ...props, locals: pageLocals },
+				},
+				layout: Layout
+					? {
+							component: Layout as EcoComponent,
+							props: locals ? { locals } : {},
+						}
+					: undefined,
+				htmlTemplate: HtmlTemplate as EcoComponent,
+				metadata,
+				pageProps: props ?? {},
+			});
+		} catch (error) {
+			throw this.createRenderError('Error rendering page', error);
+		}
+	}
+
+	async renderToResponse<P = Record<string, unknown>>(
+		view: EcoComponent<P>,
+		props: P,
+		ctx: RenderToResponseContext,
+	): Promise<Response> {
+		try {
+			return await this.renderViewWithDocumentShell({
+				view,
+				props,
+				ctx,
+				layout: view.config?.layout as GhtmlLayoutFn | undefined,
+			});
+		} catch (error) {
+			throw this.createRenderError('Error rendering view', error);
+		}
+	}
+}

package/src/integrations/ghtml/ghtml.constants.ts

@@ -0,0 +1 @@
+export const GHTML_PLUGIN_NAME = 'ghtml';

package/src/integrations/ghtml/ghtml.plugin.ts

@@ -0,0 +1,28 @@
+import { IntegrationPlugin, type IntegrationPluginConfig } from '../../plugins/integration-plugin.ts';
+import { GhtmlRenderer } from './ghtml-renderer.ts';
+import { GHTML_PLUGIN_NAME } from './ghtml.constants.ts';
+
+/**
+ * The Ghtml plugin class
+ * This plugin provides support for ghtml components in Ecopages
+ */
+export class GhtmlPlugin extends IntegrationPlugin {
+	renderer = GhtmlRenderer;
+
+	constructor(options?: Omit<IntegrationPluginConfig, 'name'>) {
+		super({
+			name: GHTML_PLUGIN_NAME,
+			extensions: ['.ghtml.ts', '.ghtml.tsx', '.ghtml'],
+			...options,
+		});
+	}
+}
+
+/**
+ * Factory function to create a Ghtml plugin instance
+ * @param options Configuration options for the Ghtml plugin
+ * @returns A new GhtmlPlugin instance
+ */
+export function ghtmlPlugin(options?: Omit<IntegrationPluginConfig, 'name'>): GhtmlPlugin {
+	return new GhtmlPlugin(options);
+}