create-phoenixjs 0.1.0

package/template/framework/validation/Validator.ts

@@ -0,0 +1,482 @@
+/**
+ * PhoenixJS - Base Validator
+ * 
+ * Abstract base class for all validators.
+ * Provides a rule-based validation engine.
+ */
+
+/**
+ * Validation result returned by validate()
+ */
+export interface ValidationResult {
+	/** Whether all validations passed */
+	passes: boolean;
+	/** Whether any validation failed */
+	fails: boolean;
+	/** Validation errors keyed by field name */
+	errors: Record<string, string[]>;
+	/** Validated data (only if passes) */
+	validated: Record<string, unknown>;
+}
+
+/**
+ * Validation rules format
+ * Key is the field name, value is an array of rule strings
+ * 
+ * Example:
+ * {
+ *   name: ['required', 'string', 'min:2', 'max:100'],
+ *   email: ['required', 'email'],
+ *   age: ['number', 'min:0', 'max:150'],
+ *   role: ['required', 'in:admin,user,guest']
+ * }
+ */
+export type ValidationRules = Record<string, string[]>;
+
+/**
+ * Custom validation messages
+ */
+export type ValidationMessages = Record<string, string>;
+
+/**
+ * Rule handler function type
+ */
+type RuleHandler = (
+	field: string,
+	value: unknown,
+	param: string | undefined,
+	data: Record<string, unknown>
+) => string | null;
+
+/**
+ * Base Validator class
+ * 
+ * All application validators should extend this class.
+ * Provides a generic rule-based validation engine.
+ */
+export abstract class Validator {
+	/**
+	 * Define validation rules for fields
+	 * Override this in subclasses
+	 */
+	abstract rules(): ValidationRules;
+
+	/**
+	 * Custom error messages (optional override)
+	 */
+	messages(): ValidationMessages {
+		return {};
+	}
+
+	/**
+	 * Custom attribute names (optional override)
+	 */
+	attributes(): Record<string, string> {
+		return {};
+	}
+
+	/**
+	 * Validate the given data against the rules
+	 */
+	validate(data: Record<string, unknown>): ValidationResult {
+		const rules = this.rules();
+		const customMessages = this.messages();
+		const customAttributes = this.attributes();
+		const errors: Record<string, string[]> = {};
+		const validated: Record<string, unknown> = {};
+
+		for (const [field, fieldRules] of Object.entries(rules)) {
+			const value = this.getNestedValue(data, field);
+			const fieldErrors: string[] = [];
+			const displayName = customAttributes[field] || this.humanize(field);
+
+			for (const rule of fieldRules) {
+				const [ruleName, ruleParam] = this.parseRule(rule);
+				const handler = this.getHandler(ruleName);
+
+				if (handler) {
+					const errorMessage = handler(field, value, ruleParam, data);
+					if (errorMessage) {
+						// Check for custom message
+						const customKey = `${field}.${ruleName}`;
+						const message = customMessages[customKey]
+							|| customMessages[ruleName]
+							|| errorMessage.replace(':attribute', displayName);
+						fieldErrors.push(message);
+					}
+				}
+			}
+
+			if (fieldErrors.length > 0) {
+				errors[field] = fieldErrors;
+			} else if (value !== undefined) {
+				validated[field] = value;
+			}
+		}
+
+		const passes = Object.keys(errors).length === 0;
+
+		return {
+			passes,
+			fails: !passes,
+			errors,
+			validated: passes ? validated : {},
+		};
+	}
+
+	/**
+	 * Parse a rule string into name and parameter
+	 */
+	private parseRule(rule: string): [string, string | undefined] {
+		const colonIndex = rule.indexOf(':');
+		if (colonIndex === -1) {
+			return [rule, undefined];
+		}
+		return [rule.substring(0, colonIndex), rule.substring(colonIndex + 1)];
+	}
+
+	/**
+	 * Get nested value from object using dot notation
+	 */
+	private getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+		const keys = path.split('.');
+		let current: unknown = obj;
+
+		for (const key of keys) {
+			if (current === null || current === undefined || typeof current !== 'object') {
+				return undefined;
+			}
+			current = (current as Record<string, unknown>)[key];
+		}
+
+		return current;
+	}
+
+	/**
+	 * Convert field name to human-readable format
+	 */
+	private humanize(field: string): string {
+		return field
+			.replace(/([A-Z])/g, ' $1')
+			.replace(/[_-]/g, ' ')
+			.toLowerCase()
+			.trim()
+			.replace(/^\w/, (c) => c.toUpperCase());
+	}
+
+	/**
+	 * Get the handler for a rule
+	 */
+	private getHandler(ruleName: string): RuleHandler | null {
+		const handlers: Record<string, RuleHandler> = {
+			required: this.validateRequired.bind(this),
+			string: this.validateString.bind(this),
+			number: this.validateNumber.bind(this),
+			boolean: this.validateBoolean.bind(this),
+			array: this.validateArray.bind(this),
+			object: this.validateObject.bind(this),
+			email: this.validateEmail.bind(this),
+			url: this.validateUrl.bind(this),
+			min: this.validateMin.bind(this),
+			max: this.validateMax.bind(this),
+			between: this.validateBetween.bind(this),
+			in: this.validateIn.bind(this),
+			notIn: this.validateNotIn.bind(this),
+			regex: this.validateRegex.bind(this),
+			alpha: this.validateAlpha.bind(this),
+			alphaNum: this.validateAlphaNum.bind(this),
+			alphaDash: this.validateAlphaDash.bind(this),
+			numeric: this.validateNumeric.bind(this),
+			integer: this.validateInteger.bind(this),
+			date: this.validateDate.bind(this),
+			uuid: this.validateUuid.bind(this),
+			confirmed: this.validateConfirmed.bind(this),
+			same: this.validateSame.bind(this),
+			different: this.validateDifferent.bind(this),
+			nullable: this.validateNullable.bind(this),
+		};
+
+		return handlers[ruleName] || null;
+	}
+
+	// ==========================================
+	// Rule Validators
+	// ==========================================
+
+	private validateRequired(field: string, value: unknown): string | null {
+		if (value === undefined || value === null || value === '') {
+			return 'The :attribute field is required.';
+		}
+		if (Array.isArray(value) && value.length === 0) {
+			return 'The :attribute field is required.';
+		}
+		return null;
+	}
+
+	private validateString(field: string, value: unknown): string | null {
+		if (value === undefined || value === null) return null;
+		if (typeof value !== 'string') {
+			return 'The :attribute must be a string.';
+		}
+		return null;
+	}
+
+	private validateNumber(field: string, value: unknown): string | null {
+		if (value === undefined || value === null) return null;
+		if (typeof value !== 'number' || isNaN(value)) {
+			return 'The :attribute must be a number.';
+		}
+		return null;
+	}
+
+	private validateBoolean(field: string, value: unknown): string | null {
+		if (value === undefined || value === null) return null;
+		if (typeof value !== 'boolean' && value !== 0 && value !== 1 && value !== '0' && value !== '1') {
+			return 'The :attribute must be true or false.';
+		}
+		return null;
+	}
+
+	private validateArray(field: string, value: unknown): string | null {
+		if (value === undefined || value === null) return null;
+		if (!Array.isArray(value)) {
+			return 'The :attribute must be an array.';
+		}
+		return null;
+	}
+
+	private validateObject(field: string, value: unknown): string | null {
+		if (value === undefined || value === null) return null;
+		if (typeof value !== 'object' || Array.isArray(value)) {
+			return 'The :attribute must be an object.';
+		}
+		return null;
+	}
+
+	private validateEmail(field: string, value: unknown): string | null {
+		if (value === undefined || value === null || value === '') return null;
+		if (typeof value !== 'string') {
+			return 'The :attribute must be a valid email address.';
+		}
+		// RFC 5322 compliant email regex (simplified)
+		const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+		if (!emailRegex.test(value)) {
+			return 'The :attribute must be a valid email address.';
+		}
+		return null;
+	}
+
+	private validateUrl(field: string, value: unknown): string | null {
+		if (value === undefined || value === null || value === '') return null;
+		if (typeof value !== 'string') {
+			return 'The :attribute must be a valid URL.';
+		}
+		try {
+			new URL(value);
+			return null;
+		} catch {
+			return 'The :attribute must be a valid URL.';
+		}
+	}
+
+	private validateMin(field: string, value: unknown, param: string | undefined): string | null {
+		if (value === undefined || value === null) return null;
+		const min = Number(param);
+		if (isNaN(min)) return null;
+
+		if (typeof value === 'string') {
+			if (value.length < min) {
+				return `The :attribute must be at least ${min} characters.`;
+			}
+		} else if (typeof value === 'number') {
+			if (value < min) {
+				return `The :attribute must be at least ${min}.`;
+			}
+		} else if (Array.isArray(value)) {
+			if (value.length < min) {
+				return `The :attribute must have at least ${min} items.`;
+			}
+		}
+		return null;
+	}
+
+	private validateMax(field: string, value: unknown, param: string | undefined): string | null {
+		if (value === undefined || value === null) return null;
+		const max = Number(param);
+		if (isNaN(max)) return null;
+
+		if (typeof value === 'string') {
+			if (value.length > max) {
+				return `The :attribute must not be greater than ${max} characters.`;
+			}
+		} else if (typeof value === 'number') {
+			if (value > max) {
+				return `The :attribute must not be greater than ${max}.`;
+			}
+		} else if (Array.isArray(value)) {
+			if (value.length > max) {
+				return `The :attribute must not have more than ${max} items.`;
+			}
+		}
+		return null;
+	}
+
+	private validateBetween(field: string, value: unknown, param: string | undefined): string | null {
+		if (value === undefined || value === null) return null;
+		if (!param) return null;
+		const [minStr, maxStr] = param.split(',');
+		const min = Number(minStr);
+		const max = Number(maxStr);
+		if (isNaN(min) || isNaN(max)) return null;
+
+		if (typeof value === 'string') {
+			if (value.length < min || value.length > max) {
+				return `The :attribute must be between ${min} and ${max} characters.`;
+			}
+		} else if (typeof value === 'number') {
+			if (value < min || value > max) {
+				return `The :attribute must be between ${min} and ${max}.`;
+			}
+		} else if (Array.isArray(value)) {
+			if (value.length < min || value.length > max) {
+				return `The :attribute must have between ${min} and ${max} items.`;
+			}
+		}
+		return null;
+	}
+
+	private validateIn(field: string, value: unknown, param: string | undefined): string | null {
+		if (value === undefined || value === null) return null;
+		if (!param) return null;
+		const allowed = param.split(',');
+		if (!allowed.includes(String(value))) {
+			return `The selected :attribute is invalid.`;
+		}
+		return null;
+	}
+
+	private validateNotIn(field: string, value: unknown, param: string | undefined): string | null {
+		if (value === undefined || value === null) return null;
+		if (!param) return null;
+		const disallowed = param.split(',');
+		if (disallowed.includes(String(value))) {
+			return `The selected :attribute is invalid.`;
+		}
+		return null;
+	}
+
+	private validateRegex(field: string, value: unknown, param: string | undefined): string | null {
+		if (value === undefined || value === null || value === '') return null;
+		if (!param) return null;
+		if (typeof value !== 'string') {
+			return 'The :attribute format is invalid.';
+		}
+		try {
+			const regex = new RegExp(param);
+			if (!regex.test(value)) {
+				return 'The :attribute format is invalid.';
+			}
+		} catch {
+			return 'The :attribute format is invalid.';
+		}
+		return null;
+	}
+
+	private validateAlpha(field: string, value: unknown): string | null {
+		if (value === undefined || value === null || value === '') return null;
+		if (typeof value !== 'string' || !/^[a-zA-Z]+$/.test(value)) {
+			return 'The :attribute must only contain letters.';
+		}
+		return null;
+	}
+
+	private validateAlphaNum(field: string, value: unknown): string | null {
+		if (value === undefined || value === null || value === '') return null;
+		if (typeof value !== 'string' || !/^[a-zA-Z0-9]+$/.test(value)) {
+			return 'The :attribute must only contain letters and numbers.';
+		}
+		return null;
+	}
+
+	private validateAlphaDash(field: string, value: unknown): string | null {
+		if (value === undefined || value === null || value === '') return null;
+		if (typeof value !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(value)) {
+			return 'The :attribute must only contain letters, numbers, dashes and underscores.';
+		}
+		return null;
+	}
+
+	private validateNumeric(field: string, value: unknown): string | null {
+		if (value === undefined || value === null || value === '') return null;
+		if (isNaN(Number(value))) {
+			return 'The :attribute must be a number.';
+		}
+		return null;
+	}
+
+	private validateInteger(field: string, value: unknown): string | null {
+		if (value === undefined || value === null) return null;
+		const num = Number(value);
+		if (isNaN(num) || !Number.isInteger(num)) {
+			return 'The :attribute must be an integer.';
+		}
+		return null;
+	}
+
+	private validateDate(field: string, value: unknown): string | null {
+		if (value === undefined || value === null || value === '') return null;
+		const date = new Date(value as string | number);
+		if (isNaN(date.getTime())) {
+			return 'The :attribute must be a valid date.';
+		}
+		return null;
+	}
+
+	private validateUuid(field: string, value: unknown): string | null {
+		if (value === undefined || value === null || value === '') return null;
+		if (typeof value !== 'string') {
+			return 'The :attribute must be a valid UUID.';
+		}
+		const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+		if (!uuidRegex.test(value)) {
+			return 'The :attribute must be a valid UUID.';
+		}
+		return null;
+	}
+
+	private validateConfirmed(field: string, value: unknown, param: string | undefined, data: Record<string, unknown>): string | null {
+		if (value === undefined || value === null) return null;
+		const confirmationField = `${field}_confirmation`;
+		const confirmationValue = this.getNestedValue(data, confirmationField);
+		if (value !== confirmationValue) {
+			return 'The :attribute confirmation does not match.';
+		}
+		return null;
+	}
+
+	private validateSame(field: string, value: unknown, param: string | undefined, data: Record<string, unknown>): string | null {
+		if (value === undefined || value === null) return null;
+		if (!param) return null;
+		const otherValue = this.getNestedValue(data, param);
+		if (value !== otherValue) {
+			return `The :attribute and ${param} must match.`;
+		}
+		return null;
+	}
+
+	private validateDifferent(field: string, value: unknown, param: string | undefined, data: Record<string, unknown>): string | null {
+		if (value === undefined || value === null) return null;
+		if (!param) return null;
+		const otherValue = this.getNestedValue(data, param);
+		if (value === otherValue) {
+			return `The :attribute and ${param} must be different.`;
+		}
+		return null;
+	}
+
+	private validateNullable(): string | null {
+		// Nullable is a special rule that allows null/undefined values
+		// It doesn't produce errors, it just signals that null is allowed
+		return null;
+	}
+}

package/template/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "my-phoenixjs-app",
+  "version": "0.1.0",
+  "description": "A PhoenixJS API project",
+  "type": "module",
+  "main": "server.ts",
+  "scripts": {
+    "dev": "bun run --watch server.ts",
+    "start": "bun run server.ts",
+    "test": "bun test"
+  },
+  "keywords": [
+    "api",
+    "typescript",
+    "bun",
+    "phoenixjs"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.0.0"
+  }
+}

package/template/routes/api.ts

@@ -0,0 +1,56 @@
+import { Router } from '@framework/routing/Router';
+import { FrameworkResponse as Response } from '@framework/http/Response';
+
+/**
+ * API Routes
+ * 
+ * Define your API routes here. These routes are loaded by the kernel
+ * and all routes here will have the /api prefix.
+ */
+export function registerRoutes() {
+	// Health check endpoint
+	Router.get('/health', () => {
+		return Response.json({
+			status: 'ok',
+			timestamp: new Date().toISOString(),
+		});
+	});
+
+	// Welcome endpoint
+	Router.get('/hello', () => {
+		return Response.json({
+			message: 'Welcome to PhoenixJS! 🚀',
+		});
+	});
+
+	// Example API group with routes
+	Router.group({ prefix: '/api' }, () => {
+		// Ping endpoint
+		Router.get('/ping', () => Response.json({ message: 'pong' }));
+
+		// Example with route parameter
+		Router.get('/users/:id', () => {
+			return Response.json({
+				user: { id: '1', name: 'John Doe' },
+			});
+		});
+
+		// Example POST route (use Controller for real implementations)
+		Router.post('/users', () => {
+			return Response.json({
+				message: 'User created',
+			}, 201);
+		});
+	});
+
+	/**
+	 * Route Groups Example
+	 * 
+	 * You can use Controllers with the 'ControllerName@method' syntax:
+	 * 
+	 * Router.group({ prefix: '/v1', middleware: [] }, () => {
+	 *     Router.get('/products', 'ProductController@index');
+	 *     Router.post('/products', 'ProductController@store');
+	 * });
+	 */
+}

package/template/server.ts

@@ -0,0 +1,29 @@
+/**
+ * PhoenixJS - Server Entry Point
+ * 
+ * This is the main entry point for the application.
+ * Run with: bun run server.ts
+ */
+
+import { app, kernel } from '@/bootstrap/app';
+import { Server } from '@framework/http/Server';
+
+// Boot the application
+app.boot();
+
+// Create and start the server
+const server = new Server(kernel);
+server.start();
+
+// Handle graceful shutdown
+process.on('SIGINT', () => {
+	console.log('\nShutting down...');
+	server.stop();
+	process.exit(0);
+});
+
+process.on('SIGTERM', () => {
+	console.log('\nShutting down...');
+	server.stop();
+	process.exit(0);
+});

package/template/tsconfig.json

@@ -0,0 +1,49 @@
+{
+	"compilerOptions": {
+		"target": "ESNext",
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"strict": true,
+		"skipLibCheck": true,
+		"esModuleInterop": true,
+		"allowSyntheticDefaultImports": true,
+		"forceConsistentCasingInFileNames": true,
+		"noEmit": true,
+		"declaration": false,
+		"resolveJsonModule": true,
+		"isolatedModules": true,
+		"lib": [
+			"ESNext"
+		],
+		"types": [
+			"bun-types"
+		],
+		"baseUrl": ".",
+		"paths": {
+			"@/*": [
+				"./*"
+			],
+			"@framework/*": [
+				"framework/*"
+			],
+			"@app/*": [
+				"app/*"
+			],
+			"@config/*": [
+				"config/*"
+			],
+			"@routes/*": [
+				"routes/*"
+			],
+			"@database/*": [
+				"database/*"
+			]
+		}
+	},
+	"include": [
+		"**/*.ts"
+	],
+	"exclude": [
+		"node_modules"
+	]
+}