kysely 0.27.3 → 0.27.5

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

@@ -123,16 +123,29 @@ export class DeleteQueryBuilder {
             queryNode: QueryNode.cloneWithReturning(this.#props.queryNode, parseSelectAll(table)),
         });
     }
+    output(args) {
+        return new DeleteQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithOutput(this.#props.queryNode, parseSelectArg(args)),
+        });
+    }
+    outputAll(table) {
+        return new DeleteQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithOutput(this.#props.queryNode, parseSelectAll(table)),
+        });
+    }
     /**
      * Clears all `returning` clauses from the query.
      *
      * ### Examples
      *
      * ```ts
-     * db.deleteFrom('pet')
+     * await db.deleteFrom('pet')
      *   .returningAll()
      *   .where('name', '=', 'Max')
      *   .clearReturning()
+     *   .execute()
      * ```
      *
      * The generated SQL(PostgreSQL):
@@ -153,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):
@@ -178,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):
@@ -254,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({
@@ -261,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.
@@ -273,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()
      * ```
@@ -314,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) {
@@ -355,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)
@@ -385,17 +443,17 @@ export class DeleteQueryBuilder {
     /**
      * Asserts that query's output row type equals the given type `T`.
      *
-     * This method can be used to simplify excessively complex types to make typescript happy
+     * This method can be used to simplify excessively complex types to make TypeScript happy
      * and much faster.
      *
      * Kysely uses complex type magic to achieve its type safety. This complexity is sometimes too much
-     * for typescript and you get errors like this:
+     * for TypeScript and you get errors like this:
      *
      * ```
      * error TS2589: Type instantiation is excessively deep and possibly infinite.
      * ```
      *
-     * In these case you can often use this method to help typescript a little bit. When you use this
+     * In these case you can often use this method to help TypeScript a little bit. When you use this
      * method to assert the output type of a query, Kysely can drop the complex output type that
      * consists of multiple nested helper types and replace it with the simple asserted type.
      *
@@ -405,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() {
@@ -448,9 +510,11 @@ export class DeleteQueryBuilder {
      */
     async execute() {
         const compiledQuery = this.compile();
-        const query = compiledQuery.query;
         const result = await this.#props.executor.executeQuery(compiledQuery, this.#props.queryId);
-        if (this.#props.executor.adapter.supportsReturning && query.returning) {
+        const { adapter } = this.#props.executor;
+        const query = compiledQuery.query;
+        if ((query.returning && adapter.supportsReturning) ||
+            (query.output && adapter.supportsOutput)) {
             return result.rows;
         }
         return [

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

@@ -88,9 +88,10 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .selectAll('person')
      *   .where(db.fn('upper', ['first_name']), '=', 'JENNIFER')
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -104,9 +105,12 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * If you prefer readability over type-safety, you can always use raw `sql`:
      *
      * ```ts
-     * db.selectFrom('person')
+     * import { sql } from 'kysely'
+     *
+     * await db.selectFrom('person')
      *   .selectAll('person')
-     *   .where(sql`upper(first_name)`, '=', 'JENNIFER')
+     *   .where(sql<string>`upper(first_name)`, '=', 'JENNIFER')
+     *   .execute()
      * ```
      */
     <O, RE extends ReferenceExpression<DB, TB> = ReferenceExpression<DB, TB>>(name: string, args?: ReadonlyArray<RE>): ExpressionWrapper<DB, TB, O>;
@@ -123,11 +127,12 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .select(({ fn }) => [
      *     fn.agg<number>('rank').over().as('rank'),
      *     fn.agg<string>('group_concat', ['first_name']).distinct().as('first_names')
      *   ])
+     *   .execute()
      * ```
      *
      * The generated SQL (MySQL):
@@ -151,7 +156,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('toy')
+     * await db.selectFrom('toy')
      *   .select((eb) => eb.fn.avg('price').as('avg_price'))
      *   .execute()
      * ```
@@ -162,18 +167,10 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * select avg("price") as "avg_price" from "toy"
      * ```
      *
-     * You can limit column range to only columns participating in current query:
-     *
-     * ```ts
-     * db.selectFrom('toy')
-     *   .select((eb) => eb.fn.avg('price').as('avg_price'))
-     *   .execute()
-     * ```
-     *
      * If this function is used in a `select` statement, the type of the selected
      * expression will be `number | string` by default. This is because Kysely can't know the
      * type the db driver outputs. Sometimes the output can be larger than the largest
-     * javascript number and a string is returned instead. Most drivers allow you
+     * JavaScript number and a string is returned instead. Most drivers allow you
      * to configure the output type of large numbers and Kysely can't know if you've
      * done so.
      *
@@ -181,7 +178,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * the first type argument:
      *
      * ```ts
-     * db.selectFrom('toy')
+     * await db.selectFrom('toy')
      *   .select((eb) => eb.fn.avg<number>('price').as('avg_price'))
      *   .execute()
      * ```
@@ -192,7 +189,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * function.
      *
      * ```ts
-     * db.selectFrom('toy')
+     * await db.selectFrom('toy')
      *   .select((eb) => eb.fn.avg<number | null>('price').as('avg_price'))
      *   .execute()
      * ```
@@ -219,35 +216,25 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('participant')
-     *   .select((eb) => eb.fn.coalesce('nickname', sql<string>`'<anonymous>'`).as('nickname'))
-     *   .where('room_id', '=', roomId)
+     * import { sql } from 'kysely'
+     *
+     * await db.selectFrom('person')
+     *   .select((eb) => eb.fn.coalesce('nullable_column', sql.lit('<unknown>')).as('column'))
+     *   .where('first_name', '=', 'Jessie')
      *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * select coalesce("nickname", '<anonymous>') as "nickname"
-     * from "participant" where "room_id" = $1
-     * ```
-     *
-     * You can limit column range to only columns participating in current query:
-     *
-     * ```ts
-     * db.selectFrom('participant')
-     *   .select((eb) =>
-     *     eb.fn.coalesce('nickname', sql<string>`'<anonymous>'`).as('nickname')
-     *   )
-     *   .where('room_id', '=', roomId)
-     *   .execute()
+     * select coalesce("nullable_column", '<unknown>') as "column" from "person" where "first_name" = $1
      * ```
      *
      * You can combine this function with other helpers in this module:
      *
      * ```ts
-     * db.selectFrom('person')
-     *   .select((eb) => eb.fn.coalesce(eb.fn.avg<number | null>('age'), sql<number>`0`).as('avg_age'))
+     * await db.selectFrom('person')
+     *   .select((eb) => eb.fn.coalesce(eb.fn.avg<number | null>('age'), eb.lit(0)).as('avg_age'))
      *   .where('first_name', '=', 'Jennifer')
      *   .execute()
      * ```
@@ -278,7 +265,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('toy')
+     * await db.selectFrom('toy')
      *   .select((eb) => eb.fn.count('id').as('num_toys'))
      *   .execute()
      * ```
@@ -292,7 +279,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * If this function is used in a `select` statement, the type of the selected
      * expression will be `number | string | bigint` by default. This is because
      * Kysely can't know the type the db driver outputs. Sometimes the output can
-     * be larger than the largest javascript number and a string is returned instead.
+     * be larger than the largest JavaScript number and a string is returned instead.
      * Most drivers allow you to configure the output type of large numbers and Kysely
      * can't know if you've done so.
      *
@@ -300,18 +287,10 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * the type as the first type argument:
      *
      * ```ts
-     * db.selectFrom('toy')
+     * await db.selectFrom('toy')
      *   .select((eb) => eb.fn.count<number>('id').as('num_toys'))
      *   .execute()
      * ```
-     *
-     * You can limit column range to only columns participating in current query:
-     *
-     * ```ts
-     * db.selectFrom('toy')
-     *   .select((eb) => eb.fn.count('id').as('num_toys'))
-     *   .execute()
-     * ```
      */
     count<O extends number | string | bigint, RE extends ReferenceExpression<DB, TB> = ReferenceExpression<DB, TB>>(expr: RE): AggregateFunctionBuilder<DB, TB, O>;
     /**
@@ -330,7 +309,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('toy')
+     * await db.selectFrom('toy')
      *   .select((eb) => eb.fn.countAll().as('num_toys'))
      *   .execute()
      * ```
@@ -344,7 +323,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * If this is used in a `select` statement, the type of the selected expression
      * will be `number | string | bigint` by default. This is because Kysely
      * can't know the type the db driver outputs. Sometimes the output can be larger
-     * than the largest javascript number and a string is returned instead. Most
+     * than the largest JavaScript number and a string is returned instead. Most
      * drivers allow you to configure the output type of large numbers and Kysely
      * can't know if you've done so.
      *
@@ -352,7 +331,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * the type as the first type argument:
      *
      * ```ts
-     * db.selectFrom('toy')
+     * await db.selectFrom('toy')
      *   .select((eb) => eb.fn.countAll<number>().as('num_toys'))
      *   .execute()
      * ```
@@ -361,7 +340,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * table:
      *
      * ```ts
-     * db.selectFrom('toy')
+     * await db.selectFrom('toy')
      *   .innerJoin('pet', 'pet.id', 'toy.pet_id')
      *   .select((eb) => eb.fn.countAll('toy').as('num_toys'))
      *   .execute()
@@ -373,15 +352,6 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * select count("toy".*) as "num_toys"
      * from "toy" inner join "pet" on "pet"."id" = "toy"."pet_id"
      * ```
-     *
-     * You can limit table range to only tables participating in current query:
-     *
-     * ```ts
-     * db.selectFrom('toy')
-     *   .innerJoin('pet', 'pet.id', 'toy.pet_id')
-     *   .select((eb) => eb.fn.countAll('toy').as('num_toys'))
-     *   .execute()
-     * ```
      */
     countAll<O extends number | string | bigint, T extends TB = TB>(table: T): AggregateFunctionBuilder<DB, TB, O>;
     countAll<O extends number | string | bigint>(): AggregateFunctionBuilder<DB, TB, O>;
@@ -401,7 +371,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('toy')
+     * await db.selectFrom('toy')
      *   .select((eb) => eb.fn.max('price').as('max_price'))
      *   .execute()
      * ```
@@ -412,21 +382,13 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * select max("price") as "max_price" from "toy"
      * ```
      *
-     * You can limit column range to only columns participating in current query:
-     *
-     * ```ts
-     * db.selectFrom('toy')
-     *   .select((eb) => eb.fn.max('price').as('max_price'))
-     *   .execute()
-     * ```
-     *
      * Sometimes a null is returned, e.g. when row count is 0, and no `group by`
      * was used. It is highly recommended to include null in the output type union
      * and handle null values in post-execute code, or wrap the function with a {@link coalesce}
      * function.
      *
      * ```ts
-     * db.selectFrom('toy')
+     * await db.selectFrom('toy')
      *   .select((eb) => eb.fn.max<number | null>('price').as('max_price'))
      *   .execute()
      * ```
@@ -448,7 +410,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('toy')
+     * await db.selectFrom('toy')
      *   .select((eb) => eb.fn.min('price').as('min_price'))
      *   .execute()
      * ```
@@ -459,21 +421,13 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * select min("price") as "min_price" from "toy"
      * ```
      *
-     * You can limit column range to only columns participating in current query:
-     *
-     * ```ts
-     * db.selectFrom('toy')
-     *   .select((eb) => eb.fn.min('price').as('min_price'))
-     *   .execute()
-     * ```
-     *
      * Sometimes a null is returned, e.g. when row count is 0, and no `group by`
      * was used. It is highly recommended to include null in the output type union
      * and handle null values in post-execute code, or wrap the function with a {@link coalesce}
      * function.
      *
      * ```ts
-     * db.selectFrom('toy')
+     * await db.selectFrom('toy')
      *   .select((eb) => eb.fn.min<number | null>('price').as('min_price'))
      *   .execute()
      * ```
@@ -491,7 +445,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('toy')
+     * await db.selectFrom('toy')
      *   .select((eb) => eb.fn.sum('price').as('total_price'))
      *   .execute()
      * ```
@@ -502,18 +456,10 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * select sum("price") as "total_price" from "toy"
      * ```
      *
-     * You can limit column range to only columns participating in current query:
-     *
-     * ```ts
-     * db.selectFrom('toy')
-     *   .select((eb) => eb.fn.sum('price').as('total_price'))
-     *   .execute()
-     * ```
-     *
      * If this function is used in a `select` statement, the type of the selected
      * expression will be `number | string` by default. This is because Kysely can't know the
      * type the db driver outputs. Sometimes the output can be larger than the largest
-     * javascript number and a string is returned instead. Most drivers allow you
+     * JavaScript number and a string is returned instead. Most drivers allow you
      * to configure the output type of large numbers and Kysely can't know if you've
      * done so.
      *
@@ -521,7 +467,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * the first type argument:
      *
      * ```ts
-     * db.selectFrom('toy')
+     * await db.selectFrom('toy')
      *   .select((eb) => eb.fn.sum<number>('price').as('total_price'))
      *   .execute()
      * ```
@@ -532,7 +478,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * function.
      *
      * ```ts
-     * db.selectFrom('toy')
+     * await db.selectFrom('toy')
      *   .select((eb) => eb.fn.sum<number | null>('price').as('total_price'))
      *   .execute()
      * ```
@@ -548,11 +494,12 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * In the following example, `nicknames` is assumed to be a column of type `string[]`:
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .selectAll('person')
      *   .where((eb) => eb(
      *     eb.val('Jen'), '=', eb.fn.any('person.nicknames')
      *   ))
+     *   .execute()
      * ```
      *
      *
@@ -576,7 +523,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * This function is only available on PostgreSQL.
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .innerJoin('pet', 'pet.owner_id', 'person.id')
      *   .select((eb) => ['first_name', eb.fn.jsonAgg('pet').as('pets')])
      *   .groupBy('person.first_name')
@@ -599,7 +546,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * This function is only available on PostgreSQL.
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .innerJoin('pet', 'pet.owner_id', 'person.id')
      *   .select((eb) => ['first_name', eb.fn.toJson('pet').as('pet')])
      *   .execute()