@knorm/knorm
Version:
A JavaScript ORM written using ES6 classes
209 lines (208 loc) • 7.46 kB
TypeScript
/**
* Creates and executes transactions, allowing multiple queries to be run within
* a transaction.
*/
export class Transaction {
/**
* Creates a {@link Transaction} instance.
*
* @param {function} [callback] The transaction callback, when [running
* transactions with a callback
* function](/guides/transactions.md#transactions-with-a-callback).
*/
constructor(callback?: Function | undefined);
callback: Function;
models: object;
/**
* Connects to the database, via {@link Connection#create}. This method is
* called by {@link Transaction#begin} or by {@link Query#connect} when
* queries are executed within transactions.
*
* @returns {Promise} The `Promise` from {@link Connection#create}, that is
* resolved when a connection is established or rejected with a
* {@link TransactionError} on error.
*/
connect(): Promise<any>;
connection: any;
/**
* Closes the database connection (via {@link Connection#close}) after
* committing (via {@link Transaction#commit}) or rolling back (via
* {@link Transaction#rollback}) a transaction.
*
* @param {QueryError} [error] The error from {@link Transaction#rollback}, if
* it was called with one. This error is then passed to
* {@link Connection#close}.
*
* @returns {Promise} The `Promise` from {@link Connection#close}, that is
* resolved when the connection is closed or rejected with a
* {@link QueryError} on error.
*/
disconnect(error?: any): Promise<any>;
/**
* Begins a transaction, via {@link Transaction#_begin}. If no database
* connection exists, one is created via {@link Transaction#connect}.
*
* @returns {Promise} A `Promise` that is resolved when the transaction is begun
* or rejected with a {@link TransactionError} on error.
*/
begin(): Promise<any>;
/**
* Shows the state of a transaction. This is initially `undefined`, set to
* `true` after {@link Transaction#begin} and finally set to `false` after
* {@link Transaction#commit} or {@link Transaction#rollback}.
*
* @type {boolean}
*/
active: boolean;
/**
* Shows the state of a transaction. This is initially `undefined` and set
* to `true` after {@link Transaction#begin}. Note that it stays `true`
* even after {@link Transaction#commit} or {@link Transaction#rollback}.
*
* @type {boolean}
*/
started: boolean;
/**
* Sends a `BEGIN` query (via {@link Connection#query}) to start a
* transaction. This can be overloaded to send a different query e.g. `START
* TRANSACTION`.
*
* @returns {Promise} The `Promise` from {@link Connection#query}, that is
* resolved with the query result.
*/
_begin(): Promise<any>;
/**
* Commits a transaction, via {@link Transaction#_commit} and afterwards
* closes the database connection, via {@link Transaction#disconnect}. If the
* commit fails, the transaction is automaticaly rolled back via
* {@link Transaction#rollback}.
*
* @returns {Promise} A `Promise` that is resolved when the transaction is
* committed and the connection closed or rejected with a
* {@link TransactionError} on error.
*/
commit(): Promise<any>;
/**
* Shows the state of a transaction. This is initially `undefined` and
* only set to `true` after {@link Transaction#commit} or
* {@link Transaction#rollback}.
*
* @type {boolean}
*/
ended: boolean;
/**
* Sends a `COMMIT` query (via {@link Connection#query}) to commit a
* transaction. This can be overloaded to send a different query.
*
* @returns {Promise} The `Promise` from {@link Connection#query}, that is
* resolved with the query result.
*/
_commit(): Promise<any>;
/**
* Rolls back a transaction, via {@link Transaction#_rollback} and afterwards
* closes the database connection, via {@link Transaction#disconnect}.
*
* @param {QueryError} [error] A {@link QueryError} from {@link Query#query},
* or a {@link TransactionError} from {@link Transaction#commit} or
* {@link Transaction#rollback}, if one occurs when those methods are run.
* This error is then passed to {@link Transaction#disconnect} and finally to
* {@link Connection#close}.
*
* @returns {Promise} A `Promise` that is resolved when the transaction is
* rolled back and the connection closed or rejected with a
* {@link TransactionError} on error.
*/
rollback(error?: any): Promise<any>;
/**
* Sends a `ROLLBACK` query (via {@link Connection#query}) to roll back a
* transaction. This can be overloaded to send a different query.
*
* @returns {Promise} The `Promise` from {@link Connection#query}, that is
* resolved with the query result.
*/
_rollback(): Promise<any>;
/**
* Executes a transaction when [running a transaction with a callback
* function](/guides/transactions.md#transactions-with-a-callback). This
* method begins a transaction (via {@link Transaction#begin}), executes the
* callback function and commits the transaction (via
* {@link Transaction#commit}).
*
* @returns {Promise} A `Promise` that is resolved with the resolution value
* of the callback function.
*/
execute(): Promise<any>;
/**
* Simulates a `Promise` interface. This method calls
* {@link Transaction#execute} and resolves with it's resolution value.
*
* @example ```js
* (async function() {
* const value = await new Transaction(async transaction => {
* return 'foo';
* });
*
* console.log(value); // => 'foo'
* })();
* ```
*
* @example ```js
* new Transaction(async transaction => {
* return 'foo';
* }).then(value => {
* console.log(value); // => 'foo'
* });
* ```
*
* @returns {Promise}
*/
then(...args: any[]): Promise<any>;
/**
* Simulates a `Promise` interface. This method calls
* {@link Transaction#execute} and calls `catch` on the promise returned.
*
* @example ```js
* (async function() {
* try {
* const value = await new Transaction(async transaction => {
* throw new Error('foo');
* });
* } catch (e) {
* console.log(e.message); // => 'foo'
* }
* })();
* ```
*
* @example ```js
* new Transaction(async transaction => {
* throw new Error('foo');
* }).catch(e => {
* console.log(e.message); // => 'foo'
* });
* ```
*
* @returns {Promise}
*/
catch(...args: any[]): Promise<any>;
/**
* A reference to the {@link Knorm} instance.
*
* ::: tip
* This is the same instance assigned to the {@link Transaction.knorm} static
* property, just added as a convenience for use in instance methods.
* :::
*/
knorm: any;
}
export namespace Transaction {
export { TransactionError };
export const knorm: any;
export const models: object;
export { Connection };
}
declare class TransactionError extends KnormError {
constructor(...args: any[]);
}
import { Connection } from "./Connection";
import { KnormError } from "./KnormError";
export {};