@harperfast/rocksdb-js 2.7.0 → 2.8.0

package/dist/index.d.mts

@@ -293,6 +293,23 @@ type CompressionInfo = {
   algorithm: CompressionAlgorithm;
   level?: number;
 };
+/**
+ * The informational-log settings currently in effect for a database, as
+ * returned by the `logOptions` getter. These are database-wide (`DBOptions`)
+ * settings, not per-column-family.
+ */
+type LogOptions = {
+  /**
+   * Per-file size cap (bytes) for informational log files (`LOG` /
+   * `LOG.old.*`).
+   */
+  maxLogFileSize: number;
+  /**
+   * Verbosity of informational logging: `0` (debug), `1` (info), `2` (warn),
+   * `3` (error), `4` (fatal), or `5` (header-only).
+   */
+  infoLogLevel: number;
+};
 /**
  * Options for the `Store` class.
  */
@@ -352,7 +369,9 @@ 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.
    */
   readOnly?: boolean;
   sharedStructuresKey?: symbol;
@@ -439,6 +458,11 @@ declare class Store {
    * Encoder specific option used to signal that the data should be frozen.
    */
   freezeData: boolean;
+  /**
+   * Verbosity of RocksDB's informational logging (`info_log_level`). Omit to
+   * leave RocksDB's own default.
+   */
+  infoLogLevel?: number;
   /**
    * Reusable buffer for encoding keys.
    */
@@ -451,6 +475,16 @@ declare class Store {
    * The maximum key size.
    */
   maxKeySize: number;
+  /**
+   * Per-file size cap (bytes) for informational log files (`LOG` /
+   * `LOG.old.*`). Bounds total informational-log footprint to roughly `5 *
+   * maxLogFileSize` (RocksDB retains up to 5 of these files). A value of `0`
+   * is RocksDB's "single unbounded log file" mode: it disables size-based
+   * rotation, so the log can grow without limit — set it only if you want that.
+   *
+   * @default 16777216 (16MB)
+   */
+  maxLogFileSize?: number;
   /**
    * The maximum number of table files RocksDB keeps open. `0` (the default)
    * derives a budget from the effective per-process open-file limit (an
@@ -470,13 +504,26 @@ declare class Store {
   /**
    * The bytes of recent memtable history to retain in memory for transaction
    * conflict checking. `-1` derives the value from
-   * `maxWriteBufferNumber * writeBufferSize`.
+   * `maxWriteBufferNumber * writeBufferSize`, except under a stalling
+   * `writeBufferManager`, where it derives `0`: retained history is charged to
+   * that manager and is only trimmable down to this target, so a target the
+   * budget cannot hold stalls writes permanently. Set a number to size it
+   * yourself against the budget and the column-family count.
    */
   maxWriteBufferSizeToMaintain?: number;
   /**
    * The total memtable budget in bytes across all column families. When the
-   * sum of memtables reaches this size, RocksDB flushes the largest one. `0`
-   * disables the global trigger so per-CF `writeBufferSize` drives flushing.
+   * sum of memtables reaches this size, RocksDB flushes the largest one.
+   * Defaults to `0`, which disables the global trigger so per-CF
+   * `writeBufferSize` drives flushing.
+   *
+   * Set this only if you know your column-family count: it is one budget split
+   * across all of them, so a value that suits a few families starves many. To
+   * bound total memtable memory instead, configure a WriteBufferManager.
+   *
+   * Database-wide, so it binds when the path is first opened in this process:
+   * a later open of the same path — including from another worker thread —
+   * keeps the first opener's value rather than overriding or rejecting it.
    */
   dbWriteBufferSize?: number;
   /**
@@ -505,7 +552,9 @@ 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;
   /**
@@ -532,8 +581,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;
   /**
@@ -641,6 +690,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;
@@ -885,6 +941,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
@@ -907,6 +978,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
@@ -1187,6 +1265,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;
@@ -1450,6 +1529,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;
@@ -1510,6 +1617,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;
@@ -1630,6 +1749,69 @@ interface ValidateTransactionLogStoreOptions {
 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}`);
+ * });
+ * ```
+ */
+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.
@@ -1663,7 +1845,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;
@@ -1811,6 +1993,22 @@ type NativeDatabaseOptions = {
   dbWriteBufferSize?: number;
   disableWAL?: boolean;
   enableStats?: boolean;
+  /**
+   * Verbosity of RocksDB's informational logging (`info_log_level`): `0`
+   * (debug), `1` (info), `2` (warn), `3` (error), `4` (fatal), or `5`
+   * (header-only). Omit to leave RocksDB's own default (`INFO_LEVEL` in a
+   * release build of the linked RocksDB library).
+   */
+  infoLogLevel?: number;
+  /**
+   * Per-file size cap (bytes) for informational log files (`LOG` /
+   * `LOG.old.*`, `max_log_file_size`). RocksDB retains up to 5 of these files
+   * (`keep_log_file_num`, not currently exposed as an option), so total
+   * informational-log footprint is bounded at roughly `5 * maxLogFileSize`.
+   *
+   * @default 16777216 (16MB)
+   */
+  maxLogFileSize?: number;
   maxOpenFiles?: number;
   maxWriteBufferNumber?: number;
   maxWriteBufferSizeToMaintain?: number;
@@ -1854,6 +2052,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;
@@ -1872,17 +2111,27 @@ 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(): {
+    maxLogFileSize: number;
+    infoLogLevel: number;
+  };
   getMonotonicTimestamp(): number;
   getOldestSnapshotTimestamp(): number;
   getStat(statName: string): number | StatsHistogramData;
@@ -1906,12 +2155,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>;
 };
@@ -1961,23 +2211,62 @@ 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[];
+/**
+ * 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.
+ */
+declare const BackgroundError: new (details: Pick<BackgroundError, "message" | "severity" | "severityName" | "writesDisabled" | "reason" | "reasonName"> & {
+  type?: string;
+}) => BackgroundError;
 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
@@ -2088,6 +2377,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.
+ */
+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 {
@@ -2164,6 +2504,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');
@@ -2234,6 +2577,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');
@@ -2259,6 +2605,22 @@ declare class RocksDatabase extends DBI<DBITransactional> {
    * ```
    */
   get compression(): CompressionInfo;
+  /**
+   * The informational-log settings currently in effect for this database,
+   * read live from RocksDB, as `{ maxLogFileSize, infoLogLevel }`. These are
+   * database-wide settings (not per-column-family): `maxLogFileSize` bounds
+   * each retained `LOG` / `LOG.old.*` file's size (defaults to 16MB, so with
+   * RocksDB's `keep_log_file_num = 5` the total footprint is bounded at
+   * roughly 80MB); `infoLogLevel` is the logging verbosity. The database must
+   * be open.
+   *
+   * @example
+   * ```typescript
+   * const db = RocksDatabase.open('/path/to/db', { maxLogFileSize: 4 * 1024 * 1024 });
+   * db.logOptions; // { maxLogFileSize: 4194304, infoLogLevel: 1 }
+   * ```
+   */
+  get logOptions(): LogOptions;
   /**
    * Set global database settings.
    *
@@ -2319,15 +2681,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.
    *
@@ -2357,7 +2794,9 @@ declare class RocksDatabase extends DBI<DBITransactional> {
    */
   getDBProperty(propertyName: string): string | undefined;
   /**
-   * Retrieves the estimated number of keys in the database.
+   * 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
@@ -2367,6 +2806,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.
@@ -2641,11 +3128,33 @@ 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.
+ */
+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: {
   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 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 { BackgroundError, type BackgroundErrorOptions, type BackupInfo, type BackupOptions, type BackupStreamOptions, type CompressionAlgorithm, type CompressionInfo, type CompressionOption, CorruptFrameError, type CountEstimate, type CountEstimateOptions, CountEstimator, type CountEstimatorOptions, DBI, DBIterator, type FlushOptions, 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 };
 //# sourceMappingURL=index.d.mts.map