@warlock.js/cascade 4.0.171 → 4.1.1

package/esm/migration/column-builder.mjs

@@ -0,0 +1,532 @@
+//#region ../../@warlock.js/cascade/src/migration/column-builder.ts
+/**
+* Fluent builder for defining column properties.
+*
+* Allows chaining modifiers like `.nullable()`, `.unique()`, `.default()`.
+* Each column builder is bound to a parent migration and accumulates
+* the column definition through method chains.
+*
+* @example
+* ```typescript
+* this.string("email")
+*   .nullable()
+*   .unique()
+*   .default("guest@example.com");
+* ```
+*
+* @example
+* ```typescript
+* this.integer("age")
+*   .unsigned()
+*   .comment("User's age in years");
+* ```
+*/
+var ColumnBuilder = class {
+	migration;
+	/** Mutable column definition being accumulated */
+	definition;
+	/** Mutable foreign key definition, set when .references() is called */
+	fkDefinition;
+	/** Temporary storage for generated expression before .stored() or .virtual() is called */
+	generatedExpression;
+	/**
+	* Create a new column builder.
+	*
+	* @param migration - Parent migration instance for index registration
+	* @param name - Column name
+	* @param type - Column data type
+	* @param options - Optional initial configuration
+	*/
+	constructor(migration, name, type, options = {}) {
+		this.migration = migration;
+		this.definition = {
+			name,
+			type,
+			nullable: false,
+			...options
+		};
+	}
+	/**
+	* Mark column as nullable (allows NULL values).
+	*
+	* @returns This builder for chaining
+	*
+	* @example
+	* ```typescript
+	* this.string("middleName").nullable();
+	* ```
+	*/
+	nullable() {
+		this.definition.nullable = true;
+		return this;
+	}
+	/**
+	* Mark column as not nullable (disallows NULL values).
+	*
+	* This is the default, but can be used for clarity.
+	*
+	* @returns This builder for chaining
+	*/
+	notNullable() {
+		this.definition.nullable = false;
+		return this;
+	}
+	/**
+	* Set default value for the column as a raw SQL expression.
+	*
+	* The value will be used as-is in the SQL statement without escaping.
+	* Use this for database functions and expressions.
+	*
+	* @param value - Default value (SQL expression, number, or boolean)
+	* @returns This builder for chaining
+	*
+	* @example
+	* ```typescript
+	* this.uuid("id").default("gen_random_uuid()");
+	* this.timestamp("created_at").default("NOW()");
+	* this.integer("version").default(1);
+	* this.boolean("is_active").default(true);
+	* ```
+	*/
+	default(value) {
+		this.definition.defaultValue = value;
+		this.definition.isRawDefault = true;
+		return this;
+	}
+	/**
+	* Set default value for the column as a literal string.
+	*
+	* The value will be properly escaped and quoted in the SQL statement.
+	* Use this for literal string values, not SQL expressions.
+	*
+	* @param value - Default string value (will be escaped)
+	* @returns This builder for chaining
+	*
+	* @example
+	* ```typescript
+	* this.text("status").defaultString("active");
+	* this.text("greeting").defaultString("Hello, World!");
+	* ```
+	*/
+	defaultString(value) {
+		this.definition.defaultValue = value;
+		this.definition.isRawDefault = false;
+		return this;
+	}
+	/**
+	* Set default value to the current timestamp.
+	*
+	* Database-agnostic. Generates NOW() / CURRENT_TIMESTAMP / GETDATE() based on driver.
+	*
+	* @returns This builder for chaining
+	*
+	* @example
+	* ```typescript
+	* this.timestamp("created_at").useCurrent();
+	* ```
+	*/
+	useCurrent() {
+		this.definition.defaultValue = { __type: "CURRENT_TIMESTAMP" };
+		return this;
+	}
+	/**
+	* Set column to update to current timestamp on row update.
+	*
+	* MySQL only. Other databases ignore this.
+	*
+	* @returns This builder for chaining
+	*
+	* @example
+	* ```typescript
+	* this.timestamp("updated_at").useCurrent().useCurrentOnUpdate();
+	* ```
+	*/
+	useCurrentOnUpdate() {
+		this.definition.onUpdateCurrent = true;
+		return this;
+	}
+	/**
+	* Add unique constraint/index on this column.
+	*
+	* Registers a pending unique index with the parent migration.
+	*
+	* @returns This builder for chaining
+	*
+	* @example
+	* ```typescript
+	* this.string("email").unique();
+	* ```
+	*/
+	unique() {
+		this.migration.addPendingIndex({
+			columns: [this.definition.name],
+			unique: true
+		});
+		return this;
+	}
+	/**
+	* Add regular index on this column.
+	*
+	* Registers a pending index with the parent migration.
+	*
+	* @returns This builder for chaining
+	*
+	* @example
+	* ```typescript
+	* this.string("email").index();
+	* ```
+	*/
+	index() {
+		this.migration.addPendingIndex({ columns: [this.definition.name] });
+		return this;
+	}
+	/**
+	* Add a vector search index on this column.
+	*
+	* Registers a pending vector index with the parent migration.
+	*
+	* @param options - Vector index options
+	* @returns This builder for chaining
+	*
+	* @example
+	* ```typescript
+	* this.vector(1536).vectorIndex({ similarity: "cosine" });
+	* ```
+	*/
+	vectorIndex(options = {}) {
+		if (this.migration.addPendingVectorIndex) this.migration.addPendingVectorIndex(this.definition.name, {
+			...options,
+			dimensions: this.definition.dimensions || 0
+		});
+		return this;
+	}
+	/**
+	* Mark as primary key.
+	*
+	* @returns This builder for chaining
+	*
+	* @example
+	* ```typescript
+	* this.integer("id").primary();
+	* ```
+	*/
+	primary() {
+		this.definition.primary = true;
+		return this;
+	}
+	/**
+	* Mark as auto-increment (numeric types only).
+	*
+	* SQL databases will use native AUTO_INCREMENT/SERIAL.
+	* NoSQL databases ignore this.
+	*
+	* @returns This builder for chaining
+	*
+	* @example
+	* ```typescript
+	* this.integer("id").primary().autoIncrement();
+	* ```
+	*/
+	autoIncrement() {
+		this.definition.autoIncrement = true;
+		return this;
+	}
+	/**
+	* Mark as unsigned (numeric types only).
+	*
+	* Disallows negative values and doubles the positive range.
+	*
+	* @returns This builder for chaining
+	*
+	* @example
+	* ```typescript
+	* this.integer("age").unsigned();
+	* ```
+	*/
+	unsigned() {
+		this.definition.unsigned = true;
+		return this;
+	}
+	/**
+	* Add comment/description to column.
+	*
+	* Stored as column metadata in the database.
+	*
+	* @param text - Comment text
+	* @returns This builder for chaining
+	*
+	* @example
+	* ```typescript
+	* this.string("sku").comment("Stock Keeping Unit code");
+	* ```
+	*/
+	comment(text) {
+		this.definition.comment = text;
+		return this;
+	}
+	/**
+	* Add a CHECK constraint scoped to this column.
+	*
+	* @param expression - SQL CHECK expression (can reference the column by name)
+	* @param name - Constraint name (defaults to `check_<column>`)
+	* @returns This builder for chaining
+	*/
+	check(expression, name) {
+		this.definition.checkConstraint = {
+			expression,
+			name: name ?? `check_${this.definition.name}`
+		};
+		return this;
+	}
+	/**
+	* Position this column after another column.
+	*
+	* MySQL/MariaDB only. Ignored by PostgreSQL and NoSQL drivers.
+	*
+	* @param columnName - Column to position after
+	* @returns This builder for chaining
+	*
+	* @example
+	* ```typescript
+	* this.string("middle_name").after("first_name");
+	* ```
+	*/
+	after(columnName) {
+		this.definition.after = columnName;
+		return this;
+	}
+	/**
+	* Position this column as the first column in the table.
+	*
+	* MySQL/MariaDB only. Ignored by PostgreSQL and NoSQL drivers.
+	*
+	* @returns This builder for chaining
+	*
+	* @example
+	* ```typescript
+	* this.integer("id").primary().first();
+	* ```
+	*/
+	first() {
+		this.definition.first = true;
+		return this;
+	}
+	/**
+	* Declare a foreign key constraint on this column.
+	*
+	* Accepts either a raw table-name string or a Model class (anything with a
+	* static `table` property). Using a Model class is preferred — it is
+	* type-safe and automatically tracks table renames.
+	*
+	* Pushes an `addForeignKey` operation immediately using a mutable reference —
+	* subsequent `.on()`, `.onDelete()`, `.onUpdate()` calls mutate the same
+	* definition that is already queued, so no `.add()` terminator is needed.
+	*
+	* Referenced column defaults to `"id"` — use `.on()` to override.
+	*
+	* @param tableOrModel - Referenced table name OR a Model class with a static `table` property
+	* @returns This builder for chaining
+	*
+	* @example
+	* ```typescript
+	* // Preferred — model class reference (type-safe, rename-proof)
+	* this.uuid("organization_id").references(Organization).onDelete("cascade");
+	*
+	* // Also supported — raw table string
+	* this.uuid("organization_id").references("organizations").onDelete("cascade");
+	* this.uuid("organization_id").references(Organization.table).onDelete("cascade");
+	* ```
+	*/
+	references(tableOrModel) {
+		const tableName = typeof tableOrModel === "string" ? tableOrModel : tableOrModel.table;
+		this.fkDefinition = {
+			column: this.definition.name,
+			referencesTable: tableName,
+			referencesColumn: "id",
+			onDelete: "restrict",
+			onUpdate: "restrict"
+		};
+		this.migration.addForeignKeyOperation(this.fkDefinition);
+		return this;
+	}
+	/**
+	* Set the referenced column for the foreign key.
+	*
+	* Only meaningful after `.references()`. Defaults to `"id"` if omitted.
+	*
+	* @param column - Referenced column name
+	* @returns This builder for chaining
+	*
+	* @example
+	* ```typescript
+	* this.integer("user_id").references("users").on("custom_id");
+	* ```
+	*/
+	on(column) {
+		if (this.fkDefinition) this.fkDefinition.referencesColumn = column;
+		return this;
+	}
+	/**
+	* Set the ON DELETE action for the foreign key.
+	*
+	* Only meaningful after `.references()`.
+	*
+	* @param action - Action when the referenced row is deleted
+	* @returns This builder for chaining
+	*
+	* @example
+	* ```typescript
+	* this.integer("user_id").references("users").onDelete("cascade");
+	* ```
+	*/
+	onDelete(action) {
+		if (this.fkDefinition) this.fkDefinition.onDelete = action;
+		return this;
+	}
+	/**
+	* Set the ON UPDATE action for the foreign key.
+	*
+	* Only meaningful after `.references()`.
+	*
+	* @param action - Action when the referenced row's key is updated
+	* @returns This builder for chaining
+	*
+	* @example
+	* ```typescript
+	* this.integer("user_id").references("users").onUpdate("cascade");
+	* ```
+	*/
+	onUpdate(action) {
+		if (this.fkDefinition) this.fkDefinition.onUpdate = action;
+		return this;
+	}
+	/**
+	* Shorthand for `.onDelete("cascade").onUpdate("cascade")`.
+	*
+	* Only meaningful after `.references()`.
+	*
+	* @returns This builder for chaining
+	*
+	* @example
+	* ```typescript
+	* this.integer("user_id").references("users").cascadeAll();
+	* ```
+	*/
+	cascadeAll() {
+		if (this.fkDefinition) {
+			this.fkDefinition.onDelete = "cascade";
+			this.fkDefinition.onUpdate = "cascade";
+		}
+		return this;
+	}
+	/**
+	* Mark this column definition as a modification of an existing column.
+	*
+	* Pushes a `modifyColumn` operation instead of `addColumn`.
+	* This method breaks the builder chain and returns the parent migration.
+	*
+	* @returns The parent migration instance (breaks builder chain)
+	*
+	* @example
+	* ```typescript
+	* // Make email nullable
+	* this.string("email").nullable().change();
+	*
+	* // Increase length
+	* this.string("name", 255).change();
+	*
+	* // Change type
+	* this.text("description").change();
+	* ```
+	*/
+	change() {
+		const operations = this.migration.pendingOperations;
+		const lastOp = operations[operations.length - 1];
+		if (lastOp?.type === "addColumn" && lastOp.payload === this.definition) operations.pop();
+		let pendingFkOp;
+		if (this.fkDefinition) {
+			const tail = operations[operations.length - 1];
+			if (tail?.type === "addForeignKey" && tail.payload === this.fkDefinition) pendingFkOp = operations.pop();
+		}
+		operations.push({
+			type: "modifyColumn",
+			payload: this.definition
+		});
+		if (pendingFkOp) operations.push(pendingFkOp);
+		return this.migration;
+	}
+	/**
+	* @alias change
+	*/
+	modify() {
+		return this.change();
+	}
+	/**
+	* Mark this column as a generated column with the given SQL expression.
+	*
+	* Must be followed by `.stored()` or `.virtual()` to specify storage type.
+	*
+	* PostgreSQL: GENERATED ALWAYS AS (...) STORED
+	* MySQL: GENERATED ALWAYS AS (...) STORED | VIRTUAL
+	*
+	* @param expression - SQL expression to compute the value
+	* @returns This builder for chaining
+	*
+	* @example
+	* ```typescript
+	* this.string("full_name")
+	*   .generatedAs("CONCAT(first_name, ' ', last_name)")
+	*   .stored();
+	*
+	* this.decimal("price_with_tax")
+	*   .generatedAs("price * 1.2")
+	*   .virtual();
+	* ```
+	*/
+	generatedAs(expression) {
+		this.generatedExpression = expression;
+		return this;
+	}
+	/**
+	* Mark the generated column as stored (computed and persisted to disk).
+	*
+	* Must be called after `.generatedAs()`.
+	*
+	* @returns This builder for chaining
+	*/
+	stored() {
+		if (this.generatedExpression) this.definition.generated = {
+			expression: this.generatedExpression,
+			stored: true
+		};
+		return this;
+	}
+	/**
+	* Mark the generated column as virtual (computed on read, not stored).
+	*
+	* Must be called after `.generatedAs()`. Not supported by PostgreSQL.
+	*
+	* @returns This builder for chaining
+	*/
+	virtual() {
+		if (this.generatedExpression) this.definition.generated = {
+			expression: this.generatedExpression,
+			stored: false
+		};
+		return this;
+	}
+	/**
+	* Get the built column definition.
+	*
+	* Called internally by the Migration class to extract the final definition.
+	*
+	* @returns The accumulated column definition
+	*/
+	getDefinition() {
+		return this.definition;
+	}
+};
+
+//#endregion
+export { ColumnBuilder };
+//# sourceMappingURL=column-builder.mjs.map

package/esm/migration/column-builder.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-builder.mjs","names":[],"sources":["../../../../../../@warlock.js/cascade/src/migration/column-builder.ts"],"sourcesContent":["import type {\n  ColumnDefinition,\n  ColumnType,\n  ForeignKeyDefinition,\n  VectorIndexOptions,\n} from \"../contracts/migration-driver.contract\";\n\n/**\n * Reference to the Migration type to avoid circular imports.\n * The actual type is injected at runtime.\n */\ntype MigrationLike = {\n  addPendingIndex(index: { columns: string[]; unique?: boolean }): void;\n  addForeignKeyOperation(fk: ForeignKeyDefinition): void;\n  addPendingVectorIndex?(column: string, options: Omit<VectorIndexOptions, \"column\">): void;\n};\n\n/**\n * Mutable foreign key definition being built via ColumnBuilder.\n */\ninterface MutableForeignKeyDefinition {\n  name?: string;\n  column: string;\n  referencesTable: string;\n  referencesColumn: string;\n  onDelete: ForeignKeyDefinition[\"onDelete\"];\n  onUpdate: ForeignKeyDefinition[\"onUpdate\"];\n}\n\n/**\n * Fluent builder for defining column properties.\n *\n * Allows chaining modifiers like `.nullable()`, `.unique()`, `.default()`.\n * Each column builder is bound to a parent migration and accumulates\n * the column definition through method chains.\n *\n * @example\n * ```typescript\n * this.string(\"email\")\n *   .nullable()\n *   .unique()\n *   .default(\"guest@example.com\");\n * ```\n *\n * @example\n * ```typescript\n * this.integer(\"age\")\n *   .unsigned()\n *   .comment(\"User's age in years\");\n * ```\n */\nexport class ColumnBuilder {\n  /** Mutable column definition being accumulated */\n  private readonly definition: ColumnDefinition;\n\n  /** Mutable foreign key definition, set when .references() is called */\n  private fkDefinition?: MutableForeignKeyDefinition;\n\n  /** Temporary storage for generated expression before .stored() or .virtual() is called */\n  private generatedExpression?: string;\n\n  /**\n   * Create a new column builder.\n   *\n   * @param migration - Parent migration instance for index registration\n   * @param name - Column name\n   * @param type - Column data type\n   * @param options - Optional initial configuration\n   */\n  public constructor(\n    private readonly migration: MigrationLike,\n    name: string,\n    type: ColumnType,\n    options: Partial<\n      Pick<ColumnDefinition, \"length\" | \"precision\" | \"scale\" | \"dimensions\" | \"values\">\n    > = {},\n  ) {\n    this.definition = {\n      name,\n      type,\n      nullable: false,\n      ...options,\n    };\n  }\n\n  // ============================================================================\n  // NULLABILITY\n  // ============================================================================\n\n  /**\n   * Mark column as nullable (allows NULL values).\n   *\n   * @returns This builder for chaining\n   *\n   * @example\n   * ```typescript\n   * this.string(\"middleName\").nullable();\n   * ```\n   */\n  public nullable(): this {\n    this.definition.nullable = true;\n    return this;\n  }\n\n  /**\n   * Mark column as not nullable (disallows NULL values).\n   *\n   * This is the default, but can be used for clarity.\n   *\n   * @returns This builder for chaining\n   */\n  public notNullable(): this {\n    this.definition.nullable = false;\n    return this;\n  }\n\n  // ============================================================================\n  // DEFAULT VALUES\n  // ============================================================================\n\n  /**\n   * Set default value for the column as a raw SQL expression.\n   *\n   * The value will be used as-is in the SQL statement without escaping.\n   * Use this for database functions and expressions.\n   *\n   * @param value - Default value (SQL expression, number, or boolean)\n   * @returns This builder for chaining\n   *\n   * @example\n   * ```typescript\n   * this.uuid(\"id\").default(\"gen_random_uuid()\");\n   * this.timestamp(\"created_at\").default(\"NOW()\");\n   * this.integer(\"version\").default(1);\n   * this.boolean(\"is_active\").default(true);\n   * ```\n   */\n  public default(value: string | number | boolean): this {\n    this.definition.defaultValue = value;\n    this.definition.isRawDefault = true;\n    return this;\n  }\n\n  /**\n   * Set default value for the column as a literal string.\n   *\n   * The value will be properly escaped and quoted in the SQL statement.\n   * Use this for literal string values, not SQL expressions.\n   *\n   * @param value - Default string value (will be escaped)\n   * @returns This builder for chaining\n   *\n   * @example\n   * ```typescript\n   * this.text(\"status\").defaultString(\"active\");\n   * this.text(\"greeting\").defaultString(\"Hello, World!\");\n   * ```\n   */\n  public defaultString(value: string): this {\n    this.definition.defaultValue = value;\n    this.definition.isRawDefault = false;\n    return this;\n  }\n\n  /**\n   * Set default value to the current timestamp.\n   *\n   * Database-agnostic. Generates NOW() / CURRENT_TIMESTAMP / GETDATE() based on driver.\n   *\n   * @returns This builder for chaining\n   *\n   * @example\n   * ```typescript\n   * this.timestamp(\"created_at\").useCurrent();\n   * ```\n   */\n  public useCurrent(): this {\n    this.definition.defaultValue = { __type: \"CURRENT_TIMESTAMP\" };\n    return this;\n  }\n\n  /**\n   * Set column to update to current timestamp on row update.\n   *\n   * MySQL only. Other databases ignore this.\n   *\n   * @returns This builder for chaining\n   *\n   * @example\n   * ```typescript\n   * this.timestamp(\"updated_at\").useCurrent().useCurrentOnUpdate();\n   * ```\n   */\n  public useCurrentOnUpdate(): this {\n    this.definition.onUpdateCurrent = true;\n    return this;\n  }\n\n  // ============================================================================\n  // INDEXES\n  // ============================================================================\n\n  /**\n   * Add unique constraint/index on this column.\n   *\n   * Registers a pending unique index with the parent migration.\n   *\n   * @returns This builder for chaining\n   *\n   * @example\n   * ```typescript\n   * this.string(\"email\").unique();\n   * ```\n   */\n  public unique(): this {\n    this.migration.addPendingIndex({\n      columns: [this.definition.name],\n      unique: true,\n    });\n    return this;\n  }\n\n  /**\n   * Add regular index on this column.\n   *\n   * Registers a pending index with the parent migration.\n   *\n   * @returns This builder for chaining\n   *\n   * @example\n   * ```typescript\n   * this.string(\"email\").index();\n   * ```\n   */\n  public index(): this {\n    this.migration.addPendingIndex({\n      columns: [this.definition.name],\n    });\n    return this;\n  }\n\n  /**\n   * Add a vector search index on this column.\n   *\n   * Registers a pending vector index with the parent migration.\n   *\n   * @param options - Vector index options\n   * @returns This builder for chaining\n   *\n   * @example\n   * ```typescript\n   * this.vector(1536).vectorIndex({ similarity: \"cosine\" });\n   * ```\n   */\n  public vectorIndex(options: Omit<VectorIndexOptions, \"dimensions\"> = {}): this {\n    if (this.migration.addPendingVectorIndex) {\n      this.migration.addPendingVectorIndex(this.definition.name, {\n        ...options,\n        dimensions: this.definition.dimensions || 0,\n      });\n    }\n    return this;\n  }\n\n  // ============================================================================\n  // PRIMARY KEY & AUTO INCREMENT\n  // ============================================================================\n\n  /**\n   * Mark as primary key.\n   *\n   * @returns This builder for chaining\n   *\n   * @example\n   * ```typescript\n   * this.integer(\"id\").primary();\n   * ```\n   */\n  public primary(): this {\n    this.definition.primary = true;\n    return this;\n  }\n\n  /**\n   * Mark as auto-increment (numeric types only).\n   *\n   * SQL databases will use native AUTO_INCREMENT/SERIAL.\n   * NoSQL databases ignore this.\n   *\n   * @returns This builder for chaining\n   *\n   * @example\n   * ```typescript\n   * this.integer(\"id\").primary().autoIncrement();\n   * ```\n   */\n  public autoIncrement(): this {\n    this.definition.autoIncrement = true;\n    return this;\n  }\n\n  // ============================================================================\n  // NUMERIC MODIFIERS\n  // ============================================================================\n\n  /**\n   * Mark as unsigned (numeric types only).\n   *\n   * Disallows negative values and doubles the positive range.\n   *\n   * @returns This builder for chaining\n   *\n   * @example\n   * ```typescript\n   * this.integer(\"age\").unsigned();\n   * ```\n   */\n  public unsigned(): this {\n    this.definition.unsigned = true;\n    return this;\n  }\n\n  // ============================================================================\n  // METADATA\n  // ============================================================================\n\n  /**\n   * Add comment/description to column.\n   *\n   * Stored as column metadata in the database.\n   *\n   * @param text - Comment text\n   * @returns This builder for chaining\n   *\n   * @example\n   * ```typescript\n   * this.string(\"sku\").comment(\"Stock Keeping Unit code\");\n   * ```\n   */\n  public comment(text: string): this {\n    this.definition.comment = text;\n    return this;\n  }\n\n  // ============================================================================\n  // CONSTRAINTS\n  // ============================================================================\n\n  /**\n   * Add a CHECK constraint scoped to this column.\n   *\n   * @param expression - SQL CHECK expression (can reference the column by name)\n   * @param name - Constraint name (defaults to `check_<column>`)\n   * @returns This builder for chaining\n   */\n  public check(expression: string, name?: string): this {\n    this.definition.checkConstraint = {\n      expression,\n      name: name ?? `check_${this.definition.name}`,\n    };\n    return this;\n  }\n\n  // ============================================================================\n  // COLUMN POSITIONING (MySQL/MariaDB only)\n  // ============================================================================\n\n  /**\n   * Position this column after another column.\n   *\n   * MySQL/MariaDB only. Ignored by PostgreSQL and NoSQL drivers.\n   *\n   * @param columnName - Column to position after\n   * @returns This builder for chaining\n   *\n   * @example\n   * ```typescript\n   * this.string(\"middle_name\").after(\"first_name\");\n   * ```\n   */\n  public after(columnName: string): this {\n    this.definition.after = columnName;\n    return this;\n  }\n\n  /**\n   * Position this column as the first column in the table.\n   *\n   * MySQL/MariaDB only. Ignored by PostgreSQL and NoSQL drivers.\n   *\n   * @returns This builder for chaining\n   *\n   * @example\n   * ```typescript\n   * this.integer(\"id\").primary().first();\n   * ```\n   */\n  public first(): this {\n    this.definition.first = true;\n    return this;\n  }\n\n  // ============================================================================\n  // FOREIGN KEY\n  // ============================================================================\n\n  /**\n   * Declare a foreign key constraint on this column.\n   *\n   * Accepts either a raw table-name string or a Model class (anything with a\n   * static `table` property). Using a Model class is preferred — it is\n   * type-safe and automatically tracks table renames.\n   *\n   * Pushes an `addForeignKey` operation immediately using a mutable reference —\n   * subsequent `.on()`, `.onDelete()`, `.onUpdate()` calls mutate the same\n   * definition that is already queued, so no `.add()` terminator is needed.\n   *\n   * Referenced column defaults to `\"id\"` — use `.on()` to override.\n   *\n   * @param tableOrModel - Referenced table name OR a Model class with a static `table` property\n   * @returns This builder for chaining\n   *\n   * @example\n   * ```typescript\n   * // Preferred — model class reference (type-safe, rename-proof)\n   * this.uuid(\"organization_id\").references(Organization).onDelete(\"cascade\");\n   *\n   * // Also supported — raw table string\n   * this.uuid(\"organization_id\").references(\"organizations\").onDelete(\"cascade\");\n   * this.uuid(\"organization_id\").references(Organization.table).onDelete(\"cascade\");\n   * ```\n   */\n  public references(tableOrModel: string | { table: string }): this {\n    const tableName = typeof tableOrModel === \"string\" ? tableOrModel : tableOrModel.table;\n\n    this.fkDefinition = {\n      column: this.definition.name,\n      referencesTable: tableName,\n      referencesColumn: \"id\",\n      onDelete: \"restrict\",\n      onUpdate: \"restrict\",\n    };\n    this.migration.addForeignKeyOperation(this.fkDefinition as ForeignKeyDefinition);\n    return this;\n  }\n\n  /**\n   * Set the referenced column for the foreign key.\n   *\n   * Only meaningful after `.references()`. Defaults to `\"id\"` if omitted.\n   *\n   * @param column - Referenced column name\n   * @returns This builder for chaining\n   *\n   * @example\n   * ```typescript\n   * this.integer(\"user_id\").references(\"users\").on(\"custom_id\");\n   * ```\n   */\n  public on(column: string): this {\n    if (this.fkDefinition) {\n      this.fkDefinition.referencesColumn = column;\n    }\n    return this;\n  }\n\n  /**\n   * Set the ON DELETE action for the foreign key.\n   *\n   * Only meaningful after `.references()`.\n   *\n   * @param action - Action when the referenced row is deleted\n   * @returns This builder for chaining\n   *\n   * @example\n   * ```typescript\n   * this.integer(\"user_id\").references(\"users\").onDelete(\"cascade\");\n   * ```\n   */\n  public onDelete(action: ForeignKeyDefinition[\"onDelete\"]): this {\n    if (this.fkDefinition) {\n      this.fkDefinition.onDelete = action;\n    }\n    return this;\n  }\n\n  /**\n   * Set the ON UPDATE action for the foreign key.\n   *\n   * Only meaningful after `.references()`.\n   *\n   * @param action - Action when the referenced row's key is updated\n   * @returns This builder for chaining\n   *\n   * @example\n   * ```typescript\n   * this.integer(\"user_id\").references(\"users\").onUpdate(\"cascade\");\n   * ```\n   */\n  public onUpdate(action: ForeignKeyDefinition[\"onUpdate\"]): this {\n    if (this.fkDefinition) {\n      this.fkDefinition.onUpdate = action;\n    }\n    return this;\n  }\n\n  /**\n   * Shorthand for `.onDelete(\"cascade\").onUpdate(\"cascade\")`.\n   *\n   * Only meaningful after `.references()`.\n   *\n   * @returns This builder for chaining\n   *\n   * @example\n   * ```typescript\n   * this.integer(\"user_id\").references(\"users\").cascadeAll();\n   * ```\n   */\n  public cascadeAll(): this {\n    if (this.fkDefinition) {\n      this.fkDefinition.onDelete = \"cascade\";\n      this.fkDefinition.onUpdate = \"cascade\";\n    }\n    return this;\n  }\n\n  // ============================================================================\n  // COLUMN MODIFICATION\n  // ============================================================================\n\n  /**\n   * Mark this column definition as a modification of an existing column.\n   *\n   * Pushes a `modifyColumn` operation instead of `addColumn`.\n   * This method breaks the builder chain and returns the parent migration.\n   *\n   * @returns The parent migration instance (breaks builder chain)\n   *\n   * @example\n   * ```typescript\n   * // Make email nullable\n   * this.string(\"email\").nullable().change();\n   *\n   * // Increase length\n   * this.string(\"name\", 255).change();\n   *\n   * // Change type\n   * this.text(\"description\").change();\n   * ```\n   */\n  public change(): unknown {\n    const operations = (this.migration as any).pendingOperations;\n\n    // Remove the addColumn pushed by the column type method (e.g. uuid(), string())\n    const lastOp = operations[operations.length - 1];\n    if (lastOp?.type === \"addColumn\" && lastOp.payload === this.definition) {\n      operations.pop();\n    }\n\n    // If .references() was called before .change(), the addForeignKey op is now\n    // last in the queue. We must pop it, push modifyColumn first, then re-push\n    // the FK — because SQL requires: ALTER COLUMN (type change) → ADD CONSTRAINT (FK).\n    let pendingFkOp: (typeof operations)[number] | undefined;\n    if (this.fkDefinition) {\n      const tail = operations[operations.length - 1];\n      if (tail?.type === \"addForeignKey\" && tail.payload === this.fkDefinition) {\n        pendingFkOp = operations.pop();\n      }\n    }\n\n    // Push modifyColumn — it must precede the FK constraint\n    operations.push({ type: \"modifyColumn\", payload: this.definition });\n\n    // Re-queue the FK after the column modification\n    if (pendingFkOp) {\n      operations.push(pendingFkOp);\n    }\n\n    return this.migration;\n  }\n\n  /**\n   * @alias change\n   */\n  public modify(): unknown {\n    return this.change();\n  }\n\n  // ============================================================================\n  // GENERATED COLUMNS\n  // ============================================================================\n\n  /**\n   * Mark this column as a generated column with the given SQL expression.\n   *\n   * Must be followed by `.stored()` or `.virtual()` to specify storage type.\n   *\n   * PostgreSQL: GENERATED ALWAYS AS (...) STORED\n   * MySQL: GENERATED ALWAYS AS (...) STORED | VIRTUAL\n   *\n   * @param expression - SQL expression to compute the value\n   * @returns This builder for chaining\n   *\n   * @example\n   * ```typescript\n   * this.string(\"full_name\")\n   *   .generatedAs(\"CONCAT(first_name, ' ', last_name)\")\n   *   .stored();\n   *\n   * this.decimal(\"price_with_tax\")\n   *   .generatedAs(\"price * 1.2\")\n   *   .virtual();\n   * ```\n   */\n  public generatedAs(expression: string): this {\n    this.generatedExpression = expression;\n    return this;\n  }\n\n  /**\n   * Mark the generated column as stored (computed and persisted to disk).\n   *\n   * Must be called after `.generatedAs()`.\n   *\n   * @returns This builder for chaining\n   */\n  public stored(): this {\n    if (this.generatedExpression) {\n      this.definition.generated = {\n        expression: this.generatedExpression,\n        stored: true,\n      };\n    }\n    return this;\n  }\n\n  /**\n   * Mark the generated column as virtual (computed on read, not stored).\n   *\n   * Must be called after `.generatedAs()`. Not supported by PostgreSQL.\n   *\n   * @returns This builder for chaining\n   */\n  public virtual(): this {\n    if (this.generatedExpression) {\n      this.definition.generated = {\n        expression: this.generatedExpression,\n        stored: false,\n      };\n    }\n    return this;\n  }\n\n  // ============================================================================\n  // ACCESSOR\n  // ============================================================================\n\n  /**\n   * Get the built column definition.\n   *\n   * Called internally by the Migration class to extract the final definition.\n   *\n   * @returns The accumulated column definition\n   */\n  public getDefinition(): ColumnDefinition {\n    return this.definition;\n  }\n}\n"],"mappings":"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"}