kysely 0.27.4 → 0.27.6

package/dist/esm/kysely.d.ts

@@ -24,33 +24,23 @@ import { DrainOuterGeneric } from './util/type-utils.js';
  *
  * ### Examples
  *
- * This example assumes your database has tables `person` and `pet`:
+ * This example assumes your database has a "person" table:
  *
  * ```ts
- * import { Kysely, Generated, PostgresDialect } from 'kysely'
- *
- * interface PersonTable {
- *   id: Generated<number>
- *   first_name: string
- *   last_name: string
- * }
- *
- * interface PetTable {
- *   id: Generated<number>
- *   owner_id: number
- *   name: string
- *   species: 'cat' | 'dog'
- * }
+ * import * as Sqlite from 'better-sqlite3'
+ * import { type Generated, Kysely, SqliteDialect } from 'kysely'
  *
  * interface Database {
- *   person: PersonTable,
- *   pet: PetTable
+ *   person: {
+ *     id: Generated<number>
+ *     first_name: string
+ *     last_name: string | null
+ *   }
  * }
  *
  * const db = new Kysely<Database>({
- *   dialect: new PostgresDialect({
- *     host: 'localhost',
- *     database: 'kysely_test',
+ *   dialect: new SqliteDialect({
+ *     database: new Sqlite(':memory:'),
  *   })
  * })
  * ```
@@ -86,30 +76,52 @@ export declare class Kysely<DB> extends QueryCreator<DB> implements QueryExecuto
     case(): CaseBuilder<DB, keyof DB>;
     case<V>(value: Expression<V>): CaseBuilder<DB, keyof DB, V>;
     /**
-     * Returns a {@link FunctionModule} that can be used to write type safe function
+     * Returns a {@link FunctionModule} that can be used to write somewhat type-safe function
      * calls.
      *
      * ```ts
+     * const { count } = db.fn
+     *
      * await db.selectFrom('person')
      *   .innerJoin('pet', 'pet.owner_id', 'person.id')
-     *   .select((eb) => [
-     *     'person.id',
-     *     eb.fn.count('pet.id').as('pet_count')
+     *   .select([
+     *     'id',
+     *     count('pet.id').as('person_count'),
      *   ])
      *   .groupBy('person.id')
-     *   .having((eb) => eb.fn.count('pet.id'), '>', 10)
+     *   .having(count('pet.id'), '>', 10)
      *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * select "person"."id", count("pet"."id") as "pet_count"
+     * select "person"."id", count("pet"."id") as "person_count"
      * from "person"
      * inner join "pet" on "pet"."owner_id" = "person"."id"
      * group by "person"."id"
      * having count("pet"."id") > $1
      * ```
+     *
+     * Why "somewhat" type-safe? Because the function calls are not bound to the
+     * current query context. They allow you to reference columns and tables that
+     * are not in the current query. E.g. remove the `innerJoin` from the previous
+     * query and TypeScript won't even complain.
+     *
+     * If you want to make the function calls fully type-safe, you can use the
+     * {@link ExpressionBuilder.fn} getter for a query context-aware, stricter {@link FunctionModule}.
+     *
+     * ```ts
+     * await db.selectFrom('person')
+     *   .innerJoin('pet', 'pet.owner_id', 'person.id')
+     *   .select((eb) => [
+     *     'person.id',
+     *     eb.fn.count('pet.id').as('pet_count')
+     *   ])
+     *   .groupBy('person.id')
+     *   .having((eb) => eb.fn.count('pet.id'), '>', 10)
+     *   .execute()
+     * ```
      */
     get fn(): FunctionModule<DB, keyof DB>;
     /**
@@ -118,8 +130,11 @@ export declare class Kysely<DB> extends QueryCreator<DB> implements QueryExecuto
      * 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.
+     * transaction. If the function throws an exception,
+     * 1. the exception is caught,
+     * 2. the transaction is rolled back, and
+     * 3. the exception is thrown again.
+     * 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
@@ -130,9 +145,12 @@ export declare class Kysely<DB> extends QueryCreator<DB> implements QueryExecuto
      *
      * <!-- siteExample("transactions", "Simple transaction", 10) -->
      *
-     * This example inserts two rows in a transaction. If an error is thrown inside
-     * the callback passed to the `execute` method, the transaction is rolled back.
-     * Otherwise it's committed.
+     * This example inserts two rows in a transaction. If an exception is thrown inside
+     * the callback passed to the `execute` method,
+     * 1. the exception is caught,
+     * 2. the transaction is rolled back, and
+     * 3. the exception is thrown again.
+     * Otherwise the transaction is committed.
      *
      * ```ts
      * const catto = await db.transaction().execute(async (trx) => {
@@ -160,12 +178,18 @@ export declare class Kysely<DB> extends QueryCreator<DB> implements QueryExecuto
      * Setting the isolation level:
      *
      * ```ts
+     * import type { Kysely } from 'kysely'
+     *
      * await db
      *   .transaction()
      *   .setIsolationLevel('serializable')
      *   .execute(async (trx) => {
      *     await doStuff(trx)
      *   })
+     *
+     * async function doStuff(kysely: typeof db) {
+     *   // ...
+     * }
      * ```
      */
     transaction(): TransactionBuilder<DB>;
@@ -183,6 +207,10 @@ export declare class Kysely<DB> extends QueryCreator<DB> implements QueryExecuto
      *     // the same connection.
      *     await doStuff(db)
      *   })
+     *
+     * async function doStuff(kysely: typeof db) {
+     *   // ...
+     * }
      * ```
      */
     connection(): ConnectionBuilder<DB>;
@@ -209,7 +237,6 @@ export declare class Kysely<DB> extends QueryCreator<DB> implements QueryExecuto
      *
      * The following example adds and uses a temporary table:
      *
-     * @example
      * ```ts
      * await db.schema
      *   .createTable('temp_table')
@@ -250,7 +277,7 @@ export declare class Kysely<DB> extends QueryCreator<DB> implements QueryExecuto
     /**
      * Executes a given compiled query or query builder.
      *
-     * See {@link https://github.com/koskimas/kysely/blob/master/site/docs/recipes/splitting-build-compile-and-execute-code.md#execute-compiled-queries splitting build, compile and execute code recipe} for more information.
+     * See {@link https://github.com/kysely-org/kysely/blob/master/site/docs/recipes/0004-splitting-query-building-and-execution.md#execute-compiled-queries splitting build, compile and execute code recipe} for more information.
      */
     executeQuery<R>(query: CompiledQuery<R> | Compilable<R>, queryId?: QueryId): Promise<QueryResult<R>>;
 }
@@ -269,8 +296,11 @@ export declare class Transaction<DB> extends Kysely<DB> {
      * 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.
+     * transaction. If the function throws an exception,
+     * 1. the exception is caught,
+     * 2. the transaction is rolled back, and
+     * 3. the exception is thrown again.
+     * 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
@@ -281,9 +311,12 @@ export declare class Transaction<DB> extends Kysely<DB> {
      *
      * <!-- siteExample("transactions", "Simple transaction", 10) -->
      *
-     * This example inserts two rows in a transaction. If an error is thrown inside
-     * the callback passed to the `execute` method, the transaction is rolled back.
-     * Otherwise it's committed.
+     * This example inserts two rows in a transaction. If an exception is thrown inside
+     * the callback passed to the `execute` method,
+     * 1. the exception is caught,
+     * 2. the transaction is rolled back, and
+     * 3. the exception is thrown again.
+     * Otherwise the transaction is committed.
      *
      * ```ts
      * const catto = await db.transaction().execute(async (trx) => {
@@ -311,12 +344,18 @@ export declare class Transaction<DB> extends Kysely<DB> {
      * Setting the isolation level:
      *
      * ```ts
+     * import type { Kysely } from 'kysely'
+     *
      * await db
      *   .transaction()
      *   .setIsolationLevel('serializable')
      *   .execute(async (trx) => {
      *     await doStuff(trx)
      *   })
+     *
+     * async function doStuff(kysely: typeof db) {
+     *   // ...
+     * }
      * ```
      */
     transaction(): TransactionBuilder<DB>;
@@ -334,6 +373,10 @@ export declare class Transaction<DB> extends Kysely<DB> {
      *     // the same connection.
      *     await doStuff(db)
      *   })
+     *
+     * async function doStuff(kysely: typeof db) {
+     *   // ...
+     * }
      * ```
      */
     connection(): ConnectionBuilder<DB>;
@@ -366,7 +409,6 @@ export declare class Transaction<DB> extends Kysely<DB> {
      *
      * The following example adds and uses a temporary table:
      *
-     * @example
      * ```ts
      * await db.schema
      *   .createTable('temp_table')
@@ -406,16 +448,32 @@ export interface KyselyConfig {
      *
      * ### Examples
      *
+     * Setting up built-in logging for preferred log levels:
+     *
      * ```ts
+     * import * as Sqlite from 'better-sqlite3'
+     * import { Kysely, SqliteDialect } from 'kysely'
+     * import type { Database } from 'type-editor' // imaginary module
+     *
      * const db = new Kysely<Database>({
-     *   dialect: new PostgresDialect(postgresConfig),
+     *   dialect: new SqliteDialect({
+     *     database: new Sqlite(':memory:'),
+     *   }),
      *   log: ['query', 'error']
      * })
      * ```
      *
+     * Setting up custom logging:
+     *
      * ```ts
+     * import * as Sqlite from 'better-sqlite3'
+     * import { Kysely, SqliteDialect } from 'kysely'
+     * import type { Database } from 'type-editor' // imaginary module
+     *
      * const db = new Kysely<Database>({
-     *   dialect: new PostgresDialect(postgresConfig),
+     *   dialect: new SqliteDialect({
+     *     database: new Sqlite(':memory:'),
+     *   }),
      *   log(event): void {
      *     if (event.level === 'query') {
      *       console.log(event.query.sql)

package/dist/esm/kysely.js

@@ -25,33 +25,23 @@ import { WithSchemaPlugin } from './plugin/with-schema/with-schema-plugin.js';
  *
  * ### Examples
  *
- * This example assumes your database has tables `person` and `pet`:
+ * This example assumes your database has a "person" table:
  *
  * ```ts
- * import { Kysely, Generated, PostgresDialect } from 'kysely'
- *
- * interface PersonTable {
- *   id: Generated<number>
- *   first_name: string
- *   last_name: string
- * }
- *
- * interface PetTable {
- *   id: Generated<number>
- *   owner_id: number
- *   name: string
- *   species: 'cat' | 'dog'
- * }
+ * import * as Sqlite from 'better-sqlite3'
+ * import { type Generated, Kysely, SqliteDialect } from 'kysely'
  *
  * interface Database {
- *   person: PersonTable,
- *   pet: PetTable
+ *   person: {
+ *     id: Generated<number>
+ *     first_name: string
+ *     last_name: string | null
+ *   }
  * }
  *
  * const db = new Kysely<Database>({
- *   dialect: new PostgresDialect({
- *     host: 'localhost',
- *     database: 'kysely_test',
+ *   dialect: new SqliteDialect({
+ *     database: new Sqlite(':memory:'),
  *   })
  * })
  * ```
@@ -116,30 +106,52 @@ export class Kysely extends QueryCreator {
         });
     }
     /**
-     * Returns a {@link FunctionModule} that can be used to write type safe function
+     * Returns a {@link FunctionModule} that can be used to write somewhat type-safe function
      * calls.
      *
      * ```ts
+     * const { count } = db.fn
+     *
      * await db.selectFrom('person')
      *   .innerJoin('pet', 'pet.owner_id', 'person.id')
-     *   .select((eb) => [
-     *     'person.id',
-     *     eb.fn.count('pet.id').as('pet_count')
+     *   .select([
+     *     'id',
+     *     count('pet.id').as('person_count'),
      *   ])
      *   .groupBy('person.id')
-     *   .having((eb) => eb.fn.count('pet.id'), '>', 10)
+     *   .having(count('pet.id'), '>', 10)
      *   .execute()
      * ```
      *
      * The generated SQL (PostgreSQL):
      *
      * ```sql
-     * select "person"."id", count("pet"."id") as "pet_count"
+     * select "person"."id", count("pet"."id") as "person_count"
      * from "person"
      * inner join "pet" on "pet"."owner_id" = "person"."id"
      * group by "person"."id"
      * having count("pet"."id") > $1
      * ```
+     *
+     * Why "somewhat" type-safe? Because the function calls are not bound to the
+     * current query context. They allow you to reference columns and tables that
+     * are not in the current query. E.g. remove the `innerJoin` from the previous
+     * query and TypeScript won't even complain.
+     *
+     * If you want to make the function calls fully type-safe, you can use the
+     * {@link ExpressionBuilder.fn} getter for a query context-aware, stricter {@link FunctionModule}.
+     *
+     * ```ts
+     * await db.selectFrom('person')
+     *   .innerJoin('pet', 'pet.owner_id', 'person.id')
+     *   .select((eb) => [
+     *     'person.id',
+     *     eb.fn.count('pet.id').as('pet_count')
+     *   ])
+     *   .groupBy('person.id')
+     *   .having((eb) => eb.fn.count('pet.id'), '>', 10)
+     *   .execute()
+     * ```
      */
     get fn() {
         return createFunctionModule();
@@ -150,8 +162,11 @@ export class Kysely extends QueryCreator {
      * 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.
+     * transaction. If the function throws an exception,
+     * 1. the exception is caught,
+     * 2. the transaction is rolled back, and
+     * 3. the exception is thrown again.
+     * 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
@@ -162,9 +177,12 @@ export class Kysely extends QueryCreator {
      *
      * <!-- siteExample("transactions", "Simple transaction", 10) -->
      *
-     * This example inserts two rows in a transaction. If an error is thrown inside
-     * the callback passed to the `execute` method, the transaction is rolled back.
-     * Otherwise it's committed.
+     * This example inserts two rows in a transaction. If an exception is thrown inside
+     * the callback passed to the `execute` method,
+     * 1. the exception is caught,
+     * 2. the transaction is rolled back, and
+     * 3. the exception is thrown again.
+     * Otherwise the transaction is committed.
      *
      * ```ts
      * const catto = await db.transaction().execute(async (trx) => {
@@ -192,12 +210,18 @@ export class Kysely extends QueryCreator {
      * Setting the isolation level:
      *
      * ```ts
+     * import type { Kysely } from 'kysely'
+     *
      * await db
      *   .transaction()
      *   .setIsolationLevel('serializable')
      *   .execute(async (trx) => {
      *     await doStuff(trx)
      *   })
+     *
+     * async function doStuff(kysely: typeof db) {
+     *   // ...
+     * }
      * ```
      */
     transaction() {
@@ -217,6 +241,10 @@ export class Kysely extends QueryCreator {
      *     // the same connection.
      *     await doStuff(db)
      *   })
+     *
+     * async function doStuff(kysely: typeof db) {
+     *   // ...
+     * }
      * ```
      */
     connection() {
@@ -260,7 +288,6 @@ export class Kysely extends QueryCreator {
      *
      * The following example adds and uses a temporary table:
      *
-     * @example
      * ```ts
      * await db.schema
      *   .createTable('temp_table')
@@ -309,7 +336,7 @@ export class Kysely extends QueryCreator {
     /**
      * Executes a given compiled query or query builder.
      *
-     * See {@link https://github.com/koskimas/kysely/blob/master/site/docs/recipes/splitting-build-compile-and-execute-code.md#execute-compiled-queries splitting build, compile and execute code recipe} for more information.
+     * See {@link https://github.com/kysely-org/kysely/blob/master/site/docs/recipes/0004-splitting-query-building-and-execution.md#execute-compiled-queries splitting build, compile and execute code recipe} for more information.
      */
     executeQuery(query, queryId = createQueryId()) {
         const compiledQuery = isCompilable(query) ? query.compile() : query;
@@ -349,9 +376,6 @@ export class Transaction extends Kysely {
             executor: this.#props.executor.withoutPlugins(),
         });
     }
-    /**
-     * @override
-     */
     withSchema(schema) {
         return new Transaction({
             ...this.#props,

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

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

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

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

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

@@ -25,16 +25,29 @@ export interface Migration {
  * other way.
  *
  * ```ts
- * import { promises as fs } from 'fs'
- * import path from 'path'
+ * import { promises as fs } from 'node:fs'
+ * import path from 'node:path'
+ * import * as Sqlite from 'better-sqlite3'
+ * import {
+ *   FileMigrationProvider,
+ *   Kysely,
+ *   Migrator,
+ *   SqliteDialect
+ * } from 'kysely'
+ *
+ * const db = new Kysely<any>({
+ *   dialect: new SqliteDialect({
+ *     database: Sqlite(':memory:')
+ *   })
+ * })
  *
  * const migrator = new Migrator({
  *   db,
  *   provider: new FileMigrationProvider({
  *     fs,
- *     path,
  *     // Path to the folder that contains all your migrations.
- *     migrationFolder: 'some/path/to/migrations'
+ *     migrationFolder: 'some/path/to/migrations',
+ *     path,
  *   })
  * })
  * ```
@@ -64,19 +77,18 @@ export declare class Migrator {
      * ### Examples
      *
      * ```ts
-     * const db = new Kysely<Database>({
-     *   dialect: new PostgresDialect({
-     *     host: 'localhost',
-     *     database: 'kysely_test',
-     *   }),
-     * })
+     * import { promises as fs } from 'node:fs'
+     * import path from 'node:path'
+     * import * as Sqlite from 'better-sqlite3'
+     * import { FileMigrationProvider, Migrator } from 'kysely'
      *
      * const migrator = new Migrator({
      *   db,
-     *   provider: new FileMigrationProvider(
-     *     // Path to the folder that contains all your migrations.
-     *     'some/path/to/migrations'
-     *   )
+     *   provider: new FileMigrationProvider({
+     *     fs,
+     *     migrationFolder: 'some/path/to/migrations',
+     *     path,
+     *   })
      * })
      *
      * const { error, results } = await migrator.migrateToLatest()
@@ -107,6 +119,20 @@ export declare class Migrator {
      * ### Examples
      *
      * ```ts
+     * import { promises as fs } from 'node:fs'
+     * import path from 'node:path'
+     * import { FileMigrationProvider, Migrator } from 'kysely'
+     *
+     * const migrator = new Migrator({
+     *   db,
+     *   provider: new FileMigrationProvider({
+     *     fs,
+     *     // Path to the folder that contains all your migrations.
+     *     migrationFolder: 'some/path/to/migrations',
+     *     path,
+     *   })
+     * })
+     *
      * await migrator.migrateTo('some_migration')
      * ```
      *
@@ -116,6 +142,20 @@ export declare class Migrator {
      * you can use a special constant `NO_MIGRATIONS`:
      *
      * ```ts
+     * import { promises as fs } from 'node:fs'
+     * import path from 'node:path'
+     * import { FileMigrationProvider, Migrator, NO_MIGRATIONS } from 'kysely'
+     *
+     * const migrator = new Migrator({
+     *   db,
+     *   provider: new FileMigrationProvider({
+     *     fs,
+     *     // Path to the folder that contains all your migrations.
+     *     migrationFolder: 'some/path/to/migrations',
+     *     path,
+     *   })
+     * })
+     *
      * await migrator.migrateTo(NO_MIGRATIONS)
      * ```
      */
@@ -131,6 +171,20 @@ export declare class Migrator {
      * ### Examples
      *
      * ```ts
+     * import { promises as fs } from 'node:fs'
+     * import path from 'node:path'
+     * import { FileMigrationProvider, Migrator } from 'kysely'
+     *
+     * const migrator = new Migrator({
+     *   db,
+     *   provider: new FileMigrationProvider({
+     *     fs,
+     *     // Path to the folder that contains all your migrations.
+     *     migrationFolder: 'some/path/to/migrations',
+     *     path,
+     *   })
+     * })
+     *
      * await migrator.migrateUp()
      * ```
      */
@@ -146,6 +200,20 @@ export declare class Migrator {
      * ### Examples
      *
      * ```ts
+     * import { promises as fs } from 'node:fs'
+     * import path from 'node:path'
+     * import { FileMigrationProvider, Migrator } from 'kysely'
+     *
+     * const migrator = new Migrator({
+     *   db,
+     *   provider: new FileMigrationProvider({
+     *     fs,
+     *     // Path to the folder that contains all your migrations.
+     *     migrationFolder: 'some/path/to/migrations',
+     *     path,
+     *   })
+     * })
+     *
      * await migrator.migrateDown()
      * ```
      */
@@ -203,7 +271,7 @@ export interface MigratorProps {
      *
      * When false, migrations must be run in their exact alpha-numeric order.
      * This is checked against the migrations already run in the database
-     * (`migrationTableName'). This ensures your migrations are always run in
+     * (`migrationTableName`). This ensures your migrations are always run in
      * the same order and is the safest option.
      *
      * When true, migrations are still run in alpha-numeric order, but
@@ -212,6 +280,13 @@ export interface MigratorProps {
      * order.
      */
     readonly allowUnorderedMigrations?: boolean;
+    /**
+     * A function that compares migration names, used when sorting migrations in
+     * ascending order.
+     *
+     * Default is `name0.localeCompare(name1)`.
+     */
+    readonly nameComparator?: (name0: string, name1: string) => number;
 }
 /**
  * All migration methods ({@link Migrator.migrateTo | migrateTo},