kysely 0.12.0 → 0.14.0

package/dist/esm/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/esm/dialect/postgres/postgres-introspector.d.ts

@@ -1,7 +1,10 @@
-import { DatabaseIntrospector, DatabaseMetadata, DatabaseMetadataOptions } from '../../introspection/database-introspector.js';
+import { DatabaseIntrospector, DatabaseMetadata, DatabaseMetadataOptions } from '../database-introspector.js';
 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/esm/dialect/sqlite/sqlite-adapter.d.ts

@@ -1,7 +1,43 @@
-import { DialectAdapter } from '../dialect-adapter.js';
-export declare class SqliteAdapter implements DialectAdapter {
+import { DialectAdapterBase } from '../dialect-adapter-base.js';
+export declare class SqliteAdapter implements DialectAdapterBase {
+    /**
+     * 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/esm/dialect/sqlite/sqlite-dialect.d.ts

@@ -2,7 +2,7 @@ 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 { DatabaseIntrospector } from '../database-introspector.js';
 import { DialectAdapter } from '../dialect-adapter.js';
 import { DatabaseConnection } from '../../driver/database-connection.js';
 /**
@@ -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/esm/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/esm/dialect/sqlite/sqlite-introspector.d.ts

@@ -1,7 +1,10 @@
-import { DatabaseIntrospector, DatabaseMetadata, DatabaseMetadataOptions } from '../../introspection/database-introspector.js';
+import { DatabaseIntrospector, DatabaseMetadata, DatabaseMetadataOptions } from '../database-introspector.js';
 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/esm/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/esm/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/esm/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/esm/index.d.ts

@@ -73,6 +73,7 @@ export * from './operation-node/column-definition-node.js';
 export * from './operation-node/column-node.js';
 export * from './operation-node/column-update-node.js';
 export * from './operation-node/common-table-expression-node.js';
+export * from './operation-node/common-table-expression-name-node.js';
 export * from './operation-node/constraint-node.js';
 export * from './operation-node/create-index-node.js';
 export * from './operation-node/create-schema-node.js';
@@ -90,7 +91,7 @@ export * from './operation-node/drop-view-node.js';
 export * from './operation-node/filter-node.js';
 export * from './operation-node/foreign-key-constraint-node.js';
 export * from './operation-node/from-node.js';
-export * from './operation-node/generated-always-as-node.js';
+export * from './operation-node/generated-node.js';
 export * from './operation-node/group-by-item-node.js';
 export * from './operation-node/group-by-node.js';
 export * from './operation-node/having-node.js';
@@ -135,11 +136,11 @@ export * from './operation-node/value-node.js';
 export * from './operation-node/values-node.js';
 export * from './operation-node/where-node.js';
 export * from './operation-node/with-node.js';
-export * from './introspection/database-introspector.js';
+export * from './dialect/database-introspector.js';
 export * from './util/compilable.js';
 export * from './util/log.js';
 export { AnyColumn, UnknownRow, AnySelectQueryBuilder, } from './util/type-utils.js';
-export { SelectExpression, SelectExpressionOrList, } from './parser/select-parser.js';
+export { SelectExpression, SelectExpressionOrList, Selection, } from './parser/select-parser.js';
 export { ReferenceExpression, ReferenceExpressionOrList, } from './parser/reference-parser.js';
 export { ValueExpression, ValueExpressionOrList, } from './parser/value-parser.js';
 export { FilterValueExpression, FilterValueExpressionOrList, ExistsExpression, FilterOperator, } from './parser/filter-parser.js';

package/dist/esm/index.js

@@ -73,6 +73,7 @@ export * from './operation-node/column-definition-node.js';
 export * from './operation-node/column-node.js';
 export * from './operation-node/column-update-node.js';
 export * from './operation-node/common-table-expression-node.js';
+export * from './operation-node/common-table-expression-name-node.js';
 export * from './operation-node/constraint-node.js';
 export * from './operation-node/create-index-node.js';
 export * from './operation-node/create-schema-node.js';
@@ -90,7 +91,7 @@ export * from './operation-node/drop-view-node.js';
 export * from './operation-node/filter-node.js';
 export * from './operation-node/foreign-key-constraint-node.js';
 export * from './operation-node/from-node.js';
-export * from './operation-node/generated-always-as-node.js';
+export * from './operation-node/generated-node.js';
 export * from './operation-node/group-by-item-node.js';
 export * from './operation-node/group-by-node.js';
 export * from './operation-node/having-node.js';
@@ -135,6 +136,6 @@ export * from './operation-node/value-node.js';
 export * from './operation-node/values-node.js';
 export * from './operation-node/where-node.js';
 export * from './operation-node/with-node.js';
-export * from './introspection/database-introspector.js';
+export * from './dialect/database-introspector.js';
 export * from './util/compilable.js';
 export * from './util/log.js';

package/dist/esm/kysely.d.ts

@@ -6,7 +6,7 @@ import { QueryExecutor } from './query-executor/query-executor.js';
 import { QueryCreator } from './query-creator.js';
 import { KyselyPlugin } from './plugin/kysely-plugin.js';
 import { GeneratedPlaceholder } from './util/type-utils.js';
-import { DatabaseIntrospector } from './introspection/database-introspector.js';
+import { DatabaseIntrospector } from './dialect/database-introspector.js';
 import { Driver, IsolationLevel } from './driver/driver.js';
 import { ParseContext } from './parser/parse-context.js';
 import { FunctionBuilder } from './query-builder/function-builder.js';
@@ -207,6 +207,38 @@ export declare class Kysely<DB> extends QueryCreator<DB> {
      * Returns a copy of this Kysely instance without any plugins.
      */
     withoutPlugins(): Kysely<DB>;
+    /**
+     * Returns a copy of this Kysely instance with tables added to its
+     * database type.
+     *
+     * This method only modifies the types and doesn't affect any of the
+     * executed queries in any way.
+     *
+     * ### Examples
+     *
+     * The following example adds and uses a temporary table:
+     *
+     * @example
+     * ```ts
+     * await db.schema
+     *   .createTable('temp_table')
+     *   .temporary()
+     *   .addColumn('some_column', 'integer')
+     *   .execute()
+     *
+     * const tempDb = db.withTables<{
+     *   temp_table: {
+     *     some_column: number
+     *   }
+     * }>()
+     *
+     * await tempDb
+     *   .insertInto('temp_table')
+     *   .values({ some_column: 100 })
+     *   .execute()
+     * ```
+     */
+    withTables<T extends Record<string, Record<string, any>>>(): Kysely<DB & T>;
     /**
      * Releases all resources and disconnects from the database.
      *
@@ -223,13 +255,132 @@ export declare class Kysely<DB> extends QueryCreator<DB> {
 export declare class Transaction<DB> extends Kysely<DB> {
     #private;
     constructor(props: KyselyProps);
+    /**
+     * Returns true if this `Kysely` instance is a transaction.
+     *
+     * You can also use `db instanceof Transaction`.
+     */
     get isTransaction(): true;
+    /**
+     * Returns the {@link MigrationModule} module for managing and running migrations.
+     */
     get migration(): MigrationModule;
+    /**
+     * Creates a {@link TransactionBuilder} that can be used to run queries inside a transaction.
+     *
+     * The returned {@link TransactionBuilder} can be used to configure the transaction. The
+     * {@link TransactionBuilder.execute} method can then be called to run the transaction.
+     * {@link TransactionBuilder.execute} takes a function that is run inside the
+     * transaction. If the function throws, the transaction is rolled back. Otherwise
+     * the transaction is committed.
+     *
+     * The callback function passed to the {@link TransactionBuilder.execute | execute}
+     * method gets the transaction object as its only argument. The transaction is
+     * of type {@link Transaction} which inherits {@link Kysely}. Any query
+     * started through the transaction object is executed inside the transaction.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * const catto = await db.transaction().execute(async (trx) => {
+     *   const jennifer = await trx.insertInto('person')
+     *     .values({
+     *       id: db.generated,
+     *       first_name: 'Jennifer',
+     *       last_name: 'Aniston',
+     *     })
+     *     .returning('id')
+     *     .executeTakeFirstOrThrow()
+     *
+     *   await someFunction(trx, jennifer)
+     *
+     *   return await trx.insertInto('pet')
+     *     .values({
+     *       id: db.generated,
+     *       user_id: jennifer.id,
+     *       name: 'Catto',
+     *       species: 'cat'
+     *     })
+     *     .returning('*')
+     *     .executeTakeFirst()
+     * })
+     * ```
+     *
+     * Setting the isolation level:
+     *
+     * ```ts
+     * await db
+     *   .transaction()
+     *   .setIsolationLevel('serializable')
+     *   .execute(async (trx) => {
+     *     await doStuff(trx)
+     *   })
+     * ```
+     */
     transaction(): TransactionBuilder<DB>;
+    /**
+     * Provides a kysely instance bound to a single database connection.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * await db
+     *   .connection()
+     *   .execute(async (db) => {
+     *     // `db` is an instance of `Kysely` that's bound to a single
+     *     // database connection. All queries executed through `db` use
+     *     // the same connection.
+     *     await doStuff(db)
+     *   })
+     * ```
+     */
     connection(): ConnectionBuilder<DB>;
+    /**
+     * Releases all resources and disconnects from the database.
+     *
+     * You need to call this when you are done using the `Kysely` instance.
+     */
     destroy(): Promise<void>;
+    /**
+     * Returns a copy of this Kysely instance with the given plugin installed.
+     */
     withPlugin(plugin: KyselyPlugin): Transaction<DB>;
+    /**
+     * Returns a copy of this Kysely instance without any plugins.
+     */
     withoutPlugins(): Transaction<DB>;
+    /**
+     * Returns a copy of this Kysely instance with tables added to its
+     * database type.
+     *
+     * This method only modifies the types and doesn't affect any of the
+     * executed queries in any way.
+     *
+     * ### Examples
+     *
+     * The following example adds and uses a temporary table:
+     *
+     * @example
+     * ```ts
+     * await db.schema
+     *   .createTable('temp_table')
+     *   .temporary()
+     *   .addColumn('some_column', 'integer')
+     *   .execute()
+     *
+     * const tempDb = db.withTables<{
+     *   temp_table: {
+     *     some_column: number
+     *   }
+     * }>()
+     *
+     * await tempDb
+     *   .insertInto('temp_table')
+     *   .values({ some_column: 100 })
+     *   .execute()
+     * ```
+     */
+    withTables<T extends Record<string, Record<string, any>>>(): Transaction<DB & T>;
 }
 export interface KyselyProps {
     readonly config: KyselyConfig;

package/dist/esm/kysely.js

@@ -258,6 +258,40 @@ export class Kysely extends QueryCreator {
             executor: this.#props.executor.withoutPlugins(),
         });
     }
+    /**
+     * Returns a copy of this Kysely instance with tables added to its
+     * database type.
+     *
+     * This method only modifies the types and doesn't affect any of the
+     * executed queries in any way.
+     *
+     * ### Examples
+     *
+     * The following example adds and uses a temporary table:
+     *
+     * @example
+     * ```ts
+     * await db.schema
+     *   .createTable('temp_table')
+     *   .temporary()
+     *   .addColumn('some_column', 'integer')
+     *   .execute()
+     *
+     * const tempDb = db.withTables<{
+     *   temp_table: {
+     *     some_column: number
+     *   }
+     * }>()
+     *
+     * await tempDb
+     *   .insertInto('temp_table')
+     *   .values({ some_column: 100 })
+     *   .execute()
+     * ```
+     */
+    withTables() {
+        return new Kysely({ ...this.#props });
+    }
     /**
      * Releases all resources and disconnects from the database.
      *
@@ -311,6 +345,9 @@ export class Transaction extends Kysely {
             executor: this.#props.executor.withoutPlugins(),
         });
     }
+    withTables() {
+        return new Transaction({ ...this.#props });
+    }
 }
 export function isKyselyProps(obj) {
     return (isObject(obj) &&