@harperfast/rocksdb-js 2.7.0 → 2.8.0

package/dist/index.mjs

@@ -55,6 +55,16 @@ function locateBinding() {
 	throw new Error("Unable to locate rocksdb-js native binding");
 }
 const binding = req(locateBinding());
+/**
+* The native `BackgroundError` constructor (a real `Error` subclass). Exported
+* as both a value — for `err instanceof BackgroundError` — and, via declaration
+* merging with the interface above, a type. Instances are produced by the
+* `'error'` event and `db.getLastError()`; consumers rarely construct their own.
+* The `details` param is required and typed to the instance fields so a bare
+* `new BackgroundError()` (which would omit `severity` / `writesDisabled` / …)
+* is a type error.
+*/
+const BackgroundError = binding.BackgroundError;
 const config = binding.config;
 const FRESH_VERSION_FLAG$1 = binding.constants.FRESH_VERSION_FLAG;
 const addGlobalListener = binding.addListener;
@@ -446,6 +456,150 @@ const backups = {
 	}
 };
 
+//#endregion
+//#region src/count-estimator.ts
+/**
+* Below this many traversed entries the observed density is too noisy to
+* calibrate with, so `estimate()` returns the raw statistical estimate.
+*/
+const CALIBRATION_MIN_TRAVERSED = 16;
+const CALIBRATION_MIN_CONFIDENCE = .8;
+/**
+* Bounds on how far the observed-vs-estimated ratio may scale the remainder;
+* the statistical estimate can be arbitrarily wrong at data-block granularity
+* and an unclamped ratio would let one bad sample dominate.
+*/
+const CALIBRATION_MAX = 8;
+/**
+* Progressively refines a range key-count estimate as an iterator traverses
+* the range. The estimate starts as the pure statistical estimate
+* (`estimateCount`) and converges toward the exact count: the traversed
+* portion is exact, and the statistical estimate of the untraversed remainder
+* is calibrated by the observed ratio of actual-to-estimated entries over the
+* portion already traversed.
+*
+* The estimator never touches the iterator itself — the caller reports
+* progress with `advance(lastKey, count)` whenever it wants a checkpoint
+* (e.g. once per page), then reads `estimate()`. The caller owns the
+* progress contract: cursors must move monotonically through the range and
+* each entry must be reported once (a re-reported page inflates the count
+* undetectably). When traversal completes, call `finish()` so `estimate()`
+* returns the exact total instead of adding a block-granular remainder.
+*
+* Each `estimate()` checkpoint queries RocksDB statistics for the two range
+* segments (cost scales with the SSTs overlapping them, not with key count);
+* results are memoized per checkpoint, so repeated reads between `advance()`
+* calls are free.
+*/
+var CountEstimator = class {
+	#store;
+	#start;
+	#end;
+	#exclusiveStart;
+	#inclusiveEnd;
+	#reverse;
+	#cursor;
+	#traversed = 0;
+	#finished = false;
+	#memoized;
+	constructor(store, options) {
+		this.#store = store;
+		this.#reverse = options?.reverse ?? false;
+		this.#start = this.#reverse ? options?.end : options?.start;
+		this.#end = this.#reverse ? options?.start : options?.end;
+		this.#exclusiveStart = options?.exclusiveStart ?? this.#reverse;
+		this.#inclusiveEnd = options?.inclusiveEnd ?? this.#reverse;
+	}
+	/**
+	* The number of entries reported traversed so far.
+	*/
+	get traversed() {
+		return this.#traversed;
+	}
+	/**
+	* Records that iteration has advanced through `count` more entries, ending
+	* at `lastKey`. Pass `count: 0` when an empty page has no last key.
+	*/
+	advance(lastKey, count = 1) {
+		if (lastKey === void 0) {
+			if (count !== 0) throw new Error("CountEstimator.advance requires lastKey when count is nonzero");
+			return;
+		}
+		this.#cursor = lastKey;
+		this.#traversed += count;
+		this.#memoized = void 0;
+	}
+	/**
+	* Marks traversal of the range as complete: `estimate()` becomes the exact
+	* traversed count.
+	*/
+	finish() {
+		this.#finished = true;
+	}
+	/**
+	* Estimates the total number of entries in the full range: the exact
+	* traversed count plus a calibrated statistical estimate of the remainder.
+	* `confidence` is the exactness-weighted blend of the traversed portion
+	* (exact) and the remainder's statistical confidence, so it approaches 1
+	* as the exact portion grows (though a checkpoint can decrease when
+	* calibration makes a large correction), and is exactly 1 after `finish()`.
+	*/
+	estimate() {
+		if (this.#finished) return {
+			count: this.#traversed,
+			confidence: 1
+		};
+		if (this.#memoized !== void 0) return { ...this.#memoized };
+		if (this.#cursor === void 0) {
+			this.#memoized = this.#store.estimateCount({
+				start: this.#start,
+				end: this.#end,
+				exclusiveStart: this.#exclusiveStart,
+				inclusiveEnd: this.#inclusiveEnd
+			});
+			return { ...this.#memoized };
+		}
+		const traversedRange = this.#reverse ? {
+			start: this.#cursor,
+			end: this.#end,
+			inclusiveEnd: this.#inclusiveEnd
+		} : {
+			start: this.#start,
+			exclusiveStart: this.#exclusiveStart,
+			end: this.#cursor,
+			inclusiveEnd: true
+		};
+		const remainingRange = this.#reverse ? {
+			start: this.#start,
+			exclusiveStart: this.#exclusiveStart,
+			end: this.#cursor
+		} : {
+			start: this.#cursor,
+			exclusiveStart: true,
+			end: this.#end,
+			inclusiveEnd: this.#inclusiveEnd
+		};
+		const remainingEstimate = this.#store.estimateCount(remainingRange);
+		let remaining = remainingEstimate.count;
+		let calibrationConfidence = 1;
+		if (this.#traversed >= CALIBRATION_MIN_TRAVERSED) {
+			const traversedEstimate = this.#store.estimateCount(traversedRange);
+			if (traversedEstimate.count >= CALIBRATION_MIN_TRAVERSED && traversedEstimate.confidence >= CALIBRATION_MIN_CONFIDENCE) {
+				const calibration = Math.min(CALIBRATION_MAX, Math.max(1 / CALIBRATION_MAX, this.#traversed / traversedEstimate.count));
+				remaining *= calibration;
+				calibrationConfidence = Math.min(calibration, 1 / calibration);
+			}
+		}
+		const count = Math.round(this.#traversed + remaining);
+		const confidence = count > 0 ? Math.min(.999, (this.#traversed + calibrationConfidence * remainingEstimate.confidence * remaining) / count) : Math.min(.999, calibrationConfidence * remainingEstimate.confidence);
+		this.#memoized = {
+			count,
+			confidence
+		};
+		return { ...this.#memoized };
+	}
+};
+
 //#endregion
 //#region src/util.ts
 /**
@@ -1311,6 +1465,11 @@ var Store = class {
 	*/
 	freezeData;
 	/**
+	* Verbosity of RocksDB's informational logging (`info_log_level`). Omit to
+	* leave RocksDB's own default.
+	*/
+	infoLogLevel;
+	/**
 	* Reusable buffer for encoding keys.
 	*/
 	keyBuffer;
@@ -1323,6 +1482,16 @@ var Store = class {
 	*/
 	maxKeySize;
 	/**
+	* Per-file size cap (bytes) for informational log files (`LOG` /
+	* `LOG.old.*`). Bounds total informational-log footprint to roughly `5 *
+	* maxLogFileSize` (RocksDB retains up to 5 of these files). A value of `0`
+	* is RocksDB's "single unbounded log file" mode: it disables size-based
+	* rotation, so the log can grow without limit — set it only if you want that.
+	*
+	* @default 16777216 (16MB)
+	*/
+	maxLogFileSize;
+	/**
 	* The maximum number of table files RocksDB keeps open. `0` (the default)
 	* derives a budget from the effective per-process open-file limit (an
 	* eighth of the limit — several databases can share one process — clamped
@@ -1341,13 +1510,26 @@ var Store = class {
 	/**
 	* The bytes of recent memtable history to retain in memory for transaction
 	* conflict checking. `-1` derives the value from
-	* `maxWriteBufferNumber * writeBufferSize`.
+	* `maxWriteBufferNumber * writeBufferSize`, except under a stalling
+	* `writeBufferManager`, where it derives `0`: retained history is charged to
+	* that manager and is only trimmable down to this target, so a target the
+	* budget cannot hold stalls writes permanently. Set a number to size it
+	* yourself against the budget and the column-family count.
 	*/
 	maxWriteBufferSizeToMaintain;
 	/**
 	* The total memtable budget in bytes across all column families. When the
-	* sum of memtables reaches this size, RocksDB flushes the largest one. `0`
-	* disables the global trigger so per-CF `writeBufferSize` drives flushing.
+	* sum of memtables reaches this size, RocksDB flushes the largest one.
+	* Defaults to `0`, which disables the global trigger so per-CF
+	* `writeBufferSize` drives flushing.
+	*
+	* Set this only if you know your column-family count: it is one budget split
+	* across all of them, so a value that suits a few families starves many. To
+	* bound total memtable memory instead, configure a WriteBufferManager.
+	*
+	* Database-wide, so it binds when the path is first opened in this process:
+	* a later open of the same path — including from another worker thread —
+	* keeps the first opener's value rather than overriding or rejecting it.
 	*/
 	dbWriteBufferSize;
 	/**
@@ -1376,7 +1558,9 @@ 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`.
+	* operations will throw an error with code `ERR_DATABASE_READONLY`, except
+	* for `flush()`/`flushSync()`/`compact()`/`compactSync()`, which succeed as
+	* no-ops.
 	*/
 	readOnly;
 	/**
@@ -1403,8 +1587,8 @@ var Store = class {
 	*/
 	transactionLogMaxAgeThreshold;
 	/**
-	* The maximum size of a transaction log before it is rotated to the next
-	* sequence number.
+	* The target maximum size of a transaction log before rotation. Transactions
+	* are never split across files, so one transaction may exceed this target.
 	*/
 	transactionLogMaxSize;
 	/**
@@ -1452,9 +1636,11 @@ var Store = class {
 		this.encoder = options?.encoder ?? null;
 		this.encoding = options?.encoding ?? null;
 		this.freezeData = options?.freezeData ?? false;
+		this.infoLogLevel = options?.infoLogLevel;
 		this.keyBuffer = KEY_BUFFER;
 		this.keyEncoding = keyEncoding;
 		this.maxKeySize = options?.maxKeySize ?? MAX_KEY_SIZE;
+		this.maxLogFileSize = options?.maxLogFileSize;
 		this.maxOpenFiles = options?.maxOpenFiles;
 		this.maxWriteBufferNumber = options?.maxWriteBufferNumber;
 		this.maxWriteBufferSizeToMaintain = options?.maxWriteBufferSizeToMaintain;
@@ -1611,6 +1797,24 @@ var Store = class {
 		}
 		return result;
 	}
+	/**
+	* Estimates the number of keys in a range from RocksDB statistics
+	* (memtable stats + approximate SST sizes with range-local entry density)
+	* without iterating. Estimates always reflect committed state, so there is
+	* no transactional variant.
+	*/
+	estimateCount(options) {
+		let startBuffer;
+		let endBuffer;
+		const reverse = options?.reverse ?? false;
+		const start = reverse ? options?.end : options?.start;
+		const end = reverse ? options?.start : options?.end;
+		const exclusiveStart = options?.exclusiveStart ?? reverse;
+		const inclusiveEnd = options?.inclusiveEnd ?? reverse;
+		if (start !== void 0) startBuffer = copyEncodedKey(this.encodeKey(start), exclusiveStart);
+		if (end !== void 0) endBuffer = copyEncodedKey(this.encodeKey(end), inclusiveEnd);
+		return this.db.estimateCount(startBuffer, endBuffer);
+	}
 	getCount(context, options) {
 		options = { ...options };
 		if (options?.start !== void 0) {
@@ -1762,6 +1966,8 @@ var Store = class {
 			dbWriteBufferSize: this.dbWriteBufferSize,
 			disableWAL: this.disableWAL,
 			enableStats: this.enableStats,
+			infoLogLevel: this.infoLogLevel,
+			maxLogFileSize: this.maxLogFileSize,
 			maxOpenFiles: this.maxOpenFiles,
 			maxWriteBufferNumber: this.maxWriteBufferNumber,
 			maxWriteBufferSizeToMaintain: this.maxWriteBufferSizeToMaintain,
@@ -1822,7 +2028,7 @@ var Store = class {
 	useLog(context, name) {
 		if (typeof name !== "string" && typeof name !== "number") throw new TypeError("Log name must be a string or number");
 		if (typeof name === "string" && /[\t\n\r\\/]/.test(name)) throw new Error(`Invalid transaction log name "${name}"`);
-		return context.useLog(String(name));
+		return context.useLog(String(name), this.db);
 	}
 	/**
 	* Checks the process-global verification table for a fresh version match
@@ -1856,6 +2062,18 @@ var Store = class {
 	}
 };
 /**
+* Copies an encoded key out of the shared key buffer (which the next
+* `encodeKey` call would clobber), optionally appending a zero byte to
+* produce the key's bytewise successor.
+*/
+function copyEncodedKey(encoded, appendSuccessorByte) {
+	const length = encoded.end - encoded.start;
+	const copy = Buffer.allocUnsafe(length + (appendSuccessorByte ? 1 : 0));
+	copy.set(encoded.subarray(encoded.start, encoded.end));
+	if (appendSuccessorByte) copy[length] = 0;
+	return copy;
+}
+/**
 * Ensure that they key has been copied into our shared buffer, and return the ending position
 * @param keyBuffer
 */
@@ -2052,6 +2270,16 @@ var Transaction = class extends DBI {
 
 //#endregion
 //#region src/database.ts
+const BACKGROUND_ERROR_SEVERITY_NAMES = [
+	"none",
+	"soft",
+	"hard",
+	"fatal",
+	"unrecoverable"
+];
+function backgroundErrorSeverityName(severity) {
+	return BACKGROUND_ERROR_SEVERITY_NAMES[severity] ?? "unknown";
+}
 /**
 * The main class for interacting with a RocksDB database.
 *
@@ -2123,6 +2351,9 @@ var RocksDatabase = class RocksDatabase extends DBI {
 	* Compacts the entire key range of the database asynchronously.
 	* This triggers manual compaction which removes tombstones and reclaims space.
 	*
+	* On a read-only database this is a no-op: arguments are still validated, but
+	* the returned promise resolves without compacting rather than rejecting.
+	*
 	* @example
 	* ```typescript
 	* const db = RocksDatabase.open('/path/to/database');
@@ -2174,6 +2405,9 @@ var RocksDatabase = class RocksDatabase extends DBI {
 	* Compacts the entire key range of the database synchronously.
 	* This triggers manual compaction which removes tombstones and reclaims space.
 	*
+	* On a read-only database this validates its arguments and then returns
+	* without compacting, rather than throwing.
+	*
 	* @example
 	* ```typescript
 	* const db = RocksDatabase.open('/path/to/database');
@@ -2206,6 +2440,24 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		return this.store.db.getCompression();
 	}
 	/**
+	* 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
+	* each retained `LOG` / `LOG.old.*` file's size (defaults to 16MB, so with
+	* RocksDB's `keep_log_file_num = 5` the total footprint is bounded at
+	* roughly 80MB); `infoLogLevel` is the logging verbosity. The database must
+	* be open.
+	*
+	* @example
+	* ```typescript
+	* const db = RocksDatabase.open('/path/to/db', { maxLogFileSize: 4 * 1024 * 1024 });
+	* db.logOptions; // { maxLogFileSize: 4194304, infoLogLevel: 1 }
+	* ```
+	*/
+	get logOptions() {
+		return this.store.db.getLogOptions();
+	}
+	/**
 	* Set global database settings.
 	*
 	* @param options - The options for the database.
@@ -2289,18 +2541,107 @@ var RocksDatabase = class RocksDatabase extends DBI {
 	/**
 	* Flushes the underlying database by performing a commit or clearing any buffered operations.
 	*
+	* On a read-only database this is a no-op: the options bag is still validated, but the
+	* returned promise resolves without flushing rather than rejecting.
+	*
+	* @param options - Flush options; see {@link FlushOptions.allowWriteStall} before relying on
+	* this resolving promptly under write pressure.
 	* @return {void} Does not return a value.
 	*/
-	flush() {
-		return new Promise((resolve, reject) => this.store.db.flush(resolve, reject));
+	flush(options) {
+		return new Promise((resolve, reject) => this.store.db.flush(resolve, reject, options));
 	}
 	/**
 	* Synchronously flushes the underlying database by performing a commit or clearing any buffered operations.
 	*
+	* The default `allowWriteStall: false` wait is taken on the JS thread here, so it freezes the
+	* event loop rather than parking a libuv worker — a larger blast radius than {@link flush}, not
+	* a smaller one.
+	*
+	* On a read-only database this validates its options and then returns without flushing, rather
+	* than throwing.
+	*
+	* @param options - Flush options; see {@link FlushOptions.allowWriteStall}.
 	* @return {void} Does not return a value.
 	*/
-	flushSync() {
-		return this.store.db.flushSync();
+	flushSync(options) {
+		return this.store.db.flushSync(options);
+	}
+	/**
+	* Returns the most recent {@link BackgroundError} observed on this database, or
+	* `null` when none has occurred. The `'error'` event is the push counterpart;
+	* this is the pull equivalent for on-demand checks (e.g. a health probe) and
+	* for catching an error that fired after open but before a listener was
+	* attached. (A background error that occurs *during* the initial open is a
+	* narrow startup window not yet captured, addressed separately.)
+	*
+	* Purely historical — it is not cleared by a successful {@link RocksDatabase.resume}.
+	* When the returned error's `writesDisabled` is `true`, writes are stopped
+	* until recovery.
+	*
+	* @example
+	* ```typescript
+	* const err = db.getLastError();
+	* if (err?.writesDisabled) {
+	*   // ...free disk space...
+	*   db.resume();
+	* }
+	* ```
+	*/
+	getLastError() {
+		return this.store.db.getLastError();
+	}
+	/**
+	* Sets or clears the last background error, mirroring the Win32
+	* `SetLastError`/`GetLastError` pair. Pass `null` (or no argument) to **reset**
+	* it — {@link RocksDatabase.getLastError} then returns `null` and no event
+	* fires; this is the intended way to clear the error after handling or
+	* recovering it (e.g. after {@link RocksDatabase.resume}). Pass an object to
+	* set it: it is stored and the `'error'` event fires with the reconstructed
+	* {@link BackgroundError}. `type` defaults to `'background'`.
+	*
+	* @example
+	* ```typescript
+	* db.resume();
+	* db.setLastError(null); // recovered — clear the historical error
+	* ```
+	*/
+	setLastError(error) {
+		if (error == null) return this.store.db.setLastError(null);
+		const severity = error.severity ?? 0;
+		return this.store.db.setLastError({
+			...error,
+			type: error.type ?? "background",
+			severity,
+			severityName: error.severityName ?? backgroundErrorSeverityName(severity),
+			writesDisabled: error.writesDisabled ?? severity >= 2
+		});
+	}
+	/**
+	* Attempts to recover the database from a background error by calling
+	* RocksDB's `DB::Resume()`. When a write fails at the filesystem level (e.g. a
+	* full disk), RocksDB stops accepting writes and this database emits an
+	* {@link BackgroundError} via the `'error'` event. Call `resume()` after the
+	* underlying condition has cleared — e.g. once disk space has been freed. On
+	* success writes are accepted again; on failure (the condition has not
+	* actually cleared) it throws and the database stays read-only. A no-op on a
+	* healthy database.
+	*
+	* Runs synchronously and may briefly block, since recovery can re-flush
+	* memtables.
+	*
+	* @example
+	* ```typescript
+	* db.on('error', (err) => {
+	*   if (err.writesDisabled) {
+	*     // ...free disk space...
+	*     db.resume();
+	*   }
+	* });
+	* ```
+	*/
+	resume() {
+		return this.store.db.resume();
 	}
 	/**
 	* Gets a RocksDB database property as an integer.
@@ -2335,7 +2676,9 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		return this.store.db.getDBProperty(propertyName);
 	}
 	/**
-	* Retrieves the estimated number of keys in the database.
+	* Retrieves the estimated number of keys in the database. This is an alias
+	* for `db.estimateCount().count`; use `estimateCount()` for range support
+	* and a confidence indicator.
 	*
 	* @example
 	* ```typescript
@@ -2348,6 +2691,58 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		return this.getDBIntProperty("rocksdb.estimate-num-keys") ?? 0;
 	}
 	/**
+	* Estimates the number of keys in the database, or within a key range,
+	* returning `{ count, confidence }`. Unlike `getKeysCount()`, this never
+	* iterates: the estimate is derived from RocksDB statistics (memtable
+	* stats plus approximate SST sizes converted through the entry density of
+	* the SSTs overlapping the range), so its cost scales with the number of
+	* SSTs overlapping the range rather than the number of keys — though
+	* reading table properties for cold files can do I/O through the table
+	* cache, and a start-only range does the work of its complement below
+	* `start`. Accuracy improves with range size. Resolution is bounded by SST
+	* data-block granularity, so tiny ranges may over-report or report zero for
+	* present keys; low `confidence` is the signal. Recently deleted or
+	* overwritten entries may be counted until compaction. An inverted range
+	* (`start` >= `end`) returns `{ count: 0, confidence: 1 }`.
+	*
+	* `confidence` is a heuristic 0–1 trust indicator (1 only when exact) —
+	* see `CountEstimate`. Estimates always reflect committed state; writes
+	* pending in a transaction are not included.
+	*
+	* @example
+	* ```typescript
+	* const db = RocksDatabase.open('/path/to/database');
+	* const { count, confidence } = db.estimateCount({ start: 'a', end: 'z' });
+	* ```
+	*/
+	estimateCount(options) {
+		return this.store.estimateCount(options);
+	}
+	/**
+	* Creates a `CountEstimator` for progressively refining a range count
+	* estimate while iterating the range: report progress with
+	* `advance(lastKey, count)` (e.g. once per page of results) and
+	* `estimate()` returns the exact traversed count plus a calibrated
+	* estimate of the remainder, converging toward the exact total. Call
+	* `finish()` when traversal completes to make `estimate()` exact.
+	*
+	* @example
+	* ```typescript
+	* const estimator = db.createCountEstimator({ start: 'a', end: 'z' });
+	* let lastKey;
+	* let pageSize = 0;
+	* for (const { key } of db.getRange({ start: 'a', end: 'z', limit: 25 })) {
+	*   lastKey = key;
+	*   pageSize++;
+	* }
+	* estimator.advance(lastKey, pageSize);
+	* const { count, confidence } = estimator.estimate();
+	* ```
+	*/
+	createCountEstimator(options) {
+		return new CountEstimator(this.store, options);
+	}
+	/**
 	* Returns the current timestamp as a monotonically increasing timestamp in
 	* milliseconds represented as a decimal number.
 	*
@@ -2853,6 +3248,98 @@ const FLOAT_TO_UINT32 = /* @__PURE__ */ new Float64Array(1);
 const UINT32_FROM_FLOAT = new Uint32Array(FLOAT_TO_UINT32.buffer);
 const { TRANSACTION_LOG_FILE_HEADER_SIZE, TRANSACTION_LOG_ENTRY_HEADER_SIZE } = constants;
 /**
+* Number of consecutive well-formed frames that, on their own, signal that real log data has
+* resumed after a framing break. Kept in step with `RESYNC_MIN_FRAMES` in
+* `src/binding/transaction_log/transaction_log_recovery.cpp`, which uses the same heuristic to
+* classify a break as mid-file corruption (valid entries follow) rather than a torn tail.
+*/
+const RESYNC_MIN_FRAMES = 8;
+/**
+* Thrown when an entry's framing is broken. `resyncPosition` is the offset where valid framing
+* resumes, when one was found: the frames after a mid-log break are intact and reachable, and
+* only the broken span between `position` and `resyncPosition` is unreadable. It is `undefined`
+* for a torn tail, where nothing follows the break.
+*
+* The iterator is left positioned at `resyncPosition` (or at end-of-log when there is none), so a
+* caller that chooses to recover the entries past the break calls `next()` again.
+*/
+var CorruptFrameError = class extends RangeError {
+	/** Sequence number of the log file the break is in. */
+	logId;
+	/** Offset of the broken frame. */
+	position;
+	/** Offset where valid framing resumes, or `undefined` when nothing valid follows. */
+	resyncPosition;
+	/** Bytes between the break and the resume point that cannot be read. */
+	unreadableBytes;
+	constructor(message, logId, position, resyncPosition) {
+		super(resyncPosition === void 0 ? message : `${message}; valid framing resumes at ${resyncPosition.toString(16)}, ${resyncPosition - position} byte(s) unreadable`);
+		this.name = "CorruptFrameError";
+		this.logId = logId;
+		this.position = position;
+		this.resyncPosition = resyncPosition;
+		this.unreadableBytes = resyncPosition === void 0 ? 0 : resyncPosition - position;
+	}
+};
+/**
+* Whether a complete, in-bounds frame begins at `pos`. The only sane bound on an entry's length is
+* the written extent: a single entry can legitimately exceed the rotation threshold (the first
+* entry written to a fresh file is always written in full). A zero timestamp is the
+* end-of-entries marker, not a frame.
+*/
+function frameFits(dataView, pos, dataEnd) {
+	if (pos + TRANSACTION_LOG_ENTRY_HEADER_SIZE > dataEnd) return false;
+	if (dataView.getFloat64(pos) === 0) return false;
+	const length = dataView.getUint32(pos + 8);
+	if (length === 0) return false;
+	return pos + TRANSACTION_LOG_ENTRY_HEADER_SIZE + length <= dataEnd;
+}
+/**
+* Finds the offset in `[from, dataEnd)` where valid log framing resumes: a run of at least
+* `RESYNC_MIN_FRAMES` well-formed frames, or a run that lands exactly on `dataEnd`. Returns
+* `undefined` when nothing resumes (a torn tail).
+*
+* `dataEnd` must be the **written extent**, not the mapped capacity. The log's memory map is
+* pre-extended well past the data, and every offset inside that zero padding reads as an
+* end-of-entries marker — so scanning against the map would both lose the exact-end signal (the
+* chain can never land on a capacity that data does not reach) and, if a zero were accepted as a
+* 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.
+*/
+function findResyncPosition(dataView, from, dataEnd) {
+	const lastStart = dataEnd - TRANSACTION_LOG_ENTRY_HEADER_SIZE;
+	for (let start = from; start <= lastStart; start++) {
+		let pos = start;
+		let frames = 0;
+		while (frames < RESYNC_MIN_FRAMES && frameFits(dataView, pos, dataEnd)) {
+			pos += TRANSACTION_LOG_ENTRY_HEADER_SIZE + dataView.getUint32(pos + 8);
+			if (++frames >= RESYNC_MIN_FRAMES || pos === dataEnd) return start;
+		}
+	}
+}
+/**
+* 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.
+*/
+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;
+	}
+	const resyncPosition = findResyncPosition(dataView, position + 1, dataEnd);
+	return {
+		error: new CorruptFrameError(message, logBuffer.logId, position, resyncPosition),
+		nextPosition: resyncPosition ?? Math.max(dataEnd || limit, size, position + 1)
+	};
+}
+/**
 * Returns an iterable for transaction entries within the specified range of timestamps
 * This iterable can be iterated over multiple times, and subsequent iterations will continue
 * from where the last iteration left off, allowing for iteration through the log file
@@ -2942,9 +3429,17 @@ Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, e
 					value: void 0
 				};
 				const limit = readUncommitted ? logBuffer.length : Math.min(size, logBuffer.length);
-				if (position + TRANSACTION_LOG_ENTRY_HEADER_SIZE > limit) throw new RangeError(`Corrupt transaction log: truncated entry header at position ${position.toString(16)} of log ${logBuffer.logId} (available=${limit - position})`);
+				if (position + TRANSACTION_LOG_ENTRY_HEADER_SIZE > limit) {
+					const broken = corruptFrame(`Corrupt transaction log: truncated entry header at position ${position.toString(16)} of log ${logBuffer.logId} (available=${limit - position})`, transactionLog, dataView, logBuffer, position, limit, size, !!readUncommitted);
+					position = broken.nextPosition;
+					throw broken.error;
+				}
 				const length = dataView.getUint32(position + 8);
-				if (position + TRANSACTION_LOG_ENTRY_HEADER_SIZE + length > limit) throw new RangeError(`Corrupt transaction log entry at position ${position.toString(16)} of log ${logBuffer.logId}: declared length ${length} overruns the log (limit=${limit})`);
+				if (length === 0 || position + TRANSACTION_LOG_ENTRY_HEADER_SIZE + length > limit) {
+					const broken = corruptFrame(length === 0 ? `Corrupt transaction log entry at position ${position.toString(16)} of log ${logBuffer.logId}: zero-length entry` : `Corrupt transaction log entry at position ${position.toString(16)} of log ${logBuffer.logId}: declared length ${length} overruns the log (limit=${limit})`, transactionLog, dataView, logBuffer, position, limit, size, !!readUncommitted);
+					position = broken.nextPosition;
+					throw broken.error;
+				}
 				position += TRANSACTION_LOG_ENTRY_HEADER_SIZE;
 				let matchesRange;
 				if (foundExactStart) matchesRange = (!exclusiveStart || timestamp !== start) && timestamp < end;
@@ -3035,9 +3530,9 @@ function loadLastPosition(transactionLog, readUncommitted) {
 //#region src/index.ts
 const versions = {
 	rocksdb: version,
-	"rocksdb-js": "2.7.0"
+	"rocksdb-js": "2.8.0"
 };
 
 //#endregion
-export { DBI, DBIterator, RocksDatabase, Store, Transaction, TransactionLog, backups, constants, coolTransactionLogs, currentThreadId, fileLockRelease, parseTransactionLog, registryStatus, shutdown, stats, supportedCompression, tryFileLock, validateTransactionLogStore, versions };
+export { BackgroundError, CorruptFrameError, CountEstimator, DBI, DBIterator, RocksDatabase, Store, Transaction, TransactionLog, backups, constants, coolTransactionLogs, currentThreadId, fileLockRelease, parseTransactionLog, registryStatus, shutdown, stats, supportedCompression, tryFileLock, validateTransactionLogStore, versions };
 //# sourceMappingURL=index.mjs.map