@ecopages/core 0.2.0-alpha.3 → 0.2.0-alpha.31

package/src/utils/invariant.ts

@@ -1,15 +0,0 @@
-/**
- * This module contains a simple utility invariant function that throws an error if the condition is not met
- * @module
- */
-
-const prefix = '[ecopages]';
-
-export function invariant(condition: boolean, message?: string): asserts condition {
-	if (condition) {
-		return;
-	}
-
-	const value = message ? `${prefix} ${message}` : `${prefix} An error occurred`;
-	throw new Error(value);
-}

package/src/utils/locals-utils.ts

@@ -1,37 +0,0 @@
-import type { ApiHandlerContext } from '../public-types.ts';
-
-/**
- * Creates a require function for validating and retrieving request locals.
- * Supports both single key access and multiple keys with type safety.
- *
- * @param getLocals - Function that returns the current locals object
- * @returns A require function that throws the onMissing response if keys are not found
- *
- * @example
- * ```ts
- * const require = createRequire(() => context.locals);
- * const userId = require('userId', () => new Response('Unauthorized', { status: 401 }));
- * ```
- */
-export function createRequire(getLocals: () => Record<string, unknown>): ApiHandlerContext['require'] {
-	return (keyOrKeys: string | readonly string[], onMissing: () => Response) => {
-		const locals = getLocals();
-		if (Array.isArray(keyOrKeys)) {
-			const result: Record<string, unknown> = {};
-			for (const key of keyOrKeys) {
-				const value = locals[key];
-				if (value === undefined || value === null) {
-					throw onMissing();
-				}
-				result[key] = value;
-			}
-			return result;
-		}
-
-		const value = locals[keyOrKeys as string];
-		if (value === undefined || value === null) {
-			throw onMissing();
-		}
-		return value;
-	};
-}

package/src/utils/parse-cli-args.ts

@@ -1,83 +0,0 @@
-import { parseArgs } from 'node:util';
-import { getRuntimeArgv } from './runtime.ts';
-
-/**
- * Parsed command line arguments for the Ecopages server.
- * @property preview - Whether to run in preview mode
- * @property build - Whether to run a static build
- * @property start - Whether to start the server
- * @property dev - Whether to run in development mode
- * @property port - Optional port number
- * @property hostname - Optional hostname
- * @property reactFastRefresh - Whether React Fast Refresh is enabled
- */
-export type ReturnParseCliArgs = {
-	preview: boolean;
-	build: boolean;
-	start: boolean;
-	dev: boolean;
-	port?: number;
-	hostname?: string;
-	reactFastRefresh?: boolean;
-};
-
-const ECOPAGES_BIN_FILES = ['ecopages.ts', 'ecopages.js', 'cli.js'];
-
-const ECOPAGES_AVAILABLE_COMMANDS = ['dev', 'build', 'start', 'preview'];
-
-/**
- * Parses command line arguments for the server.
- * It returns {@link ReturnParseCliArgs}
- */
-export function parseCliArgs(): ReturnParseCliArgs {
-	const runtimeArgv = getRuntimeArgv();
-
-	const { values } = parseArgs({
-		args: runtimeArgv,
-		options: {
-			dev: { type: 'boolean' },
-			preview: { type: 'boolean' },
-			build: { type: 'boolean' },
-			port: { type: 'string' },
-			hostname: { type: 'string' },
-			'react-fast-refresh': { type: 'boolean' },
-		},
-		allowPositionals: true,
-	});
-
-	let command = '';
-	const ecopagesIndex = runtimeArgv.findIndex((arg) => ECOPAGES_BIN_FILES.some((filename) => arg.endsWith(filename)));
-
-	const isAvailableCommand = ecopagesIndex !== -1;
-
-	if (isAvailableCommand) {
-		command =
-			ecopagesIndex < runtimeArgv.length - 1 &&
-			ECOPAGES_AVAILABLE_COMMANDS.some((cmd) => {
-				return runtimeArgv[ecopagesIndex + 1] === cmd;
-			})
-				? runtimeArgv[ecopagesIndex + 1]
-				: 'start';
-	}
-
-	const isStartCommand = command === 'start' || (!values.dev && !values.build && !values.preview);
-	const isDevCommand = command === 'dev' || !!values.dev;
-	const isBuildCommand = command === 'build' || !!values.build;
-	const isPreviewCommand = command === 'preview' || !!values.preview;
-
-	const parsedCommandOptions = {
-		preview: isPreviewCommand,
-		build: isBuildCommand,
-		start: isStartCommand,
-		dev: isDevCommand,
-		port: values.port ? Number(values.port) : undefined,
-		hostname: values.hostname,
-		reactFastRefresh: values['react-fast-refresh'],
-	};
-
-	if (!process.env.NODE_ENV) {
-		process.env.NODE_ENV = isDevCommand ? 'development' : 'production';
-	}
-
-	return parsedCommandOptions;
-}

package/src/utils/path-utils.module.ts

@@ -1,14 +0,0 @@
-import path from 'node:path';
-
-function getEcoTemplateExtension(filePath: string) {
-	const { name, ext } = path.parse(filePath);
-	const nameParts = name.split('.');
-	const descriptor = nameParts.length > 1 ? nameParts.pop() : undefined;
-	const templateExtension = descriptor ? `.${descriptor}${ext}` : ext;
-
-	return templateExtension;
-}
-
-export const PathUtils = {
-	getEcoTemplateExtension,
-};

package/src/utils/runtime.ts

@@ -1,44 +0,0 @@
-import { createHash } from 'node:crypto';
-
-export const RUNTIME_ERRORS = {
-	BUN_RUNTIME_REQUIRED: 'Bun runtime is required',
-} as const;
-
-type RuntimeBun = typeof Bun;
-
-export function getBunRuntime(): RuntimeBun | undefined {
-	return (globalThis as { Bun?: RuntimeBun }).Bun;
-}
-
-export function getRequiredBunRuntime(): RuntimeBun {
-	const bun = getBunRuntime();
-
-	if (!bun) {
-		throw new Error(RUNTIME_ERRORS.BUN_RUNTIME_REQUIRED);
-	}
-
-	return bun;
-}
-
-export function getRuntimeArgv(): string[] {
-	return process.argv;
-}
-
-export function isDevelopmentRuntime(): boolean {
-	return process.env.NODE_ENV === 'development';
-}
-
-export function isProductionRuntime(): boolean {
-	return process.env.NODE_ENV === 'production';
-}
-
-export function runtimeHash(content: string | Buffer<ArrayBufferLike>): number | bigint {
-	const bun = getBunRuntime();
-
-	if (bun) {
-		return bun.hash(content);
-	}
-
-	const hex = createHash('sha256').update(content).digest('hex').slice(0, 16);
-	return BigInt(`0x${hex}`);
-}

package/src/utils/server-utils.module.ts

@@ -1,67 +0,0 @@
-const ContentTypeMap = new Map<string, string>([
-	['jpg', 'image/jpeg'],
-	['jpeg', 'image/jpeg'],
-	['png', 'image/png'],
-	['gif', 'image/gif'],
-	['bmp', 'image/bmp'],
-	['svg', 'image/svg+xml'],
-	['tiff', 'image/tiff'],
-	['webp', 'image/webp'],
-	['avif', 'image/avif'],
-	['ico', 'image/x-icon'],
-	['mp3', 'audio/mpeg'],
-	['ogg', 'audio/ogg'],
-	['wav', 'audio/wav'],
-	['mp4', 'video/mp4'],
-	['webm', 'video/webm'],
-	['ogv', 'video/ogg'],
-	['mov', 'video/quicktime'],
-	['txt', 'text/plain'],
-	['html', 'text/html'],
-	['css', 'text/css'],
-	['js', 'text/javascript'],
-	['mjs', 'text/javascript'],
-	['json', 'application/json'],
-	['map', 'application/json'],
-	['xml', 'application/xml'],
-	['webmanifest', 'application/manifest+json'],
-	['wasm', 'application/wasm'],
-	['csv', 'text/csv'],
-	['ttf', 'font/ttf'],
-	['woff', 'font/woff'],
-	['woff2', 'font/woff2'],
-	['otf', 'font/otf'],
-	['eot', 'application/vnd.ms-fontobject'],
-	['gz', 'application/x-gzip'],
-	['zip', 'application/zip'],
-	['pdf', 'application/pdf'],
-	['doc', 'application/msword'],
-]);
-
-/**
- * Get the content type of a file based on its extension.
- * @param file - The file name.
- * @returns The content type.
- */
-export const getContentType = (file: string): string => {
-	const extension = file.split('.').pop() || 'txt';
-	return ContentTypeMap.get(extension) || 'text/plain';
-};
-
-/**
- * Check if a file path has a known static file extension.
- * @param file - The file name or path.
- * @returns true if the extension is recognized.
- */
-export const hasKnownExtension = (file: string): boolean => {
-	const extension = file.split('.').pop();
-	return extension !== undefined && ContentTypeMap.has(extension);
-};
-
-/**
- * A module for server utilities.
- */
-export const ServerUtils = {
-	getContentType,
-	hasKnownExtension,
-};

package/src/watchers/project-watcher.test-helpers.ts

@@ -1,41 +0,0 @@
-import { vi } from 'vitest';
-import type { IHmrManager } from '../internal-types';
-import type { ClientBridge } from '../adapters/bun/client-bridge';
-
-export const createMockHmrManager = (): IHmrManager =>
-	({
-		handleFileChange: vi.fn(async () => {}),
-		broadcast: vi.fn(() => {}),
-		setEnabled: vi.fn(() => {}),
-		setPlugins: vi.fn(() => {}),
-		registerEntrypoint: vi.fn(async () => ''),
-		registerSpecifierMap: vi.fn(() => {}),
-		registerStrategy: vi.fn(() => {}),
-		isEnabled: vi.fn(() => true),
-		canHandleFileChange: vi.fn(() => true),
-		getOutputUrl: vi.fn(() => undefined),
-		getWatchedFiles: vi.fn(() => new Map()),
-		getSpecifierMap: vi.fn(() => new Map()),
-		getDistDir: vi.fn(() => ''),
-		getPlugins: vi.fn(() => []),
-		getDefaultContext: vi.fn(() => ({
-			getWatchedFiles: () => new Map(),
-			getSpecifierMap: () => new Map(),
-			getDistDir: () => '',
-			getPlugins: () => [],
-			getSrcDir: () => '',
-			getLayoutsDir: () => '',
-		})),
-	}) as unknown as IHmrManager;
-
-export const createMockBridge = (): ClientBridge =>
-	({
-		reload: vi.fn(() => {}),
-		error: vi.fn(() => {}),
-		cssUpdate: vi.fn(() => {}),
-		update: vi.fn(() => {}),
-		subscribe: vi.fn(() => {}),
-		unsubscribe: vi.fn(() => {}),
-		broadcast: vi.fn(() => {}),
-		subscriberCount: 0,
-	}) as unknown as ClientBridge;

package/src/watchers/project-watcher.ts

@@ -1,344 +0,0 @@
-import path from 'node:path';
-import chokidar, { type FSWatcher } from 'chokidar';
-import { fileSystem } from '@ecopages/file-system';
-import { appLogger } from '../global/app-logger.ts';
-import type { EcoPagesAppConfig, IHmrManager, IClientBridge } from '../internal-types.ts';
-import type { ProcessorWatchContext } from '../plugins/processor.ts';
-
-/**
- * Configuration options for the ProjectWatcher
- * @interface ProjectWatcherConfig
- * @property {EcoPagesAppConfig} config - The application configuration
- * @property {() => void} refreshRouterRoutesCallback - Callback to refresh router routes
- * @property {IHmrManager} hmrManager - The HMR manager instance
- * @property {ClientBridge} bridge - The client bridge instance
- */
-export interface ProjectWatcherConfig {
-	config: EcoPagesAppConfig;
-	refreshRouterRoutesCallback: () => void;
-	hmrManager: IHmrManager;
-	bridge: IClientBridge;
-}
-
-/**
- * ProjectWatcher handles file system changes for hot module replacement (HMR).
- * It uses chokidar to watch for file changes and triggers appropriate actions:
- * - Uncaches modules when files change
- * - Refreshes router routes for page files
- * - Triggers HMR server reload
- * - Handles processor-specific file changes
- *
- * The watcher uses chokidar's built-in debouncing through `awaitWriteFinish`
- * to handle rapid file changes efficiently:
- * - stabilityThreshold: 50ms - Time to wait for writes to stabilize
- * - pollInterval: 50ms - Interval to poll for file changes
- *
- * @class ProjectWatcher
- */
-export class ProjectWatcher {
-	/**
-	 * Duplicate identical watcher events within this window are ignored.
-	 *
-	 * Some editors or save pipelines emit two near-identical filesystem change
-	 * notifications for the same file. Ecopages should treat those as one logical
-	 * update so HMR and route refresh work are not repeated unnecessarily.
-	 */
-	private static readonly duplicateChangeWindowMs = 150;
-	private appConfig: EcoPagesAppConfig;
-	private refreshRouterRoutesCallback: () => void;
-	private hmrManager: IHmrManager;
-	private bridge: IClientBridge;
-	private watcher: FSWatcher | null = null;
-	private lastHandledChange = new Map<string, number>();
-
-	constructor({ config, refreshRouterRoutesCallback, hmrManager, bridge }: ProjectWatcherConfig) {
-		this.appConfig = config;
-		this.refreshRouterRoutesCallback = refreshRouterRoutesCallback;
-		this.hmrManager = hmrManager;
-		this.bridge = bridge;
-		this.triggerRouterRefresh = this.triggerRouterRefresh.bind(this);
-		this.handleError = this.handleError.bind(this);
-		this.handleFileChange = this.handleFileChange.bind(this);
-	}
-
-	/**
-	 * Uncaches modules in the source directory to ensure fresh imports.
-	 * This is necessary for hot module replacement to work correctly.
-	 * @private
-	 */
-	private uncacheModules(): void {
-		if (typeof require === 'undefined') return;
-
-		const { srcDir, rootDir } = this.appConfig;
-		const regex = new RegExp(`${rootDir}/${srcDir}/.*`);
-
-		for (const key in require.cache) {
-			if (regex.test(key)) {
-				delete require.cache[key];
-			}
-		}
-	}
-
-	/**
-	 * Handles public directory file changes by copying only the changed file.
-	 * @param filePath - Absolute path of the changed file
-	 */
-	private async handlePublicDirFileChange(filePath: string): Promise<void> {
-		try {
-			const relativePath = path.relative(this.appConfig.absolutePaths.publicDir, filePath);
-			const destPath = path.join(this.appConfig.absolutePaths.distDir, relativePath);
-
-			if (fileSystem.exists(filePath)) {
-				const destDir = path.dirname(destPath);
-				fileSystem.ensureDir(destDir);
-				await fileSystem.copyFileAsync(filePath, destPath);
-			}
-
-			this.bridge.reload();
-		} catch (error) {
-			appLogger.error(`Failed to copy public file: ${error instanceof Error ? error.message : String(error)}`);
-			this.bridge.reload();
-		}
-	}
-
-	/**
-	 * Handles file changes by uncaching modules, refreshing routes, and delegating appropriately.
-	 * Follows 4-rule priority:
-	 * 0. Public directory match? → copy file and reload
-	 * 1. additionalWatchPaths match? → reload
-	 * 2. Processor extension match? → processor handles (skip HMR)
-	 * 3. Otherwise → HMR strategies
-	 *
-	 * Duplicate identical watcher events for the same file are coalesced within a
-	 * short window before any of the priority rules run.
-	 * @param rawPath - Path of the changed file
-	 */
-	private async handleFileChange(rawPath: string): Promise<void> {
-		const filePath = path.resolve(rawPath);
-		const now = Date.now();
-		const lastHandledAt = this.lastHandledChange.get(filePath);
-		if (lastHandledAt !== undefined && now - lastHandledAt < ProjectWatcher.duplicateChangeWindowMs) {
-			return;
-		}
-		this.lastHandledChange.set(filePath, now);
-
-		try {
-			if (this.isPublicDirFile(filePath)) {
-				await this.handlePublicDirFileChange(filePath);
-				return;
-			}
-
-			this.uncacheModules();
-			const isPageFile = filePath.startsWith(this.appConfig.absolutePaths.pagesDir);
-
-			if (isPageFile) {
-				this.refreshRouterRoutesCallback();
-			}
-
-			if (this.matchesAdditionalWatchPaths(filePath)) {
-				this.bridge.reload();
-				return;
-			}
-
-			if (this.isHandledByProcessor(filePath)) {
-				return;
-			}
-
-			if (this.isWatchedByProcessor(filePath) && !this.hmrManager.canHandleFileChange(filePath)) {
-				this.hmrManager.broadcast({ type: 'layout-update' });
-				return;
-			}
-
-			await this.hmrManager.handleFileChange(filePath);
-		} catch (error) {
-			if (error instanceof Error) {
-				this.bridge.error(error.message);
-				this.handleError(error);
-			}
-		}
-	}
-
-	/**
-	 * Checks if a file is in the public directory.
-	 */
-	private isPublicDirFile(filePath: string): boolean {
-		return filePath.startsWith(this.appConfig.absolutePaths.publicDir);
-	}
-
-	/**
-	 * Checks if file path matches any additionalWatchPaths patterns.
-	 */
-	private matchesAdditionalWatchPaths(filePath: string): boolean {
-		const patterns = this.appConfig.additionalWatchPaths;
-		if (!patterns.length) return false;
-
-		for (const pattern of patterns) {
-			if (pattern.includes('*')) {
-				const ext = pattern.replace(/\*\*?\/\*/, '');
-				if (filePath.endsWith(ext)) return true;
-			} else {
-				if (filePath.endsWith(pattern) || filePath === path.resolve(pattern)) return true;
-			}
-		}
-		return false;
-	}
-
-	/**
-	 * Checks whether a file is watched by any processor, even if that processor
-	 * does not own the file as a primary asset.
-	 */
-	private isWatchedByProcessor(filePath: string): boolean {
-		for (const processor of this.appConfig.processors.values()) {
-			const watchConfig = processor.getWatchConfig();
-			if (!watchConfig) continue;
-
-			const { extensions = [] } = watchConfig;
-			if (extensions.length && extensions.some((ext) => filePath.endsWith(ext))) {
-				return true;
-			}
-		}
-
-		return false;
-	}
-
-	/**
-	 * Checks if a file is handled by a processor.
-	 * Processors that declare extensions own those file types.
-	 */
-	private isHandledByProcessor(filePath: string): boolean {
-		for (const processor of this.appConfig.processors.values()) {
-			const capabilities = processor.getAssetCapabilities?.() ?? [];
-			if (capabilities.length > 0) {
-				const matchesConfiguredAsset =
-					typeof processor.matchesFileFilter !== 'function' || processor.matchesFileFilter(filePath);
-
-				if (
-					matchesConfiguredAsset &&
-					capabilities.some((capability) => processor.canProcessAsset?.(capability.kind, filePath))
-				) {
-					return true;
-				}
-
-				continue;
-			}
-
-			const watchConfig = processor.getWatchConfig();
-			if (!watchConfig) continue;
-
-			const { extensions = [] } = watchConfig;
-			if (extensions.length && extensions.some((ext) => filePath.endsWith(ext))) {
-				return true;
-			}
-		}
-		return false;
-	}
-
-	/**
-	 * Triggers router refresh for page directory changes.
-	 * This ensures the router is updated when pages are added or removed.
-	 *
-	 * @param {string} path - Path of the changed directory
-	 */
-	triggerRouterRefresh(path: string) {
-		const isPageDir = path.startsWith(this.appConfig.absolutePaths.pagesDir);
-		if (isPageDir) {
-			this.refreshRouterRoutesCallback();
-		}
-	}
-
-	/**
-	 * Handles and logs errors that occur during file watching.
-	 *
-	 * @param {unknown} error - The error to handle
-	 */
-	handleError(error: unknown) {
-		if (error instanceof Error) {
-			this.hmrManager.broadcast({ type: 'error', message: error.message });
-		}
-		appLogger.error(`Watcher error: ${error}`);
-	}
-
-	/**
-	 * Processes file changes for specific file extensions.
-	 * Used by processors to handle their specific file types.
-	 *
-	 * @private
-	 * @param {string} path - Path of the changed file
-	 * @param {string[]} extensions - File extensions to process
-	 * @param {(ctx: ProcessorWatchContext) => void} handler - Handler function for the file change
-	 */
-	private shouldProcess(path: string, extensions: string[], handler: (ctx: ProcessorWatchContext) => void) {
-		if (!extensions.length || extensions.some((ext) => path.endsWith(ext))) {
-			handler({ path, bridge: this.bridge });
-		}
-	}
-
-	/**
-	 * Creates and configures the file system watcher.
-	 * This sets up:
-	 * 1. Processor-specific file watching
-	 * 2. Page file watching
-	 * 3. Directory watching
-	 * 4. Error handling
-	 *
-	 * Uses chokidar's built-in debouncing through `awaitWriteFinish` to handle
-	 * rapid file changes efficiently.
-	 */
-	public async createWatcherSubscription() {
-		if (!this.watcher) {
-			const processorPaths: string[] = [];
-			for (const processor of this.appConfig.processors.values()) {
-				const watchConfig = processor.getWatchConfig();
-				if (!watchConfig) continue;
-				processorPaths.push(...watchConfig.paths);
-			}
-
-			if (fileSystem.exists(this.appConfig.absolutePaths.pagesDir)) {
-				processorPaths.push(this.appConfig.absolutePaths.pagesDir);
-			}
-
-			if (fileSystem.exists(this.appConfig.absolutePaths.publicDir)) {
-				processorPaths.push(this.appConfig.absolutePaths.publicDir);
-			}
-
-			if (this.appConfig.additionalWatchPaths.length) {
-				processorPaths.push(...this.appConfig.additionalWatchPaths);
-			}
-
-			this.watcher = chokidar.watch(processorPaths, {
-				ignoreInitial: true,
-				ignorePermissionErrors: true,
-				awaitWriteFinish: {
-					stabilityThreshold: 50,
-					pollInterval: 50,
-				},
-			});
-		}
-
-		for (const processor of this.appConfig.processors.values()) {
-			const watchConfig = processor.getWatchConfig();
-			if (!watchConfig) continue;
-			const { extensions = [], onCreate, onChange, onDelete, onError } = watchConfig;
-
-			if (onCreate) this.watcher.on('add', (path) => this.shouldProcess(path, extensions, onCreate));
-			if (onChange) this.watcher.on('change', (path) => this.shouldProcess(path, extensions, onChange));
-			if (onDelete) this.watcher.on('unlink', (path) => this.shouldProcess(path, extensions, onDelete));
-			if (onError) this.watcher.on('error', onError as (error: unknown) => void);
-		}
-
-		this.watcher.add(this.appConfig.absolutePaths.srcDir);
-
-		this.watcher
-			.on('change', (path) => this.handleFileChange(path))
-			.on('add', (path) => {
-				this.handleFileChange(path);
-				this.triggerRouterRefresh(path);
-			})
-			.on('addDir', (path) => this.triggerRouterRefresh(path))
-			.on('unlink', (path) => this.triggerRouterRefresh(path))
-			.on('unlinkDir', (path) => this.triggerRouterRefresh(path))
-			.on('error', (error) => this.handleError(error));
-
-		return this.watcher;
-	}
-}