kysely 0.27.4 → 0.27.5

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

@@ -138,7 +138,7 @@ export class InsertQueryBuilder {
      *   .insertInto('person')
      *   .values(({ ref, selectFrom, fn }) => ({
      *     first_name: 'Jennifer',
-     *     last_name: sql<string>`>concat(${ani}, ${ston})`,
+     *     last_name: sql<string>`concat(${ani}, ${ston})`,
      *     middle_name: ref('first_name'),
      *     age: selectFrom('person')
      *       .select(fn.avg<number>('age').as('avg_age')),
@@ -166,7 +166,7 @@ export class InsertQueryBuilder {
      * You can also use the callback version of subqueries or raw expressions:
      *
      * ```ts
-     * db.with('jennifer', (db) => db
+     * await db.with('jennifer', (db) => db
      *   .selectFrom('person')
      *   .where('first_name', '=', 'Jennifer')
      *   .select(['id', 'first_name', 'gender'])
@@ -176,6 +176,24 @@ export class InsertQueryBuilder {
      *   name: eb.selectFrom('jennifer').select('first_name'),
      *   species: 'cat',
      * }))
+     * .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * with "jennifer" as (
+     *   select "id", "first_name", "gender"
+     *   from "person"
+     *   where "first_name" = $1
+     *   limit $2
+     * )
+     * insert into "pet" ("owner_id", "name", "species")
+     * values (
+     *  (select "id" from "jennifer"),
+     *  (select "first_name" from "jennifer"),
+     *  $3
+     * )
      * ```
      */
     values(insert) {
@@ -198,9 +216,10 @@ export class InsertQueryBuilder {
      * ### Examples
      *
      * ```ts
-     * db.insertInto('person')
+     * await db.insertInto('person')
      *   .columns(['first_name'])
      *   .expression((eb) => eb.selectFrom('pet').select('pet.name'))
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -268,6 +287,12 @@ export class InsertQueryBuilder {
      *   .defaultValues()
      *   .execute()
      * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" default values
+     * ```
      */
     defaultValues() {
         return new InsertQueryBuilder({
@@ -277,6 +302,37 @@ export class InsertQueryBuilder {
             }),
         });
     }
+    /**
+     * This can be used to add any additional SQL to the end of the query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * await db.insertInto('person')
+     *   .values({
+     *     first_name: 'John',
+     *     last_name: 'Doe',
+     *     gender: 'male',
+     *   })
+     *   .modifyEnd(sql`-- This is a comment`)
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * insert into `person` ("first_name", "last_name", "gender")
+     * values (?, ?, ?) -- This is a comment
+     * ```
+     */
+    modifyEnd(modifier) {
+        return new InsertQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithEndModifier(this.#props.queryNode, modifier.toOperationNode()),
+        });
+    }
     /**
      * Changes an `insert into` query to an `insert ignore into` query.
      *
@@ -294,9 +350,19 @@ export class InsertQueryBuilder {
      * ```ts
      * await db.insertInto('person')
      *   .ignore()
-     *   .values(values)
+     *   .values({
+     *     first_name: 'John',
+     *     last_name: 'Doe',
+     *     gender: 'female',
+     *   })
      *   .execute()
      * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * insert ignore into `person` ("first_name", "last_name", "gender") values (?, ?, ?)
+     * ```
      */
     ignore() {
         return new InsertQueryBuilder({
@@ -316,6 +382,8 @@ export class InsertQueryBuilder {
      * Insert the first 5 rows:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * await db.insertInto('person')
      *   .top(5)
      *   .columns(['first_name', 'gender'])
@@ -334,6 +402,8 @@ export class InsertQueryBuilder {
      * Insert the first 50 percent of rows:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * await db.insertInto('person')
      *   .top(50, 'percent')
      *   .columns(['first_name', 'gender'])
@@ -369,6 +439,7 @@ export class InsertQueryBuilder {
      *   .values({
      *     name: 'Catto',
      *     species: 'cat',
+     *     owner_id: 3,
      *   })
      *   .onConflict((oc) => oc
      *     .column('name')
@@ -380,10 +451,10 @@ export class InsertQueryBuilder {
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * insert into "pet" ("name", "species")
-     * values ($1, $2)
+     * insert into "pet" ("name", "species", "owner_id")
+     * values ($1, $2, $3)
      * on conflict ("name")
-     * do update set "species" = $3
+     * do update set "species" = $4
      * ```
      *
      * You can provide the name of the constraint instead of a column name:
@@ -394,6 +465,7 @@ export class InsertQueryBuilder {
      *   .values({
      *     name: 'Catto',
      *     species: 'cat',
+     *     owner_id: 3,
      *   })
      *   .onConflict((oc) => oc
      *     .constraint('pet_name_key')
@@ -405,10 +477,10 @@ export class InsertQueryBuilder {
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * insert into "pet" ("name", "species")
-     * values ($1, $2)
+     * insert into "pet" ("name", "species", "owner_id")
+     * values ($1, $2, $3)
      * on conflict on constraint "pet_name_key"
-     * do update set "species" = $3
+     * do update set "species" = $4
      * ```
      *
      * You can also specify an expression as the conflict target in case
@@ -422,6 +494,7 @@ export class InsertQueryBuilder {
      *   .values({
      *     name: 'Catto',
      *     species: 'cat',
+     *     owner_id: 3,
      *   })
      *   .onConflict((oc) => oc
      *     .expression(sql<string>`lower(name)`)
@@ -433,10 +506,10 @@ export class InsertQueryBuilder {
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * insert into "pet" ("name", "species")
-     * values ($1, $2)
+     * insert into "pet" ("name", "species", "owner_id")
+     * values ($1, $2, $3)
      * on conflict (lower(name))
-     * do update set "species" = $3
+     * do update set "species" = $4
      * ```
      *
      * You can add a filter for the update statement like this:
@@ -447,11 +520,12 @@ export class InsertQueryBuilder {
      *   .values({
      *     name: 'Catto',
      *     species: 'cat',
+     *     owner_id: 3,
      *   })
      *   .onConflict((oc) => oc
      *     .column('name')
      *     .doUpdateSet({ species: 'hamster' })
-     *     .where('excluded.name', '!=', 'Catto'')
+     *     .where('excluded.name', '!=', 'Catto')
      *   )
      *   .execute()
      * ```
@@ -459,11 +533,11 @@ export class InsertQueryBuilder {
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * insert into "pet" ("name", "species")
-     * values ($1, $2)
+     * insert into "pet" ("name", "species", "owner_id")
+     * values ($1, $2, $3)
      * on conflict ("name")
-     * do update set "species" = $3
-     * where "excluded"."name" != $4
+     * do update set "species" = $4
+     * where "excluded"."name" != $5
      * ```
      *
      * You can create an `on conflict do nothing` clauses like this:
@@ -474,6 +548,7 @@ export class InsertQueryBuilder {
      *   .values({
      *     name: 'Catto',
      *     species: 'cat',
+     *     owner_id: 3,
      *   })
      *   .onConflict((oc) => oc
      *     .column('name')
@@ -485,8 +560,8 @@ export class InsertQueryBuilder {
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * insert into "pet" ("name", "species")
-     * values ($1, $2)
+     * insert into "pet" ("name", "species", "owner_id")
+     * values ($1, $2, $3)
      * on conflict ("name") do nothing
      * ```
      *
@@ -495,8 +570,13 @@ export class InsertQueryBuilder {
      * `ExpressionBuilder`:
      *
      * ```ts
-     * db.insertInto('person')
-     *   .values(person)
+     * await db.insertInto('person')
+     *   .values({
+     *     id: 1,
+     *     first_name: 'John',
+     *     last_name: 'Doe',
+     *     gender: 'male',
+     *   })
      *   .onConflict(oc => oc
      *     .column('id')
      *     .doUpdateSet({
@@ -504,6 +584,18 @@ export class InsertQueryBuilder {
      *       last_name: (eb) => eb.ref('excluded.last_name')
      *     })
      *   )
+     *   .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"
      * ```
      */
     onConflict(callback) {
@@ -530,8 +622,22 @@ export class InsertQueryBuilder {
      * ```ts
      * await db
      *   .insertInto('person')
-     *   .values(values)
-     *   .onDuplicateKeyUpdate({ species: 'hamster' })
+     *   .values({
+     *     id: 1,
+     *     first_name: 'John',
+     *     last_name: 'Doe',
+     *     gender: 'male',
+     *   })
+     *   .onDuplicateKeyUpdate({ updated_at: new Date().toISOString() })
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * insert into `person` (`id`, `first_name`, `last_name`, `gender`)
+     * values (?, ?, ?, ?)
+     * on duplicate key update `updated_at` = ?
      * ```
      */
     onDuplicateKeyUpdate(update) {
@@ -572,16 +678,17 @@ export class InsertQueryBuilder {
      * ### Examples
      *
      * ```ts
-     * db.insertInto('person')
-     *   .values({ first_name: 'James', last_name: 'Smith', age: 42 })
+     * await db.insertInto('person')
+     *   .values({ first_name: 'James', last_name: 'Smith', gender: 'male' })
      *   .returning(['first_name'])
      *   .clearReturning()
+     *   .execute()
      * ```
      *
      * The generated SQL(PostgreSQL):
      *
      * ```sql
-     * insert into "person" ("James", "Smith", 42)
+     * insert into "person" ("first_name", "last_name", "gender") values ($1, $2, $3)
      * ```
      */
     clearReturning() {
@@ -602,13 +709,15 @@ export class InsertQueryBuilder {
      * The next example uses a helper function `log` to log a query:
      *
      * ```ts
+     * import type { Compilable } from 'kysely'
+     *
      * function log<T extends Compilable>(qb: T): T {
      *   console.log(qb.compile())
      *   return qb
      * }
      *
-     * db.updateTable('person')
-     *   .set(values)
+     * await db.insertInto('person')
+     *   .values({ first_name: 'John', last_name: 'Doe', gender: 'male' })
      *   .$call(log)
      *   .execute()
      * ```
@@ -629,7 +738,9 @@ export class InsertQueryBuilder {
      * ### Examples
      *
      * ```ts
-     * async function insertPerson(values: InsertablePerson, returnLastName: boolean) {
+     * import type { NewPerson } from 'type-editor' // imaginary module
+     *
+     * async function insertPerson(values: NewPerson, returnLastName: boolean) {
      *   return await db
      *     .insertInto('person')
      *     .values(values)
@@ -644,11 +755,11 @@ export class InsertQueryBuilder {
      * the code. In the example above the return type of the `insertPerson` function is:
      *
      * ```ts
-     * {
+     * Promise<{
      *   id: number
      *   first_name: string
      *   last_name?: string
-     * }
+     * }>
      * ```
      */
     $if(condition, func) {
@@ -686,23 +797,41 @@ export class InsertQueryBuilder {
      * Turn this code:
      *
      * ```ts
+     * import type { Person } from 'type-editor' // imaginary module
+     *
      * const person = await db.insertInto('person')
-     *   .values({ ...inputPerson, nullable_column: 'hell yeah!' })
+     *   .values({
+     *     first_name: 'John',
+     *     last_name: 'Doe',
+     *     gender: 'male',
+     *     nullable_column: 'hell yeah!'
+     *   })
      *   .returningAll()
      *   .executeTakeFirstOrThrow()
      *
-     * if (nullable_column) {
+     * if (isWithNoNullValue(person)) {
      *   functionThatExpectsPersonWithNonNullValue(person)
      * }
+     *
+     * function isWithNoNullValue(person: Person): person is Person & { nullable_column: string } {
+     *   return person.nullable_column != null
+     * }
      * ```
      *
      * Into this:
      *
      * ```ts
+     * import type { NotNull } from 'kysely'
+     *
      * const person = await db.insertInto('person')
-     *   .values({ ...inputPerson, nullable_column: 'hell yeah!' })
+     *   .values({
+     *     first_name: 'John',
+     *     last_name: 'Doe',
+     *     gender: 'male',
+     *     nullable_column: 'hell yeah!'
+     *   })
      *   .returningAll()
-     *   .$narrowType<{ nullable_column: string }>()
+     *   .$narrowType<{ nullable_column: NotNull }>()
      *   .executeTakeFirstOrThrow()
      *
      * functionThatExpectsPersonWithNonNullValue(person)
@@ -734,22 +863,29 @@ export class InsertQueryBuilder {
      * ### Examples
      *
      * ```ts
-     * const result = await db
-     *   .with('new_person', (qb) => qb
-     *     .insertInto('person')
-     *     .values(person)
-     *     .returning('id')
-     *     .$assertType<{ id: string }>()
-     *   )
-     *   .with('new_pet', (qb) => qb
-     *     .insertInto('pet')
-     *     .values((eb) => ({ owner_id: eb.selectFrom('new_person').select('id'), ...pet }))
-     *     .returning(['name as pet_name', 'species'])
-     *     .$assertType<{ pet_name: string, species: Species }>()
-     *   )
-     *   .selectFrom(['new_person', 'new_pet'])
-     *   .selectAll()
-     *   .executeTakeFirstOrThrow()
+     * import type { NewPerson, NewPet, Species } from 'type-editor' // imaginary module
+     *
+     * async function insertPersonAndPet(person: NewPerson, pet: Omit<NewPet, 'owner_id'>) {
+     *   return await db
+     *     .with('new_person', (qb) => qb
+     *       .insertInto('person')
+     *       .values(person)
+     *       .returning('id')
+     *       .$assertType<{ id: number }>()
+     *     )
+     *     .with('new_pet', (qb) => qb
+     *       .insertInto('pet')
+     *       .values((eb) => ({
+     *         owner_id: eb.selectFrom('new_person').select('id'),
+     *         ...pet
+     *       }))
+     *       .returning(['name as pet_name', 'species'])
+     *       .$assertType<{ pet_name: string, species: Species }>()
+     *     )
+     *     .selectFrom(['new_person', 'new_pet'])
+     *     .selectAll()
+     *     .executeTakeFirstOrThrow()
+     * }
      * ```
      */
     $assertType() {

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

@@ -13,12 +13,17 @@
  * ### Examples
  *
  * ```ts
- * const result = await db
- *   .insertInto('person')
- *   .values(person)
- *   .executeTakeFirst()
+ * import type { NewPerson } from 'type-editor' // imaginary module
  *
- * console.log(result.insertId)
+ * async function insertPerson(person: NewPerson) {
+ *   const result = await db
+ *     .insertInto('person')
+ *     .values(person)
+ *     .executeTakeFirstOrThrow()
+ *
+ *   console.log(result.insertId) // relevant on MySQL
+ *   console.log(result.numInsertedOrUpdatedRows) // always relevant
+ * }
  * ```
  */
 export declare class InsertResult {

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

@@ -14,12 +14,17 @@
  * ### Examples
  *
  * ```ts
- * const result = await db
- *   .insertInto('person')
- *   .values(person)
- *   .executeTakeFirst()
+ * import type { NewPerson } from 'type-editor' // imaginary module
  *
- * console.log(result.insertId)
+ * async function insertPerson(person: NewPerson) {
+ *   const result = await db
+ *     .insertInto('person')
+ *     .values(person)
+ *     .executeTakeFirstOrThrow()
+ *
+ *   console.log(result.insertId) // relevant on MySQL
+ *   console.log(result.numInsertedOrUpdatedRows) // always relevant
+ * }
  * ```
  */
 export class InsertResult {

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

@@ -18,9 +18,12 @@ export declare class JSONPathBuilder<S, O = S> {
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person').select(eb =>
-     *   eb.ref('nicknames', '->').at(0).as('primary_nickname')
-     * )
+     * await db.selectFrom('person')
+     *   .select(eb =>
+     *     eb.ref('nicknames', '->').at(0).as('primary_nickname')
+     *   )
+     *   .execute()
+     * ```
      *
      * The generated SQL (PostgreSQL):
      *
@@ -130,11 +133,19 @@ export declare class TraversedJSONPathBuilder<S, O> extends JSONPathBuilder<S, O
      * All expressions need to have this getter for complicated type-related reasons.
      * Simply add this getter for your expression and always return `undefined` from it:
      *
+     * ### Examples
+     *
      * ```ts
+     * import { type Expression, type OperationNode, sql } from 'kysely'
+     *
      * class SomeExpression<T> implements Expression<T> {
      *   get expressionType(): T | undefined {
      *     return undefined
      *   }
+     *
+     *   toOperationNode(): OperationNode {
+     *     return sql`some sql here`.toOperationNode()
+     *   }
      * }
      * ```
      *
@@ -163,7 +174,7 @@ export declare class TraversedJSONPathBuilder<S, O> extends JSONPathBuilder<S, O
      *
      * The generated SQL (PostgreSQL):
      *
-     * ```ts
+     * ```sql
      * select "first_name" = $1 as "is_jennifer"
      * from "person"
      * ```
@@ -172,6 +183,8 @@ export declare class TraversedJSONPathBuilder<S, O> extends JSONPathBuilder<S, O
     /**
      * Returns an aliased version of the expression.
      *
+     * ### Examples
+     *
      * In addition to slapping `as "the_alias"` at the end of the expression,
      * this method also provides strict typing:
      *
@@ -180,7 +193,7 @@ export declare class TraversedJSONPathBuilder<S, O> extends JSONPathBuilder<S, O
      *   .selectFrom('person')
      *   .select((eb) =>
      *     // `eb.fn<string>` returns an AliasableExpression<string>
-     *     eb.fn<string>('concat', ['first_name' eb.val(' '), 'last_name']).as('full_name')
+     *     eb.fn<string>('concat', ['first_name', eb.val(' '), 'last_name']).as('full_name')
      *   )
      *   .executeTakeFirstOrThrow()
      *
@@ -190,7 +203,7 @@ export declare class TraversedJSONPathBuilder<S, O> extends JSONPathBuilder<S, O
      *
      * The generated SQL (PostgreSQL):
      *
-     * ```ts
+     * ```sql
      * select
      *   concat("first_name", $1, "last_name") as "full_name"
      * from
@@ -201,6 +214,8 @@ export declare class TraversedJSONPathBuilder<S, O> extends JSONPathBuilder<S, O
      * provide the alias as the only type argument:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const values = sql<{ a: number, b: string }>`(values (1, 'foo'))`
      *
      * // The alias is `t(a, b)` which specifies the column names
@@ -215,11 +230,12 @@ export declare class TraversedJSONPathBuilder<S, O> extends JSONPathBuilder<S, O
      *   .expression(
      *     db.selectFrom(aliasedValues).select(['t.a', 't.b'])
      *   )
+     *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
      *
-     * ```ts
+     * ```sql
      * insert into "person" ("first_name", "last_name")
      * from (values (1, 'foo')) as t(a, b)
      * select "t"."a", "t"."b"
@@ -232,16 +248,24 @@ export declare class TraversedJSONPathBuilder<S, O> extends JSONPathBuilder<S, O
      * This method call doesn't change the SQL in any way. This methods simply
      * returns a copy of this `JSONPathBuilder` with a new output type.
      */
-    $castTo<C>(): JSONPathBuilder<C>;
-    $notNull(): JSONPathBuilder<Exclude<O, null>>;
+    $castTo<O2>(): TraversedJSONPathBuilder<S, O2>;
+    $notNull(): TraversedJSONPathBuilder<S, Exclude<O, null>>;
     /**
      * Creates the OperationNode that describes how to compile this expression into SQL.
      *
+     * ### Examples
+     *
      * If you are creating a custom expression, it's often easiest to use the {@link sql}
      * template tag to build the node:
      *
      * ```ts
+     * import { type Expression, type OperationNode, sql } from 'kysely'
+     *
      * class SomeExpression<T> implements Expression<T> {
+     *   get expressionType(): T | undefined {
+     *     return undefined
+     *   }
+     *
      *   toOperationNode(): OperationNode {
      *     return sql`some sql here`.toOperationNode()
      *   }

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

@@ -24,9 +24,12 @@ export class JSONPathBuilder {
      * ### Examples
      *
      * ```ts
-     * db.selectFrom('person').select(eb =>
-     *   eb.ref('nicknames', '->').at(0).as('primary_nickname')
-     * )
+     * await db.selectFrom('person')
+     *   .select(eb =>
+     *     eb.ref('nicknames', '->').at(0).as('primary_nickname')
+     *   )
+     *   .execute()
+     * ```
      *
      * The generated SQL (PostgreSQL):
      *
@@ -160,10 +163,10 @@ export class TraversedJSONPathBuilder extends JSONPathBuilder {
      * returns a copy of this `JSONPathBuilder` with a new output type.
      */
     $castTo() {
-        return new JSONPathBuilder(this.#node);
+        return new TraversedJSONPathBuilder(this.#node);
     }
     $notNull() {
-        return new JSONPathBuilder(this.#node);
+        return new TraversedJSONPathBuilder(this.#node);
     }
     toOperationNode() {
         return this.#node;