@nitronjs/framework 0.2.3 → 0.2.4

package/lib/Database/Model.js

@@ -1,29 +1,60 @@
 import DB from './DB.js';
 
+/**
+ * Base model class for database entities with Active Record pattern.
+ * Provides CRUD operations and query builder integration.
+ * 
+ * @example
+ * class User extends Model {
+ *     static table = "users";
+ * }
+ * 
+ * const user = await User.find(1);
+ * user.name = "John";
+ * await user.save();
+ */
 class Model {
+    /** @type {string|null} Database table name - must be defined in subclass */
     static table = null;
 
+    /**
+     * Creates a new model instance with attribute proxy support.
+     * @param {Object} attrs - Initial attributes
+     */
     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') {
+            get: (target, prop) => {
+                if (typeof prop === 'symbol' || prop === 'constructor') {
+                    return target[prop];
+                }
+
+                if (prop.startsWith('_')) {
                     return target[prop];
                 }
+
+                if (prop in target && typeof target[prop] === 'function') {
+                    return target[prop].bind(target);
+                }
+
                 return target._attributes[prop];
             },
-            set(target, prop, value) {
-                if (prop.startsWith('_')) {
+            set: (target, prop, value) => {
+                if (typeof prop === 'symbol' || prop.startsWith('_')) {
                     target[prop] = value;
+
                     return true;
                 }
-                if (prop in target) return false;
+
+                if (prop in target) {
+                    return false;
+                }
 
                 target._attributes[prop] = value;
 
@@ -32,145 +63,188 @@ class Model {
         });
     }
 
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Static Query Methods
+    // ─────────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Get all records from the table.
+     * @returns {Promise<Model[]>}
+     */
     static async get() {
-        if (!this.table) {
-            throw new Error(`Model ${this.name} must define a static 'table' property`);
-        }
+        ensureTable(this);
 
         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;
-        });
+        return rows.map(row => hydrate(this, row));
     }
 
+    /**
+     * Find a record by ID.
+     * @param {number|string} id - Record ID
+     * @returns {Promise<Model|null>}
+     */
     static async find(id) {
-        if (!this.table) {
-            throw new Error(`Model ${this.name} must define a static 'table' property`);
-        }
+        ensureTable(this);
 
-        const row = await DB.table(this.table).where("id", id).first();
+        const row = await DB.table(this.table).where('id', id).first();
 
-        if (!row) return null;
+        return row ? hydrate(this, row) : 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;
+    /**
+     * Get the first record from the table.
+     * @returns {Promise<Model|null>}
+     */
+    static async first() {
+        ensureTable(this);
+
+        const row = await DB.table(this.table).first();
+
+        return row ? hydrate(this, row) : null;
     }
 
+    /**
+     * Add a WHERE clause to the query.
+     * @param {string|Object} column - Column name or conditions object
+     * @param {string} [operator] - Comparison operator or value (if 2 args)
+     * @param {*} [value] - Value to compare
+     * @returns {import('./QueryBuilder.js').default}
+     */
     static where(column, operator, value) {
-        if (!this.table) {
-            throw new Error(`Model ${this.name} must define a static 'table' property`);
+        ensureTable(this);
+
+        if (arguments.length === 2) {
+            return DB.table(this.table, null, this).where(column, operator);
         }
 
         return DB.table(this.table, null, this).where(column, operator, value);
     }
 
+    /**
+     * Select specific columns.
+     * @param {...string} columns - Column names
+     * @returns {import('./QueryBuilder.js').default}
+     */
     static select(...columns) {
-        if (!this.table) {
-            throw new Error(`Model ${this.name} must define a static 'table' property`);
-        }
+        ensureTable(this);
 
         return DB.table(this.table, null, this).select(...columns);
     }
 
+    /**
+     * Order results by column.
+     * @param {string} column - Column name
+     * @param {'ASC'|'DESC'} [direction='ASC'] - Sort direction
+     * @returns {import('./QueryBuilder.js').default}
+     */
     static orderBy(column, direction = 'ASC') {
-        if (!this.table) {
-            throw new Error(`Model ${this.name} must define a static 'table' property`);
-        }
+        ensureTable(this);
 
         return DB.table(this.table, null, this).orderBy(column, direction);
     }
 
+    /**
+     * Limit the number of results.
+     * @param {number} value - Maximum records to return
+     * @returns {import('./QueryBuilder.js').default}
+     */
     static limit(value) {
-        if (!this.table) {
-            throw new Error(`Model ${this.name} must define a static 'table' property`);
-        }
+        ensureTable(this);
 
         return DB.table(this.table, null, this).limit(value);
     }
 
-    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();
-    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Instance Methods
+    // ─────────────────────────────────────────────────────────────────────────────
 
+    /**
+     * Save the model (insert or update).
+     * @returns {Promise<Model>}
+     */
     async save() {
-        const constructor = this.constructor;
+        const table = this.constructor.table;
         const data = {};
 
         for (const [key, value] of Object.entries(this._attributes)) {
-            if (value !== undefined && (key !== "id" || !this._exists)) {
+            if (value !== undefined && (key !== 'id' || !this._exists)) {
                 data[key] = value;
             }
         }
 
         if (this._exists) {
-            const primaryKeyValue = this._attributes["id"];
-            await DB.table(constructor.table)
-                .where("id", primaryKeyValue)
-                .update(data);
-            
-            Object.assign(this._attributes, data);
-            this._original = { ...this._attributes };
+            await DB.table(table).where('id', this._attributes.id).update(data);
         }
         else {
-            const id = await DB.table(constructor.table).insert(data);
-            this._attributes["id"] = id;
-            
-            this._original = { ...this._attributes };
+            const id = await DB.table(table).insert(data);
+            this._attributes.id = id;
             this._exists = true;
         }
 
+        this._original = { ...this._attributes };
+
         return this;
     }
 
+    /**
+     * Delete the model from database.
+     * @returns {Promise<boolean>}
+     * @throws {Error} If model doesn't exist in database
+     */
     async delete() {
-        const constructor = this.constructor;
-        const primaryKeyValue = this._attributes["id"];
-        
         if (!this._exists) {
             throw new Error('Cannot delete a model that does not exist');
         }
 
-        await DB.table(constructor.table)
-            .where("id", primaryKeyValue)
-            .delete();
-
+        await DB.table(this.constructor.table).where('id', this._attributes.id).delete();
         this._exists = false;
+
         return true;
     }
 
+    /**
+     * Convert model attributes to plain object.
+     * @returns {Object}
+     */
     toObject() {
         return { ...this._attributes };
     }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Private Helper Functions (module-scoped to avoid ES6 static inheritance issues)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Validates that table property is defined on the model class.
+ * @param {typeof Model} modelClass
+ */
+function ensureTable(modelClass) {
+    if (!modelClass.table) {
+        throw new Error(`Model ${modelClass.name} must define a static 'table' property`);
+    }
+}
+
+/**
+ * Creates a model instance from a database row.
+ * @param {typeof Model} modelClass
+ * @param {Object} row
+ * @returns {Model}
+ */
+function hydrate(modelClass, row) {
+    const instance = new modelClass();
+
+    for (const [key, value] of Object.entries(row)) {
+        instance._attributes[key] = value instanceof Date
+            ? value.toISOString().slice(0, 19).replace('T', ' ')
+            : value;
+    }
+
+    instance._exists = true;
+    instance._original = { ...instance._attributes };
+
+    return instance;
+}
+
 export default Model;

package/lib/Database/QueryBuilder.js

@@ -1,6 +1,17 @@
 import { validateDirection, validateIdentifier, validateWhereOperator } from "./QueryValidation.js";
 import Environment from "../Core/Environment.js";
 
+/**
+ * SQL query builder with fluent interface.
+ * Provides chainable methods for building safe parameterized queries.
+ * 
+ * @example
+ * const users = await DB.table("users")
+ *     .where("status", "active")
+ *     .orderBy("created_at", "DESC")
+ *     .limit(10)
+ *     .get();
+ */
 class QueryBuilder {
     #table = null;
     #connection = null;
@@ -483,6 +494,26 @@ class QueryBuilder {
         return parseInt(result) || 0;
     }
 
+    async max(column) {
+        return await this.#aggregate('MAX', column);
+    }
+
+    async min(column) {
+        return await this.#aggregate('MIN', column);
+    }
+
+    async sum(column) {
+        const result = await this.#aggregate('SUM', column);
+
+        return parseFloat(result) || 0;
+    }
+
+    async avg(column) {
+        const result = await this.#aggregate('AVG', column);
+
+        return parseFloat(result) || 0;
+    }
+
     async #aggregate(func, column) {
         const alias = func.toLowerCase();
         const originalSelect = this.#selectColumns;

package/lib/Database/QueryValidation.js

@@ -1,7 +1,7 @@
 const RESERVED_KEYWORDS = new Set([
-    'order', 'key', 'group', 'index', 'table', 'column', 'select', 'insert', 
-    'update', 'delete', 'from', 'where', 'join', 'left', 'right', 'inner', 
-    'outer', 'on', 'and', 'or', 'not', 'null', 'true', 'false', 'like', 
+    'order', 'key', 'group', 'index', 'table', 'column', 'select', 'insert',
+    'update', 'delete', 'from', 'where', 'join', 'left', 'right', 'inner',
+    'outer', 'on', 'and', 'or', 'not', 'null', 'true', 'false', 'like',
     'in', 'between', 'is', 'as', 'by', 'asc', 'desc', 'limit', 'offset',
     'having', 'distinct', 'all', 'any', 'exists', 'case', 'when', 'then',
     'else', 'end', 'if', 'into', 'values', 'set', 'create', 'drop', 'alter',
@@ -12,72 +12,57 @@ const RESERVED_KEYWORDS = new Set([
     'range', 'rows', 'rank', 'row', 'status', 'type', 'level', 'value', 'name'
 ]);
 
-function escapeIdentifier(identifier) {
-    if (RESERVED_KEYWORDS.has(identifier.toLowerCase())) {
-        return `\`${identifier}\``;
-    }
-    return identifier;
-}
+const ALLOWED_WHERE_OPERATORS = new Set([
+    '=', '!=', '<>', '<', '>', '<=', '>=',
+    'LIKE', 'NOT LIKE', 'ILIKE', 'NOT ILIKE',
+    'IN', 'NOT IN', 'IS', 'IS NOT',
+    'BETWEEN', 'NOT BETWEEN',
+    'REGEXP', 'NOT REGEXP', 'RLIKE', 'NOT RLIKE'
+]);
+
+const IDENTIFIER_PATTERNS = [
+    /^[a-zA-Z_][a-zA-Z0-9_]*$/,
+    /^[a-zA-Z_][a-zA-Z0-9_]*\.[a-zA-Z_][a-zA-Z0-9_]*$/,
+    /^[a-zA-Z_][a-zA-Z0-9_]*\.\*$/
+];
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Public Functions
+// ─────────────────────────────────────────────────────────────────────────────
 
 export function validateIdentifier(identifier) {
     if (typeof identifier !== 'string' || identifier.length === 0) {
         throw new Error('Identifier must be a non-empty string');
     }
-
     if (identifier.length > 64) {
         throw new Error(`Invalid identifier: "${identifier}". Maximum length is 64 characters.`);
     }
-
     if (identifier === '*' || identifier === '*.*') {
         return identifier;
     }
-
     if (/--|#|\/\*|\*\//.test(identifier)) {
         throw new Error(`Invalid identifier: "${identifier}". SQL comments are not allowed.`);
     }
 
-    const patterns = [
-        /^[a-zA-Z_][a-zA-Z0-9_]*$/,
-        /^[a-zA-Z_][a-zA-Z0-9_]*\.[a-zA-Z_][a-zA-Z0-9_]*$/,
-        /^[a-zA-Z_][a-zA-Z0-9_]*\.\*$/
-    ];
-
-    const isValid = patterns.some(pattern => pattern.test(identifier));
-
-    if (!isValid) {
-        throw new Error(`Invalid identifier: "${identifier}". Must be alphanumeric with underscores, optionally qualified with table name.`);
+    if (!IDENTIFIER_PATTERNS.some(p => p.test(identifier))) {
+        throw new Error(`Invalid identifier: "${identifier}". Must be alphanumeric with underscores.`);
     }
 
     if (identifier.includes('.')) {
         const [table, column] = identifier.split('.');
-        if (column === '*') {
-            return `${escapeIdentifier(table)}.*`;
-        }
-        return `${escapeIdentifier(table)}.${escapeIdentifier(column)}`;
+        return column === '*'
+            ? `${escapeKeyword(table)}.*`
+            : `${escapeKeyword(table)}.${escapeKeyword(column)}`;
     }
 
-    return escapeIdentifier(identifier);
+    return escapeKeyword(identifier);
 }
 
 export function validateWhereOperator(operator) {
     const normalized = String(operator).trim().toUpperCase();
-    const allowedOperators = new Set([
-        '=', '!=', '<>', '<', '>', '<=', '>=',
-        'LIKE', 'NOT LIKE', 'ILIKE', 'NOT ILIKE',
-        'IN', 'NOT IN',
-        'IS', 'IS NOT',
-        'BETWEEN', 'NOT BETWEEN',
-        'REGEXP', 'NOT REGEXP',
-        'RLIKE', 'NOT RLIKE'
-    ]);
-
-    if (!allowedOperators.has(normalized)) {
-        throw new Error(
-            `Invalid WHERE operator: '${operator}'. ` +
-            `Allowed operators: ${[...allowedOperators].join(', ')}`
-        );
+    if (!ALLOWED_WHERE_OPERATORS.has(normalized)) {
+        throw new Error(`Invalid WHERE operator: '${operator}'.`);
     }
-
     return normalized;
 }
 
@@ -86,6 +71,13 @@ export function validateDirection(direction) {
     if (upper !== 'ASC' && upper !== 'DESC') {
         throw new Error(`Invalid direction: ${direction}. Use 'ASC' or 'DESC'.`);
     }
-
     return upper;
 }
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Private Functions
+// ─────────────────────────────────────────────────────────────────────────────
+
+function escapeKeyword(identifier) {
+    return RESERVED_KEYWORDS.has(identifier.toLowerCase()) ? `\`${identifier}\`` : identifier;
+}

package/lib/Database/Schema/Blueprint.js

@@ -6,6 +6,10 @@ class Blueprint {
         this.#tableName = tableName;
     }
 
+    // ─────────────────────────────────────────────────────────────────────────
+    // Public Methods
+    // ─────────────────────────────────────────────────────────────────────────
+
     getTableName() {
         return this.#tableName;
     }
@@ -14,43 +18,8 @@ class Blueprint {
         return this.#columns;
     }
 
-    #addColumn(type, name, options = {}) {
-        const column = {
-            name,
-            type,
-            ...options,
-            modifiers: {
-                nullable: false,
-                default: null,
-                unique: false
-            }
-        };
-
-        this.#columns.push(column);
-
-        return {
-            nullable: () => {
-                column.modifiers.nullable = true;
-                return this;
-            },
-            default: (value) => {
-                column.modifiers.default = value;
-                return this;
-            },
-            unique: () => {
-                column.modifiers.unique = true;
-                return this;
-            }
-        };
-    }
-
     id() {
-        const column = {
-            name: 'id',
-            type: 'id',
-            modifiers: {}
-        };
-        this.#columns.push(column);
+        this.#columns.push({ name: 'id', type: 'id', modifiers: {} });
         return this;
     }
 
@@ -81,6 +50,26 @@ class Blueprint {
     json(name) {
         return this.#addColumn('json', name);
     }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // Private Methods
+    // ─────────────────────────────────────────────────────────────────────────
+
+    #addColumn(type, name, options = {}) {
+        const column = {
+            name,
+            type,
+            ...options,
+            modifiers: { nullable: false, default: null, unique: false }
+        };
+        this.#columns.push(column);
+
+        return {
+            nullable: () => { column.modifiers.nullable = true; return this; },
+            default: (value) => { column.modifiers.default = value; return this; },
+            unique: () => { column.modifiers.unique = true; return this; }
+        };
+    }
 }
 
 export default Blueprint;