@ecopages/core 0.2.0-alpha.4 → 0.2.0-alpha.6

package/src/router/server/fs-router.test.ts

@@ -0,0 +1,214 @@
+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 { Route, Routes } from '../../internal-types.js';
+import { FSRouter } from './fs-router.ts';
+import { FSRouterScanner } from './fs-router-scanner.ts';
+
+const {
+	templatesExt,
+	absolutePaths: { pagesDir, distDir },
+} = await new ConfigBuilder().setRootDir(FIXTURE_APP_PROJECT_DIR).build();
+
+const scanner = new FSRouterScanner({
+	dir: pagesDir,
+	appConfig: {
+		absolutePaths: {
+			distDir,
+		},
+	} as any,
+	origin: 'http://localhost:3000',
+	templatesExt,
+	options: {
+		buildMode: false,
+	},
+});
+
+const router = new FSRouter({
+	origin: 'http://localhost:3000',
+	assetPrefix: distDir,
+	scanner,
+});
+
+await router.init();
+
+describe('FSRouter', async () => {
+	describe('init', async () => {
+		test('should scan and return routes', async () => {
+			expect(Object.keys(router.routes).sort()).toEqual([
+				'http://localhost:3000/',
+				'http://localhost:3000/404',
+				'http://localhost:3000/catch-all/[...path]',
+				'http://localhost:3000/dynamic/another-blog-post',
+				'http://localhost:3000/dynamic/blog-post',
+				'http://localhost:3000/postcss-hmr',
+			]);
+		});
+	});
+
+	describe('getDynamicParams', async () => {
+		test.each([
+			['/products/[id]', '/products/123', { id: '123' }],
+			['/products/[id]', '/products/123/456', { id: '123' }],
+			['/products/[id]', '/products/123/456/789', { id: '123' }],
+		])(
+			'dynamic route %p with URL %p should have dynamic params %p',
+			async (dynamicPathname, pathname, expected) => {
+				const route: Route = {
+					filePath: '',
+					kind: 'dynamic',
+					pathname: dynamicPathname,
+				};
+				const params = router.getDynamicParams(route, pathname);
+
+				expect(params).toEqual(expected);
+			},
+		);
+
+		test.each([
+			['/products/[...id]', '/products/123/456/789', { id: ['123', '456', '789'] }],
+			['/products/[...id]', '/products/123', { id: ['123'] }],
+			['/products/[...id]', '/products', { id: [] }],
+		])(
+			'catch-all route %p with URL %p should have dynamic params %p',
+			async (catchAllRoute, pathname, expected) => {
+				const route: Route = {
+					filePath: '',
+					kind: 'dynamic',
+					pathname: catchAllRoute,
+				};
+				const params = router.getDynamicParams(route, pathname);
+
+				expect(params).toEqual(expected);
+			},
+		);
+	});
+
+	describe('getSearchParams', () => {
+		test('should extract query parameters from URL', () => {
+			const url = new URL('http://localhost:3000/page?foo=bar&baz=qux');
+			const params = router.getSearchParams(url);
+
+			expect(params).toEqual({ foo: 'bar', baz: 'qux' });
+		});
+
+		test('should return empty object for URL without query params', () => {
+			const url = new URL('http://localhost:3000/page');
+			const params = router.getSearchParams(url);
+
+			expect(params).toEqual({});
+		});
+	});
+
+	describe('match', () => {
+		const createRouterWithRoutes = (routes: Routes) => {
+			const Scanner = { scan: async () => routes } as unknown as FSRouterScanner;
+			const testRouter = new FSRouter({
+				origin: 'http://localhost:3000',
+				assetPrefix: '/dist',
+				scanner: Scanner,
+			});
+			testRouter.routes = routes;
+			return testRouter;
+		};
+
+		test('should match exact route', () => {
+			const testRouter = createRouterWithRoutes({
+				'/about': { filePath: '/pages/about.ts', kind: 'exact', pathname: '/about' },
+			});
+
+			const result = testRouter.match('http://localhost:3000/about');
+
+			expect(result).not.toBeNull();
+			expect(result?.kind).toBe('exact');
+			expect(result?.pathname).toBe('/about');
+		});
+
+		test('should match exact route with trailing slash', () => {
+			const testRouter = createRouterWithRoutes({
+				'/about': { filePath: '/pages/about.ts', kind: 'exact', pathname: '/about' },
+			});
+
+			const result = testRouter.match('http://localhost:3000/about/');
+
+			expect(result).not.toBeNull();
+			expect(result?.kind).toBe('exact');
+		});
+
+		test('should match dynamic route', () => {
+			const testRouter = createRouterWithRoutes({
+				'/dynamic/[id]': { filePath: '/pages/dynamic/[id].ts', kind: 'dynamic', pathname: '/dynamic/[id]' },
+			});
+
+			const result = testRouter.match('http://localhost:3000/dynamic/123');
+
+			expect(result).not.toBeNull();
+			expect(result?.kind).toBe('dynamic');
+			expect(result?.params).toEqual({ id: '123' });
+		});
+
+		test('should match catch-all route', () => {
+			const testRouter = createRouterWithRoutes({
+				'/catch-all/[...slug]': {
+					filePath: '/pages/catch-all/[...slug].ts',
+					kind: 'catch-all',
+					pathname: '/catch-all/[...slug]',
+				},
+			});
+
+			const result = testRouter.match('http://localhost:3000/catch-all/a/b/c');
+
+			expect(result).not.toBeNull();
+			expect(result?.kind).toBe('catch-all');
+			expect(result?.params).toEqual({ slug: ['a', 'b', 'c'] });
+		});
+
+		test('should include query params in match result', () => {
+			const testRouter = createRouterWithRoutes({
+				'/page': { filePath: '/pages/page.ts', kind: 'exact', pathname: '/page' },
+			});
+
+			const result = testRouter.match('http://localhost:3000/page?sort=asc&page=2');
+
+			expect(result?.query).toEqual({ sort: 'asc', page: '2' });
+		});
+
+		test('should return null for non-matching route', () => {
+			const testRouter = createRouterWithRoutes({
+				'/about': { filePath: '/pages/about.ts', kind: 'exact', pathname: '/about' },
+			});
+
+			const result = testRouter.match('http://localhost:3000/contact');
+
+			expect(result).toBeNull();
+		});
+
+		test('should prefer exact match over dynamic', () => {
+			const testRouter = createRouterWithRoutes({
+				'/blog/latest': { filePath: '/pages/blog/latest.ts', kind: 'exact', pathname: '/blog/latest' },
+				'/blog/[slug]': { filePath: '/pages/blog/[slug].ts', kind: 'dynamic', pathname: '/blog/[slug]' },
+			});
+
+			const result = testRouter.match('http://localhost:3000/blog/latest');
+
+			expect(result?.kind).toBe('exact');
+		});
+	});
+
+	describe('setOnReload and reload', () => {
+		test('should set and call onReload callback', async () => {
+			const Scanner = { scan: async () => ({}) } as unknown as FSRouterScanner;
+			const testRouter = new FSRouter({
+				origin: 'http://localhost:3000',
+				assetPrefix: '/dist',
+				scanner: Scanner,
+			});
+
+			const callback = vi.fn(() => {});
+			testRouter.setOnReload(callback);
+			testRouter.reload();
+
+			expect(callback).toHaveBeenCalledTimes(1);
+		});
+	});
+});

package/src/router/{fs-router.ts → server/fs-router.ts}

@@ -1,5 +1,5 @@
-import { appLogger } from '../global/app-logger.ts';
-import type { MatchResult, Route, Routes } from '../internal-types.ts';
+import { appLogger } from '../../global/app-logger.js';
+import type { MatchResult, Route, Routes } from '../../internal-types.js';
 import type { FSRouterScanner } from './fs-router-scanner.ts';
 
 /**

package/src/services/README.md

@@ -0,0 +1,29 @@
+# Core Services
+
+This directory contains the app-owned service layer used by runtime startup, rendering, asset processing, browser bundling, and development invalidation.
+
+## Purpose
+
+Services in this directory exist to keep cross-cutting framework logic out of adapters, integrations, and processors.
+
+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
+
+## Main Areas
+
+- `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-manifest/`: node runtime manifest derivation and persistence
+- `html/`: final HTML dependency injection and rewriter selection
+
+## Design Rule
+
+If a concern affects more than one integration or more than one runtime adapter, it usually belongs here instead of in a package-specific implementation.

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

@@ -0,0 +1,385 @@
+import { afterEach, beforeEach, expect, test, vi } from 'vitest';
+import { fileSystem } from '@ecopages/file-system';
+import { AssetProcessingService } from './asset-processing.service';
+import type { AssetDefinition } from './assets.types';
+
+const Config = {
+	absolutePaths: {
+		distDir: '/test/dist',
+	},
+} as any;
+
+const Processor = {
+	process: async () => ({
+		filepath: '/test/dist/assets/test.js',
+		kind: 'script',
+		inline: false,
+	}),
+};
+
+const originalEnsureDirectoryExists = fileSystem.ensureDir;
+const originalGzipDir = fileSystem.gzipDir;
+const originalWrite = fileSystem.write;
+const originalReadFileSync = fileSystem.readFileSync;
+const originalRemove = fileSystem.remove;
+const originalExists = fileSystem.exists;
+
+beforeEach(() => {
+	fileSystem.ensureDir = vi.fn(() => {});
+	fileSystem.gzipDir = vi.fn(() => {});
+	fileSystem.write = vi.fn(() => {});
+	fileSystem.readFileSync = vi.fn(() => Buffer.from('') as any);
+	fileSystem.remove = vi.fn(() => {});
+	fileSystem.exists = vi.fn(() => false);
+});
+
+afterEach(() => {
+	fileSystem.ensureDir = originalEnsureDirectoryExists;
+	fileSystem.gzipDir = originalGzipDir;
+	fileSystem.write = originalWrite;
+	fileSystem.readFileSync = originalReadFileSync;
+	fileSystem.remove = originalRemove;
+	fileSystem.exists = originalExists;
+	vi.restoreAllMocks();
+});
+
+test('AssetProcessingService - registerProcessor', () => {
+	const service = new AssetProcessingService(Config);
+	service.registerProcessor('script', 'file', Processor);
+	expect(service.getRegistry().getProcessor('script', 'file')).toBeDefined();
+});
+
+test('AssetProcessingService - processDependencies', async () => {
+	const service = AssetProcessingService.createWithDefaultProcessors(Config);
+	const results = await service.processDependencies(
+		[
+			{
+				kind: 'script',
+				source: 'content',
+				content: 'console.log("test")',
+				bundle: false,
+			} as AssetDefinition,
+		],
+		'test-key',
+	);
+
+	expect(results.length).toBe(1);
+	expect((results[0] as any).key).toBe('test-key');
+});
+
+test('AssetProcessingService - createWithDefaultProcessors', () => {
+	const service = AssetProcessingService.createWithDefaultProcessors(Config);
+	expect([...service.getRegistry().getAllProcessors().values()].length).toBeGreaterThan(0);
+});
+
+test('AssetProcessingService - processDependencies - success', async () => {
+	const ensureDirMock = vi.fn(() => {});
+	const gzipDirMock = vi.fn(() => {});
+	fileSystem.ensureDir = ensureDirMock;
+	fileSystem.gzipDir = gzipDirMock;
+	fileSystem.exists = vi.fn(() => true);
+
+	const service = new AssetProcessingService(Config);
+	const Processor1 = {
+		process: vi.fn(async () => ({
+			filepath: '/test/dist/assets/script.js',
+			kind: 'script',
+			inline: false,
+		})),
+	};
+	const Processor2 = {
+		process: vi.fn(async () => ({
+			filepath: '/test/dist/assets/style.css',
+			kind: 'stylesheet',
+			inline: false,
+		})),
+	};
+	service.registerProcessor('script', 'file', Processor1);
+	service.registerProcessor('stylesheet', 'file', Processor2);
+
+	const dependencies: AssetDefinition[] = [
+		{ kind: 'script', source: 'file', filepath: 'path/to/script.js' },
+		{ kind: 'stylesheet', source: 'file', filepath: 'path/to/style.css' },
+	];
+	const key = 'test-page';
+
+	const results = await service.processDependencies(dependencies, key);
+
+	expect(ensureDirMock).toHaveBeenCalledWith('/test/dist/assets');
+	expect(Processor1.process).toHaveBeenCalledTimes(1);
+	expect(Processor2.process).toHaveBeenCalledTimes(1);
+	expect(results.length).toBe(2);
+
+	expect(results[0]).toEqual(
+		expect.objectContaining({
+			filepath: '/test/dist/assets/script.js',
+			kind: 'script',
+			inline: false,
+			srcUrl: '/assets/script.js',
+		}),
+	);
+	expect(results[1]).toEqual(
+		expect.objectContaining({
+			filepath: '/test/dist/assets/style.css',
+			kind: 'stylesheet',
+			inline: false,
+			srcUrl: '/assets/style.css',
+		}),
+	);
+
+	expect(gzipDirMock).not.toHaveBeenCalled();
+});
+
+test('AssetProcessingService - processDependencies - processor not found', async () => {
+	const ensureDirMock = vi.fn(() => {});
+	const gzipDirMock = vi.fn(() => {});
+
+	fileSystem.ensureDir = ensureDirMock;
+	fileSystem.gzipDir = gzipDirMock;
+
+	const service = new AssetProcessingService(Config);
+
+	const dependencies: AssetDefinition[] = [{ kind: 'script', source: 'content', content: 'alert(1)' }];
+	const key = 'test-key-missing';
+
+	const results = await service.processDependencies(dependencies, key);
+
+	expect(ensureDirMock).toHaveBeenCalledWith('/test/dist/assets');
+	expect(results.length).toBe(0);
+	expect(gzipDirMock).not.toHaveBeenCalled();
+});
+
+test('AssetProcessingService - processDependencies - error during processing', async () => {
+	const ensureDirMock = vi.fn(() => {});
+	const gzipDirMock = vi.fn(() => {});
+	fileSystem.ensureDir = ensureDirMock;
+	fileSystem.gzipDir = gzipDirMock;
+	fileSystem.exists = vi.fn(() => true);
+
+	const service = new AssetProcessingService(Config);
+	const erroringProcessor = {
+		process: vi.fn(async () => {
+			throw new Error('Processing failed!');
+		}),
+	};
+	service.registerProcessor('script', 'file', erroringProcessor);
+
+	const dependency: AssetDefinition = {
+		kind: 'script',
+		source: 'file',
+		filepath: 'path/to/failing.js',
+	};
+	const key = 'test-key-error';
+
+	const results = await service.processDependencies([dependency], key);
+
+	expect(ensureDirMock).toHaveBeenCalledWith('/test/dist/assets');
+	expect(erroringProcessor.process).toHaveBeenCalledTimes(1);
+	expect(results.length).toBe(0);
+	expect(gzipDirMock).not.toHaveBeenCalled();
+});
+
+test('AssetProcessingService - processDependencies - handles undefined filepath for srcUrl', async () => {
+	const ensureDirMock = vi.fn(() => {});
+	const gzipDirMock = vi.fn(() => {});
+	fileSystem.ensureDir = ensureDirMock;
+	fileSystem.gzipDir = gzipDirMock;
+
+	const service = new AssetProcessingService(Config);
+	const ProcessorInline = {
+		process: vi.fn(async () => ({
+			kind: 'script',
+			inline: true,
+			content: 'console.log("inline");',
+		})),
+	};
+	service.registerProcessor('script', 'content', ProcessorInline);
+
+	const dependencies: AssetDefinition[] = [
+		{ kind: 'script', source: 'content', content: 'console.log("inline");', inline: true },
+	];
+	const key = 'test-inline';
+
+	const results = await service.processDependencies(dependencies, key);
+
+	expect(ensureDirMock).toHaveBeenCalledWith('/test/dist/assets');
+	expect(ProcessorInline.process).toHaveBeenCalledTimes(1);
+	expect(results.length).toBe(1);
+
+	expect(results[0]).toEqual(
+		expect.objectContaining({
+			kind: 'script',
+			inline: true,
+			content: 'console.log("inline");',
+			srcUrl: undefined,
+		}),
+	);
+
+	expect(gzipDirMock).not.toHaveBeenCalled();
+});
+
+test('AssetProcessingService - processDependencies - normalizes absolute srcUrl to public assets path', async () => {
+	fileSystem.ensureDir = vi.fn(() => {});
+	fileSystem.gzipDir = vi.fn(() => {});
+	fileSystem.exists = vi.fn(() => true);
+
+	const service = new AssetProcessingService(Config);
+	const processor = {
+		process: vi.fn(async () => ({
+			srcUrl: '/test/dist/assets/scripts/module--tanstack-react-table.js',
+			kind: 'script',
+			inline: false,
+		})),
+	};
+	service.registerProcessor('script', 'file', processor);
+
+	const dependency: AssetDefinition = { kind: 'script', source: 'file', filepath: 'path/to/module.js' };
+
+	const results = await service.processDependencies([dependency], 'normalize-src-url-key');
+
+	expect(processor.process).toHaveBeenCalledTimes(1);
+	expect(results.length).toBe(1);
+	expect(results[0].srcUrl).toBe('/assets/scripts/module--tanstack-react-table.js');
+});
+
+test('AssetProcessingService - caching returns cached asset without reprocessing', async () => {
+	fileSystem.ensureDir = vi.fn(() => {});
+	fileSystem.gzipDir = vi.fn(() => {});
+	fileSystem.exists = vi.fn(() => true);
+
+	const service = new AssetProcessingService(Config);
+	const processMock = vi.fn(async () => ({
+		filepath: '/test/dist/assets/cached.js',
+		kind: 'script',
+		inline: false,
+	}));
+	service.registerProcessor('script', 'file', { process: processMock });
+
+	const dependency: AssetDefinition = { kind: 'script', source: 'file', filepath: 'path/to/cached.js' };
+
+	const results1 = await service.processDependencies([dependency], 'key1');
+	const results2 = await service.processDependencies([dependency], 'key2');
+
+	expect(processMock).toHaveBeenCalledTimes(1);
+	expect(results1.length).toBe(1);
+	expect(results2.length).toBe(1);
+	expect(results1[0].srcUrl).toBe('/assets/cached.js');
+	expect(results2[0].srcUrl).toBe('/assets/cached.js');
+});
+
+test('AssetProcessingService - stale cached emitted files are rebuilt when output is missing', async () => {
+	fileSystem.ensureDir = vi.fn(() => {});
+	fileSystem.gzipDir = vi.fn(() => {});
+	const existsMock = vi
+		.fn()
+		.mockImplementationOnce(() => true)
+		.mockImplementationOnce(() => false)
+		.mockImplementation(() => true);
+	fileSystem.exists = existsMock;
+
+	const service = new AssetProcessingService(Config);
+	const processMock = vi.fn(async () => ({
+		filepath: '/test/dist/assets/stale.js',
+		kind: 'script',
+		inline: false,
+	}));
+	service.registerProcessor('script', 'file', { process: processMock });
+
+	const dependency: AssetDefinition = { kind: 'script', source: 'file', filepath: 'path/to/stale.js' };
+
+	await service.processDependencies([dependency], 'key1');
+	await service.processDependencies([dependency], 'key2');
+
+	expect(processMock).toHaveBeenCalledTimes(2);
+});
+
+test('AssetProcessingService - deduplication processes duplicate deps only once', async () => {
+	fileSystem.ensureDir = vi.fn(() => {});
+	fileSystem.gzipDir = vi.fn(() => {});
+	fileSystem.exists = vi.fn(() => true);
+
+	const service = new AssetProcessingService(Config);
+	const processMock = vi.fn(async () => ({
+		filepath: '/test/dist/assets/dedup.js',
+		kind: 'script',
+		inline: false,
+	}));
+	service.registerProcessor('script', 'file', { process: processMock });
+
+	const dependency: AssetDefinition = { kind: 'script', source: 'file', filepath: 'path/to/dedup.js' };
+	const duplicateDeps = [dependency, dependency, dependency];
+
+	const results = await service.processDependencies(duplicateDeps, 'dedup-key');
+
+	expect(processMock).toHaveBeenCalledTimes(1);
+	expect(results.length).toBe(1);
+});
+
+test('AssetProcessingService - clearCache clears all cached assets', async () => {
+	fileSystem.ensureDir = vi.fn(() => {});
+	fileSystem.gzipDir = vi.fn(() => {});
+	fileSystem.exists = vi.fn(() => true);
+
+	const service = new AssetProcessingService(Config);
+	const processMock = vi.fn(async () => ({
+		filepath: '/test/dist/assets/clear.js',
+		kind: 'script',
+		inline: false,
+	}));
+	service.registerProcessor('script', 'file', { process: processMock });
+
+	const dependency: AssetDefinition = { kind: 'script', source: 'file', filepath: 'path/to/clear.js' };
+
+	await service.processDependencies([dependency], 'key1');
+	expect(processMock).toHaveBeenCalledTimes(1);
+
+	service.clearCache();
+
+	await service.processDependencies([dependency], 'key2');
+	expect(processMock).toHaveBeenCalledTimes(2);
+});
+
+test('AssetProcessingService - invalidateCacheForFile removes specific file from cache', async () => {
+	fileSystem.ensureDir = vi.fn(() => {});
+	fileSystem.gzipDir = vi.fn(() => {});
+	fileSystem.exists = vi.fn(() => true);
+
+	const service = new AssetProcessingService(Config);
+	const processMock = vi.fn(async () => ({
+		filepath: '/test/dist/assets/invalidate.js',
+		kind: 'script',
+		inline: false,
+	}));
+	service.registerProcessor('script', 'file', { process: processMock });
+
+	const dependency: AssetDefinition = { kind: 'script', source: 'file', filepath: 'path/to/invalidate.js' };
+
+	await service.processDependencies([dependency], 'key1');
+	expect(processMock).toHaveBeenCalledTimes(1);
+
+	service.invalidateCacheForFile('/test/dist/assets/invalidate.js');
+
+	await service.processDependencies([dependency], 'key2');
+	expect(processMock).toHaveBeenCalledTimes(2);
+});
+
+test('AssetProcessingService - skips missing file dependencies', async () => {
+	fileSystem.ensureDir = vi.fn(() => {});
+	fileSystem.gzipDir = vi.fn(() => {});
+	fileSystem.exists = vi.fn(() => false);
+
+	const service = new AssetProcessingService(Config);
+	const processMock = vi.fn(async () => ({
+		filepath: '/test/dist/assets/missing.js',
+		kind: 'script',
+		inline: false,
+	}));
+	service.registerProcessor('script', 'file', { process: processMock });
+
+	const dependency: AssetDefinition = { kind: 'script', source: 'file', filepath: 'path/to/missing.js' };
+
+	const results = await service.processDependencies([dependency], 'missing-key');
+
+	expect(processMock).not.toHaveBeenCalled();
+	expect(results.length).toBe(0);
+});