create-phoenixjs 0.1.0

package/template/framework/core/Kernel.ts

@@ -0,0 +1,297 @@
+/**
+ * PhoenixJS - HTTP Kernel
+ * 
+ * The HTTP Kernel is the heart of the framework.
+ * It receives all HTTP requests and returns responses.
+ * Now integrated with Router and Middleware Pipeline.
+ */
+
+import { Application } from '@framework/core/Application';
+import { FrameworkRequest } from '@framework/http/Request';
+import { FrameworkResponse } from '@framework/http/Response';
+import { Router } from '@framework/routing/Router';
+import { Pipeline } from '@framework/middleware/Pipeline';
+import type { MiddlewareHandler, MiddlewareResolvable } from '@framework/middleware/Middleware';
+import type { RouteMatch } from '@framework/routing/RouteRegistry';
+import type { ControllerConstructor } from '@framework/controller/Controller';
+
+export class Kernel {
+	protected app: Application;
+	protected globalMiddleware: MiddlewareHandler[] = [];
+	protected middlewareGroups: Map<string, MiddlewareHandler[]> = new Map();
+
+	constructor(app: Application) {
+		this.app = app;
+	}
+
+	/**
+	 * Register global middleware that runs on every request
+	 */
+	middleware(middleware: MiddlewareHandler[]): this {
+		this.globalMiddleware = middleware;
+		return this;
+	}
+
+	/**
+	 * Register middleware groups
+	 */
+	middlewareGroup(name: string, middleware: MiddlewareHandler[]): this {
+		this.middlewareGroups.set(name, middleware);
+		return this;
+	}
+
+	/**
+	 * Handle an incoming HTTP request
+	 * 
+	 * This is the main entry point for all HTTP requests.
+	 * It integrates with the Router and Middleware Pipeline.
+	 */
+	async handle(request: Request): Promise<Response> {
+		const frameworkRequest = new FrameworkRequest(request);
+
+		try {
+			// Run the request through global middleware, then dispatch
+			const response = await new Pipeline()
+				.send(frameworkRequest)
+				.through(this.globalMiddleware)
+				.then((req) => this.dispatch(req));
+
+			return response;
+		} catch (error) {
+			return this.handleException(error);
+		}
+	}
+
+	/**
+	 * Dispatch the request through the router
+	 */
+	protected async dispatch(request: FrameworkRequest): Promise<Response> {
+		const method = request.method();
+		const path = request.path();
+
+		// Try to resolve the route
+		const match = Router.resolve(method, path);
+
+		if (match) {
+			return this.runRoute(request, match);
+		}
+
+		// No route matched - check for fallback routes (root and health)
+		return this.handleFallback(request, path);
+	}
+
+	/**
+	 * Run the matched route through its middleware and handler
+	 */
+	protected async runRoute(request: FrameworkRequest, match: RouteMatch): Promise<Response> {
+		const { route, params } = match;
+
+		// Set the params on the request
+		request.setParams(params);
+
+		// Resolve route middleware
+		const routeMiddleware = this.resolveMiddleware(route.middleware);
+
+		// Run through route middleware then execute handler
+		return new Pipeline()
+			.send(request)
+			.through(routeMiddleware)
+			.then(async (req) => {
+				return this.executeHandler(req, match);
+			});
+	}
+
+	/**
+	 * Execute the route handler
+	 */
+	protected async executeHandler(request: FrameworkRequest, match: RouteMatch): Promise<Response> {
+		const { route, params } = match;
+		const handler = route.handler;
+
+		// If handler is a function, call it directly
+		if (typeof handler === 'function') {
+			const result = await handler(params);
+			return result;
+		}
+
+		// If handler is a string (Controller@method), resolve and execute
+		return this.executeControllerAction(request, handler, params);
+	}
+
+	/**
+	 * Execute a controller action from a string handler
+	 * Format: "path/to/Controller@methodName" or "ControllerName@methodName"
+	 */
+	protected async executeControllerAction(
+		request: FrameworkRequest,
+		handler: string,
+		params: Record<string, string>
+	): Promise<Response> {
+		const atIndex = handler.indexOf('@');
+		if (atIndex === -1) {
+			return FrameworkResponse.error(
+				`Invalid controller handler format: ${handler}. Expected "Controller@method"`,
+				500
+			);
+		}
+
+		const controllerPath = handler.substring(0, atIndex);
+		const methodName = handler.substring(atIndex + 1);
+
+		try {
+			// Resolve the controller class
+			const ControllerClass = await this.resolveController(controllerPath);
+
+			if (!ControllerClass) {
+				return FrameworkResponse.error(
+					`Controller not found: ${controllerPath}`,
+					500
+				);
+			}
+
+			// Instantiate the controller
+			const controller = new ControllerClass();
+
+			// Inject request and params
+			controller.setRequest(request);
+			controller.setParams(params);
+
+			// Check if method exists
+			const controllerAny = controller as unknown as Record<string, unknown>;
+			if (typeof controllerAny[methodName] !== 'function') {
+				console.log(`Debug: Method ${methodName} lookup failed on ${ControllerClass.name}`);
+				console.log('Debug: Available keys:', Object.keys(controllerAny));
+				console.log('Debug: Prototype keys:', Object.getOwnPropertyNames(Object.getPrototypeOf(controllerAny)));
+				// Add more debug info
+				console.log('Debug: ControllerClass source:', ControllerClass.toString());
+
+
+				return FrameworkResponse.error(
+					`Method ${methodName} not found on controller ${controllerPath}`,
+					500
+				);
+			}
+
+			// Execute the method
+			const result = await (controllerAny[methodName] as () => Promise<Response>)();
+			return result;
+		} catch (error) {
+			const message = error instanceof Error ? error.message : 'Controller execution failed';
+			return FrameworkResponse.error(message, 500);
+		}
+	}
+
+	/**
+	 * Resolve a controller class from its path
+	 * Supports: "user/UserController", "HealthController", full paths
+	 */
+	protected async resolveController(controllerPath: string): Promise<ControllerConstructor | null> {
+		// Build possible import paths
+		const paths = [
+			`@app/controllers/${controllerPath}`,
+			`./app/controllers/${controllerPath}`,
+			`../app/controllers/${controllerPath}`,
+		];
+
+		// Normalize path - remove .ts extension if present
+		const normalizedPath = controllerPath.replace(/\.ts$/, '');
+
+		for (const basePath of paths) {
+			const fullPath = basePath.replace(controllerPath, normalizedPath);
+			try {
+				// Dynamic import
+				const module = await import(fullPath);
+
+				// Get the controller class (default export or named export matching filename)
+				const className = normalizedPath.split('/').pop() || normalizedPath;
+				const ControllerClass = module.default || module[className];
+
+				if (ControllerClass) {
+					return ControllerClass as ControllerConstructor;
+				}
+			} catch {
+				// Try next path
+				continue;
+			}
+		}
+
+		return null;
+	}
+
+	/**
+	 * Resolve middleware from their resolvable forms
+	 */
+	protected resolveMiddleware(middleware: MiddlewareResolvable[]): MiddlewareHandler[] {
+		const resolved: MiddlewareHandler[] = [];
+
+		for (const m of middleware) {
+			if (typeof m === 'string') {
+				// Check for middleware alias
+				const aliased = Router.resolveMiddleware(m);
+				if (aliased && typeof aliased !== 'string') {
+					resolved.push(aliased);
+				}
+				// Check for middleware group
+				else if (this.middlewareGroups.has(m)) {
+					resolved.push(...(this.middlewareGroups.get(m) || []));
+				}
+				// String middleware not resolved - skip for now (will be resolved via controller in Phase 2)
+			} else {
+				resolved.push(m);
+			}
+		}
+
+		return resolved;
+	}
+
+	/**
+	 * Handle fallback routes (built-in routes like / and /health)
+	 */
+	protected handleFallback(request: FrameworkRequest, path: string): Response {
+		// Built-in routes for framework status
+		if (path === '/') {
+			return FrameworkResponse.json({
+				framework: 'PhoenixJS',
+				version: '0.1.0',
+				message: 'Welcome to PhoenixJS!',
+				status: 'running',
+				routes: Router.count(),
+			});
+		}
+
+		if (path === '/health') {
+			return FrameworkResponse.json({
+				status: 'healthy',
+				timestamp: new Date().toISOString(),
+				uptime: process.uptime(),
+			});
+		}
+
+		// 404 for unmatched routes
+		return FrameworkResponse.notFound(`Route ${path} not found`);
+	}
+
+	/**
+	 * Handle exceptions
+	 */
+	protected handleException(error: unknown): Response {
+		const message = error instanceof Error ? error.message : 'Internal Server Error';
+		const stack = this.app.isDebug() && error instanceof Error ? error.stack : undefined;
+
+		return FrameworkResponse.json(
+			{
+				error: 'Server Error',
+				message,
+				...(stack && { stack }),
+			},
+			500
+		);
+	}
+
+	/**
+	 * Get the application instance
+	 */
+	getApplication(): Application {
+		return this.app;
+	}
+}

package/template/framework/database/DatabaseAdapter.ts

@@ -0,0 +1,18 @@
+export interface DatabaseAdapter {
+	/**
+	 * Connect to the database.
+	 * @param config Optional configuration for the connection
+	 */
+	connect(config?: any): Promise<void>;
+
+	/**
+	 * Disconnect from the database.
+	 */
+	disconnect(): Promise<void>;
+
+	/**
+	 * Execute a query or operation against the database.
+	 * @param query Query string, object, or callback depending on the adapter
+	 */
+	query<T>(query: any): Promise<T>;
+}

package/template/framework/database/PrismaAdapter.ts

@@ -0,0 +1,65 @@
+import { DatabaseAdapter } from './DatabaseAdapter';
+
+export class PrismaAdapter implements DatabaseAdapter {
+	protected client: unknown;
+
+	constructor(client: unknown) {
+		this.client = client;
+	}
+
+	/**
+	 * Connect to the database via Prisma.
+	 */
+	async connect(): Promise<void> {
+		await (this.client as { $connect: () => Promise<void> }).$connect();
+	}
+
+	/**
+	 * Disconnect from the database.
+	 */
+	async disconnect(): Promise<void> {
+		await (this.client as { $disconnect: () => Promise<void> }).$disconnect();
+	}
+
+	/**
+	 * Execute a query using the Prisma client via callback.
+	 * The callback receives the full Prisma client for type-safe queries.
+	 */
+	async query<T>(cb: (db: unknown) => Promise<T>): Promise<T> {
+		return cb(this.client);
+	}
+
+	/**
+	 * Execute operations within a transaction.
+	 * Uses Prisma's interactive transactions for atomicity.
+	 */
+	async transaction<T>(fn: (tx: unknown) => Promise<T>): Promise<T> {
+		const prismaClient = this.client as { $transaction: <R>(fn: (tx: unknown) => Promise<R>) => Promise<R> };
+		return prismaClient.$transaction(fn);
+	}
+
+	/**
+	 * Execute raw SQL query via Prisma's $queryRaw.
+	 * Returns the query results.
+	 */
+	async raw<T>(sql: string, ...params: unknown[]): Promise<T> {
+		const prismaClient = this.client as { $queryRawUnsafe: <R>(sql: string, ...params: unknown[]) => Promise<R> };
+		return prismaClient.$queryRawUnsafe<T>(sql, ...params);
+	}
+
+	/**
+	 * Execute raw SQL statement (INSERT, UPDATE, DELETE) via Prisma's $executeRaw.
+	 * Returns the number of affected rows.
+	 */
+	async execute(sql: string, ...params: unknown[]): Promise<number> {
+		const prismaClient = this.client as { $executeRawUnsafe: (sql: string, ...params: unknown[]) => Promise<number> };
+		return prismaClient.$executeRawUnsafe(sql, ...params);
+	}
+
+	/**
+	 * Get the underlying Prisma client.
+	 */
+	getClient(): unknown {
+		return this.client;
+	}
+}

package/template/framework/database/SqlAdapter.ts

@@ -0,0 +1,117 @@
+import { Database, type SQLQueryBindings } from 'bun:sqlite';
+import { DatabaseAdapter } from './DatabaseAdapter';
+
+export interface SqlAdapterConfig {
+	filename: string;
+	readonly?: boolean;
+	create?: boolean;
+}
+
+export class SqlAdapter implements DatabaseAdapter {
+	protected db: Database | null = null;
+	protected config: SqlAdapterConfig;
+
+	constructor(config: SqlAdapterConfig = { filename: ':memory:' }) {
+		this.config = config;
+	}
+
+	/**
+	 * Connect to the SQLite database.
+	 */
+	async connect(): Promise<void> {
+		this.db = new Database(this.config.filename, {
+			readonly: this.config.readonly ?? false,
+			create: this.config.create ?? true,
+		});
+	}
+
+	/**
+	 * Disconnect from the database.
+	 */
+	async disconnect(): Promise<void> {
+		if (this.db) {
+			this.db.close();
+			this.db = null;
+		}
+	}
+
+	/**
+	 * Execute a query and return results.
+	 * For SELECT queries, returns the result rows.
+	 */
+	async query<T>(sql: string, params?: SQLQueryBindings[]): Promise<T> {
+		this.ensureConnected();
+		const stmt = this.db!.prepare(sql);
+		if (params && params.length > 0) {
+			return stmt.all(...params) as T;
+		}
+		return stmt.all() as T;
+	}
+
+	/**
+	 * Execute a statement (INSERT, UPDATE, DELETE) without returning rows.
+	 * Returns the number of changes made.
+	 */
+	async execute(sql: string, params?: SQLQueryBindings[]): Promise<number> {
+		this.ensureConnected();
+		const stmt = this.db!.prepare(sql);
+		let result;
+		if (params && params.length > 0) {
+			result = stmt.run(...params);
+		} else {
+			result = stmt.run();
+		}
+		return result.changes;
+	}
+
+	/**
+	 * Execute multiple statements in a transaction.
+	 */
+	async transaction<T>(fn: () => Promise<T>): Promise<T> {
+		this.ensureConnected();
+
+		const db = this.db!;
+		db.run('BEGIN TRANSACTION');
+
+		try {
+			const result = await fn();
+			db.run('COMMIT');
+			return result;
+		} catch (error) {
+			db.run('ROLLBACK');
+			throw error;
+		}
+	}
+
+	/**
+	 * Get a single row from a query.
+	 */
+	async get<T>(sql: string, params?: SQLQueryBindings[]): Promise<T | null> {
+		this.ensureConnected();
+		const stmt = this.db!.prepare(sql);
+		if (params && params.length > 0) {
+			return (stmt.get(...params) as T) ?? null;
+		}
+		return (stmt.get() as T) ?? null;
+	}
+
+	/**
+	 * Check if the adapter is connected.
+	 */
+	isConnected(): boolean {
+		return this.db !== null;
+	}
+
+	/**
+	 * Get the underlying Database instance.
+	 */
+	getDatabase(): Database | null {
+		return this.db;
+	}
+
+	private ensureConnected(): void {
+		if (!this.db) {
+			throw new Error('SqlAdapter is not connected. Call connect() first.');
+		}
+	}
+}

package/template/framework/gateway/Gateway.ts

@@ -0,0 +1,109 @@
+/**
+ * PhoenixJS - Gateway
+ * 
+ * Transport-agnostic Gateway interface supporting WebSocket, Socket.IO, and gRPC.
+ */
+
+import type { Application } from '@framework/core/Application';
+import type { ServerWebSocket } from 'bun';
+
+/**
+ * Supported transport types
+ */
+export type GatewayTransport = 'websocket' | 'socketio' | 'grpc';
+
+/**
+ * Gateway interface - base contract for all gateways
+ */
+export interface Gateway {
+	/** Unique gateway name */
+	name: string;
+
+	/** Transport protocol to use */
+	transport: GatewayTransport;
+
+	/** URL path for the gateway (e.g., '/ws', '/chat') */
+	path?: string;
+
+	/** Called when gateway is registered */
+	register(app: Application): void;
+
+	/** Called after all gateways are registered */
+	boot?(app: Application): void;
+}
+
+/**
+ * WebSocket-specific gateway interface
+ */
+export interface WebSocketGatewayInterface extends Gateway {
+	transport: 'websocket';
+
+	/** Called when a connection is opened */
+	onOpen?(ws: ServerWebSocket<WebSocketData>): void | Promise<void>;
+
+	/** Called when a message is received */
+	onMessage?(ws: ServerWebSocket<WebSocketData>, message: string | Buffer): void | Promise<void>;
+
+	/** Called when a connection is closed */
+	onClose?(ws: ServerWebSocket<WebSocketData>, code: number, reason: string): void | Promise<void>;
+
+	/** Called when an error occurs */
+	onError?(ws: ServerWebSocket<WebSocketData>, error: Error): void | Promise<void>;
+
+	/** Called when the socket is ready to receive more data */
+	onDrain?(ws: ServerWebSocket<WebSocketData>): void | Promise<void>;
+}
+
+/**
+ * Contextual data attached to WebSocket connections
+ */
+export interface WebSocketData {
+	/** Gateway handling this connection */
+	gateway: string;
+
+	/** Connection ID */
+	connectionId: string;
+
+	/** Connection timestamp */
+	connectedAt: number;
+
+	/** Custom user data */
+	[key: string]: unknown;
+}
+
+/**
+ * Gateway configuration options
+ */
+export interface GatewayOptions {
+	/** Path prefix for the gateway */
+	path?: string;
+
+	/** Idle timeout in seconds (default: 120) */
+	idleTimeout?: number;
+
+	/** Max message payload size in bytes (default: 1MB) */
+	maxPayloadLength?: number;
+
+	/** Enable per-message-deflate compression */
+	perMessageDeflate?: boolean;
+}
+
+/**
+ * Transport adapter interface for pluggable transports
+ */
+export interface TransportAdapter {
+	/** Adapter name */
+	name: string;
+
+	/** Transport type this adapter handles */
+	transport: GatewayTransport;
+
+	/** Start the transport adapter */
+	start(gateways: Gateway[]): void;
+
+	/** Stop the transport adapter */
+	stop(): void;
+
+	/** Check if adapter is running */
+	isRunning(): boolean;
+}