kysely 0.27.6 → 0.28.1

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

@@ -1,38 +1,22 @@
 /// <reference types="./over-builder.d.ts" />
 import { OverNode } from '../operation-node/over-node.js';
+import { QueryNode } from '../operation-node/query-node.js';
 import { parseOrderBy, } from '../parser/order-by-parser.js';
 import { parsePartitionBy, } from '../parser/partition-by-parser.js';
 import { freeze } from '../util/object-utils.js';
-import { preventAwait } from '../util/prevent-await.js';
 export class OverBuilder {
     #props;
     constructor(props) {
         this.#props = freeze(props);
     }
-    /**
-     * Adds an order by clause item inside the over function.
-     *
-     * ```ts
-     * const result = await db
-     *   .selectFrom('person')
-     *   .select(
-     *     (eb) => eb.fn.avg<number>('age').over(
-     *       ob => ob.orderBy('first_name', 'asc').orderBy('last_name', 'asc')
-     *     ).as('average_age')
-     *   )
-     *   .execute()
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select avg("age") over(order by "first_name" asc, "last_name" asc) as "average_age"
-     * from "person"
-     * ```
-     */
-    orderBy(orderBy, direction) {
+    orderBy(...args) {
+        return new OverBuilder({
+            overNode: OverNode.cloneWithOrderByItems(this.#props.overNode, parseOrderBy(args)),
+        });
+    }
+    clearOrderBy() {
         return new OverBuilder({
-            overNode: OverNode.cloneWithOrderByItems(this.#props.overNode, parseOrderBy([orderBy, direction])),
+            overNode: QueryNode.cloneWithoutOrderBy(this.#props.overNode),
         });
     }
     partitionBy(partitionBy) {
@@ -51,4 +35,3 @@ export class OverBuilder {
         return this.#props.overNode;
     }
 }
-preventAwait(OverBuilder, "don't await OverBuilder instances. They are never executed directly and are always just a part of a query.");

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

@@ -1,4 +1,4 @@
-import { ReturningCallbackRow, ReturningRow } from '../parser/returning-parser.js';
+import { ReturningAllRow, ReturningCallbackRow, ReturningRow } from '../parser/returning-parser.js';
 import { SelectCallback, SelectExpression } from '../parser/select-parser.js';
 import { Selectable } from '../util/column-type.js';
 export interface ReturningInterface<DB, TB extends keyof DB, O> {
@@ -6,7 +6,7 @@ export interface ReturningInterface<DB, TB extends keyof DB, O> {
      * Allows you to return data from modified rows.
      *
      * On supported databases like PostgreSQL, this method can be chained to
-     * `insert`, `update` and `delete` queries to return data.
+     * `insert`, `update`, `delete` and `merge` queries to return data.
      *
      * Note that on SQLite you need to give aliases for the expressions to avoid
      * [this bug](https://sqlite.org/forum/forumpost/033daf0b32) in SQLite.
@@ -65,10 +65,27 @@ export interface ReturningInterface<DB, TB extends keyof DB, O> {
     returning<CB extends SelectCallback<DB, TB>>(callback: CB): ReturningInterface<DB, TB, ReturningCallbackRow<DB, TB, O, CB>>;
     returning<SE extends SelectExpression<DB, TB>>(selection: SE): ReturningInterface<DB, TB, ReturningRow<DB, TB, O, SE>>;
     /**
-     * Adds a `returning *` to an insert/update/delete query on databases
+     * Adds a `returning *` to an insert/update/delete/merge query on databases
      * that support `returning` such as PostgreSQL.
      *
      * Also see the {@link returning} method.
      */
     returningAll(): ReturningInterface<DB, TB, Selectable<DB[TB]>>;
 }
+export interface MultiTableReturningInterface<DB, TB extends keyof DB, O> extends ReturningInterface<DB, TB, O> {
+    /**
+     * Adds a `returning *` or `returning table.*` to an insert/update/delete/merge
+     * query on databases that support `returning` such as PostgreSQL.
+     *
+     * Also see the {@link returning} method.
+     */
+    returningAll<T extends TB>(tables: ReadonlyArray<T>): MultiTableReturningInterface<DB, TB, ReturningAllRow<DB, T, O>>;
+    /**
+     * Adds a `returning *` to an insert/update/delete/merge query on databases
+     * that support `returning` such as PostgreSQL.
+     *
+     * Also see the {@link returning} method.
+     */
+    returningAll<T extends TB>(table: T): MultiTableReturningInterface<DB, TB, ReturningAllRow<DB, T, O>>;
+    returningAll(): ReturningInterface<DB, TB, Selectable<DB[TB]>>;
+}

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

@@ -6,7 +6,7 @@ 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 { DrainOuterGeneric, NarrowPartial, Nullable, ShallowRecord, Simplify, SimplifySingleResult, SqlBool } from '../util/type-utils.js';
-import { OrderByDirectionExpression, OrderByExpression, DirectedOrderByStringReference, UndirectedOrderByExpression } from '../parser/order-by-parser.js';
+import { DirectedOrderByStringReference, OrderByExpression, OrderByModifiers } from '../parser/order-by-parser.js';
 import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
 import { QueryId } from '../util/query-id.js';
@@ -28,7 +28,8 @@ import { SelectQueryBuilderExpression } from './select-query-builder-expression.
 import { ValueExpression } from '../parser/value-parser.js';
 import { FetchModifier } from '../operation-node/fetch-node.js';
 import { TopModifier } from '../operation-node/top-node.js';
-export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInterface<DB, TB>, HavingInterface<DB, TB>, SelectQueryBuilderExpression<O>, Compilable<O>, Explainable, Streamable<O> {
+import { OrderByInterface } from './order-by-interface.js';
+export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInterface<DB, TB>, HavingInterface<DB, TB>, OrderByInterface<DB, TB, O>, SelectQueryBuilderExpression<O>, Compilable<O>, Explainable, Streamable<O> {
     /**
      * Adds a `where` expression to the query.
      *
@@ -505,7 +506,7 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * import { sql } from 'kysely'
      *
      * const persons = await db.selectFrom('person')
-     *   .select(({ eb, selectFrom, or }) => [
+     *   .select(({ eb, selectFrom, or, val, lit }) => [
      *     // Select a correlated subquery
      *     selectFrom('pet')
      *       .whereRef('person.id', '=', 'pet.owner_id')
@@ -522,7 +523,13 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      *     ]).as('is_jennifer_or_arnold'),
      *
      *     // Select a raw sql expression
-     *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name')
+     *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name'),
+     *
+     *     // Select a static string value
+     *     val('Some value').as('string_value'),
+     *
+     *     // Select a literal value
+     *     lit(42).as('literal_value'),
      *   ])
      *   .execute()
      * ```
@@ -539,7 +546,9 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      *     limit $1
      *   ) as "pet_name",
      *   ("first_name" = $2 or "first_name" = $3) as "jennifer_or_arnold",
-     *   concat(first_name, ' ', last_name) as "full_name"
+     *   concat(first_name, ' ', last_name) as "full_name",
+     *   $4 as "string_value",
+     *   42 as "literal_value"
      * from "person"
      * ```
      *
@@ -803,13 +812,13 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
     selectAll<T extends TB>(table: T): SelectQueryBuilder<DB, TB, O & Selectable<DB[T]>>;
     selectAll(): SelectQueryBuilder<DB, TB, O & AllSelection<DB, TB>>;
     /**
-     * Joins another table to the query using an inner join.
+     * Joins another table to the query using an `inner join`.
      *
      * ### Examples
      *
      * <!-- siteExample("join", "Simple inner join", 10) -->
      *
-     * Simple inner joins can be done by providing a table name and two columns to join:
+     * Simple `inner join`s can be done by providing a table name and two columns to join:
      *
      * ```ts
      * const result = await db
@@ -929,23 +938,31 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
     innerJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): SelectQueryBuilderWithInnerJoin<DB, TB, O, TE>;
     innerJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): SelectQueryBuilderWithInnerJoin<DB, TB, O, TE>;
     /**
-     * Just like {@link innerJoin} but adds a left join instead of an inner join.
+     * Just like {@link innerJoin} but adds a `left join` instead of an `inner join`.
      */
     leftJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): SelectQueryBuilderWithLeftJoin<DB, TB, O, TE>;
     leftJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): SelectQueryBuilderWithLeftJoin<DB, TB, O, TE>;
     /**
-     * Just like {@link innerJoin} but adds a right join instead of an inner join.
+     * Just like {@link innerJoin} but adds a `right join` instead of an `inner join`.
      */
     rightJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): SelectQueryBuilderWithRightJoin<DB, TB, O, TE>;
     rightJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): SelectQueryBuilderWithRightJoin<DB, TB, O, TE>;
     /**
-     * Just like {@link innerJoin} but adds a full join instead of an inner join.
+     * Just like {@link innerJoin} but adds a `full join` instead of an `inner join`.
+     *
+     * This is only supported by some dialects like PostgreSQL, MS SQL Server and SQLite.
      */
     fullJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): SelectQueryBuilderWithFullJoin<DB, TB, O, TE>;
     fullJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): SelectQueryBuilderWithFullJoin<DB, TB, O, TE>;
+    /**
+     * Just like {@link innerJoin} but adds a `cross join` instead of an `inner join`.
+     */
+    crossJoin<TE extends TableExpression<DB, TB>>(table: TE): SelectQueryBuilderWithInnerJoin<DB, TB, O, TE>;
     /**
      * Just like {@link innerJoin} but adds a lateral join instead of an inner join.
      *
+     * This is only supported by some dialects like PostgreSQL and MySQL.
+     *
      * ### Examples
      *
      * ```ts
@@ -979,7 +996,10 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
     innerJoinLateral<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): SelectQueryBuilderWithInnerJoin<DB, TB, O, TE>;
     innerJoinLateral<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): SelectQueryBuilderWithInnerJoin<DB, TB, O, TE>;
     /**
-     * Just like {@link innerJoin} but adds a lateral left join instead of an inner join.
+     * Just like {@link innerJoin} but adds a `left join lateral` instead of an `inner join`.
+     *
+     * This is only supported by some dialects like PostgreSQL and MySQL.
+     *
      * ### Examples
      *
      * ```ts
@@ -1013,119 +1033,81 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
     leftJoinLateral<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): SelectQueryBuilderWithLeftJoin<DB, TB, O, TE>;
     leftJoinLateral<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): SelectQueryBuilderWithLeftJoin<DB, TB, O, TE>;
     /**
-     * Adds an `order by` clause to the query.
+     * Just like {@link innerJoin} but adds a `cross join lateral` instead of an `inner join`.
      *
-     * `orderBy` calls are additive. Meaning, additional `orderBy` calls append to
-     * the existing order by clause.
-     *
-     * In a single call you can add a single column/expression or multiple columns/expressions.
-     *
-     * Single column/expression calls can have 1-2 arguments. The first argument is
-     * the expression to order by (optionally including the direction) while the second
-     * optional argument is the direction (`asc` or `desc`).
+     * This is only supported by some dialects like PostgreSQL.
      *
      * ### Examples
      *
-     * Single column/expression per call:
-     *
      * ```ts
-     * await db
-     *   .selectFrom('person')
-     *   .select('person.first_name as fn')
-     *   .orderBy('id')
-     *   .orderBy('fn desc')
-     *   .execute()
-     * ```
-     *
-     * ```ts
-     * await db
-     *   .selectFrom('person')
-     *   .select('person.first_name as fn')
-     *   .orderBy('id')
-     *   .orderBy('fn', 'desc')
+     * await db.selectFrom('person')
+     *   .crossJoinLateral(
+     *     (eb) =>
+     *       eb.selectFrom('pet')
+     *         .select('name')
+     *         .whereRef('pet.owner_id', '=', 'person.id')
+     *         .as('p')
+     *   )
+     *   .select(['first_name', 'p.name'])
+     *   .orderBy('first_name')
      *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * select "person"."first_name" as "fn"
+     * select "person"."first_name", "p"."name"
      * from "person"
-     * order by "id" asc, "fn" desc
+     * cross join lateral (
+     *   select "name"
+     *   from "pet"
+     *   where "pet"."owner_id" = "person"."id"
+     * ) as "p"
+     * order by "first_name"
      * ```
+     */
+    crossJoinLateral<TE extends TableExpression<DB, TB>>(table: TE): SelectQueryBuilderWithInnerJoin<DB, TB, O, TE>;
+    /**
+     * Joins another table to the query using a `cross apply`.
      *
-     * Multiple columns/expressions per call:
+     * This is only supported by some dialects like MS SQL Server.
      *
-     * ```ts
-     * await db
-     *   .selectFrom('person')
-     *   .select('person.first_name as fn')
-     *   .orderBy(['id', 'fn desc'])
-     *   .execute()
-     * ```
-     *
-     * The order by expression can also be a raw sql expression or a subquery
-     * in addition to column references:
+     * ### Examples
      *
      * ```ts
-     * import { sql } from 'kysely'
-     *
-     * await db
-     *   .selectFrom('person')
-     *   .selectAll()
-     *   .orderBy((eb) => eb.selectFrom('pet')
-     *     .select('pet.name')
-     *     .whereRef('pet.owner_id', '=', 'person.id')
-     *     .limit(1)
-     *   )
-     *   .orderBy(
-     *     sql<string>`concat(first_name, last_name)`
+     * await db.selectFrom('person')
+     *   .crossApply(
+     *     (eb) =>
+     *       eb.selectFrom('pet')
+     *         .select('name')
+     *         .whereRef('pet.owner_id', '=', 'person.id')
+     *         .as('p')
      *   )
+     *   .select(['first_name', 'p.name'])
+     *   .orderBy('first_name')
      *   .execute()
      * ```
      *
-     * The generated SQL (PostgreSQL):
+     * The generated SQL (MS SQL Server):
      *
      * ```sql
-     * select *
+     * select "person"."first_name", "p"."name"
      * from "person"
-     * order by
-     *   ( select "pet"."name"
-     *     from "pet"
-     *     where "pet"."owner_id" = "person"."id"
-     *     limit 1
-     *   ) asc,
-     *   concat(first_name, last_name) asc
-     * ```
-     *
-     * `dynamic.ref` can be used to refer to columns not known at
-     * compile time:
-     *
-     * ```ts
-     * async function someQuery(orderBy: string) {
-     *   const { ref } = db.dynamic
-     *
-     *   return await db
-     *     .selectFrom('person')
-     *     .select('person.first_name as fn')
-     *     .orderBy(ref(orderBy))
-     *     .execute()
-     * }
-     *
-     * someQuery('fn')
+     * cross apply (
+     *   select "name"
+     *   from "pet"
+     *   where "pet"."owner_id" = "person"."id"
+     * ) as "p"
+     * order by "first_name"
      * ```
+     */
+    crossApply<TE extends TableExpression<DB, TB>>(table: TE): SelectQueryBuilderWithInnerJoin<DB, TB, O, TE>;
+    /**
+     * Just like {@link crossApply} but adds an `outer apply` instead of a `cross apply`.
      *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select "person"."first_name" as "fn"
-     * from "person"
-     * order by "fn" asc
-     * ```
+     * This is only supported by some dialects like MS SQL Server.
      */
-    orderBy<OE extends UndirectedOrderByExpression<DB, TB, O>>(orderBy: OE, direction?: OrderByDirectionExpression): SelectQueryBuilder<DB, TB, O>;
-    orderBy<OE extends DirectedOrderByStringReference<DB, TB, O>>(ref: OE): SelectQueryBuilder<DB, TB, O>;
-    orderBy<OE extends OrderByExpression<DB, TB, O>>(refs: ReadonlyArray<OE>): SelectQueryBuilder<DB, TB, O>;
+    outerApply<TE extends TableExpression<DB, TB>>(table: TE): SelectQueryBuilderWithLeftJoin<DB, TB, O, TE>;
     /**
      * Adds a `group by` clause to the query.
      *
@@ -1225,9 +1207,159 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * ```
      */
     groupBy<GE extends GroupByArg<DB, TB, O>>(groupBy: GE): SelectQueryBuilder<DB, TB, O>;
+    /**
+     * Adds an `order by` clause to the query.
+     *
+     * `orderBy` calls are additive. Meaning, additional `orderBy` calls append to
+     * the existing order by clause.
+     *
+     * `orderBy` is supported in select queries on all dialects. In MySQL, you can
+     * also use `orderBy` in update and delete queries.
+     *
+     * In a single call you can add a single column/expression or multiple columns/expressions.
+     *
+     * Single column/expression calls can have 1-2 arguments. The first argument is
+     * the expression to order by, while the second optional argument is the direction
+     * (`asc` or `desc`), a callback that accepts and returns an {@link OrderByItemBuilder}
+     * or an expression.
+     *
+     * See {@link clearOrderBy} to remove the `order by` clause from a query.
+     *
+     * ### Examples
+     *
+     * Single column/expression per call:
+     *
+     * ```ts
+     * await db
+     *   .selectFrom('person')
+     *   .select('person.first_name as fn')
+     *   .orderBy('id')
+     *   .orderBy('fn', 'desc')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person"."first_name" as "fn"
+     * from "person"
+     * order by "id", "fn" desc
+     * ```
+     *
+     * Multiple columns/expressions per call:
+     *
+     * ```ts
+     * await db
+     *   .selectFrom('person')
+     *   .select('person.first_name as fn')
+     *   .orderBy(['id', 'fn'])
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person"."first_name" as "fn"
+     * from "person"
+     * order by "id", "fn"
+     * ```
+     *
+     * Building advanced modifiers:
+     *
+     * ```ts
+     * await db
+     *   .selectFrom('person')
+     *   .select('person.first_name as fn')
+     *   .orderBy('id', (ob) => ob.desc().nullsFirst())
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person"."first_name" as "fn"
+     * from "person"
+     * order by "id" desc nulls first
+     * ```
+     *
+     * The order by expression can also be a raw sql expression or a subquery
+     * in addition to column references:
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * await db
+     *   .selectFrom('person')
+     *   .selectAll()
+     *   .orderBy((eb) => eb.selectFrom('pet')
+     *     .select('pet.name')
+     *     .whereRef('pet.owner_id', '=', 'person.id')
+     *     .limit(1)
+     *   )
+     *   .orderBy(
+     *     sql<string>`concat(first_name, last_name) asc`
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select *
+     * from "person"
+     * order by
+     *   ( select "pet"."name"
+     *     from "pet"
+     *     where "pet"."owner_id" = "person"."id"
+     *     limit $1
+     *   ) asc,
+     *   concat(first_name, last_name) asc
+     * ```
+     *
+     * `dynamic.ref` can be used to refer to columns not known at
+     * compile time:
+     *
+     * ```ts
+     * async function someQuery(orderBy: string) {
+     *   const { ref } = db.dynamic
+     *
+     *   return await db
+     *     .selectFrom('person')
+     *     .select('person.first_name as fn')
+     *     .orderBy(ref(orderBy))
+     *     .execute()
+     * }
+     *
+     * someQuery('fn')
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person"."first_name" as "fn"
+     * from "person"
+     * order by "fn"
+     * ```
+     */
+    orderBy<OE extends OrderByExpression<DB, TB, O>>(expr: OE, modifiers?: OrderByModifiers): SelectQueryBuilder<DB, TB, O>;
+    /**
+     * @deprecated It does ~2-2.5x more compile-time instantiations than multiple `orderBy(expr, modifiers?)` calls, and has broken autocompletion.
+     */
+    orderBy<OE extends OrderByExpression<DB, TB, O> | DirectedOrderByStringReference<DB, TB, O>>(exprs: ReadonlyArray<OE>): SelectQueryBuilder<DB, TB, O>;
+    /**
+     * @deprecated Use orderBy(expr, direction) instead.
+     */
+    orderBy<OE extends DirectedOrderByStringReference<DB, TB, O>>(expr: OE): SelectQueryBuilder<DB, TB, O>;
+    /**
+     * @deprecated Use `orderBy(expr, (ob) => ...)` instead.
+     */
+    orderBy<OE extends OrderByExpression<DB, TB, O>>(expr: OE, modifiers: Expression<any>): SelectQueryBuilder<DB, TB, O>;
     /**
      * Adds a limit clause to the query.
      *
+     * Passing a `null` value is only supported by some dialects like PostgreSQL,
+     * and will result in a no-op limit clause.
+     *
      * ### Examples
      *
      * Select the first 10 rows of the result:
@@ -1263,7 +1395,7 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
      * select "first_name" from "person" limit $1 offset $2
      * ```
      */
-    limit(limit: ValueExpression<DB, TB, number | bigint>): SelectQueryBuilder<DB, TB, O>;
+    limit(limit: ValueExpression<DB, TB, number | bigint | null>): SelectQueryBuilder<DB, TB, O>;
     /**
      * Adds an `offset` clause to the query.
      *
@@ -1978,6 +2110,55 @@ export interface SelectQueryBuilder<DB, TB extends keyof DB, O> extends WhereInt
     $asTuple<K1 extends keyof O, K2 extends Exclude<keyof O, K1>, K3 extends Exclude<keyof O, K1 | K2>>(key1: K1, key2: K2, key3: K3): keyof O extends K1 | K2 | K3 ? ExpressionWrapper<DB, TB, [O[K1], O[K2], O[K3]]> : KyselyTypeError<'$asTuple() call failed: All selected columns must be provided as arguments'>;
     $asTuple<K1 extends keyof O, K2 extends Exclude<keyof O, K1>, K3 extends Exclude<keyof O, K1 | K2>, K4 extends Exclude<keyof O, K1 | K2 | K3>>(key1: K1, key2: K2, key3: K3, key4: K4): keyof O extends K1 | K2 | K3 | K4 ? ExpressionWrapper<DB, TB, [O[K1], O[K2], O[K3], O[K4]]> : KyselyTypeError<'$asTuple() call failed: All selected columns must be provided as arguments'>;
     $asTuple<K1 extends keyof O, K2 extends Exclude<keyof O, K1>, K3 extends Exclude<keyof O, K1 | K2>, K4 extends Exclude<keyof O, K1 | K2 | K3>, K5 extends Exclude<keyof O, K1 | K2 | K3 | K4>>(key1: K1, key2: K2, key3: K3, key4: K4, key5: K5): keyof O extends K1 | K2 | K3 | K4 | K5 ? ExpressionWrapper<DB, TB, [O[K1], O[K2], O[K3], O[K4], O[K5]]> : KyselyTypeError<'$asTuple() call failed: All selected columns must be provided as arguments'>;
+    /**
+     * Plucks the value type of the output record.
+     *
+     * In SQL, any record type that only has one column can be used as a scalar.
+     * For example a query like this works:
+     *
+     * ```sql
+     * select
+     *   id,
+     *   first_name
+     * from
+     *   person as p
+     * where
+     *   -- This is ok since the query only selects one row
+     *   -- and one column.
+     *  (select name from pet where pet.owner_id = p.id limit 1) = 'Doggo'
+     * ```
+     *
+     * In many cases Kysely handles this automatically and picks the correct
+     * scalar type instead of the record type, but sometimes you need to give
+     * Kysely a hint.
+     *
+     * One such case are custom helper functions that take `Expression<T>`
+     * instances as inputs:
+     *
+     * ```ts
+     * import type { Expression } from 'kysely'
+     *
+     * function doStuff(expr: Expression<string>) {
+     *   // ...
+     * }
+     *
+     * // Error! This is not ok because the expression type is
+     * // `{ first_name: string }` instead of `string`.
+     * // doStuff(db.selectFrom('person').select('first_name'))
+     *
+     * // Ok! This is ok since we've plucked the `string` type of the
+     * // only column in the output type.
+     * doStuff(db.selectFrom('person').select('first_name').$asScalar())
+     * ```
+     *
+     * This function has absolutely no effect on the generated SQL. It's
+     * purely a type-level helper.
+     *
+     * This method returns an `ExpressionWrapper` instead of a `SelectQueryBuilder`
+     * since the return value should only be used as a part of an expression
+     * and never executed as the main query.
+     */
+    $asScalar<K extends keyof O = keyof O>(): ExpressionWrapper<DB, TB, O[K]>;
     /**
      * Narrows (parts of) the output type of the query.
      *