kysely 0.24.2 → 0.26.0

package/dist/cjs/query-builder/where-interface.d.ts

@@ -1,9 +1,8 @@
 import { Expression } from '../expression/expression.js';
 import { ComparisonOperatorExpression, OperandValueExpressionOrList } from '../parser/binary-operation-parser.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
-import { ExistsExpression } from '../parser/unary-operation-parser.js';
 import { SqlBool } from '../util/type-utils.js';
-import { WhereExpressionBuilder } from './deprecated-where-expression-builder.js';
+import { ExpressionBuilder } from '../expression/expression-builder.js';
 export interface WhereInterface<DB, TB extends keyof DB> {
     /**
      * Adds a `where` expression to the query.
@@ -14,6 +13,10 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      *
      * ### Examples
      *
+     * <!-- siteExample("where", "Simple where clause", 10) -->
+     *
+     * `where` method calls are combined with `AND`:
+     *
      * ```ts
      * const person = await db
      *   .selectFrom('person')
@@ -36,9 +39,65 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      * sql`your operator`
      * ```
      *
+     * <!-- siteExample("where", "Where in", 20) -->
+     *
+     * Find multiple items using a list of identifiers:
+     *
+     * ```ts
+     * const persons = await db
+     *   .selectFrom('person')
+     *   .selectAll()
+     *   .where('id', 'in', ['1', '2', '3'])
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select * from "person" where "id" in ($1, $2, $3)
+     * ```
+     *
+     * <!-- siteExample("where", "OR where", 30) -->
+     *
+     * To combine conditions using `OR`, you can use the expression builder:
+     *
+     * ```ts
+     * const persons = await db
+     *   .selectFrom('person')
+     *   .selectAll()
+     *   .where(({ or, and, cmpr }) => or([
+     *     and([
+     *       cmpr('first_name', '=', 'Jennifer'),
+     *       cmpr('last_name', '=', 'Aniston')
+     *     ]),
+     *     and([
+     *       cmpr('first_name', '=', 'Sylvester'),
+     *       cmpr('last_name', '=', 'Stallone')
+     *     ])
+     *   ]))
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select *
+     * from "person"
+     * where (
+     *   ("first_name" = $1 AND "last_name" = $2)
+     *   OR
+     *   ("first_name" = $3 AND "last_name" = $4)
+     * )
+     * ```
+     *
+     * <!-- siteExample("where", "Conditional where calls", 40) -->
+     *
      * You can add expressions conditionally like this:
      *
      * ```ts
+     * const firstName: string | undefined = 'Jennifer'
+     * const lastName: string | undefined = 'Aniston'
+     *
      * let query = db
      *   .selectFrom('person')
      *   .selectAll()
@@ -105,22 +164,30 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      * select * from "person" where "id" in ($1, $2, $3)
      * ```
      *
+     * <!-- siteExample("where", "Complex where clause", 50) -->
+     *
      * For complex `where` expressions you can pass in a single callback and
-     * use the {@link ExpressionBuilder} to build your expression:
+     * use the `ExpressionBuilder` to build your expression:
      *
      * ```ts
+     * const firstName = 'Jennifer'
+     * const maxAge = 60
+     *
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll('person')
-     *   .where(({ cmpr, or, and, not, exists, selectFrom, val }) => and([
+     *   .where(({ cmpr, or, and, not, exists, selectFrom }) => and([
      *     or([
      *       cmpr('first_name', '=', firstName),
      *       cmpr('age', '<', maxAge)
      *     ]),
      *     not(exists(
-     *       selectFrom('pet').select('pet.id').whereRef('pet.owner_id', '=', 'person.id')
+     *       selectFrom('pet')
+     *         .select('pet.id')
+     *         .whereRef('pet.owner_id', '=', 'person.id')
      *     ))
      *   ]))
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -241,38 +308,6 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      * from "person"
      */
     whereRef(lhs: ReferenceExpression<DB, TB>, op: ComparisonOperatorExpression, rhs: ReferenceExpression<DB, TB>): WhereInterface<DB, TB>;
-    /**
-     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
-     */
-    orWhere<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): WhereInterface<DB, TB>;
-    /**
-     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
-     */
-    orWhere(factory: WhereExpressionFactory<DB, TB>): WhereInterface<DB, TB>;
-    /**
-     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
-     */
-    orWhere(expression: Expression<any>): WhereInterface<DB, TB>;
-    /**
-     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
-     */
-    orWhereRef(lhs: ReferenceExpression<DB, TB>, op: ComparisonOperatorExpression, rhs: ReferenceExpression<DB, TB>): WhereInterface<DB, TB>;
-    /**
-     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
-     */
-    whereExists(arg: ExistsExpression<DB, TB>): WhereInterface<DB, TB>;
-    /**
-     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
-     */
-    whereNotExists(arg: ExistsExpression<DB, TB>): WhereInterface<DB, TB>;
-    /**
-     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
-     */
-    orWhereExists(arg: ExistsExpression<DB, TB>): WhereInterface<DB, TB>;
-    /**
-     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
-     */
-    orWhereNotExists(arg: ExistsExpression<DB, TB>): WhereInterface<DB, TB>;
     /**
      * Clears all where expressions from the query.
      *
@@ -293,4 +328,4 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      */
     clearWhere(): WhereInterface<DB, TB>;
 }
-export declare type WhereExpressionFactory<DB, TB extends keyof DB> = (eb: WhereExpressionBuilder<DB, TB>) => Expression<SqlBool> | WhereExpressionBuilder<DB, TB>;
+export type WhereExpressionFactory<DB, TB extends keyof DB> = (eb: ExpressionBuilder<DB, TB>) => Expression<SqlBool>;

package/dist/cjs/query-compiler/compiled-query.d.ts

@@ -5,5 +5,5 @@ export interface CompiledQuery<O = unknown> {
     readonly parameters: ReadonlyArray<unknown>;
 }
 export declare const CompiledQuery: Readonly<{
-    raw(sql: string): CompiledQuery;
+    raw(sql: string, parameters?: unknown[]): CompiledQuery;
 }>;

package/dist/cjs/query-compiler/compiled-query.js

@@ -4,11 +4,11 @@ exports.CompiledQuery = void 0;
 const raw_node_js_1 = require("../operation-node/raw-node.js");
 const object_utils_js_1 = require("../util/object-utils.js");
 exports.CompiledQuery = (0, object_utils_js_1.freeze)({
-    raw(sql) {
+    raw(sql, parameters = []) {
         return (0, object_utils_js_1.freeze)({
             sql,
             query: raw_node_js_1.RawNode.createWithSql(sql),
-            parameters: (0, object_utils_js_1.freeze)([]),
+            parameters: (0, object_utils_js_1.freeze)(parameters),
         });
     },
 });

package/dist/cjs/query-compiler/default-query-compiler.d.ts

@@ -81,6 +81,12 @@ import { BinaryOperationNode } from '../operation-node/binary-operation-node.js'
 import { UnaryOperationNode } from '../operation-node/unary-operation-node.js';
 import { UsingNode } from '../operation-node/using-node.js';
 import { FunctionNode } from '../operation-node/function-node.js';
+import { CaseNode } from '../operation-node/case-node.js';
+import { WhenNode } from '../operation-node/when-node.js';
+import { JSONReferenceNode } from '../operation-node/json-reference-node.js';
+import { JSONPathNode } from '../operation-node/json-path-node.js';
+import { JSONPathLegNode } from '../operation-node/json-path-leg-node.js';
+import { JSONOperatorChainNode } from '../operation-node/json-operator-chain-node.js';
 export declare class DefaultQueryCompiler extends OperationNodeVisitor implements QueryCompiler {
     #private;
     protected get numParameters(): number;
@@ -170,6 +176,12 @@ export declare class DefaultQueryCompiler extends OperationNodeVisitor implement
     protected isMinusOperator(node: OperationNode): node is OperatorNode;
     protected visitUsing(node: UsingNode): void;
     protected visitFunction(node: FunctionNode): void;
+    protected visitCase(node: CaseNode): void;
+    protected visitWhen(node: WhenNode): void;
+    protected visitJSONReference(node: JSONReferenceNode): void;
+    protected visitJSONPath(node: JSONPathNode): void;
+    protected visitJSONPathLeg(node: JSONPathLegNode): void;
+    protected visitJSONOperatorChain(node: JSONOperatorChainNode): void;
     protected append(str: string): void;
     protected appendValue(parameter: unknown): void;
     protected getLeftIdentifierWrapper(): string;

package/dist/cjs/query-compiler/default-query-compiler.js

@@ -230,8 +230,10 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
         this.visitNode(node.alias);
     }
     visitReference(node) {
-        this.visitNode(node.table);
-        this.append('.');
+        if (node.table) {
+            this.visitNode(node.table);
+            this.append('.');
+        }
         this.visitNode(node.column);
     }
     visitSelectAll(_) {
@@ -548,9 +550,9 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
             this.append(' using ');
             this.visitNode(node.using);
         }
-        if (node.expression) {
+        if (node.columns) {
             this.append(' (');
-            this.visitNode(node.expression);
+            this.compileList(node.columns);
             this.append(')');
         }
         if (node.where) {
@@ -869,7 +871,7 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
         if (node.distinct) {
             this.append('distinct ');
         }
-        this.visitNode(node.aggregated);
+        this.compileList(node.aggregated);
         this.append(')');
         if (node.filter) {
             this.append(' filter(');
@@ -928,6 +930,66 @@ class DefaultQueryCompiler extends operation_node_visitor_js_1.OperationNodeVisi
         this.compileList(node.arguments);
         this.append(')');
     }
+    visitCase(node) {
+        this.append('case');
+        if (node.value) {
+            this.append(' ');
+            this.visitNode(node.value);
+        }
+        if (node.when) {
+            this.append(' ');
+            this.compileList(node.when, ' ');
+        }
+        if (node.else) {
+            this.append(' else ');
+            this.visitNode(node.else);
+        }
+        this.append(' end');
+        if (node.isStatement) {
+            this.append(' case');
+        }
+    }
+    visitWhen(node) {
+        this.append('when ');
+        this.visitNode(node.condition);
+        if (node.result) {
+            this.append(' then ');
+            this.visitNode(node.result);
+        }
+    }
+    visitJSONReference(node) {
+        this.visitNode(node.reference);
+        this.visitNode(node.traversal);
+    }
+    visitJSONPath(node) {
+        if (node.inOperator) {
+            this.visitNode(node.inOperator);
+        }
+        this.append("'$");
+        for (const pathLeg of node.pathLegs) {
+            this.visitNode(pathLeg);
+        }
+        this.append("'");
+    }
+    visitJSONPathLeg(node) {
+        const isArrayLocation = node.type === 'ArrayLocation';
+        this.append(isArrayLocation ? '[' : '.');
+        this.append(String(node.value));
+        if (isArrayLocation) {
+            this.append(']');
+        }
+    }
+    visitJSONOperatorChain(node) {
+        for (let i = 0, len = node.values.length; i < len; i++) {
+            if (i === len - 1) {
+                this.visitNode(node.operator);
+            }
+            else {
+                this.append('->');
+            }
+            this.visitNode(node.values[i]);
+        }
+    }
     append(str) {
         this.#sql += str;
     }

package/dist/cjs/query-compiler/query-compiler.d.ts

@@ -12,7 +12,7 @@ import { DropViewNode } from '../operation-node/drop-view-node.js';
 import { QueryNode } from '../operation-node/query-node.js';
 import { RawNode } from '../operation-node/raw-node.js';
 import { CompiledQuery } from './compiled-query.js';
-export declare type RootOperationNode = QueryNode | CreateTableNode | CreateIndexNode | CreateSchemaNode | CreateViewNode | DropTableNode | DropIndexNode | DropSchemaNode | DropViewNode | AlterTableNode | RawNode | CreateTypeNode | DropTypeNode;
+export type RootOperationNode = QueryNode | CreateTableNode | CreateIndexNode | CreateSchemaNode | CreateViewNode | DropTableNode | DropIndexNode | DropSchemaNode | DropViewNode | AlterTableNode | RawNode | CreateTypeNode | DropTypeNode;
 /**
  * a `QueryCompiler` compiles a query expressed as a tree of `OperationNodes` into SQL.
  */

package/dist/cjs/query-creator.d.ts

@@ -201,12 +201,14 @@ export declare class QueryCreator<DB> {
      *
      * ### Examples
      *
-     * Deleting person with id 1:
+     * <!-- siteExample("delete", "Single row", 10) -->
+     *
+     * Delete a single row:
      *
      * ```ts
      * const result = await db
      *   .deleteFrom('person')
-     *   .where('person.id', '=', 1)
+     *   .where('person.id', '=', '1')
      *   .executeTakeFirst()
      *
      * console.log(result.numDeletedRows)

package/dist/cjs/schema/alter-column-builder.d.ts

@@ -1,11 +1,11 @@
 import { AlterColumnNode } from '../operation-node/alter-column-node.js';
-import { ColumnDataType } from '../operation-node/data-type-node.js';
 import { OperationNodeSource } from '../operation-node/operation-node-source.js';
+import { DataTypeExpression } from '../parser/data-type-parser.js';
 import { DefaultValueExpression } from '../parser/default-value-parser.js';
 export declare class AlterColumnBuilder {
-    protected readonly alterColumnNode: AlterColumnNode;
-    constructor(alterColumnNode: AlterColumnNode);
-    setDataType(dataType: ColumnDataType): AlteredColumnBuilder;
+    #private;
+    constructor(column: string);
+    setDataType(dataType: DataTypeExpression): AlteredColumnBuilder;
     setDefault(value: DefaultValueExpression): AlteredColumnBuilder;
     dropDefault(): AlteredColumnBuilder;
     setNotNull(): AlteredColumnBuilder;
@@ -17,7 +17,7 @@ export declare class AlterColumnBuilder {
     $call<T>(func: (qb: this) => T): T;
 }
 /**
- * Allows us to force consumers to do something, anything, when altering a column.
+ * Allows us to force consumers to do exactly one alteration to a column.
  *
  * Basically, deny the following:
  *
@@ -25,9 +25,15 @@ export declare class AlterColumnBuilder {
  * db.schema.alterTable('person').alterColumn('age', (ac) => ac)
  * ```
  *
+ * ```ts
+ * db.schema.alterTable('person').alterColumn('age', (ac) => ac.dropNotNull().setNotNull())
+ * ```
+ *
  * Which would now throw a compilation error, instead of a runtime error.
  */
-export declare class AlteredColumnBuilder extends AlterColumnBuilder implements OperationNodeSource {
+export declare class AlteredColumnBuilder implements OperationNodeSource {
+    #private;
+    constructor(alterColumnNode: AlterColumnNode);
     toOperationNode(): AlterColumnNode;
 }
-export declare type AlterColumnBuilderCallback = (builder: AlterColumnBuilder) => AlteredColumnBuilder;
+export type AlterColumnBuilderCallback = (builder: AlterColumnBuilder) => AlteredColumnBuilder;

package/dist/cjs/schema/alter-column-builder.js

@@ -2,37 +2,27 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AlteredColumnBuilder = exports.AlterColumnBuilder = void 0;
 const alter_column_node_js_1 = require("../operation-node/alter-column-node.js");
-const data_type_node_js_1 = require("../operation-node/data-type-node.js");
+const data_type_parser_js_1 = require("../parser/data-type-parser.js");
 const default_value_parser_js_1 = require("../parser/default-value-parser.js");
 class AlterColumnBuilder {
-    alterColumnNode;
-    constructor(alterColumnNode) {
-        this.alterColumnNode = alterColumnNode;
+    #column;
+    constructor(column) {
+        this.#column = column;
     }
     setDataType(dataType) {
-        return new AlteredColumnBuilder(alter_column_node_js_1.AlterColumnNode.cloneWith(this.alterColumnNode, {
-            dataType: data_type_node_js_1.DataTypeNode.create(dataType),
-        }));
+        return new AlteredColumnBuilder(alter_column_node_js_1.AlterColumnNode.create(this.#column, 'dataType', (0, data_type_parser_js_1.parseDataTypeExpression)(dataType)));
     }
     setDefault(value) {
-        return new AlteredColumnBuilder(alter_column_node_js_1.AlterColumnNode.cloneWith(this.alterColumnNode, {
-            setDefault: (0, default_value_parser_js_1.parseDefaultValueExpression)(value),
-        }));
+        return new AlteredColumnBuilder(alter_column_node_js_1.AlterColumnNode.create(this.#column, 'setDefault', (0, default_value_parser_js_1.parseDefaultValueExpression)(value)));
     }
     dropDefault() {
-        return new AlteredColumnBuilder(alter_column_node_js_1.AlterColumnNode.cloneWith(this.alterColumnNode, {
-            dropDefault: true,
-        }));
+        return new AlteredColumnBuilder(alter_column_node_js_1.AlterColumnNode.create(this.#column, 'dropDefault', true));
     }
     setNotNull() {
-        return new AlteredColumnBuilder(alter_column_node_js_1.AlterColumnNode.cloneWith(this.alterColumnNode, {
-            setNotNull: true,
-        }));
+        return new AlteredColumnBuilder(alter_column_node_js_1.AlterColumnNode.create(this.#column, 'setNotNull', true));
     }
     dropNotNull() {
-        return new AlteredColumnBuilder(alter_column_node_js_1.AlterColumnNode.cloneWith(this.alterColumnNode, {
-            dropNotNull: true,
-        }));
+        return new AlteredColumnBuilder(alter_column_node_js_1.AlterColumnNode.create(this.#column, 'dropNotNull', true));
     }
     /**
      * Simply calls the provided function passing `this` as the only argument. `$call` returns
@@ -44,7 +34,7 @@ class AlterColumnBuilder {
 }
 exports.AlterColumnBuilder = AlterColumnBuilder;
 /**
- * Allows us to force consumers to do something, anything, when altering a column.
+ * Allows us to force consumers to do exactly one alteration to a column.
  *
  * Basically, deny the following:
  *
@@ -52,11 +42,19 @@ exports.AlterColumnBuilder = AlterColumnBuilder;
  * db.schema.alterTable('person').alterColumn('age', (ac) => ac)
  * ```
  *
+ * ```ts
+ * db.schema.alterTable('person').alterColumn('age', (ac) => ac.dropNotNull().setNotNull())
+ * ```
+ *
  * Which would now throw a compilation error, instead of a runtime error.
  */
-class AlteredColumnBuilder extends AlterColumnBuilder {
+class AlteredColumnBuilder {
+    #alterColumnNode;
+    constructor(alterColumnNode) {
+        this.#alterColumnNode = alterColumnNode;
+    }
     toOperationNode() {
-        return this.alterColumnNode;
+        return this.#alterColumnNode;
     }
 }
 exports.AlteredColumnBuilder = AlteredColumnBuilder;

package/dist/cjs/schema/alter-table-builder.d.ts

@@ -55,10 +55,6 @@ export declare class AlterTableBuilder implements ColumnAlteringInterface {
      * See {@link CreateTableBuilder.$call}
      */
     $call<T>(func: (qb: this) => T): T;
-    /**
-     * @deprecated Use `$call` instead
-     */
-    call<T>(func: (qb: this) => T): T;
 }
 export interface AlterTableBuilderProps {
     readonly queryId: QueryId;

package/dist/cjs/schema/alter-table-builder.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AlterTableColumnAlteringBuilder = exports.AlterTableBuilder = void 0;
 const add_column_node_js_1 = require("../operation-node/add-column-node.js");
-const alter_column_node_js_1 = require("../operation-node/alter-column-node.js");
 const alter_table_node_js_1 = require("../operation-node/alter-table-node.js");
 const column_definition_node_js_1 = require("../operation-node/column-definition-node.js");
 const drop_column_node_js_1 = require("../operation-node/drop-column-node.js");
@@ -50,7 +49,7 @@ class AlterTableBuilder {
         });
     }
     alterColumn(column, alteration) {
-        const builder = alteration(new alter_column_builder_js_1.AlterColumnBuilder(alter_column_node_js_1.AlterColumnNode.create(column)));
+        const builder = alteration(new alter_column_builder_js_1.AlterColumnBuilder(column));
         return new AlterTableColumnAlteringBuilder({
             ...this.#props,
             node: alter_table_node_js_1.AlterTableNode.cloneWithColumnAlteration(this.#props.node, builder.toOperationNode()),
@@ -133,12 +132,6 @@ class AlterTableBuilder {
     $call(func) {
         return func(this);
     }
-    /**
-     * @deprecated Use `$call` instead
-     */
-    call(func) {
-        return this.$call(func);
-    }
 }
 exports.AlterTableBuilder = AlterTableBuilder;
 class AlterTableColumnAlteringBuilder {
@@ -147,7 +140,7 @@ class AlterTableColumnAlteringBuilder {
         this.#props = (0, object_utils_js_1.freeze)(props);
     }
     alterColumn(column, alteration) {
-        const builder = alteration(new alter_column_builder_js_1.AlterColumnBuilder(alter_column_node_js_1.AlterColumnNode.create(column)));
+        const builder = alteration(new alter_column_builder_js_1.AlterColumnBuilder(column));
         return new AlterTableColumnAlteringBuilder({
             ...this.#props,
             node: alter_table_node_js_1.AlterTableNode.cloneWithColumnAlteration(this.#props.node, builder.toOperationNode()),

package/dist/cjs/schema/column-definition-builder.d.ts

@@ -212,4 +212,4 @@ export declare class ColumnDefinitionBuilder implements OperationNodeSource {
     $call<T>(func: (qb: this) => T): T;
     toOperationNode(): ColumnDefinitionNode;
 }
-export declare type ColumnDefinitionBuilderCallback = (builder: ColumnDefinitionBuilder) => ColumnDefinitionBuilder;
+export type ColumnDefinitionBuilderCallback = (builder: ColumnDefinitionBuilder) => ColumnDefinitionBuilder;

package/dist/cjs/schema/column-definition-builder.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ColumnDefinitionBuilder = void 0;
 const check_constraint_node_js_1 = require("../operation-node/check-constraint-node.js");
-const reference_node_js_1 = require("../operation-node/reference-node.js");
 const references_node_js_1 = require("../operation-node/references-node.js");
 const select_all_node_js_1 = require("../operation-node/select-all-node.js");
 const reference_parser_js_1 = require("../parser/reference-parser.js");
@@ -51,7 +50,7 @@ class ColumnDefinitionBuilder {
      */
     references(ref) {
         const references = (0, reference_parser_js_1.parseStringReference)(ref);
-        if (!reference_node_js_1.ReferenceNode.is(references) || select_all_node_js_1.SelectAllNode.is(references.column)) {
+        if (!references.table || select_all_node_js_1.SelectAllNode.is(references.column)) {
             throw new Error(`invalid call references('${ref}'). The reference must have format table.column or schema.table.column`);
         }
         return new ColumnDefinitionBuilder(column_definition_node_js_1.ColumnDefinitionNode.cloneWith(this.#node, {

package/dist/cjs/schema/create-index-builder.d.ts

@@ -1,5 +1,6 @@
 import { CreateIndexNode, IndexType } from '../operation-node/create-index-node.js';
 import { OperationNodeSource } from '../operation-node/operation-node-source.js';
+import { ExtractColumnNameFromOrderedColumnName, OrderedColumnName } from '../parser/reference-parser.js';
 import { CompiledQuery } from '../query-compiler/compiled-query.js';
 import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
@@ -7,7 +8,7 @@ import { QueryId } from '../util/query-id.js';
 import { Expression } from '../expression/expression.js';
 import { ComparisonOperatorExpression } from '../parser/binary-operation-parser.js';
 import { ExpressionBuilder } from '../expression/expression-builder.js';
-import { SqlBool } from '../util/type-utils.js';
+import { ShallowRecord, SqlBool } from '../util/type-utils.js';
 export declare class CreateIndexBuilder<C = never> implements OperationNodeSource, Compilable {
     #private;
     constructor(props: CreateIndexBuilderProps);
@@ -26,17 +27,52 @@ export declare class CreateIndexBuilder<C = never> implements OperationNodeSourc
      */
     on(table: string): CreateIndexBuilder<C>;
     /**
-     * Specifies the column for the index.
+     * Adds a column to the index.
      *
-     * Also see the `expression` for specifying an arbitrary expression.
+     * Also see {@link columns} for adding multiple columns at once or {@link expression}
+     * for specifying an arbitrary expression.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.schema
+     *         .createIndex('person_first_name_and_age_index')
+     *         .on('person')
+     *         .column('first_name')
+     *         .column('age desc')
+     *         .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * create index "person_first_name_and_age_index" on "person" ("first_name", "age" desc)
+     * ```
      */
-    column<CL extends string>(column: CL): CreateIndexBuilder<C | CL>;
+    column<CL extends string>(column: OrderedColumnName<CL>): CreateIndexBuilder<C | ExtractColumnNameFromOrderedColumnName<CL>>;
     /**
      * Specifies a list of columns for the index.
      *
-     * Also see the `expression` for specifying an arbitrary expression.
+     * Also see {@link column} for adding a single column or {@link expression} for
+     * specifying an arbitrary expression.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.schema
+     *         .createIndex('person_first_name_and_age_index')
+     *         .on('person')
+     *         .columns(['first_name', 'age desc'])
+     *         .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * create index "person_first_name_and_age_index" on "person" ("first_name", "age" desc)
+     * ```
      */
-    columns<CL extends string>(columns: CL[]): CreateIndexBuilder<C | CL>;
+    columns<CL extends string>(columns: OrderedColumnName<CL>[]): CreateIndexBuilder<C | ExtractColumnNameFromOrderedColumnName<CL>>;
     /**
      * Specifies an arbitrary expression for the index.
      *
@@ -51,6 +87,12 @@ export declare class CreateIndexBuilder<C = never> implements OperationNodeSourc
      *   .expression(sql`first_name COLLATE "fi_FI"`)
      *   .execute()
      * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * create index "person_first_name_index" on "person" (first_name COLLATE "fi_FI")
+     * ```
      */
     expression(expression: Expression<any>): CreateIndexBuilder<C>;
     /**
@@ -90,7 +132,7 @@ export declare class CreateIndexBuilder<C = never> implements OperationNodeSourc
      * Parameters are always sent as literals due to database restrictions.
      */
     where(lhs: C | Expression<any>, op: ComparisonOperatorExpression, rhs: unknown): CreateIndexBuilder<C>;
-    where(factory: (qb: ExpressionBuilder<Record<string, Record<C & string, any>>, string>) => Expression<SqlBool>): CreateIndexBuilder<C>;
+    where(factory: (qb: ExpressionBuilder<ShallowRecord<string, ShallowRecord<C & string, any>>, string>) => Expression<SqlBool>): CreateIndexBuilder<C>;
     where(expression: Expression<any>): CreateIndexBuilder<C>;
     /**
      * Simply calls the provided function passing `this` as the only argument. `$call` returns