@harperfast/rocksdb-js 2.6.1 → 2.7.1

package/README.md

@@ -57,6 +57,18 @@ Creates a new database instance.
   - `enableStats: boolean` When `true` and the database is open, RocksDB will captures stats that
     are retrieved by calling `db.getStats()`. Enabling statistics imposes 5-10% in overhead.
     Defaults to `false`.
+  - `infoLogLevel: number` The verbosity of RocksDB's informational logging (`LOG` /
+    `LOG.old.*`): `0` (debug), `1` (info), `2` (warn), `3` (error), `4` (fatal), or `5`
+    (header-only). Omit to leave RocksDB's own default (`INFO_LEVEL` in a release build of the
+    linked RocksDB library). See [`db.logOptions`](#dblogoptions-maxlogfilesize-number-infologlevel-number).
+  - `maxLogFileSize: number` The per-file size cap, in bytes, for informational log files (`LOG` /
+    `LOG.old.*`). RocksDB retains up to 5 of these files, so the total informational-log footprint
+    is bounded at roughly `5 * maxLogFileSize`. Defaults to 16 MB (an 80 MB bound), which stops
+    purely informational logging from growing without bound. A value of `0` is RocksDB's special
+    "single unbounded log file" mode — it **disables size-based rotation entirely**, so the log
+    can grow without limit; only set `0` if you deliberately want that (it forgoes the bounded
+    footprint this option otherwise provides). See
+    [`db.logOptions`](#dblogoptions-maxlogfilesize-number-infologlevel-number).
   - `maxOpenFiles: number` 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 to `[1024, 262144]`); `-1` holds every table
@@ -128,10 +140,24 @@ when a non-default compression level is set. The database must be open. See
 [Compression](#compression).
 
 ```typescript
-const db = RocksDatabase.open('path/to/db', { compression: { algorithm: 'zstd', level: 3 } });
+const db = RocksDatabase.open('path/to/db', {
+	compression: { algorithm: 'zstd', level: 3 },
+});
 console.log(db.compression); // { algorithm: 'zstd', level: 3 }
 ```
 
+### `db.logOptions: { maxLogFileSize: number, infoLogLevel: number }`
+
+Returns the informational-log settings currently in effect for this database, read live from
+RocksDB. These are database-wide settings (not per-column-family). `maxLogFileSize` is the
+per-file size cap for informational log files (`LOG` / `LOG.old.*`); `infoLogLevel` is the logging
+verbosity. The database must be open.
+
+```typescript
+const db = RocksDatabase.open('path/to/db', { maxLogFileSize: 4 * 1024 * 1024 });
+console.log(db.logOptions); // { maxLogFileSize: 4194304, infoLogLevel: 1 }
+```
+
 ### `db.config(options)`
 
 Sets global database settings.
@@ -260,11 +286,20 @@ per database path can be performed at a time.
 - `options: object`
   - `start?: Key` The start key of the range to compact.
   - `end?: Key` The end key of the range to compact.
+  - `bottommost?: boolean` Also compact the bottommost level, rewriting every file in range.
+    RocksDB skips that level by default when no compaction filter is installed, and it holds most
+    of the data — so an ordinary compaction leaves it untouched. Because a changed
+    [`compression`](#compression) algorithm governs only newly written files, this is the way to
+    re-encode data that already exists. It rewrites the whole range regardless of whether RocksDB
+    considers it worthwhile, so it costs as much as the data is large. Defaults to `false`.
 
 ```typescript
 await db.compact();
 
 await db.compact({ start: 'a', end: 'z' });
+
+// Re-encode everything already on disk under the column family's current codec
+await db.compact({ bottommost: true });
 ```
 
 ### `db.compactSync(options?): void`
@@ -275,6 +310,8 @@ Synchronous version of `compact()`.
 db.compactSync();
 
 db.compactSync({ start: 'a', end: 'z' });
+
+db.compactSync({ bottommost: true });
 ```
 
 ### `db.destroy(): void`
@@ -660,6 +697,9 @@ an `ERR_TRANSACTION_ABANDONED` error. Coordinated retry requires the column fami
 The transaction callback is passed in a `Transaction` instance which contains all of the same data
 operations methods as the `RocksDatabase` instance plus:
 
+- `txn.abandonWrites(): void` Releases the staged writes' verification-table write intents without
+  closing the transaction, and bars any further writes or commit. Reads (including read-your-own-writes)
+  keep working until the transaction is aborted.
 - `txn.abort()` Rolls back and closes the transaction. This method is automatically called after the
   transaction callback returns, so you shouldn't need to call it, but it's ok to do so. Once called,
   no further transaction operations are permitted. Calling this method multiple times has no effect.
@@ -673,6 +713,22 @@ operations methods as the `RocksDatabase` instance plus:
   a timestamp, it will set the timestamp to the current time. The value must be in seconds with
   higher precision in the decimal.
 
+#### `txn.abandonWrites(): void`
+
+Releases the staged writes' verification-table (VT) write intents without closing the transaction,
+and bars any further writes or commit (`commit()`/`commitSync()`/`put()`/`remove()`, including
+database-context writes via `{ transaction: txn }`, all reject once called). Reads — including
+read-your-own-writes — keep working until the transaction is aborted. Idempotent, and a no-op after
+`abort()`.
+
+Scope is VT intents only: RocksDB's own transaction locks (pessimistic mode) are still held until
+the transaction is aborted.
+
+This is for a transaction kept open only for its outstanding read iterators after its writes were
+already committed elsewhere (e.g. replayed onto another transaction) — it lets the intents release
+early so other writers' coordinated-retry commits stop parking on them, instead of waiting for the
+handle's eventual `abort()`.
+
 #### `txn.abort(): void`
 
 Rolls back and closes the transaction. This method is automatically called after the transaction
@@ -960,7 +1016,9 @@ Set the algorithm per column family with the `compression` option when opening a
 const db = RocksDatabase.open('/path/to/db', { compression: 'zstd' });
 
 // Or an object with an explicit level
-const db2 = RocksDatabase.open('/path/to/db2', { compression: { algorithm: 'zstd', level: 3 } });
+const db2 = RocksDatabase.open('/path/to/db2', {
+	compression: { algorithm: 'zstd', level: 3 },
+});
 
 // Disable compression entirely
 const db3 = RocksDatabase.open('/path/to/db3', { compression: 'none' });
@@ -977,6 +1035,37 @@ was compiled against, so it varies by build. Always check
 [`supportedCompression`](#supportedcompression) at runtime — opening with an unavailable algorithm
 throws. `'none'` is always available.
 
+**Changing the codec of data already written.** Setting `compression` affects files written from
+that point on. Existing SST and blob files keep the codec they were written with until something
+rewrites them. An ordinary `compact()` can re-encode non-bottommost levels, but RocksDB leaves the
+bottommost level alone unless a compaction filter is installed — and that is where most of the data
+sits, so a plain compaction will not rewrite all existing data. Use
+[`compact({ bottommost: true })`](#dbcompactoptions-promisevoid) to force the rewrite, once per
+column family you want migrated. Note also that omitting `compression` on a column family that
+already exists **inherits** its current codec rather than applying the default — the default
+applies only when the family is created.
+
+**Adopting a codec across a whole database.** Compression is chosen per column family, and RocksDB
+opens every family of a database in one call — so by default the families you did not name keep
+their persisted algorithm. If your first open targets some other family (a catalog, say), the rest
+are already open at their old algorithm before you can ask for a new one, and a family's compression
+cannot be changed while it is open. Pass `compressionForAllColumnFamilies: true` to apply the
+requested algorithm to all of them instead:
+
+```typescript
+// Every column family in this database adopts lz4, not just 'catalog'
+const db = RocksDatabase.open('/path/to/db', {
+	name: 'catalog',
+	compression: 'lz4',
+	compressionForAllColumnFamilies: true,
+});
+```
+
+It requires an explicit `compression`, and only takes effect on the open that creates the database
+handle — later opens of the same path reuse that handle. As always the algorithm governs newly
+written files; use [`compact({ bottommost: true })`](#dbcompactoptions-promisevoid) to rewrite what
+is already there.
+
 **Scope and mutability.** Compression is genuinely **per-column-family**. Each `RocksDatabase`
 targets one column family (`name`), and its `compression` applies only to that CF — opening one CF
 never changes another's algorithm, regardless of open order. A column family keeps its own
@@ -1661,7 +1750,9 @@ live database directory would write backup files on top of RocksDB's own files.
 before anything is written.
 
 ```typescript
-const id = await db.backup('/path/to/backups', { metadata: 'nightly-2026-06-04' });
+const id = await db.backup('/path/to/backups', {
+	metadata: 'nightly-2026-06-04',
+});
 ```
 
 `BackupOptions`:
@@ -1711,7 +1802,9 @@ await db.backup(Writable.toWeb(createWriteStream('/path/to/backup.tar')));
 // Restore: `tar -xf backup.tar -C /restored`, then open '/restored'.
 
 // Or gzip it (`tar -xzf backup.tar.gz` to restore):
-await db.backup(Writable.toWeb(createWriteStream('/path/to/backup.tar.gz')), { gzip: true });
+await db.backup(Writable.toWeb(createWriteStream('/path/to/backup.tar.gz')), {
+	gzip: true,
+});
 ```
 
 `BackupStreamOptions`:

package/dist/index.cjs

@@ -1305,6 +1305,11 @@ var Store = class {
 	*/
 	compression;
 	/**
+	* Whether `compression` applies to every column family in the database rather than just this
+	* store's. See `RocksDatabaseOptions.compressionForAllColumnFamilies`.
+	*/
+	compressionForAllColumnFamilies = false;
+	/**
 	* Whether to disable the write ahead log.
 	*/
 	disableWAL;
@@ -1331,6 +1336,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;
@@ -1343,6 +1353,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
@@ -1361,13 +1381,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;
 	/**
@@ -1463,6 +1496,7 @@ var Store = class {
 		const { keyEncoding, readKey, writeKey } = initKeyEncoder(options?.keyEncoding, options?.keyEncoder);
 		this.db = new NativeDatabase();
 		this.compression = options?.compression;
+		this.compressionForAllColumnFamilies = options?.compressionForAllColumnFamilies === true;
 		this.dbWriteBufferSize = options?.dbWriteBufferSize;
 		this.decoder = options?.decoder ?? null;
 		this.disableWAL = options?.disableWAL ?? false;
@@ -1471,9 +1505,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;
@@ -1532,7 +1568,7 @@ var Store = class {
 			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));
+		return new Promise((resolve, reject) => this.db.compact(resolve, reject, startBuffer, endBuffer, options?.bottommost === true));
 	}
 	async backup(target, options) {
 		if (typeof target !== "string" && typeof target?.getWriter === "function") return backupToStream(this.db, target, options);
@@ -1560,7 +1596,7 @@ var Store = class {
 			const end = this.encodeKey(options.end);
 			endBuffer = Buffer.from(end.subarray(end.start, end.end));
 		}
-		this.db.compactSync(startBuffer, endBuffer);
+		this.db.compactSync(startBuffer, endBuffer, options?.bottommost === true);
 	}
 	/**
 	* Decodes a key from the database.
@@ -1777,9 +1813,12 @@ var Store = class {
 		this.db.open(this.path, {
 			compression,
 			compressionLevel,
+			compressionForAllColumnFamilies: this.compressionForAllColumnFamilies,
 			dbWriteBufferSize: this.dbWriteBufferSize,
 			disableWAL: this.disableWAL,
 			enableStats: this.enableStats,
+			infoLogLevel: this.infoLogLevel,
+			maxLogFileSize: this.maxLogFileSize,
 			maxOpenFiles: this.maxOpenFiles,
 			maxWriteBufferNumber: this.maxWriteBufferNumber,
 			maxWriteBufferSizeToMaintain: this.maxWriteBufferSizeToMaintain,
@@ -1959,7 +1998,7 @@ var Transaction = class extends DBI {
 		if (store.readOnly) {
 			super(store);
 			this.#txn = { id: 0 };
-			this.abort = this.commitSync = this.setTimestamp = () => {};
+			this.abandonWrites = this.abort = this.commitSync = this.setTimestamp = () => {};
 			this.commit = async () => {};
 			this.getTimestamp = () => 0;
 		} else {
@@ -1969,6 +2008,17 @@ var Transaction = class extends DBI {
 		}
 	}
 	/**
+	* Release the staged writes' verification-table write intents without
+	* closing the transaction, barring any later commit or write. For a
+	* transaction kept open only for its outstanding read iterators after the
+	* writes were replayed onto another transaction: otherwise other writers'
+	* coordinated-retry commits park on those intents until it is aborted.
+	* Reads keep working, including read-your-own-writes.
+	*/
+	abandonWrites() {
+		this.#txn.abandonWrites();
+	}
+	/**
 	* Abort the transaction.
 	*/
 	abort() {
@@ -2213,6 +2263,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.
@@ -3042,7 +3110,7 @@ function loadLastPosition(transactionLog, readUncommitted) {
 //#region src/index.ts
 const versions = {
 	rocksdb: version,
-	"rocksdb-js": "2.6.1"
+	"rocksdb-js": "2.7.1"
 };
 
 //#endregion