kysely 0.26.2 → 0.27.0

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

@@ -1,12 +1,12 @@
-import { DynamicReferenceBuilder } from '../dynamic/dynamic-reference-builder.js';
 import { ExpressionWrapper } from '../expression/expression-wrapper.js';
 import { Expression } from '../expression/expression.js';
-import { CoalesceReferenceExpressionList } from '../parser/coalesce-parser.js';
+import { ExtractTypeFromCoalesce1, ExtractTypeFromCoalesce3, ExtractTypeFromCoalesce2, ExtractTypeFromCoalesce4, ExtractTypeFromCoalesce5 } from '../parser/coalesce-parser.js';
 import { ExtractTypeFromReferenceExpression, ReferenceExpression, StringReference, ExtractTypeFromStringReference } from '../parser/reference-parser.js';
 import { KyselyTypeError } from '../util/type-error.js';
-import { Equals, IsAny } from '../util/type-utils.js';
+import { IsNever } from '../util/type-utils.js';
 import { AggregateFunctionBuilder } from './aggregate-function-builder.js';
-import { SelectQueryBuilder } from './select-query-builder.js';
+import { SelectQueryBuilderExpression } from '../query-builder/select-query-builder-expression.js';
+import { Selectable } from '../util/column-type.js';
 /**
  * Helpers for type safe SQL function calls.
  *
@@ -17,21 +17,47 @@ import { SelectQueryBuilder } from './select-query-builder.js';
  *
  * <!-- siteExample("select", "Function calls", 60) -->
  *
- * This example uses the `fn` module to select some aggregates:
+ * This example shows how to create function calls. These examples also work in any
+ * other place (`where` calls, updates, inserts etc.). The only difference is that you
+ * leave out the alias (the `as` call) if you use these in any other place than `select`.
  *
  * ```ts
+ * import { sql } from 'kysely'
+ *
  * const result = await db.selectFrom('person')
  *   .innerJoin('pet', 'pet.owner_id', 'person.id')
- *   .select(({ fn }) => [
+ *   .select(({ fn, val, ref }) => [
  *     'person.id',
  *
  *     // The `fn` module contains the most common
  *     // functions.
  *     fn.count<number>('pet.id').as('pet_count'),
  *
- *     // You can call any function using the
- *     // `agg` method
- *     fn.agg<string[]>('array_agg', ['pet.name']).as('pet_names')
+ *     // You can call any function by calling `fn`
+ *     // directly. The arguments are treated as column
+ *     // references by default. If you want  to pass in
+ *     // values, use the `val` function.
+ *     fn<string>('concat', [
+ *       val('Ms. '),
+ *       'first_name',
+ *       val(' '),
+ *       'last_name'
+ *     ]).as('full_name_with_title'),
+ *
+ *     // You can call any aggregate function using the
+ *     // `fn.agg` function.
+ *     fn.agg<string[]>('array_agg', ['pet.name']).as('pet_names'),
+ *
+ *     // And once again, you can use the `sql`
+ *     // template tag. The template tag substitutions
+ *     // are treated as values by default. If you want
+ *     // to reference columns, you can use the `ref`
+ *     // function.
+ *     sql<string>`concat(
+ *       ${ref('first_name')},
+ *       ' ',
+ *       ${ref('last_name')}
+ *     )`.as('full_name')
  *   ])
  *   .groupBy('person.id')
  *   .having((eb) => eb.fn.count('pet.id'), '>', 10)
@@ -44,11 +70,13 @@ import { SelectQueryBuilder } from './select-query-builder.js';
  * select
  *   "person"."id",
  *   count("pet"."id") as "pet_count",
- *   array_agg("pet"."name") as "pet_names"
+ *   concat($1, "first_name", $2, "last_name") as "full_name_with_title",
+ *   array_agg("pet"."name") as "pet_names",
+ *   concat("first_name", ' ', "last_name") as "full_name"
  * from "person"
  * inner join "pet" on "pet"."owner_id" = "person"."id"
  * group by "person"."id"
- * having count("pet"."id") > $1
+ * having count("pet"."id") > $3
  * ```
  */
 export interface FunctionModule<DB, TB extends keyof DB> {
@@ -81,7 +109,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      *   .where(sql`upper(first_name)`, '=', 'JENNIFER')
      * ```
      */
-    <T>(name: string, args: ReadonlyArray<ReferenceExpression<DB, TB>>): ExpressionWrapper<DB, TB, T>;
+    <O, RE extends ReferenceExpression<DB, TB> = ReferenceExpression<DB, TB>>(name: string, args?: ReadonlyArray<RE>): ExpressionWrapper<DB, TB, O>;
     /**
      * Creates an aggregate function call.
      *
@@ -110,7 +138,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * from "person"
      * ```
      */
-    agg<O>(name: string, args?: ReadonlyArray<ReferenceExpression<DB, TB>>): AggregateFunctionBuilder<DB, TB, O>;
+    agg<O, RE extends ReferenceExpression<DB, TB>>(name: string, args?: ReadonlyArray<RE>): AggregateFunctionBuilder<DB, TB, O>;
     /**
      * Calls the `avg` function for the column or expression given as the argument.
      *
@@ -169,7 +197,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      *   .execute()
      * ```
      */
-    avg<O extends number | string | null = number | string, C extends ReferenceExpression<DB, TB> = ReferenceExpression<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
+    avg<O extends number | string | null = number | string, RE extends ReferenceExpression<DB, TB> = ReferenceExpression<DB, TB>>(expr: RE): AggregateFunctionBuilder<DB, TB, O>;
     /**
      * Calls the `coalesce` function for given arguments.
      *
@@ -230,7 +258,11 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * select coalesce(avg("age"), 0) as "avg_age" from "person" where "first_name" = $1
      * ```
      */
-    coalesce<V extends ReferenceExpression<DB, TB>, OV extends ReferenceExpression<DB, TB>[]>(value: V, ...otherValues: OV): ExpressionWrapper<DB, TB, CoalesceReferenceExpressionList<DB, TB, [V, ...OV]>>;
+    coalesce<V1 extends ReferenceExpression<DB, TB>>(v1: V1): ExpressionWrapper<DB, TB, ExtractTypeFromCoalesce1<DB, TB, V1>>;
+    coalesce<V1 extends ReferenceExpression<DB, TB>, V2 extends ReferenceExpression<DB, TB>>(v1: V1, v2: V2): ExpressionWrapper<DB, TB, ExtractTypeFromCoalesce2<DB, TB, V1, V2>>;
+    coalesce<V1 extends ReferenceExpression<DB, TB>, V2 extends ReferenceExpression<DB, TB>, V3 extends ReferenceExpression<DB, TB>>(v1: V1, v2: V2, v3: V3): ExpressionWrapper<DB, TB, ExtractTypeFromCoalesce3<DB, TB, V1, V2, V3>>;
+    coalesce<V1 extends ReferenceExpression<DB, TB>, V2 extends ReferenceExpression<DB, TB>, V3 extends ReferenceExpression<DB, TB>, V4 extends ReferenceExpression<DB, TB>>(v1: V1, v2: V2, v3: V3, v4: V4): ExpressionWrapper<DB, TB, ExtractTypeFromCoalesce4<DB, TB, V1, V2, V3, V4>>;
+    coalesce<V1 extends ReferenceExpression<DB, TB>, V2 extends ReferenceExpression<DB, TB>, V3 extends ReferenceExpression<DB, TB>, V4 extends ReferenceExpression<DB, TB>, V5 extends ReferenceExpression<DB, TB>>(v1: V1, v2: V2, v3: V3, v4: V4, v5: V5): ExpressionWrapper<DB, TB, ExtractTypeFromCoalesce5<DB, TB, V1, V2, V3, V4, V5>>;
     /**
      * Calls the `count` function for the column or expression given as the argument.
      *
@@ -281,7 +313,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      *   .execute()
      * ```
      */
-    count<O extends number | string | bigint, C extends ReferenceExpression<DB, TB> = ReferenceExpression<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
+    count<O extends number | string | bigint, RE extends ReferenceExpression<DB, TB> = ReferenceExpression<DB, TB>>(expr: RE): AggregateFunctionBuilder<DB, TB, O>;
     /**
      * Calls the `count` function with `*` or `table.*` as argument.
      *
@@ -395,12 +427,11 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      *
      * ```ts
      * db.selectFrom('toy')
-     *   .select((eb) => eb.fn.max<number | null, 'price'>('price').as('max_price'))
+     *   .select((eb) => eb.fn.max<number | null>('price').as('max_price'))
      *   .execute()
      * ```
      */
-    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>;
+    max<O extends number | string | bigint | null = never, RE extends ReferenceExpression<DB, TB> = ReferenceExpression<DB, TB>>(expr: RE): AggregateFunctionBuilder<DB, TB, IsNever<O> extends true ? ExtractTypeFromReferenceExpression<DB, TB, RE, number | string | bigint> : O>;
     /**
      * Calls the `min` function for the column or expression given as the argument.
      *
@@ -443,12 +474,11 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      *
      * ```ts
      * db.selectFrom('toy')
-     *   .select((eb) => eb.fn.min<number | null, 'price'>('price').as('min_price'))
+     *   .select((eb) => eb.fn.min<number | null>('price').as('min_price'))
      *   .execute()
      * ```
      */
-    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>;
+    min<O extends number | string | bigint | null = never, RE extends ReferenceExpression<DB, TB> = ReferenceExpression<DB, TB>>(expr: RE): AggregateFunctionBuilder<DB, TB, IsNever<O> extends true ? ExtractTypeFromReferenceExpression<DB, TB, RE, number | string | bigint> : O>;
     /**
      * Calls the `sum` function for the column or expression given as the argument.
      *
@@ -507,7 +537,7 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      *   .execute()
      * ```
      */
-    sum<O extends number | string | bigint | null = number | string | bigint, C extends ReferenceExpression<DB, TB> = ReferenceExpression<DB, TB>>(column: C): AggregateFunctionBuilder<DB, TB, O>;
+    sum<O extends number | string | bigint | null = number | string | bigint, RE extends ReferenceExpression<DB, TB> = ReferenceExpression<DB, TB>>(expr: RE): AggregateFunctionBuilder<DB, TB, O>;
     /**
      * Calls the `any` function for the column or expression given as the argument.
      *
@@ -538,10 +568,51 @@ export interface FunctionModule<DB, TB extends keyof DB> {
      * ```
      */
     any<RE extends StringReference<DB, TB>>(expr: RE): Exclude<ExtractTypeFromStringReference<DB, TB, RE>, null> extends ReadonlyArray<infer I> ? ExpressionWrapper<DB, TB, I> : KyselyTypeError<'any(expr) call failed: expr must be an array'>;
-    any<T>(subquery: SelectQueryBuilder<any, any, Record<string, T>>): ExpressionWrapper<DB, TB, T>;
+    any<T>(subquery: SelectQueryBuilderExpression<Record<string, T>>): ExpressionWrapper<DB, TB, T>;
     any<T>(expr: Expression<ReadonlyArray<T>>): ExpressionWrapper<DB, TB, T>;
+    /**
+     * Creates a json_agg function call.
+     *
+     * This function is only available on PostgreSQL.
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .innerJoin('pet', 'pet.owner_id', 'person.id')
+     *   .select((eb) => ['first_name', eb.fn.jsonAgg('pet').as('pets')])
+     *   .groupBy('person.first_name')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "first_name", json_agg("pet") as "pets"
+     * from "person"
+     * inner join "pet" on "pet"."owner_id" = "person"."id"
+     * group by "person"."first_name"
+     * ```
+     */
+    jsonAgg<T extends (TB & string) | Expression<unknown>>(table: T): AggregateFunctionBuilder<DB, TB, T extends TB ? Selectable<DB[T]>[] : T extends Expression<infer O> ? O[] : never>;
+    /**
+     * Creates a to_json function call.
+     *
+     * This function is only available on PostgreSQL.
+     *
+     * ```ts
+     * db.selectFrom('person')
+     *   .innerJoin('pet', 'pet.owner_id', 'person.id')
+     *   .select((eb) => ['first_name', eb.fn.toJson('pet').as('pet')])
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "first_name", to_json("pet") as "pet"
+     * from "person"
+     * inner join "pet" on "pet"."owner_id" = "person"."id"
+     * ```
+     */
+    toJson<T extends (TB & string) | Expression<unknown>>(table: T): ExpressionWrapper<DB, TB, T extends TB ? Selectable<DB[T]> : T extends Expression<infer O> ? O : never>;
 }
 export declare function createFunctionModule<DB, TB extends keyof DB>(): FunctionModule<DB, TB>;
-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;
-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

@@ -5,9 +5,11 @@ import { FunctionNode } from '../operation-node/function-node.js';
 import { parseReferenceExpressionOrList, } from '../parser/reference-parser.js';
 import { parseSelectAll } from '../parser/select-parser.js';
 import { AggregateFunctionBuilder } from './aggregate-function-builder.js';
+import { isString } from '../util/object-utils.js';
+import { parseTable } from '../parser/table-parser.js';
 export function createFunctionModule() {
     const fn = (name, args) => {
-        return new ExpressionWrapper(FunctionNode.create(name, parseReferenceExpressionOrList(args)));
+        return new ExpressionWrapper(FunctionNode.create(name, parseReferenceExpressionOrList(args ?? [])));
     };
     const agg = (name, args) => {
         return new AggregateFunctionBuilder({
@@ -19,8 +21,8 @@ export function createFunctionModule() {
         avg(column) {
             return agg('avg', [column]);
         },
-        coalesce(value, ...otherValues) {
-            return fn('coalesce', [value, ...otherValues]);
+        coalesce(...values) {
+            return fn('coalesce', values);
         },
         count(column) {
             return agg('count', [column]);
@@ -42,5 +44,17 @@ export function createFunctionModule() {
         any(column) {
             return fn('any', [column]);
         },
+        jsonAgg(table) {
+            return new AggregateFunctionBuilder({
+                aggregateFunctionNode: AggregateFunctionNode.create('json_agg', [
+                    isString(table) ? parseTable(table) : table.toOperationNode(),
+                ]),
+            });
+        },
+        toJson(table) {
+            return new ExpressionWrapper(FunctionNode.create('to_json', [
+                isString(table) ? parseTable(table) : table.toOperationNode(),
+            ]));
+        },
     });
 }

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

@@ -1,17 +1,15 @@
 import { ComparisonOperatorExpression, OperandValueExpressionOrList } from '../parser/binary-operation-parser.js';
-import { ExpressionOrFactory } from '../parser/expression-parser.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
-import { SqlBool } from '../util/type-utils.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: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): HavingInterface<DB, TB>;
-    having(expression: ExpressionOrFactory<DB, TB, SqlBool>): HavingInterface<DB, TB>;
+    having<RE extends ReferenceExpression<DB, TB>, VE extends OperandValueExpressionOrList<DB, TB, RE>>(lhs: RE, op: ComparisonOperatorExpression, rhs: VE): HavingInterface<DB, TB>;
+    having<E>(expression: E): 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: ComparisonOperatorExpression, rhs: ReferenceExpression<DB, TB>): HavingInterface<DB, TB>;
+    havingRef<LRE extends ReferenceExpression<DB, TB>, RRE extends ReferenceExpression<DB, TB>>(lhs: LRE, op: ComparisonOperatorExpression, rhs: RRE): HavingInterface<DB, TB>;
 }

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

@@ -1,17 +1,17 @@
 import { OperationNodeSource } from '../operation-node/operation-node-source.js';
 import { CompiledQuery } from '../query-compiler/compiled-query.js';
-import { SelectExpression, SelectArg } from '../parser/select-parser.js';
+import { SelectExpression, SelectCallback } 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 { NarrowPartial, SimplifyResult, SimplifySingleResult } from '../util/type-utils.js';
-import { UpdateExpression } from '../parser/update-set-parser.js';
+import { UpdateObjectExpression } from '../parser/update-set-parser.js';
 import { Compilable } from '../util/compilable.js';
 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 { ReturningRow } from '../parser/returning-parser.js';
+import { 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';
@@ -60,13 +60,18 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *   })
      *   .executeTakeFirst()
      *
+     * // `insertId` is only available on dialects that
+     * // automatically return the id of the inserted row
+     * // such as MySQL and SQLite. On PostgreSQL, for example,
+     * // you need to add a `returning` clause to the query to
+     * // get anything out. See the "returning data" example.
      * console.log(result.insertId)
      * ```
      *
-     * The generated SQL (PostgreSQL):
+     * The generated SQL (MySQL):
      *
      * ```sql
-     * insert into "person" ("first_name", "last_name", "age") values ($1, $2, $3)
+     * insert into `person` (`first_name`, `last_name`, `age`) values (?, ?, ?)
      * ```
      *
      * <!-- siteExample("insert", "Multiple rows", 20) -->
@@ -131,11 +136,14 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * ```ts
      * import { sql } from 'kysely'
      *
+     * const ani = "Ani"
+     * const ston = "ston"
+     *
      * const result = await db
      *   .insertInto('person')
      *   .values(({ ref, selectFrom, fn }) => ({
      *     first_name: 'Jennifer',
-     *     last_name: sql`${'Ani'} || ${'ston'}`,
+     *     last_name: sql`concat(${ani}, ${ston})`,
      *     middle_name: ref('first_name'),
      *     age: selectFrom('person')
      *       .select(fn.avg<number>('age')
@@ -147,8 +155,18 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * insert into "person" ("first_name", "last_name", "age")
-     * values ($1, $2 || $3, (select avg("age") as "avg_age" from "person"))
+     * insert into "person" (
+     *   "first_name",
+     *   "last_name",
+     *   "middle_name",
+     *   "age"
+     * )
+     * values (
+     *   $1,
+     *   concat($2, $3),
+     *   "first_name",
+     *   (select avg("age") as "avg_age" from "person")
+     * )
      * ```
      *
      * You can also use the callback version of subqueries or raw expressions:
@@ -208,7 +226,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *     .select((eb) => [
      *       'pet.name',
      *       eb.val('Petson').as('last_name'),
-     *       eb.val(7).as('age'),
+     *       eb.lit(7).as('age'),
      *     ])
      *   )
      *   .execute()
@@ -218,7 +236,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *
      * ```sql
      * insert into "person" ("first_name", "last_name", "age")
-     * select "pet"."name", $1 as "first_name", $2 as "last_name" from "pet"
+     * select "pet"."name", $1 as "last_name", 7 as "age from "pet"
      * ```
      */
     expression(expression: ExpressionOrFactory<DB, TB, any>): InsertQueryBuilder<DB, TB, O>;
@@ -414,7 +432,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *   .onDuplicateKeyUpdate({ species: 'hamster' })
      * ```
      */
-    onDuplicateKeyUpdate(update: UpdateExpression<DB, TB, TB>): InsertQueryBuilder<DB, TB, O>;
+    onDuplicateKeyUpdate(update: UpdateObjectExpression<DB, TB, TB>): InsertQueryBuilder<DB, TB, O>;
     /**
      * Allows you to return data from modified rows.
      *
@@ -474,7 +492,9 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *   .executeTakeFirst()
      * ```
      */
-    returning<SE extends SelectExpression<DB, TB>>(selection: SelectArg<DB, TB, SE>): InsertQueryBuilder<DB, TB, ReturningRow<DB, TB, O, SE>>;
+    returning<SE extends SelectExpression<DB, TB>>(selections: ReadonlyArray<SE>): InsertQueryBuilder<DB, TB, ReturningRow<DB, TB, O, SE>>;
+    returning<CB extends SelectCallback<DB, TB>>(callback: CB): InsertQueryBuilder<DB, TB, ReturningCallbackRow<DB, TB, O, CB>>;
+    returning<SE extends SelectExpression<DB, TB>>(selection: SE): InsertQueryBuilder<DB, TB, ReturningRow<DB, TB, O, SE>>;
     /**
      * Adds a `returning *` to an insert/update/delete query on databases
      * that support `returning` such as PostgreSQL.

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

@@ -3,7 +3,7 @@ import { parseSelectArg, parseSelectAll, } from '../parser/select-parser.js';
 import { parseInsertExpression, } from '../parser/insert-values-parser.js';
 import { InsertQueryNode } from '../operation-node/insert-query-node.js';
 import { QueryNode } from '../operation-node/query-node.js';
-import { parseUpdateExpression, } from '../parser/update-set-parser.js';
+import { parseUpdateObjectExpression, } from '../parser/update-set-parser.js';
 import { preventAwait } from '../util/prevent-await.js';
 import { freeze } from '../util/object-utils.js';
 import { OnDuplicateKeyNode } from '../operation-node/on-duplicate-key-node.js';
@@ -75,7 +75,7 @@ export class InsertQueryBuilder {
      *     .select((eb) => [
      *       'pet.name',
      *       eb.val('Petson').as('last_name'),
-     *       eb.val(7).as('age'),
+     *       eb.lit(7).as('age'),
      *     ])
      *   )
      *   .execute()
@@ -85,7 +85,7 @@ export class InsertQueryBuilder {
      *
      * ```sql
      * insert into "person" ("first_name", "last_name", "age")
-     * select "pet"."name", $1 as "first_name", $2 as "last_name" from "pet"
+     * select "pet"."name", $1 as "last_name", 7 as "age from "pet"
      * ```
      */
     expression(expression) {
@@ -308,7 +308,7 @@ export class InsertQueryBuilder {
         return new InsertQueryBuilder({
             ...this.#props,
             queryNode: InsertQueryNode.cloneWith(this.#props.queryNode, {
-                onDuplicateKey: OnDuplicateKeyNode.create(parseUpdateExpression(update)),
+                onDuplicateKey: OnDuplicateKeyNode.create(parseUpdateObjectExpression(update)),
             }),
         });
     }

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

@@ -23,7 +23,14 @@
  */
 export declare class InsertResult {
     /**
-     * The auto incrementing primary key
+     * The auto incrementing primary key of the inserted row.
+     *
+     * This property can be undefined when the query contains an `on conflict`
+     * clause that makes the query succeed even when nothing gets inserted.
+     *
+     * This property is always undefined on dialects like PostgreSQL that
+     * don't return the inserted id by default. On those dialects you need
+     * to use the {@link ReturningInterface.returning | returning} method.
      */
     readonly insertId: bigint | undefined;
     /**

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

@@ -24,7 +24,14 @@
  */
 export class InsertResult {
     /**
-     * The auto incrementing primary key
+     * The auto incrementing primary key of the inserted row.
+     *
+     * This property can be undefined when the query contains an `on conflict`
+     * clause that makes the query succeed even when nothing gets inserted.
+     *
+     * This property is always undefined on dialects like PostgreSQL that
+     * don't return the inserted id by default. On those dialects you need
+     * to use the {@link ReturningInterface.returning | returning} method.
      */
     insertId;
     /**

package/dist/esm/query-builder/json-path-builder.d.ts

@@ -1,10 +1,11 @@
 import { AliasableExpression, AliasedExpression, Expression } from '../expression/expression.js';
 import { AliasNode } from '../operation-node/alias-node.js';
+import { JSONPathNode } from '../operation-node/json-path-node.js';
 import { JSONReferenceNode } from '../operation-node/json-reference-node.js';
 import { OperationNode } from '../operation-node/operation-node.js';
 export declare class JSONPathBuilder<S, O = S> {
     #private;
-    constructor(node: JSONReferenceNode);
+    constructor(node: JSONReferenceNode | JSONPathNode);
     /**
      * Access an element of a JSON array in a specific location.
      *
@@ -123,7 +124,7 @@ export declare class JSONPathBuilder<S, O = S> {
 }
 export declare class TraversedJSONPathBuilder<S, O> extends JSONPathBuilder<S, O> implements AliasableExpression<O> {
     #private;
-    constructor(node: JSONReferenceNode);
+    constructor(node: JSONReferenceNode | JSONPathNode);
     /** @private */
     /**
      * All expressions need to have this getter for complicated type-related reasons.

package/dist/esm/query-builder/json-path-builder.js

@@ -132,9 +132,12 @@ export class JSONPathBuilder {
         return this.#createBuilderWithPathLeg('Member', key);
     }
     #createBuilderWithPathLeg(legType, value) {
-        return new TraversedJSONPathBuilder(JSONReferenceNode.cloneWithTraversal(this.#node, JSONPathNode.is(this.#node.traversal)
-            ? JSONPathNode.cloneWithLeg(this.#node.traversal, JSONPathLegNode.create(legType, value))
-            : JSONOperatorChainNode.cloneWithValue(this.#node.traversal, ValueNode.createImmediate(value))));
+        if (JSONReferenceNode.is(this.#node)) {
+            return new TraversedJSONPathBuilder(JSONReferenceNode.cloneWithTraversal(this.#node, JSONPathNode.is(this.#node.traversal)
+                ? JSONPathNode.cloneWithLeg(this.#node.traversal, JSONPathLegNode.create(legType, value))
+                : JSONOperatorChainNode.cloneWithValue(this.#node.traversal, ValueNode.createImmediate(value))));
+        }
+        return new TraversedJSONPathBuilder(JSONPathNode.cloneWithLeg(this.#node, JSONPathLegNode.create(legType, value)));
     }
 }
 export class TraversedJSONPathBuilder extends JSONPathBuilder {

package/dist/esm/query-builder/on-conflict-builder.d.ts

@@ -4,7 +4,8 @@ import { OperationNodeSource } from '../operation-node/operation-node-source.js'
 import { ComparisonOperatorExpression, OperandValueExpressionOrList } from '../parser/binary-operation-parser.js';
 import { ExpressionOrFactory } from '../parser/expression-parser.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
-import { UpdateExpression } from '../parser/update-set-parser.js';
+import { UpdateObjectExpression } from '../parser/update-set-parser.js';
+import { Updateable } from '../util/column-type.js';
 import { AnyColumn, SqlBool } from '../util/type-utils.js';
 import { WhereInterface } from './where-interface.js';
 export declare class OnConflictBuilder<DB, TB extends keyof DB> implements WhereInterface<DB, TB> {
@@ -40,12 +41,6 @@ export declare class OnConflictBuilder<DB, TB extends keyof DB> implements Where
      * methods for alternative ways to specify the conflict target.
      */
     expression(expression: Expression<any>): OnConflictBuilder<DB, TB>;
-    /**
-     * Specify an index predicate for the index target.
-     *
-     * See {@link WhereInterface.where} for more info.
-     */
-    where<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): OnConflictBuilder<DB, TB>;
     /**
      * Adds a `where` expression to the query.
      *
@@ -345,13 +340,60 @@ export declare class OnConflictBuilder<DB, TB extends keyof DB> implements Where
      *   .execute()
      * ```
      */
-    where(expression: ExpressionOrFactory<DB, TB, SqlBool>): OnConflictBuilder<DB, TB>;
+    where<RE extends ReferenceExpression<DB, TB>, VE extends OperandValueExpressionOrList<DB, TB, RE>>(lhs: RE, op: ComparisonOperatorExpression, rhs: VE): OnConflictBuilder<DB, TB>;
+    where<E extends ExpressionOrFactory<DB, TB, SqlBool>>(expression: E): OnConflictBuilder<DB, TB>;
     /**
-     * Specify an index predicate for the index target.
+     * Adds a `where` clause where both sides of the operator are references
+     * to columns.
      *
-     * See {@link WhereInterface.whereRef} for more info.
+     * The normal `where` method treats the right hand side argument as a
+     * value by default. `whereRef` treats it as a column reference. This method is
+     * expecially useful with joins and correlated subqueries.
+     *
+     * ### Examples
+     *
+     * Usage with a join:
+     *
+     * ```ts
+     * db.selectFrom(['person', 'pet'])
+     *   .selectAll()
+     *   .whereRef('person.first_name', '=', 'pet.name')
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select * from "person", "pet" where "person"."first_name" = "pet"."name"
+     * ```
+     *
+     * Usage in a subquery:
+     *
+     * ```ts
+     * const persons = await db
+     *   .selectFrom('person')
+     *   .selectAll('person')
+     *   .select((eb) => eb
+     *     .selectFrom('pet')
+     *     .select('name')
+     *     .whereRef('pet.owner_id', '=', 'person.id')
+     *     .limit(1)
+     *     .as('pet_name')
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person".*, (
+     *   select "name"
+     *   from "pet"
+     *   where "pet"."owner_id" = "person"."id"
+     *   limit $1
+     * ) as "pet_name"
+     * from "person"
      */
-    whereRef(lhs: ReferenceExpression<DB, TB>, op: ComparisonOperatorExpression, rhs: ReferenceExpression<DB, TB>): OnConflictBuilder<DB, TB>;
+    whereRef<LRE extends ReferenceExpression<DB, TB>, RRE extends ReferenceExpression<DB, TB>>(lhs: LRE, op: ComparisonOperatorExpression, rhs: RRE): OnConflictBuilder<DB, TB>;
     /**
      * Clears all where expressions from the query.
      *
@@ -435,7 +477,7 @@ export declare class OnConflictBuilder<DB, TB extends keyof DB> implements Where
      *   )
      * ```
      */
-    doUpdateSet(update: UpdateExpression<OnConflictDatabase<DB, TB>, OnConflictTables<TB>, OnConflictTables<TB>>): OnConflictUpdateBuilder<OnConflictDatabase<DB, TB>, OnConflictTables<TB>>;
+    doUpdateSet(update: UpdateObjectExpression<OnConflictDatabase<DB, TB>, OnConflictTables<TB>, OnConflictTables<TB>>): OnConflictUpdateBuilder<OnConflictDatabase<DB, TB>, OnConflictTables<TB>>;
     /**
      * Simply calls the provided function passing `this` as the only argument. `$call` returns
      * what the provided function returns.
@@ -446,7 +488,7 @@ export interface OnConflictBuilderProps {
     readonly onConflictNode: OnConflictNode;
 }
 export type OnConflictDatabase<DB, TB extends keyof DB> = {
-    [K in keyof DB | 'excluded']: K extends keyof DB ? DB[K] : DB[TB];
+    [K in keyof DB | 'excluded']: Updateable<K extends keyof DB ? DB[K] : DB[TB]>;
 };
 export type OnConflictTables<TB> = TB | 'excluded';
 export declare class OnConflictDoNothingBuilder<DB, TB extends keyof DB> implements OperationNodeSource {
@@ -462,7 +504,7 @@ export declare class OnConflictUpdateBuilder<DB, TB extends keyof DB> implements
      *
      * See {@link WhereInterface.where} for more info.
      */
-    where<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): OnConflictUpdateBuilder<DB, TB>;
+    where<RE extends ReferenceExpression<DB, TB>, VE extends OperandValueExpressionOrList<DB, TB, RE>>(lhs: RE, op: ComparisonOperatorExpression, rhs: VE): OnConflictUpdateBuilder<DB, TB>;
     /**
      * Adds a `where` expression to the query.
      *
@@ -762,13 +804,13 @@ export declare class OnConflictUpdateBuilder<DB, TB extends keyof DB> implements
      *   .execute()
      * ```
      */
-    where(expression: ExpressionOrFactory<DB, TB, SqlBool>): OnConflictUpdateBuilder<DB, TB>;
+    where<E extends ExpressionOrFactory<DB, TB, SqlBool>>(expression: E): OnConflictUpdateBuilder<DB, TB>;
     /**
      * Specify a where condition for the update operation.
      *
      * See {@link WhereInterface.whereRef} for more info.
      */
-    whereRef(lhs: ReferenceExpression<DB, TB>, op: ComparisonOperatorExpression, rhs: ReferenceExpression<DB, TB>): OnConflictUpdateBuilder<DB, TB>;
+    whereRef<LRE extends ReferenceExpression<DB, TB>, RRE extends ReferenceExpression<DB, TB>>(lhs: LRE, op: ComparisonOperatorExpression, rhs: RRE): OnConflictUpdateBuilder<DB, TB>;
     /**
      * Clears all where expressions from the query.
      *