kysely 0.23.4 → 0.24.0

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

@@ -2,77 +2,63 @@ 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, From, FromTables } from '../parser/table-parser.js';
-import { SelectExpression } from '../parser/select-parser.js';
+import { SelectExpression, SelectArg } from '../parser/select-parser.js';
 import { ReturningRow } from '../parser/returning-parser.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
-import { MergePartial, Nullable, SingleResultType } from '../util/type-utils.js';
+import { QueryNode } from '../operation-node/query-node.js';
+import { MergePartial, Nullable, SimplifyResult, SimplifySingleResult } from '../util/type-utils.js';
 import { UpdateQueryNode } from '../operation-node/update-query-node.js';
-import { UpdateObject } from '../parser/update-set-parser.js';
+import { UpdateObject, UpdateObjectFactory } 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 { UpdateResult } from './update-result.js';
 import { KyselyPlugin } from '../plugin/kysely-plugin.js';
-import { WhereInterface } from './where-interface.js';
+import { WhereExpressionFactory, WhereInterface } from './where-interface.js';
 import { ReturningInterface } from './returning-interface.js';
 import { NoResultErrorConstructor } from './no-result-error.js';
 import { Selectable } from '../util/column-type.js';
 import { Explainable, ExplainFormat } from '../util/explainable.js';
 import { AliasedExpression, Expression } from '../expression/expression.js';
-import { ComparisonOperatorExpression, OperandValueExpressionOrList, WhereGrouper } from '../parser/binary-operation-parser.js';
+import { ComparisonOperatorExpression, OperandValueExpressionOrList } from '../parser/binary-operation-parser.js';
 import { ExistsExpression } from '../parser/unary-operation-parser.js';
 import { KyselyTypeError } from '../util/type-error.js';
-export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyof DB, O> implements WhereInterface<DB, TB>, ReturningInterface<DB, TB, O>, OperationNodeSource, Compilable<O>, Explainable {
+import { Streamable } from '../util/streamable.js';
+export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyof DB, O> implements WhereInterface<DB, TB>, ReturningInterface<DB, TB, O>, OperationNodeSource, Compilable<O>, Explainable, Streamable<O> {
     #private;
     constructor(props: UpdateQueryBuilderProps);
     /**
-     * Adds a `where` clause to the query.
+     * Adds a `where` expression to the query.
      *
-     * Also see {@link orWhere}, {@link whereExists} and {@link whereRef}.
+     * Calling this method multiple times will combine the expressions using `and`.
      *
-     * ### Examples
+     * Also see {@link whereRef}
      *
-     * Find a row by column value:
+     * ### Examples
      *
      * ```ts
      * const person = await db
      *   .selectFrom('person')
      *   .selectAll()
-     *   .where('id', '=', 100)
+     *   .where('first_name', '=', 'Jennifer')
+     *   .where('age', '>', 40)
      *   .executeTakeFirst()
      * ```
      *
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * select * from "person" where "id" = $1
+     * select * from "person" where "first_name" = $1 and "age" > $2
      * ```
      *
      * Operator can be any supported operator or if the typings don't support it
-     * you can always use
+     * you can always use:
      *
      * ```ts
      * sql`your operator`
      * ```
      *
-     * The next example uses the `>` operator:
-     *
-     * ```ts
-     * const persons = await db
-     *   .selectFrom('person')
-     *   .selectAll()
-     *   .where('id', '>', 100)
-     *   .execute()
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select * from "person" where "id" > $1
-     * ```
-     *
-     * `where` methods don't change the type of the query. You can add
-     * conditional statements easily by doing something like this:
+     * You can add expressions conditionally like this:
      *
      * ```ts
      * let query = db
@@ -85,16 +71,16 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      *   query = query.where('first_name', '=', firstName)
      * }
      *
+     * if (lastName) {
+     *   query = query.where('last_name', '=', lastName)
+     * }
+     *
      * const persons = await query.execute()
      * ```
      *
-     * This is true for basically all methods execpt the `select` and
-     * `returning`, that __do__ change the return type of the query.
-     *
-     * Both the first and third argument can also be subqueries.
-     * A subquery is defined by passing a function and calling
-     * the `selectFrom` method of the object passed into the
-     * function:
+     * Both the first and third argument can also be arbitrary expressions like
+     * subqueries. An expression can defined by passing a function and calling
+     * the methods of the {@link ExpressionBuilder} passed to the callback:
      *
      * ```ts
      * const persons = await db
@@ -125,8 +111,7 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * ```
      *
      * A `where in` query can be built by using the `in` operator and an array
-     * of values. The values in the array can also be subqueries or raw
-     * {@link sql} expressions.
+     * of values. The values in the array can also be expressions:
      *
      * ```ts
      * const persons = await db
@@ -142,40 +127,53 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * select * from "person" where "id" in ($1, $2, $3)
      * ```
      *
-     * If everything else fails, you can always use the {@link sql} tag
-     * as any of the arguments, including the operator:
+     * For complex `where` expressions you can pass in a single callback and
+     * use the {@link ExpressionBuilder} to build your expression:
      *
      * ```ts
-     * import { sql } from 'kysely'
-     *
      * const persons = await db
      *   .selectFrom('person')
-     *   .selectAll()
-     *   .where(
-     *     sql`coalesce(first_name, last_name)`,
-     *     'like',
-     *     '%' + name + '%',
-     *   )
-     *   .execute()
+     *   .selectAll('person')
+     *   .where(({ cmpr, or, and, not, exists, selectFrom, val }) => and([
+     *     or([
+     *       cmpr('first_name', '=', firstName),
+     *       cmpr('age', '<', maxAge)
+     *     ]),
+     *     not(exists(
+     *       selectFrom('pet').select('pet.id').whereRef('pet.owner_id', '=', 'person.id')
+     *     ))
+     *   ]))
      * ```
      *
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * select * from "person"
-     * where coalesce(first_name, last_name) like $1
+     * select "person".*
+     * from "person"
+     * where (
+     *   (
+     *     "first_name" = $1
+     *     or "age" < $2
+     *   )
+     *   and not exists (
+     *     select "pet"."id" from "pet" where "pet"."owner_id" = "person"."id"
+     *   )
+     * )
      * ```
      *
-     * If you only pass one function argument to this method, it can be
-     * used to create parentheses around other where statements:
+     * If everything else fails, you can always use the {@link sql} tag
+     * as any of the arguments, including the operator:
      *
      * ```ts
+     * import { sql } from 'kysely'
+     *
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll()
-     *   .where((qb) => qb
-     *     .where('id', '=', 1)
-     *     .orWhere('id', '=', 2)
+     *   .where(
+     *     sql`coalesce(first_name, last_name)`,
+     *     'like',
+     *     '%' + name + '%',
      *   )
      *   .execute()
      * ```
@@ -183,7 +181,8 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * select * from "person" (where "id" = 1 or "id" = 2)
+     * select * from "person"
+     * where coalesce(first_name, last_name) like $1
      * ```
      *
      * In all examples above the columns were known at compile time
@@ -205,12 +204,12 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      *   .selectFrom('person')
      *   .selectAll()
      *   .where(ref(columnFromUserInput), '=', 1)
-     *   .orWhere(sql.id(columnFromUserInput), '=', 2)
+     *   .where(sql.id(columnFromUserInput), '=', 2)
      *   .execute()
      * ```
      */
     where<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): UpdateQueryBuilder<DB, UT, TB, O>;
-    where(grouper: WhereGrouper<DB, TB>): UpdateQueryBuilder<DB, UT, TB, O>;
+    where(factory: WhereExpressionFactory<DB, TB>): UpdateQueryBuilder<DB, UT, TB, O>;
     where(expression: Expression<any>): UpdateQueryBuilder<DB, UT, TB, O>;
     /**
      * Adds a `where` clause where both sides of the operator are references
@@ -242,7 +241,7 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * const persons = await db
      *   .selectFrom('person')
      *   .selectAll('person')
-     *   .select((qb) => qb
+     *   .select((eb) => eb
      *     .selectFrom('pet')
      *     .select('name')
      *     .whereRef('pet.owner_id', '=', 'person.id')
@@ -265,152 +264,33 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      */
     whereRef(lhs: ReferenceExpression<DB, TB>, op: ComparisonOperatorExpression, rhs: ReferenceExpression<DB, TB>): UpdateQueryBuilder<DB, UT, TB, O>;
     /**
-     * Adds an `or where` clause to the query. Otherwise works just like {@link where}.
-     *
-     * It's often necessary to wrap `or where` clauses in parentheses to control
-     * precendence. You can use the one argument version of the `where` method
-     * for that. See the examples.
-     *
-     * ### Examples
-     *
-     * ```ts
-     * const persons = await db
-     *   .selectFrom('person')
-     *   .selectAll()
-     *   .where('id', '=', 1)
-     *   .orWhere('id', '=', 2)
-     *   .execute()
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select * from "person" where "id" = 1 or "id" = 2
-     * ```
-     *
-     * Grouping with parentheses:
-     *
-     * ```ts
-     * const persons = await db
-     *   .selectFrom('person')
-     *   .selectAll()
-     *   .where((qb) => qb
-     *     .where('id', '=', 1)
-     *     .orWhere('id', '=', 2)
-     *   )
-     *   .execute()
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select * from "person" (where "id" = 1 or "id" = 2)
-     * ```
-     *
-     * Even the first `where` can be an `orWhere`. This is useful
-     * if you are looping through a set of conditions:
-     *
-     * ```ts
-     * const persons = await db
-     *   .selectFrom('person')
-     *   .selectAll()
-     *   .where((qb) => qb
-     *     .orWhere('id', '=', 1)
-     *     .orWhere('id', '=', 2)
-     *   )
-     *   .execute()
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select * from "person" (where "id" = 1 or "id" = 2)
-     * ```
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
     orWhere<RE extends ReferenceExpression<DB, TB>>(lhs: RE, op: ComparisonOperatorExpression, rhs: OperandValueExpressionOrList<DB, TB, RE>): UpdateQueryBuilder<DB, UT, TB, O>;
-    orWhere(grouper: WhereGrouper<DB, TB>): UpdateQueryBuilder<DB, UT, TB, O>;
+    orWhere(factory: WhereExpressionFactory<DB, TB>): UpdateQueryBuilder<DB, UT, TB, O>;
     orWhere(expression: Expression<any>): UpdateQueryBuilder<DB, UT, TB, O>;
     /**
-     * Adds an `or where` clause to the query. Otherwise works just like {@link whereRef}.
-     *
-     * Also see {@link orWhere} and {@link where}.
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
     orWhereRef(lhs: ReferenceExpression<DB, TB>, op: ComparisonOperatorExpression, rhs: ReferenceExpression<DB, TB>): UpdateQueryBuilder<DB, UT, TB, O>;
     /**
-     * Adds a `where exists` clause to the query.
-     *
-     * You can either use a subquery or a raw {@link sql} snippet.
-     *
-     * ### Examples
-     *
-     * The query below selets all persons that own a pet named Catto:
-     *
-     * ```ts
-     * const petName = 'Catto'
-     * const persons = await db
-     *   .selectFrom('person')
-     *   .selectAll()
-     *   .whereExists((qb) => qb
-     *     .selectFrom('pet')
-     *     .select('pet.id')
-     *     .whereRef('person.id', '=', 'pet.owner_id')
-     *     .where('pet.name', '=', petName)
-     *   )
-     *   .execute()
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select * from "person"
-     * where exists (
-     *   select "pet"."id"
-     *   from "pet"
-     *   where "person"."id" = "pet"."owner_id"
-     *   and "pet"."name" = $1
-     * )
-     * ```
-     *
-     * The same query as in the previous example but with using raw {@link sql}:
-     *
-     * ```ts
-     * import { sql } from 'kysely'
-     *
-     * const petName = 'Catto'
-     * db.selectFrom('person')
-     *   .selectAll()
-     *   .whereExists(
-     *     sql`(select pet.id from pet where person.id = pet.owner_id and pet.name = ${petName})`
-     *   )
-     * ```
-     *
-     * The generated SQL (PostgreSQL):
-     *
-     * ```sql
-     * select * from "person"
-     * where exists (
-     *   select pet.id
-     *   from pet
-     *   where person.id = pet.owner_id
-     *   and pet.name = $1
-     * )
-     * ```
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
     whereExists(arg: ExistsExpression<DB, TB>): UpdateQueryBuilder<DB, UT, TB, O>;
     /**
-     * Just like {@link whereExists} but creates a `not exists` clause.
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
     whereNotExists(arg: ExistsExpression<DB, TB>): UpdateQueryBuilder<DB, UT, TB, O>;
     /**
-     * Just like {@link whereExists} but creates an `or exists` clause.
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
     orWhereExists(arg: ExistsExpression<DB, TB>): UpdateQueryBuilder<DB, UT, TB, O>;
     /**
-     * Just like {@link whereExists} but creates an `or not exists` clause.
+     * @deprecated Follow [these](https://github.com/koskimas/kysely/releases/tag/0.24.0) instructions to migrate
      */
     orWhereNotExists(arg: ExistsExpression<DB, TB>): UpdateQueryBuilder<DB, UT, TB, O>;
     /**
-     * Clears all where clauses from the query.
+     * Clears all where expressions from the query.
      *
      * ### Examples
      *
@@ -440,9 +320,9 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * ```ts
      * db.updateTable('person')
      *   .from('pet')
-     *   .set({
-     *     first_name: (eb) => eb.ref('pet.name')
-     *   })
+     *   .set((eb) => ({
+     *     first_name: eb.ref('pet.name')
+     *   }))
      *   .whereRef('pet.owner_id', '=', 'person.id')
      * ```
      *
@@ -470,7 +350,7 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      *   .innerJoin('pet', 'pet.owner_id', 'person.id')
      *   // `select` needs to come after the call to `innerJoin` so
      *   // that you can select from the joined table.
-     *   .select('person.id', 'pet.name')
+     *   .select(['person.id', 'pet.name'])
      *   .execute()
      *
      * result[0].id
@@ -588,7 +468,11 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      *
      * 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 {@link sql} snippets or select queries.
+     * any expressions such as raw {@link sql} snippets or select queries.
+     *
+     * This method also accepts a callback that returns the update object. The
+     * callback takes an instance of `{@link ExpressionBuilder} as its only argument.
+     * The expression builder can be used to create arbitrary update expressions.
      *
      * The return value of an update query is an instance of {@link UpdateResult}.
      * You can use the {@link returning} method on supported databases to get out
@@ -641,19 +525,20 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * update "person" set "first_name" = $1, "last_name" = $2 where "id" = $3 returning "id"
      * ```
      *
-     * In addition to primitives, the values can also be raw sql expressions or
-     * select queries:
+     * In addition to primitives, the values can arbitrary expressions including
+     * raw `sql` snippets or subqueries:
      *
      * ```ts
      * import { sql } from 'kysely'
      *
      * const result = await db
      *   .updateTable('person')
-     *   .set({
+     *   .set(({ selectFrom, ref, fn }) => ({
      *     first_name: 'Jennifer',
+     *     middle_name: ref('first_name'),
+     *     age: selectFrom('person').select(fn.avg('age')),
      *     last_name: sql`${'Ani'} || ${'ston'}`,
-     *     age: db.selectFrom('person').select(sql`avg(age)`),
-     *   })
+     *   }))
      *   .where('id', '=', 1)
      *   .executeTakeFirst()
      *
@@ -665,12 +550,14 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      * ```sql
      * update "person" set
      * "first_name" = $1,
-     * "last_name" = $2 || $3,
-     * "age" = (select avg(age) from "person")
+     * "middle_name" = "first_name",
+     * "age" = (select avg(age) from "person"),
+     * "last_name" = $2 || $3
      * where "id" = $4
      * ```
      */
-    set(row: UpdateObject<DB, TB, UT>): UpdateQueryBuilder<DB, UT, TB, O>;
+    set(update: UpdateObject<DB, TB, UT>): UpdateQueryBuilder<DB, UT, TB, O>;
+    set(update: UpdateObjectFactory<DB, TB, UT>): UpdateQueryBuilder<DB, UT, TB, O>;
     /**
      * Allows you to return data from modified rows.
      *
@@ -722,23 +609,23 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      *     first_name: 'Jennifer',
      *     last_name: 'Aniston'
      *   })
-     *   .returning([
+     *   .returning(eb => [
      *     'id as id',
      *     sql<string>`concat(first_name, ' ', last_name)`.as('full_name'),
-     *     (qb) => qb.selectFrom('pets').select('pet.id').limit(1).as('first_pet_id')
+     *     eb.selectFrom('pets').select('pet.id').limit(1).as('first_pet_id')
      *   ])
      *   .executeTakeFirst()
      * ```
      */
-    returning<SE extends SelectExpression<DB, TB>>(selections: ReadonlyArray<SE>): UpdateQueryBuilder<DB, UT, TB, ReturningRow<DB, TB, O, SE>>;
-    returning<SE extends SelectExpression<DB, TB>>(selection: SE): UpdateQueryBuilder<DB, UT, TB, ReturningRow<DB, TB, O, SE>>;
+    returning<SE extends SelectExpression<DB, TB>>(selection: SelectArg<DB, TB, SE>): UpdateQueryBuilder<DB, UT, TB, ReturningRow<DB, TB, O, SE>>;
     /**
      * Adds a `returning *` to an insert/update/delete query on databases
      * that support `returning` such as PostgreSQL.
      */
     returningAll(): UpdateQueryBuilder<DB, UT, TB, Selectable<DB[TB]>>;
     /**
-     * Simply calls the given function passing `this` as the only argument.
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
      *
      * If you want to conditionally call a method on `this`, see
      * the {@link $if} method.
@@ -869,42 +756,87 @@ export declare class UpdateQueryBuilder<DB, UT extends keyof DB, TB extends keyo
      */
     withPlugin(plugin: KyselyPlugin): UpdateQueryBuilder<DB, UT, TB, O>;
     toOperationNode(): UpdateQueryNode;
-    compile(): CompiledQuery<O>;
+    compile(): CompiledQuery<SimplifyResult<O>>;
     /**
      * Executes the query and returns an array of rows.
      *
      * Also see the {@link executeTakeFirst} and {@link executeTakeFirstOrThrow} methods.
      */
-    execute(): Promise<O[]>;
+    execute(): Promise<SimplifyResult<O>[]>;
     /**
      * Executes the query and returns the first result or undefined if
      * the query returned no result.
      */
-    executeTakeFirst(): Promise<SingleResultType<O>>;
+    executeTakeFirst(): Promise<SimplifySingleResult<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
+     * provide a custom error class, or callback as the only argument to throw a different
      * error.
      */
-    executeTakeFirstOrThrow(errorConstructor?: NoResultErrorConstructor): Promise<O>;
+    executeTakeFirstOrThrow(errorConstructor?: NoResultErrorConstructor | ((node: QueryNode) => Error)): Promise<SimplifyResult<O>>;
     /**
-     * Executes query with `explain` statement before `update` keyword.
+     * Executes the query and streams the rows.
+     *
+     * The optional argument `chunkSize` defines how many rows to fetch from the database
+     * at a time. It only affects some dialects like PostgreSQL that support it.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const stream = db.
+     *   .selectFrom('person')
+     *   .select(['first_name', 'last_name'])
+     *   .where('gender', '=', 'other')
+     *   .stream()
+     *
+     * for await (const person of stream) {
+     *   console.log(person.first_name)
+     *
+     *   if (person.last_name === 'Something') {
+     *     // Breaking or returning before the stream has ended will release
+     *     // the database connection and invalidate the stream.
+     *     break
+     *   }
+     * }
+     * ```
+     */
+    stream(chunkSize?: number): AsyncIterableIterator<O>;
+    /**
+     * Executes query with `explain` statement before the main query.
      *
      * ```ts
      * const explained = await db
-     *  .updateTable('person')
-     *  .set(updates)
-     *  .where('id', '=', 123)
+     *  .selectFrom('person')
+     *  .where('gender', '=', 'female')
+     *  .selectAll()
      *  .explain('json')
      * ```
      *
      * The generated SQL (MySQL):
      *
      * ```sql
-     * explain format=json update `person` set `first_name` = ?, `last_name` = ? where `id` = ?
+     * explain format=json select * from `person` where `gender` = ?
+     * ```
+     *
+     * You can also execute `explain analyze` statements.
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const explained = await db
+     *  .selectFrom('person')
+     *  .where('gender', '=', 'female')
+     *  .selectAll()
+     *  .explain('json', sql`analyze`)
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * explain (analyze, format json) select * from "person" where "gender" = $1
      * ```
      */
     explain<ER extends Record<string, any> = Record<string, any>>(format?: ExplainFormat, options?: Expression<any>): Promise<ER[]>;