@harperfast/rocksdb-js 2.9.1 → 2.11.0

package/dist/index.mjs

@@ -105,10 +105,60 @@ 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.
+*
+* **Throws** the first failure it encounters: a close whose native teardown
+* failed (that descriptor stays quarantined — call `shutdown()` again to retry
+* it), or a `lifecycleWaitSeconds` timeout waiting on a concurrent
+* open/destroy/shutdown. A quarantining close also emits
+* `database:closeFailed`; a timeout has no event, so the throw is its only
+* signal.
+*
+* A `process.on('exit')` listener must therefore wrap it: an exception thrown
+* from an `exit` listener skips every `exit` listener registered after it (and
+* sets exit code 1 unless an `uncaughtException` handler is installed).
+*
+* ```typescript
+* process.on('exit', () => {
+* 	try {
+* 		shutdown();
+* 	} catch (error) {
+* 		console.error('rocksdb-js shutdown failed', error);
+* 	}
+* });
+* ```
+*/
 const shutdown = binding.shutdown;
 const currentThreadId = binding.currentThreadId;
 /**
+* Reads the process-wide steady clock: `std::chrono::steady_clock` as
+* fractional milliseconds from an unspecified origin that is fixed for the life
+* of the process. Every sample in the process — main thread and every
+* `worker_threads` worker, whenever started or restarted, on Node, Bun and Deno
+* — is in one domain, and the difference between two samples is real elapsed
+* time unaffected by wall-clock steps. Non-decreasing but not unique (two
+* samples may be equal; treat `==` as "not later"). Windows QPC samples from
+* different threads within one native tick also have ambiguous ordering.
+* Clock readings alone do not prove causality. Not comparable with
+* `Date.now()`, `db.getMonotonicTimestamp()` or transaction timestamps, and not
+* meaningful across processes or restarts. Time spent in host suspend is
+* platform-defined. No open database is needed.
+*/
+const steadyClockNow = binding.steadyClockNow;
+/**
 * Advises the kernel that the file-backed pages of every mapped transaction log
 * are cold (Linux MADV_COLD), so they are reclaimed first under memory pressure
 * without being freed — useful during replication catch-up, where a full read of
@@ -129,11 +179,32 @@ 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.
 */
 const forceTryAgainForTesting = binding.forceTryAgainForTesting;
+/**
+* Test-only seam: makes the physical column-family drop report failure.
+* `0` = inert, `1` = fail without dropping (the retry performs the drop),
+* `2` = drop for real and then report failure (the retry resolves as
+* "already dropped"). Process-global, like `forceTryAgainForTesting`.
+*/
+const forceDropFailureForTesting = binding.forceDropFailureForTesting;
+/** Parks one selected transaction write after its retirement precheck. */
+const setTransactionStagingDelayForTesting = binding.setTransactionStagingDelayForTesting;
+/** Reports whether the selected transaction write is parked. */
+const isTransactionStagingDelayedForTesting = binding.isTransactionStagingDelayedForTesting;
+/** Reports whether a transaction is parked at the native commit seam. */
+const isTransactionCommitExecuteDelayedForTesting = binding.isTransactionCommitExecuteDelayedForTesting;
+const setTransactionCommitAdmissionDelayForTesting = binding.setTransactionCommitAdmissionDelayForTesting;
+const isTransactionCommitAdmissionDelayedForTesting = binding.isTransactionCommitAdmissionDelayedForTesting;
 /** Delays one selected watchdog join in the concurrent-shutdown regression test. */
 const setWriteBufferManagerJoinDelayForTesting = binding.setWriteBufferManagerJoinDelayForTesting;
 /**
@@ -1651,6 +1722,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;
 	/**
@@ -1665,6 +1737,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;
@@ -1723,6 +1800,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;
@@ -2087,6 +2165,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
 		});
@@ -2094,12 +2173,12 @@ var Store = class {
 		return false;
 	}
 	putSync(context, key, value, options) {
-		if (!this.db.opened) throw new Error("Database not open");
+		if (!this.db.opened) throw new Error(this.db.closing ? "Database is closing" : "Database not open");
 		const valueBuffer = this.encodeValue(value);
 		context.putSync(this.encodeKey(key), valueBuffer, this.getTxnId(options));
 	}
 	removeSync(context, key, options) {
-		if (!this.db.opened) throw new Error("Database not open");
+		if (!this.db.opened) throw new Error(this.db.closing ? "Database is closing" : "Database not open");
 		context.removeSync(this.encodeKey(key), this.getTxnId(options));
 	}
 	/**
@@ -2568,6 +2647,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
@@ -2603,7 +2742,10 @@ var RocksDatabase = class RocksDatabase extends DBI {
 	* native binding use namespaced keys (e.g. `'transactionLog:warning'`).
 	*
 	* Listeners are not tied to any specific database — they fire for every
-	* matching event emitted in this process.
+	* matching event emitted in this process. Native lifecycle failures use
+	* `'database:closeFailed'` with `(path, error)` string arguments. The event
+	* reports both completed and incomplete teardowns; an incomplete close can
+	* be retried by `shutdown()` or explicitly deleted by `destroy()`.
 	*
 	* @example
 	* ```typescript
@@ -2687,7 +2829,7 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		this.store.db.catchUpWithPrimarySync();
 	}
 	destroy() {
-		this.store.db.destroy();
+		this.store.db.destroy(this.store.readOnly);
 	}
 	async drop() {
 		return new Promise((resolve, reject) => {
@@ -3553,8 +3695,8 @@ function frameFits(dataView, pos, dataEnd) {
 * terminator, let a chain "end" anywhere in megabytes of padding. Against the written extent the
 * end is a single offset, so a chain landing on it is ~1/2^32 to be coincidence.
 *
-* The JS counterpart of `validFramingResumes()` in `transaction_log_recovery.cpp`, which answers
-* the same question at open time but keeps only the yes/no, discarding the offset.
+* The JS counterpart of `findFramingResumeOffset()` in `transaction_log_recovery.cpp`, which the
+* open-time scan and the timestamp index use to keep walking past the same break.
 */
 function findResyncPosition(dataView, from, dataEnd) {
 	const lastStart = dataEnd - TRANSACTION_LOG_ENTRY_HEADER_SIZE;
@@ -3568,18 +3710,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),
@@ -3609,7 +3744,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;
@@ -3627,7 +3762,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;
@@ -3637,9 +3772,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]() {
@@ -3649,15 +3786,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;
 						}
@@ -3708,19 +3845,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;
 					}
@@ -3733,6 +3876,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();
@@ -3778,9 +3950,9 @@ function loadLastPosition(transactionLog, readUncommitted) {
 //#region src/index.ts
 const versions = {
 	rocksdb: version,
-	"rocksdb-js": "2.9.1"
+	"rocksdb-js": "2.11.0"
 };
 
 //#endregion
-export { BackgroundError, CorruptFrameError, CountEstimator, DBI, DBIterator, RocksDatabase, Store, Transaction, TransactionLog, backups, constants, coolTransactionLogs, currentThreadId, fileLockRelease, getWriteBufferManagerStats, parseTransactionLog, registryStatus, shutdown, stats, supportedCompression, tryFileLock, validateTransactionLogStore, versions };
+export { BackgroundError, CorruptFrameError, CountEstimator, DBI, DBIterator, RocksDatabase, Store, Transaction, TransactionLog, backups, constants, coolTransactionLogs, currentThreadId, fileLockRelease, getRegistryStatus, getWriteBufferManagerStats, parseTransactionLog, registryStatus, shutdown, stats, steadyClockNow, supportedCompression, tryFileLock, validateTransactionLogStore, versions };
 //# sourceMappingURL=index.mjs.map