kysely 0.27.3 → 0.27.5

package/dist/cjs/query-builder/select-query-builder.d.ts

@@ -61,6 +61,8 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * you can always use:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * sql`your operator`
      * ```
      *
@@ -72,7 +74,7 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
-     *   .where('id', 'in', ['1', '2', '3'])
+     *   .where('id', 'in', [1, 2, 3])
      *   .execute()
      * ```
      *
@@ -291,7 +293,7 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      *   .selectFrom('person')
      *   .selectAll()
      *   .where(
-     *     sql`coalesce(first_name, last_name)`,
+     *     sql<string>`coalesce(first_name, last_name)`,
      *     'like',
      *     '%' + name + '%',
      *   )
@@ -320,6 +322,8 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * import { sql } from 'kysely'
      * const { ref } = db.dynamic
      *
+     * const columnFromUserInput: string = 'id'
+     *
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
@@ -542,6 +546,45 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * In case you use the {@link sql} tag you need to specify the type of the expression
      * (in this example `string`).
      *
+     *  <!-- siteExample("select", "Not null", 51) -->
+     *
+     * Sometimes you can be sure something's not null, but Kysely isn't able to infer
+     * it. For example calling `where('last_name', 'is not', null)` doesn't make
+     * `last_name` not null in the result type, but unless you have other where statements
+     * you can be sure it's never null.
+     *
+     * Kysely has a couple of helpers for dealing with these cases: `$notNull()` and `$narrowType`.
+     * Both are used in the following example:
+     *
+     * ```ts
+     * import { NotNull } from 'kysely'
+     * import { jsonObjectFrom } from 'kysely/helpers/postgres'
+     *
+     * const persons = db
+     *   .selectFrom('person')
+     *   .select((eb) => [
+     *     'last_name',
+     *      // Let's assume we know the person has at least one
+     *      // pet. We can use the `.$notNull()` method to make
+     *      // the expression not null. You could just as well
+     *      // add `pet` to the `$narrowType` call below.
+     *      jsonObjectFrom(
+     *        eb.selectFrom('pet')
+     *          .selectAll()
+     *          .limit(1)
+     *          .whereRef('person.id', '=', 'pet.owner_id')
+     *      ).$notNull().as('pet')
+     *   ])
+     *   .where('last_name', 'is not', null)
+     *   // $narrowType can be used to narrow the output type.
+     *   // The special `NotNull` type can be used to make a
+     *   // selection not null. You could add `pet: NotNull`
+     *   // here and omit the `$notNull()` call on it.
+     *   // Use whichever way you prefer.
+     *   .$narrowType<{ last_name: NotNull }>()
+     *   .execute()
+     * ```
+     *
      * All the examples above assume you know the column names at compile time.
      * While it's better to build your code like that (that way you also know
      * the types) sometimes it's not possible or you just prefer to write more
@@ -554,16 +597,16 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * const { ref } = db.dynamic
      *
      * // Some column name provided by the user. Value not known at compile time.
-     * const columnFromUserInput = req.query.select;
+     * const columnFromUserInput: string = 'first_name';
      *
      * // A type that lists all possible values `columnFromUserInput` can have.
      * // You can use `keyof Person` if any column of an interface is allowed.
-     * type PossibleColumns = 'last_name' | 'first_name' | 'birth_date'
+     * type PossibleColumns = 'last_name' | 'first_name' | 'birthdate'
      *
-     * const spersons = await db
+     * const people = await db
      *   .selectFrom('person')
      *   .select([
-     *     ref<PossibleColumns>(columnFromUserInput)
+     *     ref<PossibleColumns>(columnFromUserInput),
      *     'id'
      *   ])
      *   .execute()
@@ -571,12 +614,12 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * // The resulting type contains all `PossibleColumns` as optional fields
      * // because we cannot know which field was actually selected before
      * // running the code.
-     * const lastName: string | undefined = persons[0].last_name
-     * const firstName: string | undefined = persons[0].first_name
-     * const birthDate: string | undefined = persons[0].birth_date
+     * const lastName: string | null | undefined = people[0].last_name
+     * const firstName: string | undefined = people[0].first_name
+     * const birthDate: Date | null | undefined = people[0].birthdate
      *
      * // The result type also contains the compile time selection `id`.
-     * persons[0].id
+     * people[0].id
      * ```
      */
     select<SE extends SelectExpression<DB, TB>>(selections: ReadonlyArray<SE>): SelectQueryBuilder<DB, TB, O & Selection<DB, TB, SE>>;
@@ -615,7 +658,9 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * import { sql } from 'kysely'
+     *
+     * await db.selectFrom('person')
      *   .modifyFront(sql`sql_no_cache`)
      *   .select('first_name')
      *   .execute()
@@ -638,7 +683,9 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * import { sql } from 'kysely'
+     *
+     * await db.selectFrom('person')
      *   .select('first_name')
      *   .modifyEnd(sql`for update`)
      *   .execute()
@@ -656,10 +703,10 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
     /**
      * Makes the selection distinct.
      *
-     * <!-- siteExample("select", "Distinct", 70) -->
-     *
      * ### Examples
      *
+     * <!-- siteExample("select", "Distinct", 70) -->
+     *
      * ```ts
      * const persons = await db.selectFrom('person')
      *   .select('first_name')
@@ -824,7 +871,10 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      *     (join) => join
      *       .onRef('pet.owner_id', '=', 'person.id')
      *       .on('pet.name', '=', 'Doggo')
-     *       .on((eb) => eb.or([eb("person.age", ">", 18), eb("person.age", "<", 100)]))
+     *       .on((eb) => eb.or([
+     *         eb('person.age', '>', 18),
+     *         eb('person.age', '<', 100)
+     *       ]))
      *   )
      *   .selectAll()
      *   .execute()
@@ -838,6 +888,10 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * inner join "pet"
      * on "pet"."owner_id" = "person"."id"
      * and "pet"."name" = $1
+     * and (
+     *   "person"."age" > $2
+     *   OR "person"."age" < $3
+     * )
      * ```
      *
      * <!-- siteExample("join", "Subquery join", 40) -->
@@ -895,7 +949,7 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .innerJoinLateral(
      *     (eb) =>
      *       eb.selectFrom('pet')
@@ -906,6 +960,20 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      *   )
      *   .select(['first_name', 'p.name'])
      *   .orderBy('first_name')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person"."first_name", "p"."name"
+     * from "person"
+     * inner join lateral (
+     *   select "name"
+     *   from "pet"
+     *   where "pet"."owner_id" = "person"."id"
+     * ) as "p" on true
+     * order by "first_name"
      * ```
      */
     innerJoinLateral<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): SelectQueryBuilderWithInnerJoin<DB, TB, O, TE>;
@@ -915,7 +983,7 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .leftJoinLateral(
      *     (eb) =>
      *       eb.selectFrom('pet')
@@ -926,6 +994,20 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      *   )
      *   .select(['first_name', 'p.name'])
      *   .orderBy('first_name')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person"."first_name", "p"."name"
+     * from "person"
+     * left join lateral (
+     *   select "name"
+     *   from "pet"
+     *   where "pet"."owner_id" = "person"."id"
+     * ) as "p" on true
+     * order by "first_name"
      * ```
      */
     leftJoinLateral<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): SelectQueryBuilderWithLeftJoin<DB, TB, O, TE>;
@@ -997,7 +1079,7 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      *     .limit(1)
      *   )
      *   .orderBy(
-     *     sql`concat(first_name, last_name)`
+     *     sql<string>`concat(first_name, last_name)`
      *   )
      *   .execute()
      * ```
@@ -1056,7 +1138,7 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      *   .selectFrom('person')
      *   .select([
      *     'first_name',
-     *     sql`max(id)`.as('max_id')
+     *     sql<string>`max(id)`.as('max_id')
      *   ])
      *   .groupBy('first_name')
      *   .execute()
@@ -1080,7 +1162,7 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      *   .select([
      *     'first_name',
      *     'last_name',
-     *     sql`max(id)`.as('max_id')
+     *     sql<string>`max(id)`.as('max_id')
      *   ])
      *   .groupBy([
      *     'first_name',
@@ -1108,10 +1190,10 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      *   .select([
      *     'first_name',
      *     'last_name',
-     *     sql`max(id)`.as('max_id')
+     *     sql<string>`max(id)`.as('max_id')
      *   ])
      *   .groupBy([
-     *     sql`concat(first_name, last_name)`,
+     *     sql<string>`concat(first_name, last_name)`,
      *     (qb) => qb.selectFrom('pet').select('id').limit(1)
      *   ])
      *   .execute()
@@ -1151,7 +1233,7 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * Select the first 10 rows of the result:
      *
      * ```ts
-     * return await db
+     * await db
      *   .selectFrom('person')
      *   .select('first_name')
      *   .limit(10)
@@ -1167,7 +1249,7 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * Select rows from index 10 to index 19 of the result:
      *
      * ```ts
-     * return await db
+     * await db
      *   .selectFrom('person')
      *   .select('first_name')
      *   .limit(10)
@@ -1190,7 +1272,7 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * Select rows from index 10 to index 19 of the result:
      *
      * ```ts
-     * return await db
+     * await db
      *   .selectFrom('person')
      *   .select('first_name')
      *   .limit(10)
@@ -1213,7 +1295,7 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * ### Examples
      *
      * ```ts
-     * return await db
+     * await db
      *   .selectFrom('person')
      *   .select('first_name')
      *   .orderBy('first_name')
@@ -1243,7 +1325,7 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * Select 10 biggest ages:
      *
      * ```ts
-     * return await db
+     * await db
      *   .selectFrom('person')
      *   .select('age')
      *   .top(10)
@@ -1260,7 +1342,7 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * Select 10% first rows:
      *
      * ```ts
-     * return await db
+     * await db
      *  .selectFrom('person')
      *  .selectAll()
      *  .top(10, 'percent')
@@ -1282,22 +1364,48 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .select(['id', 'first_name as name'])
      *   .union(db.selectFrom('pet').select(['id', 'name']))
      *   .orderBy('name')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "id", "first_name" as "name"
+     * from "person"
+     * union
+     * select "id", "name"
+     * from "pet"
+     * order by "name"
      * ```
      *
      * You can provide a callback to get an expression builder.
      * In the following example, this allows us to wrap the query in parentheses:
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .select(['id', 'first_name as name'])
      *   .union((eb) => eb.parens(
      *     eb.selectFrom('pet').select(['id', 'name'])
      *   ))
      *   .orderBy('name')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "id", "first_name" as "name"
+     * from "person"
+     * union
+     * (
+     *   select "id", "name"
+     *   from "pet"
+     * )
+     * order by "name"
      * ```
      */
     union<E extends SetOperandExpression<DB, O>>(expression: E): SelectQueryBuilder<DB, TB, O>;
@@ -1309,22 +1417,48 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .select(['id', 'first_name as name'])
      *   .unionAll(db.selectFrom('pet').select(['id', 'name']))
      *   .orderBy('name')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "id", "first_name" as "name"
+     * from "person"
+     * union all
+     * select "id", "name"
+     * from "pet"
+     * order by "name"
      * ```
      *
      * You can provide a callback to get an expression builder.
      * In the following example, this allows us to wrap the query in parentheses:
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .select(['id', 'first_name as name'])
      *   .unionAll((eb) => eb.parens(
      *     eb.selectFrom('pet').select(['id', 'name'])
      *   ))
      *   .orderBy('name')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "id", "first_name" as "name"
+     * from "person"
+     * union all
+     * (
+     *   select "id", "name"
+     *   from "pet"
+     * )
+     * order by "name"
      * ```
      */
     unionAll<E extends SetOperandExpression<DB, O>>(expression: E): SelectQueryBuilder<DB, TB, O>;
@@ -1336,22 +1470,48 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .select(['id', 'first_name as name'])
      *   .intersect(db.selectFrom('pet').select(['id', 'name']))
      *   .orderBy('name')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "id", "first_name" as "name"
+     * from "person"
+     * intersect
+     * select "id", "name"
+     * from "pet"
+     * order by "name"
      * ```
      *
      * You can provide a callback to get an expression builder.
      * In the following example, this allows us to wrap the query in parentheses:
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .select(['id', 'first_name as name'])
      *   .intersect((eb) => eb.parens(
      *     eb.selectFrom('pet').select(['id', 'name'])
      *   ))
      *   .orderBy('name')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "id", "first_name" as "name"
+     * from "person"
+     * intersect
+     * (
+     *   select "id", "name"
+     *   from "pet"
+     * )
+     * order by "name"
      * ```
      */
     intersect<E extends SetOperandExpression<DB, O>>(expression: E): SelectQueryBuilder<DB, TB, O>;
@@ -1363,22 +1523,48 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .select(['id', 'first_name as name'])
      *   .intersectAll(db.selectFrom('pet').select(['id', 'name']))
      *   .orderBy('name')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "id", "first_name" as "name"
+     * from "person"
+     * intersect all
+     * select "id", "name"
+     * from "pet"
+     * order by "name"
      * ```
      *
      * You can provide a callback to get an expression builder.
      * In the following example, this allows us to wrap the query in parentheses:
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .select(['id', 'first_name as name'])
      *   .intersectAll((eb) => eb.parens(
      *     eb.selectFrom('pet').select(['id', 'name'])
      *   ))
      *   .orderBy('name')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "id", "first_name" as "name"
+     * from "person"
+     * intersect all
+     * (
+     *   select "id", "name"
+     *   from "pet"
+     * )
+     * order by "name"
      * ```
      */
     intersectAll<E extends SetOperandExpression<DB, O>>(expression: E): SelectQueryBuilder<DB, TB, O>;
@@ -1390,22 +1576,48 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .select(['id', 'first_name as name'])
      *   .except(db.selectFrom('pet').select(['id', 'name']))
      *   .orderBy('name')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "id", "first_name" as "name"
+     * from "person"
+     * except
+     * select "id", "name"
+     * from "pet"
+     * order by "name"
      * ```
      *
      * You can provide a callback to get an expression builder.
      * In the following example, this allows us to wrap the query in parentheses:
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .select(['id', 'first_name as name'])
      *   .except((eb) => eb.parens(
      *     eb.selectFrom('pet').select(['id', 'name'])
      *   ))
      *   .orderBy('name')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "id", "first_name" as "name"
+     * from "person"
+     * except
+     * (
+     *   select "id", "name"
+     *   from "pet"
+     * )
+     * order by "name"
      * ```
      */
     except<E extends SetOperandExpression<DB, O>>(expression: E): SelectQueryBuilder<DB, TB, O>;
@@ -1417,22 +1629,48 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .select(['id', 'first_name as name'])
      *   .exceptAll(db.selectFrom('pet').select(['id', 'name']))
      *   .orderBy('name')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "id", "first_name" as "name"
+     * from "person"
+     * except all
+     * select "id", "name"
+     * from "pet"
+     * order by "name"
      * ```
      *
      * You can provide a callback to get an expression builder.
      * In the following example, this allows us to wrap the query in parentheses:
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .select(['id', 'first_name as name'])
      *   .exceptAll((eb) => eb.parens(
      *     eb.selectFrom('pet').select(['id', 'name'])
      *   ))
      *   .orderBy('name')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "id", "first_name" as "name"
+     * from "person"
+     * except all
+     * (
+     *   select "id", "name"
+     *   from "pet"
+     * )
+     * order by "name"
      * ```
      */
     exceptAll<E extends SetOperandExpression<DB, O>>(expression: E): SelectQueryBuilder<DB, TB, O>;
@@ -1454,6 +1692,17 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      *
      * pets[0].owner_first_name
      * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "pet".*, (
+     *   select "first_name"
+     *   from "person"
+     *   where "pet"."owner_id" = "person"."id"
+     * ) as "owner_first_name"
+     * from "pet"
+     * ```
      */
     as<A extends string>(alias: A): AliasedSelectQueryBuilder<O, A>;
     /**
@@ -1462,10 +1711,11 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .select(['id', 'first_name'])
      *   .clearSelect()
      *   .select(['id', 'gender'])
+     *   .execute()
      * ```
      *
      * The generated SQL(PostgreSQL):
@@ -1500,10 +1750,11 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .selectAll()
      *   .limit(10)
      *   .clearLimit()
+     *   .execute()
      * ```
      *
      * The generated SQL(PostgreSQL):
@@ -1519,11 +1770,12 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .selectAll()
      *   .limit(10)
      *   .offset(20)
      *   .clearOffset()
+     *   .execute()
      * ```
      *
      * The generated SQL(PostgreSQL):
@@ -1539,10 +1791,11 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .selectAll()
      *   .orderBy('id')
      *   .clearOrderBy()
+     *   .execute()
      * ```
      *
      * The generated SQL(PostgreSQL):
@@ -1552,6 +1805,26 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * ```
      */
     clearOrderBy(): SelectQueryBuilder<DB, TB, O>;
+    /**
+     * Clears `group by` clause from the query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.selectFrom('person')
+     *   .selectAll()
+     *   .groupBy('id')
+     *   .clearGroupBy()
+     *   .execute()
+     * ```
+     *
+     * The generated SQL(PostgreSQL):
+     *
+     * ```sql
+     * select * from "person"
+     * ```
+     */
+    clearGroupBy(): SelectQueryBuilder<DB, TB, O>;
     /**
      * Simply calls the provided function passing `this` as the only argument. `$call` returns
      * what the provided function returns.
@@ -1564,12 +1837,14 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * The next example uses a helper function `log` to log a query:
      *
      * ```ts
+     * import type { Compilable } from 'kysely'
+     *
      * function log<T extends Compilable>(qb: T): T {
      *   console.log(qb.compile())
      *   return qb
      * }
      *
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .selectAll()
      *   .$call(log)
      *   .execute()
@@ -1579,29 +1854,31 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
     /**
      * Call `func(this)` if `condition` is true.
      *
-     * NOTE: This method has an impact on typescript performance and it should only be used
+     * NOTE: This method has an impact on TypeScript performance and it should only be used
      * when necessary. Remember that you can call most methods like `where` conditionally
      * like this:
      *
      * ```ts
-     * let query = db.selectFrom('person').selectAll()
+     * async function getPeople(firstName?: string, lastName?: string) {
+     *   let query = db.selectFrom('person').selectAll()
      *
-     * if (firstName) {
-     *   query = query.where('first_name', '=', firstName)
-     * }
+     *   if (firstName) {
+     *     query = query.where('first_name', '=', firstName)
+     *   }
      *
-     * if (lastName) {
-     *   query = query.where('last_name', '=', lastName)
-     * }
+     *   if (lastName) {
+     *     query = query.where('last_name', '=', lastName)
+     *   }
      *
-     * const result = await query.execute()
+     *   return await query.execute()
+     * }
      * ```
      *
      * This method is mainly useful with optional selects. Any `select` or `selectAll`
      * method called inside the callback add optional fields to the result type. This is
      * because we can't know if those selections were actually made before running the code.
      *
-     * Also see [this recipe](https://github.com/koskimas/kysely/tree/master/site/docs/recipes/conditional-selects.md)
+     * Also see [this recipe](https://github.com/kysely-org/kysely/blob/master/site/docs/recipes/0005-conditional-selects.md)
      *
      * ### Examples
      *
@@ -1621,24 +1898,27 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * the code. In the example above the return type of the `getPerson` function is:
      *
      * ```ts
-     * {
+     * Promise<{
      *   id: number
      *   first_name: string
      *   last_name?: string
-     * }
+     * }>
      * ```
      *
      * You can also call any other methods inside the callback:
      *
      * ```ts
-     * db.selectFrom('person')
-     *   .select('person.id')
-     *   .$if(filterByFirstName, (qb) => qb.where('first_name', '=', firstName))
-     *   .$if(filterByPetCount, (qb) => qb
-     *     .innerJoin('pet', 'pet.owner_id', 'person.id')
-     *     .having((eb) => eb.fn.count('pet.id'), '>', petCountLimit)
-     *     .groupBy('person.id')
-     *   )
+     * async function getPeople(firstName?: string, petCountLimit?: number) {
+     *   return await db.selectFrom('person')
+     *     .select('person.id')
+     *     .$if(firstName != null, (qb) => qb.where('first_name', '=', firstName!))
+     *     .$if(petCountLimit != null, (qb) => qb
+     *       .innerJoin('pet', 'pet.owner_id', 'person.id')
+     *       .having((eb) => eb.fn.count('pet.id'), '>', petCountLimit!)
+     *       .groupBy('person.id')
+     *     )
+     *     .execute()
+     * }
      * ```
      */
     $if<O2>(condition: boolean, func: (qb: this) => SelectQueryBuilder<any, any, O & O2>): SelectQueryBuilder<DB, TB, O & Partial<Omit<O2, keyof O>>>;
@@ -1674,6 +1954,7 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      *       .where('pet.species', '!=', 'cat')
      *       .$asTuple('name', 'species')
      *   ))
+     *   .execute()
      * ```
      *
      * The generated SQL(PostgreSQL):
@@ -1715,23 +1996,31 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * Turn this code:
      *
      * ```ts
+     * import type { Person } from 'type-editor' // imaginary module
+     *
      * const person = await db.selectFrom('person')
      *   .where('nullable_column', 'is not', null)
      *   .selectAll()
      *   .executeTakeFirstOrThrow()
      *
-     * if (person.nullable_column) {
+     * if (isWithNoNullValue(person)) {
      *   functionThatExpectsPersonWithNonNullValue(person)
      * }
+     *
+     * function isWithNoNullValue(person: Person): person is Person & { nullable_column: string } {
+     *   return person.nullable_column != null
+     * }
      * ```
      *
      * Into this:
      *
      * ```ts
+     * import type { NotNull } from 'kysely'
+     *
      * const person = await db.selectFrom('person')
      *   .where('nullable_column', 'is not', null)
      *   .selectAll()
-     *   .$narrowType<{ nullable_column: string }>()
+     *   .$narrowType<{ nullable_column: NotNull }>()
      *   .executeTakeFirstOrThrow()
      *
      * functionThatExpectsPersonWithNonNullValue(person)
@@ -1757,17 +2046,17 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
     /**
      * Asserts that query's output row type equals the given type `T`.
      *
-     * This method can be used to simplify excessively complex types to make typescript happy
+     * This method can be used to simplify excessively complex types to make TypeScript happy
      * and much faster.
      *
      * Kysely uses complex type magic to achieve its type safety. This complexity is sometimes too much
-     * for typescript and you get errors like this:
+     * for TypeScript and you get errors like this:
      *
      * ```
      * error TS2589: Type instantiation is excessively deep and possibly infinite.
      * ```
      *
-     * In these case you can often use this method to help typescript a little bit. When you use this
+     * In these case you can often use this method to help TypeScript a little bit. When you use this
      * method to assert the output type of a query, Kysely can drop the complex output type that
      * consists of multiple nested helper types and replace it with the simple asserted type.
      *
@@ -1781,12 +2070,12 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      *   .with('first_and_last', (qb) => qb
      *     .selectFrom('person')
      *     .select(['first_name', 'last_name'])
-     *     .$assertType<{ first_name: string, last_name: string }>()
+     *     .$assertType<{ first_name: string, last_name: string | null }>()
      *   )
      *   .with('age', (qb) => qb
      *     .selectFrom('person')
      *     .select('age')
-     *     .$assertType<{ age: number }>()
+     *     .$assertType<{ age: number | null }>()
      *   )
      *   .selectFrom(['first_and_last', 'age'])
      *   .selectAll()
@@ -1801,11 +2090,19 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
     /**
      * Creates the OperationNode that describes how to compile this expression into SQL.
      *
+     * ### Examples
+     *
      * If you are creating a custom expression, it's often easiest to use the {@link sql}
      * template tag to build the node:
      *
      * ```ts
+     * import { type Expression, type OperationNode, sql } from 'kysely'
+     *
      * class SomeExpression<T> implements Expression<T> {
+     *   get expressionType(): T | undefined {
+     *     return undefined
+     *   }
+     *
      *   toOperationNode(): OperationNode {
      *     return sql`some sql here`.toOperationNode()
      *   }
@@ -1843,7 +2140,7 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * ### Examples
      *
      * ```ts
-     * const stream = db.
+     * const stream = db
      *   .selectFrom('person')
      *   .select(['first_name', 'last_name'])
      *   .where('gender', '=', 'other')