kysely 0.27.3 → 0.27.5

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

@@ -119,15 +119,17 @@ export class UpdateQueryBuilder {
      * Update the first 2 rows in the 'person' table:
      *
      * ```ts
-     * return await db
+     * await db
      *   .updateTable('person')
      *   .set({ first_name: 'Foo' })
-     *   .limit(2);
+     *   .limit(2)
+     *   .execute()
      * ```
      *
      * The generated SQL (MySQL):
+     *
      * ```sql
-     * update `person` set `first_name` = 'Foo' limit 2
+     * update `person` set `first_name` = ? limit ?
      * ```
      */
     limit(limit) {
@@ -148,10 +150,51 @@ export class UpdateQueryBuilder {
             queryNode: QueryNode.cloneWithReturning(this.#props.queryNode, parseSelectArg(selection)),
         });
     }
-    returningAll() {
+    returningAll(table) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithReturning(this.#props.queryNode, parseSelectAll(table)),
+        });
+    }
+    output(args) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithOutput(this.#props.queryNode, parseSelectArg(args)),
+        });
+    }
+    outputAll(table) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithOutput(this.#props.queryNode, parseSelectAll(table)),
+        });
+    }
+    /**
+     * This can be used to add any additional SQL to the end of the query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * await db.updateTable('person')
+     *   .set({ age: 39 })
+     *   .where('first_name', '=', 'John')
+     *   .modifyEnd(sql.raw('-- This is a comment'))
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * update `person`
+     * set `age` = 39
+     * where `first_name` = "John" -- This is a comment
+     * ```
+     */
+    modifyEnd(modifier) {
         return new UpdateQueryBuilder({
             ...this.#props,
-            queryNode: QueryNode.cloneWithReturning(this.#props.queryNode, parseSelectAll()),
+            queryNode: QueryNode.cloneWithEndModifier(this.#props.queryNode, modifier.toOperationNode()),
         });
     }
     /**
@@ -191,11 +234,18 @@ export class UpdateQueryBuilder {
      * The next example uses a helper function `log` to log a query:
      *
      * ```ts
+     * import type { Compilable } from 'kysely'
+     * import type { PersonUpdate } from 'type-editor' // imaginary module
+     *
      * function log<T extends Compilable>(qb: T): T {
      *   console.log(qb.compile())
      *   return qb
      * }
      *
+     * const values = {
+     *   first_name: 'John',
+     * } satisfies PersonUpdate
+     *
      * db.updateTable('person')
      *   .set(values)
      *   .$call(log)
@@ -218,7 +268,9 @@ export class UpdateQueryBuilder {
      * ### Examples
      *
      * ```ts
-     * async function updatePerson(id: number, updates: UpdateablePerson, returnLastName: boolean) {
+     * import type { PersonUpdate } from 'type-editor' // imaginary module
+     *
+     * async function updatePerson(id: number, updates: PersonUpdate, returnLastName: boolean) {
      *   return await db
      *     .updateTable('person')
      *     .set(updates)
@@ -234,11 +286,11 @@ export class UpdateQueryBuilder {
      * the code. In the example above the return type of the `updatePerson` function is:
      *
      * ```ts
-     * {
+     * Promise<{
      *   id: number
      *   first_name: string
      *   last_name?: string
-     * }
+     * }>
      * ```
      */
     $if(condition, func) {
@@ -276,27 +328,41 @@ export class UpdateQueryBuilder {
      * Turn this code:
      *
      * ```ts
+     * import type { Person } from 'type-editor' // imaginary module
+     *
+     * const id = 1
+     * const now = new Date().toISOString()
+     *
      * const person = await db.updateTable('person')
-     *   .set({ deletedAt: now })
+     *   .set({ deleted_at: now })
      *   .where('id', '=', id)
      *   .where('nullable_column', 'is not', null)
      *   .returningAll()
      *   .executeTakeFirstOrThrow()
      *
-     * if (person.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 id = 1
+     * const now = new Date().toISOString()
+     *
      * const person = await db.updateTable('person')
-     *   .set({ deletedAt: now })
+     *   .set({ deleted_at: now })
      *   .where('id', '=', id)
      *   .where('nullable_column', 'is not', null)
      *   .returningAll()
-     *   .$narrowType<{ deletedAt: Date; nullable_column: string }>()
+     *   .$narrowType<{ deleted_at: Date; nullable_column: NotNull }>()
      *   .executeTakeFirstOrThrow()
      *
      * functionThatExpectsPersonWithNonNullValue(person)
@@ -308,17 +374,17 @@ export class UpdateQueryBuilder {
     /**
      * Asserts that query's output row type equals the given type `T`.
      *
-     * This method can be used to simplify excessively complex types to make typescript happy
+     * This method can be used to simplify excessively complex types to make TypeScript happy
      * and much faster.
      *
      * Kysely uses complex type magic to achieve its type safety. This complexity is sometimes too much
-     * for typescript and you get errors like this:
+     * for TypeScript and you get errors like this:
      *
      * ```
      * error TS2589: Type instantiation is excessively deep and possibly infinite.
      * ```
      *
-     * In these case you can often use this method to help typescript a little bit. When you use this
+     * In these case you can often use this method to help TypeScript a little bit. When you use this
      * method to assert the output type of a query, Kysely can drop the complex output type that
      * consists of multiple nested helper types and replace it with the simple asserted type.
      *
@@ -328,6 +394,17 @@ export class UpdateQueryBuilder {
      * ### Examples
      *
      * ```ts
+     * import type { PersonUpdate, PetUpdate, Species } from 'type-editor' // imaginary module
+     *
+     * const person = {
+     *   id: 1,
+     *   gender: 'other',
+     * } satisfies PersonUpdate
+     *
+     * const pet = {
+     *   name: 'Fluffy',
+     * } satisfies PetUpdate
+     *
      * const result = await db
      *   .with('updated_person', (qb) => qb
      *     .updateTable('person')
@@ -373,9 +450,11 @@ export class UpdateQueryBuilder {
      */
     async execute() {
         const compiledQuery = this.compile();
-        const query = compiledQuery.query;
         const result = await this.#props.executor.executeQuery(compiledQuery, this.#props.queryId);
-        if (this.#props.executor.adapter.supportsReturning && query.returning) {
+        const { adapter } = this.#props.executor;
+        const query = compiledQuery.query;
+        if ((query.returning && adapter.supportsReturning) ||
+            (query.output && adapter.supportsOutput)) {
             return result.rows;
         }
         return [

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

@@ -1,5 +1,14 @@
 export declare class UpdateResult {
+    /**
+     * The number of rows the update query updated (even if not changed).
+     */
     readonly numUpdatedRows: bigint;
+    /**
+     * The number of rows the update query changed.
+     *
+     * This is **optional** and only supported in dialects such as MySQL.
+     * You would probably use {@link numUpdatedRows} in most cases.
+     */
     readonly numChangedRows?: bigint;
     constructor(numUpdatedRows: bigint, numChangedRows: bigint | undefined);
 }

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

@@ -1,6 +1,15 @@
 /// <reference types="./update-result.d.ts" />
 export class UpdateResult {
+    /**
+     * The number of rows the update query updated (even if not changed).
+     */
     numUpdatedRows;
+    /**
+     * The number of rows the update query changed.
+     *
+     * This is **optional** and only supported in dialects such as MySQL.
+     * You would probably use {@link numUpdatedRows} in most cases.
+     */
     numChangedRows;
     constructor(numUpdatedRows, numChangedRows) {
         this.numUpdatedRows = numUpdatedRows;

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

@@ -35,6 +35,8 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      * you can always use:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * sql`your operator`
      * ```
      *
@@ -46,7 +48,7 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
-     *   .where('id', 'in', ['1', '2', '3'])
+     *   .where('id', 'in', [1, 2, 3])
      *   .execute()
      * ```
      *
@@ -265,7 +267,7 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      *   .selectFrom('person')
      *   .selectAll()
      *   .where(
-     *     sql`coalesce(first_name, last_name)`,
+     *     sql<string>`coalesce(first_name, last_name)`,
      *     'like',
      *     '%' + name + '%',
      *   )
@@ -294,6 +296,8 @@ export interface WhereInterface<DB, TB extends keyof DB> {
      * import { sql } from 'kysely'
      * const { ref } = db.dynamic
      *
+     * const columnFromUserInput: string = 'id'
+     *
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()

package/dist/esm/query-compiler/default-query-compiler.d.ts

@@ -94,6 +94,7 @@ import { AddIndexNode } from '../operation-node/add-index-node.js';
 import { CastNode } from '../operation-node/cast-node.js';
 import { FetchNode } from '../operation-node/fetch-node.js';
 import { TopNode } from '../operation-node/top-node.js';
+import { OutputNode } from '../operation-node/output-node.js';
 export declare class DefaultQueryCompiler extends OperationNodeVisitor implements QueryCompiler {
     #private;
     protected get numParameters(): number;
@@ -195,6 +196,7 @@ export declare class DefaultQueryCompiler extends OperationNodeVisitor implement
     protected visitAddIndex(node: AddIndexNode): void;
     protected visitCast(node: CastNode): void;
     protected visitFetch(node: FetchNode): void;
+    protected visitOutput(node: OutputNode): void;
     protected visitTop(node: TopNode): void;
     protected append(str: string): void;
     protected appendValue(parameter: unknown): void;

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

@@ -18,6 +18,7 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
     compileQuery(node) {
         this.#sql = '';
         this.#parameters = [];
+        this.nodeStack.splice(0, this.nodeStack.length);
         this.visitNode(node);
         return freeze({
             query: node,
@@ -174,6 +175,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.compileList(node.columns);
             this.append(')');
         }
+        if (node.output) {
+            this.append(' ');
+            this.visitNode(node.output);
+        }
         if (node.values) {
             this.append(' ');
             this.visitNode(node.values);
@@ -197,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 ');
@@ -221,6 +230,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
             this.append(' ');
         }
         this.visitNode(node.from);
+        if (node.output) {
+            this.append(' ');
+            this.visitNode(node.output);
+        }
         if (node.using) {
             this.append(' ');
             this.visitNode(node.using);
@@ -248,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 ');
@@ -391,6 +408,9 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         }
     }
     visitColumnDefinition(node) {
+        if (node.ifNotExists) {
+            this.append('if not exists ');
+        }
         this.visitNode(node.column);
         this.append(' ');
         this.visitNode(node.dataType);
@@ -517,6 +537,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         if (node.updates) {
             this.compileList(node.updates);
         }
+        if (node.output) {
+            this.append(' ');
+            this.visitNode(node.output);
+        }
         if (node.from) {
             this.append(' ');
             this.visitNode(node.from);
@@ -540,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);
@@ -955,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(');
@@ -1091,7 +1123,15 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         }
         if (node.whens) {
             this.append(' ');
-            this.compileList(node.whens);
+            this.compileList(node.whens, ' ');
+        }
+        if (node.output) {
+            this.append(' ');
+            this.visitNode(node.output);
+        }
+        if (node.endModifiers?.length) {
+            this.append(' ');
+            this.compileList(node.endModifiers, ' ');
         }
     }
     visitMatched(node) {
@@ -1132,6 +1172,10 @@ export class DefaultQueryCompiler extends OperationNodeVisitor {
         this.visitNode(node.rowCount);
         this.append(` rows ${node.modifier}`);
     }
+    visitOutput(node) {
+        this.append('output ');
+        this.compileList(node.selections);
+    }
     visitTop(node) {
         this.append(`top(${node.expression})`);
         if (node.modifiers) {

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

@@ -125,10 +125,10 @@ export declare class QueryCreator<DB> {
      * ```
      */
     selectFrom<TE extends keyof DB & string>(from: TE[]): SelectQueryBuilder<DB, ExtractTableAlias<DB, TE>, {}>;
-    selectFrom<TE extends TableExpression<DB, keyof DB>>(from: TE[]): SelectQueryBuilder<From<DB, TE>, FromTables<DB, never, TE>, {}>;
+    selectFrom<TE extends TableExpression<DB, never>>(from: TE[]): SelectQueryBuilder<From<DB, TE>, FromTables<DB, never, TE>, {}>;
     selectFrom<TE extends keyof DB & string>(from: TE): SelectQueryBuilder<DB, ExtractTableAlias<DB, TE>, {}>;
     selectFrom<TE extends AnyAliasedTable<DB>>(from: TE): SelectQueryBuilder<DB & PickTableWithAlias<DB, TE>, ExtractTableAlias<DB & PickTableWithAlias<DB, TE>, TE>, {}>;
-    selectFrom<TE extends TableExpression<DB, keyof DB>>(from: TE): SelectQueryBuilder<From<DB, TE>, FromTables<DB, never, TE>, {}>;
+    selectFrom<TE extends TableExpression<DB, never>>(from: TE): SelectQueryBuilder<From<DB, TE>, FromTables<DB, never, TE>, {}>;
     /**
      * Creates a `select` query builder without a `from` clause.
      *
@@ -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>;
@@ -365,24 +413,77 @@ export declare class QueryCreator<DB> {
      *
      * ### Examples
      *
+     * <!-- siteExample("cte", "Simple selects", 10) -->
+     *
+     * Common table expressions (CTE) are a great way to modularize complex queries.
+     * Essentially they allow you to run multiple separate queries within a
+     * single roundtrip to the DB.
+     *
+     * Since CTEs are a part of the main query, query optimizers inside DB
+     * engines are able to optimize the overall query. For example, postgres
+     * is able to inline the CTEs inside the using queries if it decides it's
+     * faster.
+     *
      * ```ts
-     * await db
+     * const result = await db
+     *   // Create a CTE called `jennifers` that selects all
+     *   // persons named 'Jennifer'.
      *   .with('jennifers', (db) => db
      *     .selectFrom('person')
      *     .where('first_name', '=', 'Jennifer')
      *     .select(['id', 'age'])
      *   )
+     *   // Select all rows from the `jennifers` CTE and
+     *   // further filter it.
      *   .with('adult_jennifers', (db) => db
      *     .selectFrom('jennifers')
      *     .where('age', '>', 18)
      *     .select(['id', 'age'])
      *   )
+     *   // Finally select all adult jennifers that are
+     *   // also younger than 60.
      *   .selectFrom('adult_jennifers')
      *   .where('age', '<', 60)
      *   .selectAll()
      *   .execute()
      * ```
      *
+     * <!-- siteExample("cte", "Inserts, updates and deletions", 20) -->
+     *
+     * Some databases like postgres also allow you to run other queries than selects
+     * in CTEs. On these databases CTEs are extremely powerful:
+     *
+     * ```ts
+     * const result = await db
+     *   .with('new_person', (db) => db
+     *     .insertInto('person')
+     *     .values({
+     *       first_name: 'Jennifer',
+     *       age: 35,
+     *     })
+     *     .returning('id')
+     *   )
+     *   .with('new_pet', (db) => db
+     *     .insertInto('pet')
+     *     .values({
+     *       name: 'Doggo',
+     *       species: 'dog',
+     *       is_favorite: true,
+     *       // Use the id of the person we just inserted.
+     *       owner_id: db
+     *         .selectFrom('new_person')
+     *         .select('id')
+     *     })
+     *     .returning('id')
+     *   )
+     *   .selectFrom(['new_person', 'new_pet'])
+     *   .select([
+     *     'new_person.id as person_id',
+     *     'new_pet.id as pet_id'
+     *   ])
+     *   .execute()
+     * ```
+     *
      * The CTE name can optionally specify column names in addition to
      * a name. In that case Kysely requires the expression to retun
      * rows with the same columns.
@@ -445,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