kysely 0.16.6 → 0.16.10

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

@@ -6,7 +6,7 @@ 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 { AnyRawBuilder, MergePartial, SingleResultType } from '../util/type-utils.js';
 import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
 import { QueryId } from '../util/query-id.js';
@@ -16,6 +16,7 @@ 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';
+import { DeleteResult } from './delete-result.js';
 import { DeleteQueryNode } from '../operation-node/delete-query-node.js';
 import { Selectable } from '../util/column-type.js';
 export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements WhereInterface<DB, TB>, JoinInterface<DB, TB>, ReturningInterface<DB, TB, O>, OperationNodeSource, Compilable {
@@ -563,8 +564,6 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * Return arbitrary expressions:
      *
      * ```ts
-     * const { raw } = db
-     *
      * const { id, full_name, first_pet_id } = await db
      *   .insertInto('person')
      *   .values({
@@ -573,7 +572,7 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      *   })
      *   .returning([
      *     'id as id',
-     *     raw<string>(`concat(first_name, ' ', last_name)`).as('full_name'),
+     *     db.raw<string>(`concat(first_name, ' ', last_name)`).as('full_name'),
      *     (qb) => qb.selectFrom('pets').select('pet.id').limit(1).as('first_pet_id')
      *   ])
      *   .executeTakeFirst()
@@ -589,23 +588,61 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
     /**
      * Simply calls the given function passing `this` as the only argument.
      *
-     * This method can be useful when adding optional method calls:
+     * If you want to conditionally call a method on `this`, see
+     * the {@link if} method.
      *
      * ### Examples
      *
+     * The next example uses a helper funtion `log` to log a query:
+     *
      * ```ts
+     * function log<T extends Compilable>(qb: T): T {
+     *   console.log(qb.compile())
+     *   return qb
+     * }
+     *
      * db.deleteFrom('person')
-     *   .call((qb) => {
-     *     if (something) {
-     *       return qb.where('something', '=', something)
-     *     } else {
-     *       return qb.where('somethingElse', '=', somethingElse)
-     *     }
-     *   })
+     *   .call(log)
      *   .execute()
      * ```
      */
     call<T>(func: (qb: this) => T): T;
+    /**
+     * Call `func(this)` if `condition` is true.
+     *
+     * This method is especially handy with optional selects. Any `returning` or `returningAll`
+     * method calls add columns as optional fields to the output type when called inside
+     * the `func` callback. This is because we can't know if those selections were actually
+     * made before running the code.
+     *
+     * You can also call any other methods inside the callback.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * async function deletePerson(id: number, returnLastName: boolean) {
+     *   return await db
+     *     .deleteFrom('person')
+     *     .where('id', '=', id)
+     *     .returning(['id', 'first_name'])
+     *     .if(returnLastName, (qb) => qb.returning('last_name'))
+     *     .executeTakeFirstOrThrow()
+     * }
+     * ```
+     *
+     * Any selections added inside the `if` callback will be added as optional fields to the
+     * output type since we can't know if the selections were actually made before running
+     * the code. In the example above the return type of the `deletePerson` function is:
+     *
+     * ```ts
+     * {
+     *   id: number
+     *   first_name: string
+     *   last_name?: string
+     * }
+     * ```
+     */
+    if<O2>(condition: boolean, func: (qb: this) => DeleteQueryBuilder<DB, TB, O2>): DeleteQueryBuilder<DB, TB, O2 extends DeleteResult ? DeleteResult : O extends DeleteResult ? Partial<O2> : MergePartial<O, O2>>;
     /**
      * Change the output type of the query.
      *
@@ -613,6 +650,9 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * don't support your use case.
      */
     castTo<T>(): DeleteQueryBuilder<DB, TB, T>;
+    /**
+     * Returns a copy of this DeleteQueryBuilder instance with the given plugin installed.
+     */
     withPlugin(plugin: KyselyPlugin): DeleteQueryBuilder<DB, TB, O>;
     toOperationNode(): DeleteQueryNode;
     compile(): CompiledQuery;

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

@@ -99,25 +99,70 @@ export class DeleteQueryBuilder {
     /**
      * Simply calls the given function passing `this` as the only argument.
      *
-     * This method can be useful when adding optional method calls:
+     * If you want to conditionally call a method on `this`, see
+     * the {@link if} method.
      *
      * ### Examples
      *
+     * The next example uses a helper funtion `log` to log a query:
+     *
      * ```ts
+     * function log<T extends Compilable>(qb: T): T {
+     *   console.log(qb.compile())
+     *   return qb
+     * }
+     *
      * db.deleteFrom('person')
-     *   .call((qb) => {
-     *     if (something) {
-     *       return qb.where('something', '=', something)
-     *     } else {
-     *       return qb.where('somethingElse', '=', somethingElse)
-     *     }
-     *   })
+     *   .call(log)
      *   .execute()
      * ```
      */
     call(func) {
         return func(this);
     }
+    /**
+     * Call `func(this)` if `condition` is true.
+     *
+     * This method is especially handy with optional selects. Any `returning` or `returningAll`
+     * method calls add columns as optional fields to the output type when called inside
+     * the `func` callback. This is because we can't know if those selections were actually
+     * made before running the code.
+     *
+     * You can also call any other methods inside the callback.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * async function deletePerson(id: number, returnLastName: boolean) {
+     *   return await db
+     *     .deleteFrom('person')
+     *     .where('id', '=', id)
+     *     .returning(['id', 'first_name'])
+     *     .if(returnLastName, (qb) => qb.returning('last_name'))
+     *     .executeTakeFirstOrThrow()
+     * }
+     * ```
+     *
+     * Any selections added inside the `if` callback will be added as optional fields to the
+     * output type since we can't know if the selections were actually made before running
+     * the code. In the example above the return type of the `deletePerson` function is:
+     *
+     * ```ts
+     * {
+     *   id: number
+     *   first_name: string
+     *   last_name?: string
+     * }
+     * ```
+     */
+    if(condition, func) {
+        if (condition) {
+            return func(this);
+        }
+        return new DeleteQueryBuilder({
+            ...this.#props,
+        });
+    }
     /**
      * Change the output type of the query.
      *
@@ -127,6 +172,9 @@ export class DeleteQueryBuilder {
     castTo() {
         return new DeleteQueryBuilder(this.#props);
     }
+    /**
+     * Returns a copy of this DeleteQueryBuilder instance with the given plugin installed.
+     */
     withPlugin(plugin) {
         return new DeleteQueryBuilder({
             ...this.#props,

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

@@ -4,6 +4,9 @@ import { RawBuilder } from '../raw-builder/raw-builder.js';
 /**
  * Helpers for type safe SQL function calls.
  *
+ * You can always use {@link Kysely.raw} to call functions and build arbitrary
+ * expressions. This module simply has shortcuts for most common function calls.
+ *
  * ### Examples
  *
  * ```ts
@@ -35,12 +38,33 @@ export declare class FunctionBuilder<DB, TB extends keyof DB> {
     constructor(props: FunctionBuilderProps);
     /**
      * Calls the `max` function for the column given as the argument.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const { max } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(max('price').as('max_price'))
+     *   .execute()
+     * ```
      */
-    min<C extends StringReference<DB, TB>>(column: C): RawBuilder<ExtractTypeFromReferenceExpression<DB, TB, C>>;
+    max<C extends StringReference<DB, TB>>(column: C): RawBuilder<ExtractTypeFromReferenceExpression<DB, TB, C>>;
     /**
      * Calls the `min` function for the column given as the argument.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const { min } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(min('price').as('min_price'))
+     *   .execute()
+     * ```
+     *
      */
-    max<C extends StringReference<DB, TB>>(column: C): RawBuilder<ExtractTypeFromReferenceExpression<DB, TB, C>>;
+    min<C extends StringReference<DB, TB>>(column: C): RawBuilder<ExtractTypeFromReferenceExpression<DB, TB, C>>;
     /**
      * Calls the `avg` function for the column given as the argument.
      *
@@ -58,7 +82,7 @@ export declare class FunctionBuilder<DB, TB extends keyof DB> {
      * const { avg } = db.fn
      *
      * db.selectFrom('toy')
-     *   .select(avg<number>('price'))
+     *   .select(avg<number>('price').as('avg_price'))
      *   .execute()
      * ```
      */
@@ -80,7 +104,7 @@ export declare class FunctionBuilder<DB, TB extends keyof DB> {
      * const { sum } = db.fn
      *
      * db.selectFrom('toy')
-     *   .select(sum<number>('price'))
+     *   .select(sum<number>('price').as('total_price'))
      *   .execute()
      * ```
      */
@@ -102,7 +126,7 @@ export declare class FunctionBuilder<DB, TB extends keyof DB> {
      * const { count } = db.fn
      *
      * db.selectFrom('toy')
-     *   .select(count<number>('price'))
+     *   .select(count<number>('id').as('num_toys'))
      *   .execute()
      * ```
      */

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

@@ -5,6 +5,9 @@ import { createQueryId } from '../util/query-id.js';
 /**
  * Helpers for type safe SQL function calls.
  *
+ * You can always use {@link Kysely.raw} to call functions and build arbitrary
+ * expressions. This module simply has shortcuts for most common function calls.
+ *
  * ### Examples
  *
  * ```ts
@@ -43,15 +46,36 @@ export class FunctionBuilder {
     }
     /**
      * Calls the `max` function for the column given as the argument.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const { max } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(max('price').as('max_price'))
+     *   .execute()
+     * ```
      */
-    min(column) {
-        return this.#oneArgFunction('min', column);
+    max(column) {
+        return this.#oneArgFunction('max', column);
     }
     /**
      * Calls the `min` function for the column given as the argument.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const { min } = db.fn
+     *
+     * db.selectFrom('toy')
+     *   .select(min('price').as('min_price'))
+     *   .execute()
+     * ```
+     *
      */
-    max(column) {
-        return this.#oneArgFunction('max', column);
+    min(column) {
+        return this.#oneArgFunction('min', column);
     }
     /**
      * Calls the `avg` function for the column given as the argument.
@@ -70,7 +94,7 @@ export class FunctionBuilder {
      * const { avg } = db.fn
      *
      * db.selectFrom('toy')
-     *   .select(avg<number>('price'))
+     *   .select(avg<number>('price').as('avg_price'))
      *   .execute()
      * ```
      */
@@ -94,7 +118,7 @@ export class FunctionBuilder {
      * const { sum } = db.fn
      *
      * db.selectFrom('toy')
-     *   .select(sum<number>('price'))
+     *   .select(sum<number>('price').as('total_price'))
      *   .execute()
      * ```
      */
@@ -118,7 +142,7 @@ export class FunctionBuilder {
      * const { count } = db.fn
      *
      * db.selectFrom('toy')
-     *   .select(count<number>('price'))
+     *   .select(count<number>('id').as('num_toys'))
      *   .execute()
      * ```
      */

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

@@ -3,12 +3,13 @@ import { CompiledQuery } from '../query-compiler/compiled-query.js';
 import { SelectExpression } from '../parser/select-parser.js';
 import { InsertObject } from '../parser/insert-values-parser.js';
 import { InsertQueryNode } from '../operation-node/insert-query-node.js';
-import { SingleResultType } from '../util/type-utils.js';
+import { MergePartial, SingleResultType } from '../util/type-utils.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 { InsertResult } from './insert-result.js';
 import { KyselyPlugin } from '../plugin/kysely-plugin.js';
 import { ReturningRow } from '../parser/returning-parser.js';
 import { NoResultErrorConstructor } from './no-result-error.js';
@@ -422,8 +423,6 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * Return arbitrary expressions:
      *
      * ```ts
-     * const { raw } = db
-     *
      * const { id, full_name, first_pet_id } = await db
      *   .insertInto('person')
      *   .values({
@@ -432,7 +431,7 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      *   })
      *   .returning([
      *     'id as id',
-     *     raw<string>(`concat(first_name, ' ', last_name)`).as('full_name'),
+     *     db.raw<string>(`concat(first_name, ' ', last_name)`).as('full_name'),
      *     (qb) => qb.selectFrom('pets').select('pet.id').limit(1).as('first_pet_id')
      *   ])
      *   .executeTakeFirst()
@@ -448,24 +447,62 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
     /**
      * Simply calls the given function passing `this` as the only argument.
      *
-     * This method can be useful when adding optional method calls:
+     * If you want to conditionally call a method on `this`, see
+     * the {@link if} method.
      *
      * ### Examples
      *
+     * The next example uses a helper funtion `log` to log a query:
+     *
      * ```ts
-     * db.insertInto('person')
-     *   .selectAll()
-     *   .call((qb) => {
-     *     if (something) {
-     *       return qb.onConflict((oc) => oc.column('something').doNothing())
-     *     } else {
-     *       return qb.onConflict((oc) => oc.column('something_else').doNothing())
-     *     }
-     *   })
+     * function log<T extends Compilable>(qb: T): T {
+     *   console.log(qb.compile())
+     *   return qb
+     * }
+     *
+     * db.updateTable('person')
+     *   .set(values)
+     *   .call(log)
      *   .execute()
      * ```
      */
     call<T>(func: (qb: this) => T): T;
+    /**
+     * Call `func(this)` if `condition` is true.
+     *
+     * This method is especially handy with optional selects. Any `returning` or `returningAll`
+     * method calls add columns as optional fields to the output type when called inside
+     * the `func` callback. This is because we can't know if those selections were actually
+     * made before running the code.
+     *
+     * You can also call any other methods inside the callback.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * async function insertPerson(values: InsertablePerson, returnLastName: boolean) {
+     *   return await db
+     *     .insertInto('person')
+     *     .values(values)
+     *     .returning(['id', 'first_name'])
+     *     .if(returnLastName, (qb) => qb.returning('last_name'))
+     *     .executeTakeFirstOrThrow()
+     * }
+     * ```
+     *
+     * Any selections added inside the `if` callback will be added as optional fields to the
+     * output type since we can't know if the selections were actually made before running
+     * the code. In the example above the return type of the `insertPerson` function is:
+     *
+     * ```ts
+     * {
+     *   id: number
+     *   first_name: string
+     *   last_name?: string
+     * }
+     * ```
+     */
+    if<O2>(condition: boolean, func: (qb: this) => InsertQueryBuilder<DB, TB, O2>): InsertQueryBuilder<DB, TB, O2 extends InsertResult ? InsertResult : O extends InsertResult ? Partial<O2> : MergePartial<O, O2>>;
     /**
      * Change the output type of the query.
      *
@@ -473,6 +510,9 @@ export declare class InsertQueryBuilder<DB, TB extends keyof DB, O> implements R
      * don't support your use case.
      */
     castTo<T>(): InsertQueryBuilder<DB, TB, T>;
+    /**
+     * Returns a copy of this InsertQueryBuilder instance with the given plugin installed.
+     */
     withPlugin(plugin: KyselyPlugin): InsertQueryBuilder<DB, TB, O>;
     toOperationNode(): InsertQueryNode;
     compile(): CompiledQuery;

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

@@ -315,26 +315,71 @@ export class InsertQueryBuilder {
     /**
      * Simply calls the given function passing `this` as the only argument.
      *
-     * This method can be useful when adding optional method calls:
+     * If you want to conditionally call a method on `this`, see
+     * the {@link if} method.
      *
      * ### Examples
      *
+     * The next example uses a helper funtion `log` to log a query:
+     *
      * ```ts
-     * db.insertInto('person')
-     *   .selectAll()
-     *   .call((qb) => {
-     *     if (something) {
-     *       return qb.onConflict((oc) => oc.column('something').doNothing())
-     *     } else {
-     *       return qb.onConflict((oc) => oc.column('something_else').doNothing())
-     *     }
-     *   })
+     * function log<T extends Compilable>(qb: T): T {
+     *   console.log(qb.compile())
+     *   return qb
+     * }
+     *
+     * db.updateTable('person')
+     *   .set(values)
+     *   .call(log)
      *   .execute()
      * ```
      */
     call(func) {
         return func(this);
     }
+    /**
+     * Call `func(this)` if `condition` is true.
+     *
+     * This method is especially handy with optional selects. Any `returning` or `returningAll`
+     * method calls add columns as optional fields to the output type when called inside
+     * the `func` callback. This is because we can't know if those selections were actually
+     * made before running the code.
+     *
+     * You can also call any other methods inside the callback.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * async function insertPerson(values: InsertablePerson, returnLastName: boolean) {
+     *   return await db
+     *     .insertInto('person')
+     *     .values(values)
+     *     .returning(['id', 'first_name'])
+     *     .if(returnLastName, (qb) => qb.returning('last_name'))
+     *     .executeTakeFirstOrThrow()
+     * }
+     * ```
+     *
+     * Any selections added inside the `if` callback will be added as optional fields to the
+     * output type since we can't know if the selections were actually made before running
+     * the code. In the example above the return type of the `insertPerson` function is:
+     *
+     * ```ts
+     * {
+     *   id: number
+     *   first_name: string
+     *   last_name?: string
+     * }
+     * ```
+     */
+    if(condition, func) {
+        if (condition) {
+            return func(this);
+        }
+        return new InsertQueryBuilder({
+            ...this.#props,
+        });
+    }
     /**
      * Change the output type of the query.
      *
@@ -344,6 +389,9 @@ export class InsertQueryBuilder {
     castTo() {
         return new InsertQueryBuilder(this.#props);
     }
+    /**
+     * Returns a copy of this InsertQueryBuilder instance with the given plugin installed.
+     */
     withPlugin(plugin) {
         return new InsertQueryBuilder({
             ...this.#props,

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

@@ -45,8 +45,6 @@ export interface ReturningInterface<DB, TB extends keyof DB, O> {
      * Return arbitrary expressions:
      *
      * ```ts
-     * const { raw } = db
-     *
      * const { id, full_name, first_pet_id } = await db
      *   .insertInto('person')
      *   .values({
@@ -55,7 +53,7 @@ export interface ReturningInterface<DB, TB extends keyof DB, O> {
      *   })
      *   .returning([
      *     'id as id',
-     *     raw<string>(`concat(first_name, ' ', last_name)`).as('full_name'),
+     *     db.raw<string>(`concat(first_name, ' ', last_name)`).as('full_name'),
      *     (qb) => qb.selectFrom('pets').select('pet.id').limit(1).as('first_pet_id')
      *   ])
      *   .executeTakeFirst()