kysely 0.26.2 → 0.27.0

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 {};

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

@@ -0,0 +1,265 @@
+/// <reference types="./mssql-driver.d.ts" />
+import { freeze, isBigInt, isBoolean, isBuffer, isDate, isNull, isNumber, isString, isUndefined, } from '../../util/object-utils.js';
+import { CompiledQuery } from '../../query-compiler/compiled-query.js';
+import { extendStackTrace } from '../../util/stack-trace-utils.js';
+import { randomString } from '../../util/random-string.js';
+import { Deferred } from '../../util/deferred.js';
+const PRIVATE_RELEASE_METHOD = Symbol();
+const PRIVATE_DESTROY_METHOD = Symbol();
+export class MssqlDriver {
+    #config;
+    #pool;
+    constructor(config) {
+        this.#config = freeze({ ...config });
+        this.#pool = new this.#config.tarn.Pool({
+            ...this.#config.tarn.options,
+            create: async () => {
+                const connection = await this.#config.tedious.connectionFactory();
+                await new Promise((resolve, reject) => connection.connect((error) => {
+                    if (error)
+                        reject(error);
+                    else
+                        resolve(undefined);
+                }));
+                return new MssqlConnection(connection, this.#config.tedious);
+            },
+            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(),
+        });
+    }
+    async init() {
+        // noop
+    }
+    async acquireConnection() {
+        return await this.#pool.acquire().promise;
+    }
+    async beginTransaction(connection, settings) {
+        await connection.beginTransaction(settings);
+    }
+    async commitTransaction(connection) {
+        await connection.commitTransaction();
+    }
+    async rollbackTransaction(connection) {
+        await connection.rollbackTransaction();
+    }
+    async releaseConnection(connection) {
+        await connection[PRIVATE_RELEASE_METHOD]();
+        this.#pool.release(connection);
+    }
+    async destroy() {
+        await this.#pool.destroy();
+    }
+}
+class MssqlConnection {
+    #connection;
+    #tedious;
+    constructor(connection, tedious) {
+        this.#connection = connection;
+        this.#tedious = tedious;
+    }
+    async beginTransaction(settings) {
+        const { isolationLevel } = settings;
+        await new Promise((resolve, reject) => this.#connection.beginTransaction((error) => {
+            if (error)
+                reject(error);
+            else
+                resolve(undefined);
+        }, isolationLevel ? randomString(8) : undefined, isolationLevel
+            ? this.#getTediousIsolationLevel(isolationLevel)
+            : undefined));
+    }
+    async commitTransaction() {
+        await new Promise((resolve, reject) => this.#connection.commitTransaction((error) => {
+            if (error)
+                reject(error);
+            else
+                resolve(undefined);
+        }));
+    }
+    async executeQuery(compiledQuery) {
+        try {
+            const deferred = new Deferred();
+            const request = new MssqlRequest(this.#tedious, compiledQuery, deferred);
+            this.#connection.execSql(request.request);
+            const { rowCount, rows } = await deferred.promise;
+            return {
+                numAffectedRows: rowCount !== undefined ? BigInt(rowCount) : undefined,
+                rows,
+            };
+        }
+        catch (err) {
+            throw extendStackTrace(err, new Error());
+        }
+    }
+    async rollbackTransaction() {
+        await new Promise((resolve, reject) => this.#connection.rollbackTransaction((error) => {
+            if (error)
+                reject(error);
+            else
+                resolve(undefined);
+        }));
+    }
+    async *streamQuery(compiledQuery, chunkSize) {
+        if (!Number.isInteger(chunkSize) || chunkSize <= 0) {
+            throw new Error('chunkSize must be a positive integer');
+        }
+        const request = new MssqlRequest(this.#tedious, compiledQuery);
+        this.#connection.execSql(request.request);
+        try {
+            while (true) {
+                const rows = await request.readChunk(chunkSize);
+                if (rows.length === 0) {
+                    break;
+                }
+                yield { rows };
+                if (rows.length < chunkSize) {
+                    break;
+                }
+            }
+        }
+        finally {
+            this.#connection.cancel();
+        }
+    }
+    async validate() {
+        try {
+            const deferred = new Deferred();
+            const request = new MssqlRequest(this.#tedious, CompiledQuery.raw('select 1'), deferred);
+            this.#connection.execSql(request.request);
+            await deferred.promise;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    #getTediousIsolationLevel(isolationLevel) {
+        const { ISOLATION_LEVEL } = this.#tedious;
+        const mapper = {
+            'read committed': ISOLATION_LEVEL.READ_COMMITTED,
+            'read uncommitted': ISOLATION_LEVEL.READ_UNCOMMITTED,
+            'repeatable read': ISOLATION_LEVEL.REPEATABLE_READ,
+            serializable: ISOLATION_LEVEL.SERIALIZABLE,
+            snapshot: ISOLATION_LEVEL.SNAPSHOT,
+        };
+        const tediousIsolationLevel = mapper[isolationLevel];
+        if (tediousIsolationLevel === undefined) {
+            throw new Error(`Unknown isolation level: ${isolationLevel}`);
+        }
+        return tediousIsolationLevel;
+    }
+    [PRIVATE_RELEASE_METHOD]() {
+        return new Promise((resolve, reject) => {
+            this.#connection.reset((error) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve(undefined);
+            });
+        });
+    }
+    [PRIVATE_DESTROY_METHOD]() {
+        return new Promise((resolve) => {
+            this.#connection.once('end', () => {
+                resolve(undefined);
+            });
+            this.#connection.close();
+        });
+    }
+}
+class MssqlRequest {
+    #request;
+    #rows;
+    #tedious;
+    #completed;
+    #error;
+    #rowCount;
+    constructor(tedious, compiledQuery, onDone) {
+        this.#completed = false;
+        this.#rows = [];
+        this.#tedious = tedious;
+        const { parameters, sql } = compiledQuery;
+        this.#request = new this.#tedious.Request(sql, (err, rowCount) => {
+            if (err) {
+                this.#error = err instanceof AggregateError ? err.errors : err;
+                onDone?.reject(this.#error);
+            }
+            else {
+                this.#rowCount = rowCount;
+            }
+        });
+        this.#addParametersToRequest(parameters);
+        this.#attachListeners(onDone);
+    }
+    get request() {
+        return this.#request;
+    }
+    readChunk(chunkSize) {
+        return new Promise((resolve, reject) => {
+            const interval = setInterval(() => {
+                if (this.#error) {
+                    clearInterval(interval);
+                    reject(this.#error);
+                }
+                else if (this.#completed || this.#rows.length >= chunkSize) {
+                    clearInterval(interval);
+                    resolve(this.#rows.splice(0, chunkSize));
+                }
+            }, 0);
+        });
+    }
+    #addParametersToRequest(parameters) {
+        for (let i = 0; i < parameters.length; i++) {
+            const parameter = parameters[i];
+            this.#request.addParameter(String(i + 1), this.#getTediousDataType(parameter), parameter);
+        }
+    }
+    #attachListeners(onDone) {
+        const rowListener = (columns) => {
+            const row = {};
+            for (const column of columns) {
+                row[column.metadata.colName] = column.value;
+            }
+            this.#rows.push(row);
+        };
+        this.#request.on('row', rowListener);
+        this.#request.once('requestCompleted', () => {
+            this.#completed = true;
+            this.#request.off('row', rowListener);
+            onDone?.resolve({
+                rowCount: this.#rowCount,
+                rows: this.#rows,
+            });
+        });
+    }
+    #getTediousDataType(value) {
+        if (isNull(value) || isUndefined(value) || isString(value)) {
+            return this.#tedious.TYPES.NVarChar;
+        }
+        if (isBigInt(value) || (isNumber(value) && value % 1 === 0)) {
+            if (value < -2147483648 || value > 2147483647) {
+                return this.#tedious.TYPES.BigInt;
+            }
+            else {
+                return this.#tedious.TYPES.Int;
+            }
+        }
+        if (isNumber(value)) {
+            return this.#tedious.TYPES.Float;
+        }
+        if (isBoolean(value)) {
+            return this.#tedious.TYPES.Bit;
+        }
+        if (isDate(value)) {
+            return this.#tedious.TYPES.DateTime;
+        }
+        if (isBuffer(value)) {
+            return this.#tedious.TYPES.VarBinary;
+        }
+        return this.#tedious.TYPES.NVarChar;
+    }
+}

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

@@ -0,0 +1,20 @@
+import { Kysely } from '../../kysely.js';
+import { DatabaseIntrospector, DatabaseMetadata, DatabaseMetadataOptions, SchemaMetadata, TableMetadata } from '../database-introspector.js';
+export declare class MssqlIntrospector implements DatabaseIntrospector {
+    #private;
+    constructor(db: Kysely<any>);
+    /**
+     * Get schema metadata.
+     */
+    getSchemas(): Promise<SchemaMetadata[]>;
+    /**
+     * Get tables and views metadata.
+     */
+    getTables(options?: DatabaseMetadataOptions): Promise<TableMetadata[]>;
+    /**
+     * Get the database metadata such as table and column names.
+     *
+     * @deprecated Use getTables() instead.
+     */
+    getMetadata(options?: DatabaseMetadataOptions): Promise<DatabaseMetadata>;
+}