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

package/src/router/server/route-registry.test.ts

@@ -0,0 +1,176 @@
+import { describe, expect, test, vi } from 'vitest';
+import { FIXTURE_APP_PROJECT_DIR } from '../../../__fixtures__/constants.js';
+import { ConfigBuilder } from '../../config/config-builder.js';
+import type { EcoPagesAppConfig } from '../../types/internal-types.js';
+import { RouteRegistry, type RouteRegistryPageModuleAdapter, type TemplateRoute } from './route-registry.ts';
+
+const {
+	templatesExt,
+	absolutePaths: { pagesDir },
+	...appConfig
+} = await new ConfigBuilder().setRootDir(FIXTURE_APP_PROJECT_DIR).build();
+
+const createRegistry = (overrides?: Partial<ConstructorParameters<typeof RouteRegistry>[0]>) =>
+	new RouteRegistry({
+		pagesDir,
+		appConfig: appConfig as EcoPagesAppConfig,
+		origin: 'http://localhost:3000',
+		templatesExt,
+		buildMode: false,
+		pageModuleAdapter: {
+			loadPageModule: vi.fn(async () => ({})),
+		},
+		...overrides,
+	});
+
+describe('RouteRegistry', () => {
+	test('discovers canonical template routes', async () => {
+		const registry = createRegistry();
+
+		await registry.init();
+
+		expect(registry.templateRoutes.map((route) => route.pathname)).toEqual([
+			'/',
+			'/404',
+			'/postcss-hmr',
+			'/dynamic/[slug]',
+			'/catch-all/[...path]',
+		]);
+	});
+
+	test.each([
+		['/products/[id]', '/products/123', { id: '123' }],
+		['/products/[...id]', '/products/123/456/789', { id: ['123', '456', '789'] }],
+	])('matches template route %p against request %p', async (pathname, requestPathname, expectedParams) => {
+		const registry = createRegistry();
+		await registry.init();
+
+		(registry as unknown as { templateRouteList: TemplateRoute[] }).templateRouteList = [
+			{
+				pathname,
+				kind: pathname.includes('[...') ? 'catch-all' : 'dynamic',
+				filePath: '/pages/example.ts',
+				paramNames: [],
+			},
+		];
+
+		const result = registry.matchRequest(`http://localhost:3000${requestPathname}`);
+
+		expect(result?.params).toEqual(expectedParams);
+		expect(result?.templateRoute.pathname).toBe(pathname);
+		expect(result?.requestedPathname).toBe(requestPathname);
+	});
+
+	test('includes query parameters in match results', async () => {
+		const registry = createRegistry();
+		await registry.init();
+
+		(registry as unknown as { templateRouteList: TemplateRoute[] }).templateRouteList = [
+			{ pathname: '/page', kind: 'exact', filePath: '/pages/page.ts', paramNames: [] },
+		];
+
+		const result = registry.matchRequest('http://localhost:3000/page?sort=asc&page=2');
+
+		expect(result?.query).toEqual({ sort: 'asc', page: '2' });
+	});
+
+	test('prefers exact routes over dynamic routes', async () => {
+		const registry = createRegistry();
+		await registry.init();
+
+		(registry as unknown as { templateRouteList: TemplateRoute[] }).templateRouteList = [
+			{ pathname: '/blog/latest', kind: 'exact', filePath: '/pages/blog/latest.ts', paramNames: [] },
+			{ pathname: '/blog/[slug]', kind: 'dynamic', filePath: '/pages/blog/[slug].ts', paramNames: ['slug'] },
+		];
+
+		const result = registry.matchRequest('http://localhost:3000/blog/latest');
+
+		expect(result?.templateRoute.kind).toBe('exact');
+	});
+
+	test('fires reload listeners after reload', async () => {
+		const registry = createRegistry();
+		const listener = vi.fn();
+
+		registry.onReload(listener);
+		await registry.reload();
+
+		expect(listener).toHaveBeenCalledTimes(1);
+	});
+
+	test('lists static path expansions lazily through the page module adapter', async () => {
+		const pageModuleAdapter: RouteRegistryPageModuleAdapter = {
+			loadPageModule: vi.fn(async () => ({
+				staticProps: {},
+				staticPaths: async () => ({ paths: [{ params: { slug: 'hello-world' } }] }),
+			})),
+		};
+
+		const registry = createRegistry({ pageModuleAdapter, buildMode: true });
+		await registry.init();
+
+		(registry as unknown as { templateRouteList: TemplateRoute[] }).templateRouteList = [
+			{ pathname: '/blog/[slug]', kind: 'dynamic', filePath: '/pages/blog/[slug].ts', paramNames: ['slug'] },
+		];
+
+		const expansions = await registry.listStaticPathExpansions({ runtimeOrigin: 'http://localhost:3000' });
+
+		expect(expansions).toEqual([
+			{
+				pathname: '/blog/hello-world',
+				templateRoute: {
+					pathname: '/blog/[slug]',
+					kind: 'dynamic',
+					filePath: '/pages/blog/[slug].ts',
+					paramNames: ['slug'],
+				},
+				params: { slug: 'hello-world' },
+			},
+		]);
+		expect(pageModuleAdapter.loadPageModule).toHaveBeenCalledWith('/pages/blog/[slug].ts');
+	});
+
+	test('lists static-generation routes through one registry seam', async () => {
+		const pageModuleAdapter: RouteRegistryPageModuleAdapter = {
+			loadPageModule: vi.fn(async () => ({
+				staticProps: {},
+				staticPaths: async () => ({ paths: [{ params: { slug: 'hello-world' } }] }),
+			})),
+		};
+
+		const registry = createRegistry({ pageModuleAdapter, buildMode: true });
+		await registry.init();
+
+		(registry as unknown as { templateRouteList: TemplateRoute[] }).templateRouteList = [
+			{ pathname: '/', kind: 'exact', filePath: '/pages/index.ts', paramNames: [] },
+			{ pathname: '/blog/[slug]', kind: 'dynamic', filePath: '/pages/blog/[slug].ts', paramNames: ['slug'] },
+		];
+
+		const routes = await registry.listStaticGenerationRoutes({ runtimeOrigin: 'http://localhost:3000' });
+
+		expect(routes).toEqual([
+			{
+				requestUrl: 'http://localhost:3000/',
+				pathname: '/',
+				templateRoute: {
+					pathname: '/',
+					kind: 'exact',
+					filePath: '/pages/index.ts',
+					paramNames: [],
+				},
+				params: {},
+			},
+			{
+				requestUrl: 'http://localhost:3000/blog/hello-world',
+				pathname: '/blog/hello-world',
+				templateRoute: {
+					pathname: '/blog/[slug]',
+					kind: 'dynamic',
+					filePath: '/pages/blog/[slug].ts',
+					paramNames: ['slug'],
+				},
+				params: { slug: 'hello-world' },
+			},
+		]);
+	});
+});

package/src/router/server/route-registry.ts

@@ -0,0 +1,382 @@
+import path from 'node:path';
+import { existsSync } from 'node:fs';
+import { fileSystem } from '@ecopages/file-system';
+import { appLogger } from '../../global/app-logger.ts';
+import type { EcoPagesAppConfig, RouteKind } from '../../types/internal-types.ts';
+import { invariant } from '../../utils/invariant.ts';
+
+export type RouteParams = Record<string, string | string[]>;
+export type RouteQuery = Record<string, string>;
+
+export type TemplateRoute = {
+	readonly pathname: string;
+	readonly kind: RouteKind;
+	readonly filePath: string;
+	readonly paramNames: readonly string[];
+};
+
+export type RouteMatch = {
+	readonly requestedPathname: string;
+	readonly templateRoute: TemplateRoute;
+	readonly params: RouteParams;
+	readonly query: RouteQuery;
+};
+
+export type StaticPathExpansion = {
+	readonly pathname: string;
+	readonly templateRoute: TemplateRoute;
+	readonly params: RouteParams;
+};
+
+export type StaticGenerationRoute = {
+	readonly requestUrl: string;
+	readonly pathname: string;
+	readonly templateRoute: TemplateRoute;
+	readonly params: RouteParams;
+};
+
+export type StaticPathsContext = {
+	readonly appConfig: EcoPagesAppConfig;
+	readonly runtimeOrigin: string;
+};
+
+export type RouteRegistryPageModule = {
+	readonly staticPaths?: (context: StaticPathsContext) => Promise<{
+		paths: Array<{ params: RouteParams }>;
+	}>;
+	readonly staticProps?: unknown;
+};
+
+export interface RouteRegistryPageModuleAdapter {
+	loadPageModule(filePath: string): Promise<RouteRegistryPageModule>;
+}
+
+export type RouteRegistryOptions = {
+	pagesDir: string;
+	appConfig: EcoPagesAppConfig;
+	origin: string;
+	templatesExt: readonly string[];
+	buildMode: boolean;
+	pageModuleAdapter: RouteRegistryPageModuleAdapter;
+};
+
+const ROUTE_PRIORITY: Record<RouteKind, number> = {
+	exact: 0,
+	dynamic: 1,
+	'catch-all': 2,
+};
+
+export class RouteRegistry {
+	readonly origin: string;
+	readonly appConfig: EcoPagesAppConfig;
+	readonly pagesDir: string;
+	readonly templatesExt: readonly string[];
+	readonly buildMode: boolean;
+	private readonly pageModuleAdapter: RouteRegistryPageModuleAdapter;
+	private templateRouteList: TemplateRoute[] = [];
+	private readonly reloadListeners = new Set<() => void>();
+
+	constructor(options: RouteRegistryOptions) {
+		this.origin = options.origin;
+		this.appConfig = options.appConfig;
+		this.pagesDir = options.pagesDir;
+		this.templatesExt = options.templatesExt;
+		this.buildMode = options.buildMode;
+		this.pageModuleAdapter = options.pageModuleAdapter;
+	}
+
+	get templateRoutes(): readonly TemplateRoute[] {
+		return this.templateRouteList;
+	}
+
+	async init(): Promise<void> {
+		this.templateRouteList = await this.scanTemplateRoutes();
+		appLogger.debug('RouteRegistry initialized', this.templateRouteList);
+	}
+
+	async reload(): Promise<void> {
+		await this.init();
+
+		for (const listener of this.reloadListeners) {
+			listener();
+		}
+	}
+
+	onReload(listener: () => void): () => void {
+		this.reloadListeners.add(listener);
+		return () => {
+			this.reloadListeners.delete(listener);
+		};
+	}
+
+	matchRequest(requestUrl: string): RouteMatch | null {
+		const url = new URL(requestUrl);
+		const requestedPathname = normalizePathname(url.pathname);
+		const query = this.getSearchParams(url);
+
+		for (const route of this.templateRouteList) {
+			if (route.kind !== 'exact') {
+				continue;
+			}
+
+			if (requestedPathname === route.pathname || requestedPathname === `${route.pathname}/`) {
+				return {
+					requestedPathname,
+					templateRoute: route,
+					params: {},
+					query,
+				};
+			}
+		}
+
+		for (const route of this.templateRouteList) {
+			if (route.kind !== 'dynamic') {
+				continue;
+			}
+
+			const params = this.tryExtractParams(route, requestedPathname);
+			if (!params) {
+				continue;
+			}
+
+			return {
+				requestedPathname,
+				templateRoute: route,
+				params,
+				query,
+			};
+		}
+
+		for (const route of this.templateRouteList) {
+			if (route.kind !== 'catch-all') {
+				continue;
+			}
+
+			const params = this.tryExtractParams(route, requestedPathname);
+			if (!params) {
+				continue;
+			}
+
+			return {
+				requestedPathname,
+				templateRoute: route,
+				params,
+				query,
+			};
+		}
+
+		return null;
+	}
+
+	async listStaticPathExpansions(input: { runtimeOrigin: string }): Promise<readonly StaticPathExpansion[]> {
+		const expansions: StaticPathExpansion[] = [];
+
+		for (const route of this.templateRouteList) {
+			if (route.kind === 'exact') {
+				continue;
+			}
+
+			const pageModule = await this.pageModuleAdapter.loadPageModule(route.filePath);
+			const staticPaths = pageModule.staticPaths;
+
+			if (this.buildMode) {
+				invariant(staticPaths !== undefined, `[ecopages] Missing getStaticPaths in ${route.filePath}`);
+				invariant(
+					pageModule.staticProps !== undefined,
+					`[ecopages] Missing getStaticProps in ${route.filePath}`,
+				);
+			}
+
+			if (!staticPaths) {
+				continue;
+			}
+
+			const result = await staticPaths({
+				appConfig: this.appConfig,
+				runtimeOrigin: input.runtimeOrigin,
+			});
+
+			for (const { params } of result.paths) {
+				expansions.push({
+					pathname: this.resolveTemplatePath(route.pathname, params),
+					templateRoute: route,
+					params,
+				});
+			}
+		}
+
+		return expansions;
+	}
+
+	async listStaticGenerationRoutes(input: { runtimeOrigin: string }): Promise<readonly StaticGenerationRoute[]> {
+		const staticPathExpansions = await this.listStaticPathExpansions(input);
+
+		return [
+			...this.templateRouteList
+				.filter((route) => route.kind === 'exact')
+				.map((route) => ({
+					requestUrl: `${input.runtimeOrigin}${route.pathname}`,
+					pathname: route.pathname,
+					templateRoute: route,
+					params: {},
+				})),
+			...staticPathExpansions.map((route) => ({
+				requestUrl: `${input.runtimeOrigin}${route.pathname}`,
+				pathname: route.pathname,
+				templateRoute: route.templateRoute,
+				params: route.params,
+			})),
+		];
+	}
+
+	private async scanTemplateRoutes(): Promise<TemplateRoute[]> {
+		if (!existsSync(this.pagesDir)) {
+			return [];
+		}
+
+		const scannedFiles = await fileSystem.glob(
+			this.templatesExt.map((ext) => `**/*${ext}`),
+			{
+				cwd: this.pagesDir,
+			},
+		);
+
+		const templateRoutes: TemplateRoute[] = [];
+
+		for await (const file of scannedFiles) {
+			if (file.includes('.ecopages-node.')) {
+				continue;
+			}
+
+			const routePathname = this.getRoutePath(file);
+			const filePath = path.join(this.pagesDir, file);
+			const kind = this.classifyRouteKind(filePath);
+
+			templateRoutes.push({
+				pathname: routePathname,
+				kind,
+				filePath,
+				paramNames: this.getParamNames(routePathname),
+			});
+		}
+
+		return templateRoutes.sort((left, right) => {
+			const priorityDifference = ROUTE_PRIORITY[left.kind] - ROUTE_PRIORITY[right.kind];
+			if (priorityDifference !== 0) {
+				return priorityDifference;
+			}
+
+			if (left.pathname === '/') {
+				return -1;
+			}
+
+			if (right.pathname === '/') {
+				return 1;
+			}
+
+			return left.pathname.localeCompare(right.pathname);
+		});
+	}
+
+	private getRoutePath(file: string): string {
+		const cleanedRoute = this.templatesExt
+			.reduce((route, ext) => route.replace(ext, ''), file)
+			.replace(/\/?index$/, '');
+
+		return normalizePathname(`/${cleanedRoute}`);
+	}
+
+	private classifyRouteKind(filePath: string): RouteKind {
+		if (filePath.includes('[...')) {
+			return 'catch-all';
+		}
+
+		if (filePath.includes('[') && filePath.includes(']')) {
+			return 'dynamic';
+		}
+
+		return 'exact';
+	}
+
+	private getParamNames(routePathname: string): string[] {
+		const matches = routePathname.match(/\[(?:\.\.\.)?([^\]]+)\]/g);
+		return matches ? matches.map((match) => match.replace(/^\[(?:\.\.\.)?/, '').replace(/\]$/, '')) : [];
+	}
+
+	private tryExtractParams(route: TemplateRoute, requestedPathname: string): RouteParams | null {
+		const routeParts = route.pathname.split('/');
+		const pathnameParts = requestedPathname.split('/');
+
+		if (route.kind === 'dynamic' && routeParts.length !== pathnameParts.length) {
+			return null;
+		}
+
+		const params: RouteParams = {};
+
+		for (let i = 0; i < routeParts.length; i++) {
+			const routePart = routeParts[i];
+			const pathnamePart = pathnameParts[i];
+
+			if (!routePart) {
+				continue;
+			}
+
+			if (routePart.startsWith('[...') && routePart.endsWith(']')) {
+				const paramName = routePart.slice(4, -1);
+				params[paramName] = pathnameParts.slice(i).filter(Boolean);
+				return params;
+			}
+
+			if (routePart.startsWith('[') && routePart.endsWith(']')) {
+				if (pathnamePart === undefined) {
+					return null;
+				}
+
+				params[routePart.slice(1, -1)] = pathnamePart;
+				continue;
+			}
+
+			if (routePart !== pathnamePart) {
+				return null;
+			}
+		}
+
+		if (route.kind === 'catch-all') {
+			const cleanPathname = route.pathname.replace(/\[.*?\]/g, '');
+			return requestedPathname.includes(cleanPathname) ? params : null;
+		}
+
+		return params;
+	}
+
+	private getSearchParams(url: URL): RouteQuery {
+		const query: RouteQuery = {};
+
+		for (const [key, value] of url.searchParams) {
+			query[key] = value;
+		}
+
+		return query;
+	}
+
+	private resolveTemplatePath(pathname: string, params: RouteParams): string {
+		let resolvedPath = pathname;
+
+		for (const [key, value] of Object.entries(params)) {
+			const serializedValue = Array.isArray(value) ? value.join('/') : value;
+			resolvedPath = resolvedPath.replace(`[...${key}]`, serializedValue);
+			resolvedPath = resolvedPath.replace(`[${key}]`, serializedValue);
+		}
+
+		return normalizePathname(resolvedPath);
+	}
+}
+
+function normalizePathname(pathname: string): string {
+	if (!pathname || pathname === '/') {
+		return '/';
+	}
+
+	const normalized = pathname.startsWith('/') ? pathname : `/${pathname}`;
+	return normalized.endsWith('/') ? normalized.slice(0, -1) : normalized;
+}

package/src/services/README.md

@@ -11,7 +11,6 @@ Typical responsibilities include:
 - server-module loading and transpilation
 - browser bundle coordination
 - asset processing and runtime asset declaration helpers
-- runtime specifier registry management
 - server invalidation state and entrypoint dependency graphs
 - HTML finalization and dependency injection
 
@@ -20,7 +19,7 @@ Typical responsibilities include:
 - `module-loading/`: framework-owned config/app bootstrap loading and server-side source loading
 - `assets/`: shared browser build coordination and processed asset pipelines
 - `invalidation/`: file-change classification and invalidation policy
-- `runtime-state/`: app-owned invalidation state, dependency graphs, and runtime specifier registry
+- `runtime-state/`: app-owned invalidation state and dependency graphs
 - `runtime-manifest/`: node runtime manifest derivation and persistence
 - `html/`: final HTML dependency injection and rewriter selection
 

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

@@ -63,4 +63,4 @@ export function deduplicateAssetDependencies(deps: AssetDefinition[]): AssetDefi
 	}
 
 	return Array.from(seen.values());
-}
+}

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

@@ -400,10 +400,7 @@ test('AssetProcessingService - grouped content scripts use processGrouped once p
 
 	expect(processGroupedMock).toHaveBeenCalledTimes(1);
 	expect(processMock).not.toHaveBeenCalled();
-	expect(results.map((result) => result.srcUrl)).toEqual([
-		'/assets/page-entry.js',
-		'/assets/lazy-entry.js',
-	]);
+	expect(results.map((result) => result.srcUrl)).toEqual(['/assets/page-entry.js', '/assets/lazy-entry.js']);
 });
 
 test('AssetProcessingService - clearCache clears all cached assets', async () => {

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

@@ -114,8 +114,7 @@ export class AssetProcessingService {
 					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),
+					setCachedAsset: (assetDep, depKey, processed) => this.setCachedAsset(assetDep, depKey, processed),
 					logMissingProcessor: (assetDep) => {
 						appLogger.error(`No processor found for ${assetDep.kind}/${assetDep.source}`);
 					},

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

@@ -16,6 +16,7 @@ export interface BaseAsset {
 	attributes?: Record<string, string>;
 	position?: AssetPosition;
 	packageRole?: AssetPackageRole;
+	bundledSourceFilepaths?: string[];
 }
 
 export interface ScriptAsset extends BaseAsset {
@@ -105,6 +106,7 @@ export interface JsonScriptAsset extends ScriptAsset {
 
 export type ProcessedAsset = {
 	filepath?: string;
+	sourceFilepath?: string;
 	srcUrl?: string;
 	content?: string;
 	kind: AssetKind;
@@ -114,6 +116,7 @@ export type ProcessedAsset = {
 	excludeFromHtml?: boolean;
 	packageRole?: AssetPackageRole;
 	groupedBundle?: GroupedScriptBundle;
+	bundledSourceFilepaths?: string[];
 };
 
 export type AssetDefinition =

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

@@ -101,4 +101,4 @@ export async function processGroupedDependencyBundles(
 	});
 
 	return (await Promise.all(groupedPromises)).flat();
-}
+}

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

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