@harperfast/rocksdb-js 2.5.0 → 2.6.0

package/README.md

@@ -10,6 +10,7 @@ A Node.js binding for the RocksDB library.
 - Transaction log system for recording transaction related data
 - Custom stores provide ability to override default database interactions
 - Efficient binary key and value encoding
+- Configurable block/blob compression (LZ4, Zstd, Zlib, and more)
 - Access to internal RocksDB statistics
 - Designed for Node.js and Bun on Linux, macOS, and Windows
 
@@ -43,6 +44,15 @@ Creates a new database instance.
 - `path: string` The path to write the database files to. This path does not need to exist, but the
   parent directories do.
 - `options: object` [optional]
+  - `compression: string | { algorithm: string, level?: number }` The block/blob compression
+    algorithm for this column family. Pass an algorithm name — one of `'none'`, `'snappy'`,
+    `'zlib'`, `'bzip2'`, `'lz4'`, `'lz4hc'`, or `'zstd'` — or an object with an
+    `algorithm` and an optional `level` (forwarded to RocksDB's `compression_opts.level`; the
+    meaning is algorithm-specific). Applies to both SST data blocks and blob files (large values).
+    Defaults to `'lz4'` when the native build supports it, otherwise RocksDB's own default (Snappy
+    when linked, else no compression). See [Compression](#compression). Throws if the algorithm is
+    not compiled into the native build — check [`supportedCompression`](#supportedcompression) for
+    the available list.
   - `disableWAL: boolean` Whether to disable the RocksDB write ahead log. Defaults to `false`.
   - `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.
@@ -67,7 +77,8 @@ Creates a new database instance.
   - `statsLevel: StatsLevel` Controls which type of statistics to skip and reduce statistic
     overhead. Defaults to `StatsLevel.ExceptDetailedTimers`.
   - `store: Store` A custom store that handles all interaction between the `RocksDatabase` or
-    `Transaction` instances and the native database interface. See [Custom Store](#custom-store) for
+    `Transaction` instances and the native database interface. A store is bound to a single
+    `RocksDatabase` instance and cannot be shared between them. See [Custom Store](#custom-store) for
     more information.
   - `transactionLogMaxAgeThreshold: number` The threshold for the transaction log file's last
     modified time to be older than the retention period before it is rotated to the next sequence
@@ -109,6 +120,18 @@ const db2 = new RocksDatabase('path/to/db', { name: 'users' });
 console.log(db.columns); // ['default', 'users']
 ```
 
+### `db.compression: { algorithm: string, level?: number }`
+
+Returns the compression currently in effect for this database's column family, read live from
+RocksDB. `algorithm` is a friendly name (e.g. `'lz4'`, `'zstd'`, `'none'`); `level` is present only
+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 } });
+console.log(db.compression); // { algorithm: 'zstd', level: 3 }
+```
+
 ### `db.config(options)`
 
 Sets global database settings.
@@ -911,6 +934,77 @@ An object is a record with the following properties:
 - `standardDeviation: number` A double containing the standard deviation.
 - `sum: number` An unsigned 64-bit integer containing the sum of all values.
 
+## Compression
+
+RocksDB compresses data blocks in SST files (and, in `rocksdb-js`, blob files that hold large
+values) using a configurable algorithm. Compression trades CPU for disk space and, because it
+reduces bytes read from disk, often improves read throughput on I/O-bound workloads.
+
+The following algorithm names are recognized. Which ones are actually usable depends on the native
+build — see **Availability** below.
+
+| Name     | Notes                                                                         |
+| -------- | ----------------------------------------------------------------------------- |
+| `none`   | No compression. Always available.                                             |
+| `snappy` | Fast, modest ratio. RocksDB's own stock default when linked.                  |
+| `zlib`   | Higher ratio, slower. Supports `level` (see zlib's manual).                   |
+| `bzip2`  | High ratio, slow; rarely worth it over zstd.                                  |
+| `lz4`    | Very fast, modest ratio. `rocksdb-js` default when available.                 |
+| `lz4hc`  | LZ4 high-compression variant: better ratio, slower writes, same fast reads.   |
+| `zstd`   | Best ratio-for-speed of the set; supports `level` (higher = smaller, slower). |
+
+Set the algorithm per column family with the `compression` option when opening a database:
+
+```typescript
+// Algorithm name
+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 } });
+
+// Disable compression entirely
+const db3 = RocksDatabase.open('/path/to/db3', { compression: 'none' });
+```
+
+**Default.** When `compression` is omitted, `rocksdb-js` defaults to **LZ4** if the native build
+supports it. LZ4 is fast with a modest compression ratio, making it a good general-purpose default.
+If LZ4 is not compiled in, the default falls back to RocksDB's own default — Snappy when it is
+linked, otherwise no compression. (RocksDB's stock default is Snappy; `rocksdb-js` overrides it to
+LZ4.) Read the algorithm actually in effect with the `db.compression` getter.
+
+**Availability.** The set of algorithms depends on which compression libraries the native binding
+was compiled against, so it varies by build. Always check
+[`supportedCompression`](#supportedcompression) at runtime — opening with an unavailable algorithm
+throws. `'none'` is always available.
+
+**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
+compression across a close/reopen (a plain reopen inherits it); the algorithm is dynamically
+changeable, so an explicit change governs files written afterward while existing SST/blob files keep
+their original compression until rewritten by compaction. It also applies to blob files (large
+values), whose compression otherwise defaults to none.
+
+Because a column family's compression is fixed while it is open, if the same column family is opened
+a second time in the same process (another `RocksDatabase` on the same path/`name`, including from a
+`worker_thread`) with an **explicitly different** algorithm or level, the second open **throws** — a
+plain reopen (no `compression`) instead inherits the live setting.
+
+### `supportedCompression`
+
+A module-level, frozen array of the compression algorithm names compiled into the loaded native
+binding. The set is fixed for a given binary. `'none'` is always present.
+
+```typescript
+import { supportedCompression } from '@harperfast/rocksdb-js';
+
+console.log(supportedCompression); // e.g. ['none', 'snappy', 'lz4', 'zstd']
+
+if (supportedCompression.includes('zstd')) {
+	// safe to open with { compression: 'zstd' }
+}
+```
+
 ## Exclusive Locking
 
 `rocksdb-js` includes a handful of functions for executing thread-safe mutually exclusive functions.
@@ -1767,6 +1861,13 @@ await db.put('foo', 'bar');
 console.log(await db.get('foo'));
 ```
 
+> [!NOTE]
+> A `Store` is bound to a single `RocksDatabase` instance. Passing a store that another
+> `RocksDatabase` already owns throws `Store is already in use by another RocksDatabase instance`.
+> The claim is durable across `db.close()`, so reopening the original owner does not release it.
+> (Sharing a store with the owning database's `Transaction` instances is expected and handled
+> internally.)
+
 > [!IMPORTANT]
 > If your custom store overrides `putSync()` without calling `super.putSync()` and it performs its
 > own `this.encodeKey(key)`, then you MUST encode the VALUE before you encode the KEY.

package/dist/index.cjs

@@ -87,6 +87,15 @@ const removeGlobalListener = binding.removeListener;
 const globalListenerCount = binding.listenerCount;
 const globalNotify = binding.notify;
 const constants = binding.constants;
+/**
+* The friendly names of every compression algorithm compiled into the loaded
+* RocksDB native binding, e.g. `['none', 'snappy', 'lz4', 'zstd']`. The set is
+* fixed for a given binary (it depends on which compression libraries RocksDB
+* was linked against), so this is a static list. `'none'` (no compression) is
+* always present. Use it to validate a `compression` option or to pick an
+* algorithm that is actually available at runtime.
+*/
+const supportedCompression = Object.freeze(binding.supportedCompression);
 const NativeDatabase = binding.Database;
 const NativeIterator = binding.Iterator;
 const NativeTransaction = binding.Transaction;
@@ -1228,13 +1237,50 @@ const ITERATOR_STATE = new Uint32Array(ITERATOR_STATE_BUFFER.buffer, ITERATOR_ST
 const MAX_KEY_SIZE = 1024 * 1024;
 const SAVE_BUFFER_SIZE = 8192;
 /**
+* Normalizes the public `compression` option into the primitive fields the
+* native layer expects. When `option` is omitted, returns an empty object and
+* lets the native layer apply the default (LZ4 when the build supports it, else
+* RocksDB's own default). Throws a `TypeError` for a malformed option and an
+* `Error` for an algorithm that isn't supported by this build.
+*/
+function normalizeCompression(option) {
+	if (option === void 0 || option === null) return {};
+	let algorithm;
+	let level;
+	if (typeof option === "string") algorithm = option;
+	else if (typeof option === "object" && option.algorithm !== void 0) {
+		algorithm = option.algorithm;
+		if (option.level !== void 0 && option.level !== null) {
+			const raw = option.level;
+			const coerced = typeof raw === "number" ? raw : typeof raw === "string" && raw.trim() !== "" ? Number(raw) : NaN;
+			if (!Number.isInteger(coerced) || coerced < -2147483648 || coerced > 2147483647) throw new TypeError(`compression level must be a 32-bit integer, got ${JSON.stringify(option.level)}`);
+			level = coerced;
+		}
+	} else throw new TypeError("compression must be an algorithm name or an { algorithm, level } object");
+	if (!supportedCompression.includes(algorithm)) throw new Error(`Unsupported compression algorithm "${algorithm}". This build supports: ${supportedCompression.join(", ")}`);
+	return {
+		compression: algorithm,
+		compressionLevel: level
+	};
+}
+/**
 * A store wraps the `NativeDatabase` binding and database settings so that a
 * single database instance can be shared between the main `RocksDatabase`
 * instance and the `Transaction` instance.
 *
-* This store should not be shared between `RocksDatabase` instances.
+* A store is bound to a single `RocksDatabase` instance and must not be shared
+* between `RocksDatabase` instances. Each `RocksDatabase` claims its store on
+* construction (see `claim()`); passing a store that another `RocksDatabase`
+* already owns throws. (Sharing with the owning database's `Transaction`
+* instances is expected and allowed.)
 */
 var Store = class {
+	/**
+	* Whether a `RocksDatabase` has claimed this store. Durable across
+	* close/reopen (unlike the handle's open state), so a store reused after its
+	* owner temporarily closed is still recognized as in-use. See `claim()`.
+	*/
+	#claimed = false;
 	/**
 	* The database instance.
 	*/
@@ -1249,6 +1295,11 @@ var Store = class {
 	*/
 	decoderCopies = false;
 	/**
+	* The compression algorithm (or `{ algorithm, level }`) requested for this
+	* store's column family. Normalized and applied when the database opens.
+	*/
+	compression;
+	/**
 	* Whether to disable the write ahead log.
 	*/
 	disableWAL;
@@ -1406,6 +1457,7 @@ var Store = class {
 		if (options !== void 0 && options !== null && typeof options !== "object") throw new TypeError("Database options must be an object");
 		const { keyEncoding, readKey, writeKey } = initKeyEncoder(options?.keyEncoding, options?.keyEncoder);
 		this.db = new NativeDatabase();
+		this.compression = options?.compression;
 		this.dbWriteBufferSize = options?.dbWriteBufferSize;
 		this.decoder = options?.decoder ?? null;
 		this.disableWAL = options?.disableWAL ?? false;
@@ -1445,6 +1497,16 @@ var Store = class {
 		this.db.close();
 	}
 	/**
+	* Claims this store for a `RocksDatabase`. A store is bound to a single
+	* database instance, so claiming a store that another `RocksDatabase` has
+	* already claimed throws. The claim is durable across close/reopen, so a
+	* store reused after its owner temporarily closed still throws.
+	*/
+	claim() {
+		if (this.#claimed) throw new Error("Store is already in use by another RocksDatabase instance");
+		this.#claimed = true;
+	}
+	/**
 	* Compacts the entire key range of the database asynchronously.
 	* This triggers manual compaction which removes tombstones and reclaims space.
 	*
@@ -1706,7 +1768,10 @@ var Store = class {
 	*/
 	open() {
 		if (this.db.opened) return true;
+		const { compression, compressionLevel } = normalizeCompression(this.compression);
 		this.db.open(this.path, {
+			compression,
+			compressionLevel,
 			dbWriteBufferSize: this.dbWriteBufferSize,
 			disableWAL: this.disableWAL,
 			enableStats: this.enableStats,
@@ -2008,9 +2073,12 @@ var RocksDatabase = class RocksDatabase extends DBI {
 	*/
 	#name;
 	constructor(pathOrStore, options) {
-		if (typeof pathOrStore === "string") super(new Store(pathOrStore, options));
-		else if (pathOrStore instanceof Store) super(pathOrStore);
+		let store;
+		if (typeof pathOrStore === "string") store = new Store(pathOrStore, options);
+		else if (pathOrStore instanceof Store) store = pathOrStore;
 		else throw new TypeError("Invalid database path or store");
+		store.claim();
+		super(store);
 		this.#name = options?.name ?? "default";
 	}
 	/**
@@ -2124,6 +2192,22 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		return this.store.db.columns;
 	}
 	/**
+	* The compression currently in effect for this database's column family, read
+	* live from RocksDB, as `{ algorithm, level? }`. `algorithm` is a friendly
+	* name (e.g. `'lz4'`, `'zstd'`, `'none'`); `level` is present only when a
+	* non-default compression level is set. The database must be open. Defaults to
+	* LZ4 when the native build supports it.
+	*
+	* @example
+	* ```typescript
+	* const db = RocksDatabase.open('/path/to/db', { compression: { algorithm: 'zstd', level: 3 } });
+	* db.compression; // { algorithm: 'zstd', level: 3 }
+	* ```
+	*/
+	get compression() {
+		return this.store.db.getCompression();
+	}
+	/**
 	* Set global database settings.
 	*
 	* @param options - The options for the database.
@@ -2953,7 +3037,7 @@ function loadLastPosition(transactionLog, readUncommitted) {
 //#region src/index.ts
 const versions = {
 	rocksdb: version,
-	"rocksdb-js": "2.5.0"
+	"rocksdb-js": "2.6.0"
 };
 
 //#endregion
@@ -2972,6 +3056,7 @@ exports.parseTransactionLog = parseTransactionLog;
 exports.registryStatus = registryStatus;
 exports.shutdown = shutdown;
 exports.stats = stats;
+exports.supportedCompression = supportedCompression;
 exports.tryFileLock = tryFileLock;
 exports.validateTransactionLogStore = validateTransactionLogStore;
 exports.versions = versions;