voltjs-framework 1.0.0

package/src/database/model.js

@@ -0,0 +1,285 @@
+/**
+ * VoltJS Model (Active Record ORM)
+ * 
+ * Simple, powerful Active Record pattern for database operations.
+ * 
+ * @example
+ * const User = db.model('users', {
+ *   name: { type: 'string', required: true },
+ *   email: { type: 'string', unique: true },
+ *   age: { type: 'integer' },
+ * });
+ * 
+ * const user = await User.create({ name: 'John', email: 'john@example.com' });
+ * const users = await User.where('age', '>', 18).get();
+ */
+
+'use strict';
+
+class Model {
+  constructor(data = {}, tableName, schema, db) {
+    this._tableName = tableName;
+    this._schema = schema;
+    this._db = db;
+    this._original = { ...data };
+
+    // Assign data as properties
+    Object.assign(this, data);
+  }
+
+  /** Create a model class for a table */
+  static create(tableName, schema, db) {
+    // Create auto-table if in memory mode
+    if (db._config.driver === 'memory' && !db._tables.has(tableName)) {
+      db._tables.set(tableName, { schema, data: [], autoIncrement: 1 });
+    }
+
+    class BoundModel extends Model {
+      constructor(data = {}) {
+        super(data, tableName, schema, db);
+      }
+
+      // ===== STATIC QUERY METHODS =====
+
+      /** Find by ID */
+      static async find(id) {
+        const results = await db.table(tableName).where('id', '=', id).limit(1).get();
+        return results.length > 0 ? new BoundModel(results[0]) : null;
+      }
+
+      /** Find by ID or throw */
+      static async findOrFail(id) {
+        const result = await BoundModel.find(id);
+        if (!result) throw new Error(`${tableName} with id ${id} not found`);
+        return result;
+      }
+
+      /** Find by a field */
+      static async findBy(field, value) {
+        const results = await db.table(tableName).where(field, '=', value).limit(1).get();
+        return results.length > 0 ? new BoundModel(results[0]) : null;
+      }
+
+      /** Get all records */
+      static async all() {
+        const results = await db.table(tableName).get();
+        return results.map(r => new BoundModel(r));
+      }
+
+      /** Where clause (starts a query chain) */
+      static where(field, op, value) {
+        const qb = db.table(tableName).where(field, op, value);
+        // Wrap result to return model instances
+        const originalGet = qb.get.bind(qb);
+        qb.get = async () => {
+          const results = await originalGet();
+          return results.map(r => new BoundModel(r));
+        };
+        qb.first = async () => {
+          qb.limit(1);
+          const results = await originalGet();
+          return results.length > 0 ? new BoundModel(results[0]) : null;
+        };
+        return qb;
+      }
+
+      /** Create a new record */
+      static async create(data) {
+        // Validate
+        BoundModel._validate(data);
+
+        // Add timestamps
+        const now = new Date().toISOString();
+        if (schema.created_at !== undefined || schema.createdAt !== undefined) {
+          data.created_at = data.created_at || now;
+        }
+        if (schema.updated_at !== undefined || schema.updatedAt !== undefined) {
+          data.updated_at = now;
+        }
+
+        const result = await db.table(tableName).insert(data);
+        return new BoundModel({ id: result.insertId, ...data });
+      }
+
+      /** Create multiple records */
+      static async createMany(records) {
+        return Promise.all(records.map(r => BoundModel.create(r)));
+      }
+
+      /** Update by ID */
+      static async updateById(id, data) {
+        data.updated_at = new Date().toISOString();
+        return db.table(tableName).where('id', '=', id).update(data);
+      }
+
+      /** Delete by ID */
+      static async deleteById(id) {
+        return db.table(tableName).where('id', '=', id).delete();
+      }
+
+      /** Count records */
+      static async count(field, op, value) {
+        if (field) {
+          const results = await db.table(tableName).where(field, op, value).get();
+          return results.length;
+        }
+        const results = await db.table(tableName).get();
+        return results.length;
+      }
+
+      /** Paginate results */
+      static async paginate(page = 1, perPage = 20) {
+        const offset = (page - 1) * perPage;
+        const total = await BoundModel.count();
+        const data = await db.table(tableName).limit(perPage).offset(offset).get();
+
+        return {
+          data: data.map(r => new BoundModel(r)),
+          total,
+          page,
+          perPage,
+          totalPages: Math.ceil(total / perPage),
+          hasNext: page * perPage < total,
+          hasPrev: page > 1,
+        };
+      }
+
+      /** First or create */
+      static async firstOrCreate(searchData, createData = {}) {
+        const [field, value] = Object.entries(searchData)[0];
+        const existing = await BoundModel.findBy(field, value);
+        if (existing) return existing;
+        return BoundModel.create({ ...searchData, ...createData });
+      }
+
+      /** Validate data against schema */
+      static _validate(data) {
+        for (const [field, rules] of Object.entries(schema)) {
+          if (field === 'id') continue;
+
+          const rule = typeof rules === 'string' ? { type: rules } : rules;
+
+          // Required check
+          if (rule.required && (data[field] === undefined || data[field] === null || data[field] === '')) {
+            throw new Error(`Validation failed: "${field}" is required`);
+          }
+
+          if (data[field] !== undefined && data[field] !== null) {
+            // Type check
+            if (rule.type) {
+              const type = rule.type.toLowerCase();
+              if (type === 'integer' || type === 'int') {
+                if (!Number.isInteger(Number(data[field]))) {
+                  throw new Error(`Validation failed: "${field}" must be an integer`);
+                }
+              }
+              if (type === 'email') {
+                if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(data[field])) {
+                  throw new Error(`Validation failed: "${field}" must be a valid email`);
+                }
+              }
+            }
+
+            // Min/Max
+            if (rule.min !== undefined && data[field] < rule.min) {
+              throw new Error(`Validation failed: "${field}" must be at least ${rule.min}`);
+            }
+            if (rule.max !== undefined && data[field] > rule.max) {
+              throw new Error(`Validation failed: "${field}" must be at most ${rule.max}`);
+            }
+
+            // MinLength/MaxLength
+            if (rule.minLength && String(data[field]).length < rule.minLength) {
+              throw new Error(`Validation failed: "${field}" must be at least ${rule.minLength} characters`);
+            }
+            if (rule.maxLength && String(data[field]).length > rule.maxLength) {
+              throw new Error(`Validation failed: "${field}" must be at most ${rule.maxLength} characters`);
+            }
+
+            // Pattern
+            if (rule.pattern && !new RegExp(rule.pattern).test(data[field])) {
+              throw new Error(`Validation failed: "${field}" does not match required pattern`);
+            }
+
+            // Enum
+            if (rule.enum && !rule.enum.includes(data[field])) {
+              throw new Error(`Validation failed: "${field}" must be one of: ${rule.enum.join(', ')}`);
+            }
+          }
+        }
+      }
+
+      /** Get table name */
+      static get tableName() {
+        return tableName;
+      }
+
+      /** Get schema */
+      static get modelSchema() {
+        return schema;
+      }
+    }
+
+    // Instance methods
+    BoundModel.prototype.save = async function() {
+      if (this.id) {
+        const data = this._getChangedFields();
+        if (Object.keys(data).length > 0) {
+          await BoundModel.updateById(this.id, data);
+          this._original = { ...this._original, ...data };
+        }
+      } else {
+        const data = { ...this };
+        delete data._tableName;
+        delete data._schema;
+        delete data._db;
+        delete data._original;
+        const result = await BoundModel.create(data);
+        this.id = result.id;
+      }
+      return this;
+    };
+
+    BoundModel.prototype.delete = async function() {
+      if (this.id) {
+        await BoundModel.deleteById(this.id);
+      }
+      return this;
+    };
+
+    BoundModel.prototype.refresh = async function() {
+      if (this.id) {
+        const fresh = await BoundModel.find(this.id);
+        if (fresh) {
+          Object.assign(this, fresh);
+          this._original = { ...fresh };
+        }
+      }
+      return this;
+    };
+
+    BoundModel.prototype.toJSON = function() {
+      const obj = { ...this };
+      delete obj._tableName;
+      delete obj._schema;
+      delete obj._db;
+      delete obj._original;
+      return obj;
+    };
+
+    BoundModel.prototype._getChangedFields = function() {
+      const changed = {};
+      for (const [key, value] of Object.entries(this)) {
+        if (key.startsWith('_')) continue;
+        if (this._original[key] !== value) {
+          changed[key] = value;
+        }
+      }
+      return changed;
+    };
+
+    return BoundModel;
+  }
+}
+
+module.exports = { Model };

package/src/database/query.js

@@ -0,0 +1,394 @@
+/**
+ * VoltJS Query Builder
+ * 
+ * Fluent SQL query builder with support for all common operations.
+ * 
+ * @example
+ * const users = await db.table('users')
+ *   .where('age', '>', 18)
+ *   .where('status', '=', 'active')
+ *   .orderBy('name', 'ASC')
+ *   .limit(10)
+ *   .get();
+ */
+
+'use strict';
+
+class QueryBuilder {
+  constructor(tableName, db) {
+    this._table = tableName;
+    this._db = db;
+    this._wheres = [];
+    this._orders = [];
+    this._limit = null;
+    this._offset = null;
+    this._selects = ['*'];
+    this._joins = [];
+    this._groups = [];
+    this._havings = [];
+    this._params = [];
+  }
+
+  /** Select specific columns */
+  select(...columns) {
+    this._selects = columns.flat();
+    return this;
+  }
+
+  /** Where clause */
+  where(field, op, value) {
+    if (value === undefined) {
+      // Two-arg form: where('name', 'John') → where('name', '=', 'John')
+      value = op;
+      op = '=';
+    }
+    this._wheres.push({ field, op, value, type: 'AND' });
+    this._params.push(value);
+    return this;
+  }
+
+  /** OR where */
+  orWhere(field, op, value) {
+    if (value === undefined) { value = op; op = '='; }
+    this._wheres.push({ field, op, value, type: 'OR' });
+    this._params.push(value);
+    return this;
+  }
+
+  /** Where IN */
+  whereIn(field, values) {
+    this._wheres.push({ field, op: 'IN', value: values, type: 'AND' });
+    this._params.push(...values);
+    return this;
+  }
+
+  /** Where NOT IN */
+  whereNotIn(field, values) {
+    this._wheres.push({ field, op: 'NOT IN', value: values, type: 'AND' });
+    this._params.push(...values);
+    return this;
+  }
+
+  /** Where NULL */
+  whereNull(field) {
+    this._wheres.push({ field, op: 'IS', value: null, type: 'AND' });
+    return this;
+  }
+
+  /** Where NOT NULL */
+  whereNotNull(field) {
+    this._wheres.push({ field, op: 'IS NOT', value: null, type: 'AND' });
+    return this;
+  }
+
+  /** Where BETWEEN */
+  whereBetween(field, min, max) {
+    this._wheres.push({ field, op: 'BETWEEN', value: [min, max], type: 'AND' });
+    this._params.push(min, max);
+    return this;
+  }
+
+  /** Where LIKE */
+  whereLike(field, pattern) {
+    this._wheres.push({ field, op: 'LIKE', value: pattern, type: 'AND' });
+    this._params.push(pattern);
+    return this;
+  }
+
+  /** Order by */
+  orderBy(field, direction = 'ASC') {
+    this._orders.push({ field, direction: direction.toUpperCase() });
+    return this;
+  }
+
+  /** Limit */
+  limit(count) {
+    this._limit = count;
+    return this;
+  }
+
+  /** Offset */
+  offset(count) {
+    this._offset = count;
+    return this;
+  }
+
+  /** Join */
+  join(table, left, op, right) {
+    this._joins.push({ type: 'INNER', table, left, op, right });
+    return this;
+  }
+
+  /** Left join */
+  leftJoin(table, left, op, right) {
+    this._joins.push({ type: 'LEFT', table, left, op, right });
+    return this;
+  }
+
+  /** Right join */
+  rightJoin(table, left, op, right) {
+    this._joins.push({ type: 'RIGHT', table, left, op, right });
+    return this;
+  }
+
+  /** Group by */
+  groupBy(...fields) {
+    this._groups.push(...fields);
+    return this;
+  }
+
+  /** Having */
+  having(field, op, value) {
+    this._havings.push({ field, op, value });
+    return this;
+  }
+
+  /** Execute SELECT and get results */
+  async get() {
+    if (this._db._config.driver === 'memory') {
+      return this._memoryGet();
+    }
+
+    const sql = this._buildSelect();
+    return this._db.query(sql, this._params);
+  }
+
+  /** Get the first result */
+  async first() {
+    this._limit = 1;
+    const results = await this.get();
+    return results.length > 0 ? results[0] : null;
+  }
+
+  /** Insert a record */
+  async insert(data) {
+    if (this._db._config.driver === 'memory') {
+      return this._memoryInsert(data);
+    }
+
+    const columns = Object.keys(data);
+    const values = Object.values(data);
+    const placeholders = columns.map(() => '?').join(', ');
+    const sql = `INSERT INTO ${this._table} (${columns.join(', ')}) VALUES (${placeholders})`;
+    return this._db.query(sql, values);
+  }
+
+  /** Insert multiple records */
+  async insertMany(records) {
+    const results = [];
+    for (const record of records) {
+      results.push(await this.insert(record));
+    }
+    return results;
+  }
+
+  /** Update records */
+  async update(data) {
+    if (this._db._config.driver === 'memory') {
+      return this._memoryUpdate(data);
+    }
+
+    const setParts = Object.keys(data).map(k => `${k} = ?`);
+    const values = [...Object.values(data), ...this._params];
+    const sql = `UPDATE ${this._table} SET ${setParts.join(', ')}${this._buildWhere()}`;
+    return this._db.query(sql, values);
+  }
+
+  /** Delete records */
+  async delete() {
+    if (this._db._config.driver === 'memory') {
+      return this._memoryDelete();
+    }
+
+    const sql = `DELETE FROM ${this._table}${this._buildWhere()}`;
+    return this._db.query(sql, this._params);
+  }
+
+  /** Count matching records */
+  async count() {
+    if (this._db._config.driver === 'memory') {
+      const results = await this._memoryGet();
+      return results.length;
+    }
+
+    const sql = `SELECT COUNT(*) as count FROM ${this._table}${this._buildWhere()}`;
+    const result = await this._db.query(sql, this._params);
+    return result[0]?.count || 0;
+  }
+
+  /** Check if any matching record exists */
+  async exists() {
+    const count = await this.count();
+    return count > 0;
+  }
+
+  /** Get the built SQL (for debugging) */
+  toSQL() {
+    return { sql: this._buildSelect(), params: this._params };
+  }
+
+  // ===== SQL BUILDERS =====
+
+  _buildSelect() {
+    let sql = `SELECT ${this._selects.join(', ')} FROM ${this._table}`;
+    sql += this._buildJoins();
+    sql += this._buildWhere();
+    sql += this._buildGroupBy();
+    sql += this._buildHaving();
+    sql += this._buildOrderBy();
+    if (this._limit) sql += ` LIMIT ${this._limit}`;
+    if (this._offset) sql += ` OFFSET ${this._offset}`;
+    return sql;
+  }
+
+  _buildWhere() {
+    if (this._wheres.length === 0) return '';
+
+    const parts = this._wheres.map((w, i) => {
+      const prefix = i === 0 ? 'WHERE' : w.type;
+      if (w.op === 'IN' || w.op === 'NOT IN') {
+        const placeholders = w.value.map(() => '?').join(', ');
+        return `${prefix} ${w.field} ${w.op} (${placeholders})`;
+      }
+      if (w.op === 'BETWEEN') {
+        return `${prefix} ${w.field} BETWEEN ? AND ?`;
+      }
+      if (w.value === null) {
+        return `${prefix} ${w.field} ${w.op} NULL`;
+      }
+      return `${prefix} ${w.field} ${w.op} ?`;
+    });
+
+    return ' ' + parts.join(' ');
+  }
+
+  _buildJoins() {
+    return this._joins.map(j => ` ${j.type} JOIN ${j.table} ON ${j.left} ${j.op} ${j.right}`).join('');
+  }
+
+  _buildOrderBy() {
+    if (this._orders.length === 0) return '';
+    return ' ORDER BY ' + this._orders.map(o => `${o.field} ${o.direction}`).join(', ');
+  }
+
+  _buildGroupBy() {
+    if (this._groups.length === 0) return '';
+    return ' GROUP BY ' + this._groups.join(', ');
+  }
+
+  _buildHaving() {
+    if (this._havings.length === 0) return '';
+    return ' HAVING ' + this._havings.map(h => `${h.field} ${h.op} ${h.value}`).join(' AND ');
+  }
+
+  // ===== IN-MEMORY OPERATIONS =====
+
+  _memoryGet() {
+    const table = this._db._tables.get(this._table);
+    if (!table) return [];
+
+    let results = [...table.data];
+
+    // Apply WHERE conditions
+    for (const w of this._wheres) {
+      results = results.filter(row => {
+        const val = row[w.field];
+        switch (w.op) {
+          case '=': return val == w.value;
+          case '!=': case '<>': return val != w.value;
+          case '>': return val > w.value;
+          case '<': return val < w.value;
+          case '>=': return val >= w.value;
+          case '<=': return val <= w.value;
+          case 'LIKE':
+            const pattern = String(w.value).replace(/%/g, '.*').replace(/_/g, '.');
+            return new RegExp(`^${pattern}$`, 'i').test(String(val));
+          case 'IN': return Array.isArray(w.value) && w.value.includes(val);
+          case 'NOT IN': return Array.isArray(w.value) && !w.value.includes(val);
+          case 'IS': return val === null || val === undefined;
+          case 'IS NOT': return val !== null && val !== undefined;
+          case 'BETWEEN': return val >= w.value[0] && val <= w.value[1];
+          default: return true;
+        }
+      });
+    }
+
+    // Apply ORDER BY
+    for (const order of this._orders.reverse()) {
+      results.sort((a, b) => {
+        if (a[order.field] > b[order.field]) return order.direction === 'ASC' ? 1 : -1;
+        if (a[order.field] < b[order.field]) return order.direction === 'ASC' ? -1 : 1;
+        return 0;
+      });
+    }
+
+    // Apply OFFSET & LIMIT
+    if (this._offset) results = results.slice(this._offset);
+    if (this._limit) results = results.slice(0, this._limit);
+
+    // Apply SELECT
+    if (this._selects[0] !== '*') {
+      results = results.map(row => {
+        const filtered = {};
+        this._selects.forEach(col => { filtered[col] = row[col]; });
+        return filtered;
+      });
+    }
+
+    return results;
+  }
+
+  _memoryInsert(data) {
+    const table = this._db._tables.get(this._table);
+    if (!table) throw new Error(`Table "${this._table}" not found`);
+
+    const row = { id: table.autoIncrement++, ...data };
+    row.created_at = row.created_at || new Date().toISOString();
+    row.updated_at = new Date().toISOString();
+    table.data.push(row);
+
+    return { insertId: row.id, affectedRows: 1 };
+  }
+
+  _memoryUpdate(data) {
+    const table = this._db._tables.get(this._table);
+    if (!table) throw new Error(`Table "${this._table}" not found`);
+
+    let affected = 0;
+    for (const row of table.data) {
+      if (this._matchesWheres(row)) {
+        Object.assign(row, data);
+        row.updated_at = new Date().toISOString();
+        affected++;
+      }
+    }
+    return { affectedRows: affected };
+  }
+
+  _memoryDelete() {
+    const table = this._db._tables.get(this._table);
+    if (!table) throw new Error(`Table "${this._table}" not found`);
+
+    const before = table.data.length;
+    table.data = table.data.filter(row => !this._matchesWheres(row));
+    return { affectedRows: before - table.data.length };
+  }
+
+  _matchesWheres(row) {
+    if (this._wheres.length === 0) return true;
+    return this._wheres.every(w => {
+      const val = row[w.field];
+      switch (w.op) {
+        case '=': return val == w.value;
+        case '!=': return val != w.value;
+        case '>': return val > w.value;
+        case '<': return val < w.value;
+        case '>=': return val >= w.value;
+        case '<=': return val <= w.value;
+        default: return true;
+      }
+    });
+  }
+}
+
+module.exports = { QueryBuilder };