kysely 0.3.4 → 0.3.9

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

@@ -1,10 +1,11 @@
 import { AliasNode } from '../operation-node/alias-node.js';
 import { OperationNodeSource } from '../operation-node/operation-node-source.js';
 import { CompiledQuery } from '../query-compiler/compiled-query.js';
-import { JoinCallbackArg, JoinReferenceArg } from '../parser/join-parser.js';
+import { JoinCallbackExpression, JoinReferenceExpression } from '../parser/join-parser.js';
 import { TableExpression, QueryBuilderWithTable } from '../parser/table-parser.js';
 import { SelectExpression, QueryBuilderWithSelection, SelectAllQueryBuilder } from '../parser/select-parser.js';
-import { ExistsFilterArg, FilterOperatorArg } from '../parser/filter-parser.js';
+import { ExistsExpression, FilterOperator } from '../parser/filter-parser.js';
+import { InsertObject } from '../parser/insert-values-parser.js';
 import { QueryBuilderWithReturning } from '../parser/returning-parser.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
 import { ValueExpressionOrList } from '../parser/value-parser.js';
@@ -43,9 +44,11 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * Find a row by column value:
      *
      * ```ts
-     * db.selectFrom('person')
-     *   .where('id', '=', 100)
+     * const person = await db
+     *   .selectFrom('person')
      *   .selectAll()
+     *   .where('id', '=', 100)
+     *   .executeTakeFirst()
      * ```
      *
      * The generated SQL (postgresql):
@@ -59,9 +62,11 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * you can always use `db.raw('your operator')`.
      *
      * ```ts
-     * db.selectFrom('person')
-     *   .where('id', '>', 100)
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll()
+     *   .where('id', '>', 100)
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
@@ -71,22 +76,25 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * ```
      *
      * @example
-     * A `where in` query an be built by using the `in` operator and an array
-     * of values. The values in the array can also be subqueries or raw
-     * instances.
+     * The `where` methods don't change the type of the query. You can add
+     * conditional `where`s easily by doing something like this:
      *
      * ```ts
-     * db.selectFrom('person')
-     *   .where('person.id', 'in', [100, 200, 300])
+     * let query = db
+     *   .selectFrom('person')
      *   .selectAll()
-     * ```
      *
-     * The generated SQL (postgresql):
+     * if (firstName) {
+     *   query = query.where('first_name', '=', firstName)
+     * }
      *
-     * ```sql
-     * select * from "person" where "id" in ($1, $2, $3)
+     * const persons = await query.execute()
      * ```
      *
+     * This is true for basically all methods execpt the `select` and
+     * `returning` methods, which DO change the return type of the
+     * query.
+     *
      * @example
      * Both the first and third argument can also be subqueries.
      * A subquery is defined by passing a function and calling
@@ -94,15 +102,18 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * function:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
+     *   .selectAll()
      *   .where(
      *     (qb) => qb.subQuery('pet')
-     *       .select('pet.id')
-     *       .whereRef('pet.owner_id', '=', 'person.id'),
-     *     'in',
-     *     [100, 200, 300]
+     *       .select('pet.name')
+     *       .whereRef('pet.owner_id', '=', 'person.id')
+     *       .limit(1),
+     *     '=',
+     *     'Fluffy'
      *   )
-     *   .selectAll()
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
@@ -111,10 +122,30 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * select *
      * from "person"
      * where (
-     *   select "pet"."id"
+     *   select "pet"."name"
      *   from "pet"
      *   where "pet"."owner_id" = "person"."id"
-     * ) in ($1, $2, $3)
+     *   limit $1
+     * ) = $2
+     * ```
+     *
+     * @example
+     * 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
+     * instances.
+     *
+     * ```ts
+     * const persons = await db
+     *   .selectFrom('person')
+     *   .selectAll()
+     *   .where('person.id', 'in', [100, 200, 300])
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (postgresql):
+     *
+     * ```sql
+     * select * from "person" where "id" in ($1, $2, $3)
      * ```
      *
      * @example
@@ -122,20 +153,21 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * as any of the arguments, including the operator:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
+     *   .selectAll()
      *   .where(
      *     db.raw('coalesce(first_name, last_name)'),
      *     'like',
      *     '%' + name + '%',
      *   )
-     *   .selectAll()
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
      *
      * ```sql
-     * select *
-     * from "person"
+     * select * from "person"
      * where coalesce(first_name, last_name) like $1
      * ```
      *
@@ -144,12 +176,14 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * used to create parentheses around other where clauses:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll()
      *   .where((qb) => qb
      *     .where('id', '=', 1)
      *     .orWhere('id', '=', 2)
      *   )
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
@@ -173,13 +207,15 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * ```ts
      * const { ref } = db.dynamic
      *
-     * db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll()
      *   .where(ref(columnFromUserInput), '=', 1)
      *   .orWhere(db.raw('??', [columnFromUserInput]), '=', 2)
+     *   .execute()
      * ```
      */
-    where(lhs: ReferenceExpression<DB, TB>, op: FilterOperatorArg, rhs: ValueExpressionOrList<DB, TB>): QueryBuilder<DB, TB, O>;
+    where<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: FilterOperator, rhs: ValueExpressionOrList<DB, TB, RE>): QueryBuilder<DB, TB, O>;
     where(grouper: (qb: QueryBuilder<DB, TB, O>) => QueryBuilder<DB, TB, O>): QueryBuilder<DB, TB, O>;
     /**
      * Adds a `where` clause where both sides of the operator are references
@@ -208,7 +244,8 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * Usage in a subquery:
      *
      * ```ts
-     * db.selectFrom('person)
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll('person')
      *   .select((qb) => qb
      *     .subQuery('pet')
@@ -217,6 +254,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *     .limit(1)
      *     .as('pet_name')
      *   )
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
@@ -226,10 +264,11 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   select "name"
      *   from "pet"
      *   where "pet"."owner_id" = "person"."id"
-     * ) as pet_name
-     * from "person"`
+     *   limit $1
+     * ) as "pet_name"
+     * from "person"
      */
-    whereRef(lhs: ReferenceExpression<DB, TB>, op: FilterOperatorArg, rhs: ReferenceExpression<DB, TB>): QueryBuilder<DB, TB, O>;
+    whereRef(lhs: ReferenceExpression<DB, TB>, op: FilterOperator, rhs: ReferenceExpression<DB, TB>): QueryBuilder<DB, TB, O>;
     /**
      * Adds an `or where` clause to the query. Otherwise works just like
      * {@link QueryBuilder.where | where}.
@@ -240,10 +279,12 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *
      * @example
      * ```ts
-     * db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll()
      *   .where('id', '=', 1)
      *   .orWhere('id', '=', 2)
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
@@ -256,12 +297,14 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * Grouping with parentheses:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll()
      *   .where((qb) => qb
      *     .where('id', '=', 1)
      *     .orWhere('id', '=', 2)
      *   )
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
@@ -275,12 +318,14 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * if you are looping through a set of conditions:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll()
      *   .where((qb) => qb
      *     .orWhere('id', '=', 1)
      *     .orWhere('id', '=', 2)
      *   )
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
@@ -289,7 +334,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * select * from "person" (where "id" = 1 or "id" = 2)
      * ```
      */
-    orWhere(lhs: ReferenceExpression<DB, TB>, op: FilterOperatorArg, rhs: ValueExpressionOrList<DB, TB>): QueryBuilder<DB, TB, O>;
+    orWhere<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: FilterOperator, rhs: ValueExpressionOrList<DB, TB, RE>): QueryBuilder<DB, TB, O>;
     orWhere(grouper: (qb: QueryBuilder<DB, TB, O>) => QueryBuilder<DB, TB, O>): QueryBuilder<DB, TB, O>;
     /**
      * Adds an `or where` clause to the query. Otherwise works just like
@@ -297,7 +342,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *
      * Also see {@link QueryBuilder.orWhere | orWhere} and {@link QueryBuilder.where | where}.
      */
-    orWhereRef(lhs: ReferenceExpression<DB, TB>, op: FilterOperatorArg, rhs: ReferenceExpression<DB, TB>): QueryBuilder<DB, TB, O>;
+    orWhereRef(lhs: ReferenceExpression<DB, TB>, op: FilterOperator, rhs: ReferenceExpression<DB, TB>): QueryBuilder<DB, TB, O>;
     /**
      * Adds a `where exists` clause to the query.
      *
@@ -307,7 +352,8 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * The query below selets all persons that own a pet named Catto:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll()
      *   .whereExists((qb) => qb
      *     .subQuery('pet')
@@ -315,6 +361,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *     .whereRef('person.id', '=', 'pet.owner_id')
      *     .where('pet.name', '=', 'Catto')
      *   )
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
@@ -355,72 +402,72 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * )
      * ```
      */
-    whereExists(arg: ExistsFilterArg<DB, TB>): QueryBuilder<DB, TB, O>;
+    whereExists(arg: ExistsExpression<DB, TB>): QueryBuilder<DB, TB, O>;
     /**
      * Just like {@link QueryBuilder.whereExists | whereExists} but creates a `not exists` clause.
      */
-    whereNotExists(arg: ExistsFilterArg<DB, TB>): QueryBuilder<DB, TB, O>;
+    whereNotExists(arg: ExistsExpression<DB, TB>): QueryBuilder<DB, TB, O>;
     /**
      * Just like {@link QueryBuilder.whereExists | whereExists} but creates a `or exists` clause.
      */
-    orWhereExists(arg: ExistsFilterArg<DB, TB>): QueryBuilder<DB, TB, O>;
+    orWhereExists(arg: ExistsExpression<DB, TB>): QueryBuilder<DB, TB, O>;
     /**
      * Just like {@link QueryBuilder.whereExists | whereExists} but creates a `or not exists` clause.
      */
-    orWhereNotExists(arg: ExistsFilterArg<DB, TB>): QueryBuilder<DB, TB, O>;
+    orWhereNotExists(arg: ExistsExpression<DB, TB>): QueryBuilder<DB, TB, O>;
     /**
      * Just like {@link QueryBuilder.where | where} but adds a `having` statement
      * instead of a `where` statement.
      */
-    having(lhs: ReferenceExpression<DB, TB>, op: FilterOperatorArg, rhs: ValueExpressionOrList<DB, TB>): QueryBuilder<DB, TB, O>;
+    having<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: FilterOperator, rhs: ValueExpressionOrList<DB, TB, RE>): QueryBuilder<DB, TB, O>;
     having(grouper: (qb: QueryBuilder<DB, TB, O>) => QueryBuilder<DB, TB, O>): QueryBuilder<DB, TB, O>;
     /**
      * Just like {@link QueryBuilder.whereRef | whereRef} but adds a `having` statement
      * instead of a `where` statement.
      */
-    havingRef(lhs: ReferenceExpression<DB, TB>, op: FilterOperatorArg, rhs: ReferenceExpression<DB, TB>): QueryBuilder<DB, TB, O>;
+    havingRef(lhs: ReferenceExpression<DB, TB>, op: FilterOperator, rhs: ReferenceExpression<DB, TB>): QueryBuilder<DB, TB, O>;
     /**
      * Just like {@link QueryBuilder.orWhere | orWhere} but adds a `having` statement
      * instead of a `where` statement.
      */
-    orHaving(lhs: ReferenceExpression<DB, TB>, op: FilterOperatorArg, rhs: ValueExpressionOrList<DB, TB>): QueryBuilder<DB, TB, O>;
+    orHaving<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: FilterOperator, rhs: ValueExpressionOrList<DB, TB, RE>): QueryBuilder<DB, TB, O>;
     orHaving(grouper: (qb: QueryBuilder<DB, TB, O>) => QueryBuilder<DB, TB, O>): QueryBuilder<DB, TB, O>;
     /**
      * Just like {@link QueryBuilder.orWhereRef | orWhereRef} but adds a `having` statement
      * instead of a `where` statement.
      */
-    orHavingRef(lhs: ReferenceExpression<DB, TB>, op: FilterOperatorArg, rhs: ReferenceExpression<DB, TB>): QueryBuilder<DB, TB, O>;
+    orHavingRef(lhs: ReferenceExpression<DB, TB>, op: FilterOperator, rhs: ReferenceExpression<DB, TB>): QueryBuilder<DB, TB, O>;
     /**
      * Just like {@link QueryBuilder.whereExists | whereExists} but adds a `having` statement
      * instead of a `where` statement.
      */
-    havingExists(arg: ExistsFilterArg<DB, TB>): QueryBuilder<DB, TB, O>;
+    havingExists(arg: ExistsExpression<DB, TB>): QueryBuilder<DB, TB, O>;
     /**
      * Just like {@link QueryBuilder.whereNotExists | whereNotExists} but adds a `having` statement
      * instead of a `where` statement.
      */
-    havingNotExist(arg: ExistsFilterArg<DB, TB>): QueryBuilder<DB, TB, O>;
+    havingNotExist(arg: ExistsExpression<DB, TB>): QueryBuilder<DB, TB, O>;
     /**
      * Just like {@link QueryBuilder.orWhereExists | orWhereExists} but adds a `having` statement
      * instead of a `where` statement.
      */
-    orHavingExists(arg: ExistsFilterArg<DB, TB>): QueryBuilder<DB, TB, O>;
+    orHavingExists(arg: ExistsExpression<DB, TB>): QueryBuilder<DB, TB, O>;
     /**
      * Just like {@link QueryBuilder.orWhereNotExists | orWhereNotExists} but adds a `having` statement
      * instead of a `where` statement.
      */
-    orHavingNotExists(arg: ExistsFilterArg<DB, TB>): QueryBuilder<DB, TB, O>;
+    orHavingNotExists(arg: ExistsExpression<DB, TB>): QueryBuilder<DB, TB, O>;
     /**
      * Adds a select clause to the query.
      *
-     * When a column (or any expression) is selected, Kysely also adds it to the return
-     * type of the query. Kysely is smart enough to parse the field names and types even
+     * 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
      * from aliased columns, subqueries, raw expressions etc.
      *
      * Kysely only allows you to select columns and expressions that exist and would
      * produce valid SQL. However, Kysely is not perfect and there may be cases where
      * the type inference doesn't work and you need to override it. You can always
-     * use the {@link Kysely.dynamic | dynamic} object and {@link Kysely.raw | raw}
+     * use the {@link Kysely.dynamic | dynamic} module and {@link Kysely.raw | raw}
      * to override the types.
      *
      * Select calls are additive. Calling `select('id').select('first_name')` is the
@@ -433,28 +480,29 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * Select a single column:
      *
      * ```ts
-     * const [person] = await db.selectFrom('person')
+     * const persons = await db.selectFrom('person')
      *   .select('id')
+     *   .where('first_name', '=', 'Arnold')
      *   .execute()
      *
-     * person.id
+     * persons[0].id
      * ```
      *
      * The generated SQL (postgresql):
      *
      * ```sql
-     * select "id" from "person"
+     * select "id" from "person" where "first_name" = $1
      * ```
      *
      * @example
      * Select a single column and specify a table:
      *
      * ```ts
-     * const [person] = await db.selectFrom(['person', 'pet'])
+     * const persons = await db.selectFrom(['person', 'pet'])
      *   .select('person.id')
      *   .execute()
      *
-     * person.id
+     * persons[0].id
      * ```
      *
      * The generated SQL (postgresql):
@@ -467,12 +515,12 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * Select multiple columns:
      *
      * ```ts
-     * const [person] = await db.selectFrom('person')
+     * const persons = await db.selectFrom('person')
      *   .select(['person.id', 'first_name'])
      *   .execute()
      *
-     * person.id
-     * person.first_name
+     * persons[0].id
+     * persons[0].first_name
      * ```
      *
      * The generated SQL (postgresql):
@@ -482,18 +530,18 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * ```
      *
      * @example
-     * Giving an alias for a selection:
+     * Aliased selections:
      *
      * ```ts
-     * const [person] = await db.selectFrom('person')
+     * const persons = await db.selectFrom('person')
      *   .select([
      *     'person.first_name as fn',
      *     'person.last_name as ln'
      *   ])
      *   .execute()
      *
-     * person.fn
-     * person.ln
+     * persons[0].fn
+     * persons[0].ln
      * ```
      *
      * The generated SQL (postgresql):
@@ -511,19 +559,20 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * method:
      *
      * ```ts
-     * const [person] = await db.selectFrom('person')
+     * const persons = await db.selectFrom('person')
      *   .select([
      *     (qb) => qb
      *       .subQuery('pet')
      *       .whereRef('person.id', '=', 'pet.owner_id')
      *       .select('pet.name')
+     *       .limit(1)
      *       .as('pet_name')
      *     db.raw<string>("concat(first_name, ' ', last_name)").as('full_name')
      *   ])
      *   .execute()
      *
-     * person.pet_name
-     * person.full_name
+     * persons[0].pet_name
+     * persons[0].full_name
      * ```
      *
      * The generated SQL (postgresql):
@@ -534,7 +583,8 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *     select "pet"."name"
      *     from "pet"
      *     where "person"."id" = "pet"."owner_id"
-     *   ) as pet_name,
+     *     limit $1
+     *   ) as "pet_name",
      *   concat(first_name, ' ', last_name) as full_name
      * from "person"
      * ```
@@ -548,7 +598,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * the types) sometimes it's not possible or you just prefer to write more
      * dynamic code.
      * <br><br>
-     * In this example, we use the `dynamic` object's methods to add selections
+     * In this example, we use the `dynamic` module's methods to add selections
      * dynamically:
      *
      * ```ts
@@ -561,7 +611,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * // You can use `keyof Person` if any column of an interface is allowed.
      * type PossibleColumns = 'last_name' | 'first_name' | 'birth_date'
      *
-     * const [person] = await db.selectFrom('person')
+     * const spersons = await db.selectFrom('person')
      *   .select([
      *     ref<PossibleColumns>(columnFromUserInput)
      *     'id'
@@ -571,12 +621,12 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * // 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 = person.last_name
-     * const firstName: string | undefined = person.first_name
-     * const birthDate: string | undefined = person.birth_date
+     * const lastName: string | undefined = persons[0].last_name
+     * const firstName: string | undefined = persons[0].first_name
+     * const birthDate: string | undefined = persons[0].birth_date
      *
      * // The result type also contains the compile time selection `id`.
-     * person.id
+     * persons[0].id
      * ```
      */
     select<S extends SelectExpression<DB, TB>>(selections: ReadonlyArray<S>): QueryBuilderWithSelection<DB, TB, O, S>;
@@ -584,6 +634,10 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
     /**
      * Adds `distinct on` selections to the select clause.
      *
+     * Takes the same inputs as the {@link QueryBuilder.select | select} method.
+     * See the {@link QueryBuilder.select | select} method's documentation for
+     * more examples.
+     *
      * @example
      * ```ts
      * await db.selectFrom('person')
@@ -606,7 +660,21 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
     distinctOn<S extends SelectExpression<DB, TB>>(selections: ReadonlyArray<S>): QueryBuilder<DB, TB, O>;
     distinctOn<S extends SelectExpression<DB, TB>>(selection: S): QueryBuilder<DB, TB, O>;
     /**
+     * Makes the selection distinct.
      *
+     * @example
+     * ```ts
+     * await db.selectFrom('person')
+     *   .select('first_name')
+     *   .distinct()
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (postgresql):
+     *
+     * ```sql
+     * select distinct "first_name" from "person"
+     * ```
      */
     distinct(): QueryBuilder<DB, TB, O>;
     /**
@@ -638,7 +706,8 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *
      * @example
      * ```ts
-     * await db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll()
      *   .execute()
      * ```
@@ -651,7 +720,8 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *
      * @example
      * ```ts
-     * await db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll('person')
      *   .execute()
      * ```
@@ -664,7 +734,8 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *
      * @example
      * ```ts
-     * await db.selectFrom(['person', 'pet'])
+     * const personsPets = await db
+     *   .selectFrom(['person', 'pet'])
      *   .selectAll(['person', 'pet'])
      *   .execute()
      * ```
@@ -685,10 +756,17 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * Simple usage by providing a table name and two columns to join:
      *
      * ```ts
-     * await db.selectFrom('person')
+     * const result = await db
+     *   .selectFrom('person')
      *   .selectAll()
      *   .innerJoin('pet', 'pet.owner_id', 'person.id')
      *   .execute()
+     *
+     * // The result has all `Person` columns
+     * result[0].first_name
+     *
+     * // The result has all `Pet` columns
+     * result[0].species
      * ```
      *
      * The generated SQL (postgresql):
@@ -779,52 +857,61 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   select "owner_id", "name"
      *   from "pet"
      *   where "name" = $1
-     * ) as doggos
+     * ) as "doggos"
      * on "doggos"."owner_id" = "person"."id"
      * ```
      */
-    innerJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceArg<DB, TB, TE>, K2 extends JoinReferenceArg<DB, TB, TE>>(table: TE, k1: K1, k2: K2): QueryBuilderWithTable<DB, TB, O, TE>;
-    innerJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackArg<DB, TB, TE>>(table: TE, callback: FN): QueryBuilderWithTable<DB, TB, O, TE>;
+    innerJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): QueryBuilderWithTable<DB, TB, O, TE>;
+    innerJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): QueryBuilderWithTable<DB, TB, O, TE>;
     /**
      * Just like {@link QueryBuilder.innerJoin | innerJoin} but adds a left join
      * instead of an inner join.
      */
-    leftJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceArg<DB, TB, TE>, K2 extends JoinReferenceArg<DB, TB, TE>>(table: TE, k1: K1, k2: K2): QueryBuilderWithTable<DB, TB, O, TE>;
-    leftJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackArg<DB, TB, TE>>(table: TE, callback: FN): QueryBuilderWithTable<DB, TB, O, TE>;
+    leftJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): QueryBuilderWithTable<DB, TB, O, TE>;
+    leftJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): QueryBuilderWithTable<DB, TB, O, TE>;
     /**
      * Just like {@link QueryBuilder.innerJoin | innerJoin} but adds a right join
      * instead of an inner join.
      */
-    rightJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceArg<DB, TB, TE>, K2 extends JoinReferenceArg<DB, TB, TE>>(table: TE, k1: K1, k2: K2): QueryBuilderWithTable<DB, TB, O, TE>;
-    rightJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackArg<DB, TB, TE>>(table: TE, callback: FN): QueryBuilderWithTable<DB, TB, O, TE>;
+    rightJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): QueryBuilderWithTable<DB, TB, O, TE>;
+    rightJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): QueryBuilderWithTable<DB, TB, O, TE>;
     /**
      * Just like {@link QueryBuilder.innerJoin | innerJoin} but adds a full join
      * instead of an inner join.
      */
-    fullJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceArg<DB, TB, TE>, K2 extends JoinReferenceArg<DB, TB, TE>>(table: TE, k1: K1, k2: K2): QueryBuilderWithTable<DB, TB, O, TE>;
-    fullJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackArg<DB, TB, TE>>(table: TE, callback: FN): QueryBuilderWithTable<DB, TB, O, TE>;
+    fullJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): QueryBuilderWithTable<DB, TB, O, TE>;
+    fullJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): QueryBuilderWithTable<DB, TB, O, TE>;
     /**
-     * Sets the values to insert for an `insertInto` query.
+     * Sets the values to insert for an {@link Kysely.insertInto | insert} query.
      *
      * This method takes an object whose keys are column names and values are
-     * values to insert. In addition to the column's type, the values can be `raw`
-     * instances or select queries.
+     * values to insert. In addition to the column's type, the values can be
+     * {@link Kysely.raw | raw} instances, select queries or the
+     * {@link Kysely.generated} placeholder.
+     *
+     * You must provide all values defined by the interface for the table you
+     * are inserting into. Values that are generated by the database like autoincrementing
+     * identifiers can be marked with the {@link Kysely.generated} placeholder unless you
+     * want to insert a specific value instead of the generated default.
      *
      * The return value is the primary key of the inserted row BUT on some databases
-     * there is no return value by default. That's the reason for the `any` type of the
-     * return value. On postgres you need to additionally call `returning` to get
-     * something out of the query.
+     * there is no return value by default. That's the reason for the `number | undefined`
+     * type of the return value. On postgres you need to additionally call `returning` to get
+     * something out of the query. If you know your database engine always returns the primary
+     * key, you can use the {@link QueryBuilder.executeTakeFirstOrThrow | executeTakeFirstOrThrow}
+     * method to execute the query.
      *
      * @example
      * Insert a row into `person`:
      * ```ts
-     * const maybeId = await db
+     * const id = await db
      *   .insertInto('person')
      *   .values({
+     *     id: db.generated,
      *     first_name: 'Jennifer',
      *     last_name: 'Aniston'
      *   })
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
      * ```
      *
      * The generated SQL (postgresql):
@@ -840,16 +927,18 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * row and some return nothing at all unless you call `returning`.
      *
      * ```ts
-     * const maybeId = await db
+     * await db
      *   .insertInto('person')
      *   .values([{
+     *     id: db.generated,
      *     first_name: 'Jennifer',
      *     last_name: 'Aniston'
      *   }, {
+     *     id: db.generated,
      *     first_name: 'Arnold',
      *     last_name: 'Schwarzenegger',
      *   }])
-     *   .executeTakeFirst()
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
@@ -867,11 +956,12 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * const row = await db
      *   .insertInto('person')
      *   .values({
+     *     id: db.generated,
      *     first_name: 'Jennifer',
      *     last_name: 'Aniston'
      *   })
      *   .returning('id')
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
      *
      * row.id
      * ```
@@ -890,6 +980,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * const maybeId = await db
      *   .insertInto('person')
      *   .values({
+     *     id: db.generated,
      *     first_name: 'Jennifer',
      *     last_name: db.raw('? || ?', ['Ani', 'ston']),
      *     age: db.selectFrom('person').select(raw('avg(age)')),
@@ -904,8 +995,8 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * values ($1, $2 || $3, (select avg(age) from "person"))
      * ```
      */
-    values(row: MutationObject<DB, TB>): QueryBuilder<DB, TB, O>;
-    values(row: MutationObject<DB, TB>[]): QueryBuilder<DB, TB, O>;
+    values(row: InsertObject<DB, TB>): QueryBuilder<DB, TB, O>;
+    values(row: InsertObject<DB, TB>[]): QueryBuilder<DB, TB, O>;
     /**
      * Ignores the insert if the column (or columns) given as the first
      * argument conflicts with the current rows in the database. The
@@ -928,6 +1019,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * await db
      *   .insertInto('pet')
      *   .values({
+     *     id: db.generated,
      *     name: 'Catto',
      *     species: 'cat',
      *   })
@@ -972,6 +1064,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * await db
      *   .insertInto('pet')
      *   .values({
+     *     id: db.generated,
      *     name: 'Catto',
      *     species: 'cat',
      *   })
@@ -990,7 +1083,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
     onConflictUpdate(column: AnyColumn<DB, TB>, updates: MutationObject<DB, TB>): QueryBuilder<DB, TB, O>;
     onConflictUpdate(columns: ReadonlyArray<AnyColumn<DB, TB>>, updates: MutationObject<DB, TB>): QueryBuilder<DB, TB, O>;
     /**
-     * Sets the values to update for an `updateTable` query.
+     * Sets the values to update for an {@link Kysely.updateTable | update} query.
      *
      * This method takes an object whose keys are column names and values are
      * values to update. In addition to the column's type, the values can be `raw`
@@ -1021,7 +1114,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * ```
      *
      * @example
-     * On postgresql you need to chain `returning` to the query to get
+     * On postgresql you ca chain `returning` to the query to get
      * the updated rows' columns (or any other expression) as the
      * return value:
      *
@@ -1034,7 +1127,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   })
      *   .where('id', '=', 1)
      *   .returning('id')
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
      *
      * row.id
      * ```
@@ -1087,6 +1180,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * const { id } = await db
      *   .insertInto('person')
      *   .values({
+     *     id: db.generated,
      *     first_name: 'Jennifer',
      *     last_name: 'Aniston'
      *   })
@@ -1101,6 +1195,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * const { id, first_name } = await db
      *   .insertInto('person')
      *   .values({
+     *     id: db.generated,
      *     first_name: 'Jennifer',
      *     last_name: 'Aniston'
      *   })
@@ -1117,6 +1212,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * const { id, full_name, first_pet_id } = await db
      *   .insertInto('person')
      *   .values({
+     *     id: db.generated,
      *     first_name: 'Jennifer',
      *     last_name: 'Aniston'
      *   })