kysely 0.27.4 → 0.27.6

package/dist/esm/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()
      * ```
      *
@@ -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()
@@ -593,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()
@@ -610,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>>;
@@ -654,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()
@@ -677,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()
@@ -695,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')
@@ -941,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')
@@ -952,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>;
@@ -961,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')
@@ -972,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>;
@@ -1197,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)
@@ -1213,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)
@@ -1236,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)
@@ -1259,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')
@@ -1289,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)
@@ -1306,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')
@@ -1328,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>;
@@ -1355,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>;
@@ -1382,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>;
@@ -1409,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>;
@@ -1436,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>;
@@ -1463,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>;
@@ -1500,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>;
     /**
@@ -1508,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):
@@ -1546,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):
@@ -1565,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):
@@ -1585,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):
@@ -1604,10 +1811,11 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * await db.selectFrom('person')
      *   .selectAll()
      *   .groupBy('id')
      *   .clearGroupBy()
+     *   .execute()
      * ```
      *
      * The generated SQL(PostgreSQL):
@@ -1629,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()
@@ -1649,24 +1859,26 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * 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
      *
@@ -1686,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>>>;
@@ -1739,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):
@@ -1780,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)
@@ -1846,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()
@@ -1866,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()
      *   }
@@ -1908,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')