kysely 0.16.6 → 0.16.7

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

@@ -7,7 +7,7 @@ import { SelectExpression, QueryBuilderWithSelection, SelectAllQueryBuilder } fr
 import { ExistsExpression, FilterOperator, FilterValueExpressionOrList, WhereGrouper, HavingGrouper } from '../parser/filter-parser.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
 import { SelectQueryNode } from '../operation-node/select-query-node.js';
-import { AnyRawBuilder, SingleResultType } from '../util/type-utils.js';
+import { AnyRawBuilder, MergePartial, SingleResultType } from '../util/type-utils.js';
 import { OrderByDirectionExpression, OrderByExpression } from '../parser/order-by-parser.js';
 import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
@@ -1116,27 +1116,15 @@ export declare class SelectQueryBuilder<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
      *
-     * ```ts
-     * db.selectFrom('person')
-     *   .selectAll()
-     *   .call((qb) => {
-     *     if (something) {
-     *       return qb.where('something', '=', something)
-     *     } else {
-     *       return qb.where('somethingElse', '=', somethingElse)
-     *     }
-     *   })
-     *   .execute()
-     * ```
-     *
      * The next example uses a helper funtion `log` to log a query:
      *
      * ```ts
-     * function log<T extends AnyQueryBuilder>(qb: T): T {
+     * function log<T extends Compilable>(qb: T): T {
      *   console.log(qb.compile())
      *   return qb
      * }
@@ -1148,6 +1136,57 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * ```
      */
     call<T>(func: (qb: this) => T): T;
+    /**
+     * Call `func(this)` if `condition` is true.
+     *
+     * This method is especially handy with optional selects. Any `select` or `selectAll`
+     * 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.
+     *
+     * Also see [this recipe](https://github.com/koskimas/kysely/tree/master/recipes/conditional-selects.md)
+     *
+     * ### Examples
+     *
+     * ```ts
+     * async function getPerson(id: number, withLastName: boolean) {
+     *   return await db
+     *     .selectFrom('person')
+     *     .select(['id', 'first_name'])
+     *     .if(withLastName, (qb) => qb.select('last_name'))
+     *     .where('id', '=', id)
+     *     .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 `getPerson` function is:
+     *
+     * ```ts
+     * {
+     *   id: number
+     *   first_name: string
+     *   last_name?: string
+     * }
+     * ```
+     *
+     * You can also call any other methods inside the callback:
+     *
+     * ```ts
+     * const { count } = db.fn
+     *
+     * db.selectFrom('person')
+     *   .select('person.id')
+     *   .if(filterByFirstName, (qb) => qb.where('first_name', '=', firstName))
+     *   .if(filterByPetCount, (qb) => qb
+     *     .innerJoin('pet', 'pet.owner_id', 'person.id')
+     *     .having(count('pet.id'), '>', petCountLimit)
+     *     .groupBy('person.id')
+     *   )
+     * ```
+     */
+    if<O2 extends O>(condition: boolean, func: (qb: this) => SelectQueryBuilder<DB, TB, O2>): SelectQueryBuilder<DB, TB, MergePartial<O, O2>>;
     /**
      * Gives an alias for the query. This method is only useful for sub queries.
      *
@@ -1173,6 +1212,9 @@ export declare class SelectQueryBuilder<DB, TB extends keyof DB, O> implements W
      * don't support your use case.
      */
     castTo<T>(): SelectQueryBuilder<DB, TB, T>;
+    /**
+     * Returns a copy of this SelectQueryBuilder instance with the given plugin installed.
+     */
     withPlugin(plugin: KyselyPlugin): SelectQueryBuilder<DB, TB, O>;
     toOperationNode(): SelectQueryNode;
     compile(): CompiledQuery;

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

@@ -425,27 +425,15 @@ export class SelectQueryBuilder {
     /**
      * 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
      *
-     * ```ts
-     * db.selectFrom('person')
-     *   .selectAll()
-     *   .call((qb) => {
-     *     if (something) {
-     *       return qb.where('something', '=', something)
-     *     } else {
-     *       return qb.where('somethingElse', '=', somethingElse)
-     *     }
-     *   })
-     *   .execute()
-     * ```
-     *
      * The next example uses a helper funtion `log` to log a query:
      *
      * ```ts
-     * function log<T extends AnyQueryBuilder>(qb: T): T {
+     * function log<T extends Compilable>(qb: T): T {
      *   console.log(qb.compile())
      *   return qb
      * }
@@ -459,6 +447,64 @@ export class SelectQueryBuilder {
     call(func) {
         return func(this);
     }
+    /**
+     * Call `func(this)` if `condition` is true.
+     *
+     * This method is especially handy with optional selects. Any `select` or `selectAll`
+     * 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.
+     *
+     * Also see [this recipe](https://github.com/koskimas/kysely/tree/master/recipes/conditional-selects.md)
+     *
+     * ### Examples
+     *
+     * ```ts
+     * async function getPerson(id: number, withLastName: boolean) {
+     *   return await db
+     *     .selectFrom('person')
+     *     .select(['id', 'first_name'])
+     *     .if(withLastName, (qb) => qb.select('last_name'))
+     *     .where('id', '=', id)
+     *     .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 `getPerson` function is:
+     *
+     * ```ts
+     * {
+     *   id: number
+     *   first_name: string
+     *   last_name?: string
+     * }
+     * ```
+     *
+     * You can also call any other methods inside the callback:
+     *
+     * ```ts
+     * const { count } = db.fn
+     *
+     * db.selectFrom('person')
+     *   .select('person.id')
+     *   .if(filterByFirstName, (qb) => qb.where('first_name', '=', firstName))
+     *   .if(filterByPetCount, (qb) => qb
+     *     .innerJoin('pet', 'pet.owner_id', 'person.id')
+     *     .having(count('pet.id'), '>', petCountLimit)
+     *     .groupBy('person.id')
+     *   )
+     * ```
+     */
+    if(condition, func) {
+        if (condition) {
+            return func(this);
+        }
+        return new SelectQueryBuilder({
+            ...this.#props,
+        });
+    }
     /**
      * Gives an alias for the query. This method is only useful for sub queries.
      *
@@ -488,6 +534,9 @@ export class SelectQueryBuilder {
     castTo() {
         return new SelectQueryBuilder(this.#props);
     }
+    /**
+     * Returns a copy of this SelectQueryBuilder instance with the given plugin installed.
+     */
     withPlugin(plugin) {
         return new SelectQueryBuilder({
             ...this.#props,

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

@@ -6,13 +6,14 @@ 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 { 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 { UpdateResult } from './update-result.js';
 import { KyselyPlugin } from '../plugin/kysely-plugin.js';
 import { WhereInterface } from './where-interface.js';
 import { JoinInterface } from './join-interface.js';
@@ -676,24 +677,63 @@ export declare class UpdateQueryBuilder<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.updateTable('person')
      *   .set(values)
-     *   .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 updatePerson(id: number, updates: UpdateablePerson, returnLastName: boolean) {
+     *   return await db
+     *     .updateTable('person')
+     *     .set(updates)
+     *     .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 `updatePerson` function is:
+     *
+     * ```ts
+     * {
+     *   id: number
+     *   first_name: string
+     *   last_name?: string
+     * }
+     * ```
+     */
+    if<O2>(condition: boolean, func: (qb: this) => UpdateQueryBuilder<DB, TB, O2>): UpdateQueryBuilder<DB, TB, O2 extends UpdateResult ? UpdateResult : O extends UpdateResult ? Partial<O2> : MergePartial<O, O2>>;
     /**
      * Change the output type of the query.
      *
@@ -701,6 +741,9 @@ export declare class UpdateQueryBuilder<DB, TB extends keyof DB, O> implements W
      * don't support your use case.
      */
     castTo<T>(): UpdateQueryBuilder<DB, TB, T>;
+    /**
+     * Returns a copy of this UpdateQueryBuilder instance with the given plugin installed.
+     */
     withPlugin(plugin: KyselyPlugin): UpdateQueryBuilder<DB, TB, O>;
     toOperationNode(): UpdateQueryNode;
     compile(): CompiledQuery;

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

@@ -192,26 +192,72 @@ export class UpdateQueryBuilder {
     /**
      * 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.updateTable('person')
      *   .set(values)
-     *   .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 updatePerson(id: number, updates: UpdateablePerson, returnLastName: boolean) {
+     *   return await db
+     *     .updateTable('person')
+     *     .set(updates)
+     *     .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 `updatePerson` function is:
+     *
+     * ```ts
+     * {
+     *   id: number
+     *   first_name: string
+     *   last_name?: string
+     * }
+     * ```
+     */
+    if(condition, func) {
+        if (condition) {
+            return func(this);
+        }
+        return new UpdateQueryBuilder({
+            ...this.#props,
+        });
+    }
     /**
      * Change the output type of the query.
      *
@@ -221,6 +267,9 @@ export class UpdateQueryBuilder {
     castTo() {
         return new UpdateQueryBuilder(this.#props);
     }
+    /**
+     * Returns a copy of this UpdateQueryBuilder instance with the given plugin installed.
+     */
     withPlugin(plugin) {
         return new UpdateQueryBuilder({
             ...this.#props,

package/dist/esm/query-creator.d.ts

@@ -162,7 +162,7 @@ export declare class QueryCreator<DB> {
     /**
      * Creates a delete query.
      *
-     * See the {@link WhereInterface.where} method for examples on how to specify
+     * See the {@link DeleteQueryBuilder.where} method for examples on how to specify
      * a where clause for the delete operation.
      *
      * The return value of the query is an instance of {@link DeleteResult}.
@@ -182,7 +182,7 @@ export declare class QueryCreator<DB> {
     /**
      * Creates an update query.
      *
-     * See the {@link WhereInterface.where} method for examples on how to specify
+     * See the {@link UpdateQueryBuilder.where} method for examples on how to specify
      * a where clause for the update operation.
      *
      * See the {@link UpdateQueryBuilder.set} method for examples on how to

package/dist/esm/query-creator.js

@@ -76,7 +76,7 @@ export class QueryCreator {
     /**
      * Creates a delete query.
      *
-     * See the {@link WhereInterface.where} method for examples on how to specify
+     * See the {@link DeleteQueryBuilder.where} method for examples on how to specify
      * a where clause for the delete operation.
      *
      * The return value of the query is an instance of {@link DeleteResult}.
@@ -103,7 +103,7 @@ export class QueryCreator {
     /**
      * Creates an update query.
      *
-     * See the {@link WhereInterface.where} method for examples on how to specify
+     * See the {@link UpdateQueryBuilder.where} method for examples on how to specify
      * a where clause for the update operation.
      *
      * See the {@link UpdateQueryBuilder.set} method for examples on how to

package/dist/esm/schema/create-view-builder.js

@@ -3,7 +3,7 @@ import { preventAwait } from '../util/prevent-await.js';
 import { freeze } from '../util/object-utils.js';
 import { CreateViewNode } from '../operation-node/create-view-node.js';
 import { parseColumnName } from '../parser/reference-parser.js';
-import { ImmediateValuePlugin } from '../plugin/immediate-value.ts/immediate-value-plugin.js';
+import { ImmediateValuePlugin } from '../plugin/immediate-value/immediate-value-plugin.js';
 export class CreateViewBuilder {
     #props;
     constructor(props) {

package/dist/esm/util/object-utils.d.ts

@@ -16,3 +16,4 @@ export declare function asArray<T>(arg: T | T[]): T[];
 export declare function asReadonlyArray<T>(arg: T | ReadonlyArray<T>): ReadonlyArray<T>;
 export declare function isReadonlyArray(arg: unknown): arg is ReadonlyArray<unknown>;
 export declare function noop<T>(obj: T): T;
+export declare function compare(obj1: unknown, obj2: unknown): boolean;

package/dist/esm/util/object-utils.js

@@ -65,3 +65,51 @@ export function isReadonlyArray(arg) {
 export function noop(obj) {
     return obj;
 }
+export function compare(obj1, obj2) {
+    if (isReadonlyArray(obj1) && isReadonlyArray(obj2)) {
+        return compareArrays(obj1, obj2);
+    }
+    else if (isObject(obj1) && isObject(obj2)) {
+        return compareObjects(obj1, obj2);
+    }
+    return obj1 === obj2;
+}
+function compareArrays(arr1, arr2) {
+    if (arr1.length !== arr2.length) {
+        return false;
+    }
+    for (let i = 0; i < arr1.length; ++i) {
+        if (!compare(arr1[i], arr2[i])) {
+            return false;
+        }
+    }
+    return true;
+}
+function compareObjects(obj1, obj2) {
+    if (isBuffer(obj1) && isBuffer(obj2)) {
+        return compareBuffers(obj1, obj2);
+    }
+    else if (isDate(obj1) && isDate(obj2)) {
+        return compareDates(obj1, obj2);
+    }
+    return compareGenericObjects(obj1, obj2);
+}
+function compareBuffers(buf1, buf2) {
+    return Buffer.compare(buf1, buf2) === 0;
+}
+function compareDates(date1, date2) {
+    return date1.getTime() === date2.getTime();
+}
+function compareGenericObjects(obj1, obj2) {
+    const keys1 = Object.keys(obj1);
+    const keys2 = Object.keys(obj2);
+    if (keys1.length !== keys2.length) {
+        return false;
+    }
+    for (const key of keys1) {
+        if (!compare(obj1[key], obj2[key])) {
+            return false;
+        }
+    }
+    return true;
+}

package/dist/esm/util/type-utils.d.ts

@@ -111,3 +111,24 @@ export declare type UnknownRow = Record<string, unknown>;
 export declare type Nullable<T> = {
     [P in keyof T]: T[P] | null;
 };
+/**
+ * Takes all properties from T1 and merges all properties from T2
+ * that don't exist in T1 as optional properties.
+ *
+ * Example:
+ *
+ * interface Person {
+ *   name: string
+ *   age: number
+ * }
+ *
+ * interface Pet {
+ *   name: string
+ *   species: 'cat' | 'dog'
+ * }
+ *
+ * type Merged = MergePartial<Person, Pet>
+ *
+ * // { name: string, age: number, species?: 'cat' | 'dog' }
+ */
+export declare type MergePartial<T1, T2> = T1 & Partial<Omit<T2, keyof T1>>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kysely",
-  "version": "0.16.6",
+  "version": "0.16.7",
   "description": "Type safe SQL query builder",
   "repository": {
     "type": "git",
@@ -25,9 +25,11 @@
     "test:node:build": "rm -rf test/node/dist && tsc -p test/node",
     "test:node": "mocha --timeout 15000 test/node/dist/**/*.test.js",
     "test:browser:build": "rm -rf test/browser/bundle.js && esbuild test/browser/main.ts --bundle --outfile=test/browser/bundle.js",
-    "test:browser": "npm run clean && npm run build:esm && npm run test:browser:build && node test/browser/test.js",
+    "test:browser": "npm run build && npm run test:browser:build && node test/browser/test.js",
+    "test:deno": "npm run build && deno run test/deno/local.test.ts && deno run test/deno/cdn.test.ts",
     "test:typings": "tsd test/typings",
     "test:esmimports": "node scripts/check-esm-imports.js",
+    "test:esbuild": "esbuild --bundle --platform=node --external:pg-native dist/esm/index.js --outfile=/dev/null",
     "prettier": "prettier --write src/**/*.ts test/**/*.ts",
     "build": "npm run clean && npm run build:esm && npm run build:cjs && npm run script:module-fixup && npm run script:copy-interface-doc",
     "build:esm": "tsc -p tsconfig.json && npm run script:add-deno-type-references",