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

package/src/errors/http-error.test.ts

@@ -0,0 +1,134 @@
+import { describe, expect, test } from 'vitest';
+import { HttpError } from './http-error.ts';
+
+describe('HttpError', () => {
+	describe('constructor', () => {
+		test('creates error with status and message', () => {
+			const error = new HttpError(400, 'Bad request');
+
+			expect(error).toBeInstanceOf(Error);
+			expect(error).toBeInstanceOf(HttpError);
+			expect(error.status).toBe(400);
+			expect(error.message).toBe('Bad request');
+			expect(error.name).toBe('HttpError');
+			expect(error.details).toBeUndefined();
+		});
+
+		test('creates error with details', () => {
+			const details = { field: 'email', reason: 'invalid format' };
+			const error = new HttpError(400, 'Validation failed', details);
+
+			expect(error.details).toEqual(details);
+		});
+	});
+
+	describe('toJSON', () => {
+		test('serializes error without details', () => {
+			const error = new HttpError(404, 'Not found');
+
+			expect(error.toJSON()).toEqual({
+				error: 'Not found',
+				status: 404,
+			});
+		});
+
+		test('serializes error with details', () => {
+			const details = { body: [{ path: ['title'], message: 'Required' }] };
+			const error = new HttpError(400, 'Validation failed', details);
+
+			expect(error.toJSON()).toEqual({
+				error: 'Validation failed',
+				status: 400,
+				details,
+			});
+		});
+	});
+
+	describe('toResponse', () => {
+		test('creates Response with correct status and body', async () => {
+			const error = new HttpError(403, 'Access denied');
+			const response = error.toResponse();
+
+			expect(response).toBeInstanceOf(Response);
+			expect(response.status).toBe(403);
+			expect(response.headers.get('content-type')).toContain('application/json');
+
+			const body = await response.json();
+			expect(body).toEqual({ error: 'Access denied', status: 403 });
+		});
+	});
+
+	describe('factory methods', () => {
+		test('BadRequest creates 400 error', () => {
+			const error = HttpError.BadRequest();
+			expect(error.status).toBe(400);
+			expect(error.message).toBe('Bad Request');
+		});
+
+		test('BadRequest accepts custom message and details', () => {
+			const details = { field: 'name' };
+			const error = HttpError.BadRequest('Invalid input', details);
+
+			expect(error.message).toBe('Invalid input');
+			expect(error.details).toEqual(details);
+		});
+
+		test('Unauthorized creates 401 error', () => {
+			const error = HttpError.Unauthorized();
+			expect(error.status).toBe(401);
+			expect(error.message).toBe('Unauthorized');
+		});
+
+		test('Unauthorized accepts custom message', () => {
+			const error = HttpError.Unauthorized('Token expired');
+			expect(error.message).toBe('Token expired');
+		});
+
+		test('Forbidden creates 403 error', () => {
+			const error = HttpError.Forbidden();
+			expect(error.status).toBe(403);
+			expect(error.message).toBe('Forbidden');
+		});
+
+		test('Forbidden accepts custom message', () => {
+			const error = HttpError.Forbidden('Admin access required');
+			expect(error.message).toBe('Admin access required');
+		});
+
+		test('NotFound creates 404 error', () => {
+			const error = HttpError.NotFound();
+			expect(error.status).toBe(404);
+			expect(error.message).toBe('Not Found');
+		});
+
+		test('NotFound accepts custom message', () => {
+			const error = HttpError.NotFound('Post not found');
+			expect(error.message).toBe('Post not found');
+		});
+
+		test('Conflict creates 409 error', () => {
+			const error = HttpError.Conflict();
+			expect(error.status).toBe(409);
+			expect(error.message).toBe('Conflict');
+		});
+
+		test('Conflict accepts custom message and details', () => {
+			const details = { resource: 'user', conflict: 'email already exists' };
+			const error = HttpError.Conflict('Resource conflict', details);
+
+			expect(error.message).toBe('Resource conflict');
+			expect(error.details).toEqual(details);
+		});
+
+		test('InternalServerError creates 500 error', () => {
+			const error = HttpError.InternalServerError();
+			expect(error.status).toBe(500);
+			expect(error.message).toBe('Internal Server Error');
+		});
+
+		test('InternalServerError accepts custom message', () => {
+			const error = HttpError.InternalServerError('Database connection failed');
+			expect(error.message).toBe('Database connection failed');
+		});
+	});
+});

package/src/errors/http-error.ts

@@ -0,0 +1,72 @@
+export interface HttpErrorDetails {
+	[key: string]: unknown;
+}
+
+export interface HttpErrorJson {
+	error: string;
+	status: number;
+	details?: HttpErrorDetails;
+}
+
+/**
+ * HTTP error class for structured error handling in route handlers.
+ * Provides static factory methods for common HTTP error responses.
+ */
+export class HttpError extends Error {
+	readonly status: number;
+	readonly details?: HttpErrorDetails;
+
+	constructor(status: number, message: string, details?: HttpErrorDetails) {
+		super(message);
+		this.name = 'HttpError';
+		this.status = status;
+		this.details = details;
+	}
+
+	/**
+	 * Serialize error to JSON for API responses.
+	 */
+	toJSON(): HttpErrorJson {
+		const json: HttpErrorJson = {
+			error: this.message,
+			status: this.status,
+		};
+
+		if (this.details) {
+			json.details = this.details;
+		}
+
+		return json;
+	}
+
+	/**
+	 * Create a Response object from this error.
+	 */
+	toResponse(): Response {
+		return Response.json(this.toJSON(), { status: this.status });
+	}
+
+	static BadRequest(message = 'Bad Request', details?: HttpErrorDetails): HttpError {
+		return new HttpError(400, message, details);
+	}
+
+	static Unauthorized(message = 'Unauthorized'): HttpError {
+		return new HttpError(401, message);
+	}
+
+	static Forbidden(message = 'Forbidden'): HttpError {
+		return new HttpError(403, message);
+	}
+
+	static NotFound(message = 'Not Found'): HttpError {
+		return new HttpError(404, message);
+	}
+
+	static Conflict(message = 'Conflict', details?: HttpErrorDetails): HttpError {
+		return new HttpError(409, message, details);
+	}
+
+	static InternalServerError(message = 'Internal Server Error'): HttpError {
+		return new HttpError(500, message);
+	}
+}

package/src/errors/index.ts

@@ -0,0 +1,3 @@
+export { HttpError } from './http-error.ts';
+export type { HttpErrorDetails, HttpErrorJson } from './http-error.ts';
+export { LocalsAccessError } from './locals-access-error.ts';

package/src/errors/locals-access-error.ts

@@ -0,0 +1,7 @@
+export class LocalsAccessError extends Error {
+	override name = 'LocalsAccessError';
+
+	constructor(message: string) {
+		super(message);
+	}
+}

package/src/global/app-logger.ts

@@ -0,0 +1,4 @@
+import { Logger } from '@ecopages/logger';
+
+const debug = process.env.ECOPAGES_LOGGER_DEBUG === 'true';
+export const appLogger = new Logger('[@ecopages/core]', { debug });

package/src/global/utils.test.ts

@@ -0,0 +1,12 @@
+import { describe, expect, test } from 'vitest';
+import { invariant } from '../utils/invariant.ts';
+
+describe('Utils', () => {
+	test('invariant should throw error when condition is falsy', () => {
+		expect(() => invariant(false, 'Test error')).toThrowError('[ecopages] Test error');
+	});
+
+	test('invariant should not throw error when condition is truthy', () => {
+		expect(() => invariant(true, 'Test error')).not.toThrow();
+	});
+});

package/src/hmr/client/hmr-runtime.ts

@@ -0,0 +1,162 @@
+/**
+ * Ecopages HMR Runtime
+ * Injected into the browser to handle Hot Module Replacement updates.
+ */
+
+import { getEcoNavigationRuntime } from '../../router/client/navigation-coordinator.ts';
+
+interface HMRPayload {
+	type: 'reload' | 'error' | 'update' | 'css-update' | 'layout-update';
+	path?: string;
+	message?: string;
+	timestamp?: number;
+}
+
+(function () {
+	const WS_URL = 'ws://' + location.host + '/_hmr';
+	let socket: WebSocket;
+	let reconnectAttempts = 0;
+
+	function connect() {
+		socket = new WebSocket(WS_URL);
+
+		socket.addEventListener('open', () => {
+			console.log('[ecopages] HMR Connected');
+			reconnectAttempts = 0;
+		});
+
+		socket.addEventListener('message', async (event) => {
+			try {
+				const payload: HMRPayload = JSON.parse(event.data);
+				handleMessage(payload);
+			} catch (e) {
+				console.error('[ecopages] Invalid HMR message:', e);
+			}
+		});
+
+		socket.addEventListener('close', () => {
+			if (reconnectAttempts < 10) {
+				setTimeout(connect, 1000 * 2 ** reconnectAttempts);
+				reconnectAttempts++;
+			}
+		});
+	}
+
+	async function handleMessage(payload: HMRPayload) {
+		const navigationRuntime = getEcoNavigationRuntime(window);
+
+		switch (payload.type) {
+			case 'reload':
+				await waitForNavigationToSettle(navigationRuntime);
+				location.reload();
+				break;
+			case 'layout-update': {
+				await waitForNavigationToSettle(navigationRuntime);
+				if (
+					await navigationRuntime.reloadCurrentPage({ clearCache: true, moduleUrl: getActiveHmrModuleUrl() })
+				) {
+				} else {
+					location.reload();
+				}
+				break;
+			}
+			case 'error':
+				console.error('[ecopages] HMR Error:', payload.message);
+				break;
+			case 'update':
+				if (payload.path) {
+					await applyUpdate(payload.path, payload.timestamp);
+				}
+				break;
+			case 'css-update':
+				if (payload.path) {
+					refreshStylesheet(payload.path);
+				}
+				break;
+		}
+	}
+
+	/**
+	 * Applies a module update by calling registered HMR handlers or re-importing the module.
+	 * @param path - The module path to update
+	 * @param timestamp - Optional timestamp for cache busting
+	 */
+	async function applyUpdate(path: string, timestamp?: number) {
+		try {
+			const url = path + '?t=' + (timestamp || Date.now());
+			const handlers = window.__ECO_PAGES__?.hmrHandlers;
+			const navigationRuntime = getEcoNavigationRuntime(window);
+			await waitForNavigationToSettle(navigationRuntime);
+
+			if (handlers?.[path]) {
+				await handlers[path](url);
+				return;
+			}
+
+			await import(url);
+
+			if (await navigationRuntime.reloadCurrentPage({ clearCache: false })) {
+			}
+		} catch (e) {
+			console.error('[ecopages] Failed to apply HMR update:', e);
+		}
+	}
+
+	function getActiveHmrModuleUrl(): string | undefined {
+		const pageModule = window.__ECO_PAGES__?.page?.module;
+		if (pageModule && pageModule.includes('/assets/_hmr/')) {
+			return pageModule.split('?')[0];
+		}
+
+		const handlerPaths = Object.keys(window.__ECO_PAGES__?.hmrHandlers ?? {});
+		return handlerPaths[handlerPaths.length - 1];
+	}
+
+	async function waitForNavigationToSettle(navigationRuntime: ReturnType<typeof getEcoNavigationRuntime>) {
+		if (!navigationRuntime.hasPendingNavigationTransaction()) {
+			return;
+		}
+
+		await new Promise<void>((resolve) => {
+			const startedAt = performance.now();
+			const timeoutMs = 2000;
+
+			const poll = () => {
+				if (!navigationRuntime.hasPendingNavigationTransaction()) {
+					resolve();
+					return;
+				}
+
+				if (performance.now() - startedAt >= timeoutMs) {
+					resolve();
+					return;
+				}
+
+				requestAnimationFrame(poll);
+			};
+
+			requestAnimationFrame(poll);
+		});
+	}
+
+	/**
+	 * Hot-reload CSS by updating stylesheet link href with cache-busting query param.
+	 * This causes the browser to re-fetch the stylesheet without a full page reload.
+	 */
+	function refreshStylesheet(path: string) {
+		const filename = path.split('/').pop() || '';
+		const links = document.querySelectorAll('link[rel="stylesheet"]');
+
+		links.forEach((link) => {
+			const href = (link as HTMLLinkElement).href;
+			if (href.includes(filename) || href.includes(path.replace(/^.*\/src\//, '/assets/'))) {
+				const url = new URL(href, location.origin);
+				url.searchParams.set('t', Date.now().toString());
+				(link as HTMLLinkElement).href = url.toString();
+				console.log('[ecopages] CSS updated:', filename);
+			}
+		});
+	}
+
+	connect();
+})();

package/src/hmr/hmr-strategy.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from 'vitest';
+import { HmrStrategy, HmrStrategyType, type HmrAction } from './hmr-strategy';
+
+/**
+ * Mock strategy for testing the base class behavior
+ */
+class MockStrategy extends HmrStrategy {
+	readonly type: HmrStrategyType;
+	override readonly priorityOffset: number;
+	private matchPattern: string;
+
+	constructor(options: { type: HmrStrategyType; priorityOffset?: number; matchPattern?: string }) {
+		super();
+		this.type = options.type;
+		this.priorityOffset = options.priorityOffset ?? 0;
+		this.matchPattern = options.matchPattern ?? '.';
+	}
+
+	matches(filePath: string): boolean {
+		return filePath.endsWith(this.matchPattern);
+	}
+
+	async process(filePath: string): Promise<HmrAction> {
+		return {
+			type: 'broadcast',
+			events: [{ type: 'update', path: filePath, timestamp: Date.now() }],
+		};
+	}
+}
+
+describe('HmrStrategyType', () => {
+	it('INTEGRATION has value 100', () => {
+		expect(HmrStrategyType.INTEGRATION).toBe(100);
+	});
+
+	it('ASSET has value 50', () => {
+		expect(HmrStrategyType.ASSET).toBe(50);
+	});
+
+	it('SCRIPT has value 25', () => {
+		expect(HmrStrategyType.SCRIPT).toBe(25);
+	});
+
+	it('FALLBACK has value 0', () => {
+		expect(HmrStrategyType.FALLBACK).toBe(0);
+	});
+
+	it('maintains priority order: INTEGRATION > ASSET > SCRIPT > FALLBACK', () => {
+		expect(HmrStrategyType.INTEGRATION).toBeGreaterThan(HmrStrategyType.ASSET);
+		expect(HmrStrategyType.ASSET).toBeGreaterThan(HmrStrategyType.SCRIPT);
+		expect(HmrStrategyType.SCRIPT).toBeGreaterThan(HmrStrategyType.FALLBACK);
+	});
+});
+
+describe('HmrStrategy', () => {
+	describe('priority', () => {
+		it('returns type value when priorityOffset is 0', () => {
+			const strategy = new MockStrategy({ type: HmrStrategyType.INTEGRATION });
+			expect(strategy.priority).toBe(100);
+		});
+
+		it('returns type + priorityOffset', () => {
+			const strategy = new MockStrategy({ type: HmrStrategyType.INTEGRATION, priorityOffset: 5 });
+			expect(strategy.priority).toBe(105);
+		});
+
+		it('allows negative priorityOffset', () => {
+			const strategy = new MockStrategy({ type: HmrStrategyType.ASSET, priorityOffset: -10 });
+			expect(strategy.priority).toBe(40);
+		});
+	});
+
+	describe('strategy selection by priority', () => {
+		it('higher priority strategies are selected first', () => {
+			const strategies = [
+				new MockStrategy({ type: HmrStrategyType.FALLBACK, matchPattern: '.test' }),
+				new MockStrategy({ type: HmrStrategyType.INTEGRATION, matchPattern: '.test' }),
+				new MockStrategy({ type: HmrStrategyType.SCRIPT, matchPattern: '.test' }),
+				new MockStrategy({ type: HmrStrategyType.ASSET, matchPattern: '.test' }),
+			];
+
+			const sorted = [...strategies].sort((a, b) => b.priority - a.priority);
+
+			expect(sorted[0].type).toBe(HmrStrategyType.INTEGRATION);
+			expect(sorted[1].type).toBe(HmrStrategyType.ASSET);
+			expect(sorted[2].type).toBe(HmrStrategyType.SCRIPT);
+			expect(sorted[3].type).toBe(HmrStrategyType.FALLBACK);
+		});
+
+		it('priorityOffset can override default ordering', () => {
+			const assetWithHighOffset = new MockStrategy({
+				type: HmrStrategyType.ASSET,
+				priorityOffset: 60,
+				matchPattern: '.test',
+			});
+			const integration = new MockStrategy({
+				type: HmrStrategyType.INTEGRATION,
+				matchPattern: '.test',
+			});
+
+			expect(assetWithHighOffset.priority).toBeGreaterThan(integration.priority);
+		});
+	});
+
+	describe('matches', () => {
+		it('should be implemented by subclasses', () => {
+			const strategy = new MockStrategy({ type: HmrStrategyType.ASSET, matchPattern: '.css' });
+			expect(strategy.matches('styles.css')).toBe(true);
+			expect(strategy.matches('script.js')).toBe(false);
+		});
+	});
+
+	describe('process', () => {
+		it('should return an HmrAction', async () => {
+			const strategy = new MockStrategy({ type: HmrStrategyType.ASSET });
+			const action = await strategy.process('/path/to/file.');
+
+			expect(action.type).toBe('broadcast');
+			expect(action.events).toBeDefined();
+			expect(action.events?.[0].type).toBe('update');
+			expect(action.events?.[0].path).toBe('/path/to/file.');
+		});
+	});
+});