kysely 0.16.6 → 0.16.10

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Sami Koskimäki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -1,5 +1,33 @@
 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.

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

@@ -1,9 +1,37 @@
 "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 {
-    init() {
-        throw new Error('Method not implemented.');
+    async init() {
+        // Nothing to do here.
     }
     async acquireConnection() {
         return new DummyConnection();
@@ -26,7 +54,7 @@ class DummyDriver {
 }
 exports.DummyDriver = DummyDriver;
 class DummyConnection {
-    async executeQuery(compiledQuery) {
+    async executeQuery() {
         return {
             rows: [],
         };

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

@@ -59,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

@@ -71,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>({
@@ -343,12 +345,12 @@ class ConnectionBuilder {
     async execute(callback) {
         const connection = await this.#props.driver.acquireConnection();
         const connectionProvider = new single_connection_provider_js_1.SingleConnectionProvider(connection);
-        const transaction = new Kysely({
+        const db = new Kysely({
             ...this.#props,
             executor: this.#props.executor.withConnectionProvider(connectionProvider),
         });
         try {
-            return await callback(transaction);
+            return await callback(db);
         }
         finally {
             await this.#props.driver.releaseConnection(connection);

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;
+}

package/dist/cjs/migration/migrator.js

@@ -32,6 +32,28 @@ class Migrator {
     constructor(props) {
         this.#props = (0, object_utils_js_1.freeze)(props);
     }
+    /**
+     * Returns a {@link MigrationInfo} object for each migration.
+     *
+     * The returned array is sorted by migration name.
+     */
+    async getMigrations() {
+        const executedMigrations = (await this.#doesTableExists(exports.MIGRATION_TABLE))
+            ? await this.#props.db
+                .selectFrom(exports.MIGRATION_TABLE)
+                .select(['name', 'timestamp'])
+                .execute()
+            : [];
+        const migrations = await this.#resolveMigrations();
+        return migrations.map(({ name, ...migration }) => {
+            const executed = executedMigrations.find((it) => it.name === name);
+            return {
+                name,
+                migration,
+                executedAt: executed ? new Date(executed.timestamp) : undefined,
+            };
+        });
+    }
     /**
      * Runs all migrations that have not yet been run.
      *
@@ -215,7 +237,7 @@ class Migrator {
             try {
                 await this.#props.db
                     .insertInto(exports.MIGRATION_LOCK_TABLE)
-                    .values({ id: exports.MIGRATION_LOCK_ID })
+                    .values({ id: exports.MIGRATION_LOCK_ID, is_locked: 0 })
                     .execute();
             }
             catch (error) {

package/dist/cjs/plugin/deduplicate-joins/deduplicate-joins-plugin.d.ts

@@ -0,0 +1,48 @@
+import { QueryResult } from '../../driver/database-connection.js';
+import { RootOperationNode } from '../../query-compiler/query-compiler.js';
+import { UnknownRow } from '../../util/type-utils.js';
+import { KyselyPlugin, PluginTransformQueryArgs, PluginTransformResultArgs } from '../kysely-plugin.js';
+/**
+ * Plugin that removes duplicate joins from queries.
+ *
+ * See [this recipe](https://github.com/koskimas/kysely/tree/master/recipes/deduplicate-joins.md)
+ */
+export declare class DeduplicateJoinsPlugin implements KyselyPlugin {
+    #private;
+    /**
+     * This is called for each query before it is executed. You can modify the query by
+     * transforming its {@link OperationNode} tree provided in {@link PluginTransformQueryArgs.node | args.node}
+     * and returning the transformed tree. You'd usually want to use an {@link OperationNodeTransformer}
+     * for this.
+     *
+     * If you need to pass some query-related data between this method and `transformResult` you
+     * can use a `WeakMap` with {@link PluginTransformQueryArgs.queryId | args.queryId} as the key:
+     *
+     * ```ts
+     * const plugin = {
+     *   data: new WeakMap<QueryId, SomeData>(),
+     *
+     *   transformQuery(args: PluginTransformQueryArgs): RootOperationNode {
+     *     this.data.set(args.queryId, something)
+     *     return args.node
+     *   },
+     *
+     *   transformResult(args: PluginTransformResultArgs): QueryResult<UnknownRow> {
+     *     const data = this.data.get(args.queryId)
+     *     return args.result
+     *   }
+     * }
+     * ```
+     *
+     * You should use a `WeakMap` instead of a `Map` or some other strong references because `transformQuery`
+     * is not always matched by a call to `transformResult` which would leave orphaned items in the map
+     * and cause a memory leak.
+     */
+    transformQuery(args: PluginTransformQueryArgs): RootOperationNode;
+    /**
+     * This method is called for each query after it has been executed. The result
+     * of the query can be accessed through {@link PluginTransformResultArgs.result | args.result}.
+     * You can modify the result and return the modifier result.
+     */
+    transformResult(args: PluginTransformResultArgs): Promise<QueryResult<UnknownRow>>;
+}

package/dist/cjs/plugin/deduplicate-joins/deduplicate-joins-plugin.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeduplicateJoinsPlugin = void 0;
+const deduplicate_joins_transformer_js_1 = require("./deduplicate-joins-transformer.js");
+/**
+ * Plugin that removes duplicate joins from queries.
+ *
+ * See [this recipe](https://github.com/koskimas/kysely/tree/master/recipes/deduplicate-joins.md)
+ */
+class DeduplicateJoinsPlugin {
+    #transformer = new deduplicate_joins_transformer_js_1.DeduplicateJoinsTransformer();
+    transformQuery(args) {
+        return this.#transformer.transformNode(args.node);
+    }
+    transformResult(args) {
+        return Promise.resolve(args.result);
+    }
+}
+exports.DeduplicateJoinsPlugin = DeduplicateJoinsPlugin;

package/dist/cjs/plugin/deduplicate-joins/deduplicate-joins-transformer.d.ts

@@ -0,0 +1,9 @@
+import { DeleteQueryNode, UpdateQueryNode } from '../../index-nodeless.js';
+import { OperationNodeTransformer } from '../../operation-node/operation-node-transformer.js';
+import { SelectQueryNode } from '../../operation-node/select-query-node.js';
+export declare class DeduplicateJoinsTransformer extends OperationNodeTransformer {
+    #private;
+    protected transformSelectQuery(node: SelectQueryNode): SelectQueryNode;
+    protected transformUpdateQuery(node: UpdateQueryNode): UpdateQueryNode;
+    protected transformDeleteQuery(node: DeleteQueryNode): DeleteQueryNode;
+}