kysely 0.16.6 → 0.16.7

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)
 
@@ -341,6 +345,8 @@ async function migrateToLatest() {
     console.error(error)
     process.exit(1)
   }
+
+  await db.destroy()
 }
 
 migrateToLatest()
@@ -350,6 +356,113 @@ The migration methods use a lock on the database level, and parallel calls are e
 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.
 
+# 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
 
 Kysely is very similar to knex, but it also attempts to fix things that I personally find not-so-good

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>({

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

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

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DeduplicateJoinsTransformer = void 0;
+const operation_node_transformer_js_1 = require("../../operation-node/operation-node-transformer.js");
+const object_utils_js_1 = require("../../util/object-utils.js");
+class DeduplicateJoinsTransformer extends operation_node_transformer_js_1.OperationNodeTransformer {
+    transformSelectQuery(node) {
+        return this.#transformQuery(super.transformSelectQuery(node));
+    }
+    transformUpdateQuery(node) {
+        return this.#transformQuery(super.transformUpdateQuery(node));
+    }
+    transformDeleteQuery(node) {
+        return this.#transformQuery(super.transformDeleteQuery(node));
+    }
+    #transformQuery(node) {
+        if (!node.joins || node.joins.length === 0) {
+            return node;
+        }
+        return (0, object_utils_js_1.freeze)({
+            ...node,
+            joins: this.#deduplicateJoins(node.joins),
+        });
+    }
+    #deduplicateJoins(joins) {
+        const out = [];
+        for (let i = 0; i < joins.length; ++i) {
+            let foundDuplicate = false;
+            for (let j = i + 1; j < joins.length; ++j) {
+                if ((0, object_utils_js_1.compare)(joins[i], joins[j])) {
+                    foundDuplicate = true;
+                    break;
+                }
+            }
+            if (!foundDuplicate) {
+                out.push(joins[i]);
+            }
+        }
+        return (0, object_utils_js_1.freeze)(out);
+    }
+}
+exports.DeduplicateJoinsTransformer = DeduplicateJoinsTransformer;

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

@@ -6,7 +6,7 @@ import { SelectExpression } from '../parser/select-parser.js';
 import { ExistsExpression, FilterOperator, FilterValueExpressionOrList, WhereGrouper } from '../parser/filter-parser.js';
 import { ReturningRow } from '../parser/returning-parser.js';
 import { ReferenceExpression } from '../parser/reference-parser.js';
-import { AnyRawBuilder, SingleResultType } from '../util/type-utils.js';
+import { AnyRawBuilder, MergePartial, SingleResultType } from '../util/type-utils.js';
 import { Compilable } from '../util/compilable.js';
 import { QueryExecutor } from '../query-executor/query-executor.js';
 import { QueryId } from '../util/query-id.js';
@@ -16,6 +16,7 @@ import { WhereInterface } from './where-interface.js';
 import { JoinInterface } from './join-interface.js';
 import { ReturningInterface } from './returning-interface.js';
 import { NoResultErrorConstructor } from './no-result-error.js';
+import { DeleteResult } from './delete-result.js';
 import { DeleteQueryNode } from '../operation-node/delete-query-node.js';
 import { Selectable } from '../util/column-type.js';
 export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements WhereInterface<DB, TB>, JoinInterface<DB, TB>, ReturningInterface<DB, TB, O>, OperationNodeSource, Compilable {
@@ -589,23 +590,61 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
     /**
      * Simply calls the given function passing `this` as the only argument.
      *
-     * This method can be useful when adding optional method calls:
+     * If you want to conditionally call a method on `this`, see
+     * the {@link if} method.
      *
      * ### Examples
      *
+     * The next example uses a helper funtion `log` to log a query:
+     *
      * ```ts
+     * function log<T extends Compilable>(qb: T): T {
+     *   console.log(qb.compile())
+     *   return qb
+     * }
+     *
      * db.deleteFrom('person')
-     *   .call((qb) => {
-     *     if (something) {
-     *       return qb.where('something', '=', something)
-     *     } else {
-     *       return qb.where('somethingElse', '=', somethingElse)
-     *     }
-     *   })
+     *   .call(log)
      *   .execute()
      * ```
      */
     call<T>(func: (qb: this) => T): T;
+    /**
+     * Call `func(this)` if `condition` is true.
+     *
+     * This method is especially handy with optional selects. Any `returning` or `returningAll`
+     * method calls add columns as optional fields to the output type when called inside
+     * the `func` callback. This is because we can't know if those selections were actually
+     * made before running the code.
+     *
+     * You can also call any other methods inside the callback.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * async function deletePerson(id: number, returnLastName: boolean) {
+     *   return await db
+     *     .deleteFrom('person')
+     *     .where('id', '=', id)
+     *     .returning(['id', 'first_name'])
+     *     .if(returnLastName, (qb) => qb.returning('last_name'))
+     *     .executeTakeFirstOrThrow()
+     * }
+     * ```
+     *
+     * Any selections added inside the `if` callback will be added as optional fields to the
+     * output type since we can't know if the selections were actually made before running
+     * the code. In the example above the return type of the `deletePerson` function is:
+     *
+     * ```ts
+     * {
+     *   id: number
+     *   first_name: string
+     *   last_name?: string
+     * }
+     * ```
+     */
+    if<O2>(condition: boolean, func: (qb: this) => DeleteQueryBuilder<DB, TB, O2>): DeleteQueryBuilder<DB, TB, O2 extends DeleteResult ? DeleteResult : O extends DeleteResult ? Partial<O2> : MergePartial<O, O2>>;
     /**
      * Change the output type of the query.
      *
@@ -613,6 +652,9 @@ export declare class DeleteQueryBuilder<DB, TB extends keyof DB, O> implements W
      * don't support your use case.
      */
     castTo<T>(): DeleteQueryBuilder<DB, TB, T>;
+    /**
+     * Returns a copy of this DeleteQueryBuilder instance with the given plugin installed.
+     */
     withPlugin(plugin: KyselyPlugin): DeleteQueryBuilder<DB, TB, O>;
     toOperationNode(): DeleteQueryNode;
     compile(): CompiledQuery;