kysely 0.9.3 → 0.9.4

package/dist/cjs/dialect/mysql/mysql-dialect.d.ts

@@ -5,6 +5,13 @@ import { Dialect } from '../dialect.js';
 import { DatabaseIntrospector } from '../../introspection/database-introspector.js';
 import { DialectAdapter } from '../dialect-adapter.js';
 import { DatabaseConnection } from '../../driver/database-connection.js';
+/**
+ * MySQL dialect that uses the [mysql2](https://github.com/sidorares/node-mysql2#readme) library.
+ *
+ * The {@link MysqlDialectConfig | configuration} passed to the constructor
+ * is given as-is to the mysql2 library's [createPool](https://github.com/sidorares/node-mysql2#using-connection-pools)
+ * method.
+ */
 export declare class MysqlDialect implements Dialect {
     #private;
     constructor(config: MysqlDialectConfig);
@@ -17,6 +24,8 @@ export declare class MysqlDialect implements Dialect {
  * Config for the mysql dialect.
  *
  * This interface is equal to `mysql2` library's pool config.
+ *
+ * https://github.com/sidorares/node-mysql2#using-connection-pools
  */
 export interface MysqlDialectConfig {
     /**

package/dist/cjs/dialect/mysql/mysql-dialect.js

@@ -5,6 +5,13 @@ const mysql_driver_js_1 = require("./mysql-driver.js");
 const mysql_query_compiler_js_1 = require("./mysql-query-compiler.js");
 const mysql_introspector_js_1 = require("./mysql-introspector.js");
 const mysql_adapter_js_1 = require("./mysql-adapter.js");
+/**
+ * MySQL dialect that uses the [mysql2](https://github.com/sidorares/node-mysql2#readme) library.
+ *
+ * The {@link MysqlDialectConfig | configuration} passed to the constructor
+ * is given as-is to the mysql2 library's [createPool](https://github.com/sidorares/node-mysql2#using-connection-pools)
+ * method.
+ */
 class MysqlDialect {
     #config;
     constructor(config) {

package/dist/cjs/dialect/postgres/postgres-dialect.d.ts

@@ -8,6 +8,16 @@ import { Dialect } from '../dialect.js';
 import { DatabaseIntrospector } from '../../introspection/database-introspector.js';
 import { DialectAdapter } from '../dialect-adapter.js';
 import { DatabaseConnection } from '../../driver/database-connection.js';
+/**
+ * PostgreSQL dialect that uses the [pg](https://node-postgres.com/) library.
+ *
+ * The {@link PostgresDialectConfig | configuration} passed to the constructor
+ * is given as-is to the pg library's [Pool](https://node-postgres.com/api/pool)
+ * constructor. See the following two links for more documentation:
+ *
+ * https://node-postgres.com/api/pool
+ * https://node-postgres.com/api/client
+ */
 export declare class PostgresDialect implements Dialect {
     #private;
     constructor(config: PostgresDialectConfig);
@@ -19,7 +29,7 @@ export declare class PostgresDialect implements Dialect {
 /**
  * Config for the postgres dialect.
  *
- * This interface is equal to `pg` library's pool config:
+ * This interface is equal to `pg` library's `Pool` config:
  *
  * https://node-postgres.com/api/pool
  * https://node-postgres.com/api/client

package/dist/cjs/dialect/postgres/postgres-dialect.js

@@ -5,6 +5,16 @@ const postgres_driver_js_1 = require("./postgres-driver.js");
 const postgres_introspector_js_1 = require("./postgres-introspector.js");
 const postgres_query_compiler_js_1 = require("./postgres-query-compiler.js");
 const postgres_adapter_js_1 = require("./postgres-adapter.js");
+/**
+ * PostgreSQL dialect that uses the [pg](https://node-postgres.com/) library.
+ *
+ * The {@link PostgresDialectConfig | configuration} passed to the constructor
+ * is given as-is to the pg library's [Pool](https://node-postgres.com/api/pool)
+ * constructor. See the following two links for more documentation:
+ *
+ * https://node-postgres.com/api/pool
+ * https://node-postgres.com/api/client
+ */
 class PostgresDialect {
     #config;
     constructor(config) {

package/dist/cjs/driver/runtime-driver.d.ts

@@ -1,3 +1,4 @@
+import { Log } from '../util/log.js';
 import { DatabaseConnection } from './database-connection.js';
 import { Driver, TransactionSettings } from './driver.js';
 /**
@@ -7,10 +8,10 @@ import { Driver, TransactionSettings } from './driver.js';
  */
 export declare class RuntimeDriver implements Driver {
     #private;
-    constructor(driver: Driver);
+    constructor(driver: Driver, log: Log);
     init(): Promise<void>;
     acquireConnection(): Promise<DatabaseConnection>;
-    releaseConnection(connection: DatabaseConnection): Promise<void>;
+    releaseConnection(runtimeConnection: DatabaseConnection): Promise<void>;
     beginTransaction(connection: DatabaseConnection, settings: TransactionSettings): Promise<void>;
     commitTransaction(connection: DatabaseConnection): Promise<void>;
     rollbackTransaction(connection: DatabaseConnection): Promise<void>;

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

@@ -8,10 +8,13 @@ exports.RuntimeDriver = void 0;
  */
 class RuntimeDriver {
     #driver;
+    #log;
     #initPromise;
     #destroyPromise;
-    constructor(driver) {
+    #connections = new WeakMap();
+    constructor(driver, log) {
         this.#driver = driver;
+        this.#log = log;
     }
     async init() {
         if (!this.#initPromise) {
@@ -24,10 +27,18 @@ class RuntimeDriver {
     }
     async acquireConnection() {
         await this.init();
-        return this.#driver.acquireConnection();
+        const connection = await this.#driver.acquireConnection();
+        let runtimeConnection = this.#connections.get(connection);
+        if (!runtimeConnection) {
+            runtimeConnection = new RuntimeConnection(connection, this.#log);
+            this.#connections.set(connection, runtimeConnection);
+        }
+        return runtimeConnection;
     }
-    releaseConnection(connection) {
-        return this.#driver.releaseConnection(connection);
+    async releaseConnection(runtimeConnection) {
+        if (runtimeConnection instanceof RuntimeConnection) {
+            await this.#driver.releaseConnection(runtimeConnection.connection);
+        }
     }
     beginTransaction(connection, settings) {
         return this.#driver.beginTransaction(connection, settings);
@@ -53,3 +64,31 @@ class RuntimeDriver {
     }
 }
 exports.RuntimeDriver = RuntimeDriver;
+class RuntimeConnection {
+    #connection;
+    #log;
+    get connection() {
+        return this.#connection;
+    }
+    constructor(connection, log) {
+        this.#connection = connection;
+        this.#log = log;
+    }
+    async executeQuery(compiledQuery) {
+        const startTime = process.hrtime.bigint();
+        try {
+            return await this.#connection.executeQuery(compiledQuery);
+        }
+        finally {
+            this.#log.query((log) => {
+                log(compiledQuery.sql);
+                log(`duration: ${this.#calculateDurationMillis(startTime)}ms`);
+            });
+        }
+    }
+    #calculateDurationMillis(startTime) {
+        const endTime = process.hrtime.bigint();
+        const durationTensMillis = Number((endTime - startTime) / 100000n);
+        return durationTensMillis / 10;
+    }
+}

package/dist/cjs/index.d.ts

@@ -110,7 +110,7 @@ export * from './operation-node/operation-node-source.js';
 export * from './operation-node/order-by-node.js';
 export * from './introspection/database-introspector.js';
 export * from './util/compilable.js';
-export { AnyColumn, UnknownRow as AnyRow } from './util/type-utils.js';
+export { AnyColumn, UnknownRow, AnyQueryBuilder } from './util/type-utils.js';
 export { SelectExpression, SelectExpressionOrList, } from './parser/select-parser.js';
 export { ReferenceExpression, ReferenceExpressionOrList, } from './parser/reference-parser.js';
 export { ValueExpression, ValueExpressionOrList, } from './parser/value-parser.js';

package/dist/cjs/kysely.d.ts

@@ -10,6 +10,7 @@ import { DatabaseIntrospector } from './introspection/database-introspector.js';
 import { Driver, IsolationLevel } from './driver/driver.js';
 import { ParseContext } from './parser/parse-context.js';
 import { FunctionBuilder } from './query-builder/function-builder.js';
+import { LogLevel } from './util/log.js';
 /**
  * The main Kysely class.
  *
@@ -127,15 +128,20 @@ export declare class Kysely<DB> extends QueryCreator<DB> {
      */
     get fn(): FunctionBuilder<DB, keyof DB>;
     /**
-     * Starts a transaction. If the callback throws the transaction is rolled back,
-     * otherwise it's committed.
+     * Creates a {@link TransactionBuilder} that can be used to run queries inside a transaction.
      *
-     * @example
-     * In the example below if either query fails or `someFunction` throws, both inserts
-     * will be rolled back. Otherwise the transaction will be committed by the time the
-     * `transaction` function returns the output value. The output value of the
-     * `transaction` method is the value returned from the callback.
+     * The returned {@link TransactionBuilder} can be used to configure the transaction. The
+     * {@link TransactionBuilder.execute} method can then be called to run the transaction.
+     * {@link TransactionBuilder.execute} takes a function that is run inside the
+     * transaction. If the function throws, the transaction is rolled back. Otherwise
+     * the transaction is committed.
+     *
+     * The callback function passed to the {@link TransactionBuilder.execute | execute}
+     * method gets the transaction object as its only argument. The transaction is
+     * of type {@link Transaction} which inherits {@link Kysely}. Any query
+     * started through the transaction object is executed inside the transaction.
      *
+     * @example
      * ```ts
      * const catto = await db.transaction().execute(async (trx) => {
      *   const jennifer = await trx.insertInto('person')
@@ -220,8 +226,19 @@ export interface KyselyProps {
 }
 export declare function isKyselyProps(obj: unknown): obj is KyselyProps;
 export interface KyselyConfig {
-    dialect: Dialect;
-    plugins?: KyselyPlugin[];
+    readonly dialect: Dialect;
+    readonly plugins?: KyselyPlugin[];
+    /**
+     * A list of log levels to log.
+     *
+     * Currently there's only one level: `query` and it's logged using
+     * `console.log`. This will be expanded based on user request later.
+     *
+     * Log levels:
+     *
+     *  - query: Log each query's SQL and duration.
+     */
+    readonly log?: ReadonlyArray<LogLevel>;
 }
 export declare class ConnectionBuilder<DB> {
     #private;

package/dist/cjs/kysely.js

@@ -15,6 +15,7 @@ const driver_js_1 = require("./driver/driver.js");
 const prevent_await_js_1 = require("./util/prevent-await.js");
 const parse_context_js_1 = require("./parser/parse-context.js");
 const function_builder_js_1 = require("./query-builder/function-builder.js");
+const log_js_1 = require("./util/log.js");
 /**
  * The main Kysely class.
  *
@@ -60,15 +61,16 @@ class Kysely extends query_creator_js_1.QueryCreator {
     constructor(args) {
         if (isKyselyProps(args)) {
             super({ executor: args.executor, parseContext: args.parseContext });
-            this.#props = (0, object_utils_js_1.freeze)(args);
+            this.#props = (0, object_utils_js_1.freeze)({ ...args });
         }
         else {
             const dialect = args.dialect;
             const driver = dialect.createDriver();
             const compiler = dialect.createQueryCompiler();
             const adapter = dialect.createAdapter();
+            const log = new log_js_1.Log(args.log ?? []);
             const parseContext = new parse_context_js_1.DefaultParseContext(adapter);
-            const runtimeDriver = new runtime_driver_js_1.RuntimeDriver(driver);
+            const runtimeDriver = new runtime_driver_js_1.RuntimeDriver(driver, log);
             const connectionProvider = new default_connection_provider_js_1.DefaultConnectionProvider(runtimeDriver);
             const executor = new default_query_executor_js_1.DefaultQueryExecutor(compiler, connectionProvider, args.plugins ?? []);
             super({ executor, parseContext });
@@ -166,15 +168,20 @@ class Kysely extends query_creator_js_1.QueryCreator {
         return new function_builder_js_1.FunctionBuilder({ executor: this.#props.executor });
     }
     /**
-     * Starts a transaction. If the callback throws the transaction is rolled back,
-     * otherwise it's committed.
+     * Creates a {@link TransactionBuilder} that can be used to run queries inside a transaction.
      *
-     * @example
-     * In the example below if either query fails or `someFunction` throws, both inserts
-     * will be rolled back. Otherwise the transaction will be committed by the time the
-     * `transaction` function returns the output value. The output value of the
-     * `transaction` method is the value returned from the callback.
+     * The returned {@link TransactionBuilder} can be used to configure the transaction. The
+     * {@link TransactionBuilder.execute} method can then be called to run the transaction.
+     * {@link TransactionBuilder.execute} takes a function that is run inside the
+     * transaction. If the function throws, the transaction is rolled back. Otherwise
+     * the transaction is committed.
+     *
+     * The callback function passed to the {@link TransactionBuilder.execute | execute}
+     * method gets the transaction object as its only argument. The transaction is
+     * of type {@link Transaction} which inherits {@link Kysely}. Any query
+     * started through the transaction object is executed inside the transaction.
      *
+     * @example
      * ```ts
      * const catto = await db.transaction().execute(async (trx) => {
      *   const jennifer = await trx.insertInto('person')

package/dist/cjs/migration/migration.d.ts

@@ -24,6 +24,38 @@ export declare class MigrationModule {
      *   path.join(__dirname, 'migrations')
      * )
      * ```
+     *
+     * In the next example, we use a record of migration objects instead of file folder path.
+     * The keys in the object are migration names that can be anything you want. The order of
+     * the migrations is determined based on the alphabetical order of the keys in the record.
+     * This can be useful if you are using a bundler like webpack or esbuild.
+     *
+     * @example
+     * ```ts
+     * await db.migration.migrateToLatest({
+     *   migration1: {
+     *     async up(db: Kysely<any>): Promise<void> {
+     *       ...
+     *     },
+     *
+     *     async down(db: Kysely<any>): Promise<void> {
+     *       ...
+     *     }
+     *   },
+     *
+     *   migration2: {
+     *     async up(db: Kysely<any>): Promise<void> {
+     *       ...
+     *     },
+     *
+     *     async down(db: Kysely<any>): Promise<void> {
+     *       ...
+     *     }
+     *   },
+     *
+     *  ...
+     * })
+     * ```
      */
     migrateToLatest(migrationsFolderPath: string): Promise<void>;
     migrateToLatest(allMigrations: Record<string, Migration>): Promise<void>;

package/dist/cjs/parser/join-parser.d.ts

@@ -3,9 +3,9 @@ import { AnyColumn, AnyColumnWithTable } from '../util/type-utils.js';
 import { ExtractAliasFromTableExpression, TableExpressionDatabase } from './table-parser.js';
 import { JoinBuilder } from '../query-builder/join-builder.js';
 import { ParseContext } from './parse-context.js';
-export declare type JoinReferenceExpression<DB, TB extends keyof DB, F> = AnyJoinColumn<DB, TB, F> | AnyJoinColumnWithTable<DB, TB, F>;
-export declare type JoinCallbackExpression<DB, TB extends keyof DB, F> = (join: JoinBuilder<TableExpressionDatabase<DB, F>, TB | ExtractAliasFromTableExpression<DB, F>>) => JoinBuilder<any, any>;
-declare type AnyJoinColumn<DB, TB extends keyof DB, F> = AnyColumn<TableExpressionDatabase<DB, F>, TB | ExtractAliasFromTableExpression<DB, F>>;
-declare type AnyJoinColumnWithTable<DB, TB extends keyof DB, F> = AnyColumnWithTable<TableExpressionDatabase<DB, F>, TB | ExtractAliasFromTableExpression<DB, F>>;
+export declare type JoinReferenceExpression<DB, TB extends keyof DB, TE> = AnyJoinColumn<DB, TB, TE> | AnyJoinColumnWithTable<DB, TB, TE>;
+export declare type JoinCallbackExpression<DB, TB extends keyof DB, TE> = (join: JoinBuilder<TableExpressionDatabase<DB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>>) => JoinBuilder<any, any>;
+declare type AnyJoinColumn<DB, TB extends keyof DB, TE> = AnyColumn<TableExpressionDatabase<DB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>>;
+declare type AnyJoinColumnWithTable<DB, TB extends keyof DB, TE> = AnyColumnWithTable<TableExpressionDatabase<DB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>>;
 export declare function parseJoin(ctx: ParseContext, joinType: JoinType, args: any[]): JoinNode;
 export {};

package/dist/cjs/query-builder/query-builder.d.ts

@@ -1582,6 +1582,41 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * ```
      */
     unionAll(expression: UnionExpression<DB, O>): QueryBuilder<DB, TB, O>;
+    /**
+     * Simply calls the given method passing `this` as the only argument.
+     *
+     * This method can be useful when adding optional method calls:
+     *
+     * @example
+     * ```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:
+     *
+     * @example
+     * ```ts
+     * function log<T extends AnyQueryBuilder>(qb: T): T {
+     *   console.log(qb.compile())
+     *   return qb
+     * }
+     *
+     * db.selectFrom('person')
+     *   .selectAll()
+     *   .call(log)
+     *   .execute()
+     * ```
+     */
+    call<T>(func: (qb: this) => T): T;
     /**
      * Gives an alias for the query. This method is only useful for sub queries.
      *

package/dist/cjs/query-builder/query-builder.js

@@ -818,6 +818,43 @@ class QueryBuilder {
             queryNode: select_query_node_js_1.SelectQueryNode.cloneWithUnion(this.#props.queryNode, (0, union_parser_js_1.parseUnion)(expression, true)),
         });
     }
+    /**
+     * Simply calls the given method passing `this` as the only argument.
+     *
+     * This method can be useful when adding optional method calls:
+     *
+     * @example
+     * ```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:
+     *
+     * @example
+     * ```ts
+     * function log<T extends AnyQueryBuilder>(qb: T): T {
+     *   console.log(qb.compile())
+     *   return qb
+     * }
+     *
+     * db.selectFrom('person')
+     *   .selectAll()
+     *   .call(log)
+     *   .execute()
+     * ```
+     */
+    call(func) {
+        return func(this);
+    }
     /**
      * Gives an alias for the query. This method is only useful for sub queries.
      *

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

@@ -0,0 +1,8 @@
+import { ArrayItemType } from './type-utils.js';
+export declare const LOG_LEVELS: readonly ["query"];
+export declare type LogLevel = ArrayItemType<typeof LOG_LEVELS>;
+export declare class Log {
+    #private;
+    constructor(levels: ReadonlyArray<LogLevel>);
+    query(callback: (log: (message: string) => void) => void): void;
+}

package/dist/cjs/util/log.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Log = exports.LOG_LEVELS = void 0;
+exports.LOG_LEVELS = ['query'];
+class Log {
+    #levels;
+    constructor(levels) {
+        this.#levels = {
+            query: levels.includes('query'),
+        };
+    }
+    query(callback) {
+        if (this.#levels.query) {
+            callback(this.#query);
+        }
+    }
+    #query(message) {
+        console.log(`kysely:query: ${message}`);
+    }
+}
+exports.Log = Log;

package/dist/cjs/util/random-string.js

@@ -3,10 +3,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.randomString = void 0;
 const CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
 function randomString(length) {
-    let chars = new Array(length);
+    let chars = '';
     for (let i = 0; i < length; ++i) {
-        chars[i] = CHARS[Math.floor(Math.random() * CHARS.length)];
+        chars += randomChar();
     }
-    return chars.join('');
+    return chars;
 }
 exports.randomString = randomString;
+function randomChar() {
+    return CHARS[Math.floor(Math.random() * CHARS.length)];
+}

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

@@ -136,19 +136,19 @@ export declare type RawBuilderFactory<DB, TB extends keyof DB> = (qb: Expression
 export declare type AliasedRawBuilderFactory<DB, TB extends keyof DB> = (qb: ExpressionBuilder<DB, TB>) => AnyAliasedRawBuilder;
 export interface InsertResultTypeTag {
     /** @internal */
-    __isInsertResultTypeTag__: true;
+    readonly __isInsertResultTypeTag__: true;
 }
 export interface DeleteResultTypeTag {
     /** @internal */
-    __isDeleteResultTypeTag__: true;
+    readonly __isDeleteResultTypeTag__: true;
 }
 export interface UpdateResultTypeTag {
     /** @internal */
-    __isUpdateResultTypeTag__: true;
+    readonly __isUpdateResultTypeTag__: true;
 }
 export interface GeneratedPlaceholder {
     /** @internal */
-    __isGeneratedPlaceholder__: true;
+    readonly __isGeneratedPlaceholder__: true;
 }
 export declare type ManyResultRowType<O> = O extends InsertResultTypeTag ? number | undefined : O extends DeleteResultTypeTag ? number : O extends UpdateResultTypeTag ? number : O;
 export declare type SingleResultRowType<O> = O extends InsertResultTypeTag ? number | undefined : O extends DeleteResultTypeTag ? number : O extends UpdateResultTypeTag ? number : O | undefined;

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

@@ -5,6 +5,13 @@ import { Dialect } from '../dialect.js';
 import { DatabaseIntrospector } from '../../introspection/database-introspector.js';
 import { DialectAdapter } from '../dialect-adapter.js';
 import { DatabaseConnection } from '../../driver/database-connection.js';
+/**
+ * MySQL dialect that uses the [mysql2](https://github.com/sidorares/node-mysql2#readme) library.
+ *
+ * The {@link MysqlDialectConfig | configuration} passed to the constructor
+ * is given as-is to the mysql2 library's [createPool](https://github.com/sidorares/node-mysql2#using-connection-pools)
+ * method.
+ */
 export declare class MysqlDialect implements Dialect {
     #private;
     constructor(config: MysqlDialectConfig);
@@ -17,6 +24,8 @@ export declare class MysqlDialect implements Dialect {
  * Config for the mysql dialect.
  *
  * This interface is equal to `mysql2` library's pool config.
+ *
+ * https://github.com/sidorares/node-mysql2#using-connection-pools
  */
 export interface MysqlDialectConfig {
     /**

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

@@ -2,6 +2,13 @@ import { MysqlDriver } from './mysql-driver.js';
 import { MysqlQueryCompiler } from './mysql-query-compiler.js';
 import { MysqlIntrospector } from './mysql-introspector.js';
 import { MysqlAdapter } from './mysql-adapter.js';
+/**
+ * MySQL dialect that uses the [mysql2](https://github.com/sidorares/node-mysql2#readme) library.
+ *
+ * The {@link MysqlDialectConfig | configuration} passed to the constructor
+ * is given as-is to the mysql2 library's [createPool](https://github.com/sidorares/node-mysql2#using-connection-pools)
+ * method.
+ */
 export class MysqlDialect {
     #config;
     constructor(config) {

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

@@ -1,4 +1,4 @@
-import { isFunction, isNumber, isObject, } from '../../util/object-utils.js';
+import { isFunction, isNumber, isObject } from '../../util/object-utils.js';
 const PRIVATE_RELEASE_METHOD = Symbol();
 export class MysqlDriver {
     #config;

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

@@ -8,6 +8,16 @@ import { Dialect } from '../dialect.js';
 import { DatabaseIntrospector } from '../../introspection/database-introspector.js';
 import { DialectAdapter } from '../dialect-adapter.js';
 import { DatabaseConnection } from '../../driver/database-connection.js';
+/**
+ * PostgreSQL dialect that uses the [pg](https://node-postgres.com/) library.
+ *
+ * The {@link PostgresDialectConfig | configuration} passed to the constructor
+ * is given as-is to the pg library's [Pool](https://node-postgres.com/api/pool)
+ * constructor. See the following two links for more documentation:
+ *
+ * https://node-postgres.com/api/pool
+ * https://node-postgres.com/api/client
+ */
 export declare class PostgresDialect implements Dialect {
     #private;
     constructor(config: PostgresDialectConfig);
@@ -19,7 +29,7 @@ export declare class PostgresDialect implements Dialect {
 /**
  * Config for the postgres dialect.
  *
- * This interface is equal to `pg` library's pool config:
+ * This interface is equal to `pg` library's `Pool` config:
  *
  * https://node-postgres.com/api/pool
  * https://node-postgres.com/api/client

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

@@ -2,6 +2,16 @@ import { PostgresDriver } from './postgres-driver.js';
 import { PostgresIntrospector } from './postgres-introspector.js';
 import { PostgresQueryCompiler } from './postgres-query-compiler.js';
 import { PostgresAdapter } from './postgres-adapter.js';
+/**
+ * PostgreSQL dialect that uses the [pg](https://node-postgres.com/) library.
+ *
+ * The {@link PostgresDialectConfig | configuration} passed to the constructor
+ * is given as-is to the pg library's [Pool](https://node-postgres.com/api/pool)
+ * constructor. See the following two links for more documentation:
+ *
+ * https://node-postgres.com/api/pool
+ * https://node-postgres.com/api/client
+ */
 export class PostgresDialect {
     #config;
     constructor(config) {

package/dist/esm/driver/runtime-driver.d.ts

@@ -1,3 +1,4 @@
+import { Log } from '../util/log.js';
 import { DatabaseConnection } from './database-connection.js';
 import { Driver, TransactionSettings } from './driver.js';
 /**
@@ -7,10 +8,10 @@ import { Driver, TransactionSettings } from './driver.js';
  */
 export declare class RuntimeDriver implements Driver {
     #private;
-    constructor(driver: Driver);
+    constructor(driver: Driver, log: Log);
     init(): Promise<void>;
     acquireConnection(): Promise<DatabaseConnection>;
-    releaseConnection(connection: DatabaseConnection): Promise<void>;
+    releaseConnection(runtimeConnection: DatabaseConnection): Promise<void>;
     beginTransaction(connection: DatabaseConnection, settings: TransactionSettings): Promise<void>;
     commitTransaction(connection: DatabaseConnection): Promise<void>;
     rollbackTransaction(connection: DatabaseConnection): Promise<void>;

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

@@ -5,10 +5,13 @@
  */
 export class RuntimeDriver {
     #driver;
+    #log;
     #initPromise;
     #destroyPromise;
-    constructor(driver) {
+    #connections = new WeakMap();
+    constructor(driver, log) {
         this.#driver = driver;
+        this.#log = log;
     }
     async init() {
         if (!this.#initPromise) {
@@ -21,10 +24,18 @@ export class RuntimeDriver {
     }
     async acquireConnection() {
         await this.init();
-        return this.#driver.acquireConnection();
+        const connection = await this.#driver.acquireConnection();
+        let runtimeConnection = this.#connections.get(connection);
+        if (!runtimeConnection) {
+            runtimeConnection = new RuntimeConnection(connection, this.#log);
+            this.#connections.set(connection, runtimeConnection);
+        }
+        return runtimeConnection;
     }
-    releaseConnection(connection) {
-        return this.#driver.releaseConnection(connection);
+    async releaseConnection(runtimeConnection) {
+        if (runtimeConnection instanceof RuntimeConnection) {
+            await this.#driver.releaseConnection(runtimeConnection.connection);
+        }
     }
     beginTransaction(connection, settings) {
         return this.#driver.beginTransaction(connection, settings);
@@ -49,3 +60,31 @@ export class RuntimeDriver {
         await this.#destroyPromise;
     }
 }
+class RuntimeConnection {
+    #connection;
+    #log;
+    get connection() {
+        return this.#connection;
+    }
+    constructor(connection, log) {
+        this.#connection = connection;
+        this.#log = log;
+    }
+    async executeQuery(compiledQuery) {
+        const startTime = process.hrtime.bigint();
+        try {
+            return await this.#connection.executeQuery(compiledQuery);
+        }
+        finally {
+            this.#log.query((log) => {
+                log(compiledQuery.sql);
+                log(`duration: ${this.#calculateDurationMillis(startTime)}ms`);
+            });
+        }
+    }
+    #calculateDurationMillis(startTime) {
+        const endTime = process.hrtime.bigint();
+        const durationTensMillis = Number((endTime - startTime) / 100000n);
+        return durationTensMillis / 10;
+    }
+}

package/dist/esm/index.d.ts

@@ -110,7 +110,7 @@ export * from './operation-node/operation-node-source.js';
 export * from './operation-node/order-by-node.js';
 export * from './introspection/database-introspector.js';
 export * from './util/compilable.js';
-export { AnyColumn, UnknownRow as AnyRow } from './util/type-utils.js';
+export { AnyColumn, UnknownRow, AnyQueryBuilder } from './util/type-utils.js';
 export { SelectExpression, SelectExpressionOrList, } from './parser/select-parser.js';
 export { ReferenceExpression, ReferenceExpressionOrList, } from './parser/reference-parser.js';
 export { ValueExpression, ValueExpressionOrList, } from './parser/value-parser.js';

package/dist/esm/kysely.d.ts

@@ -10,6 +10,7 @@ import { DatabaseIntrospector } from './introspection/database-introspector.js';
 import { Driver, IsolationLevel } from './driver/driver.js';
 import { ParseContext } from './parser/parse-context.js';
 import { FunctionBuilder } from './query-builder/function-builder.js';
+import { LogLevel } from './util/log.js';
 /**
  * The main Kysely class.
  *
@@ -127,15 +128,20 @@ export declare class Kysely<DB> extends QueryCreator<DB> {
      */
     get fn(): FunctionBuilder<DB, keyof DB>;
     /**
-     * Starts a transaction. If the callback throws the transaction is rolled back,
-     * otherwise it's committed.
+     * Creates a {@link TransactionBuilder} that can be used to run queries inside a transaction.
      *
-     * @example
-     * In the example below if either query fails or `someFunction` throws, both inserts
-     * will be rolled back. Otherwise the transaction will be committed by the time the
-     * `transaction` function returns the output value. The output value of the
-     * `transaction` method is the value returned from the callback.
+     * The returned {@link TransactionBuilder} can be used to configure the transaction. The
+     * {@link TransactionBuilder.execute} method can then be called to run the transaction.
+     * {@link TransactionBuilder.execute} takes a function that is run inside the
+     * transaction. If the function throws, the transaction is rolled back. Otherwise
+     * the transaction is committed.
+     *
+     * The callback function passed to the {@link TransactionBuilder.execute | execute}
+     * method gets the transaction object as its only argument. The transaction is
+     * of type {@link Transaction} which inherits {@link Kysely}. Any query
+     * started through the transaction object is executed inside the transaction.
      *
+     * @example
      * ```ts
      * const catto = await db.transaction().execute(async (trx) => {
      *   const jennifer = await trx.insertInto('person')
@@ -220,8 +226,19 @@ export interface KyselyProps {
 }
 export declare function isKyselyProps(obj: unknown): obj is KyselyProps;
 export interface KyselyConfig {
-    dialect: Dialect;
-    plugins?: KyselyPlugin[];
+    readonly dialect: Dialect;
+    readonly plugins?: KyselyPlugin[];
+    /**
+     * A list of log levels to log.
+     *
+     * Currently there's only one level: `query` and it's logged using
+     * `console.log`. This will be expanded based on user request later.
+     *
+     * Log levels:
+     *
+     *  - query: Log each query's SQL and duration.
+     */
+    readonly log?: ReadonlyArray<LogLevel>;
 }
 export declare class ConnectionBuilder<DB> {
     #private;

package/dist/esm/kysely.js

@@ -12,6 +12,7 @@ import { TRANSACTION_ISOLATION_LEVELS, } from './driver/driver.js';
 import { preventAwait } from './util/prevent-await.js';
 import { DefaultParseContext } from './parser/parse-context.js';
 import { FunctionBuilder } from './query-builder/function-builder.js';
+import { Log } from './util/log.js';
 /**
  * The main Kysely class.
  *
@@ -57,15 +58,16 @@ export class Kysely extends QueryCreator {
     constructor(args) {
         if (isKyselyProps(args)) {
             super({ executor: args.executor, parseContext: args.parseContext });
-            this.#props = freeze(args);
+            this.#props = freeze({ ...args });
         }
         else {
             const dialect = args.dialect;
             const driver = dialect.createDriver();
             const compiler = dialect.createQueryCompiler();
             const adapter = dialect.createAdapter();
+            const log = new Log(args.log ?? []);
             const parseContext = new DefaultParseContext(adapter);
-            const runtimeDriver = new RuntimeDriver(driver);
+            const runtimeDriver = new RuntimeDriver(driver, log);
             const connectionProvider = new DefaultConnectionProvider(runtimeDriver);
             const executor = new DefaultQueryExecutor(compiler, connectionProvider, args.plugins ?? []);
             super({ executor, parseContext });
@@ -163,15 +165,20 @@ export class Kysely extends QueryCreator {
         return new FunctionBuilder({ executor: this.#props.executor });
     }
     /**
-     * Starts a transaction. If the callback throws the transaction is rolled back,
-     * otherwise it's committed.
+     * Creates a {@link TransactionBuilder} that can be used to run queries inside a transaction.
      *
-     * @example
-     * In the example below if either query fails or `someFunction` throws, both inserts
-     * will be rolled back. Otherwise the transaction will be committed by the time the
-     * `transaction` function returns the output value. The output value of the
-     * `transaction` method is the value returned from the callback.
+     * The returned {@link TransactionBuilder} can be used to configure the transaction. The
+     * {@link TransactionBuilder.execute} method can then be called to run the transaction.
+     * {@link TransactionBuilder.execute} takes a function that is run inside the
+     * transaction. If the function throws, the transaction is rolled back. Otherwise
+     * the transaction is committed.
+     *
+     * The callback function passed to the {@link TransactionBuilder.execute | execute}
+     * method gets the transaction object as its only argument. The transaction is
+     * of type {@link Transaction} which inherits {@link Kysely}. Any query
+     * started through the transaction object is executed inside the transaction.
      *
+     * @example
      * ```ts
      * const catto = await db.transaction().execute(async (trx) => {
      *   const jennifer = await trx.insertInto('person')

package/dist/esm/migration/migration.d.ts

@@ -24,6 +24,38 @@ export declare class MigrationModule {
      *   path.join(__dirname, 'migrations')
      * )
      * ```
+     *
+     * In the next example, we use a record of migration objects instead of file folder path.
+     * The keys in the object are migration names that can be anything you want. The order of
+     * the migrations is determined based on the alphabetical order of the keys in the record.
+     * This can be useful if you are using a bundler like webpack or esbuild.
+     *
+     * @example
+     * ```ts
+     * await db.migration.migrateToLatest({
+     *   migration1: {
+     *     async up(db: Kysely<any>): Promise<void> {
+     *       ...
+     *     },
+     *
+     *     async down(db: Kysely<any>): Promise<void> {
+     *       ...
+     *     }
+     *   },
+     *
+     *   migration2: {
+     *     async up(db: Kysely<any>): Promise<void> {
+     *       ...
+     *     },
+     *
+     *     async down(db: Kysely<any>): Promise<void> {
+     *       ...
+     *     }
+     *   },
+     *
+     *  ...
+     * })
+     * ```
      */
     migrateToLatest(migrationsFolderPath: string): Promise<void>;
     migrateToLatest(allMigrations: Record<string, Migration>): Promise<void>;

package/dist/esm/parser/join-parser.d.ts

@@ -3,9 +3,9 @@ import { AnyColumn, AnyColumnWithTable } from '../util/type-utils.js';
 import { ExtractAliasFromTableExpression, TableExpressionDatabase } from './table-parser.js';
 import { JoinBuilder } from '../query-builder/join-builder.js';
 import { ParseContext } from './parse-context.js';
-export declare type JoinReferenceExpression<DB, TB extends keyof DB, F> = AnyJoinColumn<DB, TB, F> | AnyJoinColumnWithTable<DB, TB, F>;
-export declare type JoinCallbackExpression<DB, TB extends keyof DB, F> = (join: JoinBuilder<TableExpressionDatabase<DB, F>, TB | ExtractAliasFromTableExpression<DB, F>>) => JoinBuilder<any, any>;
-declare type AnyJoinColumn<DB, TB extends keyof DB, F> = AnyColumn<TableExpressionDatabase<DB, F>, TB | ExtractAliasFromTableExpression<DB, F>>;
-declare type AnyJoinColumnWithTable<DB, TB extends keyof DB, F> = AnyColumnWithTable<TableExpressionDatabase<DB, F>, TB | ExtractAliasFromTableExpression<DB, F>>;
+export declare type JoinReferenceExpression<DB, TB extends keyof DB, TE> = AnyJoinColumn<DB, TB, TE> | AnyJoinColumnWithTable<DB, TB, TE>;
+export declare type JoinCallbackExpression<DB, TB extends keyof DB, TE> = (join: JoinBuilder<TableExpressionDatabase<DB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>>) => JoinBuilder<any, any>;
+declare type AnyJoinColumn<DB, TB extends keyof DB, TE> = AnyColumn<TableExpressionDatabase<DB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>>;
+declare type AnyJoinColumnWithTable<DB, TB extends keyof DB, TE> = AnyColumnWithTable<TableExpressionDatabase<DB, TE>, TB | ExtractAliasFromTableExpression<DB, TE>>;
 export declare function parseJoin(ctx: ParseContext, joinType: JoinType, args: any[]): JoinNode;
 export {};

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

@@ -1582,6 +1582,41 @@ export declare class QueryBuilder<DB, TB extends keyof DB, O = {}> implements Op
      * ```
      */
     unionAll(expression: UnionExpression<DB, O>): QueryBuilder<DB, TB, O>;
+    /**
+     * Simply calls the given method passing `this` as the only argument.
+     *
+     * This method can be useful when adding optional method calls:
+     *
+     * @example
+     * ```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:
+     *
+     * @example
+     * ```ts
+     * function log<T extends AnyQueryBuilder>(qb: T): T {
+     *   console.log(qb.compile())
+     *   return qb
+     * }
+     *
+     * db.selectFrom('person')
+     *   .selectAll()
+     *   .call(log)
+     *   .execute()
+     * ```
+     */
+    call<T>(func: (qb: this) => T): T;
     /**
      * Gives an alias for the query. This method is only useful for sub queries.
      *

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

@@ -815,6 +815,43 @@ export class QueryBuilder {
             queryNode: SelectQueryNode.cloneWithUnion(this.#props.queryNode, parseUnion(expression, true)),
         });
     }
+    /**
+     * Simply calls the given method passing `this` as the only argument.
+     *
+     * This method can be useful when adding optional method calls:
+     *
+     * @example
+     * ```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:
+     *
+     * @example
+     * ```ts
+     * function log<T extends AnyQueryBuilder>(qb: T): T {
+     *   console.log(qb.compile())
+     *   return qb
+     * }
+     *
+     * db.selectFrom('person')
+     *   .selectAll()
+     *   .call(log)
+     *   .execute()
+     * ```
+     */
+    call(func) {
+        return func(this);
+    }
     /**
      * Gives an alias for the query. This method is only useful for sub queries.
      *

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

@@ -0,0 +1,8 @@
+import { ArrayItemType } from './type-utils.js';
+export declare const LOG_LEVELS: readonly ["query"];
+export declare type LogLevel = ArrayItemType<typeof LOG_LEVELS>;
+export declare class Log {
+    #private;
+    constructor(levels: ReadonlyArray<LogLevel>);
+    query(callback: (log: (message: string) => void) => void): void;
+}

package/dist/esm/util/log.js

@@ -0,0 +1,17 @@
+export const LOG_LEVELS = ['query'];
+export class Log {
+    #levels;
+    constructor(levels) {
+        this.#levels = {
+            query: levels.includes('query'),
+        };
+    }
+    query(callback) {
+        if (this.#levels.query) {
+            callback(this.#query);
+        }
+    }
+    #query(message) {
+        console.log(`kysely:query: ${message}`);
+    }
+}

package/dist/esm/util/random-string.js

@@ -1,8 +1,11 @@
 const CHARS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
 export function randomString(length) {
-    let chars = new Array(length);
+    let chars = '';
     for (let i = 0; i < length; ++i) {
-        chars[i] = CHARS[Math.floor(Math.random() * CHARS.length)];
+        chars += randomChar();
     }
-    return chars.join('');
+    return chars;
+}
+function randomChar() {
+    return CHARS[Math.floor(Math.random() * CHARS.length)];
 }

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

@@ -136,19 +136,19 @@ export declare type RawBuilderFactory<DB, TB extends keyof DB> = (qb: Expression
 export declare type AliasedRawBuilderFactory<DB, TB extends keyof DB> = (qb: ExpressionBuilder<DB, TB>) => AnyAliasedRawBuilder;
 export interface InsertResultTypeTag {
     /** @internal */
-    __isInsertResultTypeTag__: true;
+    readonly __isInsertResultTypeTag__: true;
 }
 export interface DeleteResultTypeTag {
     /** @internal */
-    __isDeleteResultTypeTag__: true;
+    readonly __isDeleteResultTypeTag__: true;
 }
 export interface UpdateResultTypeTag {
     /** @internal */
-    __isUpdateResultTypeTag__: true;
+    readonly __isUpdateResultTypeTag__: true;
 }
 export interface GeneratedPlaceholder {
     /** @internal */
-    __isGeneratedPlaceholder__: true;
+    readonly __isGeneratedPlaceholder__: true;
 }
 export declare type ManyResultRowType<O> = O extends InsertResultTypeTag ? number | undefined : O extends DeleteResultTypeTag ? number : O extends UpdateResultTypeTag ? number : O;
 export declare type SingleResultRowType<O> = O extends InsertResultTypeTag ? number | undefined : O extends DeleteResultTypeTag ? number : O extends UpdateResultTypeTag ? number : O | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kysely",
-  "version": "0.9.3",
+  "version": "0.9.4",
   "description": "Type safe SQL query builder",
   "repository": {
     "type": "git",