chore: fix jsdoc errors and add some examples, pt. 2.

deno.check.d.ts

@@ -11,6 +11,7 @@ import type {
 interface Database {
   person: PersonTable
   pet: PetTable
+  toy: ToyTable
   wine: WineTable
   wine_stock_change: WineStockChangeTable
 }
@@ -45,6 +46,12 @@ interface PetTable {
   species: Species
 }
 
+interface ToyTable {
+  id: Generated<number>
+  pet_id: number
+  price: number
+}
+
 interface WineTable {
   name: string
   stock: number
@@ -61,7 +68,7 @@ export type PersonUpdate = Updateable<PersonTable>
 export type Pet = Selectable<PetTable>
 export type NewPet = Insertable<PetTable>
 export type PetUpdate = Updateable<PetTable>
-export type Species = 'dog' | 'cat'
+export type Species = 'dog' | 'cat' | 'hamster'
 
 declare global {
   // @ts-ignore

src/query-builder/function-module.ts

@@ -106,9 +106,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):
@@ -122,9 +123,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>>(
@@ -145,11 +149,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):
@@ -177,7 +182,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()
    * ```
@@ -188,14 +193,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
@@ -207,7 +204,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()
    * ```
@@ -218,7 +215,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()
    * ```
@@ -251,35 +248,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()
    * ```
@@ -357,7 +344,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()
    * ```
@@ -379,18 +366,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,
@@ -415,7 +394,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()
    * ```
@@ -437,7 +416,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()
    * ```
@@ -446,7 +425,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()
@@ -458,15 +437,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,
@@ -494,7 +464,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()
    * ```
@@ -505,21 +475,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()
    * ```
@@ -553,7 +515,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()
    * ```
@@ -564,21 +526,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()
    * ```
@@ -608,7 +562,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()
    * ```
@@ -619,14 +573,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
@@ -638,7 +584,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()
    * ```
@@ -649,7 +595,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()
    * ```
@@ -671,11 +617,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()
    * ```
    *
    *
@@ -711,7 +658,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')
@@ -745,7 +692,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()