kysely 0.23.3 → 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):
@@ -456,7 +455,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * Simply calls the given function passing `this` as the only argument.
      *
      * If you want to conditionally call a method on `this`, see
-     * the {@link if} method.
+     * the {@link $if} method.
      *
      * ### Examples
      *
@@ -470,10 +469,14 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *
      * db.updateTable('person')
      *   .set(values)
-     *   .call(log)
+     *   .$call(log)
      *   .execute()
      * ```
      */
+    $call<T>(func: (qb: this) => T): T;
+    /**
+     * @deprecated Use `$call` instead
+     */
     call<T>(func: (qb: this) => T): T;
     /**
      * Call `func(this)` if `condition` is true.
@@ -493,7 +496,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *     .insertInto('person')
      *     .values(values)
      *     .returning(['id', 'first_name'])
-     *     .if(returnLastName, (qb) => qb.returning('last_name'))
+     *     .$if(returnLastName, (qb) => qb.returning('last_name'))
      *     .executeTakeFirstOrThrow()
      * }
      * ```
@@ -510,6 +513,10 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * }
      * ```
      */
+    $if<O2>(condition: boolean, func: (qb: this) => InsertQueryBuilder<DB, TB, O2>): InsertQueryBuilder<DB, TB, O2 extends InsertResult ? InsertResult : O extends InsertResult ? Partial<O2> : MergePartial<O, O2>>;
+    /**
+     * @deprecated Use `$if` instead
+     */
     if<O2>(condition: boolean, func: (qb: this) => InsertQueryBuilder<DB, TB, O2>): InsertQueryBuilder<DB, TB, O2 extends InsertResult ? InsertResult : O extends InsertResult ? Partial<O2> : MergePartial<O, O2>>;
     /**
      * Change the output type of the query.
@@ -517,6 +524,10 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * You should only use this method as the last resort if the types
      * don't support your use case.
      */
+    $castTo<T>(): InsertQueryBuilder<DB, TB, T>;
+    /**
+     * @deprecated Use `$castTo` instead.
+     */
     castTo<T>(): InsertQueryBuilder<DB, TB, T>;
     /**
      * Asserts that query's output row type equals the given type `T`.
@@ -546,19 +557,23 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *     .insertInto('person')
      *     .values(person)
      *     .returning('id')
-     *     .assertType<{ id: string }>()
+     *     .$assertType<{ id: string }>()
      *   )
      *   .with('new_pet', (qb) => qb
      *     .insertInto('pet')
      *     .values({ owner_id: (eb) => eb.selectFrom('new_person').select('id'), ...pet })
      *     .returning(['name as pet_name', 'species'])
-     *     .assertType<{ pet_name: string, species: Species }>()
+     *     .$assertType<{ pet_name: string, species: Species }>()
      *   )
      *   .selectFrom(['new_person', 'new_pet'])
      *   .selectAll()
      *   .executeTakeFirstOrThrow()
      * ```
      */
+    $assertType<T extends O>(): O extends T ? InsertQueryBuilder<DB, TB, T> : KyselyTypeError<`$assertType() call failed: The type passed in is not equal to the output type of the query.`>;
+    /**
+     * @deprecated Use `$assertType` instead.
+     */
     assertType<T extends O>(): O extends T ? InsertQueryBuilder<DB, TB, T> : KyselyTypeError<`assertType() call failed: The type passed in is not equal to the output type of the query.`>;
     /**
      * Returns a copy of this InsertQueryBuilder instance with the given plugin installed.
@@ -571,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.
@@ -585,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

@@ -3,7 +3,7 @@ import { parseSelectExpressionOrList, parseSelectAll, } from '../parser/select-p
 import { parseInsertObjectOrList, } from '../parser/insert-values-parser.js';
 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 { parseUpdateObject } from '../parser/update-set-parser.js';
 import { preventAwait } from '../util/prevent-await.js';
 import { freeze } from '../util/object-utils.js';
 import { OnDuplicateKeyNode } from '../operation-node/on-duplicate-key-node.js';
@@ -159,7 +159,6 @@ export class InsertQueryBuilder {
      *     .doUpdateSet({ species: 'hamster' })
      *   )
      *   .execute()
-     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -318,7 +317,7 @@ export class InsertQueryBuilder {
      * Simply calls the given function passing `this` as the only argument.
      *
      * If you want to conditionally call a method on `this`, see
-     * the {@link if} method.
+     * the {@link $if} method.
      *
      * ### Examples
      *
@@ -332,13 +331,19 @@ export class InsertQueryBuilder {
      *
      * db.updateTable('person')
      *   .set(values)
-     *   .call(log)
+     *   .$call(log)
      *   .execute()
      * ```
      */
-    call(func) {
+    $call(func) {
         return func(this);
     }
+    /**
+     * @deprecated Use `$call` instead
+     */
+    call(func) {
+        return this.$call(func);
+    }
     /**
      * Call `func(this)` if `condition` is true.
      *
@@ -357,7 +362,7 @@ export class InsertQueryBuilder {
      *     .insertInto('person')
      *     .values(values)
      *     .returning(['id', 'first_name'])
-     *     .if(returnLastName, (qb) => qb.returning('last_name'))
+     *     .$if(returnLastName, (qb) => qb.returning('last_name'))
      *     .executeTakeFirstOrThrow()
      * }
      * ```
@@ -374,7 +379,7 @@ export class InsertQueryBuilder {
      * }
      * ```
      */
-    if(condition, func) {
+    $if(condition, func) {
         if (condition) {
             return func(this);
         }
@@ -382,15 +387,27 @@ export class InsertQueryBuilder {
             ...this.#props,
         });
     }
+    /**
+     * @deprecated Use `$if` instead
+     */
+    if(condition, func) {
+        return this.$if(condition, func);
+    }
     /**
      * Change the output type of the query.
      *
      * You should only use this method as the last resort if the types
      * don't support your use case.
      */
-    castTo() {
+    $castTo() {
         return new InsertQueryBuilder(this.#props);
     }
+    /**
+     * @deprecated Use `$castTo` instead.
+     */
+    castTo() {
+        return this.$castTo();
+    }
     /**
      * Asserts that query's output row type equals the given type `T`.
      *
@@ -419,19 +436,25 @@ export class InsertQueryBuilder {
      *     .insertInto('person')
      *     .values(person)
      *     .returning('id')
-     *     .assertType<{ id: string }>()
+     *     .$assertType<{ id: string }>()
      *   )
      *   .with('new_pet', (qb) => qb
      *     .insertInto('pet')
      *     .values({ owner_id: (eb) => eb.selectFrom('new_person').select('id'), ...pet })
      *     .returning(['name as pet_name', 'species'])
-     *     .assertType<{ pet_name: string, species: Species }>()
+     *     .$assertType<{ pet_name: string, species: Species }>()
      *   )
      *   .selectFrom(['new_person', 'new_pet'])
      *   .selectAll()
      *   .executeTakeFirstOrThrow()
      * ```
      */
+    $assertType() {
+        return new InsertQueryBuilder(this.#props);
+    }
+    /**
+     * @deprecated Use `$assertType` instead.
+     */
     assertType() {
         return new InsertQueryBuilder(this.#props);
     }