@harperfast/rocksdb-js 2.8.0 → 2.9.1

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;
@@ -372,8 +372,55 @@ interface StoreOptions extends Omit<NativeDatabaseOptions, "compression" | "comp
    * 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
@@ -407,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.
@@ -504,10 +551,16 @@ declare class Store {
   /**
    * The bytes of recent memtable history to retain in memory for transaction
    * conflict checking. `-1` derives the value from
-   * `maxWriteBufferNumber * writeBufferSize`, except under a stalling
-   * `writeBufferManager`, where it derives `0`: retained history is charged to
-   * that manager and is only trimmable down to this target, so a target the
-   * budget cannot hold stalls writes permanently. Set a number to size it
+   * `maxWriteBufferNumber * writeBufferSize`, except when a
+   * `writeBufferManager` is configured, where it derives `1`: retained history
+   * is charged to that manager and is only trimmable down to this target, so a
+   * target the budget cannot hold is memory the manager never reclaims, and
+   * stalls writes permanently when `writeBufferManagerAllowStall` is on. Any
+   * configured manager, not only a stalling one — that flag is mutable at
+   * runtime while this value is fixed when the family is created. `1`, not `0`, because
+   * RocksDB's transaction wrappers rewrite a `0` target to the derived value —
+   * so `0` asks for the largest history rather than none, and an explicit `0`
+   * is normalized to `1` for that reason. Set a positive number to size it
    * yourself against the budget and the column-family count.
    */
   maxWriteBufferSizeToMaintain?: number;
@@ -544,6 +597,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`,
@@ -557,6 +615,13 @@ declare class Store {
    * 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.
@@ -616,6 +681,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.
    */
@@ -835,7 +918,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.
@@ -869,10 +952,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;
   /**
@@ -880,9 +965,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;
 }
@@ -1024,7 +1114,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()`.
    */
@@ -1230,7 +1320,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;
@@ -1282,6 +1378,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;
@@ -1746,7 +1847,7 @@ 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
 /**
@@ -1769,7 +1870,7 @@ declare function validateTransactionLogStore(path: string, options?: ValidateTra
  * });
  * ```
  */
-interface BackgroundError extends Error {
+export interface BackgroundError extends Error {
   /** Always `'BackgroundError'`. */
   name: string;
   /** Discriminator for the error class; always `'background'` here. */
@@ -1925,7 +2026,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;
@@ -1966,7 +2067,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;
@@ -2017,6 +2118,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;
@@ -2101,6 +2211,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;
@@ -2140,6 +2252,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;
@@ -2243,10 +2356,84 @@ type RegistryStatus = RegistryStatusDB[];
  * `new BackgroundError()` (which would omit `severity` / `writesDisabled` / …)
  * is a type error.
  */
-declare const BackgroundError: new (details: Pick<BackgroundError, "message" | "severity" | "severityName" | "writesDisabled" | "reason" | "reasonName"> & {
+export declare const BackgroundError: new (details: Pick<BackgroundError, "message" | "severity" | "severityName" | "writesDisabled" | "reason" | "reasonName"> & {
   type?: string;
 }) => BackgroundError;
-declare const constants: {
+/**
+ * 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;
@@ -2282,6 +2469,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;
 };
@@ -2293,13 +2481,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
@@ -2313,7 +2501,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;
 };
@@ -2328,13 +2516,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;
@@ -2400,7 +2588,7 @@ interface CountEstimatorOptions extends CountEstimateOptions {}
  * results are memoized per checkpoint, so repeated reads between `advance()`
  * calls are free.
  */
-declare class CountEstimator {
+export declare class CountEstimator {
   #private;
   constructor(store: Store, options?: CountEstimatorOptions);
   /**
@@ -2467,7 +2655,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);
   /**
@@ -2674,6 +2862,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;
@@ -2793,6 +3011,27 @@ declare class RocksDatabase extends DBI<DBITransactional> {
    * ```
    */
   getDBProperty(propertyName: string): string | undefined;
+  /**
+   * 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
@@ -2961,13 +3200,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.
    *
@@ -3085,6 +3333,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.
@@ -3124,7 +3413,7 @@ 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
@@ -3138,7 +3427,7 @@ declare function parseTransactionLog(path: string, options?: {
  * 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 {
+export declare class CorruptFrameError extends RangeError {
   /** Sequence number of the log file the break is in. */
   logId: number;
   /** Offset of the broken frame. */
@@ -3151,10 +3440,10 @@ declare class CorruptFrameError extends RangeError {
 }
 //#endregion
 //#region src/index.d.ts
-declare const versions: {
+export declare const versions: {
   rocksdb: string;
   "rocksdb-js": string;
 };
 //#endregion
-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 };
+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