@harperfast/rocksdb-js 2.7.1 → 2.9.0

package/dist/index.d.mts

@@ -142,7 +142,7 @@ interface BackupInfo {
  * await backups.restore('/path/to/backups', '/path/to/restored-db');
  * ```
  */
-declare const backups: {
+export declare const backups: {
   /**
    * Restores a database from a backup directory into a (closed) database
    * directory. The default mode purges the destination directory, so it must
@@ -234,7 +234,7 @@ interface DBIteratorValue<T> {
  * shared `ITERATOR_STATE` buffer) instead of constructing a JS result object,
  * so this class is responsible for building the `IteratorResult`.
  */
-declare class DBIterator<T> implements Iterator<DBIteratorValue<T>> {
+export declare class DBIterator<T> implements Iterator<DBIteratorValue<T>> {
   #private;
   iterator: InstanceType<typeof NativeIteratorCls>;
   store: Store;
@@ -369,9 +369,58 @@ interface StoreOptions extends Omit<NativeDatabaseOptions, "compression" | "comp
   randomAccessStructure?: boolean;
   /**
    * When `true`, the database is opened in read-only mode. Write operations
-   * will throw an error with code `ERR_DATABASE_READONLY`.
+   * will throw an error with code `ERR_DATABASE_READONLY`, except for
+   * `flush()`/`flushSync()`/`compact()`/`compactSync()`, which succeed as
+   * no-ops.
+   *
+   * A read-only open is a **point-in-time snapshot**: it replays the MANIFEST
+   * as of the open and never sees later writes. It is safe against a
+   * quiescent database (nothing else writing), but **unsafe against a live
+   * writer**: the open holds no reference on the files it is about to read,
+   * so a concurrent compaction or blob GC in the writing process can delete
+   * one mid-open and the open fails with `ERR_CONCURRENT_COMPACTION` (the
+   * database is not corrupt — the reader lost a race). Even a successful open
+   * can fail *later reads* the same way: files the snapshot references are
+   * opened lazily, and the writer keeps deleting obsolete ones. To follow a
+   * database another process is actively writing, open a secondary instead
+   * (see `secondaryPath`) — that is the supported mode for a live follower.
    */
   readOnly?: boolean;
+  /**
+   * Opens the database as a **secondary instance**: a read-only follower of a
+   * live primary that tolerates the primary deleting files and sees new
+   * writes on each `catchUpWithPrimary()` / `catchUpWithPrimarySync()` call.
+   * This is the supported way to read a database another process is actively
+   * writing (a plain `readOnly` open is only safe against a quiescent
+   * database — see `readOnly`).
+   *
+   * The value is the secondary instance's own workspace directory (RocksDB
+   * keeps the secondary's private state there; it is created if missing).
+   * It must be distinct from the database `path` (enforced at open) and
+   * exclusive to one secondary instance — two secondaries sharing a
+   * workspace corrupt each other's state. Reusing a workspace in-process for
+   * a DIFFERENT database is rejected at open (the same database and
+   * workspace share the one follower instance), and a kernel advisory lock
+   * on `<secondaryPath>/.secondary.lock`
+   * excludes other processes — but on filesystems without advisory locking
+   * (e.g. FUSE/9p mounts behind Docker Desktop bind mounts) the lock
+   * degrades to a no-op, and on network filesystems it does not exclude
+   * across hosts, so workspace exclusivity is the caller's job there.
+   *
+   * Implies `readOnly: true` (combining with an explicit `readOnly: false`
+   * throws) and forces `maxOpenFiles: -1`: every table and blob file is
+   * opened and held for the life of each version, which is what makes the
+   * primary's file deletions safe — note the file-descriptor footprint on
+   * large databases. Column families created by the primary after the
+   * secondary opens are invisible until the secondary reopens.
+   *
+   * Note: RocksDB upstream documents secondary instances as unsupported in
+   * combination with integrated BlobDB (which this library enables for
+   * values >= 2KB); this library's pinned RocksDB build handles blob files
+   * in secondary mode and it is covered by tests, but the combination is
+   * not guaranteed by upstream.
+   */
+  secondaryPath?: string;
   sharedStructuresKey?: symbol;
   /**
    * A string containing the amount of time or the number of milliseconds to
@@ -405,7 +454,7 @@ type ArrayBufferWithNotify = ArrayBuffer & {
  * already owns throws. (Sharing with the owning database's `Transaction`
  * instances is expected and allowed.)
  */
-declare class Store {
+export declare class Store {
   #private;
   /**
    * The database instance.
@@ -542,6 +591,11 @@ declare class Store {
    * The path to the database.
    */
   path: string;
+  /**
+   * The open database's resolved filesystem identity, read once from
+   * `NativeDatabase.identityPath`. `undefined` until opened.
+   */
+  identityPath?: string;
   /**
    * Whether to use pessimistic locking for transactions. When `true`,
    * transactions will fail as soon as a conflict is detected. When `false`,
@@ -550,9 +604,18 @@ declare class Store {
   pessimistic: boolean;
   /**
    * Whether the database is open in readonly mode. When `true`, write
-   * operations will throw an error with code `ERR_DATABASE_READONLY`.
+   * operations will throw an error with code `ERR_DATABASE_READONLY`, except
+   * for `flush()`/`flushSync()`/`compact()`/`compactSync()`, which succeed as
+   * no-ops.
    */
   readOnly: boolean;
+  /**
+   * 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?: string;
   /**
    * Encoder specific flag used to signal that the encoder should use a random
    * access structure.
@@ -577,8 +640,8 @@ declare class Store {
    */
   transactionLogMaxAgeThreshold?: number;
   /**
-   * The maximum size of a transaction log before it is rotated to the next
-   * sequence number.
+   * The target maximum size of a transaction log before rotation. Transactions
+   * are never split across files, so one transaction may exceed this target.
    */
   transactionLogMaxSize?: number;
   /**
@@ -612,6 +675,24 @@ declare class Store {
    * @param options - The options for the store.
    */
   constructor(path: string, options?: StoreOptions);
+  /**
+   * 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: string, options?: StoreOptions): Store;
   /**
    * Closes the database.
    */
@@ -686,6 +767,13 @@ declare class Store {
    */
   encodeValue(value: any): BufferWithDataView | Uint8Array;
   get(context: StoreContext, key: Key, alwaysCreateNewBuffer?: boolean, options?: StoreGetOptions): any | undefined;
+  /**
+   * Estimates the number of keys in a range from RocksDB statistics
+   * (memtable stats + approximate SST sizes with range-local entry density)
+   * without iterating. Estimates always reflect committed state, so there is
+   * no transactional variant.
+   */
+  estimateCount(options?: CountEstimateOptions): CountEstimate;
   getCount(context: StoreContext, options?: StoreRangeOptions): number;
   getKeys(context: StoreContext, options?: StoreIteratorOptions): any | undefined;
   getKeysCount(context: StoreContext, options?: StoreRangeOptions): number;
@@ -824,7 +912,7 @@ declare const RETRY_NOW: number;
 /**
  * Provides transaction level operations to a transaction callback.
  */
-declare class Transaction extends DBI {
+export declare class Transaction extends DBI {
   #private;
   /**
    * Create a new transaction.
@@ -858,10 +946,12 @@ declare class Transaction extends DBI {
    */
   commitSync(): void;
   /**
-   * 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(): number;
   /**
@@ -869,9 +959,14 @@ declare class Transaction extends DBI {
    */
   get id(): number;
   /**
-   * 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?: number): void;
 }
@@ -930,6 +1025,21 @@ interface RocksDBOptions {
    */
   tailing?: boolean;
 }
+interface CountEstimate {
+  /**
+   * The estimated number of keys.
+   */
+  count: number;
+  /**
+   * Heuristic 0–1 indicator of how trustworthy `count` is; exactly 1 only
+   * when the count is exact. Derived from the estimate's resolution
+   * (SST data-block / memtable sampling granularity relative to the count),
+   * the tombstone fraction of the overlapping SSTs, and — for open-ended
+   * starts — the error compounded by complement subtraction. A heuristic
+   * ordering signal, not a statistical bound.
+   */
+  confidence: number;
+}
 interface RangeOptions extends RocksDBOptions {
   /**
    * The range end key, otherwise known as the "upper bound". Defaults to
@@ -952,6 +1062,13 @@ interface RangeOptions extends RocksDBOptions {
    */
   start?: Key | Uint8Array;
 }
+interface CountEstimateOptions extends RangeOptions {
+  /**
+   * Interpret `start` as the upper bound and `end` as the lower bound, as
+   * `getRange()` does for reverse iteration. Defaults to `false`.
+   */
+  reverse?: boolean;
+}
 interface IteratorOptions extends RangeOptions {
   /**
    * The maximum number of entries to yield. When set, iteration stops after
@@ -991,7 +1108,7 @@ interface DBITransactional {
  *
  * This class is not meant to be used directly.
  */
-declare class DBI<T extends DBITransactional | unknown = unknown> {
+export declare class DBI<T extends DBITransactional | unknown = unknown> {
   /**
    * The RocksDB context for `get()`, `put()`, and `remove()`.
    */
@@ -1197,7 +1314,13 @@ declare class DBI<T extends DBITransactional | unknown = unknown> {
 }
 //#endregion
 //#region src/stats.d.ts
-/** Database-level RocksDB statistics types for `db.getStats()` / `db.getStat()`. */
+/**
+ * Database-level RocksDB statistics types for `db.getStats()` / `db.getStat()`.
+ *
+ * The `writeBufferManager.*` keys are the exception to "database-level": the
+ * WriteBufferManager is a process-wide singleton, so those values describe every
+ * database in the process. See `getWriteBufferManagerStats()`.
+ */
 type StatsHistogramData = {
   average: number;
   count: number;
@@ -1232,6 +1355,7 @@ type StatsBasics = {
   "rocksdb.num-live-versions": number;
   "rocksdb.current-super-version-number": number;
   "rocksdb.oldest-snapshot-time": number;
+  "rocksdb.num-snapshots": number;
   "rocksdb.num-blob-files": number;
   "rocksdb.total-blob-file-size": number;
   "rocksdb.live-blob-file-size": number;
@@ -1248,6 +1372,11 @@ type StatsBasics = {
   "txnlog.replayGapBytes": number;
   "commitPipeline.logQueueDepth": number;
   "commitPipeline.commitQueueDepth": number;
+  "writeBufferManager.bufferSize": number;
+  "writeBufferManager.memoryUsage": number;
+  "writeBufferManager.mutableMemoryUsage": number;
+  "writeBufferManager.stallActive": number;
+  "writeBufferManager.stallActiveMs": number;
 };
 type StatsCuratedExtras = {
   "rocksdb.block.cache.hit": number;
@@ -1495,6 +1624,34 @@ type StatsAllExtras = {
   "rocksdb.prefetch.memory.bytes.granted": number;
   "rocksdb.prefetch.memory.bytes.released": number;
   "rocksdb.prefetch.memory.requests.blocked": number;
+  "rocksdb.wal.precreate.hit": number;
+  "rocksdb.wal.precreate.miss": number;
+  "rocksdb.wal.precreate.waited": number;
+  "rocksdb.wal.precreate.wait.micros": number;
+  "rocksdb.wal.precreate.failed": number;
+  "rocksdb.rate.limiter.bytes.read": number;
+  "rocksdb.rate.limiter.bytes.write": number;
+  "rocksdb.rate.limiter.requests.read": number;
+  "rocksdb.rate.limiter.requests.write": number;
+  "rocksdb.rate.limiter.delayed.requests.read": number;
+  "rocksdb.rate.limiter.delayed.requests.write": number;
+  "rocksdb.rate.limiter.total.wait.micros.read": number;
+  "rocksdb.rate.limiter.total.wait.micros.write": number;
+  "rocksdb.read.path.range.tombstones.inserted": number;
+  "rocksdb.read.path.range.tombstones.discarded": number;
+  "rocksdb.file.open.metadata.retrieved": number;
+  "rocksdb.file.open.metadata.passed": number;
+  "rocksdb.manifest.validation.failure.count": number;
+  "rocksdb.flush.reason.write_buffer_full": number;
+  "rocksdb.flush.reason.write_buffer_manager": number;
+  "rocksdb.flush.reason.memtable_max_range_deletions": number;
+  "rocksdb.atomic_flush.request.reason.write_buffer_full": number;
+  "rocksdb.atomic_flush.request.reason.write_buffer_manager": number;
+  "rocksdb.atomic_flush.request.reason.memtable_max_range_deletions": number;
+  "rocksdb.atomic_flush.request.reason.other": number;
+  "rocksdb.checkpoint.read.bytes": number;
+  "rocksdb.checkpoint.write.bytes": number;
+  "rocksdb.file.submit.async.read.fallback": number;
   "rocksdb.compaction.times.cpu_micros": StatsHistogramData;
   "rocksdb.subcompaction.setup.times.micros": StatsHistogramData;
   "rocksdb.table.sync.micros": StatsHistogramData;
@@ -1555,6 +1712,18 @@ type StatsAllExtras = {
   "rocksdb.multiscan.prepare.micros": StatsHistogramData;
   "rocksdb.multiscan.blocks.per.prepare": StatsHistogramData;
   "rocksdb.block.key.distribution.cv": StatsHistogramData;
+  "rocksdb.ingest.external.file.prepare.micros": StatsHistogramData;
+  "rocksdb.ingest.external.file.run.micros": StatsHistogramData;
+  "rocksdb.iodispatcher.async.read.observed.completion.micros": StatsHistogramData;
+  "rocksdb.iodispatcher.async.read.poll.wait.micros": StatsHistogramData;
+  "rocksdb.iodispatcher.async.read.prefetch.lead.micros": StatsHistogramData;
+  "rocksdb.rate.limiter.wait.micros.read": StatsHistogramData;
+  "rocksdb.rate.limiter.wait.micros.write": StatsHistogramData;
+  "rocksdb.flush.memtable.memory.bytes": StatsHistogramData;
+  "rocksdb.flush.memtable.total.data.size.bytes": StatsHistogramData;
+  "rocksdb.flush.write_buffer_full.memtable.memory.bytes": StatsHistogramData;
+  "rocksdb.flush.write_buffer_manager.memtable.memory.bytes": StatsHistogramData;
+  "rocksdb.open.and.compact.db.open.micros": StatsHistogramData;
 };
 type StatsCurated = StatsBasics & StatsCuratedExtras;
 type StatsAll = StatsCurated & StatsAllExtras;
@@ -1672,9 +1841,72 @@ interface ValidateTransactionLogStoreOptions {
  * }
  * ```
  */
-declare function validateTransactionLogStore(path: string, options?: ValidateTransactionLogStoreOptions): Promise<TransactionLogStoreValidation>;
+export declare function validateTransactionLogStore(path: string, options?: ValidateTransactionLogStoreOptions): Promise<TransactionLogStoreValidation>;
 //#endregion
 //#region src/load-binding.d.ts
+/**
+ * The `Error` subclass passed to `'error'` event listeners and returned by
+ * `db.getLastError()` when RocksDB reports a background error (e.g. a write
+ * failing at the filesystem level). A real `Error` instance (`instanceof Error`
+ * and `instanceof BackgroundError` both hold) with the fields below. Only a
+ * hard-or-worse error (`writesDisabled`) stops writes; a soft error is
+ * auto-recoverable. When `writesDisabled` is `true` and the underlying condition
+ * has cleared, call {@link RocksDatabase.resume}. See HarperFast/rocksdb-js#730.
+ *
+ * The runtime constructor is defined natively and exported as
+ * {@link BackgroundError}; the same name is both a value (for `instanceof`) and
+ * this instance type.
+ *
+ * @example
+ * ```typescript
+ * db.on('error', (err: BackgroundError) => {
+ *   if (err.writesDisabled) console.error(`writes disabled: ${err.message}`);
+ * });
+ * ```
+ */
+export interface BackgroundError extends Error {
+  /** Always `'BackgroundError'`. */
+  name: string;
+  /** Discriminator for the error class; always `'background'` here. */
+  type: string;
+  /**
+   * The RocksDB `Status::Severity` as a number: 1 soft, 2 hard, 3 fatal,
+   * 4 unrecoverable.
+   */
+  severity: number;
+  /** Human-readable severity: `'soft'`, `'hard'`, `'fatal'`, or `'unrecoverable'`. */
+  severityName: string;
+  /**
+   * Whether RocksDB has disabled writes on the database in response to this
+   * error (severity hard or worse, i.e. `severity >= 2`). Only when `true` is
+   * {@link RocksDatabase.resume} warranted; a soft error auto-recovers and
+   * leaves writes enabled. Distinct from opening the database in read-only
+   * mode — this is RocksDB halting writes after a background failure.
+   */
+  writesDisabled: boolean;
+  /**
+   * The RocksDB `BackgroundErrorReason` as a number, present when the error
+   * originated from a reason-bearing callback (flush, compaction, etc.).
+   */
+  reason?: number;
+  /** Human-readable reason, e.g. `'flush'` or `'compaction'`. */
+  reasonName?: string;
+}
+/**
+ * The shape accepted by `db.setLastError(...)` to inject or reset a background
+ * error. `message` is required; the rest default/omit as with a real error.
+ * `type` defaults to `'background'`. Pass `null`/nothing to `setLastError` to
+ * clear instead of an object of this shape.
+ */
+type BackgroundErrorOptions = {
+  message: string;
+  severity?: number;
+  severityName?: string;
+  writesDisabled?: boolean;
+  reason?: number;
+  reasonName?: string;
+  type?: string;
+};
 type NativeTransactionOptions = {
   /**
    * Whether to disable snapshots.
@@ -1708,7 +1940,7 @@ type NativeTransaction = {
   putSync(key: Key, value: Buffer | Uint8Array, txnId?: number): void;
   removeSync(key: Key): void;
   setTimestamp(timestamp?: number): void;
-  useLog(name: string | number): TransactionLog;
+  useLog(name: string | number, jsDatabase: NativeDatabase): TransactionLog;
 };
 type LogBuffer = Buffer & {
   dataView: DataView;
@@ -1788,7 +2020,7 @@ type TransactionLogStats = {
     maxAgeThreshold: number;
   };
 };
-type TransactionLog = {
+export type TransactionLog = {
   new (db: NativeDatabase, name: string): TransactionLog;
   addEntry(data: Buffer | Uint8Array, txnId?: number): void;
   getLogFileSize(sequenceId?: number): number;
@@ -1829,7 +2061,7 @@ type NativeIteratorResult = number | {
   value?: Buffer;
 };
 declare class NativeIteratorCls {
-  constructor(context: StoreContext, flags: number, startKeyEnd: number, endKeyStart: number, endKeyEnd: number, options?: NativeIteratorAdvancedOptions);
+  constructor(context: StoreContext, flags: number, startKeyEnd: number, endKeyStart: number, endKeyEnd: number, options?: NativeIteratorAdvancedOptions, transactionId?: number);
   next(): NativeIteratorResult;
   return(): void;
   throw(err?: unknown): void;
@@ -1880,6 +2112,15 @@ type NativeDatabaseOptions = {
   noBlockCache?: boolean;
   parallelismThreads?: number;
   readOnly?: boolean;
+  /**
+   * A present, non-empty string opens the database via `DB::OpenAsSecondary`:
+   * a read-only follower of a live primary that advances with
+   * `catchUpWithPrimary()`. The value is the secondary instance's own
+   * workspace directory (created if missing), distinct from `path` (the
+   * primary's data directory) and exclusive to one secondary instance.
+   * Implies `readOnly: true` and forces `maxOpenFiles: -1`.
+   */
+  secondaryPath?: string;
   statsLevel?: (typeof stats.StatsLevel)[keyof typeof stats.StatsLevel];
   transactionLogMaxAgeThreshold?: number;
   transactionLogMaxSize?: number;
@@ -1915,6 +2156,47 @@ type PurgedLog = {
   path: string;
   entries: number;
 };
+type FlushOptions = {
+  /**
+   * Whether the flush may proceed even though it will stall writes for its duration.
+   *
+   * Maps to `rocksdb::FlushOptions::allow_write_stall`. RocksDB's default is `false`, which
+   * means the opposite of what the name suggests on first read: the flush **waits** until it
+   * can run without causing a stall. That wait has no timeout, so a database sitting in a stall
+   * condition — immutable-memtable backlog, L0 stop trigger, pending-compaction-bytes limit, an
+   * exhausted WriteBufferManager budget — blocks the caller for as long as the condition lasts.
+   * `flush()` runs on the libuv threadpool, so there the wait shows up as a promise that simply
+   * never settles while the event loop stays alive — and it parks that whole worker, not just
+   * the caller's promise: `UV_THREADPOOL_SIZE` defaults to 4, so a handful of concurrently
+   * stalled flushes can exhaust the pool and stall every unrelated `fs`/`dns`/`crypto` call and
+   * cold-cache `get()` in the process, not only this database's own operations. `flushSync()`
+   * takes the same wait on the JS thread, so it is the worse of the two here rather than the
+   * safer one: it freezes the event loop outright instead of parking a pool worker, and it holds
+   * the in-flight operation claim that `close()` waits on for the duration.
+   *
+   * Pass `true` when the flush is a durability gate the caller is blocked on and stalling
+   * writers is the acceptable cost of it completing — decide that up front, before issuing the
+   * call, since there is no way to cancel an in-flight `flush()` and turn `true` into an escape
+   * hatch after the fact. It is also not a free way out of an existing stall: forcing the
+   * memtable switch adds another L0 file to the level whose file count may be *causing* the
+   * stop trigger, so it can prolong the condition it is meant to clear. Weigh the cost
+   * database-wide, not per-caller: a flush covers **every column family** on the database, and
+   * the descriptor is process-global and shared across `worker_threads`, so the stall lands on
+   * every other column family and every other handle that opened the same path — not just the
+   * one you called. It also relocates the hang rather than removing it: a stalled `db->Write()`
+   * blocks the database's single `CommitWorker` thread, which dispatches every
+   * `Transaction.commit()` in order, so the stall queues up every commit behind it — including
+   * ones from callers that never touched flush — until the stall clears.
+   *
+   * Note this is a *different* knob from the `writeBufferManagerAllowStall` config, and their
+   * polarity is nearly opposite: that one decides whether the WriteBufferManager may stall
+   * writers at all, this one decides whether a manual flush is willing to cause a stall rather
+   * than wait one out.
+   *
+   * @default false
+   */
+  allowWriteStall?: boolean;
+};
 type NativeDatabase = {
   new (): NativeDatabase;
   addListener(event: string, callback: (...args: any[]) => void): void;
@@ -1923,6 +2205,8 @@ type NativeDatabase = {
     flushBeforeBackup?: boolean;
     transactionLogs?: boolean;
   }): void;
+  catchUpWithPrimary(resolve: ResolveCallback<void>, reject: RejectCallback): void;
+  catchUpWithPrimarySync(): void;
   clear(resolve: ResolveCallback<void>, reject: RejectCallback): void;
   clearSync(): void;
   close(): void;
@@ -1933,15 +2217,21 @@ type NativeDatabase = {
   destroy(): void;
   drop(resolve: ResolveCallback<void>, reject: RejectCallback): void;
   dropSync(): void;
-  flush(resolve: ResolveCallback<void>, reject: RejectCallback): void;
-  flushSync(): void;
+  flush(resolve: ResolveCallback<void>, reject: RejectCallback, options?: FlushOptions): void;
+  flushSync(options?: FlushOptions): void;
   notify(event: string | BufferWithDataView, args?: any[]): boolean;
   get(keyLengthOrKeyBuffer: number | Buffer, resolve: ResolveCallback<Buffer | number>, reject: RejectCallback, txnId?: number, expectedVersion?: number): number;
+  estimateCount(startKey?: Buffer, endKey?: Buffer): {
+    count: number;
+    confidence: number;
+  };
   getCompression(): {
     algorithm: string;
     level?: number;
   };
   getCount(options?: RangeOptions, txnId?: number): number;
+  getLastError(): BackgroundError | null;
+  setLastError(error?: BackgroundErrorOptions | null): void;
   getDBIntProperty(propertyName: string): number | undefined;
   getDBProperty(propertyName: string): string | undefined;
   getLogOptions(): {
@@ -1956,6 +2246,7 @@ type NativeDatabase = {
   getSync(keyLengthOrKeyBuffer: number | Buffer, flags: number, txnId?: number, expectedVersion?: number): Buffer;
   getUserSharedBuffer(key: BufferWithDataView, defaultBuffer: ArrayBuffer, callback?: UserSharedBufferCallback): ArrayBuffer;
   hasLock(key: BufferWithDataView): boolean;
+  identityPath: string | undefined;
   listeners(event: string | BufferWithDataView): number;
   listLogs(): string[];
   opened: boolean;
@@ -1971,12 +2262,13 @@ type NativeDatabase = {
   putSync(key: BufferWithDataView, value: any, txnId?: number): void;
   removeListener(event: string | BufferWithDataView, callback: () => void): boolean;
   removeSync(key: BufferWithDataView, txnId?: number): void;
+  resume(): void;
   setDefaultKeyBuffer(buffer: Buffer | Uint8Array | null): void;
   setDefaultValueBuffer(buffer: Buffer | Uint8Array | null): void;
   setIteratorState(buffer: Buffer | Uint8Array): void;
   tryLock(key: BufferWithDataView, callback?: () => void): boolean;
   unlock(key: BufferWithDataView): void;
-  useLog(name: string): TransactionLog;
+  useLog(name: string, jsDatabase?: NativeDatabase): TransactionLog;
   verifyVersion(keyLengthOrKeyBuffer: number | Buffer, version: number): boolean;
   withLock(key: BufferWithDataView, callback: () => void | Promise<void>): Promise<void>;
 };
@@ -2026,23 +2318,136 @@ type RocksDatabaseConfig = {
    */
   writeBufferManagerAllowStall?: boolean;
 };
+type RegistryStatusTransaction = {
+  /** The transaction id assigned by the database descriptor. */
+  id: number;
+  /** Milliseconds since the transaction handle was created. */
+  ageMs: number;
+};
 type RegistryStatusDB = {
   path: string;
   refCount: number;
   columnFamilies: string[];
   transactions: number;
+  /**
+   * One entry per live transaction handle. An `ageMs` beyond any plausible request lifetime,
+   * against a nonzero `rocksdb.num-snapshots`, identifies a handle holding back reclamation for
+   * its whole database.
+   */
+  transactionDetails: RegistryStatusTransaction[];
   closables: number;
   locks: number;
   userSharedBuffers: number;
   listenerCallbacks: number;
 };
 type RegistryStatus = RegistryStatusDB[];
-declare const constants: {
+/**
+ * The native `BackgroundError` constructor (a real `Error` subclass). Exported
+ * as both a value — for `err instanceof BackgroundError` — and, via declaration
+ * merging with the interface above, a type. Instances are produced by the
+ * `'error'` event and `db.getLastError()`; consumers rarely construct their own.
+ * The `details` param is required and typed to the instance fields so a bare
+ * `new BackgroundError()` (which would omit `severity` / `writesDisabled` / …)
+ * is a type error.
+ */
+export declare const BackgroundError: new (details: Pick<BackgroundError, "message" | "severity" | "severityName" | "writesDisabled" | "reason" | "reasonName"> & {
+  type?: string;
+}) => BackgroundError;
+/**
+ * Live state of the process-wide `WriteBufferManager` singleton — see
+ * {@link getWriteBufferManagerStats}.
+ */
+type WriteBufferManagerStats = {
+  /**
+   * Whether a manager has been created in this process. `bufferSize`,
+   * `memoryUsage`, `mutableMemoryUsage`, `stallActive`, `stallActiveMs`,
+   * `watchdogRunning` and `columnFamilies` are 0/false when not; `allowStall`
+   * and `costToCache` still reflect the configured setting, and
+   * `inventoryAvailable` is `true`.
+   */
+  enabled: boolean;
+  /** The manager's budget in bytes (`writeBufferManagerSize`, live). */
+  bufferSize: number;
+  /** Total memtable memory charged to the manager, in bytes. */
+  memoryUsage: number;
+  /** The share of `memoryUsage` held by active (mutable) memtables, in bytes. */
+  mutableMemoryUsage: number;
+  allowStall: boolean;
+  costToCache: boolean;
+  stallActive: boolean;
+  /**
+   * How long the current stall has been active, in milliseconds; 0 when not
+   * stalled. Sampled once a second by the stall watchdog, so it is 0 for the
+   * first second of a stall and whenever `watchdogRunning` is false.
+   */
+  stallActiveMs: number;
+  /**
+   * Whether the stall watchdog is running. It runs only while a manager exists
+   * with `writeBufferManagerAllowStall`, and only when
+   * `ROCKSDB_JS_WBM_STALL_WARN_MS` is not `0`.
+   */
+  watchdogRunning: boolean;
+  /**
+   * Live column families across every database attached to this manager. A
+   * dropped column family keeps charging the manager until its last handle
+   * closes, so it is counted until then.
+   */
+  columnFamilies: number;
+  /**
+   * `false` when the column-family inventory could not be collected because the
+   * database registry was locked — most plausibly by a close that is itself
+   * waiting out this stall. `columnFamilies` is then `0` and
+   * `maxWriteBufferSizeToMaintain` empty; every other field is still live.
+   */
+  inventoryAvailable: boolean;
+  /**
+   * Effective per-column-family `max_write_buffer_size_to_maintain` (as a decimal
+   * string) to the number of those column families holding it. Effective, not
+   * requested: RocksDB rewrites a requested `0` for a transaction database.
+   */
+  maxWriteBufferSizeToMaintain: Record<string, number>;
+};
+/**
+ * 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`);
+ * }
+ * ```
+ */
+export declare const getWriteBufferManagerStats: () => WriteBufferManagerStats;
+export declare const constants: {
   ALWAYS_CREATE_NEW_BUFFER_FLAG: number;
   NOT_IN_MEMORY_CACHE_FLAG: number;
   ONLY_IF_IN_MEMORY_CACHE_FLAG: number;
   POPULATE_VERSION_FLAG: number;
   FRESH_VERSION_FLAG: number;
+  /**
+   * Producer flag in a value's metadata word (4 big-endian bytes at offset 8, top byte `0x0E`,
+   * low 24 bits flags), declaring that this version does NOT uniquely identify the value —
+   * the producer has stored more than one distinct value under it.
+   *
+   * Set it and the VerificationTable stops treating version equality as evidence for this value:
+   * a read never answers `FRESH_VERSION_FLAG` for it and never publishes its version to a slot,
+   * so a consumer holding a differing cached copy at that version cannot have it confirmed.
+   * Clear it again on the next write that gives the value a version of its own.
+   *
+   * Read only from values in a column family that opted into the verification table. Do not call
+   * `populateVersion()` for a marked version: that explicit primitive never sees the value and
+   * cannot enforce this flag.
+   */
+  VERSION_NOT_UNIQUE_FLAG: number;
   /**
    * Sentinel value resolved (not rejected) by `commit()` when
    * `coordinatedRetry: true` and the transaction encountered an IsBusy
@@ -2058,6 +2463,7 @@ declare const constants: {
   ITERATOR_INCLUDE_VALUES_FLAG: number;
   ITERATOR_NEEDS_STABLE_VALUE_BUFFER_FLAG: number;
   ITERATOR_CONTEXT_IS_TRANSACTION_FLAG: number;
+  ITERATOR_HAS_TRANSACTION_ID_FLAG: number;
   ITERATOR_RESULT_DONE: number;
   ITERATOR_RESULT_FAST: number;
 };
@@ -2069,13 +2475,13 @@ declare const constants: {
  * always present. Use it to validate a `compression` option or to pick an
  * algorithm that is actually available at runtime.
  */
-declare const supportedCompression: readonly string[];
+export declare const supportedCompression: readonly string[];
 declare const NativeDatabase: NativeDatabase;
 declare const NativeTransaction: NativeTransaction;
-declare const TransactionLog: TransactionLog;
-declare const registryStatus: () => RegistryStatus;
-declare const shutdown: () => void;
-declare const currentThreadId: () => number;
+export declare const TransactionLog: TransactionLog;
+export declare const registryStatus: () => RegistryStatus;
+export declare const shutdown: () => void;
+export declare const currentThreadId: () => number;
 /**
  * Advises the kernel that the file-backed pages of every mapped transaction log
  * are cold (Linux MADV_COLD), so they are reclaimed first under memory pressure
@@ -2089,7 +2495,7 @@ declare const currentThreadId: () => number;
  *
  * @returns the number of maps cooled and total file-backed bytes advised.
  */
-declare const coolTransactionLogs: () => {
+export declare const coolTransactionLogs: () => {
   maps: number;
   bytes: number;
 };
@@ -2104,13 +2510,13 @@ declare const coolTransactionLogs: () => {
  * OS handle is owned entirely in native code (no fd crosses into JS), and the
  * kernel releases the lock when the handle closes, including on process death.
  */
-declare const tryFileLock: (file: string, shared?: boolean) => number;
+export declare const tryFileLock: (file: string, shared?: boolean) => number;
 /**
  * Releases a file lock acquired via `tryFileLock`. A no-op for
  * token `0` or an unknown token.
  */
-declare const fileLockRelease: (token: number) => void;
-declare const stats: {
+export declare const fileLockRelease: (token: number) => void;
+export declare const stats: {
   StatsLevel: {
     DisableAll: number;
     ExceptTickers: number;
@@ -2153,6 +2559,57 @@ interface BackupStreamOptions {
   transactionLogs?: boolean;
 }
 //#endregion
+//#region src/count-estimator.d.ts
+interface CountEstimatorOptions extends CountEstimateOptions {}
+/**
+ * Progressively refines a range key-count estimate as an iterator traverses
+ * the range. The estimate starts as the pure statistical estimate
+ * (`estimateCount`) and converges toward the exact count: the traversed
+ * portion is exact, and the statistical estimate of the untraversed remainder
+ * is calibrated by the observed ratio of actual-to-estimated entries over the
+ * portion already traversed.
+ *
+ * The estimator never touches the iterator itself — the caller reports
+ * progress with `advance(lastKey, count)` whenever it wants a checkpoint
+ * (e.g. once per page), then reads `estimate()`. The caller owns the
+ * progress contract: cursors must move monotonically through the range and
+ * each entry must be reported once (a re-reported page inflates the count
+ * undetectably). When traversal completes, call `finish()` so `estimate()`
+ * returns the exact total instead of adding a block-granular remainder.
+ *
+ * Each `estimate()` checkpoint queries RocksDB statistics for the two range
+ * segments (cost scales with the SSTs overlapping them, not with key count);
+ * results are memoized per checkpoint, so repeated reads between `advance()`
+ * calls are free.
+ */
+export declare class CountEstimator {
+  #private;
+  constructor(store: Store, options?: CountEstimatorOptions);
+  /**
+   * The number of entries reported traversed so far.
+   */
+  get traversed(): number;
+  /**
+   * Records that iteration has advanced through `count` more entries, ending
+   * at `lastKey`. Pass `count: 0` when an empty page has no last key.
+   */
+  advance(lastKey: Key | Uint8Array | undefined, count?: number): void;
+  /**
+   * Marks traversal of the range as complete: `estimate()` becomes the exact
+   * traversed count.
+   */
+  finish(): void;
+  /**
+   * Estimates the total number of entries in the full range: the exact
+   * traversed count plus a calibrated statistical estimate of the remainder.
+   * `confidence` is the exactness-weighted blend of the traversed portion
+   * (exact) and the remainder's statistical confidence, so it approaches 1
+   * as the exact portion grows (though a checkpoint can decrease when
+   * calibration makes a large correction), and is exactly 1 after `finish()`.
+   */
+  estimate(): CountEstimate;
+}
+//#endregion
 //#region src/database.d.ts
 type TransactionCallback<T> = (txn: Transaction, attempt: number) => T | PromiseLike<T>;
 interface RocksDatabaseOptions extends StoreOptions {
@@ -2192,7 +2649,7 @@ type RocksDBStats = StatsDefault | StatsAll;
  * db.close();
  * ```
  */
-declare class RocksDatabase extends DBI<DBITransactional> {
+export declare class RocksDatabase extends DBI<DBITransactional> {
   #private;
   constructor(pathOrStore: string | Store, options?: RocksDatabaseOptions);
   /**
@@ -2229,6 +2686,9 @@ declare class RocksDatabase extends DBI<DBITransactional> {
    * Compacts the entire key range of the database asynchronously.
    * This triggers manual compaction which removes tombstones and reclaims space.
    *
+   * On a read-only database this is a no-op: arguments are still validated, but
+   * the returned promise resolves without compacting rather than rejecting.
+   *
    * @example
    * ```typescript
    * const db = RocksDatabase.open('/path/to/database');
@@ -2299,6 +2759,9 @@ declare class RocksDatabase extends DBI<DBITransactional> {
    * Compacts the entire key range of the database synchronously.
    * This triggers manual compaction which removes tombstones and reclaims space.
    *
+   * On a read-only database this validates its arguments and then returns
+   * without compacting, rather than throwing.
+   *
    * @example
    * ```typescript
    * const db = RocksDatabase.open('/path/to/database');
@@ -2393,6 +2856,36 @@ declare class RocksDatabase extends DBI<DBITransactional> {
    * @returns `true` if there was at least one listener.
    */
   static notify(event: string, ...args: any[]): boolean;
+  /**
+   * 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(): Promise<void>;
+  /**
+   * Synchronous version of {@link catchUpWithPrimary}. The replay runs on the
+   * JS thread, so prefer the async form unless the caller is already blocking.
+   */
+  catchUpWithPrimarySync(): void;
   destroy(): void;
   drop(): Promise<void>;
   dropSync(): void;
@@ -2400,15 +2893,90 @@ declare class RocksDatabase extends DBI<DBITransactional> {
   /**
    * Flushes the underlying database by performing a commit or clearing any buffered operations.
    *
+   * On a read-only database this is a no-op: the options bag is still validated, but the
+   * returned promise resolves without flushing rather than rejecting.
+   *
+   * @param options - Flush options; see {@link FlushOptions.allowWriteStall} before relying on
+   * this resolving promptly under write pressure.
    * @return {void} Does not return a value.
    */
-  flush(): Promise<void>;
+  flush(options?: FlushOptions): Promise<void>;
   /**
    * Synchronously flushes the underlying database by performing a commit or clearing any buffered operations.
    *
+   * The default `allowWriteStall: false` wait is taken on the JS thread here, so it freezes the
+   * event loop rather than parking a libuv worker — a larger blast radius than {@link flush}, not
+   * a smaller one.
+   *
+   * On a read-only database this validates its options and then returns without flushing, rather
+   * than throwing.
+   *
+   * @param options - Flush options; see {@link FlushOptions.allowWriteStall}.
    * @return {void} Does not return a value.
    */
-  flushSync(): void;
+  flushSync(options?: FlushOptions): void;
+  /**
+   * Returns the most recent {@link BackgroundError} observed on this database, or
+   * `null` when none has occurred. The `'error'` event is the push counterpart;
+   * this is the pull equivalent for on-demand checks (e.g. a health probe) and
+   * for catching an error that fired after open but before a listener was
+   * attached. (A background error that occurs *during* the initial open is a
+   * narrow startup window not yet captured, addressed separately.)
+   *
+   * Purely historical — it is not cleared by a successful {@link RocksDatabase.resume}.
+   * When the returned error's `writesDisabled` is `true`, writes are stopped
+   * until recovery.
+   *
+   * @example
+   * ```typescript
+   * const err = db.getLastError();
+   * if (err?.writesDisabled) {
+   *   // ...free disk space...
+   *   db.resume();
+   * }
+   * ```
+   */
+  getLastError(): BackgroundError | null;
+  /**
+   * Sets or clears the last background error, mirroring the Win32
+   * `SetLastError`/`GetLastError` pair. Pass `null` (or no argument) to **reset**
+   * it — {@link RocksDatabase.getLastError} then returns `null` and no event
+   * fires; this is the intended way to clear the error after handling or
+   * recovering it (e.g. after {@link RocksDatabase.resume}). Pass an object to
+   * set it: it is stored and the `'error'` event fires with the reconstructed
+   * {@link BackgroundError}. `type` defaults to `'background'`.
+   *
+   * @example
+   * ```typescript
+   * db.resume();
+   * db.setLastError(null); // recovered — clear the historical error
+   * ```
+   */
+  setLastError(error?: BackgroundErrorOptions | null): void;
+  /**
+   * Attempts to recover the database from a background error by calling
+   * RocksDB's `DB::Resume()`. When a write fails at the filesystem level (e.g. a
+   * full disk), RocksDB stops accepting writes and this database emits an
+   * {@link BackgroundError} via the `'error'` event. Call `resume()` after the
+   * underlying condition has cleared — e.g. once disk space has been freed. On
+   * success writes are accepted again; on failure (the condition has not
+   * actually cleared) it throws and the database stays read-only. A no-op on a
+   * healthy database.
+   *
+   * Runs synchronously and may briefly block, since recovery can re-flush
+   * memtables.
+   *
+   * @example
+   * ```typescript
+   * db.on('error', (err) => {
+   *   if (err.writesDisabled) {
+   *     // ...free disk space...
+   *     db.resume();
+   *   }
+   * });
+   * ```
+   */
+  resume(): void;
   /**
    * Gets a RocksDB database property as an integer.
    *
@@ -2438,7 +3006,30 @@ declare class RocksDatabase extends DBI<DBITransactional> {
    */
   getDBProperty(propertyName: string): string | undefined;
   /**
-   * Retrieves the estimated number of keys in the database.
+   * 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(): boolean;
+  /**
+   * 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.
    *
    * @example
    * ```typescript
@@ -2448,6 +3039,54 @@ declare class RocksDatabase extends DBI<DBITransactional> {
    * ```
    */
   getEstimatedKeyCount(): number;
+  /**
+   * Estimates the number of keys in the database, or within a key range,
+   * returning `{ count, confidence }`. Unlike `getKeysCount()`, this never
+   * iterates: the estimate is derived from RocksDB statistics (memtable
+   * stats plus approximate SST sizes converted through the entry density of
+   * the SSTs overlapping the range), so its cost scales with the number of
+   * SSTs overlapping the range rather than the number of keys — though
+   * reading table properties for cold files can do I/O through the table
+   * cache, and a start-only range does the work of its complement below
+   * `start`. Accuracy improves with range size. Resolution is bounded by SST
+   * data-block granularity, so tiny ranges may over-report or report zero for
+   * present keys; low `confidence` is the signal. Recently deleted or
+   * overwritten entries may be counted until compaction. An inverted range
+   * (`start` >= `end`) returns `{ count: 0, confidence: 1 }`.
+   *
+   * `confidence` is a heuristic 0–1 trust indicator (1 only when exact) —
+   * see `CountEstimate`. Estimates always reflect committed state; writes
+   * pending in a transaction are not included.
+   *
+   * @example
+   * ```typescript
+   * const db = RocksDatabase.open('/path/to/database');
+   * const { count, confidence } = db.estimateCount({ start: 'a', end: 'z' });
+   * ```
+   */
+  estimateCount(options?: CountEstimateOptions): CountEstimate;
+  /**
+   * Creates a `CountEstimator` for progressively refining a range count
+   * estimate while iterating the range: report progress with
+   * `advance(lastKey, count)` (e.g. once per page of results) and
+   * `estimate()` returns the exact traversed count plus a calibrated
+   * estimate of the remainder, converging toward the exact total. Call
+   * `finish()` when traversal completes to make `estimate()` exact.
+   *
+   * @example
+   * ```typescript
+   * const estimator = db.createCountEstimator({ start: 'a', end: 'z' });
+   * let lastKey;
+   * let pageSize = 0;
+   * for (const { key } of db.getRange({ start: 'a', end: 'z', limit: 25 })) {
+   *   lastKey = key;
+   *   pageSize++;
+   * }
+   * estimator.advance(lastKey, pageSize);
+   * const { count, confidence } = estimator.estimate();
+   * ```
+   */
+  createCountEstimator(options?: CountEstimatorOptions): CountEstimator;
   /**
    * Returns the current timestamp as a monotonically increasing timestamp in
    * milliseconds represented as a decimal number.
@@ -2555,13 +3194,22 @@ declare class RocksDatabase extends DBI<DBITransactional> {
    */
   listLogs(): string[];
   /**
-   * The name of the database.
+   * The name of the database's column family.
    */
   get name(): string;
   /**
-   * 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(): boolean;
+  /**
+   * 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(): string | undefined;
   /**
    * Sugar method for opening a database.
    *
@@ -2679,6 +3327,47 @@ declare class RocksDatabase extends DBI<DBITransactional> {
    * ```
    */
   unlock(key: Key): void;
+  /**
+   * 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: string, options?: RocksDatabaseOptions): RocksDatabase;
   /**
    * Excecutes a function using a thread-safe lock to ensure mutual
    * exclusion.
@@ -2718,15 +3407,37 @@ interface TransactionLog$1 {
  * @param path - The path to the transaction log file.
  * @returns The transaction log.
  */
-declare function parseTransactionLog(path: string, options?: {
+export declare function parseTransactionLog(path: string, options?: {
   skipData?: boolean;
 }): TransactionLog$1;
 //#endregion
+//#region src/transaction-log-reader.d.ts
+/**
+ * Thrown when an entry's framing is broken. `resyncPosition` is the offset where valid framing
+ * resumes, when one was found: the frames after a mid-log break are intact and reachable, and
+ * only the broken span between `position` and `resyncPosition` is unreadable. It is `undefined`
+ * for a torn tail, where nothing follows the break.
+ *
+ * The iterator is left positioned at `resyncPosition` (or at end-of-log when there is none), so a
+ * caller that chooses to recover the entries past the break calls `next()` again.
+ */
+export declare class CorruptFrameError extends RangeError {
+  /** Sequence number of the log file the break is in. */
+  logId: number;
+  /** Offset of the broken frame. */
+  position: number;
+  /** Offset where valid framing resumes, or `undefined` when nothing valid follows. */
+  resyncPosition?: number;
+  /** Bytes between the break and the resume point that cannot be read. */
+  unreadableBytes: number;
+  constructor(message: string, logId: number, position: number, resyncPosition: number | undefined);
+}
+//#endregion
 //#region src/index.d.ts
-declare const versions: {
+export declare const versions: {
   rocksdb: string;
   "rocksdb-js": string;
 };
 //#endregion
-export { type BackupInfo, type BackupOptions, type BackupStreamOptions, type CompressionAlgorithm, type CompressionInfo, type CompressionOption, DBI, DBIterator, type GetStatsMethod, type IteratorOptions, type Key, type LogOptions, type RestoreMode, type RestoreOptions, type RocksDBStat, type RocksDBStats, RocksDatabase, type RocksDatabaseOptions, type StatsAll, type StatsAllExtras, type StatsBasics, type StatsCurated, type StatsCuratedExtras, type StatsDefault, type StatsHistogramData, type StatsValue, Store, type StoreContext, type StoreGetOptions, type StoreIteratorOptions, type StorePutOptions, type StoreRangeOptions, type StoreRemoveOptions, Transaction, type TransactionEntry, TransactionLog, type TransactionLogFileValidation, type TransactionLogPosition, type TransactionLogStats, type TransactionLogStoreValidation, type ValidateTransactionLogStoreOptions, backups, constants, coolTransactionLogs, currentThreadId, fileLockRelease, parseTransactionLog, registryStatus, shutdown, stats, supportedCompression, tryFileLock, validateTransactionLogStore, versions };
+export type { BackgroundErrorOptions, BackupInfo, BackupOptions, BackupStreamOptions, CompressionAlgorithm, CompressionInfo, CompressionOption, CountEstimate, CountEstimateOptions, CountEstimatorOptions, FlushOptions, GetStatsMethod, IteratorOptions, Key, LogOptions, RestoreMode, RestoreOptions, RocksDBStat, RocksDBStats, RocksDatabaseOptions, StatsAll, StatsAllExtras, StatsBasics, StatsCurated, StatsCuratedExtras, StatsDefault, StatsHistogramData, StatsValue, StoreContext, StoreGetOptions, StoreIteratorOptions, StorePutOptions, StoreRangeOptions, StoreRemoveOptions, TransactionEntry, TransactionLogFileValidation, TransactionLogPosition, TransactionLogStats, TransactionLogStoreValidation, ValidateTransactionLogStoreOptions, WriteBufferManagerStats };
 //# sourceMappingURL=index.d.mts.map