kysely 0.27.5 → 0.28.0

package/dist/cjs/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/cjs/query-builder/order-by-interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/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/cjs/query-builder/order-by-item-builder.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OrderByItemBuilder = void 0;
+const collate_node_js_1 = require("../operation-node/collate-node.js");
+const order_by_item_node_js_1 = require("../operation-node/order-by-item-node.js");
+const raw_node_js_1 = require("../operation-node/raw-node.js");
+const object_utils_js_1 = require("../util/object-utils.js");
+class OrderByItemBuilder {
+    #props;
+    constructor(props) {
+        this.#props = (0, object_utils_js_1.freeze)(props);
+    }
+    /**
+     * Adds `desc` to the `order by` item.
+     *
+     * See {@link asc} for the opposite.
+     */
+    desc() {
+        return new OrderByItemBuilder({
+            node: order_by_item_node_js_1.OrderByItemNode.cloneWith(this.#props.node, {
+                direction: raw_node_js_1.RawNode.createWithSql('desc'),
+            }),
+        });
+    }
+    /**
+     * Adds `asc` to the `order by` item.
+     *
+     * See {@link desc} for the opposite.
+     */
+    asc() {
+        return new OrderByItemBuilder({
+            node: order_by_item_node_js_1.OrderByItemNode.cloneWith(this.#props.node, {
+                direction: raw_node_js_1.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: order_by_item_node_js_1.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: order_by_item_node_js_1.OrderByItemNode.cloneWith(this.#props.node, { nulls: 'first' }),
+        });
+    }
+    /**
+     * Adds `collate <collationName>` to the `order by` item.
+     */
+    collate(collation) {
+        return new OrderByItemBuilder({
+            node: order_by_item_node_js_1.OrderByItemNode.cloneWith(this.#props.node, {
+                collation: collate_node_js_1.CollateNode.create(collation),
+            }),
+        });
+    }
+    toOperationNode() {
+        return this.#props.node;
+    }
+}
+exports.OrderByItemBuilder = OrderByItemBuilder;

package/dist/cjs/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.
      *

package/dist/cjs/query-builder/over-builder.js

@@ -2,39 +2,23 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OverBuilder = void 0;
 const over_node_js_1 = require("../operation-node/over-node.js");
+const query_node_js_1 = require("../operation-node/query-node.js");
 const order_by_parser_js_1 = require("../parser/order-by-parser.js");
 const partition_by_parser_js_1 = require("../parser/partition-by-parser.js");
 const object_utils_js_1 = require("../util/object-utils.js");
-const prevent_await_js_1 = require("../util/prevent-await.js");
 class OverBuilder {
     #props;
     constructor(props) {
         this.#props = (0, object_utils_js_1.freeze)(props);
     }
-    /**
-     * Adds an order by clause item inside the over function.
-     *
-     * ```ts
-     * const result = await db
-     *   .selectFrom('person')
-     *   .select(
-     *     (eb) => eb.fn.avg<number>('age').over(
-     *       ob => ob.orderBy('first_name', 'asc').orderBy('last_name', 'asc')
-     *     ).as('average_age')
-     *   )
-     *   .execute()
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select avg("age") over(order by "first_name" asc, "last_name" asc) as "average_age"
-     * from "person"
-     * ```
-     */
-    orderBy(orderBy, direction) {
+    orderBy(...args) {
+        return new OverBuilder({
+            overNode: over_node_js_1.OverNode.cloneWithOrderByItems(this.#props.overNode, (0, order_by_parser_js_1.parseOrderBy)(args)),
+        });
+    }
+    clearOrderBy() {
         return new OverBuilder({
-            overNode: over_node_js_1.OverNode.cloneWithOrderByItems(this.#props.overNode, (0, order_by_parser_js_1.parseOrderBy)([orderBy, direction])),
+            overNode: query_node_js_1.QueryNode.cloneWithoutOrderBy(this.#props.overNode),
         });
     }
     partitionBy(partitionBy) {
@@ -54,4 +38,3 @@ class OverBuilder {
     }
 }
 exports.OverBuilder = OverBuilder;
-(0, prevent_await_js_1.preventAwait)(OverBuilder, "don't await OverBuilder instances. They are never executed directly and are always just a part of a query.");

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

@@ -1,4 +1,4 @@
-import { ReturningCallbackRow, ReturningRow } from '../parser/returning-parser.js';
+import { ReturningAllRow, ReturningCallbackRow, ReturningRow } from '../parser/returning-parser.js';
 import { SelectCallback, SelectExpression } from '../parser/select-parser.js';
 import { Selectable } from '../util/column-type.js';
 export interface ReturningInterface<DB, TB extends keyof DB, O> {
@@ -6,7 +6,7 @@ export interface ReturningInterface<DB, TB extends keyof DB, O> {
      * 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.
@@ -65,10 +65,27 @@ export interface ReturningInterface<DB, TB extends keyof DB, O> {
     returning<CB extends SelectCallback<DB, TB>>(callback: CB): ReturningInterface<DB, TB, ReturningCallbackRow<DB, TB, O, CB>>;
     returning<SE extends SelectExpression<DB, TB>>(selection: SE): ReturningInterface<DB, TB, ReturningRow<DB, TB, O, SE>>;
     /**
-     * Adds a `returning *` to an insert/update/delete query on databases
+     * Adds a `returning *` to an insert/update/delete/merge query on databases
      * that support `returning` such as PostgreSQL.
      *
      * Also see the {@link returning} method.
      */
     returningAll(): ReturningInterface<DB, TB, Selectable<DB[TB]>>;
 }
+export interface MultiTableReturningInterface<DB, TB extends keyof DB, O> extends ReturningInterface<DB, TB, O> {
+    /**
+     * 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 TB>(tables: ReadonlyArray<T>): MultiTableReturningInterface<DB, TB, ReturningAllRow<DB, T, O>>;
+    /**
+     * Adds a `returning *` to an insert/update/delete/merge query on databases
+     * that support `returning` such as PostgreSQL.
+     *
+     * Also see the {@link returning} method.
+     */
+    returningAll<T extends TB>(table: T): MultiTableReturningInterface<DB, TB, ReturningAllRow<DB, T, O>>;
+    returningAll(): ReturningInterface<DB, TB, Selectable<DB[TB]>>;
+}