kysely 0.27.5 → 0.28.0

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

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

@@ -5,7 +5,6 @@ const join_parser_js_1 = require("../parser/join-parser.js");
 const table_parser_js_1 = require("../parser/table-parser.js");
 const select_parser_js_1 = require("../parser/select-parser.js");
 const query_node_js_1 = require("../operation-node/query-node.js");
-const prevent_await_js_1 = require("../util/prevent-await.js");
 const object_utils_js_1 = require("../util/object-utils.js");
 const no_result_error_js_1 = require("./no-result-error.js");
 const delete_result_js_1 = require("./delete-result.js");
@@ -90,27 +89,21 @@ class DeleteQueryBuilder {
         });
     }
     innerJoin(...args) {
-        return new DeleteQueryBuilder({
-            ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)('InnerJoin', args)),
-        });
+        return this.#join('InnerJoin', args);
     }
     leftJoin(...args) {
-        return new DeleteQueryBuilder({
-            ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)('LeftJoin', args)),
-        });
+        return this.#join('LeftJoin', args);
     }
     rightJoin(...args) {
-        return new DeleteQueryBuilder({
-            ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)('RightJoin', args)),
-        });
+        return this.#join('RightJoin', args);
     }
     fullJoin(...args) {
+        return this.#join('FullJoin', args);
+    }
+    #join(joinType, args) {
         return new DeleteQueryBuilder({
             ...this.#props,
-            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)('FullJoin', args)),
+            queryNode: query_node_js_1.QueryNode.cloneWithJoin(this.#props.queryNode, (0, join_parser_js_1.parseJoin)(joinType, args)),
         });
     }
     returning(selection) {
@@ -188,70 +181,16 @@ class DeleteQueryBuilder {
             queryNode: delete_query_node_js_1.DeleteQueryNode.cloneWithoutLimit(this.#props.queryNode),
         });
     }
-    /**
-     * 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 *
-     * ```
-     */
-    clearOrderBy() {
+    orderBy(...args) {
         return new DeleteQueryBuilder({
             ...this.#props,
-            queryNode: delete_query_node_js_1.DeleteQueryNode.cloneWithoutOrderBy(this.#props.queryNode),
+            queryNode: query_node_js_1.QueryNode.cloneWithOrderByItems(this.#props.queryNode, (0, order_by_parser_js_1.parseOrderBy)(args)),
         });
     }
-    /**
-     * 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.
-     *
-     * See {@link SelectQueryBuilder.orderBy} for more examples.
-     *
-     * ### Examples
-     *
-     * Delete 5 oldest items in a table:
-     *
-     * ```ts
-     * await db
-     *   .deleteFrom('pet')
-     *   .orderBy('created_at')
-     *   .limit(5)
-     *   .execute()
-     * ```
-     *
-     * The generated SQL (MySQL):
-     *
-     * ```sql
-     * delete from `pet`
-     * order by `created_at`
-     * limit ?
-     * ```
-     */
-    orderBy(orderBy, direction) {
+    clearOrderBy() {
         return new DeleteQueryBuilder({
             ...this.#props,
-            queryNode: delete_query_node_js_1.DeleteQueryNode.cloneWithOrderByItems(this.#props.queryNode, (0, order_by_parser_js_1.parseOrderBy)([orderBy, direction])),
+            queryNode: query_node_js_1.QueryNode.cloneWithoutOrderBy(this.#props.queryNode),
         });
     }
     /**
@@ -519,11 +458,7 @@ class DeleteQueryBuilder {
             (query.output && adapter.supportsOutput)) {
             return result.rows;
         }
-        return [
-            new delete_result_js_1.DeleteResult(
-            // TODO: remove numUpdatedOrDeletedRows.
-            result.numAffectedRows ?? result.numUpdatedOrDeletedRows ?? BigInt(0)),
-        ];
+        return [new delete_result_js_1.DeleteResult(result.numAffectedRows ?? BigInt(0))];
     }
     /**
      * Executes the query and returns the first result or undefined if
@@ -567,4 +502,3 @@ class DeleteQueryBuilder {
     }
 }
 exports.DeleteQueryBuilder = DeleteQueryBuilder;
-(0, prevent_await_js_1.preventAwait)(DeleteQueryBuilder, "don't await DeleteQueryBuilder instances directly. To execute the query you need to call `execute` or `executeTakeFirst`.");

package/dist/cjs/query-builder/function-module.d.ts

@@ -393,7 +393,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      *   .execute()
      * ```
      */
-    max<O extends number | string | bigint | null = never, RE extends ReferenceExpression<DB, TB> = ReferenceExpression<DB, TB>>(expr: RE): AggregateFunctionBuilder<DB, TB, IsNever<O> extends true ? ExtractTypeFromReferenceExpression<DB, TB, RE, number | string | bigint> : O>;
+    max<O extends number | string | Date | bigint | null = never, RE extends ReferenceExpression<DB, TB> = ReferenceExpression<DB, TB>>(expr: RE): AggregateFunctionBuilder<DB, TB, IsNever<O> extends true ? ExtractTypeFromReferenceExpression<DB, TB, RE, number | string | Date | bigint> : O>;
     /**
      * Calls the `min` function for the column or expression given as the argument.
      *
@@ -432,7 +432,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      *   .execute()
      * ```
      */
-    min<O extends number | string | bigint | null = never, RE extends ReferenceExpression<DB, TB> = ReferenceExpression<DB, TB>>(expr: RE): AggregateFunctionBuilder<DB, TB, IsNever<O> extends true ? ExtractTypeFromReferenceExpression<DB, TB, RE, number | string | bigint> : O>;
+    min<O extends number | string | Date | bigint | null = never, RE extends ReferenceExpression<DB, TB> = ReferenceExpression<DB, TB>>(expr: RE): AggregateFunctionBuilder<DB, TB, IsNever<O> extends true ? ExtractTypeFromReferenceExpression<DB, TB, RE, number | string | Date | bigint> : O>;
     /**
      * Calls the `sum` function for the column or expression given as the argument.
      *
@@ -518,9 +518,13 @@ export interface FunctionModule<DB, TB extends keyof DB> {
     any<T>(subquery: SelectQueryBuilderExpression<Record<string, T>>): ExpressionWrapper<DB, TB, T>;
     any<T>(expr: Expression<ReadonlyArray<T>>): ExpressionWrapper<DB, TB, T>;
     /**
-     * Creates a json_agg function call.
+     * Creates a `json_agg` function call.
      *
-     * This function is only available on PostgreSQL.
+     * This is only supported by some dialects like PostgreSQL.
+     *
+     * ### Examples
+     *
+     * You can use it on table expressions:
      *
      * ```ts
      * await db.selectFrom('person')
@@ -538,8 +542,31 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * inner join "pet" on "pet"."owner_id" = "person"."id"
      * group by "person"."first_name"
      * ```
+     *
+     * or on columns:
+     *
+     * ```ts
+     * await db.selectFrom('person')
+     *   .innerJoin('pet', 'pet.owner_id', 'person.id')
+     *   .select((eb) => [
+     *     'first_name',
+     *     eb.fn.jsonAgg('pet.name').as('pet_names'),
+     *   ])
+     *   .groupBy('person.first_name')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "first_name", json_agg("pet"."name") AS "pet_names"
+     * from "person"
+     * inner join "pet" ON "pet"."owner_id" = "person"."id"
+     * group by "person"."first_name"
+     * ```
      */
     jsonAgg<T extends (TB & string) | Expression<unknown>>(table: T): AggregateFunctionBuilder<DB, TB, T extends TB ? Selectable<DB[T]>[] : T extends Expression<infer O> ? O[] : never>;
+    jsonAgg<RE extends StringReference<DB, TB>>(column: RE): AggregateFunctionBuilder<DB, TB, ExtractTypeFromStringReference<DB, TB, RE>[] | null>;
     /**
      * Creates a to_json function call.
      *

package/dist/cjs/query-builder/insert-query-builder.d.ts

@@ -307,15 +307,18 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
     /**
      * Changes an `insert into` query to an `insert ignore into` query.
      *
+     * This is only supported by some dialects like MySQL.
+     *
+     * To avoid a footgun, when invoked with the SQLite dialect, this method will
+     * be handled like {@link orIgnore}. See also, {@link orAbort}, {@link orFail},
+     * {@link orReplace}, and {@link orRollback}.
+     *
      * If you use the ignore modifier, ignorable errors that occur while executing the
      * insert statement are ignored. For example, without ignore, a row that duplicates
      * an existing unique index or primary key value in the table causes a duplicate-key
      * error and the statement is aborted. With ignore, the row is discarded and no error
      * occurs.
      *
-     * This is only supported on some dialects like MySQL. On most dialects you should
-     * use the {@link onConflict} method.
-     *
      * ### Examples
      *
      * ```ts
@@ -332,10 +335,162 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * The generated SQL (MySQL):
      *
      * ```sql
-     * insert ignore into `person` ("first_name", "last_name", "gender") values (?, ?, ?)
+     * insert ignore into `person` (`first_name`, `last_name`, `gender`) values (?, ?, ?)
+     * ```
+     *
+     * The generated SQL (SQLite):
+     *
+     * ```sql
+     * insert or ignore into "person" ("first_name", "last_name", "gender") values (?, ?, ?)
      * ```
      */
     ignore(): InsertQueryBuilder<DB, TB, O>;
+    /**
+     * Changes an `insert into` query to an `insert or ignore into` query.
+     *
+     * This is only supported by some dialects like SQLite.
+     *
+     * To avoid a footgun, when invoked with the MySQL dialect, this method will
+     * be handled like {@link ignore}.
+     *
+     * See also, {@link orAbort}, {@link orFail}, {@link orReplace}, and {@link orRollback}.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.insertInto('person')
+     *   .orIgnore()
+     *   .values({
+     *     first_name: 'John',
+     *     last_name: 'Doe',
+     *     gender: 'female',
+     *   })
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (SQLite):
+     *
+     * ```sql
+     * insert or ignore into "person" ("first_name", "last_name", "gender") values (?, ?, ?)
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * insert ignore into `person` (`first_name`, `last_name`, `gender`) values (?, ?, ?)
+     * ```
+     */
+    orIgnore(): InsertQueryBuilder<DB, TB, O>;
+    /**
+     * Changes an `insert into` query to an `insert or abort into` query.
+     *
+     * This is only supported by some dialects like SQLite.
+     *
+     * See also, {@link orIgnore}, {@link orFail}, {@link orReplace}, and {@link orRollback}.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.insertInto('person')
+     *   .orAbort()
+     *   .values({
+     *     first_name: 'John',
+     *     last_name: 'Doe',
+     *     gender: 'female',
+     *   })
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (SQLite):
+     *
+     * ```sql
+     * insert or abort into "person" ("first_name", "last_name", "gender") values (?, ?, ?)
+     * ```
+     */
+    orAbort(): InsertQueryBuilder<DB, TB, O>;
+    /**
+     * Changes an `insert into` query to an `insert or fail into` query.
+     *
+     * This is only supported by some dialects like SQLite.
+     *
+     * See also, {@link orIgnore}, {@link orAbort}, {@link orReplace}, and {@link orRollback}.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.insertInto('person')
+     *   .orFail()
+     *   .values({
+     *     first_name: 'John',
+     *     last_name: 'Doe',
+     *     gender: 'female',
+     *   })
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (SQLite):
+     *
+     * ```sql
+     * insert or fail into "person" ("first_name", "last_name", "gender") values (?, ?, ?)
+     * ```
+     */
+    orFail(): InsertQueryBuilder<DB, TB, O>;
+    /**
+     * Changes an `insert into` query to an `insert or replace into` query.
+     *
+     * This is only supported by some dialects like SQLite.
+     *
+     * You can also use {@link Kysely.replaceInto} to achieve the same result.
+     *
+     * See also, {@link orIgnore}, {@link orAbort}, {@link orFail}, and {@link orRollback}.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.insertInto('person')
+     *   .orReplace()
+     *   .values({
+     *     first_name: 'John',
+     *     last_name: 'Doe',
+     *     gender: 'female',
+     *   })
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (SQLite):
+     *
+     * ```sql
+     * insert or replace into "person" ("first_name", "last_name", "gender") values (?, ?, ?)
+     * ```
+     */
+    orReplace(): InsertQueryBuilder<DB, TB, O>;
+    /**
+     * Changes an `insert into` query to an `insert or rollback into` query.
+     *
+     * This is only supported by some dialects like SQLite.
+     *
+     * See also, {@link orIgnore}, {@link orAbort}, {@link orFail}, and {@link orReplace}.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.insertInto('person')
+     *   .orRollback()
+     *   .values({
+     *     first_name: 'John',
+     *     last_name: 'Doe',
+     *     gender: 'female',
+     *   })
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (SQLite):
+     *
+     * ```sql
+     * insert or rollback into "person" ("first_name", "last_name", "gender") values (?, ?, ?)
+     * ```
+     */
+    orRollback(): InsertQueryBuilder<DB, TB, O>;
     /**
      * Changes an `insert into` query to an `insert top into` query.
      *
@@ -595,7 +750,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * 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.
@@ -654,7 +809,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
     returning<CB extends SelectCallback<DB, TB>>(callback: CB): InsertQueryBuilder<DB, TB, ReturningCallbackRow<DB, TB, O, CB>>;
     returning<SE extends SelectExpression<DB, TB>>(selection: SE): InsertQueryBuilder<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.