@ecopages/core 0.2.0-alpha.9 → 0.2.1-beta.0

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

@@ -1,337 +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 type { EcoPagesAppConfig } from '../../internal-types.ts';
-import { invariant } from '../../utils/invariant.ts';
-import type {
-	ApiHandler,
-	ApiHandlerContext,
-	ErrorHandler,
-	Middleware,
-	RouteOptions,
-	StaticRoute,
-	ViewLoader,
-} from '../../public-types.ts';
-import { fileSystem } from '@ecopages/file-system';
-import { parseCliArgs, type ReturnParseCliArgs } from '../../utils/parse-cli-args.ts';
-
-/**
- * Configuration options for application adapters
- */
-export interface ApplicationAdapterOptions {
-	appConfig: EcoPagesAppConfig;
-	serverOptions?: Record<string, any>;
-	/**
-	 * 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 apiHandlers: ApiHandler[] = [];
-	protected staticRoutes: StaticRoute[] = [];
-	protected errorHandler?: ErrorHandler;
-
-	constructor(options: TOptions) {
-		this.appConfig = options.appConfig;
-		this.serverOptions = options.serverOptions || {};
-		this.cliArgs = parseCliArgs();
-
-		if (options.clearOutput) {
-			this.clearDistFolder().catch((error) => {
-				appLogger.error('Error clearing dist folder', error as Error);
-			});
-		}
-	}
-
-	private async clearDistFolder(_filter: string[] = []): 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 '../../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 '../../internal-types.ts';
-import type { ApiHandler } from '../../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 '../../public-types';
-
-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;
-	}
-}

package/src/adapters/bun/create-app.ts

@@ -1,189 +0,0 @@
-/**
- * This file contains the implementation of the Bun application adapter for EcoPages.
- * It extends the AbstractApplicationAdapter class and provides methods for handling
- * HTTP requests, initializing the server adapter, and starting the Bun application server.
- * The adapter is designed to work with the Bun runtime and provides a way to create
- * EcoPages applications using Bun's features.
- *
- * @module EcopagesApp
- */
-
-import type { Server } from 'bun';
-import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from '../../constants.ts';
-import { appLogger } from '../../global/app-logger.ts';
-import type { EcoPagesAppConfig } from '../../internal-types.ts';
-import { getBunRuntime } from '../../utils/runtime.ts';
-import type { ApiHandlerContext, RouteGroupBuilder } from '../../public-types.ts';
-import { type ApplicationAdapterOptions } from '../abstract/application-adapter.ts';
-import { SharedApplicationAdapter } from '../shared/application-adapter.ts';
-import { type BunServerAdapterResult, createBunServerAdapter } from './server-adapter.ts';
-
-/**
- * Configuration options for the Bun application adapter
- */
-export interface EcopagesAppOptions extends ApplicationAdapterOptions {
-	appConfig: EcoPagesAppConfig;
-	serverOptions?: Record<string, any>;
-}
-
-/**
- * Bun-specific route group builder that properly infers route params from path patterns.
- * When you define a route like `/posts/:slug`, the handler context will have
- * `ctx.params.slug` typed as `string`.
- *
- * @typeParam WebSocketData - WebSocket data type for the server
- * @typeParam TContext - Extended context type from middleware (e.g., `{ user: User }`)
- */
-export type BunRouteGroupBuilder<
-	WebSocketData = undefined,
-	TContext extends ApiHandlerContext<Request, Server<WebSocketData>> = ApiHandlerContext<
-		Request,
-		Server<WebSocketData>
-	>,
-> = RouteGroupBuilder<Request, Server<WebSocketData>, TContext>;
-
-/**
- * Bun-specific application adapter implementation
- * This class extends the {@link AbstractApplicationAdapter}
- * and provides methods for handling HTTP requests and managing the server.
- */
-
-export class EcopagesApp<WebSocketData = undefined> extends SharedApplicationAdapter<
-	EcopagesAppOptions,
-	Server<WebSocketData>,
-	Request
-> {
-	serverAdapter: BunServerAdapterResult | undefined;
-	private server: Server<WebSocketData> | null = null;
-
-	public async fetch(request: Request): Promise<Response> {
-		if (!this.serverAdapter) {
-			this.serverAdapter = await this.initializeServerAdapter();
-		}
-
-		await this.serverAdapter.completeInitialization(this.server);
-		return this.serverAdapter.handleRequest(request);
-	}
-
-	/**
-	 * Complete the initialization of the server adapter by processing dynamic routes
-	 * @param server The Bun server instance
-	 */
-	public async completeInitialization(server: Server<WebSocketData>): Promise<void> {
-		if (!this.serverAdapter) {
-			throw new Error('Server adapter not initialized. Call start() first.');
-		}
-
-		await this.serverAdapter.completeInitialization(server);
-	}
-
-	/**
-	 * Initialize the Bun server adapter
-	 */
-	protected async initializeServerAdapter(): Promise<BunServerAdapterResult> {
-		const { dev } = this.cliArgs;
-		const { port: cliPort, hostname: cliHostname } = this.cliArgs;
-
-		const envPort = process.env.ECOPAGES_PORT ? process.env.ECOPAGES_PORT : undefined;
-		const envHostname = process.env.ECOPAGES_HOSTNAME;
-
-		const preferredPort = cliPort ?? envPort ?? DEFAULT_ECOPAGES_PORT;
-		const preferredHostname = cliHostname ?? envHostname ?? DEFAULT_ECOPAGES_HOSTNAME;
-
-		appLogger.debug('initializeServerAdapter', {
-			dev,
-			cliPort,
-			cliHostname,
-			envPort,
-			envHostname,
-			preferredPort,
-			preferredHostname,
-			composedUrl: `http://${preferredHostname}:${preferredPort}`,
-		});
-
-		return await createBunServerAdapter({
-			runtimeOrigin: `http://${preferredHostname}:${preferredPort}`,
-			appConfig: this.appConfig,
-			apiHandlers: this.apiHandlers,
-			staticRoutes: this.staticRoutes,
-			errorHandler: this.errorHandler,
-			options: { watch: dev },
-			serveOptions: {
-				port: preferredPort,
-				hostname: preferredHostname,
-				...this.serverOptions,
-			},
-		});
-	}
-
-	/**
-	 * Start the Bun application server
-	 * @param options Optional settings
-	 * @param options.autoCompleteInitialization Whether to automatically complete initialization with dynamic routes after server start (defaults to true)
-	 */
-	public async start(): Promise<Server<WebSocketData> | void> {
-		if (!this.serverAdapter) {
-			this.serverAdapter = await this.initializeServerAdapter();
-		}
-
-		const { dev, preview, build } = this.cliArgs;
-		const requiresFetchRuntime = this.appConfig.integrations.some(
-			(integration) => integration.staticBuildStep === 'fetch',
-		);
-		const canBuildWithoutRuntimeServer = (build || preview) && !requiresFetchRuntime;
-
-		if (canBuildWithoutRuntimeServer) {
-			appLogger.debugTime('Building static pages');
-			await this.serverAdapter.buildStatic({ preview });
-			appLogger.debugTimeEnd('Building static pages');
-
-			if (build) {
-				process.exit(0);
-			}
-
-			return;
-		}
-
-		const enableHmr = dev || (!preview && !build);
-		const serverOptions = this.serverAdapter.getServerOptions({ enableHmr });
-
-		const bun = getBunRuntime();
-		if (!bun) {
-			throw new Error('Bun runtime is required for the Bun adapter');
-		}
-
-		const bunServer = bun.serve(serverOptions as Bun.Serve.Options<WebSocketData>);
-		this.server = bunServer as Server<WebSocketData>;
-
-		await this.serverAdapter.completeInitialization(this.server).catch((error: Error) => {
-			appLogger.error(`Failed to complete initialization: ${error}`);
-		});
-
-		if (!this.server) {
-			throw new Error('Server failed to start');
-		}
-		appLogger.info(`Server running at http://${this.server.hostname}:${this.server.port}`);
-
-		if (build || preview) {
-			appLogger.debugTime('Building static pages');
-			await this.serverAdapter.buildStatic({ preview });
-			this.server.stop(true);
-			appLogger.debugTimeEnd('Building static pages');
-
-			if (build) {
-				process.exit(0);
-			}
-		}
-
-		return this.server;
-	}
-}
-
-/**
- * Factory function to create a Bun application
- */
-export async function createApp<WebSocketData = undefined>(
-	options: EcopagesAppOptions,
-): Promise<EcopagesApp<WebSocketData>> {
-	return new EcopagesApp(options);
-}