@ecopages/core 0.2.0-alpha.1

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

@@ -0,0 +1,109 @@
+import { appLogger } from "../../global/app-logger.js";
+import { invariant } from "../../utils/invariant.js";
+import { fileSystem } from "@ecopages/file-system";
+import { parseCliArgs } from "../../utils/parse-cli-args.js";
+class AbstractApplicationAdapter {
+  appConfig;
+  serverOptions;
+  cliArgs;
+  apiHandlers = [];
+  staticRoutes = [];
+  errorHandler;
+  constructor(options) {
+    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);
+      });
+    }
+  }
+  async clearDistFolder(_filter = []) {
+    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);
+    }
+  }
+  /**
+   * Internal method to add route handlers to the API handlers array
+   */
+  addRouteHandler(path, method, handler, middleware, schema) {
+    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,
+      middleware,
+      schema
+    });
+    return this;
+  }
+  /**
+   * Get all registered API handlers
+   */
+  getApiHandlers() {
+    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(path, loader) {
+    this.staticRoutes.push({ path, loader });
+    return this;
+  }
+  /**
+   * Get all registered static routes
+   */
+  getStaticRoutes() {
+    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) {
+    this.errorHandler = handler;
+    return this;
+  }
+  /**
+   * Get the registered error handler
+   */
+  getErrorHandler() {
+    return this.errorHandler;
+  }
+}
+export {
+  AbstractApplicationAdapter
+};

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

@@ -0,0 +1,337 @@
+/**
+ * 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.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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.js';
+/**
+ * Abstract base class for router adapters across different runtimes
+ */
+export declare 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
+     */
+    abstract adaptRoutes(routes: Routes): TRouteFormat;
+}

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

@@ -0,0 +1,5 @@
+class AbstractRouterAdapter {
+}
+export {
+  AbstractRouterAdapter
+};

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

@@ -0,0 +1,30 @@
+/**
+ * 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.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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.js';
+import type { ApiHandler } from '../../public-types.js';
+/**
+ * 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 declare 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);
+    /**
+     * Initialize the server adapter
+     */
+    abstract initialize(): Promise<void>;
+    /**
+     * Create server options specific to the runtime
+     */
+    abstract getServerOptions(options?: {
+        enableHmr?: boolean;
+    }): any;
+    /**
+     * Build static files for the application
+     */
+    abstract buildStatic(options?: {
+        preview?: boolean;
+    }): Promise<void>;
+    /**
+     * Factory method to create a server adapter with runtime-specific functionality
+     */
+    abstract createAdapter(): Promise<TResult>;
+    /**
+     * Handle HTTP requests
+     */
+    abstract handleRequest(request: Request): Promise<Response>;
+}

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

@@ -0,0 +1,15 @@
+class AbstractServerAdapter {
+  appConfig;
+  options;
+  serveOptions;
+  runtimeOrigin;
+  constructor(options) {
+    this.appConfig = options.appConfig;
+    this.options = options.options || {};
+    this.serveOptions = options.serveOptions || {};
+    this.runtimeOrigin = options.runtimeOrigin;
+  }
+}
+export {
+  AbstractServerAdapter
+};

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

@@ -0,0 +1,79 @@
+/**
+ * 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>;
+}