kysely 0.12.0 → 0.14.0

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

@@ -3,18 +3,18 @@ import { CompiledQuery } from '../query-compiler/compiled-query.js';
 import { SelectExpression } from '../parser/select-parser.js';
 import { InsertObject } from '../parser/insert-values-parser.js';
 import { InsertQueryNode } from '../operation-node/insert-query-node.js';
-import { AnyColumn, SingleResultType } from '../util/type-utils.js';
+import { SingleResultType } from '../util/type-utils.js';
 import { MutationObject } from '../parser/update-set-parser.js';
 import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
 import { QueryId } from '../util/query-id.js';
-import { OnConflictConstraintTarget } from '../parser/on-conflict-parser.js';
 import { ParseContext } from '../parser/parse-context.js';
 import { KyselyPlugin } from '../plugin/kysely-plugin.js';
 import { ReturningRow } from '../parser/returning-parser.js';
 import { NoResultErrorConstructor } from './no-result-error.js';
 import { ComplexExpression } from '../parser/complex-expression-parser.js';
 import { ReturningInterface } from './returning-interface.js';
+import { OnConflictBuilder, OnConflictDoNothingBuilder, OnConflictUpdateBuilder } from './on-conflict-builder.js';
 export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements ReturningInterface<DB, TB, O>, OperationNodeSource, Compilable {
     #private;
     constructor(props: InsertQueryBuilderProps);
@@ -196,21 +196,32 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      */
     expression(expression: ComplexExpression<DB, TB>): InsertQueryBuilder<DB, TB, O>;
     /**
-     * Ignores the insert if the column or constraint given as the first
-     * argument conflicts with the current rows in the database. The
-     * default behavior without this method call is to throw an error.
+     * Changes an `insert into` query to an `insert ignore into` query.
+     *
+     * 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.
      *
-     * For example if a table has a field `name` that has a unique constraint
-     * and you try to insert a row with a `name` that already exists in the
-     * database, calling `onConflictDoNothing('name')` will ignore the conflict
-     * and do nothing. By default the query would throw.
+     * This is only supported on some dialects like MySQL. On most dialects you should
+     * use the {@link onConflict} method.
+     *
+     * ### Examples
      *
-     * Only some dialects like PostgreSQL and SQLite implement the `on conflict`
-     * statement. On MySQL you should use the {@link ignore} method to achieve
-     * similar results.
+     * ```ts
+     * await db.insertInto('person')
+     *   .ignore()
+     *   .values(values)
+     *   .execute()
+     * ```
+     */
+    ignore(): InsertQueryBuilder<DB, TB, O>;
+    /**
+     * Adds an `on conflict` clause to the query.
      *
-     * Also see the {@link InsertQueryBuilder.onConflictUpdate | onConflictUpdate}
-     * method if you want to perform an update in case of a conflict (upsert).
+     * `on conflict` is only supported by some dialects like PostgreSQL and SQLite. On MySQL
+     * you can use {@link ignore} and {@link onDuplicateKeyUpdate} to achieve similar results.
      *
      * ### Examples
      *
@@ -222,7 +233,10 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *     name: 'Catto',
      *     species: 'cat',
      *   })
-     *   .onConflictDoNothing('name')
+     *   .onConflict((oc) => oc
+     *     .column('name')
+     *     .doUpdateSet({ species: 'hamster' })
+     *   )
      *   .execute()
      * ```
      *
@@ -231,10 +245,11 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * ```sql
      * insert into "pet" ("name", "species")
      * values ($1, $2)
-     * on conflict ("name") do nothing
+     * on conflict ("name")
+     * do update set "species" = $3
      * ```
      *
-     * You can provide the name of the constraint instead of a column name
+     * You can provide the name of the constraint instead of a column name:
      *
      * ```ts
      * await db
@@ -244,9 +259,11 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *     name: 'Catto',
      *     species: 'cat',
      *   })
-     *   .onConflictDoNothing({
-     *     constraint: 'pet_name_key'
-     *   })
+     *   .onConflict((oc) => oc
+     *     .constraint('pet_name_key')
+     *     .doUpdateSet({ species: 'hamster' })
+     *   )
+     *   .execute()
      *   .execute()
      * ```
      *
@@ -256,57 +273,37 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * insert into "pet" ("name", "species")
      * values ($1, $2)
      * on conflict on constraint "pet_name_key"
-     * do nothing
+     * do update set "species" = $3
      * ```
-     */
-    onConflictDoNothing(column: AnyColumn<DB, TB>): InsertQueryBuilder<DB, TB, O>;
-    onConflictDoNothing(columns: ReadonlyArray<AnyColumn<DB, TB>>): InsertQueryBuilder<DB, TB, O>;
-    onConflictDoNothing(constraint: OnConflictConstraintTarget): InsertQueryBuilder<DB, TB, O>;
-    /**
-     * Changes an `insert into` query to an `insert ignore into` query.
-     *
-     * 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 onConflictDoNothing} method.
-     *
-     * ### Examples
+     * You can also specify an expression as the conflict target in case
+     * the unique index is an expression index:
      *
      * ```ts
-     * await db.insertInto('person')
-     *   .ignore()
-     *   .values(values)
+     * await db
+     *   .insertInto('pet')
+     *   .values({
+     *     id: db.generated,
+     *     name: 'Catto',
+     *     species: 'cat',
+     *   })
+     *   .onConflict((oc) => oc
+     *     .expression(db.raw('lower(name)'))
+     *     .doUpdateSet({ species: 'hamster' })
+     *   )
      *   .execute()
      * ```
-     */
-    ignore(): InsertQueryBuilder<DB, TB, O>;
-    /**
-     * Ignores an insert if the column or constraint given as the first
-     * argument conflicts with the current rows in the database and
-     * performs an update on the conflicting row instead. This method
-     * can be used to implement an upsert operation.
      *
-     * For example if a table has a field `name` that has a unique constraint
-     * and you try to insert a row with a `name` that already exists in the
-     * database, calling `onConfictUpdate('name', { species: 'hamster' })`
-     * will set the conflicting row's `species` field to value `'hamster'`.
-     * By default the query would throw.
-     *
-     * The second argument (updates) can be anything the {@link UpdateQueryBuilder.set | set}
-     * method accepts.
-     *
-     * The `on conflict do update` statement is only implemented by some dialects
-     * like PostgreSQL and SQLite. On MySQL you should use the {@link onDuplicateKeyUpdate}
-     * method instead.
+     * The generated SQL (PostgreSQL):
      *
-     * Also see the {@link InsertQueryBuilder.onConflictDoNothing | onConflictDoNothing}
-     * method.
+     * ```sql
+     * insert into "pet" ("name", "species")
+     * values ($1, $2)
+     * on conflict (lower(name))
+     * do update set "species" = $3
+     * ```
      *
-     * ### Examples
+     * You can add a filter for the update statement like this:
      *
      * ```ts
      * await db
@@ -316,7 +313,11 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *     name: 'Catto',
      *     species: 'cat',
      *   })
-     *   .onConflictUpdate('name', { species: 'hamster' })
+     *   .onConflict((oc) => oc
+     *     .column('name')
+     *     .doUpdateSet({ species: 'hamster' })
+     *     .where('excluded.name', '!=', 'Catto'')
+     *   )
      *   .execute()
      * ```
      *
@@ -325,10 +326,12 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * ```sql
      * insert into "pet" ("name", "species")
      * values ($1, $2)
-     * on conflict ("name") do update set "species" = $3
+     * on conflict ("name")
+     * do update set "species" = $3
+     * where "excluded"."name" != $4
      * ```
      *
-     * You can provied the name of the constraint instead of a column name
+     * You can create an `on conflict do nothing` clauses like this:
      *
      * ```ts
      * await db
@@ -338,9 +341,9 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *     name: 'Catto',
      *     species: 'cat',
      *   })
-     *   .onConflictUpdate(
-     *     { constraint: 'pet_name_key' },
-     *     { species: 'hamster' }
+     *   .onConflict((oc) => oc
+     *     .column('name')
+     *     .doNothing()
      *   )
      *   .execute()
      * ```
@@ -350,13 +353,10 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * ```sql
      * insert into "pet" ("name", "species")
      * values ($1, $2)
-     * on conflict on constraint "pet_name_key"
-     * do update set "species" = $3
+     * on conflict ("name") do nothing
      * ```
      */
-    onConflictUpdate(column: AnyColumn<DB, TB>, updates: MutationObject<DB, TB>): InsertQueryBuilder<DB, TB, O>;
-    onConflictUpdate(columns: ReadonlyArray<AnyColumn<DB, TB>>, updates: MutationObject<DB, TB>): InsertQueryBuilder<DB, TB, O>;
-    onConflictUpdate(constraint: OnConflictConstraintTarget, updates: MutationObject<DB, TB>): InsertQueryBuilder<DB, TB, O>;
+    onConflict(callback: (builder: OnConflictBuilder<DB, TB>) => OnConflictDoNothingBuilder<DB, TB> | OnConflictUpdateBuilder<DB, TB>): InsertQueryBuilder<DB, TB, O>;
     /**
      * Adds `on duplicate key update` to the query.
      *
@@ -364,7 +364,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * a duplicate value in a unique index or primary key, an update of the old row occurs.
      *
      * This is only implemented by some dialects like MySQL. On most dialects you should
-     * use {@link onConflictUpdate} instead.
+     * use {@link onConflict} instead.
      *
      * ### Examples
      *
@@ -376,8 +376,74 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * ```
      */
     onDuplicateKeyUpdate(updates: MutationObject<DB, TB>): InsertQueryBuilder<DB, TB, 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.
+     *
+     * 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({
+     *     id: db.generated,
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston'
+     *   })
+     *   .returning('id')
+     *   .executeTakeFirst()
+     * ```
+     *
+     * Return multiple columns:
+     *
+     * ```ts
+     * const { id, first_name } = await db
+     *   .insertInto('person')
+     *   .values({
+     *     id: db.generated,
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston'
+     *   })
+     *   .returning(['id', 'last_name'])
+     *   .executeTakeFirst()
+     * ```
+     *
+     * Return arbitrary expressions:
+     *
+     * ```ts
+     * const { raw } = db
+     *
+     * const { id, full_name, first_pet_id } = await db
+     *   .insertInto('person')
+     *   .values({
+     *     id: db.generated,
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston'
+     *   })
+     *   .returning([
+     *     'id as id',
+     *     raw<string>(`concat(first_name, ' ', last_name)`).as('full_name'),
+     *     (qb) => qb.selectFrom('pets').select('pet.id').limit(1).as('first_pet_id')
+     *   ])
+     *   .executeTakeFirst()
+     * ```
+     */
     returning<SE extends SelectExpression<DB, TB>>(selections: ReadonlyArray<SE>): InsertQueryBuilder<DB, TB, ReturningRow<DB, TB, O, SE>>;
     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
+     * that support `returning` such as PostgreSQL.
+     */
     returningAll(): InsertQueryBuilder<DB, TB, DB[TB]>;
     /**
      * Simply calls the given function passing `this` as the only argument.
@@ -391,9 +457,9 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *   .selectAll()
      *   .call((qb) => {
      *     if (something) {
-     *       return qb.onConflictDoNothing('something')
+     *       return qb.onConflict((oc) => oc.column('something').doNothing())
      *     } else {
-     *       return qb.onConflictDoNothing('something_else')
+     *       return qb.onConflict((oc) => oc.column('something_else').doNothing())
      *     }
      *   })
      *   .execute()

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

@@ -4,13 +4,14 @@ import { InsertQueryNode } from '../operation-node/insert-query-node.js';
 import { QueryNode } from '../operation-node/query-node.js';
 import { parseUpdateObject, } from '../parser/update-set-parser.js';
 import { preventAwait } from '../util/prevent-await.js';
-import { parseOnConflictDoNothing, parseOnConflictUpdate, } from '../parser/on-conflict-parser.js';
 import { freeze } from '../util/object-utils.js';
 import { OnDuplicateKeyNode } from '../operation-node/on-duplicate-key-node.js';
 import { InsertResult } from './insert-result.js';
 import { NoResultError } from './no-result-error.js';
 import { parseComplexExpression, } from '../parser/complex-expression-parser.js';
 import { ColumnNode } from '../operation-node/column-node.js';
+import { OnConflictNode } from '../index.js';
+import { OnConflictBuilder, } from './on-conflict-builder.js';
 export class InsertQueryBuilder {
     #props;
     constructor(props) {
@@ -82,14 +83,6 @@ export class InsertQueryBuilder {
             }),
         });
     }
-    onConflictDoNothing(target) {
-        return new InsertQueryBuilder({
-            ...this.#props,
-            queryNode: InsertQueryNode.cloneWith(this.#props.queryNode, {
-                onConflict: parseOnConflictDoNothing(target),
-            }),
-        });
-    }
     /**
      * Changes an `insert into` query to an `insert ignore into` query.
      *
@@ -100,7 +93,7 @@ export class InsertQueryBuilder {
      * occurs.
      *
      * This is only supported on some dialects like MySQL. On most dialects you should
-     * use the {@link onConflictDoNothing} method.
+     * use the {@link onConflict} method.
      *
      * ### Examples
      *
@@ -119,11 +112,153 @@ export class InsertQueryBuilder {
             }),
         });
     }
-    onConflictUpdate(target, updates) {
+    /**
+     * Adds an `on conflict` clause to the query.
+     *
+     * `on conflict` is only supported by some dialects like PostgreSQL and SQLite. On MySQL
+     * you can use {@link ignore} and {@link onDuplicateKeyUpdate} to achieve similar results.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db
+     *   .insertInto('pet')
+     *   .values({
+     *     id: db.generated,
+     *     name: 'Catto',
+     *     species: 'cat',
+     *   })
+     *   .onConflict((oc) => oc
+     *     .column('name')
+     *     .doUpdateSet({ species: 'hamster' })
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "pet" ("name", "species")
+     * values ($1, $2)
+     * on conflict ("name")
+     * do update set "species" = $3
+     * ```
+     *
+     * You can provide the name of the constraint instead of a column name:
+     *
+     * ```ts
+     * await db
+     *   .insertInto('pet')
+     *   .values({
+     *     id: db.generated,
+     *     name: 'Catto',
+     *     species: 'cat',
+     *   })
+     *   .onConflict((oc) => oc
+     *     .constraint('pet_name_key')
+     *     .doUpdateSet({ species: 'hamster' })
+     *   )
+     *   .execute()
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "pet" ("name", "species")
+     * values ($1, $2)
+     * on conflict on constraint "pet_name_key"
+     * do update set "species" = $3
+     * ```
+     *
+     * You can also specify an expression as the conflict target in case
+     * the unique index is an expression index:
+     *
+     * ```ts
+     * await db
+     *   .insertInto('pet')
+     *   .values({
+     *     id: db.generated,
+     *     name: 'Catto',
+     *     species: 'cat',
+     *   })
+     *   .onConflict((oc) => oc
+     *     .expression(db.raw('lower(name)'))
+     *     .doUpdateSet({ species: 'hamster' })
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "pet" ("name", "species")
+     * values ($1, $2)
+     * on conflict (lower(name))
+     * do update set "species" = $3
+     * ```
+     *
+     * You can add a filter for the update statement like this:
+     *
+     * ```ts
+     * await db
+     *   .insertInto('pet')
+     *   .values({
+     *     id: db.generated,
+     *     name: 'Catto',
+     *     species: 'cat',
+     *   })
+     *   .onConflict((oc) => oc
+     *     .column('name')
+     *     .doUpdateSet({ species: 'hamster' })
+     *     .where('excluded.name', '!=', 'Catto'')
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "pet" ("name", "species")
+     * values ($1, $2)
+     * on conflict ("name")
+     * do update set "species" = $3
+     * where "excluded"."name" != $4
+     * ```
+     *
+     * You can create an `on conflict do nothing` clauses like this:
+     *
+     * ```ts
+     * await db
+     *   .insertInto('pet')
+     *   .values({
+     *     id: db.generated,
+     *     name: 'Catto',
+     *     species: 'cat',
+     *   })
+     *   .onConflict((oc) => oc
+     *     .column('name')
+     *     .doNothing()
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "pet" ("name", "species")
+     * values ($1, $2)
+     * on conflict ("name") do nothing
+     * ```
+     */
+    onConflict(callback) {
         return new InsertQueryBuilder({
             ...this.#props,
             queryNode: InsertQueryNode.cloneWith(this.#props.queryNode, {
-                onConflict: parseOnConflictUpdate(this.#props.parseContext, target, updates),
+                onConflict: callback(new OnConflictBuilder({
+                    onConflictNode: OnConflictNode.create(),
+                    parseContext: this.#props.parseContext,
+                })).toOperationNode(),
             }),
         });
     }
@@ -134,7 +269,7 @@ export class InsertQueryBuilder {
      * a duplicate value in a unique index or primary key, an update of the old row occurs.
      *
      * This is only implemented by some dialects like MySQL. On most dialects you should
-     * use {@link onConflictUpdate} instead.
+     * use {@link onConflict} instead.
      *
      * ### Examples
      *
@@ -177,9 +312,9 @@ export class InsertQueryBuilder {
      *   .selectAll()
      *   .call((qb) => {
      *     if (something) {
-     *       return qb.onConflictDoNothing('something')
+     *       return qb.onConflict((oc) => oc.column('something').doNothing())
      *     } else {
-     *       return qb.onConflictDoNothing('something_else')
+     *       return qb.onConflict((oc) => oc.column('something_else').doNothing())
      *     }
      *   })
      *   .execute()

package/dist/esm/query-builder/join-interface.d.ts

@@ -113,20 +113,17 @@ export interface JoinInterface<DB, TB extends keyof DB> {
     innerJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): JoinInterface<TableExpressionDatabase<DB, TE>, TableExpressionTables<DB, TB, TE>>;
     innerJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): JoinInterface<TableExpressionDatabase<DB, TE>, TableExpressionTables<DB, TB, TE>>;
     /**
-     * Just like {@link JoinInterface.innerJoin | innerJoin} but adds a left join
-     * instead of an inner join.
+     * Just like {@link innerJoin} but adds a left join nstead of an inner join.
      */
     leftJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): JoinInterface<LeftJoinTableExpressionDatabase<DB, TE>, TableExpressionTables<DB, TB, TE>>;
     leftJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): JoinInterface<LeftJoinTableExpressionDatabase<DB, TE>, TableExpressionTables<DB, TB, TE>>;
     /**
-     * Just like {@link JoinInterface.innerJoin | innerJoin} but adds a right join
-     * instead of an inner join.
+     * Just like {@link innerJoin} but adds a right join instead of an inner join.
      */
     rightJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): JoinInterface<RightJoinTableExpressionDatabase<DB, TB, TE>, TableExpressionTables<DB, TB, TE>>;
     rightJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): JoinInterface<RightJoinTableExpressionDatabase<DB, TB, TE>, TableExpressionTables<DB, TB, TE>>;
     /**
-     * Just like {@link JoinInterface.innerJoin | innerJoin} but adds a full join
-     * instead of an inner join.
+     * Just like {@link innerJoin} but adds a full join instead of an inner join.
      */
     fullJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): JoinInterface<FullJoinTableExpressionDatabase<DB, TB, TE>, TableExpressionTables<DB, TB, TE>>;
     fullJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): JoinInterface<FullJoinTableExpressionDatabase<DB, TB, TE>, TableExpressionTables<DB, TB, TE>>;