@harperfast/rocksdb-js 2.8.0 → 2.9.1

package/dist/index.mjs

@@ -66,6 +66,26 @@ const binding = req(locateBinding());
 */
 const BackgroundError = binding.BackgroundError;
 const config = binding.config;
+/**
+* Reads the live state of the process-wide `WriteBufferManager`: its budget,
+* charged memory, mutable share, stall state, and attached column-family
+* inventory. The manager is shared by every database and worker thread in the
+* process.
+*
+* A WriteBufferManager stall does not pass through RocksDB's `WriteController`,
+* so it is not reflected by `rocksdb.stall.micros`, `db.isWriteStalled()`, or
+* the `'writeStall'` event. Use `stallActive` to distinguish this condition from
+* an idle database.
+*
+* @example
+* ```typescript
+* const wbm = getWriteBufferManagerStats();
+* if (wbm.stallActive) {
+* 	log.warn(`writes stalled for ${wbm.stallActiveMs}ms`);
+* }
+* ```
+*/
+const getWriteBufferManagerStats = binding.getWriteBufferManagerStats;
 const FRESH_VERSION_FLAG$1 = binding.constants.FRESH_VERSION_FLAG;
 const addGlobalListener = binding.addListener;
 const removeGlobalListener = binding.removeListener;
@@ -114,6 +134,8 @@ const transactionLogMapCount = binding.transactionLogMapCount;
 * disarm. Used by the ERR_TRY_AGAIN retry regression test.
 */
 const forceTryAgainForTesting = binding.forceTryAgainForTesting;
+/** Delays one selected watchdog join in the concurrent-shutdown regression test. */
+const setWriteBufferManagerJoinDelayForTesting = binding.setWriteBufferManagerJoinDelayForTesting;
 /**
 * Creates a native file lock using the specified file path (`flock` on POSIX,
 * `LockFileEx` on Windows), creating the file and any missing parent
@@ -642,14 +664,12 @@ function parseDuration(duration) {
 				num *= 1e3;
 				break;
 			case "m":
-				num *= 1e3 * 60;
+				num *= 6e4;
 				break;
 			case "h":
-				num *= 1e3 * 60 * 60;
-				break;
-			case "d":
-				num *= 1e3 * 60 * 60 * 24;
+				num *= 36e5;
 				break;
+			case "d": num *= 864e5;
 		}
 		result += num;
 	}
@@ -1248,7 +1268,15 @@ var DBIterator = class {
 			this.iterator.return?.();
 			return DONE_RESULT;
 		}
-		const result = this.iterator.next();
+		let result;
+		try {
+			result = this.iterator.next();
+		} catch (err) {
+			try {
+				this.iterator.return?.();
+			} catch {}
+			throw err;
+		}
 		if (result === ITERATOR_RESULT_DONE) return DONE_RESULT;
 		this.#yielded++;
 		const includeValues = this.#includeValues;
@@ -1352,10 +1380,10 @@ function createFixedBuffer(size) {
 
 //#endregion
 //#region src/store.ts
-const { ONLY_IF_IN_MEMORY_CACHE_FLAG, NOT_IN_MEMORY_CACHE_FLAG, ALWAYS_CREATE_NEW_BUFFER_FLAG, FRESH_VERSION_FLAG, POPULATE_VERSION_FLAG, ITERATOR_REVERSE_FLAG, ITERATOR_INCLUSIVE_END_FLAG, ITERATOR_EXCLUSIVE_START_FLAG, ITERATOR_INCLUDE_VALUES_FLAG, ITERATOR_NEEDS_STABLE_VALUE_BUFFER_FLAG, ITERATOR_CONTEXT_IS_TRANSACTION_FLAG } = constants;
+const { ONLY_IF_IN_MEMORY_CACHE_FLAG, NOT_IN_MEMORY_CACHE_FLAG, ALWAYS_CREATE_NEW_BUFFER_FLAG, FRESH_VERSION_FLAG, POPULATE_VERSION_FLAG, ITERATOR_REVERSE_FLAG, ITERATOR_INCLUSIVE_END_FLAG, ITERATOR_EXCLUSIVE_START_FLAG, ITERATOR_INCLUDE_VALUES_FLAG, ITERATOR_NEEDS_STABLE_VALUE_BUFFER_FLAG, ITERATOR_CONTEXT_IS_TRANSACTION_FLAG, ITERATOR_HAS_TRANSACTION_ID_FLAG } = constants;
 const KEY_BUFFER_SIZE = 4096;
 const KEY_BUFFER = createFixedBuffer(KEY_BUFFER_SIZE);
-const VALUE_BUFFER = createFixedBuffer(64 * 1024);
+const VALUE_BUFFER = createFixedBuffer(65536);
 /**
 * Backing buffer for the shared iterator state. Layout (Uint32Array view):
 *   [0] = key length written into KEY_BUFFER by the most recent iterator step
@@ -1363,7 +1391,7 @@ const VALUE_BUFFER = createFixedBuffer(64 * 1024);
 */
 const ITERATOR_STATE_BUFFER = Buffer.allocUnsafeSlow(8);
 const ITERATOR_STATE = new Uint32Array(ITERATOR_STATE_BUFFER.buffer, ITERATOR_STATE_BUFFER.byteOffset, 2);
-const MAX_KEY_SIZE = 1024 * 1024;
+const MAX_KEY_SIZE = 1048576;
 const SAVE_BUFFER_SIZE = 8192;
 /**
 * Normalizes the public `compression` option into the primitive fields the
@@ -1398,6 +1426,15 @@ function normalizeCompression(option) {
 	};
 }
 /**
+* Whether `codec` is a pre-constructed encoder/decoder instance that `open()`
+* would reuse as-is (rather than instantiate fresh from an `Encoder` factory).
+* Such an instance carries per-column-family mutable state (its `name`, msgpack
+* `structures`), so it cannot be shared across column families.
+*/
+function sharesMutableCodec(codec) {
+	return codec != null && typeof codec === "object" && typeof codec.Encoder !== "function" && (typeof codec.encode === "function" || typeof codec.decode === "function");
+}
+/**
 * 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.
@@ -1416,6 +1453,13 @@ var Store = class {
 	*/
 	#claimed = false;
 	/**
+	* Shallow snapshot of the options this store was constructed with, used by
+	* `createColumnFamilyStore()` to derive sibling column-family stores. Snapshot
+	* (not the caller's object) so later mutations of the caller's options don't
+	* leak into derived views.
+	*/
+	#columnFamilyOptions;
+	/**
 	* The database instance.
 	*/
 	db;
@@ -1510,10 +1554,16 @@ var Store = class {
 	/**
 	* The bytes of recent memtable history to retain in memory for transaction
 	* conflict checking. `-1` derives the value from
-	* `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
+	* `maxWriteBufferNumber * writeBufferSize`, except when a
+	* `writeBufferManager` is configured, where it derives `1`: retained history
+	* is charged to that manager and is only trimmable down to this target, so a
+	* target the budget cannot hold is memory the manager never reclaims, and
+	* stalls writes permanently when `writeBufferManagerAllowStall` is on. Any
+	* configured manager, not only a stalling one — that flag is mutable at
+	* runtime while this value is fixed when the family is created. `1`, not `0`, because
+	* RocksDB's transaction wrappers rewrite a `0` target to the derived value —
+	* so `0` asks for the largest history rather than none, and an explicit `0`
+	* is normalized to `1` for that reason. Set a positive number to size it
 	* yourself against the budget and the column-family count.
 	*/
 	maxWriteBufferSizeToMaintain;
@@ -1551,6 +1601,11 @@ var Store = class {
 	*/
 	path;
 	/**
+	* The open database's resolved filesystem identity, read once from
+	* `NativeDatabase.identityPath`. `undefined` until opened.
+	*/
+	identityPath;
+	/**
 	* Whether to use pessimistic locking for transactions. When `true`,
 	* transactions will fail as soon as a conflict is detected. When `false`,
 	* transactions will only fail when `commit()` is called.
@@ -1564,6 +1619,13 @@ var Store = class {
 	*/
 	readOnly;
 	/**
+	* The secondary instance's workspace directory when the database is opened
+	* as a secondary (see `RocksDatabaseOptions.secondaryPath`); `undefined`
+	* otherwise. A secondary is read-only, so `readOnly` is `true` whenever
+	* this is set.
+	*/
+	secondaryPath;
+	/**
 	* Encoder specific flag used to signal that the encoder should use a random
 	* access structure.
 	*/
@@ -1649,7 +1711,10 @@ var Store = class {
 		this.parallelismThreads = options?.parallelismThreads;
 		this.path = path;
 		this.pessimistic = options?.pessimistic ?? false;
-		this.readOnly = options?.readOnly ?? false;
+		const secondaryPath = options?.secondaryPath ?? void 0;
+		if (secondaryPath !== void 0 && options?.readOnly === false) throw new Error("A secondary open is read-only; secondaryPath cannot be combined with readOnly: false");
+		this.readOnly = options?.readOnly ?? secondaryPath !== void 0;
+		this.secondaryPath = secondaryPath;
 		this.randomAccessStructure = options?.randomAccessStructure ?? false;
 		this.readKey = readKey;
 		this.sharedStructuresKey = options?.sharedStructuresKey;
@@ -1661,6 +1726,36 @@ var Store = class {
 		this.verificationTable = options?.verificationTable;
 		this.writeBufferSize = options?.writeBufferSize;
 		this.writeKey = writeKey;
+		this.#columnFamilyOptions = options ? { ...options } : void 0;
+	}
+	/**
+	* Creates an independent `Store` for another column family of the same
+	* database, used by {@link RocksDatabase#use}. The returned store shares the
+	* underlying database but must have its own codec state: a mutable
+	* encoder/decoder instance cannot be shared across column families (opening a
+	* view mutates the encoder's `name`, and clearing a view resets its
+	* `structures`), so a pre-constructed instance is rejected here — supply an
+	* encoder factory (`{ Encoder }`) or a named `encoding` instead.
+	*
+	* Override this in a `Store` subclass whose constructor cannot be recreated
+	* from `(path, options)` (e.g. it takes injected dependencies) or that needs
+	* to control how a view's codec state is built.
+	*
+	* @param name - The column family name for the derived store.
+	* @param options - Options overriding this store's, for the derived store.
+	* @returns A new, independent `Store` bound to `name`.
+	*/
+	createColumnFamilyStore(name, options) {
+		const derived = {
+			...this.#columnFamilyOptions,
+			...options,
+			name
+		};
+		if (sharesMutableCodec(derived.encoder) || sharesMutableCodec(derived.decoder)) throw new Error("Cannot derive a column family view from a Store configured with a pre-constructed encoder/decoder instance — its mutable state would be shared across column families. Provide an encoder factory (`{ Encoder }`) or a named `encoding`, or override `Store#createColumnFamilyStore`.");
+		const StoreClass = this.constructor;
+		const store = new StoreClass(this.path, derived);
+		if (store.name !== name) throw new Error(`Store#createColumnFamilyStore produced a store bound to "${store.name}" instead of "${name}"; a custom Store must forward options to super() or override this method.`);
+		return store;
 	}
 	/**
 	* Closes the database.
@@ -1842,6 +1937,7 @@ var Store = class {
 		let endUnencoded = options?.key ?? options?.end;
 		const includeValues = options?.values ?? true;
 		const reverse = options?.reverse ?? false;
+		const txnId = this.getTxnId(options);
 		let exclusiveStart = options?.exclusiveStart ?? false;
 		let inclusiveEnd = options?.inclusiveEnd ?? false;
 		if (options?.key !== void 0) inclusiveEnd = true;
@@ -1860,13 +1956,15 @@ var Store = class {
 			startKeyEnd = this.writeKey(startUnencoded, keyBuffer, 0);
 			if (startKeyEnd === 0) throw new Error("Zero length key is not allowed");
 		}
-		if (endUnencoded !== void 0) if (endUnencoded === startUnencoded) {
-			endKeyStart = 0;
-			endKeyEnd = startKeyEnd;
-		} else {
-			endKeyStart = startKeyEnd;
-			endKeyEnd = this.writeKey(endUnencoded, keyBuffer, endKeyStart);
-			if (endKeyEnd === endKeyStart) throw new Error("Zero length key is not allowed");
+		if (endUnencoded !== void 0) {
+			if (endUnencoded === startUnencoded) {
+				endKeyStart = 0;
+				endKeyEnd = startKeyEnd;
+			} else {
+				endKeyStart = startKeyEnd;
+				endKeyEnd = this.writeKey(endUnencoded, keyBuffer, endKeyStart);
+				if (endKeyEnd === endKeyStart) throw new Error("Zero length key is not allowed");
+			}
 		}
 		let flags = 0;
 		if (reverse) flags |= ITERATOR_REVERSE_FLAG;
@@ -1875,8 +1973,9 @@ var Store = class {
 		if (includeValues) flags |= ITERATOR_INCLUDE_VALUES_FLAG;
 		if (includeValues && !this.decoderCopies) flags |= ITERATOR_NEEDS_STABLE_VALUE_BUFFER_FLAG;
 		if (context !== this.db) flags |= ITERATOR_CONTEXT_IS_TRANSACTION_FLAG;
+		if (txnId !== void 0) flags |= ITERATOR_HAS_TRANSACTION_ID_FLAG;
 		const advancedOptions = options !== void 0 && (options.adaptiveReadahead !== void 0 || options.asyncIO !== void 0 || options.autoReadaheadSize !== void 0 || options.backgroundPurgeOnIteratorCleanup !== void 0 || options.fillCache !== void 0 || options.readaheadSize !== void 0 || options.tailing !== void 0) ? options : void 0;
-		return new ExtendedIterable(new DBIterator(new NativeIterator(context, flags, startKeyEnd, endKeyStart, endKeyEnd, advancedOptions), this, includeValues, options?.limit));
+		return new ExtendedIterable(new DBIterator(new NativeIterator(context, flags, startKeyEnd, endKeyStart, endKeyEnd, advancedOptions, txnId), this, includeValues, options?.limit));
 	}
 	getSync(context, key, alwaysCreateNewBuffer = false, options) {
 		const keyParam = getKeyParam(this.encodeKey(key));
@@ -1897,9 +1996,12 @@ var Store = class {
 	*/
 	getTxnId(options) {
 		let txnId;
-		if (!this.readOnly && options?.transaction) {
-			txnId = options.transaction.id;
+		const transaction = options?.transaction;
+		if (!this.readOnly && transaction) {
+			txnId = transaction.id;
 			if (txnId === void 0) throw new TypeError("Invalid transaction");
+			if (transaction.store === void 0) throw new TypeError("Invalid transaction");
+			if (this.identityPath !== void 0 && transaction.store.identityPath !== this.identityPath) throw new TypeError("Transaction belongs to a different database");
 		}
 		return txnId;
 	}
@@ -1957,7 +2059,10 @@ var Store = class {
 	* are performed.
 	*/
 	open() {
-		if (this.db.opened) return true;
+		if (this.db.opened) {
+			this.identityPath = this.db.identityPath;
+			return true;
+		}
 		const { compression, compressionLevel } = normalizeCompression(this.compression);
 		this.db.open(this.path, {
 			compression,
@@ -1976,6 +2081,7 @@ var Store = class {
 			noBlockCache: this.noBlockCache,
 			parallelismThreads: this.parallelismThreads,
 			readOnly: this.readOnly,
+			secondaryPath: this.secondaryPath,
 			statsLevel: this.statsLevel,
 			transactionLogMaxAgeThreshold: this.transactionLogMaxAgeThreshold,
 			transactionLogMaxSize: this.transactionLogMaxSize,
@@ -1984,6 +2090,7 @@ var Store = class {
 			verificationTable: this.verificationTable,
 			writeBufferSize: this.writeBufferSize
 		});
+		this.identityPath = this.db.identityPath;
 		return false;
 	}
 	putSync(context, key, value, options) {
@@ -2244,10 +2351,12 @@ var Transaction = class extends DBI {
 		return err;
 	}
 	/**
-	* Returns the transaction start timestamp in seconds. Defaults to the time at which
-	* the transaction was created.
+	* Returns the transaction timestamp in milliseconds since the Unix epoch. It
+	* defaults to a process-wide monotonic value assigned when the transaction
+	* was created. A producer may use this value as its write identity; the
+	* transaction log uses it as the batch key.
 	*
-	* @returns The transaction start timestamp in seconds.
+	* @returns The transaction timestamp in milliseconds.
 	*/
 	getTimestamp() {
 		return this.#txn.getTimestamp();
@@ -2259,9 +2368,14 @@ var Transaction = class extends DBI {
 		return this.#txn.id;
 	}
 	/**
-	* Set the transaction start timestamp in seconds.
+	* Overrides the transaction timestamp in milliseconds since the Unix epoch.
+	* Call this before reading the timestamp or staging writes when adopting an
+	* origin timestamp for replication or replay. Once a write or log entry is
+	* staged, the timestamp is frozen, but reapplying the same timestamp remains
+	* idempotent while the transaction is pending. The value must be finite,
+	* positive, and below 8640000000000000.
 	*
-	* @param timestamp - The timestamp to set in seconds.
+	* @param timestamp - The timestamp to set in milliseconds.
 	*/
 	setTimestamp(timestamp) {
 		this.#txn.setTimestamp(timestamp);
@@ -2295,9 +2409,23 @@ function backgroundErrorSeverityName(severity) {
 */
 var RocksDatabase = class RocksDatabase extends DBI {
 	/**
-	* The name of the database.
+	* The name of the database's column family.
 	*/
 	#name;
+	/**
+	* Weak cache of column-family views opened via `use()`, keyed by column
+	* family name — mirroring `useLog`'s get-or-create semantics. The reference
+	* is weak so a view is never pinned for this database's lifetime: an
+	* unreferenced view can be collected (closing its own `DBHandle`), and the
+	* next `use()` transparently recreates it. `#columnFamilyRegistry` deletes an
+	* entry once its view is collected so a churn of distinct names (e.g.
+	* `use(uuid())`) does not grow the map without bound.
+	*/
+	#columnFamilies = /* @__PURE__ */ new Map();
+	#columnFamilyRegistry = new FinalizationRegistry((name) => {
+		const ref = this.#columnFamilies.get(name);
+		if (ref !== void 0 && ref.deref() === void 0) this.#columnFamilies.delete(name);
+	});
 	constructor(pathOrStore, options) {
 		let store;
 		if (typeof pathOrStore === "string") store = new Store(pathOrStore, options);
@@ -2305,7 +2433,7 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		else throw new TypeError("Invalid database path or store");
 		store.claim();
 		super(store);
-		this.#name = options?.name ?? "default";
+		this.#name = this.store.name;
 	}
 	/**
 	* Removes all data from the database asynchronously.
@@ -2524,6 +2652,40 @@ var RocksDatabase = class RocksDatabase extends DBI {
 	static notify(event, ...args) {
 		return globalNotify(event, args);
 	}
+	/**
+	* Advances a secondary instance to the primary's current state by tailing
+	* and replaying the primary's MANIFEST and WAL. A secondary does not see
+	* the primary's writes until this (or {@link catchUpWithPrimarySync}) is
+	* called. Concurrent reads through this handle remain safe while the
+	* catch-up runs.
+	*
+	* Only valid on a database opened with the `secondaryPath` option; throws
+	* with code `ERR_NOT_SECONDARY` otherwise.
+	*
+	* Advances the **database** view only. Against a cross-process primary,
+	* transaction-log reads keep serving the stores discovered at open (a store
+	* the primary creates later, and its appends, need a reopen); a primary in
+	* the same process shares the store registry, so its stores and appends are
+	* visible immediately. Either way a log entry can describe data this
+	* handle's database view does not have yet — the log write completes before
+	* the RocksDB commit for every writer, so consumers must tolerate the log
+	* leading the database.
+	*
+	* Await one call before starting the next: the replay holds a libuv worker
+	* for its whole duration and concurrent calls queue on a per-database mutex
+	* while holding theirs, so overlapping catch-ups on a backlogged follower
+	* can exhaust the default four-thread pool and stall unrelated I/O.
+	*/
+	catchUpWithPrimary() {
+		return new Promise((resolve, reject) => this.store.db.catchUpWithPrimary(resolve, reject));
+	}
+	/**
+	* Synchronous version of {@link catchUpWithPrimary}. The replay runs on the
+	* JS thread, so prefer the async form unless the caller is already blocking.
+	*/
+	catchUpWithPrimarySync() {
+		this.store.db.catchUpWithPrimarySync();
+	}
 	destroy() {
 		this.store.db.destroy();
 	}
@@ -2676,6 +2838,29 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		return this.store.db.getDBProperty(propertyName);
 	}
 	/**
+	* Whether RocksDB is currently applying write backpressure to this database —
+	* either delaying (rate-limiting) or fully stopping writes. This is the
+	* authoritative, live pull counterpart to the `'writeStall'`
+	* [event](../README.md#event-writestall): the event pushes per-column-family
+	* transitions (and is rate-limited), while this reads the current state on
+	* demand and can never be stale.
+	*
+	* The write controller is database-wide (shared across every column family),
+	* so this reflects the database as a whole, not a single column family — a
+	* stall triggered by any column family stops writes for all of them. Reads
+	* `rocksdb.is-write-stopped` and `rocksdb.actual-delayed-write-rate`.
+	*
+	* @example
+	* ```typescript
+	* db.on('writeStall', (cf) => {
+	* 	if (db.isWriteStalled()) log.warn(`writes throttled/blocked (triggered by ${cf})`);
+	* });
+	* ```
+	*/
+	isWriteStalled() {
+		return this.getDBIntProperty("rocksdb.is-write-stopped") === 1 || (this.getDBIntProperty("rocksdb.actual-delayed-write-rate") ?? 0) > 0;
+	}
+	/**
 	* 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.
@@ -2853,18 +3038,29 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		return this.store.listLogs();
 	}
 	/**
-	* The name of the database.
+	* The name of the database's column family.
 	*/
 	get name() {
 		return this.#name;
 	}
 	/**
-	* Whether the database is open in readonly mode.
+	* Whether the database is open in readonly mode. Also `true` for a
+	* secondary instance (see {@link secondaryPath}), which is read-only by
+	* construction.
 	*/
 	get readOnly() {
 		return this.store.readOnly;
 	}
 	/**
+	* The secondary instance's workspace directory when the database was opened
+	* as a secondary (a read-only follower of a live primary — see the
+	* `secondaryPath` open option), or `undefined` for a regular or plain
+	* read-only open.
+	*/
+	get secondaryPath() {
+		return this.store.secondaryPath;
+	}
+	/**
 	* Sugar method for opening a database.
 	*
 	* @param pathOrStore - The filesystem path to the database or a custom store.
@@ -3137,6 +3333,57 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		return this.store.unlock(key);
 	}
 	/**
+	* Returns a `RocksDatabase` bound to the `name` column family of this same
+	* database, opening (and creating, if missing) the column family on first
+	* use. This is a factory — create-and-open sugar — not a stateful switch: the
+	* returned view is an independent instance whose own reads/writes target its
+	* column family, while sharing the underlying database (so a transaction,
+	* backup, or checkpoint still spans every column family). Because the view
+	* opens its own handle, this database need not itself be open — a discarded
+	* parent (`new RocksDatabase(path).use('events')`) still yields a valid,
+	* opened view.
+	*
+	* Get-or-create, backed by a weak cache: `db.use('events') === db.use('events')`
+	* while the view is still referenced **and open**, and calling with this
+	* database's own column-family name returns `this`. A view that has been
+	* closed (or garbage-collected — the cache does not pin it) is transparently
+	* recreated on the next `use()`. Views are independent handles: closing this
+	* database does not close them, and vice versa — the underlying database
+	* stays open until every handle is closed or collected.
+	*
+	* The view's store is derived by {@link Store#createColumnFamilyStore}, which
+	* builds an independent store of the same class with its own codec state (so
+	* views never share a mutable encoder/decoder) and inherits the options this
+	* store was constructed with; pass `options` to override them for this column
+	* family. A database configured with a pre-constructed encoder/decoder
+	* instance cannot derive views (its state would be shared) — use an encoder
+	* factory (`{ Encoder }`) or a named `encoding`, or override
+	* `createColumnFamilyStore` on a custom `Store`.
+	*
+	* @param name - The column family name.
+	* @param options - Options for the column family, overriding inherited ones.
+	* @returns A `RocksDatabase` bound to the column family.
+	*
+	* @example
+	* ```typescript
+	* const db = RocksDatabase.open('/path/to/database');
+	* const events = db.use('events');
+	* await events.put('e1', payload);
+	* await db.put('k', 'v'); // default column family, unaffected
+	* ```
+	*/
+	use(name, options) {
+		if (typeof name !== "string" || name === "") throw new TypeError("Column family name must be a non-empty string");
+		if (name === this.#name) return this.open();
+		const cached = this.#columnFamilies.get(name)?.deref();
+		if (cached !== void 0 && cached.isOpen()) return cached;
+		const columnFamily = new RocksDatabase(this.store.createColumnFamilyStore(name, options));
+		columnFamily.open();
+		this.#columnFamilies.set(name, new WeakRef(columnFamily));
+		this.#columnFamilyRegistry.register(columnFamily, name);
+		return columnFamily;
+	}
+	/**
 	* Excecutes a function using a thread-safe lock to ensure mutual
 	* exclusion.
 	*
@@ -3443,11 +3690,12 @@ Object.defineProperty(TransactionLog.prototype, "query", { value({ start, end, e
 				position += TRANSACTION_LOG_ENTRY_HEADER_SIZE;
 				let matchesRange;
 				if (foundExactStart) matchesRange = (!exclusiveStart || timestamp !== start) && timestamp < end;
-				else if (exactStart) if (timestamp === start) {
-					matchesRange = !exclusiveStart;
-					foundExactStart = true;
-				} else matchesRange = false;
-				else matchesRange = (exclusiveStart ? timestamp > start : timestamp >= start) && timestamp < end;
+				else if (exactStart) {
+					if (timestamp === start) {
+						matchesRange = !exclusiveStart;
+						foundExactStart = true;
+					} else matchesRange = false;
+				} else matchesRange = (exclusiveStart ? timestamp > start : timestamp >= start) && timestamp < end;
 				const entryStart = position;
 				position += length;
 				if (matchesRange) return {
@@ -3530,9 +3778,9 @@ function loadLastPosition(transactionLog, readUncommitted) {
 //#region src/index.ts
 const versions = {
 	rocksdb: version,
-	"rocksdb-js": "2.8.0"
+	"rocksdb-js": "2.9.1"
 };
 
 //#endregion
-export { BackgroundError, CorruptFrameError, CountEstimator, 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, getWriteBufferManagerStats, parseTransactionLog, registryStatus, shutdown, stats, supportedCompression, tryFileLock, validateTransactionLogStore, versions };
 //# sourceMappingURL=index.mjs.map