kysely 0.27.4 → 0.27.5

package/.renovaterc.json

@@ -0,0 +1,3 @@
+{
+  "rangeStrategy": "bump"  
+}

package/CONTRIBUTING.md

@@ -52,7 +52,7 @@ for all cases, are best left for consumers to implement.
 
 5. create a branch.
 
-6. create a draft pull request. link the relevant issue by refering to it in the 
+6. create a draft pull request. link the relevant issue by referring to it in the 
 PR's description. E.g. `closes #123` will link the PR to issue/pull request #123.
 
 7. implement your changes.

package/deno.check.d.ts

@@ -0,0 +1,86 @@
+import type {
+  ColumnType,
+  Generated,
+  GeneratedAlways,
+  Insertable,
+  Kysely,
+  Selectable,
+  SqlBool,
+  Updateable,
+} from './dist/esm'
+
+export interface Database {
+  person: PersonTable
+  pet: PetTable
+  toy: ToyTable
+  wine: WineTable
+  wine_stock_change: WineStockChangeTable
+}
+
+interface PersonTable {
+  id: Generated<number>
+  address: { city: string } | null
+  age: number | null
+  birthdate: ColumnType<Date | null, string | null | undefined, string | null>
+  created_at: GeneratedAlways<Date>
+  deleted_at: ColumnType<Date | null, string | null | undefined, string | null>
+  experience: { role: string }[] | null
+  first_name: string
+  gender: 'male' | 'female' | 'other' | null
+  has_pets: Generated<'Y' | 'N'>
+  last_name: string | null
+  middle_name: string | null
+  nicknames: string[] | null
+  nullable_column: string | null
+  profile: {
+    addresses: { city: string }[]
+    website: { url: string }
+  } | null
+  updated_at: ColumnType<Date | null, string | null | undefined, string | null>
+  marital_status: 'single' | 'married' | 'divorced' | 'widowed' | null
+}
+
+interface PetTable {
+  id: Generated<number>
+  created_at: GeneratedAlways<Date>
+  is_favorite: Generated<SqlBool>
+  name: string
+  owner_id: number
+  species: Species
+}
+
+interface ToyTable {
+  id: Generated<number>
+  pet_id: number
+  price: number
+}
+
+interface WineTable {
+  name: string
+  stock: number
+}
+
+interface WineStockChangeTable {
+  stock_delta: number
+  wine_name: string
+}
+
+export type Person = Selectable<PersonTable>
+export type NewPerson = Insertable<PersonTable>
+export type PersonUpdate = Updateable<PersonTable>
+export type Pet = Selectable<PetTable>
+export type NewPet = Insertable<PetTable>
+export type PetUpdate = Updateable<PetTable>
+export type Species = 'dog' | 'cat' | 'hamster'
+
+declare global {
+  // @ts-ignore
+  export class Buffer {
+    static isBuffer(obj: unknown): obj is { length: number }
+    static compare(a: Buffer, b: Buffer): number
+  }
+  export const db: Kysely<Database>
+  export function functionThatExpectsPersonWithNonNullValue(
+    person: Person & { nullable_column: string },
+  ): void
+}

package/deno.check.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://deno.land/x/deno/cli/schemas/config-file.v1.json",
+  "compilerOptions": {
+    "types": ["./deno.check.d.ts"]
+  },
+  "imports": {
+    "better-sqlite3": "npm:better-sqlite3",
+    "kysely": "./dist/esm",
+    "kysely/helpers/mssql": "./dist/esm/helpers/mssql.js",
+    "kysely/helpers/mysql": "./dist/esm/helpers/mysql.js",
+    "kysely/helpers/postgres": "./dist/esm/helpers/postgres.js",
+    "kysely/helpers/sqlite": "./dist/esm/helpers/sqlite.js",
+    "lodash/snakeCase": "npm:lodash/snakeCase",
+    "mysql2": "npm:mysql2",
+    "pg": "npm:pg",
+    "pg-cursor": "npm:pg-cursor",
+    "tarn": "npm:tarn",
+    "tedious": "npm:tedious",
+    "type-editor": "./deno.check.d.ts"
+  }
+}

package/dist/cjs/dialect/dialect-adapter-base.d.ts

@@ -47,8 +47,13 @@ export declare abstract class DialectAdapterBase implements DialectAdapter {
      * have explicit locks but supports `FOR UPDATE` row locks and transactional DDL:
      *
      * ```ts
-     * {
-     *   async acquireMigrationLock(db, options): Promise<void> {
+     * import { DialectAdapterBase, type MigrationLockOptions, Kysely } from 'kysely'
+     *
+     * export class MyAdapter extends DialectAdapterBase {
+     *   override async acquireMigrationLock(
+     *     db: Kysely<any>,
+     *     options: MigrationLockOptions
+     *   ): Promise<void> {
      *     const queryDb = options.lockTableSchema
      *       ? db.withSchema(options.lockTableSchema)
      *       : db
@@ -64,6 +69,10 @@ export declare abstract class DialectAdapterBase implements DialectAdapter {
      *       .forUpdate()
      *       .execute()
      *   }
+     *
+     *   override async releaseMigrationLock() {
+     *     // noop
+     *   }
      * }
      * ```
      *

package/dist/cjs/dialect/dialect-adapter.d.ts

@@ -52,8 +52,13 @@ export interface DialectAdapter {
      * have explicit locks but supports `FOR UPDATE` row locks and transactional DDL:
      *
      * ```ts
-     * {
-     *   async acquireMigrationLock(db, options): Promise<void> {
+     * import { DialectAdapterBase, type MigrationLockOptions, Kysely } from 'kysely'
+     *
+     * export class MyAdapter extends DialectAdapterBase {
+     *   override async acquireMigrationLock(
+     *     db: Kysely<any>,
+     *     options: MigrationLockOptions
+     *   ): Promise<void> {
      *     const queryDb = options.lockTableSchema
      *       ? db.withSchema(options.lockTableSchema)
      *       : db
@@ -69,6 +74,10 @@ export interface DialectAdapter {
      *       .forUpdate()
      *       .execute()
      *   }
+     *
+     *   override async releaseMigrationLock() {
+     *     // noop
+     *   }
      * }
      * ```
      *

package/dist/cjs/dialect/mssql/mssql-adapter.d.ts

@@ -36,8 +36,13 @@ export declare class MssqlAdapter extends DialectAdapterBase {
      * have explicit locks but supports `FOR UPDATE` row locks and transactional DDL:
      *
      * ```ts
-     * {
-     *   async acquireMigrationLock(db, options): Promise<void> {
+     * import { DialectAdapterBase, type MigrationLockOptions, Kysely } from 'kysely'
+     *
+     * export class MyAdapter extends DialectAdapterBase {
+     *   override async acquireMigrationLock(
+     *     db: Kysely<any>,
+     *     options: MigrationLockOptions
+     *   ): Promise<void> {
      *     const queryDb = options.lockTableSchema
      *       ? db.withSchema(options.lockTableSchema)
      *       : db
@@ -53,6 +58,10 @@ export declare class MssqlAdapter extends DialectAdapterBase {
      *       .forUpdate()
      *       .execute()
      *   }
+     *
+     *   override async releaseMigrationLock() {
+     *     // noop
+     *   }
      * }
      * ```
      *

package/dist/cjs/dialect/mssql/mssql-dialect-config.d.ts

@@ -6,21 +6,23 @@ export interface MssqlDialectConfig {
      * (excluding `create`, `destroy` and `validate` functions which are controlled by this dialect),
      * `min` & `max` connections at the very least.
      *
-     * Example:
+     * ### Examples
      *
      * ```ts
+     * import { MssqlDialect } from 'kysely'
      * import * as Tarn from 'tarn'
+     * import * as Tedious from 'tedious'
      *
      * const dialect = new MssqlDialect({
-     *   // ...
-     *   tarn: {
-     *     ...Tarn,
-     *     options: {
+     *   tarn: { ...Tarn, options: { max: 10, min: 0 } },
+     *   tedious: {
+     *     ...Tedious,
+     *     connectionFactory: () => new Tedious.Connection({
      *       // ...
-     *       min: 0,
-     *       max: 10,
-     *     },
-     *   },
+     *       server: 'localhost',
+     *       // ...
+     *     }),
+     *   }
      * })
      * ```
      */
@@ -31,17 +33,23 @@ export interface MssqlDialectConfig {
      * you need to pass the `tedious` package itself. You also need to pass a factory
      * function that creates new `tedious` `Connection` instances on demand.
      *
-     * Example:
+     * ### Examples
      *
      * ```ts
+     * import { MssqlDialect } from 'kysely'
+     * import * as Tarn from 'tarn'
      * import * as Tedious from 'tedious'
      *
      * const dialect = new MssqlDialect({
-     *   // ...
+     *   tarn: { ...Tarn, options: { max: 10, min: 0 } },
      *   tedious: {
      *     ...Tedious,
-     *     connectionFactory: () => new Tedious.Connection({ ... }),
-     *   },
+     *     connectionFactory: () => new Tedious.Connection({
+     *       // ...
+     *       server: 'localhost',
+     *       // ...
+     *     }),
+     *   }
      * })
      * ```
      */
@@ -52,6 +60,13 @@ export interface Tedious {
     ISOLATION_LEVEL: TediousIsolationLevel;
     Request: TediousRequestClass;
     TYPES: TediousTypes;
+    /**
+     * Controls whether connections are reset to their initial states when released back to the pool. Resetting a connection performs additional requests to the database.
+     * See {@link https://tediousjs.github.io/tedious/api-connection.html#function_reset | connection.reset}.
+     *
+     * Defaults to `true`.
+     */
+    resetConnectionOnRelease?: boolean;
 }
 export interface TediousConnection {
     beginTransaction(callback: (error?: Error | null, transactionDescriptor?: any) => void, name?: string, isolationLevel?: number): void;
@@ -115,23 +130,16 @@ export interface Tarn {
      * Tarn.js' pool options, excluding `create`, `destroy` and `validate` functions,
      * which must be implemented by this dialect.
      */
-    options: Omit<TarnPoolOptions<any>, 'create' | 'destroy' | 'validate'>;
+    options: Omit<TarnPoolOptions<any>, 'create' | 'destroy' | 'validate'> & {
+        /**
+         * Controls whether connections are validated before being acquired from the pool. Connection validation performs additional requests to the database.
+         *
+         * Defaults to `true`.
+         */
+        validateConnections?: boolean;
+    };
     /**
      * Tarn.js' Pool class.
-     *
-     * Example:
-     *
-     * ```ts
-     * import { Pool } from 'tarn'
-     *
-     * const dialect = new MssqlDialect({
-     *   // ...
-     *   tarn: {
-     *     // ...
-     *     Pool,
-     *   },
-     * })
-     * ```
      */
     Pool: typeof TarnPool;
 }
@@ -154,7 +162,7 @@ export interface TarnPoolOptions<R> {
     min: number;
     propagateCreateError?: boolean;
     reapIntervalMillis?: number;
-    validate(resource: R): boolean;
+    validate?(resource: R): boolean;
 }
 export interface TarnPendingRequest<R> {
     promise: Promise<R>;

package/dist/cjs/dialect/mssql/mssql-driver.js

@@ -13,18 +13,22 @@ class MssqlDriver {
     #pool;
     constructor(config) {
         this.#config = (0, object_utils_js_1.freeze)({ ...config });
-        this.#pool = new this.#config.tarn.Pool({
-            ...this.#config.tarn.options,
+        const { tarn, tedious } = this.#config;
+        const { validateConnections, ...poolOptions } = tarn.options;
+        this.#pool = new tarn.Pool({
+            ...poolOptions,
             create: async () => {
-                const connection = await this.#config.tedious.connectionFactory();
-                return await new MssqlConnection(connection, this.#config.tedious).connect();
+                const connection = await tedious.connectionFactory();
+                return await new MssqlConnection(connection, tedious).connect();
             },
             destroy: async (connection) => {
                 await connection[PRIVATE_DESTROY_METHOD]();
             },
             // @ts-ignore `tarn` accepts a function that returns a promise here, but
             // the types are not aligned and it type errors.
-            validate: (connection) => connection.validate(),
+            validate: validateConnections === false
+                ? undefined
+                : (connection) => connection.validate(),
         });
     }
     async init() {
@@ -189,15 +193,18 @@ class MssqlConnection {
             }
         });
     }
-    [PRIVATE_RELEASE_METHOD]() {
-        return new Promise((resolve, reject) => {
-            this.#connection.reset((error) => {
-                if (error)
-                    reject(error);
-                else
-                    resolve(undefined);
+    async [PRIVATE_RELEASE_METHOD]() {
+        // TODO: flip this to `if (!this.#tedious.resetConnectionOnRelease) {}` in a future PR.
+        if (this.#tedious.resetConnectionOnRelease !== false) {
+            await new Promise((resolve, reject) => {
+                this.#connection.reset((error) => {
+                    if (error)
+                        reject(error);
+                    else
+                        resolve(undefined);
+                });
             });
-        });
+        }
     }
     [PRIVATE_DESTROY_METHOD]() {
         return new Promise((resolve) => {

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

@@ -33,8 +33,13 @@ export declare class MysqlAdapter extends DialectAdapterBase {
      * have explicit locks but supports `FOR UPDATE` row locks and transactional DDL:
      *
      * ```ts
-     * {
-     *   async acquireMigrationLock(db, options): Promise<void> {
+     * import { DialectAdapterBase, type MigrationLockOptions, Kysely } from 'kysely'
+     *
+     * export class MyAdapter extends DialectAdapterBase {
+     *   override async acquireMigrationLock(
+     *     db: Kysely<any>,
+     *     options: MigrationLockOptions
+     *   ): Promise<void> {
      *     const queryDb = options.lockTableSchema
      *       ? db.withSchema(options.lockTableSchema)
      *       : db
@@ -50,6 +55,10 @@ export declare class MysqlAdapter extends DialectAdapterBase {
      *       .forUpdate()
      *       .execute()
      *   }
+     *
+     *   override async releaseMigrationLock() {
+     *     // noop
+     *   }
      * }
      * ```
      *

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

@@ -17,6 +17,10 @@ export interface MysqlDialectConfig {
      * Called once for each created connection.
      */
     onCreateConnection?: (connection: DatabaseConnection) => Promise<void>;
+    /**
+     * Called every time a connection is acquired from the connection pool.
+     */
+    onReserveConnection?: (connection: DatabaseConnection) => Promise<void>;
 }
 /**
  * This interface is the subset of mysql2 driver's `Pool` class that

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

@@ -30,6 +30,9 @@ class MysqlDriver {
                 await this.#config.onCreateConnection(connection);
             }
         }
+        if (this.#config?.onReserveConnection) {
+            await this.#config.onReserveConnection(connection);
+        }
         return connection;
     }
     async #acquireConnection() {

package/dist/cjs/dialect/postgres/postgres-adapter.d.ts

@@ -33,8 +33,13 @@ export declare class PostgresAdapter extends DialectAdapterBase {
      * have explicit locks but supports `FOR UPDATE` row locks and transactional DDL:
      *
      * ```ts
-     * {
-     *   async acquireMigrationLock(db, options): Promise<void> {
+     * import { DialectAdapterBase, type MigrationLockOptions, Kysely } from 'kysely'
+     *
+     * export class MyAdapter extends DialectAdapterBase {
+     *   override async acquireMigrationLock(
+     *     db: Kysely<any>,
+     *     options: MigrationLockOptions
+     *   ): Promise<void> {
      *     const queryDb = options.lockTableSchema
      *       ? db.withSchema(options.lockTableSchema)
      *       : db
@@ -50,6 +55,10 @@ export declare class PostgresAdapter extends DialectAdapterBase {
      *       .forUpdate()
      *       .execute()
      *   }
+     *
+     *   override async releaseMigrationLock() {
+     *     // noop
+     *   }
      * }
      * ```
      *

package/dist/cjs/dialect/postgres/postgres-dialect-config.d.ts

@@ -13,13 +13,16 @@ export interface PostgresDialectConfig {
     pool: PostgresPool | (() => Promise<PostgresPool>);
     /**
      * https://github.com/brianc/node-postgres/tree/master/packages/pg-cursor
+     *
      * ```ts
+     * import { PostgresDialect } from 'kysely'
+     * import { Pool } from 'pg'
      * import Cursor from 'pg-cursor'
-     * // or
-     * import * as Cursor from 'pg-cursor'
+     * // or import * as Cursor from 'pg-cursor'
      *
      * new PostgresDialect({
-     *  cursor: Cursor
+     *  cursor: Cursor,
+     *  pool: new Pool('postgres://localhost:5432/mydb')
      * })
      * ```
      */
@@ -28,6 +31,10 @@ export interface PostgresDialectConfig {
      * Called once for each created connection.
      */
     onCreateConnection?: (connection: DatabaseConnection) => Promise<void>;
+    /**
+     * Called every time a connection is acquired from the pool.
+     */
+    onReserveConnection?: (connection: DatabaseConnection) => Promise<void>;
 }
 /**
  * This interface is the subset of pg driver's `Pool` class that

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

@@ -32,6 +32,9 @@ class PostgresDriver {
                 await this.#config.onCreateConnection(connection);
             }
         }
+        if (this.#config.onReserveConnection) {
+            await this.#config.onReserveConnection(connection);
+        }
         return connection;
     }
     async beginTransaction(connection, settings) {

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

@@ -51,7 +51,11 @@ class PostgresIntrospector {
                 .as('auto_incrementing'),
         ])
             // r == normal table
-            .where((eb) => eb.or([eb('c.relkind', '=', 'r'), eb('c.relkind', '=', 'v'), eb('c.relkind', '=', 'p')]))
+            .where((eb) => eb.or([
+            eb('c.relkind', '=', 'r'),
+            eb('c.relkind', '=', 'v'),
+            eb('c.relkind', '=', 'p'),
+        ]))
             .where('ns.nspname', '!~', '^pg_')
             .where('ns.nspname', '!=', 'information_schema')
             // No system columns

package/dist/cjs/dialect/sqlite/sqlite-adapter.d.ts

@@ -33,8 +33,13 @@ export declare class SqliteAdapter extends DialectAdapterBase {
      * have explicit locks but supports `FOR UPDATE` row locks and transactional DDL:
      *
      * ```ts
-     * {
-     *   async acquireMigrationLock(db, options): Promise<void> {
+     * import { DialectAdapterBase, type MigrationLockOptions, Kysely } from 'kysely'
+     *
+     * export class MyAdapter extends DialectAdapterBase {
+     *   override async acquireMigrationLock(
+     *     db: Kysely<any>,
+     *     options: MigrationLockOptions
+     *   ): Promise<void> {
      *     const queryDb = options.lockTableSchema
      *       ? db.withSchema(options.lockTableSchema)
      *       : db
@@ -50,6 +55,10 @@ export declare class SqliteAdapter extends DialectAdapterBase {
      *       .forUpdate()
      *       .execute()
      *   }
+     *
+     *   override async releaseMigrationLock() {
+     *     // noop
+     *   }
      * }
      * ```
      *

package/dist/cjs/driver/dummy-driver.d.ts

@@ -10,20 +10,21 @@ import { Driver } from './driver.js';
  * This example creates a Kysely instance for building postgres queries:
  *
  * ```ts
+ * import {
+ *   DummyDriver,
+ *   Kysely,
+ *   PostgresAdapter,
+ *   PostgresIntrospector,
+ *   PostgresQueryCompiler
+ * } from 'kysely'
+ * import type { Database } from 'type-editor' // imaginary module
+ *
  * const db = new Kysely<Database>({
  *   dialect: {
- *     createAdapter() {
- *       return new PostgresAdapter()
- *     },
- *     createDriver() {
- *       return new DummyDriver()
- *     },
- *     createIntrospector(db: Kysely<any>) {
- *       return new PostgresIntrospector(db)
- *     },
- *     createQueryCompiler() {
- *       return new PostgresQueryCompiler()
- *     },
+ *     createAdapter: () => new PostgresAdapter(),
+ *     createDriver: () => new DummyDriver(),
+ *     createIntrospector: (db: Kysely<any>) => new PostgresIntrospector(db),
+ *     createQueryCompiler: () => new PostgresQueryCompiler(),
  *   },
  * })
  * ```

package/dist/cjs/driver/dummy-driver.js

@@ -11,20 +11,21 @@ exports.DummyDriver = void 0;
  * This example creates a Kysely instance for building postgres queries:
  *
  * ```ts
+ * import {
+ *   DummyDriver,
+ *   Kysely,
+ *   PostgresAdapter,
+ *   PostgresIntrospector,
+ *   PostgresQueryCompiler
+ * } from 'kysely'
+ * import type { Database } from 'type-editor' // imaginary module
+ *
  * const db = new Kysely<Database>({
  *   dialect: {
- *     createAdapter() {
- *       return new PostgresAdapter()
- *     },
- *     createDriver() {
- *       return new DummyDriver()
- *     },
- *     createIntrospector(db: Kysely<any>) {
- *       return new PostgresIntrospector(db)
- *     },
- *     createQueryCompiler() {
- *       return new PostgresQueryCompiler()
- *     },
+ *     createAdapter: () => new PostgresAdapter(),
+ *     createDriver: () => new DummyDriver(),
+ *     createIntrospector: (db: Kysely<any>) => new PostgresIntrospector(db),
+ *     createQueryCompiler: () => new PostgresQueryCompiler(),
  *   },
  * })
  * ```

package/dist/cjs/dynamic/dynamic.d.ts

@@ -61,11 +61,11 @@ export declare class DynamicModule {
      * const { ref } = db.dynamic
      *
      * // Some column name provided by the user. Value not known at compile time.
-     * const columnFromUserInput = req.query.select;
+     * const columnFromUserInput: PossibleColumns = 'birthdate';
      *
      * // A type that lists all possible values `columnFromUserInput` can have.
      * // You can use `keyof Person` if any column of an interface is allowed.
-     * type PossibleColumns = 'last_name' | 'first_name' | 'birth_date'
+     * type PossibleColumns = 'last_name' | 'first_name' | 'birthdate'
      *
      * const [person] = await db.selectFrom('person')
      *   .select([
@@ -77,12 +77,12 @@ export declare class DynamicModule {
      * // The resulting type contains all `PossibleColumns` as optional fields
      * // because we cannot know which field was actually selected before
      * // running the code.
-     * const lastName: string | undefined = person.last_name
-     * const firstName: string | undefined = person.first_name
-     * const birthDate: string | undefined = person.birth_date
+     * const lastName: string | null | undefined = person?.last_name
+     * const firstName: string | undefined = person?.first_name
+     * const birthDate: Date | null | undefined = person?.birthdate
      *
      * // The result type also contains the compile time selection `id`.
-     * person.id
+     * person?.id
      * ```
      */
     ref<R extends string = never>(reference: string): DynamicReferenceBuilder<R>;

package/dist/cjs/dynamic/dynamic.js

@@ -64,11 +64,11 @@ class DynamicModule {
      * const { ref } = db.dynamic
      *
      * // Some column name provided by the user. Value not known at compile time.
-     * const columnFromUserInput = req.query.select;
+     * const columnFromUserInput: PossibleColumns = 'birthdate';
      *
      * // A type that lists all possible values `columnFromUserInput` can have.
      * // You can use `keyof Person` if any column of an interface is allowed.
-     * type PossibleColumns = 'last_name' | 'first_name' | 'birth_date'
+     * type PossibleColumns = 'last_name' | 'first_name' | 'birthdate'
      *
      * const [person] = await db.selectFrom('person')
      *   .select([
@@ -80,12 +80,12 @@ class DynamicModule {
      * // The resulting type contains all `PossibleColumns` as optional fields
      * // because we cannot know which field was actually selected before
      * // running the code.
-     * const lastName: string | undefined = person.last_name
-     * const firstName: string | undefined = person.first_name
-     * const birthDate: string | undefined = person.birth_date
+     * const lastName: string | null | undefined = person?.last_name
+     * const firstName: string | undefined = person?.first_name
+     * const birthDate: Date | null | undefined = person?.birthdate
      *
      * // The result type also contains the compile time selection `id`.
-     * person.id
+     * person?.id
      * ```
      */
     ref(reference) {