kysely 0.27.3 → 0.27.5

package/dist/cjs/query-builder/select-query-builder.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createSelectQueryBuilder = void 0;
+exports.createSelectQueryBuilder = createSelectQueryBuilder;
 const alias_node_js_1 = require("../operation-node/alias-node.js");
 const select_modifier_node_js_1 = require("../operation-node/select-modifier-node.js");
 const join_parser_js_1 = require("../parser/join-parser.js");
@@ -79,7 +79,7 @@ class SelectQueryBuilderImpl {
     modifyEnd(modifier) {
         return new SelectQueryBuilderImpl({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithEndModifier(this.#props.queryNode, select_modifier_node_js_1.SelectModifierNode.createWithExpression(modifier.toOperationNode())),
+            queryNode: query_node_js_1.QueryNode.cloneWithEndModifier(this.#props.queryNode, select_modifier_node_js_1.SelectModifierNode.createWithExpression(modifier.toOperationNode())),
         });
     }
     distinct() {
@@ -91,37 +91,37 @@ class SelectQueryBuilderImpl {
     forUpdate(of) {
         return new SelectQueryBuilderImpl({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithEndModifier(this.#props.queryNode, select_modifier_node_js_1.SelectModifierNode.create('ForUpdate', of ? (0, object_utils_js_1.asArray)(of).map(table_parser_js_1.parseTable) : undefined)),
+            queryNode: query_node_js_1.QueryNode.cloneWithEndModifier(this.#props.queryNode, select_modifier_node_js_1.SelectModifierNode.create('ForUpdate', of ? (0, object_utils_js_1.asArray)(of).map(table_parser_js_1.parseTable) : undefined)),
         });
     }
     forShare(of) {
         return new SelectQueryBuilderImpl({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithEndModifier(this.#props.queryNode, select_modifier_node_js_1.SelectModifierNode.create('ForShare', of ? (0, object_utils_js_1.asArray)(of).map(table_parser_js_1.parseTable) : undefined)),
+            queryNode: query_node_js_1.QueryNode.cloneWithEndModifier(this.#props.queryNode, select_modifier_node_js_1.SelectModifierNode.create('ForShare', of ? (0, object_utils_js_1.asArray)(of).map(table_parser_js_1.parseTable) : undefined)),
         });
     }
     forKeyShare(of) {
         return new SelectQueryBuilderImpl({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithEndModifier(this.#props.queryNode, select_modifier_node_js_1.SelectModifierNode.create('ForKeyShare', of ? (0, object_utils_js_1.asArray)(of).map(table_parser_js_1.parseTable) : undefined)),
+            queryNode: query_node_js_1.QueryNode.cloneWithEndModifier(this.#props.queryNode, select_modifier_node_js_1.SelectModifierNode.create('ForKeyShare', of ? (0, object_utils_js_1.asArray)(of).map(table_parser_js_1.parseTable) : undefined)),
         });
     }
     forNoKeyUpdate(of) {
         return new SelectQueryBuilderImpl({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithEndModifier(this.#props.queryNode, select_modifier_node_js_1.SelectModifierNode.create('ForNoKeyUpdate', of ? (0, object_utils_js_1.asArray)(of).map(table_parser_js_1.parseTable) : undefined)),
+            queryNode: query_node_js_1.QueryNode.cloneWithEndModifier(this.#props.queryNode, select_modifier_node_js_1.SelectModifierNode.create('ForNoKeyUpdate', of ? (0, object_utils_js_1.asArray)(of).map(table_parser_js_1.parseTable) : undefined)),
         });
     }
     skipLocked() {
         return new SelectQueryBuilderImpl({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithEndModifier(this.#props.queryNode, select_modifier_node_js_1.SelectModifierNode.create('SkipLocked')),
+            queryNode: query_node_js_1.QueryNode.cloneWithEndModifier(this.#props.queryNode, select_modifier_node_js_1.SelectModifierNode.create('SkipLocked')),
         });
     }
     noWait() {
         return new SelectQueryBuilderImpl({
             ...this.#props,
-            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithEndModifier(this.#props.queryNode, select_modifier_node_js_1.SelectModifierNode.create('NoWait')),
+            queryNode: query_node_js_1.QueryNode.cloneWithEndModifier(this.#props.queryNode, select_modifier_node_js_1.SelectModifierNode.create('NoWait')),
         });
     }
     selectAll(table) {
@@ -271,6 +271,12 @@ class SelectQueryBuilderImpl {
             queryNode: select_query_node_js_1.SelectQueryNode.cloneWithoutOrderBy(this.#props.queryNode),
         });
     }
+    clearGroupBy() {
+        return new SelectQueryBuilderImpl({
+            ...this.#props,
+            queryNode: select_query_node_js_1.SelectQueryNode.cloneWithoutGroupBy(this.#props.queryNode),
+        });
+    }
     $call(func) {
         return func(this);
     }
@@ -344,7 +350,6 @@ class SelectQueryBuilderImpl {
 function createSelectQueryBuilder(props) {
     return new SelectQueryBuilderImpl(props);
 }
-exports.createSelectQueryBuilder = createSelectQueryBuilder;
 /**
  * {@link SelectQueryBuilder} with an alias. The result of calling {@link SelectQueryBuilder.as}.
  */

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

@@ -3,7 +3,7 @@ import { CompiledQuery } from '../query-compiler/compiled-query.js';
 import { JoinCallbackExpression, JoinReferenceExpression } from '../parser/join-parser.js';
 import { TableExpression, From, FromTables } from '../parser/table-parser.js';
 import { SelectExpression, SelectCallback } from '../parser/select-parser.js';
-import { ReturningCallbackRow, ReturningRow } from '../parser/returning-parser.js';
+import { ReturningAllRow, ReturningCallbackRow, ReturningRow } from '../parser/returning-parser.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
 import { QueryNode } from '../operation-node/query-node.js';
 import { DrainOuterGeneric, NarrowPartial, Nullable, ShallowRecord, SimplifyResult, SimplifySingleResult, SqlBool } from '../util/type-utils.js';
@@ -17,7 +17,6 @@ import { KyselyPlugin } from '../plugin/kysely-plugin.js';
 import { WhereInterface } from './where-interface.js';
 import { ReturningInterface } from './returning-interface.js';
 import { NoResultErrorConstructor } from './no-result-error.js';
-import { Selectable } from '../util/column-type.js';
 import { Explainable, ExplainFormat } from '../util/explainable.js';
 import { AliasedExpression, Expression } from '../expression/expression.js';
 import { ComparisonOperatorExpression, OperandValueExpressionOrList } from '../parser/binary-operation-parser.js';
@@ -25,7 +24,8 @@ import { KyselyTypeError } from '../util/type-error.js';
 import { Streamable } from '../util/streamable.js';
 import { ExpressionOrFactory } from '../parser/expression-parser.js';
 import { ValueExpression } from '../parser/value-parser.js';
-export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyof DB, O> implements WhereInterface<DB, TB>, ReturningInterface<DB, TB, O>, OperationNodeSource, Compilable<O>, Explainable, Streamable<O> {
+import { OutputCallback, OutputExpression, OutputInterface, OutputPrefix, SelectExpressionFromOutputCallback, SelectExpressionFromOutputExpression } from './output-interface.js';
+export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyof DB, O> implements WhereInterface<DB, TB>, ReturningInterface<DB, TB, O>, OutputInterface<DB, TB, O>, OperationNodeSource, Compilable<O>, Explainable, Streamable<O> {
     #private;
     constructor(props: UpdateQueryBuilderProps);
     /**
@@ -60,6 +60,8 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * you can always use:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * sql`your operator`
      * ```
      *
@@ -71,7 +73,7 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
-     *   .where('id', 'in', ['1', '2', '3'])
+     *   .where('id', 'in', [1, 2, 3])
      *   .execute()
      * ```
      *
@@ -290,7 +292,7 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      *   .selectFrom('person')
      *   .selectAll()
      *   .where(
-     *     sql`coalesce(first_name, last_name)`,
+     *     sql<string>`coalesce(first_name, last_name)`,
      *     'like',
      *     '%' + name + '%',
      *   )
@@ -319,6 +321,8 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * import { sql } from 'kysely'
      * const { ref } = db.dynamic
      *
+     * const columnFromUserInput: string = 'id'
+     *
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
@@ -554,7 +558,7 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * ```ts
      * await db.selectFrom('person')
      *   .innerJoin(
-     *     qb.selectFrom('pet')
+     *     db.selectFrom('pet')
      *       .select(['owner_id', 'name'])
      *       .where('name', '=', 'Doggo')
      *       .as('doggos'),
@@ -603,15 +607,17 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * Update the first 2 rows in the 'person' table:
      *
      * ```ts
-     * return await db
+     * await db
      *   .updateTable('person')
      *   .set({ first_name: 'Foo' })
-     *   .limit(2);
+     *   .limit(2)
+     *   .execute()
      * ```
      *
      * The generated SQL (MySQL):
+     *
      * ```sql
-     * update `person` set `first_name` = 'Foo' limit 2
+     * update `person` set `first_name` = ? limit ?
      * ```
      */
     limit(limit: ValueExpression<DB, TB, number>): UpdateQueryBuilder<DB, UT, TB, O>;
@@ -643,7 +649,7 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      *     first_name: 'Jennifer',
      *     last_name: 'Aniston'
      *   })
-     *   .where('id', '=', '1')
+     *   .where('id', '=', 1)
      *   .executeTakeFirst()
      *
      * console.log(result.numUpdatedRows)
@@ -668,7 +674,7 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      *     first_name: eb.selectFrom('pet').select('name').limit(1),
      *     last_name: 'updated',
      *   }))
-     *   .where('id', '=', '1')
+     *   .where('id', '=', 1)
      *   .executeTakeFirst()
      *
      * console.log(result.numUpdatedRows)
@@ -690,13 +696,15 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * (or other target) and the second as the value:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const result = await db
      *   .updateTable('person')
      *   .set('first_name', 'Foo')
      *   // As always, both arguments can be arbitrary expressions or
      *   // callbacks that give you access to an expression builder:
-     *   .set(sql`address['postalCode']`, (eb) => eb.val('61710))
-     *   .where('id', '=', '1')
+     *   .set(sql<string>`address['postalCode']`, (eb) => eb.val('61710'))
+     *   .where('id', '=', 1)
      *   .executeTakeFirst()
      * ```
      *
@@ -736,7 +744,7 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      *     first_name: selectFrom('person').select('first_name').limit(1),
      *     middle_name: ref('first_name'),
      *     age: eb('age', '+', 1),
-     *     last_name: sql`${'Ani'} || ${'ston'}`,
+     *     last_name: sql<string>`${'Ani'} || ${'ston'}`,
      *   }))
      *   .where('id', '=', 1)
      *   .executeTakeFirst()
@@ -781,20 +789,20 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      *     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:
@@ -811,9 +819,9 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      *   .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>): UpdateQueryBuilder<DB, UT, TB, ReturningRow<DB, TB, O, SE>>;
@@ -822,8 +830,160 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
     /**
      * Adds a `returning *` to an insert/update/delete query on databases
      * that support `returning` such as PostgreSQL.
+     *
+     * Also see the {@link returning} method.
+     */
+    returningAll<T extends TB>(tables: ReadonlyArray<T>): UpdateQueryBuilder<DB, UT, TB, ReturningAllRow<DB, T, O>>;
+    returningAll<T extends TB>(table: T): UpdateQueryBuilder<DB, UT, TB, ReturningAllRow<DB, T, O>>;
+    returningAll(): UpdateQueryBuilder<DB, UT, TB, ReturningAllRow<DB, TB, O>>;
+    /**
+     * 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"
+     * ```
+     *
      */
-    returningAll(): UpdateQueryBuilder<DB, UT, TB, Selectable<DB[TB]>>;
+    output<OE extends OutputExpression<DB, UT>>(selections: readonly OE[]): UpdateQueryBuilder<DB, UT, TB, ReturningRow<DB, TB, O, SelectExpressionFromOutputExpression<OE>>>;
+    output<CB extends OutputCallback<DB, TB>>(callback: CB): UpdateQueryBuilder<DB, UT, TB, ReturningRow<DB, TB, O, SelectExpressionFromOutputCallback<CB>>>;
+    output<OE extends OutputExpression<DB, TB>>(selection: OE): UpdateQueryBuilder<DB, UT, 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: OutputPrefix): UpdateQueryBuilder<DB, UT, TB, ReturningAllRow<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.updateTable('person')
+     *   .set({ age: 39 })
+     *   .where('first_name', '=', 'John')
+     *   .modifyEnd(sql.raw('-- This is a comment'))
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * update `person`
+     * set `age` = 39
+     * where `first_name` = "John" -- This is a comment
+     * ```
+     */
+    modifyEnd(modifier: Expression<any>): UpdateQueryBuilder<DB, UT, TB, O>;
     /**
      * Clears all `returning` clauses from the query.
      *
@@ -856,11 +1016,18 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * The next example uses a helper function `log` to log a query:
      *
      * ```ts
+     * import type { Compilable } from 'kysely'
+     * import type { PersonUpdate } from 'type-editor' // imaginary module
+     *
      * function log<T extends Compilable>(qb: T): T {
      *   console.log(qb.compile())
      *   return qb
      * }
      *
+     * const values = {
+     *   first_name: 'John',
+     * } satisfies PersonUpdate
+     *
      * db.updateTable('person')
      *   .set(values)
      *   .$call(log)
@@ -881,7 +1048,9 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * ### Examples
      *
      * ```ts
-     * async function updatePerson(id: number, updates: UpdateablePerson, returnLastName: boolean) {
+     * import type { PersonUpdate } from 'type-editor' // imaginary module
+     *
+     * async function updatePerson(id: number, updates: PersonUpdate, returnLastName: boolean) {
      *   return await db
      *     .updateTable('person')
      *     .set(updates)
@@ -897,11 +1066,11 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * the code. In the example above the return type of the `updatePerson` function is:
      *
      * ```ts
-     * {
+     * Promise<{
      *   id: number
      *   first_name: string
      *   last_name?: string
-     * }
+     * }>
      * ```
      */
     $if<O2>(condition: boolean, func: (qb: this) => UpdateQueryBuilder<any, any, any, O2>): O2 extends UpdateResult ? UpdateQueryBuilder<DB, UT, TB, UpdateResult> : O2 extends O & infer E ? UpdateQueryBuilder<DB, UT, TB, O & Partial<E>> : UpdateQueryBuilder<DB, UT, TB, Partial<O2>>;
@@ -930,27 +1099,41 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * Turn this code:
      *
      * ```ts
+     * import type { Person } from 'type-editor' // imaginary module
+     *
+     * const id = 1
+     * const now = new Date().toISOString()
+     *
      * const person = await db.updateTable('person')
-     *   .set({ deletedAt: now })
+     *   .set({ deleted_at: now })
      *   .where('id', '=', id)
      *   .where('nullable_column', 'is not', null)
      *   .returningAll()
      *   .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 id = 1
+     * const now = new Date().toISOString()
+     *
      * const person = await db.updateTable('person')
-     *   .set({ deletedAt: now })
+     *   .set({ deleted_at: now })
      *   .where('id', '=', id)
      *   .where('nullable_column', 'is not', null)
      *   .returningAll()
-     *   .$narrowType<{ deletedAt: Date; nullable_column: string }>()
+     *   .$narrowType<{ deleted_at: Date; nullable_column: NotNull }>()
      *   .executeTakeFirstOrThrow()
      *
      * functionThatExpectsPersonWithNonNullValue(person)
@@ -960,17 +1143,17 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
     /**
      * 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.
      *
@@ -980,6 +1163,17 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * ### Examples
      *
      * ```ts
+     * import type { PersonUpdate, PetUpdate, Species } from 'type-editor' // imaginary module
+     *
+     * const person = {
+     *   id: 1,
+     *   gender: 'other',
+     * } satisfies PersonUpdate
+     *
+     * const pet = {
+     *   name: 'Fluffy',
+     * } satisfies PetUpdate
+     *
      * const result = await db
      *   .with('updated_person', (qb) => qb
      *     .updateTable('person')
@@ -1036,7 +1230,7 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * ### Examples
      *
      * ```ts
-     * const stream = db.
+     * const stream = db
      *   .selectFrom('person')
      *   .select(['first_name', 'last_name'])
      *   .where('gender', '=', 'other')