kysely 0.27.5 → 0.28.0

package/dist/esm/query-builder/merge-query-builder.d.ts

@@ -7,7 +7,8 @@ import { ExpressionOrFactory } from '../parser/expression-parser.js';
 import { InsertObjectOrList, InsertObjectOrListFactory } from '../parser/insert-values-parser.js';
 import { JoinCallbackExpression, JoinReferenceExpression } from '../parser/join-parser.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
-import { ReturningAllRow, ReturningRow } from '../parser/returning-parser.js';
+import { ReturningAllRow, ReturningCallbackRow, ReturningRow } from '../parser/returning-parser.js';
+import { SelectCallback, SelectExpression } from '../parser/select-parser.js';
 import { TableExpression } from '../parser/table-parser.js';
 import { ExtractUpdateTypeFromReferenceExpression, UpdateObject, UpdateObjectFactory } from '../parser/update-set-parser.js';
 import { ValueExpression } from '../parser/value-parser.js';
@@ -19,8 +20,9 @@ import { ShallowRecord, SimplifyResult, SimplifySingleResult, SqlBool } from '..
 import { MergeResult } from './merge-result.js';
 import { NoResultErrorConstructor } from './no-result-error.js';
 import { OutputCallback, OutputExpression, OutputInterface, OutputPrefix, SelectExpressionFromOutputCallback, SelectExpressionFromOutputExpression } from './output-interface.js';
+import { MultiTableReturningInterface } from './returning-interface.js';
 import { UpdateQueryBuilder } from './update-query-builder.js';
-export declare class MergeQueryBuilder<DB, TT extends keyof DB, O> implements OutputInterface<DB, TT, O> {
+export declare class MergeQueryBuilder<DB, TT extends keyof DB, O> implements MultiTableReturningInterface<DB, TT, O>, OutputInterface<DB, TT, O> {
     #private;
     constructor(props: MergeQueryBuilderProps);
     /**
@@ -122,6 +124,76 @@ export declare class MergeQueryBuilder<DB, TT extends keyof DB, O> implements Ou
      */
     using<TE extends TableExpression<DB, TT>, K1 extends JoinReferenceExpression<DB, TT, TE>, K2 extends JoinReferenceExpression<DB, TT, TE>>(sourceTable: TE, k1: K1, k2: K2): ExtractWheneableMergeQueryBuilder<DB, TT, TE, O>;
     using<TE extends TableExpression<DB, TT>, FN extends JoinCallbackExpression<DB, TT, TE>>(sourceTable: TE, callback: FN): ExtractWheneableMergeQueryBuilder<DB, TT, TE, O>;
+    /**
+     * Allows you to return data from modified rows.
+     *
+     * On supported databases like PostgreSQL, this method can be chained to
+     * `insert`, `update`, `delete` and `merge` queries to return data.
+     *
+     * Note that on SQLite you need to give aliases for the expressions to avoid
+     * [this bug](https://sqlite.org/forum/forumpost/033daf0b32) in SQLite.
+     * For example `.returning('id as id')`.
+     *
+     * Also see the {@link returningAll} method.
+     *
+     * ### Examples
+     *
+     * Return one column:
+     *
+     * ```ts
+     * const { id } = await db
+     *   .insertInto('person')
+     *   .values({
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston'
+     *   })
+     *   .returning('id')
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * Return multiple columns:
+     *
+     * ```ts
+     * const { id, last_name } = await db
+     *   .insertInto('person')
+     *   .values({
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston'
+     *   })
+     *   .returning(['id', 'last_name'])
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * Return arbitrary expressions:
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const { id, full_name, first_pet_id } = await db
+     *   .insertInto('person')
+     *   .values({
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston'
+     *   })
+     *   .returning((eb) => [
+     *     'id as id',
+     *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name'),
+     *     eb.selectFrom('pet').select('pet.id').limit(1).as('first_pet_id')
+     *   ])
+     *   .executeTakeFirstOrThrow()
+     * ```
+     */
+    returning<SE extends SelectExpression<DB, TT>>(selections: ReadonlyArray<SE>): MergeQueryBuilder<DB, TT, ReturningRow<DB, TT, O, SE>>;
+    returning<CB extends SelectCallback<DB, TT>>(callback: CB): MergeQueryBuilder<DB, TT, ReturningCallbackRow<DB, TT, O, CB>>;
+    returning<SE extends SelectExpression<DB, TT>>(selection: SE): MergeQueryBuilder<DB, TT, ReturningRow<DB, TT, O, SE>>;
+    /**
+     * Adds a `returning *` or `returning table.*` to an insert/update/delete/merge
+     * query on databases that support `returning` such as PostgreSQL.
+     *
+     * Also see the {@link returning} method.
+     */
+    returningAll<T extends TT>(table: T): MergeQueryBuilder<DB, TT, ReturningAllRow<DB, T, O>>;
+    returningAll(): MergeQueryBuilder<DB, TT, ReturningAllRow<DB, TT, O>>;
     /**
      * Allows you to return data from modified rows.
      *
@@ -252,7 +324,7 @@ export interface MergeQueryBuilderProps {
     readonly queryNode: MergeQueryNode;
     readonly executor: QueryExecutor;
 }
-export declare class WheneableMergeQueryBuilder<DB, TT extends keyof DB, ST extends keyof DB, O> implements Compilable<O>, OutputInterface<DB, TT, O>, OperationNodeSource {
+export declare class WheneableMergeQueryBuilder<DB, TT extends keyof DB, ST extends keyof DB, O> implements Compilable<O>, MultiTableReturningInterface<DB, TT | ST, O>, OutputInterface<DB, TT, O>, OperationNodeSource {
     #private;
     constructor(props: MergeQueryBuilderProps);
     /**
@@ -449,6 +521,76 @@ export declare class WheneableMergeQueryBuilder<DB, TT extends keyof DB, ST exte
      * the target table, and not from source table and returns a {@link MatchedThenableMergeQueryBuilder}.
      */
     whenNotMatchedBySourceAndRef<LRE extends ReferenceExpression<DB, TT>, RRE extends ReferenceExpression<DB, TT>>(lhs: LRE, op: ComparisonOperatorExpression, rhs: RRE): MatchedThenableMergeQueryBuilder<DB, TT, ST, TT, O>;
+    /**
+     * Allows you to return data from modified rows.
+     *
+     * On supported databases like PostgreSQL, this method can be chained to
+     * `insert`, `update`, `delete` and `merge` queries to return data.
+     *
+     * Note that on SQLite you need to give aliases for the expressions to avoid
+     * [this bug](https://sqlite.org/forum/forumpost/033daf0b32) in SQLite.
+     * For example `.returning('id as id')`.
+     *
+     * Also see the {@link returningAll} method.
+     *
+     * ### Examples
+     *
+     * Return one column:
+     *
+     * ```ts
+     * const { id } = await db
+     *   .insertInto('person')
+     *   .values({
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston'
+     *   })
+     *   .returning('id')
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * Return multiple columns:
+     *
+     * ```ts
+     * const { id, last_name } = await db
+     *   .insertInto('person')
+     *   .values({
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston'
+     *   })
+     *   .returning(['id', 'last_name'])
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * Return arbitrary expressions:
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const { id, full_name, first_pet_id } = await db
+     *   .insertInto('person')
+     *   .values({
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston'
+     *   })
+     *   .returning((eb) => [
+     *     'id as id',
+     *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name'),
+     *     eb.selectFrom('pet').select('pet.id').limit(1).as('first_pet_id')
+     *   ])
+     *   .executeTakeFirstOrThrow()
+     * ```
+     */
+    returning<SE extends SelectExpression<DB, TT | ST>>(selections: ReadonlyArray<SE>): WheneableMergeQueryBuilder<DB, TT, ST, ReturningRow<DB, TT | ST, O, SE>>;
+    returning<CB extends SelectCallback<DB, TT | ST>>(callback: CB): WheneableMergeQueryBuilder<DB, TT, ST, ReturningCallbackRow<DB, TT | ST, O, CB>>;
+    returning<SE extends SelectExpression<DB, TT | ST>>(selection: SE): WheneableMergeQueryBuilder<DB, TT, ST, ReturningRow<DB, TT | ST, O, SE>>;
+    /**
+     * Adds a `returning *` or `returning table.*` to an insert/update/delete/merge
+     * query on databases that support `returning` such as PostgreSQL.
+     *
+     * Also see the {@link returning} method.
+     */
+    returningAll<T extends TT | ST>(table: T): WheneableMergeQueryBuilder<DB, TT, ST, ReturningAllRow<DB, T, O>>;
+    returningAll(): WheneableMergeQueryBuilder<DB, TT, ST, ReturningAllRow<DB, TT | ST, O>>;
     /**
      * Allows you to return data from modified rows.
      *

package/dist/esm/query-builder/merge-query-builder.js

@@ -6,11 +6,10 @@ import { UpdateQueryNode } from '../operation-node/update-query-node.js';
 import { parseInsertExpression, } from '../parser/insert-values-parser.js';
 import { parseJoin, } from '../parser/join-parser.js';
 import { parseMergeThen, parseMergeWhen } from '../parser/merge-parser.js';
-import { parseSelectAll, parseSelectArg } from '../parser/select-parser.js';
+import { parseSelectAll, parseSelectArg, } from '../parser/select-parser.js';
 import { parseTop } from '../parser/top-parser.js';
 import { NOOP_QUERY_EXECUTOR } from '../query-executor/noop-query-executor.js';
 import { freeze } from '../util/object-utils.js';
-import { preventAwait } from '../util/prevent-await.js';
 import { MergeResult } from './merge-result.js';
 import { NoResultError, isNoResultErrorConstructor, } from './no-result-error.js';
 import { UpdateQueryBuilder } from './update-query-builder.js';
@@ -107,6 +106,18 @@ export class MergeQueryBuilder {
             queryNode: MergeQueryNode.cloneWithUsing(this.#props.queryNode, parseJoin('Using', args)),
         });
     }
+    returning(args) {
+        return new MergeQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithReturning(this.#props.queryNode, parseSelectArg(args)),
+        });
+    }
+    returningAll(table) {
+        return new MergeQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithReturning(this.#props.queryNode, parseSelectAll(table)),
+        });
+    }
     output(args) {
         return new MergeQueryBuilder({
             ...this.#props,
@@ -120,7 +131,6 @@ export class MergeQueryBuilder {
         });
     }
 }
-preventAwait(MergeQueryBuilder, "don't await MergeQueryBuilder instances directly. To execute the query you need to call `execute` when available.");
 export class WheneableMergeQueryBuilder {
     #props;
     constructor(props) {
@@ -285,6 +295,18 @@ export class WheneableMergeQueryBuilder {
     whenNotMatchedBySourceAndRef(lhs, op, rhs) {
         return this.#whenNotMatched([lhs, op, rhs], true, true);
     }
+    returning(args) {
+        return new WheneableMergeQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithReturning(this.#props.queryNode, parseSelectArg(args)),
+        });
+    }
+    returningAll(table) {
+        return new WheneableMergeQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithReturning(this.#props.queryNode, parseSelectAll(table)),
+        });
+    }
     output(args) {
         return new WheneableMergeQueryBuilder({
             ...this.#props,
@@ -395,8 +417,10 @@ export class WheneableMergeQueryBuilder {
     async execute() {
         const compiledQuery = this.compile();
         const result = await this.#props.executor.executeQuery(compiledQuery, this.#props.queryId);
-        if (compiledQuery.query.output &&
-            this.#props.executor.adapter.supportsOutput) {
+        const { adapter } = this.#props.executor;
+        const query = compiledQuery.query;
+        if ((query.returning && adapter.supportsReturning) ||
+            (query.output && adapter.supportsOutput)) {
             return result.rows;
         }
         return [new MergeResult(result.numAffectedRows)];
@@ -428,7 +452,6 @@ export class WheneableMergeQueryBuilder {
         return result;
     }
 }
-preventAwait(WheneableMergeQueryBuilder, "don't await WheneableMergeQueryBuilder instances directly. To execute the query you need to call `execute`.");
 export class MatchedThenableMergeQueryBuilder {
     #props;
     constructor(props) {
@@ -551,7 +574,6 @@ export class MatchedThenableMergeQueryBuilder {
         return this.thenUpdate((ub) => ub.set(...args));
     }
 }
-preventAwait(MatchedThenableMergeQueryBuilder, "don't await MatchedThenableMergeQueryBuilder instances directly. To execute the query you need to call `execute` when available.");
 export class NotMatchedThenableMergeQueryBuilder {
     #props;
     constructor(props) {
@@ -600,4 +622,3 @@ export class NotMatchedThenableMergeQueryBuilder {
         });
     }
 }
-preventAwait(NotMatchedThenableMergeQueryBuilder, "don't await NotMatchedThenableMergeQueryBuilder instances directly. To execute the query you need to call `execute` when available.");

package/dist/esm/query-builder/on-conflict-builder.js

@@ -5,7 +5,6 @@ import { OnConflictNode } from '../operation-node/on-conflict-node.js';
 import { parseValueBinaryOperationOrExpression, parseReferentialBinaryOperation, } from '../parser/binary-operation-parser.js';
 import { parseUpdateObjectExpression, } from '../parser/update-set-parser.js';
 import { freeze } from '../util/object-utils.js';
-import { preventAwait } from '../util/prevent-await.js';
 export class OnConflictBuilder {
     #props;
     constructor(props) {
@@ -205,7 +204,6 @@ export class OnConflictBuilder {
         return func(this);
     }
 }
-preventAwait(OnConflictBuilder, "don't await OnConflictBuilder instances.");
 export class OnConflictDoNothingBuilder {
     #props;
     constructor(props) {
@@ -215,7 +213,6 @@ export class OnConflictDoNothingBuilder {
         return this.#props.onConflictNode;
     }
 }
-preventAwait(OnConflictDoNothingBuilder, "don't await OnConflictDoNothingBuilder instances.");
 export class OnConflictUpdateBuilder {
     #props;
     constructor(props) {
@@ -255,4 +252,3 @@ export class OnConflictUpdateBuilder {
         return this.#props.onConflictNode;
     }
 }
-preventAwait(OnConflictUpdateBuilder, "don't await OnConflictUpdateBuilder instances.");

package/dist/esm/query-builder/order-by-interface.d.ts

@@ -0,0 +1,176 @@
+import { Expression } from '../expression/expression.js';
+import { OrderByExpression, DirectedOrderByStringReference, OrderByModifiers } from '../parser/order-by-parser.js';
+export interface OrderByInterface<DB, TB extends keyof DB, O> {
+    /**
+     * Adds an `order by` clause to the query.
+     *
+     * `orderBy` calls are additive. Meaning, additional `orderBy` calls append to
+     * the existing order by clause.
+     *
+     * `orderBy` is supported in select queries on all dialects. In MySQL, you can
+     * also use `orderBy` in update and delete queries.
+     *
+     * In a single call you can add a single column/expression or multiple columns/expressions.
+     *
+     * Single column/expression calls can have 1-2 arguments. The first argument is
+     * the expression to order by, while the second optional argument is the direction
+     * (`asc` or `desc`), a callback that accepts and returns an {@link OrderByItemBuilder}
+     * or an expression.
+     *
+     * See {@link clearOrderBy} to remove the `order by` clause from a query.
+     *
+     * ### Examples
+     *
+     * Single column/expression per call:
+     *
+     * ```ts
+     * await db
+     *   .selectFrom('person')
+     *   .select('person.first_name as fn')
+     *   .orderBy('id')
+     *   .orderBy('fn', 'desc')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person"."first_name" as "fn"
+     * from "person"
+     * order by "id", "fn" desc
+     * ```
+     *
+     * Multiple columns/expressions per call:
+     *
+     * ```ts
+     * await db
+     *   .selectFrom('person')
+     *   .select('person.first_name as fn')
+     *   .orderBy(['id', 'fn'])
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person"."first_name" as "fn"
+     * from "person"
+     * order by "id", "fn"
+     * ```
+     *
+     * Building advanced modifiers:
+     *
+     * ```ts
+     * await db
+     *   .selectFrom('person')
+     *   .select('person.first_name as fn')
+     *   .orderBy('id', (ob) => ob.desc().nullsFirst())
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person"."first_name" as "fn"
+     * from "person"
+     * order by "id" desc nulls first
+     * ```
+     *
+     * The order by expression can also be a raw sql expression or a subquery
+     * in addition to column references:
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * await db
+     *   .selectFrom('person')
+     *   .selectAll()
+     *   .orderBy((eb) => eb.selectFrom('pet')
+     *     .select('pet.name')
+     *     .whereRef('pet.owner_id', '=', 'person.id')
+     *     .limit(1)
+     *   )
+     *   .orderBy(
+     *     sql<string>`concat(first_name, last_name) asc`
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select *
+     * from "person"
+     * order by
+     *   ( select "pet"."name"
+     *     from "pet"
+     *     where "pet"."owner_id" = "person"."id"
+     *     limit $1
+     *   ) asc,
+     *   concat(first_name, last_name) asc
+     * ```
+     *
+     * `dynamic.ref` can be used to refer to columns not known at
+     * compile time:
+     *
+     * ```ts
+     * async function someQuery(orderBy: string) {
+     *   const { ref } = db.dynamic
+     *
+     *   return await db
+     *     .selectFrom('person')
+     *     .select('person.first_name as fn')
+     *     .orderBy(ref(orderBy))
+     *     .execute()
+     * }
+     *
+     * someQuery('fn')
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person"."first_name" as "fn"
+     * from "person"
+     * order by "fn"
+     * ```
+     */
+    orderBy<OE extends OrderByExpression<DB, TB, O>>(expr: OE, modifiers?: OrderByModifiers): OrderByInterface<DB, TB, O>;
+    /**
+     * @deprecated It does ~2-2.6x more compile-time instantiations compared to multiple chained `orderBy(expr, modifiers?)` calls (in `order by` clauses with reasonable item counts), and has broken autocompletion.
+     */
+    orderBy<OE extends OrderByExpression<DB, TB, O> | DirectedOrderByStringReference<DB, TB, O>>(exprs: ReadonlyArray<OE>): OrderByInterface<DB, TB, O>;
+    /**
+     * @deprecated It does ~2.9x more compile-time instantiations compared to a `orderBy(expr, direction)` call.
+     */
+    orderBy<OE extends DirectedOrderByStringReference<DB, TB, O>>(expr: OE): OrderByInterface<DB, TB, O>;
+    /**
+     * @deprecated Use `orderBy(expr, (ob) => ...)` instead.
+     */
+    orderBy<OE extends OrderByExpression<DB, TB, O>>(expr: OE, modifiers: Expression<any>): OrderByInterface<DB, TB, O>;
+    /**
+     * Clears the `order by` clause from the query.
+     *
+     * See {@link orderBy} for adding an `order by` clause or item to a query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const query = db
+     *   .selectFrom('person')
+     *   .selectAll()
+     *   .orderBy('id', 'desc')
+     *
+     * const results = await query
+     *   .clearOrderBy()
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select * from "person"
+     * ```
+     */
+    clearOrderBy(): OrderByInterface<DB, TB, O>;
+}

package/dist/esm/query-builder/order-by-interface.js

@@ -0,0 +1,2 @@
+/// <reference types="./order-by-interface.d.ts" />
+export {};

package/dist/esm/query-builder/order-by-item-builder.d.ts

@@ -0,0 +1,43 @@
+import { OperationNodeSource } from '../operation-node/operation-node-source.js';
+import { OrderByItemNode } from '../operation-node/order-by-item-node.js';
+import { Collation } from '../parser/collate-parser.js';
+export declare class OrderByItemBuilder implements OperationNodeSource {
+    #private;
+    constructor(props: OrderByItemBuilderProps);
+    /**
+     * Adds `desc` to the `order by` item.
+     *
+     * See {@link asc} for the opposite.
+     */
+    desc(): OrderByItemBuilder;
+    /**
+     * Adds `asc` to the `order by` item.
+     *
+     * See {@link desc} for the opposite.
+     */
+    asc(): OrderByItemBuilder;
+    /**
+     * Adds `nulls last` to the `order by` item.
+     *
+     * This is only supported by some dialects like PostgreSQL and SQLite.
+     *
+     * See {@link nullsFirst} for the opposite.
+     */
+    nullsLast(): OrderByItemBuilder;
+    /**
+     * Adds `nulls first` to the `order by` item.
+     *
+     * This is only supported by some dialects like PostgreSQL and SQLite.
+     *
+     * See {@link nullsLast} for the opposite.
+     */
+    nullsFirst(): OrderByItemBuilder;
+    /**
+     * Adds `collate <collationName>` to the `order by` item.
+     */
+    collate(collation: Collation): OrderByItemBuilder;
+    toOperationNode(): OrderByItemNode;
+}
+export interface OrderByItemBuilderProps {
+    readonly node: OrderByItemNode;
+}

package/dist/esm/query-builder/order-by-item-builder.js

@@ -0,0 +1,72 @@
+/// <reference types="./order-by-item-builder.d.ts" />
+import { CollateNode } from '../operation-node/collate-node.js';
+import { OrderByItemNode } from '../operation-node/order-by-item-node.js';
+import { RawNode } from '../operation-node/raw-node.js';
+import { freeze } from '../util/object-utils.js';
+export class OrderByItemBuilder {
+    #props;
+    constructor(props) {
+        this.#props = freeze(props);
+    }
+    /**
+     * Adds `desc` to the `order by` item.
+     *
+     * See {@link asc} for the opposite.
+     */
+    desc() {
+        return new OrderByItemBuilder({
+            node: OrderByItemNode.cloneWith(this.#props.node, {
+                direction: RawNode.createWithSql('desc'),
+            }),
+        });
+    }
+    /**
+     * Adds `asc` to the `order by` item.
+     *
+     * See {@link desc} for the opposite.
+     */
+    asc() {
+        return new OrderByItemBuilder({
+            node: OrderByItemNode.cloneWith(this.#props.node, {
+                direction: RawNode.createWithSql('asc'),
+            }),
+        });
+    }
+    /**
+     * Adds `nulls last` to the `order by` item.
+     *
+     * This is only supported by some dialects like PostgreSQL and SQLite.
+     *
+     * See {@link nullsFirst} for the opposite.
+     */
+    nullsLast() {
+        return new OrderByItemBuilder({
+            node: OrderByItemNode.cloneWith(this.#props.node, { nulls: 'last' }),
+        });
+    }
+    /**
+     * Adds `nulls first` to the `order by` item.
+     *
+     * This is only supported by some dialects like PostgreSQL and SQLite.
+     *
+     * See {@link nullsLast} for the opposite.
+     */
+    nullsFirst() {
+        return new OrderByItemBuilder({
+            node: OrderByItemNode.cloneWith(this.#props.node, { nulls: 'first' }),
+        });
+    }
+    /**
+     * Adds `collate <collationName>` to the `order by` item.
+     */
+    collate(collation) {
+        return new OrderByItemBuilder({
+            node: OrderByItemNode.cloneWith(this.#props.node, {
+                collation: CollateNode.create(collation),
+            }),
+        });
+    }
+    toOperationNode() {
+        return this.#props.node;
+    }
+}

package/dist/esm/query-builder/over-builder.d.ts

@@ -1,14 +1,14 @@
-import { DynamicReferenceBuilder } from '../dynamic/dynamic-reference-builder.js';
+import { Expression } from '../expression/expression.js';
 import { OperationNodeSource } from '../operation-node/operation-node-source.js';
 import { OverNode } from '../operation-node/over-node.js';
-import { OrderByDirectionExpression } from '../parser/order-by-parser.js';
+import { DirectedOrderByStringReference, OrderByExpression, OrderByModifiers } from '../parser/order-by-parser.js';
 import { PartitionByExpression } from '../parser/partition-by-parser.js';
-import { StringReference } from '../parser/reference-parser.js';
-export declare class OverBuilder<DB, TB extends keyof DB> implements OperationNodeSource {
+import { OrderByInterface } from './order-by-interface.js';
+export declare class OverBuilder<DB, TB extends keyof DB> implements OrderByInterface<DB, TB, {}>, OperationNodeSource {
     #private;
     constructor(props: OverBuilderProps);
     /**
-     * Adds an order by clause item inside the over function.
+     * Adds an `order by` clause or item inside the `over` function.
      *
      * ```ts
      * const result = await db
@@ -28,7 +28,44 @@ export declare class OverBuilder<DB, TB extends keyof DB> implements OperationNo
      * from "person"
      * ```
      */
-    orderBy<OE extends StringReference<DB, TB> | DynamicReferenceBuilder<any>>(orderBy: OE, direction?: OrderByDirectionExpression): OverBuilder<DB, TB>;
+    orderBy<OE extends OrderByExpression<DB, TB, {}>>(expr: OE, modifiers?: OrderByModifiers): OverBuilder<DB, TB>;
+    /**
+     * @deprecated It does ~2-2.6x more compile-time instantiations compared to multiple chained `orderBy(expr, modifiers?)` calls (in `order by` clauses with reasonable item counts), and has broken autocompletion.
+     */
+    orderBy<OE extends OrderByExpression<DB, TB, {}> | DirectedOrderByStringReference<DB, TB, {}>>(exprs: ReadonlyArray<OE>): OverBuilder<DB, TB>;
+    /**
+     * @deprecated It does ~2.9x more compile-time instantiations compared to a `orderBy(expr, direction)` call.
+     */
+    orderBy<OE extends DirectedOrderByStringReference<DB, TB, {}>>(expr: OE): OverBuilder<DB, TB>;
+    /**
+     * @deprecated Use `orderBy(expr, (ob) => ...)` instead.
+     */
+    orderBy<OE extends OrderByExpression<DB, TB, {}>>(expr: OE, modifiers: Expression<any>): OverBuilder<DB, TB>;
+    /**
+     * Clears the `order by` clause from the query.
+     *
+     * See {@link orderBy} for adding an `order by` clause or item to a query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const query = db
+     *   .selectFrom('person')
+     *   .selectAll()
+     *   .orderBy('id', 'desc')
+     *
+     * const results = await query
+     *   .clearOrderBy()
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select * from "person"
+     * ```
+     */
+    clearOrderBy(): OverBuilder<DB, TB>;
     /**
      * Adds partition by clause item/s inside the over function.
      *