kysely 0.24.1 → 0.25.0

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

@@ -6,7 +6,7 @@ import { SelectExpression, SelectArg } from '../parser/select-parser.js';
 import { ReturningAllRow, ReturningRow } from '../parser/returning-parser.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
 import { QueryNode } from '../operation-node/query-node.js';
-import { MergePartial, Nullable, SimplifyResult, SimplifySingleResult } from '../util/type-utils.js';
+import { DrainOuterGeneric, NarrowPartial, Nullable, ShallowRecord, SimplifyResult, SimplifySingleResult } from '../util/type-utils.js';
 import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
 import { QueryId } from '../util/query-id.js';
@@ -784,11 +784,11 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * }
      * ```
      */
-    $if<O2>(condition: boolean, func: (qb: this) => DeleteQueryBuilder<DB, TB, O2>): DeleteQueryBuilder<DB, TB, O2 extends DeleteResult ? DeleteResult : O extends DeleteResult ? Partial<O2> : MergePartial<O, O2>>;
+    $if<O2>(condition: boolean, func: (qb: this) => DeleteQueryBuilder<DB, TB, O2>): O2 extends DeleteResult ? DeleteQueryBuilder<DB, TB, DeleteResult> : O2 extends O & infer E ? DeleteQueryBuilder<DB, TB, O & Partial<E>> : DeleteQueryBuilder<DB, TB, Partial<O2>>;
     /**
      * @deprecated Use `$if` instead
      */
-    if<O2>(condition: boolean, func: (qb: this) => DeleteQueryBuilder<DB, TB, O2>): DeleteQueryBuilder<DB, TB, O2 extends DeleteResult ? DeleteResult : O extends DeleteResult ? Partial<O2> : MergePartial<O, O2>>;
+    if<O2>(condition: boolean, func: (qb: this) => DeleteQueryBuilder<DB, TB, O2>): O2 extends DeleteResult ? DeleteQueryBuilder<DB, TB, DeleteResult> : O2 extends O & infer E ? DeleteQueryBuilder<DB, TB, O & Partial<E>> : DeleteQueryBuilder<DB, TB, Partial<O2>>;
     /**
      * Change the output type of the query.
      *
@@ -800,6 +800,48 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * @deprecated Use `$castTo` instead.
      */
     castTo<T>(): DeleteQueryBuilder<DB, TB, T>;
+    /**
+     * Narrows (parts of) the output type of the query.
+     *
+     * Kysely tries to be as type-safe as possible, but in some cases we have to make
+     * compromises for better maintainability and compilation performance. At present,
+     * Kysely doesn't narrow the output type of the query when using {@link where} and {@link returning} or {@link returningAll}.
+     *
+     * This utility method is very useful for these situations, as it removes unncessary
+     * runtime assertion/guard code. Its input type is limited to the output type
+     * of the query, so you can't add a column that doesn't exist, or change a column's
+     * type to something that doesn't exist in its union type.
+     *
+     * ### Examples
+     *
+     * Turn this code:
+     *
+     * ```ts
+     * const person = await db.deleteFrom('person')
+     *   .where('id', '=', id)
+     *   .where('nullable_column', 'is not', null)
+     *   .returningAll()
+     *   .executeTakeFirstOrThrow()
+     *
+     * if (person.nullable_column) {
+     *   functionThatExpectsPersonWithNonNullValue(person)
+     * }
+     * ```
+     *
+     * Into this:
+     *
+     * ```ts
+     * const person = await db.deleteFrom('person')
+     *   .where('id', '=', id)
+     *   .where('nullable_column', 'is not', null)
+     *   .returningAll()
+     *   .$narrowType<{ nullable_column: string }>()
+     *   .executeTakeFirstOrThrow()
+     *
+     * functionThatExpectsPersonWithNonNullValue(person)
+     * ```
+     */
+    $narrowType<T>(): DeleteQueryBuilder<DB, TB, NarrowPartial<O, T>>;
     /**
      * Asserts that query's output row type equals the given type `T`.
      *
@@ -942,23 +984,23 @@ export interface DeleteQueryBuilderProps {
     readonly executor: QueryExecutor;
 }
 export declare type DeleteQueryBuilderWithInnerJoin<DB, TB extends keyof DB, O, TE extends TableExpression<DB, TB>> = TE extends `${infer T} as ${infer A}` ? T extends keyof DB ? InnerJoinedBuilder<DB, TB, O, A, DB[T]> : never : TE extends keyof DB ? DeleteQueryBuilder<DB, TB | TE, O> : TE extends AliasedExpression<infer QO, infer QA> ? InnerJoinedBuilder<DB, TB, O, QA, QO> : TE extends (qb: any) => AliasedExpression<infer QO, infer QA> ? InnerJoinedBuilder<DB, TB, O, QA, QO> : never;
-declare type InnerJoinedBuilder<DB, TB extends keyof DB, O, A extends string, R> = A extends keyof DB ? DeleteQueryBuilder<InnerJoinedDB<DB, A, R>, TB | A, O> : DeleteQueryBuilder<DB & Record<A, R>, TB | A, O>;
-declare type InnerJoinedDB<DB, A extends string, R> = {
+declare type InnerJoinedBuilder<DB, TB extends keyof DB, O, A extends string, R> = A extends keyof DB ? DeleteQueryBuilder<InnerJoinedDB<DB, A, R>, TB | A, O> : DeleteQueryBuilder<DB & ShallowRecord<A, R>, TB | A, O>;
+declare type InnerJoinedDB<DB, A extends string, R> = DrainOuterGeneric<{
     [C in keyof DB | A]: C extends A ? R : C extends keyof DB ? DB[C] : never;
-};
+}>;
 export declare type DeleteQueryBuilderWithLeftJoin<DB, TB extends keyof DB, O, TE extends TableExpression<DB, TB>> = TE extends `${infer T} as ${infer A}` ? T extends keyof DB ? LeftJoinedBuilder<DB, TB, O, A, DB[T]> : never : TE extends keyof DB ? LeftJoinedBuilder<DB, TB, O, TE, DB[TE]> : TE extends AliasedExpression<infer QO, infer QA> ? LeftJoinedBuilder<DB, TB, O, QA, QO> : TE extends (qb: any) => AliasedExpression<infer QO, infer QA> ? LeftJoinedBuilder<DB, TB, O, QA, QO> : never;
-declare type LeftJoinedBuilder<DB, TB extends keyof DB, O, A extends keyof any, R> = A extends keyof DB ? DeleteQueryBuilder<LeftJoinedDB<DB, A, R>, TB | A, O> : DeleteQueryBuilder<DB & Record<A, Nullable<R>>, TB | A, O>;
-declare type LeftJoinedDB<DB, A extends keyof any, R> = {
+declare type LeftJoinedBuilder<DB, TB extends keyof DB, O, A extends keyof any, R> = A extends keyof DB ? DeleteQueryBuilder<LeftJoinedDB<DB, A, R>, TB | A, O> : DeleteQueryBuilder<DB & ShallowRecord<A, Nullable<R>>, TB | A, O>;
+declare type LeftJoinedDB<DB, A extends keyof any, R> = DrainOuterGeneric<{
     [C in keyof DB | A]: C extends A ? Nullable<R> : C extends keyof DB ? DB[C] : never;
-};
+}>;
 export declare type DeleteQueryBuilderWithRightJoin<DB, TB extends keyof DB, O, TE extends TableExpression<DB, TB>> = TE extends `${infer T} as ${infer A}` ? T extends keyof DB ? RightJoinedBuilder<DB, TB, O, A, DB[T]> : never : TE extends keyof DB ? RightJoinedBuilder<DB, TB, O, TE, DB[TE]> : TE extends AliasedExpression<infer QO, infer QA> ? RightJoinedBuilder<DB, TB, O, QA, QO> : TE extends (qb: any) => AliasedExpression<infer QO, infer QA> ? RightJoinedBuilder<DB, TB, O, QA, QO> : never;
 declare type RightJoinedBuilder<DB, TB extends keyof DB, O, A extends keyof any, R> = DeleteQueryBuilder<RightJoinedDB<DB, TB, A, R>, TB | A, O>;
-declare type RightJoinedDB<DB, TB extends keyof DB, A extends keyof any, R> = {
+declare type RightJoinedDB<DB, TB extends keyof DB, A extends keyof any, R> = DrainOuterGeneric<{
     [C in keyof DB | A]: C extends A ? R : C extends TB ? Nullable<DB[C]> : C extends keyof DB ? DB[C] : never;
-};
+}>;
 export declare type DeleteQueryBuilderWithFullJoin<DB, TB extends keyof DB, O, TE extends TableExpression<DB, TB>> = TE extends `${infer T} as ${infer A}` ? T extends keyof DB ? OuterJoinedBuilder<DB, TB, O, A, DB[T]> : never : TE extends keyof DB ? OuterJoinedBuilder<DB, TB, O, TE, DB[TE]> : TE extends AliasedExpression<infer QO, infer QA> ? OuterJoinedBuilder<DB, TB, O, QA, QO> : TE extends (qb: any) => AliasedExpression<infer QO, infer QA> ? OuterJoinedBuilder<DB, TB, O, QA, QO> : never;
 declare type OuterJoinedBuilder<DB, TB extends keyof DB, O, A extends keyof any, R> = DeleteQueryBuilder<OuterJoinedBuilderDB<DB, TB, A, R>, TB | A, O>;
-declare type OuterJoinedBuilderDB<DB, TB extends keyof DB, A extends keyof any, R> = {
+declare type OuterJoinedBuilderDB<DB, TB extends keyof DB, A extends keyof any, R> = DrainOuterGeneric<{
     [C in keyof DB | A]: C extends A ? Nullable<R> : C extends TB ? Nullable<DB[C]> : C extends keyof DB ? DB[C] : never;
-};
+}>;
 export {};

package/dist/esm/query-builder/delete-query-builder.js

@@ -272,6 +272,50 @@ export class DeleteQueryBuilder {
     castTo() {
         return this.$castTo();
     }
+    /**
+     * Narrows (parts of) the output type of the query.
+     *
+     * Kysely tries to be as type-safe as possible, but in some cases we have to make
+     * compromises for better maintainability and compilation performance. At present,
+     * Kysely doesn't narrow the output type of the query when using {@link where} and {@link returning} or {@link returningAll}.
+     *
+     * This utility method is very useful for these situations, as it removes unncessary
+     * runtime assertion/guard code. Its input type is limited to the output type
+     * of the query, so you can't add a column that doesn't exist, or change a column's
+     * type to something that doesn't exist in its union type.
+     *
+     * ### Examples
+     *
+     * Turn this code:
+     *
+     * ```ts
+     * const person = await db.deleteFrom('person')
+     *   .where('id', '=', id)
+     *   .where('nullable_column', 'is not', null)
+     *   .returningAll()
+     *   .executeTakeFirstOrThrow()
+     *
+     * if (person.nullable_column) {
+     *   functionThatExpectsPersonWithNonNullValue(person)
+     * }
+     * ```
+     *
+     * Into this:
+     *
+     * ```ts
+     * const person = await db.deleteFrom('person')
+     *   .where('id', '=', id)
+     *   .where('nullable_column', 'is not', null)
+     *   .returningAll()
+     *   .$narrowType<{ nullable_column: string }>()
+     *   .executeTakeFirstOrThrow()
+     *
+     * functionThatExpectsPersonWithNonNullValue(person)
+     * ```
+     */
+    $narrowType() {
+        return new DeleteQueryBuilder(this.#props);
+    }
     /**
      * Asserts that query's output row type equals the given type `T`.
      *

package/dist/esm/query-builder/function-module.d.ts

@@ -2,7 +2,7 @@ import { DynamicReferenceBuilder } from '../dynamic/dynamic-reference-builder.js
 import { ExpressionWrapper } from '../expression/expression-wrapper.js';
 import { CoalesceReferenceExpressionList } from '../parser/coalesce-parser.js';
 import { ExtractTypeFromReferenceExpression, SimpleReferenceExpression, ReferenceExpression, StringReference } from '../parser/reference-parser.js';
-import { Equals, IsNever } from '../util/type-utils.js';
+import { Equals, IsAny } from '../util/type-utils.js';
 import { AggregateFunctionBuilder } from './aggregate-function-builder.js';
 /**
  * Helpers for type safe SQL function calls.
@@ -40,6 +40,8 @@ export interface FunctionModule<DB, TB extends keyof DB> {
     /**
      * Creates a function call.
      *
+     * To create an aggregate function call, use {@link FunctionModule.agg}.
+     *
      * ### Examples
      *
      * ```ts
@@ -65,6 +67,35 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * ```
      */
     <T>(name: string, args: ReadonlyArray<ReferenceExpression<DB, TB>>): ExpressionWrapper<T>;
+    /**
+     * Creates an aggregate function call.
+     *
+     * This is a specialized version of the `fn` method, that returns an {@link AggregateFunctionBuilder}
+     * instance. A builder that allows you to chain additional methods such as `distinct`,
+     * `filterWhere` and `over`.
+     *
+     * See {@link avg}, {@link count}, {@link countAll}, {@link max}, {@link min}, {@link sum}
+     * shortcuts of common aggregate functions.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .select(({ fn }) => [
+     *     fn.agg<number>('rank').over().as('rank'),
+     *     fn.agg<string>('group_concat', ['first_name']).distinct().as('first_names')
+     *   ])
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * select rank() over() as "rank",
+     *   group_concat(distinct "first_name") as "first_names"
+     * from "person"
+     * ```
+     */
+    agg<O>(name: string, args?: ReadonlyArray<ReferenceExpression<DB, TB>>): AggregateFunctionBuilder<DB, TB, O>;
     /**
      * Calls the `avg` function for the column given as the argument.
      *
@@ -377,7 +408,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      *   .execute()
      * ```
      */
-    max<O extends number | string | bigint | null = never, C extends StringReference<DB, TB> = StringReference<DB, TB>>(column: OutputBoundStringReference<DB, TB, C, O>): StringReferenceBoundAggregateFunctionBuilder<DB, TB, C, O>;
+    max<O extends number | string | bigint | null = any, C extends StringReference<DB, TB> = StringReference<DB, TB>>(column: OutputBoundStringReference<DB, TB, C, O>): StringReferenceBoundAggregateFunctionBuilder<DB, TB, C, O>;
     max<O extends number | string | bigint | null = number | string | bigint>(column: DynamicReferenceBuilder): AggregateFunctionBuilder<DB, TB, O>;
     /**
      * Calls the `min` function for the column given as the argument.
@@ -429,7 +460,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      *   .execute()
      * ```
      */
-    min<O extends number | string | bigint | null = never, C extends StringReference<DB, TB> = StringReference<DB, TB>>(column: OutputBoundStringReference<DB, TB, C, O>): StringReferenceBoundAggregateFunctionBuilder<DB, TB, C, O>;
+    min<O extends number | string | bigint | null = any, C extends StringReference<DB, TB> = StringReference<DB, TB>>(column: OutputBoundStringReference<DB, TB, C, O>): StringReferenceBoundAggregateFunctionBuilder<DB, TB, C, O>;
     min<O extends number | string | bigint | null = number | string | bigint>(column: DynamicReferenceBuilder): AggregateFunctionBuilder<DB, TB, O>;
     /**
      * Calls the `sum` function for the column given as the argument.
@@ -498,6 +529,6 @@ export interface FunctionModule<DB, TB extends keyof DB> {
     sum<O extends number | string | bigint | null = number | string | bigint, C extends SimpleReferenceExpression<DB, TB> = SimpleReferenceExpression<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
 }
 export declare function createFunctionModule<DB, TB extends keyof DB>(): FunctionModule<DB, TB>;
-declare type OutputBoundStringReference<DB, TB extends keyof DB, C extends StringReference<DB, TB>, O> = IsNever<O> extends true ? C : Equals<ExtractTypeFromReferenceExpression<DB, TB, C> | null, O | null> extends true ? C : never;
-declare type StringReferenceBoundAggregateFunctionBuilder<DB, TB extends keyof DB, C extends StringReference<DB, TB>, O> = AggregateFunctionBuilder<DB, TB, ExtractTypeFromReferenceExpression<DB, TB, C> | (null extends O ? null : never)>;
+declare type OutputBoundStringReference<DB, TB extends keyof DB, C extends StringReference<DB, TB>, O> = IsAny<O> extends true ? C : Equals<ExtractTypeFromReferenceExpression<DB, TB, C> | null, O | null> extends true ? C : never;
+declare type StringReferenceBoundAggregateFunctionBuilder<DB, TB extends keyof DB, C extends StringReference<DB, TB>, O> = AggregateFunctionBuilder<DB, TB, ExtractTypeFromReferenceExpression<DB, TB, C> | (IsAny<O> extends true ? never : null extends O ? null : never)>;
 export {};

package/dist/esm/query-builder/function-module.js

@@ -2,46 +2,42 @@
 import { ExpressionWrapper } from '../expression/expression-wrapper.js';
 import { AggregateFunctionNode } from '../operation-node/aggregate-function-node.js';
 import { FunctionNode } from '../operation-node/function-node.js';
-import { parseSimpleReferenceExpression, parseReferenceExpressionOrList, } from '../parser/reference-parser.js';
+import { parseReferenceExpressionOrList, } from '../parser/reference-parser.js';
 import { parseSelectAll } from '../parser/select-parser.js';
 import { AggregateFunctionBuilder } from './aggregate-function-builder.js';
 export function createFunctionModule() {
     const fn = (name, args) => {
         return new ExpressionWrapper(FunctionNode.create(name, parseReferenceExpressionOrList(args)));
     };
+    const agg = (name, args) => {
+        return new AggregateFunctionBuilder({
+            aggregateFunctionNode: AggregateFunctionNode.create(name, args ? parseReferenceExpressionOrList(args) : undefined),
+        });
+    };
     return Object.assign(fn, {
+        agg,
         avg(column) {
-            return new AggregateFunctionBuilder({
-                aggregateFunctionNode: AggregateFunctionNode.create('avg', parseSimpleReferenceExpression(column)),
-            });
+            return agg('avg', [column]);
         },
         coalesce(value, ...otherValues) {
             return fn('coalesce', [value, ...otherValues]);
         },
         count(column) {
-            return new AggregateFunctionBuilder({
-                aggregateFunctionNode: AggregateFunctionNode.create('count', parseSimpleReferenceExpression(column)),
-            });
+            return agg('count', [column]);
         },
         countAll(table) {
             return new AggregateFunctionBuilder({
-                aggregateFunctionNode: AggregateFunctionNode.create('count', parseSelectAll(table)[0]),
+                aggregateFunctionNode: AggregateFunctionNode.create('count', parseSelectAll(table)),
             });
         },
         max(column) {
-            return new AggregateFunctionBuilder({
-                aggregateFunctionNode: AggregateFunctionNode.create('max', parseSimpleReferenceExpression(column)),
-            });
+            return agg('max', [column]);
         },
         min(column) {
-            return new AggregateFunctionBuilder({
-                aggregateFunctionNode: AggregateFunctionNode.create('min', parseSimpleReferenceExpression(column)),
-            });
+            return agg('min', [column]);
         },
         sum(column) {
-            return new AggregateFunctionBuilder({
-                aggregateFunctionNode: AggregateFunctionNode.create('sum', parseSimpleReferenceExpression(column)),
-            });
+            return agg('sum', [column]);
         },
     });
 }

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

@@ -4,7 +4,7 @@ import { SelectExpression, SelectArg } from '../parser/select-parser.js';
 import { InsertObjectOrList, InsertObjectOrListFactory } from '../parser/insert-values-parser.js';
 import { InsertQueryNode } from '../operation-node/insert-query-node.js';
 import { QueryNode } from '../operation-node/query-node.js';
-import { MergePartial, SimplifyResult, SimplifySingleResult } from '../util/type-utils.js';
+import { NarrowPartial, SimplifyResult, SimplifySingleResult } from '../util/type-utils.js';
 import { UpdateExpression } from '../parser/update-set-parser.js';
 import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
@@ -516,11 +516,11 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * }
      * ```
      */
-    $if<O2>(condition: boolean, func: (qb: this) => InsertQueryBuilder<DB, TB, O2>): InsertQueryBuilder<DB, TB, O2 extends InsertResult ? InsertResult : O extends InsertResult ? Partial<O2> : MergePartial<O, O2>>;
+    $if<O2>(condition: boolean, func: (qb: this) => InsertQueryBuilder<DB, TB, O2>): O2 extends InsertResult ? InsertQueryBuilder<DB, TB, InsertResult> : O2 extends O & infer E ? InsertQueryBuilder<DB, TB, O & Partial<E>> : InsertQueryBuilder<DB, TB, Partial<O2>>;
     /**
      * @deprecated Use `$if` instead
      */
-    if<O2>(condition: boolean, func: (qb: this) => InsertQueryBuilder<DB, TB, O2>): InsertQueryBuilder<DB, TB, O2 extends InsertResult ? InsertResult : O extends InsertResult ? Partial<O2> : MergePartial<O, O2>>;
+    if<O2>(condition: boolean, func: (qb: this) => InsertQueryBuilder<DB, TB, O2>): O2 extends InsertResult ? InsertQueryBuilder<DB, TB, InsertResult> : O2 extends O & infer E ? InsertQueryBuilder<DB, TB, O & Partial<E>> : InsertQueryBuilder<DB, TB, Partial<O2>>;
     /**
      * Change the output type of the query.
      *
@@ -532,6 +532,47 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * @deprecated Use `$castTo` instead.
      */
     castTo<T>(): InsertQueryBuilder<DB, TB, T>;
+    /**
+     * Narrows (parts of) the output type of the query.
+     *
+     * Kysely tries to be as type-safe as possible, but in some cases we have to make
+     * compromises for better maintainability and compilation performance. At present,
+     * Kysely doesn't narrow the output type of the query based on {@link values} input
+     * when using {@link returning} or {@link returningAll}.
+     *
+     * This utility method is very useful for these situations, as it removes unncessary
+     * runtime assertion/guard code. Its input type is limited to the output type
+     * of the query, so you can't add a column that doesn't exist, or change a column's
+     * type to something that doesn't exist in its union type.
+     *
+     * ### Examples
+     *
+     * Turn this code:
+     *
+     * ```ts
+     * const person = await db.insertInto('person')
+     *   .values({ ...inputPerson, nullable_column: 'hell yeah!' })
+     *   .returningAll()
+     *   .executeTakeFirstOrThrow()
+     *
+     * if (nullable_column) {
+     *   functionThatExpectsPersonWithNonNullValue(person)
+     * }
+     * ```
+     *
+     * Into this:
+     *
+     * ```ts
+     * const person = await db.insertInto('person')
+     *   .values({ ...inputPerson, nullable_column: 'hell yeah!' })
+     *   .returningAll()
+     *   .$narrowType<{ nullable_column: string }>()
+     *   .executeTakeFirstOrThrow()
+     *
+     * functionThatExpectsPersonWithNonNullValue(person)
+     * ```
+     */
+    $narrowType<T>(): InsertQueryBuilder<DB, TB, NarrowPartial<O, T>>;
     /**
      * Asserts that query's output row type equals the given type `T`.
      *

package/dist/esm/query-builder/insert-query-builder.js

@@ -391,7 +391,12 @@ export class InsertQueryBuilder {
      * @deprecated Use `$if` instead
      */
     if(condition, func) {
-        return this.$if(condition, func);
+        if (condition) {
+            return func(this);
+        }
+        return new InsertQueryBuilder({
+            ...this.#props,
+        });
     }
     /**
      * Change the output type of the query.
@@ -408,6 +413,49 @@ export class InsertQueryBuilder {
     castTo() {
         return this.$castTo();
     }
+    /**
+     * Narrows (parts of) the output type of the query.
+     *
+     * Kysely tries to be as type-safe as possible, but in some cases we have to make
+     * compromises for better maintainability and compilation performance. At present,
+     * Kysely doesn't narrow the output type of the query based on {@link values} input
+     * when using {@link returning} or {@link returningAll}.
+     *
+     * This utility method is very useful for these situations, as it removes unncessary
+     * runtime assertion/guard code. Its input type is limited to the output type
+     * of the query, so you can't add a column that doesn't exist, or change a column's
+     * type to something that doesn't exist in its union type.
+     *
+     * ### Examples
+     *
+     * Turn this code:
+     *
+     * ```ts
+     * const person = await db.insertInto('person')
+     *   .values({ ...inputPerson, nullable_column: 'hell yeah!' })
+     *   .returningAll()
+     *   .executeTakeFirstOrThrow()
+     *
+     * if (nullable_column) {
+     *   functionThatExpectsPersonWithNonNullValue(person)
+     * }
+     * ```
+     *
+     * Into this:
+     *
+     * ```ts
+     * const person = await db.insertInto('person')
+     *   .values({ ...inputPerson, nullable_column: 'hell yeah!' })
+     *   .returningAll()
+     *   .$narrowType<{ nullable_column: string }>()
+     *   .executeTakeFirstOrThrow()
+     *
+     * functionThatExpectsPersonWithNonNullValue(person)
+     * ```
+     */
+    $narrowType() {
+        return new InsertQueryBuilder(this.#props);
+    }
     /**
      * Asserts that query's output row type equals the given type `T`.
      *

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

@@ -6,7 +6,7 @@ import { SelectExpression, Selection, SelectArg, AllSelection } from '../parser/
 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 { DrainOuterGeneric, NarrowPartial, Nullable, ShallowRecord, 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';
@@ -1397,11 +1397,11 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      *   )
      * ```
      */
-    $if<O2 extends O>(condition: boolean, func: (qb: this) => SelectQueryBuilder<DB, TB, O2>): SelectQueryBuilder<DB, TB, MergePartial<O, O2>>;
+    $if<O2>(condition: boolean, func: (qb: this) => SelectQueryBuilder<DB, TB, O & O2>): SelectQueryBuilder<DB, TB, O & Partial<O2>>;
     /**
      * @deprecated Use `$if` instead
      */
-    if<O2 extends O>(condition: boolean, func: (qb: this) => SelectQueryBuilder<DB, TB, O2>): SelectQueryBuilder<DB, TB, MergePartial<O, O2>>;
+    if<O2>(condition: boolean, func: (qb: this) => SelectQueryBuilder<DB, TB, O & O2>): SelectQueryBuilder<DB, TB, O & Partial<O2>>;
     /**
      * Change the output type of the query.
      *
@@ -1413,6 +1413,47 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * @deprecated Use `$castTo` instead.
      */
     castTo<T>(): SelectQueryBuilder<DB, TB, T>;
+    /**
+     * Narrows (parts of) the output type of the query.
+     *
+     * Kysely tries to be as type-safe as possible, but in some cases we have to make
+     * compromises for better maintainability and compilation performance. At present,
+     * Kysely doesn't narrow the output type of the query when using {@link where}, {@link having}
+     * or {@link JoinQueryBuilder.on}.
+     *
+     * This utility method is very useful for these situations, as it removes unncessary
+     * runtime assertion/guard code. Its input type is limited to the output type
+     * of the query, so you can't add a column that doesn't exist, or change a column's
+     * type to something that doesn't exist in its union type.
+     *
+     * ### Examples
+     *
+     * Turn this code:
+     *
+     * ```ts
+     * const person = await db.selectFrom('person')
+     *   .where('nullable_column', 'is not', null)
+     *   .selectAll()
+     *   .executeTakeFirstOrThrow()
+     *
+     * if (person.nullable_column) {
+     *   functionThatExpectsPersonWithNonNullValue(person)
+     * }
+     * ```
+     *
+     * Into this:
+     *
+     * ```ts
+     * const person = await db.selectFrom('person')
+     *   .where('nullable_column', 'is not', null)
+     *   .selectAll()
+     *   .$narrowType<{ nullable_column: string }>()
+     *   .executeTakeFirstOrThrow()
+     *
+     * functionThatExpectsPersonWithNonNullValue(person)
+     * ```
+     */
+    $narrowType<T>(): SelectQueryBuilder<DB, TB, NarrowPartial<O, T>>;
     /**
      * Asserts that query's output row type equals the given type `T`.
      *
@@ -1588,23 +1629,23 @@ export declare class AliasedSelectQueryBuilder<DB, TB extends keyof DB, O = unde
     toOperationNode(): AliasNode;
 }
 export declare type SelectQueryBuilderWithInnerJoin<DB, TB extends keyof DB, O, TE extends TableExpression<DB, TB>> = TE extends `${infer T} as ${infer A}` ? T extends keyof DB ? InnerJoinedBuilder<DB, TB, O, A, DB[T]> : never : TE extends keyof DB ? SelectQueryBuilder<DB, TB | TE, O> : TE extends AliasedExpression<infer QO, infer QA> ? InnerJoinedBuilder<DB, TB, O, QA, QO> : TE extends (qb: any) => AliasedExpression<infer QO, infer QA> ? InnerJoinedBuilder<DB, TB, O, QA, QO> : never;
-declare type InnerJoinedBuilder<DB, TB extends keyof DB, O, A extends string, R> = A extends keyof DB ? SelectQueryBuilder<InnerJoinedDB<DB, A, R>, TB | A, O> : SelectQueryBuilder<DB & Record<A, R>, TB | A, O>;
-declare type InnerJoinedDB<DB, A extends string, R> = {
+declare type InnerJoinedBuilder<DB, TB extends keyof DB, O, A extends string, R> = A extends keyof DB ? SelectQueryBuilder<InnerJoinedDB<DB, A, R>, TB | A, O> : SelectQueryBuilder<DB & ShallowRecord<A, R>, TB | A, O>;
+declare type InnerJoinedDB<DB, A extends string, R> = DrainOuterGeneric<{
     [C in keyof DB | A]: C extends A ? R : C extends keyof DB ? DB[C] : never;
-};
+}>;
 export declare type SelectQueryBuilderWithLeftJoin<DB, TB extends keyof DB, O, TE extends TableExpression<DB, TB>> = TE extends `${infer T} as ${infer A}` ? T extends keyof DB ? LeftJoinedBuilder<DB, TB, O, A, DB[T]> : never : TE extends keyof DB ? LeftJoinedBuilder<DB, TB, O, TE, DB[TE]> : TE extends AliasedExpression<infer QO, infer QA> ? LeftJoinedBuilder<DB, TB, O, QA, QO> : TE extends (qb: any) => AliasedExpression<infer QO, infer QA> ? LeftJoinedBuilder<DB, TB, O, QA, QO> : never;
-declare type LeftJoinedBuilder<DB, TB extends keyof DB, O, A extends keyof any, R> = A extends keyof DB ? SelectQueryBuilder<LeftJoinedDB<DB, A, R>, TB | A, O> : SelectQueryBuilder<DB & Record<A, Nullable<R>>, TB | A, O>;
-declare type LeftJoinedDB<DB, A extends keyof any, R> = {
+declare type LeftJoinedBuilder<DB, TB extends keyof DB, O, A extends keyof any, R> = A extends keyof DB ? SelectQueryBuilder<LeftJoinedDB<DB, A, R>, TB | A, O> : SelectQueryBuilder<DB & ShallowRecord<A, Nullable<R>>, TB | A, O>;
+declare type LeftJoinedDB<DB, A extends keyof any, R> = DrainOuterGeneric<{
     [C in keyof DB | A]: C extends A ? Nullable<R> : C extends keyof DB ? DB[C] : never;
-};
+}>;
 export declare type SelectQueryBuilderWithRightJoin<DB, TB extends keyof DB, O, TE extends TableExpression<DB, TB>> = TE extends `${infer T} as ${infer A}` ? T extends keyof DB ? RightJoinedBuilder<DB, TB, O, A, DB[T]> : never : TE extends keyof DB ? RightJoinedBuilder<DB, TB, O, TE, DB[TE]> : TE extends AliasedExpression<infer QO, infer QA> ? RightJoinedBuilder<DB, TB, O, QA, QO> : TE extends (qb: any) => AliasedExpression<infer QO, infer QA> ? RightJoinedBuilder<DB, TB, O, QA, QO> : never;
 declare type RightJoinedBuilder<DB, TB extends keyof DB, O, A extends keyof any, R> = SelectQueryBuilder<RightJoinedDB<DB, TB, A, R>, TB | A, O>;
-declare type RightJoinedDB<DB, TB extends keyof DB, A extends keyof any, R> = {
+declare type RightJoinedDB<DB, TB extends keyof DB, A extends keyof any, R> = DrainOuterGeneric<{
     [C in keyof DB | A]: C extends A ? R : C extends TB ? Nullable<DB[C]> : C extends keyof DB ? DB[C] : never;
-};
+}>;
 export declare type SelectQueryBuilderWithFullJoin<DB, TB extends keyof DB, O, TE extends TableExpression<DB, TB>> = TE extends `${infer T} as ${infer A}` ? T extends keyof DB ? OuterJoinedBuilder<DB, TB, O, A, DB[T]> : never : TE extends keyof DB ? OuterJoinedBuilder<DB, TB, O, TE, DB[TE]> : TE extends AliasedExpression<infer QO, infer QA> ? OuterJoinedBuilder<DB, TB, O, QA, QO> : TE extends (qb: any) => AliasedExpression<infer QO, infer QA> ? OuterJoinedBuilder<DB, TB, O, QA, QO> : never;
 declare type OuterJoinedBuilder<DB, TB extends keyof DB, O, A extends keyof any, R> = SelectQueryBuilder<OuterJoinedBuilderDB<DB, TB, A, R>, TB | A, O>;
-declare type OuterJoinedBuilderDB<DB, TB extends keyof DB, A extends keyof any, R> = {
+declare type OuterJoinedBuilderDB<DB, TB extends keyof DB, A extends keyof any, R> = DrainOuterGeneric<{
     [C in keyof DB | A]: C extends A ? Nullable<R> : C extends TB ? Nullable<DB[C]> : C extends keyof DB ? DB[C] : never;
-};
+}>;
 export {};

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

@@ -1127,6 +1127,49 @@ export class SelectQueryBuilder {
     castTo() {
         return this.$castTo();
     }
+    /**
+     * Narrows (parts of) the output type of the query.
+     *
+     * Kysely tries to be as type-safe as possible, but in some cases we have to make
+     * compromises for better maintainability and compilation performance. At present,
+     * Kysely doesn't narrow the output type of the query when using {@link where}, {@link having}
+     * or {@link JoinQueryBuilder.on}.
+     *
+     * This utility method is very useful for these situations, as it removes unncessary
+     * runtime assertion/guard code. Its input type is limited to the output type
+     * of the query, so you can't add a column that doesn't exist, or change a column's
+     * type to something that doesn't exist in its union type.
+     *
+     * ### Examples
+     *
+     * Turn this code:
+     *
+     * ```ts
+     * const person = await db.selectFrom('person')
+     *   .where('nullable_column', 'is not', null)
+     *   .selectAll()
+     *   .executeTakeFirstOrThrow()
+     *
+     * if (person.nullable_column) {
+     *   functionThatExpectsPersonWithNonNullValue(person)
+     * }
+     * ```
+     *
+     * Into this:
+     *
+     * ```ts
+     * const person = await db.selectFrom('person')
+     *   .where('nullable_column', 'is not', null)
+     *   .selectAll()
+     *   .$narrowType<{ nullable_column: string }>()
+     *   .executeTakeFirstOrThrow()
+     *
+     * functionThatExpectsPersonWithNonNullValue(person)
+     * ```
+     */
+    $narrowType() {
+        return new SelectQueryBuilder(this.#props);
+    }
     /**
      * Asserts that query's output row type equals the given type `T`.
      *