kysely 0.27.4 → 0.27.6

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

@@ -60,6 +60,8 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * you can always use:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * sql`your operator`
      * ```
      *
@@ -71,7 +73,7 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
-     *   .where('id', 'in', ['1', '2', '3'])
+     *   .where('id', 'in', [1, 2, 3])
      *   .execute()
      * ```
      *
@@ -319,6 +321,8 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * import { sql } from 'kysely'
      * const { ref } = db.dynamic
      *
+     * const columnFromUserInput: string = 'id'
+     *
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
@@ -529,7 +533,7 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      *   .innerJoin('pet', 'pet.owner_id', 'person.id')
      *   // `select` needs to come after the call to `innerJoin` so
      *   // that you can select from the joined table.
-     *   .select('person.id', 'pet.name')
+     *   .select(['person.id', 'pet.name'])
      *   .execute()
      *
      * result[0].id
@@ -601,7 +605,7 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ```ts
      * await db.selectFrom('person')
      *   .innerJoin(
-     *     qb.selectFrom('pet')
+     *     db.selectFrom('pet')
      *       .select(['owner_id', 'name'])
      *       .where('name', '=', 'Doggo')
      *       .as('doggos'),
@@ -666,20 +670,20 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      *     last_name: 'Aniston'
      *   })
      *   .returning('id')
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
      * ```
      *
      * Return multiple columns:
      *
      * ```ts
-     * const { id, first_name } = await db
+     * const { id, last_name } = await db
      *   .insertInto('person')
      *   .values({
      *     first_name: 'Jennifer',
      *     last_name: 'Aniston'
      *   })
      *   .returning(['id', 'last_name'])
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
      * ```
      *
      * Return arbitrary expressions:
@@ -696,9 +700,9 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      *   .returning((eb) => [
      *     'id as id',
      *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name'),
-     *     eb.selectFrom('pets').select('pet.id').limit(1).as('first_pet_id')
+     *     eb.selectFrom('pet').select('pet.id').limit(1).as('first_pet_id')
      *   ])
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
      * ```
      */
     returning<SE extends SelectExpression<DB, TB>>(selections: ReadonlyArray<SE>): DeleteQueryBuilder<DB, TB, ReturningRow<DB, TB, O, SE>>;
@@ -727,7 +731,7 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * Return all columns from all tables
      *
      * ```ts
-     * const result = ctx.db
+     * const result = await db
      *   .deleteFrom('toy')
      *   .using(['pet', 'person'])
      *   .whereRef('toy.pet_id', '=', 'pet.id')
@@ -751,7 +755,7 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * Return all columns from a single table.
      *
      * ```ts
-     * const result = ctx.db
+     * const result = await db
      *   .deleteFrom('toy')
      *   .using(['pet', 'person'])
      *   .whereRef('toy.pet_id', '=', 'pet.id')
@@ -775,7 +779,7 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * Return all columns from multiple tables.
      *
      * ```ts
-     * const result = ctx.db
+     * const result = await db
      *   .deleteFrom('toy')
      *   .using(['pet', 'person'])
      *   .whereRef('toy.pet_id', '=', 'pet.id')
@@ -823,15 +827,24 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      *   .output('inserted.id')
      *   .values({
      *     first_name: 'Jennifer',
-     *     last_name: 'Aniston'
+     *     last_name: 'Aniston',
+     *     gender: 'female',
      *   })
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (MSSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name", "last_name", "gender")
+     * output "inserted"."id"
+     * values (@1, @2, @3)
      * ```
      *
      * Return multiple columns:
      *
      * ```ts
-     * const { id, first_name } = await db
+     * const { old_first_name, old_last_name, new_first_name, new_last_name } = await db
      *   .updateTable('person')
      *   .set({ first_name: 'John', last_name: 'Doe' })
      *   .output([
@@ -841,7 +854,19 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      *     'inserted.last_name as new_last_name',
      *   ])
      *   .where('created_at', '<', new Date())
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (MSSQL):
+     *
+     * ```sql
+     * update "person"
+     * set "first_name" = @1, "last_name" = @2
+     * output "deleted"."first_name" as "old_first_name",
+     *   "deleted"."last_name" as "old_last_name",
+     *   "inserted"."first_name" as "new_first_name",
+     *   "inserted"."last_name" as "new_last_name"
+     * where "created_at" < @3
      * ```
      *
      * Return arbitrary expressions:
@@ -849,11 +874,19 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ```ts
      * import { sql } from 'kysely'
      *
-     * const { id, full_name } = await db
+     * const { full_name } = await db
      *   .deleteFrom('person')
-     *   .output((eb) => sql<string>`concat(${eb.ref('deleted.first_name')}, ' ', ${eb.ref('deleted.last_name')})`.as('full_name')
+     *   .output((eb) => sql<string>`concat(${eb.ref('deleted.first_name')}, ' ', ${eb.ref('deleted.last_name')})`.as('full_name'))
      *   .where('created_at', '<', new Date())
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (MSSQL):
+     *
+     * ```sql
+     * delete from "person"
+     * output concat("deleted"."first_name", ' ', "deleted"."last_name") as "full_name"
+     * where "created_at" < @1
      * ```
      *
      * Return the action performed on the row:
@@ -874,7 +907,21 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      *     'inserted.id as inserted_id',
      *     'deleted.id as deleted_id',
      *   ])
+     *   .execute()
      * ```
+     *
+     * The generated SQL (MSSQL):
+     *
+     * ```sql
+     * merge into "person"
+     * using "pet" on "pet"."owner_id" = "person"."id"
+     * when matched then delete
+     * when not matched then
+     * insert ("first_name", "last_name", "gender")
+     * values (@1, @2, @3)
+     * output "inserted"."id" as "inserted_id", "deleted"."id" as "deleted_id"
+     * ```
+     *
      */
     output<OE extends OutputExpression<DB, TB, 'deleted'>>(selections: readonly OE[]): DeleteQueryBuilder<DB, TB, ReturningRow<DB, TB, O, SelectExpressionFromOutputExpression<OE>>>;
     output<CB extends OutputCallback<DB, TB, 'deleted'>>(callback: CB): DeleteQueryBuilder<DB, TB, ReturningRow<DB, TB, O, SelectExpressionFromOutputCallback<CB>>>;
@@ -892,10 +939,11 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ### Examples
      *
      * ```ts
-     * db.deleteFrom('pet')
+     * await db.deleteFrom('pet')
      *   .returningAll()
      *   .where('name', '=', 'Max')
      *   .clearReturning()
+     *   .execute()
      * ```
      *
      * The generated SQL(PostgreSQL):
@@ -911,11 +959,12 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ### Examples
      *
      * ```ts
-     * db.deleteFrom('pet')
+     * await db.deleteFrom('pet')
      *   .returningAll()
      *   .where('name', '=', 'Max')
      *   .limit(5)
      *   .clearLimit()
+     *   .execute()
      * ```
      *
      * The generated SQL(PostgreSQL):
@@ -931,11 +980,12 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ### Examples
      *
      * ```ts
-     * db.deleteFrom('pet')
+     * await db.deleteFrom('pet')
      *   .returningAll()
      *   .where('name', '=', 'Max')
      *   .orderBy('id')
      *   .clearOrderBy()
+     *   .execute()
      * ```
      *
      * The generated SQL(PostgreSQL):
@@ -997,8 +1047,36 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      *   .limit(5)
      *   .execute()
      * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * delete from `pet` order by `created_at` limit ?
+     * ```
      */
     limit(limit: ValueExpression<DB, TB, number>): DeleteQueryBuilder<DB, TB, O>;
+    /**
+     * This can be used to add any additional SQL to the end of the query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * await db.deleteFrom('person')
+     *   .where('first_name', '=', 'John')
+     *   .modifyEnd(sql`-- This is a comment`)
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * delete from `person`
+     * where `first_name` = "John" -- This is a comment
+     * ```
+     */
+    modifyEnd(modifier: Expression<any>): DeleteQueryBuilder<DB, TB, O>;
     /**
      * Simply calls the provided function passing `this` as the only argument. `$call` returns
      * what the provided function returns.
@@ -1011,12 +1089,14 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * The next example uses a helper function `log` to log a query:
      *
      * ```ts
+     * import type { Compilable } from 'kysely'
+     *
      * function log<T extends Compilable>(qb: T): T {
      *   console.log(qb.compile())
      *   return qb
      * }
      *
-     * db.deleteFrom('person')
+     * await db.deleteFrom('person')
      *   .$call(log)
      *   .execute()
      * ```
@@ -1050,11 +1130,11 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * the code. In the example above the return type of the `deletePerson` function is:
      *
      * ```ts
-     * {
+     * Promise<{
      *   id: number
      *   first_name: string
      *   last_name?: string
-     * }
+     * }>
      * ```
      */
     $if<O2>(condition: boolean, func: (qb: this) => DeleteQueryBuilder<any, any, O2>): O2 extends DeleteResult ? DeleteQueryBuilder<DB, TB, DeleteResult> : O2 extends O & infer E ? DeleteQueryBuilder<DB, TB, O & Partial<E>> : DeleteQueryBuilder<DB, TB, Partial<O2>>;
@@ -1082,25 +1162,33 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * Turn this code:
      *
      * ```ts
+     * import type { Person } from 'type-editor' // imaginary module
+     *
      * const person = await db.deleteFrom('person')
-     *   .where('id', '=', id)
+     *   .where('id', '=', 3)
      *   .where('nullable_column', 'is not', null)
      *   .returningAll()
      *   .executeTakeFirstOrThrow()
      *
-     * if (person.nullable_column) {
+     * if (isWithNoNullValue(person)) {
      *   functionThatExpectsPersonWithNonNullValue(person)
      * }
+     *
+     * function isWithNoNullValue(person: Person): person is Person & { nullable_column: string } {
+     *   return person.nullable_column != null
+     * }
      * ```
      *
      * Into this:
      *
      * ```ts
+     * import type { NotNull } from 'kysely'
+     *
      * const person = await db.deleteFrom('person')
-     *   .where('id', '=', id)
+     *   .where('id', '=', 3)
      *   .where('nullable_column', 'is not', null)
      *   .returningAll()
-     *   .$narrowType<{ nullable_column: string }>()
+     *   .$narrowType<{ nullable_column: NotNull }>()
      *   .executeTakeFirstOrThrow()
      *
      * functionThatExpectsPersonWithNonNullValue(person)
@@ -1130,22 +1218,26 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ### Examples
      *
      * ```ts
-     * const result = await db
-     *   .with('deleted_person', (qb) => qb
-     *     .deleteFrom('person')
-     *     .where('id', '=', person.id)
-     *     .returning('first_name')
-     *     .$assertType<{ first_name: string }>()
-     *   )
-     *   .with('deleted_pet', (qb) => qb
-     *     .deleteFrom('pet')
-     *     .where('owner_id', '=', person.id)
-     *     .returning(['name as pet_name', 'species'])
-     *     .$assertType<{ pet_name: string, species: Species }>()
-     *   )
-     *   .selectFrom(['deleted_person', 'deleted_pet'])
-     *   .selectAll()
-     *   .executeTakeFirstOrThrow()
+     * import type { Species } from 'type-editor' // imaginary module
+     *
+     * async function deletePersonAndPets(personId: number) {
+     *   return await db
+     *     .with('deleted_person', (qb) => qb
+     *        .deleteFrom('person')
+     *        .where('id', '=', personId)
+     *        .returning('first_name')
+     *        .$assertType<{ first_name: string }>()
+     *     )
+     *     .with('deleted_pets', (qb) => qb
+     *       .deleteFrom('pet')
+     *       .where('owner_id', '=', personId)
+     *       .returning(['name as pet_name', 'species'])
+     *       .$assertType<{ pet_name: string, species: Species }>()
+     *     )
+     *     .selectFrom(['deleted_person', 'deleted_pets'])
+     *     .selectAll()
+     *     .execute()
+     * }
      * ```
      */
     $assertType<T extends O>(): O extends T ? DeleteQueryBuilder<DB, TB, T> : KyselyTypeError<`$assertType() call failed: The type passed in is not equal to the output type of the query.`>;
@@ -1184,7 +1276,7 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ### Examples
      *
      * ```ts
-     * const stream = db.
+     * const stream = db
      *   .selectFrom('person')
      *   .select(['first_name', 'last_name'])
      *   .where('gender', '=', 'other')

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

@@ -141,10 +141,11 @@ export class DeleteQueryBuilder {
      * ### Examples
      *
      * ```ts
-     * db.deleteFrom('pet')
+     * await db.deleteFrom('pet')
      *   .returningAll()
      *   .where('name', '=', 'Max')
      *   .clearReturning()
+     *   .execute()
      * ```
      *
      * The generated SQL(PostgreSQL):
@@ -165,11 +166,12 @@ export class DeleteQueryBuilder {
      * ### Examples
      *
      * ```ts
-     * db.deleteFrom('pet')
+     * await db.deleteFrom('pet')
      *   .returningAll()
      *   .where('name', '=', 'Max')
      *   .limit(5)
      *   .clearLimit()
+     *   .execute()
      * ```
      *
      * The generated SQL(PostgreSQL):
@@ -190,11 +192,12 @@ export class DeleteQueryBuilder {
      * ### Examples
      *
      * ```ts
-     * db.deleteFrom('pet')
+     * await db.deleteFrom('pet')
      *   .returningAll()
      *   .where('name', '=', 'Max')
      *   .orderBy('id')
      *   .clearOrderBy()
+     *   .execute()
      * ```
      *
      * The generated SQL(PostgreSQL):
@@ -266,6 +269,12 @@ export class DeleteQueryBuilder {
      *   .limit(5)
      *   .execute()
      * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * delete from `pet` order by `created_at` limit ?
+     * ```
      */
     limit(limit) {
         return new DeleteQueryBuilder({
@@ -273,6 +282,33 @@ export class DeleteQueryBuilder {
             queryNode: DeleteQueryNode.cloneWithLimit(this.#props.queryNode, LimitNode.create(parseValueExpression(limit))),
         });
     }
+    /**
+     * This can be used to add any additional SQL to the end of the query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * await db.deleteFrom('person')
+     *   .where('first_name', '=', 'John')
+     *   .modifyEnd(sql`-- This is a comment`)
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * delete from `person`
+     * where `first_name` = "John" -- This is a comment
+     * ```
+     */
+    modifyEnd(modifier) {
+        return new DeleteQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithEndModifier(this.#props.queryNode, modifier.toOperationNode()),
+        });
+    }
     /**
      * Simply calls the provided function passing `this` as the only argument. `$call` returns
      * what the provided function returns.
@@ -285,12 +321,14 @@ export class DeleteQueryBuilder {
      * The next example uses a helper function `log` to log a query:
      *
      * ```ts
+     * import type { Compilable } from 'kysely'
+     *
      * function log<T extends Compilable>(qb: T): T {
      *   console.log(qb.compile())
      *   return qb
      * }
      *
-     * db.deleteFrom('person')
+     * await db.deleteFrom('person')
      *   .$call(log)
      *   .execute()
      * ```
@@ -326,11 +364,11 @@ export class DeleteQueryBuilder {
      * the code. In the example above the return type of the `deletePerson` function is:
      *
      * ```ts
-     * {
+     * Promise<{
      *   id: number
      *   first_name: string
      *   last_name?: string
-     * }
+     * }>
      * ```
      */
     $if(condition, func) {
@@ -367,25 +405,33 @@ export class DeleteQueryBuilder {
      * Turn this code:
      *
      * ```ts
+     * import type { Person } from 'type-editor' // imaginary module
+     *
      * const person = await db.deleteFrom('person')
-     *   .where('id', '=', id)
+     *   .where('id', '=', 3)
      *   .where('nullable_column', 'is not', null)
      *   .returningAll()
      *   .executeTakeFirstOrThrow()
      *
-     * if (person.nullable_column) {
+     * if (isWithNoNullValue(person)) {
      *   functionThatExpectsPersonWithNonNullValue(person)
      * }
+     *
+     * function isWithNoNullValue(person: Person): person is Person & { nullable_column: string } {
+     *   return person.nullable_column != null
+     * }
      * ```
      *
      * Into this:
      *
      * ```ts
+     * import type { NotNull } from 'kysely'
+     *
      * const person = await db.deleteFrom('person')
-     *   .where('id', '=', id)
+     *   .where('id', '=', 3)
      *   .where('nullable_column', 'is not', null)
      *   .returningAll()
-     *   .$narrowType<{ nullable_column: string }>()
+     *   .$narrowType<{ nullable_column: NotNull }>()
      *   .executeTakeFirstOrThrow()
      *
      * functionThatExpectsPersonWithNonNullValue(person)
@@ -417,22 +463,26 @@ export class DeleteQueryBuilder {
      * ### Examples
      *
      * ```ts
-     * const result = await db
-     *   .with('deleted_person', (qb) => qb
-     *     .deleteFrom('person')
-     *     .where('id', '=', person.id)
-     *     .returning('first_name')
-     *     .$assertType<{ first_name: string }>()
-     *   )
-     *   .with('deleted_pet', (qb) => qb
-     *     .deleteFrom('pet')
-     *     .where('owner_id', '=', person.id)
-     *     .returning(['name as pet_name', 'species'])
-     *     .$assertType<{ pet_name: string, species: Species }>()
-     *   )
-     *   .selectFrom(['deleted_person', 'deleted_pet'])
-     *   .selectAll()
-     *   .executeTakeFirstOrThrow()
+     * import type { Species } from 'type-editor' // imaginary module
+     *
+     * async function deletePersonAndPets(personId: number) {
+     *   return await db
+     *     .with('deleted_person', (qb) => qb
+     *        .deleteFrom('person')
+     *        .where('id', '=', personId)
+     *        .returning('first_name')
+     *        .$assertType<{ first_name: string }>()
+     *     )
+     *     .with('deleted_pets', (qb) => qb
+     *       .deleteFrom('pet')
+     *       .where('owner_id', '=', personId)
+     *       .returning(['name as pet_name', 'species'])
+     *       .$assertType<{ pet_name: string, species: Species }>()
+     *     )
+     *     .selectFrom(['deleted_person', 'deleted_pets'])
+     *     .selectAll()
+     *     .execute()
+     * }
      * ```
      */
     $assertType() {