@harperfast/rocksdb-js 1.1.0 → 1.2.0

package/dist/index.cjs

@@ -453,42 +453,62 @@ var DBI = class DBI {
 
 //#endregion
 //#region src/dbi-iterator.ts
+const { ITERATOR_RESULT_DONE, ITERATOR_RESULT_FAST } = constants;
+const DONE_RESULT = Object.freeze({
+	done: true,
+	value: void 0
+});
 /**
-* Wraps an iterator, namely the `NativeIterator` class, and decodes the key
-* and value.
+* Wraps the `NativeIterator` C++ binding, decoding keys and values from the
+* shared key/value buffers (fast path) or from per-iteration buffers (slow
+* fallback path used for oversized data or stable-buffer decoders).
+*
+* The native `next()` returns a primitive signal (and writes lengths to the
+* shared `ITERATOR_STATE` buffer) instead of constructing a JS result object,
+* so this class is responsible for building the `IteratorResult`.
 */
 var DBIterator = class {
 	iterator;
 	store;
 	#includeValues;
-	constructor(iterator, store, options) {
+	constructor(iterator, store, includeValues) {
 		this.iterator = iterator;
 		this.store = store;
-		this.#includeValues = options?.values ?? true;
+		this.#includeValues = includeValues;
 	}
 	[Symbol.iterator]() {
 		return this;
 	}
-	next(...[_value]) {
+	next() {
 		const result = this.iterator.next();
-		if (result.done) return result;
+		if (result === ITERATOR_RESULT_DONE) return DONE_RESULT;
+		const includeValues = this.#includeValues;
 		const value = {};
-		value.key = this.store.decodeKey(result.value.key);
-		if (this.#includeValues) value.value = this.store.decodeValue(result.value.value);
+		if (result === ITERATOR_RESULT_FAST) {
+			value.key = this.store.readKey(KEY_BUFFER, 0, ITERATOR_STATE[0]);
+			if (includeValues) {
+				VALUE_BUFFER.end = ITERATOR_STATE[1];
+				value.value = this.store.decodeValue(VALUE_BUFFER);
+			}
+		} else {
+			const slow = result;
+			value.key = this.store.decodeKey(slow.key);
+			if (includeValues && slow.value !== void 0) value.value = this.store.decodeValue(slow.value);
+		}
 		return {
 			done: false,
 			value
 		};
 	}
 	return(value) {
-		if (this.iterator.return) return this.iterator.return(value);
+		this.iterator.return?.();
 		return {
 			done: true,
 			value
 		};
 	}
 	throw(err) {
-		if (this.iterator.throw) return this.iterator.throw(err);
+		this.iterator.throw?.(err);
 		throw err;
 	}
 };
@@ -563,10 +583,17 @@ function createFixedBuffer(size) {
 
 //#endregion
 //#region src/store.ts
-const { ONLY_IF_IN_MEMORY_CACHE_FLAG, NOT_IN_MEMORY_CACHE_FLAG, ALWAYS_CREATE_NEW_BUFFER_FLAG } = constants;
+const { ONLY_IF_IN_MEMORY_CACHE_FLAG, NOT_IN_MEMORY_CACHE_FLAG, ALWAYS_CREATE_NEW_BUFFER_FLAG, ITERATOR_REVERSE_FLAG, ITERATOR_INCLUSIVE_END_FLAG, ITERATOR_EXCLUSIVE_START_FLAG, ITERATOR_INCLUDE_VALUES_FLAG, ITERATOR_NEEDS_STABLE_VALUE_BUFFER_FLAG, ITERATOR_CONTEXT_IS_TRANSACTION_FLAG } = constants;
 const KEY_BUFFER_SIZE = 4096;
 const KEY_BUFFER = createFixedBuffer(KEY_BUFFER_SIZE);
 const VALUE_BUFFER = createFixedBuffer(64 * 1024);
+/**
+* Backing buffer for the shared iterator state. Layout (Uint32Array view):
+*   [0] = key length written into KEY_BUFFER by the most recent iterator step
+*   [1] = value length written into VALUE_BUFFER by the most recent step
+*/
+const ITERATOR_STATE_BUFFER = Buffer.allocUnsafeSlow(8);
+const ITERATOR_STATE = new Uint32Array(ITERATOR_STATE_BUFFER.buffer, ITERATOR_STATE_BUFFER.byteOffset, 2);
 const MAX_KEY_SIZE = 1024 * 1024;
 const RESET_BUFFER_MODE = 1024;
 const REUSE_BUFFER_MODE = 512;
@@ -745,6 +772,52 @@ var Store = class {
 		this.db.close();
 	}
 	/**
+	* Compacts the entire key range of the database asynchronously.
+	* This triggers manual compaction which removes tombstones and reclaims space.
+	*
+	* @example
+	* ```typescript
+	* const db = RocksDatabase.open('/path/to/database');
+	* await db.compact();
+	* ```
+	*/
+	compact(options) {
+		let startBuffer;
+		let endBuffer;
+		if (options?.start !== void 0) {
+			const start = this.encodeKey(options.start);
+			startBuffer = Buffer.from(start.subarray(start.start, start.end));
+		}
+		if (options?.end !== void 0) {
+			const end = this.encodeKey(options.end);
+			endBuffer = Buffer.from(end.subarray(end.start, end.end));
+		}
+		return new Promise((resolve, reject) => this.db.compact(resolve, reject, startBuffer, endBuffer));
+	}
+	/**
+	* Compacts the entire key range of the database synchronously.
+	* This triggers manual compaction which removes tombstones and reclaims space.
+	*
+	* @example
+	* ```typescript
+	* const db = RocksDatabase.open('/path/to/database');
+	* db.compactSync();
+	* ```
+	*/
+	compactSync(options) {
+		let startBuffer;
+		let endBuffer;
+		if (options?.start !== void 0) {
+			const start = this.encodeKey(options.start);
+			startBuffer = Buffer.from(start.subarray(start.start, start.end));
+		}
+		if (options?.end !== void 0) {
+			const end = this.encodeKey(options.end);
+			endBuffer = Buffer.from(end.subarray(end.start, end.end));
+		}
+		this.db.compactSync(startBuffer, endBuffer);
+	}
+	/**
 	* Decodes a key from the database.
 	*
 	* @param key - The key to decode.
@@ -832,27 +905,45 @@ var Store = class {
 	}
 	getRange(context, options) {
 		if (!this.db.opened) throw new Error("Database not open");
-		options = { ...options };
-		const unencodedStartKey = options.key ?? options.start;
-		if (unencodedStartKey !== void 0) {
-			const start = this.encodeKey(unencodedStartKey);
-			options.start = Buffer.from(start.subarray(start.start, start.end));
+		let startUnencoded = options?.key ?? options?.start;
+		let endUnencoded = options?.key ?? options?.end;
+		const includeValues = options?.values ?? true;
+		const reverse = options?.reverse ?? false;
+		let exclusiveStart = options?.exclusiveStart ?? false;
+		let inclusiveEnd = options?.inclusiveEnd ?? false;
+		if (options?.key !== void 0) inclusiveEnd = true;
+		if (reverse) {
+			const tmp = startUnencoded;
+			startUnencoded = endUnencoded;
+			endUnencoded = tmp;
+			exclusiveStart = options?.exclusiveStart ?? true;
+			inclusiveEnd = options?.inclusiveEnd ?? true;
 		}
-		if (options.key !== void 0) {
-			options.end = options.start;
-			options.inclusiveEnd = true;
-		} else if (options.end !== void 0) {
-			const end = this.encodeKey(options.end);
-			options.end = Buffer.from(end.subarray(end.start, end.end));
+		const keyBuffer = this.keyBuffer;
+		let startKeyEnd = 0;
+		let endKeyStart = 0;
+		let endKeyEnd = 0;
+		if (startUnencoded !== void 0) {
+			startKeyEnd = this.writeKey(startUnencoded, keyBuffer, 0);
+			if (startKeyEnd === 0) throw new Error("Zero length key is not allowed");
 		}
-		if (options.reverse) {
-			const start = options.start;
-			options.start = options.end;
-			options.end = start;
-			options.exclusiveStart = options.exclusiveStart ?? true;
-			options.inclusiveEnd = options.inclusiveEnd ?? true;
+		if (endUnencoded !== void 0) if (endUnencoded === startUnencoded) {
+			endKeyStart = 0;
+			endKeyEnd = startKeyEnd;
+		} else {
+			endKeyStart = startKeyEnd;
+			endKeyEnd = this.writeKey(endUnencoded, keyBuffer, endKeyStart);
+			if (endKeyEnd === endKeyStart) throw new Error("Zero length key is not allowed");
 		}
-		return new _harperfast_extended_iterable.ExtendedIterable(new DBIterator(new NativeIterator(context, options), this, options));
+		let flags = 0;
+		if (reverse) flags |= ITERATOR_REVERSE_FLAG;
+		if (exclusiveStart) flags |= ITERATOR_EXCLUSIVE_START_FLAG;
+		if (inclusiveEnd) flags |= ITERATOR_INCLUSIVE_END_FLAG;
+		if (includeValues) flags |= ITERATOR_INCLUDE_VALUES_FLAG;
+		if (includeValues && !this.decoderCopies) flags |= ITERATOR_NEEDS_STABLE_VALUE_BUFFER_FLAG;
+		if (context !== this.db) flags |= ITERATOR_CONTEXT_IS_TRANSACTION_FLAG;
+		const advancedOptions = options !== void 0 && (options.adaptiveReadahead !== void 0 || options.asyncIO !== void 0 || options.autoReadaheadSize !== void 0 || options.backgroundPurgeOnIteratorCleanup !== void 0 || options.fillCache !== void 0 || options.readaheadSize !== void 0 || options.tailing !== void 0) ? options : void 0;
+		return new _harperfast_extended_iterable.ExtendedIterable(new DBIterator(new NativeIterator(context, flags, startKeyEnd, endKeyStart, endKeyEnd, advancedOptions), this, includeValues));
 	}
 	getSync(context, key, alwaysCreateNewBuffer = false, options) {
 		const keyParam = getKeyParam(this.encodeKey(key));
@@ -1219,6 +1310,38 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		this.store.close();
 	}
 	/**
+	* Compacts the entire key range of the database asynchronously.
+	* This triggers manual compaction which removes tombstones and reclaims space.
+	*
+	* @example
+	* ```typescript
+	* const db = RocksDatabase.open('/path/to/database');
+	* await db.compact();
+	* ```
+	*/
+	compact(options) {
+		return this.store.compact(options);
+	}
+	/**
+	* Compacts the entire key range of the database synchronously.
+	* This triggers manual compaction which removes tombstones and reclaims space.
+	*
+	* @example
+	* ```typescript
+	* const db = RocksDatabase.open('/path/to/database');
+	* db.compactSync();
+	* ```
+	*/
+	compactSync(options) {
+		return this.store.compactSync(options);
+	}
+	/**
+	* 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.
@@ -1294,6 +1417,19 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		return this.store.db.getDBProperty(propertyName);
 	}
 	/**
+	* Retrieves the estimated number of keys in the database.
+	*
+	* @example
+	* ```typescript
+	* const db = RocksDatabase.open('/path/to/database');
+	* const estimated = db.getEstimatedKeyCount();
+	* console.log(estimated);
+	* ```
+	*/
+	getEstimatedKeyCount() {
+		return this.getDBIntProperty("rocksdb.estimate-num-keys") ?? 0;
+	}
+	/**
 	* Returns the current timestamp as a monotonically increasing timestamp in
 	* milliseconds represented as a decimal number.
 	*
@@ -1432,6 +1568,7 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		if (store.open()) return this;
 		store.db.setDefaultValueBuffer(VALUE_BUFFER);
 		store.db.setDefaultKeyBuffer(KEY_BUFFER);
+		store.db.setIteratorState(ITERATOR_STATE_BUFFER);
 		/**
 		* The encoder initialization precedence is:
 		* 1. encoder.Encoder
@@ -1462,14 +1599,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({
@@ -1486,16 +1623,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) => {
@@ -1804,6 +1940,7 @@ Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, e
 			logBuffer.logId = 0;
 			logBuffer.size = 0;
 			logBuffer.dataView = new DataView(logBuffer.buffer);
+			size = 0;
 		}
 	}
 	dataView = logBuffer.dataView;
@@ -1931,7 +2068,7 @@ function loadLastPosition(transactionLog, readUncommitted) {
 //#region src/index.ts
 const versions = {
 	rocksdb: version,
-	"rocksdb-js": "1.1.0"
+	"rocksdb-js": "1.2.0"
 };
 
 //#endregion