kysely 0.10.1 → 0.11.0

package/dist/cjs/query-creator.js

@@ -29,20 +29,17 @@ class QueryCreator {
     /**
      * Creates an insert query.
      *
-     * The return value of this query is `number | undefined` because of the differences
-     * between database engines. Most engines (like Mysql) return the auto incrementing
-     * primary key (if it exists), but some (like postgres) return nothing by default.
-     * If you are running a database engine like `Mysql` that always returns the primary
-     * key, you can safely use `!` or the {@link QueryBuilder.castTo | castTo} method
-     * to cast away the `undefined` from the type.
+     * The return value of this query is an instance of {@link InsertResult}. {@link InsertResult}
+     * has the {@link InsertResult.insertId | insertId} field that holds the auto incremented id of
+     * the inserted row if the db returned one.
      *
      * See the {@link QueryBuilder.values | values} method for more info and examples. Also see
      * the {@link QueryBuilder.returning | returning} method for a way to return columns
-     * on supported databases like postgres.
+     * on supported databases like PostgreSQL.
      *
      * @example
      * ```ts
-     * const maybePrimaryKey: number | undefined = await db
+     * const result = await db
      *   .insertInto('person')
      *   .values({
      *     id: db.generated,
@@ -50,10 +47,12 @@ class QueryCreator {
      *     last_name: 'Aniston'
      *   })
      *   .executeTakeFirst()
+     *
+     * console.log(result.insertId)
      * ```
      *
      * @example
-     * Some databases like postgres support the `returning` method:
+     * Some databases like PostgreSQL support the `returning` method:
      *
      * ```ts
      * const { id } = await db
@@ -79,14 +78,18 @@ class QueryCreator {
      * Creates a delete query.
      *
      * See the {@link QueryBuilder.where} method for examples on how to specify
-     * a where clause for the delete operation .
+     * a where clause for the delete operation.
+     *
+     * The return value of the query is an instance of {@link DeleteResult}.
      *
      * @example
      * ```ts
-     * const numAffectedRows = await db
+     * const result = await db
      *   .deleteFrom('person')
      *   .where('person.id', '=', 1)
      *   .executeTakeFirst()
+     *
+     * console.log(result.numDeletedRows)
      * ```
      */
     deleteFrom(table) {
@@ -106,13 +109,17 @@ class QueryCreator {
      * See the {@link QueryBuilder.set} method for examples on how to
      * specify the updates.
      *
+     * The return value of the query is an {@link UpdateResult}.
+     *
      * @example
      * ```ts
-     * const numAffectedRows = await db
+     * const result = await db
      *   .updateTable('person')
      *   .set({ first_name: 'Jennifer' })
      *   .where('person.id', '=', 1)
      *   .executeTakeFirst()
+     *
+     * console.log(result.numUpdatedRows)
      * ```
      */
     updateTable(table) {
@@ -170,7 +177,7 @@ class QueryCreator {
      *  .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "mammals"."pet"
@@ -190,7 +197,7 @@ class QueryCreator {
      *  .execute()
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select "p"."name" from "mammals"."pet" as "p"
@@ -240,7 +247,7 @@ class QueryCreator {
      * console.log(person.name)
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select concat(first_name, ' ', last_name) as "name"
@@ -298,7 +305,7 @@ class QueryCreator {
      * }
      * ```
      *
-     * The generated SQL (postgresql):
+     * The generated SQL (PostgreSQL):
      *
      * ```sql
      * select * from "person" where now() - birth_date > interval $1 year
@@ -312,7 +319,8 @@ class QueryCreator {
      * Example of creating a completely raw query from scratch:
      *
      * ```ts
-     * const persons = await db.raw<Person>('select p.* from person p').execute()
+     * const result = await db.raw<Person>('select p.* from person p').execute()
+     * const persons = result.rows
      * ```
      *
      * For a raw query, you need to specify the type of the returned __row__. In

package/dist/cjs/schema/create-view-builder.d.ts

@@ -10,6 +10,10 @@ export declare class CreateViewBuilder implements OperationNodeSource, Compilabl
     #private;
     constructor(props: CreateViewBuilderProps);
     materialized(): CreateViewBuilder;
+    /**
+     * Only implemented on some dialects like SQLite. On most dialects, use {@link orReplace}.
+     */
+    ifNotExists(): CreateViewBuilder;
     orReplace(): CreateViewBuilder;
     columns(columns: string[]): CreateViewBuilder;
     as(query: AnyQueryBuilder | AnyRawBuilder): CreateViewBuilder;

package/dist/cjs/schema/create-view-builder.js

@@ -31,6 +31,17 @@ class CreateViewBuilder {
             }),
         });
     }
+    /**
+     * Only implemented on some dialects like SQLite. On most dialects, use {@link orReplace}.
+     */
+    ifNotExists() {
+        return new CreateViewBuilder({
+            ...this.#props,
+            createViewNode: create_view_node_js_1.CreateViewNode.cloneWith(this.#props.createViewNode, {
+                ifNotExists: true,
+            }),
+        });
+    }
     orReplace() {
         return new CreateViewBuilder({
             ...this.#props,

package/dist/cjs/util/dynamic-import.d.ts

@@ -0,0 +1,2 @@
+export declare function importFunction<T extends Function>(modulePath: string): Promise<T>;
+export declare function importNamedFunction<T extends Function>(modulePath: string, exportName: string): Promise<T>;

package/dist/cjs/util/dynamic-import.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.importNamedFunction = exports.importFunction = void 0;
+const object_utils_js_1 = require("./object-utils.js");
+async function importFunction(modulePath) {
+    const module = await Promise.resolve().then(() => require(modulePath));
+    const errorMessage = `module "${modulePath}" doesn export a function`;
+    if ((0, object_utils_js_1.isFunction)(module)) {
+        return module;
+    }
+    else if ((0, object_utils_js_1.isObject)(module) && (0, object_utils_js_1.isFunction)(module.default)) {
+        return module.default;
+    }
+    throw new Error(errorMessage);
+}
+exports.importFunction = importFunction;
+async function importNamedFunction(modulePath, exportName) {
+    const module = await Promise.resolve().then(() => require(modulePath));
+    const errorMessage = `no function export named "${exportName}" found in module "${modulePath}"`;
+    if (!(0, object_utils_js_1.isObject)(module)) {
+        throw new Error(errorMessage);
+    }
+    if ((0, object_utils_js_1.isFunction)(module[exportName])) {
+        return module[exportName];
+    }
+    else if ((0, object_utils_js_1.isObject)(module.default) &&
+        (0, object_utils_js_1.isFunction)(module.default[exportName])) {
+        return module.default[exportName];
+    }
+    throw new Error(errorMessage);
+}
+exports.importNamedFunction = importNamedFunction;

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

@@ -1,6 +1,9 @@
 import { AliasedRawBuilder, RawBuilder } from '../raw-builder/raw-builder.js';
 import { AliasedQueryBuilder, QueryBuilder } from '../query-builder/query-builder.js';
 import { ExpressionBuilder } from '../query-builder/expression-builder.js';
+import { InsertResult } from '../query-builder/insert-result.js';
+import { DeleteResult } from '../query-builder/delete-result.js';
+import { UpdateResult } from '../query-builder/update-result.js';
 /**
  * Given an object type, extracts the union of all value types.
  */
@@ -134,25 +137,11 @@ export declare type QueryBuilderFactory<DB, TB extends keyof DB> = (qb: Expressi
 export declare type AliasedQueryBuilderFactory<DB, TB extends keyof DB> = (qb: ExpressionBuilder<DB, TB>) => AnyAliasedQueryBuilder;
 export declare type RawBuilderFactory<DB, TB extends keyof DB> = (qb: ExpressionBuilder<DB, TB>) => AnyRawBuilder;
 export declare type AliasedRawBuilderFactory<DB, TB extends keyof DB> = (qb: ExpressionBuilder<DB, TB>) => AnyAliasedRawBuilder;
-export interface InsertResultTypeTag {
-    /** @internal */
-    readonly __isInsertResultTypeTag__: true;
-}
-export interface DeleteResultTypeTag {
-    /** @internal */
-    readonly __isDeleteResultTypeTag__: true;
-}
-export interface UpdateResultTypeTag {
-    /** @internal */
-    readonly __isUpdateResultTypeTag__: true;
-}
 export interface GeneratedPlaceholder {
     /** @internal */
     readonly __isGeneratedPlaceholder__: true;
 }
-export declare type ManyResultRowType<O> = O extends InsertResultTypeTag ? number | undefined : O extends DeleteResultTypeTag ? number : O extends UpdateResultTypeTag ? number : O;
-export declare type SingleResultRowType<O> = O extends InsertResultTypeTag ? number | undefined : O extends DeleteResultTypeTag ? number : O extends UpdateResultTypeTag ? number : O | undefined;
-export declare type NonEmptySingleResultRowType<O> = O extends InsertResultTypeTag ? number : O extends DeleteResultTypeTag ? number : O extends UpdateResultTypeTag ? number : O;
+export declare type SingleResultType<O> = O extends InsertResult ? O : O extends DeleteResult ? O : O extends UpdateResult ? O : O | undefined;
 export declare type UnknownRow = Record<string, unknown>;
 export declare type Nullable<T> = {
     [P in keyof T]: T[P] | null;

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

@@ -24,7 +24,7 @@ export interface DialectAdapter {
      * it's not possible for two migration processes to run in parallel.
      *
      * Most dialects have explicit locks that can be used, like advisory locks
-     * in postgres and the get_lock function in mysql.
+     * in PostgreSQL and the get_lock function in MySQL.
      *
      * If the dialect doesn't have explicit locks the {@link MIGRATION_LOCK_TABLE}
      * created by Kysely can be used instead. {@link MIGRATION_LOCK_TABLE}
@@ -44,7 +44,8 @@ export interface DialectAdapter {
      *
      * 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.
+     * is a single connection (session) that was used to execute the migrations
+     * and the `acquireMigrationLock` call.
      */
     releaseMigrationLock(db: Kysely<any>): Promise<void>;
 }

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

@@ -13,7 +13,7 @@ export class MysqlAdapter {
         // released when the connection is destroyed (session ends) or when the lock
         // is released using `release_lock`. This way we know that the lock is either
         // released by us after successfull or failed migrations OR it's released by
-        // mysql if the process gets killed for some reason.
+        // MySQL if the process gets killed for some reason.
         await db
             .raw(`select get_lock('${LOCK_ID}', ${LOCK_TIMEOUT_SECONDS})`)
             .execute();

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

@@ -21,7 +21,7 @@ export declare class MysqlDialect implements Dialect {
     createIntrospector(db: Kysely<any>): DatabaseIntrospector;
 }
 /**
- * Config for the mysql dialect.
+ * Config for the MySQL dialect.
  *
  * This interface is equal to `mysql2` library's pool config.
  *
@@ -137,7 +137,7 @@ export interface MysqlDialectConfig {
      */
     trace?: boolean;
     /**
-     * Allow multiple mysql statements per query. Be careful with this, it exposes you to SQL injection attacks. (Default: false)
+     * Allow multiple MySQL statements per query. Be careful with this, it exposes you to SQL injection attacks. (Default: false)
      */
     multipleStatements?: boolean;
     /**
@@ -186,7 +186,7 @@ export interface MysqlDialectConfig {
     /**
      * Called once for each created connection.
      *
-     * This is a Kysely specific feature and does not come from the `pg` module.
+     * This is a Kysely specific feature and does not come from the `mysql2` module.
      */
     onCreateConnection?: (connection: DatabaseConnection) => Promise<void>;
 }

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

@@ -1,4 +1,6 @@
-import { isFunction, isNumber, isObject } from '../../util/object-utils.js';
+import { CompiledQuery } from '../../query-compiler/compiled-query.js';
+import { importNamedFunction } from '../../util/dynamic-import.js';
+import { isObject } from '../../util/object-utils.js';
 const PRIVATE_RELEASE_METHOD = Symbol();
 export class MysqlDriver {
     #config;
@@ -47,19 +49,16 @@ export class MysqlDriver {
     }
     async beginTransaction(connection, settings) {
         if (settings.isolationLevel) {
-            // On mysql this sets the isolation level of the next transaction.
-            await connection.executeQuery({
-                sql: `set transaction isolation level ${settings.isolationLevel}`,
-                parameters: [],
-            });
+            // On MySQL this sets the isolation level of the next transaction.
+            await connection.executeQuery(CompiledQuery.raw(`set transaction isolation level ${settings.isolationLevel}`));
         }
-        await connection.executeQuery({ sql: 'begin', parameters: [] });
+        await connection.executeQuery(CompiledQuery.raw('begin'));
     }
     async commitTransaction(connection) {
-        await connection.executeQuery({ sql: 'commit', parameters: [] });
+        await connection.executeQuery(CompiledQuery.raw('commit'));
     }
     async rollbackTransaction(connection) {
-        await connection.executeQuery({ sql: 'rollback', parameters: [] });
+        await connection.executeQuery(CompiledQuery.raw('rollback'));
     }
     async releaseConnection(connection) {
         const mysqlConnection = connection;
@@ -80,19 +79,10 @@ export class MysqlDriver {
 }
 async function importMysqlPoolFactory() {
     try {
-        // For this to work with both esm and cjs modules we need
-        // this hacky crap here.
-        const mysql = (await import('mysql2'));
-        if (isFunction(mysql.createPool)) {
-            return mysql.createPool;
-        }
-        else {
-            // With esm the imported module doesn't match the typings.
-            return mysql.default.createPool;
-        }
+        return await importNamedFunction('mysql2', 'createPool');
     }
     catch (error) {
-        throw new Error('Mysql client not installed. Please run `npm install mysql2`');
+        throw new Error('MySQL client not installed. Please run `npm install mysql2`');
     }
 }
 class MysqlConnection {
@@ -102,19 +92,19 @@ class MysqlConnection {
     }
     async executeQuery(compiledQuery) {
         const result = await this.#executeQuery(compiledQuery);
-        if (isObject(result) && 'insertId' in result && 'affectedRows' in result) {
-            if (isNumber(result.insertId) && result.insertId > 0) {
-                return {
-                    insertedPrimaryKey: result.insertId,
-                    rows: [],
-                };
-            }
-            else if (isNumber(result.affectedRows)) {
-                return {
-                    numUpdatedOrDeletedRows: result.affectedRows,
-                    rows: [],
-                };
-            }
+        if (isOkPacket(result)) {
+            const { insertId, affectedRows } = result;
+            return {
+                insertId: insertId !== undefined &&
+                    insertId !== null &&
+                    insertId.toString() !== '0'
+                    ? BigInt(insertId)
+                    : undefined,
+                numUpdatedOrDeletedRows: affectedRows !== undefined && insertId !== null
+                    ? BigInt(affectedRows)
+                    : undefined,
+                rows: [],
+            };
         }
         else if (Array.isArray(result)) {
             return {
@@ -141,3 +131,6 @@ class MysqlConnection {
         this.#rawConnection.release();
     }
 }
+function isOkPacket(obj) {
+    return isObject(obj) && 'insertId' in obj && 'affectedRows' in obj;
+}

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

@@ -27,7 +27,7 @@ export declare class PostgresDialect implements Dialect {
     createIntrospector(db: Kysely<any>): DatabaseIntrospector;
 }
 /**
- * Config for the postgres dialect.
+ * Config for the PostgreSQL dialect.
  *
  * This interface is equal to `pg` library's `Pool` config:
  *
@@ -91,7 +91,7 @@ export interface PostgresDialectConfig {
      *
      * Setting `allowExitOnIdle: true` in the config will allow the node event loop to exit
      * as soon as all clients in the pool are idle, even if their socket is still open
-     * to the postgres server.  This can be handy in scripts & tests
+     * to the PostgreSQL server.  This can be handy in scripts & tests
      * where you don't want to wait for your clients to go idle before your process exits.
      */
     allowExitOnIdle?: boolean;

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

@@ -1,4 +1,5 @@
-import { isFunction } from '../../util/object-utils.js';
+import { CompiledQuery } from '../../query-compiler/compiled-query.js';
+import { importNamedFunction } from '../../util/dynamic-import.js';
 const PRIVATE_RELEASE_METHOD = Symbol();
 export class PostgresDriver {
     #config;
@@ -35,20 +36,17 @@ export class PostgresDriver {
     }
     async beginTransaction(connection, settings) {
         if (settings.isolationLevel) {
-            await connection.executeQuery({
-                sql: `start transaction isolation level ${settings.isolationLevel}`,
-                parameters: [],
-            });
+            await connection.executeQuery(CompiledQuery.raw(`start transaction isolation level ${settings.isolationLevel}`));
         }
         else {
-            await connection.executeQuery({ sql: 'begin', parameters: [] });
+            await connection.executeQuery(CompiledQuery.raw('begin'));
         }
     }
     async commitTransaction(connection) {
-        await connection.executeQuery({ sql: 'commit', parameters: [] });
+        await connection.executeQuery(CompiledQuery.raw('commit'));
     }
     async rollbackTransaction(connection) {
-        await connection.executeQuery({ sql: 'rollback', parameters: [] });
+        await connection.executeQuery(CompiledQuery.raw('rollback'));
     }
     async releaseConnection(connection) {
         const pgConnection = connection;
@@ -64,16 +62,7 @@ export class PostgresDriver {
 }
 async function importPgPool() {
     try {
-        // For this to work with both esm and cjs modules we need
-        // this hacky crap here.
-        const pg = (await import('pg'));
-        if (isFunction(pg.Pool)) {
-            return pg.Pool;
-        }
-        else {
-            // With esm the imported module doesn't match the typings.
-            return pg.default.Pool;
-        }
+        return await importNamedFunction('pg', 'Pool');
     }
     catch (error) {
         throw new Error('Postgres client not installed. Please run `npm install pg`');
@@ -90,7 +79,7 @@ class PostgresConnection {
         ]);
         if (result.command === 'UPDATE' || result.command === 'DELETE') {
             return {
-                numUpdatedOrDeletedRows: result.rowCount,
+                numUpdatedOrDeletedRows: BigInt(result.rowCount),
                 rows: result.rows ?? [],
             };
         }

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

@@ -0,0 +1,7 @@
+import { DialectAdapter } from '../dialect-adapter.js';
+export declare class SqliteAdapter implements DialectAdapter {
+    get supportsTransactionalDdl(): boolean;
+    get supportsReturning(): boolean;
+    acquireMigrationLock(): Promise<void>;
+    releaseMigrationLock(): Promise<void>;
+}

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

@@ -0,0 +1,14 @@
+export class SqliteAdapter {
+    get supportsTransactionalDdl() {
+        return false;
+    }
+    get supportsReturning() {
+        return false;
+    }
+    async acquireMigrationLock() {
+        // Nothing to do here.
+    }
+    async releaseMigrationLock() {
+        // Nothing to do here.
+    }
+}

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

@@ -0,0 +1,64 @@
+import { Driver } from '../../driver/driver.js';
+import { Kysely } from '../../kysely.js';
+import { QueryCompiler } from '../../query-compiler/query-compiler.js';
+import { Dialect } from '../dialect.js';
+import { DatabaseIntrospector } from '../../introspection/database-introspector.js';
+import { DialectAdapter } from '../dialect-adapter.js';
+import { DatabaseConnection } from '../../driver/database-connection.js';
+/**
+ * SQLite dialect that uses the [better-sqlite3](https://github.com/JoshuaWise/better-sqlite3) library.
+ *
+ * The {@link SqliteDialectConfig | configuration} is used to construct an instance of
+ * [Database](https://github.com/JoshuaWise/better-sqlite3/blob/master/docs/api.md#new-databasepath-options)
+ * class. The configuration values are passed directly to the `Database` constructor.
+ */
+export declare class SqliteDialect implements Dialect {
+    #private;
+    constructor(config: SqliteDialectConfig);
+    createDriver(): Driver;
+    createQueryCompiler(): QueryCompiler;
+    createAdapter(): DialectAdapter;
+    createIntrospector(db: Kysely<any>): DatabaseIntrospector;
+}
+/**
+ * Config for the SQLite dialect.
+ *
+ * This interface is equal to `better-sqlite3` library's `Databse` class's constructor parameters.
+ *
+ * https://github.com/JoshuaWise/better-sqlite3/blob/master/docs/api.md#new-databasepath-options
+ */
+export interface SqliteDialectConfig {
+    /**
+     * The database file path.
+     *
+     * This is passed as the first argument for the [Database](https://github.com/JoshuaWise/better-sqlite3/blob/master/docs/api.md#new-databasepath-options)
+     * class constructor.
+     */
+    databasePath: string;
+    /**
+     * Open the database connection in readonly mode (default: false)
+     */
+    readonly?: boolean;
+    /**
+     * If the database does not exist, an Error will be thrown instead of creating a new file.
+     * This option is ignored for in-memory, temporary, or readonly database connections
+     * (default: false)
+     */
+    fileMustExist?: boolean;
+    /**
+     * The number of milliseconds to wait when executing queries on a locked database,
+     * before throwing a SQLITE_BUSY error (default: 5000)
+     */
+    timeout?: number;
+    /**
+     * Provide a function that gets called with every SQL string executed by the database connection
+     * (default: null)
+     */
+    verbose?: (sql: string) => void;
+    /**
+     * Called once when the first query is executed.
+     *
+     * This is a Kysely specific feature and does not come from the `better-sqlite3` module.
+     */
+    onCreateConnection?: (connection: DatabaseConnection) => Promise<void>;
+}

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

@@ -0,0 +1,29 @@
+import { SqliteDriver } from './sqlite-driver.js';
+import { SqliteQueryCompiler } from './sqlite-query-compiler.js';
+import { SqliteIntrospector } from './sqlite-introspector.js';
+import { SqliteAdapter } from './sqlite-adapter.js';
+/**
+ * SQLite dialect that uses the [better-sqlite3](https://github.com/JoshuaWise/better-sqlite3) library.
+ *
+ * The {@link SqliteDialectConfig | configuration} is used to construct an instance of
+ * [Database](https://github.com/JoshuaWise/better-sqlite3/blob/master/docs/api.md#new-databasepath-options)
+ * class. The configuration values are passed directly to the `Database` constructor.
+ */
+export class SqliteDialect {
+    #config;
+    constructor(config) {
+        this.#config = config;
+    }
+    createDriver() {
+        return new SqliteDriver(this.#config);
+    }
+    createQueryCompiler() {
+        return new SqliteQueryCompiler();
+    }
+    createAdapter() {
+        return new SqliteAdapter();
+    }
+    createIntrospector(db) {
+        return new SqliteIntrospector(db);
+    }
+}

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

@@ -0,0 +1,14 @@
+import { DatabaseConnection } from '../../driver/database-connection.js';
+import { Driver } from '../../driver/driver.js';
+import { SqliteDialectConfig } from './sqlite-dialect.js';
+export declare class SqliteDriver implements Driver {
+    #private;
+    constructor(config: SqliteDialectConfig);
+    init(): Promise<void>;
+    acquireConnection(): Promise<DatabaseConnection>;
+    beginTransaction(connection: DatabaseConnection): Promise<void>;
+    commitTransaction(connection: DatabaseConnection): Promise<void>;
+    rollbackTransaction(connection: DatabaseConnection): Promise<void>;
+    releaseConnection(): Promise<void>;
+    destroy(): Promise<void>;
+}