@ecopages/core 0.2.0-alpha.26 → 0.2.0-alpha.27

package/src/adapters/shared/explicit-static-render-preparation.ts

@@ -0,0 +1,58 @@
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import type { EcoFunctionComponent, EcoPageComponent } from '../../types/public-types.ts';
+import type { ExplicitViewRenderer, ExplicitViewRendererResolver } from '../../route-renderer/route-renderer.ts';
+
+type ExplicitStaticRenderPreparationResult = {
+	renderer: ExplicitViewRenderer;
+	props: Record<string, unknown>;
+	view: EcoFunctionComponent<Record<string, unknown>, any>;
+};
+
+function getViewIntegrationName(view: {
+	config?: { integration?: string; __eco?: { integration?: string } };
+}): string | undefined {
+	return view.config?.integration ?? view.config?.__eco?.integration;
+}
+
+/**
+ * Resolves the renderer and static props needed to render one explicit static
+ * view at runtime or during static generation.
+ */
+export async function prepareExplicitStaticRender(input: {
+	routePath: string;
+	view: EcoPageComponent<any>;
+	params: Record<string, string | string[]>;
+	appConfig: EcoPagesAppConfig;
+	runtimeOrigin: string;
+	routeRendererFactory: ExplicitViewRendererResolver;
+	errors: {
+		missingIntegration(routePath: string): string;
+		noRendererForIntegration(integrationName: string): string;
+	};
+}): Promise<ExplicitStaticRenderPreparationResult> {
+	const integrationName = getViewIntegrationName(input.view);
+	if (!integrationName) {
+		throw new Error(input.errors.missingIntegration(input.routePath));
+	}
+
+	const renderer = input.routeRendererFactory.getExplicitViewRenderer(integrationName);
+	if (!renderer) {
+		throw new Error(input.errors.noRendererForIntegration(integrationName));
+	}
+
+	const props = input.view.staticProps
+		? (
+				await input.view.staticProps({
+					pathname: { params: input.params },
+					appConfig: input.appConfig,
+					runtimeOrigin: input.runtimeOrigin,
+				})
+			).props
+		: {};
+
+	return {
+		renderer,
+		props,
+		view: input.view as EcoFunctionComponent<Record<string, unknown>, any>,
+	};
+}

package/src/adapters/shared/explicit-static-route-matcher.test.ts

@@ -0,0 +1,381 @@
+import { describe, expect, test, vi } from 'vitest';
+import type { EcoPageComponent, StaticRoute, ViewLoader } from '../../types/public-types.ts';
+import { ExplicitStaticRouteMatcher } from './explicit-static-route-matcher.ts';
+
+function createMockView(integration = 'ghtml'): EcoPageComponent<any> {
+	const view = (() => '<div>Test</div>') as EcoPageComponent<any>;
+	view.config = {
+		integration,
+		__eco: { id: 'test', file: '/test/-view.ts', integration },
+	};
+	return view;
+}
+
+function createMockLoader(view?: EcoPageComponent<any>): ViewLoader<any> {
+	const actualView = view ?? createMockView();
+	return () => Promise.resolve({ default: actualView });
+}
+
+function createMockRoute(path: string, view?: EcoPageComponent<any>): StaticRoute {
+	return {
+		path,
+		loader: createMockLoader(view),
+	};
+}
+
+function createMatcher(staticRoutes: StaticRoute[]) {
+	return new ExplicitStaticRouteMatcher({
+		appConfig: { baseUrl: 'http://localhost:3000' } as any,
+		routeRendererFactory: {} as any,
+		staticRoutes,
+	});
+}
+
+describe('ExplicitStaticRouteMatcher', () => {
+	describe('match', () => {
+		test('should match exact static path', () => {
+			const matcher = createMatcher([createMockRoute('/about')]);
+
+			const result = matcher.match('http://localhost:3000/about');
+
+			expect(result).not.toBeNull();
+			expect(result?.route.path).toBe('/about');
+			expect(result?.params).toEqual({});
+		});
+
+		test('should match root path', () => {
+			const matcher = createMatcher([createMockRoute('/')]);
+
+			const result = matcher.match('http://localhost:3000/');
+
+			expect(result).not.toBeNull();
+			expect(result?.route.path).toBe('/');
+			expect(result?.params).toEqual({});
+		});
+
+		test('should match nested static path', () => {
+			const matcher = createMatcher([createMockRoute('/docs/getting-started')]);
+
+			const result = matcher.match('http://localhost:3000/docs/getting-started');
+
+			expect(result).not.toBeNull();
+			expect(result?.route.path).toBe('/docs/getting-started');
+		});
+
+		test('should return null for non-matching path', () => {
+			const matcher = createMatcher([createMockRoute('/about')]);
+
+			const result = matcher.match('http://localhost:3000/contact');
+
+			expect(result).toBeNull();
+		});
+
+		test('should return null for partial match', () => {
+			const matcher = createMatcher([createMockRoute('/about')]);
+
+			const result = matcher.match('http://localhost:3000/about/team');
+
+			expect(result).toBeNull();
+		});
+	});
+
+	describe('match with :param syntax', () => {
+		test('should match dynamic segment with colon syntax', () => {
+			const matcher = createMatcher([createMockRoute('/blog/:slug')]);
+
+			const result = matcher.match('http://localhost:3000/blog/hello-world');
+
+			expect(result).not.toBeNull();
+			expect(result?.params).toEqual({ slug: 'hello-world' });
+		});
+
+		test('should match multiple dynamic segments', () => {
+			const matcher = createMatcher([createMockRoute('/blog/:year/:month/:slug')]);
+
+			const result = matcher.match('http://localhost:3000/blog/2024/01/hello-world');
+
+			expect(result).not.toBeNull();
+			expect(result?.params).toEqual({
+				year: '2024',
+				month: '01',
+				slug: 'hello-world',
+			});
+		});
+
+		test('should match mixed static and dynamic segments', () => {
+			const matcher = createMatcher([createMockRoute('/users/:id/posts')]);
+
+			const result = matcher.match('http://localhost:3000/users/123/posts');
+
+			expect(result).not.toBeNull();
+			expect(result?.params).toEqual({ id: '123' });
+		});
+	});
+
+	describe('match with [param] syntax', () => {
+		test('should match dynamic segment with bracket syntax', () => {
+			const matcher = createMatcher([createMockRoute('/blog/[slug]')]);
+
+			const result = matcher.match('http://localhost:3000/blog/hello-world');
+
+			expect(result).not.toBeNull();
+			expect(result?.params).toEqual({ slug: 'hello-world' });
+		});
+
+		test('should match multiple bracket parameters', () => {
+			const matcher = createMatcher([createMockRoute('/products/[category]/[id]')]);
+
+			const result = matcher.match('http://localhost:3000/products/electronics/12345');
+
+			expect(result).not.toBeNull();
+			expect(result?.params).toEqual({
+				category: 'electronics',
+				id: '12345',
+			});
+		});
+	});
+
+	describe('match with catch-all routes', () => {
+		test('should match catch-all with bracket syntax', () => {
+			const matcher = createMatcher([createMockRoute('/docs/[...path]')]);
+
+			const result = matcher.match('http://localhost:3000/docs/api/reference/components');
+
+			expect(result).not.toBeNull();
+			expect(result?.params).toEqual({ path: 'api/reference/components' });
+		});
+
+		test('should match catch-all with colon syntax', () => {
+			const matcher = createMatcher([createMockRoute('/files/:...path')]);
+
+			const result = matcher.match('http://localhost:3000/files/images/2024/photo.jpg');
+
+			expect(result).not.toBeNull();
+			expect(result?.params).toEqual({ path: 'images/2024/photo.jpg' });
+		});
+
+		test('should match catch-all with single segment', () => {
+			const matcher = createMatcher([createMockRoute('/docs/[...path]')]);
+
+			const result = matcher.match('http://localhost:3000/docs/intro');
+
+			expect(result).not.toBeNull();
+			expect(result?.params).toEqual({ path: 'intro' });
+		});
+	});
+
+	describe('route priority', () => {
+		test('should match first route when multiple routes match', () => {
+			const aboutView = createMockView();
+			const catchAllView = createMockView();
+
+			const matcher = createMatcher([
+				createMockRoute('/about', aboutView),
+				createMockRoute('/[...path]', catchAllView),
+			]);
+
+			const result = matcher.match('http://localhost:3000/about');
+
+			expect(result).not.toBeNull();
+			expect(result?.route.path).toBe('/about');
+		});
+
+		test('should match exact route before dynamic route', () => {
+			const exactView = createMockView();
+			const dynamicView = createMockView();
+
+			const matcher = createMatcher([
+				createMockRoute('/blog/featured', exactView),
+				createMockRoute('/blog/:slug', dynamicView),
+			]);
+
+			const result = matcher.match('http://localhost:3000/blog/featured');
+
+			expect(result).not.toBeNull();
+			expect(result?.route.path).toBe('/blog/featured');
+		});
+	});
+
+	describe('edge cases', () => {
+		test('should handle URL with query parameters', () => {
+			const matcher = createMatcher([createMockRoute('/search')]);
+
+			const result = matcher.match('http://localhost:3000/search?q=test&page=1');
+
+			expect(result).not.toBeNull();
+			expect(result?.route.path).toBe('/search');
+		});
+
+		test('should handle URL with hash', () => {
+			const matcher = createMatcher([createMockRoute('/docs/intro')]);
+
+			const result = matcher.match('http://localhost:3000/docs/intro#section-1');
+
+			expect(result).not.toBeNull();
+			expect(result?.route.path).toBe('/docs/intro');
+		});
+
+		test('should handle trailing slash', () => {
+			const matcher = createMatcher([createMockRoute('/about')]);
+
+			const result = matcher.match('http://localhost:3000/about/');
+
+			expect(result).not.toBeNull();
+			expect(result?.route.path).toBe('/about');
+		});
+
+		test('should return null for empty routes array', () => {
+			const matcher = createMatcher([]);
+
+			const result = matcher.match('http://localhost:3000/anything');
+
+			expect(result).toBeNull();
+		});
+	});
+
+	describe('handleMatch', () => {
+		test('should accept integration metadata from view.config.integration', async () => {
+			const view = (() => '<div>Test</div>') as EcoPageComponent<any>;
+			view.config = {
+				integration: 'ghtml',
+				__eco: { id: 'test', file: '/test/-view.ts', integration: 'ghtml' },
+			};
+
+			const mockResponse = new Response('<html>Test</html>');
+			const renderToResponse = vi.fn(() => mockResponse);
+			const matcher = new ExplicitStaticRouteMatcher({
+				appConfig: { baseUrl: 'http://localhost:3000' } as any,
+				routeRendererFactory: {
+					getExplicitViewRenderer: vi.fn(() => ({
+						renderToResponse,
+					})),
+				} as any,
+				staticRoutes: [createMockRoute('/about', view)],
+			});
+
+			const match = matcher.match('http://localhost:3000/about');
+			const response = await matcher.handleMatch(match!);
+
+			expect(response).toBe(mockResponse);
+			expect(renderToResponse).toHaveBeenCalledWith(view, {}, {});
+		});
+
+		test('should throw error when view is missing __eco.integration', async () => {
+			const viewWithoutIntegration = (() => '<div>Test</div>') as EcoPageComponent<any>;
+			viewWithoutIntegration.config = {
+				__eco: undefined,
+			};
+
+			const matcher = new ExplicitStaticRouteMatcher({
+				appConfig: { baseUrl: 'http://localhost:3000' } as any,
+				routeRendererFactory: {
+					getExplicitViewRenderer: vi.fn(() => null),
+				} as any,
+				staticRoutes: [createMockRoute('/about', viewWithoutIntegration)],
+			});
+			const match = matcher.match('http://localhost:3000/about');
+
+			expect(match).not.toBeNull();
+			await expect(matcher.handleMatch(match!)).rejects.toThrow('missing __eco.integration');
+		});
+
+		test('should throw error when renderer is not found', async () => {
+			const view = createMockView('nonexistent-integration');
+			const RendererFactory = {
+				getExplicitViewRenderer: vi.fn(() => null),
+			};
+
+			const matcher = new ExplicitStaticRouteMatcher({
+				appConfig: { baseUrl: 'http://localhost:3000' } as any,
+				routeRendererFactory: RendererFactory as any,
+				staticRoutes: [createMockRoute('/about', view)],
+			});
+
+			const match = matcher.match('http://localhost:3000/about');
+
+			await expect(matcher.handleMatch(match!)).rejects.toThrow(
+				'No renderer found for integration: nonexistent-integration',
+			);
+		});
+
+		test('should call renderer.renderToResponse with correct arguments', async () => {
+			const view = createMockView('ghtml');
+			const mockResponse = new Response('<html>Test</html>');
+			const RenderToResponse = vi.fn(() => mockResponse);
+			const RendererFactory = {
+				getExplicitViewRenderer: vi.fn(() => ({
+					renderToResponse: RenderToResponse,
+				})),
+			};
+
+			const matcher = new ExplicitStaticRouteMatcher({
+				appConfig: { baseUrl: 'http://localhost:3000' } as any,
+				routeRendererFactory: RendererFactory as any,
+				staticRoutes: [createMockRoute('/about', view)],
+			});
+
+			const match = matcher.match('http://localhost:3000/about');
+			const response = await matcher.handleMatch(match!);
+
+			expect(response).toBe(mockResponse);
+			expect(RenderToResponse).toHaveBeenCalledTimes(1);
+			expect(RenderToResponse).toHaveBeenCalledWith(view, {}, {});
+		});
+
+		test('should resolve staticProps and pass to renderer', async () => {
+			const view = createMockView('ghtml');
+			view.staticProps = vi.fn(async () => ({
+				props: { title: 'About Page', content: 'Hello' },
+			}));
+
+			const mockResponse = new Response('<html>Test</html>');
+			const RenderToResponse = vi.fn(() => mockResponse);
+			const RendererFactory = {
+				getExplicitViewRenderer: vi.fn(() => ({
+					renderToResponse: RenderToResponse,
+				})),
+			};
+
+			const matcher = new ExplicitStaticRouteMatcher({
+				appConfig: { baseUrl: 'http://localhost:3000' } as any,
+				routeRendererFactory: RendererFactory as any,
+				staticRoutes: [createMockRoute('/about', view)],
+			});
+
+			const match = matcher.match('http://localhost:3000/about');
+			await matcher.handleMatch(match!);
+
+			expect(view.staticProps).toHaveBeenCalledTimes(1);
+			expect(RenderToResponse).toHaveBeenCalledWith(view, { title: 'About Page', content: 'Hello' }, {});
+		});
+
+		test('should pass params to staticProps', async () => {
+			const view = createMockView('ghtml');
+			view.staticProps = vi.fn(async ({ pathname }) => ({
+				props: { slug: pathname.params.slug },
+			}));
+
+			const mockResponse = new Response('<html>Test</html>');
+			const RendererFactory = {
+				getExplicitViewRenderer: vi.fn(() => ({
+					renderToResponse: vi.fn(() => mockResponse),
+				})),
+			};
+
+			const matcher = new ExplicitStaticRouteMatcher({
+				appConfig: { baseUrl: 'http://localhost:3000' } as any,
+				routeRendererFactory: RendererFactory as any,
+				staticRoutes: [createMockRoute('/blog/:slug', view)],
+			});
+
+			const match = matcher.match('http://localhost:3000/blog/hello-world');
+			await matcher.handleMatch(match!);
+
+			expect(view.staticProps).toHaveBeenCalledWith(
+				expect.objectContaining({
+					pathname: { params: { slug: 'hello-world' } },
+				}),
+			);
+		});
+	});
+});

package/src/adapters/shared/explicit-static-route-matcher.ts

@@ -0,0 +1,131 @@
+import { appLogger } from '../../global/app-logger.ts';
+import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
+import type { StaticRoute } from '../../types/public-types.ts';
+import type { ExplicitViewRendererResolver } from '../../route-renderer/route-renderer.ts';
+import { prepareExplicitStaticRender } from './explicit-static-render-preparation.ts';
+
+export const EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS = {
+	missingIntegration: (routePath: string) =>
+		`View at ${routePath} is missing __eco.integration. Ensure it's defined with eco.page() and exported as default.`,
+	noRendererForIntegration: (integrationName: string) => `No renderer found for integration: ${integrationName}`,
+} as const;
+
+export interface ExplicitStaticRouteMatcherOptions {
+	appConfig: EcoPagesAppConfig;
+	routeRendererFactory: ExplicitViewRendererResolver;
+	staticRoutes: StaticRoute[];
+}
+
+export interface ExplicitRouteMatch {
+	route: StaticRoute;
+	params: Record<string, string>;
+}
+
+/**
+ * Matches and renders explicit static routes declared through `app.static()`.
+ */
+export class ExplicitStaticRouteMatcher {
+	private readonly appConfig: EcoPagesAppConfig;
+	private readonly routeRendererFactory: ExplicitViewRendererResolver;
+	private readonly staticRoutes: StaticRoute[];
+
+	constructor({ appConfig, routeRendererFactory, staticRoutes }: ExplicitStaticRouteMatcherOptions) {
+		this.appConfig = appConfig;
+		this.routeRendererFactory = routeRendererFactory;
+		this.staticRoutes = staticRoutes;
+	}
+
+	/**
+	 * Match a request URL against explicit static routes.
+	 * Returns the matched route and extracted params, or null if no match.
+	 */
+	match(url: string): ExplicitRouteMatch | null {
+		const pathname = new URL(url).pathname;
+
+		for (const route of this.staticRoutes) {
+			const params = this.matchRoute(route.path, pathname);
+			if (params !== null) {
+				return { route, params };
+			}
+		}
+
+		return null;
+	}
+
+	/**
+	 * Match a route pattern against a pathname.
+	 * Supports :param and [param] syntax.
+	 * Returns extracted params or null if no match.
+	 */
+	private matchRoute(pattern: string, pathname: string): Record<string, string> | null {
+		const patternSegments = pattern.split('/').filter(Boolean);
+		const pathSegments = pathname.split('/').filter(Boolean);
+
+		if (patternSegments.length !== pathSegments.length) {
+			const lastPattern = patternSegments[patternSegments.length - 1];
+			const isCatchAll = lastPattern?.startsWith('[...') || lastPattern?.startsWith(':...');
+			if (!isCatchAll) {
+				return null;
+			}
+		}
+
+		const params: Record<string, string> = {};
+
+		for (let i = 0; i < patternSegments.length; i++) {
+			const patternPart = patternSegments[i];
+			const pathPart = pathSegments[i];
+
+			if (patternPart.startsWith(':...') || patternPart.startsWith('[...')) {
+				const paramName = patternPart.replace(/^(:\.\.\.|\[\.\.\.)/, '').replace(/\]$/, '');
+				params[paramName] = pathSegments.slice(i).join('/');
+				return params;
+			}
+
+			if (patternPart.startsWith(':')) {
+				const paramName = patternPart.slice(1);
+				params[paramName] = pathPart;
+			} else if (patternPart.startsWith('[') && patternPart.endsWith(']')) {
+				const paramName = patternPart.slice(1, -1);
+				params[paramName] = pathPart;
+			} else if (patternPart !== pathPart) {
+				return null;
+			}
+		}
+
+		return params;
+	}
+
+	/**
+	 * Handle a matched explicit static route.
+	 * Resolves the loader and renders the view using the appropriate integration renderer.
+	 */
+	async handleMatch(match: ExplicitRouteMatch): Promise<Response> {
+		const { route, params } = match;
+
+		try {
+			const mod = await route.loader();
+			const view = mod.default;
+			const {
+				renderer,
+				props,
+				view: renderableView,
+			} = await prepareExplicitStaticRender({
+				routePath: route.path,
+				view,
+				params,
+				appConfig: this.appConfig,
+				runtimeOrigin: this.appConfig.baseUrl,
+				routeRendererFactory: this.routeRendererFactory,
+				errors: EXPLICIT_STATIC_ROUTE_MATCHER_ERRORS,
+			});
+
+			return renderer.renderToResponse(renderableView, props, {});
+		} catch (error) {
+			appLogger.error(
+				`Error rendering explicit static route ${route.path}:`,
+				error instanceof Error ? error : String(error),
+			);
+			throw error;
+		}
+	}
+}

package/src/adapters/shared/file-route-middleware-pipeline.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest';
+import type { FileRouteMiddleware } from '../../types/public-types.ts';
+import { LocalsAccessError } from '../../errors/locals-access-error.ts';
+import {
+	FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS,
+	FileRouteMiddlewarePipeline,
+} from './file-route-middleware-pipeline.ts';
+
+declare module '../../types/public-types.ts' {
+	interface RequestLocals {
+		user?: string;
+		first?: boolean;
+	}
+}
+
+describe('FileRouteMiddlewarePipeline', () => {
+	it('should reject middleware on non-dynamic pages', () => {
+		const service = new FileRouteMiddlewarePipeline(null);
+
+		expect(() =>
+			service.assertValidConfiguration({
+				middleware: [async (_ctx, next) => next()],
+				pageCacheStrategy: 'static',
+				filePath: '/app/pages/index.tsx',
+			}),
+		).toThrowError(
+			new LocalsAccessError(
+				FILE_ROUTE_MIDDLEWARE_PIPELINE_ERRORS.middlewareRequiresDynamic('/app/pages/index.tsx'),
+			),
+		);
+	});
+
+	it('should create middleware context without handler render methods', async () => {
+		const service = new FileRouteMiddlewarePipeline(null);
+		const context = service.createContext({
+			request: new Request('http://localhost:3000/hello'),
+			params: { slug: 'hello' },
+			locals: { user: 'andee' },
+		});
+
+		expect('render' in context).toBe(false);
+		expect('renderPartial' in context).toBe(false);
+
+		expect(context.require('user', () => new Response('missing', { status: 500 }))).toBe('andee');
+		expect(await context.html('<p>ok</p>').text()).toContain('<p>ok</p>');
+		expect(await context.json({ ok: true }).text()).toContain('{"ok":true}');
+	});
+
+	it('should execute middleware in order and eventually render the response', async () => {
+		const service = new FileRouteMiddlewarePipeline(null);
+		const context = service.createContext({
+			request: new Request('http://localhost:3000/hello'),
+			params: {},
+			locals: {},
+		});
+		const events: string[] = [];
+
+		const middleware: FileRouteMiddleware[] = [
+			async (ctx, next) => {
+				events.push('first:before');
+				ctx.locals.first = true;
+				const response = await next();
+				events.push('first:after');
+				return response;
+			},
+			async (ctx, next) => {
+				events.push('second');
+				expect(ctx.locals.first).toBe(true);
+				return next();
+			},
+		];
+
+		const response = await service.run({
+			middleware,
+			context,
+			renderResponse: async () => {
+				events.push('render');
+				return new Response('done');
+			},
+		});
+
+		expect(await response.text()).toBe('done');
+		expect(events).toEqual(['first:before', 'second', 'render', 'first:after']);
+	});
+});