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

package/src/adapters/shared/render-context.test.ts

@@ -0,0 +1,244 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createRenderContext } from './render-context.ts';
+import type { IntegrationPlugin } from '../../plugins/integration-plugin.ts';
+import type { IntegrationRenderer } from '../../route-renderer/orchestration/integration-renderer.ts';
+import type { EcoFunctionComponent } from '../../types/public-types.ts';
+
+describe('createRenderContext', () => {
+	const RenderToResponse = vi.fn(() => Promise.resolve(new Response('rendered')));
+	const rendererModules = {
+		integrationManifestModuleId: 'virtual:ecopages/integration-manifest.ts',
+	};
+
+	const Renderer = {
+		name: '-renderer',
+		renderToResponse: RenderToResponse,
+	} as unknown as IntegrationRenderer;
+
+	const ExplicitRenderer = {
+		name: 'explicit-renderer',
+		renderToResponse: RenderToResponse,
+	} as unknown as IntegrationRenderer;
+
+	const InitializeRenderer = vi.fn(() => Renderer);
+
+	const Plugin = {
+		name: '-integration',
+		initializeRenderer: InitializeRenderer,
+	} as unknown as IntegrationPlugin;
+
+	const ExplicitInitializeRenderer = vi.fn(() => ExplicitRenderer);
+
+	const ExplicitPlugin = {
+		name: 'explicit-renderer',
+		initializeRenderer: ExplicitInitializeRenderer,
+	} as unknown as IntegrationPlugin;
+
+	const ViewFn = ((props: { foo: string }) => `<div>${props.foo}</div>`) as EcoFunctionComponent<
+		{ foo: string },
+		string
+	>;
+	ViewFn.config = {
+		__eco: {
+			id: 'test',
+			file: '/some/dir/-view.ts',
+			integration: '-integration',
+		},
+	};
+
+	const renderContext = createRenderContext({
+		integrations: [Plugin, ExplicitPlugin],
+		rendererModules,
+	});
+
+	it('should create a render context with methods', () => {
+		expect(renderContext.importServerModule).toBeDefined();
+		expect(renderContext.renderServerModule).toBeDefined();
+		expect(renderContext.render).toBeDefined();
+		expect(renderContext.renderPartial).toBeDefined();
+		expect(renderContext.json).toBeDefined();
+		expect(renderContext.html).toBeDefined();
+	});
+
+	it('should delegate importServerModule to the active render-context loader', async () => {
+		const ImportServerModule = vi.fn(async (filePath: string) => ({ filePath }));
+		const delegatedContext = createRenderContext({
+			integrations: [Plugin, ExplicitPlugin],
+			rendererModules,
+			importServerModule: ImportServerModule,
+		});
+
+		const result = await delegatedContext.importServerModule('/tmp/view.kita.tsx');
+
+		expect(ImportServerModule).toHaveBeenCalledWith('/tmp/view.kita.tsx');
+		expect(result).toEqual({ filePath: '/tmp/view.kita.tsx' });
+	});
+
+	it('should accept file URLs for importServerModule', async () => {
+		const ImportServerModule = vi.fn(async (filePath: string) => ({ filePath }));
+		const delegatedContext = createRenderContext({
+			integrations: [Plugin, ExplicitPlugin],
+			rendererModules,
+			importServerModule: ImportServerModule,
+		});
+
+		const result = await delegatedContext.importServerModule(new URL('file:///tmp/view.kita.tsx'));
+
+		expect(ImportServerModule).toHaveBeenCalledWith('/tmp/view.kita.tsx');
+		expect(result).toEqual({ filePath: '/tmp/view.kita.tsx' });
+	});
+
+	it('should import and render a default-exported server view in one call', async () => {
+		RenderToResponse.mockClear();
+		const importedView = (() => '<div></div>') as EcoFunctionComponent<{ slug: string }, string>;
+		importedView.config = {
+			__eco: {
+				id: 'imported-view',
+				file: '/tmp/imported-view.kita.tsx',
+				integration: '-integration',
+			},
+		};
+
+		const ImportServerModule = vi.fn(async (_filePath: string) => ({ default: importedView }));
+		const delegatedContext = createRenderContext({
+			integrations: [Plugin, ExplicitPlugin],
+			rendererModules,
+			importServerModule: ImportServerModule,
+		});
+
+		await delegatedContext.renderServerModule('/tmp/view.kita.tsx', { slug: 'release' });
+
+		expect(ImportServerModule).toHaveBeenCalledWith('/tmp/view.kita.tsx');
+		expect(RenderToResponse).toHaveBeenCalledWith(
+			importedView,
+			{ slug: 'release' },
+			{
+				partial: false,
+				status: undefined,
+				headers: undefined,
+			},
+		);
+	});
+
+	it('should accept file URLs for renderServerModule', async () => {
+		RenderToResponse.mockClear();
+		const importedView = (() => '<div></div>') as EcoFunctionComponent<{ slug: string }, string>;
+		importedView.config = {
+			__eco: {
+				id: 'imported-view-url',
+				file: '/tmp/imported-view-url.kita.tsx',
+				integration: '-integration',
+			},
+		};
+
+		const ImportServerModule = vi.fn(async (_filePath: string) => ({ default: importedView }));
+		const delegatedContext = createRenderContext({
+			integrations: [Plugin, ExplicitPlugin],
+			rendererModules,
+			importServerModule: ImportServerModule,
+		});
+
+		await delegatedContext.renderServerModule(new URL('file:///tmp/view.kita.tsx'), { slug: 'release' });
+
+		expect(ImportServerModule).toHaveBeenCalledWith('/tmp/view.kita.tsx');
+		expect(RenderToResponse).toHaveBeenCalledWith(
+			importedView,
+			{ slug: 'release' },
+			{
+				partial: false,
+				status: undefined,
+				headers: undefined,
+			},
+		);
+	});
+
+	describe('render', () => {
+		it('should call renderer.renderToResponse with partial: false', async () => {
+			RenderToResponse.mockClear();
+			InitializeRenderer.mockClear();
+			ExplicitInitializeRenderer.mockClear();
+			const props = { foo: 'bar' };
+			const options = { status: 201, headers: { 'X-Custom': '1' } };
+
+			const response = await renderContext.render(ViewFn, props, options);
+
+			expect(InitializeRenderer).toHaveBeenCalledWith({ rendererModules });
+			expect(RenderToResponse).toHaveBeenCalledWith(ViewFn, props, {
+				partial: false,
+				status: 201,
+				headers: { 'X-Custom': '1' },
+			});
+			expect(response instanceof Response).toBe(true);
+		});
+
+		it('should throw if view integration is unknown', async () => {
+			const badViewFn = (() => '<div></div>') as EcoFunctionComponent<{}, string>;
+			badViewFn.config = { __eco: { id: 'test', file: '/bad-view.ts', integration: 'unknown' } };
+			await expect(renderContext.render(badViewFn, {})).rejects.toThrow('No integration found for: unknown');
+		});
+
+		it('should throw if view integration is missing', async () => {
+			const badViewFn = (() => '<div></div>') as EcoFunctionComponent<{}, string>;
+			badViewFn.config = { __eco: undefined };
+			await expect(renderContext.render(badViewFn, {})).rejects.toThrow('Cannot determine integration for view');
+		});
+
+		it('should prefer explicit config.integration over injected metadata', async () => {
+			RenderToResponse.mockClear();
+			InitializeRenderer.mockClear();
+			ExplicitInitializeRenderer.mockClear();
+
+			const explicitViewFn = (() => '<div></div>') as EcoFunctionComponent<{}, string>;
+			explicitViewFn.config = {
+				integration: 'explicit-renderer',
+				__eco: { id: 'test', file: '/some/file.tsx', integration: '-integration' },
+			};
+
+			await renderContext.render(explicitViewFn, {});
+
+			expect(ExplicitInitializeRenderer).toHaveBeenCalled();
+			expect(InitializeRenderer).not.toHaveBeenCalled();
+		});
+	});
+
+	describe('renderPartial', () => {
+		it('should call renderer.renderToResponse with partial: true', async () => {
+			RenderToResponse.mockClear();
+			const props = { foo: 'bar' };
+			const options = { status: 200 };
+
+			await renderContext.renderPartial(ViewFn, props, options);
+
+			expect(InitializeRenderer).toHaveBeenCalled();
+			expect(RenderToResponse).toHaveBeenCalledWith(ViewFn, props, {
+				partial: true,
+				status: 200,
+				headers: undefined,
+			});
+		});
+	});
+
+	describe('json', () => {
+		it('should return a JSON response', async () => {
+			const data = { hello: 'world' };
+			const response = renderContext.json(data);
+			expect(response.headers.get('Content-Type')).toContain('application/json');
+			expect(await response.json()).toEqual(data);
+		});
+
+		it('should support custom status and headers', async () => {
+			const response = renderContext.json({}, { status: 201, headers: { 'X-Test': 'true' } });
+			expect(response.status).toBe(201);
+			expect(response.headers.get('X-Test')).toBe('true');
+		});
+	});
+
+	describe('html', () => {
+		it('should return an HTML response', async () => {
+			const html = '<div>hello</div>';
+			const response = renderContext.html(html);
+			expect(response.headers.get('Content-Type')).toContain('text/html');
+			expect(await response.text()).toBe(html);
+		});
+	});
+});

package/src/adapters/shared/render-context.ts

@@ -0,0 +1,161 @@
+import { fileURLToPath } from 'node:url';
+import type {
+	EcoComponent,
+	EcoPageComponent,
+	RenderContext,
+	RenderOptions,
+	ResponseOptions,
+} from '../../types/public-types.ts';
+import type {
+	IntegrationRenderer,
+	RenderToResponseContext,
+} from '../../route-renderer/orchestration/integration-renderer.ts';
+import type { AnyIntegrationPlugin } from '../../plugins/integration-plugin.ts';
+import { invariant } from '../../utils/invariant.ts';
+
+export interface CreateRenderContextOptions {
+	integrations: AnyIntegrationPlugin[];
+	rendererModules?: unknown;
+	importServerModule?: (filePath: string) => Promise<unknown>;
+}
+
+function resolveServerModulePath(filePath: string | URL): string {
+	return filePath instanceof URL ? fileURLToPath(filePath) : filePath;
+}
+
+/**
+ * Merges request locals into component props as a dedicated 'locals' property.
+ * This prevents naming conflicts and maintains type safety by keeping locals
+ * separate from other props.
+ *
+ * @param props - The original component props
+ * @param locals - Optional request-scoped locals from middleware
+ * @returns Props with locals merged in, or original props if no locals provided
+ */
+function mergePropsWithLocals<P>(props: P, locals: Record<string, unknown> | undefined): P {
+	if (!locals || typeof props !== 'object' || props === null) {
+		return props;
+	}
+	return { ...(props as Record<string, unknown>), locals } as P;
+}
+
+/**
+ * Creates a render context for route handlers.
+ * Provides render(), renderPartial(), json(), and html() methods that can be used
+ * within route handlers to generate responses.
+ *
+ * @param options - Configuration options including available integrations
+ * @returns A RenderContext object with methods for rendering views and creating responses
+ */
+export function createRenderContext(options: CreateRenderContextOptions): RenderContext {
+	const { integrations } = options;
+
+	/**
+	 * Resolves the appropriate renderer for a given view component based on its integration.
+	 * Throws an error if the integration cannot be determined or is not found.
+	 */
+	const getRendererForView = <P>(view: EcoComponent<P>): IntegrationRenderer => {
+		const integrationName = view.config?.integration ?? view.config?.__eco?.integration;
+		invariant(
+			!!integrationName,
+			'Cannot determine integration for view. Set view.config.integration explicitly or ensure the view is defined with eco.page() in a file with a recognized extension.',
+		);
+
+		const integration = integrations.find((i) => i.name === integrationName);
+		invariant(!!integration, `No integration found for: ${integrationName}`);
+
+		return integration.initializeRenderer({
+			rendererModules: options.rendererModules,
+		}) as IntegrationRenderer;
+	};
+
+	const renderContext: RenderContext = {
+		importServerModule: async <T = unknown>(filePath: string | URL) => {
+			invariant(!!options.importServerModule, 'Server module importing is not available in this render context.');
+			return (await options.importServerModule(resolveServerModulePath(filePath))) as T;
+		},
+
+		async renderServerModule<P = Record<string, unknown>>(
+			this: { locals?: Record<string, unknown> } | undefined,
+			filePath: string | URL,
+			props?: P,
+			renderOptions?: RenderOptions,
+		): Promise<Response> {
+			const module = await renderContext.importServerModule<{ default: EcoPageComponent<P> }>(filePath);
+			const view = module.default as EcoComponent<P>;
+			const locals = (this as { locals?: Record<string, unknown> } | undefined)?.locals;
+			const mergedProps = mergePropsWithLocals<P>(props ?? ({} as P), locals);
+
+			const renderer = getRendererForView(view);
+			const ctx: RenderToResponseContext = {
+				partial: false,
+				status: renderOptions?.status,
+				headers: renderOptions?.headers,
+			};
+
+			return await renderer.renderToResponse(view, mergedProps, ctx);
+		},
+
+		async render<P>(
+			this: { locals?: Record<string, unknown> } | undefined,
+			view: EcoComponent<P>,
+			props?: P,
+			renderOptions?: RenderOptions,
+		): Promise<Response> {
+			const locals = (this as { locals?: Record<string, unknown> } | undefined)?.locals;
+			const mergedProps = mergePropsWithLocals<P>(props ?? ({} as P), locals);
+
+			const renderer = getRendererForView(view);
+			const ctx: RenderToResponseContext = {
+				partial: false,
+				status: renderOptions?.status,
+				headers: renderOptions?.headers,
+			};
+			return renderer.renderToResponse(view, mergedProps, ctx);
+		},
+
+		async renderPartial<P>(
+			this: { locals?: Record<string, unknown> } | undefined,
+			view: EcoComponent<P>,
+			props: P,
+			renderOptions?: RenderOptions,
+		): Promise<Response> {
+			const locals = (this as { locals?: Record<string, unknown> } | undefined)?.locals;
+			const mergedProps = mergePropsWithLocals<P>(props, locals);
+
+			const renderer = getRendererForView(view);
+			const ctx: RenderToResponseContext = {
+				partial: true,
+				status: renderOptions?.status,
+				headers: renderOptions?.headers,
+			};
+			return renderer.renderToResponse(view, mergedProps, ctx);
+		},
+
+		json(data: unknown, responseOptions?: ResponseOptions): Response {
+			const headers = new Headers({ 'Content-Type': 'application/json; charset=utf-8' });
+			if (responseOptions?.headers) {
+				const incomingHeaders = new Headers(responseOptions.headers);
+				incomingHeaders.forEach((value, key) => headers.set(key, value));
+			}
+			return new Response(JSON.stringify(data), {
+				status: responseOptions?.status ?? 200,
+				headers,
+			});
+		},
+
+		html(content: string, responseOptions?: ResponseOptions): Response {
+			const headers = new Headers({ 'Content-Type': 'text/html; charset=utf-8' });
+			if (responseOptions?.headers) {
+				const incomingHeaders = new Headers(responseOptions.headers);
+				incomingHeaders.forEach((value, key) => headers.set(key, value));
+			}
+			return new Response(content, {
+				status: responseOptions?.status ?? 200,
+				headers,
+			});
+		},
+	};
+
+	return renderContext;
+}

package/src/adapters/shared/runtime-app-bootstrap.test.ts

@@ -0,0 +1,96 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'vitest';
+import { resolveRuntimeBinding, resolveServeRuntimeOrigin, resolveStaticRuntimeMode } from './runtime-app-bootstrap.ts';
+
+describe('resolveServeRuntimeOrigin', () => {
+	it('normalizes hostname and port into an origin string', () => {
+		assert.equal(
+			resolveServeRuntimeOrigin({
+				hostname: '127.0.0.1',
+				port: '4567',
+			}),
+			'http://127.0.0.1:4567',
+		);
+	});
+
+	it('wraps bare IPv6 hostnames so the origin stays valid', () => {
+		assert.equal(
+			resolveServeRuntimeOrigin({
+				hostname: '::1',
+				port: 4567,
+			}),
+			'http://[::1]:4567',
+		);
+	});
+});
+
+describe('runtime app bootstrap', () => {
+	it('prefers CLI binding values over environment values', () => {
+		const binding = resolveRuntimeBinding({
+			cliArgs: {
+				preview: false,
+				build: false,
+				start: false,
+				dev: true,
+				port: 4321,
+				hostname: '127.0.0.1',
+				reactFastRefresh: undefined,
+			},
+			serverOptions: {
+				custom: true,
+			},
+			env: {
+				ECOPAGES_PORT: '9999',
+				ECOPAGES_HOSTNAME: 'env-host',
+			} as NodeJS.ProcessEnv,
+		});
+
+		assert.equal(binding.preferredPort, 4321);
+		assert.equal(binding.preferredHostname, '127.0.0.1');
+		assert.equal(binding.runtimeOrigin, 'http://127.0.0.1:4321');
+		assert.deepEqual(binding.serveOptions, {
+			port: 4321,
+			hostname: '127.0.0.1',
+			custom: true,
+		});
+		assert.equal(binding.watch, true);
+	});
+
+	it('skips the runtime server only when build or preview does not require fetch', () => {
+		const withoutFetchRuntime = resolveStaticRuntimeMode({
+			appConfig: {
+				integrations: [{ staticBuildStep: 'render' }],
+			} as any,
+			cliArgs: {
+				preview: true,
+				build: false,
+				start: false,
+				dev: false,
+				port: undefined,
+				hostname: undefined,
+				reactFastRefresh: undefined,
+			},
+		});
+
+		assert.equal(withoutFetchRuntime.requiresFetchRuntime, false);
+		assert.equal(withoutFetchRuntime.canBuildWithoutRuntimeServer, true);
+
+		const withFetchRuntime = resolveStaticRuntimeMode({
+			appConfig: {
+				integrations: [{ staticBuildStep: 'fetch' }],
+			} as any,
+			cliArgs: {
+				preview: false,
+				build: true,
+				start: false,
+				dev: false,
+				port: undefined,
+				hostname: undefined,
+				reactFastRefresh: undefined,
+			},
+		});
+
+		assert.equal(withFetchRuntime.requiresFetchRuntime, true);
+		assert.equal(withFetchRuntime.canBuildWithoutRuntimeServer, false);
+	});
+});

package/src/adapters/shared/runtime-app-bootstrap.ts

@@ -0,0 +1,72 @@
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from '../../config/constants.ts';
+import type { ReturnParseCliArgs } from '../../utils/parse-cli-args.ts';
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+
+export type RuntimeBinding = {
+	preferredPort: number;
+	preferredHostname: string;
+	runtimeOrigin: string;
+	serveOptions: Record<string, unknown>;
+	watch: boolean;
+};
+
+export type StaticRuntimeMode = {
+	requiresFetchRuntime: boolean;
+	canBuildWithoutRuntimeServer: boolean;
+};
+
+function normalizeOriginHostname(hostname: string): string {
+	if (hostname.includes(':') && !hostname.startsWith('[') && !hostname.endsWith(']')) {
+		return `[${hostname}]`;
+	}
+
+	return hostname;
+}
+
+export function resolveServeRuntimeOrigin(serveOptions: { hostname?: string; port?: number | string }): string {
+	const hostname = normalizeOriginHostname(String(serveOptions.hostname ?? DEFAULT_ECOPAGES_HOSTNAME));
+	const port = Number(serveOptions.port ?? DEFAULT_ECOPAGES_PORT);
+
+	return `http://${hostname}:${port}`;
+}
+
+export function resolveRuntimeBinding(options: {
+	cliArgs: ReturnParseCliArgs;
+	serverOptions?: Record<string, unknown>;
+	env?: NodeJS.ProcessEnv;
+}): RuntimeBinding {
+	const env = options.env ?? process.env;
+	const preferredPort =
+		options.cliArgs.port ?? (env.ECOPAGES_PORT ? Number(env.ECOPAGES_PORT) : undefined) ?? DEFAULT_ECOPAGES_PORT;
+	const preferredHostname = options.cliArgs.hostname ?? env.ECOPAGES_HOSTNAME ?? DEFAULT_ECOPAGES_HOSTNAME;
+
+	return {
+		preferredPort,
+		preferredHostname,
+		runtimeOrigin: resolveServeRuntimeOrigin({
+			hostname: preferredHostname,
+			port: preferredPort,
+		}),
+		serveOptions: {
+			port: preferredPort,
+			hostname: preferredHostname,
+			...(options.serverOptions ?? {}),
+		},
+		watch: options.cliArgs.dev,
+	};
+}
+
+export function resolveStaticRuntimeMode(options: {
+	appConfig: EcoPagesAppConfig;
+	cliArgs: ReturnParseCliArgs;
+}): StaticRuntimeMode {
+	const requiresFetchRuntime = options.appConfig.integrations.some(
+		(integration) => integration.staticBuildStep === 'fetch',
+	);
+	const canBuildWithoutRuntimeServer = (options.cliArgs.build || options.cliArgs.preview) && !requiresFetchRuntime;
+
+	return {
+		requiresFetchRuntime,
+		canBuildWithoutRuntimeServer,
+	};
+}

package/src/adapters/shared/runtime-host.ts

@@ -0,0 +1,11 @@
+export interface RuntimeHost<TServer, TServeOptions> {
+	start(options: RuntimeHostStartOptions<TServeOptions>): Promise<TServer>;
+	stop(server: TServer, options?: { force?: boolean }): Promise<void>;
+	getOrigin(server: TServer, fallbackServeOptions: TServeOptions): string;
+}
+
+export interface RuntimeHostStartOptions<TServeOptions> {
+	serveOptions: TServeOptions;
+	handleRequest(request: Request): Promise<Response>;
+	onError(error: Error): Promise<void> | void;
+}