kysely 0.11.3 → 0.12.2

package/README.md

@@ -72,7 +72,7 @@ interface Person {
   first_name: string
   // If the column is nullable in the db, make its type nullable.
   // Don't use optional properties.
-  last_name: string | null
+  last_name: string | null
   gender: 'male' | 'female' | 'other'
 }
 

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

@@ -7,8 +7,44 @@ import { DialectAdapter } 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 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 processes 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 MIGRATION_LOCK_TABLE}
+     * created by Kysely can be used instead. {@link MIGRATION_LOCK_TABLE}
+     * has two columns `id` and `is_locked` and there's only one row in the
+     * table whose id is {@link MIGRATION_LOCK_ID}. `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 `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.
+     */
     abstract 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.
+     */
     abstract releaseMigrationLock(db: Kysely<any>): Promise<void>;
 }

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

@@ -1,8 +1,44 @@
 import { Kysely } from '../../kysely.js';
 import { DialectAdapter } from '../dialect-adapter.js';
 export declare class MysqlAdapter implements DialectAdapter {
+    /**
+     * 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 processes 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 MIGRATION_LOCK_TABLE}
+     * created by Kysely can be used instead. {@link MIGRATION_LOCK_TABLE}
+     * has two columns `id` and `is_locked` and there's only one row in the
+     * table whose id is {@link MIGRATION_LOCK_ID}. `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 `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(db: Kysely<any>): Promise<void>;
 }

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

@@ -15,9 +15,25 @@ import { DatabaseConnection } from '../../driver/database-connection.js';
 export declare class MysqlDialect implements Dialect {
     #private;
     constructor(config: MysqlDialectConfig);
+    /**
+     * 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 the database metadata
+     * such as the tables and columns that exist in the database.
+     *
+     * `db` never has any plugins installed. It's created using
+     * {@link Kysely.withoutPlugins}.
+     */
     createIntrospector(db: Kysely<any>): DatabaseIntrospector;
 }
 /**

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

@@ -4,11 +4,40 @@ import { MysqlDialectConfig } from './mysql-dialect.js';
 export declare class MysqlDriver implements Driver {
     #private;
     constructor(config: MysqlDialectConfig);
+    /**
+     * Initializes the driver.
+     *
+     * After calling this method the driver should be usable and `acquireConnection` etc.
+     * methods should be callable.
+     *
+     * IMPORTANT: The underlying database engine driver (like [pg](https://node-postgres.com/))
+     * should be imported inside this function, not at the top of the driver file! This is
+     * important so that Kysely is usable without installing all database driver libraries
+     * it supports.
+     */
     init(): Promise<void>;
+    /**
+     * Acquires a new connection from the pool.
+     */
     acquireConnection(): Promise<DatabaseConnection>;
+    /**
+     * Begins a transaction.
+     */
     beginTransaction(connection: DatabaseConnection, settings: TransactionSettings): Promise<void>;
+    /**
+     * Commits a transaction.
+     */
     commitTransaction(connection: DatabaseConnection): Promise<void>;
+    /**
+     * Rolls back a transaction.
+     */
     rollbackTransaction(connection: DatabaseConnection): Promise<void>;
+    /**
+     * Releases a connection back to the pool.
+     */
     releaseConnection(connection: DatabaseConnection): Promise<void>;
+    /**
+     * Destroys the driver and releases all resources.
+     */
     destroy(): Promise<void>;
 }

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

@@ -3,5 +3,8 @@ import { Kysely } from '../../kysely.js';
 export declare class MysqlIntrospector implements DatabaseIntrospector {
     #private;
     constructor(db: Kysely<any>);
+    /**
+     * Get the database metadata such as the names of the tables and columns.
+     */
     getMetadata(options?: DatabaseMetadataOptions): Promise<DatabaseMetadata>;
 }

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

@@ -1,8 +1,44 @@
 import { Kysely } from '../../kysely.js';
 import { DialectAdapter } from '../dialect-adapter.js';
 export declare class PostgresAdapter implements DialectAdapter {
+    /**
+     * 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 processes 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 MIGRATION_LOCK_TABLE}
+     * created by Kysely can be used instead. {@link MIGRATION_LOCK_TABLE}
+     * has two columns `id` and `is_locked` and there's only one row in the
+     * table whose id is {@link MIGRATION_LOCK_ID}. `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 `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/cjs/dialect/postgres/postgres-dialect.d.ts

@@ -21,9 +21,25 @@ import { DatabaseConnection } from '../../driver/database-connection.js';
 export declare class PostgresDialect implements Dialect {
     #private;
     constructor(config: PostgresDialectConfig);
+    /**
+     * 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 the database metadata
+     * such as the tables and columns that exist in the database.
+     *
+     * `db` never has any plugins installed. It's created using
+     * {@link Kysely.withoutPlugins}.
+     */
     createIntrospector(db: Kysely<any>): DatabaseIntrospector;
 }
 /**

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

@@ -4,11 +4,40 @@ import { PostgresDialectConfig } from './postgres-dialect.js';
 export declare class PostgresDriver implements Driver {
     #private;
     constructor(config: PostgresDialectConfig);
+    /**
+     * Initializes the driver.
+     *
+     * After calling this method the driver should be usable and `acquireConnection` etc.
+     * methods should be callable.
+     *
+     * IMPORTANT: The underlying database engine driver (like [pg](https://node-postgres.com/))
+     * should be imported inside this function, not at the top of the driver file! This is
+     * important so that Kysely is usable without installing all database driver libraries
+     * it supports.
+     */
     init(): Promise<void>;
+    /**
+     * Acquires a new connection from the pool.
+     */
     acquireConnection(): Promise<DatabaseConnection>;
+    /**
+     * Begins a transaction.
+     */
     beginTransaction(connection: DatabaseConnection, settings: TransactionSettings): Promise<void>;
+    /**
+     * Commits a transaction.
+     */
     commitTransaction(connection: DatabaseConnection): Promise<void>;
+    /**
+     * Rolls back a transaction.
+     */
     rollbackTransaction(connection: DatabaseConnection): Promise<void>;
+    /**
+     * Releases a connection back to the pool.
+     */
     releaseConnection(connection: DatabaseConnection): Promise<void>;
+    /**
+     * Destroys the driver and releases all resources.
+     */
     destroy(): Promise<void>;
 }

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

@@ -3,5 +3,8 @@ import { Kysely } from '../../kysely.js';
 export declare class PostgresIntrospector implements DatabaseIntrospector {
     #private;
     constructor(db: Kysely<any>);
+    /**
+     * Get the database metadata such as the names of the tables and columns.
+     */
     getMetadata(options?: DatabaseMetadataOptions): Promise<DatabaseMetadata>;
 }

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

@@ -1,7 +1,43 @@
 import { DialectAdapter } from '../dialect-adapter.js';
 export declare class SqliteAdapter implements DialectAdapter {
+    /**
+     * 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 processes 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 MIGRATION_LOCK_TABLE}
+     * created by Kysely can be used instead. {@link MIGRATION_LOCK_TABLE}
+     * has two columns `id` and `is_locked` and there's only one row in the
+     * table whose id is {@link MIGRATION_LOCK_ID}. `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 `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(): 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/cjs/dialect/sqlite/sqlite-adapter.js

@@ -9,10 +9,14 @@ class SqliteAdapter {
         return false;
     }
     async acquireMigrationLock() {
-        // Nothing to do here.
+        // SQLite only has one connection that's reserved by the migration system
+        // for the whole time between acquireMigrationLock and releaseMigrationLock.
+        // We don't need to do anything here.
     }
     async releaseMigrationLock() {
-        // Nothing to do here.
+        // SQLite only has one connection that's reserved by the migration system
+        // for the whole time between acquireMigrationLock and releaseMigrationLock.
+        // We don't need to do anything here.
     }
 }
 exports.SqliteAdapter = SqliteAdapter;

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

@@ -15,9 +15,25 @@ import { DatabaseConnection } from '../../driver/database-connection.js';
 export declare class SqliteDialect implements Dialect {
     #private;
     constructor(config: SqliteDialectConfig);
+    /**
+     * 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 the database metadata
+     * such as the tables and columns that exist in the database.
+     *
+     * `db` never has any plugins installed. It's created using
+     * {@link Kysely.withoutPlugins}.
+     */
     createIntrospector(db: Kysely<any>): DatabaseIntrospector;
 }
 /**

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

@@ -4,11 +4,40 @@ import { SqliteDialectConfig } from './sqlite-dialect.js';
 export declare class SqliteDriver implements Driver {
     #private;
     constructor(config: SqliteDialectConfig);
+    /**
+     * Initializes the driver.
+     *
+     * After calling this method the driver should be usable and `acquireConnection` etc.
+     * methods should be callable.
+     *
+     * IMPORTANT: The underlying database engine driver (like [pg](https://node-postgres.com/))
+     * should be imported inside this function, not at the top of the driver file! This is
+     * important so that Kysely is usable without installing all database driver libraries
+     * it supports.
+     */
     init(): Promise<void>;
+    /**
+     * Acquires a new connection from the pool.
+     */
     acquireConnection(): Promise<DatabaseConnection>;
+    /**
+     * Begins a transaction.
+     */
     beginTransaction(connection: DatabaseConnection): Promise<void>;
+    /**
+     * Commits a transaction.
+     */
     commitTransaction(connection: DatabaseConnection): Promise<void>;
+    /**
+     * Rolls back a transaction.
+     */
     rollbackTransaction(connection: DatabaseConnection): Promise<void>;
+    /**
+     * Releases a connection back to the pool.
+     */
     releaseConnection(): Promise<void>;
+    /**
+     * Destroys the driver and releases all resources.
+     */
     destroy(): Promise<void>;
 }

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

@@ -3,5 +3,8 @@ import { Kysely } from '../../kysely.js';
 export declare class SqliteIntrospector implements DatabaseIntrospector {
     #private;
     constructor(db: Kysely<any>);
+    /**
+     * Get the database metadata such as the names of the tables and columns.
+     */
     getMetadata(options?: DatabaseMetadataOptions): Promise<DatabaseMetadata>;
 }

package/dist/cjs/driver/default-connection-provider.d.ts

@@ -4,5 +4,9 @@ import { Driver } from './driver.js';
 export declare class DefaultConnectionProvider implements ConnectionProvider {
     #private;
     constructor(driver: Driver);
+    /**
+     * Provides a connection for the callback and takes care of disposing
+     * the connection after the callback has been run.
+     */
     withConnection<T>(runner: (connection: DatabaseConnection) => Promise<T>): Promise<T>;
 }

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

@@ -9,11 +9,40 @@ import { Driver, TransactionSettings } from './driver.js';
 export declare class RuntimeDriver implements Driver {
     #private;
     constructor(driver: Driver, log: Log);
+    /**
+     * Initializes the driver.
+     *
+     * After calling this method the driver should be usable and `acquireConnection` etc.
+     * methods should be callable.
+     *
+     * IMPORTANT: The underlying database engine driver (like [pg](https://node-postgres.com/))
+     * should be imported inside this function, not at the top of the driver file! This is
+     * important so that Kysely is usable without installing all database driver libraries
+     * it supports.
+     */
     init(): Promise<void>;
+    /**
+     * Acquires a new connection from the pool.
+     */
     acquireConnection(): Promise<DatabaseConnection>;
+    /**
+     * Releases a connection back to the pool.
+     */
     releaseConnection(runtimeConnection: DatabaseConnection): Promise<void>;
+    /**
+     * Begins a transaction.
+     */
     beginTransaction(connection: DatabaseConnection, settings: TransactionSettings): Promise<void>;
+    /**
+     * Commits a transaction.
+     */
     commitTransaction(connection: DatabaseConnection): Promise<void>;
+    /**
+     * Rolls back a transaction.
+     */
     rollbackTransaction(connection: DatabaseConnection): Promise<void>;
+    /**
+     * Destroys the driver and releases all resources.
+     */
     destroy(): Promise<void>;
 }

package/dist/cjs/driver/single-connection-provider.d.ts

@@ -3,5 +3,9 @@ import { ConnectionProvider } from './connection-provider.js';
 export declare class SingleConnectionProvider implements ConnectionProvider {
     #private;
     constructor(connection: DatabaseConnection);
+    /**
+     * Provides a connection for the callback and takes care of disposing
+     * the connection after the callback has been run.
+     */
     withConnection<T>(runner: (connection: DatabaseConnection) => Promise<T>): Promise<T>;
 }

package/dist/cjs/dynamic/dynamic-reference-builder.d.ts

@@ -16,3 +16,4 @@ export declare class DynamicReferenceBuilder<R extends string = never> implement
     constructor(reference: string);
     toOperationNode(): ReferenceNode | ColumnNode;
 }
+export declare function isDynamicReferenceBuilder(obj: unknown): obj is DynamicReferenceBuilder<any>;

package/dist/cjs/dynamic/dynamic-reference-builder.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DynamicReferenceBuilder = void 0;
+exports.isDynamicReferenceBuilder = exports.DynamicReferenceBuilder = void 0;
+const operation_node_source_js_1 = require("../operation-node/operation-node-source.js");
 const reference_parser_js_1 = require("../parser/reference-parser.js");
+const object_utils_js_1 = require("../util/object-utils.js");
 class DynamicReferenceBuilder {
     #dynamicReference;
     get dynamicReference() {
@@ -26,3 +28,9 @@ class DynamicReferenceBuilder {
     }
 }
 exports.DynamicReferenceBuilder = DynamicReferenceBuilder;
+function isDynamicReferenceBuilder(obj) {
+    return ((0, object_utils_js_1.isObject)(obj) &&
+        (0, operation_node_source_js_1.isOperationNodeSource)(obj) &&
+        (0, object_utils_js_1.isString)(obj.dynamicReference));
+}
+exports.isDynamicReferenceBuilder = isDynamicReferenceBuilder;

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

@@ -20,7 +20,8 @@ export declare class DynamicModule {
      * `ref` to other methods as well. If the types allow you to pass a `ref`
      * value to some place, it should work.
      *
-     * @example
+     * ### Examples
+     *
      * Filter by a column not know at compile time:
      *
      * ```ts
@@ -38,7 +39,6 @@ export declare class DynamicModule {
      * someQuery('person.last_name', 'Aniston')
      * ```
      *
-     * @example
      * Order by a column not know at compile time:
      *
      * ```ts
@@ -55,7 +55,6 @@ export declare class DynamicModule {
      * someQuery('fn')
      * ```
      *
-     * @example
      * In this example we add selections dynamically:
      *
      * ```ts
@@ -66,7 +65,7 @@ export declare class DynamicModule {
      *
      * // 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' | 'birth_date'
      *
      * const [person] = await db.selectFrom('person')
      *   .select([
@@ -78,9 +77,9 @@ 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 | undefined = person.last_name
+     * const firstName: string | undefined = person.first_name
+     * const birthDate: string | undefined = person.birth_date
      *
      * // The result type also contains the compile time selection `id`.
      * person.id

package/dist/cjs/dynamic/dynamic.js

@@ -23,7 +23,8 @@ class DynamicModule {
      * `ref` to other methods as well. If the types allow you to pass a `ref`
      * value to some place, it should work.
      *
-     * @example
+     * ### Examples
+     *
      * Filter by a column not know at compile time:
      *
      * ```ts
@@ -41,7 +42,6 @@ class DynamicModule {
      * someQuery('person.last_name', 'Aniston')
      * ```
      *
-     * @example
      * Order by a column not know at compile time:
      *
      * ```ts
@@ -58,7 +58,6 @@ class DynamicModule {
      * someQuery('fn')
      * ```
      *
-     * @example
      * In this example we add selections dynamically:
      *
      * ```ts
@@ -69,7 +68,7 @@ class DynamicModule {
      *
      * // 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' | 'birth_date'
      *
      * const [person] = await db.selectFrom('person')
      *   .select([
@@ -81,9 +80,9 @@ 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 | undefined = person.last_name
+     * const firstName: string | undefined = person.first_name
+     * const birthDate: string | undefined = person.birth_date
      *
      * // The result type also contains the compile time selection `id`.
      * person.id