kysely 0.27.3 → 0.27.5

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

@@ -11,7 +11,7 @@ import { QueryExecutor } from '../query-executor/query-executor.js';
 import { QueryId } from '../util/query-id.js';
 import { InsertResult } from './insert-result.js';
 import { KyselyPlugin } from '../plugin/kysely-plugin.js';
-import { ReturningCallbackRow, ReturningRow } from '../parser/returning-parser.js';
+import { ReturningAllRow, ReturningCallbackRow, ReturningRow } from '../parser/returning-parser.js';
 import { NoResultErrorConstructor } from './no-result-error.js';
 import { ExpressionOrFactory } from '../parser/expression-parser.js';
 import { ReturningInterface } from './returning-interface.js';
@@ -21,7 +21,8 @@ import { Explainable, ExplainFormat } from '../util/explainable.js';
 import { Expression } from '../expression/expression.js';
 import { KyselyTypeError } from '../util/type-error.js';
 import { Streamable } from '../util/streamable.js';
-export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements ReturningInterface<DB, TB, O>, OperationNodeSource, Compilable<O>, Explainable, Streamable<O> {
+import { OutputCallback, OutputExpression, OutputInterface, SelectExpressionFromOutputCallback, SelectExpressionFromOutputExpression } from './output-interface.js';
+export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements ReturningInterface<DB, TB, O>, OutputInterface<DB, TB, O, 'inserted'>, OperationNodeSource, Compilable<O>, Explainable, Streamable<O> {
     #private;
     constructor(props: InsertQueryBuilderProps);
     /**
@@ -143,11 +144,10 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *   .insertInto('person')
      *   .values(({ ref, selectFrom, fn }) => ({
      *     first_name: 'Jennifer',
-     *     last_name: sql`concat(${ani}, ${ston})`,
+     *     last_name: sql<string>`concat(${ani}, ${ston})`,
      *     middle_name: ref('first_name'),
      *     age: selectFrom('person')
-     *       .select(fn.avg<number>('age')
-     *       .as('avg_age')),
+     *       .select(fn.avg<number>('age').as('avg_age')),
      *   }))
      *   .executeTakeFirst()
      * ```
@@ -172,7 +172,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * You can also use the callback version of subqueries or raw expressions:
      *
      * ```ts
-     * db.with('jennifer', (db) => db
+     * await db.with('jennifer', (db) => db
      *   .selectFrom('person')
      *   .where('first_name', '=', 'Jennifer')
      *   .select(['id', 'first_name', 'gender'])
@@ -182,6 +182,24 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *   name: eb.selectFrom('jennifer').select('first_name'),
      *   species: 'cat',
      * }))
+     * .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * with "jennifer" as (
+     *   select "id", "first_name", "gender"
+     *   from "person"
+     *   where "first_name" = $1
+     *   limit $2
+     * )
+     * insert into "pet" ("owner_id", "name", "species")
+     * values (
+     *  (select "id" from "jennifer"),
+     *  (select "first_name" from "jennifer"),
+     *  $3
+     * )
      * ```
      */
     values(insert: InsertExpression<DB, TB>): InsertQueryBuilder<DB, TB, O>;
@@ -195,9 +213,10 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * ### Examples
      *
      * ```ts
-     * db.insertInto('person')
+     * await db.insertInto('person')
      *   .columns(['first_name'])
      *   .expression((eb) => eb.selectFrom('pet').select('pet.name'))
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -215,7 +234,9 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *
      * <!-- siteExample("insert", "Insert subquery", 50) -->
      *
-     * You can create an `INSERT INTO SELECT FROM` query using the `expression` method:
+     * You can create an `INSERT INTO SELECT FROM` query using the `expression` method.
+     * This API doesn't follow our WYSIWYG principles and might be a bit difficult to
+     * remember. The reasons for this design stem from implementation difficulties.
      *
      * ```ts
      * const result = await db.insertInto('person')
@@ -249,8 +270,40 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *   .defaultValues()
      *   .execute()
      * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" default values
+     * ```
      */
     defaultValues(): InsertQueryBuilder<DB, TB, O>;
+    /**
+     * This can be used to add any additional SQL to the end of the query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * await db.insertInto('person')
+     *   .values({
+     *     first_name: 'John',
+     *     last_name: 'Doe',
+     *     gender: 'male',
+     *   })
+     *   .modifyEnd(sql`-- This is a comment`)
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * insert into `person` ("first_name", "last_name", "gender")
+     * values (?, ?, ?) -- This is a comment
+     * ```
+     */
+    modifyEnd(modifier: Expression<any>): InsertQueryBuilder<DB, TB, O>;
     /**
      * Changes an `insert into` query to an `insert ignore into` query.
      *
@@ -268,9 +321,19 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * ```ts
      * await db.insertInto('person')
      *   .ignore()
-     *   .values(values)
+     *   .values({
+     *     first_name: 'John',
+     *     last_name: 'Doe',
+     *     gender: 'female',
+     *   })
      *   .execute()
      * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * insert ignore into `person` ("first_name", "last_name", "gender") values (?, ?, ?)
+     * ```
      */
     ignore(): InsertQueryBuilder<DB, TB, O>;
     /**
@@ -283,6 +346,8 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * Insert the first 5 rows:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * await db.insertInto('person')
      *   .top(5)
      *   .columns(['first_name', 'gender'])
@@ -301,6 +366,8 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * Insert the first 50 percent of rows:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * await db.insertInto('person')
      *   .top(50, 'percent')
      *   .columns(['first_name', 'gender'])
@@ -331,6 +398,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *   .values({
      *     name: 'Catto',
      *     species: 'cat',
+     *     owner_id: 3,
      *   })
      *   .onConflict((oc) => oc
      *     .column('name')
@@ -342,10 +410,10 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * insert into "pet" ("name", "species")
-     * values ($1, $2)
+     * insert into "pet" ("name", "species", "owner_id")
+     * values ($1, $2, $3)
      * on conflict ("name")
-     * do update set "species" = $3
+     * do update set "species" = $4
      * ```
      *
      * You can provide the name of the constraint instead of a column name:
@@ -356,6 +424,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *   .values({
      *     name: 'Catto',
      *     species: 'cat',
+     *     owner_id: 3,
      *   })
      *   .onConflict((oc) => oc
      *     .constraint('pet_name_key')
@@ -367,10 +436,10 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * insert into "pet" ("name", "species")
-     * values ($1, $2)
+     * insert into "pet" ("name", "species", "owner_id")
+     * values ($1, $2, $3)
      * on conflict on constraint "pet_name_key"
-     * do update set "species" = $3
+     * do update set "species" = $4
      * ```
      *
      * You can also specify an expression as the conflict target in case
@@ -384,9 +453,10 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *   .values({
      *     name: 'Catto',
      *     species: 'cat',
+     *     owner_id: 3,
      *   })
      *   .onConflict((oc) => oc
-     *     .expression(sql`lower(name)`)
+     *     .expression(sql<string>`lower(name)`)
      *     .doUpdateSet({ species: 'hamster' })
      *   )
      *   .execute()
@@ -395,10 +465,10 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * insert into "pet" ("name", "species")
-     * values ($1, $2)
+     * insert into "pet" ("name", "species", "owner_id")
+     * values ($1, $2, $3)
      * on conflict (lower(name))
-     * do update set "species" = $3
+     * do update set "species" = $4
      * ```
      *
      * You can add a filter for the update statement like this:
@@ -409,11 +479,12 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *   .values({
      *     name: 'Catto',
      *     species: 'cat',
+     *     owner_id: 3,
      *   })
      *   .onConflict((oc) => oc
      *     .column('name')
      *     .doUpdateSet({ species: 'hamster' })
-     *     .where('excluded.name', '!=', 'Catto'')
+     *     .where('excluded.name', '!=', 'Catto')
      *   )
      *   .execute()
      * ```
@@ -421,11 +492,11 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * insert into "pet" ("name", "species")
-     * values ($1, $2)
+     * insert into "pet" ("name", "species", "owner_id")
+     * values ($1, $2, $3)
      * on conflict ("name")
-     * do update set "species" = $3
-     * where "excluded"."name" != $4
+     * do update set "species" = $4
+     * where "excluded"."name" != $5
      * ```
      *
      * You can create an `on conflict do nothing` clauses like this:
@@ -436,6 +507,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *   .values({
      *     name: 'Catto',
      *     species: 'cat',
+     *     owner_id: 3,
      *   })
      *   .onConflict((oc) => oc
      *     .column('name')
@@ -447,8 +519,8 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * insert into "pet" ("name", "species")
-     * values ($1, $2)
+     * insert into "pet" ("name", "species", "owner_id")
+     * values ($1, $2, $3)
      * on conflict ("name") do nothing
      * ```
      *
@@ -457,8 +529,13 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * `ExpressionBuilder`:
      *
      * ```ts
-     * db.insertInto('person')
-     *   .values(person)
+     * await db.insertInto('person')
+     *   .values({
+     *     id: 1,
+     *     first_name: 'John',
+     *     last_name: 'Doe',
+     *     gender: 'male',
+     *   })
      *   .onConflict(oc => oc
      *     .column('id')
      *     .doUpdateSet({
@@ -466,6 +543,18 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *       last_name: (eb) => eb.ref('excluded.last_name')
      *     })
      *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("id", "first_name", "last_name", "gender")
+     * values ($1, $2, $3, $4)
+     * on conflict ("id")
+     * do update set
+     *  "first_name" = "excluded"."first_name",
+     *  "last_name" = "excluded"."last_name"
      * ```
      */
     onConflict(callback: (builder: OnConflictBuilder<DB, TB>) => OnConflictUpdateBuilder<OnConflictDatabase<DB, TB>, OnConflictTables<TB>> | OnConflictDoNothingBuilder<DB, TB>): InsertQueryBuilder<DB, TB, O>;
@@ -483,8 +572,22 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * ```ts
      * await db
      *   .insertInto('person')
-     *   .values(values)
-     *   .onDuplicateKeyUpdate({ species: 'hamster' })
+     *   .values({
+     *     id: 1,
+     *     first_name: 'John',
+     *     last_name: 'Doe',
+     *     gender: 'male',
+     *   })
+     *   .onDuplicateKeyUpdate({ updated_at: new Date().toISOString() })
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * insert into `person` (`id`, `first_name`, `last_name`, `gender`)
+     * values (?, ?, ?, ?)
+     * on duplicate key update `updated_at` = ?
      * ```
      */
     onDuplicateKeyUpdate(update: UpdateObjectExpression<DB, TB, TB>): InsertQueryBuilder<DB, TB, O>;
@@ -512,20 +615,20 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *     last_name: 'Aniston'
      *   })
      *   .returning('id')
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
      * ```
      *
      * Return multiple columns:
      *
      * ```ts
-     * const { id, first_name } = await db
+     * const { id, last_name } = await db
      *   .insertInto('person')
      *   .values({
      *     first_name: 'Jennifer',
      *     last_name: 'Aniston'
      *   })
      *   .returning(['id', 'last_name'])
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
      * ```
      *
      * Return arbitrary expressions:
@@ -542,9 +645,9 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *   .returning((eb) => [
      *     'id as id',
      *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name'),
-     *     eb.selectFrom('pets').select('pet.id').limit(1).as('first_pet_id')
+     *     eb.selectFrom('pet').select('pet.id').limit(1).as('first_pet_id')
      *   ])
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
      * ```
      */
     returning<SE extends SelectExpression<DB, TB>>(selections: ReadonlyArray<SE>): InsertQueryBuilder<DB, TB, ReturningRow<DB, TB, O, SE>>;
@@ -553,24 +656,151 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
     /**
      * Adds a `returning *` to an insert/update/delete query on databases
      * that support `returning` such as PostgreSQL.
+     *
+     * Also see the {@link returning} method.
      */
     returningAll(): InsertQueryBuilder<DB, TB, Selectable<DB[TB]>>;
+    /**
+     * Allows you to return data from modified rows.
+     *
+     * On supported databases like MS SQL Server (MSSQL), this method can be chained
+     * to `insert`, `update`, `delete` and `merge` queries to return data.
+     *
+     * Also see the {@link outputAll} method.
+     *
+     * ### Examples
+     *
+     * Return one column:
+     *
+     * ```ts
+     * const { id } = await db
+     *   .insertInto('person')
+     *   .output('inserted.id')
+     *   .values({
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston',
+     *     gender: 'female',
+     *   })
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (MSSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name", "last_name", "gender")
+     * output "inserted"."id"
+     * values (@1, @2, @3)
+     * ```
+     *
+     * Return multiple columns:
+     *
+     * ```ts
+     * const { old_first_name, old_last_name, new_first_name, new_last_name } = await db
+     *   .updateTable('person')
+     *   .set({ first_name: 'John', last_name: 'Doe' })
+     *   .output([
+     *     'deleted.first_name as old_first_name',
+     *     'deleted.last_name as old_last_name',
+     *     'inserted.first_name as new_first_name',
+     *     'inserted.last_name as new_last_name',
+     *   ])
+     *   .where('created_at', '<', new Date())
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (MSSQL):
+     *
+     * ```sql
+     * update "person"
+     * set "first_name" = @1, "last_name" = @2
+     * output "deleted"."first_name" as "old_first_name",
+     *   "deleted"."last_name" as "old_last_name",
+     *   "inserted"."first_name" as "new_first_name",
+     *   "inserted"."last_name" as "new_last_name"
+     * where "created_at" < @3
+     * ```
+     *
+     * Return arbitrary expressions:
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const { full_name } = await db
+     *   .deleteFrom('person')
+     *   .output((eb) => sql<string>`concat(${eb.ref('deleted.first_name')}, ' ', ${eb.ref('deleted.last_name')})`.as('full_name'))
+     *   .where('created_at', '<', new Date())
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (MSSQL):
+     *
+     * ```sql
+     * delete from "person"
+     * output concat("deleted"."first_name", ' ', "deleted"."last_name") as "full_name"
+     * where "created_at" < @1
+     * ```
+     *
+     * Return the action performed on the row:
+     *
+     * ```ts
+     * await db
+     *   .mergeInto('person')
+     *   .using('pet', 'pet.owner_id', 'person.id')
+     *   .whenMatched()
+     *   .thenDelete()
+     *   .whenNotMatched()
+     *   .thenInsertValues({
+     *     first_name: 'John',
+     *     last_name: 'Doe',
+     *     gender: 'male'
+     *   })
+     *   .output([
+     *     'inserted.id as inserted_id',
+     *     'deleted.id as deleted_id',
+     *   ])
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MSSQL):
+     *
+     * ```sql
+     * merge into "person"
+     * using "pet" on "pet"."owner_id" = "person"."id"
+     * when matched then delete
+     * when not matched then
+     * insert ("first_name", "last_name", "gender")
+     * values (@1, @2, @3)
+     * output "inserted"."id" as "inserted_id", "deleted"."id" as "deleted_id"
+     * ```
+     *
+     */
+    output<OE extends OutputExpression<DB, TB, 'inserted'>>(selections: readonly OE[]): InsertQueryBuilder<DB, TB, ReturningRow<DB, TB, O, SelectExpressionFromOutputExpression<OE>>>;
+    output<CB extends OutputCallback<DB, TB, 'inserted'>>(callback: CB): InsertQueryBuilder<DB, TB, ReturningRow<DB, TB, O, SelectExpressionFromOutputCallback<CB>>>;
+    output<OE extends OutputExpression<DB, TB, 'inserted'>>(selection: OE): InsertQueryBuilder<DB, TB, ReturningRow<DB, TB, O, SelectExpressionFromOutputExpression<OE>>>;
+    /**
+     * Adds an `output {prefix}.*` to an `insert`/`update`/`delete`/`merge` query on databases
+     * that support `output` such as MS SQL Server (MSSQL).
+     *
+     * Also see the {@link output} method.
+     */
+    outputAll(table: 'inserted'): InsertQueryBuilder<DB, TB, ReturningAllRow<DB, TB, O>>;
     /**
      * Clears all `returning` clauses from the query.
      *
      * ### Examples
      *
      * ```ts
-     * db.insertInto('person')
-     *   .values({ first_name: 'James', last_name: 'Smith', age: 42 })
+     * await db.insertInto('person')
+     *   .values({ first_name: 'James', last_name: 'Smith', gender: 'male' })
      *   .returning(['first_name'])
      *   .clearReturning()
+     *   .execute()
      * ```
      *
      * The generated SQL(PostgreSQL):
      *
      * ```sql
-     * insert into "person" ("James", "Smith", 42)
+     * insert into "person" ("first_name", "last_name", "gender") values ($1, $2, $3)
      * ```
      */
     clearReturning(): InsertQueryBuilder<DB, TB, InsertResult>;
@@ -586,13 +816,15 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * 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.updateTable('person')
-     *   .set(values)
+     * await db.insertInto('person')
+     *   .values({ first_name: 'John', last_name: 'Doe', gender: 'male' })
      *   .$call(log)
      *   .execute()
      * ```
@@ -611,7 +843,9 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * ### Examples
      *
      * ```ts
-     * async function insertPerson(values: InsertablePerson, returnLastName: boolean) {
+     * import type { NewPerson } from 'type-editor' // imaginary module
+     *
+     * async function insertPerson(values: NewPerson, returnLastName: boolean) {
      *   return await db
      *     .insertInto('person')
      *     .values(values)
@@ -626,11 +860,11 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * the code. In the example above the return type of the `insertPerson` function is:
      *
      * ```ts
-     * {
+     * Promise<{
      *   id: number
      *   first_name: string
      *   last_name?: string
-     * }
+     * }>
      * ```
      */
     $if<O2>(condition: boolean, func: (qb: this) => InsertQueryBuilder<any, any, O2>): O2 extends InsertResult ? InsertQueryBuilder<DB, TB, InsertResult> : O2 extends O & infer E ? InsertQueryBuilder<DB, TB, O & Partial<E>> : InsertQueryBuilder<DB, TB, Partial<O2>>;
@@ -659,23 +893,41 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * Turn this code:
      *
      * ```ts
+     * import type { Person } from 'type-editor' // imaginary module
+     *
      * const person = await db.insertInto('person')
-     *   .values({ ...inputPerson, nullable_column: 'hell yeah!' })
+     *   .values({
+     *     first_name: 'John',
+     *     last_name: 'Doe',
+     *     gender: 'male',
+     *     nullable_column: 'hell yeah!'
+     *   })
      *   .returningAll()
      *   .executeTakeFirstOrThrow()
      *
-     * if (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.insertInto('person')
-     *   .values({ ...inputPerson, nullable_column: 'hell yeah!' })
+     *   .values({
+     *     first_name: 'John',
+     *     last_name: 'Doe',
+     *     gender: 'male',
+     *     nullable_column: 'hell yeah!'
+     *   })
      *   .returningAll()
-     *   .$narrowType<{ nullable_column: string }>()
+     *   .$narrowType<{ nullable_column: NotNull }>()
      *   .executeTakeFirstOrThrow()
      *
      * functionThatExpectsPersonWithNonNullValue(person)
@@ -685,17 +937,17 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
     /**
      * 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.
      *
@@ -705,22 +957,29 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * ### Examples
      *
      * ```ts
-     * const result = await db
-     *   .with('new_person', (qb) => qb
-     *     .insertInto('person')
-     *     .values(person)
-     *     .returning('id')
-     *     .$assertType<{ id: string }>()
-     *   )
-     *   .with('new_pet', (qb) => qb
-     *     .insertInto('pet')
-     *     .values((eb) => ({ owner_id: eb.selectFrom('new_person').select('id'), ...pet }))
-     *     .returning(['name as pet_name', 'species'])
-     *     .$assertType<{ pet_name: string, species: Species }>()
-     *   )
-     *   .selectFrom(['new_person', 'new_pet'])
-     *   .selectAll()
-     *   .executeTakeFirstOrThrow()
+     * import type { NewPerson, NewPet, Species } from 'type-editor' // imaginary module
+     *
+     * async function insertPersonAndPet(person: NewPerson, pet: Omit<NewPet, 'owner_id'>) {
+     *   return await db
+     *     .with('new_person', (qb) => qb
+     *       .insertInto('person')
+     *       .values(person)
+     *       .returning('id')
+     *       .$assertType<{ id: number }>()
+     *     )
+     *     .with('new_pet', (qb) => qb
+     *       .insertInto('pet')
+     *       .values((eb) => ({
+     *         owner_id: eb.selectFrom('new_person').select('id'),
+     *         ...pet
+     *       }))
+     *       .returning(['name as pet_name', 'species'])
+     *       .$assertType<{ pet_name: string, species: Species }>()
+     *     )
+     *     .selectFrom(['new_person', 'new_pet'])
+     *     .selectAll()
+     *     .executeTakeFirstOrThrow()
+     * }
      * ```
      */
     $assertType<T extends O>(): O extends T ? InsertQueryBuilder<DB, TB, T> : KyselyTypeError<`$assertType() call failed: The type passed in is not equal to the output type of the query.`>;
@@ -759,7 +1018,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * ### Examples
      *
      * ```ts
-     * const stream = db.
+     * const stream = db
      *   .selectFrom('person')
      *   .select(['first_name', 'last_name'])
      *   .where('gender', '=', 'other')