@harperfast/rocksdb-js - npm Package Compare versions

Comparing version 1.0.1 to 1.1.0

dist/index.cjs

@@ -657,2 +657,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 	/**
+	* 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
@@ -726,2 +731,3 @@ * access structure.
 		this.pessimistic = options?.pessimistic ?? false;
+		this.readOnly = options?.readOnly ?? false;
 		this.randomAccessStructure = options?.randomAccessStructure ?? false;
@@ -797,2 +803,3 @@ this.readKey = readKey;
 		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);
@@ -870,3 +877,3 @@ if (typeof result === "number") {
 		let txnId;
-		if (options?.transaction) {
+		if (!this.readOnly && options?.transaction) {
 			txnId = options.transaction.id;
@@ -939,2 +946,3 @@ if (txnId === void 0) throw new TypeError("Invalid transaction");
 			parallelismThreads: this.parallelismThreads,
+			readOnly: this.readOnly,
 			statsLevel: this.statsLevel,
@@ -1055,5 +1063,13 @@ transactionLogMaxAgeThreshold: this.transactionLogMaxAgeThreshold,
 	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;
+		}
 	}
@@ -1388,2 +1404,8 @@ /**
 	/**
+	* Whether the database is open in readonly mode.
+	*/
+	get readOnly() {
+		return this.store.readOnly;
+	}
+	/**
 	* Sugar method for opening a database.
@@ -1919,3 +1941,3 @@ *
 	rocksdb: version,
-	"rocksdb-js": "1.0.1"
+	"rocksdb-js": "1.1.0"
 };
@@ -1922,0 +1944,0 @@

dist/index.d.cts

@@ -78,2 +78,7 @@ import { ExtendedIterable } from "@harperfast/extended-iterable";
   randomAccessStructure?: boolean;
+  /**
+  * When `true`, the database is opened in read-only mode. Write operations
+  * will throw an error with code `ERR_DATABASE_READONLY`.
+  */
+  readOnly?: boolean;
   sharedStructuresKey?: symbol;
@@ -184,2 +189,7 @@ /**
   /**
+  * Whether the database is open in readonly mode. When `true`, write
+  * operations will throw an error with code `ERR_DATABASE_READONLY`.
+  */
+  readOnly: boolean;
+  /**
   * Encoder specific flag used to signal that the encoder should use a random
@@ -421,3 +431,3 @@ * access structure.
 type TransactionLog = {
-  new (name: string): TransactionLog;
+  new (db: NativeDatabase, name: string): TransactionLog;
   addEntry(data: Buffer | Uint8Array, txnId?: number): void;
@@ -444,2 +454,3 @@ getLogFileSize(sequenceId?: number): number;
   parallelismThreads?: number;
+  readOnly?: boolean;
   statsLevel?: (typeof stats.StatsLevel)[keyof typeof stats.StatsLevel];
@@ -918,2 +929,4 @@ transactionLogMaxAgeThreshold?: number;
 }
+type RocksDBStat = number | StatsHistogramData;
+type RocksDBStats = Record<string, RocksDBStat>;
 /**
@@ -1040,3 +1053,3 @@ * The main class for interacting with a RocksDB database.
   */
-  getStat(statName: string): number | StatsHistogramData;
+  getStat(statName: string): RocksDBStat;
   /**
@@ -1051,3 +1064,3 @@ * Gets the RocksDB statistics. Requires statistics to be enabled.
   */
-  getStats(all?: boolean): Record<string, number | StatsHistogramData>;
+  getStats(all?: boolean): RocksDBStats;
   /**
@@ -1106,2 +1119,6 @@ * Gets or creates a buffer that can be shared across worker threads.
   /**
+  * Whether the database is open in readonly mode.
+  */
+  get readOnly(): boolean;
+  /**
   * Sugar method for opening a database.
@@ -1257,3 +1274,3 @@ *
 //#endregion
-export { DBI, DBIterator, type IteratorOptions, type Key, RocksDatabase, type RocksDatabaseOptions, type StatsHistogramData, Store, type StoreContext, type StoreGetOptions, type StoreIteratorOptions, type StorePutOptions, type StoreRangeOptions, type StoreRemoveOptions, Transaction, type TransactionEntry, TransactionLog, constants, currentThreadId, parseTransactionLog, registryStatus, shutdown, stats, versions };
+export { DBI, DBIterator, type IteratorOptions, type Key, type RocksDBStat, type RocksDBStats, RocksDatabase, type RocksDatabaseOptions, type StatsHistogramData, Store, type StoreContext, type StoreGetOptions, type StoreIteratorOptions, type StorePutOptions, type StoreRangeOptions, type StoreRemoveOptions, Transaction, type TransactionEntry, TransactionLog, constants, currentThreadId, parseTransactionLog, registryStatus, shutdown, stats, versions };
 //# sourceMappingURL=index.d.cts.map

dist/index.d.mts

@@ -78,2 +78,7 @@ import { ExtendedIterable } from "@harperfast/extended-iterable";
   randomAccessStructure?: boolean;
+  /**
+  * When `true`, the database is opened in read-only mode. Write operations
+  * will throw an error with code `ERR_DATABASE_READONLY`.
+  */
+  readOnly?: boolean;
   sharedStructuresKey?: symbol;
@@ -184,2 +189,7 @@ /**
   /**
+  * Whether the database is open in readonly mode. When `true`, write
+  * operations will throw an error with code `ERR_DATABASE_READONLY`.
+  */
+  readOnly: boolean;
+  /**
   * Encoder specific flag used to signal that the encoder should use a random
@@ -421,3 +431,3 @@ * access structure.
 type TransactionLog = {
-  new (name: string): TransactionLog;
+  new (db: NativeDatabase, name: string): TransactionLog;
   addEntry(data: Buffer | Uint8Array, txnId?: number): void;
@@ -444,2 +454,3 @@ getLogFileSize(sequenceId?: number): number;
   parallelismThreads?: number;
+  readOnly?: boolean;
   statsLevel?: (typeof stats.StatsLevel)[keyof typeof stats.StatsLevel];
@@ -918,2 +929,4 @@ transactionLogMaxAgeThreshold?: number;
 }
+type RocksDBStat = number | StatsHistogramData;
+type RocksDBStats = Record<string, RocksDBStat>;
 /**
@@ -1040,3 +1053,3 @@ * The main class for interacting with a RocksDB database.
   */
-  getStat(statName: string): number | StatsHistogramData;
+  getStat(statName: string): RocksDBStat;
   /**
@@ -1051,3 +1064,3 @@ * Gets the RocksDB statistics. Requires statistics to be enabled.
   */
-  getStats(all?: boolean): Record<string, number | StatsHistogramData>;
+  getStats(all?: boolean): RocksDBStats;
   /**
@@ -1106,2 +1119,6 @@ * Gets or creates a buffer that can be shared across worker threads.
   /**
+  * Whether the database is open in readonly mode.
+  */
+  get readOnly(): boolean;
+  /**
   * Sugar method for opening a database.
@@ -1257,3 +1274,3 @@ *
 //#endregion
-export { DBI, DBIterator, type IteratorOptions, type Key, RocksDatabase, type RocksDatabaseOptions, type StatsHistogramData, Store, type StoreContext, type StoreGetOptions, type StoreIteratorOptions, type StorePutOptions, type StoreRangeOptions, type StoreRemoveOptions, Transaction, type TransactionEntry, TransactionLog, constants, currentThreadId, parseTransactionLog, registryStatus, shutdown, stats, versions };
+export { DBI, DBIterator, type IteratorOptions, type Key, type RocksDBStat, type RocksDBStats, RocksDatabase, type RocksDatabaseOptions, type StatsHistogramData, Store, type StoreContext, type StoreGetOptions, type StoreIteratorOptions, type StorePutOptions, type StoreRangeOptions, type StoreRemoveOptions, Transaction, type TransactionEntry, TransactionLog, constants, currentThreadId, parseTransactionLog, registryStatus, shutdown, stats, versions };
 //# sourceMappingURL=index.d.mts.map

dist/index.mjs

@@ -632,2 +632,7 @@ import { createRequire } from "node:module";
 	/**
+	* 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
@@ -701,2 +706,3 @@ * access structure.
 		this.pessimistic = options?.pessimistic ?? false;
+		this.readOnly = options?.readOnly ?? false;
 		this.randomAccessStructure = options?.randomAccessStructure ?? false;
@@ -772,2 +778,3 @@ this.readKey = readKey;
 		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);
@@ -845,3 +852,3 @@ if (typeof result === "number") {
 		let txnId;
-		if (options?.transaction) {
+		if (!this.readOnly && options?.transaction) {
 			txnId = options.transaction.id;
@@ -914,2 +921,3 @@ if (txnId === void 0) throw new TypeError("Invalid transaction");
 			parallelismThreads: this.parallelismThreads,
+			readOnly: this.readOnly,
 			statsLevel: this.statsLevel,
@@ -1030,5 +1038,13 @@ transactionLogMaxAgeThreshold: this.transactionLogMaxAgeThreshold,
 	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;
+		}
 	}
@@ -1363,2 +1379,8 @@ /**
 	/**
+	* Whether the database is open in readonly mode.
+	*/
+	get readOnly() {
+		return this.store.readOnly;
+	}
+	/**
 	* Sugar method for opening a database.
@@ -1894,3 +1916,3 @@ *
 	rocksdb: version,
-	"rocksdb-js": "1.0.1"
+	"rocksdb-js": "1.1.0"
 };
@@ -1897,0 +1919,0 @@

package.json

 {
   "name": "@harperfast/rocksdb-js",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "RocksDB binding for Node.js",
@@ -32,3 +32,3 @@ "homepage": "https://github.com/HarperFast/rocksdb-js",
     "@harperfast/extended-iterable": "1.0.3",
-    "msgpackr": "1.11.9",
+    "msgpackr": "1.11.10",
     "ordered-binary": "1.6.1"
@@ -39,27 +39,27 @@ },
     "@types/node": "25.6.0",
-    "@vitest/coverage-v8": "4.1.4",
+    "@vitest/coverage-v8": "4.1.5",
     "cross-env": "10.1.0",
     "dotenv": "17.4.2",
-    "lefthook": "2.1.5",
-    "lmdb": "3.5.3",
-    "node-gyp": "12.2.0",
-    "oxfmt": "0.45.0",
-    "oxlint": "1.60.0",
+    "lefthook": "2.1.6",
+    "lmdb": "3.5.4",
+    "node-gyp": "12.3.0",
+    "oxfmt": "0.46.0",
+    "oxlint": "1.61.0",
     "prebuildify": "6.0.1",
     "semver": "7.7.4",
-    "tsdown": "0.21.8",
+    "tsdown": "0.21.10",
     "tslib": "2.8.1",
     "tsx": "4.21.0",
-    "typescript": "6.0.2",
-    "vitest": "4.1.4"
+    "typescript": "6.0.3",
+    "vitest": "4.1.5"
   },
   "optionalDependencies": {
-    "@harperfast/rocksdb-js-darwin-arm64": "1.0.1",
-    "@harperfast/rocksdb-js-darwin-x64": "1.0.1",
-    "@harperfast/rocksdb-js-linux-arm64-glibc": "1.0.1",
-    "@harperfast/rocksdb-js-linux-arm64-musl": "1.0.1",
-    "@harperfast/rocksdb-js-linux-x64-glibc": "1.0.1",
-    "@harperfast/rocksdb-js-linux-x64-musl": "1.0.1",
-    "@harperfast/rocksdb-js-win32-arm64": "1.0.1",
-    "@harperfast/rocksdb-js-win32-x64": "1.0.1"
+    "@harperfast/rocksdb-js-darwin-arm64": "1.1.0",
+    "@harperfast/rocksdb-js-darwin-x64": "1.1.0",
+    "@harperfast/rocksdb-js-linux-arm64-glibc": "1.1.0",
+    "@harperfast/rocksdb-js-linux-arm64-musl": "1.1.0",
+    "@harperfast/rocksdb-js-linux-x64-glibc": "1.1.0",
+    "@harperfast/rocksdb-js-linux-x64-musl": "1.1.0",
+    "@harperfast/rocksdb-js-win32-arm64": "1.1.0",
+    "@harperfast/rocksdb-js-win32-x64": "1.1.0"
   },
@@ -66,0 +66,0 @@ "engines": {

README.md

@@ -57,2 +57,5 @@ # rocksdb-js
     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
@@ -445,2 +448,20 @@ overhead. Defaults to `StatsLevel.ExceptDetailedTimers`.
 
+### 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>`
@@ -491,3 +512,3 @@
   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.
@@ -668,5 +689,6 @@ - `txn.setTimestamp(ts?: number): void` Overrides the transaction start timestamp. If called without
 
-### `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.
 
@@ -677,6 +699,7 @@ ```typescript
 
-### `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.
 
@@ -731,2 +754,10 @@ By default, it only returns the most meaningful internal stats. When `all = true`, it returns the
 
+### `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`
@@ -733,0 +764,0 @@

New alerts

AI-detected potential code anomaly

Supply chain risk

AI has identified unusual behaviors that may pose a security risk.

Found 1 instance in 1 package

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

Fixed alerts

Long strings

Supply chain risk

Contains long string literals, which may be a sign of obfuscated or packed code.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

494068

1.34%

Lines of code

3837

1.16%

Number of lines in readme file

1360

2.33%

Worsened metrics

Number of low supply chain risk alerts

25

4.17%

Dependency changes

• + Added

  @harperfast/rocksdb-js-darwin-arm64@1.1.0
  (transitive)

• + Added

  @harperfast/rocksdb-js-darwin-x64@1.1.0
  (transitive)

• + Added

  @harperfast/rocksdb-js-linux-arm64-glibc@1.1.0
  (transitive)

• + Added

  @harperfast/rocksdb-js-linux-arm64-musl@1.1.0
  (transitive)

• + Added

  @harperfast/rocksdb-js-linux-x64-glibc@1.1.0
  (transitive)

• + Added

  @harperfast/rocksdb-js-linux-x64-musl@1.1.0
  (transitive)

• + Added

  @harperfast/rocksdb-js-win32-arm64@1.1.0
  (transitive)

• + Added

  @harperfast/rocksdb-js-win32-x64@1.1.0
  (transitive)

• + Added

  msgpackr@1.11.10
  (transitive)

• - Removed

  @harperfast/rocksdb-js-darwin-arm64@1.0.1
  (transitive)

• - Removed

  @harperfast/rocksdb-js-darwin-x64@1.0.1
  (transitive)

• - Removed

  @harperfast/rocksdb-js-linux-arm64-glibc@1.0.1
  (transitive)

• - Removed

  @harperfast/rocksdb-js-linux-arm64-musl@1.0.1
  (transitive)

• - Removed

  @harperfast/rocksdb-js-linux-x64-glibc@1.0.1
  (transitive)

• - Removed

  @harperfast/rocksdb-js-linux-x64-musl@1.0.1
  (transitive)

• - Removed

  @harperfast/rocksdb-js-win32-arm64@1.0.1
  (transitive)

• - Removed

  @harperfast/rocksdb-js-win32-x64@1.0.1
  (transitive)

• - Removed

  msgpackr@1.11.9
  (transitive)

• Updated

  msgpackr@1.11.10