millas 0.1.7 → 0.1.9

package/src/orm/relations/BelongsToMany.js

@@ -0,0 +1,188 @@
+'use strict';
+
+/**
+ * BelongsToMany
+ *
+ * Many-to-many through a pivot table.
+ *
+ *   class Post extends Model {
+ *     static relations = {
+ *       tags: new BelongsToMany(() => Tag, 'post_tag', 'post_id', 'tag_id'),
+ *     };
+ *   }
+ *
+ *   class Tag extends Model {
+ *     static relations = {
+ *       posts: new BelongsToMany(() => Post, 'post_tag', 'tag_id', 'post_id'),
+ *     };
+ *   }
+ *
+ *   const post = await Post.find(1);
+ *
+ *   // Lazy
+ *   const tags = await post.tags();
+ *
+ *   // Eager
+ *   const posts = await Post.with('tags').get();
+ *
+ *   // Attach / detach / sync
+ *   await post.tags.attach(5)
+ *   await post.tags.attach([5, 6], { approved: true })  // with pivot data
+ *   await post.tags.detach(5)
+ *   await post.tags.detach()         // detach all
+ *   await post.tags.sync([1, 2, 3])  // replace pivot rows
+ *   await post.tags.toggle([1, 2])
+ */
+class BelongsToMany {
+  /**
+   * @param {Function} relatedFn      — () => RelatedModelClass
+   * @param {string}   pivotTable     — name of the join table
+   * @param {string}   foreignPivotKey — pivot column pointing to this model
+   * @param {string}   relatedPivotKey — pivot column pointing to the related model
+   * @param {string}   localKey        — PK on this model (default: 'id')
+   * @param {string}   relatedKey      — PK on related model (default: 'id')
+   */
+  constructor(relatedFn, pivotTable, foreignPivotKey, relatedPivotKey, localKey = 'id', relatedKey = 'id') {
+    this._relatedFn       = relatedFn;
+    this._pivotTable      = pivotTable;
+    this._foreignPivotKey = foreignPivotKey;
+    this._relatedPivotKey = relatedPivotKey;
+    this._localKey        = localKey;
+    this._relatedKey      = relatedKey;
+  }
+
+  get _related() { return this._relatedFn(); }
+
+  // ─── Lazy load ────────────────────────────────────────────────────────────
+
+  async load(ownerInstance) {
+    const db  = this._related._db;
+    const key = ownerInstance[this._localKey];
+
+    const rows = await this._related._db()
+      .join(
+        this._pivotTable,
+        `${this._related.table}.${this._relatedKey}`,
+        '=',
+        `${this._pivotTable}.${this._relatedPivotKey}`,
+      )
+      .where(`${this._pivotTable}.${this._foreignPivotKey}`, key)
+      .select(`${this._related.table}.*`);
+
+    return rows.map(r => this._related._hydrate(r));
+  }
+
+  // ─── Eager load ───────────────────────────────────────────────────────────
+
+  async eagerLoad(instances, relationName, constraint) {
+    const keys = [...new Set(instances.map(i => i[this._localKey]).filter(v => v != null))];
+    if (!keys.length) {
+      for (const i of instances) i[relationName] = [];
+      return;
+    }
+
+    let q = this._related._db()
+      .join(
+        this._pivotTable,
+        `${this._related.table}.${this._relatedKey}`,
+        '=',
+        `${this._pivotTable}.${this._relatedPivotKey}`,
+      )
+      .whereIn(`${this._pivotTable}.${this._foreignPivotKey}`, keys)
+      .select(
+        `${this._related.table}.*`,
+        `${this._pivotTable}.${this._foreignPivotKey} as _pivot_owner_id`,
+      );
+
+    if (constraint) {
+      const QueryBuilder = require('../query/QueryBuilder');
+      const qb = new QueryBuilder(q, this._related);
+      constraint(qb);
+      q = qb._query;
+    }
+
+    const rows    = await q;
+    const related = rows.map(r => {
+      const instance = this._related._hydrate(r);
+      instance._pivotOwnerId = r._pivot_owner_id;
+      return instance;
+    });
+
+    const map = new Map();
+    for (const r of related) {
+      const ownerId = r._pivotOwnerId;
+      if (!map.has(ownerId)) map.set(ownerId, []);
+      map.get(ownerId).push(r);
+    }
+
+    for (const instance of instances) {
+      instance[relationName] = map.get(instance[this._localKey]) ?? [];
+    }
+  }
+
+  // ─── Pivot management (returned as methods on the instance proxy) ─────────
+
+  /**
+   * Build pivot manager bound to a specific owner instance.
+   * Called internally — results attached as instance[relationName].
+   */
+  _pivotManager(ownerInstance) {
+    const self = this;
+    const db   = () => ownerInstance.constructor._db().client; // knex instance
+
+    // We need raw knex for pivot table operations
+    const knex = () => {
+      const DatabaseManager = require('../drivers/DatabaseManager');
+      return DatabaseManager.connection();
+    };
+
+    return {
+      /** Attach related IDs to the pivot table */
+      async attach(ids, pivotData = {}) {
+        const ownerId  = ownerInstance[self._localKey];
+        const idArray  = Array.isArray(ids) ? ids : [ids];
+        const rows     = idArray.map(id => ({
+          [self._foreignPivotKey]: ownerId,
+          [self._relatedPivotKey]: id,
+          ...pivotData,
+        }));
+        await knex()(self._pivotTable).insert(rows).onConflict().ignore();
+      },
+
+      /** Remove related IDs from the pivot table */
+      async detach(ids) {
+        const ownerId = ownerInstance[self._localKey];
+        let q = knex()(self._pivotTable).where(self._foreignPivotKey, ownerId);
+        if (ids != null) {
+          const idArray = Array.isArray(ids) ? ids : [ids];
+          q = q.whereIn(self._relatedPivotKey, idArray);
+        }
+        await q.delete();
+      },
+
+      /** Replace all pivot rows with the given set of IDs */
+      async sync(ids, pivotData = {}) {
+        await this.detach();
+        if (ids.length) await this.attach(ids, pivotData);
+      },
+
+      /** Toggle IDs — attach if not present, detach if present */
+      async toggle(ids) {
+        const ownerId  = ownerInstance[self._localKey];
+        const idArray  = Array.isArray(ids) ? ids : [ids];
+        const existing = await knex()(self._pivotTable)
+          .where(self._foreignPivotKey, ownerId)
+          .whereIn(self._relatedPivotKey, idArray)
+          .pluck(self._relatedPivotKey);
+
+        const toAttach = idArray.filter(id => !existing.includes(id));
+        const toDetach = existing;
+
+        if (toAttach.length) await this.attach(toAttach);
+        if (toDetach.length) await this.detach(toDetach);
+      },
+    };
+  }
+}
+
+module.exports = BelongsToMany;

package/src/orm/relations/HasMany.js

@@ -0,0 +1,72 @@
+'use strict';
+
+/**
+ * HasMany
+ *
+ * One-to-many: the foreign key lives on the related table.
+ *
+ *   class User extends Model {
+ *     static relations = {
+ *       posts: new HasMany(() => Post, 'user_id'),
+ *     };
+ *   }
+ *
+ *   const user  = await User.find(1);
+ *   const posts = await user.posts();                     // lazy
+ *   const users = await User.with('posts').get();         // eager
+ *   const users = await User.with({                       // eager + constrained
+ *     posts: q => q.where('published', true).latest()
+ *   }).get();
+ */
+class HasMany {
+  constructor(relatedFn, foreignKey, localKey = 'id') {
+    this._relatedFn  = relatedFn;
+    this._foreignKey = foreignKey;
+    this._localKey   = localKey;
+  }
+
+  get _related() { return this._relatedFn(); }
+
+  // ─── Lazy load ────────────────────────────────────────────────────────────
+
+  async load(ownerInstance) {
+    const key  = ownerInstance[this._localKey];
+    const rows = await this._related._db().where(this._foreignKey, key);
+    return rows.map(r => this._related._hydrate(r));
+  }
+
+  // ─── Eager load ───────────────────────────────────────────────────────────
+
+  async eagerLoad(instances, relationName, constraint) {
+    const keys = [...new Set(instances.map(i => i[this._localKey]).filter(v => v != null))];
+    if (!keys.length) {
+      for (const i of instances) i[relationName] = [];
+      return;
+    }
+
+    let q = this._related._db().whereIn(this._foreignKey, keys);
+    if (constraint) {
+      const QueryBuilder = require('../query/QueryBuilder');
+      const qb = new QueryBuilder(q, this._related);
+      constraint(qb);
+      q = qb._query;
+    }
+
+    const rows    = await q;
+    const related = rows.map(r => this._related._hydrate(r));
+
+    // Group by foreign key
+    const map = new Map();
+    for (const r of related) {
+      const fkVal = r[this._foreignKey];
+      if (!map.has(fkVal)) map.set(fkVal, []);
+      map.get(fkVal).push(r);
+    }
+
+    for (const instance of instances) {
+      instance[relationName] = map.get(instance[this._localKey]) ?? [];
+    }
+  }
+}
+
+module.exports = HasMany;

package/src/orm/relations/HasOne.js

@@ -0,0 +1,67 @@
+'use strict';
+
+/**
+ * HasOne
+ *
+ * Represents a one-to-one relation where the foreign key lives on the
+ * related model's table.
+ *
+ *   class User extends Model {
+ *     static relations = {
+ *       profile: new HasOne(() => Profile, 'user_id'),
+ *     };
+ *   }
+ *
+ *   const user = await User.find(1);
+ *   const profile = await user.profile();        // single instance or null
+ *   const users   = await User.with('profile').get();  // eager loaded
+ */
+class HasOne {
+  /**
+   * @param {Function} relatedFn   — () => RelatedModelClass  (thunk avoids circular requires)
+   * @param {string}   foreignKey  — column on the related table pointing back here
+   * @param {string}   localKey    — column on this table (default: 'id')
+   */
+  constructor(relatedFn, foreignKey, localKey = 'id') {
+    this._relatedFn   = relatedFn;
+    this._foreignKey  = foreignKey;
+    this._localKey    = localKey;
+  }
+
+  get _related() { return this._relatedFn(); }
+
+  // ─── Lazy load (instance method) ─────────────────────────────────────────
+
+  async load(ownerInstance) {
+    const key = ownerInstance[this._localKey];
+    const row = await this._related._db()
+      .where(this._foreignKey, key)
+      .first();
+    return row ? this._related._hydrate(row) : null;
+  }
+
+  // ─── Eager load ───────────────────────────────────────────────────────────
+
+  async eagerLoad(instances, relationName, constraint) {
+    const keys = [...new Set(instances.map(i => i[this._localKey]).filter(v => v != null))];
+    if (!keys.length) return;
+
+    let q = this._related._db().whereIn(this._foreignKey, keys);
+    if (constraint) {
+      const QueryBuilder = require('../query/QueryBuilder');
+      const qb = new QueryBuilder(q, this._related);
+      constraint(qb);
+      q = qb._query;
+    }
+
+    const rows    = await q;
+    const related = rows.map(r => this._related._hydrate(r));
+    const map     = new Map(related.map(r => [r[this._foreignKey], r]));
+
+    for (const instance of instances) {
+      instance[relationName] = map.get(instance[this._localKey]) ?? null;
+    }
+  }
+}
+
+module.exports = HasOne;

package/src/orm/relations/index.js

@@ -0,0 +1,8 @@
+'use strict';
+
+const HasOne        = require('./HasOne');
+const HasMany       = require('./HasMany');
+const BelongsTo     = require('./BelongsTo');
+const BelongsToMany = require('./BelongsToMany');
+
+module.exports = { HasOne, HasMany, BelongsTo, BelongsToMany };

package/src/scaffold/maker.js

@@ -105,23 +105,58 @@ async function makeModel(name, options = {}) {
 
   const content = `'use strict';
 
-const { Model, fields } = require('millas');
+const { Model, fields, HasMany, HasOne, BelongsTo, BelongsToMany } = require('millas');
 
 /**
  * ${className} Model
  *
- * Represents the "${tableName}" table.
- * Run: millas makemigrations  — to generate the migration.
- * Run: millas migrate         — to apply it.
+ * Table: ${tableName}
+ *
+ * Edit this file, then run:
+ *   millas makemigrations   — generates migration files from your changes
+ *   millas migrate          — applies them to the database
  */
 class ${className} extends Model {
   static table = '${tableName}';
 
+  // ── Fields ──────────────────────────────────────────────────────
   static fields = {
     id:         fields.id(),
     created_at: fields.timestamp(),
     updated_at: fields.timestamp(),
+    // deleted_at: fields.timestamp({ nullable: true }),  // uncomment + set softDeletes = true
   };
+
+  // ── Soft deletes ─────────────────────────────────────────────────
+  // static softDeletes = true;
+
+  // ── Relations ─────────────────────────────────────────────────────
+  // static relations = {
+  //   posts:   new HasMany(() => require('./Post'), 'user_id'),
+  //   profile: new HasOne(() => require('./Profile'), 'user_id'),
+  //   role:    new BelongsTo(() => require('./Role'), 'role_id'),
+  //   tags:    new BelongsToMany(() => require('./Tag'), '${tableName.replace(/s$/, '')}_tag', '${tableName.replace(/s$/, '')}_id', 'tag_id'),
+  // };
+
+  // ── Scopes ───────────────────────────────────────────────────────
+  // static scopes = {
+  //   active:  qb => qb.where('active', true),
+  //   recent:  qb => qb.latest().limit(10),
+  //   byUser: (qb, userId) => qb.where('user_id', userId),
+  // };
+
+  // ── Validation ───────────────────────────────────────────────────
+  // static validate(data) {
+  //   if (!data.name) throw new Error('name is required');
+  // }
+
+  // ── Lifecycle hooks ──────────────────────────────────────────────
+  // 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) {}
 }
 
 module.exports = ${className};

package/src/scaffold/templates.js

@@ -66,6 +66,8 @@ storage/logs/*.log
 storage/uploads/*
 !storage/uploads/.gitkeep
 database/database.sqlite
+# Millas migration snapshot — auto-generated, do not commit
+.millas/
 `,
 
     // ─── millas.config.js ─────────────────────────────────────────
@@ -356,17 +358,37 @@ millas make:controller UserController
 
 # Generate a model
 millas make:model User
+\`\`\`
+
+## Database Migrations (Django-style)
+
+Millas handles migrations automatically — you only edit your model files.
+
+\`\`\`bash
+# 1. Edit app/models/User.js — add, remove, or change fields
+# 2. Generate migration files from your changes
+millas makemigrations
 
-# Run migrations
+# 3. Apply pending migrations to the database
 millas migrate
 \`\`\`
 
+Other migration commands:
+
+\`\`\`bash
+millas migrate:status     # Show which migrations have run
+millas migrate:rollback   # Undo the last batch
+millas migrate:fresh      # Drop everything and re-run all migrations
+millas migrate:reset      # Roll back all migrations
+millas migrate:refresh    # Reset + re-run (like fresh but using down() methods)
+\`\`\`
+
 ## Project Structure
 
 \`\`\`
 app/
   controllers/    # HTTP controllers
-  models/         # ORM models
+  models/         # ORM models  ← only file you edit for schema changes
   services/       # Business logic
   middleware/     # HTTP middleware
   jobs/           # Background jobs
@@ -374,13 +396,14 @@ bootstrap/
   app.js          # Application entry point
 config/           # Configuration files
 database/
-  migrations/     # Database migrations
+  migrations/     # Auto-generated — do not edit by hand
   seeders/        # Database seeders
 routes/
   web.js          # Web routes
   api.js          # API routes
 storage/          # Logs, uploads
 providers/        # Service providers
+.millas/          # Migration snapshot (gitignored)
 \`\`\`
 `,
   };