kysely 0.23.4 → 0.24.0

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

@@ -1,7 +1,7 @@
 import { DynamicReferenceBuilder } from '../dynamic/dynamic-reference-builder.js';
+import { ExpressionWrapper } from '../expression/expression-wrapper.js';
 import { CoalesceReferenceExpressionList } from '../parser/coalesce-parser.js';
 import { ExtractTypeFromReferenceExpression, SimpleReferenceExpression, ReferenceExpression, StringReference } from '../parser/reference-parser.js';
-import { RawBuilder } from '../raw-builder/raw-builder.js';
 import { Equals, IsNever } from '../util/type-utils.js';
 import { AggregateFunctionBuilder } from './aggregate-function-builder.js';
 /**
@@ -36,13 +36,70 @@ import { AggregateFunctionBuilder } from './aggregate-function-builder.js';
  * having count("pet"."id") > $1
  * ```
  */
-export declare class FunctionModule<DB, TB extends keyof DB> {
-    constructor();
+export interface FunctionModule<DB, TB extends keyof DB> {
+    /**
+     * Creates a function call.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .selectAll('person')
+     *   .where(db.fn('upper', ['first_name']), '=', 'JENNIFER')
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person".*
+     * from "person"
+     * where upper("first_name") = $1
+     * ```
+     *
+     * If you prefer readability over type-safety, you can always use raw `sql`:
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .selectAll('person')
+     *   .where(sql`upper(first_name)`, '=', 'JENNIFER')
+     * ```
+     */
+    <T>(name: string, args: ReadonlyArray<ReferenceExpression<DB, TB>>): ExpressionWrapper<T>;
     /**
      * 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((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
      * to configure the output type of large numbers and Kysely can't know if you've
@@ -61,7 +118,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 +133,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('participant')
+     *   .select(coalesce('nickname', sql<string>`'<anonymous>'`).as('nickname'))
+     *   .where('room_id', '=', roomId)
+     *   .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()
+     * ```
+     *
+     * You can combine this function with other helpers in this module:
+     *
+     * ```ts
+     * const { avg, coalesce } = db.fn
      *
      * db.selectFrom('person')
-     *   .select(coalesce(max('age'), sql<number>`0`).as('max_age'))
+     *   .select(coalesce(avg<number | null>('age'), sql<number>`0`).as('avg_age'))
      *   .where('first_name', '=', 'Jennifer')
      *   .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(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): ExpressionWrapper<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
-     * 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.
+     * 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.
      *
-     * Examples:
+     * For counting all rows nulls included (`count(*)`), see {@link countAll}.
      *
-     * `(string | null, number | null)` is inferred as `string | number | null`.
+     * 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.
      *
-     * `(string | null, number, Date | null)` is inferred as `string | number`.
+     * ### Examples
      *
-     * `(number, string | null)` is inferred as `number`.
+     * ```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((eb) => eb.fn.count('id').as('num_toys'))
+     *   .execute()
+     * ```
      */
-    coalesce<V extends ReferenceExpression<DB, TB>, OV extends ReferenceExpression<DB, TB>[]>(value: V, ...otherValues: OV): RawBuilder<CoalesceReferenceExpressionList<DB, TB, [V, ...OV]>>;
+    count<O extends number | string | bigint, C extends SimpleReferenceExpression<DB, TB> = SimpleReferenceExpression<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
     /**
-     * Calls the `count` function for the column given as the argument.
+     * 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):
      *
-     * If this is used in a `select` statement the type of the selected expression
+     * ```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 +290,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((eb) => eb.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 +350,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((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 `coalesce`
+     * and handle null values in post-execute code, or wrap the function with a {@link coalesce}
      * function.
      *
      * ```ts
@@ -172,8 +382,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 +402,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((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 `coalesce`
+     * and handle null values in post-execute code, or wrap the function with a {@link coalesce}
      * function.
      *
      * ```ts
@@ -203,15 +434,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((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
+     * 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 +484,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
@@ -236,6 +497,7 @@ export declare class FunctionModule<DB, TB extends keyof DB> {
      */
     sum<O extends number | string | bigint | null = number | string | bigint, C extends SimpleReferenceExpression<DB, TB> = SimpleReferenceExpression<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
 }
+export declare function createFunctionModule<DB, TB extends keyof DB>(): FunctionModule<DB, TB>;
 declare type OutputBoundStringReference<DB, TB extends keyof DB, C extends StringReference<DB, TB>, O> = IsNever<O> extends true ? C : Equals<ExtractTypeFromReferenceExpression<DB, TB, C> | null, O | null> extends true ? C : never;
 declare type StringReferenceBoundAggregateFunctionBuilder<DB, TB extends keyof DB, C extends StringReference<DB, TB>, O> = AggregateFunctionBuilder<DB, TB, ExtractTypeFromReferenceExpression<DB, TB, C> | (null extends O ? null : never)>;
 export {};