kysely 0.30.0-beta.0 → 0.30.0-beta.1

package/README.md

@@ -1,7 +1,7 @@
 [![Stand With Ukraine](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg)](https://stand-with-ukraine.pp.ua)
 
 [![NPM Version](https://img.shields.io/npm/v/kysely?style=flat&label=latest)](https://github.com/kysely-org/kysely/releases/latest)
-[![Socket Badge](https://badge.socket.dev/npm/package/kysely/0.30.0-beta.0)](https://socket.dev/npm/package/kysely/overview/0.30.0-beta.0)
+[![Socket Badge](https://badge.socket.dev/npm/package/kysely/0.30.0-beta.1)](https://socket.dev/npm/package/kysely/overview/0.30.0-beta.1)
 [![Tests](https://github.com/kysely-org/kysely/actions/workflows/test.yml/badge.svg)](https://github.com/kysely-org/kysely)
 [![License](https://img.shields.io/github/license/kysely-org/kysely?style=flat)](https://github.com/kysely-org/kysely/blob/master/LICENSE)
 [![Issues](https://img.shields.io/github/issues-closed/kysely-org/kysely?logo=github)](https://github.com/kysely-org/kysely/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc)

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

@@ -5,23 +5,25 @@ import type { AbortableOperationOptions } from '../../util/abort.js';
  */
 export interface MysqlDialectConfig {
     /**
-     * A `mysql2` `Client` constructor, to be used for connecting to the database
-     * outside of the `pool` to avoid waiting for an idle connection.
+     * A `createConnection` function (from either `mysql2` or `mysql2/promise`),
+     * to be used for connecting to the database outside of the `pool` to avoid
+     * waiting for an idle connection.
      *
      * This is useful for cancelling queries on the database side.
      */
     controlConnection?: {
-        (connectionUri: string): MysqlConnection;
-        (config: object): MysqlConnection;
+        (connectionUri: string): MysqlConnection | Promise<MysqlPromiseConnection>;
+        (config: object): MysqlConnection | Promise<MysqlPromiseConnection>;
     };
     /**
-     * A mysql2 Pool instance or a function that returns one.
+     * A mysql2 Pool instance (from either `mysql2` or `mysql2/promise`) or a
+     * function that returns one.
      *
      * If a function is provided, it's called once when the first query is executed.
      *
      * https://github.com/sidorares/node-mysql2#using-connection-pools
      */
-    pool: MysqlPool | ((options?: AbortableOperationOptions) => Promise<MysqlPool>);
+    pool: MysqlPool | MysqlPromisePool | ((options?: AbortableOperationOptions) => Promise<MysqlPool | MysqlPromisePool>);
     /**
      * Called once for each created connection.
      */
@@ -43,6 +45,17 @@ export interface MysqlPool {
     getConnection(callback: (error: unknown, connection: MysqlPoolConnection) => void): void;
     end(callback: (error: unknown) => void): void;
 }
+/**
+ * This interface is the subset of `mysql2/promise`'s `Pool` class that
+ * kysely needs.
+ *
+ * It's a thin promise wrapper around the callback pool, which it exposes
+ * as its `pool` property. The dialect unwraps it and uses the callback
+ * pool directly.
+ */
+export interface MysqlPromisePool {
+    pool: MysqlPool;
+}
 export interface MysqlConnection {
     config: object;
     connect(callback?: (error: unknown) => void): void;
@@ -52,6 +65,18 @@ export interface MysqlConnection {
     };
     threadId: number;
 }
+/**
+ * This interface is the subset of `mysql2/promise`'s `Connection` class that
+ * kysely needs.
+ *
+ * It's a thin promise wrapper around the callback connection. It's already
+ * connected when the `createConnection` promise resolves, so the dialect
+ * uses its promise-based API directly.
+ */
+export interface MysqlPromiseConnection {
+    destroy(): void;
+    query(sql: string, values?: unknown[]): Promise<unknown>;
+}
 export type MysqlConectionConstructor = new (opts?: object) => MysqlConnection;
 export interface MysqlPoolConnection extends MysqlConnection {
     release(): void;

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

@@ -11,7 +11,7 @@ import type { MysqlDialectConfig } from './mysql-dialect-config.js';
  * The constructor takes an instance of {@link MysqlDialectConfig}.
  *
  * ```ts
- * import { createPool } from 'mysql2'
+ * import { createPool } from 'mysql2/promise' // or just 'mysql2' — both work
  *
  * new MysqlDialect({
  *   pool: createPool({
@@ -25,7 +25,7 @@ import type { MysqlDialectConfig } from './mysql-dialect-config.js';
  * can be a function:
  *
  * ```ts
- * import { createPool } from 'mysql2'
+ * import { createPool } from 'mysql2/promise' // or just 'mysql2' — both work
  *
  * new MysqlDialect({
  *   pool: async () => createPool({

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

@@ -9,7 +9,7 @@ import { MysqlAdapter } from './mysql-adapter.js';
  * The constructor takes an instance of {@link MysqlDialectConfig}.
  *
  * ```ts
- * import { createPool } from 'mysql2'
+ * import { createPool } from 'mysql2/promise' // or just 'mysql2' — both work
  *
  * new MysqlDialect({
  *   pool: createPool({
@@ -23,7 +23,7 @@ import { MysqlAdapter } from './mysql-adapter.js';
  * can be a function:
  *
  * ```ts
- * import { createPool } from 'mysql2'
+ * import { createPool } from 'mysql2/promise' // or just 'mysql2' — both work
  *
  * new MysqlDialect({
  *   pool: async () => createPool({

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

@@ -13,9 +13,12 @@ export class MysqlDriver {
         this.#config = freeze({ ...config });
     }
     async init(options) {
-        this.#pool = isFunction(this.#config.pool)
+        const pool = isFunction(this.#config.pool)
             ? await this.#config.pool(options)
             : this.#config.pool;
+        // A `mysql2/promise` pool's `getConnection` ignores the callback we pass
+        // it, hanging any query forever. Unwrap the callback pool it decorates.
+        this.#pool = isPromisePool(pool) ? pool.pool : pool;
     }
     async acquireConnection(options) {
         const rawConnection = await this.#acquireConnection();
@@ -93,6 +96,12 @@ export class MysqlDriver {
         });
     }
 }
+function isPromisePool(pool) {
+    return ('pool' in pool && isObject(pool.pool) && isFunction(pool.pool.getConnection));
+}
+function isPromiseConnection(connection) {
+    return isFunction(connection.then);
+}
 function isOkPacket(obj) {
     return isObject(obj) && 'insertId' in obj && 'affectedRows' in obj;
 }
@@ -224,7 +233,24 @@ class MysqlConnection {
         const { 
         // omitting these as they cause a warning and perhaps a future error when passed.
         clientFlags: _, maxPacketSize: __, ...cfg } = config;
-        const controlConnection = this.#controlConnection(cfg);
+        const controlConnectionOrPromise = this.#controlConnection(cfg);
+        // `mysql2/promise`'s `createConnection` returns a promise of a connection
+        // that's already connected, with a promise-based API. Use it directly.
+        if (isPromiseConnection(controlConnectionOrPromise)) {
+            const controlConnection = await controlConnectionOrPromise;
+            try {
+                // by the time we get the connection, another query might have been executed.
+                // we need to ensure we're not canceling the wrong query.
+                if (queryIdToCancel.queryId === this.#queryId?.queryId) {
+                    await controlConnection.query(query, []);
+                }
+            }
+            finally {
+                controlConnection.destroy();
+            }
+            return;
+        }
+        const controlConnection = controlConnectionOrPromise;
         try {
             await new Promise((resolve, reject) => {
                 controlConnection.connect((connectError) => {

package/dist/migration/file-migration-provider.d.ts

@@ -6,7 +6,7 @@ import type { MigrationProvider } from './migrator.js';
  * ### Examples
  *
  * ```ts
- * import { promises as fs } from 'node:fs'
+ * import fs from 'node:fs/promises'
  * import path from 'node:path'
  *
  * new FileMigrationProvider({

package/dist/migration/file-migration-provider.js

@@ -6,7 +6,7 @@ import { isFunction, isObject } from '../util/object-utils.js';
  * ### Examples
  *
  * ```ts
- * import { promises as fs } from 'node:fs'
+ * import fs from 'node:fs/promises'
  * import path from 'node:path'
  *
  * new FileMigrationProvider({

package/dist/migration/migrator.d.ts

@@ -16,7 +16,7 @@ export declare const NO_MIGRATIONS: NoMigrations;
  * other way.
  *
  * ```ts
- * import { promises as fs } from 'node:fs'
+ * import fs from 'node:fs/promises'
  * import path from 'node:path'
  * import * as Sqlite from 'better-sqlite3'
  * import { Kysely, SqliteDialect } from 'kysely'
@@ -64,7 +64,7 @@ export declare class Migrator {
      * ### Examples
      *
      * ```ts
-     * import { promises as fs } from 'node:fs'
+     * import fs from 'node:fs/promises'
      * import path from 'node:path'
      * import * as Sqlite from 'better-sqlite3'
      * import { FileMigrationProvider, Migrator } from 'kysely/migration'
@@ -106,7 +106,7 @@ export declare class Migrator {
      * ### Examples
      *
      * ```ts
-     * import { promises as fs } from 'node:fs'
+     * import fs from 'node:fs/promises'
      * import path from 'node:path'
      * import { FileMigrationProvider, Migrator } from 'kysely/migration'
      *
@@ -129,7 +129,7 @@ export declare class Migrator {
      * you can use a special constant `NO_MIGRATIONS`:
      *
      * ```ts
-     * import { promises as fs } from 'node:fs'
+     * import fs from 'node:fs/promises'
      * import path from 'node:path'
      * import { FileMigrationProvider, Migrator, NO_MIGRATIONS } from 'kysely/migration'
      *
@@ -145,8 +145,33 @@ export declare class Migrator {
      *
      * await migrator.migrateTo(NO_MIGRATIONS)
      * ```
+     *
+     * By default, this method migrates up or down depending on which side of the
+     * current migration state the target migration is on. Pass
+     * {@link MigrateToOptions.direction} to enforce a direction — if reaching the
+     * target would require migrating the other way, nothing is executed and
+     * {@link MigrationResultSet.error} holds an error:
+     *
+     * ```ts
+     * import fs from 'node:fs/promises'
+     * import path from 'node:path'
+     * import { FileMigrationProvider, Migrator } from 'kysely/migration'
+     *
+     * const migrator = new Migrator({
+     *   db,
+     *   provider: new FileMigrationProvider({
+     *     fs,
+     *     // Path to the folder that contains all your migrations.
+     *     migrationFolder: 'some/path/to/migrations',
+     *     path,
+     *   })
+     * })
+     *
+     * // Errors if `some_migration` is already executed.
+     * await migrator.migrateTo('some_migration', { direction: 'Up' })
+     * ```
      */
-    migrateTo(targetMigrationName: string | NoMigrations, options?: MigrateOptions): Promise<MigrationResultSet>;
+    migrateTo(targetMigrationName: string | NoMigrations, options?: MigrateToOptions): Promise<MigrationResultSet>;
     /**
      * Migrate one step up.
      *
@@ -158,7 +183,7 @@ export declare class Migrator {
      * ### Examples
      *
      * ```ts
-     * import { promises as fs } from 'node:fs'
+     * import fs from 'node:fs/promises'
      * import path from 'node:path'
      * import { FileMigrationProvider, Migrator } from 'kysely/migration'
      *
@@ -187,7 +212,7 @@ export declare class Migrator {
      * ### Examples
      *
      * ```ts
-     * import { promises as fs } from 'node:fs'
+     * import fs from 'node:fs/promises'
      * import path from 'node:path'
      * import { FileMigrationProvider, Migrator } from 'kysely/migration'
      *
@@ -257,6 +282,21 @@ export interface MigrateOptions {
     readonly transactionMode?: MigratorTransactionMode;
 }
 export type MigratorTransactionMode = 'per-run' | 'per-migration' | 'none';
+export interface MigrateToOptions extends MigrateOptions {
+    /**
+     * Enforces a migration direction.
+     *
+     * When provided and reaching the target migration would require migrating
+     * the other way, nothing is executed and {@link MigrationResultSet.error}
+     * holds an error. For example, `direction: 'Up'` errors when the target
+     * migration is already executed.
+     *
+     * By default, {@link Migrator.migrateTo | migrateTo} migrates up or down
+     * depending on which side of the current migration state the target
+     * migration is on.
+     */
+    readonly direction?: MigrationDirection;
+}
 export interface MigratorProps extends MigrateOptions {
     readonly db: Kysely<any>;
     readonly provider: MigrationProvider;
@@ -359,7 +399,7 @@ export interface MigrationResultSet {
      */
     readonly results?: MigrationResult[];
 }
-type MigrationDirection = 'Up' | 'Down';
+export type MigrationDirection = 'Up' | 'Down';
 export interface MigrationResult {
     readonly migrationName: string;
     /**
@@ -422,4 +462,3 @@ export interface MigrationInfo {
      */
     executedAt?: Date;
 }
-export {};

package/dist/migration/migrator.js

@@ -19,7 +19,7 @@ export const NO_MIGRATIONS = freeze({ __noMigrations__: true });
  * other way.
  *
  * ```ts
- * import { promises as fs } from 'node:fs'
+ * import fs from 'node:fs/promises'
  * import path from 'node:path'
  * import * as Sqlite from 'better-sqlite3'
  * import { Kysely, SqliteDialect } from 'kysely'
@@ -88,7 +88,7 @@ export class Migrator {
      * ### Examples
      *
      * ```ts
-     * import { promises as fs } from 'node:fs'
+     * import fs from 'node:fs/promises'
      * import path from 'node:path'
      * import * as Sqlite from 'better-sqlite3'
      * import { FileMigrationProvider, Migrator } from 'kysely/migration'
@@ -132,7 +132,7 @@ export class Migrator {
      * ### Examples
      *
      * ```ts
-     * import { promises as fs } from 'node:fs'
+     * import fs from 'node:fs/promises'
      * import path from 'node:path'
      * import { FileMigrationProvider, Migrator } from 'kysely/migration'
      *
@@ -155,7 +155,7 @@ export class Migrator {
      * you can use a special constant `NO_MIGRATIONS`:
      *
      * ```ts
-     * import { promises as fs } from 'node:fs'
+     * import fs from 'node:fs/promises'
      * import path from 'node:path'
      * import { FileMigrationProvider, Migrator, NO_MIGRATIONS } from 'kysely/migration'
      *
@@ -171,11 +171,39 @@ export class Migrator {
      *
      * await migrator.migrateTo(NO_MIGRATIONS)
      * ```
+     *
+     * By default, this method migrates up or down depending on which side of the
+     * current migration state the target migration is on. Pass
+     * {@link MigrateToOptions.direction} to enforce a direction — if reaching the
+     * target would require migrating the other way, nothing is executed and
+     * {@link MigrationResultSet.error} holds an error:
+     *
+     * ```ts
+     * import fs from 'node:fs/promises'
+     * import path from 'node:path'
+     * import { FileMigrationProvider, Migrator } from 'kysely/migration'
+     *
+     * const migrator = new Migrator({
+     *   db,
+     *   provider: new FileMigrationProvider({
+     *     fs,
+     *     // Path to the folder that contains all your migrations.
+     *     migrationFolder: 'some/path/to/migrations',
+     *     path,
+     *   })
+     * })
+     *
+     * // Errors if `some_migration` is already executed.
+     * await migrator.migrateTo('some_migration', { direction: 'Up' })
+     * ```
      */
     async migrateTo(targetMigrationName, options) {
         return this.#migrate(({ migrations, executedMigrations, pendingMigrations, }) => {
             if (isObject(targetMigrationName) &&
                 targetMigrationName.__noMigrations__ === true) {
+                if (options?.direction === 'Up') {
+                    throw new Error(`can't migrate up to NO_MIGRATIONS`);
+                }
                 return { direction: 'Down', step: Infinity };
             }
             if (!migrations.find((m) => m.name === targetMigrationName)) {
@@ -184,12 +212,18 @@ export class Migrator {
             const executedIndex = executedMigrations.indexOf(targetMigrationName);
             const pendingIndex = pendingMigrations.findIndex((m) => m.name === targetMigrationName);
             if (executedIndex !== -1) {
+                if (options?.direction === 'Up') {
+                    throw new Error(`migration "${targetMigrationName}" is already executed; can't migrate up to it`);
+                }
                 return {
                     direction: 'Down',
                     step: executedMigrations.length - executedIndex - 1,
                 };
             }
             if (pendingIndex !== -1) {
+                if (options?.direction === 'Down') {
+                    throw new Error(`migration "${targetMigrationName}" isn't executed; can't migrate down to it`);
+                }
                 return { direction: 'Up', step: pendingIndex + 1 };
             }
             throw new Error(`migration "${targetMigrationName}" isn't executed or pending`);
@@ -206,7 +240,7 @@ export class Migrator {
      * ### Examples
      *
      * ```ts
-     * import { promises as fs } from 'node:fs'
+     * import fs from 'node:fs/promises'
      * import path from 'node:path'
      * import { FileMigrationProvider, Migrator } from 'kysely/migration'
      *
@@ -237,7 +271,7 @@ export class Migrator {
      * ### Examples
      *
      * ```ts
-     * import { promises as fs } from 'node:fs'
+     * import fs from 'node:fs/promises'
      * import path from 'node:path'
      * import { FileMigrationProvider, Migrator } from 'kysely/migration'
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kysely",
-  "version": "0.30.0-beta.0",
+  "version": "0.30.0-beta.1",
   "description": "Type safe SQL query builder",
   "repository": {
     "type": "git",