kysely 0.16.5 → 0.16.9

package/README.md

@@ -3,14 +3,15 @@
 
 # [Kysely](https://koskimas.github.io/kysely/index.html)
 
-A type-safe and autocompletion-friendly typescript SQL query builder for node.js. Inspired by
-[knex](http://knexjs.org/).
+A type-safe and autocompletion-friendly typescript SQL query builder. Inspired by [knex](http://knexjs.org/).
+Mainly developed for [node.js](https://nodejs.org/en/) but also runs on [deno](https://deno.land/) and
+in the browser.
 
 ![](https://github.com/koskimas/kysely/blob/master/assets/demo.gif)
 
-Kysely's typings make sure you only refer to tables and columns that are visible to the part of the query
-you are writing. The result type only has the selected columns with correct types and aliases. This 
-allows tools like vscode autocompletion to make your life so much easier.
+Kysely makes sure you only refer to tables and columns that are visible to the part of the query
+you are writing. The result type only has the selected columns with correct types and aliases. As an
+added bonus you get autocompletion for all that stuff.
 
 As you can see in the gif above, through the pure magic of modern typescript, Kysely is even able to parse
 the alias given to `pet.name` and add the `pet_name` column to the result row type. Kysely is able to infer
@@ -32,7 +33,10 @@ You can find a more thorough introduction [here](https://www.jakso.me/blog/kysel
 - [Installation](#installation)
 - [Minimal example](#minimal-example)
 - [Query examples](#query-examples)
+- [Recipes](https://github.com/koskimas/kysely/tree/master/recipes)
 - [Migrations](#migrations)
+- [Deno](#deno)
+- [Browser](#browser)
 - [API reference](https://koskimas.github.io/kysely/index.html)
 - [Changelog](https://github.com/koskimas/kysely/releases)
 
@@ -200,14 +204,24 @@ export async function down(db: Kysely<any>): Promise<void> {
 ```
 
 The `up` function is called when you update your database schema to next version and `down`
-when you go back to previous version. The only argument to the functions is an instance of
-`Kysely<any>`. It is important to use `Kysely<any>` and not `Kysely<YourDatabase>`. Migrations
-should never depend on the current code of your app because they need to work even if the app
-changes completely. Migrations need to be "frozen in time".
+when you go back to previous version. The only argument for the functions is an instance of
+`Kysely<any>`. It's important to use `Kysely<any>` and not `Kysely<YourDatabase>`. Migrations
+should never depend on the current code of your app because they need to work even when the app
+changes. Migrations need to be "frozen in time".
 
 The migrations can use the [Kysely.schema](https://koskimas.github.io/kysely/classes/SchemaModule.html)
 module to modify the schema. Migrations can also run normal queries to modify data.
 
+Execution order of the migrations is the alpabetical order of their names. An excellent way to name your
+migrations is to prefix them with an ISO 8601 date string. A date prefix works well in large teams
+where multiple team members may add migrations at the same time in parallel commits without knowing
+about the other migrations.
+
+You don't need to store your migrations as separate files if you don't want to. You can easily
+implement your own [MigrationProvider](https://koskimas.github.io/kysely/interfaces/MigrationProvider.html)
+and give it to the [Migrator](https://koskimas.github.io/kysely/classes/Migrator.html) class
+when you instantiate one.
+
 ### PostgreSQL migration example
 
 ```ts
@@ -291,9 +305,9 @@ const migrator = new Migrator(migratorConfig);
 await migrator.migrateToLatest(pathToMigrationsFolder)
 ```
 
-to run all migrations that have not yet been run. The migrations are executed in alphabetical
-order by their name. See the [Migrator](https://koskimas.github.io/kysely/classes/Migrator.html) 
-documentation for more info.
+to run all migrations that have not yet been run. See the
+[Migrator](https://koskimas.github.io/kysely/classes/Migrator.html)
+class's documentation for more info.
 
 Kysely doesn't have a CLI for running migrations and probably never will. This is because Kysely's
 migrations are also written in typescript. To run the migrations, you need to first build the
@@ -341,14 +355,125 @@ async function migrateToLatest() {
     console.error(error)
     process.exit(1)
   }
+
+  await db.destroy()
 }
 
 migrateToLatest()
 ```
 
-The migration methods use a lock on the database level, and parallel calls are executed serially.
+The migration methods use a lock on the database level and parallel calls are executed serially.
 This means that you can safely call `migrateToLatest` and other migration methods from multiple
-server instances simultaneously and the migrations are guaranteed to only be executed once.
+server instances simultaneously and the migrations are guaranteed to only be executed once. The
+locks are also automatically released if the migration process crashes or the connection to the
+database fails.
+
+# Deno
+
+Kysely doesn't include drivers for deno, but you can still use Kysely as a query builder
+or implement your own driver:
+
+```ts
+// We use jsdeliver to get Kysely from npm. We also need to
+// import the `dist/esm/index-nodeless.js` file instead of the
+// root which has node dependencies.
+import {
+  DummyDriver,
+  Generated,
+  Kysely,
+  PostgresAdapter,
+  PostgresIntrospector,
+  PostgresQueryCompiler,
+} from 'https://cdn.jsdelivr.net/npm/kysely/dist/esm/index-nodeless.js'
+
+interface Person {
+  id: Generated<number>
+  first_name: string
+  last_name: string | null
+}
+
+interface Database {
+  person: Person
+}
+
+const db = new Kysely<Database>({
+  dialect: {
+    createAdapter() {
+      return new PostgresAdapter()
+    },
+    createDriver() {
+      // You need a driver to be able to execute queries. In this example
+      // we use the dummy driver that never does anything.
+      return new DummyDriver()
+    },
+    createIntrospector(db: Kysely<unknown>) {
+      return new PostgresIntrospector(db)
+    },
+    createQueryCompiler() {
+      return new PostgresQueryCompiler()
+    },
+  },
+})
+
+const query = db.selectFrom('person').select('id')
+const sql = query.compile()
+
+console.log(sql.sql)
+```
+
+# Browser
+
+Kysely also runs in the browser as long as you import the `dist/esm/index-nodeless.js`
+module instead of the root that has node dependencies. You can also import the
+`dist/cjs/index-nodeless.js` file if you are using commonjs modules instead of ESM.
+
+```ts
+import {
+  Kysely,
+  Generated,
+  DummyDriver,
+  SqliteAdapter,
+  SqliteIntrospector,
+  SqliteQueryCompiler,
+} from 'kysely/dist/esm/index-nodeless.js'
+
+interface Person {
+  id: Generated<number>
+  first_name: string
+  last_name: string | null
+}
+
+interface Database {
+  person: Person
+}
+
+const db = new Kysely<Database>({
+  dialect: {
+    createAdapter() {
+      return new SqliteAdapter()
+    },
+    createDriver() {
+      return new DummyDriver()
+    },
+    createIntrospector(db: Kysely<unknown>) {
+      return new SqliteIntrospector(db)
+    },
+    createQueryCompiler() {
+      return new SqliteQueryCompiler()
+    },
+  },
+})
+
+window.addEventListener('load', () => {
+  const sql = db.selectFrom('person').select('id').compile()
+
+  const result = document.createElement('span')
+  result.id = 'result'
+  result.innerHTML = sql.sql
+
+  document.body.appendChild(result)
+})
+```
 
 # Why not just contribute to knex
 

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

@@ -5,6 +5,7 @@ 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");
+const object_utils_js_1 = require("../../util/object-utils.js");
 /**
  * MySQL dialect that uses the [mysql2](https://github.com/sidorares/node-mysql2#readme) library.
  *
@@ -15,7 +16,7 @@ const mysql_adapter_js_1 = require("./mysql-adapter.js");
 class MysqlDialect {
     #config;
     constructor(config) {
-        this.#config = config;
+        this.#config = (0, object_utils_js_1.freeze)({ ...config });
     }
     createDriver() {
         return new mysql_driver_js_1.MysqlDriver(this.#config);

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

@@ -9,7 +9,7 @@ class MysqlDriver {
     #connections = new WeakMap();
     #pool;
     constructor(config) {
-        this.#config = config;
+        this.#config = (0, object_utils_js_1.freeze)({ ...config });
     }
     async init() {
         // Import the `mysql2` module here instead at the top of the file

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

@@ -5,6 +5,7 @@ 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");
+const object_utils_js_1 = require("../../util/object-utils.js");
 /**
  * PostgreSQL dialect that uses the [pg](https://node-postgres.com/) library.
  *
@@ -18,7 +19,7 @@ const postgres_adapter_js_1 = require("./postgres-adapter.js");
 class PostgresDialect {
     #config;
     constructor(config) {
-        this.#config = config;
+        this.#config = (0, object_utils_js_1.freeze)({ ...config });
     }
     createDriver() {
         return new postgres_driver_js_1.PostgresDriver(this.#config);

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

@@ -9,7 +9,7 @@ class PostgresDriver {
     #connections = new WeakMap();
     #pool = null;
     constructor(config) {
-        this.#config = config;
+        this.#config = (0, object_utils_js_1.freeze)({ ...config });
     }
     async init() {
         // Import the `pg` module here instead at the top of the file

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

@@ -5,6 +5,7 @@ const sqlite_driver_js_1 = require("./sqlite-driver.js");
 const sqlite_query_compiler_js_1 = require("./sqlite-query-compiler.js");
 const sqlite_introspector_js_1 = require("./sqlite-introspector.js");
 const sqlite_adapter_js_1 = require("./sqlite-adapter.js");
+const object_utils_js_1 = require("../../util/object-utils.js");
 /**
  * SQLite dialect that uses the [better-sqlite3](https://github.com/JoshuaWise/better-sqlite3) library.
  *
@@ -15,7 +16,7 @@ const sqlite_adapter_js_1 = require("./sqlite-adapter.js");
 class SqliteDialect {
     #config;
     constructor(config) {
-        this.#config = config;
+        this.#config = (0, object_utils_js_1.freeze)({ ...config });
     }
     createDriver() {
         return new sqlite_driver_js_1.SqliteDriver(this.#config);

package/dist/cjs/dialect/sqlite/sqlite-driver.js

@@ -9,7 +9,7 @@ class SqliteDriver {
     #db;
     #connection;
     constructor(config) {
-        this.#config = config;
+        this.#config = (0, object_utils_js_1.freeze)({ ...config });
     }
     async init() {
         // Import the `better-sqlite3` module here instead at the top of the file

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

@@ -0,0 +1,68 @@
+import { DatabaseConnection } from './database-connection.js';
+import { Driver } from './driver.js';
+/**
+ * A driver that does absolutely nothing.
+ *
+ * You can use this to create Kysely instances solely for building queries
+ *
+ * ### Examples
+ *
+ * This example creates a Kysely instance for building postgres queries:
+ *
+ * ```ts
+ * const db = new Kysely<Database>({
+ *   dialect: {
+ *     createAdapter() {
+ *       return new PostgresAdapter()
+ *     },
+ *     createDriver() {
+ *       return new DummyDriver()
+ *     },
+ *     createIntrospector(db: Kysely<any>) {
+ *       return new PostgresIntrospector(db)
+ *     },
+ *     createQueryCompiler() {
+ *       return new PostgresQueryCompiler()
+ *     },
+ *   },
+ * })
+ * ```
+ */
+export declare class DummyDriver implements Driver {
+    /**
+     * Initializes the driver.
+     *
+     * After calling this method the driver should be usable and `acquireConnection` etc.
+     * methods should be callable.
+     *
+     * IMPORTANT: The underlying database engine driver (like [pg](https://node-postgres.com/))
+     * should be imported inside this function, not at the top of the driver file! This is
+     * important so that Kysely is usable without installing all database driver libraries
+     * it supports.
+     */
+    init(): Promise<void>;
+    /**
+     * Acquires a new connection from the pool.
+     */
+    acquireConnection(): Promise<DatabaseConnection>;
+    /**
+     * Begins a transaction.
+     */
+    beginTransaction(): Promise<void>;
+    /**
+     * Commits a transaction.
+     */
+    commitTransaction(): Promise<void>;
+    /**
+     * Rolls back a transaction.
+     */
+    rollbackTransaction(): Promise<void>;
+    /**
+     * Releases a connection back to the pool.
+     */
+    releaseConnection(): Promise<void>;
+    /**
+     * Destroys the driver and releases all resources.
+     */
+    destroy(): Promise<void>;
+}

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

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DummyDriver = void 0;
+/**
+ * A driver that does absolutely nothing.
+ *
+ * You can use this to create Kysely instances solely for building queries
+ *
+ * ### Examples
+ *
+ * This example creates a Kysely instance for building postgres queries:
+ *
+ * ```ts
+ * const db = new Kysely<Database>({
+ *   dialect: {
+ *     createAdapter() {
+ *       return new PostgresAdapter()
+ *     },
+ *     createDriver() {
+ *       return new DummyDriver()
+ *     },
+ *     createIntrospector(db: Kysely<any>) {
+ *       return new PostgresIntrospector(db)
+ *     },
+ *     createQueryCompiler() {
+ *       return new PostgresQueryCompiler()
+ *     },
+ *   },
+ * })
+ * ```
+ */
+class DummyDriver {
+    async init() {
+        // Nothing to do here.
+    }
+    async acquireConnection() {
+        return new DummyConnection();
+    }
+    async beginTransaction() {
+        // Nothing to do here.
+    }
+    async commitTransaction() {
+        // Nothing to do here.
+    }
+    async rollbackTransaction() {
+        // Nothing to do here.
+    }
+    async releaseConnection() {
+        // Nothing to do here.
+    }
+    async destroy() {
+        // Nothing to do here.
+    }
+}
+exports.DummyDriver = DummyDriver;
+class DummyConnection {
+    async executeQuery() {
+        return {
+            rows: [],
+        };
+    }
+}

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

@@ -28,7 +28,7 @@ export declare class RuntimeDriver implements Driver {
     /**
      * Releases a connection back to the pool.
      */
-    releaseConnection(runtimeConnection: DatabaseConnection): Promise<void>;
+    releaseConnection(connection: DatabaseConnection): Promise<void>;
     /**
      * Begins a transaction.
      */

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

@@ -12,7 +12,7 @@ class RuntimeDriver {
     #log;
     #initPromise;
     #destroyPromise;
-    #connections = new WeakMap();
+    #connections = new WeakSet();
     constructor(driver, log) {
         this.#driver = driver;
         this.#log = log;
@@ -29,17 +29,16 @@ class RuntimeDriver {
     async acquireConnection() {
         await this.init();
         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);
+        if (!this.#connections.has(connection)) {
+            if (this.#needsLogging()) {
+                this.#addLogging(connection);
+            }
+            this.#connections.add(connection);
         }
-        return runtimeConnection;
+        return connection;
     }
-    async releaseConnection(runtimeConnection) {
-        if (runtimeConnection instanceof RuntimeConnection) {
-            await this.#driver.releaseConnection(runtimeConnection.connection);
-        }
+    async releaseConnection(connection) {
+        await this.#driver.releaseConnection(connection);
     }
     beginTransaction(connection, settings) {
         return this.#driver.beginTransaction(connection, settings);
@@ -63,30 +62,27 @@ class RuntimeDriver {
         }
         await this.#destroyPromise;
     }
-}
-exports.RuntimeDriver = RuntimeDriver;
-class RuntimeConnection {
-    #connection;
-    #log;
-    get connection() {
-        return this.#connection;
-    }
-    constructor(connection, log) {
-        this.#connection = connection;
-        this.#log = log;
+    #needsLogging() {
+        return (this.#log.isLevelEnabled('query') || this.#log.isLevelEnabled('error'));
     }
-    async executeQuery(compiledQuery) {
-        const startTime = (0, performance_now_js_1.performanceNow)();
-        try {
-            return await this.#connection.executeQuery(compiledQuery);
-        }
-        catch (error) {
-            this.#logError(error);
-            throw error;
-        }
-        finally {
-            this.#logQuery(compiledQuery, startTime);
-        }
+    // This method monkey patches the database connection's executeQuery method
+    // by adding logging code around it. Monkey patching is not pretty, but it's
+    // the best option in this case.
+    #addLogging(connection) {
+        const executeQuery = connection.executeQuery;
+        connection.executeQuery = async (compiledQuery) => {
+            const startTime = (0, performance_now_js_1.performanceNow)();
+            try {
+                return await executeQuery.call(connection, compiledQuery);
+            }
+            catch (error) {
+                this.#logError(error);
+                throw error;
+            }
+            finally {
+                this.#logQuery(compiledQuery, startTime);
+            }
+        };
     }
     #logError(error) {
         this.#log.error(() => ({
@@ -105,3 +101,4 @@ class RuntimeConnection {
         return (0, performance_now_js_1.performanceNow)() - startTime;
     }
 }
+exports.RuntimeDriver = RuntimeDriver;

package/dist/cjs/index-nodeless.d.ts

@@ -40,6 +40,7 @@ export * from './driver/database-connection.js';
 export * from './driver/connection-provider.js';
 export * from './driver/default-connection-provider.js';
 export * from './driver/single-connection-provider.js';
+export * from './driver/dummy-driver.js';
 export * from './dialect/dialect.js';
 export * from './dialect/dialect-adapter.js';
 export * from './dialect/dialect-adapter-base.js';
@@ -58,6 +59,7 @@ export * from './query-compiler/query-compiler.js';
 export * from './migration/migrator.js';
 export * from './plugin/kysely-plugin.js';
 export * from './plugin/camel-case/camel-case-plugin.js';
+export * from './plugin/deduplicate-joins/deduplicate-joins-plugin.js';
 export * from './operation-node/add-column-node.js';
 export * from './operation-node/add-constraint-node.js';
 export * from './operation-node/alias-node.js';

package/dist/cjs/index-nodeless.js

@@ -52,6 +52,7 @@ __exportStar(require("./driver/database-connection.js"), exports);
 __exportStar(require("./driver/connection-provider.js"), exports);
 __exportStar(require("./driver/default-connection-provider.js"), exports);
 __exportStar(require("./driver/single-connection-provider.js"), exports);
+__exportStar(require("./driver/dummy-driver.js"), exports);
 __exportStar(require("./dialect/dialect.js"), exports);
 __exportStar(require("./dialect/dialect-adapter.js"), exports);
 __exportStar(require("./dialect/dialect-adapter-base.js"), exports);
@@ -70,6 +71,7 @@ __exportStar(require("./query-compiler/query-compiler.js"), exports);
 __exportStar(require("./migration/migrator.js"), exports);
 __exportStar(require("./plugin/kysely-plugin.js"), exports);
 __exportStar(require("./plugin/camel-case/camel-case-plugin.js"), exports);
+__exportStar(require("./plugin/deduplicate-joins/deduplicate-joins-plugin.js"), exports);
 __exportStar(require("./operation-node/add-column-node.js"), exports);
 __exportStar(require("./operation-node/add-constraint-node.js"), exports);
 __exportStar(require("./operation-node/alias-node.js"), exports);

package/dist/cjs/kysely.d.ts

@@ -22,22 +22,24 @@ import { DialectAdapter } from './dialect/dialect-adapter.js';
  * This example assumes your database has tables `person` and `pet`:
  *
  * ```ts
- * interface Person {
- *   id: number
+ * import { Kysely, Generated, PostgresDialect } from 'kysely'
+ *
+ * interface PersonTable {
+ *   id: Generated<number>
  *   first_name: string
  *   last_name: string
  * }
  *
- * interface Pet {
- *   id: number
+ * interface PetTable {
+ *   id: Generated<number>
  *   owner_id: number
  *   name: string
  *   species 'cat' | 'dog'
  * }
  *
  * interface Database {
- *   person: Person,
- *   pet: Pet
+ *   person: PersonTable,
+ *   pet: PetTable
  * }
  *
  * const db = new Kysely<Database>({

package/dist/cjs/kysely.js

@@ -26,22 +26,24 @@ const private_symbols_js_1 = require("./util/private-symbols.js");
  * This example assumes your database has tables `person` and `pet`:
  *
  * ```ts
- * interface Person {
- *   id: number
+ * import { Kysely, Generated, PostgresDialect } from 'kysely'
+ *
+ * interface PersonTable {
+ *   id: Generated<number>
  *   first_name: string
  *   last_name: string
  * }
  *
- * interface Pet {
- *   id: number
+ * interface PetTable {
+ *   id: Generated<number>
  *   owner_id: number
  *   name: string
  *   species 'cat' | 'dog'
  * }
  *
  * interface Database {
- *   person: Person,
- *   pet: Pet
+ *   person: PersonTable,
+ *   pet: PetTable
  * }
  *
  * const db = new Kysely<Database>({

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

@@ -36,6 +36,12 @@ export interface Migration {
 export declare class Migrator {
     #private;
     constructor(props: MigratorProps);
+    /**
+     * Returns a {@link MigrationInfo} object for each migration.
+     *
+     * The returned array is sorted by migration name.
+     */
+    getMigrations(): Promise<ReadonlyArray<MigrationInfo>>;
     /**
      * Runs all migrations that have not yet been run.
      *
@@ -219,3 +225,19 @@ export interface MigrationProvider {
 export interface NoMigrations {
     readonly __noMigrations__: true;
 }
+export interface MigrationInfo {
+    /**
+     * Name of the migration.
+     */
+    name: string;
+    /**
+     * The actual migration.
+     */
+    migration: Migration;
+    /**
+     * When was the migration executed.
+     *
+     * If this is undefined, the migration hasn't been executed yet.
+     */
+    executedAt?: Date;
+}