kysely 0.23.4 → 0.23.5

package/dist/esm/query-builder/function-module.js

@@ -2,6 +2,7 @@
 import { AggregateFunctionNode } from '../operation-node/aggregate-function-node.js';
 import { parseCoalesce, } from '../parser/coalesce-parser.js';
 import { parseSimpleReferenceExpression, } from '../parser/reference-parser.js';
+import { parseSelectAll } from '../parser/select-parser.js';
 import { RawBuilder } from '../raw-builder/raw-builder.js';
 import { createQueryId } from '../util/query-id.js';
 import { AggregateFunctionBuilder } from './aggregate-function-builder.js';
@@ -42,6 +43,7 @@ export class FunctionModule {
         this.avg = this.avg.bind(this);
         this.coalesce = this.coalesce.bind(this);
         this.count = this.count.bind(this);
+        this.countAll = this.countAll.bind(this);
         this.max = this.max.bind(this);
         this.min = this.min.bind(this);
         this.sum = this.sum.bind(this);
@@ -49,8 +51,38 @@ export class FunctionModule {
     /**
      * Calls the `avg` function for the column given as the argument.
      *
-     * If this 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
+     * This sql function calculates the average value for a given column.
+     *
+     * For additional functionality such as distinct, filtering and window functions,
+     * refer to {@link AggregateFunctionBuilder}. An instance of this builder is
+     * returned when calling this function.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const { avg } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(avg('price').as('avg_price'))
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * 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(qb => qb.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
      * to configure the output type of large numbers and Kysely can't know if you've
@@ -69,7 +101,7 @@ export class FunctionModule {
      *
      * 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 `coalesce`
+     * and handle null values in post-execute code, or wrap the function with a {@link coalesce}
      * function.
      *
      * ```ts
@@ -88,36 +120,66 @@ export class FunctionModule {
     /**
      * Calls the `coalesce` function for given arguments.
      *
-     * This function returns the first non-null value from left to right, commonly
+     * This sql function returns the first non-null value from left to right, commonly
      * used to provide a default scalar for nullable columns or functions.
      *
+     * If this function is used in a `select` statement, the type of the selected
+     * expression is inferred in the same manner that the sql function computes.
+     * A union of arguments' types - if a non-nullable argument exists, it stops
+     * there (ignoring any further arguments' types) and exludes null from the final
+     * union type.
+     *
+     * `(string | null, number | null)` is inferred as `string | number | null`.
+     *
+     * `(string | null, number, Date | null)` is inferred as `string | number`.
+     *
+     * `(number, string | null)` is inferred as `number`.
+     *
+     * ### Examples
+     *
      * ```ts
-     * const { coalesce, max } = db.fn
+     * const { coalesce } = db.fn
      *
-     * db.selectFrom('person')
-     *   .select(coalesce(max('age'), sql<number>`0`).as('max_age'))
-     *   .where('first_name', '=', 'Jennifer')
+     * db.selectFrom('participant')
+     *   .select(coalesce('nickname', sql<string>`'<anonymous>'`).as('nickname'))
+     *   .where('room_id', '=', roomId)
      *   .execute()
      * ```
      *
-     * The generated SQL (postgres):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * select coalesce(max("age"), 0) as "max_age" from "person" where "first_name" = $1
+     * select coalesce("nickname", '<anonymous>') as "nickname"
+     * from "participant" where "room_id" = $1
      * ```
      *
-     * If this is used in a `select` statement the type of the selected expression
-     * is inferred in the same manner that the function computes. A union of arguments'
-     * types - if a non-nullable argument exists, it stops there (ignoring any further
-     * arguments' types) and exludes null from the final union type.
+     * You can limit column range to only columns participating in current query:
      *
-     * Examples:
+     * ```ts
+     * db.selectFrom('participant')
+     *   .select(qb =>
+     *     qb.fn.coalesce('nickname', sql<string>`'<anonymous>'`).as('nickname')
+     *   )
+     *   .where('room_id', '=', roomId)
+     *   .execute()
+     * ```
      *
-     * `(string | null, number | null)` is inferred as `string | number | null`.
+     * You can combine this function with other helpers in this module:
      *
-     * `(string | null, number, Date | null)` is inferred as `string | number`.
+     * ```ts
+     * const { avg, coalesce } = db.fn
      *
-     * `(number, string | null)` is inferred as `number`.
+     * db.selectFrom('person')
+     *   .select(coalesce(avg<number | null>('age'), sql<number>`0`).as('avg_age'))
+     *   .where('first_name', '=', 'Jennifer')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select coalesce(avg("age"), 0) as "avg_age" from "person" where "first_name" = $1
+     * ```
      */
     coalesce(value, ...otherValues) {
         return new RawBuilder({
@@ -128,11 +190,36 @@ export class FunctionModule {
     /**
      * Calls the `count` function for the column given as the argument.
      *
-     * 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
-     * drivers allow you to configure the output type of large numbers and Kysely
+     * When called with a column as argument, this sql function counts the number of rows where there
+     * is a non-null value in that column.
+     *
+     * For counting all rows nulls included (`count(*)`), see {@link countAll}.
+     *
+     * For additional functionality such as distinct, filtering and window functions,
+     * refer to {@link AggregateFunctionBuilder}. An instance of this builder is
+     * returned when calling this function.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const { count } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(count('id').as('num_toys'))
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select count("id") as "num_toys" from "toy"
+     * ```
+     *
+     * 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.
+     * Most drivers allow you to configure the output type of large numbers and Kysely
      * can't know if you've done so.
      *
      * You can specify the output type of the expression by providing
@@ -146,11 +233,11 @@ export class FunctionModule {
      *   .execute()
      * ```
      *
-     * You can limit column range:
+     * You can limit column range to only columns participating in current query:
      *
      * ```ts
      * db.selectFrom('toy')
-     *   .select(qb => qb.fn.count<number>('id').as('num_toys'))
+     *   .select(qb => qb.fn.count('id').as('num_toys'))
      *   .execute()
      * ```
      */
@@ -159,6 +246,11 @@ export class FunctionModule {
             aggregateFunctionNode: AggregateFunctionNode.create('count', parseSimpleReferenceExpression(column)),
         });
     }
+    countAll(table) {
+        return new AggregateFunctionBuilder({
+            aggregateFunctionNode: AggregateFunctionNode.create('count', parseSelectAll(table)[0].selection),
+        });
+    }
     max(column) {
         return new AggregateFunctionBuilder({
             aggregateFunctionNode: AggregateFunctionNode.create('max', parseSimpleReferenceExpression(column)),
@@ -172,15 +264,45 @@ export class FunctionModule {
     /**
      * Calls the `sum` function for the column given as the argument.
      *
-     * 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
-     * drivers allow you to configure the output type of large numbers and Kysely
-     * can't know if you've done so.
+     * This sql function sums the values of a given column.
      *
-     * You can specify the output type of the expression by providing
-     * the type as the first type argument:
+     * For additional functionality such as distinct, filtering and window functions,
+     * refer to {@link AggregateFunctionBuilder}. An instance of this builder is
+     * returned when calling this function.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const { sum } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(sum('price').as('total_price'))
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * 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(qb => qb.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
+     * to configure the output type of large numbers and Kysely can't know if you've
+     * done so.
+     *
+     * You can specify the output type of the expression by providing the type as
+     * the first type argument:
      *
      * ```ts
      * const { sum } = db.fn
@@ -192,7 +314,7 @@ export class FunctionModule {
      *
      * 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 `coalesce`
+     * and handle null values in post-execute code, or wrap the function with a {@link coalesce}
      * function.
      *
      * ```ts

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

@@ -3,7 +3,7 @@ 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 { MergePartial, SingleResultType } from '../util/type-utils.js';
+import { MergePartial, SimplifyResult, SimplifySingleResult } from '../util/type-utils.js';
 import { UpdateObject } from '../parser/update-set-parser.js';
 import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
@@ -259,7 +259,6 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *     .doUpdateSet({ species: 'hamster' })
      *   )
      *   .execute()
-     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -587,12 +586,12 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *
      * Also see the {@link executeTakeFirst} and {@link executeTakeFirstOrThrow} methods.
      */
-    execute(): Promise<O[]>;
+    execute(): Promise<SimplifyResult<O>[]>;
     /**
      * Executes the query and returns the first result or undefined if
      * the query returned no result.
      */
-    executeTakeFirst(): Promise<SingleResultType<O>>;
+    executeTakeFirst(): Promise<SimplifySingleResult<O>>;
     /**
      * Executes the query and returns the first result or throws if
      * the query returned no result.
@@ -601,7 +600,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * provide a custom error class as the only argument to throw a different
      * error.
      */
-    executeTakeFirstOrThrow(errorConstructor?: NoResultErrorConstructor): Promise<O>;
+    executeTakeFirstOrThrow(errorConstructor?: NoResultErrorConstructor): Promise<SimplifyResult<O>>;
     /**
      * Executes query with `explain` statement before `insert` keyword.
      *

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

@@ -159,7 +159,6 @@ export class InsertQueryBuilder {
      *     .doUpdateSet({ species: 'hamster' })
      *   )
      *   .execute()
-     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):

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

@@ -5,7 +5,7 @@ import { TableExpression } from '../parser/table-parser.js';
 import { SelectExpression, QueryBuilderWithSelection, SelectAllQueryBuilder } from '../parser/select-parser.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
 import { SelectQueryNode } from '../operation-node/select-query-node.js';
-import { MergePartial, Nullable, SingleResultType } from '../util/type-utils.js';
+import { MergePartial, Nullable, Simplify, SimplifySingleResult } from '../util/type-utils.js';
 import { OrderByDirectionExpression, OrderByExpression } from '../parser/order-by-parser.js';
 import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
@@ -483,7 +483,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * to override the types.
      *
      * Select calls are additive. Calling `select('id').select('first_name')` is the
-     * same as calling `select(['id', 'first_name']).
+     * same as calling `select(['id', 'first_name'])`.
      *
      * To select all columns of the query or specific tables see the
      * {@link selectAll} method.
@@ -892,7 +892,7 @@ export declare class SelectQueryBuilder<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'),
@@ -950,6 +950,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      *   )
      *   .select(['first_name', 'p.name'])
      *   .orderBy('first_name')
+     * ```
      */
     innerJoinLateral<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): SelectQueryBuilderWithInnerJoin<DB, TB, O, TE>;
     innerJoinLateral<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): SelectQueryBuilderWithInnerJoin<DB, TB, O, TE>;
@@ -1564,18 +1565,18 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ```
      */
     toOperationNode(): SelectQueryNode;
-    compile(): CompiledQuery<O>;
+    compile(): CompiledQuery<Simplify<O>>;
     /**
      * Executes the query and returns an array of rows.
      *
      * Also see the {@link executeTakeFirst} and {@link executeTakeFirstOrThrow} methods.
      */
-    execute(): Promise<O[]>;
+    execute(): Promise<Simplify<O>[]>;
     /**
      * Executes the query and returns the first result or undefined if
      * the query returned no result.
      */
-    executeTakeFirst(): Promise<SingleResultType<O>>;
+    executeTakeFirst(): Promise<SimplifySingleResult<O>>;
     /**
      * Executes the query and returns the first result or throws if
      * the query returned no result.
@@ -1584,7 +1585,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * provide a custom error class as the only argument to throw a different
      * error.
      */
-    executeTakeFirstOrThrow(errorConstructor?: NoResultErrorConstructor): Promise<O>;
+    executeTakeFirstOrThrow(errorConstructor?: NoResultErrorConstructor): Promise<Simplify<O>>;
     /**
      * Executes the query and streams the rows.
      *

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

@@ -5,7 +5,7 @@ import { TableExpression, From, FromTables } from '../parser/table-parser.js';
 import { SelectExpression } from '../parser/select-parser.js';
 import { ReturningRow } from '../parser/returning-parser.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
-import { MergePartial, Nullable, SingleResultType } from '../util/type-utils.js';
+import { MergePartial, Nullable, SimplifyResult, SimplifySingleResult } from '../util/type-utils.js';
 import { UpdateQueryNode } from '../operation-node/update-query-node.js';
 import { UpdateObject } from '../parser/update-set-parser.js';
 import { Compilable } from '../util/compilable.js';
@@ -869,18 +869,18 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      */
     withPlugin(plugin: KyselyPlugin): UpdateQueryBuilder<DB, UT, TB, O>;
     toOperationNode(): UpdateQueryNode;
-    compile(): CompiledQuery<O>;
+    compile(): CompiledQuery<SimplifyResult<O>>;
     /**
      * Executes the query and returns an array of rows.
      *
      * Also see the {@link executeTakeFirst} and {@link executeTakeFirstOrThrow} methods.
      */
-    execute(): Promise<O[]>;
+    execute(): Promise<SimplifyResult<O>[]>;
     /**
      * Executes the query and returns the first result or undefined if
      * the query returned no result.
      */
-    executeTakeFirst(): Promise<SingleResultType<O>>;
+    executeTakeFirst(): Promise<SimplifySingleResult<O>>;
     /**
      * Executes the query and returns the first result or throws if
      * the query returned no result.
@@ -889,7 +889,7 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * provide a custom error class as the only argument to throw a different
      * error.
      */
-    executeTakeFirstOrThrow(errorConstructor?: NoResultErrorConstructor): Promise<O>;
+    executeTakeFirstOrThrow(errorConstructor?: NoResultErrorConstructor): Promise<SimplifyResult<O>>;
     /**
      * Executes query with `explain` statement before `update` keyword.
      *

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

@@ -384,7 +384,7 @@ export class UpdateQueryBuilder {
         return [
             new UpdateResult(
             // TODO: remove numUpdatedOrDeletedRows.
-            (result.numAffectedRows ?? result.numUpdatedOrDeletedRows)),
+            result.numAffectedRows ?? result.numUpdatedOrDeletedRows ?? 0n),
         ];
     }
     /**

package/dist/esm/query-compiler/default-query-compiler.js

@@ -862,7 +862,7 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         if (node.distinct) {
             this.append('distinct ');
         }
-        this.visitNode(node.column);
+        this.visitNode(node.aggregated);
         this.append(')');
         if (node.filter) {
             this.append(' filter(');

package/dist/esm/query-creator.d.ts

@@ -198,6 +198,8 @@ export declare class QueryCreator<DB> {
      *
      * ### Examples
      *
+     * Deleting person with id 1:
+     *
      * ```ts
      * const result = await db
      *   .deleteFrom('person')
@@ -206,7 +208,34 @@ export declare class QueryCreator<DB> {
      *
      * console.log(result.numDeletedRows)
      * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * delete from "person" where "person"."id" = $1
+     * ```
+     *
+     * Some databases such as MySQL support deleting from multiple tables:
+     *
+     * ```ts
+     * const result = await db
+     *   .deleteFrom(['person', 'pet'])
+     *   .using('person')
+     *   .innerJoin('pet', 'pet.owner_id', '=', 'person.id')
+     *   .where('person.id', '=', 1)
+     *   .executeTakeFirst()
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * delete from `person`, `pet`
+     * using `person`
+     * inner join `pet` on `pet`.`owner_id` = `person`.`id`
+     * where `person`.`id` = ?
+     * ```
      */
+    deleteFrom<TR extends TableReference<DB>>(tables: TR[]): DeleteQueryBuilder<From<DB, TR>, FromTables<DB, never, TR>, DeleteResult>;
     deleteFrom<TR extends TableReference<DB>>(table: TR): DeleteQueryBuilder<From<DB, TR>, FromTables<DB, never, TR>, DeleteResult>;
     /**
      * Creates an update query.

package/dist/esm/query-creator.js

@@ -103,30 +103,11 @@ export class QueryCreator {
             queryNode: InsertQueryNode.create(parseTable(table), this.#props.withNode, true),
         });
     }
-    /**
-     * Creates a delete query.
-     *
-     * See the {@link DeleteQueryBuilder.where} method for examples on how to specify
-     * a where clause for the delete operation.
-     *
-     * The return value of the query is an instance of {@link DeleteResult}.
-     *
-     * ### Examples
-     *
-     * ```ts
-     * const result = await db
-     *   .deleteFrom('person')
-     *   .where('person.id', '=', 1)
-     *   .executeTakeFirst()
-     *
-     * console.log(result.numDeletedRows)
-     * ```
-     */
-    deleteFrom(table) {
+    deleteFrom(tables) {
         return new DeleteQueryBuilder({
             queryId: createQueryId(),
             executor: this.#props.executor,
-            queryNode: DeleteQueryNode.create(parseTableExpression(table), this.#props.withNode),
+            queryNode: DeleteQueryNode.create(parseTableExpressionOrList(tables), this.#props.withNode),
         });
     }
     /**

package/dist/esm/util/type-utils.d.ts

@@ -100,10 +100,11 @@ export declare type ArrayItemType<T> = T extends ReadonlyArray<infer I> ? I : ne
  * Any select query builder.
  */
 export declare type AnySelectQueryBuilder = SelectQueryBuilder<any, any, any>;
-/**
- * Given a query output type `O` evaluates to the output type of a `executeTakeFirst` call.
- */
-export declare type SingleResultType<O> = O extends InsertResult ? O : O extends DeleteResult ? O : O extends UpdateResult ? O : O | undefined;
+export declare type SimplifySingleResult<O> = O extends InsertResult ? O : O extends DeleteResult ? O : O extends UpdateResult ? O : Simplify<O> | undefined;
+export declare type SimplifyResult<O> = O extends InsertResult ? O : O extends DeleteResult ? O : O extends UpdateResult ? O : Simplify<O>;
+export declare type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
 /**
  * Represents a database row whose column names and their types are unknown.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kysely",
-  "version": "0.23.4",
+  "version": "0.23.5",
   "description": "Type safe SQL query builder",
   "repository": {
     "type": "git",