kysely 0.23.5 → 0.24.0

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

@@ -79,6 +79,13 @@ class CreateViewBuilder {
             }),
         });
     }
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call(func) {
+        return func(this);
+    }
     toOperationNode() {
         return this.#props.executor.transformQuery(this.#props.node, this.#props.queryId);
     }

package/dist/cjs/schema/drop-index-builder.d.ts

@@ -14,6 +14,11 @@ export declare class DropIndexBuilder implements OperationNodeSource, Compilable
     on(table: string): DropIndexBuilder;
     ifExists(): DropIndexBuilder;
     cascade(): DropIndexBuilder;
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call<T>(func: (qb: this) => T): T;
     toOperationNode(): DropIndexNode;
     compile(): CompiledQuery;
     execute(): Promise<void>;

package/dist/cjs/schema/drop-index-builder.js

@@ -38,6 +38,13 @@ class DropIndexBuilder {
             }),
         });
     }
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call(func) {
+        return func(this);
+    }
     toOperationNode() {
         return this.#props.executor.transformQuery(this.#props.node, this.#props.queryId);
     }

package/dist/cjs/schema/drop-schema-builder.d.ts

@@ -9,6 +9,11 @@ export declare class DropSchemaBuilder implements OperationNodeSource, Compilabl
     constructor(props: DropSchemaBuilderProps);
     ifExists(): DropSchemaBuilder;
     cascade(): DropSchemaBuilder;
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call<T>(func: (qb: this) => T): T;
     toOperationNode(): DropSchemaNode;
     compile(): CompiledQuery;
     execute(): Promise<void>;

package/dist/cjs/schema/drop-schema-builder.js

@@ -25,6 +25,13 @@ class DropSchemaBuilder {
             }),
         });
     }
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call(func) {
+        return func(this);
+    }
     toOperationNode() {
         return this.#props.executor.transformQuery(this.#props.node, this.#props.queryId);
     }

package/dist/cjs/schema/drop-table-builder.d.ts

@@ -9,6 +9,11 @@ export declare class DropTableBuilder implements OperationNodeSource, Compilable
     constructor(props: DropTableBuilderProps);
     ifExists(): DropTableBuilder;
     cascade(): DropTableBuilder;
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call<T>(func: (qb: this) => T): T;
     toOperationNode(): DropTableNode;
     compile(): CompiledQuery;
     execute(): Promise<void>;

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

@@ -25,6 +25,13 @@ class DropTableBuilder {
             }),
         });
     }
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call(func) {
+        return func(this);
+    }
     toOperationNode() {
         return this.#props.executor.transformQuery(this.#props.node, this.#props.queryId);
     }

package/dist/cjs/schema/drop-type-builder.d.ts

@@ -8,6 +8,11 @@ export declare class DropTypeBuilder implements OperationNodeSource, Compilable
     #private;
     constructor(props: DropTypeBuilderProps);
     ifExists(): DropTypeBuilder;
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call<T>(func: (qb: this) => T): T;
     toOperationNode(): DropTypeNode;
     compile(): CompiledQuery;
     execute(): Promise<void>;

package/dist/cjs/schema/drop-type-builder.js

@@ -17,6 +17,13 @@ class DropTypeBuilder {
             }),
         });
     }
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call(func) {
+        return func(this);
+    }
     toOperationNode() {
         return this.#props.executor.transformQuery(this.#props.node, this.#props.queryId);
     }

package/dist/cjs/schema/drop-view-builder.d.ts

@@ -10,6 +10,11 @@ export declare class DropViewBuilder implements OperationNodeSource, Compilable
     materialized(): DropViewBuilder;
     ifExists(): DropViewBuilder;
     cascade(): DropViewBuilder;
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call<T>(func: (qb: this) => T): T;
     toOperationNode(): DropViewNode;
     compile(): CompiledQuery;
     execute(): Promise<void>;

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

@@ -33,6 +33,13 @@ class DropViewBuilder {
             }),
         });
     }
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call(func) {
+        return func(this);
+    }
     toOperationNode() {
         return this.#props.executor.transformQuery(this.#props.node, this.#props.queryId);
     }

package/dist/cjs/schema/foreign-key-constraint-builder.d.ts

@@ -10,5 +10,10 @@ export declare class ForeignKeyConstraintBuilder implements ForeignKeyConstraint
     constructor(node: ForeignKeyConstraintNode);
     onDelete(onDelete: OnModifyForeignAction): ForeignKeyConstraintBuilder;
     onUpdate(onUpdate: OnModifyForeignAction): ForeignKeyConstraintBuilder;
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call<T>(func: (qb: this) => T): T;
     toOperationNode(): ForeignKeyConstraintNode;
 }

package/dist/cjs/schema/foreign-key-constraint-builder.js

@@ -19,6 +19,13 @@ class ForeignKeyConstraintBuilder {
             onUpdate: (0, on_modify_action_parser_js_1.parseOnModifyForeignAction)(onUpdate),
         }));
     }
+    /**
+     * Simply calls the provided function passing `this` as the only argument. `$call` returns
+     * what the provided function returns.
+     */
+    $call(func) {
+        return func(this);
+    }
     toOperationNode() {
         return this.#node;
     }

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

@@ -2,3 +2,4 @@ import { CompiledQuery } from '../query-compiler/compiled-query.js';
 export interface Compilable<O = unknown> {
     compile(): CompiledQuery<O>;
 }
+export declare function isCompilable(value: unknown): value is Compilable;

package/dist/cjs/util/compilable.js

@@ -1,2 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCompilable = void 0;
+const object_utils_js_1 = require("./object-utils.js");
+function isCompilable(value) {
+    return (0, object_utils_js_1.isObject)(value) && (0, object_utils_js_1.isFunction)(value.compile);
+}
+exports.isCompilable = isCompilable;

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

@@ -1,5 +1,40 @@
 import { Expression } from '../expression/expression.js';
 export declare type ExplainFormat = 'text' | 'xml' | 'json' | 'yaml' | 'traditional' | 'tree';
 export interface Explainable {
+    /**
+     * Executes query with `explain` statement before the main query.
+     *
+     * ```ts
+     * const explained = await db
+     *  .selectFrom('person')
+     *  .where('gender', '=', 'female')
+     *  .selectAll()
+     *  .explain('json')
+     * ```
+     *
+     * The generated SQL (MySQL):
+     *
+     * ```sql
+     * 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<O extends Record<string, any> = Record<string, any>>(format?: ExplainFormat, options?: Expression<any>): Promise<O[]>;
 }

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

@@ -10,6 +10,8 @@ export interface QueryLogEvent {
 export interface ErrorLogEvent {
     readonly level: 'error';
     readonly error: unknown;
+    readonly query: CompiledQuery;
+    readonly queryDurationMillis: number;
 }
 export declare type LogEvent = QueryLogEvent | ErrorLogEvent;
 export declare type Logger = (event: LogEvent) => void;

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

@@ -12,7 +12,7 @@ function isEmpty(obj) {
 }
 exports.isEmpty = isEmpty;
 function isUndefined(obj) {
-    return obj === undefined;
+    return typeof obj === 'undefined' || obj === undefined;
 }
 exports.isUndefined = isUndefined;
 function isString(obj) {

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

@@ -0,0 +1,29 @@
+export interface Streamable<O> {
+    /**
+     * 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>;
+}

package/dist/cjs/util/streamable.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -144,3 +144,4 @@ export declare type IsNever<T> = [T] extends [never] ? true : false;
  * Evaluates to `true` if the types `T` and `U` are equal.
  */
 export declare type Equals<T, U> = (<G>() => G extends T ? 1 : 2) extends <G>() => G extends U ? 1 : 2 ? true : false;
+export declare type SqlBool = boolean | 0 | 1;

package/dist/esm/dialect/mysql/mysql-adapter.js

@@ -17,9 +17,9 @@ export class MysqlAdapter extends DialectAdapterBase {
         // is released using `release_lock`. This way we know that the lock is either
         // released by us after successfull or failed migrations OR it's released by
         // MySQL if the process gets killed for some reason.
-        await sql `select get_lock(${sql.literal(LOCK_ID)}, ${sql.literal(LOCK_TIMEOUT_SECONDS)})`.execute(db);
+        await sql `select get_lock(${sql.lit(LOCK_ID)}, ${sql.lit(LOCK_TIMEOUT_SECONDS)})`.execute(db);
     }
     async releaseMigrationLock(db) {
-        await sql `select release_lock(${sql.literal(LOCK_ID)})`.execute(db);
+        await sql `select release_lock(${sql.lit(LOCK_ID)})`.execute(db);
     }
 }

package/dist/esm/dialect/mysql/mysql-driver.d.ts

@@ -42,7 +42,7 @@ declare class MysqlConnection implements DatabaseConnection {
     #private;
     constructor(rawConnection: MysqlPoolConnection);
     executeQuery<O>(compiledQuery: CompiledQuery): Promise<QueryResult<O>>;
-    streamQuery<O>(compiledQuery: CompiledQuery, chunkSize: number): AsyncIterableIterator<QueryResult<O>>;
+    streamQuery<O>(compiledQuery: CompiledQuery, _chunkSize: number): AsyncIterableIterator<QueryResult<O>>;
     [PRIVATE_RELEASE_METHOD](): void;
 }
 export {};

package/dist/esm/dialect/mysql/mysql-driver.js

@@ -124,7 +124,7 @@ class MysqlConnection {
             });
         });
     }
-    async *streamQuery(compiledQuery, chunkSize) {
+    async *streamQuery(compiledQuery, _chunkSize) {
         const stream = this.#rawConnection
             .query(compiledQuery.sql, compiledQuery.parameters)
             .stream({

package/dist/esm/dialect/postgres/postgres-adapter.js

@@ -12,7 +12,7 @@ export class PostgresAdapter extends DialectAdapterBase {
     }
     async acquireMigrationLock(db) {
         // Acquire a transaction level advisory lock.
-        await sql `select pg_advisory_xact_lock(${sql.literal(LOCK_ID)})`.execute(db);
+        await sql `select pg_advisory_xact_lock(${sql.lit(LOCK_ID)})`.execute(db);
     }
     async releaseMigrationLock() {
         // Nothing to do here. `pg_advisory_xact_lock` is automatically released at the

package/dist/esm/dialect/sqlite/sqlite-dialect.d.ts

@@ -27,6 +27,7 @@ import { SqliteDialectConfig } from './sqlite-dialect-config.js';
  * new SqliteDialect({
  *   database: async () => new Database('db.sqlite')
  * })
+ * ```
  */
 export declare class SqliteDialect implements Dialect {
     #private;

package/dist/esm/dialect/sqlite/sqlite-dialect.js

@@ -26,6 +26,7 @@ import { freeze } from '../../util/object-utils.js';
  * new SqliteDialect({
  *   database: async () => new Database('db.sqlite')
  * })
+ * ```
  */
 export class SqliteDialect {
     #config;

package/dist/esm/driver/runtime-driver.js

@@ -74,7 +74,7 @@ export class RuntimeDriver {
                 return await executeQuery.call(connection, compiledQuery);
             }
             catch (error) {
-                this.#logError(error);
+                this.#logError(error, compiledQuery, startTime);
                 throw error;
             }
             finally {
@@ -82,10 +82,12 @@ export class RuntimeDriver {
             }
         };
     }
-    #logError(error) {
+    #logError(error, compiledQuery, startTime) {
         this.#log.error(() => ({
             level: 'error',
             error,
+            query: compiledQuery,
+            queryDurationMillis: this.#calculateDurationMillis(startTime),
         }));
     }
     #logQuery(compiledQuery, startTime) {