kysely 0.11.4 → 0.13.0

package/dist/esm/kysely.d.ts

@@ -17,7 +17,8 @@ import { LogConfig } from './util/log.js';
  * You should create one instance of `Kysely` per database using the {@link Kysely}
  * constructor. Each `Kysely` instance maintains it's own connection pool.
  *
- * @example
+ * ### Examples
+ *
  * This example assumes your database has tables `person` and `pet`:
  *
  * ```ts
@@ -31,7 +32,7 @@ import { LogConfig } from './util/log.js';
  *   id: number
  *   owner_id: number
  *   name: string
- *   species 'cat' | 'dog'
+ *   species 'cat' | 'dog'
  * }
  *
  * interface Database {
@@ -78,10 +79,11 @@ export declare class Kysely<DB> extends QueryCreator<DB> {
      * A value to be used in place of columns that are generated in the database
      * when inserting rows.
      *
-     * @example
+     * ### Examples
+     *
      * In this example the `Person` table has non-null properties `id` and `created_at`
      * which are both automatically genereted by the database. Since their types are
-     * `number` and `string` respectively instead of `number | null` and `string | null`
+     * `number` and `string` respectively instead of `number | null` and `string | null`
      * the `values` method requires you to give a value for them. the `generated`
      * placeholder can be used in these cases.
      *
@@ -136,12 +138,13 @@ export declare class Kysely<DB> extends QueryCreator<DB> {
      * 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}
+     * 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
+     * ### Examples
+     *
      * ```ts
      * const catto = await db.transaction().execute(async (trx) => {
      *   const jennifer = await trx.insertInto('person')
@@ -167,8 +170,7 @@ export declare class Kysely<DB> extends QueryCreator<DB> {
      * })
      * ```
      *
-     * @example
-     * Setting the isolation level.
+     * Setting the isolation level:
      *
      * ```ts
      * await db
@@ -183,7 +185,8 @@ export declare class Kysely<DB> extends QueryCreator<DB> {
     /**
      * Provides a kysely instance bound to a single database connection.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * await db
      *   .connection()
@@ -204,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.
      *
@@ -218,10 +253,134 @@ export declare class Kysely<DB> extends QueryCreator<DB> {
     get isTransaction(): boolean;
 }
 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;
@@ -240,7 +399,8 @@ export interface KyselyConfig {
      * Currently there's only two levels: `query` and `error`.
      * This will be expanded based on user feedback later.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * const db = new Kysely<Database>({
      *   dialect: new PostgresDialect(postgresConfig),
@@ -248,7 +408,6 @@ export interface KyselyConfig {
      * })
      * ```
      *
-     * @example
      * ```ts
      * const db = new Kysely<Database>({
      *   dialect: new PostgresDialect(postgresConfig),

package/dist/esm/kysely.js

@@ -19,7 +19,8 @@ import { Log } from './util/log.js';
  * You should create one instance of `Kysely` per database using the {@link Kysely}
  * constructor. Each `Kysely` instance maintains it's own connection pool.
  *
- * @example
+ * ### Examples
+ *
  * This example assumes your database has tables `person` and `pet`:
  *
  * ```ts
@@ -33,7 +34,7 @@ import { Log } from './util/log.js';
  *   id: number
  *   owner_id: number
  *   name: string
- *   species 'cat' | 'dog'
+ *   species 'cat' | 'dog'
  * }
  *
  * interface Database {
@@ -111,10 +112,11 @@ export class Kysely extends QueryCreator {
      * A value to be used in place of columns that are generated in the database
      * when inserting rows.
      *
-     * @example
+     * ### Examples
+     *
      * In this example the `Person` table has non-null properties `id` and `created_at`
      * which are both automatically genereted by the database. Since their types are
-     * `number` and `string` respectively instead of `number | null` and `string | null`
+     * `number` and `string` respectively instead of `number | null` and `string | null`
      * the `values` method requires you to give a value for them. the `generated`
      * placeholder can be used in these cases.
      *
@@ -173,12 +175,13 @@ export class Kysely extends QueryCreator {
      * 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}
+     * 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
+     * ### Examples
+     *
      * ```ts
      * const catto = await db.transaction().execute(async (trx) => {
      *   const jennifer = await trx.insertInto('person')
@@ -204,8 +207,7 @@ export class Kysely extends QueryCreator {
      * })
      * ```
      *
-     * @example
-     * Setting the isolation level.
+     * Setting the isolation level:
      *
      * ```ts
      * await db
@@ -222,7 +224,8 @@ export class Kysely extends QueryCreator {
     /**
      * Provides a kysely instance bound to a single database connection.
      *
-     * @example
+     * ### Examples
+     *
      * ```ts
      * await db
      *   .connection()
@@ -255,6 +258,40 @@ export class Kysely extends 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.
      *
@@ -273,6 +310,11 @@ export class Kysely extends QueryCreator {
     }
 }
 export class Transaction extends Kysely {
+    #props;
+    constructor(props) {
+        super(props);
+        this.#props = props;
+    }
     // The return type is `true` instead of `boolean` to make Kysely<DB>
     // unassignable to Transaction<DB> while allowing assignment the
     // other way around.
@@ -285,9 +327,27 @@ export class Transaction extends Kysely {
     transaction() {
         throw new Error('calling the transaction method for a Transaction is not supported');
     }
+    connection() {
+        throw new Error('calling the connection method for a Transaction is not supported');
+    }
     async destroy() {
         throw new Error('calling the destroy method for a Transaction is not supported');
     }
+    withPlugin(plugin) {
+        return new Transaction({
+            ...this.#props,
+            executor: this.#props.executor.withPlugin(plugin),
+        });
+    }
+    withoutPlugins() {
+        return new Transaction({
+            ...this.#props,
+            executor: this.#props.executor.withoutPlugins(),
+        });
+    }
+    withTables() {
+        return new Transaction({ ...this.#props });
+    }
 }
 export function isKyselyProps(obj) {
     return (isObject(obj) &&

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

@@ -3,6 +3,73 @@ import { DialectAdapter } from '../dialect/dialect-adapter.js';
 export declare const MIGRATION_TABLE = "kysely_migration";
 export declare const MIGRATION_LOCK_TABLE = "kysely_migration_lock";
 export declare const MIGRATION_LOCK_ID = "migration_lock";
+export declare const NO_MIGRATIONS: NoMigrations;
+export declare type MigrationsOrFolderPath = Record<string, Migration> | string;
+export interface Migration {
+    up(db: Kysely<any>): Promise<void>;
+    down?(db: Kysely<any>): Promise<void>;
+}
+/**
+ * Type for the NO_MIGRATIONS constant. Never create one of these.
+ */
+export interface NoMigrations {
+    readonly __noMigrations__: true;
+}
+/**
+ * All migration methods ({@link MigrationModule.migrateTo | migrateTo},
+ * {@link MigrationModule.migrateToLatest | migrateToLatest} etc.) never
+ * throw but return this object instead.
+ */
+export interface MigrationResultSet {
+    /**
+     * This is defined if something went wrong.
+     *
+     * An error may have occurred in one of the migrations in which case the
+     * {@link results} list contains an item with `status === 'Error'` to
+     * indicate which migration failed.
+     *
+     * An error may also have occurred before Kysely was able to figure out
+     * which migrations should be executed, in which case the {@link results}
+     * list is undefined.
+     */
+    readonly error?: unknown;
+    /**
+     * {@link MigrationResult} for each individual migration that was supposed
+     * to be executed by the operation.
+     *
+     * If all went well, each result's `status` is `Success`. If some migration
+     * failed, the failed migration's result's `status` is `Error` and all
+     * results after that one have `status` ´NotExecuted`.
+     *
+     * This property can be undefined if an error occurred before Kysely was
+     * able to figure out which migrations should be executed.
+     *
+     * If this list is empty, there were no migrations to execute.
+     */
+    readonly results?: MigrationResult[];
+}
+export interface MigrationResult {
+    readonly migrationName: string;
+    /**
+     * The direction in which this migration was executed.
+     */
+    readonly direction: 'Up' | 'Down';
+    /**
+     * The execution status.
+     *
+     *  - `Success` means the migration was successfully executed. Note that
+     *    if any of the later migrations in the {@link MigrationResult.results}
+     *    list failed (have status `Error`) AND the dialect supports transactional
+     *    DDL, even the successfull migrations were rolled back.
+     *
+     *  - `Error` means the migration failed. In this case the
+     *    {@link MigrationResult.error} contains the error.
+     *
+     *  - `NotExecuted` means that the migration was supposed to be executed
+     *    but wasn't because an earlier migration failed.
+     */
+    readonly status: 'Success' | 'Error' | 'NotExecuted';
+}
 export declare class MigrationModule {
     #private;
     constructor(db: Kysely<any>, adapter: DialectAdapter);
@@ -10,27 +77,46 @@ export declare class MigrationModule {
      * Runs all migrations that have not yet been run.
      *
      * The only argument must either be a file path to the folder that contains all migrations
-     * OR an object that contains all migrations (not just the ones that need to be run).
+     * OR an object that contains all migrations (not just the ones that need to be executed).
      * The keys in the object must be the unique migration names.
      *
+     * This method returns a {@link MigrationResultSet} instance and _never_ throws.
+     * {@link MigrationResultSet.error} holds the error if something went wrong.
+     * {@link MigrationResultSet.results} contains information about which migrations
+     * were executed and which failed. See the examples below.
+     *
      * This method goes through all possible migrations (passed as the argument) and runs the
      * ones whose names are alphabetically after the last migration that has been run. If the
-     * list of executed migrations doesn't match the list of possible migrations, and error
-     * is thrown.
+     * list of executed migrations doesn't match the beginning of the list of possible migrations
+     * an error is thrown.
+     *
+     * ### Examples
      *
-     * @example
      * ```ts
-     * await db.migration.migrateToLatest(
+     * const { error, results } = await db.migration.migrateToLatest(
      *   path.join(__dirname, 'migrations')
      * )
+     *
+     * 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 run `migrateToLatest`')
+     *   console.error(error)
+     * }
      * ```
      *
      * 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.
+     * This version of the `migrateToLatest` method can be useful if you are using a bundler
+     * like webpack or esbuild.
      *
-     * @example
      * ```ts
      * await db.migration.migrateToLatest({
      *   migration1: {
@@ -57,10 +143,67 @@ export declare class MigrationModule {
      * })
      * ```
      */
-    migrateToLatest(migrationsFolderPath: string): Promise<void>;
-    migrateToLatest(allMigrations: Record<string, Migration>): Promise<void>;
-}
-export interface Migration {
-    up(db: Kysely<any>): Promise<void>;
-    down?(db: Kysely<any>): Promise<void>;
+    migrateToLatest(migrationsFolderPath: string): Promise<MigrationResultSet>;
+    migrateToLatest(allMigrations: Record<string, Migration>): Promise<MigrationResultSet>;
+    /**
+     * Migrate up/down to a specific migration.
+     *
+     * Otherwise works just like {@link migrateToLatest}. The first argument
+     * behaves the same, the output is the same etc.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.migration.migrateTo(
+     *   path.join(__dirname, 'migrations'),
+     *   'some_migration'
+     * )
+     * ```
+     *
+     * If you specify the name of the first migration, this method migrates
+     * down to the first migration, but doesn't run the `down` migration for
+     * the first migration. In case you want to migrate down ALL migrations
+     * you can use a special constant `NO_MIGRATIONS`:
+     *
+     * ```ts
+     * await db.migration.migrateTo(
+     *   path.join(__dirname, 'migrations'),
+     *   NO_MIGRATIONS,
+     * )
+     * ```
+     */
+    migrateTo(migrationsFolderPath: string, targetMigrationName: string | NoMigrations): Promise<MigrationResultSet>;
+    migrateTo(allMigrations: Record<string, Migration>, targetMigrationName: string | NoMigrations): Promise<MigrationResultSet>;
+    /**
+     * Migrate one step up.
+     *
+     * Otherwise works just like {@link migrateToLatest}. The only argument
+     * behaves the same, the output is the same etc.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.migration.migrateUp(
+     *   path.join(__dirname, 'migrations'),
+     * )
+     * ```
+     */
+    migrateUp(migrationsFolderPath: string): Promise<MigrationResultSet>;
+    migrateUp(allMigrations: Record<string, Migration>): Promise<MigrationResultSet>;
+    /**
+     * Migrate one step down.
+     *
+     * Otherwise works just like {@link migrateToLatest}. The only argument
+     * behaves the same, the output is the same etc.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db.migration.migrateDown(
+     *   path.join(__dirname, 'migrations'),
+     * )
+     * ```
+     */
+    migrateDown(migrationsFolderPath: string): Promise<MigrationResultSet>;
+    migrateDown(allMigrations: Record<string, Migration>): Promise<MigrationResultSet>;
 }