kysely 0.27.3 → 0.27.5

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;

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

@@ -1,4 +1,4 @@
-import { AliasedExpression } from '../expression/expression.js';
+import { AliasedExpression, Expression } from '../expression/expression.js';
 import { MergeQueryNode } from '../operation-node/merge-query-node.js';
 import { OperationNodeSource } from '../operation-node/operation-node-source.js';
 import { QueryNode } from '../operation-node/query-node.js';
@@ -7,6 +7,7 @@ import { ExpressionOrFactory } from '../parser/expression-parser.js';
 import { InsertObjectOrList, InsertObjectOrListFactory } from '../parser/insert-values-parser.js';
 import { JoinCallbackExpression, JoinReferenceExpression } from '../parser/join-parser.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
+import { ReturningAllRow, ReturningRow } from '../parser/returning-parser.js';
 import { TableExpression } from '../parser/table-parser.js';
 import { ExtractUpdateTypeFromReferenceExpression, UpdateObject, UpdateObjectFactory } from '../parser/update-set-parser.js';
 import { ValueExpression } from '../parser/value-parser.js';
@@ -17,10 +18,35 @@ import { QueryId } from '../util/query-id.js';
 import { ShallowRecord, SimplifyResult, SimplifySingleResult, SqlBool } from '../util/type-utils.js';
 import { MergeResult } from './merge-result.js';
 import { NoResultErrorConstructor } from './no-result-error.js';
+import { OutputCallback, OutputExpression, OutputInterface, OutputPrefix, SelectExpressionFromOutputCallback, SelectExpressionFromOutputExpression } from './output-interface.js';
 import { UpdateQueryBuilder } from './update-query-builder.js';
-export declare class MergeQueryBuilder<DB, TT extends keyof DB, O> {
+export declare class MergeQueryBuilder<DB, TT extends keyof DB, O> implements OutputInterface<DB, TT, O> {
     #private;
     constructor(props: MergeQueryBuilderProps);
+    /**
+     * This can be used to add any additional SQL to the end of the query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * await db
+     *   .mergeInto('person')
+     *   .using('pet', 'pet.owner_id', 'person.id')
+     *   .whenMatched()
+     *   .thenDelete()
+     *   .modifyEnd(sql.raw('-- this is a comment'))
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * merge into "person" using "pet" on "pet"."owner_id" = "person"."id" when matched then delete -- this is a comment
+     * ```
+     */
+    modifyEnd(modifier: Expression<any>): MergeQueryBuilder<DB, TT, O>;
     /**
      * Changes a `merge into` query to an `merge top into` query.
      *
@@ -96,15 +122,163 @@ export declare class MergeQueryBuilder<DB, TT extends keyof DB, O> {
      */
     using<TE extends TableExpression<DB, TT>, K1 extends JoinReferenceExpression<DB, TT, TE>, K2 extends JoinReferenceExpression<DB, TT, TE>>(sourceTable: TE, k1: K1, k2: K2): ExtractWheneableMergeQueryBuilder<DB, TT, TE, O>;
     using<TE extends TableExpression<DB, TT>, FN extends JoinCallbackExpression<DB, TT, TE>>(sourceTable: TE, callback: FN): ExtractWheneableMergeQueryBuilder<DB, TT, TE, O>;
+    /**
+     * Allows you to return data from modified rows.
+     *
+     * On supported databases like MS SQL Server (MSSQL), this method can be chained
+     * to `insert`, `update`, `delete` and `merge` queries to return data.
+     *
+     * Also see the {@link outputAll} method.
+     *
+     * ### Examples
+     *
+     * Return one column:
+     *
+     * ```ts
+     * const { id } = await db
+     *   .insertInto('person')
+     *   .output('inserted.id')
+     *   .values({
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston',
+     *     gender: 'female',
+     *   })
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (MSSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name", "last_name", "gender")
+     * output "inserted"."id"
+     * values (@1, @2, @3)
+     * ```
+     *
+     * Return multiple columns:
+     *
+     * ```ts
+     * const { old_first_name, old_last_name, new_first_name, new_last_name } = await db
+     *   .updateTable('person')
+     *   .set({ first_name: 'John', last_name: 'Doe' })
+     *   .output([
+     *     'deleted.first_name as old_first_name',
+     *     'deleted.last_name as old_last_name',
+     *     'inserted.first_name as new_first_name',
+     *     'inserted.last_name as new_last_name',
+     *   ])
+     *   .where('created_at', '<', new Date())
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (MSSQL):
+     *
+     * ```sql
+     * update "person"
+     * set "first_name" = @1, "last_name" = @2
+     * output "deleted"."first_name" as "old_first_name",
+     *   "deleted"."last_name" as "old_last_name",
+     *   "inserted"."first_name" as "new_first_name",
+     *   "inserted"."last_name" as "new_last_name"
+     * where "created_at" < @3
+     * ```
+     *
+     * Return arbitrary expressions:
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const { full_name } = await db
+     *   .deleteFrom('person')
+     *   .output((eb) => sql<string>`concat(${eb.ref('deleted.first_name')}, ' ', ${eb.ref('deleted.last_name')})`.as('full_name'))
+     *   .where('created_at', '<', new Date())
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (MSSQL):
+     *
+     * ```sql
+     * delete from "person"
+     * output concat("deleted"."first_name", ' ', "deleted"."last_name") as "full_name"
+     * where "created_at" < @1
+     * ```
+     *
+     * Return the action performed on the row:
+     *
+     * ```ts
+     * await db
+     *   .mergeInto('person')
+     *   .using('pet', 'pet.owner_id', 'person.id')
+     *   .whenMatched()
+     *   .thenDelete()
+     *   .whenNotMatched()
+     *   .thenInsertValues({
+     *     first_name: 'John',
+     *     last_name: 'Doe',
+     *     gender: 'male'
+     *   })
+     *   .output([
+     *     'inserted.id as inserted_id',
+     *     'deleted.id as deleted_id',
+     *   ])
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MSSQL):
+     *
+     * ```sql
+     * merge into "person"
+     * using "pet" on "pet"."owner_id" = "person"."id"
+     * when matched then delete
+     * when not matched then
+     * insert ("first_name", "last_name", "gender")
+     * values (@1, @2, @3)
+     * output "inserted"."id" as "inserted_id", "deleted"."id" as "deleted_id"
+     * ```
+     *
+     */
+    output<OE extends OutputExpression<DB, TT>>(selections: readonly OE[]): MergeQueryBuilder<DB, TT, ReturningRow<DB, TT, O, SelectExpressionFromOutputExpression<OE>>>;
+    output<CB extends OutputCallback<DB, TT>>(callback: CB): MergeQueryBuilder<DB, TT, ReturningRow<DB, TT, O, SelectExpressionFromOutputCallback<CB>>>;
+    output<OE extends OutputExpression<DB, TT>>(selection: OE): MergeQueryBuilder<DB, TT, ReturningRow<DB, TT, O, SelectExpressionFromOutputExpression<OE>>>;
+    /**
+     * Adds an `output {prefix}.*` to an `insert`/`update`/`delete`/`merge` query on databases
+     * that support `output` such as MS SQL Server (MSSQL).
+     *
+     * Also see the {@link output} method.
+     */
+    outputAll(table: OutputPrefix): MergeQueryBuilder<DB, TT, ReturningAllRow<DB, TT, O>>;
 }
 export interface MergeQueryBuilderProps {
     readonly queryId: QueryId;
     readonly queryNode: MergeQueryNode;
     readonly executor: QueryExecutor;
 }
-export declare class WheneableMergeQueryBuilder<DB, TT extends keyof DB, ST extends keyof DB, O> implements Compilable<O>, OperationNodeSource {
+export declare class WheneableMergeQueryBuilder<DB, TT extends keyof DB, ST extends keyof DB, O> implements Compilable<O>, OutputInterface<DB, TT, O>, OperationNodeSource {
     #private;
     constructor(props: MergeQueryBuilderProps);
+    /**
+     * This can be used to add any additional SQL to the end of the query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * await db
+     *   .mergeInto('person')
+     *   .using('pet', 'pet.owner_id', 'person.id')
+     *   .whenMatched()
+     *   .thenDelete()
+     *   .modifyEnd(sql.raw('-- this is a comment'))
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * merge into "person" using "pet" on "pet"."owner_id" = "person"."id" when matched then delete -- this is a comment
+     * ```
+     */
+    modifyEnd(modifier: Expression<any>): WheneableMergeQueryBuilder<DB, TT, ST, O>;
     /**
      * See {@link MergeQueryBuilder.top}.
      */
@@ -275,6 +449,130 @@ export declare class WheneableMergeQueryBuilder<DB, TT extends keyof DB, ST exte
      * the target table, and not from source table and returns a {@link MatchedThenableMergeQueryBuilder}.
      */
     whenNotMatchedBySourceAndRef<LRE extends ReferenceExpression<DB, TT>, RRE extends ReferenceExpression<DB, TT>>(lhs: LRE, op: ComparisonOperatorExpression, rhs: RRE): MatchedThenableMergeQueryBuilder<DB, TT, ST, TT, O>;
+    /**
+     * Allows you to return data from modified rows.
+     *
+     * On supported databases like MS SQL Server (MSSQL), this method can be chained
+     * to `insert`, `update`, `delete` and `merge` queries to return data.
+     *
+     * Also see the {@link outputAll} method.
+     *
+     * ### Examples
+     *
+     * Return one column:
+     *
+     * ```ts
+     * const { id } = await db
+     *   .insertInto('person')
+     *   .output('inserted.id')
+     *   .values({
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston',
+     *     gender: 'female',
+     *   })
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (MSSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name", "last_name", "gender")
+     * output "inserted"."id"
+     * values (@1, @2, @3)
+     * ```
+     *
+     * Return multiple columns:
+     *
+     * ```ts
+     * const { old_first_name, old_last_name, new_first_name, new_last_name } = await db
+     *   .updateTable('person')
+     *   .set({ first_name: 'John', last_name: 'Doe' })
+     *   .output([
+     *     'deleted.first_name as old_first_name',
+     *     'deleted.last_name as old_last_name',
+     *     'inserted.first_name as new_first_name',
+     *     'inserted.last_name as new_last_name',
+     *   ])
+     *   .where('created_at', '<', new Date())
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (MSSQL):
+     *
+     * ```sql
+     * update "person"
+     * set "first_name" = @1, "last_name" = @2
+     * output "deleted"."first_name" as "old_first_name",
+     *   "deleted"."last_name" as "old_last_name",
+     *   "inserted"."first_name" as "new_first_name",
+     *   "inserted"."last_name" as "new_last_name"
+     * where "created_at" < @3
+     * ```
+     *
+     * Return arbitrary expressions:
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const { full_name } = await db
+     *   .deleteFrom('person')
+     *   .output((eb) => sql<string>`concat(${eb.ref('deleted.first_name')}, ' ', ${eb.ref('deleted.last_name')})`.as('full_name'))
+     *   .where('created_at', '<', new Date())
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (MSSQL):
+     *
+     * ```sql
+     * delete from "person"
+     * output concat("deleted"."first_name", ' ', "deleted"."last_name") as "full_name"
+     * where "created_at" < @1
+     * ```
+     *
+     * Return the action performed on the row:
+     *
+     * ```ts
+     * await db
+     *   .mergeInto('person')
+     *   .using('pet', 'pet.owner_id', 'person.id')
+     *   .whenMatched()
+     *   .thenDelete()
+     *   .whenNotMatched()
+     *   .thenInsertValues({
+     *     first_name: 'John',
+     *     last_name: 'Doe',
+     *     gender: 'male'
+     *   })
+     *   .output([
+     *     'inserted.id as inserted_id',
+     *     'deleted.id as deleted_id',
+     *   ])
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MSSQL):
+     *
+     * ```sql
+     * merge into "person"
+     * using "pet" on "pet"."owner_id" = "person"."id"
+     * when matched then delete
+     * when not matched then
+     * insert ("first_name", "last_name", "gender")
+     * values (@1, @2, @3)
+     * output "inserted"."id" as "inserted_id", "deleted"."id" as "deleted_id"
+     * ```
+     *
+     */
+    output<OE extends OutputExpression<DB, TT>>(selections: readonly OE[]): WheneableMergeQueryBuilder<DB, TT, ST, ReturningRow<DB, TT, O, SelectExpressionFromOutputExpression<OE>>>;
+    output<CB extends OutputCallback<DB, TT>>(callback: CB): WheneableMergeQueryBuilder<DB, TT, ST, ReturningRow<DB, TT, O, SelectExpressionFromOutputCallback<CB>>>;
+    output<OE extends OutputExpression<DB, TT>>(selection: OE): WheneableMergeQueryBuilder<DB, TT, ST, ReturningRow<DB, TT, O, SelectExpressionFromOutputExpression<OE>>>;
+    /**
+     * Adds an `output {prefix}.*` to an `insert`/`update`/`delete`/`merge` query on databases
+     * that support `output` such as MS SQL Server (MSSQL).
+     *
+     * Also see the {@link output} method.
+     */
+    outputAll(table: OutputPrefix): WheneableMergeQueryBuilder<DB, TT, ST, ReturningAllRow<DB, TT, O>>;
     /**
      * Simply calls the provided function passing `this` as the only argument. `$call` returns
      * what the provided function returns.
@@ -287,13 +585,15 @@ export declare class WheneableMergeQueryBuilder<DB, TT extends keyof DB, ST exte
      * 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.updateTable('person')
+     *   .set({ first_name: 'John' })
      *   .$call(log)
      *   .execute()
      * ```
@@ -312,7 +612,9 @@ export declare class WheneableMergeQueryBuilder<DB, TT extends keyof DB, ST exte
      * ### 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)
@@ -328,16 +630,16 @@ export declare class WheneableMergeQueryBuilder<DB, TT extends keyof DB, ST exte
      * 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<O2>(condition: boolean, func: (qb: this) => WheneableMergeQueryBuilder<any, any, any, O2>): O2 extends MergeResult ? WheneableMergeQueryBuilder<DB, TT, ST, MergeResult> : O2 extends O & infer E ? WheneableMergeQueryBuilder<DB, TT, ST, O & Partial<E>> : WheneableMergeQueryBuilder<DB, TT, ST, Partial<O2>>;
     toOperationNode(): MergeQueryNode;
-    compile(): CompiledQuery<never>;
+    compile(): CompiledQuery<O>;
     /**
      * Executes the query and returns an array of rows.
      *
@@ -439,7 +741,7 @@ export declare class MatchedThenableMergeQueryBuilder<DB, TT extends keyof DB, S
      *   .thenUpdate((ub) => ub
      *     .set(sql`metadata['has_pets']`, 'Y')
      *     .set({
-     *       updated_at: Date.now(),
+     *       updated_at: new Date().toISOString(),
      *     })
      *   )
      *   .execute()