kysely 0.16.3 → 0.16.7

package/dist/cjs/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/cjs/query-builder/update-query-builder.js

@@ -194,26 +194,72 @@ 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.
      *
@@ -223,6 +269,9 @@ 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/cjs/query-compiler/default-query-compiler.d.ts

@@ -44,7 +44,6 @@ import { ValueNode } from '../operation-node/value-node.js';
 import { WhereNode } from '../operation-node/where-node.js';
 import { CommonTableExpressionNode } from '../operation-node/common-table-expression-node.js';
 import { WithNode } from '../operation-node/with-node.js';
-import { PrimitiveValue } from '../util/object-utils.js';
 import { CompiledQuery } from './compiled-query.js';
 import { RootOperationNode, QueryCompiler } from './query-compiler.js';
 import { HavingNode } from '../operation-node/having-node.js';
@@ -150,5 +149,5 @@ export declare class DefaultQueryCompiler extends OperationNodeVisitor implement
     protected getRightIdentifierWrapper(): string;
     protected getCurrentParameterPlaceholder(): string;
     protected addParameter(parameter: unknown): void;
-    protected appendImmediateValue(value: PrimitiveValue): void;
+    protected appendImmediateValue(value: unknown): void;
 }

package/dist/cjs/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/cjs/query-creator.js

@@ -78,7 +78,7 @@ 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}.
@@ -105,7 +105,7 @@ 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/cjs/schema/alter-table-builder.d.ts

@@ -5,13 +5,13 @@ import { OperationNodeSource } from '../operation-node/operation-node-source.js'
 import { OnModifyForeignAction } from '../operation-node/references-node.js';
 import { CompiledQuery } from '../query-compiler/compiled-query.js';
 import { Compilable } from '../util/compilable.js';
-import { PrimitiveValue } from '../util/object-utils.js';
 import { ColumnDefinitionBuilder, ColumnDefinitionBuilderInterface } from './column-definition-builder.js';
 import { AnyRawBuilder } from '../util/type-utils.js';
 import { QueryId } from '../util/query-id.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
 import { DataTypeExpression } from '../parser/data-type-parser.js';
 import { ForeignKeyConstraintBuilder, ForeignKeyConstraintBuilderInterface } from './foreign-key-constraint-builder.js';
+import { DefaultValueExpression } from '../parser/default-value-parser.js';
 /**
  * This builder can be used to create a `alter table` query.
  */
@@ -43,7 +43,7 @@ export declare class AlterColumnBuilder {
     #private;
     constructor(props: AlterColumnBuilderProps);
     setDataType(dataType: ColumnDataType): AlterTableExecutor;
-    setDefault(value: PrimitiveValue | AnyRawBuilder): AlterTableExecutor;
+    setDefault(value: DefaultValueExpression): AlterTableExecutor;
     dropDefault(): AlterTableExecutor;
     setNotNull(): AlterTableExecutor;
     dropNotNull(): AlterTableExecutor;
@@ -141,8 +141,21 @@ export declare class AlterTableAddColumnBuilder implements ColumnDefinitionBuild
      *   .addColumn('number_of_legs', 'integer', (col) => col.defaultTo(4))
      *   .execute()
      * ```
+     *
+     * Raw expressions are also supported:
+     *
+     * ```ts
+     * db.schema
+     *   .createTable('pet')
+     *   .addColumn(
+     *     'number_of_legs',
+     *     'integer',
+     *     (col) => col.defaultTo(db.raw('any SQL here'))
+     *   )
+     *   .execute()
+     * ```
      */
-    defaultTo(value: PrimitiveValue | AnyRawBuilder): AlterTableAddColumnBuilder;
+    defaultTo(value: DefaultValueExpression): AlterTableAddColumnBuilder;
     /**
      * Adds a check constraint for the column.
      *
@@ -286,8 +299,21 @@ export declare class AlterTableModifyColumnBuilder implements ColumnDefinitionBu
      *   .addColumn('number_of_legs', 'integer', (col) => col.defaultTo(4))
      *   .execute()
      * ```
+     *
+     * Raw expressions are also supported:
+     *
+     * ```ts
+     * db.schema
+     *   .createTable('pet')
+     *   .addColumn(
+     *     'number_of_legs',
+     *     'integer',
+     *     (col) => col.defaultTo(db.raw('any SQL here'))
+     *   )
+     *   .execute()
+     * ```
      */
-    defaultTo(value: PrimitiveValue | AnyRawBuilder): AlterTableModifyColumnBuilder;
+    defaultTo(value: DefaultValueExpression): AlterTableModifyColumnBuilder;
     /**
      * Adds a check constraint for the column.
      *

package/dist/cjs/schema/alter-table-builder.js

@@ -8,10 +8,8 @@ const column_definition_node_js_1 = require("../operation-node/column-definition
 const data_type_node_js_1 = require("../operation-node/data-type-node.js");
 const drop_column_node_js_1 = require("../operation-node/drop-column-node.js");
 const identifier_node_js_1 = require("../operation-node/identifier-node.js");
-const operation_node_source_js_1 = require("../operation-node/operation-node-source.js");
 const rename_column_node_js_1 = require("../operation-node/rename-column-node.js");
 const table_node_js_1 = require("../operation-node/table-node.js");
-const value_node_js_1 = require("../operation-node/value-node.js");
 const object_utils_js_1 = require("../util/object-utils.js");
 const prevent_await_js_1 = require("../util/prevent-await.js");
 const column_definition_builder_js_1 = require("./column-definition-builder.js");
@@ -23,6 +21,7 @@ const unique_constraint_node_js_1 = require("../operation-node/unique-constraint
 const check_constraint_node_js_1 = require("../operation-node/check-constraint-node.js");
 const foreign_key_constraint_node_js_1 = require("../operation-node/foreign-key-constraint-node.js");
 const column_node_js_1 = require("../operation-node/column-node.js");
+const default_value_parser_js_1 = require("../parser/default-value-parser.js");
 /**
  * This builder can be used to create a `alter table` query.
  */
@@ -130,9 +129,7 @@ class AlterColumnBuilder {
             ...this.#props,
             alterTableNode: alter_table_node_js_1.AlterTableNode.cloneWith(this.#props.alterTableNode, {
                 alterColumn: alter_column_node_js_1.AlterColumnNode.cloneWith(this.#props.alterColumnNode, {
-                    setDefault: (0, operation_node_source_js_1.isOperationNodeSource)(value)
-                        ? value.toOperationNode()
-                        : value_node_js_1.ValueNode.createImmediate(value),
+                    setDefault: (0, default_value_parser_js_1.parseDefaultValueExpression)(value),
                 }),
             }),
         });

package/dist/cjs/schema/column-definition-builder.d.ts

@@ -1,6 +1,5 @@
 import { OperationNodeSource } from '../operation-node/operation-node-source.js';
 import { OnModifyForeignAction } from '../operation-node/references-node.js';
-import { PrimitiveValue } from '../util/object-utils.js';
 import { ColumnDefinitionNode } from '../operation-node/column-definition-node.js';
 import { AnyRawBuilder } from '../util/type-utils.js';
 import { DefaultValueExpression } from '../parser/default-value-parser.js';
@@ -83,8 +82,21 @@ export interface ColumnDefinitionBuilderInterface {
      *   .addColumn('number_of_legs', 'integer', (col) => col.defaultTo(4))
      *   .execute()
      * ```
+     *
+     * Raw expressions are also supported:
+     *
+     * ```ts
+     * db.schema
+     *   .createTable('pet')
+     *   .addColumn(
+     *     'number_of_legs',
+     *     'integer',
+     *     (col) => col.defaultTo(db.raw('any SQL here'))
+     *   )
+     *   .execute()
+     * ```
      */
-    defaultTo(value: PrimitiveValue | AnyRawBuilder): ColumnDefinitionBuilderInterface;
+    defaultTo(value: DefaultValueExpression): ColumnDefinitionBuilderInterface;
     /**
      * Adds a check constraint for the column.
      *
@@ -222,6 +234,19 @@ export declare class ColumnDefinitionBuilder implements ColumnDefinitionBuilderI
      *   .addColumn('number_of_legs', 'integer', (col) => col.defaultTo(4))
      *   .execute()
      * ```
+     *
+     * Raw expressions are also supported:
+     *
+     * ```ts
+     * db.schema
+     *   .createTable('pet')
+     *   .addColumn(
+     *     'number_of_legs',
+     *     'integer',
+     *     (col) => col.defaultTo(db.raw('any SQL here'))
+     *   )
+     *   .execute()
+     * ```
      */
     defaultTo(value: DefaultValueExpression): ColumnDefinitionBuilder;
     /**

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

@@ -5,7 +5,7 @@ const prevent_await_js_1 = require("../util/prevent-await.js");
 const object_utils_js_1 = require("../util/object-utils.js");
 const create_view_node_js_1 = require("../operation-node/create-view-node.js");
 const reference_parser_js_1 = require("../parser/reference-parser.js");
-const immediate_value_plugin_js_1 = require("../plugin/immediate-value.ts/immediate-value-plugin.js");
+const immediate_value_plugin_js_1 = require("../plugin/immediate-value/immediate-value-plugin.js");
 class CreateViewBuilder {
     #props;
     constructor(props) {

package/dist/cjs/util/log.d.ts

@@ -17,6 +17,7 @@ export declare type LogConfig = ReadonlyArray<LogLevel> | Logger;
 export declare class Log {
     #private;
     constructor(config: LogConfig);
+    isLevelEnabled(level: LogLevel): boolean;
     query(getEvent: () => QueryLogEvent): void;
     error(getEvent: () => ErrorLogEvent): void;
 }

package/dist/cjs/util/log.js

@@ -22,6 +22,9 @@ class Log {
             });
         }
     }
+    isLevelEnabled(level) {
+        return this.#levels[level];
+    }
     query(getEvent) {
         if (this.#levels.query) {
             this.#logger(getEvent());

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

@@ -1,14 +1,13 @@
-/// <reference types="node" />
-export declare type PrimitiveValue = string | number | boolean | null | Date | Buffer | BigInt;
-export declare function isEmpty(obj: ArrayLike<unknown> | string | object | Buffer): boolean;
+export declare function isEmpty(obj: ArrayLike<unknown> | string | object): boolean;
 export declare function isString(obj: unknown): obj is string;
 export declare function isNumber(obj: unknown): obj is number;
 export declare function isBoolean(obj: unknown): obj is boolean;
 export declare function isNull(obj: unknown): obj is null;
 export declare function isDate(obj: unknown): obj is Date;
 export declare function isBigInt(obj: unknown): obj is BigInt;
-export declare function isBuffer(obj: unknown): obj is Buffer;
-export declare function isPrimitive(obj: unknown): obj is PrimitiveValue;
+export declare function isBuffer(obj: unknown): obj is {
+    length: number;
+};
 export declare function isFunction(obj: unknown): obj is Function;
 export declare function isObject(obj: unknown): obj is Record<string, unknown>;
 export declare function getLast<T>(arr: ArrayLike<T>): T | undefined;
@@ -17,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/cjs/util/object-utils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.noop = exports.isReadonlyArray = exports.asReadonlyArray = exports.asArray = exports.freeze = exports.getLast = exports.isObject = exports.isFunction = exports.isPrimitive = exports.isBuffer = exports.isBigInt = exports.isDate = exports.isNull = exports.isBoolean = exports.isNumber = exports.isString = exports.isEmpty = void 0;
+exports.compare = exports.noop = exports.isReadonlyArray = exports.asReadonlyArray = exports.asArray = exports.freeze = exports.getLast = exports.isObject = exports.isFunction = exports.isBuffer = exports.isBigInt = exports.isDate = exports.isNull = exports.isBoolean = exports.isNumber = exports.isString = exports.isEmpty = void 0;
 function isEmpty(obj) {
     if (Array.isArray(obj) || isString(obj) || isBuffer(obj)) {
         return obj.length === 0;
@@ -35,20 +35,12 @@ function isBigInt(obj) {
     return typeof obj === 'bigint';
 }
 exports.isBigInt = isBigInt;
+// Don't change the returnd type to `obj is Buffer` to not create a
+// hard dependency to node.
 function isBuffer(obj) {
     return typeof Buffer !== 'undefined' && Buffer.isBuffer(obj);
 }
 exports.isBuffer = isBuffer;
-function isPrimitive(obj) {
-    return (isString(obj) ||
-        isNumber(obj) ||
-        isBoolean(obj) ||
-        isNull(obj) ||
-        isDate(obj) ||
-        isBigInt(obj) ||
-        isBuffer(obj));
-}
-exports.isPrimitive = isPrimitive;
 function isFunction(obj) {
     return typeof obj === 'function';
 }
@@ -91,3 +83,52 @@ function noop(obj) {
     return obj;
 }
 exports.noop = noop;
+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;
+}
+exports.compare = compare;
+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/cjs/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>>;