millas 0.2.12-beta-1 → 0.2.13

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,
+};

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

@@ -0,0 +1,152 @@
+'use strict';
+
+const { BaseOperation }                        = require('./base');
+const { applyColumn, attachFKConstraints }     = require('./column');
+const { normaliseField }                       = require('../ProjectState');
+
+/**
+ * models.js
+ *
+ * Table-level migration operations:
+ *   CreateModel  — CREATE TABLE
+ *   DeleteModel  — DROP TABLE
+ *   RenameModel  — RENAME TABLE
+ *
+ * FK constraint strategy (CreateModel):
+ *   MigrationRunner calls upWithoutFKs() for every CreateModel in a migration
+ *   first, then calls applyFKConstraints() for each — so all tables exist
+ *   before any constraint is attached. This handles any ordering and circular
+ *   references without extra DB round-trips per column.
+ *
+ *   up() still creates with inline FKs for the single-CreateModel case
+ *   (e.g. AddField to an existing schema) where ordering is never an issue.
+ */
+
+// ─── CreateModel ──────────────────────────────────────────────────────────────
+
+class CreateModel extends BaseOperation {
+  /**
+   * @param {string} table
+   * @param {object} fields  — { columnName: normalisedFieldDef }
+   */
+  constructor(table, fields) {
+    super();
+    this.type   = 'CreateModel';
+    this.table  = table;
+    this.fields = fields;
+  }
+
+  applyState(state) {
+    state.createModel(this.table, this.fields);
+  }
+
+  // Standard up() — inline FKs. Safe when only one CreateModel in a migration.
+  async up(db) {
+    await db.schema.createTable(this.table, (t) => {
+      for (const [name, def] of Object.entries(this.fields)) {
+        applyColumn(t, name, normaliseField(def));
+      }
+    });
+  }
+
+  /**
+   * Create the table with FK columns as plain integers (no constraints).
+   * Called by MigrationRunner phase 1 when a migration has multiple CreateModel ops.
+   */
+  async upWithoutFKs(db) {
+    await db.schema.createTable(this.table, (t) => {
+      for (const [name, def] of Object.entries(this.fields)) {
+        applyColumn(t, name, { ...normaliseField(def), references: null });
+      }
+    });
+  }
+
+  /**
+   * Attach all FK constraints for this table in a single ALTER TABLE.
+   * Called by MigrationRunner phase 2, after all tables exist.
+   */
+  async applyFKConstraints(db) {
+    const normalisedFields = Object.fromEntries(
+      Object.entries(this.fields).map(([name, def]) => [name, normaliseField(def)])
+    );
+    await attachFKConstraints(db, this.table, normalisedFields);
+  }
+
+  async down(db) {
+    await db.schema.dropTableIfExists(this.table);
+  }
+
+  toJSON() {
+    return { type: 'CreateModel', table: this.table, fields: this.fields };
+  }
+}
+
+// ─── DeleteModel ──────────────────────────────────────────────────────────────
+
+class DeleteModel extends BaseOperation {
+  /**
+   * @param {string} table
+   * @param {object} fields — kept for down() reconstruction only
+   */
+  constructor(table, fields) {
+    super();
+    this.type   = 'DeleteModel';
+    this.table  = table;
+    this.fields = fields;
+  }
+
+  applyState(state) {
+    state.deleteModel(this.table);
+  }
+
+  async up(db) {
+    await db.schema.dropTableIfExists(this.table);
+  }
+
+  // Reconstruct table on rollback. FK constraints included — the table
+  // being restored was previously fully formed.
+  async down(db) {
+    await db.schema.createTable(this.table, (t) => {
+      for (const [name, def] of Object.entries(this.fields)) {
+        applyColumn(t, name, normaliseField(def));
+      }
+    });
+  }
+
+  toJSON() {
+    return { type: 'DeleteModel', table: this.table, fields: this.fields };
+  }
+}
+
+// ─── RenameModel ──────────────────────────────────────────────────────────────
+
+class RenameModel extends BaseOperation {
+  /**
+   * @param {string} oldTable
+   * @param {string} newTable
+   */
+  constructor(oldTable, newTable) {
+    super();
+    this.type     = 'RenameModel';
+    this.oldTable = oldTable;
+    this.newTable = newTable;
+  }
+
+  applyState(state) {
+    state.renameModel(this.oldTable, this.newTable);
+  }
+
+  async up(db) {
+    await db.schema.renameTable(this.oldTable, this.newTable);
+  }
+
+  async down(db) {
+    await db.schema.renameTable(this.newTable, this.oldTable);
+  }
+
+  toJSON() {
+    return { type: 'RenameModel', oldTable: this.oldTable, newTable: this.newTable };
+  }
+}
+
+module.exports = { CreateModel, DeleteModel, RenameModel };