kysely 0.27.4 → 0.27.6

package/dist/esm/expression/expression-builder.d.ts

@@ -28,9 +28,10 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * A simple comparison:
      *
      * ```ts
-     * eb.selectFrom('person')
+     * const result = await db.selectFrom('person')
      *   .selectAll()
      *   .where((eb) => eb('first_name', '=', 'Jennifer'))
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -45,9 +46,10 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * a column reference, you can use {@link ref}:
      *
      * ```ts
-     * eb.selectFrom('person')
+     * const result = await db.selectFrom('person')
      *   .selectAll()
      *   .where((eb) => eb('first_name', '=', eb.ref('last_name')))
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -61,11 +63,12 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * In the following example `eb` is used to increment an integer column:
      *
      * ```ts
-     * db.updateTable('person')
+     * await db.updateTable('person')
      *   .set((eb) => ({
      *     age: eb('age', '+', 1)
      *   }))
-     *   .where('id', '=', id)
+     *   .where('id', '=', 3)
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -80,15 +83,28 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * can be any expression:
      *
      * ```ts
-     * eb.selectFrom('person')
+     * const result = await db.selectFrom('person')
      *   .selectAll()
      *   .where((eb) => eb(
-     *     eb.fn('lower', ['first_name']),
+     *     eb.fn<string>('lower', ['first_name']),
      *     'in',
      *     eb.selectFrom('pet')
      *       .select('pet.name')
      *       .where('pet.species', '=', 'cat')
      *   ))
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select *
+     * from "person"
+     * where lower("first_name") in (
+     *   select "pet"."name"
+     *   from "pet"
+     *   where "pet"."species" = $1
+     * )
      * ```
      */
     <RE extends ReferenceExpression<DB, TB>, OP extends BinaryOperatorExpression, VE extends OperandValueExpressionOrList<DB, TB, RE>>(lhs: RE, op: OP, rhs: VE): ExpressionWrapper<DB, TB, OP extends ComparisonOperator ? SqlBool : ExtractTypeFromReferenceExpression<DB, TB, RE>>;
@@ -98,13 +114,14 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * const result = await db.selectFrom('person')
      *   .where(({ eb, exists, selectFrom }) =>
      *     eb('first_name', '=', 'Jennifer').and(
      *       exists(selectFrom('pet').whereRef('owner_id', '=', 'person.id').select('pet.id'))
      *     )
      *   )
      *   .selectAll()
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -126,7 +143,7 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * table of the database even if it doesn't produce valid SQL.
      *
      * ```ts
-     * await db.selectFrom('person')
+     * const result = await db.selectFrom('person')
      *   .innerJoin('pet', 'pet.owner_id', 'person.id')
      *   .select((eb) => [
      *     'person.id',
@@ -173,7 +190,7 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      *   ])
      *   .execute()
      *
-     * console.log(result[0].owner_name)
+     * console.log(result[0]?.owner_name)
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -205,11 +222,9 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * Kitchen sink example with 2 flavors of `case` operator:
      *
      * ```ts
-     * import { sql } from 'kysely'
-     *
      * const { title, name } = await db
      *   .selectFrom('person')
-     *   .where('id', '=', '123')
+     *   .where('id', '=', 123)
      *   .select((eb) => [
      *     eb.fn.coalesce('last_name', 'first_name').as('name'),
      *     eb
@@ -219,7 +234,7 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      *       .when('gender', '=', 'female')
      *       .then(
      *         eb
-     *           .case('maritalStatus')
+     *           .case('marital_status')
      *           .when('single')
      *           .then('Ms.')
      *           .else('Mrs.')
@@ -239,7 +254,7 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      *   case
      *     when "gender" = $1 then $2
      *     when "gender" = $3 then
-     *       case "maritalStatus"
+     *       case "marital_status"
      *         when $4 then $5
      *         else $6
      *       end
@@ -265,72 +280,112 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * This function can be used to pass in a column reference instead:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const result = await db.selectFrom('person')
      *   .selectAll('person')
      *   .where((eb) => eb.or([
      *     eb('first_name', '=', eb.ref('last_name')),
      *     eb('first_name', '=', eb.ref('middle_name'))
      *   ]))
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * select "person".*
+     * from "person"
+     * where "first_name" = "last_name" or "first_name" = "middle_name"
      * ```
      *
      * In the next example we use the `ref` method to reference columns of the virtual
      * table `excluded` in a type-safe way to create an upsert operation:
      *
      * ```ts
-     * db.insertInto('person')
-     *   .values(person)
+     * await db.insertInto('person')
+     *   .values({
+     *     id: 3,
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston',
+     *     gender: 'female',
+     *   })
      *   .onConflict((oc) => oc
      *     .column('id')
      *     .doUpdateSet(({ ref }) => ({
      *       first_name: ref('excluded.first_name'),
-     *       last_name: ref('excluded.last_name')
+     *       last_name: ref('excluded.last_name'),
+     *       gender: ref('excluded.gender'),
      *     }))
      *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("id", "first_name", "last_name", "gender")
+     * values ($1, $2, $3, $4)
+     * on conflict ("id") do update set
+     *   "first_name" = "excluded"."first_name",
+     *   "last_name" = "excluded"."last_name",
+     *   "gender" = "excluded"."gender"
      * ```
      *
      * In the next example we use `ref` in a raw sql expression. Unless you want
      * to be as type-safe as possible, this is probably overkill:
      *
      * ```ts
-     * db.update('pet').set((eb) => ({
-     *   name: sql<string>`concat(${eb.ref('pet.name')}, ${suffix})`
-     * }))
+     * import { sql } from 'kysely'
+     *
+     * await db.updateTable('pet')
+     *   .set((eb) => ({
+     *     name: sql<string>`concat(${eb.ref('pet.name')}, ${' the animal'})`
+     *   }))
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * update "pet" set "name" = concat("pet"."name", $1)
      * ```
      *
      * In the next example we use `ref` to reference a nested JSON property:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const result = await db.selectFrom('person')
      *   .where(({ eb, ref }) => eb(
-     *     ref('address', '->').key('state').key('abbr'),
+     *     ref('profile', '->').key('addresses').at(0).key('city'),
      *     '=',
-     *     'CA'
+     *     'San Diego'
      *   ))
      *   .selectAll()
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * select * from "person" where "address"->'state'->'abbr' = $1
+     * select * from "person" where "profile"->'addresses'->0->'city' = $1
      * ```
      *
      * You can also compile to a JSON path expression by using the `->$`or `->>$` operator:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const result = await db.selectFrom('person')
      *   .select(({ ref }) =>
-     *     ref('experience', '->$')
+     *     ref('profile', '->$')
+     *       .key('addresses')
      *       .at('last')
-     *       .key('title')
-     *       .as('current_job')
+     *       .key('city')
+     *       .as('current_city')
      *   )
+     *   .execute()
      * ```
      *
      * The generated SQL (MySQL):
      *
      * ```sql
-     * select `experience`->'$[last].title' as `current_job` from `person`
+     * select `profile`->'$.addresses[last].city' as `current_city` from `person`
      * ```
      */
     ref<RE extends StringReference<DB, TB>>(reference: RE): ExpressionWrapper<DB, TB, ExtractTypeFromReferenceExpression<DB, TB, RE>>;
@@ -343,13 +398,13 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * db.updateTable('person')
-     *   .set('experience', (eb) => eb.fn('json_set', [
-     *     'experience',
-     *     eb.jsonPath<'experience'>().at('last').key('title'),
-     *     eb.val('CEO')
+     * await db.updateTable('person')
+     *   .set('profile', (eb) => eb.fn('json_set', [
+     *     'profile',
+     *     eb.jsonPath<'profile'>().key('addresses').at('last').key('city'),
+     *     eb.val('San Diego')
      *   ]))
-     *   .where('id', '=', id)
+     *   .where('id', '=', 3)
      *   .execute()
      * ```
      *
@@ -357,16 +412,21 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      *
      * ```sql
      * update `person`
-     * set `experience` = json_set(`experience`, '$[last].title', ?)
-     * where `id` = ?
+     * set `profile` = json_set(`profile`, '$.addresses[last].city', $1)
+     * where `id` = $2
      * ```
      */
     jsonPath<$ extends StringReference<DB, TB> = never>(): IsNever<$> extends true ? KyselyTypeError<"You must provide a column reference as this method's $ generic"> : JSONPathBuilder<ExtractTypeFromReferenceExpression<DB, TB, $>>;
     /**
      * Creates a table reference.
      *
+     * ### Examples
+     *
      * ```ts
-     * db.selectFrom('person')
+     * import { sql } from 'kysely'
+     * import type { Pet } from 'type-editor' // imaginary module
+     *
+     * const result = await db.selectFrom('person')
      *   .innerJoin('pet', 'pet.owner_id', 'person.id')
      *   .select(eb => [
      *     'person.id',
@@ -384,6 +444,8 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * inner join "pet" on "pet"."owner_id" = "person"."id"
      * group by "person"."id"
      * ```
+     *
+     * If you need a column reference, use {@link ref}.
      */
     table<T extends TB & string>(table: T): ExpressionWrapper<DB, TB, Selectable<DB[T]>>;
     /**
@@ -399,13 +461,30 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * be used to pass in a value instead:
      *
      * ```ts
-     * eb(val(38), '=', ref('age'))
+     * const result = await db.selectFrom('person')
+     *   .selectAll()
+     *   .where((eb) => eb(
+     *     eb.val('cat'),
+     *     '=',
+     *     eb.fn.any(
+     *       eb.selectFrom('pet')
+     *         .select('species')
+     *         .whereRef('owner_id', '=', 'person.id')
+     *     )
+     *   ))
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * $1 = "age"
+     * select *
+     * from "person"
+     * where $1 = any(
+     *   select "species"
+     *   from "pet"
+     *   where "owner_id" = "person"."id"
+     * )
      * ```
      */
     val<VE>(value: VE): ExpressionWrapper<DB, TB, ExtractTypeFromValueExpression<VE>>;
@@ -418,7 +497,7 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * const result = await db.selectFrom('person')
      *   .selectAll('person')
      *   .where(({ eb, refTuple, tuple }) => eb(
      *     refTuple('first_name', 'last_name'),
@@ -428,6 +507,7 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      *       tuple('Sylvester', 'Stallone')
      *     ]
      *   ))
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -451,7 +531,7 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * function:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const result = await db.selectFrom('person')
      *   .selectAll('person')
      *   .where(({ eb, refTuple, selectFrom }) => eb(
      *     refTuple('first_name', 'last_name'),
@@ -461,6 +541,7 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      *       .where('species', '!=', 'cat')
      *       .$asTuple('name', 'species')
      *   ))
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -493,7 +574,7 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * const result = await db.selectFrom('person')
      *   .selectAll('person')
      *   .where(({ eb, refTuple, tuple }) => eb(
      *     refTuple('first_name', 'last_name'),
@@ -503,6 +584,7 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      *       tuple('Sylvester', 'Stallone')
      *     ]
      *   ))
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -535,8 +617,9 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * const result = await db.selectFrom('person')
      *   .select((eb) => eb.lit(1).as('one'))
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -557,11 +640,12 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * const result = await db.selectFrom('person')
      *   .select((eb) => [
      *     'first_name',
      *     eb.unary('-', 'age').as('negative_age')
      *   ])
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -602,9 +686,10 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * const result = await db.selectFrom('person')
      *   .selectAll()
      *   .where((eb) => eb.between('age', 40, 60))
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -620,9 +705,10 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * const result = await db.selectFrom('person')
      *   .selectAll()
      *   .where((eb) => eb.betweenSymmetric('age', 40, 60))
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -646,13 +732,14 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * statement:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const result = await db.selectFrom('person')
      *   .selectAll('person')
      *   .where((eb) => eb.and([
      *     eb('first_name', '=', 'Jennifer'),
-     *     eb('fist_name', '=', 'Arnold'),
-     *     eb('fist_name', '=', 'Sylvester')
+     *     eb('first_name', '=', 'Arnold'),
+     *     eb('first_name', '=', 'Sylvester')
      *   ]))
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -671,12 +758,13 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * equality comparisons:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const result = await db.selectFrom('person')
      *   .selectAll('person')
      *   .where((eb) => eb.and({
      *     first_name: 'Jennifer',
      *     last_name: 'Aniston'
      *   }))
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -706,13 +794,14 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * statement:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const result = await db.selectFrom('person')
      *   .selectAll('person')
      *   .where((eb) => eb.or([
      *     eb('first_name', '=', 'Jennifer'),
-     *     eb('fist_name', '=', 'Arnold'),
-     *     eb('fist_name', '=', 'Sylvester')
+     *     eb('first_name', '=', 'Arnold'),
+     *     eb('first_name', '=', 'Sylvester')
      *   ]))
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -731,12 +820,13 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * equality comparisons:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const result = await db.selectFrom('person')
      *   .selectAll('person')
      *   .where((eb) => eb.or({
      *     first_name: 'Jennifer',
      *     last_name: 'Aniston'
      *   }))
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -758,9 +848,10 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * const result = await db.selectFrom('person')
      *   .selectAll('person')
-     *   .where((eb) => eb(eb.parens('age', '+', 1), '/', 100), '<', 0.1))
+     *   .where((eb) => eb(eb.parens('age', '+', 1), '/', 100), '<', 0.1)
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -774,13 +865,14 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * You can also pass in any expression as the only argument:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const result = await db.selectFrom('person')
      *   .selectAll('person')
      *   .where((eb) => eb.parens(
-     *     eb('age', '=', 1).or('age', '=', 2))
+     *     eb('age', '=', 1).or('age', '=', 2)
      *   ).and(
      *     eb('first_name', '=', 'Jennifer').or('first_name', '=', 'Arnold')
      *   ))
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -802,12 +894,13 @@ export interface ExpressionBuilder<DB, TB extends keyof DB> {
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person')
+     * const result = await db.selectFrom('person')
      *   .select((eb) => [
      *     'id',
      *     'first_name',
      *     eb.cast<number>('age', 'integer').as('age')
      *   ])
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):