@ecopages/core 0.2.0-alpha.1

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

@@ -0,0 +1,34 @@
+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 declare class ClientBridge implements IClientBridge {
+    private subscribers;
+    subscribe(ws: BunSocket): void;
+    unsubscribe(ws: BunSocket): void;
+    /**
+     * Broadcast a raw event to all connected clients.
+     */
+    broadcast(event: ClientBridgeEvent): void;
+    /**
+     * Trigger a full page reload on all connected clients.
+     */
+    reload(): void;
+    /**
+     * Broadcast a CSS update for hot stylesheet reload.
+     */
+    cssUpdate(path: string): void;
+    /**
+     * Broadcast a JS module update for hot module replacement.
+     */
+    update(path: string): void;
+    /**
+     * Broadcast an error message to connected clients.
+     */
+    error(message: string): void;
+    get subscriberCount(): number;
+}
+export {};

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

@@ -0,0 +1,48 @@
+class ClientBridge {
+  subscribers = /* @__PURE__ */ new Set();
+  subscribe(ws) {
+    this.subscribers.add(ws);
+  }
+  unsubscribe(ws) {
+    this.subscribers.delete(ws);
+  }
+  /**
+   * Broadcast a raw event to all connected clients.
+   */
+  broadcast(event) {
+    const payload = JSON.stringify(event);
+    for (const ws of this.subscribers) {
+      ws.send(payload);
+    }
+  }
+  /**
+   * Trigger a full page reload on all connected clients.
+   */
+  reload() {
+    this.broadcast({ type: "reload" });
+  }
+  /**
+   * Broadcast a CSS update for hot stylesheet reload.
+   */
+  cssUpdate(path) {
+    this.broadcast({ type: "css-update", path, timestamp: Date.now() });
+  }
+  /**
+   * Broadcast a JS module update for hot module replacement.
+   */
+  update(path) {
+    this.broadcast({ type: "update", path, timestamp: Date.now() });
+  }
+  /**
+   * Broadcast an error message to connected clients.
+   */
+  error(message) {
+    this.broadcast({ type: "error", message });
+  }
+  get subscriberCount() {
+    return this.subscribers.size;
+  }
+}
+export {
+  ClientBridge
+};

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

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

@@ -0,0 +1,60 @@
+/**
+ * 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 type { EcoPagesAppConfig } from '../../internal-types.js';
+import type { ApiHandlerContext, RouteGroupBuilder } from '../../public-types.js';
+import { type ApplicationAdapterOptions } from '../abstract/application-adapter.js';
+import { SharedApplicationAdapter } from '../shared/application-adapter.js';
+import { type BunServerAdapterResult } from './server-adapter.js';
+/**
+ * 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 declare class EcopagesApp<WebSocketData = undefined> extends SharedApplicationAdapter<EcopagesAppOptions, Server<WebSocketData>, Request> {
+    serverAdapter: BunServerAdapterResult | undefined;
+    private server;
+    fetch(request: Request): Promise<Response>;
+    /**
+     * Complete the initialization of the server adapter by processing dynamic routes
+     * @param server The Bun server instance
+     */
+    completeInitialization(server: Server<WebSocketData>): Promise<void>;
+    /**
+     * Initialize the Bun server adapter
+     */
+    protected initializeServerAdapter(): Promise<BunServerAdapterResult>;
+    /**
+     * 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)
+     */
+    start(): Promise<Server<WebSocketData> | void>;
+}
+/**
+ * Factory function to create a Bun application
+ */
+export declare function createApp<WebSocketData = undefined>(options: EcopagesAppOptions): Promise<EcopagesApp<WebSocketData>>;

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

@@ -0,0 +1,117 @@
+import { DEFAULT_ECOPAGES_HOSTNAME, DEFAULT_ECOPAGES_PORT } from "../../constants.js";
+import { appLogger } from "../../global/app-logger.js";
+import { getBunRuntime } from "../../utils/runtime.js";
+import {} from "../abstract/application-adapter.js";
+import { SharedApplicationAdapter } from "../shared/application-adapter.js";
+import { createBunServerAdapter } from "./server-adapter.js";
+class EcopagesApp extends SharedApplicationAdapter {
+  serverAdapter;
+  server = null;
+  async fetch(request) {
+    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
+   */
+  async completeInitialization(server) {
+    if (!this.serverAdapter) {
+      throw new Error("Server adapter not initialized. Call start() first.");
+    }
+    await this.serverAdapter.completeInitialization(server);
+  }
+  /**
+   * Initialize the Bun server adapter
+   */
+  async initializeServerAdapter() {
+    const { dev } = this.cliArgs;
+    const { port: cliPort, hostname: cliHostname } = this.cliArgs;
+    const envPort = process.env.ECOPAGES_PORT ? process.env.ECOPAGES_PORT : void 0;
+    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)
+   */
+  async start() {
+    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);
+    this.server = bunServer;
+    await this.serverAdapter.completeInitialization(this.server).catch((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;
+  }
+}
+async function createApp(options) {
+  return new EcopagesApp(options);
+}
+export {
+  EcopagesApp,
+  createApp
+};

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

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

package/src/adapters/bun/define-api-handler.d.ts

@@ -0,0 +1,61 @@
+import type { Server } from 'bun';
+import type { ApiHandler, ApiHandlerContext, Middleware, RouteSchema, TypedGroupHandlerContext } from '../../public-types';
+type BunSchemaHandlerContext<TSchema extends RouteSchema | undefined, WebSocketData, TContext extends ApiHandlerContext<Request, Server<WebSocketData>>> = TSchema extends RouteSchema ? TypedGroupHandlerContext<TSchema, TContext> : TContext;
+/**
+ * Helper function specifically for Bun to define an API handler with
+ * automatically inferred path type for BunRequest.
+ *
+ * This returns a self-describing route declaration (`path`, `method`, `handler`,
+ * optional `middleware`, optional `schema`) that can be registered on the app.
+ *
+ * @template TPath The literal string type of the path, inferred from the 'path' property.
+ * @param handler The API handler configuration object using BunRequest.
+ * @returns The same handler object, strongly typed for Bun.
+ */
+export declare function defineApiHandler<TSchema extends RouteSchema | undefined = undefined, WebSocketData = undefined, TContext extends ApiHandlerContext<Request, Server<WebSocketData>> = ApiHandlerContext<Request, Server<WebSocketData>>>(handler: Omit<ApiHandler<string, Request, Server<WebSocketData>>, 'handler' | 'middleware' | 'schema'> & {
+    handler: (context: BunSchemaHandlerContext<TSchema, WebSocketData, TContext>) => Promise<Response> | Response;
+    middleware?: Middleware<Request, Server<WebSocketData>, TContext>[];
+    schema?: TSchema;
+}): ApiHandler<string, Request, Server<WebSocketData>>;
+/**
+ * Configuration for a group of related API handlers with shared prefix and middleware.
+ */
+export interface GroupHandler<TPrefix extends string = string, WebSocketData = undefined> {
+    prefix: TPrefix;
+    middleware?: readonly Middleware<Request, Server<WebSocketData>, any>[];
+    routes: readonly ApiHandler<string, Request, Server<WebSocketData>>[];
+}
+type GroupDefineHandler<WebSocketData, TContext extends ApiHandlerContext<Request, Server<WebSocketData>>> = <const TPath extends string, TSchema extends RouteSchema | undefined = undefined>(handler: Omit<ApiHandler<TPath, Request, Server<WebSocketData>>, 'handler' | 'middleware' | 'schema'> & {
+    path: TPath;
+    handler: (context: TSchema extends RouteSchema ? TypedGroupHandlerContext<TSchema, TContext> : TContext) => Promise<Response> | Response;
+    middleware?: Middleware<Request, Server<WebSocketData>, TContext>[];
+    schema?: TSchema;
+}) => ApiHandler<TPath, Request, Server<WebSocketData>>;
+/**
+ * Helper function to define a group of API handlers with shared prefix and middleware.
+ * The group middleware context is inferred and passed to all route handlers.
+ *
+ * @example
+ * ```typescript
+ * const adminGroup = defineGroupHandler({
+ *   prefix: '/admin',
+ *   middleware: [authMiddleware],
+ *   routes: (define) => [
+ *     define({ path: '/', method: 'GET', handler: (ctx) => ctx.render(List, {}) }),
+ *     define({ path: '/posts/:id', method: 'GET', handler: (ctx) => {
+ *       // ctx.session is typed from authMiddleware!
+ *       // ctx.params.id is typed from path!
+ *       return ctx.render(Post, { id: ctx.params.id });
+ *     }}),
+ *   ],
+ * });
+ *
+ * app.group(adminGroup);
+ * ```
+ */
+export declare function defineGroupHandler<TPrefix extends string, WebSocketData = undefined, TMiddleware extends readonly Middleware<Request, Server<WebSocketData>, any>[] = [], TContext extends ApiHandlerContext<Request, Server<WebSocketData>> = TMiddleware extends readonly Middleware<Request, Server<WebSocketData>, infer TGroupContext>[] ? TGroupContext : ApiHandlerContext<Request, Server<WebSocketData>>>(config: {
+    prefix: TPrefix;
+    middleware?: TMiddleware;
+    routes: (define: GroupDefineHandler<WebSocketData, TContext>) => readonly ApiHandler<string, Request, Server<WebSocketData>>[];
+}): GroupHandler<TPrefix, WebSocketData>;
+export {};

package/src/adapters/bun/define-api-handler.js

@@ -0,0 +1,15 @@
+function defineApiHandler(handler) {
+  return handler;
+}
+function defineGroupHandler(config) {
+  const define = ((handler) => handler);
+  return {
+    prefix: config.prefix,
+    middleware: config.middleware,
+    routes: config.routes(define)
+  };
+}
+export {
+  defineApiHandler,
+  defineGroupHandler
+};