@harperfast/rocksdb-js 1.0.1 → 1.1.0

package/README.md

@@ -54,6 +54,9 @@ Creates a new database instance.
     Defaults to `1`.
   - `pessimistic: boolean` When `true`, throws conflict errors when they occur instead of waiting
     until commit. Defaults to `false`.
+  - `readOnly: boolean` When `true`, the database is opened in read-only mode. Read operations are
+    permitted. Write operations will throw an error with code `ERR_DATABASE_READONLY`. Transactions
+    are a no-op in read-only mode.
   - `statsLevel: StatsLevel` Controls which type of statistics to skip and reduce statistic
     overhead. Defaults to `StatsLevel.ExceptDetailedTimers`.
   - `store: Store` A custom store that handles all interaction between the `RocksDatabase` or
@@ -441,6 +444,24 @@ db.transactionSync((txn: Transaction) => {
 });
 ```
 
+### Optimistic and Pessimistic Modes
+
+`rocksdb-js` supports two different transaction modes: optimistic and pessimistic. The default mode
+is optimistic.
+
+- Optimistic: Conflicts detected at commit time.
+- Pessimistic: Conflicts throw immediately on detection.
+
+When a database is opened in optimistic mode, transactions are not locked and can be retried if
+they fail with a conflict. When a database is opened in pessimistic mode, transactions are aborted
+and cannot be retried if they fail with a conflict.
+
+Optimistic mode is the default mode and is recommended for most use cases. Pessimistic mode is
+recommended for use cases where you need to know immediately if a conflict occurs.
+
+If a database is opened in one mode, it cannot be opened in a different mode. An error will be
+thrown when trying to open it in a different mode without closing the database first.
+
 ### `TransactionCallback<T>`
 
 `(txn: Transaction, attempt: number) => T | PromiseLike<T>`
@@ -486,7 +507,7 @@ operations methods as the `RocksDatabase` instance plus:
 - `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
+- `txn.id: number` The read-only 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
@@ -662,18 +683,20 @@ const db = RocksDatabase.open('/path/to/db', {
 console.log(db.getStats());
 ```
 
-### `db.getStat(statName: string): number`
+### `db.getStat(statName: string): RocksDBStat`
 
-Retrieves a single statistic value.
+Retrieves a single statistic value. Return value is either a `number` or `StatsHistogramData`
+object.
 
 ```typescript
 console.log(db.getStat('rocksdb.block.cache.miss'));
 ```
 
-### `db.getStats(all?: boolean): Object<string, number | StatsHistogramData>`
+### `db.getStats(all?: boolean): RocksDBStats`
 
 Returns an object containing a curated list of column family-level properties, internal tickers
-stats, and internal histogram stats.
+stats, and internal histogram stats. Return value is an object with the stat name as the key and
+a `RocksDBStat` as the value.
 
 By default, it only returns the most meaningful internal stats. When `all = true`, it returns the
 same column family-level properties, but includes all internal tickers and histogram stats.
@@ -723,6 +746,14 @@ The `stats.StatsLevel` contains constants used to set which types of skip and re
 - `StatsLevel.ExceptTimeForMutex` Skip time waiting for mutex locks.
 - `StatsLevel.All` Collects all stats.
 
+### `type RocksDBStat = number | StatsHistogramData`
+
+A `RocksDBStat` is either a `number` or `StatsHistogramData` object.
+
+### `type RocksDBStats = Record<string, RocksDBStat>`
+
+A `RocksDBStats` is an object with the stat name as the key and a `RocksDBStat` as the value.
+
 ### `type StatsHistogramData`
 
 An object is a record with the following properties:

package/dist/index.cjs

@@ -654,6 +654,11 @@ var Store = class {
 	*/
 	pessimistic;
 	/**
+	* Whether the database is open in readonly mode. When `true`, write
+	* operations will throw an error with code `ERR_DATABASE_READONLY`.
+	*/
+	readOnly;
+	/**
 	* Encoder specific flag used to signal that the encoder should use a random
 	* access structure.
 	*/
@@ -722,6 +727,7 @@ var Store = class {
 		this.parallelismThreads = options?.parallelismThreads ?? 1;
 		this.path = path;
 		this.pessimistic = options?.pessimistic ?? false;
+		this.readOnly = options?.readOnly ?? false;
 		this.randomAccessStructure = options?.randomAccessStructure ?? false;
 		this.readKey = readKey;
 		this.sharedStructuresKey = options?.sharedStructuresKey;
@@ -792,6 +798,7 @@ var Store = class {
 		const keyParam = getKeyParam(this.encodeKey(key));
 		let flags = 0;
 		if (alwaysCreateNewBuffer) flags |= ALWAYS_CREATE_NEW_BUFFER_FLAG;
+		if (this.readOnly) txnId = void 0;
 		const result = context.getSync(keyParam, flags | ONLY_IF_IN_MEMORY_CACHE_FLAG, txnId);
 		if (typeof result === "number") {
 			if (result === NOT_IN_MEMORY_CACHE_FLAG) return new Promise((resolve, reject) => {
@@ -864,7 +871,7 @@ var Store = class {
 	*/
 	getTxnId(options) {
 		let txnId;
-		if (options?.transaction) {
+		if (!this.readOnly && options?.transaction) {
 			txnId = options.transaction.id;
 			if (txnId === void 0) throw new TypeError("Invalid transaction");
 		}
@@ -932,6 +939,7 @@ var Store = class {
 			name: this.name,
 			noBlockCache: this.noBlockCache,
 			parallelismThreads: this.parallelismThreads,
+			readOnly: this.readOnly,
 			statsLevel: this.statsLevel,
 			transactionLogMaxAgeThreshold: this.transactionLogMaxAgeThreshold,
 			transactionLogMaxSize: this.transactionLogMaxSize,
@@ -1047,9 +1055,17 @@ var Transaction = class extends DBI {
 	* @param options - The options for the transaction.
 	*/
 	constructor(store, options) {
-		const txn = new NativeTransaction(store.db, options);
-		super(store, txn);
-		this.#txn = txn;
+		if (store.readOnly) {
+			super(store);
+			this.#txn = { id: 0 };
+			this.abort = this.commitSync = this.setTimestamp = () => {};
+			this.commit = async () => {};
+			this.getTimestamp = () => 0;
+		} else {
+			const txn = new NativeTransaction(store.db, options);
+			super(store, txn);
+			this.#txn = txn;
+		}
 	}
 	/**
 	* Abort the transaction.
@@ -1379,6 +1395,12 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		return this.#name;
 	}
 	/**
+	* Whether the database is open in readonly mode.
+	*/
+	get readOnly() {
+		return this.store.readOnly;
+	}
+	/**
 	* Sugar method for opening a database.
 	*
 	* @param pathOrStore - The filesystem path to the database or a custom store.
@@ -1909,7 +1931,7 @@ function loadLastPosition(transactionLog, readUncommitted) {
 //#region src/index.ts
 const versions = {
 	rocksdb: version,
-	"rocksdb-js": "1.0.1"
+	"rocksdb-js": "1.1.0"
 };
 
 //#endregion