millas 0.1.8 → 0.1.9

package/src/orm/model/Model.js

@@ -1,6 +1,7 @@
 'use strict';
 
-const QueryBuilder   = require('../query/QueryBuilder');
+const QueryBuilder    = require('../query/QueryBuilder');
+const LookupParser    = require('../query/LookupParser');
 const DatabaseManager = require('../drivers/DatabaseManager');
 
 /**
@@ -8,80 +9,176 @@ const DatabaseManager = require('../drivers/DatabaseManager');
  *
  * Base class for all Millas ORM models.
  *
- * Define your schema with static fields and interact via static
- * query methods — no instantiation needed for reads.
+ * ── Schema ───────────────────────────────────────────────────────────────────
  *
- * Usage:
+ *   class Post extends Model {
+ *     static table  = 'posts';
+ *     static fields = {
+ *       id:           fields.id(),
+ *       title:        fields.string(),
+ *       body:         fields.text({ nullable: true }),
+ *       user_id:      fields.foreignId('user_id'),
+ *       published:    fields.boolean({ default: false }),
+ *       published_at: fields.timestamp({ nullable: true }),
+ *       created_at:   fields.timestamp(),
+ *       updated_at:   fields.timestamp(),
+ *     };
  *
- *   const { Model, fields } = require('millas/src/orm');
+ * ── Relations ────────────────────────────────────────────────────────────────
  *
- *   class User extends Model {
- *     static table  = 'users';
- *     static fields = {
- *       id:         fields.id(),
- *       name:       fields.string(),
- *       email:      fields.string({ unique: true }),
- *       active:     fields.boolean({ default: true }),
- *       created_at: fields.timestamp(),
- *       updated_at: fields.timestamp(),
+ *     static relations = {
+ *       author:   new BelongsTo(() => User, 'user_id'),
+ *       comments: new HasMany(() => Comment, 'post_id'),
+ *       tags:     new BelongsToMany(() => Tag, 'post_tag', 'post_id', 'tag_id'),
+ *     };
+ *
+ * ── Scopes ───────────────────────────────────────────────────────────────────
+ *
+ *     static scopes = {
+ *       published:  qb => qb.where('published', true),
+ *       recent:     qb => qb.latest().limit(10),
+ *       byUser:    (qb, userId) => qb.where('user_id', userId),
  *     };
+ *
+ * ── Soft deletes ─────────────────────────────────────────────────────────────
+ *
+ *     static softDeletes = true;
+ *     // Now delete() sets deleted_at instead of removing the row.
+ *     // All queries automatically exclude deleted rows.
+ *
+ * ── Validation ───────────────────────────────────────────────────────────────
+ *
+ *     static validate(data) {
+ *       if (!data.title) throw new Error('title is required');
+ *     }
+ *
+ * ── Lifecycle hooks (signals) ────────────────────────────────────────────────
+ *
+ *     static beforeCreate(data)   { return data; }  // can modify data
+ *     static afterCreate(instance) {}
+ *     static beforeUpdate(data)   { return data; }
+ *     static afterUpdate(instance) {}
+ *     static beforeDelete(instance) {}
+ *     static afterDelete(instance) {}
  *   }
  *
+ * ── Usage ─────────────────────────────────────────────────────────────────────
+ *
  *   // CRUD
- *   const user  = await User.create({ name: 'Alice', email: 'a@b.com' });
- *   const users = await User.all();
- *   const found = await User.find(1);
- *   const alice = await User.findBy('email', 'a@b.com');
- *   await user.update({ name: 'Alice Smith' });
- *   await user.delete();
+ *   const post  = await Post.create({ title: 'Hello' });
+ *   const posts = await Post.all();
+ *   const found = await Post.find(1);
+ *   await post.update({ title: 'New Title' });
+ *   await post.delete();                     // soft-delete if enabled
+ *
+ *   // Lookups
+ *   Post.where('title__icontains', 'world').get()
+ *   Post.where('published_at__year', 2024).get()
+ *
+ *   // Q objects
+ *   Post.filter(Q({ published: true }).or({ user_id: 5 })).get()
+ *
+ *   // Scopes
+ *   Post.scope('published').scope('recent').get()
+ *
+ *   // Relations
+ *   Post.with('author', 'tags').get()
+ *   post.author()     // lazy-load
+ *   post.tags()       // lazy-load
+ *   post.tags.attach(5)
+ *   post.tags.sync([1, 2, 3])
+ *
+ *   // Aggregates
+ *   Post.aggregate({ total: Count('id'), avg: Avg('views') })
+ *   Post.annotate({ comment_count: Count('comments.id') }).get()
+ *
+ *   // Transactions
+ *   await Post.transaction(async (trx) => {
+ *     await Post.create({ title: 'Hello' }, { trx });
+ *     await Tag.create({ name: 'news' }, { trx });
+ *   });
+ *
+ *   // Soft deletes
+ *   await post.delete()                 // sets deleted_at
+ *   await post.restore()                // clears deleted_at
+ *   Post.withTrashed().get()            // includes deleted
+ *   Post.onlyTrashed().get()            // only deleted
  *
- *   // Query builder
- *   const active = await User.where('active', true).orderBy('name').get();
- *   const admins = await User.where('role', 'admin').limit(10).get();
- *   const page   = await User.where('active', true).paginate(1, 15);
+ *   // Bulk update
+ *   await Post.bulkUpdate([
+ *     { id: 1, title: 'One' },
+ *     { id: 2, title: 'Two' },
+ *   ], 'id');
+ *
+ *   // only() / defer()
+ *   Post.only('id', 'title').get()
+ *   Post.defer('body').get()
+ *
+ *   // Raw
+ *   Post.raw('SELECT * FROM posts WHERE YEAR(created_at) = ?', [2024])
  */
 class Model {
   // ─── Static schema config ─────────────────────────────────────────────────
 
-  /** @type {string} Table name — defaults to pluralised lowercase class name */
   static get table() {
     return this._table || (this._table = this._defaultTable());
   }
   static set table(v) { this._table = v; }
 
-  /** @type {string} Primary key column name */
-  static primaryKey = 'id';
+  static primaryKey  = 'id';
+  static timestamps  = true;
+  static softDeletes = false;
+  static fields      = {};
+  static connection  = null;
+
+  /** Define named scopes: static scopes = { published: qb => qb.where('published', true) } */
+  static scopes = {};
+
+  /** Define relations: static relations = { author: new BelongsTo(...) } */
+  static relations = {};
+
+  // ─── Lifecycle hooks (override in subclass) ───────────────────────────────
 
-  /** @type {boolean} Whether to auto-manage created_at / updated_at */
-  static timestamps = true;
+  static async beforeCreate(data)    { return data; }
+  static async afterCreate(instance) {}
+  static async beforeUpdate(data)    { return data; }
+  static async afterUpdate(instance) {}
+  static async beforeDelete(instance){}
+  static async afterDelete(instance) {}
 
-  /** @type {object} Field definitions */
-  static fields = {};
+  // ─── Validation (override in subclass) ───────────────────────────────────
 
-  /** @type {string|null} Named DB connection to use */
-  static connection = null;
+  /** Override to throw validation errors before create/update. */
+  static validate(data) {}
 
-  // ─── Static CRUD methods ──────────────────────────────────────────────────
+  // ─── Transactions ─────────────────────────────────────────────────────────
 
   /**
-   * Return all rows.
+   * Run a callback inside a database transaction.
+   * If the callback throws, the transaction is rolled back automatically.
+   *
+   *   await Post.transaction(async (trx) => {
+   *     const post = await Post.create({ title: 'Hi' }, { trx });
+   *     await post.update({ published: true }, { trx });
+   *   });
    */
+  static async transaction(callback) {
+    const db = DatabaseManager.connection(this.connection || null);
+    return db.transaction(callback);
+  }
+
+  // ─── Static CRUD ──────────────────────────────────────────────────────────
+
   static async all() {
     const rows = await this._db();
     return rows.map(r => this._hydrate(r));
   }
 
-  /**
-   * Find by primary key. Returns null if not found.
-   */
   static async find(id) {
     const row = await this._db().where(this.primaryKey, id).first();
     return row ? this._hydrate(row) : null;
   }
 
-  /**
-   * Find by primary key. Throws 404 HttpError if not found.
-   */
   static async findOrFail(id) {
     const result = await this.find(id);
     if (!result) {
@@ -91,17 +188,12 @@ class Model {
     return result;
   }
 
-  /**
-   * Find the first row matching column = value.
-   */
   static async findBy(column, value) {
-    const row = await this._db().where(column, value).first();
-    return row ? this._hydrate(row) : null;
+    const qb = new QueryBuilder(this._db(), this);
+    qb.where(column, value);
+    return qb.first();
   }
 
-  /**
-   * Find the first row matching column = value or throw 404.
-   */
   static async findByOrFail(column, value) {
     const result = await this.findBy(column, value);
     if (!result) {
@@ -112,31 +204,37 @@ class Model {
   }
 
   /**
-   * Create a new row and return the model instance.
+   * Create a new row.
+   * @param {object} data
+   * @param {object} options  — { trx } for transaction support
    */
-  static async create(data) {
-    const now = new Date().toISOString();
-    const payload = {
+  static async create(data, { trx } = {}) {
+    this.validate(data);
+
+    const now     = new Date().toISOString();
+    let payload   = {
       ...this._applyDefaults(data),
       ...(this.timestamps ? { created_at: now, updated_at: now } : {}),
     };
 
-    const [id] = await this._db().insert(payload);
-    return this.find(id);
+    payload = await this.beforeCreate(payload) ?? payload;
+
+    const q     = trx ? trx(this.table) : this._db();
+    const [id]  = await q.insert(payload);
+    const instance = await (trx
+      ? this._hydrateFromTrx(id, trx)
+      : this.find(id));
+
+    await this.afterCreate(instance);
+    return instance;
   }
 
-  /**
-   * Find by column or create if not found.
-   */
   static async firstOrCreate(search, extra = {}) {
-    const existing = await this.findBy(Object.keys(search)[0], Object.values(search)[0]);
+    const existing = await this.where(search).first();
     if (existing) return existing;
     return this.create({ ...search, ...extra });
   }
 
-  /**
-   * Update or create based on search criteria.
-   */
   static async updateOrCreate(search, data) {
     const existing = await this.where(search).first();
     if (existing) {
@@ -146,31 +244,19 @@ class Model {
     return this.create({ ...search, ...data });
   }
 
-  /**
-   * Count rows.
-   */
   static async count(column = '*') {
-    const result = await this._db().count(`${column} as count`);
-    const row = Array.isArray(result) ? result[0] : result;
-    return Number(row?.count ?? 0);
+    const result = await this._db().count(`${column} as count`).first();
+    return Number(result?.count ?? 0);
   }
 
-  /**
-   * Check whether any row matches the optional conditions.
-   */
   static async exists(conditions = {}) {
-    let q = this._db();
-    if (Object.keys(conditions).length) q = q.where(conditions);
-    const result = await q.count('* as count');
-    const row = Array.isArray(result) ? result[0] : result;
-    return Number(row?.count ?? 0) > 0;
+    const qb = new QueryBuilder(this._db(), this);
+    for (const [k, v] of Object.entries(conditions)) qb.where(k, v);
+    return (await qb.count()) > 0;
   }
 
-  /**
-   * Bulk insert — returns number of rows inserted.
-   */
   static async insert(rows) {
-    const now = new Date().toISOString();
+    const now     = new Date().toISOString();
     const payload = rows.map(r => ({
       ...this._applyDefaults(r),
       ...(this.timestamps ? { created_at: now, updated_at: now } : {}),
@@ -178,25 +264,116 @@ class Model {
     return this._db().insert(payload);
   }
 
-  /**
-   * Delete rows by primary key.
-   */
   static async destroy(...ids) {
     return this._db().whereIn(this.primaryKey, ids.flat()).delete();
   }
 
-  /**
-   * Truncate the table.
-   */
   static async truncate() {
     return this._db().truncate();
   }
 
+  // ─── Aggregation ──────────────────────────────────────────────────────────
+
+  /**
+   * Compute one or more aggregate values over the whole table.
+   *
+   *   await Order.aggregate({ total: Sum('amount'), avg: Avg('amount') })
+   *   // → { total: 9430.5, avg: 94.3 }
+   */
+  static async aggregate(expressions) {
+    const { AggregateExpression } = require('../query/Aggregates');
+    let q = this._db();
+
+    const selects = [];
+    for (const [alias, expr] of Object.entries(expressions)) {
+      if (!(expr instanceof AggregateExpression)) {
+        throw new Error(`aggregate() values must be Aggregate expressions (Sum, Count, …)`);
+      }
+      selects.push(q.client.raw(expr.toSQL(alias)));
+    }
+
+    const row = await q.select(selects).first();
+    // Parse numeric strings returned by some drivers
+    const result = {};
+    for (const key of Object.keys(expressions)) {
+      result[key] = row[key] == null ? null : Number(row[key]);
+    }
+    return result;
+  }
+
+  // ─── Bulk update ──────────────────────────────────────────────────────────
+
+  /**
+   * Update many rows with different values in a single transaction.
+   *
+   *   await Post.bulkUpdate([
+   *     { id: 1, title: 'One', published: true },
+   *     { id: 2, title: 'Two', published: false },
+   *   ], 'id');
+   */
+  static async bulkUpdate(rows, keyColumn = null) {
+    const pk = keyColumn || this.primaryKey;
+    return this.transaction(async (trx) => {
+      for (const row of rows) {
+        const { [pk]: keyValue, ...data } = row;
+        if (keyValue == null) continue;
+        const now = new Date().toISOString();
+        await trx(this.table)
+          .where(pk, keyValue)
+          .update({ ...data, ...(this.timestamps ? { updated_at: now } : {}) });
+      }
+    });
+  }
+
+  // ─── only() / defer() ────────────────────────────────────────────────────
+
+  /**
+   * Select only these columns (like Django's .only()).
+   *   Post.only('id', 'title').get()
+   */
+  static only(...columns) {
+    return new QueryBuilder(this._db(), this).select(...columns);
+  }
+
+  /**
+   * Select all columns EXCEPT the given ones (like Django's .defer()).
+   *   Post.defer('body', 'metadata').get()
+   */
+  static defer(...columns) {
+    const all     = Object.keys(this.fields);
+    const exclude = new Set(columns);
+    const keep    = all.filter(c => !exclude.has(c));
+    return new QueryBuilder(this._db(), this).select(...keep.map(c => `${this.table}.${c}`));
+  }
+
+  // ─── Raw ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Execute a raw SQL query and return hydrated model instances.
+   *   Post.raw('SELECT * FROM posts WHERE YEAR(created_at) = ?', [2024])
+   */
+  static async raw(sql, bindings = []) {
+    const db   = DatabaseManager.connection(this.connection || null);
+    const rows = await db.raw(sql, bindings);
+    // knex wraps raw results differently per driver
+    const data = rows.rows ?? rows[0] ?? rows;
+    return Array.isArray(data) ? data.map(r => this._hydrate(r)) : data;
+  }
+
   // ─── Query Builder entry points ───────────────────────────────────────────
 
   static where(column, operatorOrValue, value) {
-    const qb = new QueryBuilder(this._db(), this);
-    return qb.where(column, operatorOrValue, value);
+    return new QueryBuilder(this._db(), this).where(column, operatorOrValue, value);
+  }
+
+  /** filter() — Django alias for where() */
+  static filter(column, operatorOrValue, value) {
+    return this.where(column, operatorOrValue, value);
+  }
+
+  /** exclude() — Django alias for whereNot() */
+  static exclude(column, value) {
+    return new QueryBuilder(this._db(), this).whereNot(column, value);
   }
 
   static whereIn(column, values) {
@@ -231,58 +408,104 @@ class Model {
     return new QueryBuilder(this._db(), this).select(...cols);
   }
 
-  /**
-   * Raw query builder — escape hatch.
-   */
+  static distinct(...cols) {
+    return new QueryBuilder(this._db(), this).distinct(...cols);
+  }
+
+  /** Start an eager-load chain. */
+  static with(...relations) {
+    return new QueryBuilder(this._db(), this).with(...relations);
+  }
+
+  /** Apply a named scope. */
+  static scope(name, ...args) {
+    return new QueryBuilder(this._db(), this).scope(name, ...args);
+  }
+
+  /** Annotate rows with aggregate expressions. */
+  static annotate(expressions) {
+    return new QueryBuilder(this._db(), this).annotate(expressions);
+  }
+
+  /** Return plain objects instead of model instances. */
+  static values(...columns) {
+    return new QueryBuilder(this._db(), this).values(...columns);
+  }
+
+  /** Return a flat array of a single column. */
+  static valuesList(column) {
+    return new QueryBuilder(this._db(), this).valuesList(column);
+  }
+
+  /** Include soft-deleted rows. */
+  static withTrashed() {
+    return new QueryBuilder(this._db(), this).withTrashed();
+  }
+
+  /** Return only soft-deleted rows. */
+  static onlyTrashed() {
+    return new QueryBuilder(this._db(), this).onlyTrashed();
+  }
+
   static query() {
     return new QueryBuilder(this._db(), this);
   }
 
-  /**
-   * Paginate static shorthand.
-   */
   static async paginate(page = 1, perPage = 15) {
-    const offset = (page - 1) * perPage;
-    const total  = await this.count();
-    const rows   = await this._db().limit(perPage).offset(offset);
-    return {
-      data:     rows.map(r => this._hydrate(r)),
-      total,
-      page:     Number(page),
-      perPage,
-      lastPage: Math.ceil(total / perPage),
-    };
+    return new QueryBuilder(this._db(), this).paginate(page, perPage);
   }
 
   // ─── Instance methods ─────────────────────────────────────────────────────
 
   constructor(attributes = {}) {
     Object.assign(this, attributes);
-    this._original  = { ...attributes };
-    this._isDirty   = false;
+    this._original = { ...attributes };
+
+    // Attach lazy relation loaders as callable methods
+    const relations = this.constructor.relations || {};
+    for (const [name, rel] of Object.entries(relations)) {
+      // Skip if already set by eager load
+      if (!(name in this)) {
+        this[name] = () => rel.load(this);
+      }
+
+      // Attach pivot manager for BelongsToMany
+      const BelongsToMany = require('../relations/BelongsToMany');
+      if (rel instanceof BelongsToMany) {
+        Object.assign(this[name], rel._pivotManager(this));
+      }
+    }
   }
 
   /**
-   * Persist changes to this instance back to the database.
+   * Persist changes to this instance.
+   * @param {object} data
+   * @param {object} options — { trx }
    */
-  async update(data = {}) {
+  async update(data = {}, { trx } = {}) {
+    this.constructor.validate(data);
+
     const now = new Date().toISOString();
-    const payload = {
+    let payload = {
       ...data,
       ...(this.constructor.timestamps ? { updated_at: now } : {}),
     };
 
-    await this.constructor._db()
+    payload = await this.constructor.beforeUpdate(payload) ?? payload;
+
+    const q = trx
+      ? trx(this.constructor.table)
+      : this.constructor._db();
+
+    await q
       .where(this.constructor.primaryKey, this[this.constructor.primaryKey])
       .update(payload);
 
     Object.assign(this, payload);
+    await this.constructor.afterUpdate(this);
     return this;
   }
 
-  /**
-   * Save any changes made directly to this instance's properties.
-   */
   async save() {
     const dirty = this._getDirty();
     if (!Object.keys(dirty).length) return this;
@@ -290,53 +513,95 @@ class Model {
   }
 
   /**
-   * Delete this row from the database.
+   * Delete this row.
+   * If softDeletes = true, sets deleted_at instead of removing.
    */
-  async delete() {
+  async delete({ trx } = {}) {
+    await this.constructor.beforeDelete(this);
+
+    const q = trx
+      ? trx(this.constructor.table)
+      : this.constructor._db();
+
+    if (this.constructor.softDeletes) {
+      const now = new Date().toISOString();
+      await q
+        .where(this.constructor.primaryKey, this[this.constructor.primaryKey])
+        .update({ deleted_at: now });
+      this.deleted_at = now;
+    } else {
+      await q
+        .where(this.constructor.primaryKey, this[this.constructor.primaryKey])
+        .delete();
+    }
+
+    await this.constructor.afterDelete(this);
+    return this;
+  }
+
+  /** Restore a soft-deleted row. */
+  async restore() {
+    if (!this.constructor.softDeletes) {
+      throw new Error(`${this.constructor.name} does not use soft deletes.`);
+    }
     await this.constructor._db()
       .where(this.constructor.primaryKey, this[this.constructor.primaryKey])
-      .delete();
+      .update({ deleted_at: null });
+    this.deleted_at = null;
+    return this;
+  }
+
+  /** Force-delete even if softDeletes is enabled. */
+  async forceDelete({ trx } = {}) {
+    await this.constructor.beforeDelete(this);
+    const q = trx ? trx(this.constructor.table) : this.constructor._db();
+    await q.where(this.constructor.primaryKey, this[this.constructor.primaryKey]).delete();
+    await this.constructor.afterDelete(this);
     return this;
   }
 
-  /**
-   * Reload this instance's attributes from the database.
-   */
   async refresh() {
     const fresh = await this.constructor.find(this[this.constructor.primaryKey]);
     if (fresh) Object.assign(this, fresh);
     return this;
   }
 
-  /**
-   * Return a plain object representation.
-   */
+  get isNew()       { return !this[this.constructor.primaryKey]; }
+  get isTrashed()   { return !!this.deleted_at; }
+
   toJSON() {
     const obj = {};
     for (const key of Object.keys(this)) {
-      if (!key.startsWith('_')) obj[key] = this[key];
+      if (!key.startsWith('_') && typeof this[key] !== 'function') {
+        obj[key] = this[key];
+      }
     }
     return obj;
   }
 
-  /**
-   * Check whether this instance has been persisted.
-   */
-  get isNew() {
-    return !this[this.constructor.primaryKey];
-  }
-
   // ─── Internal ─────────────────────────────────────────────────────────────
 
   static _db() {
-    const db = DatabaseManager.connection(this.connection || null);
-    return db(this.table);
+    const db    = DatabaseManager.connection(this.connection || null);
+    let   q     = db(this.table);
+
+    // Auto-exclude soft-deleted rows unless caller opts in
+    if (this.softDeletes) {
+      q = q.whereNull(`${this.table}.deleted_at`);
+    }
+
+    return q;
   }
 
   static _hydrate(row) {
     return new this(row);
   }
 
+  static async _hydrateFromTrx(id, trx) {
+    const row = await trx(this.table).where(this.primaryKey, id).first();
+    return row ? this._hydrate(row) : null;
+  }
+
   static _applyDefaults(data) {
     const result = { ...data };
     for (const [key, field] of Object.entries(this.fields)) {
@@ -360,7 +625,7 @@ class Model {
   _getDirty() {
     const dirty = {};
     for (const key of Object.keys(this)) {
-      if (!key.startsWith('_') && this[key] !== this._original[key]) {
+      if (!key.startsWith('_') && typeof this[key] !== 'function' && this[key] !== this._original[key]) {
         dirty[key] = this[key];
       }
     }