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

package/src/adapters/abstract/application-adapter.ts

@@ -1,379 +0,0 @@
-/**
- * This file defines the abstract class for application adapters in EcoPages.
- * It provides a common interface for different runtimes (e.g., Node.js, Deno) to implement.
- * The class includes methods for handling HTTP requests and managing application state.
- * It also includes a method for parsing command-line arguments.
- *
- * @module ApplicationAdapter
- */
-
-import { appLogger } from '../../global/app-logger.ts';
-import {
-	getAppModuleLoader,
-	setAppHostModuleLoader,
-} from '../../services/module-loading/app-server-module-transpiler.service.ts';
-import { getHostModuleLoader } from '../../services/module-loading/host-module-loader-registry.ts';
-import type { SourceModuleLoader } from '../../services/module-loading/module-loading-types.ts';
-import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
-import { invariant } from '../../utils/invariant.ts';
-import type {
-	ApiHandler,
-	ApiHandlerContext,
-	ErrorHandler,
-	Middleware,
-	RouteOptions,
-	StaticRoute,
-	ViewLoader,
-} from '../../types/public-types.ts';
-import { fileSystem } from '@ecopages/file-system';
-import { parseCliArgs, type ReturnParseCliArgs } from '../../utils/parse-cli-args.ts';
-
-/**
- * Runtime bootstrap options layered on top of the app config.
- *
- * These options let a host runtime embed Ecopages without mutating process
- * globals or app runtime state before calling `createApp()`.
- */
-export interface ApplicationRuntimeOptions {
-	/**
-	 * Forces the app into the embedded-runtime CLI mode used by host
-	 * environments.
-	 *
-	 * When enabled and no explicit `hostModuleLoader` is provided, the
-	 * adapter auto-detects a host module loader from the global scope.
-	 */
-	embedded?: boolean;
-	/**
-	 * Explicit source module loader for request-time imports.
-	 *
-	 * When omitted in embedded mode, the adapter attempts automatic
-	 * detection from globals set by the host environment.
-	 */
-	hostModuleLoader?: SourceModuleLoader;
-}
-
-/**
- * Configuration options for application adapters
- */
-export interface ApplicationAdapterOptions {
-	appConfig: EcoPagesAppConfig;
-	serverOptions?: Record<string, any>;
-	runtime?: ApplicationRuntimeOptions;
-	/**
-	 * Options for clearing the output directory before starting the server
-	 * @default false
-	 */
-	clearOutput?: boolean;
-}
-
-/**
- * Common interface for application adapters
- */
-export interface ApplicationAdapter<T = any> {
-	start(): Promise<T | void>;
-}
-
-/**
- * Handler function type for route handlers
- */
-export type RouteHandler<
-	TRequest extends Request = Request,
-	TServer = any,
-	TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>,
-> = (context: TContext) => Promise<Response> | Response;
-
-export type RouteGroupDefinition<TRequest extends Request = Request, TServer = any> = {
-	prefix: string;
-	middleware?: readonly Middleware<TRequest, TServer, any>[];
-	routes: readonly ApiHandler<string, TRequest, TServer>[];
-};
-
-/**
- * Abstract base class for application adapters across different runtimes
- */
-export abstract class AbstractApplicationAdapter<
-	TOptions extends ApplicationAdapterOptions = ApplicationAdapterOptions,
-	TServer = any,
-	TRequest extends Request = any,
-> implements ApplicationAdapter<TServer> {
-	protected appConfig: EcoPagesAppConfig;
-	protected serverOptions: Record<string, any>;
-	protected cliArgs: ReturnParseCliArgs;
-	protected runtimeOptions: ApplicationRuntimeOptions;
-	protected apiHandlers: ApiHandler[] = [];
-	protected staticRoutes: StaticRoute[] = [];
-	protected errorHandler?: ErrorHandler;
-
-	constructor(options: TOptions) {
-		this.appConfig = options.appConfig;
-		this.serverOptions = options.serverOptions || {};
-		this.runtimeOptions = options.runtime ?? {};
-		this.cliArgs = parseCliArgs({ embeddedRuntime: this.runtimeOptions.embedded });
-
-		const hostModuleLoader =
-			this.runtimeOptions.hostModuleLoader ?? (this.runtimeOptions.embedded ? getHostModuleLoader() : undefined);
-
-		if (hostModuleLoader) {
-			setAppHostModuleLoader(this.appConfig, hostModuleLoader);
-		}
-
-		getAppModuleLoader(this.appConfig);
-
-		if (options.clearOutput) {
-			this.clearDistFolder().catch((error) => {
-				appLogger.error('Error clearing dist folder', error as Error);
-			});
-		}
-	}
-
-	private async clearDistFolder(): Promise<void> {
-		const distPath = this.appConfig.absolutePaths.distDir;
-		const distExists = fileSystem.exists(distPath);
-
-		if (!distExists) return;
-
-		try {
-			await fileSystem.removeAsync(distPath);
-			appLogger.debug(`Cleared dist folder: ${distPath}`);
-		} catch (error) {
-			appLogger.error(`Error clearing dist folder: ${distPath}`, error as Error);
-		}
-	}
-
-	/**
-	 * Register a GET route handler.
-	 *
-	 * Use verb methods for inline route definitions.
-	 * For dynamic HTTP method registration, use `route(...)`.
-	 */
-	abstract get<
-		P extends string,
-		TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>,
-	>(
-		path: P,
-		handler: RouteHandler<TRequest, TServer, TContext>,
-		options?: RouteOptions<TRequest, TServer, TContext>,
-	): this;
-
-	/**
-	 * Register a POST route handler
-	 */
-	abstract post<
-		P extends string,
-		TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>,
-	>(
-		path: P,
-		handler: RouteHandler<TRequest, TServer, TContext>,
-		options?: RouteOptions<TRequest, TServer, TContext>,
-	): this;
-
-	/**
-	 * Register a PUT route handler
-	 */
-	abstract put<
-		P extends string,
-		TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>,
-	>(
-		path: P,
-		handler: RouteHandler<TRequest, TServer, TContext>,
-		options?: RouteOptions<TRequest, TServer, TContext>,
-	): this;
-
-	/**
-	 * Register a DELETE route handler
-	 */
-	abstract delete<
-		P extends string,
-		TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>,
-	>(
-		path: P,
-		handler: RouteHandler<TRequest, TServer, TContext>,
-		options?: RouteOptions<TRequest, TServer, TContext>,
-	): this;
-
-	/**
-	 * Register a PATCH route handler
-	 */
-	abstract patch<
-		P extends string,
-		TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>,
-	>(
-		path: P,
-		handler: RouteHandler<TRequest, TServer, TContext>,
-		options?: RouteOptions<TRequest, TServer, TContext>,
-	): this;
-
-	/**
-	 * Register an OPTIONS route handler
-	 */
-	abstract options<
-		P extends string,
-		TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>,
-	>(
-		path: P,
-		handler: RouteHandler<TRequest, TServer, TContext>,
-		options?: RouteOptions<TRequest, TServer, TContext>,
-	): this;
-
-	/**
-	 * Register a HEAD route handler
-	 */
-	abstract head<
-		P extends string,
-		TContext extends ApiHandlerContext<TRequest, TServer> = ApiHandlerContext<TRequest, TServer>,
-	>(
-		path: P,
-		handler: RouteHandler<TRequest, TServer, TContext>,
-		options?: RouteOptions<TRequest, TServer, TContext>,
-	): this;
-
-	/**
-	 * Register a route with an explicit HTTP method.
-	 *
-	 * This is useful when the method is determined programmatically, or when
-	 * registering a pre-built route declaration object by forwarding its
-	 * `path`, `method`, and `handler` fields.
-	 */
-	abstract route<P extends string>(
-		path: P,
-		method: ApiHandler['method'],
-		handler: RouteHandler<TRequest, TServer>,
-		options?: RouteOptions<TRequest, TServer>,
-	): this;
-
-	/**
-	 * Register a pre-built API handler declaration.
-	 */
-	abstract add(handler: ApiHandler<string, TRequest, TServer>): this;
-
-	/**
-	 * Internal method to add route handlers to the API handlers array
-	 */
-	protected addRouteHandler<
-		P extends string,
-		TSpecRequest extends TRequest = TRequest,
-		TSpecServer extends TServer = TServer,
-		TContext extends ApiHandlerContext<TSpecRequest, TSpecServer> = ApiHandlerContext<TSpecRequest, TSpecServer>,
-	>(
-		path: P,
-		method: ApiHandler['method'],
-		handler: RouteHandler<TSpecRequest, TSpecServer, TContext>,
-		middleware?: Middleware<TSpecRequest, TSpecServer, TContext>[],
-		schema?: ApiHandler['schema'],
-	): this {
-		invariant(
-			typeof path === 'string',
-			`Invalid route path for ${method}: expected a string path starting with "/" but received ${Object.prototype.toString.call(path)}. If you're passing a prebuilt ApiHandler, use app.add(handler).`,
-		);
-
-		invariant(
-			path.startsWith('/'),
-			`Invalid route path for ${method}: "${path}". Route paths must start with '/'.`,
-		);
-
-		this.apiHandlers.push({
-			path,
-			method,
-			handler: handler as ApiHandler['handler'],
-			middleware: middleware as ApiHandler['middleware'],
-			schema,
-		});
-		return this;
-	}
-
-	/**
-	 * Create a route group with shared prefix and middleware.
-	 * Routes defined within the group inherit the prefix and middleware.
-	 *
-	 * Each adapter implements this with its own builder type to support
-	 * runtime-specific features (e.g., Bun's path parameter inference).
-	 * Implementations may also support passing a pre-built group object.
-	 *
-	 * @param prefix - URL prefix for all routes in the group (e.g., '/api/v1')
-	 * @param callback - Function that receives a builder to define routes
-	 * @param options - Optional group-level middleware
-	 */
-	abstract group(
-		prefix: string,
-		callback: (builder: unknown) => void,
-		options?: {
-			middleware?: readonly Middleware<TRequest, TServer, any>[];
-		},
-	): this;
-
-	abstract group(group: RouteGroupDefinition<TRequest, TServer>): this;
-
-	/**
-	 * Get all registered API handlers
-	 */
-	getApiHandlers(): ApiHandler[] {
-		return this.apiHandlers;
-	}
-
-	/**
-	 * Register a view for static generation at build time.
-	 * The view must have staticPaths defined for dynamic routes.
-	 *
-	 * Uses a loader function to enable HMR in development.
-	 *
-	 * @param path - URL path pattern (e.g., '/posts/:slug')
-	 * @param loader - A function that dynamically imports the eco.page view module
-	 * @example
-	 * ```typescript
-	 * app.static('/login', () => import('./src/views/login.kita'))
-	 * app.static('/posts/:slug', () => import('./src/views/post-view.kita'))
-	 * ```
-	 */
-	static<P>(path: string, loader: ViewLoader<P>): this {
-		this.staticRoutes.push({ path, loader });
-		return this;
-	}
-
-	/**
-	 * Get all registered static routes
-	 */
-	getStaticRoutes(): StaticRoute[] {
-		return this.staticRoutes;
-	}
-
-	/**
-	 * Register a global error handler for all routes.
-	 * Useful for logging, monitoring integration, and custom error formatting.
-	 *
-	 * @example
-	 * ```typescript
-	 * app.onError(async (error, ctx) => {
-	 *   logger.error(error);
-	 *   return ctx.response.status(500).json({ error: 'Something went wrong' });
-	 * });
-	 * ```
-	 */
-	onError(handler: ErrorHandler<TRequest, TServer>): this {
-		this.errorHandler = handler as unknown as ErrorHandler;
-		return this;
-	}
-
-	/**
-	 * Get the registered error handler
-	 */
-	getErrorHandler(): ErrorHandler | undefined {
-		return this.errorHandler;
-	}
-
-	/**
-	 * Initialize the server adapter based on the runtime
-	 */
-	protected abstract initializeServerAdapter(): Promise<any>;
-
-	/**
-	 * Start the application server
-	 */
-	public abstract start(): Promise<TServer | void>;
-
-	/**
-	 * Handles a standard Web request without requiring a bound network server.
-	 * This is the primary interoperability surface for embedding Ecopages inside
-	 * other runtimes and frameworks.
-	 */
-	public abstract fetch(request: TRequest): Promise<Response>;
-}

package/src/adapters/abstract/router-adapter.ts

@@ -1,30 +0,0 @@
-/**
- * This file contains the abstract router adapter class and its methods.
- * It is designed to be extended by specific router adapters for different runtimes.
- * The class provides methods for converting paths, creating route handlers,
- * and adapting routes to the expected format of the runtime.
- *
- * @module RouterAdapter
- */
-
-import type { Routes } from '../../types/internal-types.ts';
-
-/**
- * Abstract base class for router adapters across different runtimes
- */
-export abstract class AbstractRouterAdapter<TRouteFormat = any> {
-	/**
-	 * Convert a route path to the format expected by the runtime
-	 */
-	protected abstract convertPath(pathname: string): string;
-
-	/**
-	 * Create a route handler compatible with the runtime
-	 */
-	protected abstract createRouteHandler(route: any): any;
-
-	/**
-	 * Adapt framework routes to the format expected by the runtime
-	 */
-	public abstract adaptRoutes(routes: Routes): TRouteFormat;
-}

package/src/adapters/abstract/server-adapter.ts

@@ -1,79 +0,0 @@
-/**
- * This file contains the abstract server adapter class and its related types.
- * It is designed to be extended by specific server adapters for different runtimes.
- * The class provides methods for initializing the server, creating server options,
- * building static files, and handling HTTP requests.
- *
- * @module ServerAdapter
- */
-
-import type { EcoPagesAppConfig } from '../../types/internal-types.ts';
-import type { ApiHandler } from '../../types/public-types.ts';
-
-/**
- * Configuration options for all server adapters
- */
-export interface ServerAdapterOptions {
-	appConfig: EcoPagesAppConfig;
-	apiHandlers?: ApiHandler<string, any>[];
-	options?: {
-		watch?: boolean;
-		[key: string]: any;
-	};
-	serveOptions?: Record<string, any>;
-	runtimeOrigin: string;
-}
-
-/**
- * Base adapter result containing common functionalities
- * across different runtime implementations
- */
-export interface ServerAdapterResult {
-	getServerOptions: (options?: { enableHmr?: boolean }) => any;
-	buildStatic: (options?: { preview?: boolean }) => Promise<void>;
-}
-
-/**
- * Abstract base class for server adapters across different runtimes
- */
-export abstract class AbstractServerAdapter<
-	TOptions extends ServerAdapterOptions = ServerAdapterOptions,
-	TResult extends ServerAdapterResult = ServerAdapterResult,
-> {
-	protected appConfig: EcoPagesAppConfig;
-	protected options: TOptions['options'];
-	protected serveOptions: TOptions['serveOptions'];
-	protected runtimeOrigin: string;
-
-	constructor(options: TOptions) {
-		this.appConfig = options.appConfig;
-		this.options = options.options || {};
-		this.serveOptions = options.serveOptions || {};
-		this.runtimeOrigin = options.runtimeOrigin;
-	}
-
-	/**
-	 * Initialize the server adapter
-	 */
-	public abstract initialize(): Promise<void>;
-
-	/**
-	 * Create server options specific to the runtime
-	 */
-	public abstract getServerOptions(options?: { enableHmr?: boolean }): any;
-
-	/**
-	 * Build static files for the application
-	 */
-	public abstract buildStatic(options?: { preview?: boolean }): Promise<void>;
-
-	/**
-	 * Factory method to create a server adapter with runtime-specific functionality
-	 */
-	public abstract createAdapter(): Promise<TResult>;
-
-	/**
-	 * Handle HTTP requests
-	 */
-	public abstract handleRequest(request: Request): Promise<Response>;
-}

package/src/adapters/bun/client-bridge.ts

@@ -1,62 +0,0 @@
-import type { ServerWebSocket } from 'bun';
-import type { ClientBridgeEvent, IClientBridge } from '../../types/public-types.ts';
-
-type BunSocket = ServerWebSocket<unknown>;
-
-/**
- * Manages WebSocket subscribers and broadcasts development events.
- * Bridges the gap between the server and the development client.
- */
-export class ClientBridge implements IClientBridge {
-	private subscribers = new Set<BunSocket>();
-
-	subscribe(ws: BunSocket): void {
-		this.subscribers.add(ws);
-	}
-
-	unsubscribe(ws: BunSocket): void {
-		this.subscribers.delete(ws);
-	}
-
-	/**
-	 * Broadcast a raw event to all connected clients.
-	 */
-	broadcast(event: ClientBridgeEvent): void {
-		const payload = JSON.stringify(event);
-		for (const ws of this.subscribers) {
-			ws.send(payload);
-		}
-	}
-
-	/**
-	 * Trigger a full page reload on all connected clients.
-	 */
-	reload(): void {
-		this.broadcast({ type: 'reload' });
-	}
-
-	/**
-	 * Broadcast a CSS update for hot stylesheet reload.
-	 */
-	cssUpdate(path: string): void {
-		this.broadcast({ type: 'css-update', path, timestamp: Date.now() });
-	}
-
-	/**
-	 * Broadcast a JS module update for hot module replacement.
-	 */
-	update(path: string): void {
-		this.broadcast({ type: 'update', path, timestamp: Date.now() });
-	}
-
-	/**
-	 * Broadcast an error message to connected clients.
-	 */
-	error(message: string): void {
-		this.broadcast({ type: 'error', message });
-	}
-
-	get subscriberCount(): number {
-		return this.subscribers.size;
-	}
-}