kysely 0.12.1 → 0.14.1

package/README.md

@@ -252,32 +252,56 @@ await db.migration.migrateToLatest(pathToMigrationsFolder)
 ```
 
 to run all migrations that have not yet been run. The migrations are executed in alphabetical
-order by their file name.
+order by their name. See the [migration module](https://koskimas.github.io/kysely/classes/MigrationModule.html) 
+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
 typescript code into javascript. The CLI would cause confusion over which migrations are being
-run, the typescript ones or the javascript ones. If we added support for both, it would mean the
-CLI would depend on a typescript compiler, which most production environments don't (and shouldn't)
+run, the typescript ones or the javascript ones. If we added support for both, the CLI would 
+need to depend on a typescript compiler, which most production environments don't (and shouldn't)
 have. You will probably want to add a simple migration script to your projects like this:
 
 ```ts
 import path from 'path'
+
+// This example assumes you have a file named `database.ts` that
+// creates and exports a `Kysely` instance `db`. You can just
+// as well create a new `Kysely` instance in the function below
+// or do something completely different to obtain an instance
+// of `Kysely`.
 import { db } from './database'
 
-db.migration
-  .migrateToLatest(path.join(__dirname, 'migrations'))
-  .then(() => db.destroy())
+async function migrateToLatest() {
+  const { error, results } = await db.migration.migrateToLatest(
+    path.join(__dirname, 'migrations')
+  )
+
+  // Destroy the `Kysely` instance to make the script exit faster.
+  await db.destroy()
+
+  results?.forEach((it) => {
+    if (it.status === 'Success') {
+      console.log(`migration "${it.migrationName}" was executed successfully`)
+    } else if (it.status === 'Error') {
+      console.error(`failed to execute migration "${it.migrationName}"`)
+    }
+  })
+
+  if (error) {
+    console.error('failed to migrate')
+    console.error(error)
+    process.exit(1)
+  }
+}
+
+migrateToLatest()
 ```
 
 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.
 
-NOTE: Only `db.migration.migrateToLatest` method is implemented at the moment. There is no way
-to run the down migrations, or to go forward to a specific migration. These methods will be
-added soon.
-
 # 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/dialect.d.ts

@@ -1,7 +1,7 @@
 import { Driver } from '../driver/driver.js';
 import { Kysely } from '../kysely.js';
 import { QueryCompiler } from '../query-compiler/query-compiler.js';
-import { DatabaseIntrospector } from '../introspection/database-introspector.js';
+import { DatabaseIntrospector } from './database-introspector.js';
 import { DialectAdapter } from './dialect-adapter.js';
 /**
  * A Dialect is the glue between Kysely and the underlying database engine.

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

@@ -1,6 +1,6 @@
 import { Kysely } from '../../kysely.js';
-import { DialectAdapter } from '../dialect-adapter.js';
-export declare class MysqlAdapter implements DialectAdapter {
+import { DialectAdapterBase } from '../dialect-adapter-base.js';
+export declare class MysqlAdapter extends DialectAdapterBase {
     /**
      * Whether or not this dialect supports transactional DDL.
      *

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

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MysqlAdapter = void 0;
+const dialect_adapter_base_js_1 = require("../dialect-adapter-base.js");
 const LOCK_ID = 'ea586330-2c93-47c8-908d-981d9d270f9d';
 const LOCK_TIMEOUT_SECONDS = 60 * 60;
-class MysqlAdapter {
+class MysqlAdapter extends dialect_adapter_base_js_1.DialectAdapterBase {
     get supportsTransactionalDdl() {
         return false;
     }

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

@@ -2,7 +2,7 @@ import { Driver } from '../../driver/driver.js';
 import { Kysely } from '../../kysely.js';
 import { QueryCompiler } from '../../query-compiler/query-compiler.js';
 import { Dialect } from '../dialect.js';
-import { DatabaseIntrospector } from '../../introspection/database-introspector.js';
+import { DatabaseIntrospector } from '../database-introspector.js';
 import { DialectAdapter } from '../dialect-adapter.js';
 import { DatabaseConnection } from '../../driver/database-connection.js';
 /**

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

@@ -1,4 +1,4 @@
-import { DatabaseIntrospector, DatabaseMetadata, DatabaseMetadataOptions } from '../../introspection/database-introspector.js';
+import { DatabaseIntrospector, DatabaseMetadata, DatabaseMetadataOptions } from '../database-introspector.js';
 import { Kysely } from '../../kysely.js';
 export declare class MysqlIntrospector implements DatabaseIntrospector {
     #private;

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

@@ -1,6 +1,6 @@
 import { Kysely } from '../../kysely.js';
-import { DialectAdapter } from '../dialect-adapter.js';
-export declare class PostgresAdapter implements DialectAdapter {
+import { DialectAdapterBase } from '../dialect-adapter-base.js';
+export declare class PostgresAdapter extends DialectAdapterBase {
     /**
      * Whether or not this dialect supports transactional DDL.
      *

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

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PostgresAdapter = void 0;
+const dialect_adapter_base_js_1 = require("../dialect-adapter-base.js");
 // Random id for our transaction lock.
 const LOCK_ID = '3853314791062309107';
-class PostgresAdapter {
+class PostgresAdapter extends dialect_adapter_base_js_1.DialectAdapterBase {
     get supportsTransactionalDdl() {
         return true;
     }

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

@@ -5,7 +5,7 @@ import { Driver } from '../../driver/driver.js';
 import { Kysely } from '../../kysely.js';
 import { QueryCompiler } from '../../query-compiler/query-compiler.js';
 import { Dialect } from '../dialect.js';
-import { DatabaseIntrospector } from '../../introspection/database-introspector.js';
+import { DatabaseIntrospector } from '../database-introspector.js';
 import { DialectAdapter } from '../dialect-adapter.js';
 import { DatabaseConnection } from '../../driver/database-connection.js';
 /**

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

@@ -1,4 +1,4 @@
-import { DatabaseIntrospector, DatabaseMetadata, DatabaseMetadataOptions } from '../../introspection/database-introspector.js';
+import { DatabaseIntrospector, DatabaseMetadata, DatabaseMetadataOptions } from '../database-introspector.js';
 import { Kysely } from '../../kysely.js';
 export declare class PostgresIntrospector implements DatabaseIntrospector {
     #private;

package/dist/cjs/dialect/sqlite/sqlite-adapter.d.ts

@@ -1,5 +1,5 @@
-import { DialectAdapter } from '../dialect-adapter.js';
-export declare class SqliteAdapter implements DialectAdapter {
+import { DialectAdapterBase } from '../dialect-adapter-base.js';
+export declare class SqliteAdapter implements DialectAdapterBase {
     /**
      * Whether or not this dialect supports transactional DDL.
      *

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

@@ -2,7 +2,7 @@ import { Driver } from '../../driver/driver.js';
 import { Kysely } from '../../kysely.js';
 import { QueryCompiler } from '../../query-compiler/query-compiler.js';
 import { Dialect } from '../dialect.js';
-import { DatabaseIntrospector } from '../../introspection/database-introspector.js';
+import { DatabaseIntrospector } from '../database-introspector.js';
 import { DialectAdapter } from '../dialect-adapter.js';
 import { DatabaseConnection } from '../../driver/database-connection.js';
 /**

package/dist/cjs/dialect/sqlite/sqlite-introspector.d.ts

@@ -1,4 +1,4 @@
-import { DatabaseIntrospector, DatabaseMetadata, DatabaseMetadataOptions } from '../../introspection/database-introspector.js';
+import { DatabaseIntrospector, DatabaseMetadata, DatabaseMetadataOptions } from '../database-introspector.js';
 import { Kysely } from '../../kysely.js';
 export declare class SqliteIntrospector implements DatabaseIntrospector {
     #private;

package/dist/cjs/index.d.ts

@@ -15,6 +15,7 @@ export * from './query-builder/function-builder.js';
 export * from './query-builder/insert-result.js';
 export * from './query-builder/delete-result.js';
 export * from './query-builder/update-result.js';
+export * from './query-builder/on-conflict-builder.js';
 export * from './raw-builder/raw-builder.js';
 export * from './query-executor/query-executor.js';
 export * from './query-executor/default-query-executor.js';
@@ -73,6 +74,7 @@ export * from './operation-node/column-definition-node.js';
 export * from './operation-node/column-node.js';
 export * from './operation-node/column-update-node.js';
 export * from './operation-node/common-table-expression-node.js';
+export * from './operation-node/common-table-expression-name-node.js';
 export * from './operation-node/constraint-node.js';
 export * from './operation-node/create-index-node.js';
 export * from './operation-node/create-schema-node.js';
@@ -90,7 +92,7 @@ export * from './operation-node/drop-view-node.js';
 export * from './operation-node/filter-node.js';
 export * from './operation-node/foreign-key-constraint-node.js';
 export * from './operation-node/from-node.js';
-export * from './operation-node/generated-always-as-node.js';
+export * from './operation-node/generated-node.js';
 export * from './operation-node/group-by-item-node.js';
 export * from './operation-node/group-by-node.js';
 export * from './operation-node/having-node.js';
@@ -135,11 +137,11 @@ export * from './operation-node/value-node.js';
 export * from './operation-node/values-node.js';
 export * from './operation-node/where-node.js';
 export * from './operation-node/with-node.js';
-export * from './introspection/database-introspector.js';
+export * from './dialect/database-introspector.js';
 export * from './util/compilable.js';
 export * from './util/log.js';
 export { AnyColumn, UnknownRow, AnySelectQueryBuilder, } from './util/type-utils.js';
-export { SelectExpression, SelectExpressionOrList, } from './parser/select-parser.js';
+export { SelectExpression, SelectExpressionOrList, Selection, } from './parser/select-parser.js';
 export { ReferenceExpression, ReferenceExpressionOrList, } from './parser/reference-parser.js';
 export { ValueExpression, ValueExpressionOrList, } from './parser/value-parser.js';
 export { FilterValueExpression, FilterValueExpressionOrList, ExistsExpression, FilterOperator, } from './parser/filter-parser.js';

package/dist/cjs/index.js

@@ -27,6 +27,7 @@ __exportStar(require("./query-builder/function-builder.js"), exports);
 __exportStar(require("./query-builder/insert-result.js"), exports);
 __exportStar(require("./query-builder/delete-result.js"), exports);
 __exportStar(require("./query-builder/update-result.js"), exports);
+__exportStar(require("./query-builder/on-conflict-builder.js"), exports);
 __exportStar(require("./raw-builder/raw-builder.js"), exports);
 __exportStar(require("./query-executor/query-executor.js"), exports);
 __exportStar(require("./query-executor/default-query-executor.js"), exports);
@@ -85,6 +86,7 @@ __exportStar(require("./operation-node/column-definition-node.js"), exports);
 __exportStar(require("./operation-node/column-node.js"), exports);
 __exportStar(require("./operation-node/column-update-node.js"), exports);
 __exportStar(require("./operation-node/common-table-expression-node.js"), exports);
+__exportStar(require("./operation-node/common-table-expression-name-node.js"), exports);
 __exportStar(require("./operation-node/constraint-node.js"), exports);
 __exportStar(require("./operation-node/create-index-node.js"), exports);
 __exportStar(require("./operation-node/create-schema-node.js"), exports);
@@ -102,7 +104,7 @@ __exportStar(require("./operation-node/drop-view-node.js"), exports);
 __exportStar(require("./operation-node/filter-node.js"), exports);
 __exportStar(require("./operation-node/foreign-key-constraint-node.js"), exports);
 __exportStar(require("./operation-node/from-node.js"), exports);
-__exportStar(require("./operation-node/generated-always-as-node.js"), exports);
+__exportStar(require("./operation-node/generated-node.js"), exports);
 __exportStar(require("./operation-node/group-by-item-node.js"), exports);
 __exportStar(require("./operation-node/group-by-node.js"), exports);
 __exportStar(require("./operation-node/having-node.js"), exports);
@@ -147,6 +149,6 @@ __exportStar(require("./operation-node/value-node.js"), exports);
 __exportStar(require("./operation-node/values-node.js"), exports);
 __exportStar(require("./operation-node/where-node.js"), exports);
 __exportStar(require("./operation-node/with-node.js"), exports);
-__exportStar(require("./introspection/database-introspector.js"), exports);
+__exportStar(require("./dialect/database-introspector.js"), exports);
 __exportStar(require("./util/compilable.js"), exports);
 __exportStar(require("./util/log.js"), exports);

package/dist/cjs/kysely.d.ts

@@ -6,7 +6,7 @@ import { QueryExecutor } from './query-executor/query-executor.js';
 import { QueryCreator } from './query-creator.js';
 import { KyselyPlugin } from './plugin/kysely-plugin.js';
 import { GeneratedPlaceholder } from './util/type-utils.js';
-import { DatabaseIntrospector } from './introspection/database-introspector.js';
+import { DatabaseIntrospector } from './dialect/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';
@@ -207,6 +207,38 @@ export declare class Kysely<DB> extends QueryCreator<DB> {
      * Returns a copy of this Kysely instance without any plugins.
      */
     withoutPlugins(): Kysely<DB>;
+    /**
+     * Returns a copy of this Kysely instance with tables added to its
+     * database type.
+     *
+     * This method only modifies the types and doesn't affect any of the
+     * executed queries in any way.
+     *
+     * ### Examples
+     *
+     * The following example adds and uses a temporary table:
+     *
+     * @example
+     * ```ts
+     * await db.schema
+     *   .createTable('temp_table')
+     *   .temporary()
+     *   .addColumn('some_column', 'integer')
+     *   .execute()
+     *
+     * const tempDb = db.withTables<{
+     *   temp_table: {
+     *     some_column: number
+     *   }
+     * }>()
+     *
+     * await tempDb
+     *   .insertInto('temp_table')
+     *   .values({ some_column: 100 })
+     *   .execute()
+     * ```
+     */
+    withTables<T extends Record<string, Record<string, any>>>(): Kysely<DB & T>;
     /**
      * Releases all resources and disconnects from the database.
      *
@@ -223,13 +255,132 @@ export declare class Kysely<DB> extends QueryCreator<DB> {
 export declare class Transaction<DB> extends Kysely<DB> {
     #private;
     constructor(props: KyselyProps);
+    /**
+     * Returns true if this `Kysely` instance is a transaction.
+     *
+     * You can also use `db instanceof Transaction`.
+     */
     get isTransaction(): true;
+    /**
+     * Returns the {@link MigrationModule} module for managing and running migrations.
+     */
     get migration(): MigrationModule;
+    /**
+     * Creates a {@link TransactionBuilder} that can be used to run queries inside a transaction.
+     *
+     * 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.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const catto = await db.transaction().execute(async (trx) => {
+     *   const jennifer = await trx.insertInto('person')
+     *     .values({
+     *       id: db.generated,
+     *       first_name: 'Jennifer',
+     *       last_name: 'Aniston',
+     *     })
+     *     .returning('id')
+     *     .executeTakeFirstOrThrow()
+     *
+     *   await someFunction(trx, jennifer)
+     *
+     *   return await trx.insertInto('pet')
+     *     .values({
+     *       id: db.generated,
+     *       user_id: jennifer.id,
+     *       name: 'Catto',
+     *       species: 'cat'
+     *     })
+     *     .returning('*')
+     *     .executeTakeFirst()
+     * })
+     * ```
+     *
+     * Setting the isolation level:
+     *
+     * ```ts
+     * await db
+     *   .transaction()
+     *   .setIsolationLevel('serializable')
+     *   .execute(async (trx) => {
+     *     await doStuff(trx)
+     *   })
+     * ```
+     */
     transaction(): TransactionBuilder<DB>;
+    /**
+     * Provides a kysely instance bound to a single database connection.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db
+     *   .connection()
+     *   .execute(async (db) => {
+     *     // `db` is an instance of `Kysely` that's bound to a single
+     *     // database connection. All queries executed through `db` use
+     *     // the same connection.
+     *     await doStuff(db)
+     *   })
+     * ```
+     */
     connection(): ConnectionBuilder<DB>;
+    /**
+     * Releases all resources and disconnects from the database.
+     *
+     * You need to call this when you are done using the `Kysely` instance.
+     */
     destroy(): Promise<void>;
+    /**
+     * Returns a copy of this Kysely instance with the given plugin installed.
+     */
     withPlugin(plugin: KyselyPlugin): Transaction<DB>;
+    /**
+     * Returns a copy of this Kysely instance without any plugins.
+     */
     withoutPlugins(): Transaction<DB>;
+    /**
+     * Returns a copy of this Kysely instance with tables added to its
+     * database type.
+     *
+     * This method only modifies the types and doesn't affect any of the
+     * executed queries in any way.
+     *
+     * ### Examples
+     *
+     * The following example adds and uses a temporary table:
+     *
+     * @example
+     * ```ts
+     * await db.schema
+     *   .createTable('temp_table')
+     *   .temporary()
+     *   .addColumn('some_column', 'integer')
+     *   .execute()
+     *
+     * const tempDb = db.withTables<{
+     *   temp_table: {
+     *     some_column: number
+     *   }
+     * }>()
+     *
+     * await tempDb
+     *   .insertInto('temp_table')
+     *   .values({ some_column: 100 })
+     *   .execute()
+     * ```
+     */
+    withTables<T extends Record<string, Record<string, any>>>(): Transaction<DB & T>;
 }
 export interface KyselyProps {
     readonly config: KyselyConfig;

package/dist/cjs/kysely.js

@@ -261,6 +261,40 @@ class Kysely extends query_creator_js_1.QueryCreator {
             executor: this.#props.executor.withoutPlugins(),
         });
     }
+    /**
+     * Returns a copy of this Kysely instance with tables added to its
+     * database type.
+     *
+     * This method only modifies the types and doesn't affect any of the
+     * executed queries in any way.
+     *
+     * ### Examples
+     *
+     * The following example adds and uses a temporary table:
+     *
+     * @example
+     * ```ts
+     * await db.schema
+     *   .createTable('temp_table')
+     *   .temporary()
+     *   .addColumn('some_column', 'integer')
+     *   .execute()
+     *
+     * const tempDb = db.withTables<{
+     *   temp_table: {
+     *     some_column: number
+     *   }
+     * }>()
+     *
+     * await tempDb
+     *   .insertInto('temp_table')
+     *   .values({ some_column: 100 })
+     *   .execute()
+     * ```
+     */
+    withTables() {
+        return new Kysely({ ...this.#props });
+    }
     /**
      * Releases all resources and disconnects from the database.
      *
@@ -315,6 +349,9 @@ class Transaction extends Kysely {
             executor: this.#props.executor.withoutPlugins(),
         });
     }
+    withTables() {
+        return new Transaction({ ...this.#props });
+    }
 }
 exports.Transaction = Transaction;
 function isKyselyProps(obj) {