kysely 0.3.8 → 0.3.9

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

@@ -44,9 +44,11 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * Find a row by column value:
      *
      * ```ts
-     * db.selectFrom('person')
-     *   .where('id', '=', 100)
+     * const person = await db
+     *   .selectFrom('person')
      *   .selectAll()
+     *   .where('id', '=', 100)
+     *   .executeTakeFirst()
      * ```
      *
      * The generated SQL (postgresql):
@@ -60,9 +62,11 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * you can always use `db.raw('your operator')`.
      *
      * ```ts
-     * db.selectFrom('person')
-     *   .where('id', '>', 100)
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll()
+     *   .where('id', '>', 100)
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
@@ -72,22 +76,25 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * ```
      *
      * @example
-     * A `where in` query an be built by using the `in` operator and an array
-     * of values. The values in the array can also be subqueries or raw
-     * instances.
+     * The `where` methods don't change the type of the query. You can add
+     * conditional `where`s easily by doing something like this:
      *
      * ```ts
-     * db.selectFrom('person')
-     *   .where('person.id', 'in', [100, 200, 300])
+     * let query = db
+     *   .selectFrom('person')
      *   .selectAll()
-     * ```
      *
-     * The generated SQL (postgresql):
+     * if (firstName) {
+     *   query = query.where('first_name', '=', firstName)
+     * }
      *
-     * ```sql
-     * select * from "person" where "id" in ($1, $2, $3)
+     * const persons = await query.execute()
      * ```
      *
+     * This is true for basically all methods execpt the `select` and
+     * `returning` methods, which DO change the return type of the
+     * query.
+     *
      * @example
      * Both the first and third argument can also be subqueries.
      * A subquery is defined by passing a function and calling
@@ -95,15 +102,18 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * function:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
+     *   .selectAll()
      *   .where(
      *     (qb) => qb.subQuery('pet')
-     *       .select('pet.id')
-     *       .whereRef('pet.owner_id', '=', 'person.id'),
-     *     'in',
-     *     [100, 200, 300]
+     *       .select('pet.name')
+     *       .whereRef('pet.owner_id', '=', 'person.id')
+     *       .limit(1),
+     *     '=',
+     *     'Fluffy'
      *   )
-     *   .selectAll()
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
@@ -112,10 +122,30 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * select *
      * from "person"
      * where (
-     *   select "pet"."id"
+     *   select "pet"."name"
      *   from "pet"
      *   where "pet"."owner_id" = "person"."id"
-     * ) in ($1, $2, $3)
+     *   limit $1
+     * ) = $2
+     * ```
+     *
+     * @example
+     * A `where in` query can be built by using the `in` operator and an array
+     * of values. The values in the array can also be subqueries or raw
+     * instances.
+     *
+     * ```ts
+     * const persons = await db
+     *   .selectFrom('person')
+     *   .selectAll()
+     *   .where('person.id', 'in', [100, 200, 300])
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (postgresql):
+     *
+     * ```sql
+     * select * from "person" where "id" in ($1, $2, $3)
      * ```
      *
      * @example
@@ -123,20 +153,21 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * as any of the arguments, including the operator:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
+     *   .selectAll()
      *   .where(
      *     db.raw('coalesce(first_name, last_name)'),
      *     'like',
      *     '%' + name + '%',
      *   )
-     *   .selectAll()
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
      *
      * ```sql
-     * select *
-     * from "person"
+     * select * from "person"
      * where coalesce(first_name, last_name) like $1
      * ```
      *
@@ -145,12 +176,14 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * used to create parentheses around other where clauses:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll()
      *   .where((qb) => qb
      *     .where('id', '=', 1)
      *     .orWhere('id', '=', 2)
      *   )
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
@@ -174,10 +207,12 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * ```ts
      * const { ref } = db.dynamic
      *
-     * db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll()
      *   .where(ref(columnFromUserInput), '=', 1)
      *   .orWhere(db.raw('??', [columnFromUserInput]), '=', 2)
+     *   .execute()
      * ```
      */
     where<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: FilterOperator, rhs: ValueExpressionOrList<DB, TB, RE>): QueryBuilder<DB, TB, O>;
@@ -209,7 +244,8 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * Usage in a subquery:
      *
      * ```ts
-     * db.selectFrom('person)
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll('person')
      *   .select((qb) => qb
      *     .subQuery('pet')
@@ -218,6 +254,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *     .limit(1)
      *     .as('pet_name')
      *   )
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
@@ -227,8 +264,9 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   select "name"
      *   from "pet"
      *   where "pet"."owner_id" = "person"."id"
-     * ) as pet_name
-     * from "person"`
+     *   limit $1
+     * ) as "pet_name"
+     * from "person"
      */
     whereRef(lhs: ReferenceExpression<DB, TB>, op: FilterOperator, rhs: ReferenceExpression<DB, TB>): QueryBuilder<DB, TB, O>;
     /**
@@ -241,10 +279,12 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *
      * @example
      * ```ts
-     * db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll()
      *   .where('id', '=', 1)
      *   .orWhere('id', '=', 2)
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
@@ -257,12 +297,14 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * Grouping with parentheses:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll()
      *   .where((qb) => qb
      *     .where('id', '=', 1)
      *     .orWhere('id', '=', 2)
      *   )
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
@@ -276,12 +318,14 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * if you are looping through a set of conditions:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll()
      *   .where((qb) => qb
      *     .orWhere('id', '=', 1)
      *     .orWhere('id', '=', 2)
      *   )
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
@@ -308,7 +352,8 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * The query below selets all persons that own a pet named Catto:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll()
      *   .whereExists((qb) => qb
      *     .subQuery('pet')
@@ -316,6 +361,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *     .whereRef('person.id', '=', 'pet.owner_id')
      *     .where('pet.name', '=', 'Catto')
      *   )
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
@@ -414,14 +460,14 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
     /**
      * Adds a select clause to the query.
      *
-     * When a column (or any expression) is selected, Kysely also adds it to the return
-     * type of the query. Kysely is smart enough to parse the field names and types even
+     * When a column (or any expression) is selected, Kysely adds its type to the return
+     * type of the query. Kysely is smart enough to parse the column names and types even
      * from aliased columns, subqueries, raw expressions etc.
      *
      * Kysely only allows you to select columns and expressions that exist and would
      * produce valid SQL. However, Kysely is not perfect and there may be cases where
      * the type inference doesn't work and you need to override it. You can always
-     * use the {@link Kysely.dynamic | dynamic} object and {@link Kysely.raw | raw}
+     * use the {@link Kysely.dynamic | dynamic} module and {@link Kysely.raw | raw}
      * to override the types.
      *
      * Select calls are additive. Calling `select('id').select('first_name')` is the
@@ -434,28 +480,29 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * Select a single column:
      *
      * ```ts
-     * const [person] = await db.selectFrom('person')
+     * const persons = await db.selectFrom('person')
      *   .select('id')
+     *   .where('first_name', '=', 'Arnold')
      *   .execute()
      *
-     * person.id
+     * persons[0].id
      * ```
      *
      * The generated SQL (postgresql):
      *
      * ```sql
-     * select "id" from "person"
+     * select "id" from "person" where "first_name" = $1
      * ```
      *
      * @example
      * Select a single column and specify a table:
      *
      * ```ts
-     * const [person] = await db.selectFrom(['person', 'pet'])
+     * const persons = await db.selectFrom(['person', 'pet'])
      *   .select('person.id')
      *   .execute()
      *
-     * person.id
+     * persons[0].id
      * ```
      *
      * The generated SQL (postgresql):
@@ -468,12 +515,12 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * Select multiple columns:
      *
      * ```ts
-     * const [person] = await db.selectFrom('person')
+     * const persons = await db.selectFrom('person')
      *   .select(['person.id', 'first_name'])
      *   .execute()
      *
-     * person.id
-     * person.first_name
+     * persons[0].id
+     * persons[0].first_name
      * ```
      *
      * The generated SQL (postgresql):
@@ -483,18 +530,18 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * ```
      *
      * @example
-     * Giving an alias for a selection:
+     * Aliased selections:
      *
      * ```ts
-     * const [person] = await db.selectFrom('person')
+     * const persons = await db.selectFrom('person')
      *   .select([
      *     'person.first_name as fn',
      *     'person.last_name as ln'
      *   ])
      *   .execute()
      *
-     * person.fn
-     * person.ln
+     * persons[0].fn
+     * persons[0].ln
      * ```
      *
      * The generated SQL (postgresql):
@@ -512,19 +559,20 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * method:
      *
      * ```ts
-     * const [person] = await db.selectFrom('person')
+     * const persons = await db.selectFrom('person')
      *   .select([
      *     (qb) => qb
      *       .subQuery('pet')
      *       .whereRef('person.id', '=', 'pet.owner_id')
      *       .select('pet.name')
+     *       .limit(1)
      *       .as('pet_name')
      *     db.raw<string>("concat(first_name, ' ', last_name)").as('full_name')
      *   ])
      *   .execute()
      *
-     * person.pet_name
-     * person.full_name
+     * persons[0].pet_name
+     * persons[0].full_name
      * ```
      *
      * The generated SQL (postgresql):
@@ -535,7 +583,8 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *     select "pet"."name"
      *     from "pet"
      *     where "person"."id" = "pet"."owner_id"
-     *   ) as pet_name,
+     *     limit $1
+     *   ) as "pet_name",
      *   concat(first_name, ' ', last_name) as full_name
      * from "person"
      * ```
@@ -549,7 +598,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * the types) sometimes it's not possible or you just prefer to write more
      * dynamic code.
      * <br><br>
-     * In this example, we use the `dynamic` object's methods to add selections
+     * In this example, we use the `dynamic` module's methods to add selections
      * dynamically:
      *
      * ```ts
@@ -562,7 +611,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * // You can use `keyof Person` if any column of an interface is allowed.
      * type PossibleColumns = 'last_name' | 'first_name' | 'birth_date'
      *
-     * const [person] = await db.selectFrom('person')
+     * const spersons = await db.selectFrom('person')
      *   .select([
      *     ref<PossibleColumns>(columnFromUserInput)
      *     'id'
@@ -572,12 +621,12 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * // The resulting type contains all `PossibleColumns` as optional fields
      * // because we cannot know which field was actually selected before
      * // running the code.
-     * const lastName: string | undefined = person.last_name
-     * const firstName: string | undefined = person.first_name
-     * const birthDate: string | undefined = person.birth_date
+     * const lastName: string | undefined = persons[0].last_name
+     * const firstName: string | undefined = persons[0].first_name
+     * const birthDate: string | undefined = persons[0].birth_date
      *
      * // The result type also contains the compile time selection `id`.
-     * person.id
+     * persons[0].id
      * ```
      */
     select<S extends SelectExpression<DB, TB>>(selections: ReadonlyArray<S>): QueryBuilderWithSelection<DB, TB, O, S>;
@@ -585,6 +634,10 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
     /**
      * Adds `distinct on` selections to the select clause.
      *
+     * Takes the same inputs as the {@link QueryBuilder.select | select} method.
+     * See the {@link QueryBuilder.select | select} method's documentation for
+     * more examples.
+     *
      * @example
      * ```ts
      * await db.selectFrom('person')
@@ -653,7 +706,8 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *
      * @example
      * ```ts
-     * await db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll()
      *   .execute()
      * ```
@@ -666,7 +720,8 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *
      * @example
      * ```ts
-     * await db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll('person')
      *   .execute()
      * ```
@@ -679,7 +734,8 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *
      * @example
      * ```ts
-     * await db.selectFrom(['person', 'pet'])
+     * const personsPets = await db
+     *   .selectFrom(['person', 'pet'])
      *   .selectAll(['person', 'pet'])
      *   .execute()
      * ```
@@ -700,10 +756,17 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * Simple usage by providing a table name and two columns to join:
      *
      * ```ts
-     * await db.selectFrom('person')
+     * const result = await db
+     *   .selectFrom('person')
      *   .selectAll()
      *   .innerJoin('pet', 'pet.owner_id', 'person.id')
      *   .execute()
+     *
+     * // The result has all `Person` columns
+     * result[0].first_name
+     *
+     * // The result has all `Pet` columns
+     * result[0].species
      * ```
      *
      * The generated SQL (postgresql):
@@ -794,7 +857,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   select "owner_id", "name"
      *   from "pet"
      *   where "name" = $1
-     * ) as doggos
+     * ) as "doggos"
      * on "doggos"."owner_id" = "person"."id"
      * ```
      */
@@ -819,20 +882,24 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
     fullJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): QueryBuilderWithTable<DB, TB, O, TE>;
     fullJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): QueryBuilderWithTable<DB, TB, O, TE>;
     /**
-     * Sets the values to insert for an `insertInto` query.
+     * Sets the values to insert for an {@link Kysely.insertInto | insert} query.
      *
      * 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 `raw`
-     * instances, select queries or the {@link Kysely.generated} placeholder.
+     * 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.
      *
-     * You must provide all values defined by the interface to for the table you
+     * 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
-     * identifiers can be marked with the {@link Kysely.generated} placeholder.
+     * 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.
+     * 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.
      *
      * @example
      * Insert a row into `person`:
@@ -844,7 +911,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *     first_name: 'Jennifer',
      *     last_name: 'Aniston'
      *   })
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
      * ```
      *
      * The generated SQL (postgresql):
@@ -894,9 +961,9 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *     last_name: 'Aniston'
      *   })
      *   .returning('id')
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
      *
-     * row!.id
+     * row.id
      * ```
      *
      * The generated SQL (postgresql):
@@ -1016,7 +1083,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
     onConflictUpdate(column: AnyColumn<DB, TB>, updates: MutationObject<DB, TB>): QueryBuilder<DB, TB, O>;
     onConflictUpdate(columns: ReadonlyArray<AnyColumn<DB, TB>>, updates: MutationObject<DB, TB>): QueryBuilder<DB, TB, O>;
     /**
-     * Sets the values to update for an `updateTable` query.
+     * Sets the values to update for an {@link Kysely.updateTable | update} query.
      *
      * This method takes an object whose keys are column names and values are
      * values to update. In addition to the column's type, the values can be `raw`
@@ -1047,7 +1114,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * ```
      *
      * @example
-     * On postgresql you need to chain `returning` to the query to get
+     * On postgresql you ca chain `returning` to the query to get
      * the updated rows' columns (or any other expression) as the
      * return value:
      *
@@ -1060,7 +1127,7 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      *   })
      *   .where('id', '=', 1)
      *   .returning('id')
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
      *
      * row.id
      * ```

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

@@ -72,7 +72,8 @@ export class QueryBuilder {
      * Usage in a subquery:
      *
      * ```ts
-     * db.selectFrom('person)
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll('person')
      *   .select((qb) => qb
      *     .subQuery('pet')
@@ -81,6 +82,7 @@ export class QueryBuilder {
      *     .limit(1)
      *     .as('pet_name')
      *   )
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
@@ -90,8 +92,9 @@ export class QueryBuilder {
      *   select "name"
      *   from "pet"
      *   where "pet"."owner_id" = "person"."id"
-     * ) as pet_name
-     * from "person"`
+     *   limit $1
+     * ) as "pet_name"
+     * from "person"
      */
     whereRef(lhs, op, rhs) {
         ensureCanHaveWhereClause(this.#queryNode);
@@ -129,7 +132,8 @@ export class QueryBuilder {
      * The query below selets all persons that own a pet named Catto:
      *
      * ```ts
-     * db.selectFrom('person')
+     * const persons = await db
+     *   .selectFrom('person')
      *   .selectAll()
      *   .whereExists((qb) => qb
      *     .subQuery('pet')
@@ -137,6 +141,7 @@ export class QueryBuilder {
      *     .whereRef('person.id', '=', 'pet.owner_id')
      *     .where('pet.name', '=', 'Catto')
      *   )
+     *   .execute()
      * ```
      *
      * The generated SQL (postgresql):
@@ -449,7 +454,7 @@ export class QueryBuilder {
         });
     }
     /**
-     * Sets the values to update for an `updateTable` query.
+     * Sets the values to update for an {@link Kysely.updateTable | update} query.
      *
      * This method takes an object whose keys are column names and values are
      * values to update. In addition to the column's type, the values can be `raw`
@@ -480,7 +485,7 @@ export class QueryBuilder {
      * ```
      *
      * @example
-     * On postgresql you need to chain `returning` to the query to get
+     * On postgresql you ca chain `returning` to the query to get
      * the updated rows' columns (or any other expression) as the
      * return value:
      *
@@ -493,7 +498,7 @@ export class QueryBuilder {
      *   })
      *   .where('id', '=', 1)
      *   .returning('id')
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
      *
      * row.id
      * ```