kysely 0.22.0 → 0.23.0

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

@@ -1,4 +1,8 @@
-import { StringReference, ExtractTypeFromReferenceExpression } from '../parser/reference-parser.js';
+import { DynamicReferenceBuilder } from '../dynamic/dynamic-reference-builder.js';
+import { CoalesceReferenceExpressionList } from '../parser/coalesce-parser.js';
+import { ExtractTypeFromReferenceExpression, SimpleReferenceExpression, ReferenceExpression, StringReference } from '../parser/reference-parser.js';
+import { RawBuilder } from '../raw-builder/raw-builder.js';
+import { Equals, IsNever } from '../util/type-utils.js';
 import { AggregateFunctionBuilder } from './aggregate-function-builder.js';
 /**
  * Helpers for type safe SQL function calls.
@@ -39,13 +43,13 @@ export declare class FunctionModule<DB, TB extends keyof DB> {
      *
      * If this is used in a `select` statement the type of the selected expression
      * will be `number | string` by default. This is because Kysely can't know the
-     * type the db driver outputs. Sometimes the output can be larger than the
-     * largest javascript number and a string is returned instead. Most drivers
-     * allow you to configure the output type of large numbers and Kysely can't
-     * know if you've done so.
+     * type the db driver outputs. Sometimes the output can be larger than the largest
+     * javascript number and a string is returned instead. Most drivers allow you
+     * to configure the output type of large numbers and Kysely can't know if you've
+     * done so.
      *
-     * You can specify the output type of the expression by providing
-     * the type as the first type argument:
+     * You can specify the output type of the expression by providing the type as
+     * the first type argument:
      *
      * ```ts
      * const { avg } = db.fn
@@ -54,17 +58,65 @@ export declare class FunctionModule<DB, TB extends keyof DB> {
      *   .select(avg<number>('price').as('avg_price'))
      *   .execute()
      * ```
+     *
+     * Sometimes a null is returned, e.g. when row count is 0, and no `group by`
+     * was used. It is highly recommended to include null in the output type union
+     * and handle null values in post-execute code, or wrap the function with a `coalesce`
+     * function.
+     *
+     * ```ts
+     * const { avg } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(avg<number | null>('price').as('avg_price'))
+     *   .execute()
+     * ```
+     */
+    avg<O extends number | string | null = number | string, C extends SimpleReferenceExpression<DB, TB> = SimpleReferenceExpression<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
+    /**
+     * Calls the `coalesce` function for given arguments.
+     *
+     * This function returns the first non-null value from left to right, commonly
+     * used to provide a default scalar for nullable columns or functions.
+     *
+     * ```ts
+     * const { coalesce, max } = db.fn
+     *
+     * db.selectFrom('person')
+     *   .select(coalesce(max('age'), sql<number>`0`).as('max_age'))
+     *   .where('first_name', '=', 'Jennifer')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (postgres):
+     *
+     * ```sql
+     * select coalesce(max("age"), 0) as "max_age" from "person" where "first_name" = $1
+     * ```
+     *
+     * If this is used in a `select` statement the type of the selected expression
+     * is inferred in the same manner that the function computes. A union of arguments'
+     * types - if a non-nullable argument exists, it stops there (ignoring any further
+     * arguments' types) and exludes null from the final union type.
+     *
+     * Examples:
+     *
+     * `(string | null, number | null)` is inferred as `string | number | null`.
+     *
+     * `(string | null, number, Date | null)` is inferred as `string | number`.
+     *
+     * `(number, string | null)` is inferred as `number`.
      */
-    avg<O extends number | string, C extends StringReference<DB, TB> = StringReference<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
+    coalesce<V extends ReferenceExpression<DB, TB>, OV extends ReferenceExpression<DB, TB>[]>(value: V, ...otherValues: OV): RawBuilder<CoalesceReferenceExpressionList<DB, TB, [V, ...OV]>>;
     /**
      * Calls the `count` function for the column given as the argument.
      *
      * If this is used in a `select` statement the type of the selected expression
-     * will be `number | string | bigint` by default. This is because Kysely can't
-     * know the type the db driver outputs. Sometimes the output can be larger than
-     * the largest javascript number and a string is returned instead. Most drivers
-     * allow you to configure the output type of large numbers and Kysely can't
-     * know if you've done so.
+     * will be `number | string | bigint` by default. This is because Kysely
+     * can't know the type the db driver outputs. Sometimes the output can be larger
+     * than the largest javascript number and a string is returned instead. Most
+     * drivers allow you to configure the output type of large numbers and Kysely
+     * can't know if you've done so.
      *
      * You can specify the output type of the expression by providing
      * the type as the first type argument:
@@ -85,10 +137,13 @@ export declare class FunctionModule<DB, TB extends keyof DB> {
      *   .execute()
      * ```
      */
-    count<O extends number | string | bigint, C extends StringReference<DB, TB> = StringReference<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
+    count<O extends number | string | bigint, C extends SimpleReferenceExpression<DB, TB> = SimpleReferenceExpression<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
     /**
      * Calls the `max` function for the column given as the argument.
      *
+     * If this is used in a `select` statement the type of the selected expression
+     * will be the referenced column's type.
+     *
      * ### Examples
      *
      * ```ts
@@ -98,11 +153,28 @@ export declare class FunctionModule<DB, TB extends keyof DB> {
      *   .select(max('price').as('max_price'))
      *   .execute()
      * ```
+     *
+     * Sometimes a null is returned, e.g. when row count is 0, and no `group by`
+     * was used. It is highly recommended to include null in the output type union
+     * and handle null values in post-execute code, or wrap the function with a `coalesce`
+     * function.
+     *
+     * ```ts
+     * const { max } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(max<number | null, 'price'>('price').as('max_price'))
+     *   .execute()
+     * ```
      */
-    max<C extends StringReference<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, ExtractTypeFromReferenceExpression<DB, TB, C>>;
+    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 = number | string | bigint>(column: DynamicReferenceBuilder): AggregateFunctionBuilder<DB, TB, O>;
     /**
      * Calls the `min` function for the column given as the argument.
      *
+     * If this is used in a `select` statement the type of the selected expression
+     * will be the referenced column's type.
+     *
      * ### Examples
      *
      * ```ts
@@ -113,17 +185,30 @@ export declare class FunctionModule<DB, TB extends keyof DB> {
      *   .execute()
      * ```
      *
+     * Sometimes a null is returned, e.g. when row count is 0, and no `group by`
+     * was used. It is highly recommended to include null in the output type union
+     * and handle null values in post-execute code, or wrap the function with a `coalesce`
+     * function.
+     *
+     * ```ts
+     * const { min } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(min<number | null, 'price'>('price').as('min_price'))
+     *   .execute()
+     * ```
      */
-    min<C extends StringReference<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, ExtractTypeFromReferenceExpression<DB, TB, C>>;
+    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 = number | string | bigint>(column: DynamicReferenceBuilder): AggregateFunctionBuilder<DB, TB, O>;
     /**
      * Calls the `sum` function for the column given as the argument.
      *
      * If this is used in a `select` statement the type of the selected expression
-     * will be `number | string | bigint` by default. This is because Kysely can't
-     * know the type the db driver outputs. Sometimes the output can be larger than
-     * the largest javascript number and a string is returned instead. Most drivers
-     * allow you to configure the output type of large numbers and Kysely can't
-     * know if you've done so.
+     * will be `number | string | bigint` by default. This is because Kysely
+     * can't know the type the db driver outputs. Sometimes the output can be larger
+     * than the largest javascript number and a string is returned instead. Most
+     * drivers allow you to configure the output type of large numbers and Kysely
+     * can't know if you've done so.
      *
      * You can specify the output type of the expression by providing
      * the type as the first type argument:
@@ -135,6 +220,22 @@ export declare class FunctionModule<DB, TB extends keyof DB> {
      *   .select(sum<number>('price').as('total_price'))
      *   .execute()
      * ```
+     *
+     * Sometimes a null is returned, e.g. when row count is 0, and no `group by`
+     * was used. It is highly recommended to include null in the output type union
+     * and handle null values in post-execute code, or wrap the function with a `coalesce`
+     * function.
+     *
+     * ```ts
+     * const { sum } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(sum<number | null>('price').as('total_price'))
+     *   .execute()
+     * ```
      */
-    sum<O extends number | string | bigint, C extends StringReference<DB, TB> = StringReference<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
+    sum<O extends number | string | bigint | null = number | string | bigint, C extends SimpleReferenceExpression<DB, TB> = SimpleReferenceExpression<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
 }
+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)>;
+export {};

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

@@ -1,6 +1,9 @@
 /// <reference types="./function-module.d.ts" />
 import { AggregateFunctionNode } from '../operation-node/aggregate-function-node.js';
-import { parseStringReference, } from '../parser/reference-parser.js';
+import { parseCoalesce, } from '../parser/coalesce-parser.js';
+import { parseSimpleReferenceExpression, } from '../parser/reference-parser.js';
+import { RawBuilder } from '../raw-builder/raw-builder.js';
+import { createQueryId } from '../util/query-id.js';
 import { AggregateFunctionBuilder } from './aggregate-function-builder.js';
 /**
  * Helpers for type safe SQL function calls.
@@ -37,6 +40,7 @@ import { AggregateFunctionBuilder } from './aggregate-function-builder.js';
 export class FunctionModule {
     constructor() {
         this.avg = this.avg.bind(this);
+        this.coalesce = this.coalesce.bind(this);
         this.count = this.count.bind(this);
         this.max = this.max.bind(this);
         this.min = this.min.bind(this);
@@ -47,13 +51,13 @@ export class FunctionModule {
      *
      * If this is used in a `select` statement the type of the selected expression
      * will be `number | string` by default. This is because Kysely can't know the
-     * type the db driver outputs. Sometimes the output can be larger than the
-     * largest javascript number and a string is returned instead. Most drivers
-     * allow you to configure the output type of large numbers and Kysely can't
-     * know if you've done so.
+     * type the db driver outputs. Sometimes the output can be larger than the largest
+     * javascript number and a string is returned instead. Most drivers allow you
+     * to configure the output type of large numbers and Kysely can't know if you've
+     * done so.
      *
-     * You can specify the output type of the expression by providing
-     * the type as the first type argument:
+     * You can specify the output type of the expression by providing the type as
+     * the first type argument:
      *
      * ```ts
      * const { avg } = db.fn
@@ -62,21 +66,74 @@ export class FunctionModule {
      *   .select(avg<number>('price').as('avg_price'))
      *   .execute()
      * ```
+     *
+     * Sometimes a null is returned, e.g. when row count is 0, and no `group by`
+     * was used. It is highly recommended to include null in the output type union
+     * and handle null values in post-execute code, or wrap the function with a `coalesce`
+     * function.
+     *
+     * ```ts
+     * const { avg } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(avg<number | null>('price').as('avg_price'))
+     *   .execute()
+     * ```
      */
     avg(column) {
         return new AggregateFunctionBuilder({
-            aggregateFunctionNode: AggregateFunctionNode.create('avg', parseStringReference(column)),
+            aggregateFunctionNode: AggregateFunctionNode.create('avg', parseSimpleReferenceExpression(column)),
+        });
+    }
+    /**
+     * Calls the `coalesce` function for given arguments.
+     *
+     * This function returns the first non-null value from left to right, commonly
+     * used to provide a default scalar for nullable columns or functions.
+     *
+     * ```ts
+     * const { coalesce, max } = db.fn
+     *
+     * db.selectFrom('person')
+     *   .select(coalesce(max('age'), sql<number>`0`).as('max_age'))
+     *   .where('first_name', '=', 'Jennifer')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (postgres):
+     *
+     * ```sql
+     * select coalesce(max("age"), 0) as "max_age" from "person" where "first_name" = $1
+     * ```
+     *
+     * If this is used in a `select` statement the type of the selected expression
+     * is inferred in the same manner that the function computes. A union of arguments'
+     * types - if a non-nullable argument exists, it stops there (ignoring any further
+     * arguments' types) and exludes null from the final union type.
+     *
+     * Examples:
+     *
+     * `(string | null, number | null)` is inferred as `string | number | null`.
+     *
+     * `(string | null, number, Date | null)` is inferred as `string | number`.
+     *
+     * `(number, string | null)` is inferred as `number`.
+     */
+    coalesce(value, ...otherValues) {
+        return new RawBuilder({
+            queryId: createQueryId(),
+            rawNode: parseCoalesce([value, ...otherValues]),
         });
     }
     /**
      * Calls the `count` function for the column given as the argument.
      *
      * If this is used in a `select` statement the type of the selected expression
-     * will be `number | string | bigint` by default. This is because Kysely can't
-     * know the type the db driver outputs. Sometimes the output can be larger than
-     * the largest javascript number and a string is returned instead. Most drivers
-     * allow you to configure the output type of large numbers and Kysely can't
-     * know if you've done so.
+     * will be `number | string | bigint` by default. This is because Kysely
+     * can't know the type the db driver outputs. Sometimes the output can be larger
+     * than the largest javascript number and a string is returned instead. Most
+     * drivers allow you to configure the output type of large numbers and Kysely
+     * can't know if you've done so.
      *
      * You can specify the output type of the expression by providing
      * the type as the first type argument:
@@ -99,55 +156,28 @@ export class FunctionModule {
      */
     count(column) {
         return new AggregateFunctionBuilder({
-            aggregateFunctionNode: AggregateFunctionNode.create('count', parseStringReference(column)),
+            aggregateFunctionNode: AggregateFunctionNode.create('count', parseSimpleReferenceExpression(column)),
         });
     }
-    /**
-     * Calls the `max` function for the column given as the argument.
-     *
-     * ### Examples
-     *
-     * ```ts
-     * const { max } = db.fn
-     *
-     * db.selectFrom('toy')
-     *   .select(max('price').as('max_price'))
-     *   .execute()
-     * ```
-     */
     max(column) {
         return new AggregateFunctionBuilder({
-            aggregateFunctionNode: AggregateFunctionNode.create('max', parseStringReference(column)),
+            aggregateFunctionNode: AggregateFunctionNode.create('max', parseSimpleReferenceExpression(column)),
         });
     }
-    /**
-     * Calls the `min` function for the column given as the argument.
-     *
-     * ### Examples
-     *
-     * ```ts
-     * const { min } = db.fn
-     *
-     * db.selectFrom('toy')
-     *   .select(min('price').as('min_price'))
-     *   .execute()
-     * ```
-     *
-     */
     min(column) {
         return new AggregateFunctionBuilder({
-            aggregateFunctionNode: AggregateFunctionNode.create('min', parseStringReference(column)),
+            aggregateFunctionNode: AggregateFunctionNode.create('min', parseSimpleReferenceExpression(column)),
         });
     }
     /**
      * Calls the `sum` function for the column given as the argument.
      *
      * If this is used in a `select` statement the type of the selected expression
-     * will be `number | string | bigint` by default. This is because Kysely can't
-     * know the type the db driver outputs. Sometimes the output can be larger than
-     * the largest javascript number and a string is returned instead. Most drivers
-     * allow you to configure the output type of large numbers and Kysely can't
-     * know if you've done so.
+     * will be `number | string | bigint` by default. This is because Kysely
+     * can't know the type the db driver outputs. Sometimes the output can be larger
+     * than the largest javascript number and a string is returned instead. Most
+     * drivers allow you to configure the output type of large numbers and Kysely
+     * can't know if you've done so.
      *
      * You can specify the output type of the expression by providing
      * the type as the first type argument:
@@ -159,10 +189,23 @@ export class FunctionModule {
      *   .select(sum<number>('price').as('total_price'))
      *   .execute()
      * ```
+     *
+     * Sometimes a null is returned, e.g. when row count is 0, and no `group by`
+     * was used. It is highly recommended to include null in the output type union
+     * and handle null values in post-execute code, or wrap the function with a `coalesce`
+     * function.
+     *
+     * ```ts
+     * const { sum } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(sum<number | null>('price').as('total_price'))
+     *   .execute()
+     * ```
      */
     sum(column) {
         return new AggregateFunctionBuilder({
-            aggregateFunctionNode: AggregateFunctionNode.create('sum', parseStringReference(column)),
+            aggregateFunctionNode: AggregateFunctionNode.create('sum', parseSimpleReferenceExpression(column)),
         });
     }
 }

package/dist/esm/query-builder/having-interface.d.ts

@@ -1,31 +1,32 @@
-import { ExistsExpression, FilterOperator, FilterValueExpressionOrList, HavingGrouper } from '../parser/filter-parser.js';
+import { Expression } from '../expression/expression.js';
+import { ComparisonOperatorExpression, HavingGrouper, OperandValueExpressionOrList } from '../parser/binary-operation-parser.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
-import { AnyRawBuilder } from '../util/type-utils.js';
+import { ExistsExpression } from '../parser/unary-operation-parser.js';
 export interface HavingInterface<DB, TB extends keyof DB> {
     /**
      * Just like {@link WhereInterface.where | where} but adds a `having` statement
      * instead of a `where` statement.
      */
-    having<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: FilterOperator, rhs: FilterValueExpressionOrList<DB, TB, RE>): HavingInterface<DB, TB>;
+    having<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): HavingInterface<DB, TB>;
     having(grouper: HavingGrouper<DB, TB>): HavingInterface<DB, TB>;
-    having(raw: AnyRawBuilder): HavingInterface<DB, TB>;
+    having(expression: Expression<any>): HavingInterface<DB, TB>;
     /**
      * Just like {@link WhereInterface.whereRef | whereRef} but adds a `having` statement
      * instead of a `where` statement.
      */
-    havingRef(lhs: ReferenceExpression<DB, TB>, op: FilterOperator, rhs: ReferenceExpression<DB, TB>): HavingInterface<DB, TB>;
+    havingRef(lhs: ReferenceExpression<DB, TB>, op: ComparisonOperatorExpression, rhs: ReferenceExpression<DB, TB>): HavingInterface<DB, TB>;
     /**
      * Just like {@link WhereInterface.orWhere | orWhere} but adds a `having` statement
      * instead of a `where` statement.
      */
-    orHaving<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: FilterOperator, rhs: FilterValueExpressionOrList<DB, TB, RE>): HavingInterface<DB, TB>;
+    orHaving<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): HavingInterface<DB, TB>;
     orHaving(grouper: HavingGrouper<DB, TB>): HavingInterface<DB, TB>;
-    orHaving(raw: AnyRawBuilder): HavingInterface<DB, TB>;
+    orHaving(expression: Expression<any>): HavingInterface<DB, TB>;
     /**
      * Just like {@link WhereInterface.orWhereRef | orWhereRef} but adds a `having` statement
      * instead of a `where` statement.
      */
-    orHavingRef(lhs: ReferenceExpression<DB, TB>, op: FilterOperator, rhs: ReferenceExpression<DB, TB>): HavingInterface<DB, TB>;
+    orHavingRef(lhs: ReferenceExpression<DB, TB>, op: ComparisonOperatorExpression, rhs: ReferenceExpression<DB, TB>): HavingInterface<DB, TB>;
     /**
      * Just like {@link WhereInterface.whereExists | whereExists} but adds a `having` statement
      * instead of a `where` statement.

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

@@ -3,7 +3,7 @@ import { CompiledQuery } from '../query-compiler/compiled-query.js';
 import { SelectExpression } from '../parser/select-parser.js';
 import { InsertObject } from '../parser/insert-values-parser.js';
 import { InsertQueryNode } from '../operation-node/insert-query-node.js';
-import { AnyRawBuilder, MergePartial, SingleResultType } from '../util/type-utils.js';
+import { MergePartial, SingleResultType } from '../util/type-utils.js';
 import { MutationObject } from '../parser/update-set-parser.js';
 import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
@@ -12,12 +12,13 @@ import { InsertResult } from './insert-result.js';
 import { KyselyPlugin } from '../plugin/kysely-plugin.js';
 import { ReturningRow } from '../parser/returning-parser.js';
 import { NoResultErrorConstructor } from './no-result-error.js';
-import { ComplexExpression } from '../parser/complex-expression-parser.js';
+import { ExpressionOrFactory } from '../parser/expression-parser.js';
 import { ReturningInterface } from './returning-interface.js';
 import { OnConflictBuilder, OnConflictDoNothingBuilder, OnConflictUpdateBuilder } from './on-conflict-builder.js';
 import { Selectable } from '../util/column-type.js';
 import { Explainable, ExplainFormat } from '../util/explainable.js';
-export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements ReturningInterface<DB, TB, O>, OperationNodeSource, Compilable, Explainable {
+import { Expression } from '../expression/expression.js';
+export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements ReturningInterface<DB, TB, O>, OperationNodeSource, Compilable<O>, Explainable {
     #private;
     constructor(props: InsertQueryBuilderProps);
     /**
@@ -189,7 +190,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * select "pet"."name" from "pet"
      * ```
      */
-    expression(expression: ComplexExpression<DB, TB>): InsertQueryBuilder<DB, TB, O>;
+    expression(expression: ExpressionOrFactory<DB, TB, any>): InsertQueryBuilder<DB, TB, O>;
     /**
      * Changes an `insert into` query to an `insert ignore into` query.
      *
@@ -521,7 +522,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      */
     withPlugin(plugin: KyselyPlugin): InsertQueryBuilder<DB, TB, O>;
     toOperationNode(): InsertQueryNode;
-    compile(): CompiledQuery;
+    compile(): CompiledQuery<O>;
     /**
      * Executes the query and returns an array of rows.
      *
@@ -558,7 +559,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * explain format=json insert into `person` (`id`, `first_name`, `last_name`) values (?, ?, ?) (?, ?, ?)
      * ```
      */
-    explain<ER extends Record<string, any> = Record<string, any>>(format?: ExplainFormat, options?: AnyRawBuilder): Promise<ER[]>;
+    explain<ER extends Record<string, any> = Record<string, any>>(format?: ExplainFormat, options?: Expression<any>): Promise<ER[]>;
 }
 export interface InsertQueryBuilderProps {
     readonly queryId: QueryId;

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

@@ -9,7 +9,7 @@ import { freeze } from '../util/object-utils.js';
 import { OnDuplicateKeyNode } from '../operation-node/on-duplicate-key-node.js';
 import { InsertResult } from './insert-result.js';
 import { NoResultError } from './no-result-error.js';
-import { parseComplexExpression, } from '../parser/complex-expression-parser.js';
+import { parseExpression, } from '../parser/expression-parser.js';
 import { ColumnNode } from '../operation-node/column-node.js';
 import { OnConflictBuilder, } from './on-conflict-builder.js';
 import { OnConflictNode } from '../operation-node/on-conflict-node.js';
@@ -81,7 +81,7 @@ export class InsertQueryBuilder {
         return new InsertQueryBuilder({
             ...this.#props,
             queryNode: InsertQueryNode.cloneWith(this.#props.queryNode, {
-                values: parseComplexExpression(expression),
+                values: parseExpression(expression),
             }),
         });
     }
@@ -412,15 +412,17 @@ export class InsertQueryBuilder {
      * Also see the {@link executeTakeFirst} and {@link executeTakeFirstOrThrow} methods.
      */
     async execute() {
-        const compildQuery = this.compile();
-        const query = compildQuery.query;
-        const result = await this.#props.executor.executeQuery(compildQuery, this.#props.queryId);
+        const compiledQuery = this.compile();
+        const query = compiledQuery.query;
+        const result = await this.#props.executor.executeQuery(compiledQuery, this.#props.queryId);
         if (this.#props.executor.adapter.supportsReturning && query.returning) {
             return result.rows;
         }
-        else {
-            return [new InsertResult(result.insertId)];
-        }
+        return [
+            new InsertResult(result.insertId, 
+            // TODO: remove numUpdatedOrDeletedRows.
+            result.numAffectedRows ?? result.numUpdatedOrDeletedRows),
+        ];
     }
     /**
      * Executes the query and returns the first result or undefined if
@@ -465,7 +467,7 @@ export class InsertQueryBuilder {
         const builder = new InsertQueryBuilder({
             ...this.#props,
             queryNode: InsertQueryNode.cloneWith(this.#props.queryNode, {
-                explain: ExplainNode.create(format, options),
+                explain: ExplainNode.create(format, options?.toOperationNode()),
             }),
         });
         return await builder.execute();

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

@@ -7,6 +7,9 @@
  * need to use {@link ReturningInterface.returning} or {@link ReturningInterface.returningAll}
  * to get out the inserted id.
  *
+ * {@link numInsertedOrUpdatedRows} holds the number of (actually) inserted rows.
+ * On MySQL, updated rows are counted twice when using `on duplicate key update`.
+ *
  * ### Examples
  *
  * ```ts
@@ -20,9 +23,13 @@
  */
 export declare class InsertResult {
     #private;
-    constructor(insertId: bigint | undefined);
+    constructor(insertId: bigint | undefined, numInsertedOrUpdatedRows: bigint | undefined);
     /**
      * The auto incrementing primary key
      */
     get insertId(): bigint | undefined;
+    /**
+     * Affected rows count.
+     */
+    get numInsertedOrUpdatedRows(): bigint | undefined;
 }

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

@@ -8,6 +8,9 @@
  * need to use {@link ReturningInterface.returning} or {@link ReturningInterface.returningAll}
  * to get out the inserted id.
  *
+ * {@link numInsertedOrUpdatedRows} holds the number of (actually) inserted rows.
+ * On MySQL, updated rows are counted twice when using `on duplicate key update`.
+ *
  * ### Examples
  *
  * ```ts
@@ -21,8 +24,10 @@
  */
 export class InsertResult {
     #insertId;
-    constructor(insertId) {
+    #numInsertedOrUpdatedRows;
+    constructor(insertId, numInsertedOrUpdatedRows) {
         this.#insertId = insertId;
+        this.#numInsertedOrUpdatedRows = numInsertedOrUpdatedRows;
     }
     /**
      * The auto incrementing primary key
@@ -30,4 +35,10 @@ export class InsertResult {
     get insertId() {
         return this.#insertId;
     }
+    /**
+     * Affected rows count.
+     */
+    get numInsertedOrUpdatedRows() {
+        return this.#numInsertedOrUpdatedRows;
+    }
 }