kysely 0.12.2 → 0.15.0

package/dist/cjs/kysely.js

@@ -4,9 +4,7 @@ exports.TransactionBuilder = exports.ConnectionBuilder = exports.isKyselyProps =
 const schema_js_1 = require("./schema/schema.js");
 const dynamic_js_1 = require("./dynamic/dynamic.js");
 const default_connection_provider_js_1 = require("./driver/default-connection-provider.js");
-const migration_js_1 = require("./migration/migration.js");
 const query_creator_js_1 = require("./query-creator.js");
-const generated_placeholder_js_1 = require("./util/generated-placeholder.js");
 const default_query_executor_js_1 = require("./query-executor/default-query-executor.js");
 const object_utils_js_1 = require("./util/object-utils.js");
 const runtime_driver_js_1 = require("./driver/runtime-driver.js");
@@ -16,6 +14,7 @@ const prevent_await_js_1 = require("./util/prevent-await.js");
 const parse_context_js_1 = require("./parser/parse-context.js");
 const function_builder_js_1 = require("./query-builder/function-builder.js");
 const log_js_1 = require("./util/log.js");
+const private_symbols_js_1 = require("./util/private-symbols.js");
 /**
  * The main Kysely class.
  *
@@ -90,12 +89,6 @@ class Kysely extends query_creator_js_1.QueryCreator {
     get schema() {
         return new schema_js_1.SchemaModule(this.#props.executor);
     }
-    /**
-     * Returns the {@link MigrationModule} module for managing and running migrations.
-     */
-    get migration() {
-        return new migration_js_1.MigrationModule(this, this.#props.parseContext.adapter);
-    }
     /**
      * Returns a the {@link DynamicModule} module.
      *
@@ -111,33 +104,6 @@ class Kysely extends query_creator_js_1.QueryCreator {
     get introspection() {
         return this.#props.dialect.createIntrospector(this.withoutPlugins());
     }
-    /**
-     * A value to be used in place of columns that are generated in the database
-     * when inserting rows.
-     *
-     * ### 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`
-     * the `values` method requires you to give a value for them. the `generated`
-     * placeholder can be used in these cases.
-     *
-     * ```ts
-     * await db.insertInto('person')
-     *   .values({
-     *     id: db.generated,
-     *     created_at: db.generated,
-     *     first_name: 'Jennifer',
-     *     last_name: 'Aniston',
-     *     gender: 'female'
-     *   })
-     *   .execute()
-     * ```
-     */
-    get generated() {
-        return generated_placeholder_js_1.GENERATED_PLACEHOLDER;
-    }
     /**
      * Returns a {@link FunctionBuilder} that can be used to write type safe function
      * calls.
@@ -189,7 +155,6 @@ class Kysely extends query_creator_js_1.QueryCreator {
      * const catto = await db.transaction().execute(async (trx) => {
      *   const jennifer = await trx.insertInto('person')
      *     .values({
-     *       id: db.generated,
      *       first_name: 'Jennifer',
      *       last_name: 'Aniston',
      *     })
@@ -200,7 +165,6 @@ class Kysely extends query_creator_js_1.QueryCreator {
      *
      *   return await trx.insertInto('pet')
      *     .values({
-     *       id: db.generated,
      *       user_id: jennifer.id,
      *       name: 'Catto',
      *       species: 'cat'
@@ -311,6 +275,13 @@ class Kysely extends query_creator_js_1.QueryCreator {
     get isTransaction() {
         return false;
     }
+    /**
+     * @internal
+     * @private
+     */
+    get [private_symbols_js_1.PRIVATE_ADAPTER]() {
+        return this.#props.parseContext.adapter;
+    }
 }
 exports.Kysely = Kysely;
 class Transaction extends Kysely {
@@ -325,9 +296,6 @@ class Transaction extends Kysely {
     get isTransaction() {
         return true;
     }
-    get migration() {
-        throw new Error('the migration module is not available for a transaction. Use the main Kysely instance to run migrations');
-    }
     transaction() {
         throw new Error('calling the transaction method for a Transaction is not supported');
     }

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

@@ -0,0 +1,52 @@
+import { Migration, MigrationProvider } from './migrator.js';
+/**
+ * A function that takes a folder path and returns names of the
+ * files insider that folder.
+ */
+export declare type ReadDir = (migrationFolderPath: string) => Promise<string[]>;
+/**
+ * A function that combines two file path parts into a single file path.
+ *
+ * ```ts
+ * joinPath('/some/path', 'file.ts')
+ * // ==> '/some/path/file.ts'
+ * ```
+ */
+export declare type JoinPath = (part1: string, part2: string) => string;
+/**
+ * Reads all migrations from a folder.
+ *
+ * You need to provide a function for reading files in a folder and a function for
+ * joining file paths together. The API is like this to make Kysely independent of
+ * node.js or any other environment. See the example usage on node.js below.
+ *
+ * ### Examples
+ *
+ * ```ts
+ * import * as path from 'path'
+ * import * as fs from 'fs/promises'
+ *
+ * new FileMigrationProvider(
+ *   fs.readdir,
+ *   path.join,
+ *   path.join(__dirname, 'migrations')
+ * )
+ * ```
+ */
+export declare class FileMigrationProvider implements MigrationProvider {
+    #private;
+    constructor(readDir: ReadDir, joinPath: JoinPath, migrationFolderPath: string);
+    /**
+     * Returns all migrations, old and new.
+     *
+     * For example if you have your migrations in a folder as separate files,
+     * you can use the {@link FileMigrationProvider} that implements this
+     * method to return all migrations in a folder.
+     *
+     * The keys of the returned object are migration names and values are the
+     * migrations. The order of the migrations is determined by the alphabetical
+     * order of the migration names. The items in the object don't need to be
+     * sorted, they are sorted by Kysely.
+     */
+    getMigrations(): Promise<Record<string, Migration>>;
+}

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

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileMigrationProvider = void 0;
+const object_utils_js_1 = require("../util/object-utils.js");
+/**
+ * Reads all migrations from a folder.
+ *
+ * You need to provide a function for reading files in a folder and a function for
+ * joining file paths together. The API is like this to make Kysely independent of
+ * node.js or any other environment. See the example usage on node.js below.
+ *
+ * ### Examples
+ *
+ * ```ts
+ * import * as path from 'path'
+ * import * as fs from 'fs/promises'
+ *
+ * new FileMigrationProvider(
+ *   fs.readdir,
+ *   path.join,
+ *   path.join(__dirname, 'migrations')
+ * )
+ * ```
+ */
+class FileMigrationProvider {
+    #readDir;
+    #joinPath;
+    #migrationFolderPath;
+    constructor(readDir, joinPath, migrationFolderPath) {
+        this.#readDir = readDir;
+        this.#joinPath = joinPath;
+        this.#migrationFolderPath = migrationFolderPath;
+    }
+    async getMigrations() {
+        const migrations = {};
+        const files = await this.#readDir(this.#migrationFolderPath);
+        for (const fileName of files) {
+            if ((fileName.endsWith('.js') || fileName.endsWith('.ts')) &&
+                !fileName.endsWith('.d.ts')) {
+                const migration = await Promise.resolve().then(() => require(this.#joinPath(this.#migrationFolderPath, fileName)));
+                if (isMigration(migration)) {
+                    migrations[fileName.substring(0, fileName.length - 3)] = migration;
+                }
+            }
+        }
+        return migrations;
+    }
+}
+exports.FileMigrationProvider = FileMigrationProvider;
+function isMigration(obj) {
+    return (0, object_utils_js_1.isObject)(obj) && (0, object_utils_js_1.isFunction)(obj.up);
+}

package/dist/cjs/migration/migrator.d.ts

@@ -0,0 +1,234 @@
+import { Kysely } from '../kysely.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 interface Migration {
+    up(db: Kysely<any>): Promise<void>;
+    /**
+     * An optional down method.
+     *
+     * If you don't provide a down method, the migration is skipped when
+     * migrating down.
+     */
+    down?(db: Kysely<any>): Promise<void>;
+}
+/**
+ * A class for running migrations.
+ *
+ * ### Example
+ *
+ * This example uses the {@link FileMigrationProvider} that reads migrations
+ * files from a single folder. You can easily implement your own
+ * {@link MigrationProvider} if you want to provide migrations some
+ * other way.
+ *
+ * ```ts
+ * const migrator = new Migrator({
+ *   db,
+ *   // The constructor signature of FileMigrationProvider is a
+ *   // bit weird to keep Kysely independent of node.js or any
+ *   // other environment.
+ *   provider: new FileMigrationProvider(
+ *     fs.readdir,
+ *     path.join,
+ *     // Path to the folder that contains all your migrations.
+ *     'migrations'
+ *   )
+ * })
+ * ```
+ */
+export declare class Migrator {
+    #private;
+    constructor(props: MigratorProps);
+    /**
+     * Runs all migrations that have not yet been run.
+     *
+     * 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 provided by the provider and runs the
+     * ones whose names come alphabetically after the last migration that has been run. If the
+     * list of executed migrations doesn't match the beginning of the list of possible migrations
+     * an error is thrown.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * import * as path from 'path'
+     * import * as fs from 'fs/promises'
+     *
+     * const db = new Kysely<Database>({
+     *   dialect: new PostgresDialect({
+     *     host: 'localhost',
+     *     database: 'kysely_test',
+     *   }),
+     * })
+     *
+     * const migrator = new Migrator({
+     *   db,
+     *   // The constructor signature of FileMigrationProvider is a
+     *   // bit weird to keep Kysely independent of node.js or any
+     *   // other environment.
+     *   provider: new FileMigrationProvider(
+     *     fs.readdir,
+     *     path.join,
+     *     // Path to the folder that contains all your migrations.
+     *     'migrations'
+     *   )
+     * })
+     *
+     * const { error, results } = await migrator.migrateToLatest()
+     *
+     * 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)
+     * }
+     * ```
+     */
+    migrateToLatest(): Promise<MigrationResultSet>;
+    /**
+     * Migrate up/down to a specific migration.
+     *
+     * 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.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await migrator.migrateTo('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` method of
+     * the first migration. In case you want to migrate all the way down,
+     * you can use a special constant `NO_MIGRATIONS`:
+     *
+     * ```ts
+     * await migrator.migrateTo(NO_MIGRATIONS)
+     * ```
+     */
+    migrateTo(targetMigrationName: string | NoMigrations): Promise<MigrationResultSet>;
+    /**
+     * Migrate one step up.
+     *
+     * 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.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await migrator.migrateUp()
+     * ```
+     */
+    migrateUp(): Promise<MigrationResultSet>;
+    /**
+     * Migrate one step down.
+     *
+     * 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.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await migrator.migrateDown()
+     * ```
+     */
+    migrateDown(): Promise<MigrationResultSet>;
+}
+export interface MigratorProps {
+    readonly db: Kysely<any>;
+    readonly provider: MigrationProvider;
+}
+/**
+ * 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 interface MigrationProvider {
+    /**
+     * Returns all migrations, old and new.
+     *
+     * For example if you have your migrations in a folder as separate files,
+     * you can use the {@link FileMigrationProvider} that implements this
+     * method to return all migrations in a folder.
+     *
+     * The keys of the returned object are migration names and values are the
+     * migrations. The order of the migrations is determined by the alphabetical
+     * order of the migration names. The items in the object don't need to be
+     * sorted, they are sorted by Kysely.
+     */
+    getMigrations(): Promise<Record<string, Migration>>;
+}
+/**
+ * Type for the {@link NO_MIGRATIONS} constant. Never create one of these.
+ */
+export interface NoMigrations {
+    readonly __noMigrations__: true;
+}