@harperfast/rocksdb-js 0.1.12 → 0.1.13

package/README.md

@@ -396,7 +396,7 @@ Synchronous version of `remove()`.
 
 ## Transactions
 
-### `db.transaction(async (txn: Transaction) => void | Promise<any>): Promise<any>`
+### `db.transaction<T>(callback: TransactionCallback<T>, options?: DBTransactionOptions): Promise<T>`
 
 Executes all database operations within the specified callback within a single transaction. If the
 callback completes without error, the database operations are automatically committed. However, if
@@ -427,7 +427,7 @@ const isBar = await db.transaction(async (txn: Transaction) => {
 console.log(isBar ? 'Foo is bar' : 'Foo is not bar');
 ```
 
-### `db.transactionSync((txn: Transaction) => any): any`
+### `db.transactionSync<T>(callback: TransactionCallback<T>, options?: TransactionOptions): T`
 
 Executes a transaction callback and commits synchronously. Once the transaction callback returns,
 the commit is executed synchronously and blocks the current thread until finished.
@@ -441,17 +441,56 @@ db.transactionSync((txn: Transaction) => {
 });
 ```
 
+### `TransactionCallback<T>`
+
+`(txn: Transaction, attempt: number) => T | PromiseLike<T>`
+
+A sync or async function to encapsulate all of the transaction operations. Once the function is
+executed, the transaction is automatically committed. If the function returns a value, it will be
+returned from the transaction call.
+
+The `txn` parameter is a `Transaction`. See the [Transaction](#class-transaction) section for more
+details.
+
+The `attempt` parameter is the number of times the transaction has been retried.
+
+### `TransactionOptions`
+
+- `disableSnapshot?: boolean` Whether to disable snapshots. Defaults to `false`.
+- `maxRetries?: number` The maximum number of times to retry the transaction. Defaults to `3`.
+- `retryOnBusy?: boolean` Whether to retry the transaction if the commit fails with `IsBusy`.
+  Defaults to `true` when the transaction is bound to a transaction log, otherwise `false`.
+
+### Transaction Retry Logic
+
+The retry mechanism will only be active when the `retryOnBusy` option is `true` or when
+`retryOnBusy` is `undefined` and the transaction is bound to a transaction log. The attempts starts
+at `1` and ends at `maxRetries`.
+
+When using a transaction log and the commit fails with `ERR_BUSY`, the transaction log will be in
+a bad state and the transaction will need to be retried. If the max retries is reached or the
+transaction is not retried, a `ERR_TRANSACTION_ABANDONED` error will be thrown.
+
+Users should use the `attempt` transaction callback parameter to ensure duplicate transaction log
+entries are not added.
+
 ### Class: `Transaction`
 
 The transaction callback is passed in a `Transaction` instance which contains all of the same data
 operations methods as the `RocksDatabase` instance plus:
 
-- `txn.abort()`
-- `txn.commit()`
-- `txn.commitSync()`
-- `txn.getTimestamp()`
-- `txn.id`
-- `txn.setTimestamp(ts)`
+- `txn.abort()` Rolls back and closes the transaction. This method is automatically called after the
+  transaction callback returns, so you shouldn't need to call it, but it's ok to do so. Once called,
+  no further transaction operations are permitted. Calling this method multiple times has no effect.
+- `txn.commit(): Promise<void>` Asynchronously commits the transaction and closes the transaction.
+- `txn.commitSync()` Synchronously commits and closes the transaction.
+- `txn.getTimestamp(): number` Retrieves the transaction start timestamp in seconds as a decimal. It
+  defaults to the time at which the transaction was created.
+- `txn.id: number` The readonly transaction ID. Transaction IDs are unique to the RocksDB database
+  path, regardless the database name/column family.
+- `txn.setTimestamp(ts?: number): void` Overrides the transaction start timestamp. If called without
+  a timestamp, it will set the timestamp to the current time. The value must be in seconds with
+  higher precision in the decimal.
 
 #### `txn.abort(): void`
 

package/dist/index.cjs

@@ -1011,6 +1011,29 @@ function getKeyParam(keyBuffer) {
 
 //#endregion
 //#region src/transaction.ts
+var TransactionAlreadyAbortedError = class extends Error {
+	code = "ERR_ALREADY_ABORTED";
+};
+var TransactionIsBusyError = class extends Error {
+	code = "ERR_BUSY";
+	hasLog;
+	txn;
+	constructor(error, txn) {
+		super(error.message);
+		this.hasLog = error.hasLog ?? false;
+		this.txn = txn;
+	}
+};
+var TransactionAbandonedError = class extends Error {
+	code = "ERR_TRANSACTION_ABANDONED";
+	hasLog;
+	txn;
+	constructor(error, txn) {
+		super(error.message);
+		this.hasLog = error.hasLog ?? false;
+		this.txn = txn;
+	}
+};
 /**
 * Provides transaction level operations to a transaction callback.
 */
@@ -1031,7 +1054,12 @@ var Transaction = class extends DBI {
 	* Abort the transaction.
 	*/
 	abort() {
-		this.#txn.abort();
+		try {
+			this.#txn.abort();
+		} catch (err) {
+			if (err instanceof Error && "code" in err && err.code === "ERR_TRANSACTION_ABANDONED") throw new TransactionAbandonedError(err, this);
+			throw err;
+		}
 	}
 	/**
 	* Commit the transaction.
@@ -1042,6 +1070,8 @@ var Transaction = class extends DBI {
 				this.notify("beforecommit");
 				this.#txn.commit(resolve, reject);
 			});
+		} catch (err) {
+			throw this.#handleCommitError(err);
 		} finally {
 			this.notify("aftercommit", {
 				next: null,
@@ -1057,6 +1087,8 @@ var Transaction = class extends DBI {
 		try {
 			this.notify("beforecommit");
 			this.#txn.commitSync();
+		} catch (err) {
+			throw this.#handleCommitError(err);
 		} finally {
 			this.notify("aftercommit", {
 				next: null,
@@ -1066,6 +1098,19 @@ var Transaction = class extends DBI {
 		}
 	}
 	/**
+	* Detect if error is an already aborted or busy error and return the appropriate error class.
+	*
+	* @param err - The error to check.
+	* @returns The specialized error.
+	*/
+	#handleCommitError(err) {
+		if (err instanceof Error && "code" in err) {
+			if (err.code === "ERR_ALREADY_ABORTED") return new TransactionAlreadyAbortedError(err.message);
+			if (err.code === "ERR_BUSY") return new TransactionIsBusyError(err, this);
+		}
+		return err;
+	}
+	/**
 	* Returns the transaction start timestamp in seconds. Defaults to the time at which
 	* the transaction was created.
 	*
@@ -1472,30 +1517,24 @@ var RocksDatabase = class RocksDatabase extends DBI {
 	*/
 	async transaction(callback, options) {
 		if (typeof callback !== "function") throw new TypeError("Callback must be a function");
+		const maxRetries = options?.maxRetries ?? 3;
 		const txn = new Transaction(this.store, options);
 		let result;
-		try {
-			this.notify("begin-transaction");
-			result = await callback(txn);
-		} catch (err) {
+		this.notify("begin-transaction");
+		for (let attempt = 1; attempt <= maxRetries; attempt++) {
 			try {
-				txn.abort();
-			} catch (abortErr) {
-				if (abortErr instanceof Error && "code" in abortErr && abortErr.code === "ERR_ALREADY_ABORTED") return;
+				result = await callback(txn, attempt);
+			} catch (callbackErr) {
+				return this.#abortTransaction(txn, callbackErr);
 			}
-			throw err;
-		}
-		try {
-			await txn.commit();
-			return result;
-		} catch (err) {
-			if (err instanceof Error && "code" in err && err.code === "ERR_ALREADY_ABORTED") return;
 			try {
-				txn.abort();
-			} catch (abortErr) {
-				if (abortErr instanceof Error && "code" in abortErr && abortErr.code === "ERR_TRANSACTION_ABANDONED") throw abortErr;
+				await txn.commit();
+				return result;
+			} catch (commitErr) {
+				if (commitErr instanceof TransactionAlreadyAbortedError) return;
+				if (commitErr instanceof TransactionIsBusyError && (options?.retryOnBusy ?? commitErr.hasLog) && attempt <= maxRetries) continue;
+				this.#abandonTransaction(txn, commitErr);
 			}
-			throw err;
 		}
 	}
 	/**
@@ -1517,38 +1556,55 @@ var RocksDatabase = class RocksDatabase extends DBI {
 	*/
 	transactionSync(callback, options) {
 		if (typeof callback !== "function") throw new TypeError("Callback must be a function");
-		const txn = new Transaction(this.store, options);
-		let result;
-		try {
-			this.notify("begin-transaction");
-			result = callback(txn);
-		} catch (err) {
+		const maxRetries = options?.maxRetries ?? 3;
+		const isRetryable = (err, attempt) => {
+			return err instanceof TransactionIsBusyError && (options?.retryOnBusy ?? err.hasLog) && attempt <= maxRetries;
+		};
+		const runAttempt = (attempt) => {
+			const txn = new Transaction(this.store, options);
+			let result;
 			try {
-				txn.abort();
-			} catch (err) {
-				if (err instanceof Error && "code" in err && err.code === "ERR_ALREADY_ABORTED") return;
+				result = callback(txn, attempt);
+			} catch (callbackErr) {
+				return this.#abortTransaction(txn, callbackErr);
 			}
-			throw err;
-		}
-		if (result && typeof result === "object" && "then" in result && typeof result.then === "function") return result.then((value) => {
+			if (typeof result?.then === "function") return result.then((value) => {
+				try {
+					txn.commitSync();
+					return value;
+				} catch (commitErr) {
+					if (commitErr instanceof TransactionAlreadyAbortedError) return;
+					if (isRetryable(commitErr, attempt)) return runAttempt(attempt + 1);
+					this.#abandonTransaction(txn, commitErr);
+				}
+			});
 			try {
 				txn.commitSync();
-				return value;
-			} catch (err) {
-				if (err instanceof Error && "code" in err && err.code === "ERR_ALREADY_ABORTED") return;
-				throw err;
+				return result;
+			} catch (commitErr) {
+				if (commitErr instanceof TransactionAlreadyAbortedError) return;
+				if (isRetryable(commitErr, attempt)) return runAttempt(attempt + 1);
+				this.#abandonTransaction(txn, commitErr);
 			}
-		});
+		};
+		this.notify("begin-transaction");
+		return runAttempt(1);
+	}
+	#abortTransaction(txn, callbackErr) {
 		try {
-			txn.commitSync();
-			return result;
-		} catch (err) {
-			if (err instanceof Error && "code" in err && err.code === "ERR_ALREADY_ABORTED") return;
-			try {
-				txn.abort();
-			} catch {}
-			throw err;
+			txn.abort();
+		} catch (abortErr) {
+			if (abortErr instanceof TransactionAlreadyAbortedError) return;
+		}
+		throw callbackErr;
+	}
+	#abandonTransaction(txn, commitErr) {
+		try {
+			txn.abort();
+		} catch (abortErr) {
+			if (abortErr instanceof TransactionAbandonedError) throw abortErr;
 		}
+		throw commitErr;
 	}
 	/**
 	* Attempts to acquire a lock for a given key. If the lock is available,
@@ -1852,7 +1908,7 @@ function loadLastPosition(transactionLog, readUncommitted) {
 //#region src/index.ts
 const versions = {
 	rocksdb: version,
-	"rocksdb-js": "0.1.12"
+	"rocksdb-js": "0.1.13"
 };
 
 //#endregion