kysely 0.23.3 → 0.23.5

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

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DeleteQueryBuilder = void 0;
 const join_parser_js_1 = require("../parser/join-parser.js");
+const table_parser_js_1 = require("../parser/table-parser.js");
 const select_parser_js_1 = require("../parser/select-parser.js");
 const query_node_js_1 = require("../operation-node/query-node.js");
 const prevent_await_js_1 = require("../util/prevent-await.js");
@@ -73,6 +74,12 @@ class DeleteQueryBuilder {
             queryNode: query_node_js_1.QueryNode.cloneWithoutWhere(this.#props.queryNode),
         });
     }
+    using(tables) {
+        return new DeleteQueryBuilder({
+            ...this.#props,
+            queryNode: delete_query_node_js_1.DeleteQueryNode.cloneWithUsing(this.#props.queryNode, (0, table_parser_js_1.parseTableExpressionOrList)(tables)),
+        });
+    }
     innerJoin(...args) {
         return new DeleteQueryBuilder({
             ...this.#props,
@@ -177,7 +184,7 @@ class DeleteQueryBuilder {
      * 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
      *
@@ -190,13 +197,19 @@ class DeleteQueryBuilder {
      * }
      *
      * db.deleteFrom('person')
-     *   .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.
      *
@@ -215,7 +228,7 @@ class DeleteQueryBuilder {
      *     .deleteFrom('person')
      *     .where('id', '=', id)
      *     .returning(['id', 'first_name'])
-     *     .if(returnLastName, (qb) => qb.returning('last_name'))
+     *     .$if(returnLastName, (qb) => qb.returning('last_name'))
      *     .executeTakeFirstOrThrow()
      * }
      * ```
@@ -232,7 +245,7 @@ class DeleteQueryBuilder {
      * }
      * ```
      */
-    if(condition, func) {
+    $if(condition, func) {
         if (condition) {
             return func(this);
         }
@@ -240,15 +253,27 @@ class DeleteQueryBuilder {
             ...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 DeleteQueryBuilder(this.#props);
     }
+    /**
+     * @deprecated Use `$castTo` instead.
+     */
+    castTo() {
+        return this.$castTo();
+    }
     /**
      * Asserts that query's output row type equals the given type `T`.
      *
@@ -277,19 +302,25 @@ class DeleteQueryBuilder {
      *     .deleteFrom('person')
      *     .where('id', '=', person.id)
      *     .returning('first_name')
-     *     .assertType<{ first_name: string }>()
+     *     .$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 }>()
+     *     .$assertType<{ pet_name: string, species: Species }>()
      *   )
      *   .selectFrom(['deleted_person', 'deleted_pet'])
      *   .selectAll()
      *   .executeTakeFirstOrThrow()
      * ```
      */
+    $assertType() {
+        return new DeleteQueryBuilder(this.#props);
+    }
+    /**
+     * @deprecated Use `$assertType` instead.
+     */
     assertType() {
         return new DeleteQueryBuilder(this.#props);
     }
@@ -323,7 +354,7 @@ class DeleteQueryBuilder {
         return [
             new delete_result_js_1.DeleteResult(
             // TODO: remove numUpdatedOrDeletedRows.
-            (result.numAffectedRows ?? result.numUpdatedOrDeletedRows)),
+            result.numAffectedRows ?? result.numUpdatedOrDeletedRows ?? 0n),
         ];
     }
     /**

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

@@ -41,8 +41,38 @@ export declare class FunctionModule<DB, TB extends keyof DB> {
     /**
      * 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
@@ -61,7 +91,7 @@ export declare class FunctionModule<DB, TB extends keyof DB> {
      *
      * 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
@@ -76,42 +106,153 @@ export declare class FunctionModule<DB, TB extends keyof DB> {
     /**
      * 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<V extends ReferenceExpression<DB, TB>, OV extends ReferenceExpression<DB, TB>[]>(value: V, ...otherValues: OV): RawBuilder<CoalesceReferenceExpressionList<DB, TB, [V, ...OV]>>;
     /**
      * 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
+     * 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
+     * the type as the first type argument:
+     *
+     * ```ts
+     * const { count } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(count<number>('id').as('num_toys'))
+     *   .execute()
+     * ```
+     *
+     * You can limit column range to only columns participating in current query:
+     *
+     * ```ts
+     * db.selectFrom('toy')
+     *   .select(qb => qb.fn.count('id').as('num_toys'))
+     *   .execute()
+     * ```
+     */
+    count<O extends number | string | bigint, C extends SimpleReferenceExpression<DB, TB> = SimpleReferenceExpression<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
+    /**
+     * Calls the `count` function with `*` or `table.*` as argument.
+     *
+     * When called with `*` as argument, this sql function counts the number of rows,
+     * nulls included.
+     *
+     * For counting rows with non-null values in a given column (`count(column)`),
+     * see {@link count}.
+     *
+     * For additional functionality such as filtering and window functions, refer
+     * to {@link AggregateFunctionBuilder}. An instance of this builder is returned
+     * when calling this function.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const { countAll } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(countAll().as('num_toys'))
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select count(*) as "num_toys" from "toy"
+     * ```
+     *
+     * 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
@@ -122,27 +263,55 @@ export declare class FunctionModule<DB, TB extends keyof DB> {
      * the type as the first type argument:
      *
      * ```ts
-     * const { count } = db.fn
+     * const { countAll } = db.fn
      *
      * db.selectFrom('toy')
-     *   .select(count<number>('id').as('num_toys'))
+     *   .select(countAll<number>().as('num_toys'))
      *   .execute()
      * ```
      *
-     * You can limit column range:
+     * Some databases, such as PostgreSQL, support scoping the function to a specific
+     * table:
      *
      * ```ts
+     * const { countAll } = db.fn
+     *
      * db.selectFrom('toy')
-     *   .select(qb => qb.fn.count<number>('id').as('num_toys'))
+     *   .innerJoin('pet', 'pet.id', 'toy.pet_id')
+     *   .select(countAll('toy').as('num_toys'))
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * 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(qb => qb.fn.countAll('toy').as('num_toys'))
      *   .execute()
      * ```
      */
-    count<O extends number | string | bigint, C extends SimpleReferenceExpression<DB, TB> = SimpleReferenceExpression<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
+    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>;
     /**
      * Calls the `max` function for the column given as the argument.
      *
-     * If this is used in a `select` statement the type of the selected expression
-     * will be the referenced column's type.
+     * This sql function calculates the maximum 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.
+     *
+     * If this function is used in a `select` statement, the type of the selected
+     * expression will be the referenced column's type. This is because the result
+     * is within the column's value range.
      *
      * ### Examples
      *
@@ -154,9 +323,23 @@ export declare class FunctionModule<DB, TB extends keyof DB> {
      *   .execute()
      * ```
      *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * 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(qb => qb.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 `coalesce`
+     * and handle null values in post-execute code, or wrap the function with a {@link coalesce}
      * function.
      *
      * ```ts
@@ -172,8 +355,15 @@ export declare class FunctionModule<DB, TB extends keyof DB> {
     /**
      * Calls the `min` function for the column given as the argument.
      *
-     * If this is used in a `select` statement the type of the selected expression
-     * will be the referenced column's type.
+     * This sql function calculates the minimum 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.
+     *
+     * If this function is used in a `select` statement, the type of the selected
+     * expression will be the referenced column's type. This is because the result
+     * is within the column's value range.
      *
      * ### Examples
      *
@@ -185,9 +375,23 @@ export declare class FunctionModule<DB, TB extends keyof DB> {
      *   .execute()
      * ```
      *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * 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(qb => qb.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 `coalesce`
+     * and handle null values in post-execute code, or wrap the function with a {@link coalesce}
      * function.
      *
      * ```ts
@@ -203,15 +407,45 @@ export declare class FunctionModule<DB, TB extends keyof DB> {
     /**
      * 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
@@ -223,7 +457,7 @@ export declare class FunctionModule<DB, TB extends keyof DB> {
      *
      * 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