@harperfast/rocksdb-js 2.10.0 → 2.12.0

package/dist/index.cjs

@@ -130,7 +130,17 @@ const NativeDatabase = binding.Database;
 const NativeIterator = binding.Iterator;
 const NativeTransaction = binding.Transaction;
 const TransactionLog = binding.TransactionLog;
-const registryStatus = binding.registryStatus;
+/**
+* Returns the status of every database currently held by the native registry.
+* Walks every registered descriptor, so it samples live state rather than
+* reading a stored property.
+*/
+const getRegistryStatus = binding.registryStatus;
+/**
+* @deprecated Use {@link getRegistryStatus} instead. This alias will be removed
+* in v3.0.0.
+*/
+const registryStatus = getRegistryStatus;
 /**
 * Flushes every open database and waits for outstanding compactions, then
 * releases the registry.
@@ -194,6 +204,12 @@ const coolTransactionLogs = binding.coolTransactionLogs;
 */
 const transactionLogMapCount = binding.transactionLogMapCount;
 /**
+* Number of coordinated-retry wake callbacks registered on verification-table
+* locks across the process. Internal — used by tests to verify that a park
+* ending by timeout, env teardown, or close leaves no registration behind.
+*/
+const lockWakeCallbackCount = binding.lockWakeCallbackCount;
+/**
 * Test-only: force the next `count` transaction commits to fail with TryAgain (rolled back, so
 * no data is committed), reproducing a stranded-snapshot conflict deterministically. Pass 0 to
 * disarm. Used by the ERR_TRY_AGAIN retry regression test.
@@ -534,6 +550,14 @@ const backups = {
 	* Verifies a backup's file sizes, and optionally their checksums (which
 	* requires reading all backed-up data).
 	*
+	* Set `verifyTables: true` to also prove this build can read the backup
+	* before restoring it: every table file is opened, one at a time, and its
+	* footer (including `format_version`) and properties must be readable, and
+	* every compression algorithm it records must be supported by this build.
+	* A checksum-valid table written by a newer or differently built RocksDB
+	* otherwise passes and fails on the first read after a restore. Blob files
+	* are not checked.
+	*
 	* When the backup was created with `transactionLogs: true`, the backup's
 	* transaction log snapshot (`<backupDir>/transaction_logs/<backupId>/`) is
 	* also validated — every log file's header and entry framing must be intact
@@ -541,7 +565,9 @@ const backups = {
 	* is a verification failure). Set `verifyTransactionLogs: false` to skip.
 	*/
 	async verify(backupDir, backupId, options) {
-		await new Promise((resolve, reject) => nativeBackupVerify(resolve, reject, backupDir, backupId, options?.verifyWithChecksum ?? false));
+		const verifyTables = options?.verifyTables;
+		if (verifyTables !== void 0 && typeof verifyTables !== "boolean") throw new TypeError(`verifyTables must be a boolean, received ${verifyTables === null ? "null" : typeof verifyTables}`);
+		await new Promise((resolve, reject) => nativeBackupVerify(resolve, reject, backupDir, backupId, options?.verifyWithChecksum ?? false, verifyTables === true));
 		if (options?.verifyTransactionLogs === false) return;
 		const logsDir = (0, node_path.join)(backupDir, TRANSACTION_LOGS_DIRNAME, String(backupId));
 		if (!await exists(logsDir)) return;
@@ -1731,6 +1757,7 @@ var Store = class {
 	/**
 	* The target maximum size of a transaction log before rotation. Transactions
 	* are never split across files, so one transaction may exceed this target.
+	* Defaults to 16 MiB. `0` (formerly unlimited) is rejected at open.
 	*/
 	transactionLogMaxSize;
 	/**
@@ -1745,6 +1772,11 @@ var Store = class {
 	*/
 	transactionLogsPath;
 	/**
+	* The transaction log whose batch keys this process originates; seeds the
+	* monotonic timestamp floor at open. See `StoreOptions.timestampFloorLog`.
+	*/
+	timestampFloorLog;
+	/**
 	* Whether this store's column family participates in the VerificationTable.
 	*/
 	verificationTable;
@@ -1803,6 +1835,7 @@ var Store = class {
 		this.transactionLogMaxSize = options?.transactionLogMaxSize;
 		this.transactionLogRetention = options?.transactionLogRetention;
 		this.transactionLogsPath = options?.transactionLogsPath;
+		this.timestampFloorLog = options?.timestampFloorLog;
 		this.verificationTable = options?.verificationTable;
 		this.writeBufferSize = options?.writeBufferSize;
 		this.writeKey = writeKey;
@@ -2167,6 +2200,7 @@ var Store = class {
 			transactionLogMaxSize: this.transactionLogMaxSize,
 			transactionLogRetentionMs: this.transactionLogRetention ? parseDuration(this.transactionLogRetention) : void 0,
 			transactionLogsPath: this.transactionLogsPath,
+			timestampFloorLog: this.timestampFloorLog,
 			verificationTable: this.verificationTable,
 			writeBufferSize: this.writeBufferSize
 		});
@@ -2648,6 +2682,66 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		return this.store.db.getCompression();
 	}
 	/**
+	* Dynamically changes the compression algorithm (and optional level) for
+	* this database's column family on an already-open database — no close, no
+	* reopen, and it does not conflict with another handle that already has
+	* this column family open (unlike an explicit open-time `compression`
+	* mismatch). That other handle's live options change too, silently,
+	* without notice; a later explicit reopen of it is compared against the
+	* new value, so a stale request it still holds can then conflict. Backed
+	* by RocksDB's `DB::SetOptions()`, which documents both `compression` and
+	* `blob_compression_type` as mutable column family options.
+	*
+	* This governs only *newly written* files (the next flush and any future
+	* compaction output) going forward; SST and blob files already on disk
+	* keep their existing compression until they are rewritten by a later
+	* compaction. `compact()`'s default options can skip already-bottommost
+	* files; use `compact({ bottommost: true })` to rewrite them under the new
+	* codec. This is the live-mutation counterpart to the open-time
+	* `compression` option — see the README's Compression section for when to
+	* use each.
+	*
+	* @example
+	* ```typescript
+	* const db = RocksDatabase.open('/path/to/db', { compression: 'none' });
+	* db.setCompression({ algorithm: 'zstd', level: 19 });
+	* // new writes are now compressed with zstd; existing SSTs are untouched
+	* // until compacted.
+	* ```
+	*/
+	setCompression(compression) {
+		const { compression: algorithm, compressionLevel } = normalizeCompression(compression);
+		if (algorithm === void 0) throw new TypeError("setCompression requires a compression algorithm");
+		try {
+			this.store.db.setCompression(algorithm, compressionLevel);
+		} catch (error) {
+			if (error?.appliedInMemoryOnly) this.syncStoreCompressionFromLive();
+			throw error;
+		}
+		this.syncStoreCompressionFromLive();
+	}
+	/**
+	* Resyncs the store's cached open-time compression option from the live
+	* database state after `setCompression()`. Also clears
+	* `compressionForAllColumnFamilies`: that flag means "apply this option to
+	* every column family opened for this database", which no longer describes
+	* a live change scoped to a single column family — leaving it set would
+	* restamp every other family with this algorithm on the next
+	* same-instance `close()` + `open()`.
+	*
+	* The flag clear is unconditional (a plain assignment, so it cannot itself
+	* fail) and comes first: a concurrent close racing the live-state read
+	* below throws "Database not open" from the getter, and that read failing
+	* must not also skip the flag clear -- otherwise the same restamp this
+	* method exists to prevent survives on the next open().
+	*/
+	syncStoreCompressionFromLive() {
+		this.store.compressionForAllColumnFamilies = false;
+		try {
+			this.store.compression = this.compression;
+		} catch {}
+	}
+	/**
 	* The informational-log settings currently in effect for this database,
 	* read live from RocksDB, as `{ maxLogFileSize, infoLogLevel }`. These are
 	* database-wide settings (not per-column-family): `maxLogFileSize` bounds
@@ -3651,18 +3745,11 @@ function findResyncPosition(dataView, from, dataEnd) {
 	}
 }
 /**
-* Builds the report for a broken frame, with the offset iteration should continue from. Resolves
-* the written extent here rather than per frame: `getLogFileSize` crosses into native and takes
-* the store mutex, which a healthy read must never pay.
+* Builds the report for a broken frame, with the offset iteration should continue from.
 */
 function corruptFrame(message, transactionLog, dataView, logBuffer, position, limit, size, readUncommitted) {
 	let dataEnd = limit;
-	if (readUncommitted) try {
-		const writtenExtent = transactionLog.getLogFileSize(logBuffer.logId);
-		dataEnd = writtenExtent > 0 ? Math.min(logBuffer.length, writtenExtent) : 0;
-	} catch {
-		dataEnd = 0;
-	}
+	if (readUncommitted) dataEnd = Math.min(logBuffer.length, logBuffer.size ?? readableExtent(logBuffer));
 	const resyncPosition = findResyncPosition(dataView, position + 1, dataEnd);
 	return {
 		error: new CorruptFrameError(message, logBuffer.logId, position, resyncPosition),
@@ -3692,7 +3779,7 @@ Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, e
 	let logId = latestLogId;
 	let position = 0;
 	let dataView;
-	let logBuffer = this._currentLogBuffer;
+	let logBuffer = this._currentLogBuffer?.deref();
 	let foundExactStart = false;
 	if (start === void 0 && !startFromLastFlushed) {
 		position = size;
@@ -3710,7 +3797,7 @@ Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, e
 	}
 	if (logBuffer === void 0 || logBuffer.logId !== logId) {
 		logBuffer = getLogMemoryMap(this, logId);
-		if (logBuffer && latestLogId === logId && !readUncommitted) this._currentLogBuffer = logBuffer;
+		if (logBuffer && latestLogId === logId && !readUncommitted && this._currentLogBuffer?.deref() !== logBuffer) this._currentLogBuffer = new WeakRef(logBuffer);
 		if (logBuffer === void 0) {
 			logBuffer = Buffer.alloc(0);
 			logBuffer.logId = 0;
@@ -3720,9 +3807,11 @@ Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, e
 		}
 	}
 	dataView = logBuffer.dataView;
-	if (latestLogId !== logId) {
-		size = logBuffer.size;
-		if (size === void 0) size = logBuffer.size = this.getLogFileSize(logId);
+	if (latestLogId < logId) size = 0;
+	else if (latestLogId > logId) {
+		const cachedSize = logBuffer.size;
+		if (cachedSize === void 0) size = logBuffer.size = readableExtent(logBuffer);
+		else size = cachedSize;
 	}
 	return {
 		[Symbol.iterator]() {
@@ -3732,15 +3821,15 @@ Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, e
 			let timestamp;
 			if (position >= size) {
 				const { logId: latestLogId, size: latestSize } = loadLastPosition(transactionLog, !!readUncommitted);
-				size = latestSize;
+				size = latestLogId < logBuffer.logId ? 0 : latestSize;
 				if (latestLogId > logBuffer.logId) {
-					size = logBuffer.size ?? (logBuffer.size = transactionLog.getLogFileSize(logBuffer.logId));
+					size = logBuffer.size ?? (logBuffer.size = readableExtent(logBuffer));
 					if (position >= size) {
-						const nextLogBuffer = getLogMemoryMap(transactionLog, logBuffer.logId + 1);
+						const nextLogBuffer = nextReadableLogBuffer(transactionLog, logBuffer.logId, latestLogId);
 						if (nextLogBuffer) {
 							dataView = nextLogBuffer.dataView;
 							logBuffer = nextLogBuffer;
-							if (latestLogId > logBuffer.logId) size = logBuffer.size ?? (logBuffer.size = transactionLog.getLogFileSize(logBuffer.logId));
+							if (latestLogId > logBuffer.logId) size = logBuffer.size ?? (logBuffer.size = readableExtent(logBuffer));
 							else size = latestSize;
 							position = TRANSACTION_LOG_FILE_HEADER_SIZE;
 						}
@@ -3791,19 +3880,25 @@ Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, e
 				};
 				if (position >= size) {
 					const { logId: latestLogId, size: latestSize } = loadLastPosition(transactionLog, !!readUncommitted);
-					size = latestSize;
+					size = latestLogId < logBuffer.logId ? 0 : latestSize;
 					if (latestLogId > logBuffer.logId) {
-						const nextLogBuffer = getLogMemoryMap(transactionLog, logBuffer.logId + 1);
+						size = logBuffer.size ?? readableExtent(logBuffer);
+						if (!readUncommitted) logBuffer.size = size;
+						if (position < size) continue;
+						const nextLogBuffer = nextReadableLogBuffer(transactionLog, logBuffer.logId, latestLogId);
 						if (!nextLogBuffer) return {
 							done: true,
 							value: void 0
 						};
 						logBuffer = nextLogBuffer;
 						dataView = logBuffer.dataView;
-						size = logBuffer.size;
-						if (size == void 0) {
-							size = transactionLog.getLogFileSize(logBuffer.logId);
-							if (!readUncommitted) logBuffer.size = size;
+						if (latestLogId === logBuffer.logId) size = latestSize;
+						else {
+							const cachedSize = logBuffer.size;
+							if (cachedSize === void 0) {
+								size = readableExtent(logBuffer);
+								if (!readUncommitted) logBuffer.size = size;
+							} else size = cachedSize;
 						}
 						position = TRANSACTION_LOG_FILE_HEADER_SIZE;
 					}
@@ -3816,6 +3911,35 @@ Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, e
 		}
 	};
 } });
+/**
+* Maps the next readable segment after `fromLogId`, skipping a run retention has deleted —
+* stopping at the hole wedges the iterator there for every later poll (invariant 30).
+*
+* The jump target is `_nextLogId()`, the successor over the store's registered segments — *not*
+* `_findPosition(0)`, which names the bottom of the contiguous run ending at the current segment
+* and so lands *past* a survivor sitting between two holes.
+*/
+function nextReadableLogBuffer(transactionLog, fromLogId, latestLogId) {
+	let candidateLogId = fromLogId + 1;
+	while (candidateLogId <= latestLogId) {
+		const logBuffer = getLogMemoryMap(transactionLog, candidateLogId);
+		if (logBuffer) {
+			if (candidateLogId === latestLogId || readableExtent(logBuffer) > TRANSACTION_LOG_FILE_HEADER_SIZE) return logBuffer;
+		} else if (transactionLog.getLogFileSize(candidateLogId) > TRANSACTION_LOG_FILE_HEADER_SIZE) return;
+		candidateLogId = transactionLog._nextLogId(candidateLogId);
+		if (candidateLogId === 0) return;
+	}
+}
+/**
+* The bound for reading `logBuffer`. Native advances this append-owned extent only after a
+* successful write. It remains attached to the mapping after purge forgets the file object, so
+* readers retain committed history without interpreting a partial failed append as another frame.
+*/
+function readableExtent(logBuffer) {
+	const extent = logBuffer.readableExtent;
+	if (extent === void 0) throw new Error(`Transaction log buffer ${logBuffer.logId} has no readableExtent`);
+	return Math.min(logBuffer.length, extent);
+}
 function getLogMemoryMap(transactionLog, logId) {
 	if (logId <= 0) return;
 	let logBuffer = transactionLog._logBuffers.get(logId)?.deref();
@@ -3861,7 +3985,7 @@ function loadLastPosition(transactionLog, readUncommitted) {
 //#region src/index.ts
 const versions = {
 	rocksdb: version,
-	"rocksdb-js": "2.10.0"
+	"rocksdb-js": "2.12.0"
 };
 
 //#endregion
@@ -3879,6 +4003,7 @@ exports.constants = constants;
 exports.coolTransactionLogs = coolTransactionLogs;
 exports.currentThreadId = currentThreadId;
 exports.fileLockRelease = fileLockRelease;
+exports.getRegistryStatus = getRegistryStatus;
 exports.getWriteBufferManagerStats = getWriteBufferManagerStats;
 exports.parseTransactionLog = parseTransactionLog;
 exports.registryStatus = registryStatus;