kysely 0.11.1 → 0.12.0

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

@@ -0,0 +1,190 @@
+import { OperationNodeSource } from '../operation-node/operation-node-source.js';
+import { CompiledQuery } from '../query-compiler/compiled-query.js';
+import { JoinCallbackExpression, JoinReferenceExpression } from '../parser/join-parser.js';
+import { TableExpression, TableExpressionDatabase, TableExpressionTables, LeftJoinTableExpressionDatabase, RightJoinTableExpressionDatabase, FullJoinTableExpressionDatabase } from '../parser/table-parser.js';
+import { SelectExpression } from '../parser/select-parser.js';
+import { ExistsExpression, FilterOperator, FilterValueExpressionOrList, WhereGrouper } from '../parser/filter-parser.js';
+import { ReturningRow } from '../parser/returning-parser.js';
+import { ReferenceExpression } from '../parser/reference-parser.js';
+import { AnyRawBuilder, SingleResultType } from '../util/type-utils.js';
+import { UpdateQueryNode } from '../operation-node/update-query-node.js';
+import { MutationObject } from '../parser/update-set-parser.js';
+import { Compilable } from '../util/compilable.js';
+import { QueryExecutor } from '../query-executor/query-executor.js';
+import { QueryId } from '../util/query-id.js';
+import { ParseContext } from '../parser/parse-context.js';
+import { KyselyPlugin } from '../plugin/kysely-plugin.js';
+import { WhereInterface } from './where-interface.js';
+import { JoinInterface } from './join-interface.js';
+import { ReturningInterface } from './returning-interface.js';
+import { NoResultErrorConstructor } from './no-result-error.js';
+export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements WhereInterface<DB, TB>, JoinInterface<DB, TB>, ReturningInterface<DB, TB, O>, OperationNodeSource, Compilable {
+    #private;
+    constructor(props: UpdateQueryBuilderProps);
+    where<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: FilterOperator, rhs: FilterValueExpressionOrList<DB, TB, RE>): UpdateQueryBuilder<DB, TB, O>;
+    where(grouper: WhereGrouper<DB, TB>): UpdateQueryBuilder<DB, TB, O>;
+    where(raw: AnyRawBuilder): UpdateQueryBuilder<DB, TB, O>;
+    whereRef(lhs: ReferenceExpression<DB, TB>, op: FilterOperator, rhs: ReferenceExpression<DB, TB>): UpdateQueryBuilder<DB, TB, O>;
+    orWhere<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: FilterOperator, rhs: FilterValueExpressionOrList<DB, TB, RE>): UpdateQueryBuilder<DB, TB, O>;
+    orWhere(grouper: WhereGrouper<DB, TB>): UpdateQueryBuilder<DB, TB, O>;
+    orWhere(raw: AnyRawBuilder): UpdateQueryBuilder<DB, TB, O>;
+    orWhereRef(lhs: ReferenceExpression<DB, TB>, op: FilterOperator, rhs: ReferenceExpression<DB, TB>): UpdateQueryBuilder<DB, TB, O>;
+    whereExists(arg: ExistsExpression<DB, TB>): UpdateQueryBuilder<DB, TB, O>;
+    whereNotExists(arg: ExistsExpression<DB, TB>): UpdateQueryBuilder<DB, TB, O>;
+    orWhereExists(arg: ExistsExpression<DB, TB>): UpdateQueryBuilder<DB, TB, O>;
+    orWhereNotExists(arg: ExistsExpression<DB, TB>): UpdateQueryBuilder<DB, TB, O>;
+    innerJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): UpdateQueryBuilder<TableExpressionDatabase<DB, TE>, TableExpressionTables<DB, TB, TE>, O>;
+    innerJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): UpdateQueryBuilder<TableExpressionDatabase<DB, TE>, TableExpressionTables<DB, TB, TE>, O>;
+    leftJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): UpdateQueryBuilder<LeftJoinTableExpressionDatabase<DB, TE>, TableExpressionTables<DB, TB, TE>, O>;
+    leftJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): UpdateQueryBuilder<LeftJoinTableExpressionDatabase<DB, TE>, TableExpressionTables<DB, TB, TE>, O>;
+    rightJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): UpdateQueryBuilder<RightJoinTableExpressionDatabase<DB, TB, TE>, TableExpressionTables<DB, TB, TE>, O>;
+    rightJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): UpdateQueryBuilder<RightJoinTableExpressionDatabase<DB, TB, TE>, TableExpressionTables<DB, TB, TE>, O>;
+    fullJoin<TE extends TableExpression<DB, TB>, K1 extends JoinReferenceExpression<DB, TB, TE>, K2 extends JoinReferenceExpression<DB, TB, TE>>(table: TE, k1: K1, k2: K2): UpdateQueryBuilder<FullJoinTableExpressionDatabase<DB, TB, TE>, TableExpressionTables<DB, TB, TE>, O>;
+    fullJoin<TE extends TableExpression<DB, TB>, FN extends JoinCallbackExpression<DB, TB, TE>>(table: TE, callback: FN): UpdateQueryBuilder<FullJoinTableExpressionDatabase<DB, TB, TE>, TableExpressionTables<DB, TB, TE>, O>;
+    /**
+     * 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`
+     * instances or select queries.
+     *
+     * The return value of an update query is an instance of {@link UpdateResult}.
+     * You can use the {@link ReturningInterface.returning | returning} method on
+     * supported databases to get out the updated rows.
+     *
+     * ### Examples
+     *
+     * Update a row in `person` table:
+     *
+     * ```ts
+     * const result = await db
+     *   .updateTable('person')
+     *   .set({
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston'
+     *   })
+     *   .where('id', '=', 1)
+     *   .executeTakeFirst()
+     *
+     * console.log(result.numUpdatedRows)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * update "person" set "first_name" = $1, "last_name" = $2 where "id" = $3
+     * ```
+     *
+     * On PostgreSQL you ca chain `returning` to the query to get
+     * the updated rows' columns (or any other expression) as the
+     * return value:
+     *
+     * ```ts
+     * const row = await db
+     *   .updateTable('person')
+     *   .set({
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston'
+     *   })
+     *   .where('id', '=', 1)
+     *   .returning('id')
+     *   .executeTakeFirstOrThrow()
+     *
+     * row.id
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * update "person" set "first_name" = $1, "last_name" = $2 where "id" = $3 returning "id"
+     * ```
+     *
+     * In addition to primitives, the values can also be `raw` expressions or
+     * select queries:
+     *
+     * ```ts
+     * const result = await db
+     *   .updateTable('person')
+     *   .set({
+     *     first_name: 'Jennifer',
+     *     last_name: db.raw('? || ?', ['Ani', 'ston']),
+     *     age: db.selectFrom('person').select(raw('avg(age)')),
+     *   })
+     *   .where('id', '=', 1)
+     *   .executeTakeFirst()
+     *
+     * console.log(result.numUpdatedRows)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * update "person" set
+     * "first_name" = $1,
+     * "last_name" = $2 || $3,
+     * "age" = (select avg(age) from "person")
+     * where "id" = $4
+     * ```
+     */
+    set(row: MutationObject<DB, TB>): UpdateQueryBuilder<DB, TB, O>;
+    returning<SE extends SelectExpression<DB, TB>>(selections: ReadonlyArray<SE>): UpdateQueryBuilder<DB, TB, ReturningRow<DB, TB, O, SE>>;
+    returning<SE extends SelectExpression<DB, TB>>(selection: SE): UpdateQueryBuilder<DB, TB, ReturningRow<DB, TB, O, SE>>;
+    returningAll(): UpdateQueryBuilder<DB, TB, DB[TB]>;
+    /**
+     * Simply calls the given function passing `this` as the only argument.
+     *
+     * This method can be useful when adding optional method calls:
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.updateTable('person')
+     *   .set(values)
+     *   .call((qb) => {
+     *     if (something) {
+     *       return qb.where('something', '=', something)
+     *     } else {
+     *       return qb.where('somethingElse', '=', somethingElse)
+     *     }
+     *   })
+     *   .execute()
+     * ```
+     */
+    call<T>(func: (qb: this) => T): T;
+    /**
+     * Change the output type of the query.
+     *
+     * You should only use this method as the last resort if the types
+     * don't support your use case.
+     */
+    castTo<T>(): UpdateQueryBuilder<DB, TB, T>;
+    withPlugin(plugin: KyselyPlugin): UpdateQueryBuilder<DB, TB, O>;
+    toOperationNode(): UpdateQueryNode;
+    compile(): CompiledQuery;
+    /**
+     * Executes the query and returns an array of rows.
+     *
+     * Also see the {@link executeTakeFirst} and {@link executeTakeFirstOrThrow} methods.
+     */
+    execute(): Promise<O[]>;
+    /**
+     * Executes the query and returns the first result or undefined if
+     * the query returned no result.
+     */
+    executeTakeFirst(): Promise<SingleResultType<O>>;
+    /**
+     * Executes the query and returns the first result or throws if
+     * the query returned no result.
+     *
+     * By default an instance of {@link NoResultError} is thrown, but you can
+     * provide a custom error class as the only argument to throw a different
+     * error.
+     */
+    executeTakeFirstOrThrow(errorConstructor?: NoResultErrorConstructor): Promise<O>;
+}
+export interface UpdateQueryBuilderProps {
+    readonly queryId: QueryId;
+    readonly queryNode: UpdateQueryNode;
+    readonly executor: QueryExecutor;
+    readonly parseContext: ParseContext;
+}

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

@@ -0,0 +1,275 @@
+import { parseJoin, } from '../parser/join-parser.js';
+import { parseSelectExpressionOrList, parseSelectAll, } from '../parser/select-parser.js';
+import { parseExistFilter, parseReferenceFilter, parseWhereFilter, parseNotExistFilter, } from '../parser/filter-parser.js';
+import { QueryNode } from '../operation-node/query-node.js';
+import { UpdateQueryNode } from '../operation-node/update-query-node.js';
+import { parseUpdateObject, } from '../parser/update-set-parser.js';
+import { preventAwait } from '../util/prevent-await.js';
+import { freeze } from '../util/object-utils.js';
+import { UpdateResult } from './update-result.js';
+import { NoResultError } from './no-result-error.js';
+export class UpdateQueryBuilder {
+    #props;
+    constructor(props) {
+        this.#props = freeze(props);
+    }
+    where(...args) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseWhereFilter(this.#props.parseContext, args)),
+        });
+    }
+    whereRef(lhs, op, rhs) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseReferenceFilter(this.#props.parseContext, lhs, op, rhs)),
+        });
+    }
+    orWhere(...args) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseWhereFilter(this.#props.parseContext, args)),
+        });
+    }
+    orWhereRef(lhs, op, rhs) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseReferenceFilter(this.#props.parseContext, lhs, op, rhs)),
+        });
+    }
+    whereExists(arg) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseExistFilter(this.#props.parseContext, arg)),
+        });
+    }
+    whereNotExists(arg) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithWhere(this.#props.queryNode, parseNotExistFilter(this.#props.parseContext, arg)),
+        });
+    }
+    orWhereExists(arg) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseExistFilter(this.#props.parseContext, arg)),
+        });
+    }
+    orWhereNotExists(arg) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithOrWhere(this.#props.queryNode, parseNotExistFilter(this.#props.parseContext, arg)),
+        });
+    }
+    innerJoin(...args) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin(this.#props.parseContext, 'InnerJoin', args)),
+        });
+    }
+    leftJoin(...args) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin(this.#props.parseContext, 'LeftJoin', args)),
+        });
+    }
+    rightJoin(...args) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin(this.#props.parseContext, 'RightJoin', args)),
+        });
+    }
+    fullJoin(...args) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithJoin(this.#props.queryNode, parseJoin(this.#props.parseContext, 'FullJoin', args)),
+        });
+    }
+    /**
+     * 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`
+     * instances or select queries.
+     *
+     * The return value of an update query is an instance of {@link UpdateResult}.
+     * You can use the {@link ReturningInterface.returning | returning} method on
+     * supported databases to get out the updated rows.
+     *
+     * ### Examples
+     *
+     * Update a row in `person` table:
+     *
+     * ```ts
+     * const result = await db
+     *   .updateTable('person')
+     *   .set({
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston'
+     *   })
+     *   .where('id', '=', 1)
+     *   .executeTakeFirst()
+     *
+     * console.log(result.numUpdatedRows)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * update "person" set "first_name" = $1, "last_name" = $2 where "id" = $3
+     * ```
+     *
+     * On PostgreSQL you ca chain `returning` to the query to get
+     * the updated rows' columns (or any other expression) as the
+     * return value:
+     *
+     * ```ts
+     * const row = await db
+     *   .updateTable('person')
+     *   .set({
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston'
+     *   })
+     *   .where('id', '=', 1)
+     *   .returning('id')
+     *   .executeTakeFirstOrThrow()
+     *
+     * row.id
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * update "person" set "first_name" = $1, "last_name" = $2 where "id" = $3 returning "id"
+     * ```
+     *
+     * In addition to primitives, the values can also be `raw` expressions or
+     * select queries:
+     *
+     * ```ts
+     * const result = await db
+     *   .updateTable('person')
+     *   .set({
+     *     first_name: 'Jennifer',
+     *     last_name: db.raw('? || ?', ['Ani', 'ston']),
+     *     age: db.selectFrom('person').select(raw('avg(age)')),
+     *   })
+     *   .where('id', '=', 1)
+     *   .executeTakeFirst()
+     *
+     * console.log(result.numUpdatedRows)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * update "person" set
+     * "first_name" = $1,
+     * "last_name" = $2 || $3,
+     * "age" = (select avg(age) from "person")
+     * where "id" = $4
+     * ```
+     */
+    set(row) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: UpdateQueryNode.cloneWithUpdates(this.#props.queryNode, parseUpdateObject(this.#props.parseContext, row)),
+        });
+    }
+    returning(selection) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithReturning(this.#props.queryNode, parseSelectExpressionOrList(this.#props.parseContext, selection)),
+        });
+    }
+    returningAll() {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithReturning(this.#props.queryNode, parseSelectAll()),
+        });
+    }
+    /**
+     * Simply calls the given function passing `this` as the only argument.
+     *
+     * This method can be useful when adding optional method calls:
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.updateTable('person')
+     *   .set(values)
+     *   .call((qb) => {
+     *     if (something) {
+     *       return qb.where('something', '=', something)
+     *     } else {
+     *       return qb.where('somethingElse', '=', somethingElse)
+     *     }
+     *   })
+     *   .execute()
+     * ```
+     */
+    call(func) {
+        return func(this);
+    }
+    /**
+     * Change the output type of the query.
+     *
+     * You should only use this method as the last resort if the types
+     * don't support your use case.
+     */
+    castTo() {
+        return new UpdateQueryBuilder(this.#props);
+    }
+    withPlugin(plugin) {
+        return new UpdateQueryBuilder({
+            ...this.#props,
+            executor: this.#props.executor.withPlugin(plugin),
+        });
+    }
+    toOperationNode() {
+        return this.#props.executor.transformQuery(this.#props.queryNode, this.#props.queryId);
+    }
+    compile() {
+        return this.#props.executor.compileQuery(this.toOperationNode(), this.#props.queryId);
+    }
+    /**
+     * Executes the query and returns an array of rows.
+     *
+     * Also see the {@link executeTakeFirst} and {@link executeTakeFirstOrThrow} methods.
+     */
+    async execute() {
+        const compildQuery = this.compile();
+        const query = compildQuery.query;
+        const result = await this.#props.executor.executeQuery(compildQuery, this.#props.queryId);
+        if (this.#props.parseContext.adapter.supportsReturning && query.returning) {
+            return result.rows;
+        }
+        else {
+            return [new UpdateResult(result.numUpdatedOrDeletedRows)];
+        }
+    }
+    /**
+     * Executes the query and returns the first result or undefined if
+     * the query returned no result.
+     */
+    async executeTakeFirst() {
+        const [result] = await this.execute();
+        return result;
+    }
+    /**
+     * Executes the query and returns the first result or throws if
+     * the query returned no result.
+     *
+     * By default an instance of {@link NoResultError} is thrown, but you can
+     * provide a custom error class as the only argument to throw a different
+     * error.
+     */
+    async executeTakeFirstOrThrow(errorConstructor = NoResultError) {
+        const result = await this.executeTakeFirst();
+        if (result === undefined) {
+            throw new errorConstructor(this.toOperationNode());
+        }
+        return result;
+    }
+}
+preventAwait(UpdateQueryBuilder, "don't await UpdateQueryBuilder instances directly. To execute the query you need to call `execute` or `executeTakeFirst`.");