@harperfast/rocksdb-js 1.1.1 → 1.3.0

package/README.md

@@ -105,10 +105,27 @@ Sets global database settings.
   - `blockCacheSize: number` The amount of memory in bytes to use to cache uncompressed blocks.
     Defaults to 32MB. Set to `0` (zero) disables block cache for future opened databases. Existing
     block cache for any opened databases is resized immediately. Negative values throw an error.
+  - `compactOnClose: boolean` When `true`, compacts the database on close. Defaults to `false`.
+  - `writeBufferManagerAllowStall: boolean` When `true`, writes are stalled once the manager's
+    `buffer_size` is exceeded, providing a hard cap on memtable memory. When `false`, memtables are
+    allowed to grow past the limit and flushes are simply scheduled more aggressively. Off by
+    default to favor write throughput over hard memory bounding. Defaults to `false`.
+  - `writeBufferManagerCostToCache: boolean` When `true`, memtable memory is "charged" against the
+    shared block cache so the block cache and write buffers draw from a single pool. During write
+    bursts the cache shrinks to make room for memtables; once memtables flush, the cache can grow
+    back into the reclaimed space. Defaults to `false`.
+  - `writeBufferManagerSize: number` Total memtable memory limit (bytes) shared across every
+    database opened in this process. When set, RocksDB uses a single `WriteBufferManager` so write
+    buffers are bounded process-wide rather than per database. A value of `0` disables the manager.
+    Defaults to `0`.
 
 ```typescript
 RocksDatabase.config({
 	blockCacheSize: 100 * 1024 * 1024, // 100MB
+	compactOnClose: true,
+	writeBufferManagerAllowStall: false,
+	writeBufferManagerCostToCache: false,
+	writeBufferManagerSize: 64 * 1024 * 1024, // 64MB
 });
 ```
 
@@ -193,6 +210,33 @@ const entriesRemoved = db.clearSync();
 console.log(entriesRemoved); // 10
 ```
 
+### `db.compact(options?): Promise<void>`
+
+Compacts a range of keys in the database. In RocksDB, deleted keys are not immediately removed from
+the database. Instead, they are marked as deleted and a tombstone is written. This function
+triggers a manual compaction which removes the tombstones and reclaims space. Only one compaction
+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.
+
+```typescript
+await db.compact();
+
+await db.compact({ start: 'a', end: 'z' });
+```
+
+### `db.compactSync(options?): void`
+
+Synchronous version of `compact()`.
+
+```typescript
+db.compactSync();
+
+db.compactSync({ start: 'a', end: 'z' });
+```
+
 ### `db.destroy(): void`
 
 Completely removes a database based on the `db` instance's path including all data, column families,
@@ -224,6 +268,23 @@ db.dropSync();
 db.close();
 ```
 
+### `db.flush(): Promise<void>`
+
+Flushes all in-memory data to disk asynchronously.
+
+```typescript
+await db.flush();
+```
+
+### `db.flushSync(): void`
+
+Flushes all in-memory data to disk synchronously. Note that this can be an expensive operation, so
+it is recommended to use `flush()` if you want to keep the event loop free.
+
+```typescript
+db.flushSync();
+```
+
 ### `db.get(key: Key, options?: GetOptions): MaybePromise<any>`
 
 Retreives the value for a given key. If the key does not exist, it will resolve `undefined`.
@@ -248,6 +309,16 @@ Note that all errors are returned as rejected promises.
 
 Synchronous version of `get()`.
 
+### `db.getEstimatedKeyCount(): number`
+
+Retrieves the estimated number of keys in the database. This is an alias for
+`db.getDBIntProperty('rocksdb.estimate-num-keys')`.
+
+```typescript
+const estimated = db.getEstimatedKeyCount();
+console.log(estimated);
+```
+
 ### `db.getKeys(options?: IteratorOptions): ExtendedIterable`
 
 Retrieves all keys within a range.
@@ -260,11 +331,11 @@ for (const key of db.getKeys()) {
 
 ### `db.getKeysCount(options?: RangeOptions): number`
 
-Retrieves the number of keys within a range.
+Retrieves the exact number of keys in a database or a range.
 
 ```typescript
-const total = db.getKeysCount();
-const range = db.getKeysCount({ start: 'a', end: 'z' });
+const count = db.getKeysCount(); // estimated number of keys
+const range = db.getKeysCount({ start: 'a', end: 'z' }); // exact number of keys in the range
 ```
 
 ### `db.getMonotonicTimestamp(): number`
@@ -876,23 +947,6 @@ Note: If the `callback` throws an error, Node.js suppress the error. Node.js 18.
 `--force-node-api-uncaught-exceptions-policy` flag which will cause errors to emit the
 `'uncaughtException'` event. Future Node.js releases will enable this flag by default.
 
-### `db.flush(): Promise<void>`
-
-Flushes all in-memory data to disk asynchronously.
-
-```typescript
-await db.flush();
-```
-
-### `db.flushSync(): void`
-
-Flushes all in-memory data to disk synchronously. Note that this can be an expensive operation, so
-it is recommended to use `flush()` if you want to keep the event loop free.
-
-```typescript
-db.flushSync();
-```
-
 ## Transaction Log
 
 A user controlled API for logging transactions. This API is designed to be generic so that you can
@@ -1129,6 +1183,8 @@ The default `Store` contains the following methods which can be overridden:
 
 - `constructor(path, options?)`
 - `close()`
+- `compact(options?)`
+- `compactSync(options?)`
 - `decodeKey(key)`
 - `decodeValue(value)`
 - `encodeKey(key)`
@@ -1235,6 +1291,40 @@ Extends `RangeOptions`.
 - `options: object`
   - `reverse: boolean` When `true`, the iterator will iterate in reverse order. Defaults to `false`.
 
+## CLI
+
+The `rocksdb-js` CLI is a command line interface for interacting with RocksDB databases.
+
+```bash
+rocksdb-js [dbpath]
+```
+
+Options:
+
+- `-h, --help` Show this help message
+- `-r, --readonly` Open the database in read-only mode
+- `-v, --version` Show the version information
+
+Available commands:
+
+- `clear` Clear all data in the current column family
+- `columns` List column families
+- `compact` Compact the current column family
+- `count` Count the number of keys in the current column family
+- `drop <column>` Permanently drop a column family
+- `exit` Exit the REPL
+- `get <key>` Get the value of a key
+- `help` Show this help message
+- `log [name] [file] [entry]` List the transaction log store names and log store files
+- `prop <key>` Get a RocksDB property (try "rocksdb.stats")
+- `purge-logs <name>` Purge transaction log files older than 3 days
+- `put <key> <value>` Set the value of a key
+- `query [start] [end]` Query a range of keys
+- `remove <key>` Delete a key
+- `repl` Open a JS sub-REPL; "db" refers to the current column family
+- `stats` Show the statistics for the current column family
+- `use [column]` Create a new column family or switch to an existing one
+
 ## Development
 
 This package requires Node.js 18 or higher, pnpm, and a C++ compiler.
@@ -1346,6 +1436,24 @@ To run the tests without code coverage, run:
 pnpm test
 ```
 
+#### Native C++ unit tests (GoogleTest)
+
+Build and run standalone native tests (RocksDB + binding `core/` helpers, no Node in the test
+binary):
+
+```bash
+pnpm test:native
+```
+
+Coverage report for native tests (macOS/Linux; requires `lcov`):
+
+```bash
+pnpm coverage:native
+# open coverage/native/html/index.html
+```
+
+Note: Code coverage is not supported on Windows. Tests are run without coverage.
+
 To run a specific test suite, for example `"ranges"`, run:
 
 ```bash