@harperfast/rocksdb-js 2.1.0 → 2.2.0

package/dist/index.d.mts

@@ -1,5 +1,140 @@
 import { ExtendedIterable } from "@harperfast/extended-iterable";
 
+//#region src/backup.d.ts
+/**
+* Options for creating a backup via `db.backup()`.
+*
+* Backups are whole-database: every column family, the manifest, and (unless
+* `backupLogFiles` is disabled) the write-ahead log are captured. A backup is
+* not scoped to an individual `Store`.
+*/
+interface BackupOptions {
+  /**
+  * Flush the memtable before backing up. Defaults to `true` when the database
+  * was opened with `disableWAL` (otherwise unflushed data would be lost from
+  * the backup), and `false` otherwise.
+  */
+  flushBeforeBackup?: boolean;
+  /**
+  * Arbitrary application metadata stored with the backup and returned by
+  * `backups.list()`.
+  */
+  metadata?: string;
+  /**
+  * Share table/blob files between backups in the same directory to enable
+  * incremental backups. Defaults to `true`.
+  */
+  shareTableFiles?: boolean;
+  /**
+  * Distinguish shared files by checksum to avoid collisions across databases.
+  * Defaults to `true`. Only relevant when `shareTableFiles` is enabled.
+  */
+  shareFilesWithChecksum?: boolean;
+  /**
+  * Include write-ahead log files in the backup. Defaults to `true`.
+  */
+  backupLogFiles?: boolean;
+  /**
+  * `fsync` backup files for crash consistency. Defaults to `true`.
+  */
+  sync?: boolean;
+  /**
+  * Number of background threads used to copy files. Defaults to `1`.
+  */
+  maxBackgroundOperations?: number;
+}
+/**
+* The level of incremental restore to perform.
+*
+* - `purgeAllFiles` (default): purge the destination directory and restore all
+*   files from the backup. Destructive but always correct.
+* - `keepLatestDbSessionIdFiles`: efficiently restore a healthy database,
+*   reusing existing files that match the backup.
+* - `verifyChecksum`: reuse existing destination files whose checksums match the
+*   backup, replacing only mismatched/corrupt files.
+*/
+type RestoreMode = "purgeAllFiles" | "keepLatestDbSessionIdFiles" | "verifyChecksum";
+/**
+* Options for restoring a backup via `backups.restore()`.
+*/
+interface RestoreOptions {
+  /**
+  * The backup id to restore. Defaults to the latest non-corrupt backup.
+  */
+  backupId?: number;
+  /**
+  * Directory to restore write-ahead log files into. Defaults to the database
+  * directory.
+  */
+  walDir?: string;
+  /**
+  * Keep existing log files in `walDir` rather than overwriting them. Defaults
+  * to `false`.
+  */
+  keepLogFiles?: boolean;
+  /**
+  * The restore strategy. Defaults to `purgeAllFiles`, which is destructive.
+  */
+  mode?: RestoreMode;
+}
+/**
+* Information about a single backup, as returned by `backups.list()`.
+*/
+interface BackupInfo {
+  /** The backup id (monotonically increasing integer). */
+  backupId: number;
+  /** Creation time in seconds since the epoch. */
+  timestamp: number;
+  /** Total size in bytes of the backed-up file payloads. */
+  size: number;
+  /** Number of files in the backup (some may be shared with other backups). */
+  numberFiles: number;
+  /** Application metadata supplied when the backup was created. */
+  appMetadata: string;
+}
+/**
+* Backup management operations that act on a backup directory and do not
+* require an open database. To create a backup, use the `db.backup()` instance
+* method instead (it needs a live database for a consistent snapshot).
+*
+* @example
+* ```typescript
+* import { backups } from '@harperfast/rocksdb-js';
+*
+* const id = await db.backup('/path/to/backups');
+* db.close();
+* await backups.restore('/path/to/backups', '/path/to/restored-db');
+* ```
+*/
+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
+  * not point at a live database.
+  */
+  restore(backupDir: string, dbDir: string, options?: RestoreOptions): Promise<void>;
+  /**
+  * Lists the non-corrupt backups in a backup directory, ordered by id.
+  */
+  list(backupDir: string): Promise<BackupInfo[]>;
+  /**
+  * Deletes a specific backup. Shared files are reference-counted and only
+  * removed once no remaining backup references them.
+  */
+  delete(backupDir: string, backupId: number): Promise<void>;
+  /**
+  * Deletes all but the newest `keepCount` backups.
+  */
+  purge(backupDir: string, keepCount: number): Promise<void>;
+  /**
+  * Verifies a backup's file sizes, and optionally their checksums (which
+  * requires reading all backed-up data).
+  */
+  verify(backupDir: string, backupId: number, options?: {
+    verifyWithChecksum?: boolean;
+  }): Promise<void>;
+};
+//#endregion
 //#region src/encoding.d.ts
 type Key = Key[] | string | symbol | number | boolean | Uint8Array | Buffer | null;
 interface BufferWithDataView extends Buffer {
@@ -416,7 +551,7 @@ declare class DBIterator<T> implements Iterator<DBIteratorValue<T>> {
   #private;
   iterator: InstanceType<typeof NativeIteratorCls>;
   store: Store;
-  constructor(iterator: InstanceType<typeof NativeIteratorCls>, store: Store, includeValues: boolean);
+  constructor(iterator: InstanceType<typeof NativeIteratorCls>, store: Store, includeValues: boolean, limit?: number);
   [Symbol.iterator](): Iterator<DBIteratorValue<T>>;
   next(): IteratorResult<DBIteratorValue<T>>;
   return(value?: any): IteratorResult<DBIteratorValue<T>, any>;
@@ -626,6 +761,10 @@ declare class Store {
   */
   transactionLogsPath?: string;
   /**
+  * Whether this store's column family participates in the VerificationTable.
+  */
+  verificationTable?: boolean;
+  /**
   * The per-column-family memtable size in bytes at which the memtable is
   * sealed and flushed.
   */
@@ -657,6 +796,17 @@ declare class Store {
   */
   compact(options?: CompactOptions): Promise<void>;
   /**
+  * Creates a backup of the entire database (all column families) into the
+  * given directory and resolves with the new backup id. Parent directories
+  * are created as needed. See `backups` for restore and management.
+  *
+  * @example
+  * ```typescript
+  * const id = await db.backup('/path/to/backups');
+  * ```
+  */
+  backup(backupDir: string, options?: BackupOptions): Promise<number>;
+  /**
   * Compacts the entire key range of the database synchronously.
   * This triggers manual compaction which removes tombstones and reclaims space.
   *
@@ -695,7 +845,7 @@ declare class Store {
   * @returns The encoded value.
   */
   encodeValue(value: any): BufferWithDataView | Uint8Array;
-  get(context: StoreContext, key: Key, alwaysCreateNewBuffer?: boolean, txnId?: number): any | undefined;
+  get(context: StoreContext, key: Key, alwaysCreateNewBuffer?: boolean, options?: StoreGetOptions): any | undefined;
   getCount(context: StoreContext, options?: StoreRangeOptions): number;
   getKeys(context: StoreContext, options?: StoreIteratorOptions): any | undefined;
   getKeysCount(context: StoreContext, options?: StoreRangeOptions): number;
@@ -772,6 +922,19 @@ declare class Store {
   */
   useLog(context: StoreContext, name: string | number): TransactionLog;
   /**
+  * Checks the process-global verification table for a fresh version match
+  * on `key`. Returns `true` when the table currently records `version` for
+  * this database+column-family. Provides a fast cache-freshness check
+  * before falling back to a full read.
+  */
+  verifyVersion(key: Key, version: number): boolean;
+  /**
+  * Seeds the verification-table slot for `key` with `version`. Has no
+  * effect if the slot is currently lock-tagged or the table is disabled.
+  * Useful after a full read where the caller already knows the version.
+  */
+  populateVersion(key: Key, version: number): void;
+  /**
   * Acquires a lock on the given key and calls the callback.
   *
   * @param key - The key to lock.
@@ -781,6 +944,21 @@ declare class Store {
   withLock(key: Key, callback: () => void | Promise<void>): Promise<void>;
 }
 interface GetOptions {
+  /**
+  * When set, the native layer checks the verification table before reading.
+  * If the slot holds this version, returns `FRESH_VERSION_FLAG` immediately
+  * (the cached value is still valid). After a DB read, also seeds the slot
+  * with the version extracted from the value.
+  */
+  expectedVersion?: number;
+  /**
+  * When `true`, after a DB read the native layer automatically seeds the
+  * verification-table slot with the version extracted from the value.
+  * Eliminates the need for a separate `populateVersion` call on cold reads.
+  *
+  * @default false
+  */
+  populateVersion?: boolean;
   /**
   * Whether to skip decoding the value.
   *
@@ -803,14 +981,25 @@ type NativeTransactionOptions = {
   * @default false
   */
   disableSnapshot?: boolean;
+  /**
+  * When `true`, an `IsBusy` conflict at commit time is resolved with the
+  * `RETRY_NOW` sentinel value instead of being rejected. The native layer
+  * may park on a VT slot before resolving, so the JS retry fires only after
+  * the conflicting transaction has committed and released its write intent.
+  *
+  * Use together with `verificationTable: true` on the database.
+  *
+  * @default false
+  */
+  coordinatedRetry?: boolean;
 };
 type NativeTransaction = {
   id: number;
   new (context: NativeDatabase, options?: NativeTransactionOptions): NativeTransaction;
   abort(): void;
-  commit(resolve: () => void, reject: (err: Error) => void): void;
+  commit(resolve: (retrySignal?: number) => void, reject: (err: Error) => void): void;
   commitSync(): void;
-  get(keyLengthOrKeyBuffer: number | Buffer, resolve: (value: Buffer) => void, reject: (err: Error) => void): number;
+  get(keyLengthOrKeyBuffer: number | Buffer, resolve: (value: Buffer | number) => void, reject: (err: Error) => void, txnIdIgnored?: number, expectedVersion?: number): number;
   getCount(options?: RangeOptions): number;
   getSync(keyLengthOrKeyBuffer: number | Buffer): Buffer | number | undefined;
   getTimestamp(): number;
@@ -960,6 +1149,13 @@ type NativeDatabaseOptions = {
   transactionLogMaxSize?: number;
   transactionLogRetentionMs?: number;
   transactionLogsPath?: string;
+  /**
+  * When true, transaction writes to this column family invalidate the
+  * VerificationTable slot for each written key at write time (not at
+  * commit time). Enable only for column families whose records are
+  * cached (e.g. the primary CF of a table). Default: false.
+  */
+  verificationTable?: boolean;
   writeBufferSize?: number;
 };
 type ResolveCallback<T> = (value: T) => void;
@@ -968,11 +1164,25 @@ type UserSharedBufferCallback = () => void;
 type PurgeLogsOptions = {
   before?: number;
   destroy?: boolean;
+  /**
+  * When `true`, count the entries in each purged log file (extra work) and
+  * return `PurgedLog[]` instead of the default `string[]` of file paths.
+  */
+  includeEntryCounts?: boolean;
   name?: string;
 };
+/**
+* A purged transaction log file and the number of entries it held, returned by
+* `purgeLogs()` when `includeEntryCounts` is `true`.
+*/
+type PurgedLog = {
+  path: string;
+  entries: number;
+};
 type NativeDatabase = {
   new (): NativeDatabase;
   addListener(event: string, callback: (...args: any[]) => void): void;
+  backup(resolve: ResolveCallback<number>, reject: RejectCallback, backupDir: string, options?: BackupOptions): void;
   clear(resolve: ResolveCallback<void>, reject: RejectCallback): void;
   clearSync(): void;
   close(): void;
@@ -985,7 +1195,7 @@ type NativeDatabase = {
   flush(resolve: ResolveCallback<void>, reject: RejectCallback): void;
   flushSync(): void;
   notify(event: string | BufferWithDataView, args?: any[]): boolean;
-  get(keyLengthOrKeyBuffer: number | Buffer, resolve: ResolveCallback<Buffer>, reject: RejectCallback, txnId?: number): number;
+  get(keyLengthOrKeyBuffer: number | Buffer, resolve: ResolveCallback<Buffer | number>, reject: RejectCallback, txnId?: number, expectedVersion?: number): number;
   getCount(options?: RangeOptions, txnId?: number): number;
   getDBIntProperty(propertyName: string): number | undefined;
   getDBProperty(propertyName: string): string | undefined;
@@ -994,14 +1204,21 @@ type NativeDatabase = {
   getStat(statName: string): number | StatsHistogramData;
   getStats(all?: false): StatsDefault;
   getStats(all: true): StatsAll;
-  getSync(keyLengthOrKeyBuffer: number | Buffer, flags: number, txnId?: number): Buffer;
+  getSync(keyLengthOrKeyBuffer: number | Buffer, flags: number, txnId?: number, expectedVersion?: number): Buffer;
   getUserSharedBuffer(key: BufferWithDataView, defaultBuffer: ArrayBuffer, callback?: UserSharedBufferCallback): ArrayBuffer;
   hasLock(key: BufferWithDataView): boolean;
   listeners(event: string | BufferWithDataView): number;
   listLogs(): string[];
   opened: boolean;
   open(path: string, options?: NativeDatabaseOptions): void;
-  purgeLogs(options?: PurgeLogsOptions): string[];
+  populateVersion(keyLengthOrKeyBuffer: number | Buffer, version: number): void;
+  purgeLogs(options: PurgeLogsOptions & {
+    includeEntryCounts: true;
+  }): PurgedLog[];
+  purgeLogs(options?: PurgeLogsOptions & {
+    includeEntryCounts?: false;
+  }): string[];
+  purgeLogs(options?: PurgeLogsOptions): string[] | PurgedLog[];
   putSync(key: BufferWithDataView, value: any, txnId?: number): void;
   removeListener(event: string | BufferWithDataView, callback: () => void): boolean;
   removeSync(key: BufferWithDataView, txnId?: number): void;
@@ -1011,10 +1228,19 @@ type NativeDatabase = {
   tryLock(key: BufferWithDataView, callback?: () => void): boolean;
   unlock(key: BufferWithDataView): void;
   useLog(name: string): TransactionLog;
+  verifyVersion(keyLengthOrKeyBuffer: number | Buffer, version: number): boolean;
   withLock(key: BufferWithDataView, callback: () => void | Promise<void>): Promise<void>;
 };
 type RocksDatabaseConfig = {
   blockCacheSize?: number;
+  /**
+  * Number of slots in the process-global verification table. Each slot is
+  * 8 bytes; the default of 128K slots is 1 MB. Set to 0 to disable.
+  *
+  * Must be configured before the first database is opened. Once the table
+  * is materialized, attempts to change this value will throw.
+  */
+  verificationTableEntries?: number;
   compactOnClose?: boolean;
   /**
   * Total memtable memory limit (bytes) shared across every database opened
@@ -1066,6 +1292,14 @@ 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;
+  /**
+  * Sentinel value resolved (not rejected) by `commit()` when
+  * `coordinatedRetry: true` and the transaction encountered an IsBusy
+  * conflict. JS should retry the transaction body immediately.
+  */
+  RETRY_NOW_VALUE: number;
   TRANSACTION_LOG_TOKEN: number;
   TRANSACTION_LOG_ENTRY_HEADER_SIZE: number;
   TRANSACTION_LOG_FILE_HEADER_SIZE: number;
@@ -1084,6 +1318,23 @@ declare const TransactionLog: TransactionLog;
 declare const registryStatus: () => RegistryStatus;
 declare const shutdown: () => void;
 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
+* without being freed — useful during replication catch-up, where a full read of
+* the logs would otherwise inflate the container's reclaimable cache toward its
+* cgroup limit. No-op on kernels < 5.4, macOS, and Windows.
+*
+* The transaction log registry is a process-global singleton shared across all
+* worker threads, so a single call cools every worker's maps. Call it on an
+* interval from one thread (e.g. an `unref()`ed timer on the main thread).
+*
+* @returns the number of maps cooled and total file-backed bytes advised.
+*/
+declare const coolTransactionLogs: () => {
+  maps: number;
+  bytes: number;
+};
 declare const stats: {
   StatsLevel: {
     DisableAll: number;
@@ -1098,6 +1349,13 @@ declare const stats: {
 //#endregion
 //#region src/transaction.d.ts
 /**
+* Sentinel value returned by `commit()` when `coordinatedRetry: true` and the
+* transaction encountered an IsBusy conflict. The native layer parks on VT
+* slots and resolves only after the conflicting transaction releases its write
+* intent, so callers should retry immediately without any backoff delay.
+*/
+declare const RETRY_NOW: number;
+/**
 * Provides transaction level operations to a transaction callback.
 */
 declare class Transaction extends DBI {
@@ -1115,8 +1373,11 @@ declare class Transaction extends DBI {
   abort(): void;
   /**
   * Commit the transaction.
+  *
+  * Returns `RETRY_NOW` when `coordinatedRetry: true` and an IsBusy conflict
+  * was detected. The caller should retry the transaction body immediately.
   */
-  commit(): Promise<void>;
+  commit(): Promise<typeof RETRY_NOW | void>;
   /**
   * Commit the transaction synchronously.
   */
@@ -1217,6 +1478,12 @@ interface RangeOptions extends RocksDBOptions {
   start?: Key | Uint8Array;
 }
 interface IteratorOptions extends RangeOptions {
+  /**
+  * The maximum number of entries to yield. When set, iteration stops after
+  * `limit` entries regardless of the range bounds. Values <= 0 yield nothing.
+  * Unset means no limit.
+  */
+  limit?: number;
   /**
   * A specific key to match which may result in zero, one, or many values.
   */
@@ -1283,11 +1550,11 @@ declare class DBI<T extends DBITransactional | unknown = unknown> {
   *
   * Note: Used by HDBreplication.
   */
-  getBinary(key: Key, options?: GetOptions & T): MaybePromise<Buffer | undefined>;
+  getBinary(key: Key, options?: GetOptions & T): MaybePromise<Buffer | number | undefined>;
   /**
   * Synchronously retrieves the binary data for the given key.
   */
-  getBinarySync(key: Key, options?: GetOptions & T): Buffer | undefined;
+  getBinarySync(key: Key, options?: GetOptions & T): Buffer | number | undefined;
   /**
   * Retrieves the binary data for the given key using a preallocated,
   * reusable buffer. Data in the buffer is only valid until the next get
@@ -1298,13 +1565,13 @@ declare class DBI<T extends DBITransactional | unknown = unknown> {
   * - `.byteLength` is set to the size of the full allocated memory area for
   *   the buffer (usually much larger).
   */
-  getBinaryFast(key: Key, options?: GetOptions & T): MaybePromise<Buffer | undefined>;
+  getBinaryFast(key: Key, options?: GetOptions & T): MaybePromise<Buffer | number | undefined>;
   /**
   * Synchronously retrieves the binary data for the given key using a
   * preallocated, reusable buffer. Data in the buffer is only valid until the
   * next get operation (including cursor operations).
   */
-  getBinaryFastSync(key: Key, options?: GetOptions & T): Buffer | undefined;
+  getBinaryFastSync(key: Key, options?: GetOptions & T): Buffer | number | undefined;
   /**
   * Retrieves all keys within a range.
   */
@@ -1538,6 +1805,24 @@ declare class RocksDatabase extends DBI<DBITransactional> {
   */
   compact(options?: CompactOptions): Promise<void>;
   /**
+  * Creates a backup of the entire database (all column families) into the
+  * given directory, creating parent directories as needed, and resolves with
+  * the new backup id. Use the `backups` namespace to restore, list, delete,
+  * purge, or verify backups.
+  *
+  * When the database was opened with `disableWAL`, the memtable is flushed
+  * before the backup by default so unflushed data is not lost.
+  *
+  * @example
+  * ```typescript
+  * import { backups } from '@harperfast/rocksdb-js';
+  *
+  * const db = RocksDatabase.open('/path/to/database');
+  * const id = await db.backup('/path/to/backups');
+  * ```
+  */
+  backup(backupDir: string, options?: BackupOptions): Promise<number>;
+  /**
   * Compacts the entire key range of the database synchronously.
   * This triggers manual compaction which removes tombstones and reclaims space.
   *
@@ -1735,6 +2020,26 @@ declare class RocksDatabase extends DBI<DBITransactional> {
   hasLock(key: Key): boolean;
   ifNoExists(_key: Key): Promise<void>;
   /**
+  * Checks the process-global verification table for a fresh version match
+  * on `key`. Returns `true` when the table currently records `version`. Use
+  * this as a fast cache-freshness check before falling back to a full read:
+  *
+  * ```typescript
+  * if (db.verifyVersion(key, cachedEntry.version)) {
+  *   return cachedEntry.value;
+  * }
+  * const value = db.getSync(key);
+  * db.populateVersion(key, extractVersion(value));
+  * ```
+  */
+  verifyVersion(key: Key, version: number): boolean;
+  /**
+  * Seeds the verification-table slot for `key` with `version`. Has no
+  * effect if the slot is currently lock-tagged or if the verification
+  * table is disabled.
+  */
+  populateVersion(key: Key, version: number): void;
+  /**
   * Returns whether the database is open.
   *
   * @returns `true` if the database is open, `false` otherwise.
@@ -1786,8 +2091,18 @@ declare class RocksDatabase extends DBI<DBITransactional> {
   get path(): string;
   /**
   * Purges transaction logs.
+  *
+  * By default returns the paths of the deleted log files. Pass
+  * `includeEntryCounts: true` to instead return, for each deleted file, its
+  * path and the number of entries it held (`{ path, entries }`).
   */
-  purgeLogs(options?: PurgeLogsOptions): string[];
+  purgeLogs(options: PurgeLogsOptions & {
+    includeEntryCounts: true;
+  }): PurgedLog[];
+  purgeLogs(options?: PurgeLogsOptions & {
+    includeEntryCounts?: false;
+  }): string[];
+  purgeLogs(options?: PurgeLogsOptions): string[] | PurgedLog[];
   /**
   * The status of the database.
   */
@@ -1910,5 +2225,5 @@ declare const versions: {
   "rocksdb-js": string;
 };
 //#endregion
-export { DBI, DBIterator, type GetStatsMethod, type IteratorOptions, type Key, 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 TransactionLogPosition, type TransactionLogStats, constants, currentThreadId, parseTransactionLog, registryStatus, shutdown, stats, versions };
+export { type BackupInfo, type BackupOptions, 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 TransactionLogPosition, type TransactionLogStats, backups, constants, coolTransactionLogs, currentThreadId, parseTransactionLog, registryStatus, shutdown, stats, versions };
 //# sourceMappingURL=index.d.mts.map