kysely 0.27.5 → 0.28.0

package/dist/cjs/kysely.d.ts

@@ -5,7 +5,7 @@ import { QueryExecutor } from './query-executor/query-executor.js';
 import { QueryCreator } from './query-creator.js';
 import { KyselyPlugin } from './plugin/kysely-plugin.js';
 import { DatabaseIntrospector } from './dialect/database-introspector.js';
-import { Driver, IsolationLevel } from './driver/driver.js';
+import { Driver, IsolationLevel, AccessMode } from './driver/driver.js';
 import { FunctionModule } from './query-builder/function-module.js';
 import { LogConfig } from './util/log.js';
 import { QueryExecutorProvider } from './query-executor/query-executor-provider.js';
@@ -16,6 +16,8 @@ import { Compilable } from './util/compilable.js';
 import { CaseBuilder } from './query-builder/case-builder.js';
 import { Expression } from './expression/expression.js';
 import { DrainOuterGeneric } from './util/type-utils.js';
+import { ReleaseSavepoint, RollbackToSavepoint } from './parser/savepoint-parser.js';
+import { ControlledConnection } from './util/provide-controlled-connection.js';
 /**
  * The main Kysely class.
  *
@@ -49,7 +51,7 @@ import { DrainOuterGeneric } from './util/type-utils.js';
  *    in the database and values must be interfaces that describe the rows in those
  *    tables. See the examples above.
  */
-export declare class Kysely<DB> extends QueryCreator<DB> implements QueryExecutorProvider {
+export declare class Kysely<DB> extends QueryCreator<DB> implements QueryExecutorProvider, AsyncDisposable {
     #private;
     constructor(args: KyselyConfig);
     constructor(args: KyselyProps);
@@ -141,6 +143,9 @@ export declare class Kysely<DB> extends QueryCreator<DB> implements QueryExecuto
      * of type {@link Transaction} which inherits {@link Kysely}. Any query
      * started through the transaction object is executed inside the transaction.
      *
+     * To run a controlled transaction, allowing you to commit and rollback manually,
+     * use {@link startTransaction} instead.
+     *
      * ### Examples
      *
      * <!-- siteExample("transactions", "Simple transaction", 10) -->
@@ -193,6 +198,118 @@ export declare class Kysely<DB> extends QueryCreator<DB> implements QueryExecuto
      * ```
      */
     transaction(): TransactionBuilder<DB>;
+    /**
+     * Creates a {@link ControlledTransactionBuilder} that can be used to run queries inside a controlled transaction.
+     *
+     * The returned {@link ControlledTransactionBuilder} can be used to configure the transaction.
+     * The {@link ControlledTransactionBuilder.execute} method can then be called
+     * to start the transaction and return a {@link ControlledTransaction}.
+     *
+     * A {@link ControlledTransaction} allows you to commit and rollback manually,
+     * execute savepoint commands. It extends {@link Transaction} which extends {@link Kysely},
+     * so you can run queries inside the transaction. Once the transaction is committed,
+     * or rolled back, it can't be used anymore - all queries will throw an error.
+     * This is to prevent accidentally running queries outside the transaction - where
+     * atomicity is not guaranteed anymore.
+     *
+     * ### Examples
+     *
+     * <!-- siteExample("transactions", "Controlled transaction", 11) -->
+     *
+     * A controlled transaction allows you to commit and rollback manually, execute
+     * savepoint commands, and queries in general.
+     *
+     * In this example we start a transaction, use it to insert two rows and then commit
+     * the transaction. If an error is thrown, we catch it and rollback the transaction.
+     *
+     * ```ts
+     * const trx = await db.startTransaction().execute()
+     *
+     * try {
+     *   const jennifer = await trx.insertInto('person')
+     *     .values({
+     *       first_name: 'Jennifer',
+     *       last_name: 'Aniston',
+     *       age: 40,
+     *     })
+     *     .returning('id')
+     *     .executeTakeFirstOrThrow()
+     *
+     *   const catto = await trx.insertInto('pet')
+     *     .values({
+     *       owner_id: jennifer.id,
+     *       name: 'Catto',
+     *       species: 'cat',
+     *       is_favorite: false,
+     *     })
+     *     .returningAll()
+     *     .executeTakeFirstOrThrow()
+     *
+     *   await trx.commit().execute()
+     *
+     *   // ...
+     * } catch (error) {
+     *   await trx.rollback().execute()
+     * }
+     * ```
+     *
+     * <!-- siteExample("transactions", "Controlled transaction /w savepoints", 12) -->
+     *
+     * A controlled transaction allows you to commit and rollback manually, execute
+     * savepoint commands, and queries in general.
+     *
+     * In this example we start a transaction, insert a person, create a savepoint,
+     * try inserting a toy and a pet, and if an error is thrown, we rollback to the
+     * savepoint. Eventually we release the savepoint, insert an audit record and
+     * commit the transaction. If an error is thrown, we catch it and rollback the
+     * transaction.
+     *
+     * ```ts
+     * const trx = await db.startTransaction().execute()
+     *
+     * try {
+     *   const jennifer = await trx
+     *     .insertInto('person')
+     *     .values({
+     *       first_name: 'Jennifer',
+     *       last_name: 'Aniston',
+     *       age: 40,
+     *     })
+     *     .returning('id')
+     *     .executeTakeFirstOrThrow()
+     *
+     *   const trxAfterJennifer = await trx.savepoint('after_jennifer').execute()
+     *
+     *   try {
+     *     const catto = await trxAfterJennifer
+     *       .insertInto('pet')
+     *       .values({
+     *         owner_id: jennifer.id,
+     *         name: 'Catto',
+     *         species: 'cat',
+     *       })
+     *       .returning('id')
+     *       .executeTakeFirstOrThrow()
+     *
+     *     await trxAfterJennifer
+     *       .insertInto('toy')
+     *       .values({ name: 'Bone', price: 1.99, pet_id: catto.id })
+     *       .execute()
+     *   } catch (error) {
+     *     await trxAfterJennifer.rollbackToSavepoint('after_jennifer').execute()
+     *   }
+     *
+     *   await trxAfterJennifer.releaseSavepoint('after_jennifer').execute()
+     *
+     *   await trx.insertInto('audit').values({ action: 'added Jennifer' }).execute()
+     *
+     *   await trx.commit().execute()
+     * } catch (error) {
+     *   await trx.rollback().execute()
+     * }
+     * ```
+     */
+    startTransaction(): ControlledTransactionBuilder<DB>;
     /**
      * Provides a kysely instance bound to a single database connection.
      *
@@ -280,6 +397,7 @@ export declare class Kysely<DB> extends QueryCreator<DB> implements QueryExecuto
      * See {@link https://github.com/kysely-org/kysely/blob/master/site/docs/recipes/0004-splitting-query-building-and-execution.md#execute-compiled-queries splitting build, compile and execute code recipe} for more information.
      */
     executeQuery<R>(query: CompiledQuery<R> | Compilable<R>, queryId?: QueryId): Promise<QueryResult<R>>;
+    [Symbol.asyncDispose](): Promise<void>;
 }
 export declare class Transaction<DB> extends Kysely<DB> {
     #private;
@@ -307,6 +425,9 @@ export declare class Transaction<DB> extends Kysely<DB> {
      * of type {@link Transaction} which inherits {@link Kysely}. Any query
      * started through the transaction object is executed inside the transaction.
      *
+     * To run a controlled transaction, allowing you to commit and rollback manually,
+     * use {@link startTransaction} instead.
+     *
      * ### Examples
      *
      * <!-- siteExample("transactions", "Simple transaction", 10) -->
@@ -495,10 +616,226 @@ interface ConnectionBuilderProps extends KyselyProps {
 export declare class TransactionBuilder<DB> {
     #private;
     constructor(props: TransactionBuilderProps);
+    setAccessMode(accessMode: AccessMode): TransactionBuilder<DB>;
     setIsolationLevel(isolationLevel: IsolationLevel): TransactionBuilder<DB>;
     execute<T>(callback: (trx: Transaction<DB>) => Promise<T>): Promise<T>;
 }
 interface TransactionBuilderProps extends KyselyProps {
+    readonly accessMode?: AccessMode;
     readonly isolationLevel?: IsolationLevel;
 }
+export declare class ControlledTransactionBuilder<DB> {
+    #private;
+    constructor(props: TransactionBuilderProps);
+    setAccessMode(accessMode: AccessMode): ControlledTransactionBuilder<DB>;
+    setIsolationLevel(isolationLevel: IsolationLevel): ControlledTransactionBuilder<DB>;
+    execute(): Promise<ControlledTransaction<DB>>;
+}
+export declare class ControlledTransaction<DB, S extends string[] = []> extends Transaction<DB> {
+    #private;
+    constructor(props: ControlledTransactionProps);
+    get isCommitted(): boolean;
+    get isRolledBack(): boolean;
+    /**
+     * Commits the transaction.
+     *
+     * See {@link rollback}.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * import type { Kysely } from 'kysely'
+     * import type { Database } from 'type-editor' // imaginary module
+     *
+     * const trx = await db.startTransaction().execute()
+     *
+     * try {
+     *   await doSomething(trx)
+     *
+     *   await trx.commit().execute()
+     * } catch (error) {
+     *   await trx.rollback().execute()
+     * }
+     *
+     * async function doSomething(kysely: Kysely<Database>) {}
+     * ```
+     */
+    commit(): Command<void>;
+    /**
+     * Rolls back the transaction.
+     *
+     * See {@link commit} and {@link rollbackToSavepoint}.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * import type { Kysely } from 'kysely'
+     * import type { Database } from 'type-editor' // imaginary module
+     *
+     * const trx = await db.startTransaction().execute()
+     *
+     * try {
+     *   await doSomething(trx)
+     *
+     *   await trx.commit().execute()
+     * } catch (error) {
+     *   await trx.rollback().execute()
+     * }
+     *
+     * async function doSomething(kysely: Kysely<Database>) {}
+     * ```
+     */
+    rollback(): Command<void>;
+    /**
+     * Creates a savepoint with a given name.
+     *
+     * See {@link rollbackToSavepoint} and {@link releaseSavepoint}.
+     *
+     * For a type-safe experience, you should use the returned instance from now on.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * import type { Kysely } from 'kysely'
+     * import type { Database } from 'type-editor' // imaginary module
+     *
+     * const trx = await db.startTransaction().execute()
+     *
+     * await insertJennifer(trx)
+     *
+     * const trxAfterJennifer = await trx.savepoint('after_jennifer').execute()
+     *
+     * try {
+     *   await doSomething(trxAfterJennifer)
+     * } catch (error) {
+     *   await trxAfterJennifer.rollbackToSavepoint('after_jennifer').execute()
+     * }
+     *
+     * async function insertJennifer(kysely: Kysely<Database>) {}
+     * async function doSomething(kysely: Kysely<Database>) {}
+     * ```
+     */
+    savepoint<SN extends string>(savepointName: SN extends S ? never : SN): Command<ControlledTransaction<DB, [...S, SN]>>;
+    /**
+     * Rolls back to a savepoint with a given name.
+     *
+     * See {@link savepoint} and {@link releaseSavepoint}.
+     *
+     * You must use the same instance returned by {@link savepoint}, or
+     * escape the type-check by using `as any`.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * import type { Kysely } from 'kysely'
+     * import type { Database } from 'type-editor' // imaginary module
+     *
+     * const trx = await db.startTransaction().execute()
+     *
+     * await insertJennifer(trx)
+     *
+     * const trxAfterJennifer = await trx.savepoint('after_jennifer').execute()
+     *
+     * try {
+     *   await doSomething(trxAfterJennifer)
+     * } catch (error) {
+     *   await trxAfterJennifer.rollbackToSavepoint('after_jennifer').execute()
+     * }
+     *
+     * async function insertJennifer(kysely: Kysely<Database>) {}
+     * async function doSomething(kysely: Kysely<Database>) {}
+     * ```
+     */
+    rollbackToSavepoint<SN extends S[number]>(savepointName: SN): RollbackToSavepoint<S, SN> extends string[] ? Command<ControlledTransaction<DB, RollbackToSavepoint<S, SN>>> : never;
+    /**
+     * Releases a savepoint with a given name.
+     *
+     * See {@link savepoint} and {@link rollbackToSavepoint}.
+     *
+     * You must use the same instance returned by {@link savepoint}, or
+     * escape the type-check by using `as any`.
+     *
+     * ### Examples
+     *
+     * ```ts
+     * import type { Kysely } from 'kysely'
+     * import type { Database } from 'type-editor' // imaginary module
+     *
+     * const trx = await db.startTransaction().execute()
+     *
+     * await insertJennifer(trx)
+     *
+     * const trxAfterJennifer = await trx.savepoint('after_jennifer').execute()
+     *
+     * try {
+     *   await doSomething(trxAfterJennifer)
+     * } catch (error) {
+     *   await trxAfterJennifer.rollbackToSavepoint('after_jennifer').execute()
+     * }
+     *
+     * await trxAfterJennifer.releaseSavepoint('after_jennifer').execute()
+     *
+     * await doSomethingElse(trx)
+     *
+     * async function insertJennifer(kysely: Kysely<Database>) {}
+     * async function doSomething(kysely: Kysely<Database>) {}
+     * async function doSomethingElse(kysely: Kysely<Database>) {}
+     * ```
+     */
+    releaseSavepoint<SN extends S[number]>(savepointName: SN): ReleaseSavepoint<S, SN> extends string[] ? Command<ControlledTransaction<DB, ReleaseSavepoint<S, SN>>> : never;
+    /**
+     * Returns a copy of this Kysely instance with the given plugin installed.
+     */
+    withPlugin(plugin: KyselyPlugin): ControlledTransaction<DB, S>;
+    /**
+     * Returns a copy of this Kysely instance without any plugins.
+     */
+    withoutPlugins(): ControlledTransaction<DB, S>;
+    /**
+     * @override
+     */
+    withSchema(schema: string): ControlledTransaction<DB, S>;
+    /**
+     * 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:
+     *
+     * ```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>>>(): ControlledTransaction<DrainOuterGeneric<DB & T>, S>;
+}
+interface ControlledTransactionProps extends KyselyProps {
+    readonly connection: ControlledConnection;
+}
+export declare class Command<T> {
+    #private;
+    constructor(cb: () => Promise<T>);
+    /**
+     * Executes the command.
+     */
+    execute(): Promise<T>;
+}
 export {};