kysely 0.27.1 → 0.27.3

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

@@ -12,6 +12,7 @@ import { LimitNode } from '../operation-node/limit-node.js';
 import { parseOrderBy, } from '../parser/order-by-parser.js';
 import { parseValueBinaryOperationOrExpression, parseReferentialBinaryOperation, } from '../parser/binary-operation-parser.js';
 import { parseValueExpression, } from '../parser/value-parser.js';
+import { parseTop } from '../parser/top-parser.js';
 export class DeleteQueryBuilder {
     #props;
     constructor(props) {
@@ -35,6 +36,51 @@ export class DeleteQueryBuilder {
             queryNode: QueryNode.cloneWithoutWhere(this.#props.queryNode),
         });
     }
+    /**
+     * Changes a `delete from` query into a `delete top from` query.
+     *
+     * `top` clause is only supported by some dialects like MS SQL Server.
+     *
+     * ### Examples
+     *
+     * Delete the first 5 rows:
+     *
+     * ```ts
+     * await db
+     *   .deleteFrom('person')
+     *   .top(5)
+     *   .where('age', '>', 18)
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (MS SQL Server):
+     *
+     * ```sql
+     * delete top(5) from "person" where "age" > @1
+     * ```
+     *
+     * Delete the first 50% of rows:
+     *
+     * ```ts
+     * await db
+     *   .deleteFrom('person')
+     *   .top(50, 'percent')
+     *   .where('age', '>', 18)
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (MS SQL Server):
+     *
+     * ```sql
+     * delete top(50) percent from "person" where "age" > @1
+     * ```
+     */
+    top(expression, modifiers) {
+        return new DeleteQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithTop(this.#props.queryNode, parseTop(expression, modifiers)),
+        });
+    }
     using(tables) {
         return new DeleteQueryBuilder({
             ...this.#props,
@@ -77,6 +123,80 @@ export class DeleteQueryBuilder {
             queryNode: QueryNode.cloneWithReturning(this.#props.queryNode, parseSelectAll(table)),
         });
     }
+    /**
+     * Clears all `returning` clauses from the query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.deleteFrom('pet')
+     *   .returningAll()
+     *   .where('name', '=', 'Max')
+     *   .clearReturning()
+     * ```
+     *
+     * The generated SQL(PostgreSQL):
+     *
+     * ```sql
+     * delete from "pet" where "name" = "Max"
+     * ```
+     */
+    clearReturning() {
+        return new DeleteQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithoutReturning(this.#props.queryNode),
+        });
+    }
+    /**
+     * Clears the `limit` clause from the query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.deleteFrom('pet')
+     *   .returningAll()
+     *   .where('name', '=', 'Max')
+     *   .limit(5)
+     *   .clearLimit()
+     * ```
+     *
+     * The generated SQL(PostgreSQL):
+     *
+     * ```sql
+     * delete from "pet" where "name" = "Max" returning *
+     * ```
+     */
+    clearLimit() {
+        return new DeleteQueryBuilder({
+            ...this.#props,
+            queryNode: DeleteQueryNode.cloneWithoutLimit(this.#props.queryNode),
+        });
+    }
+    /**
+     * Clears the `order by` clause from the query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.deleteFrom('pet')
+     *   .returningAll()
+     *   .where('name', '=', 'Max')
+     *   .orderBy('id')
+     *   .clearOrderBy()
+     * ```
+     *
+     * The generated SQL(PostgreSQL):
+     *
+     * ```sql
+     * delete from "pet" where "name" = "Max" returning *
+     * ```
+     */
+    clearOrderBy() {
+        return new DeleteQueryBuilder({
+            ...this.#props,
+            queryNode: DeleteQueryNode.cloneWithoutOrderBy(this.#props.queryNode),
+        });
+    }
     /**
      * Adds an `order by` clause to the query.
      *

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

@@ -1,7 +1,7 @@
 import { OperationNodeSource } from '../operation-node/operation-node-source.js';
 import { CompiledQuery } from '../query-compiler/compiled-query.js';
 import { SelectExpression, SelectCallback } from '../parser/select-parser.js';
-import { InsertObjectOrList, InsertObjectOrListFactory } from '../parser/insert-values-parser.js';
+import { InsertExpression } from '../parser/insert-values-parser.js';
 import { InsertQueryNode } from '../operation-node/insert-query-node.js';
 import { QueryNode } from '../operation-node/query-node.js';
 import { NarrowPartial, SimplifyResult, SimplifySingleResult } from '../util/type-utils.js';
@@ -184,8 +184,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * }))
      * ```
      */
-    values(insert: InsertObjectOrList<DB, TB>): InsertQueryBuilder<DB, TB, O>;
-    values(insert: InsertObjectOrListFactory<DB, TB>): InsertQueryBuilder<DB, TB, O>;
+    values(insert: InsertExpression<DB, TB>): InsertQueryBuilder<DB, TB, O>;
     /**
      * Sets the columns to insert.
      *
@@ -242,6 +241,14 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
     expression(expression: ExpressionOrFactory<DB, TB, any>): InsertQueryBuilder<DB, TB, O>;
     /**
      * Creates an `insert into "person" default values` query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.insertInto('person')
+     *   .defaultValues()
+     *   .execute()
+     * ```
      */
     defaultValues(): InsertQueryBuilder<DB, TB, O>;
     /**
@@ -266,6 +273,50 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * ```
      */
     ignore(): InsertQueryBuilder<DB, TB, O>;
+    /**
+     * Changes an `insert into` query to an `insert top into` query.
+     *
+     * `top` clause is only supported by some dialects like MS SQL Server.
+     *
+     * ### Examples
+     *
+     * Insert the first 5 rows:
+     *
+     * ```ts
+     * await db.insertInto('person')
+     *   .top(5)
+     *   .columns(['first_name', 'gender'])
+     *   .expression(
+     *     (eb) => eb.selectFrom('pet').select(['name', sql.lit('other').as('gender')])
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MS SQL Server):
+     *
+     * ```sql
+     * insert top(5) into "person" ("first_name", "gender") select "name", 'other' as "gender" from "pet"
+     * ```
+     *
+     * Insert the first 50 percent of rows:
+     *
+     * ```ts
+     * await db.insertInto('person')
+     *   .top(50, 'percent')
+     *   .columns(['first_name', 'gender'])
+     *   .expression(
+     *     (eb) => eb.selectFrom('pet').select(['name', sql.lit('other').as('gender')])
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MS SQL Server):
+     *
+     * ```sql
+     * insert top(50) percent into "person" ("first_name", "gender") select "name", 'other' as "gender" from "pet"
+     * ```
+     */
+    top(expression: number | bigint, modifiers?: 'percent'): InsertQueryBuilder<DB, TB, O>;
     /**
      * Adds an `on conflict` clause to the query.
      *
@@ -504,6 +555,25 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * that support `returning` such as PostgreSQL.
      */
     returningAll(): InsertQueryBuilder<DB, TB, Selectable<DB[TB]>>;
+    /**
+     * Clears all `returning` clauses from the query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.insertInto('person')
+     *   .values({ first_name: 'James', last_name: 'Smith', age: 42 })
+     *   .returning(['first_name'])
+     *   .clearReturning()
+     * ```
+     *
+     * The generated SQL(PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("James", "Smith", 42)
+     * ```
+     */
+    clearReturning(): InsertQueryBuilder<DB, TB, InsertResult>;
     /**
      * Simply calls the provided function passing `this` as the only argument. `$call` returns
      * what the provided function returns.

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

@@ -13,11 +13,172 @@ import { parseExpression, } from '../parser/expression-parser.js';
 import { ColumnNode } from '../operation-node/column-node.js';
 import { OnConflictBuilder, } from './on-conflict-builder.js';
 import { OnConflictNode } from '../operation-node/on-conflict-node.js';
+import { parseTop } from '../parser/top-parser.js';
 export class InsertQueryBuilder {
     #props;
     constructor(props) {
         this.#props = freeze(props);
     }
+    /**
+     * Sets the values to insert for an {@link Kysely.insertInto | insert} query.
+     *
+     * This method takes an object whose keys are column names and values are
+     * values to insert. In addition to the column's type, the values can be
+     * raw {@link sql} snippets or select queries.
+     *
+     * You must provide all fields you haven't explicitly marked as nullable
+     * or optional using {@link Generated} or {@link ColumnType}.
+     *
+     * The return value of an `insert` query is an instance of {@link InsertResult}. The
+     * {@link InsertResult.insertId | insertId} field holds the auto incremented primary
+     * key if the database returned one.
+     *
+     * On PostgreSQL and some other dialects, you need to call `returning` to get
+     * something out of the query.
+     *
+     * Also see the {@link expression} method for inserting the result of a select
+     * query or any other expression.
+     *
+     * ### Examples
+     *
+     * <!-- siteExample("insert", "Single row", 10) -->
+     *
+     * Insert a single row:
+     *
+     * ```ts
+     * const result = await db
+     *   .insertInto('person')
+     *   .values({
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston',
+     *     age: 40
+     *   })
+     *   .executeTakeFirst()
+     *
+     * // `insertId` is only available on dialects that
+     * // automatically return the id of the inserted row
+     * // such as MySQL and SQLite. On PostgreSQL, for example,
+     * // you need to add a `returning` clause to the query to
+     * // get anything out. See the "returning data" example.
+     * console.log(result.insertId)
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * insert into `person` (`first_name`, `last_name`, `age`) values (?, ?, ?)
+     * ```
+     *
+     * <!-- siteExample("insert", "Multiple rows", 20) -->
+     *
+     * On dialects that support it (for example PostgreSQL) you can insert multiple
+     * rows by providing an array. Note that the return value is once again very
+     * dialect-specific. Some databases may only return the id of the *last* inserted
+     * row and some return nothing at all unless you call `returning`.
+     *
+     * ```ts
+     * await db
+     *   .insertInto('person')
+     *   .values([{
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston',
+     *     age: 40,
+     *   }, {
+     *     first_name: 'Arnold',
+     *     last_name: 'Schwarzenegger',
+     *     age: 70,
+     *   }])
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name", "last_name", "age") values (($1, $2, $3), ($4, $5, $6))
+     * ```
+     *
+     * <!-- siteExample("insert", "Returning data", 30) -->
+     *
+     * On supported dialects like PostgreSQL you need to chain `returning` to the query to get
+     * the inserted row's columns (or any other expression) as the return value. `returning`
+     * works just like `select`. Refer to `select` method's examples and documentation for
+     * more info.
+     *
+     * ```ts
+     * const result = await db
+     *   .insertInto('person')
+     *   .values({
+     *     first_name: 'Jennifer',
+     *     last_name: 'Aniston',
+     *     age: 40,
+     *   })
+     *   .returning(['id', 'first_name as name'])
+     *   .executeTakeFirstOrThrow()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("first_name", "last_name", "age") values ($1, $2, $3) returning "id", "first_name" as "name"
+     * ```
+     *
+     * <!-- siteExample("insert", "Complex values", 40) -->
+     *
+     * In addition to primitives, the values can also be arbitrary expressions.
+     * You can build the expressions by using a callback and calling the methods
+     * on the expression builder passed to it:
+     *
+     * ```ts
+     * import { sql } from 'kysely'
+     *
+     * const ani = "Ani"
+     * const ston = "ston"
+     *
+     * const result = await db
+     *   .insertInto('person')
+     *   .values(({ ref, selectFrom, fn }) => ({
+     *     first_name: 'Jennifer',
+     *     last_name: sql`concat(${ani}, ${ston})`,
+     *     middle_name: ref('first_name'),
+     *     age: selectFrom('person')
+     *       .select(fn.avg<number>('age')
+     *       .as('avg_age')),
+     *   }))
+     *   .executeTakeFirst()
+     * ```
+     *
+     * The generated SQL (PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" (
+     *   "first_name",
+     *   "last_name",
+     *   "middle_name",
+     *   "age"
+     * )
+     * values (
+     *   $1,
+     *   concat($2, $3),
+     *   "first_name",
+     *   (select avg("age") as "avg_age" from "person")
+     * )
+     * ```
+     *
+     * You can also use the callback version of subqueries or raw expressions:
+     *
+     * ```ts
+     * db.with('jennifer', (db) => db
+     *   .selectFrom('person')
+     *   .where('first_name', '=', 'Jennifer')
+     *   .select(['id', 'first_name', 'gender'])
+     *   .limit(1)
+     * ).insertInto('pet').values((eb) => ({
+     *   owner_id: eb.selectFrom('jennifer').select('id'),
+     *   name: eb.selectFrom('jennifer').select('first_name'),
+     *   species: 'cat',
+     * }))
+     * ```
+     */
     values(insert) {
         const [columns, values] = parseInsertExpression(insert);
         return new InsertQueryBuilder({
@@ -98,6 +259,14 @@ export class InsertQueryBuilder {
     }
     /**
      * Creates an `insert into "person" default values` query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.insertInto('person')
+     *   .defaultValues()
+     *   .execute()
+     * ```
      */
     defaultValues() {
         return new InsertQueryBuilder({
@@ -136,6 +305,55 @@ export class InsertQueryBuilder {
             }),
         });
     }
+    /**
+     * Changes an `insert into` query to an `insert top into` query.
+     *
+     * `top` clause is only supported by some dialects like MS SQL Server.
+     *
+     * ### Examples
+     *
+     * Insert the first 5 rows:
+     *
+     * ```ts
+     * await db.insertInto('person')
+     *   .top(5)
+     *   .columns(['first_name', 'gender'])
+     *   .expression(
+     *     (eb) => eb.selectFrom('pet').select(['name', sql.lit('other').as('gender')])
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MS SQL Server):
+     *
+     * ```sql
+     * insert top(5) into "person" ("first_name", "gender") select "name", 'other' as "gender" from "pet"
+     * ```
+     *
+     * Insert the first 50 percent of rows:
+     *
+     * ```ts
+     * await db.insertInto('person')
+     *   .top(50, 'percent')
+     *   .columns(['first_name', 'gender'])
+     *   .expression(
+     *     (eb) => eb.selectFrom('pet').select(['name', sql.lit('other').as('gender')])
+     *   )
+     *   .execute()
+     * ```
+     *
+     * The generated SQL (MS SQL Server):
+     *
+     * ```sql
+     * insert top(50) percent into "person" ("first_name", "gender") select "name", 'other' as "gender" from "pet"
+     * ```
+     */
+    top(expression, modifiers) {
+        return new InsertQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithTop(this.#props.queryNode, parseTop(expression, modifiers)),
+        });
+    }
     /**
      * Adds an `on conflict` clause to the query.
      *
@@ -335,6 +553,30 @@ export class InsertQueryBuilder {
             queryNode: QueryNode.cloneWithReturning(this.#props.queryNode, parseSelectAll()),
         });
     }
+    /**
+     * Clears all `returning` clauses from the query.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * db.insertInto('person')
+     *   .values({ first_name: 'James', last_name: 'Smith', age: 42 })
+     *   .returning(['first_name'])
+     *   .clearReturning()
+     * ```
+     *
+     * The generated SQL(PostgreSQL):
+     *
+     * ```sql
+     * insert into "person" ("James", "Smith", 42)
+     * ```
+     */
+    clearReturning() {
+        return new InsertQueryBuilder({
+            ...this.#props,
+            queryNode: QueryNode.cloneWithoutReturning(this.#props.queryNode),
+        });
+    }
     /**
      * Simply calls the provided function passing `this` as the only argument. `$call` returns
      * what the provided function returns.