millas 0.2.12-beta → 0.2.12-beta-2

package/src/orm/migration/SchemaBuilder.js

@@ -1,6 +1,7 @@
 'use strict';
 
-const { FieldDefinition } = require('../fields');
+const { applyColumn } = require('./operations/column');
+const { normaliseField } = require('./ProjectState');
 
 /**
  * SchemaBuilder
@@ -27,7 +28,7 @@ class SchemaBuilder {
     const fields = ModelClass.fields;
 
     await this._db.schema.createTable(table, (t) => {
-      this._applyFields(t, fields, ModelClass);
+      this._applyFields(t, fields);
     });
   }
 
@@ -87,87 +88,13 @@ class SchemaBuilder {
 
   // ─── Internal ─────────────────────────────────────────────────────────────
 
-  _applyFields(tableBuilder, fields, ModelClass) {
+  // Delegates to operations/column.js applyColumn — single source of truth
+  // for the type → knex column builder mapping.
+  _applyFields(tableBuilder, fields) {
     for (const [name, field] of Object.entries(fields)) {
-      this._applyField(tableBuilder, name, field, ModelClass);
-    }
-  }
-
-  _applyField(t, name, field) {
-    let col;
-
-    switch (field.type) {
-      case 'id':
-        t.increments(name);
-        return;
-
-      case 'string':
-        col = t.string(name, field.max || 255);
-        break;
-
-      case 'text':
-        col = t.text(name);
-        break;
-
-      case 'integer':
-        col = field.unsigned ? t.integer(name).unsigned() : t.integer(name);
-        break;
-
-      case 'bigInteger':
-        col = field.unsigned ? t.bigInteger(name).unsigned() : t.bigInteger(name);
-        break;
-
-      case 'float':
-        col = t.float(name);
-        break;
-
-      case 'decimal':
-        col = t.decimal(name, field.precision || 8, field.scale || 2);
-        break;
-
-      case 'boolean':
-        col = t.boolean(name);
-        break;
-
-      case 'json':
-        col = t.json(name);
-        break;
-
-      case 'date':
-        col = t.date(name);
-        break;
-
-      case 'timestamp':
-        col = t.timestamp(name, { useTz: false });
-        break;
-
-      case 'enum':
-        col = t.enum(name, field.enumValues || []);
-        break;
-
-      case 'uuid':
-        col = t.uuid(name);
-        break;
-
-      default:
-        col = t.string(name);
-    }
-
-    if (!col) return;
-
-    if (field.nullable)               col = col.nullable();
-    else if (field.type !== 'id')     col = col.notNullable();
-
-    if (field.unique)                 col = col.unique();
-
-    if (field.default !== undefined)  col = col.defaultTo(field.default);
-
-    if (field.references) {
-      col = col.references(field.references.column)
-                .inTable(field.references.table)
-                .onDelete('CASCADE');
+      applyColumn(tableBuilder, name, normaliseField(field));
     }
   }
 }
 
-module.exports = SchemaBuilder;
+module.exports = SchemaBuilder;

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

@@ -0,0 +1,57 @@
+'use strict';
+
+/**
+ * BaseOperation
+ *
+ * Abstract base class for all migration operations.
+ *
+ * Every operation must implement:
+ *   applyState(projectState)  — mutate the in-memory ProjectState (no DB touch)
+ *   up(db)                    — apply the change to the live database
+ *   down(db)                  — revert the change from the live database
+ *   toJSON()                  — return a plain serialisable descriptor
+ *
+ * The `type` property is set by each subclass and must match the key used
+ * in the deserialise() registry in registry.js.
+ */
+class BaseOperation {
+  /**
+   * Mutate the in-memory ProjectState.
+   * Called during migration graph replay (makemigrations) — never touches DB.
+   * @param {import('../ProjectState').ProjectState} _state
+   */
+  // eslint-disable-next-line no-unused-vars
+  applyState(_state) {
+    throw new Error(`${this.constructor.name}.applyState() not implemented`);
+  }
+
+  /**
+   * Apply this operation to the live database (forward migration).
+   * @param {import('knex').Knex} _db
+   */
+  // eslint-disable-next-line no-unused-vars
+  async up(_db) {
+    throw new Error(`${this.constructor.name}.up() not implemented`);
+  }
+
+  /**
+   * Revert this operation from the live database (rollback).
+   * @param {import('knex').Knex} _db
+   */
+  // eslint-disable-next-line no-unused-vars
+  async down(_db) {
+    throw new Error(`${this.constructor.name}.down() not implemented`);
+  }
+
+  /**
+   * Return a plain, JSON-serialisable descriptor for this operation.
+   * Used by MigrationWriter to write migration files and by MigrationGraph
+   * to reload them via deserialise().
+   * @returns {object}
+   */
+  toJSON() {
+    throw new Error(`${this.constructor.name}.toJSON() not implemented`);
+  }
+}
+
+module.exports = { BaseOperation };

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

@@ -0,0 +1,191 @@
+'use strict';
+
+/**
+ * column.js
+ *
+ * Knex column builder helpers shared across all field-level operations.
+ *
+ * Having these in one place means:
+ *   - The type → knex method mapping is never duplicated
+ *   - AlterField reuses the same logic as AddField, with `.alter()` appended
+ *   - FK constraint attachment is explicit and separated from column creation
+ *
+ * Exports:
+ *   applyColumn(t, name, def)            — add a new column to a table builder
+ *   alterColumn(t, name, def)            — modify an existing column (.alter())
+ *   attachFKConstraints(db, table, fields) — attach FK constraints via ALTER TABLE
+ *                                           after all tables in a migration exist
+ */
+
+// ─── Core column builder ──────────────────────────────────────────────────────
+
+/**
+ * Add a single column to a knex table builder.
+ *
+ * Handles all supported field types, nullability, uniqueness, defaults,
+ * and inline FK constraints (references).
+ *
+ * Pass `{ ...def, references: null }` to suppress FK constraint creation
+ * when deferring constraints to a later ALTER TABLE pass.
+ *
+ * @param {object} t     — knex table builder (from createTable / table callback)
+ * @param {string} name  — column name
+ * @param {object} def   — normalised field definition from ProjectState.normaliseField()
+ */
+function applyColumn(t, name, def) {
+  const col = _buildColumn(t, name, def);
+  if (!col) return; // 'id' handled internally by _buildColumn
+
+  _applyModifiers(col, def);
+}
+
+/**
+ * Modify an existing column in a knex alterTable builder.
+ * Identical to applyColumn but appends `.alter()` — required by knex to
+ * signal that this is a column modification, not a new column addition.
+ *
+ * Note: FK constraints are NOT altered here — use attachFKConstraints()
+ * to manage them separately. Most DBs require DROP CONSTRAINT + re-add
+ * for FK changes, which is safer to do explicitly.
+ *
+ * @param {object} t     — knex table builder (from alterTable callback)
+ * @param {string} name  — column name
+ * @param {object} def   — normalised field definition
+ */
+function alterColumn(t, name, def) {
+  const col = _buildColumn(t, name, def, { forAlter: true });
+  if (!col) return;
+
+  _applyModifiers(col, def, { skipFK: true }); // FKs not altered inline
+  col.alter();
+}
+
+/**
+ * Attach FK constraints for a set of fields on a table.
+ *
+ * Called by MigrationRunner AFTER all tables in a migration have been
+ * created — this guarantees all referenced tables exist.
+ *
+ * All FK columns for a given table are batched into a single ALTER TABLE
+ * statement, not one per column.
+ *
+ * @param {import('knex').Knex} db
+ * @param {string}  table   — table name
+ * @param {object}  fields  — { columnName: normalisedDef, ... }
+ */
+async function attachFKConstraints(db, table, fields) {
+  const fkEntries = Object.entries(fields).filter(([, def]) => def.references);
+
+  if (fkEntries.length === 0) return;
+
+  await db.schema.alterTable(table, (t) => {
+    for (const [name, def] of fkEntries) {
+      const ref = def.references;
+      t.foreign(name)
+       .references(ref.column)
+       .inTable(ref.table)
+       .onDelete(ref.onDelete || 'CASCADE');
+    }
+  });
+}
+
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Build a knex column builder for a given field type.
+ * Returns null for 'id' fields (handled by t.increments which returns void).
+ *
+ * @param {object}  t
+ * @param {string}  name
+ * @param {object}  def
+ * @param {object}  [opts]
+ * @param {boolean} [opts.forAlter] — if true, skip t.increments (can't alter PK)
+ * @returns {object|null} knex column builder
+ */
+function _buildColumn(t, name, def, opts = {}) {
+  switch (def.type) {
+    case 'id':
+      if (!opts.forAlter) t.increments(name).primary();
+      return null; // increments() doesn't return a chainable column builder
+
+    case 'string':
+      return t.string(name, def.max || 255);
+
+    case 'text':
+      return t.text(name);
+
+    case 'integer':
+      return def.unsigned
+        ? t.integer(name).unsigned()
+        : t.integer(name);
+
+    case 'bigInteger':
+      return def.unsigned
+        ? t.bigInteger(name).unsigned()
+        : t.bigInteger(name);
+
+    case 'float':
+      return t.float(name);
+
+    case 'decimal':
+      return t.decimal(name, def.precision || 8, def.scale || 2);
+
+    case 'boolean':
+      return t.boolean(name);
+
+    case 'json':
+      return t.json(name);
+
+    case 'date':
+      return t.date(name);
+
+    case 'timestamp':
+      return t.timestamp(name, { useTz: false });
+
+    case 'enum':
+      return t.enu(name, def.enumValues || []);
+
+    case 'uuid':
+      return t.uuid(name);
+
+    default:
+      return t.string(name); // safe fallback
+  }
+}
+
+/**
+ * Apply nullability, uniqueness, default, and FK constraint modifiers
+ * to an already-built knex column builder.
+ *
+ * @param {object}  col           — knex column builder
+ * @param {object}  def           — normalised field def
+ * @param {object}  [opts]
+ * @param {boolean} [opts.skipFK] — skip FK constraint (used by alterColumn)
+ */
+function _applyModifiers(col, def, opts = {}) {
+  // Nullability
+  if (def.nullable) {
+    col.nullable();
+  } else if (def.type !== 'id') {
+    col.notNullable();
+  }
+
+  // Uniqueness
+  if (def.unique) col.unique();
+
+  // Default value
+  if (def.default !== null && def.default !== undefined) {
+    col.defaultTo(def.default);
+  }
+
+  // Inline FK constraint — skipped when deferring to attachFKConstraints()
+  if (!opts.skipFK && def.references) {
+    const ref = def.references;
+    col
+      .references(ref.column)
+      .inTable(ref.table)
+      .onDelete(ref.onDelete || 'CASCADE');
+  }
+}
+
+module.exports = { applyColumn, alterColumn, attachFKConstraints };

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

@@ -0,0 +1,252 @@
+'use strict';
+
+const { BaseOperation }              = require('./base');
+const { applyColumn, alterColumn }   = require('./column');
+const { normaliseField }             = require('../ProjectState');
+const { resolveDefault }             = require('../DefaultValueParser');
+
+/**
+ * fields.js
+ *
+ * Column-level migration operations:
+ *   AddField     — add a new column (with optional safe backfill for NOT NULL)
+ *   RemoveField  — drop a column
+ *   AlterField   — modify a column definition
+ *   RenameField  — rename a column
+ *
+ * Key improvement over the old Operations.js:
+ *   AlterField no longer duplicates the type→knex switch. It delegates to
+ *   alterColumn() from column.js — one place for all column-building logic.
+ */
+
+// ─── AddField ─────────────────────────────────────────────────────────────────
+
+class AddField extends BaseOperation {
+  /**
+   * @param {string}   table
+   * @param {string}   column
+   * @param {object}   field          — FieldDefinition or normalised plain object
+   * @param {object}   [oneOffDefault] — backfill descriptor for existing rows.
+   *   NOT part of the model schema — only lives in this migration file.
+   *   Shape: { kind: 'literal', value } | { kind: 'callable', expression }
+   *   Legacy: plain primitive (backward compat)
+   */
+  constructor(table, column, field, oneOffDefault = undefined) {
+    super();
+    this.type          = 'AddField';
+    this.table         = table;
+    this.column        = column;
+    this.field         = field;
+    this.oneOffDefault = oneOffDefault;
+  }
+
+  applyState(state) {
+    state.addField(this.table, this.column, this.field);
+  }
+
+  async up(db) {
+    const def         = normaliseField(this.field);
+    const hasBackfill = this.oneOffDefault !== undefined && this.oneOffDefault !== null;
+    const needsSafe   = hasBackfill && !def.nullable && def.default === null;
+
+    if (needsSafe) {
+      await this._safeBackfill(db, def);
+    } else {
+      await db.schema.table(this.table, (t) => {
+        applyColumn(t, this.column, def);
+      });
+    }
+  }
+
+  async down(db) {
+    await db.schema.table(this.table, (t) => {
+      t.dropColumn(this.column);
+    });
+  }
+
+  toJSON() {
+    const j = {
+      type:   'AddField',
+      table:  this.table,
+      column: this.column,
+      field:  this.field,
+    };
+    if (this.oneOffDefault !== undefined) j.oneOffDefault = this.oneOffDefault;
+    return j;
+  }
+
+  // ── Private ────────────────────────────────────────────────────────────────
+
+  /**
+   * Three-step safe backfill for adding a NOT NULL column to a non-empty table.
+   *
+   * Step 1 — Add column as nullable so existing rows don't immediately
+   *           violate the NOT NULL constraint.
+   * Step 2 — Backfill existing rows with the one-off default value.
+   *           Callable defaults (uuid, timestamp) are invoked per row so
+   *           each row gets its own unique value.
+   *           Literal defaults are applied in a single bulk UPDATE.
+   * Step 3 — Tighten the column to NOT NULL now that all rows have a value.
+   */
+  async _safeBackfill(db, def) {
+    const resolved   = resolveDefault(this.oneOffDefault);
+    const isCallable = typeof resolved === 'function';
+
+    // Step 1: add as nullable
+    await db.schema.table(this.table, (t) => {
+      applyColumn(t, this.column, { ...def, nullable: true, default: null });
+    });
+
+    // Step 2: backfill
+    if (isCallable) {
+      // Callable — fetch PKs and update each row individually
+      const rows = await db(this.table).whereNull(this.column).select('id');
+      for (const row of rows) {
+        await db(this.table)
+          .where('id', row.id)
+          .update({ [this.column]: resolved() });
+      }
+    } else {
+      // Literal — single bulk UPDATE
+      await db(this.table)
+        .whereNull(this.column)
+        .update({ [this.column]: resolved });
+    }
+
+    // Step 3: tighten to NOT NULL
+    await db.schema.alterTable(this.table, (t) => {
+      alterColumn(t, this.column, { ...def, nullable: false });
+    });
+  }
+}
+
+// ─── RemoveField ──────────────────────────────────────────────────────────────
+
+class RemoveField extends BaseOperation {
+  /**
+   * @param {string} table
+   * @param {string} column
+   * @param {object} field  — kept for down() reconstruction
+   */
+  constructor(table, column, field) {
+    super();
+    this.type   = 'RemoveField';
+    this.table  = table;
+    this.column = column;
+    this.field  = field;
+  }
+
+  applyState(state) {
+    state.removeField(this.table, this.column);
+  }
+
+  async up(db) {
+    await db.schema.table(this.table, (t) => {
+      t.dropColumn(this.column);
+    });
+  }
+
+  async down(db) {
+    await db.schema.table(this.table, (t) => {
+      applyColumn(t, this.column, normaliseField(this.field));
+    });
+  }
+
+  toJSON() {
+    return {
+      type:   'RemoveField',
+      table:  this.table,
+      column: this.column,
+      field:  this.field,
+    };
+  }
+}
+
+// ─── AlterField ───────────────────────────────────────────────────────────────
+
+class AlterField extends BaseOperation {
+  /**
+   * @param {string} table
+   * @param {string} column
+   * @param {object} field         — new field definition
+   * @param {object} previousField — old field definition (for down())
+   */
+  constructor(table, column, field, previousField) {
+    super();
+    this.type          = 'AlterField';
+    this.table         = table;
+    this.column        = column;
+    this.field         = field;
+    this.previousField = previousField;
+  }
+
+  applyState(state) {
+    state.alterField(this.table, this.column, this.field);
+  }
+
+  async up(db) {
+    await db.schema.alterTable(this.table, (t) => {
+      alterColumn(t, this.column, normaliseField(this.field));
+    });
+  }
+
+  async down(db) {
+    await db.schema.alterTable(this.table, (t) => {
+      alterColumn(t, this.column, normaliseField(this.previousField));
+    });
+  }
+
+  toJSON() {
+    return {
+      type:          'AlterField',
+      table:         this.table,
+      column:        this.column,
+      field:         this.field,
+      previousField: this.previousField,
+    };
+  }
+}
+
+// ─── RenameField ──────────────────────────────────────────────────────────────
+
+class RenameField extends BaseOperation {
+  /**
+   * @param {string} table
+   * @param {string} oldColumn
+   * @param {string} newColumn
+   */
+  constructor(table, oldColumn, newColumn) {
+    super();
+    this.type      = 'RenameField';
+    this.table     = table;
+    this.oldColumn = oldColumn;
+    this.newColumn = newColumn;
+  }
+
+  applyState(state) {
+    state.renameField(this.table, this.oldColumn, this.newColumn);
+  }
+
+  async up(db) {
+    await db.schema.table(this.table, (t) => {
+      t.renameColumn(this.oldColumn, this.newColumn);
+    });
+  }
+
+  async down(db) {
+    await db.schema.table(this.table, (t) => {
+      t.renameColumn(this.newColumn, this.oldColumn);
+    });
+  }
+
+  toJSON() {
+    return {
+      type:      'RenameField',
+      table:     this.table,
+      oldColumn: this.oldColumn,
+      newColumn: this.newColumn,
+    };
+  }
+}
+
+module.exports = { AddField, RemoveField, AlterField, RenameField };

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

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * operations/index.js
+ *
+ * Public surface of the operations/ folder.
+ *
+ * Import from here for the full set:
+ *   require('./operations')
+ *
+ * Or import directly from a sub-module when you only need one concern:
+ *   require('./operations/models')   — CreateModel, DeleteModel, RenameModel
+ *   require('./operations/fields')   — AddField, RemoveField, AlterField, RenameField
+ *   require('./operations/column')   — applyColumn, alterColumn, attachFKConstraints
+ *   require('./operations/registry') — deserialise, migrations proxy
+ *   require('./operations/special')  — RunSQL
+ */
+
+const { BaseOperation }                            = require('./base');
+const { applyColumn, alterColumn,
+        attachFKConstraints }                       = require('./column');
+const { CreateModel, DeleteModel, RenameModel }    = require('./models');
+const { AddField, RemoveField,
+        AlterField, RenameField }                  = require('./fields');
+const { RunSQL }                                   = require('./special');
+const { deserialise, migrations, _tableFromName }  = require('./registry');
+
+module.exports = {
+  // Base
+  BaseOperation,
+
+  // Column helpers
+  applyColumn,
+  alterColumn,
+  attachFKConstraints,
+
+  // Table-level ops
+  CreateModel,
+  DeleteModel,
+  RenameModel,
+
+  // Field-level ops
+  AddField,
+  RemoveField,
+  AlterField,
+  RenameField,
+
+  // Escape hatch
+  RunSQL,
+
+  // Registry
+  deserialise,
+  migrations,
+  _tableFromName,
+};