kysely 0.26.3 → 0.27.0

package/dist/cjs/util/type-utils.d.ts

@@ -33,19 +33,15 @@ import { KyselyTypeError } from './type-error.js';
  * // Columns == 'id' | 'name' | 'species'
  * ```
  */
-export type AnyColumn<DB, TB extends keyof DB> = [
-    DB
-] extends [unknown] ? {
+export type AnyColumn<DB, TB extends keyof DB> = {
     [T in TB]: keyof DB[T];
-}[TB] & string : never;
+}[TB] & string;
 /**
  * Extracts a column type.
  */
-export type ExtractColumnType<DB, TB extends keyof DB, C> = [
-    DB
-] extends [unknown] ? {
+export type ExtractColumnType<DB, TB extends keyof DB, C> = {
     [T in TB]: C extends keyof DB[T] ? DB[T][C] : never;
-}[TB] : never;
+}[TB];
 /**
  * Given a database type and a union of table names in that db, returns
  * a union type with all possible `table`.`column` combinations.
@@ -77,21 +73,17 @@ export type ExtractColumnType<DB, TB extends keyof DB, C> = [
  * // Columns == 'person.id' | 'pet.name' | 'pet.species'
  * ```
  */
-export type AnyColumnWithTable<DB, TB extends keyof DB> = DrainOuterGeneric<{
-    [T in TB]: T extends string ? keyof DB[T] extends string ? `${T}.${keyof DB[T]}` : never : never;
-}[TB]>;
+export type AnyColumnWithTable<DB, TB extends keyof DB> = {
+    [T in TB]: `${T & string}.${keyof DB[T] & string}`;
+}[TB];
 /**
  * Just like {@link AnyColumn} but with a ` as <string>` suffix.
  */
-export type AnyAliasedColumn<DB, TB extends keyof DB> = DrainOuterGeneric<{
-    [T in TB]: T extends string ? keyof DB[T] extends string ? `${keyof DB[T]} as ${string}` : never : never;
-}[TB]>;
+export type AnyAliasedColumn<DB, TB extends keyof DB> = `${AnyColumn<DB, TB>} as ${string}`;
 /**
  * Just like {@link AnyColumnWithTable} but with a ` as <string>` suffix.
  */
-export type AnyAliasedColumnWithTable<DB, TB extends keyof DB> = DrainOuterGeneric<{
-    [T in TB]: T extends string ? keyof DB[T] extends string ? `${T}.${keyof DB[T]} as ${string}` : never : never;
-}[TB]>;
+export type AnyAliasedColumnWithTable<DB, TB extends keyof DB> = `${AnyColumnWithTable<DB, TB>} as ${string}`;
 /**
  * Extracts the item type of an array.
  */
@@ -123,9 +115,25 @@ export type IsAny<T> = 0 extends T & 1 ? true : false;
  * Evaluates to `true` if the types `T` and `U` are equal.
  */
 export type Equals<T, U> = (<G>() => G extends T ? 1 : 2) extends <G>() => G extends U ? 1 : 2 ? true : false;
-export type NarrowPartial<S, T> = DrainOuterGeneric<T extends object ? {
-    [K in keyof S & string]: K extends keyof T ? T[K] extends S[K] ? T[K] : KyselyTypeError<`$narrowType() call failed: passed type does not exist in '${K}'s type union`> : S[K];
+export type NarrowPartial<O, T> = DrainOuterGeneric<T extends object ? {
+    [K in keyof O & string]: K extends keyof T ? T[K] extends NotNull ? Exclude<O[K], null> : T[K] extends O[K] ? T[K] : KyselyTypeError<`$narrowType() call failed: passed type does not exist in '${K}'s type union`> : O[K];
 } : never>;
+/**
+ * A type constant for marking a column as not null. Can be used with `$narrowPartial`.
+ *
+ * Example:
+ *
+ * ```ts
+ * const person = await db.selectFrom('person')
+ *   .where('nullable_column', 'is not', null)
+ *   .selectAll()
+ *   .$narrowType<{ nullable_column: NotNull }>()
+ *   .executeTakeFirstOrThrow()
+ * ```
+ */
+export type NotNull = {
+    readonly __notNull__: unique symbol;
+};
 export type SqlBool = boolean | 0 | 1;
 /**
  * Utility to reduce depth of TypeScript's internal type instantiation stack.

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

@@ -7,6 +7,14 @@ import { DialectAdapter, MigrationLockOptions } from './dialect-adapter.js';
  * they are added and there will be less breaking changes.
  */
 export declare abstract class DialectAdapterBase implements DialectAdapter {
+    /**
+     * Whether or not this dialect supports `if not exists` in creation of tables/schemas/views/etc.
+     *
+     * If this is false, Kysely's internal migrations tables and schemas are created
+     * without `if not exists` in migrations. This is not a problem if the dialect
+     * supports transactional DDL.
+     */
+    get supportsCreateIfNotExists(): boolean;
     /**
      * Whether or not this dialect supports transactional DDL.
      *

package/dist/esm/dialect/dialect-adapter-base.js

@@ -6,6 +6,9 @@
  * they are added and there will be less breaking changes.
  */
 export class DialectAdapterBase {
+    get supportsCreateIfNotExists() {
+        return true;
+    }
     get supportsTransactionalDdl() {
         return false;
     }

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

@@ -8,6 +8,14 @@ import { Kysely } from '../kysely.js';
  * it. For that there's a `supportsTransactionalDdl` boolean in this interface.
  */
 export interface DialectAdapter {
+    /**
+     * Whether or not this dialect supports `if not exists` in creation of tables/schemas/views/etc.
+     *
+     * If this is false, Kysely's internal migrations tables and schemas are created
+     * without `if not exists` in migrations. This is not a problem if the dialect
+     * supports transactional DDL.
+     */
+    readonly supportsCreateIfNotExists: boolean;
     /**
      * Whether or not this dialect supports transactional DDL.
      *

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

@@ -0,0 +1,78 @@
+import { Kysely } from '../../kysely.js';
+import { DialectAdapterBase } from '../dialect-adapter-base.js';
+export declare class MssqlAdapter extends DialectAdapterBase {
+    /**
+     * Whether or not this dialect supports `if not exists` in creation of tables/schemas/views/etc.
+     *
+     * If this is false, Kysely's internal migrations tables and schemas are created
+     * without `if not exists` in migrations. This is not a problem if the dialect
+     * supports transactional DDL.
+     */
+    get supportsCreateIfNotExists(): boolean;
+    /**
+     * Whether or not this dialect supports transactional DDL.
+     *
+     * If this is true, migrations are executed inside a transaction.
+     */
+    get supportsTransactionalDdl(): boolean;
+    /**
+     * Whether or not this dialect supports the `returning` in inserts
+     * updates and deletes.
+     */
+    get supportsReturning(): boolean;
+    /**
+     * This method is used to acquire a lock for the migrations so that
+     * it's not possible for two migration operations to run in parallel.
+     *
+     * Most dialects have explicit locks that can be used, like advisory locks
+     * in PostgreSQL and the get_lock function in MySQL.
+     *
+     * If the dialect doesn't have explicit locks the {@link MigrationLockOptions.lockTable}
+     * created by Kysely can be used instead. You can access it through the `options` object.
+     * The lock table has two columns `id` and `is_locked` and there's only one row in the table
+     * whose id is {@link MigrationLockOptions.lockRowId}. `is_locked` is an integer. Kysely
+     * takes care of creating the lock table and inserting the one single row to it before this
+     * method is executed. If the dialect supports schemas and the user has specified a custom
+     * schema in their migration settings, the options object also contains the schema name in
+     * {@link MigrationLockOptions.lockTableSchema}.
+     *
+     * Here's an example of how you might implement this method for a dialect that doesn't
+     * have explicit locks but supports `FOR UPDATE` row locks and transactional DDL:
+     *
+     * ```ts
+     * {
+     *   async acquireMigrationLock(db, options): Promise<void> {
+     *     const queryDb = options.lockTableSchema
+     *       ? db.withSchema(options.lockTableSchema)
+     *       : db
+     *
+     *     // Since our imaginary dialect supports transactional DDL and has
+     *     // row locks, we can simply take a row lock here and it will guarantee
+     *     // all subsequent calls to this method from other transactions will
+     *     // wait until this transaction finishes.
+     *     await queryDb
+     *       .selectFrom(options.lockTable)
+     *       .selectAll()
+     *       .where('id', '=', options.lockRowId)
+     *       .forUpdate()
+     *       .execute()
+     *   }
+     * }
+     * ```
+     *
+     * If `supportsTransactionalDdl` is `true` then the `db` passed to this method
+     * is a transaction inside which the migrations will be executed. Otherwise
+     * `db` is a single connection (session) that will be used to execute the
+     * migrations.
+     */
+    acquireMigrationLock(db: Kysely<any>): Promise<void>;
+    /**
+     * Releases the migration lock. See {@link acquireMigrationLock}.
+     *
+     * If `supportsTransactionalDdl` is `true` then the `db` passed to this method
+     * is a transaction inside which the migrations were executed. Otherwise `db`
+     * is a single connection (session) that was used to execute the migrations
+     * and the `acquireMigrationLock` call.
+     */
+    releaseMigrationLock(): Promise<void>;
+}

package/dist/esm/dialect/mssql/mssql-adapter.js

@@ -0,0 +1,27 @@
+/// <reference types="./mssql-adapter.d.ts" />
+import { DEFAULT_MIGRATION_TABLE } from '../../migration/migrator.js';
+import { sql } from '../../raw-builder/sql.js';
+import { DialectAdapterBase } from '../dialect-adapter-base.js';
+export class MssqlAdapter extends DialectAdapterBase {
+    get supportsCreateIfNotExists() {
+        return false;
+    }
+    get supportsTransactionalDdl() {
+        return true;
+    }
+    get supportsReturning() {
+        // mssql should support returning with the `output` clause.
+        // we need to figure this out when we'll introduce support for it.
+        return false;
+    }
+    async acquireMigrationLock(db) {
+        // Acquire a transaction-level exclusive lock on the migrations table.
+        // https://learn.microsoft.com/en-us/sql/relational-databases/system-stored-procedures/sp-getapplock-transact-sql?view=sql-server-ver16
+        await sql `exec sp_getapplock @DbPrincipal = ${sql.lit('dbo')}, @Resource = ${sql.lit(DEFAULT_MIGRATION_TABLE)}, @LockMode = ${sql.lit('Exclusive')}`.execute(db);
+    }
+    async releaseMigrationLock() {
+        // Nothing to do here. `sp_getapplock` is automatically released at the
+        // end of the transaction and since `supportsTransactionalDdl` true, we know
+        // the `db` instance passed to acquireMigrationLock is actually a transaction.
+    }
+}

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

@@ -0,0 +1,143 @@
+export interface MssqlDialectConfig {
+    /**
+     * This dialect uses the `tarn` package to manage the connection pool to your
+     * database. To use it as a peer dependency and not bundle it with Kysely's code,
+     * you need to pass the `tarn` package itself. You also need to pass some pool options
+     * (excluding `create`, `destroy` and `validate` functions which are controlled by this dialect),
+     * `min` & `max` connections at the very least.
+     *
+     * Example:
+     *
+     * ```ts
+     * import * as Tarn from 'tarn'
+     *
+     * const dialect = new MssqlDialect({
+     *   // ...
+     *   tarn: {
+     *     ...Tarn,
+     *     options: {
+     *       // ...
+     *       min: 0,
+     *       max: 10,
+     *     },
+     *   },
+     * })
+     * ```
+     */
+    tarn: Tarn;
+    /**
+     * This dialect uses the `tedious` package to communicate with your MS SQL Server
+     * database. To use it as a peer dependency and not bundle it with Kysely's code,
+     * 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:
+     *
+     * ```ts
+     * import * as Tedious from 'tedious'
+     *
+     * const dialect = new MssqlDialect({
+     *   // ...
+     *   tedious: {
+     *     ...Tedious,
+     *     connectionFactory: () => new Tedious.Connection({ ... }),
+     *   },
+     * })
+     * ```
+     */
+    tedious: Tedious;
+}
+export interface Tedious {
+    connectionFactory: () => TediousConnection | Promise<TediousConnection>;
+    ISOLATION_LEVEL: TediousIsolationLevel;
+    Request: typeof TediousRequest;
+    TYPES: TediousTypes;
+}
+export type TediousIsolationLevel = Record<'NO_CHANGE' | 'READ_UNCOMMITTED' | 'READ_COMMITTED' | 'REPEATABLE_READ' | 'SERIALIZABLE' | 'SNAPSHOT', number>;
+export type TediousTypes = Record<'BigInt' | 'Binary' | 'Bit' | 'Char' | 'Date' | 'DateTime' | 'DateTime2' | 'DateTimeOffset' | 'Decimal' | 'Float' | 'Image' | 'Int' | 'Money' | 'NChar' | 'NText' | 'Null' | 'Numeric' | 'NVarChar' | 'Real' | 'SmallDateTime' | 'SmallInt' | 'SmallMoney' | 'Text' | 'Time' | 'TinyInt' | 'TVP' | 'UDT' | 'UniqueIdentifier' | 'VarBinary' | 'VarChar' | 'Xml', {
+    name: string;
+    type: string;
+}>;
+export interface TediousType {
+    name: string;
+    type: string;
+}
+export interface TediousConnection {
+    beginTransaction(callback: (error?: Error) => void, transactionId?: string | undefined, isolationLevel?: number | undefined): void;
+    cancel(): void;
+    close(): void;
+    commitTransaction(callback: (error?: Error) => void): void;
+    connect(callback: (error?: Error) => void): void;
+    execSql(request: TediousRequest): void;
+    reset(callback: (error?: Error) => void): void;
+    rollbackTransaction(callback: (error?: Error) => void): void;
+    once(event: 'end', listener: () => void): void;
+}
+export declare class TediousRequest {
+    constructor(sql: string, callback: (error: Error, rowCount: number, rows: any[]) => void);
+    addParameter(name: string, type: TediousType, value: any, options?: {
+        length?: number | 'max' | undefined;
+        precision?: number | undefined;
+        scale?: number | undefined;
+    }): void;
+    off(event: 'row', listener: (...args: any[]) => void): void;
+    on(event: 'row', listener: (columns: TediousColumnValue[]) => void): void;
+    once(event: 'requestCompleted', listener: (...args: any[]) => void): void;
+}
+export interface TediousColumnValue {
+    metadata: {
+        colName: string;
+    };
+    value: any;
+}
+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'>;
+    /**
+     * Tarn.js' Pool class.
+     *
+     * Example:
+     *
+     * ```ts
+     * import { Pool } from 'tarn'
+     *
+     * const dialect = new MssqlDialect({
+     *   // ...
+     *   tarn: {
+     *     // ...
+     *     Pool,
+     *   },
+     * })
+     * ```
+     */
+    Pool: typeof TarnPool;
+}
+export declare class TarnPool<R> {
+    constructor(opt: TarnPoolOptions<R>);
+    acquire(): TarnPendingRequest<R>;
+    destroy(): any;
+    release(resource: R): void;
+}
+export interface TarnPoolOptions<R> {
+    acquireTimeoutMillis?: number;
+    create(cb: (err: Error | null, resource: R) => void): any | (() => Promise<R>);
+    createRetryIntervalMillis?: number;
+    createTimeoutMillis?: number;
+    destroy(resource: R): any;
+    destroyTimeoutMillis?: number;
+    idleTimeoutMillis?: number;
+    log?(msg: string): any;
+    max: number;
+    min: number;
+    propagateCreateError?: boolean;
+    reapIntervalMillis?: number;
+    validate(resource: R): boolean;
+}
+export interface TarnPendingRequest<R> {
+    promise: Promise<R>;
+    resolve: (resource: R) => void;
+    reject: (err: Error) => void;
+}

package/dist/esm/dialect/mssql/mssql-dialect-config.js

@@ -0,0 +1,2 @@
+/// <reference types="./mssql-dialect-config.d.ts" />
+export {};

package/dist/esm/dialect/mssql/mssql-dialect.d.ts

@@ -0,0 +1,70 @@
+import { Driver } from '../../driver/driver.js';
+import { Kysely } from '../../kysely.js';
+import { QueryCompiler } from '../../query-compiler/query-compiler.js';
+import { DatabaseIntrospector } from '../database-introspector.js';
+import { DialectAdapter } from '../dialect-adapter.js';
+import { Dialect } from '../dialect.js';
+import { MssqlDialectConfig } from './mssql-dialect-config.js';
+/**
+ * MS SQL Server dialect that uses the [tedious](https://tediousjs.github.io/tedious)
+ * library.
+ *
+ * The constructor takes an instance of {@link MssqlDialectConfig}.
+ *
+ * ```ts
+ * import * as Tedious from 'tedious'
+ * import * as Tarn from 'tarn'
+ *
+ * const dialect = new MssqlDialect({
+ *   tarn: {
+ *     ...Tarn,
+ *     options: {
+ *       min: 0,
+ *       max: 10,
+ *     },
+ *   },
+ *   tedious: {
+ *     ...Tedious,
+ *     connectionFactory: () => new Tedious.Connection({
+ *       authentication: {
+ *         options: {
+ *           password: 'password',
+ *           userName: 'username',
+ *         },
+ *         type: 'default',
+ *       },
+ *       options: {
+ *         database: 'some_db',
+ *         port: 1433,
+ *         trustServerCertificate: true,
+ *       },
+ *       server: 'localhost',
+ *     }),
+ *   },
+ * })
+ * ```
+ */
+export declare class MssqlDialect implements Dialect {
+    #private;
+    constructor(config: MssqlDialectConfig);
+    /**
+     * Creates a driver for the dialect.
+     */
+    createDriver(): Driver;
+    /**
+     * Creates a query compiler for the dialect.
+     */
+    createQueryCompiler(): QueryCompiler;
+    /**
+     * Creates an adapter for the dialect.
+     */
+    createAdapter(): DialectAdapter;
+    /**
+     * Creates a database introspector that can be used to get database metadata
+     * such as the table names and column names of those tables.
+     *
+     * `db` never has any plugins installed. It's created using
+     * {@link Kysely.withoutPlugins}.
+     */
+    createIntrospector(db: Kysely<any>): DatabaseIntrospector;
+}

package/dist/esm/dialect/mssql/mssql-dialect.js

@@ -0,0 +1,62 @@
+/// <reference types="./mssql-dialect.d.ts" />
+import { MssqlAdapter } from './mssql-adapter.js';
+import { MssqlDriver } from './mssql-driver.js';
+import { MssqlIntrospector } from './mssql-introspector.js';
+import { MssqlQueryCompiler } from './mssql-query-compiler.js';
+/**
+ * MS SQL Server dialect that uses the [tedious](https://tediousjs.github.io/tedious)
+ * library.
+ *
+ * The constructor takes an instance of {@link MssqlDialectConfig}.
+ *
+ * ```ts
+ * import * as Tedious from 'tedious'
+ * import * as Tarn from 'tarn'
+ *
+ * const dialect = new MssqlDialect({
+ *   tarn: {
+ *     ...Tarn,
+ *     options: {
+ *       min: 0,
+ *       max: 10,
+ *     },
+ *   },
+ *   tedious: {
+ *     ...Tedious,
+ *     connectionFactory: () => new Tedious.Connection({
+ *       authentication: {
+ *         options: {
+ *           password: 'password',
+ *           userName: 'username',
+ *         },
+ *         type: 'default',
+ *       },
+ *       options: {
+ *         database: 'some_db',
+ *         port: 1433,
+ *         trustServerCertificate: true,
+ *       },
+ *       server: 'localhost',
+ *     }),
+ *   },
+ * })
+ * ```
+ */
+export class MssqlDialect {
+    #config;
+    constructor(config) {
+        this.#config = config;
+    }
+    createDriver() {
+        return new MssqlDriver(this.#config);
+    }
+    createQueryCompiler() {
+        return new MssqlQueryCompiler();
+    }
+    createAdapter() {
+        return new MssqlAdapter();
+    }
+    createIntrospector(db) {
+        return new MssqlIntrospector(db);
+    }
+}

package/dist/esm/dialect/mssql/mssql-driver.d.ts

@@ -0,0 +1,54 @@
+import { DatabaseConnection, QueryResult } from '../../driver/database-connection.js';
+import { Driver, TransactionSettings } from '../../driver/driver.js';
+import { MssqlDialectConfig, Tedious, TediousConnection } from './mssql-dialect-config.js';
+import { CompiledQuery } from '../../query-compiler/compiled-query.js';
+declare const PRIVATE_RELEASE_METHOD: unique symbol;
+declare const PRIVATE_DESTROY_METHOD: unique symbol;
+export declare class MssqlDriver implements Driver {
+    #private;
+    constructor(config: MssqlDialectConfig);
+    /**
+     * Initializes the driver.
+     *
+     * After calling this method the driver should be usable and `acquireConnection` etc.
+     * methods should be callable.
+     */
+    init(): Promise<void>;
+    /**
+     * Acquires a new connection from the pool.
+     */
+    acquireConnection(): Promise<DatabaseConnection>;
+    /**
+     * Begins a transaction.
+     */
+    beginTransaction(connection: MssqlConnection, settings: TransactionSettings): Promise<void>;
+    /**
+     * Commits a transaction.
+     */
+    commitTransaction(connection: MssqlConnection): Promise<void>;
+    /**
+     * Rolls back a transaction.
+     */
+    rollbackTransaction(connection: MssqlConnection): Promise<void>;
+    /**
+     * Releases a connection back to the pool.
+     */
+    releaseConnection(connection: MssqlConnection): Promise<void>;
+    /**
+     * Destroys the driver and releases all resources.
+     */
+    destroy(): Promise<void>;
+}
+declare class MssqlConnection implements DatabaseConnection {
+    #private;
+    constructor(connection: TediousConnection, tedious: Tedious);
+    beginTransaction(settings: TransactionSettings): Promise<void>;
+    commitTransaction(): Promise<void>;
+    executeQuery<O>(compiledQuery: CompiledQuery): Promise<QueryResult<O>>;
+    rollbackTransaction(): Promise<void>;
+    streamQuery<O>(compiledQuery: CompiledQuery, chunkSize: number): AsyncIterableIterator<QueryResult<O>>;
+    validate(): Promise<boolean>;
+    [PRIVATE_RELEASE_METHOD](): Promise<void>;
+    [PRIVATE_DESTROY_METHOD](): Promise<void>;
+}
+export {};