millas 0.2.12-beta-1 → 0.2.13

package/src/orm/migration/operations/registry.js

@@ -0,0 +1,131 @@
+'use strict';
+
+const { CreateModel, DeleteModel, RenameModel } = require('./models');
+const { AddField, RemoveField, AlterField, RenameField } = require('./fields');
+const { RunSQL } = require('./special');
+const { modelNameToTable, isSnakeCase } = require('../utils');
+
+/**
+ * registry.js
+ *
+ * Two responsibilities:
+ *
+ * 1. deserialise(op)
+ *    Converts a plain JSON descriptor (loaded from a migration file) back
+ *    into a live operation instance. Used by MigrationGraph.loadAll().
+ *
+ * 2. migrations proxy
+ *    The named-argument API used inside generated migration files:
+ *
+ *      const { migrations, fields } = require('millas/core/db');
+ *      static operations = [
+ *        migrations.CreateModel({ name: 'posts', fields: [...] }),
+ *        migrations.AddField({ modelName: 'posts', name: 'slug', field: fields.string() }),
+ *      ];
+ *
+ *    Each proxy method returns a PLAIN DESCRIPTOR OBJECT — no live instances,
+ *    no side-effects at require() time. MigrationGraph feeds these through
+ *    deserialise() when it needs live operation objects.
+ *
+ *    _tableFromName() handles the legacy PascalCase → snake_case conversion
+ *    for any hand-written migrations that used model names instead of table names.
+ */
+
+// ─── Deserialise ──────────────────────────────────────────────────────────────
+
+/**
+ * Convert a plain operation descriptor into a live operation instance.
+ *
+ * @param {object} op — plain descriptor with a `type` field
+ * @returns {BaseOperation}
+ * @throws {Error} if op.type is unrecognised
+ */
+function deserialise(op) {
+  switch (op.type) {
+    case 'CreateModel':  return new CreateModel(op.table, op.fields);
+    case 'DeleteModel':  return new DeleteModel(op.table, op.fields);
+    case 'RenameModel':  return new RenameModel(op.oldTable, op.newTable);
+    case 'AddField':     return new AddField(op.table, op.column, op.field, op.oneOffDefault);
+    case 'RemoveField':  return new RemoveField(op.table, op.column, op.field);
+    case 'AlterField':   return new AlterField(op.table, op.column, op.field, op.previousField);
+    case 'RenameField':  return new RenameField(op.table, op.oldColumn, op.newColumn);
+    case 'RunSQL':       return new RunSQL(op.sql, op.reverseSql);
+    default:
+      throw new Error(`Unknown migration operation type: "${op.type}"`);
+  }
+}
+
+// ─── migrations proxy ─────────────────────────────────────────────────────────
+
+/**
+ * Named-argument API used in generated migration files.
+ * Returns plain descriptor objects — zero side-effects at require() time.
+ */
+const migrations = {
+
+  CreateModel({ name, fields: fieldList = [] }) {
+    const fields = {};
+    for (const [col, def] of fieldList) fields[col] = def;
+    return { type: 'CreateModel', table: _tableFromName(name), fields };
+  },
+
+  DeleteModel({ name, fields: fieldList = [] }) {
+    const fields = {};
+    for (const [col, def] of (fieldList || [])) fields[col] = def;
+    return { type: 'DeleteModel', table: _tableFromName(name), fields };
+  },
+
+  RenameModel({ oldName, newName }) {
+    return {
+      type:     'RenameModel',
+      oldTable: _tableFromName(oldName),
+      newTable: _tableFromName(newName),
+    };
+  },
+
+  AddField({ modelName, name, field, oneOffDefault }) {
+    const d = { type: 'AddField', table: modelName, column: name, field };
+    if (oneOffDefault !== undefined) d.oneOffDefault = oneOffDefault;
+    return d;
+  },
+
+  RemoveField({ modelName, name, field }) {
+    return { type: 'RemoveField', table: modelName, column: name, field };
+  },
+
+  AlterField({ modelName, name, field, previousField }) {
+    return { type: 'AlterField', table: modelName, column: name, field, previousField };
+  },
+
+  RenameField({ modelName, oldName, newName }) {
+    return { type: 'RenameField', table: modelName, oldColumn: oldName, newColumn: newName };
+  },
+
+  RunSQL({ sql, reverseSql = null }) {
+    return { type: 'RunSQL', sql, reverseSql };
+  },
+
+};
+
+// ─── _tableFromName ───────────────────────────────────────────────────────────
+
+/**
+ * Resolve a migration file `name:` field to a table name.
+ *
+ * MigrationWriter now writes the actual table name directly
+ * (e.g. name: 'landlord_verification') so this is an identity function
+ * for all newly generated migrations.
+ *
+ * Kept for backward compatibility with hand-written migrations that used
+ * PascalCase model names (e.g. name: 'Post') — those get converted to
+ * snake_case plural table names.
+ *
+ * @param {string} name
+ * @returns {string} table name
+ */
+function _tableFromName(name) {
+  // Already snake_case → return as-is. PascalCase → convert via utils.
+  return isSnakeCase(name) ? name : modelNameToTable(name);
+}
+
+module.exports = { deserialise, migrations, _tableFromName };

package/src/orm/migration/operations/special.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const { BaseOperation } = require('./base');
+
+/**
+ * special.js
+ *
+ * Escape-hatch operations that don't fit the structured field/model pattern:
+ *   RunSQL — execute arbitrary SQL (forward and optionally reverse)
+ *
+ * applyState() is a no-op for RunSQL — the migration system cannot know
+ * what arbitrary SQL does to the schema, so ProjectState is not mutated.
+ * This means RunSQL migrations are opaque to makemigrations diffing.
+ */
+
+// ─── RunSQL ───────────────────────────────────────────────────────────────────
+
+class RunSQL extends BaseOperation {
+  /**
+   * @param {string}      sql         — SQL to run on migrate
+   * @param {string|null} reverseSql  — SQL to run on rollback (optional)
+   */
+  constructor(sql, reverseSql = null) {
+    super();
+    this.type       = 'RunSQL';
+    this.sql        = sql;
+    this.reverseSql = reverseSql;
+  }
+
+  // Opaque — RunSQL does not mutate ProjectState.
+  // makemigrations cannot infer schema changes from raw SQL.
+  applyState(/* _state */) {}
+
+  async up(db) {
+    await db.raw(this.sql);
+  }
+
+  async down(db) {
+    if (this.reverseSql) await db.raw(this.reverseSql);
+  }
+
+  toJSON() {
+    return {
+      type:       'RunSQL',
+      sql:        this.sql,
+      reverseSql: this.reverseSql,
+    };
+  }
+}
+
+module.exports = { RunSQL };

package/src/orm/migration/utils.js

@@ -0,0 +1,208 @@
+'use strict';
+
+const fs   = require('fs-extra');
+const path = require('path');
+
+/**
+ * utils.js — shared utilities for the migration system
+ *
+ * Every function here was previously duplicated across two or more files.
+ * Single source of truth — import from here, never re-implement.
+ *
+ * Exports:
+ *   walkJs(dir)                    — recursively collect .js files
+ *   extractClasses(exported)       — pull class candidates from a module export
+ *   isMillasModel(cls)             — true if cls looks like a Millas Model
+ *   resolveTable(cls)              — table name for a Model class (convention or explicit)
+ *   modelNameToTable(name)         — PascalCase model name → snake_case plural table
+ *   tableFromClass(cls)            — walk prototype chain to find nearest static table
+ *   isSnakeCase(str)               — true if string is already snake_case
+ *   fieldsEqual(a, b)              — schema-key equality, ignores internal FK flags
+ */
+
+// ─── File system ──────────────────────────────────────────────────────────────
+
+/**
+ * Recursively collect all .js files under a directory.
+ * Skips dotfiles and index.js at any depth.
+ *
+ * @param {string} dir
+ * @returns {string[]} absolute paths
+ */
+function walkJs(dir) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkJs(fullPath));
+    } else if (entry.name.endsWith('.js') && entry.name !== 'index.js') {
+      results.push(fullPath);
+    }
+  }
+
+  return results;
+}
+
+// ─── Model class detection ────────────────────────────────────────────────────
+
+/**
+ * Given a module export (class, object, or anything), return every
+ * function/class value that could be a Model subclass.
+ *
+ * Handles:
+ *   module.exports = MyModel              → [MyModel]
+ *   module.exports = { User, Post }       → [User, Post]
+ *
+ * @param {*} exported
+ * @returns {Function[]}
+ */
+function extractClasses(exported) {
+  if (!exported) return [];
+  if (typeof exported === 'function') return [exported];
+  if (typeof exported === 'object') {
+    return Object.values(exported).filter(v => typeof v === 'function');
+  }
+  return [];
+}
+
+/**
+ * A class qualifies as a Millas Model if:
+ *   - It is a function (class)
+ *   - It has a static `fields` property that is a non-null object with at least one key
+ *
+ * Intentionally avoids instanceof checks so this works regardless of which
+ * resolution path Model was loaded from (e.g. during tests or monorepo setups).
+ *
+ * @param {*} cls
+ * @returns {boolean}
+ */
+function isMillasModel(cls) {
+  if (typeof cls !== 'function') return false;
+  if (!cls.fields || typeof cls.fields !== 'object') return false;
+  return Object.keys(cls.fields).length > 0;
+}
+
+// ─── Table name resolution ────────────────────────────────────────────────────
+
+/**
+ * Resolve the table name for a Model class.
+ *
+ * Rules (in priority order):
+ *   1. Abstract class (hasOwnProperty 'abstract' === true) → null (no table)
+ *   2. Explicitly declared via static set table(v) → stored in _table
+ *   3. Explicitly declared as static string property
+ *   4. Convention — auto-generated from class name via Model._defaultTable()
+ *      (same as Laravel/Eloquent and Rails/ActiveRecord)
+ *
+ * @param {Function} cls — Model subclass
+ * @returns {string|null}
+ */
+function resolveTable(cls) {
+  if (Object.prototype.hasOwnProperty.call(cls, 'abstract') && cls.abstract) return null;
+  if (Object.prototype.hasOwnProperty.call(cls, '_table') && cls._table) return cls._table;
+  if (Object.prototype.hasOwnProperty.call(cls, 'table') && typeof cls.table === 'string' && cls.table) return cls.table;
+  const generated = typeof cls.table === 'string' ? cls.table : null;
+  return generated || null;
+}
+
+/**
+ * Walk a Model class's prototype chain to find the nearest ancestor that
+ * explicitly declares a static table property via hasOwnProperty.
+ *
+ * Correctly resolves:
+ *   Concrete model:          User.table = 'users'      → 'users'
+ *   Same-table child:        AdminUser extends User    → 'users'  (no own table)
+ *   Multi-table child:       Employee.table='employees'→ 'employees'
+ *   Abstract base:           AuthUser (abstract=true)  → null
+ *
+ * @param {Function} cls
+ * @returns {string|null}
+ */
+function tableFromClass(cls) {
+  let current = cls;
+  while (current && current !== Function.prototype) {
+    if (Object.prototype.hasOwnProperty.call(current, 'table') && current.table) {
+      return current.table;
+    }
+    current = Object.getPrototypeOf(current);
+  }
+  return null;
+}
+
+/**
+ * Convert a PascalCase model name to a snake_case plural table name.
+ *
+ * Used as a last resort when _fkModel is a string and no class reference
+ * is available. Handles irregular pluralisation:
+ *
+ *   'User'          → 'users'
+ *   'Category'      → 'categories'
+ *   'TaggedPost'    → 'tagged_posts'
+ *   'UnitCategory'  → 'unit_categories'
+ *
+ * @param {string} name — PascalCase model name
+ * @returns {string} snake_case plural table name
+ */
+function modelNameToTable(name) {
+  const snake = name
+    .replace(/([A-Z])/g, (m, c, i) => (i ? '_' : '') + c.toLowerCase())
+    .replace(/^_/, '');
+  if (snake.endsWith('y') && !/[aeiou]y$/.test(snake)) return snake.slice(0, -1) + 'ies';
+  if (/(?:s|sh|ch|x|z)$/.test(snake)) return snake + 'es';
+  return snake + 's';
+}
+
+/**
+ * Return true if the string is already a snake_case table name.
+ * Detected by: all lowercase (no uppercase letters).
+ *
+ *   'users'           → true  (table name — return as-is)
+ *   'unit_categories' → true  (table name — return as-is)
+ *   'User'            → false (PascalCase — needs conversion)
+ *   'UnitCategory'    → false (PascalCase — needs conversion)
+ *
+ * @param {string} str
+ * @returns {boolean}
+ */
+function isSnakeCase(str) {
+  return str === str.toLowerCase();
+}
+
+// ─── Field comparison ─────────────────────────────────────────────────────────
+
+/**
+ * Compare two normalised field definitions for schema equality.
+ *
+ * Only compares the 10 schema-relevant keys — ignores internal FK metadata
+ * flags (_isForeignKey, _isOneToOne, _fkOnDelete, _fkRelatedName) which are
+ * present on live-scanned fields but absent on replayed migration state.
+ * Comparing those would cause phantom AlterField diffs on every makemigrations run.
+ *
+ * @param {object} a — normalised field def
+ * @param {object} b — normalised field def
+ * @returns {boolean}
+ */
+function fieldsEqual(a, b) {
+  const SCHEMA_KEYS = [
+    'type', 'nullable', 'unique', 'default', 'max',
+    'unsigned', 'enumValues', 'references', 'precision', 'scale',
+  ];
+  for (const k of SCHEMA_KEYS) {
+    if (JSON.stringify(a[k]) !== JSON.stringify(b[k])) return false;
+  }
+  return true;
+}
+
+module.exports = {
+  walkJs,
+  extractClasses,
+  isMillasModel,
+  resolveTable,
+  tableFromClass,
+  modelNameToTable,
+  isSnakeCase,
+  fieldsEqual,
+};

package/src/orm/model/Model.js

@@ -128,9 +128,70 @@ class Model {
   static primaryKey  = 'id';
   static timestamps  = true;
   static softDeletes = false;
-  static fields      = {};
   static connection  = null;
 
+  /**
+   * Own fields declared directly on this class only.
+   * Subclasses override this with just their own additions/overrides —
+   * no need to spread parent fields manually (like Django's AbstractUser).
+   *
+   *   class User extends AuthUser {
+   *     static ownFields = {
+   *       phone: fields.string({ nullable: true }),
+   *       role:  fields.enum(['tenant', 'landlord'], { default: 'tenant' }),
+   *     };
+   *   }
+   *
+   * You can still use 'static fields = {...}' to completely replace the schema.
+   */
+  /**
+   * Merged field map — walks the prototype chain and merges fields from:
+   *   - The class itself (always)
+   *   - Any ancestor marked 'static abstract = true' (fields flow down)
+   *   - Concrete ancestors with the same table (single-table inheritance)
+   *
+   * Child fields win on collision. Result is cached per class.
+   *
+   * Usage — just declare what's new or overridden, no spread needed:
+   *
+   *   class AuthUser extends Model {
+   *     static abstract = true;
+   *     static fields = { id: fields.id(), email: fields.string() };
+   *   }
+   *   class User extends AuthUser {
+   *     static table  = 'users';
+   *     static fields = { phone: fields.string(), role: fields.enum([...]) };
+   *     // User.getFields() → id, email, phone, role  (merged)
+   *   }
+   */
+  static getFields() {
+    if (Object.prototype.hasOwnProperty.call(this, '_cachedFields')) return this._cachedFields;
+
+    const chain   = [];
+    const myTable = this.table || this.name;
+    let cur       = this;
+
+    while (cur && cur !== Function.prototype) {
+      if (Object.prototype.hasOwnProperty.call(cur, 'fields')) {
+        chain.unshift(cur.fields); // ancestor first → child wins in Object.assign
+      }
+      const curTable = cur.table || cur.name;
+      // Stop walking when we reach a non-abstract ancestor with a different table
+      // (that's a separate model with its own migration — don't merge its fields)
+      if (cur !== this && !cur.abstract && curTable !== myTable) break;
+      cur = Object.getPrototypeOf(cur);
+    }
+
+    const merged = Object.assign({}, ...chain);
+    Object.defineProperty(this, '_cachedFields', {
+      value: merged, writable: true, configurable: true, enumerable: false,
+    });
+    return merged;
+  }
+
+  /** Clear the fields cache — call if fields are modified at runtime. */
+  static _clearFieldCache() { delete this._cachedFields; }
+
   /** Define named scopes: static scopes = { published: qb => qb.where('published', true) } */
   static scopes = {};
 
@@ -340,7 +401,7 @@ class Model {
    *   Post.defer('body', 'metadata').get()
    */
   static defer(...columns) {
-    const all     = Object.keys(this.fields);
+    const all     = Object.keys(this.getFields());
     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}`));
@@ -495,7 +556,7 @@ class Model {
     // Start with explicitly declared relations
     const merged = { ...(this.relations || {}) };
 
-    for (const [fieldName, fieldDef] of Object.entries(this.fields || {})) {
+    for (const [fieldName, fieldDef] of Object.entries(this.getFields())) {
 
       // ── ForeignKey / OneToOne ────────────────────────────────────────────
       if (fieldDef._isForeignKey) {
@@ -519,11 +580,14 @@ class Model {
             return M;
           };
 
+          // Django convention: declared as 'landlord' → DB column 'landlord_id'.
+          // If already ends with _id (e.g. declared as 'landlord_id'), use as-is.
+          const colName = fieldName.endsWith('_id') ? fieldName : fieldName + '_id';
+
           if (fieldDef._isOneToOne) {
-            // OneToOne: BelongsTo on the declaring side
-            merged[accessorName] = new BelongsTo(resolveModel, fieldName.endsWith('_id') ? fieldName : fieldName + '_id', toField);
+            merged[accessorName] = new BelongsTo(resolveModel, colName, toField);
           } else {
-            merged[accessorName] = new BelongsTo(resolveModel, fieldName.endsWith('_id') ? fieldName : fieldName + '_id', toField);
+            merged[accessorName] = new BelongsTo(resolveModel, colName, toField);
           }
         }
       }
@@ -694,7 +758,7 @@ class Model {
 
   static _applyDefaults(data) {
     const result = { ...data };
-    for (const [key, field] of Object.entries(this.fields)) {
+    for (const [key, field] of Object.entries(this.getFields())) {
       if (!(key in result) && field.default !== undefined) {
         result[key] = typeof field.default === 'function'
           ? field.default()
@@ -705,11 +769,15 @@ class Model {
   }
 
   static _defaultTable() {
-    const name = this.name.toLowerCase();
-    if (name.endsWith('y') && !['ay','ey','iy','oy','uy'].some(s => name.endsWith(s)))
-      return name.slice(0, -1) + 'ies';
-    if (/(?:s|sh|ch|x|z)$/.test(name)) return name + 'es';
-    return name + 's';
+    // Convert PascalCase class name to snake_case plural table name.
+    // BlogPost → blog_posts, Category → categories, User → users.
+    const snake = this.name
+      .replace(/([A-Z])/g, (m, c, i) => (i ? '_' : '') + c.toLowerCase())
+      .replace(/^_/, '');
+    if (snake.endsWith('y') && !['ay','ey','iy','oy','uy'].some(s => snake.endsWith(s)))
+      return snake.slice(0, -1) + 'ies';
+    if (/(?:s|sh|ch|x|z)$/.test(snake)) return snake + 'es';
+    return snake + 's';
   }
 
   _getDirty() {
@@ -723,4 +791,4 @@ class Model {
   }
 }
 
-module.exports = Model;
+module.exports = Model;