create-phoenixjs 0.1.0

package/template/framework/http/UploadedFile.ts

@@ -0,0 +1,145 @@
+/**
+ * PhoenixJS - Uploaded File Handler
+ * 
+ * Represents a file uploaded via HTTP request.
+ */
+
+import { join } from 'path';
+import { writeFile, mkdir } from 'fs/promises';
+
+export interface UploadedFileOptions {
+	name: string;
+	originalName: string;
+	mimeType: string;
+	size: number;
+	content: ArrayBuffer;
+}
+
+export class UploadedFile {
+	readonly name: string;
+	readonly originalName: string;
+	readonly mimeType: string;
+	readonly size: number;
+	private content: ArrayBuffer;
+
+	constructor(options: UploadedFileOptions) {
+		this.name = options.name;
+		this.originalName = options.originalName;
+		this.mimeType = options.mimeType;
+		this.size = options.size;
+		this.content = options.content;
+	}
+
+	/**
+	 * Get the file extension
+	 */
+	extension(): string {
+		const parts = this.originalName.split('.');
+		return parts.length > 1 ? parts[parts.length - 1] : '';
+	}
+
+	/**
+	 * Check if the file is valid (has content)
+	 */
+	isValid(): boolean {
+		return this.size > 0 && this.content.byteLength > 0;
+	}
+
+	/**
+	 * Get the file content as ArrayBuffer
+	 */
+	getContent(): ArrayBuffer {
+		return this.content;
+	}
+
+	/**
+	 * Get the file content as Buffer
+	 */
+	getBuffer(): Buffer {
+		return Buffer.from(this.content);
+	}
+
+	/**
+	 * Get the file content as text
+	 */
+	async text(): Promise<string> {
+		const decoder = new TextDecoder();
+		return decoder.decode(this.content);
+	}
+
+	/**
+	 * Get the file content as base64
+	 */
+	toBase64(): string {
+		return Buffer.from(this.content).toString('base64');
+	}
+
+	/**
+	 * Store the file to a given path
+	 * Returns the full path where the file was stored
+	 */
+	async store(directory: string, filename?: string): Promise<string> {
+		const finalFilename = filename ?? this.generateFilename();
+		const fullPath = join(directory, finalFilename);
+
+		// Ensure directory exists
+		await mkdir(directory, { recursive: true });
+
+		// Write file
+		await writeFile(fullPath, this.getBuffer());
+
+		return fullPath;
+	}
+
+	/**
+	 * Store the file with its original name
+	 */
+	async storeAs(directory: string, filename: string): Promise<string> {
+		return this.store(directory, filename);
+	}
+
+	/**
+	 * Generate a unique filename
+	 */
+	private generateFilename(): string {
+		const timestamp = Date.now();
+		const random = Math.random().toString(36).substring(2, 10);
+		const ext = this.extension();
+		return ext ? `${timestamp}_${random}.${ext}` : `${timestamp}_${random}`;
+	}
+
+	/**
+	 * Check if the file has a specific MIME type
+	 */
+	hasMimeType(type: string): boolean {
+		return this.mimeType === type;
+	}
+
+	/**
+	 * Check if the file is an image
+	 */
+	isImage(): boolean {
+		return this.mimeType.startsWith('image/');
+	}
+
+	/**
+	 * Check if the file is a video
+	 */
+	isVideo(): boolean {
+		return this.mimeType.startsWith('video/');
+	}
+
+	/**
+	 * Check if the file is an audio file
+	 */
+	isAudio(): boolean {
+		return this.mimeType.startsWith('audio/');
+	}
+
+	/**
+	 * Check if the file is a PDF
+	 */
+	isPdf(): boolean {
+		return this.mimeType === 'application/pdf';
+	}
+}

package/template/framework/middleware/Middleware.ts

@@ -0,0 +1,50 @@
+/**
+ * PhoenixJS - Middleware
+ * 
+ * Middleware interface and types for the middleware pipeline.
+ * Inspired by Laravel's middleware system.
+ */
+
+import { FrameworkRequest } from '@framework/http/Request';
+
+/**
+ * The function signature for the next middleware in the chain
+ */
+export type NextFunction = (request: FrameworkRequest) => Promise<Response>;
+
+/**
+ * Middleware interface
+ * 
+ * All middleware must implement this interface. The handle method receives
+ * the request and a next function to call the next middleware in the chain.
+ */
+export interface Middleware {
+	/**
+	 * Handle the incoming request
+	 * 
+	 * @param request - The incoming request
+	 * @param next - The next middleware in the chain
+	 * @returns The response from the middleware chain
+	 */
+	handle(request: FrameworkRequest, next: NextFunction): Promise<Response>;
+}
+
+/**
+ * Middleware class (alternative to interface for those who prefer classes)
+ */
+export abstract class MiddlewareBase implements Middleware {
+	abstract handle(request: FrameworkRequest, next: NextFunction): Promise<Response>;
+}
+
+/**
+ * Type for middleware that can be registered
+ * Supports class instances, constructor functions, and callback functions
+ */
+export type MiddlewareHandler =
+	| Middleware
+	| ((request: FrameworkRequest, next: NextFunction) => Promise<Response>);
+
+/**
+ * Type for middleware that can be resolved from string name
+ */
+export type MiddlewareResolvable = string | MiddlewareHandler;

package/template/framework/middleware/Pipeline.ts

@@ -0,0 +1,89 @@
+/**
+ * PhoenixJS - Middleware Pipeline
+ * 
+ * A pipeline for executing middleware in sequence.
+ * Inspired by Laravel's Pipeline class.
+ */
+
+import { FrameworkRequest } from '@framework/http/Request';
+import type { MiddlewareHandler, NextFunction } from '@framework/middleware/Middleware';
+
+/**
+ * Pipeline class for chaining middleware
+ * 
+ * Usage:
+ * const response = await new Pipeline()
+ *   .send(request)
+ *   .through([middleware1, middleware2])
+ *   .then(finalHandler);
+ */
+export class Pipeline {
+	private passable: FrameworkRequest | null = null;
+	private pipes: MiddlewareHandler[] = [];
+
+	/**
+	 * Set the object being sent through the pipeline
+	 */
+	send(passable: FrameworkRequest): this {
+		this.passable = passable;
+		return this;
+	}
+
+	/**
+	 * Set the array of pipes (middleware)
+	 */
+	through(pipes: MiddlewareHandler[]): this {
+		this.pipes = pipes;
+		return this;
+	}
+
+	/**
+	 * Add a single pipe to the pipeline
+	 */
+	pipe(pipe: MiddlewareHandler): this {
+		this.pipes.push(pipe);
+		return this;
+	}
+
+	/**
+	 * Run the pipeline with a final destination callback
+	 */
+	async then(destination: (request: FrameworkRequest) => Promise<Response>): Promise<Response> {
+		if (!this.passable) {
+			throw new Error('Pipeline: No passable set. Call send() first.');
+		}
+
+		// Build the middleware chain from the end backwards
+		const pipeline = this.pipes.reduceRight<NextFunction>(
+			(next, pipe) => {
+				return async (request: FrameworkRequest): Promise<Response> => {
+					return this.executePipe(pipe, request, next);
+				};
+			},
+			destination
+		);
+
+		return pipeline(this.passable);
+	}
+
+	/**
+	 * Execute a single pipe (middleware)
+	 */
+	private async executePipe(
+		pipe: MiddlewareHandler,
+		request: FrameworkRequest,
+		next: NextFunction
+	): Promise<Response> {
+		// If it's an object with handle method (Middleware interface)
+		if (typeof pipe === 'object' && 'handle' in pipe) {
+			return pipe.handle(request, next);
+		}
+
+		// If it's a function (callback middleware)
+		if (typeof pipe === 'function') {
+			return pipe(request, next);
+		}
+
+		throw new Error(`Pipeline: Invalid middleware type: ${typeof pipe}`);
+	}
+}

package/template/framework/plugin/Plugin.ts

@@ -0,0 +1,26 @@
+import { Application } from '@framework/core/Application';
+
+/**
+ * Plugin Interface
+ * 
+ * Plugins allow extending the framework with external functionality.
+ * They can register services, add middleware, register routes, etc.
+ */
+export interface Plugin {
+	/**
+	 * The unique name of the plugin
+	 */
+	name: string;
+
+	/**
+	 * Register services on the application
+	 * This is called when the plugin is registered
+	 */
+	register(app: Application): void;
+
+	/**
+	 * Boot the plugin
+	 * This is called after all services are registered
+	 */
+	boot?(app: Application): void;
+}

package/template/framework/plugin/PluginManager.ts

@@ -0,0 +1,61 @@
+import { Application } from '@framework/core/Application';
+import { Plugin } from '@framework/plugin/Plugin';
+
+export class PluginManager {
+	protected app: Application;
+	protected plugins: Map<string, Plugin> = new Map();
+	protected booted = false;
+
+	constructor(app: Application) {
+		this.app = app;
+	}
+
+	/**
+	 * Register a plugin with the application
+	 */
+	register(plugin: Plugin): void {
+		if (this.plugins.has(plugin.name)) {
+			console.warn(`Plugin ${plugin.name} is already registered.`);
+			return;
+		}
+
+		this.plugins.set(plugin.name, plugin);
+		plugin.register(this.app);
+
+		// If app is already booted and plugin has boot method, boot it immediately
+		if (this.booted && plugin.boot) {
+			plugin.boot(this.app);
+		}
+	}
+
+	/**
+	 * Boot all registered plugins
+	 */
+	boot(): void {
+		if (this.booted) {
+			return;
+		}
+
+		for (const plugin of this.plugins.values()) {
+			if (plugin.boot) {
+				plugin.boot(this.app);
+			}
+		}
+
+		this.booted = true;
+	}
+
+	/**
+	 * Get a registered plugin by name
+	 */
+	get(name: string): Plugin | undefined {
+		return this.plugins.get(name);
+	}
+
+	/**
+	 * Get all registered plugins
+	 */
+	getAll(): Plugin[] {
+		return Array.from(this.plugins.values());
+	}
+}

package/template/framework/routing/RouteRegistry.ts

@@ -0,0 +1,185 @@
+/**
+ * PhoenixJS - Route Registry
+ * 
+ * Internal storage for route definitions with pattern compilation.
+ */
+
+import type { MiddlewareResolvable } from '@framework/middleware/Middleware';
+
+/**
+ * HTTP methods supported by the router
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD';
+
+/**
+ * Route handler types
+ * - String: 'Controller@method' format
+ * - Function: Direct handler function
+ */
+export type RouteHandler =
+	| string
+	| ((params: Record<string, string>) => Promise<Response> | Response);
+
+/**
+ * Route definition
+ */
+export interface Route {
+	/** HTTP method */
+	method: HttpMethod;
+	/** Original path pattern (e.g., '/users/:id') */
+	path: string;
+	/** Compiled regex pattern */
+	pattern: RegExp;
+	/** Parameter names extracted from path */
+	paramNames: string[];
+	/** Route handler (controller@method or function) */
+	handler: RouteHandler;
+	/** Middleware stack for this route */
+	middleware: MiddlewareResolvable[];
+	/** Route name for URL generation */
+	name?: string;
+}
+
+/**
+ * Match result from route resolution
+ */
+export interface RouteMatch {
+	route: Route;
+	params: Record<string, string>;
+}
+
+/**
+ * RouteRegistry - Internal storage and matching
+ */
+export class RouteRegistry {
+	private routes: Route[] = [];
+
+	/**
+	 * Add a route to the registry
+	 */
+	add(
+		method: HttpMethod,
+		path: string,
+		handler: RouteHandler,
+		middleware: MiddlewareResolvable[] = [],
+		name?: string
+	): Route {
+		const { pattern, paramNames } = this.compilePath(path);
+
+		const route: Route = {
+			method,
+			path,
+			pattern,
+			paramNames,
+			handler,
+			middleware,
+			name,
+		};
+
+		this.routes.push(route);
+		return route;
+	}
+
+	/**
+	 * Find a matching route for method and path
+	 */
+	match(method: string, path: string): RouteMatch | null {
+		const normalizedMethod = method.toUpperCase() as HttpMethod;
+
+		for (const route of this.routes) {
+			// Check method match (HEAD can match GET routes)
+			if (route.method !== normalizedMethod) {
+				if (!(normalizedMethod === 'HEAD' && route.method === 'GET')) {
+					continue;
+				}
+			}
+
+			// Check path match
+			const match = route.pattern.exec(path);
+			if (match) {
+				// Extract params from match groups
+				const params: Record<string, string> = {};
+				route.paramNames.forEach((name, index) => {
+					params[name] = match[index + 1] || '';
+				});
+
+				return { route, params };
+			}
+		}
+
+		return null;
+	}
+
+	/**
+	 * Get all registered routes
+	 */
+	all(): Route[] {
+		return [...this.routes];
+	}
+
+	/**
+	 * Find a route by name
+	 */
+	findByName(name: string): Route | undefined {
+		return this.routes.find(r => r.name === name);
+	}
+
+	/**
+	 * Clear all routes (useful for testing)
+	 */
+	clear(): void {
+		this.routes = [];
+	}
+
+	/**
+	 * Get count of registered routes
+	 */
+	count(): number {
+		return this.routes.length;
+	}
+
+	/**
+	 * Compile a path pattern into a regex
+	 * 
+	 * Supports:
+	 * - Static paths: /users
+	 * - Named params: /users/:id
+	 * - Optional params: /users/:id?
+	 * - Wildcards: /files/*
+	 */
+	private compilePath(path: string): { pattern: RegExp; paramNames: string[] } {
+		const paramNames: string[] = [];
+
+		// Normalize path
+		let normalizedPath = path.startsWith('/') ? path : `/${path}`;
+
+		// Handle wildcards (*) first - replace with placeholder
+		const WILDCARD_PLACEHOLDER = '__WILDCARD__';
+		normalizedPath = normalizedPath.replace(/\*$/g, WILDCARD_PLACEHOLDER);
+		normalizedPath = normalizedPath.replace(/\*\//g, `${WILDCARD_PLACEHOLDER}/`);
+
+		// Escape special regex characters except for our patterns
+		let regexString = normalizedPath
+			.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+
+		// Convert wildcard placeholders back to regex
+		regexString = regexString.replace(/__WILDCARD__/g, '.*');
+
+		// Handle optional params (:param?)
+		regexString = regexString.replace(/:(\w+)\?/g, (_, name) => {
+			paramNames.push(name);
+			return '([^/]*)';
+		});
+
+		// Handle required params (:param)
+		regexString = regexString.replace(/:(\w+)/g, (_, name) => {
+			paramNames.push(name);
+			return '([^/]+)';
+		});
+
+		// Create the final regex
+		const pattern = new RegExp(`^${regexString}$`);
+
+		return { pattern, paramNames };
+	}
+}