@nitronjs/framework 0.1.0

package/lib/Database/Connection.js

@@ -0,0 +1,61 @@
+class Connection {
+    #driver = null;
+    #name = null;
+    
+    constructor(name, driver) {
+        this.#name = name;
+        this.#driver = driver;
+    }
+
+    async query(sql, bindings = []) {
+        return await this.#driver.query(sql, bindings);
+    }
+
+    async raw(sql) {
+        return await this.#driver.raw(sql);
+    }
+
+    async withTransaction(callback, options = {}) {
+        const timeout = options.timeout || 30000; // 30 seconds default
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => {
+            controller.abort();
+        }, timeout);
+
+        try {
+            const result = await this.#driver.withTransaction(callback, {
+                signal: controller.signal
+            });
+
+            clearTimeout(timeoutId);
+            return result;
+        } catch (err) {
+            clearTimeout(timeoutId);
+            if (controller.signal.aborted) {
+                throw new Error(
+                    `Transaction timeout after ${timeout}ms. ` +
+                    'This may indicate a forgotten await in the callback or a slow query. ' +
+                    'Consider: 1) Adding await to all async operations, 2) Increasing timeout, 3) Optimizing queries.'
+                );
+            }
+
+            throw err;
+        }
+    }
+
+    async healthCheck() {
+        return await this.#driver.healthCheck();
+    }
+
+    getName() {
+        return this.#name;
+    }
+
+    async close() {
+        if (this.#driver && typeof this.#driver.close === 'function') {
+            await this.#driver.close();
+        }
+    }
+}
+
+export default Connection;

package/lib/Database/DB.js

@@ -0,0 +1,84 @@
+import DatabaseManager from "./Manager.js";
+import { query as createQueryBuilder, RawExpression } from "./QueryBuilder.js";
+
+class DB {
+    static manager() {
+        return DatabaseManager.getInstance();
+    }
+
+    static connection(name = null) {
+        if (!this.#isEnabled()) return null;
+        return this.manager().connection(name);
+    }
+
+    static async query(sql, bindings = []) {
+        if (!this.#isEnabled()) return null;
+        return await this.manager().query(sql, bindings);
+    }
+
+    static rawExpr(expression) {
+        return new RawExpression(expression);
+    }
+
+    static async rawQuery(sql) {
+        if (!this.#isEnabled()) return null;
+        return await this.connection().raw(sql);
+    }
+
+    static async transaction(callback) {
+        if (!this.#isEnabled()) return null;
+        return await this.connection().withTransaction(callback);
+    }
+
+    /**
+     * Create a query builder for a table.
+     * Uses lazy connection loading - connection is fetched only when query is executed.
+     * @param {string} table - The table name
+     * @param {string|null} connectionName - Optional connection name
+     * @param {Function|null} modelClass - Optional model class for hydration
+     * @returns {QueryBuilder} A query builder instance
+     */
+    static table(table, connectionName = null, modelClass = null) {
+        // Pass connection directly now (synchronous)
+        const connection = this.connection(connectionName);
+        return createQueryBuilder(table, connection, modelClass);
+    }
+
+    static async setup() {
+        if (!this.#isEnabled()) return;
+
+        const manager = this.manager();
+        const defaultConnection = manager.getDefaultConnection();
+
+        try {
+            const connection = manager.connection(defaultConnection);
+            const isHealthy = await connection.healthCheck();
+
+            if (!isHealthy) {
+                throw new Error(`Database connection '${defaultConnection}' health check failed`);
+            }
+        }
+        catch (error) {
+            console.error('[Database] Setup failed:', error.message);
+            console.error('[Database] Check your .env credentials and ensure MySQL is running');
+            throw error;
+        }
+    }
+
+    static async close() {
+        if (!this.#isEnabled()) return;
+
+        try {
+            await this.manager().closeAll();
+        }
+        catch (error) {
+            console.error('[Database] Error during shutdown:', error.message);
+        }
+    }
+
+    static #isEnabled() {
+        return !!DatabaseManager.getInstance().getDefaultConnection();
+    }
+}
+
+export default DB;

package/lib/Database/Drivers/MySQLDriver.js

@@ -0,0 +1,234 @@
+import mysql from 'mysql2/promise';
+
+class MySQLDriver {
+    #pool = null;
+    #config = null;
+    #credentials = null;
+
+    constructor(config, credentials = null) {
+        this.#config = config;
+        this.#credentials = credentials;
+        this.#createPool();
+    }
+
+    #createPool() {
+        const creds = this.#credentials;
+
+        this.#pool = mysql.createPool({
+            host: creds?.host ?? process.env.DATABASE_HOST ?? '127.0.0.1',
+            port: parseInt(creds?.port ?? process.env.DATABASE_PORT ?? '3306'),
+            user: creds?.username ?? process.env.DATABASE_USERNAME ?? 'root',
+            password: creds?.password ?? process.env.DATABASE_PASSWORD ?? '',
+            database: creds?.database ?? process.env.DATABASE_NAME ?? 'test',
+            charset: this.#config.charset || 'utf8mb4',
+
+            waitForConnections: true,
+            connectionLimit: this.#config.pool?.max ?? 10,
+            queueLimit: this.#config.pool?.queueLimit ?? 100,
+            connectTimeout: 10000,
+
+            enableKeepAlive: true,
+            keepAliveInitialDelay: 10000,
+            namedPlaceholders: true,
+            decimalNumbers: true
+        });
+    }
+
+    async query(sql, bindings = []) {
+        const isProduction = process.env.APP_DEV === 'false';
+
+        try {
+            const connection = await this.#pool.getConnection();
+
+            try {
+                await connection.query('SET SESSION MAX_EXECUTION_TIME = 60000');
+                const [rows, fields] = await connection.execute(sql, bindings);
+
+                return [rows, fields];
+            }
+            finally {
+                connection.release();
+            }
+        }
+
+        catch (error) {
+            if (isProduction) {
+                console.error('[MySQLDriver] Query failed', {
+                    code: error.code,
+                    errno: error.errno,
+                    sqlState: error.sqlState
+                });
+
+                const sanitized = new Error('Database query failed');
+                sanitized.code = error.code;
+                sanitized.driver = 'mysql';
+                throw sanitized;
+            }
+
+            error.sql = sql;
+            error.bindings = this.#maskSensitiveData(bindings);
+            error.driver = 'mysql';
+            throw error;
+        }
+    }
+
+    async raw(sql) {
+        const isProduction = process.env.APP_DEV === 'false';
+        
+        try {
+            const [rows, fields] = await this.#pool.query(sql);
+            return [rows, fields];
+        }
+
+        catch (error) {
+            if (isProduction) {
+                console.error('[MySQLDriver] Raw query failed', {
+                    code: error.code,
+                    errno: error.errno,
+                    sqlState: error.sqlState
+                });
+
+                const sanitized = new Error('Database query failed');
+                sanitized.code = error.code;
+                sanitized.driver = 'mysql';
+                throw sanitized;
+            }
+
+            error.sql = sql;
+            error.driver = 'mysql';
+            throw error;
+        }
+    }
+
+    #maskSensitiveData(bindings) {
+        if (process.env.APP_DEV === 'true') {
+            return bindings; // Show all in development
+        }
+
+        return bindings.map((value, index) => {
+            if (typeof value !== 'string') {
+                return value;
+            }
+
+            const sensitivePatterns = /password|token|secret|key|auth|bearer|jwt|otp|pin|credential/i;
+            const valuePreview = value.substring(0, 30).toLowerCase();
+            const looksLikeBase64 = /^[A-Za-z0-9+/]+=*$/.test(value) && value.length > 16;
+
+            if (sensitivePatterns.test(valuePreview) || value.length > 20 || looksLikeBase64) {
+                return '***MASKED***';
+            }
+
+            return value;
+        });
+    }
+
+    async beginTransaction() {
+        const connection = await this.#pool.getConnection();
+        await connection.query('SET SESSION MAX_EXECUTION_TIME = 60000');
+
+        await connection.beginTransaction();
+
+        return connection;
+    }
+
+    async commit(connection) {
+        try {
+            await connection.commit();
+        }
+
+        finally {
+            connection.release();
+        }
+    }
+
+    async rollback(connection) {
+        try {
+            await connection.rollback();
+        }
+
+        catch (error) {
+        }
+
+        finally {
+            connection.release();
+        }
+    }
+
+    async transactionQuery(connection, sql, bindings = []) {
+        try {
+            const [rows, fields] = await connection.execute(sql, bindings);
+            return [rows, fields];
+        }
+
+        catch (error) {
+            const isProduction = process.env.APP_DEV === 'false';
+
+            if (isProduction) {
+                console.error('[MySQLDriver] Transaction query failed', {
+                    code: error.code,
+                    errno: error.errno,
+                    sqlState: error.sqlState,
+                    inTransaction: true
+                });
+
+                const sanitized = new Error('Database query failed');
+                sanitized.code = error.code;
+                sanitized.driver = 'mysql';
+                sanitized.inTransaction = true;
+                throw sanitized;
+            }
+
+            error.sql = sql;
+            error.bindings = this.#maskSensitiveData(bindings);
+            error.driver = 'mysql';
+            error.inTransaction = true;
+            throw error;
+        }
+    }
+
+    async withTransaction(callback, options = {}) {
+        const signal = options?.signal;
+        const connection = await this.beginTransaction();
+
+        try {
+            if (signal?.aborted) {
+                throw new Error('Transaction aborted');
+            }
+
+            const result = await callback(connection);
+            if (signal?.aborted) {
+                await this.rollback(connection);
+                throw new Error('Transaction aborted');
+            }
+
+            await this.commit(connection);
+
+            return result;
+        }
+
+        catch (error) {
+            await this.rollback(connection);
+            throw error;
+        }
+    }
+
+    async healthCheck() {
+        try {
+            await this.#pool.query('SELECT 1');
+            return true;
+        }
+
+        catch (error) {
+            return false;
+        }
+    }
+
+    async close() {
+        if (this.#pool) {
+            await this.#pool.end();
+            this.#pool = null;
+        }
+    }
+}
+
+export default MySQLDriver;

package/lib/Database/Manager.js

@@ -0,0 +1,162 @@
+import Connection from './Connection.js';
+import MySQLDriver from './Drivers/MySQLDriver.js';
+import Config from '../Core/Config.js';
+
+class DatabaseManager {
+
+    static instance = null;
+    static #isInternal = false;
+
+    #connections = new Map();
+    #defaultConnection = null;
+    #config = null;
+    #credentials = null;
+
+    constructor() {
+        if (!DatabaseManager.#isInternal) {
+            throw new Error('DatabaseManager must be initialized with await DatabaseManager.getInstance()');
+        }
+    }
+
+    static createInstance() {
+        DatabaseManager.#isInternal = true;
+        const instance = new DatabaseManager();
+        DatabaseManager.#isInternal = false;
+        
+        instance.#config = Config.all('database');
+        instance.#initializeDefaultConnection();
+        return instance;
+    }
+
+    #initializeDefaultConnection() {
+        const envDriver = (process.env.DATABASE_DRIVER || 'mysql').toLowerCase();
+        const normalized = envDriver === 'postgresql' ? 'postgres' : envDriver;
+
+        this.#defaultConnection = normalized === 'none' ? null : normalized;
+    }
+
+    static getInstance() {
+        if (!this.instance) {
+            this.instance = DatabaseManager.createInstance();
+        }
+
+        return this.instance;
+    }
+
+    // ========================================
+    // Connection Management
+    // ========================================
+
+    connection(name = null) {
+        const connectionName = name || this.#defaultConnection;
+
+        if (!connectionName) {
+            throw new Error('Database is disabled (DATABASE_DRIVER=none)');
+        }
+
+        if (this.#connections.has(connectionName)) {
+            return this.#connections.get(connectionName);
+        }
+
+        const config = this.#config.connections[connectionName];
+
+        if (!config) {
+            throw new Error(`Database connection '${connectionName}' is not configured`);
+        }
+
+        return this.#addConnection(connectionName, config);
+    }
+
+    #addConnection(name, config) {
+        const driver = this.#createDriver(config);
+        const connection = new Connection(name, driver);
+
+        this.#connections.set(name, connection);
+
+        return connection;
+    }
+
+    #createDriver(config) {
+        switch (config.driver) {
+            case 'mysql':
+                return new MySQLDriver(config, this.#credentials);
+
+            case 'postgres':
+                throw new Error('Postgres driver not yet implemented');
+
+            case 'mongodb':
+                throw new Error('MongoDB driver not yet implemented');
+
+            default:
+                throw new Error(`Unknown database driver: ${config.driver}`);
+        }
+    }
+
+    // ========================================
+    // Reconfiguration (for Installer)
+    // ========================================
+
+    /**
+     * Reconfigure database with new credentials
+     * Closes existing connections and creates new pool with provided credentials
+     */
+    async reconfigure(credentials) {
+        await this.closeAll();
+
+        this.#credentials = {
+            host: credentials.host,
+            port: String(credentials.port),
+            database: credentials.database,
+            username: credentials.username,
+            password: credentials.password || ""
+        };
+
+        this.#defaultConnection = "mysql";
+    }
+
+    // ========================================
+    // Query & Health
+    // ========================================
+
+    async query(sql, bindings = []) {
+        return await this.connection().query(sql, bindings);
+    }
+
+    async healthCheck() {
+        const results = {};
+
+        for (const [name, connection] of this.#connections.entries()) {
+            try {
+                results[name] = await connection.healthCheck();
+            }
+            catch (error) {
+                results[name] = false;
+            }
+        }
+
+        return results;
+    }
+
+    // ========================================
+    // Lifecycle
+    // ========================================
+
+    async closeAll() {
+        for (const [name, connection] of this.#connections.entries()) {
+            try {
+                await connection.close();
+            }
+            catch (error) {
+                // Ignore close errors
+            }
+        }
+
+        this.#connections.clear();
+    }
+
+    getDefaultConnection() {
+        return this.#defaultConnection;
+    }
+}
+
+export default DatabaseManager;

package/lib/Database/Model.js

@@ -0,0 +1,161 @@
+import DB from './DB.js';
+
+class Model {
+    static table = null;
+    static primaryKey = 'id';
+
+    constructor(attrs = {}) {
+        Object.defineProperty(this, '_attributes', { value: {}, writable: true });
+        Object.defineProperty(this, '_original', { value: {}, writable: true });
+        Object.defineProperty(this, '_exists', { value: false, writable: true });
+        
+        Object.assign(this._attributes, attrs);
+        this._original = { ...this._attributes };
+        
+        return new Proxy(this, {
+            get(target, prop) {
+                if (prop.startsWith('_') || typeof target[prop] === 'function' || prop === 'constructor') {
+                    return target[prop];
+                }
+                return target._attributes[prop];
+            },
+            set(target, prop, value) {
+                if (prop.startsWith('_')) {
+                    target[prop] = value;
+                    return true;
+                }
+                if (prop in target) return false;
+
+                target._attributes[prop] = value;
+
+                return true;
+            }
+        });
+    }
+
+    static async get() {
+        if (!this.table) {
+            throw new Error(`Model ${this.name} must define a static 'table' property`);
+        }
+
+        const rows = await DB.table(this.table).get();
+
+        return rows.map(row => {
+            const instance = new this();
+            
+            for (const [key, value] of Object.entries(row)) {
+                if (value instanceof Date) {
+                    instance._attributes[key] = value.toISOString().slice(0, 19).replace('T', ' ');
+                } else {
+                    instance._attributes[key] = value;
+                }
+            }
+            
+            instance._exists = true;
+            instance._original = { ...instance._attributes };
+            
+            return instance;
+        });
+    }
+
+    static async find(id) {
+        if (!this.table) {
+            throw new Error(`Model ${this.name} must define a static 'table' property`);
+        }
+
+        const row = await DB.table(this.table).where(this.primaryKey, id).first();
+
+        if (!row) return null;
+
+        const instance = new this();
+        
+        for (const [key, value] of Object.entries(row)) {
+            if (value instanceof Date) {
+                instance._attributes[key] = value.toISOString().slice(0, 19).replace('T', ' ');
+            } else {
+                instance._attributes[key] = value;
+            }
+        }
+        
+        instance._exists = true;
+        instance._original = { ...instance._attributes };
+        
+        return instance;
+    }
+
+    static where(column, operator, value) {
+        if (!this.table) {
+            throw new Error(`Model ${this.name} must define a static 'table' property`);
+        }
+
+        return DB.table(this.table, null, this).where(column, operator, value);
+    }
+
+    static select(...columns) {
+        if (!this.table) {
+            throw new Error(`Model ${this.name} must define a static 'table' property`);
+        }
+
+        return DB.table(this.table, null, this).select(...columns);
+    }
+
+    static async first() {
+        if (!this.table) {
+            throw new Error(`Model ${this.name} must define a static 'table' property`);
+        }
+
+        return await DB.table(this.table, null, this).limit(1).first();
+    }
+
+    async save() {
+        const constructor = this.constructor;
+        const data = {};
+
+        for (const [key, value] of Object.entries(this._attributes)) {
+            if (value !== undefined && (key !== constructor.primaryKey || !this._exists)) {
+                data[key] = value;
+            }
+        }
+
+        if (this._exists) {
+            const primaryKeyValue = this._attributes[constructor.primaryKey];
+            await DB.table(constructor.table)
+                .where(constructor.primaryKey, primaryKeyValue)
+                .update(data);
+            
+            Object.assign(this._attributes, data);
+            this._original = { ...this._attributes };
+        }
+        else {
+            const id = await DB.table(constructor.table).insert(data);
+            this._attributes[constructor.primaryKey] = id;
+            
+            this._original = { ...this._attributes };
+            this._exists = true;
+        }
+
+        return this;
+    }
+
+    async delete() {
+        const constructor = this.constructor;
+        const primaryKeyValue = this._attributes[constructor.primaryKey];
+        
+        if (!this._exists) {
+            throw new Error('Cannot delete a model that does not exist');
+        }
+
+        await DB.table(constructor.table)
+            .where(constructor.primaryKey, primaryKeyValue)
+            .delete();
+
+        this._exists = false;
+        return true;
+    }
+
+    toObject() {
+        return { ...this._attributes };
+    }
+}
+
+export default Model;