feat: allow expressions in create/add index's column and columns functions, deprecate their expression functions. (#1664)

Author: igalklebanov

src/schema/alter-table-add-index-builder.ts

@@ -11,7 +11,7 @@ import {
 import type { CompiledQuery } from '../query-compiler/compiled-query.js'
 import type { QueryExecutor } from '../query-executor/query-executor.js'
 import type { Compilable } from '../util/compilable.js'
-import { freeze } from '../util/object-utils.js'
+import { freeze, isString } from '../util/object-utils.js'
 import type { QueryId } from '../util/query-id.js'
 
 export class AlterTableAddIndexBuilder
@@ -63,28 +63,40 @@ export class AlterTableAddIndexBuilder
    * ### Examples
    *
    * ```ts
+   * import { sql } from 'kysely'
+   *
    * await db.schema
    *   .alterTable('person')
    *   .addIndex('person_first_name_and_age_index')
    *   .column('first_name')
+   *   .column(sql`(left(lower(last_name), 1))`)
    *   .column('age desc')
    *   .execute()
    * ```
    *
    * The generated SQL (MySQL):
    *
    * ```sql
-   * alter table `person` add index `person_first_name_and_age_index` (`first_name`, `age` desc)
+   * alter table `person`
+   * add index `person_first_name_and_age_index` (
+   *   `first_name`,
+   *   (left(lower(last_name), 1)),
+   *   `age` desc
+   * )
    * ```
    */
   column<CL extends string>(
     column: OrderedColumnName<CL>,
-  ): AlterTableAddIndexBuilder {
+  ): AlterTableAddIndexBuilder
+
+  column(expression: Expression<any>): AlterTableAddIndexBuilder
+
+  column(arg: any): any {
     return new AlterTableAddIndexBuilder({
       ...this.#props,
       node: AlterTableNode.cloneWithTableProps(this.#props.node, {
         addIndex: AddIndexNode.cloneWithColumns(this.#props.node.addIndex!, [
-          parseOrderedColumnName(column),
+          isString(arg) ? parseOrderedColumnName(arg) : arg.toOperationNode(),
         ]),
       }),
     })
@@ -99,28 +111,39 @@ export class AlterTableAddIndexBuilder
    * ### Examples
    *
    * ```ts
+   * import { sql } from 'kysely'
+   *
    * await db.schema
    *   .alterTable('person')
    *   .addIndex('person_first_name_and_age_index')
-   *   .columns(['first_name', 'age desc'])
+   *   .columns(['first_name', sql`(left(lower(last_name), 1))`, 'age desc'])
    *   .execute()
    * ```
    *
    * The generated SQL (MySQL):
    *
    * ```sql
-   * alter table `person` add index `person_first_name_and_age_index` (`first_name`, `age` desc)
+   * alter table `person`
+   * add index `person_first_name_and_age_index` (
+   *   `first_name`,
+   *   (left(lower(last_name), 1)),
+   *   `age` desc
+   * )
    * ```
    */
   columns<CL extends string>(
-    columns: OrderedColumnName<CL>[],
+    columns: (OrderedColumnName<CL> | Expression<any>)[],
   ): AlterTableAddIndexBuilder {
     return new AlterTableAddIndexBuilder({
       ...this.#props,
       node: AlterTableNode.cloneWithTableProps(this.#props.node, {
         addIndex: AddIndexNode.cloneWithColumns(
           this.#props.node.addIndex!,
-          columns.map(parseOrderedColumnName),
+          columns.map((item) =>
+            isString(item)
+              ? parseOrderedColumnName(item)
+              : item.toOperationNode(),
+          ),
         ),
       }),
     })
@@ -146,7 +169,10 @@ export class AlterTableAddIndexBuilder
    * ```sql
    * alter table `person` add index `person_first_name_index` ((first_name < 'Sami'))
    * ```
+   *
+   * @deprecated Use {@link column} or {@link columns} with an {@link Expression} instead.
    */
+  // TODO: remove in v0.30
   expression(expression: Expression<any>): AlterTableAddIndexBuilder {
     return new AlterTableAddIndexBuilder({
       ...this.#props,

src/schema/create-index-builder.ts

@@ -14,7 +14,7 @@ import type { CompiledQuery } from '../query-compiler/compiled-query.js'
 import type { Compilable } from '../util/compilable.js'
 import type { QueryExecutor } from '../query-executor/query-executor.js'
 import type { QueryId } from '../util/query-id.js'
-import { freeze } from '../util/object-utils.js'
+import { freeze, isString } from '../util/object-utils.js'
 import type { Expression } from '../expression/expression.js'
 import {
   type ComparisonOperatorExpression,
@@ -106,73 +106,88 @@ export class CreateIndexBuilder<C = never>
   /**
    * Adds a column to the index.
    *
-   * Also see {@link columns} for adding multiple columns at once or {@link expression}
-   * for specifying an arbitrary expression.
+   * Also see {@link columns} for adding multiple columns at once.
    *
    * ### Examples
    *
    * ```ts
+   * import { sql } from 'kysely'
+   *
    * await db.schema
-   *         .createIndex('person_first_name_and_age_index')
-   *         .on('person')
-   *         .column('first_name')
-   *         .column('age desc')
-   *         .execute()
+   *   .createIndex('person_first_name_and_age_index')
+   *   .on('person')
+   *   .column('first_name')
+   *   .column<'last_name'>(sql`left(lower("last_name"), 1)`)
+   *   .column('age desc')
+   *   .where('last_name', 'is not', null)
+   *   .execute()
    * ```
    *
    * The generated SQL (PostgreSQL):
    *
    * ```sql
-   * create index "person_first_name_and_age_index" on "person" ("first_name", "age" desc)
+   * create index "person_first_name_and_age_index"
+   * on "person" ("first_name", left(lower("last_name"), 1), "age" desc)
+   * where "last_name" is not null
    * ```
    */
   column<CL extends string>(
     column: OrderedColumnName<CL>,
-  ): CreateIndexBuilder<C | ExtractColumnNameFromOrderedColumnName<CL>> {
+  ): CreateIndexBuilder<C | ExtractColumnNameFromOrderedColumnName<CL>>
+  column<CL extends string = never>(
+    expression: Expression<any>,
+  ): CreateIndexBuilder<C | CL>
+  column(arg: any): any {
     return new CreateIndexBuilder({
       ...this.#props,
       node: CreateIndexNode.cloneWithColumns(this.#props.node, [
-        parseOrderedColumnName(column),
+        isString(arg) ? parseOrderedColumnName(arg) : arg.toOperationNode(),
       ]),
     })
   }
 
   /**
-   * Specifies a list of columns for the index.
+   * Adds a list of columns to the index.
    *
-   * Also see {@link column} for adding a single column or {@link expression} for
-   * specifying an arbitrary expression.
+   * Also see {@link column} for adding a single column.
    *
    * ### Examples
    *
    * ```ts
+   * import { sql } from 'kysely'
+   *
    * await db.schema
-   *         .createIndex('person_first_name_and_age_index')
-   *         .on('person')
-   *         .columns(['first_name', 'age desc'])
-   *         .execute()
+   *   .createIndex('person_first_name_and_age_index')
+   *   .on('person')
+   *   .columns(['first_name', sql`left(lower("last_name"), 1)`, 'age desc'])
+   *   .execute()
    * ```
    *
    * The generated SQL (PostgreSQL):
    *
    * ```sql
-   * create index "person_first_name_and_age_index" on "person" ("first_name", "age" desc)
+   * create index "person_first_name_and_age_index"
+   * on "person" ("first_name", left(lower("last_name"), 1), "age" desc)
    * ```
    */
   columns<CL extends string>(
-    columns: OrderedColumnName<CL>[],
+    columns: (OrderedColumnName<CL> | Expression<any>)[],
   ): CreateIndexBuilder<C | ExtractColumnNameFromOrderedColumnName<CL>> {
     return new CreateIndexBuilder({
       ...this.#props,
       node: CreateIndexNode.cloneWithColumns(
         this.#props.node,
-        columns.map(parseOrderedColumnName),
+        columns.map((item) =>
+          isString(item)
+            ? parseOrderedColumnName(item)
+            : item.toOperationNode(),
+        ),
       ),
     })
   }
 
   /**
-   * Specifies an arbitrary expression for the index.
+   * Adds an arbitrary expression as a column to the index.
    *
    * ### Examples
    *
@@ -183,15 +198,20 @@ export class CreateIndexBuilder<C = never>
    *   .createIndex('person_first_name_index')
    *   .on('person')
    *   .expression(sql`first_name COLLATE "fi_FI"`)
+   *   .column('gender')
    *   .execute()
    * ```
    *
    * The generated SQL (PostgreSQL):
    *
    * ```sql
-   * create index "person_first_name_index" on "person" (first_name COLLATE "fi_FI")
+   * create index "person_first_name_index"
+   * on "person" (first_name COLLATE "fi_FI", "gender")
    * ```
+   *
+   * @deprecated Use {@link column} or {@link columns} with an {@link Expression} instead.
    */
+  // TODO: remove in v0.30
   expression(expression: Expression<any>): CreateIndexBuilder<C> {
     return new CreateIndexBuilder({
       ...this.#props,
@@ -203,6 +223,23 @@ export class CreateIndexBuilder<C = never>
 
   /**
    * Specifies the index type.
+   *
+   * ### Examples
+   *
+   * ```ts
+   * await db.schema
+   *   .createIndex('person_first_name_index')
+   *   .on('person')
+   *   .column('first_name')
+   *   .using('hash')
+   *   .execute()
+   * ```
+   *
+   * The generated SQL (MySQL):
+   *
+   * ```sql
+   * create index `person_first_name_index` on `person` (`first_name`) using hash
+   * ```
    */
   using(indexType: IndexType): CreateIndexBuilder<C>
   using(indexType: string): CreateIndexBuilder<C>
@@ -218,6 +255,8 @@ export class CreateIndexBuilder<C = never>
   /**
    * Adds a where clause to the query. This Effectively turns the index partial.
    *
+   * This is only supported by some dialects like PostgreSQL and MS SQL Server.
+   *
    * ### Examples
    *
    * ```ts

test/node/src/schema.test.ts

@@ -1855,7 +1855,7 @@ for (const dialect of DIALECTS) {
           const builder = ctx.db.schema
             .createIndex('test_first_name_index')
             .on('test')
-            .expression(sql`(first_name < 'Sami')`)
+            .column(sql`(first_name < 'Sami')`)
 
           testSql(builder, dialect, {
             postgres: {
@@ -4093,7 +4093,7 @@ for (const dialect of DIALECTS) {
             const query = ctx.db.schema
               .alterTable('test')
               .addIndex('test_varchar_col_index')
-              .expression(sql`(varchar_col < 'Sami')`)
+              .column(sql`(varchar_col < 'Sami')`)
 
             testSql(query, dialect, {
               mysql: {