kysely 0.14.1 → 0.15.0

package/README.md

@@ -4,8 +4,7 @@
 # [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/). [Here's](https://www.jakso.me/blog/kysely-a-type-safe-sql-query-builder-for-typescript)
-an introductory blog post for you.
+[knex](http://knexjs.org/).
 
 ![](https://github.com/koskimas/kysely/blob/master/assets/demo.gif)
 
@@ -29,6 +28,9 @@ Kysely is still young and some useful features are propably not yet implemented.
 using Kysely and can't find something you'd want to use, please open an issue or join our
 [discord server](https://discord.gg/C9aJ49mCra).
 
+[Here's](https://www.jakso.me/blog/kysely-a-type-safe-sql-query-builder-for-typescript)
+an introductory blog post.
+
 # Table of contents
 
 - [Installation](#installation)
@@ -36,6 +38,7 @@ using Kysely and can't find something you'd want to use, please open an issue or
 - [Query examples](#query-examples)
 - [Migrations](#migrations)
 - [API reference](https://koskimas.github.io/kysely/index.html)
+- [Changelog](https://github.com/koskimas/kysely/releases)
 
 # Installation
 
@@ -65,34 +68,55 @@ All you need to do is define an interface for each table in the database and pas
 interfaces to the `Kysely` constructor:
 
 ```ts
-import { Kysely, PostgresDialect } from 'kysely'
+import {
+  Kysely,
+  PostgresDialect,
+  Generated,
+  ColumnType,
+  Selectable,
+  Insertable,
+  Updateable,
+} from 'kysely'
+
+interface PersonTable {
+  // Columns that are generated by the database should be marked
+  // using the `Generated` type. This way they are automatically
+  // made optional in inserts.
+  id: Generated<number>
 
-interface Person {
-  id: number
   first_name: string
-  // If the column is nullable in the db, make its type nullable.
-  // Don't use optional properties.
-  last_name: string | null
   gender: 'male' | 'female' | 'other'
+
+  // If the column is nullable in the database, make its type nullable.
+  // Don't use optional properties. Optionality is always determined
+  // automatically by Kysely.
+  last_name: string | null
+
+  // You can specity a type for each operation (select, insert and update)
+  // using the `ColumnType<SelectType, InsertType, UpdateType>` wrapper.
+  // Here we define a column `modified_at` that is selected as a `Date`,
+  // can optionally be provided as a `string` in inserts and can never
+  // be updated:
+  modified_at: ColumnType<Date, string | undefined, never>
 }
 
-interface Pet {
-  id: number
+interface PetTable {
+  id: Generated<number>
   name: string
   owner_id: number
   species: 'dog' | 'cat'
 }
 
-interface Movie {
-  id: string
+interface MovieTable {
+  id: Generated<string>
   stars: number
 }
 
 // Keys of this interface are table names.
 interface Database {
-  person: Person
-  pet: Pet
-  movie: Movie
+  person: PersonTable
+  pet: PetTable
+  movie: MovieTable
 }
 
 // You'd create one of these when you start your app.
@@ -101,15 +125,26 @@ const db = new Kysely<Database>({
   dialect: new PostgresDialect({
     host: 'localhost',
     database: 'kysely_test',
-  })
+  }),
 })
 
 async function demo() {
+  const { id } = await db
+    .insertInto('person')
+    .values({ first_name: 'Jennifer', gender: 'female' })
+    .returning('id')
+    .executeTakeFirstOrThrow()
+
+  await db
+    .insertInto('pet')
+    .values({ name: 'Catto', species: 'cat', owner_id: id })
+    .execute()
+
   const person = await db
     .selectFrom('person')
     .innerJoin('pet', 'pet.owner_id', 'person.id')
     .select(['first_name', 'pet.name as pet_name'])
-    .where('person.id', '=', 1)
+    .where('person.id', '=', id)
     .executeTakeFirst()
 
   if (person) {
@@ -118,6 +153,14 @@ async function demo() {
 }
 ```
 
+```ts
+// You can extract the select, insert and update interfaces like this
+// if you want (you don't need to):
+type Person = Selectable<PersonTable>
+type InsertablePerson = Insertable<PersonTable>
+type UpdateablePerson = Updateable<PersonTable>
+```
+
 # Query examples
 
 ## Select queries
@@ -248,37 +291,54 @@ export async function down(db: Kysely<any>): Promise<void> {
 You can then use
 
 ```ts
-await db.migration.migrateToLatest(pathToMigrationsFolder)
+const migrator = new Migrator(migratorConfig);
+await migrator.migrateToLatest(pathToMigrationsFolder)
 ```
 
 to run all migrations that have not yet been run. The migrations are executed in alphabetical
-order by their name. See the [migration module](https://koskimas.github.io/kysely/classes/MigrationModule.html) 
+order by their name. See the [Migrator](https://koskimas.github.io/kysely/classes/Migrator.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
+typescript code into javascript. A CLI would cause confusion over which migrations are being
 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'
+import * as path from 'path'
+import * as fs from 'fs/promises'
 
-// 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'
+import {
+  Kysely,
+  Migrator,
+  PostgresDialect,
+  FileMigrationProvider
+} from 'kysely'
 
 async function migrateToLatest() {
-  const { error, results } = await db.migration.migrateToLatest(
-    path.join(__dirname, 'migrations')
-  )
+  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'
+    )
+  })
 
-  // Destroy the `Kysely` instance to make the script exit faster.
-  await db.destroy()
+  const { error, results } = await migrator.migrateToLatest()
 
   results?.forEach((it) => {
     if (it.status === 'Success') {

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

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MysqlIntrospector = void 0;
-const migration_js_1 = require("../../migration/migration.js");
+const migrator_js_1 = require("../../migration/migrator.js");
 const object_utils_js_1 = require("../../util/object-utils.js");
 class MysqlIntrospector {
     #db;
@@ -16,8 +16,8 @@ class MysqlIntrospector {
             .castTo();
         if (!options.withInternalKyselyTables) {
             query = query
-                .where('table_name', '!=', migration_js_1.MIGRATION_TABLE)
-                .where('table_name', '!=', migration_js_1.MIGRATION_LOCK_TABLE);
+                .where('table_name', '!=', migrator_js_1.MIGRATION_TABLE)
+                .where('table_name', '!=', migrator_js_1.MIGRATION_LOCK_TABLE);
         }
         const rawColumns = await query.execute();
         return {

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

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PostgresIntrospector = void 0;
-const migration_js_1 = require("../../migration/migration.js");
+const migrator_js_1 = require("../../migration/migrator.js");
 const object_utils_js_1 = require("../../util/object-utils.js");
 class PostgresIntrospector {
     #db;
@@ -28,8 +28,8 @@ class PostgresIntrospector {
             .castTo();
         if (!options.withInternalKyselyTables) {
             query = query
-                .where('t.tablename', '!=', migration_js_1.MIGRATION_TABLE)
-                .where('t.tablename', '!=', migration_js_1.MIGRATION_LOCK_TABLE);
+                .where('t.tablename', '!=', migrator_js_1.MIGRATION_TABLE)
+                .where('t.tablename', '!=', migrator_js_1.MIGRATION_LOCK_TABLE);
         }
         const rawColumns = await query.execute();
         return {

package/dist/cjs/dialect/sqlite/sqlite-introspector.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SqliteIntrospector = void 0;
-const migration_js_1 = require("../../migration/migration.js");
+const migrator_js_1 = require("../../migration/migrator.js");
 class SqliteIntrospector {
     #db;
     constructor(db) {
@@ -16,8 +16,8 @@ class SqliteIntrospector {
             .castTo();
         if (!options.withInternalKyselyTables) {
             query = query
-                .where('name', '!=', migration_js_1.MIGRATION_TABLE)
-                .where('name', '!=', migration_js_1.MIGRATION_LOCK_TABLE);
+                .where('name', '!=', migrator_js_1.MIGRATION_TABLE)
+                .where('name', '!=', migrator_js_1.MIGRATION_LOCK_TABLE);
         }
         const tables = await query.execute();
         return {

package/dist/cjs/index.d.ts

@@ -57,7 +57,8 @@ export * from './dialect/sqlite/sqlite-introspector.js';
 export * from './dialect/sqlite/sqlite-adapter.js';
 export * from './query-compiler/default-query-compiler.js';
 export * from './query-compiler/query-compiler.js';
-export * from './migration/migration.js';
+export * from './migration/migrator.js';
+export * from './migration/file-migration-provider.js';
 export * from './dialect/dialect.js';
 export * from './dialect/dialect-adapter.js';
 export * from './dialect/dialect-adapter-base.js';
@@ -138,6 +139,7 @@ export * from './operation-node/values-node.js';
 export * from './operation-node/where-node.js';
 export * from './operation-node/with-node.js';
 export * from './dialect/database-introspector.js';
+export * from './util/column-type.js';
 export * from './util/compilable.js';
 export * from './util/log.js';
 export { AnyColumn, UnknownRow, AnySelectQueryBuilder, } from './util/type-utils.js';

package/dist/cjs/index.js

@@ -69,7 +69,8 @@ __exportStar(require("./dialect/sqlite/sqlite-introspector.js"), exports);
 __exportStar(require("./dialect/sqlite/sqlite-adapter.js"), exports);
 __exportStar(require("./query-compiler/default-query-compiler.js"), exports);
 __exportStar(require("./query-compiler/query-compiler.js"), exports);
-__exportStar(require("./migration/migration.js"), exports);
+__exportStar(require("./migration/migrator.js"), exports);
+__exportStar(require("./migration/file-migration-provider.js"), exports);
 __exportStar(require("./dialect/dialect.js"), exports);
 __exportStar(require("./dialect/dialect-adapter.js"), exports);
 __exportStar(require("./dialect/dialect-adapter-base.js"), exports);
@@ -150,5 +151,6 @@ __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("./dialect/database-introspector.js"), exports);
+__exportStar(require("./util/column-type.js"), exports);
 __exportStar(require("./util/compilable.js"), exports);
 __exportStar(require("./util/log.js"), exports);

package/dist/cjs/kysely.d.ts

@@ -1,16 +1,16 @@
 import { Dialect } from './dialect/dialect.js';
 import { SchemaModule } from './schema/schema.js';
 import { DynamicModule } from './dynamic/dynamic.js';
-import { MigrationModule } from './migration/migration.js';
 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 './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';
 import { LogConfig } from './util/log.js';
+import { PRIVATE_ADAPTER } from './util/private-symbols.js';
+import { DialectAdapter } from './dialect/dialect-adapter.js';
 /**
  * The main Kysely class.
  *
@@ -60,10 +60,6 @@ export declare class Kysely<DB> extends QueryCreator<DB> {
      * Returns the {@link SchemaModule} module for building database schema.
      */
     get schema(): SchemaModule;
-    /**
-     * Returns the {@link MigrationModule} module for managing and running migrations.
-     */
-    get migration(): MigrationModule;
     /**
      * Returns a the {@link DynamicModule} module.
      *
@@ -75,31 +71,6 @@ export declare class Kysely<DB> extends QueryCreator<DB> {
      * Returns a {@link DatabaseIntrospector | database introspector}.
      */
     get introspection(): DatabaseIntrospector;
-    /**
-     * 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(): GeneratedPlaceholder;
     /**
      * Returns a {@link FunctionBuilder} that can be used to write type safe function
      * calls.
@@ -149,7 +120,6 @@ export declare class Kysely<DB> extends QueryCreator<DB> {
      * const catto = await db.transaction().execute(async (trx) => {
      *   const jennifer = await trx.insertInto('person')
      *     .values({
-     *       id: db.generated,
      *       first_name: 'Jennifer',
      *       last_name: 'Aniston',
      *     })
@@ -160,7 +130,6 @@ export declare class Kysely<DB> extends QueryCreator<DB> {
      *
      *   return await trx.insertInto('pet')
      *     .values({
-     *       id: db.generated,
      *       user_id: jennifer.id,
      *       name: 'Catto',
      *       species: 'cat'
@@ -251,6 +220,11 @@ export declare class Kysely<DB> extends QueryCreator<DB> {
      * You can also use `db instanceof Transaction`.
      */
     get isTransaction(): boolean;
+    /**
+     * @internal
+     * @private
+     */
+    get [PRIVATE_ADAPTER](): DialectAdapter;
 }
 export declare class Transaction<DB> extends Kysely<DB> {
     #private;
@@ -261,10 +235,6 @@ export declare class Transaction<DB> extends Kysely<DB> {
      * 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.
      *
@@ -285,7 +255,6 @@ export declare class Transaction<DB> extends Kysely<DB> {
      * const catto = await db.transaction().execute(async (trx) => {
      *   const jennifer = await trx.insertInto('person')
      *     .values({
-     *       id: db.generated,
      *       first_name: 'Jennifer',
      *       last_name: 'Aniston',
      *     })
@@ -296,7 +265,6 @@ export declare class Transaction<DB> extends Kysely<DB> {
      *
      *   return await trx.insertInto('pet')
      *     .values({
-     *       id: db.generated,
      *       user_id: jennifer.id,
      *       name: 'Catto',
      *       species: 'cat'

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