kysely 0.27.4 → 0.27.5

package/dist/esm/query-compiler/default-query-compiler.js

@@ -202,6 +202,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         if (isSubQuery && !MergeQueryNode.is(rootQueryNode)) {
             this.append(')');
         }
+        if (node.endModifiers?.length) {
+            this.append(' ');
+            this.compileList(node.endModifiers, ' ');
+        }
     }
     visitValues(node) {
         this.append('values ');
@@ -257,6 +261,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         if (isSubQuery) {
             this.append(')');
         }
+        if (node.endModifiers?.length) {
+            this.append(' ');
+            this.compileList(node.endModifiers, ' ');
+        }
     }
     visitReturning(node) {
         this.append('returning ');
@@ -556,6 +564,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         if (isSubQuery && !MergeQueryNode.is(rootQueryNode)) {
             this.append(')');
         }
+        if (node.endModifiers?.length) {
+            this.append(' ');
+            this.compileList(node.endModifiers, ' ');
+        }
     }
     visitColumnUpdate(node) {
         this.visitNode(node.column);
@@ -971,6 +983,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.append('distinct ');
         }
         this.compileList(node.aggregated);
+        if (node.orderBy) {
+            this.append(' ');
+            this.visitNode(node.orderBy);
+        }
         this.append(')');
         if (node.filter) {
             this.append(' filter(');
@@ -1113,6 +1129,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.append(' ');
             this.visitNode(node.output);
         }
+        if (node.endModifiers?.length) {
+            this.append(' ');
+            this.compileList(node.endModifiers, ' ');
+        }
     }
     visitMatched(node) {
         if (node.not) {

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

@@ -141,20 +141,19 @@ export declare class QueryCreator<DB> {
      * ### Examples
      *
      * ```ts
-     * const result = db.selectNoFrom((eb) => [
+     * const result = await db.selectNoFrom((eb) => [
      *   eb.selectFrom('person')
      *     .select('id')
      *     .where('first_name', '=', 'Jennifer')
      *     .limit(1)
      *     .as('jennifer_id'),
-     *
      *   eb.selectFrom('pet')
      *     .select('id')
      *     .where('name', '=', 'Doggo')
      *     .limit(1)
      *     .as('doggo_id')
-     *   ])
-     *   .executeTakeFirstOrThrow()
+     * ])
+     * .executeTakeFirstOrThrow()
      *
      * console.log(result.jennifer_id)
      * console.log(result.doggo_id)
@@ -214,7 +213,7 @@ export declare class QueryCreator<DB> {
      *     last_name: 'Aniston'
      *   })
      *   .returning('id')
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
      * ```
      */
     insertInto<T extends keyof DB & string>(table: T): InsertQueryBuilder<DB, T, InsertResult>;
@@ -262,7 +261,7 @@ export declare class QueryCreator<DB> {
      * ```ts
      * const result = await db
      *   .deleteFrom('person')
-     *   .where('person.id', '=', '1')
+     *   .where('person.id', '=', 1)
      *   .executeTakeFirst()
      *
      * console.log(result.numDeletedRows)
@@ -280,7 +279,7 @@ export declare class QueryCreator<DB> {
      * const result = await db
      *   .deleteFrom(['person', 'pet'])
      *   .using('person')
-     *   .innerJoin('pet', 'pet.owner_id', '=', 'person.id')
+     *   .innerJoin('pet', 'pet.owner_id', 'person.id')
      *   .where('person.id', '=', 1)
      *   .executeTakeFirst()
      * ```
@@ -334,14 +333,18 @@ export declare class QueryCreator<DB> {
      *
      * ### Examples
      *
+     * <!-- siteExample("merge", "Source row existence", 10) -->
+     *
+     * Update a target column based on the existence of a source row:
+     *
      * ```ts
      * const result = await db
-     *   .mergeInto('person')
-     *   .using('pet', 'pet.owner_id', 'person.id')
-     *   .whenMatched((and) => and('has_pets', '!=', 'Y'))
+     *   .mergeInto('person as target')
+     *   .using('pet as source', 'source.owner_id', 'target.id')
+     *   .whenMatchedAnd('target.has_pets', '!=', 'Y')
      *   .thenUpdateSet({ has_pets: 'Y' })
-     *   .whenNotMatched()
-     *   .thenDoNothing()
+     *   .whenNotMatchedBySourceAnd('target.has_pets', '=', 'Y')
+     *   .thenUpdateSet({ has_pets: 'N' })
      *   .executeTakeFirstOrThrow()
      *
      * console.log(result.numChangedRows)
@@ -351,11 +354,56 @@ export declare class QueryCreator<DB> {
      *
      * ```sql
      * merge into "person"
-     * using "pet" on "pet"."owner_id" = "person"."id"
-     * when matched and "has_pets" != $1 then
-     *   update set "has_pets" = $2
-     * when not matched then
-     *   do nothing
+     * using "pet"
+     * on "pet"."owner_id" = "person"."id"
+     * when matched and "has_pets" != $1
+     * then update set "has_pets" = $2
+     * when not matched by source and "has_pets" = $3
+     * then update set "has_pets" = $4
+     * ```
+     *
+     * <!-- siteExample("merge", "Temporary changes table", 20) -->
+     *
+     * Merge new entries from a temporary changes table:
+     *
+     * ```ts
+     * const result = await db
+     *   .mergeInto('wine as target')
+     *   .using(
+     *     'wine_stock_change as source',
+     *     'source.wine_name',
+     *     'target.name',
+     *   )
+     *   .whenNotMatchedAnd('source.stock_delta', '>', 0)
+     *   .thenInsertValues(({ ref }) => ({
+     *     name: ref('source.wine_name'),
+     *     stock: ref('source.stock_delta'),
+     *   }))
+     *   .whenMatchedAnd(
+     *     (eb) => eb('target.stock', '+', eb.ref('source.stock_delta')),
+     *     '>',
+     *     0,
+     *   )
+     *   .thenUpdateSet('stock', (eb) =>
+     *     eb('target.stock', '+', eb.ref('source.stock_delta')),
+     *   )
+     *   .whenMatched()
+     *   .thenDelete()
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * merge into "wine" as "target"
+     * using "wine_stock_change" as "source"
+     * on "source"."wine_name" = "target"."name"
+     * when not matched and "source"."stock_delta" > $1
+     * then insert ("name", "stock") values ("source"."wine_name", "source"."stock_delta")
+     * when matched and "target"."stock" + "source"."stock_delta" > $2
+     * then update set "stock" = "target"."stock" + "source"."stock_delta"
+     * when matched
+     * then delete
      * ```
      */
     mergeInto<TR extends keyof DB & string>(targetTable: TR): MergeQueryBuilder<DB, TR, MergeResult>;
@@ -498,7 +546,7 @@ export declare class QueryCreator<DB> {
      * This only affects the query created through the builder returned from
      * this method and doesn't modify the `db` instance.
      *
-     * See [this recipe](https://github.com/koskimas/kysely/tree/master/site/docs/recipes/schemas.md)
+     * See [this recipe](https://github.com/kysely-org/kysely/blob/master/site/docs/recipes/0007-schemas.md)
      * for a more detailed explanation.
      *
      * ### Examples

package/dist/esm/query-creator.js

@@ -70,7 +70,7 @@ export class QueryCreator {
      *     last_name: 'Aniston'
      *   })
      *   .returning('id')
-     *   .executeTakeFirst()
+     *   .executeTakeFirstOrThrow()
      * ```
      */
     insertInto(table) {
@@ -298,7 +298,7 @@ export class QueryCreator {
      * This only affects the query created through the builder returned from
      * this method and doesn't modify the `db` instance.
      *
-     * See [this recipe](https://github.com/koskimas/kysely/tree/master/site/docs/recipes/schemas.md)
+     * See [this recipe](https://github.com/kysely-org/kysely/blob/master/site/docs/recipes/0007-schemas.md)
      * for a more detailed explanation.
      *
      * ### Examples

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

@@ -20,6 +20,8 @@ export interface RawBuilder<O> extends AliasableExpression<O> {
      * this method also provides strict typing:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const result = await db
      *   .selectFrom('person')
      *   .select(
@@ -33,7 +35,7 @@ export interface RawBuilder<O> extends AliasableExpression<O> {
      *
      * The generated SQL (PostgreSQL):
      *
-     * ```ts
+     * ```sql
      * select concat(first_name, ' ', last_name) as "full_name"
      * from "person"
      * ```
@@ -42,6 +44,8 @@ export interface RawBuilder<O> extends AliasableExpression<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
@@ -56,11 +60,12 @@ export interface RawBuilder<O> extends AliasableExpression<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"
@@ -70,6 +75,8 @@ export interface RawBuilder<O> extends AliasableExpression<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:
      *
@@ -78,7 +85,7 @@ export interface RawBuilder<O> extends AliasableExpression<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()
      *
@@ -88,7 +95,7 @@ export interface RawBuilder<O> extends AliasableExpression<O> {
      *
      * The generated SQL (PostgreSQL):
      *
-     * ```ts
+     * ```sql
      * select
      *   concat("first_name", $1, "last_name") as "full_name"
      * from
@@ -99,6 +106,8 @@ export interface RawBuilder<O> extends AliasableExpression<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
@@ -113,11 +122,12 @@ export interface RawBuilder<O> extends AliasableExpression<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"
@@ -151,8 +161,10 @@ export interface RawBuilder<O> extends AliasableExpression<O> {
      * ### Examples
      *
      * ```ts
-     * const { sql } = sql`select * from ${sql.table('person')}`.compile(db)
-     * console.log(sql)
+     * import { sql } from 'kysely'
+     *
+     * const compiledQuery = sql`select * from ${sql.table('person')}`.compile(db)
+     * console.log(compiledQuery.sql)
      * ```
      */
     compile(executorProvider: QueryExecutorProvider): CompiledQuery<O>;
@@ -162,6 +174,8 @@ export interface RawBuilder<O> extends AliasableExpression<O> {
      * ### Examples
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const result = await sql`select * from ${sql.table('person')}`.execute(db)
      * ```
      */
@@ -169,11 +183,19 @@ export interface RawBuilder<O> extends AliasableExpression<O> {
     /**
      * 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/raw-builder/sql.d.ts

@@ -5,6 +5,7 @@ export interface Sql {
      *
      * ```ts
      * import { sql } from 'kysely'
+     * import type { Person } from 'type-editor' // imaginary module
      *
      * const id = 123
      * const snippet = sql<Person[]>`select * from person where id = ${id}`
@@ -26,6 +27,12 @@ export interface Sql {
      * of methods:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const nicknames = ['johnny', 'john', 'jon']
+     * const date1 = new Date('2000-01-01')
+     * const date2 = new Date('2001-01-01')
+     *
      * const persons = await db
      *   .selectFrom('person')
      *   .select(
@@ -56,19 +63,24 @@ export interface Sql {
      * instance as the only argument:
      *
      * ```ts
-     * const result = await sql<Person[]>`select * from person`.execute(db)
+     * import { sql } from 'kysely'
+     * import type { Person } from 'type-editor'
+     *
+     * const { rows: results } = await sql<Person[]>`select * from person`.execute(db)
      * ```
      *
      * You can merge other `sql` expressions and queries using substitutions:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const petName = db.selectFrom('pet').select('name').limit(1)
      * const fullName = sql<string>`concat(first_name, ' ', last_name)`
      *
-     * sql`
+     * sql<{ full_name: string; pet_name: string }[]>`
      *   select ${fullName} as full_name, ${petName} as pet_name
      *   from person
-     * `
+     * `.execute(db)
      * ```
      *
      * Substitutions also handle {@link ExpressionBuilder.ref},
@@ -101,6 +113,11 @@ export interface Sql {
      * `sql.val(value)` is a shortcut for:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const value = 123
+     * type ValueType = typeof value
+     *
      * sql<ValueType>`${value}`
      * ```
      */
@@ -131,7 +148,7 @@ export interface Sql {
      * select "first_name" from person
      * ```
      *
-     * The refefences can also include a table name:
+     * The references can also include a table name:
      *
      * ```ts
      * const columnRef = 'person.first_name'
@@ -145,7 +162,7 @@ export interface Sql {
      * select "person"."first_name" from person
      * ```
      *
-     * The refefences can also include a schema on supported databases:
+     * The references can also include a schema on supported databases:
      *
      * ```ts
      * const columnRef = 'public.person.first_name'
@@ -204,7 +221,7 @@ export interface Sql {
      * but can also be used for any other identifiers like index names.
      *
      * You should use {@link Sql.ref | ref} and {@link Sql.table | table}
-     * instead of this whenever possible as they produce a more sematic
+     * instead of this whenever possible as they produce a more semantic
      * operation node tree.
      *
      * WARNING! Using this with unchecked inputs WILL lead to SQL injection
@@ -229,7 +246,7 @@ export interface Sql {
      * const columnName = 'first_name'
      * const table = 'person'
      *
-     * sql`select ${sql.id(schema, table, columnName)}} from ${sql.id(schema, table)}`
+     * sql`select ${sql.id(schema, table, columnName)} from ${sql.id(schema, table)}`
      * ```
      *
      * The generated SQL (PostgreSQL):
@@ -297,6 +314,8 @@ export interface Sql {
      * ### Examples
      *
      * ```ts
+     * import type { Person } from 'type-editor' // imaginary module
+     *
      * function findByNicknames(nicknames: string[]): Promise<Person[]> {
      *   return db
      *     .selectFrom('person')

package/dist/esm/schema/alter-column-builder.d.ts

@@ -19,14 +19,28 @@ export declare class AlterColumnBuilder {
 /**
  * Allows us to force consumers to do exactly one alteration to a column.
  *
- * Basically, deny the following:
+ * One cannot do no alterations:
  *
  * ```ts
- * db.schema.alterTable('person').alterColumn('age', (ac) => ac)
+ * await db.schema
+ *   .alterTable('person')
+ * //  .execute() // Property 'execute' does not exist on type 'AlteredColumnBuilder'.
  * ```
  *
  * ```ts
- * db.schema.alterTable('person').alterColumn('age', (ac) => ac.dropNotNull().setNotNull())
+ * await db.schema
+ *   .alterTable('person')
+ * //  .alterColumn('age', (ac) => ac) // Type 'AlterColumnBuilder' is not assignable to type 'AlteredColumnBuilder'.
+ * //  .execute()
+ * ```
+ *
+ * One cannot do multiple alterations:
+ *
+ * ```ts
+ * await db.schema
+ *   .alterTable('person')
+ * //  .alterColumn('age', (ac) => ac.dropNotNull().setNotNull()) // Property 'setNotNull' does not exist on type 'AlteredColumnBuilder'.
+ * //  .execute()
  * ```
  *
  * Which would now throw a compilation error, instead of a runtime error.

package/dist/esm/schema/alter-column-builder.js

@@ -35,14 +35,28 @@ preventAwait(AlterColumnBuilder, "don't await AlterColumnBuilder instances");
 /**
  * Allows us to force consumers to do exactly one alteration to a column.
  *
- * Basically, deny the following:
+ * One cannot do no alterations:
  *
  * ```ts
- * db.schema.alterTable('person').alterColumn('age', (ac) => ac)
+ * await db.schema
+ *   .alterTable('person')
+ * //  .execute() // Property 'execute' does not exist on type 'AlteredColumnBuilder'.
  * ```
  *
  * ```ts
- * db.schema.alterTable('person').alterColumn('age', (ac) => ac.dropNotNull().setNotNull())
+ * await db.schema
+ *   .alterTable('person')
+ * //  .alterColumn('age', (ac) => ac) // Type 'AlterColumnBuilder' is not assignable to type 'AlteredColumnBuilder'.
+ * //  .execute()
+ * ```
+ *
+ * One cannot do multiple alterations:
+ *
+ * ```ts
+ * await db.schema
+ *   .alterTable('person')
+ * //  .alterColumn('age', (ac) => ac.dropNotNull().setNotNull()) // Property 'setNotNull' does not exist on type 'AlteredColumnBuilder'.
+ * //  .execute()
  * ```
  *
  * Which would now throw a compilation error, instead of a runtime error.

package/dist/esm/schema/alter-table-add-index-builder.d.ts

@@ -12,6 +12,23 @@ export declare class AlterTableAddIndexBuilder implements OperationNodeSource, C
     constructor(props: AlterTableAddIndexBuilderProps);
     /**
      * Makes the index unique.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.schema
+     *   .alterTable('person')
+     *   .addIndex('person_first_name_index')
+     *   .unique()
+     *   .column('email')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * alter table `person` add unique index `person_first_name_index` (`email`)
+     * ```
      */
     unique(): AlterTableAddIndexBuilder;
     /**
@@ -24,11 +41,11 @@ export declare class AlterTableAddIndexBuilder implements OperationNodeSource, C
      *
      * ```ts
      * await db.schema
-     *         .alterTable('person')
-     *         .createIndex('person_first_name_and_age_index')
-     *         .column('first_name')
-     *         .column('age desc')
-     *         .execute()
+     *   .alterTable('person')
+     *   .addIndex('person_first_name_and_age_index')
+     *   .column('first_name')
+     *   .column('age desc')
+     *   .execute()
      * ```
      *
      * The generated SQL (MySQL):
@@ -48,10 +65,10 @@ export declare class AlterTableAddIndexBuilder implements OperationNodeSource, C
      *
      * ```ts
      * await db.schema
-     *         .alterTable('person')
-     *         .addIndex('person_first_name_and_age_index')
-     *         .columns(['first_name', 'age desc'])
-     *         .execute()
+     *   .alterTable('person')
+     *   .addIndex('person_first_name_and_age_index')
+     *   .columns(['first_name', 'age desc'])
+     *   .execute()
      * ```
      *
      * The generated SQL (MySQL):
@@ -85,6 +102,23 @@ export declare class AlterTableAddIndexBuilder implements OperationNodeSource, C
     expression(expression: Expression<any>): AlterTableAddIndexBuilder;
     /**
      * Specifies the index type.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.schema
+     *   .alterTable('person')
+     *   .addIndex('person_first_name_index')
+     *   .column('first_name')
+     *   .using('hash')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * alter table `person` add index `person_first_name_index` (`first_name`) using hash
+     * ```
      */
     using(indexType: IndexType): AlterTableAddIndexBuilder;
     using(indexType: string): AlterTableAddIndexBuilder;

package/dist/esm/schema/alter-table-add-index-builder.js

@@ -12,6 +12,23 @@ export class AlterTableAddIndexBuilder {
     }
     /**
      * Makes the index unique.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.schema
+     *   .alterTable('person')
+     *   .addIndex('person_first_name_index')
+     *   .unique()
+     *   .column('email')
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * alter table `person` add unique index `person_first_name_index` (`email`)
+     * ```
      */
     unique() {
         return new AlterTableAddIndexBuilder({
@@ -33,11 +50,11 @@ export class AlterTableAddIndexBuilder {
      *
      * ```ts
      * await db.schema
-     *         .alterTable('person')
-     *         .createIndex('person_first_name_and_age_index')
-     *         .column('first_name')
-     *         .column('age desc')
-     *         .execute()
+     *   .alterTable('person')
+     *   .addIndex('person_first_name_and_age_index')
+     *   .column('first_name')
+     *   .column('age desc')
+     *   .execute()
      * ```
      *
      * The generated SQL (MySQL):
@@ -66,10 +83,10 @@ export class AlterTableAddIndexBuilder {
      *
      * ```ts
      * await db.schema
-     *         .alterTable('person')
-     *         .addIndex('person_first_name_and_age_index')
-     *         .columns(['first_name', 'age desc'])
-     *         .execute()
+     *   .alterTable('person')
+     *   .addIndex('person_first_name_and_age_index')
+     *   .columns(['first_name', 'age desc'])
+     *   .execute()
      * ```
      *
      * The generated SQL (MySQL):