kysely 0.23.5 → 0.24.1

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

@@ -2,25 +2,28 @@ import { AliasNode } from '../operation-node/alias-node.js';
 import { CompiledQuery } from '../query-compiler/compiled-query.js';
 import { JoinCallbackExpression, JoinReferenceExpression } from '../parser/join-parser.js';
 import { TableExpression } from '../parser/table-parser.js';
-import { SelectExpression, QueryBuilderWithSelection, SelectAllQueryBuilder } from '../parser/select-parser.js';
+import { SelectExpression, Selection, SelectArg, AllSelection } from '../parser/select-parser.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
 import { SelectQueryNode } from '../operation-node/select-query-node.js';
+import { QueryNode } from '../operation-node/query-node.js';
 import { MergePartial, Nullable, Simplify, SimplifySingleResult } from '../util/type-utils.js';
 import { OrderByDirectionExpression, OrderByExpression } from '../parser/order-by-parser.js';
 import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
 import { QueryId } from '../util/query-id.js';
-import { GroupByExpression } from '../parser/group-by-parser.js';
+import { GroupByArg } from '../parser/group-by-parser.js';
 import { KyselyPlugin } from '../plugin/kysely-plugin.js';
-import { WhereInterface } from './where-interface.js';
+import { WhereExpressionFactory, WhereInterface } from './where-interface.js';
 import { NoResultErrorConstructor } from './no-result-error.js';
-import { HavingInterface } from './having-interface.js';
+import { HavingExpressionFactory, HavingInterface } from './having-interface.js';
 import { Explainable, ExplainFormat } from '../util/explainable.js';
 import { AliasedExpression, Expression } from '../expression/expression.js';
-import { ComparisonOperatorExpression, HavingGrouper, OperandValueExpressionOrList, WhereGrouper } from '../parser/binary-operation-parser.js';
+import { ComparisonOperatorExpression, OperandValueExpressionOrList } from '../parser/binary-operation-parser.js';
 import { ExistsExpression } from '../parser/unary-operation-parser.js';
 import { KyselyTypeError } from '../util/type-error.js';
-export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements WhereInterface<DB, TB>, HavingInterface<DB, TB>, Expression<O>, Compilable<O>, Explainable {
+import { Selectable } from '../util/column-type.js';
+import { Streamable } from '../util/streamable.js';
+export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements WhereInterface<DB, TB>, HavingInterface<DB, TB>, Expression<O>, Compilable<O>, Explainable, Streamable<O> {
     #private;
     constructor(props: SelectQueryBuilderProps);
     /** @private */
@@ -42,53 +45,37 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      */
     get expressionType(): O | undefined;
     /**
-     * Adds a `where` clause to the query.
+     * Adds a `where` expression to the query.
      *
-     * Also see {@link orWhere}, {@link whereExists} and {@link whereRef}.
+     * Calling this method multiple times will combine the expressions using `and`.
      *
-     * ### Examples
+     * Also see {@link whereRef}
      *
-     * Find a row by column value:
+     * ### Examples
      *
      * ```ts
      * const person = await db
      *   .selectFrom('person')
      *   .selectAll()
-     *   .where('id', '=', 100)
+     *   .where('first_name', '=', 'Jennifer')
+     *   .where('age', '>', 40)
      *   .executeTakeFirst()
      * ```
      *
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * select * from "person" where "id" = $1
+     * select * from "person" where "first_name" = $1 and "age" > $2
      * ```
      *
      * Operator can be any supported operator or if the typings don't support it
-     * you can always use
+     * you can always use:
      *
      * ```ts
      * sql`your operator`
      * ```
      *
-     * The next example uses the `>` operator:
-     *
-     * ```ts
-     * const persons = await db
-     *   .selectFrom('person')
-     *   .selectAll()
-     *   .where('id', '>', 100)
-     *   .execute()
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select * from "person" where "id" > $1
-     * ```
-     *
-     * `where` methods don't change the type of the query. You can add
-     * conditional statements easily by doing something like this:
+     * You can add expressions conditionally like this:
      *
      * ```ts
      * let query = db
@@ -101,16 +88,16 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      *   query = query.where('first_name', '=', firstName)
      * }
      *
+     * if (lastName) {
+     *   query = query.where('last_name', '=', lastName)
+     * }
+     *
      * const persons = await query.execute()
      * ```
      *
-     * This is true for basically all methods execpt the `select` and
-     * `returning`, that __do__ change the return type of the query.
-     *
-     * Both the first and third argument can also be subqueries.
-     * A subquery is defined by passing a function and calling
-     * the `selectFrom` method of the object passed into the
-     * function:
+     * Both the first and third argument can also be arbitrary expressions like
+     * subqueries. An expression can defined by passing a function and calling
+     * the methods of the {@link ExpressionBuilder} passed to the callback:
      *
      * ```ts
      * const persons = await db
@@ -141,8 +128,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ```
      *
      * A `where in` query can be built by using the `in` operator and an array
-     * of values. The values in the array can also be subqueries or raw
-     * {@link sql} expressions.
+     * of values. The values in the array can also be expressions:
      *
      * ```ts
      * const persons = await db
@@ -158,40 +144,53 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * select * from "person" where "id" in ($1, $2, $3)
      * ```
      *
-     * If everything else fails, you can always use the {@link sql} tag
-     * as any of the arguments, including the operator:
+     * For complex `where` expressions you can pass in a single callback and
+     * use the {@link ExpressionBuilder} to build your expression:
      *
      * ```ts
-     * import { sql } from 'kysely'
-     *
      * const persons = await db
      *   .selectFrom('person')
-     *   .selectAll()
-     *   .where(
-     *     sql`coalesce(first_name, last_name)`,
-     *     'like',
-     *     '%' + name + '%',
-     *   )
-     *   .execute()
+     *   .selectAll('person')
+     *   .where(({ cmpr, or, and, not, exists, selectFrom, val }) => and([
+     *     or([
+     *       cmpr('first_name', '=', firstName),
+     *       cmpr('age', '<', maxAge)
+     *     ]),
+     *     not(exists(
+     *       selectFrom('pet').select('pet.id').whereRef('pet.owner_id', '=', 'person.id')
+     *     ))
+     *   ]))
      * ```
      *
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * select * from "person"
-     * where coalesce(first_name, last_name) like $1
+     * select "person".*
+     * from "person"
+     * where (
+     *   (
+     *     "first_name" = $1
+     *     or "age" < $2
+     *   )
+     *   and not exists (
+     *     select "pet"."id" from "pet" where "pet"."owner_id" = "person"."id"
+     *   )
+     * )
      * ```
      *
-     * If you only pass one function argument to this method, it can be
-     * used to create parentheses around other where statements:
+     * If everything else fails, you can always use the {@link sql} tag
+     * as any of the arguments, including the operator:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
-     *   .where((qb) => qb
-     *     .where('id', '=', 1)
-     *     .orWhere('id', '=', 2)
+     *   .where(
+     *     sql`coalesce(first_name, last_name)`,
+     *     'like',
+     *     '%' + name + '%',
      *   )
      *   .execute()
      * ```
@@ -199,7 +198,8 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * select * from "person" (where "id" = 1 or "id" = 2)
+     * select * from "person"
+     * where coalesce(first_name, last_name) like $1
      * ```
      *
      * In all examples above the columns were known at compile time
@@ -221,12 +221,12 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      *   .selectFrom('person')
      *   .selectAll()
      *   .where(ref(columnFromUserInput), '=', 1)
-     *   .orWhere(sql.id(columnFromUserInput), '=', 2)
+     *   .where(sql.id(columnFromUserInput), '=', 2)
      *   .execute()
      * ```
      */
     where<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): SelectQueryBuilder<DB, TB, O>;
-    where(grouper: WhereGrouper<DB, TB>): SelectQueryBuilder<DB, TB, O>;
+    where(factory: WhereExpressionFactory<DB, TB>): SelectQueryBuilder<DB, TB, O>;
     where(expression: Expression<any>): SelectQueryBuilder<DB, TB, O>;
     /**
      * Adds a `where` clause where both sides of the operator are references
@@ -258,7 +258,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll('person')
-     *   .select((qb) => qb
+     *   .select((eb) => eb
      *     .selectFrom('pet')
      *     .select('name')
      *     .whereRef('pet.owner_id', '=', 'person.id')
@@ -281,148 +281,29 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      */
     whereRef(lhs: ReferenceExpression<DB, TB>, op: ComparisonOperatorExpression, rhs: ReferenceExpression<DB, TB>): SelectQueryBuilder<DB, TB, O>;
     /**
-     * Adds an `or where` clause to the query. Otherwise works just like {@link where}.
-     *
-     * It's often necessary to wrap `or where` clauses in parentheses to control
-     * precendence. You can use the one argument version of the `where` method
-     * for that. See the examples.
-     *
-     * ### Examples
-     *
-     * ```ts
-     * const persons = await db
-     *   .selectFrom('person')
-     *   .selectAll()
-     *   .where('id', '=', 1)
-     *   .orWhere('id', '=', 2)
-     *   .execute()
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select * from "person" where "id" = 1 or "id" = 2
-     * ```
-     *
-     * Grouping with parentheses:
-     *
-     * ```ts
-     * const persons = await db
-     *   .selectFrom('person')
-     *   .selectAll()
-     *   .where((qb) => qb
-     *     .where('id', '=', 1)
-     *     .orWhere('id', '=', 2)
-     *   )
-     *   .execute()
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select * from "person" (where "id" = 1 or "id" = 2)
-     * ```
-     *
-     * Even the first `where` can be an `orWhere`. This is useful
-     * if you are looping through a set of conditions:
-     *
-     * ```ts
-     * const persons = await db
-     *   .selectFrom('person')
-     *   .selectAll()
-     *   .where((qb) => qb
-     *     .orWhere('id', '=', 1)
-     *     .orWhere('id', '=', 2)
-     *   )
-     *   .execute()
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select * from "person" (where "id" = 1 or "id" = 2)
-     * ```
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
     orWhere<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): SelectQueryBuilder<DB, TB, O>;
-    orWhere(grouper: WhereGrouper<DB, TB>): SelectQueryBuilder<DB, TB, O>;
+    orWhere(factory: WhereExpressionFactory<DB, TB>): SelectQueryBuilder<DB, TB, O>;
     orWhere(expression: Expression<any>): SelectQueryBuilder<DB, TB, O>;
     /**
-     * Adds an `or where` clause to the query. Otherwise works just like {@link whereRef}.
-     *
-     * Also see {@link orWhere} and {@link where}.
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
     orWhereRef(lhs: ReferenceExpression<DB, TB>, op: ComparisonOperatorExpression, rhs: ReferenceExpression<DB, TB>): SelectQueryBuilder<DB, TB, O>;
     /**
-     * Adds a `where exists` clause to the query.
-     *
-     * You can either use a subquery or a raw {@link sql} snippet.
-     *
-     * ### Examples
-     *
-     * The query below selets all persons that own a pet named Catto:
-     *
-     * ```ts
-     * const petName = 'Catto'
-     * const persons = await db
-     *   .selectFrom('person')
-     *   .selectAll()
-     *   .whereExists((qb) => qb
-     *     .selectFrom('pet')
-     *     .select('pet.id')
-     *     .whereRef('person.id', '=', 'pet.owner_id')
-     *     .where('pet.name', '=', petName)
-     *   )
-     *   .execute()
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select * from "person"
-     * where exists (
-     *   select "pet"."id"
-     *   from "pet"
-     *   where "person"."id" = "pet"."owner_id"
-     *   and "pet"."name" = $1
-     * )
-     * ```
-     *
-     * The same query as in the previous example but with using raw {@link sql}:
-     *
-     * ```ts
-     * import { sql } from 'kysely'
-     *
-     * const petName = 'Catto'
-     * db.selectFrom('person')
-     *   .selectAll()
-     *   .whereExists(
-     *     sql`(select pet.id from pet where person.id = pet.owner_id and pet.name = ${petName})`
-     *   )
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select * from "person"
-     * where exists (
-     *   select pet.id
-     *   from pet
-     *   where person.id = pet.owner_id
-     *   and pet.name = $1
-     * )
-     * ```
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
     whereExists(arg: ExistsExpression<DB, TB>): SelectQueryBuilder<DB, TB, O>;
     /**
-     * Just like {@link whereExists} but creates a `not exists` clause.
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
     whereNotExists(arg: ExistsExpression<DB, TB>): SelectQueryBuilder<DB, TB, O>;
     /**
-     * Just like {@link whereExists} but creates an `or exists` clause.
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
     orWhereExists(arg: ExistsExpression<DB, TB>): SelectQueryBuilder<DB, TB, O>;
     /**
-     * Just like {@link whereExists} but creates an `or not exists` clause.
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
     orWhereNotExists(arg: ExistsExpression<DB, TB>): SelectQueryBuilder<DB, TB, O>;
     /**
@@ -430,7 +311,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * instead of a `where` statement.
      */
     having<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): SelectQueryBuilder<DB, TB, O>;
-    having(grouper: HavingGrouper<DB, TB>): SelectQueryBuilder<DB, TB, O>;
+    having(factory: HavingExpressionFactory<DB, TB>): SelectQueryBuilder<DB, TB, O>;
     having(expression: Expression<any>): SelectQueryBuilder<DB, TB, O>;
     /**
      * Just like {@link WhereInterface.whereRef | whereRef} but adds a `having` statement
@@ -438,42 +319,40 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      */
     havingRef(lhs: ReferenceExpression<DB, TB>, op: ComparisonOperatorExpression, rhs: ReferenceExpression<DB, TB>): SelectQueryBuilder<DB, TB, O>;
     /**
-     * Just like {@link WhereInterface.orWhere | orWhere} but adds a `having` statement
-     * instead of a `where` statement.
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
     orHaving<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): SelectQueryBuilder<DB, TB, O>;
-    orHaving(grouper: HavingGrouper<DB, TB>): SelectQueryBuilder<DB, TB, O>;
+    orHaving(factory: HavingExpressionFactory<DB, TB>): SelectQueryBuilder<DB, TB, O>;
     orHaving(expression: Expression<any>): SelectQueryBuilder<DB, TB, O>;
     /**
-     * Just like {@link WhereInterface.orWhereRef | orWhereRef} but adds a `having` statement
-     * instead of a `where` statement.
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
     orHavingRef(lhs: ReferenceExpression<DB, TB>, op: ComparisonOperatorExpression, rhs: ReferenceExpression<DB, TB>): SelectQueryBuilder<DB, TB, O>;
     /**
-     * Just like {@link WhereInterface.whereExists | whereExists} but adds a `having` statement
-     * instead of a `where` statement.
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
     havingExists(arg: ExistsExpression<DB, TB>): SelectQueryBuilder<DB, TB, O>;
     /**
-     * Just like {@link WhereInterface.whereNotExists | whereNotExists} but adds a `having` statement
-     * instead of a `where` statement.
+     * @deprecated Use {@link havingNotExists} instead.
      */
     havingNotExist(arg: ExistsExpression<DB, TB>): SelectQueryBuilder<DB, TB, O>;
     /**
-     * Just like {@link WhereInterface.orWhereExists | orWhereExists} but adds a `having` statement
-     * instead of a `where` statement.
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
+     */
+    havingNotExists(arg: ExistsExpression<DB, TB>): SelectQueryBuilder<DB, TB, O>;
+    /**
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
     orHavingExists(arg: ExistsExpression<DB, TB>): SelectQueryBuilder<DB, TB, O>;
     /**
-     * Just like {@link WhereInterface.orWhereNotExists | orWhereNotExists} but adds a `having` statement
-     * instead of a `where` statement.
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
     orHavingNotExists(arg: ExistsExpression<DB, TB>): SelectQueryBuilder<DB, TB, O>;
     /**
-     * Adds a select clause to the query.
+     * Adds a select statement to the query.
      *
      * When a column (or any expression) is selected, Kysely adds its type to the return
-     * type of the query. Kysely is smart enough to parse the column names and types even
+     * type of the query. Kysely is smart enough to parse the selection names and types
      * from aliased columns, subqueries, raw expressions etc.
      *
      * Kysely only allows you to select columns and expressions that exist and would
@@ -496,7 +375,8 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * Select a single column:
      *
      * ```ts
-     * const persons = await db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
      *   .select('id')
      *   .where('first_name', '=', 'Arnold')
      *   .execute()
@@ -513,7 +393,8 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * Select a single column and specify a table:
      *
      * ```ts
-     * const persons = await db.selectFrom(['person', 'pet'])
+     * const persons = await db
+     *   .selectFrom(['person', 'pet'])
      *   .select('person.id')
      *   .execute()
      *
@@ -529,7 +410,8 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * Select multiple columns:
      *
      * ```ts
-     * const persons = await db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
      *   .select(['person.id', 'first_name'])
      *   .execute()
      *
@@ -546,7 +428,8 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * Aliased selections:
      *
      * ```ts
-     * const persons = await db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
      *   .select([
      *     'person.first_name as fn',
      *     'person.last_name as ln'
@@ -566,26 +449,35 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * from "person"
      * ```
      *
-     * You can also select subqueries and raw sql expressions. Note that you
-     * always need to give a name for the selections using the `as`
-     * method:
+     * You can also select arbitrary expression including subqueries and raw sql snippets.
+     * When you do that, you need to give a name for the selections using the {@link as} method:
      *
      * ```ts
      * import { sql } from 'kysely'
      *
      * const persons = await db.selectFrom('person')
-     *   .select([
-     *     (qb) => qb
-     *       .selectFrom('pet')
+     *   .select(({ selectFrom, or, cmpr }) => [
+     *     // Select a correlated subquery
+     *     selectFrom('pet')
      *       .whereRef('person.id', '=', 'pet.owner_id')
      *       .select('pet.name')
+     *       .orderBy('pet.name')
      *       .limit(1)
-     *       .as('pet_name')
+     *       .as('first_pet_name'),
+     *
+     *     // Build and select an expression using the expression builder
+     *     or([
+     *       cmpr('first_name', '=', 'Jennifer'),
+     *       cmpr('first_name', '=', 'Arnold')
+     *     ]).as('is_jennifer_or_arnold'),
+     *
+     *     // Select a raw sql expression
      *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name')
      *   ])
      *   .execute()
      *
-     * persons[0].pet_name
+     * persons[0].first_pet_name
+     * persons[0].is_jennifer_or_arnold
      * persons[0].full_name
      * ```
      *
@@ -597,9 +489,11 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      *     select "pet"."name"
      *     from "pet"
      *     where "person"."id" = "pet"."owner_id"
+     *     order by "pet"."name"
      *     limit $1
      *   ) as "pet_name",
-     *   concat(first_name, ' ', last_name) as full_name
+     *   ("first_name" = $2 or "first_name" = $3) as "jennifer_or_arnold",
+     *   concat(first_name, ' ', last_name) as "full_name"
      * from "person"
      * ```
      *
@@ -624,7 +518,8 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * // You can use `keyof Person` if any column of an interface is allowed.
      * type PossibleColumns = 'last_name' | 'first_name' | 'birth_date'
      *
-     * const spersons = await db.selectFrom('person')
+     * const spersons = await db
+     *   .selectFrom('person')
      *   .select([
      *     ref<PossibleColumns>(columnFromUserInput)
      *     'id'
@@ -642,8 +537,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * persons[0].id
      * ```
      */
-    select<SE extends SelectExpression<DB, TB>>(selections: ReadonlyArray<SE>): QueryBuilderWithSelection<DB, TB, O, SE>;
-    select<SE extends SelectExpression<DB, TB>>(selection: SE): QueryBuilderWithSelection<DB, TB, O, SE>;
+    select<SE extends SelectExpression<DB, TB>>(selection: SelectArg<DB, TB, SE>): SelectQueryBuilder<DB, TB, O & Selection<DB, TB, SE>>;
     /**
      * Adds `distinct on` expressions to the select clause.
      *
@@ -804,9 +698,9 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * select "person".*, "pet".* from "person", "pet"
      * ```
      */
-    selectAll<T extends TB>(table: ReadonlyArray<T>): SelectAllQueryBuilder<DB, TB, O, T>;
-    selectAll<T extends TB>(table: T): SelectAllQueryBuilder<DB, TB, O, T>;
-    selectAll(): SelectAllQueryBuilder<DB, TB, O, TB>;
+    selectAll<T extends TB>(table: ReadonlyArray<T>): SelectQueryBuilder<DB, TB, O & AllSelection<DB, T>>;
+    selectAll<T extends TB>(table: T): SelectQueryBuilder<DB, TB, Selectable<DB[T]>>;
+    selectAll(): SelectQueryBuilder<DB, TB, O & AllSelection<DB, TB>>;
     /**
      * Joins another table to the query using an inner join.
      *
@@ -1011,7 +905,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * await db
      *   .selectFrom('person')
      *   .selectAll()
-     *   .orderBy((qb) => qb.selectFrom('pet')
+     *   .orderBy((eb) => eb.selectFrom('pet')
      *     .select('pet.name')
      *     .whereRef('pet.owner_id', '=', 'person.id')
      *     .limit(1)
@@ -1160,8 +1054,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * group by "first_name"
      * ```
      */
-    groupBy(groupBy: ReadonlyArray<GroupByExpression<DB, TB, O>>): SelectQueryBuilder<DB, TB, O>;
-    groupBy(groupBy: GroupByExpression<DB, TB, O>): SelectQueryBuilder<DB, TB, O>;
+    groupBy(groupBy: GroupByArg<DB, TB, O>): SelectQueryBuilder<DB, TB, O>;
     /**
      * Adds a limit clause to the query.
      *
@@ -1322,7 +1215,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * db.selectFrom('person')
      *   .select(['id', 'first_name'])
      *   .clearSelect()
-     *   .select(['id','gender'])
+     *   .select(['id', 'gender'])
      * ```
      *
      * The generated SQL(PostgreSQL):
@@ -1333,7 +1226,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      */
     clearSelect(): SelectQueryBuilder<DB, TB, {}>;
     /**
-     * Clears all where clauses from the query.
+     * Clears all where expressions from the query.
      *
      * ### Examples
      *
@@ -1410,7 +1303,8 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      */
     clearOrderBy(): SelectQueryBuilder<DB, TB, O>;
     /**
-     * Simply calls the given function passing `this` as the only argument.
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
      *
      * If you want to conditionally call a method on `this`, see
      * the {@link $if} method.
@@ -1439,12 +1333,29 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
     /**
      * Call `func(this)` if `condition` is true.
      *
-     * This method is especially handy with optional selects. Any `select` or `selectAll`
-     * method calls add columns as optional fields to the output type when called inside
-     * the `func` callback. This is because we can't know if those selections were actually
-     * made before running the code.
+     * 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()
+     *
+     * if (firstName) {
+     *   query = query.where('first_name', '=', firstName)
+     * }
+     *
+     * if (lastName) {
+     *   query = query.where('last_name', '=', lastName)
+     * }
+     *
+     * const result = 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/recipes/conditional-selects.md)
+     * Also see [this recipe](https://github.com/koskimas/kysely/tree/master/site/docs/recipes/conditional-selects.md)
      *
      * ### Examples
      *
@@ -1582,10 +1493,10 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * the query returned no result.
      *
      * By default an instance of {@link NoResultError} is thrown, but you can
-     * provide a custom error class as the only argument to throw a different
+     * provide a custom error class, or callback to throw a different
      * error.
      */
-    executeTakeFirstOrThrow(errorConstructor?: NoResultErrorConstructor): Promise<Simplify<O>>;
+    executeTakeFirstOrThrow(errorConstructor?: NoResultErrorConstructor | ((node: QueryNode) => Error)): Promise<Simplify<O>>;
     /**
      * Executes the query and streams the rows.
      *
@@ -1614,7 +1525,7 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      */
     stream(chunkSize?: number): AsyncIterableIterator<O>;
     /**
-     * Executes query with `explain` statement before `select` keyword.
+     * Executes query with `explain` statement before the main query.
      *
      * ```ts
      * const explained = await db