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

package/src/eco/global-injector-map.ts

@@ -0,0 +1,112 @@
+import type { ResolvedLazyTrigger } from '../types/public-types.ts';
+
+type GlobalInjectorEntry = {
+	'on:idle'?: { scripts: string[] };
+	'on:interaction'?: { value: string; scripts: string[] };
+	'on:visible'?: { value?: string; scripts: string[] };
+};
+
+type GlobalInjectorMap = Record<string, GlobalInjectorEntry>;
+
+/**
+ * Converts a flat list of resolved triggers into the map structure consumed
+ * by the `initGlobalInjector` bootstrap. Multiple triggers sharing the same
+ * `triggerId` are merged so their script lists are deduplicated.
+ */
+function buildGlobalInjectorMap(triggers: ResolvedLazyTrigger[]): GlobalInjectorMap {
+	const map: GlobalInjectorMap = {};
+
+	for (const { triggerId, rules } of triggers) {
+		const entry: GlobalInjectorEntry = map[triggerId] ?? {};
+
+		for (const rule of rules) {
+			if ('on:idle' in rule) {
+				const { scripts } = rule['on:idle'];
+				entry['on:idle'] = {
+					scripts: Array.from(new Set([...(entry['on:idle']?.scripts ?? []), ...scripts])),
+				};
+				continue;
+			}
+
+			if ('on:interaction' in rule) {
+				const { value, scripts } = rule['on:interaction'];
+				entry['on:interaction'] = {
+					value,
+					scripts: Array.from(new Set([...(entry['on:interaction']?.scripts ?? []), ...scripts])),
+				};
+				continue;
+			}
+
+			if ('on:visible' in rule) {
+				const { value, scripts } = rule['on:visible'];
+				entry['on:visible'] = {
+					...(value ? { value } : {}),
+					scripts: Array.from(new Set([...(entry['on:visible']?.scripts ?? []), ...scripts])),
+				};
+				continue;
+			}
+		}
+
+		if (Object.keys(entry).length > 0) {
+			map[triggerId] = entry;
+		}
+	}
+
+	return map;
+}
+
+/**
+ * Serializes resolved lazy triggers into a JSON string safe for embedding
+ * inside an inline `<script type="ecopages/global-injector-map">` tag.
+ *
+ * The `</script` sequence is escaped because an unescaped occurrence in inline
+ * script content causes the HTML parser to close the script tag prematurely,
+ * breaking page rendering. `JSON.stringify` does not perform this escape by
+ * default, so a targeted replacement is applied after serialization.
+ */
+export function buildGlobalInjectorMapScript(triggers: ResolvedLazyTrigger[]): string {
+	const map = buildGlobalInjectorMap(triggers);
+	return JSON.stringify(map).replace(/<\/script/gi, '<\\/script');
+}
+
+/**
+ * Builds the module source that boots the global lazy injector on the client.
+ * Emitted once per page alongside the `ecopages/global-injector-map` script block.
+ */
+export function buildGlobalInjectorBootstrapContent(globalInjectorModuleSpecifier: string): string {
+	return `import { initGlobalInjector } from ${JSON.stringify(globalInjectorModuleSpecifier)};
+
+function pruneStaleTriggerMaps() {
+	const mapScripts = Array.from(document.querySelectorAll('script[type="ecopages/global-injector-map"]'));
+	if (mapScripts.length <= 1) {
+		return;
+	}
+
+	const latestMapScript = mapScripts[mapScripts.length - 1];
+	for (const mapScript of mapScripts) {
+		if (mapScript !== latestMapScript) {
+			mapScript.remove();
+		}
+	}
+}
+
+const globalScope = window;
+if (typeof globalScope.__ecoGlobalInjectorCleanup === 'function') {
+	globalScope.__ecoGlobalInjectorCleanup();
+}
+
+const injector = initGlobalInjector();
+
+const handleAfterSwap = () => {
+	pruneStaleTriggerMaps();
+	injector.refresh();
+};
+
+document.addEventListener('eco:after-swap', handleAfterSwap);
+pruneStaleTriggerMaps();
+
+globalScope.__ecoGlobalInjectorCleanup = () => {
+	document.removeEventListener('eco:after-swap', handleAfterSwap);
+	injector.cleanup();
+};`;
+}

package/src/eco/lazy-injector-map.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from 'vitest';
+import { buildInjectorMapScript } from './lazy-injector-map.ts';
+import type { InjectorMapConfig } from '@ecopages/scripts-injector/types';
+import type { ResolvedLazyScriptGroup } from '../types/public-types.ts';
+
+describe('buildInjectorMapScript', () => {
+	test('builds injector map for mixed lazy triggers', () => {
+		const lazyGroups: ResolvedLazyScriptGroup[] = [
+			{ lazy: { 'on:idle': true }, scripts: './idle-a.js, /idle-b.js' },
+			{ lazy: { 'on:interaction': 'click' }, scripts: './int-a.js' },
+			{ lazy: { 'on:visible': '0.5' }, scripts: '/vis-a.js' },
+		];
+
+		const result = buildInjectorMapScript(lazyGroups);
+		const map = JSON.parse(result) as InjectorMapConfig;
+
+		expect(map['on:idle']).toEqual({ scripts: ['/idle-a.js', '/idle-b.js'] });
+		expect(map['on:interaction']).toEqual({
+			value: 'click',
+			scripts: ['/int-a.js'],
+		});
+		expect(map['on:visible']).toEqual({
+			value: '0.5',
+			scripts: ['/vis-a.js'],
+		});
+	});
+
+	test('dedupes scripts and merges interaction events while preserving order', () => {
+		const lazyGroups: ResolvedLazyScriptGroup[] = [
+			{ lazy: { 'on:interaction': 'click,mouseenter' }, scripts: './one.js,./two.js' },
+			{ lazy: { 'on:interaction': 'mouseenter,focusin' }, scripts: '/two.js,/three.js' },
+		];
+
+		const result = buildInjectorMapScript(lazyGroups);
+		const map = JSON.parse(result) as InjectorMapConfig;
+
+		expect(map['on:interaction']).toEqual({
+			value: 'click,mouseenter,focusin',
+			scripts: ['/one.js', '/two.js', '/three.js'],
+		});
+	});
+
+	test('keeps existing on:visible threshold when a later boolean trigger is encountered', () => {
+		const lazyGroups: ResolvedLazyScriptGroup[] = [
+			{ lazy: { 'on:visible': '100px' }, scripts: './threshold.js' },
+			{ lazy: { 'on:visible': true }, scripts: './fallback.js' },
+		];
+
+		const result = buildInjectorMapScript(lazyGroups);
+		const map = JSON.parse(result) as InjectorMapConfig;
+
+		expect(map['on:visible']).toEqual({
+			value: '100px',
+			scripts: ['/threshold.js', '/fallback.js'],
+		});
+	});
+
+	test('escapes closing script tags in output payload', () => {
+		const lazyGroups: ResolvedLazyScriptGroup[] = [
+			{ lazy: { 'on:idle': true }, scripts: '/safe.js, /x</script>y.js' },
+		];
+
+		const result = buildInjectorMapScript(lazyGroups);
+		expect(result).toContain('<\\/script>');
+	});
+});

package/src/eco/lazy-injector-map.ts

@@ -0,0 +1,120 @@
+import type { InjectorMapConfig } from '@ecopages/scripts-injector/types';
+import type { ResolvedLazyScriptGroup } from '../types/public-types.ts';
+
+/**
+ * Normalizes a comma-separated scripts string into absolute script URLs.
+ *
+ * @param scripts Comma-separated script paths.
+ * @returns Normalized script path list.
+ */
+function normalizeScripts(scripts: string): string[] {
+	return scripts
+		.split(',')
+		.map((scriptPath) => scriptPath.trim())
+		.filter(Boolean)
+		.map((scriptPath) => {
+			if (scriptPath.startsWith('/')) {
+				return scriptPath;
+			}
+
+			const normalizedRelativePath = scriptPath.replace(/^\/+/, '').replace(/^(\.\/)+/, '');
+			return `/${normalizedRelativePath}`;
+		});
+}
+
+/**
+ * Deduplicates comma-separated values while preserving first-seen order.
+ *
+ * @param values CSV value list.
+ * @returns A single normalized CSV string.
+ */
+function dedupeCsvValues(values: string[]): string {
+	const seen = new Set<string>();
+
+	for (const value of values) {
+		for (const token of value
+			.split(',')
+			.map((part) => part.trim())
+			.filter(Boolean)) {
+			seen.add(token);
+		}
+	}
+
+	return Array.from(seen).join(',');
+}
+
+/**
+ * Builds a scripts-injector map config from resolved lazy script groups.
+ *
+ * @param lazyGroups Lazy script groups resolved during dependency processing.
+ * @returns Injector map config keyed by lazy trigger.
+ */
+function buildInjectorMap(lazyGroups: readonly ResolvedLazyScriptGroup[]): InjectorMapConfig {
+	const map: InjectorMapConfig = {};
+
+	for (const group of lazyGroups) {
+		const scripts = normalizeScripts(group.scripts);
+		const lazy = group.lazy;
+
+		if ('on:idle' in lazy) {
+			map['on:idle'] = {
+				scripts: [...(map['on:idle']?.scripts ?? []), ...scripts],
+			};
+			continue;
+		}
+
+		if ('on:interaction' in lazy) {
+			const currentValue = map['on:interaction']?.value;
+			const nextValue = lazy['on:interaction'];
+
+			map['on:interaction'] = {
+				value: typeof currentValue === 'string' ? dedupeCsvValues([currentValue, nextValue]) : nextValue,
+				scripts: [...(map['on:interaction']?.scripts ?? []), ...scripts],
+			};
+			continue;
+		}
+
+		if ('on:visible' in lazy) {
+			const currentValue = map['on:visible']?.value;
+			const currentThreshold = typeof currentValue === 'string' ? currentValue : undefined;
+			const nextValue = lazy['on:visible'];
+
+			map['on:visible'] = {
+				...(nextValue === true
+					? currentThreshold
+						? { value: currentThreshold }
+						: {}
+					: { value: String(nextValue) }),
+				scripts: [...(map['on:visible']?.scripts ?? []), ...scripts],
+			};
+			continue;
+		}
+
+		throw new Error(
+			`Invalid lazy options: must specify on:idle, on:interaction, or on:visible. Received: ${JSON.stringify(lazy)}`,
+		);
+	}
+
+	for (const key of Object.keys(map)) {
+		const scripts = map[key]?.scripts;
+		if (scripts) {
+			map[key] = {
+				...map[key],
+				scripts: Array.from(new Set(scripts)),
+			};
+		}
+	}
+
+	return map;
+}
+
+/**
+ * Creates a safe JSON payload string for `<script type="ecopages/injector-map">`.
+ *
+ * @param lazyGroups Lazy script groups resolved during dependency processing.
+ * @returns Escaped JSON string safe for inline script embedding.
+ */
+export function buildInjectorMapScript(lazyGroups: readonly ResolvedLazyScriptGroup[]): string {
+	const map = buildInjectorMap(lazyGroups);
+	return JSON.stringify(map).replace(/<\/script/gi, '<\\/script');
+}

package/src/eco/module-dependencies.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from 'vitest';
+import { normalizeModuleDeclarations, parseModuleDeclaration } from './module-dependencies.ts';
+
+describe('module dependencies parser', () => {
+	test('parses simple module declaration', () => {
+		expect(parseModuleDeclaration('react-aria-components')).toEqual({
+			from: 'react-aria-components',
+		});
+	});
+
+	test('parses declaration with named imports', () => {
+		expect(parseModuleDeclaration('react-aria-components{Table,Select}')).toEqual({
+			from: 'react-aria-components',
+			imports: ['Table', 'Select'],
+		});
+	});
+
+	test('normalizes and deduplicates module declarations', () => {
+		expect(
+			normalizeModuleDeclarations([
+				'react-aria-components{Table,Select}',
+				'react-aria-components{Table,Select}',
+				'lodash-es{debounce}',
+			]),
+		).toEqual([
+			{ from: 'react-aria-components', imports: ['Table', 'Select'] },
+			{ from: 'lodash-es', imports: ['debounce'] },
+		]);
+	});
+});

package/src/eco/module-dependencies.ts

@@ -0,0 +1,75 @@
+export type ModuleDependencyDeclaration = {
+	from: string;
+	imports?: string[];
+};
+
+function normalizeImports(imports: string[] | undefined): string[] | undefined {
+	if (!imports || imports.length === 0) {
+		return undefined;
+	}
+
+	const normalized = Array.from(new Set(imports.map((entry) => entry.trim()).filter((entry) => entry.length > 0)));
+
+	return normalized.length > 0 ? normalized : undefined;
+}
+
+/**
+ * Parses a module grammar declaration into normalized object form.
+ *
+ * Supported input examples:
+ * - `react-aria-components`
+ * - `react-aria-components{Table,Select}`
+ */
+export function parseModuleDeclaration(value: string): ModuleDependencyDeclaration {
+	const source = value.trim();
+	if (source.length === 0) {
+		throw new Error('Module declaration cannot be empty');
+	}
+
+	const openBraceIndex = source.indexOf('{');
+	if (openBraceIndex < 0) {
+		return { from: source };
+	}
+
+	const closeBraceIndex = source.lastIndexOf('}');
+	if (closeBraceIndex !== source.length - 1 || closeBraceIndex <= openBraceIndex) {
+		throw new Error(`Invalid module declaration '${value}'`);
+	}
+
+	const from = source.slice(0, openBraceIndex).trim();
+	if (from.length === 0) {
+		throw new Error(`Invalid module declaration '${value}'`);
+	}
+
+	const importsSlice = source.slice(openBraceIndex + 1, closeBraceIndex);
+	const imports = normalizeImports(importsSlice.split(','));
+
+	return {
+		from,
+		imports,
+	};
+}
+
+/**
+ * Normalizes and deduplicates module declarations from `modules`.
+ *
+ * Returns canonical object declarations suitable for downstream bundling logic.
+ */
+export function normalizeModuleDeclarations(modules?: string[]): ModuleDependencyDeclaration[] {
+	const declarations = modules ?? [];
+
+	const output: ModuleDependencyDeclaration[] = [];
+	const seen = new Set<string>();
+
+	for (const declaration of declarations) {
+		const normalized = parseModuleDeclaration(declaration);
+		const key = `${normalized.from}::${(normalized.imports ?? []).join(',')}`;
+
+		if (!seen.has(key)) {
+			seen.add(key);
+			output.push(normalized);
+		}
+	}
+
+	return output;
+}

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();
+	});
+});