@warlock.js/cascade 4.0.171 → 4.1.1

package/esm/migration/column-builder.d.mts

@@ -0,0 +1,420 @@
+import { ColumnDefinition, ColumnType, ForeignKeyDefinition, VectorIndexOptions } from "../contracts/migration-driver.contract.mjs";
+
+//#region ../../@warlock.js/cascade/src/migration/column-builder.d.ts
+/**
+ * Reference to the Migration type to avoid circular imports.
+ * The actual type is injected at runtime.
+ */
+type MigrationLike = {
+  addPendingIndex(index: {
+    columns: string[];
+    unique?: boolean;
+  }): void;
+  addForeignKeyOperation(fk: ForeignKeyDefinition): void;
+  addPendingVectorIndex?(column: string, options: Omit<VectorIndexOptions, "column">): void;
+};
+/**
+ * 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");
+ * ```
+ */
+declare class ColumnBuilder {
+  private readonly migration;
+  /** Mutable column definition being accumulated */
+  private readonly definition;
+  /** Mutable foreign key definition, set when .references() is called */
+  private fkDefinition?;
+  /** Temporary storage for generated expression before .stored() or .virtual() is called */
+  private 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: MigrationLike, name: string, type: ColumnType, options?: Partial<Pick<ColumnDefinition, "length" | "precision" | "scale" | "dimensions" | "values">>);
+  /**
+   * Mark column as nullable (allows NULL values).
+   *
+   * @returns This builder for chaining
+   *
+   * @example
+   * ```typescript
+   * this.string("middleName").nullable();
+   * ```
+   */
+  nullable(): 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;
+  /**
+   * 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: string | number | boolean): 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: string): 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;
+  /**
+   * 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;
+  /**
+   * 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;
+  /**
+   * 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;
+  /**
+   * 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?: Omit<VectorIndexOptions, "dimensions">): this;
+  /**
+   * Mark as primary key.
+   *
+   * @returns This builder for chaining
+   *
+   * @example
+   * ```typescript
+   * this.integer("id").primary();
+   * ```
+   */
+  primary(): 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;
+  /**
+   * 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;
+  /**
+   * 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: string): 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: string, name?: string): 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: string): 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;
+  /**
+   * 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: string | {
+    table: string;
+  }): 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: string): 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: ForeignKeyDefinition["onDelete"]): 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: ForeignKeyDefinition["onUpdate"]): 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(): 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(): unknown;
+  /**
+   * @alias change
+   */
+  modify(): unknown;
+  /**
+   * 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: string): this;
+  /**
+   * Mark the generated column as stored (computed and persisted to disk).
+   *
+   * Must be called after `.generatedAs()`.
+   *
+   * @returns This builder for chaining
+   */
+  stored(): 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(): this;
+  /**
+   * Get the built column definition.
+   *
+   * Called internally by the Migration class to extract the final definition.
+   *
+   * @returns The accumulated column definition
+   */
+  getDefinition(): ColumnDefinition;
+}
+//#endregion
+export { ColumnBuilder };
+//# sourceMappingURL=column-builder.d.mts.map

package/esm/migration/column-builder.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-builder.d.mts","names":[],"sources":["../../../../../../@warlock.js/cascade/src/migration/column-builder.ts"],"mappings":";;;;;AAKgD;;KAM3C,aAAA;EACH,eAAA,CAAgB,KAAA;IAAS,OAAA;IAAmB,MAAA;EAAA;EAC5C,sBAAA,CAAuB,EAAA,EAAI,oBAAA;EAC3B,qBAAA,EAAuB,MAAA,UAAgB,OAAA,EAAS,IAAA,CAAK,kBAAA;AAAA;;;;;;;;;;;;AAA6B;AAqCpF;;;;;;;;;;cAAa,aAAA;EAAA,iBAmBQ,SAAA;EAklBK;EAAA,iBAnmBP,UAAA;EAmmBuB;EAAA,QAhmBhC,YAAA;EAHS;EAAA,QAMT,mBAAA;EAAA;;;;;;;;cAWW,SAAA,EAAW,aAAA,EAC5B,IAAA,UACA,IAAA,EAAM,UAAA,EACN,OAAA,GAAS,OAAA,CACP,IAAA,CAAK,gBAAA;EAAA;;;;;;;;;;EAyBF,QAAA,CAAA;EAuIA;;;;;;;EA3HA,WAAA,CAAA;EAoOA;;;;;;;;;;;;;;;;;EA1MA,OAAA,CAAQ,KAAA;EA0WC;;;;;;;;;;;AAqKwB;;;;EA1fjC,aAAA,CAAc,KAAA;;;;;;;;;;;;;EAkBd,UAAA,CAAA;;;;;;;;;;;;;EAiBA,kBAAA,CAAA;;;;;;;;;;;;;EAqBA,MAAA,CAAA;;;;;;;;;;;;;EAoBA,KAAA,CAAA;;;;;;;;;;;;;;EAoBA,WAAA,CAAY,OAAA,GAAS,IAAA,CAAK,kBAAA;;;;;;;;;;;EAwB1B,OAAA,CAAA;;;;;;;;;;;;;;EAkBA,aAAA,CAAA;;;;;;;;;;;;;EAqBA,QAAA,CAAA;;;;;;;;;;;;;;EAsBA,OAAA,CAAQ,IAAA;;;;;;;;EAgBR,KAAA,CAAM,UAAA,UAAoB,IAAA;;;;;;;;;;;;;;EAyB1B,KAAA,CAAM,UAAA;;;;;;;;;;;;;EAiBN,KAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmCA,UAAA,CAAW,YAAA;IAAyB,KAAA;EAAA;;;;;;;;;;;;;;EA2BpC,EAAA,CAAG,MAAA;;;;;;;;;;;;;;EAoBH,QAAA,CAAS,MAAA,EAAQ,oBAAA;;;;;;;;;;;;;;EAoBjB,QAAA,CAAS,MAAA,EAAQ,oBAAA;;;;;;;;;;;;;EAmBjB,UAAA,CAAA;;;;;;;;;;;;;;;;;;;;;EAgCA,MAAA,CAAA;;;;EAkCA,MAAA,CAAA;;;;;;;;;;;;;;;;;;;;;;;EA8BA,WAAA,CAAY,UAAA;;;;;;;;EAYZ,MAAA,CAAA;;;;;;;;EAiBA,OAAA,CAAA;;;;;;;;EAqBA,aAAA,CAAA,GAAiB,gBAAA;AAAA"}