@harperfast/rocksdb-js 1.0.1 → 1.1.1

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
@@ -82,6 +85,18 @@ const db = RocksDatabase.open('foo');
 db.close();
 ```
 
+### `db.columns: string[]`
+
+Returns the list of column families in the RocksDB database.
+
+```typescript
+const db = RocksDatabase.open('path/to/db');
+console.log(db.columns); // ['default']
+
+const db2 = new RocksDatabase('path/to/db', { name: 'users' });
+console.log(db.columns); // ['default', 'users']
+```
+
 ### `db.config(options)`
 
 Sets global database settings.
@@ -287,24 +302,28 @@ await promise;
 console.log(db.getOldestSnapshotTimestamp()); // returns `0`, no snapshots
 ```
 
-### `db.getDBProperty(propertyName: string): string`
+### `db.getDBProperty(propertyName: string): string | undefined`
 
 Gets a RocksDB database property as a string.
 
 - `propertyName: string` The name of the property to retrieve (e.g., ) `'rocksdb.levelstats'`.
 
+Returns `undefined` if the property is not found.
+
 ```typescript
 const db = RocksDatabase.open('/path/to/database');
 const levelStats = db.getDBProperty('rocksdb.levelstats');
 const stats = db.getDBProperty('rocksdb.stats');
 ```
 
-### `db.getDBIntProperty(propertyName: string): number`
+### `db.getDBIntProperty(propertyName: string): number | undefined`
 
 Gets a RocksDB database property as an integer.
 
 - `propertyName: string` The name of the property to retrieve (e.g., ) `'rocksdb.num-blob-files'`.
 
+Returns `undefined` if the property is not found.
+
 ```typescript
 const db = RocksDatabase.open('/path/to/database');
 const blobFiles = db.getDBIntProperty('rocksdb.num-blob-files');
@@ -396,7 +415,7 @@ Synchronous version of `remove()`.
 
 ## Transactions
 
-### `db.transaction<T>(callback: TransactionCallback<T>, options?: DBTransactionOptions): Promise<T>`
+### `db.transaction<T>(callback: TransactionCallback<T>, options?: TransactionOptions): 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
@@ -441,6 +460,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 +523,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 +699,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 +762,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.
@@ -1203,6 +1219,12 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		this.store.close();
 	}
 	/**
+	* Returns the list of column families in the RocksDB database.
+	*/
+	get columns() {
+		return this.store.db.columns;
+	}
+	/**
 	* Set global database settings.
 	*
 	* @param options - The options for the database.
@@ -1379,6 +1401,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.
@@ -1440,14 +1468,14 @@ var RocksDatabase = class RocksDatabase extends DBI {
 					return buffer && store.decoder?.decode ? store.decoder.decode(buffer) : void 0;
 				};
 				opts.saveStructures = (structures, isCompatible) => {
-					return this.transactionSync((txn) => {
+					return this.transactionSync((txn, _attempt) => {
 						const existingStructuresBuffer = this.getBinarySync(sharedStructuresKey);
 						const existingStructures = existingStructuresBuffer && store.decoder?.decode ? store.decoder.decode(existingStructuresBuffer) : void 0;
 						if (typeof isCompatible == "function") {
 							if (!isCompatible(existingStructures)) return false;
 						} else if (existingStructures && existingStructures.length !== isCompatible) return false;
 						txn.putSync(sharedStructuresKey, structures);
-					});
+					}, { retryOnBusy: true });
 				};
 			}
 			store.encoder = new EncoderClass({
@@ -1464,16 +1492,15 @@ var RocksDatabase = class RocksDatabase extends DBI {
 			};
 			store.decoder = store.encoder;
 		}
-		if (typeof store.encoder?.writeKey === "function" && !store.encoder?.encode) {
-			store.encoder = {
-				...store.encoder,
-				encode: (value, _mode) => {
-					const bytesWritten = store.writeKey(value, store.encodeBuffer, 0);
-					return store.encodeBuffer.subarray(0, bytesWritten);
-				}
-			};
-			store.encoder.copyBuffers = true;
-		}
+		if (typeof store.encoder?.writeKey === "function" && !store.encoder?.encode) store.encoder = {
+			...store.encoder,
+			encode: (value, _mode) => {
+				const bytesWritten = store.writeKey(value, store.encodeBuffer, 0);
+				return store.encodeBuffer.subarray(0, bytesWritten);
+			},
+			copyBuffers: true
+		};
+		if (store.encoder) store.encoder.name = this.#name;
 		if (store.decoder && store.decoder.needsStableBuffer !== true) store.decoderCopies = true;
 		if (store.decoder?.readKey && !store.decoder.decode) {
 			store.decoder.decode = (buffer) => {
@@ -1909,7 +1936,7 @@ function loadLastPosition(transactionLog, readUncommitted) {
 //#region src/index.ts
 const versions = {
 	rocksdb: version,
-	"rocksdb-js": "1.0.1"
+	"rocksdb-js": "1.1.1"
 };
 
 //#endregion