kysely 0.27.6 → 0.28.1

package/dist/esm/plugin/handle-empty-in-lists/handle-empty-in-lists.d.ts

@@ -0,0 +1,44 @@
+import { BinaryOperationNode } from '../../operation-node/binary-operation-node.js';
+import { OperatorNode } from '../../operation-node/operator-node.js';
+import { PrimitiveValueListNode } from '../../operation-node/primitive-value-list-node.js';
+import { ValueListNode } from '../../operation-node/value-list-node.js';
+export interface HandleEmptyInListsOptions {
+    /**
+     * The strategy to use when handling `in ()` and `not in ()`.
+     *
+     * See {@link HandleEmptyInListsPlugin} for examples.
+     */
+    strategy: EmptyInListsStrategy;
+}
+export type EmptyInListNode = BinaryOperationNode & {
+    operator: OperatorNode & {
+        operator: 'in' | 'not in';
+    };
+    rightOperand: (ValueListNode | PrimitiveValueListNode) & {
+        values: Readonly<[]>;
+    };
+};
+export type EmptyInListsStrategy = (node: EmptyInListNode) => BinaryOperationNode;
+/**
+ * Replaces the `in`/`not in` expression with a noncontingent expression (always true or always
+ * false) depending on the original operator.
+ *
+ * This is how Knex.js, PrismaORM, Laravel, and SQLAlchemy handle `in ()` and `not in ()`.
+ *
+ * See {@link pushValueIntoList} for an alternative strategy.
+ */
+export declare function replaceWithNoncontingentExpression(node: EmptyInListNode): BinaryOperationNode;
+/**
+ * When `in`, pushes a `null` value into the list resulting in `in (null)`. This
+ * is how TypeORM and Sequelize handle `in ()`. `in (null)` is logically the equivalent
+ * of `= null`, which returns `null`, which is a falsy expression in most SQL databases.
+ * We recommend NOT using this strategy if you plan to use `in` in `select`, `returning`,
+ * or `output` clauses, as the return type differs from the `SqlBool` default type.
+ *
+ * When `not in`, casts the left operand as `char` and pushes a literal value into
+ * the list resulting in `cast({{lhs}} as char) not in ({{VALUE}})`. Casting
+ * is required to avoid database errors with non-string columns.
+ *
+ * See {@link replaceWithNoncontingentExpression} for an alternative strategy.
+ */
+export declare function pushValueIntoList(uniqueNotInLiteral: '__kysely_no_values_were_provided__' | (string & {})): EmptyInListsStrategy;

package/dist/esm/plugin/handle-empty-in-lists/handle-empty-in-lists.js

@@ -0,0 +1,63 @@
+/// <reference types="./handle-empty-in-lists.d.ts" />
+import { BinaryOperationNode } from '../../operation-node/binary-operation-node.js';
+import { CastNode } from '../../operation-node/cast-node.js';
+import { DataTypeNode } from '../../operation-node/data-type-node.js';
+import { OperatorNode } from '../../operation-node/operator-node.js';
+import { ValueListNode } from '../../operation-node/value-list-node.js';
+import { ValueNode } from '../../operation-node/value-node.js';
+import { freeze } from '../../util/object-utils.js';
+let contradiction;
+let eq;
+let one;
+let tautology;
+/**
+ * Replaces the `in`/`not in` expression with a noncontingent expression (always true or always
+ * false) depending on the original operator.
+ *
+ * This is how Knex.js, PrismaORM, Laravel, and SQLAlchemy handle `in ()` and `not in ()`.
+ *
+ * See {@link pushValueIntoList} for an alternative strategy.
+ */
+export function replaceWithNoncontingentExpression(node) {
+    const _one = (one ||= ValueNode.createImmediate(1));
+    const _eq = (eq ||= OperatorNode.create('='));
+    if (node.operator.operator === 'in') {
+        return (contradiction ||= BinaryOperationNode.create(_one, _eq, ValueNode.createImmediate(0)));
+    }
+    return (tautology ||= BinaryOperationNode.create(_one, _eq, _one));
+}
+let char;
+let listNull;
+let listVal;
+/**
+ * When `in`, pushes a `null` value into the list resulting in `in (null)`. This
+ * is how TypeORM and Sequelize handle `in ()`. `in (null)` is logically the equivalent
+ * of `= null`, which returns `null`, which is a falsy expression in most SQL databases.
+ * We recommend NOT using this strategy if you plan to use `in` in `select`, `returning`,
+ * or `output` clauses, as the return type differs from the `SqlBool` default type.
+ *
+ * When `not in`, casts the left operand as `char` and pushes a literal value into
+ * the list resulting in `cast({{lhs}} as char) not in ({{VALUE}})`. Casting
+ * is required to avoid database errors with non-string columns.
+ *
+ * See {@link replaceWithNoncontingentExpression} for an alternative strategy.
+ */
+export function pushValueIntoList(uniqueNotInLiteral) {
+    return function pushValueIntoList(node) {
+        if (node.operator.operator === 'in') {
+            return freeze({
+                ...node,
+                rightOperand: (listNull ||= ValueListNode.create([
+                    ValueNode.createImmediate(null),
+                ])),
+            });
+        }
+        return freeze({
+            ...node,
+            leftOperand: CastNode.create(node.leftOperand, (char ||= DataTypeNode.create('char'))),
+            rightOperand: (listVal ||= ValueListNode.create([
+                ValueNode.createImmediate(uniqueNotInLiteral),
+            ])),
+        });
+    };
+}

package/dist/esm/plugin/immediate-value/immediate-value-plugin.js

@@ -11,7 +11,7 @@ import { ImmediateValueTransformer } from './immediate-value-transformer.js';
 export class ImmediateValuePlugin {
     #transformer = new ImmediateValueTransformer();
     transformQuery(args) {
-        return this.#transformer.transformNode(args.node);
+        return this.#transformer.transformNode(args.node, args.queryId);
     }
     transformResult(args) {
         return Promise.resolve(args.result);

package/dist/esm/plugin/immediate-value/immediate-value-transformer.d.ts

@@ -1,4 +1,5 @@
 import { OperationNodeTransformer } from '../../operation-node/operation-node-transformer.js';
+import { PrimitiveValueListNode } from '../../operation-node/primitive-value-list-node.js';
 import { ValueNode } from '../../operation-node/value-node.js';
 /**
  * Transforms all ValueNodes to immediate.
@@ -9,5 +10,6 @@ import { ValueNode } from '../../operation-node/value-node.js';
  * @internal
  */
 export declare class ImmediateValueTransformer extends OperationNodeTransformer {
+    transformPrimitiveValueList(node: PrimitiveValueListNode): PrimitiveValueListNode;
     transformValue(node: ValueNode): ValueNode;
 }

package/dist/esm/plugin/immediate-value/immediate-value-transformer.js

@@ -1,5 +1,7 @@
 /// <reference types="./immediate-value-transformer.d.ts" />
 import { OperationNodeTransformer } from '../../operation-node/operation-node-transformer.js';
+import { ValueListNode } from '../../operation-node/value-list-node.js';
+import { ValueNode } from '../../operation-node/value-node.js';
 /**
  * Transforms all ValueNodes to immediate.
  *
@@ -9,10 +11,10 @@ import { OperationNodeTransformer } from '../../operation-node/operation-node-tr
  * @internal
  */
 export class ImmediateValueTransformer extends OperationNodeTransformer {
+    transformPrimitiveValueList(node) {
+        return ValueListNode.create(node.values.map(ValueNode.createImmediate));
+    }
     transformValue(node) {
-        return {
-            ...super.transformValue(node),
-            immediate: true,
-        };
+        return ValueNode.createImmediate(node.value);
     }
 }

package/dist/esm/plugin/with-schema/with-schema-plugin.js

@@ -6,7 +6,7 @@ export class WithSchemaPlugin {
         this.#transformer = new WithSchemaTransformer(schema);
     }
     transformQuery(args) {
-        return this.#transformer.transformNode(args.node);
+        return this.#transformer.transformNode(args.node, args.queryId);
     }
     async transformResult(args) {
         return args.result;

package/dist/esm/plugin/with-schema/with-schema-transformer.d.ts

@@ -4,12 +4,13 @@ import { OperationNodeTransformer } from '../../operation-node/operation-node-tr
 import { OperationNode } from '../../operation-node/operation-node.js';
 import { ReferencesNode } from '../../operation-node/references-node.js';
 import { SchemableIdentifierNode } from '../../operation-node/schemable-identifier-node.js';
+import { QueryId } from '../../util/query-id.js';
 export declare class WithSchemaTransformer extends OperationNodeTransformer {
     #private;
     constructor(schema: string);
-    protected transformNodeImpl<T extends OperationNode>(node: T): T;
-    protected transformSchemableIdentifier(node: SchemableIdentifierNode): SchemableIdentifierNode;
-    protected transformReferences(node: ReferencesNode): ReferencesNode;
-    protected transformAggregateFunction(node: AggregateFunctionNode): AggregateFunctionNode;
-    protected transformFunction(node: FunctionNode): FunctionNode;
+    protected transformNodeImpl<T extends OperationNode>(node: T, queryId: QueryId): T;
+    protected transformSchemableIdentifier(node: SchemableIdentifierNode, queryId: QueryId): SchemableIdentifierNode;
+    protected transformReferences(node: ReferencesNode, queryId: QueryId): ReferencesNode;
+    protected transformAggregateFunction(node: AggregateFunctionNode, queryId: QueryId): AggregateFunctionNode;
+    protected transformFunction(node: FunctionNode, queryId: QueryId): FunctionNode;
 }

package/dist/esm/plugin/with-schema/with-schema-transformer.js

@@ -1,6 +1,7 @@
 /// <reference types="./with-schema-transformer.d.ts" />
 import { AliasNode } from '../../operation-node/alias-node.js';
 import { IdentifierNode } from '../../operation-node/identifier-node.js';
+import { ListNode } from '../../operation-node/list-node.js';
 import { OperationNodeTransformer } from '../../operation-node/operation-node-transformer.js';
 import { SchemableIdentifierNode } from '../../operation-node/schemable-identifier-node.js';
 import { TableNode } from '../../operation-node/table-node.js';
@@ -17,6 +18,7 @@ const ROOT_OPERATION_NODES = freeze({
     CreateTableNode: true,
     CreateTypeNode: true,
     CreateViewNode: true,
+    RefreshMaterializedViewNode: true,
     DeleteQueryNode: true,
     DropIndexNode: true,
     DropSchemaNode: true,
@@ -41,9 +43,9 @@ export class WithSchemaTransformer extends OperationNodeTransformer {
         super();
         this.#schema = schema;
     }
-    transformNodeImpl(node) {
+    transformNodeImpl(node, queryId) {
         if (!this.#isRootOperationNode(node)) {
-            return super.transformNodeImpl(node);
+            return super.transformNodeImpl(node, queryId);
         }
         const ctes = this.#collectCTEs(node);
         for (const cte of ctes) {
@@ -53,7 +55,7 @@ export class WithSchemaTransformer extends OperationNodeTransformer {
         for (const table of tables) {
             this.#schemableIds.add(table);
         }
-        const transformed = super.transformNodeImpl(node);
+        const transformed = super.transformNodeImpl(node, queryId);
         for (const table of tables) {
             this.#schemableIds.delete(table);
         }
@@ -62,8 +64,8 @@ export class WithSchemaTransformer extends OperationNodeTransformer {
         }
         return transformed;
     }
-    transformSchemableIdentifier(node) {
-        const transformed = super.transformSchemableIdentifier(node);
+    transformSchemableIdentifier(node, queryId) {
+        const transformed = super.transformSchemableIdentifier(node, queryId);
         if (transformed.schema || !this.#schemableIds.has(node.identifier.name)) {
             return transformed;
         }
@@ -72,8 +74,8 @@ export class WithSchemaTransformer extends OperationNodeTransformer {
             schema: IdentifierNode.create(this.#schema),
         };
     }
-    transformReferences(node) {
-        const transformed = super.transformReferences(node);
+    transformReferences(node, queryId) {
+        const transformed = super.transformReferences(node, queryId);
         if (transformed.table.table.schema) {
             return transformed;
         }
@@ -82,27 +84,27 @@ export class WithSchemaTransformer extends OperationNodeTransformer {
             table: TableNode.createWithSchema(this.#schema, transformed.table.table.identifier.name),
         };
     }
-    transformAggregateFunction(node) {
+    transformAggregateFunction(node, queryId) {
         return {
-            ...super.transformAggregateFunction({ ...node, aggregated: [] }),
-            aggregated: this.#transformTableArgsWithoutSchemas(node, 'aggregated'),
+            ...super.transformAggregateFunction({ ...node, aggregated: [] }, queryId),
+            aggregated: this.#transformTableArgsWithoutSchemas(node, queryId, 'aggregated'),
         };
     }
-    transformFunction(node) {
+    transformFunction(node, queryId) {
         return {
-            ...super.transformFunction({ ...node, arguments: [] }),
-            arguments: this.#transformTableArgsWithoutSchemas(node, 'arguments'),
+            ...super.transformFunction({ ...node, arguments: [] }, queryId),
+            arguments: this.#transformTableArgsWithoutSchemas(node, queryId, 'arguments'),
         };
     }
-    #transformTableArgsWithoutSchemas(node, argsKey) {
+    #transformTableArgsWithoutSchemas(node, queryId, argsKey) {
         return SCHEMALESS_FUNCTIONS[node.func]
             ? node[argsKey].map((arg) => !TableNode.is(arg) || arg.table.schema
-                ? this.transformNode(arg)
+                ? this.transformNode(arg, queryId)
                 : {
                     ...arg,
-                    table: this.transformIdentifier(arg.table.identifier),
+                    table: this.transformIdentifier(arg.table.identifier, queryId),
                 })
-            : this.transformNodeList(node[argsKey]);
+            : this.transformNodeList(node[argsKey], queryId);
     }
     #isRootOperationNode(node) {
         return node.kind in ROOT_OPERATION_NODES;
@@ -141,13 +143,16 @@ export class WithSchemaTransformer extends OperationNodeTransformer {
         return ctes;
     }
     #collectSchemableIdsFromTableExpr(node, schemableIds) {
-        const table = TableNode.is(node)
-            ? node
-            : AliasNode.is(node) && TableNode.is(node.node)
-                ? node.node
-                : null;
-        if (table) {
-            this.#collectSchemableId(table.table, schemableIds);
+        if (TableNode.is(node)) {
+            this.#collectSchemableId(node.table, schemableIds);
+        }
+        else if (AliasNode.is(node) && TableNode.is(node.node)) {
+            this.#collectSchemableId(node.node.table, schemableIds);
+        }
+        else if (ListNode.is(node)) {
+            for (const table of node.items) {
+                this.#collectSchemableIdsFromTableExpr(table, schemableIds);
+            }
         }
     }
     #collectSchemableId(node, schemableIds) {

package/dist/esm/query-builder/aggregate-function-builder.d.ts

@@ -2,13 +2,13 @@ import { AggregateFunctionNode } from '../operation-node/aggregate-function-node
 import { AliasNode } from '../operation-node/alias-node.js';
 import { OverBuilder } from './over-builder.js';
 import { AliasableExpression, AliasedExpression, Expression } from '../expression/expression.js';
-import { ReferenceExpression, StringReference } from '../parser/reference-parser.js';
+import { ReferenceExpression } from '../parser/reference-parser.js';
 import { ComparisonOperatorExpression, OperandValueExpressionOrList } from '../parser/binary-operation-parser.js';
 import { SqlBool } from '../util/type-utils.js';
 import { ExpressionOrFactory } from '../parser/expression-parser.js';
-import { DynamicReferenceBuilder } from '../dynamic/dynamic-reference-builder.js';
-import { OrderByDirectionExpression } from '../parser/order-by-parser.js';
-export declare class AggregateFunctionBuilder<DB, TB extends keyof DB, O = unknown> implements AliasableExpression<O> {
+import { DirectedOrderByStringReference, OrderByExpression, OrderByModifiers } from '../parser/order-by-parser.js';
+import { OrderByInterface } from './order-by-interface.js';
+export declare class AggregateFunctionBuilder<DB, TB extends keyof DB, O = unknown> implements OrderByInterface<DB, TB, {}>, AliasableExpression<O> {
     #private;
     constructor(props: AggregateFunctionBuilderProps);
     /** @private */
@@ -108,7 +108,85 @@ export declare class AggregateFunctionBuilder<DB, TB extends keyof DB, O = unkno
      * inner join "pet" ON "pet"."owner_id" = "person"."id"
      * ```
      */
-    orderBy<OE extends StringReference<DB, TB> | DynamicReferenceBuilder<any>>(orderBy: OE, direction?: OrderByDirectionExpression): AggregateFunctionBuilder<DB, TB, O>;
+    orderBy<OE extends OrderByExpression<DB, TB, {}>>(expr: OE, modifiers?: OrderByModifiers): AggregateFunctionBuilder<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, {}> | DirectedOrderByStringReference<DB, TB, {}>>(exprs: ReadonlyArray<OE>): AggregateFunctionBuilder<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, {}>>(expr: OE): AggregateFunctionBuilder<DB, TB, O>;
+    /**
+     * @deprecated Use `orderBy(expr, (ob) => ...)` instead.
+     */
+    orderBy<OE extends OrderByExpression<DB, TB, {}>>(expr: OE, modifiers: Expression<any>): AggregateFunctionBuilder<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(): AggregateFunctionBuilder<DB, TB, O>;
+    /**
+     * Adds a `withing group` clause with a nested `order by` clause after the function.
+     *
+     * This is only supported by some dialects like PostgreSQL or MS SQL Server.
+     *
+     * ### Examples
+     *
+     * Most frequent person name:
+     *
+     * ```ts
+     * const result = await db
+     *   .selectFrom('person')
+     *   .select((eb) => [
+     *     eb.fn
+     *       .agg<string>('mode')
+     *       .withinGroupOrderBy('person.first_name')
+     *       .as('most_frequent_name')
+     *   ])
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select mode() within group (order by "person"."first_name") as "most_frequent_name"
+     * from "person"
+     * ```
+     */
+    withinGroupOrderBy<OE extends OrderByExpression<DB, TB, {}>>(expr: OE, modifiers?: OrderByModifiers): AggregateFunctionBuilder<DB, TB, O>;
+    /**
+     * @deprecated It does ~2-2.6x more compile-time instantiations compared to multiple chained `withinGroupOrderBy(expr, modifiers?)` calls (in `order by` clauses with reasonable item counts), and has broken autocompletion.
+     */
+    withinGroupOrderBy<OE extends OrderByExpression<DB, TB, {}> | DirectedOrderByStringReference<DB, TB, {}>>(exprs: ReadonlyArray<OE>): AggregateFunctionBuilder<DB, TB, O>;
+    /**
+     * @deprecated It does ~2.9x more compile-time instantiations compared to a `withinGroupOrderBy(expr, direction)` call.
+     */
+    withinGroupOrderBy<OE extends DirectedOrderByStringReference<DB, TB, {}>>(expr: OE): AggregateFunctionBuilder<DB, TB, O>;
+    /**
+     * @deprecated Use `withinGroupOrderBy(expr, (ob) => ...)` instead.
+     */
+    withinGroupOrderBy<OE extends OrderByExpression<DB, TB, {}>>(expr: OE, modifiers: Expression<any>): AggregateFunctionBuilder<DB, TB, O>;
     /**
      * Adds a `filter` clause with a nested `where` clause after the function.
      *

package/dist/esm/query-builder/aggregate-function-builder.js

@@ -3,10 +3,10 @@ import { freeze } from '../util/object-utils.js';
 import { AggregateFunctionNode } from '../operation-node/aggregate-function-node.js';
 import { AliasNode } from '../operation-node/alias-node.js';
 import { IdentifierNode } from '../operation-node/identifier-node.js';
-import { preventAwait } from '../util/prevent-await.js';
 import { createOverBuilder } from '../parser/parse-utils.js';
 import { parseReferentialBinaryOperation, parseValueBinaryOperationOrExpression, } from '../parser/binary-operation-parser.js';
 import { parseOrderBy, } from '../parser/order-by-parser.js';
+import { QueryNode } from '../operation-node/query-node.js';
 export class AggregateFunctionBuilder {
     #props;
     constructor(props) {
@@ -71,33 +71,22 @@ export class AggregateFunctionBuilder {
             aggregateFunctionNode: AggregateFunctionNode.cloneWithDistinct(this.#props.aggregateFunctionNode),
         });
     }
-    /**
-     * Adds an `order by` clause inside the aggregate function.
-     *
-     * ### Examples
-     *
-     * ```ts
-     * const result = await db
-     *   .selectFrom('person')
-     *   .innerJoin('pet', 'pet.owner_id', 'person.id')
-     *   .select((eb) =>
-     *     eb.fn.jsonAgg('pet').orderBy('pet.name').as('person_pets')
-     *   )
-     *   .executeTakeFirstOrThrow()
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select json_agg("pet" order by "pet"."name") as "person_pets"
-     * from "person"
-     * inner join "pet" ON "pet"."owner_id" = "person"."id"
-     * ```
-     */
-    orderBy(orderBy, direction) {
+    orderBy(...args) {
+        return new AggregateFunctionBuilder({
+            ...this.#props,
+            aggregateFunctionNode: QueryNode.cloneWithOrderByItems(this.#props.aggregateFunctionNode, parseOrderBy(args)),
+        });
+    }
+    clearOrderBy() {
+        return new AggregateFunctionBuilder({
+            ...this.#props,
+            aggregateFunctionNode: QueryNode.cloneWithoutOrderBy(this.#props.aggregateFunctionNode),
+        });
+    }
+    withinGroupOrderBy(...args) {
         return new AggregateFunctionBuilder({
             ...this.#props,
-            aggregateFunctionNode: AggregateFunctionNode.cloneWithOrderBy(this.#props.aggregateFunctionNode, parseOrderBy([orderBy, direction])),
+            aggregateFunctionNode: AggregateFunctionNode.cloneWithOrderBy(this.#props.aggregateFunctionNode, parseOrderBy(args), true),
         });
     }
     filterWhere(...args) {
@@ -225,7 +214,6 @@ export class AggregateFunctionBuilder {
         return this.#props.aggregateFunctionNode;
     }
 }
-preventAwait(AggregateFunctionBuilder, "don't await AggregateFunctionBuilder instances. They are never executed directly and are always just a part of a query.");
 /**
  * {@link AggregateFunctionBuilder} with an alias. The result of calling {@link AggregateFunctionBuilder.as}.
  */

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

@@ -1,6 +1,5 @@
 /// <reference types="./cte-builder.d.ts" />
 import { CommonTableExpressionNode } from '../operation-node/common-table-expression-node.js';
-import { preventAwait } from '../util/prevent-await.js';
 import { freeze } from '../util/object-utils.js';
 export class CTEBuilder {
     #props;
@@ -33,4 +32,3 @@ export class CTEBuilder {
         return this.#props.node;
     }
 }
-preventAwait(CTEBuilder, "don't await CTEBuilder instances. They are never executed directly and are always just a part of a query.");

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

@@ -12,11 +12,11 @@ import { QueryExecutor } from '../query-executor/query-executor.js';
 import { QueryId } from '../util/query-id.js';
 import { KyselyPlugin } from '../plugin/kysely-plugin.js';
 import { WhereInterface } from './where-interface.js';
-import { ReturningInterface } from './returning-interface.js';
+import { MultiTableReturningInterface } from './returning-interface.js';
 import { NoResultErrorConstructor } from './no-result-error.js';
 import { DeleteResult } from './delete-result.js';
 import { DeleteQueryNode } from '../operation-node/delete-query-node.js';
-import { OrderByDirectionExpression, OrderByExpression } from '../parser/order-by-parser.js';
+import { OrderByExpression, OrderByModifiers, DirectedOrderByStringReference } from '../parser/order-by-parser.js';
 import { Explainable, ExplainFormat } from '../util/explainable.js';
 import { AliasedExpression, Expression } from '../expression/expression.js';
 import { ComparisonOperatorExpression, OperandValueExpressionOrList } from '../parser/binary-operation-parser.js';
@@ -25,7 +25,8 @@ import { Streamable } from '../util/streamable.js';
 import { ExpressionOrFactory } from '../parser/expression-parser.js';
 import { ValueExpression } from '../parser/value-parser.js';
 import { OutputCallback, OutputExpression, OutputInterface, SelectExpressionFromOutputCallback, SelectExpressionFromOutputExpression } from './output-interface.js';
-export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements WhereInterface<DB, TB>, ReturningInterface<DB, TB, O>, OutputInterface<DB, TB, O, 'deleted'>, OperationNodeSource, Compilable<O>, Explainable, Streamable<O> {
+import { OrderByInterface } from './order-by-interface.js';
+export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements WhereInterface<DB, TB>, MultiTableReturningInterface<DB, TB, O>, OutputInterface<DB, TB, O, 'deleted'>, OrderByInterface<DB, TB, {}>, OperationNodeSource, Compilable<O>, Explainable, Streamable<O> {
     #private;
     constructor(props: DeleteQueryBuilderProps);
     /**
@@ -650,7 +651,7 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * Allows you to return data from modified rows.
      *
      * On supported databases like PostgreSQL, this method can be chained to
-     * `insert`, `update` and `delete` queries to return data.
+     * `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.
@@ -802,8 +803,8 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      */
     returningAll<T extends TB>(tables: ReadonlyArray<T>): DeleteQueryBuilder<DB, TB, ReturningAllRow<DB, T, O>>;
     /**
-     * Adds a `returning *` to an insert/update/delete query on databases
-     * that support `returning` such as PostgreSQL.
+     * 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.
      */
@@ -975,61 +976,49 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      */
     clearLimit(): DeleteQueryBuilder<DB, TB, O>;
     /**
-     * Clears the `order by` clause from the query.
-     *
-     * ### Examples
-     *
-     * ```ts
-     * await db.deleteFrom('pet')
-     *   .returningAll()
-     *   .where('name', '=', 'Max')
-     *   .orderBy('id')
-     *   .clearOrderBy()
-     *   .execute()
-     * ```
-     *
-     * The generated SQL(PostgreSQL):
-     *
-     * ```sql
-     * delete from "pet" where "name" = "Max" returning *
-     * ```
+     * @description This is only supported by some dialects like MySQL or SQLite with `SQLITE_ENABLE_UPDATE_DELETE_LIMIT`.
      */
-    clearOrderBy(): DeleteQueryBuilder<DB, TB, O>;
+    orderBy<OE extends OrderByExpression<DB, TB, {}>>(expr: OE, modifiers?: OrderByModifiers): DeleteQueryBuilder<DB, TB, O>;
     /**
-     * Adds an `order by` clause to the query.
-     *
-     * `orderBy` calls are additive. To order by multiple columns, call `orderBy`
-     * multiple times.
-     *
-     * The first argument is the expression to order by and the second is the
-     * order (`asc` or `desc`).
-     *
-     * An `order by` clause in a delete query is only supported by some dialects
-     * like MySQL.
+     * @description This is only supported by some dialects like MySQL or SQLite with `SQLITE_ENABLE_UPDATE_DELETE_LIMIT`.
+     * @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>): DeleteQueryBuilder<DB, TB, O>;
+    /**
+     * @description This is only supported by some dialects like MySQL or SQLite with `SQLITE_ENABLE_UPDATE_DELETE_LIMIT`.
+     * @deprecated It does ~2.9x more compile-time instantiations compared to a `orderBy(expr, direction)` call.
+     */
+    orderBy<OE extends DirectedOrderByStringReference<DB, TB, {}>>(expr: OE): DeleteQueryBuilder<DB, TB, O>;
+    /**
+     * @description This is only supported by some dialects like MySQL or SQLite with `SQLITE_ENABLE_UPDATE_DELETE_LIMIT`.
+     * @deprecated Use `orderBy(expr, (ob) => ...)` instead.
+     */
+    orderBy<OE extends OrderByExpression<DB, TB, {}>>(expr: OE, modifiers: Expression<any>): DeleteQueryBuilder<DB, TB, O>;
+    /**
+     * Clears the `order by` clause from the query.
      *
-     * See {@link SelectQueryBuilder.orderBy} for more examples.
+     * See {@link orderBy} for adding an `order by` clause or item to a query.
      *
      * ### Examples
      *
-     * Delete 5 oldest items in a table:
-     *
      * ```ts
-     * await db
-     *   .deleteFrom('pet')
-     *   .orderBy('created_at')
-     *   .limit(5)
+     * const query = db
+     *   .selectFrom('person')
+     *   .selectAll()
+     *   .orderBy('id', 'desc')
+     *
+     * const results = await query
+     *   .clearOrderBy()
      *   .execute()
      * ```
      *
-     * The generated SQL (MySQL):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * delete from `pet`
-     * order by `created_at`
-     * limit ?
+     * select * from "person"
      * ```
      */
-    orderBy(orderBy: OrderByExpression<DB, TB, O>, direction?: OrderByDirectionExpression): DeleteQueryBuilder<DB, TB, O>;
+    clearOrderBy(): DeleteQueryBuilder<DB, TB, O>;
     /**
      * Adds a limit clause to the query.
      *