kysely 0.27.4 → 0.27.6

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<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,14 +167,6 @@ 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
@@ -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()
      * ```
@@ -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()
      * ```
@@ -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,14 +456,6 @@ 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
@@ -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()