@harperfast/rocksdb-js 1.4.1 → 1.5.0

package/README.md

@@ -668,12 +668,25 @@ complete, use the `'aftercommit'` event.
 ## Event API
 
 `rocksdb-js` provides a EventEmitter-like API that lets you asynchronously notify events to one or
-more synchronous listener callbacks. Events are scoped by database path.
+more synchronous listener callbacks. There are two types of events:
+
+- Per-database events: scoped by database path.
+- Process-global events: not scoped by database path.
 
 Unlike `EventEmitter`, events are emitted asynchronously, but in the same order that the listeners
 were added.
 
 ```typescript
+// Process-global events
+RocksDatabase.on('log.warn', console.warn);
+
+RocksDatabase.on('foo', (...args) => {
+	console.log(args);
+});
+RocksDatabase.notify('foo', 'bar');
+RocksDatabase.off('foo', callback);
+
+// Per-database events
 const callback = (name) => console.log(`Hi from ${name}`);
 db.addListener('foo', callback);
 db.notify('foo');
@@ -1103,6 +1116,18 @@ for (const entry of rangeIter) {
 Returns the size of the given transaction log sequence file in bytes. Omit the sequence number to
 get the total size of all the transaction log sequence files for this log.
 
+### Transaction Log Initialization
+
+When a database is opened, `rocksdb-js` will automatically discover the transaction log files. If
+a corrupt transaction log file is detected, the `log.warn` event is emitted on the global
+`RocksDatabase` instance. This should be wired up prior to opening the database.
+
+```typescript
+RocksDatabase.on('log.warn', console.warn);
+
+const db = RocksDatabase.open('path/to/db');
+```
+
 ### Transaction Log Parser
 
 #### `parseTransactionLog(file)`

package/dist/index.cjs

@@ -80,6 +80,10 @@ function locateBinding() {
 }
 const binding = req(locateBinding());
 const config = binding.config;
+const addGlobalListener = binding.addListener;
+const removeGlobalListener = binding.removeListener;
+const globalListenerCount = binding.listenerCount;
+const globalNotify = binding.notify;
 const constants = binding.constants;
 const NativeDatabase = binding.Database;
 const NativeIterator = binding.Iterator;
@@ -1386,6 +1390,60 @@ var RocksDatabase = class RocksDatabase extends DBI {
 	static config(options) {
 		config(options);
 	}
+	/**
+	* Registers a process-wide event listener. Internal events emitted by the
+	* 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.
+	*
+	* @example
+	* ```typescript
+	* RocksDatabase.on('transactionLog:warning', (warning) => {
+	*   console.warn(warning);
+	* });
+	* ```
+	*/
+	static on(event, callback) {
+		addGlobalListener(event, callback);
+	}
+	/**
+	* Alias for {@link RocksDatabase.on}, mirroring the Node `EventEmitter` API.
+	*/
+	static addListener(event, callback) {
+		addGlobalListener(event, callback);
+	}
+	/**
+	* Removes a previously-registered process-wide event listener. The
+	* callback identity must match the one passed to {@link RocksDatabase.on}.
+	*
+	* @returns `true` if a matching listener was removed.
+	*/
+	static off(event, callback) {
+		return removeGlobalListener(event, callback);
+	}
+	/**
+	* Alias for {@link RocksDatabase.off}, mirroring the Node `EventEmitter` API.
+	*/
+	static removeListener(event, callback) {
+		return removeGlobalListener(event, callback);
+	}
+	/**
+	* Returns the number of process-wide listeners registered for the given event.
+	*/
+	static listenerCount(event) {
+		return globalListenerCount(event);
+	}
+	/**
+	* Emits a process-wide event. Mostly intended for tests and as a peer to
+	* {@link RocksDatabase.on} — native code should call `emitGlobalEvent` in
+	* `napi/global_events.h` directly rather than round-tripping through JS.
+	*
+	* @returns `true` if there was at least one listener.
+	*/
+	static notify(event, ...args) {
+		return globalNotify(event, args);
+	}
 	destroy() {
 		this.store.db.destroy();
 	}
@@ -1859,7 +1917,7 @@ var RocksDatabase = class RocksDatabase extends DBI {
 
 //#endregion
 //#region src/parse-transaction-log.ts
-const { TRANSACTION_LOG_TOKEN } = constants;
+const { TRANSACTION_LOG_TOKEN, TRANSACTION_LOG_ENTRY_HEADER_SIZE: TRANSACTION_LOG_ENTRY_HEADER_SIZE$1 } = constants;
 const MIN_VALID_TIMESTAMP = Date.UTC(2026, 0, 27);
 const VALID_FLAGS_MASK = 1;
 /**
@@ -1883,7 +1941,11 @@ function parseTransactionLog(path, options = {}) {
 		const buffer = Buffer.allocUnsafe(numBytes);
 		const bytesRead = (0, node_fs.readSync)(fileHandle, buffer, 0, numBytes, fileOffset);
 		fileOffset += bytesRead;
-		if (bytesRead !== numBytes) throw new Error(`Expected to read ${numBytes} bytes but only read ${bytesRead}, file offset: ${fileOffset}, file size: ${size}, file path: ${path}, buffer: ${buffer.toString("hex")}`);
+		if (bytesRead !== numBytes) {
+			const previewBytes = Math.min(bytesRead, 64);
+			const preview = buffer.subarray(0, previewBytes).toString("hex");
+			throw new Error(`Expected to read ${numBytes} bytes but only read ${bytesRead}, file offset: ${fileOffset.toString(16)}, file size: ${size}, file path: ${path}, buffer (first ${previewBytes} bytes): ${preview}`);
+		}
 		return buffer;
 	};
 	try {
@@ -1903,6 +1965,11 @@ function parseTransactionLog(path, options = {}) {
 			}
 			const length = read(4).readUInt32BE(0);
 			const flags = read(1).readUInt8(0);
+			const remaining = size - fileOffset;
+			if (length > remaining) {
+				const entryOffset = fileOffset - TRANSACTION_LOG_ENTRY_HEADER_SIZE$1;
+				throw new Error(`Corrupt entry at offset ${entryOffset.toString(16)}: declared length ${length} exceeds ${remaining} bytes remaining (file size: ${size})`);
+			}
 			const data = read(length);
 			const entryAnomalies = [];
 			if (!Number.isFinite(timestamp) || timestamp < MIN_VALID_TIMESTAMP) entryAnomalies.push(`timestamp ${timestamp} predates 2026-01-27 (possible corruption)`);
@@ -2022,14 +2089,17 @@ Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, e
 				try {
 					timestamp = dataView.getFloat64(position);
 				} catch (error) {
-					error.message += ` at position ${position} of log ${logBuffer.logId} (size=${size}, log buffer length=${logBuffer.length})`;
+					error.message += ` at position ${position.toString(16)} of log ${logBuffer.logId} (size=${size}, log buffer length=${logBuffer.length})`;
 					throw error;
 				}
 				if (!timestamp) return {
 					done: true,
 					value: void 0
 				};
+				const limit = readUncommitted ? logBuffer.length : size;
+				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})`);
 				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})`);
 				position += TRANSACTION_LOG_ENTRY_HEADER_SIZE;
 				let matchesRange;
 				if (foundExactStart) matchesRange = (!exclusiveStart || timestamp !== start) && timestamp < end;
@@ -2052,7 +2122,12 @@ Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, e
 					const { logId: latestLogId, size: latestSize } = loadLastPosition(transactionLog, !!readUncommitted);
 					size = latestSize;
 					if (latestLogId > logBuffer.logId) {
-						logBuffer = getLogMemoryMap(transactionLog, logBuffer.logId + 1);
+						const nextLogBuffer = getLogMemoryMap(transactionLog, logBuffer.logId + 1);
+						if (!nextLogBuffer) return {
+							done: true,
+							value: void 0
+						};
+						logBuffer = nextLogBuffer;
 						dataView = logBuffer.dataView;
 						size = logBuffer.size;
 						if (size == void 0) {
@@ -2115,7 +2190,7 @@ function loadLastPosition(transactionLog, readUncommitted) {
 //#region src/index.ts
 const versions = {
 	rocksdb: version,
-	"rocksdb-js": "1.4.1"
+	"rocksdb-js": "1.5.0"
 };
 
 //#endregion