@nitronjs/framework 0.1.0

package/lib/Database/QueryBuilder.js

@@ -0,0 +1,714 @@
+import { validateDirection, validateIdentifier, validateWhereOperator } from "./QueryValidation.js";
+
+class QueryBuilder {
+    #table = null;
+    #connection = null;
+    #connectionGetter = null;
+    #selectColumns = ['*'];
+    #wheres = [];
+    #bindings = [];
+    #joins = [];
+    #orders = [];
+    #groups = [];
+    #havings = [];
+    #limitValue = null;
+    #offsetValue = null;
+    #distinctFlag = false;
+    #modelClass = null;
+
+    constructor(table, connectionOrGetter, modelClass = null) {
+        this.#table = this.#validateIdentifier(table);
+        // connectionOrGetter can be:
+        // - null for SQL compilation (toSql())
+        // - a connection object directly
+        // - an async function that returns a connection (lazy loading)
+        if (typeof connectionOrGetter === 'function') {
+            this.#connectionGetter = connectionOrGetter;
+            this.#connection = null;
+        } else {
+            this.#connection = connectionOrGetter;
+            this.#connectionGetter = null;
+        }
+        this.#modelClass = modelClass;
+    }
+
+    async #getConnection() {
+        if (this.#connection) {
+            return this.#connection;
+        }
+        if (this.#connectionGetter) {
+            this.#connection = await this.#connectionGetter();
+            return this.#connection;
+        }
+        throw new Error('QueryBuilder: No database connection. Cannot execute query. Use DB.table() after DB.setup().');
+    }
+
+    #validateIdentifier(identifier) {
+        return validateIdentifier(identifier);
+    }
+
+    #validateWhereOperator(operator) {
+        return validateWhereOperator(operator);
+    }
+
+    #validateDirection(direction) {
+        return validateDirection(direction);
+    }
+
+    #validateJoinOperator(operator) {
+        const validOperators = ['=', '!=', '<>', '<', '>', '<=', '>='];
+        if (!validOperators.includes(operator)) {
+            throw new Error(`Invalid JOIN operator: "${operator}". Must be one of: ${validOperators.join(', ')}.`);
+        }
+
+        return operator;
+    }
+
+    #validateInteger(value) {
+        const stringValue = String(value).trim();
+        if (!/^\d+$/.test(stringValue)) {
+            throw new Error(`Invalid integer: "${value}". Must be a pure positive number.`);
+        }
+
+        const num = parseInt(stringValue, 10);
+        if (isNaN(num) || num < 0) {
+            throw new Error(`Invalid integer: "${value}". Must be a non-negative number.`);
+        }
+
+        if (num > 100000) {
+            throw new Error(`Invalid integer: "${value}". Maximum allowed value is 100000.`);
+        }
+
+        return num;
+    }
+
+    #isRawExpression(value) {
+        return value instanceof RawExpression;
+    }
+
+    #validateWhereValue(value) {
+        if (value === null || value === undefined) {
+            return value;
+        }
+
+        const type = typeof value;
+        
+        if (type !== 'string' && type !== 'number' && type !== 'boolean') {
+            throw new Error(
+                `Invalid WHERE value type: ${type}. ` +
+                `Only string, number, boolean, or null are allowed.`
+            );
+        }
+
+        return value;
+    }
+
+    #sanitizeError(error) {
+        const isProduction = process.env.APP_DEV === 'false';
+
+        if (isProduction) {
+            console.error('[QueryBuilder] Database error:', {
+                message: error.message,
+                code: error.code,
+                errno: error.errno,
+                sql: error.sql?.substring(0, 100),
+                sqlState: error.sqlState
+            });
+
+            const sanitized = new Error('Database query failed. Please contact support if the problem persists.');
+            sanitized.code = 'DATABASE_ERROR';
+
+            return sanitized;
+        }
+
+        return error;
+    }
+
+    #reset() {
+        this.#selectColumns = ['*'];
+        this.#wheres = [];
+        this.#bindings = [];
+        this.#joins = [];
+        this.#orders = [];
+        this.#groups = [];
+        this.#havings = [];
+        this.#limitValue = null;
+        this.#offsetValue = null;
+        this.#distinctFlag = false;
+    }
+
+    select(...columns) {
+        if (columns.length === 0) {
+            return this;
+        }
+
+        this.#selectColumns = columns.map(col => {
+            if (this.#isRawExpression(col)) {
+                return col;
+            }
+
+            return this.#validateIdentifier(col);
+        });
+
+        return this;
+    }
+
+    distinct() {
+        this.#distinctFlag = true;
+
+        return this;
+    }
+
+    where(column, operator, value) {
+        if (arguments.length === 2) {
+            value = operator;
+            operator = '=';
+        }
+
+        operator = this.#validateWhereOperator(operator);
+        value = this.#validateWhereValue(value);
+
+        this.#wheres.push({
+            type: 'basic',
+            column: this.#validateIdentifier(column),
+            operator,
+            value,
+            boolean: 'AND'
+        });
+
+        this.#bindings.push(value);
+
+        return this;
+    }
+
+    orWhere(column, operator, value) {
+        if (arguments.length === 2) {
+            value = operator;
+            operator = '=';
+        }
+
+        operator = this.#validateWhereOperator(operator);
+        value = this.#validateWhereValue(value);
+
+        this.#wheres.push({
+            type: 'basic',
+            column: this.#validateIdentifier(column),
+            operator,
+            value,
+            boolean: 'OR'
+        });
+
+        this.#bindings.push(value);
+
+        return this;
+    }
+
+    whereIn(column, values) {
+        if (!Array.isArray(values) || values.length === 0) {
+            return this;
+        }
+
+        if (values.length > 1000) {
+            throw new Error(
+                `whereIn() array too large (${values.length} values). ` +
+                'Maximum allowed is 1000. Consider splitting into multiple queries or using a temporary table.'
+            );
+        }
+
+        for (const value of values) {
+            const type = typeof value;
+            if (type !== 'string' && type !== 'number' && type !== 'boolean' && value !== null) {
+                throw new Error(
+                    `whereIn() values must be primitives (string, number, boolean, null). ` +
+                    `Found: ${type}`
+                );
+            }
+        }
+
+        this.#wheres.push({
+            type: 'in',
+            column: this.#validateIdentifier(column),
+            values,
+            boolean: 'AND'
+        });
+
+        this.#bindings.push(...values);
+
+        return this;
+    }
+
+    whereNotIn(column, values) {
+        if (!Array.isArray(values) || values.length === 0) {
+            return this;
+        }
+
+        if (values.length > 1000) {
+            throw new Error(
+                `whereNotIn() array too large (${values.length} values). ` +
+                'Maximum allowed is 1000. Consider splitting into multiple queries.'
+            );
+        }
+
+        this.#wheres.push({
+            type: 'notIn',
+            column: this.#validateIdentifier(column),
+            values,
+            boolean: 'AND'
+        });
+
+        this.#bindings.push(...values);
+
+        return this;
+    }
+
+    whereNull(column) {
+        this.#wheres.push({
+            type: 'null',
+            column: this.#validateIdentifier(column),
+            boolean: 'AND'
+        });
+
+        return this;
+    }
+
+    whereNotNull(column) {
+        this.#wheres.push({
+            type: 'notNull',
+            column: this.#validateIdentifier(column),
+            boolean: 'AND'
+        });
+
+        return this;
+    }
+
+    whereBetween(column, values) {
+        if (!Array.isArray(values) || values.length !== 2) {
+            throw new Error('whereBetween requires array with exactly 2 values');
+        }
+
+        this.#wheres.push({
+            type: 'between',
+            column: this.#validateIdentifier(column),
+            values,
+            boolean: 'AND'
+        });
+
+        this.#bindings.push(...values);
+
+        return this;
+    }
+
+    whereRaw(sql, bindings = []) {
+        if (typeof sql !== 'string' || sql.length === 0) {
+            throw new Error('whereRaw requires non-empty SQL string');
+        }
+
+        this.#wheres.push({
+            type: 'raw',
+            sql,
+            boolean: 'AND'
+        });
+
+        this.#bindings.push(...bindings);
+
+        return this;
+    }
+
+    join(table, first, operator, second, type = 'inner') {
+        if (arguments.length === 3) {
+            second = operator;
+            operator = '=';
+        }
+
+        const validTypes = ['inner', 'left', 'right'];
+        const joinType = validTypes.includes(type) ? type : 'inner';
+
+        this.#joins.push({
+            type: joinType,
+            table: this.#validateIdentifier(table),
+            first: this.#validateIdentifier(first),
+            operator: this.#validateJoinOperator(operator),
+            second: this.#validateIdentifier(second)
+        });
+
+        return this;
+    }
+
+    leftJoin(table, first, operator, second) {
+        return this.join(table, first, operator, second, 'left');
+    }
+
+    rightJoin(table, first, operator, second) {
+        return this.join(table, first, operator, second, 'right');
+    }
+
+    orderBy(column, direction = 'ASC') {
+        this.#orders.push({
+            column: this.#validateIdentifier(column),
+            direction: this.#validateDirection(direction)
+        });
+
+        return this;
+    }
+
+    groupBy(...columns) {
+        const validated = columns.map(col => this.#validateIdentifier(col));
+        this.#groups.push(...validated);
+
+        return this;
+    }
+
+    having(column, operator, value) {
+        if (arguments.length === 2) {
+            value = operator;
+            operator = '=';
+        }
+
+        operator = this.#validateWhereOperator(operator);
+
+        this.#havings.push({
+            column: this.#validateIdentifier(column),
+            operator,
+            value
+        });
+        this.#bindings.push(value);
+
+
+        return this;
+    }
+
+    limit(value) {
+        this.#limitValue = this.#validateInteger(value);
+
+        return this;
+    }
+
+    offset(value) {
+        this.#offsetValue = this.#validateInteger(value);
+
+        return this;
+    }
+
+    forPage(page, perPage = 15) {
+        return this.offset((page - 1) * perPage).limit(perPage);
+    }
+
+    async get() {
+        const connection = await this.#getConnection();
+
+        try {
+            const sql = this.#toSql();
+            const [rows] = await connection.query(sql, this.#bindings);
+
+            if (this.#modelClass) {
+                return rows.map(row => this.#hydrateModel(row));
+            }
+
+            return rows;
+        }
+
+        catch (error) {
+            throw this.#sanitizeError(error);
+        }
+
+        finally {
+            this.#reset();
+        }
+    }
+
+    async first() {
+        const connection = await this.#getConnection();
+
+        const originalLimit = this.#limitValue;
+        this.#limitValue = 1;
+
+        try {
+            const sql = this.#toSql();
+            const [rows] = await connection.query(sql, this.#bindings);
+
+            if (!rows[0]) return null;
+
+            if (this.#modelClass) {
+                return this.#hydrateModel(rows[0]);
+            }
+
+            return rows[0];
+        }
+
+        catch (error) {
+            throw this.#sanitizeError(error);
+        }
+
+        finally {
+            this.#limitValue = originalLimit;
+            this.#reset();
+        }
+    }
+
+    #hydrateModel(row) {
+        const instance = new this.#modelClass();
+        
+        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;
+    }
+
+    async find(id) {
+        return this.where('id', id).first();
+    }
+
+    async count(column = '*') {
+        const result = await this.#aggregate('COUNT', column);
+
+        return parseInt(result) || 0;
+    }
+
+    async #aggregate(func, column) {
+        const alias = func.toLowerCase();
+        const originalSelect = this.#selectColumns;
+
+        try {
+            const validatedColumn = column === '*' ? '*' : this.#validateIdentifier(column);
+            this.#selectColumns = [new RawExpression(`${func}(${validatedColumn}) as ${alias}`)];
+
+            const row = await this.first(); // first() handles reset internally
+
+            return row ? row[alias] : null;
+        }
+
+        finally {
+            this.#selectColumns = originalSelect;
+        }
+    }
+
+    async insert(data) {
+        const connection = await this.#getConnection();
+        try {
+            const isArray = Array.isArray(data);
+            const rows = isArray ? data : [data];
+
+            if (rows.length === 0) {
+                throw new Error('Cannot insert empty data');
+            }
+
+            const columns = Object.keys(rows[0]);
+            columns.forEach(col => this.#validateIdentifier(col));
+
+            const placeholders = rows.map(() => `(${columns.map(() => '?').join(', ')})`).join(', ');
+            const values = rows.flatMap(row => columns.map(col => row[col]));
+
+            const sql = `INSERT INTO ${this.#table} (${columns.join(', ')}) VALUES ${placeholders}`;
+            const [result] = await connection.query(sql, values);
+
+
+            return result.insertId;
+        }
+
+        catch (error) {
+            throw this.#sanitizeError(error);
+        }
+
+        finally {
+            this.#reset();
+        }
+    }
+
+    async update(data) {
+        const connection = await this.#getConnection();
+        try {
+            const columns = Object.keys(data);
+            const values = [];
+            const sets = [];
+
+            for (const col of columns) {
+                const validatedCol = this.#validateIdentifier(col);
+                const val = data[col];
+                if (this.#isRawExpression(val)) {
+                    sets.push(`${validatedCol} = ${val.value}`);
+                }
+
+                else {
+                    sets.push(`${validatedCol} = ?`);
+                    values.push(val);
+                }
+            }
+
+            const sql = `UPDATE ${this.#table} SET ${sets.join(', ')}${this.#compileWheres()}`;
+            const [result] = await connection.query(sql, [...values, ...this.#bindings]);
+
+            return result.affectedRows;
+        }
+
+        catch (error) {
+            throw this.#sanitizeError(error);
+        }
+
+        finally {
+            this.#reset();
+        }
+    }
+
+    async delete() {
+        const connection = await this.#getConnection();
+        try {
+            const sql = `DELETE FROM ${this.#table}${this.#compileWheres()}`;
+            const [result] = await connection.query(sql, this.#bindings);
+
+            return result.affectedRows;
+        }
+
+        catch (error) {
+            throw this.#sanitizeError(error);
+        }
+
+        finally {
+            this.#reset();
+        }
+    }
+
+    #toSql() {
+        const distinct = this.#distinctFlag ? 'DISTINCT ' : '';
+        const columns = this.#selectColumns.map(col => {
+            return this.#isRawExpression(col) ? col.value : col;
+        }).join(', ');
+
+        const joins = this.#compileJoins();
+        const wheres = this.#compileWheres();
+        const groups = this.#compileGroupBy();
+        const havings = this.#compileHaving();
+        const orders = this.#compileOrders();
+        const limit = this.#compileLimit();
+
+        return `SELECT ${distinct}${columns} FROM ${this.#table}${joins}${wheres}${groups}${havings}${orders}${limit}`;
+    }
+
+    #compileJoins() {
+        if (this.#joins.length === 0) {
+            return '';
+        }
+
+        return this.#joins.map(join => {
+            const type = join.type.toUpperCase();
+
+            return ` ${type} JOIN ${join.table} ON ${join.first} ${join.operator} ${join.second}`;
+        }).join('');
+    }
+
+    #compileWheres() {
+        if (this.#wheres.length === 0) {
+            return '';
+        }
+
+        const compiled = this.#wheres.map((where, index) => {
+            const boolean = index === 0 ? '' : ` ${where.boolean} `;
+
+            switch (where.type) {
+                case 'basic':
+                    return `${boolean}${where.column} ${where.operator} ?`;
+                case 'in':
+                    const inPlaceholders = where.values.map(() => '?').join(', ');
+
+                    return `${boolean}${where.column} IN (${inPlaceholders})`;
+                case 'notIn':
+                    const notInPlaceholders = where.values.map(() => '?').join(', ');
+
+                    return `${boolean}${where.column} NOT IN (${notInPlaceholders})`;
+                case 'null':
+                    return `${boolean}${where.column} IS NULL`;
+                case 'notNull':
+                    return `${boolean}${where.column} IS NOT NULL`;
+                case 'between':
+                    return `${boolean}${where.column} BETWEEN ? AND ?`;
+                case 'raw':
+                    return `${boolean}${where.sql}`;
+                default:
+                    return '';
+            }
+        }).join('');
+
+        return ` WHERE ${compiled}`;
+    }
+
+    #compileGroupBy() {
+        if (this.#groups.length === 0) {
+            return '';
+        }
+
+        return ` GROUP BY ${this.#groups.join(', ')}`;
+    }
+
+    #compileHaving() {
+        if (this.#havings.length === 0) {
+            return '';
+        }
+
+        const compiled = this.#havings.map((having, index) => {
+            const boolean = index === 0 ? '' : ' AND ';
+
+            return `${boolean}${having.column} ${having.operator} ?`;
+        }).join('');
+
+        return ` HAVING ${compiled}`;
+    }
+
+    #compileOrders() {
+        if (this.#orders.length === 0) {
+            return '';
+        }
+
+        const compiled = this.#orders.map(order => `${order.column} ${order.direction}`).join(', ');
+
+        return ` ORDER BY ${compiled}`;
+    }
+
+    #compileLimit() {
+        let sql = '';
+
+        if (this.#limitValue !== null) {
+            sql += ` LIMIT ${this.#limitValue}`;
+        }
+
+        if (this.#offsetValue !== null) {
+            sql += ` OFFSET ${this.#offsetValue}`;
+        }
+
+        return sql;
+    }
+
+    toSql() {
+        return this.#toSql();
+    }
+
+    getBindings() {
+        return [...this.#bindings];
+    }
+}
+
+export class RawExpression {
+    constructor(value) {
+        if (typeof value !== 'string') {
+            throw new Error('RawExpression value must be a string');
+        }
+
+        this.value = value;
+    }
+
+    toString() {
+        return this.value;
+    }
+}
+
+export function query(table, connection = null, modelClass = null) {
+    return new QueryBuilder(table, connection, modelClass);
+}
+
+export default QueryBuilder;