kysely 0.9.8 → 0.11.0

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

@@ -10,7 +10,7 @@ import { QueryBuilderWithReturning } from '../parser/returning-parser.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
 import { ValueExpressionOrList } from '../parser/value-parser.js';
 import { QueryNode } from '../operation-node/query-node.js';
-import { AnyColumn, ManyResultRowType, NonEmptySingleResultRowType, SingleResultRowType } from '../util/type-utils.js';
+import { AnyColumn, SingleResultType } from '../util/type-utils.js';
 import { OrderByDirectionExpression, OrderByExpression } from '../parser/order-by-parser.js';
 import { MutationObject } from '../parser/update-set-parser.js';
 import { Compilable } from '../util/compilable.js';
@@ -54,7 +54,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .executeTakeFirst()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "person" where "id" = $1
@@ -72,7 +72,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "person" where "id" > $1
@@ -119,7 +119,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select *
@@ -145,7 +145,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "person" where "id" in ($1, $2, $3)
@@ -167,7 +167,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "person"
@@ -189,7 +189,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "person" (where "id" = 1 or "id" = 2)
@@ -237,7 +237,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .whereRef('person.first_name', '=', 'pet.name')
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "person", "pet" where "person"."first_name" = "pet"."name"
@@ -260,7 +260,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select "person".*, (
@@ -290,7 +290,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "person" where "id" = 1 or "id" = 2
@@ -310,7 +310,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "person" (where "id" = 1 or "id" = 2)
@@ -331,7 +331,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "person" (where "id" = 1 or "id" = 2)
@@ -367,7 +367,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "person"
@@ -393,7 +393,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   )
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "person"
@@ -491,7 +491,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * persons[0].id
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select "id" from "person" where "first_name" = $1
@@ -508,7 +508,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * persons[0].id
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select "person"."id" from "person", "pet"
@@ -526,7 +526,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * persons[0].first_name
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select "person"."id", "first_name" from "person"
@@ -547,7 +547,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * persons[0].ln
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select
@@ -578,7 +578,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * persons[0].full_name
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select
@@ -644,14 +644,14 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * @example
      * ```ts
      * await db.selectFrom('person')
-     *   .selectAll('person')
-     *   .distinctOn('person.id')
      *   .innerJoin('pet', 'pet.owner_id', 'person.id')
      *   .where('pet.name', '=', 'Doggo')
+     *   .distinctOn('person.id')
+     *   .selectAll('person')
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select distinct on ("person"."id") "person".*
@@ -673,7 +673,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select distinct "first_name" from "person"
@@ -715,7 +715,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "person"
@@ -729,7 +729,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select "person".* from "person"
@@ -743,7 +743,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select "person".*, "pet".* from "person", "pet"
@@ -761,21 +761,20 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * ```ts
      * const result = await db
      *   .selectFrom('person')
-     *   .selectAll()
      *   .innerJoin('pet', 'pet.owner_id', 'person.id')
+     *   // `select` needs to come after the call to `innerJoin` so
+     *   // that you can select from the joined table.
+     *   .select('person.id', 'pet.name')
      *   .execute()
      *
-     * // The result has all `Person` columns
-     * result[0].first_name
-     *
-     * // The result has all `Pet` columns
-     * result[0].species
+     * result[0].id
+     * result[0].name
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * select *
+     * select "person"."id", "pet"."name"
      * from "person"
      * inner join "pet"
      * on "pet"."owner_id" = "person"."id"
@@ -786,13 +785,13 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *
      * ```ts
      * await db.selectFrom('person')
-     *   .selectAll()
      *   .innerJoin('pet as p', 'p.owner_id', 'person.id')
      *   .where('p.name', '=', 'Doggo')
+     *   .selectAll()
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select *
@@ -813,17 +812,17 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *
      * ```ts
      * await db.selectFrom('person')
-     *   .selectAll()
      *   .innerJoin(
      *     'pet',
      *     (join) => join
      *       .onRef('pet.owner_id', '=', 'person.id')
      *       .on('pet.name', '=', 'Doggo')
      *   )
+     *   .selectAll()
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select *
@@ -839,7 +838,6 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *
      * ```ts
      * await db.selectFrom('person')
-     *   .selectAll()
      *   .innerJoin(
      *     (qb) => qb.subQuery('pet')
      *       .select(['owner_id', 'name'])
@@ -848,10 +846,11 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *     'doggos.owner_id',
      *     'person.id',
      *   )
+     *   .selectAll()
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select *
@@ -890,19 +889,19 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * This method takes an object whose keys are column names and values are
      * values to insert. In addition to the column's type, the values can be
      * {@link Kysely.raw | raw} instances, select queries or the
-     * {@link Kysely.generated} placeholder.
+     * {@link Kysely.generated | generated} placeholder.
      *
-     * You must provide all values defined by the interface for the table you
-     * are inserting into. Values that are generated by the database like autoincrementing
+     * You must provide all values defined by the interface of the table you
+     * are inserting into. Values that are generated by the database like auto incrementing
      * identifiers can be marked with the {@link Kysely.generated} placeholder unless you
      * want to insert a specific value instead of the generated default.
      *
-     * The return value is the primary key of the inserted row BUT on some databases
-     * there is no return value by default. That's the reason for the `number | undefined`
-     * type of the return value. On postgres you need to additionally call `returning` to get
-     * something out of the query. If you know your database engine always returns the primary
-     * key, you can use the {@link QueryBuilder.executeTakeFirstOrThrow | executeTakeFirstOrThrow}
-     * method to execute the query.
+     * The return value of an `insert` query is an instance of {@link InsertResult}. The
+     * {@link InsertResult.insertId | insertId} field holds the auto incremented primary
+     * key if the database returned one.
+     *
+     * On PostgreSQL and some other dialects, you need to call `returning` to get
+     * something out of the query.
      *
      * @example
      * Insert a row into `person`:
@@ -917,16 +916,16 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .executeTakeFirstOrThrow()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * insert into "person" ("first_name", "last_name") values ($1, $2)
      * ```
      *
      * @example
-     * On dialects that support it (for example postgres) you can insert multiple
+     * On dialects that support it (for example PostgreSQL) you can insert multiple
      * rows by providing an array. Note that the return value is once again very
-     * dialect-specific. Some databases may only return the id of the *first* inserted
+     * dialect-specific. Some databases may only return the id of the *last* inserted
      * row and some return nothing at all unless you call `returning`.
      *
      * ```ts
@@ -944,7 +943,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * insert into "person" ("first_name", "last_name") values (($1, $2), ($3, $4))
@@ -969,7 +968,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * row.id
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * insert into "person" ("first_name", "last_name") values ($1, $2) returning "id"
@@ -980,7 +979,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * select queries:
      *
      * ```ts
-     * const maybeId = await db
+     * const result = await db
      *   .insertInto('person')
      *   .values({
      *     id: db.generated,
@@ -989,9 +988,11 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *     age: db.selectFrom('person').select(raw('avg(age)')),
      *   })
      *   .executeTakeFirst()
+     *
+     * console.log(result.insertId)
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * insert into "person" ("first_name", "last_name", "age")
@@ -1010,7 +1011,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * database, calling `onConflictDoNothing('name')` will ignore the conflict
      * and do nothing. By default the query would throw.
      *
-     * Only some dialects like postgres and sqlite implement the `on conflict`
+     * Only some dialects like PostgreSQL and SQLite implement the `on conflict`
      * statement. On MySQL you should use the {@link ignore} method to achieve
      * similar results.
      *
@@ -1030,7 +1031,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * insert into "pet" ("name", "species")
@@ -1055,7 +1056,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * insert into "pet" ("name", "species")
@@ -1104,7 +1105,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * method accepts.
      *
      * The `on conflict do update` statement is only implemented by some dialects
-     * like postgres and sqlite. On MySQL you should use the {@link onDuplicateKeyUpdate}
+     * like PostgreSQL and SQLite. On MySQL you should use the {@link onDuplicateKeyUpdate}
      * method instead.
      *
      * Also see the {@link QueryBuilder.onConflictDoNothing | onConflictDoNothing}
@@ -1123,7 +1124,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * insert into "pet" ("name", "species")
@@ -1149,7 +1150,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * insert into "pet" ("name", "species")
@@ -1186,15 +1187,15 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * values to update. In addition to the column's type, the values can be `raw`
      * instances or select queries.
      *
-     * The return value is the number of affected rows. You can use the
-     * {@link QueryBuilder.returning | returning} method on supported databases
-     * to get out the updated rows.
+     * The return value of an update query is an instance of {@link UpdateResult}.
+     * You can use the {@link QueryBuilder.returning | returning} method on
+     * supported databases to get out the updated rows.
      *
      * @example
      * Update a row in `person` table:
      *
      * ```ts
-     * const numAffectedRows = await db
+     * const result = await db
      *   .updateTable('person')
      *   .set({
      *     first_name: 'Jennifer',
@@ -1202,9 +1203,11 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   })
      *   .where('id', '=', 1)
      *   .executeTakeFirst()
+     *
+     * console.log(result.numUpdatedRows)
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * update "person" set "first_name" = $1, "last_name" = $2 where "id" = $3
@@ -1229,7 +1232,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * row.id
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * update "person" set "first_name" = $1, "last_name" = $2 where "id" = $3 returning "id"
@@ -1240,7 +1243,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * select queries:
      *
      * ```ts
-     * const numAffectedRows = await db
+     * const result = await db
      *   .updateTable('person')
      *   .set({
      *     first_name: 'Jennifer',
@@ -1249,9 +1252,11 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   })
      *   .where('id', '=', 1)
      *   .executeTakeFirst()
+     *
+     * console.log(result.numUpdatedRows)
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * update "person" set
@@ -1265,9 +1270,13 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
     /**
      * Allows you to return data from modified rows.
      *
-     * On supported databases like postgres, this method can be chained to
+     * On supported databases like PostgreSQL, this method can be chained to
      * `insert`, `update` and `delete` 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.
+     * For example `.returning('id as id')`.
+     *
      * Also see the {@link QueryBuilder.returningAll | returningAll} method.
      *
      * @example
@@ -1314,6 +1323,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *     last_name: 'Aniston'
      *   })
      *   .returning([
+     *     'id as id',
      *     raw<string>(`concat(first_name, ' ', last_name)`).as('full_name'),
      *     (qb) => qb.subQuery('pets').select('pet.id').limit(1).as('first_pet_id')
      *   ])
@@ -1324,7 +1334,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
     returning<S extends SelectExpression<DB, TB>>(selection: S): QueryBuilderWithReturning<DB, TB, O, S>;
     /**
      * Adds a `returning *` to an insert/update/delete query on databases
-     * that support `returning` such as postgres.
+     * that support `returning` such as PostgreSQL.
      */
     returningAll(): QueryBuilder<DB, TB, DB[TB]>;
     /**
@@ -1346,7 +1356,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select "person"."first_name" as "fn"
@@ -1373,7 +1383,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select *
@@ -1405,7 +1415,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * someQuery('fn')
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select "person"."first_name" as "fn"
@@ -1429,7 +1439,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select "first_name", max(id)
@@ -1457,7 +1467,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select "first_name", "last_name", max(id)
@@ -1504,7 +1514,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * someQuery('first_name')
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select "first_name"
@@ -1648,12 +1658,12 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *
      * Also see the {@link executeTakeFirst} and {@link executeTakeFirstOrThrow} methods.
      */
-    execute(): Promise<ManyResultRowType<O>[]>;
+    execute(): Promise<O[]>;
     /**
      * Executes the query and returns the first result or undefined if
      * the query returned no result.
      */
-    executeTakeFirst(): Promise<SingleResultRowType<O>>;
+    executeTakeFirst(): Promise<SingleResultType<O>>;
     /**
      * Executes the query and returns the first result or throws if
      * the query returned no result.
@@ -1662,7 +1672,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * provide a custom error class as the only argument to throw a different
      * error.
      */
-    executeTakeFirstOrThrow(errorConstructor?: NoResultErrorConstructor): Promise<NonEmptySingleResultRowType<O>>;
+    executeTakeFirstOrThrow(errorConstructor?: NoResultErrorConstructor): Promise<O>;
 }
 export interface QueryBuilderProps {
     readonly queryId: QueryId;