@harperfast/rocksdb-js 2.1.0 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -1,5 +1,140 @@
1
1
  import { ExtendedIterable } from "@harperfast/extended-iterable";
2
2
 
3
+ //#region src/backup.d.ts
4
+ /**
5
+ * Options for creating a backup via `db.backup()`.
6
+ *
7
+ * Backups are whole-database: every column family, the manifest, and (unless
8
+ * `backupLogFiles` is disabled) the write-ahead log are captured. A backup is
9
+ * not scoped to an individual `Store`.
10
+ */
11
+ interface BackupOptions {
12
+ /**
13
+ * Flush the memtable before backing up. Defaults to `true` when the database
14
+ * was opened with `disableWAL` (otherwise unflushed data would be lost from
15
+ * the backup), and `false` otherwise.
16
+ */
17
+ flushBeforeBackup?: boolean;
18
+ /**
19
+ * Arbitrary application metadata stored with the backup and returned by
20
+ * `backups.list()`.
21
+ */
22
+ metadata?: string;
23
+ /**
24
+ * Share table/blob files between backups in the same directory to enable
25
+ * incremental backups. Defaults to `true`.
26
+ */
27
+ shareTableFiles?: boolean;
28
+ /**
29
+ * Distinguish shared files by checksum to avoid collisions across databases.
30
+ * Defaults to `true`. Only relevant when `shareTableFiles` is enabled.
31
+ */
32
+ shareFilesWithChecksum?: boolean;
33
+ /**
34
+ * Include write-ahead log files in the backup. Defaults to `true`.
35
+ */
36
+ backupLogFiles?: boolean;
37
+ /**
38
+ * `fsync` backup files for crash consistency. Defaults to `true`.
39
+ */
40
+ sync?: boolean;
41
+ /**
42
+ * Number of background threads used to copy files. Defaults to `1`.
43
+ */
44
+ maxBackgroundOperations?: number;
45
+ }
46
+ /**
47
+ * The level of incremental restore to perform.
48
+ *
49
+ * - `purgeAllFiles` (default): purge the destination directory and restore all
50
+ * files from the backup. Destructive but always correct.
51
+ * - `keepLatestDbSessionIdFiles`: efficiently restore a healthy database,
52
+ * reusing existing files that match the backup.
53
+ * - `verifyChecksum`: reuse existing destination files whose checksums match the
54
+ * backup, replacing only mismatched/corrupt files.
55
+ */
56
+ type RestoreMode = "purgeAllFiles" | "keepLatestDbSessionIdFiles" | "verifyChecksum";
57
+ /**
58
+ * Options for restoring a backup via `backups.restore()`.
59
+ */
60
+ interface RestoreOptions {
61
+ /**
62
+ * The backup id to restore. Defaults to the latest non-corrupt backup.
63
+ */
64
+ backupId?: number;
65
+ /**
66
+ * Directory to restore write-ahead log files into. Defaults to the database
67
+ * directory.
68
+ */
69
+ walDir?: string;
70
+ /**
71
+ * Keep existing log files in `walDir` rather than overwriting them. Defaults
72
+ * to `false`.
73
+ */
74
+ keepLogFiles?: boolean;
75
+ /**
76
+ * The restore strategy. Defaults to `purgeAllFiles`, which is destructive.
77
+ */
78
+ mode?: RestoreMode;
79
+ }
80
+ /**
81
+ * Information about a single backup, as returned by `backups.list()`.
82
+ */
83
+ interface BackupInfo {
84
+ /** The backup id (monotonically increasing integer). */
85
+ backupId: number;
86
+ /** Creation time in seconds since the epoch. */
87
+ timestamp: number;
88
+ /** Total size in bytes of the backed-up file payloads. */
89
+ size: number;
90
+ /** Number of files in the backup (some may be shared with other backups). */
91
+ numberFiles: number;
92
+ /** Application metadata supplied when the backup was created. */
93
+ appMetadata: string;
94
+ }
95
+ /**
96
+ * Backup management operations that act on a backup directory and do not
97
+ * require an open database. To create a backup, use the `db.backup()` instance
98
+ * method instead (it needs a live database for a consistent snapshot).
99
+ *
100
+ * @example
101
+ * ```typescript
102
+ * import { backups } from '@harperfast/rocksdb-js';
103
+ *
104
+ * const id = await db.backup('/path/to/backups');
105
+ * db.close();
106
+ * await backups.restore('/path/to/backups', '/path/to/restored-db');
107
+ * ```
108
+ */
109
+ declare const backups: {
110
+ /**
111
+ * Restores a database from a backup directory into a (closed) database
112
+ * directory. The default mode purges the destination directory, so it must
113
+ * not point at a live database.
114
+ */
115
+ restore(backupDir: string, dbDir: string, options?: RestoreOptions): Promise<void>;
116
+ /**
117
+ * Lists the non-corrupt backups in a backup directory, ordered by id.
118
+ */
119
+ list(backupDir: string): Promise<BackupInfo[]>;
120
+ /**
121
+ * Deletes a specific backup. Shared files are reference-counted and only
122
+ * removed once no remaining backup references them.
123
+ */
124
+ delete(backupDir: string, backupId: number): Promise<void>;
125
+ /**
126
+ * Deletes all but the newest `keepCount` backups.
127
+ */
128
+ purge(backupDir: string, keepCount: number): Promise<void>;
129
+ /**
130
+ * Verifies a backup's file sizes, and optionally their checksums (which
131
+ * requires reading all backed-up data).
132
+ */
133
+ verify(backupDir: string, backupId: number, options?: {
134
+ verifyWithChecksum?: boolean;
135
+ }): Promise<void>;
136
+ };
137
+ //#endregion
3
138
  //#region src/encoding.d.ts
4
139
  type Key = Key[] | string | symbol | number | boolean | Uint8Array | Buffer | null;
5
140
  interface BufferWithDataView extends Buffer {
@@ -416,7 +551,7 @@ declare class DBIterator<T> implements Iterator<DBIteratorValue<T>> {
416
551
  #private;
417
552
  iterator: InstanceType<typeof NativeIteratorCls>;
418
553
  store: Store;
419
- constructor(iterator: InstanceType<typeof NativeIteratorCls>, store: Store, includeValues: boolean);
554
+ constructor(iterator: InstanceType<typeof NativeIteratorCls>, store: Store, includeValues: boolean, limit?: number);
420
555
  [Symbol.iterator](): Iterator<DBIteratorValue<T>>;
421
556
  next(): IteratorResult<DBIteratorValue<T>>;
422
557
  return(value?: any): IteratorResult<DBIteratorValue<T>, any>;
@@ -626,6 +761,10 @@ declare class Store {
626
761
  */
627
762
  transactionLogsPath?: string;
628
763
  /**
764
+ * Whether this store's column family participates in the VerificationTable.
765
+ */
766
+ verificationTable?: boolean;
767
+ /**
629
768
  * The per-column-family memtable size in bytes at which the memtable is
630
769
  * sealed and flushed.
631
770
  */
@@ -657,6 +796,17 @@ declare class Store {
657
796
  */
658
797
  compact(options?: CompactOptions): Promise<void>;
659
798
  /**
799
+ * Creates a backup of the entire database (all column families) into the
800
+ * given directory and resolves with the new backup id. Parent directories
801
+ * are created as needed. See `backups` for restore and management.
802
+ *
803
+ * @example
804
+ * ```typescript
805
+ * const id = await db.backup('/path/to/backups');
806
+ * ```
807
+ */
808
+ backup(backupDir: string, options?: BackupOptions): Promise<number>;
809
+ /**
660
810
  * Compacts the entire key range of the database synchronously.
661
811
  * This triggers manual compaction which removes tombstones and reclaims space.
662
812
  *
@@ -695,7 +845,7 @@ declare class Store {
695
845
  * @returns The encoded value.
696
846
  */
697
847
  encodeValue(value: any): BufferWithDataView | Uint8Array;
698
- get(context: StoreContext, key: Key, alwaysCreateNewBuffer?: boolean, txnId?: number): any | undefined;
848
+ get(context: StoreContext, key: Key, alwaysCreateNewBuffer?: boolean, options?: StoreGetOptions): any | undefined;
699
849
  getCount(context: StoreContext, options?: StoreRangeOptions): number;
700
850
  getKeys(context: StoreContext, options?: StoreIteratorOptions): any | undefined;
701
851
  getKeysCount(context: StoreContext, options?: StoreRangeOptions): number;
@@ -772,6 +922,19 @@ declare class Store {
772
922
  */
773
923
  useLog(context: StoreContext, name: string | number): TransactionLog;
774
924
  /**
925
+ * Checks the process-global verification table for a fresh version match
926
+ * on `key`. Returns `true` when the table currently records `version` for
927
+ * this database+column-family. Provides a fast cache-freshness check
928
+ * before falling back to a full read.
929
+ */
930
+ verifyVersion(key: Key, version: number): boolean;
931
+ /**
932
+ * Seeds the verification-table slot for `key` with `version`. Has no
933
+ * effect if the slot is currently lock-tagged or the table is disabled.
934
+ * Useful after a full read where the caller already knows the version.
935
+ */
936
+ populateVersion(key: Key, version: number): void;
937
+ /**
775
938
  * Acquires a lock on the given key and calls the callback.
776
939
  *
777
940
  * @param key - The key to lock.
@@ -781,6 +944,21 @@ declare class Store {
781
944
  withLock(key: Key, callback: () => void | Promise<void>): Promise<void>;
782
945
  }
783
946
  interface GetOptions {
947
+ /**
948
+ * When set, the native layer checks the verification table before reading.
949
+ * If the slot holds this version, returns `FRESH_VERSION_FLAG` immediately
950
+ * (the cached value is still valid). After a DB read, also seeds the slot
951
+ * with the version extracted from the value.
952
+ */
953
+ expectedVersion?: number;
954
+ /**
955
+ * When `true`, after a DB read the native layer automatically seeds the
956
+ * verification-table slot with the version extracted from the value.
957
+ * Eliminates the need for a separate `populateVersion` call on cold reads.
958
+ *
959
+ * @default false
960
+ */
961
+ populateVersion?: boolean;
784
962
  /**
785
963
  * Whether to skip decoding the value.
786
964
  *
@@ -803,14 +981,25 @@ type NativeTransactionOptions = {
803
981
  * @default false
804
982
  */
805
983
  disableSnapshot?: boolean;
984
+ /**
985
+ * When `true`, an `IsBusy` conflict at commit time is resolved with the
986
+ * `RETRY_NOW` sentinel value instead of being rejected. The native layer
987
+ * may park on a VT slot before resolving, so the JS retry fires only after
988
+ * the conflicting transaction has committed and released its write intent.
989
+ *
990
+ * Use together with `verificationTable: true` on the database.
991
+ *
992
+ * @default false
993
+ */
994
+ coordinatedRetry?: boolean;
806
995
  };
807
996
  type NativeTransaction = {
808
997
  id: number;
809
998
  new (context: NativeDatabase, options?: NativeTransactionOptions): NativeTransaction;
810
999
  abort(): void;
811
- commit(resolve: () => void, reject: (err: Error) => void): void;
1000
+ commit(resolve: (retrySignal?: number) => void, reject: (err: Error) => void): void;
812
1001
  commitSync(): void;
813
- get(keyLengthOrKeyBuffer: number | Buffer, resolve: (value: Buffer) => void, reject: (err: Error) => void): number;
1002
+ get(keyLengthOrKeyBuffer: number | Buffer, resolve: (value: Buffer | number) => void, reject: (err: Error) => void, txnIdIgnored?: number, expectedVersion?: number): number;
814
1003
  getCount(options?: RangeOptions): number;
815
1004
  getSync(keyLengthOrKeyBuffer: number | Buffer): Buffer | number | undefined;
816
1005
  getTimestamp(): number;
@@ -960,6 +1149,13 @@ type NativeDatabaseOptions = {
960
1149
  transactionLogMaxSize?: number;
961
1150
  transactionLogRetentionMs?: number;
962
1151
  transactionLogsPath?: string;
1152
+ /**
1153
+ * When true, transaction writes to this column family invalidate the
1154
+ * VerificationTable slot for each written key at write time (not at
1155
+ * commit time). Enable only for column families whose records are
1156
+ * cached (e.g. the primary CF of a table). Default: false.
1157
+ */
1158
+ verificationTable?: boolean;
963
1159
  writeBufferSize?: number;
964
1160
  };
965
1161
  type ResolveCallback<T> = (value: T) => void;
@@ -968,24 +1164,39 @@ type UserSharedBufferCallback = () => void;
968
1164
  type PurgeLogsOptions = {
969
1165
  before?: number;
970
1166
  destroy?: boolean;
1167
+ /**
1168
+ * When `true`, count the entries in each purged log file (extra work) and
1169
+ * return `PurgedLog[]` instead of the default `string[]` of file paths.
1170
+ */
1171
+ includeEntryCounts?: boolean;
971
1172
  name?: string;
972
1173
  };
1174
+ /**
1175
+ * A purged transaction log file and the number of entries it held, returned by
1176
+ * `purgeLogs()` when `includeEntryCounts` is `true`.
1177
+ */
1178
+ type PurgedLog = {
1179
+ path: string;
1180
+ entries: number;
1181
+ };
973
1182
  type NativeDatabase = {
974
1183
  new (): NativeDatabase;
975
1184
  addListener(event: string, callback: (...args: any[]) => void): void;
1185
+ backup(resolve: ResolveCallback<number>, reject: RejectCallback, backupDir: string, options?: BackupOptions): void;
976
1186
  clear(resolve: ResolveCallback<void>, reject: RejectCallback): void;
977
1187
  clearSync(): void;
978
1188
  close(): void;
979
1189
  compact(resolve: ResolveCallback<void>, reject: RejectCallback, start?: Key, end?: Key): void;
980
1190
  compactSync(start?: Key, end?: Key): void;
981
1191
  columns: string[];
1192
+ createCheckpoint(resolve: ResolveCallback<void>, reject: RejectCallback, targetPath: string): void;
982
1193
  destroy(): void;
983
1194
  drop(resolve: ResolveCallback<void>, reject: RejectCallback): void;
984
1195
  dropSync(): void;
985
1196
  flush(resolve: ResolveCallback<void>, reject: RejectCallback): void;
986
1197
  flushSync(): void;
987
1198
  notify(event: string | BufferWithDataView, args?: any[]): boolean;
988
- get(keyLengthOrKeyBuffer: number | Buffer, resolve: ResolveCallback<Buffer>, reject: RejectCallback, txnId?: number): number;
1199
+ get(keyLengthOrKeyBuffer: number | Buffer, resolve: ResolveCallback<Buffer | number>, reject: RejectCallback, txnId?: number, expectedVersion?: number): number;
989
1200
  getCount(options?: RangeOptions, txnId?: number): number;
990
1201
  getDBIntProperty(propertyName: string): number | undefined;
991
1202
  getDBProperty(propertyName: string): string | undefined;
@@ -994,14 +1205,21 @@ type NativeDatabase = {
994
1205
  getStat(statName: string): number | StatsHistogramData;
995
1206
  getStats(all?: false): StatsDefault;
996
1207
  getStats(all: true): StatsAll;
997
- getSync(keyLengthOrKeyBuffer: number | Buffer, flags: number, txnId?: number): Buffer;
1208
+ getSync(keyLengthOrKeyBuffer: number | Buffer, flags: number, txnId?: number, expectedVersion?: number): Buffer;
998
1209
  getUserSharedBuffer(key: BufferWithDataView, defaultBuffer: ArrayBuffer, callback?: UserSharedBufferCallback): ArrayBuffer;
999
1210
  hasLock(key: BufferWithDataView): boolean;
1000
1211
  listeners(event: string | BufferWithDataView): number;
1001
1212
  listLogs(): string[];
1002
1213
  opened: boolean;
1003
1214
  open(path: string, options?: NativeDatabaseOptions): void;
1004
- purgeLogs(options?: PurgeLogsOptions): string[];
1215
+ populateVersion(keyLengthOrKeyBuffer: number | Buffer, version: number): void;
1216
+ purgeLogs(options: PurgeLogsOptions & {
1217
+ includeEntryCounts: true;
1218
+ }): PurgedLog[];
1219
+ purgeLogs(options?: PurgeLogsOptions & {
1220
+ includeEntryCounts?: false;
1221
+ }): string[];
1222
+ purgeLogs(options?: PurgeLogsOptions): string[] | PurgedLog[];
1005
1223
  putSync(key: BufferWithDataView, value: any, txnId?: number): void;
1006
1224
  removeListener(event: string | BufferWithDataView, callback: () => void): boolean;
1007
1225
  removeSync(key: BufferWithDataView, txnId?: number): void;
@@ -1011,10 +1229,19 @@ type NativeDatabase = {
1011
1229
  tryLock(key: BufferWithDataView, callback?: () => void): boolean;
1012
1230
  unlock(key: BufferWithDataView): void;
1013
1231
  useLog(name: string): TransactionLog;
1232
+ verifyVersion(keyLengthOrKeyBuffer: number | Buffer, version: number): boolean;
1014
1233
  withLock(key: BufferWithDataView, callback: () => void | Promise<void>): Promise<void>;
1015
1234
  };
1016
1235
  type RocksDatabaseConfig = {
1017
1236
  blockCacheSize?: number;
1237
+ /**
1238
+ * Number of slots in the process-global verification table. Each slot is
1239
+ * 8 bytes; the default of 128K slots is 1 MB. Set to 0 to disable.
1240
+ *
1241
+ * Must be configured before the first database is opened. Once the table
1242
+ * is materialized, attempts to change this value will throw.
1243
+ */
1244
+ verificationTableEntries?: number;
1018
1245
  compactOnClose?: boolean;
1019
1246
  /**
1020
1247
  * Total memtable memory limit (bytes) shared across every database opened
@@ -1066,6 +1293,14 @@ declare const constants: {
1066
1293
  ALWAYS_CREATE_NEW_BUFFER_FLAG: number;
1067
1294
  NOT_IN_MEMORY_CACHE_FLAG: number;
1068
1295
  ONLY_IF_IN_MEMORY_CACHE_FLAG: number;
1296
+ POPULATE_VERSION_FLAG: number;
1297
+ FRESH_VERSION_FLAG: number;
1298
+ /**
1299
+ * Sentinel value resolved (not rejected) by `commit()` when
1300
+ * `coordinatedRetry: true` and the transaction encountered an IsBusy
1301
+ * conflict. JS should retry the transaction body immediately.
1302
+ */
1303
+ RETRY_NOW_VALUE: number;
1069
1304
  TRANSACTION_LOG_TOKEN: number;
1070
1305
  TRANSACTION_LOG_ENTRY_HEADER_SIZE: number;
1071
1306
  TRANSACTION_LOG_FILE_HEADER_SIZE: number;
@@ -1084,6 +1319,23 @@ declare const TransactionLog: TransactionLog;
1084
1319
  declare const registryStatus: () => RegistryStatus;
1085
1320
  declare const shutdown: () => void;
1086
1321
  declare const currentThreadId: () => number;
1322
+ /**
1323
+ * Advises the kernel that the file-backed pages of every mapped transaction log
1324
+ * are cold (Linux MADV_COLD), so they are reclaimed first under memory pressure
1325
+ * without being freed — useful during replication catch-up, where a full read of
1326
+ * the logs would otherwise inflate the container's reclaimable cache toward its
1327
+ * cgroup limit. No-op on kernels < 5.4, macOS, and Windows.
1328
+ *
1329
+ * The transaction log registry is a process-global singleton shared across all
1330
+ * worker threads, so a single call cools every worker's maps. Call it on an
1331
+ * interval from one thread (e.g. an `unref()`ed timer on the main thread).
1332
+ *
1333
+ * @returns the number of maps cooled and total file-backed bytes advised.
1334
+ */
1335
+ declare const coolTransactionLogs: () => {
1336
+ maps: number;
1337
+ bytes: number;
1338
+ };
1087
1339
  declare const stats: {
1088
1340
  StatsLevel: {
1089
1341
  DisableAll: number;
@@ -1098,6 +1350,13 @@ declare const stats: {
1098
1350
  //#endregion
1099
1351
  //#region src/transaction.d.ts
1100
1352
  /**
1353
+ * Sentinel value returned by `commit()` when `coordinatedRetry: true` and the
1354
+ * transaction encountered an IsBusy conflict. The native layer parks on VT
1355
+ * slots and resolves only after the conflicting transaction releases its write
1356
+ * intent, so callers should retry immediately without any backoff delay.
1357
+ */
1358
+ declare const RETRY_NOW: number;
1359
+ /**
1101
1360
  * Provides transaction level operations to a transaction callback.
1102
1361
  */
1103
1362
  declare class Transaction extends DBI {
@@ -1115,8 +1374,11 @@ declare class Transaction extends DBI {
1115
1374
  abort(): void;
1116
1375
  /**
1117
1376
  * Commit the transaction.
1377
+ *
1378
+ * Returns `RETRY_NOW` when `coordinatedRetry: true` and an IsBusy conflict
1379
+ * was detected. The caller should retry the transaction body immediately.
1118
1380
  */
1119
- commit(): Promise<void>;
1381
+ commit(): Promise<typeof RETRY_NOW | void>;
1120
1382
  /**
1121
1383
  * Commit the transaction synchronously.
1122
1384
  */
@@ -1217,6 +1479,12 @@ interface RangeOptions extends RocksDBOptions {
1217
1479
  start?: Key | Uint8Array;
1218
1480
  }
1219
1481
  interface IteratorOptions extends RangeOptions {
1482
+ /**
1483
+ * The maximum number of entries to yield. When set, iteration stops after
1484
+ * `limit` entries regardless of the range bounds. Values <= 0 yield nothing.
1485
+ * Unset means no limit.
1486
+ */
1487
+ limit?: number;
1220
1488
  /**
1221
1489
  * A specific key to match which may result in zero, one, or many values.
1222
1490
  */
@@ -1283,11 +1551,11 @@ declare class DBI<T extends DBITransactional | unknown = unknown> {
1283
1551
  *
1284
1552
  * Note: Used by HDBreplication.
1285
1553
  */
1286
- getBinary(key: Key, options?: GetOptions & T): MaybePromise<Buffer | undefined>;
1554
+ getBinary(key: Key, options?: GetOptions & T): MaybePromise<Buffer | number | undefined>;
1287
1555
  /**
1288
1556
  * Synchronously retrieves the binary data for the given key.
1289
1557
  */
1290
- getBinarySync(key: Key, options?: GetOptions & T): Buffer | undefined;
1558
+ getBinarySync(key: Key, options?: GetOptions & T): Buffer | number | undefined;
1291
1559
  /**
1292
1560
  * Retrieves the binary data for the given key using a preallocated,
1293
1561
  * reusable buffer. Data in the buffer is only valid until the next get
@@ -1298,13 +1566,13 @@ declare class DBI<T extends DBITransactional | unknown = unknown> {
1298
1566
  * - `.byteLength` is set to the size of the full allocated memory area for
1299
1567
  * the buffer (usually much larger).
1300
1568
  */
1301
- getBinaryFast(key: Key, options?: GetOptions & T): MaybePromise<Buffer | undefined>;
1569
+ getBinaryFast(key: Key, options?: GetOptions & T): MaybePromise<Buffer | number | undefined>;
1302
1570
  /**
1303
1571
  * Synchronously retrieves the binary data for the given key using a
1304
1572
  * preallocated, reusable buffer. Data in the buffer is only valid until the
1305
1573
  * next get operation (including cursor operations).
1306
1574
  */
1307
- getBinaryFastSync(key: Key, options?: GetOptions & T): Buffer | undefined;
1575
+ getBinaryFastSync(key: Key, options?: GetOptions & T): Buffer | number | undefined;
1308
1576
  /**
1309
1577
  * Retrieves all keys within a range.
1310
1578
  */
@@ -1538,6 +1806,49 @@ declare class RocksDatabase extends DBI<DBITransactional> {
1538
1806
  */
1539
1807
  compact(options?: CompactOptions): Promise<void>;
1540
1808
  /**
1809
+ * Creates a backup of the entire database (all column families) into the
1810
+ * given directory, creating parent directories as needed, and resolves with
1811
+ * the new backup id. Use the `backups` namespace to restore, list, delete,
1812
+ * purge, or verify backups.
1813
+ *
1814
+ * When the database was opened with `disableWAL`, the memtable is flushed
1815
+ * before the backup by default so unflushed data is not lost.
1816
+ *
1817
+ * @example
1818
+ * ```typescript
1819
+ * import { backups } from '@harperfast/rocksdb-js';
1820
+ *
1821
+ * const db = RocksDatabase.open('/path/to/database');
1822
+ * const id = await db.backup('/path/to/backups');
1823
+ * ```
1824
+ */
1825
+ backup(backupDir: string, options?: BackupOptions): Promise<number>;
1826
+ /**
1827
+ * Creates a hardlinked, point-in-time, fully independent copy of the entire
1828
+ * database (all column families) at `targetPath` and resolves once written.
1829
+ *
1830
+ * Unlike a backup, a checkpoint is a normal, writable sibling database: open
1831
+ * it with {@link RocksDatabase.open} and it diverges independently from the
1832
+ * source. SST and blob files are hardlinked when `targetPath` is on the same
1833
+ * filesystem as the database and copied otherwise (other files such as the
1834
+ * MANIFEST are always copied), so the operation is near-instant on the same
1835
+ * filesystem. The memtable is flushed so the checkpoint includes the latest
1836
+ * writes even when the WAL is disabled.
1837
+ *
1838
+ * Parent directories are created as needed. `targetPath` itself must not
1839
+ * already exist (RocksDB creates the checkpoint directory) and rejects with
1840
+ * `Create checkpoint failed: target path exists` if it does. The caller is
1841
+ * responsible for eventual cleanup of the directory.
1842
+ *
1843
+ * @example
1844
+ * ```typescript
1845
+ * const db = RocksDatabase.open('/path/to/database');
1846
+ * await db.createCheckpoint('/path/to/checkpoint');
1847
+ * const branch = RocksDatabase.open('/path/to/checkpoint');
1848
+ * ```
1849
+ */
1850
+ createCheckpoint(targetPath: string): Promise<void>;
1851
+ /**
1541
1852
  * Compacts the entire key range of the database synchronously.
1542
1853
  * This triggers manual compaction which removes tombstones and reclaims space.
1543
1854
  *
@@ -1735,6 +2046,26 @@ declare class RocksDatabase extends DBI<DBITransactional> {
1735
2046
  hasLock(key: Key): boolean;
1736
2047
  ifNoExists(_key: Key): Promise<void>;
1737
2048
  /**
2049
+ * Checks the process-global verification table for a fresh version match
2050
+ * on `key`. Returns `true` when the table currently records `version`. Use
2051
+ * this as a fast cache-freshness check before falling back to a full read:
2052
+ *
2053
+ * ```typescript
2054
+ * if (db.verifyVersion(key, cachedEntry.version)) {
2055
+ * return cachedEntry.value;
2056
+ * }
2057
+ * const value = db.getSync(key);
2058
+ * db.populateVersion(key, extractVersion(value));
2059
+ * ```
2060
+ */
2061
+ verifyVersion(key: Key, version: number): boolean;
2062
+ /**
2063
+ * Seeds the verification-table slot for `key` with `version`. Has no
2064
+ * effect if the slot is currently lock-tagged or if the verification
2065
+ * table is disabled.
2066
+ */
2067
+ populateVersion(key: Key, version: number): void;
2068
+ /**
1738
2069
  * Returns whether the database is open.
1739
2070
  *
1740
2071
  * @returns `true` if the database is open, `false` otherwise.
@@ -1786,8 +2117,18 @@ declare class RocksDatabase extends DBI<DBITransactional> {
1786
2117
  get path(): string;
1787
2118
  /**
1788
2119
  * Purges transaction logs.
2120
+ *
2121
+ * By default returns the paths of the deleted log files. Pass
2122
+ * `includeEntryCounts: true` to instead return, for each deleted file, its
2123
+ * path and the number of entries it held (`{ path, entries }`).
1789
2124
  */
1790
- purgeLogs(options?: PurgeLogsOptions): string[];
2125
+ purgeLogs(options: PurgeLogsOptions & {
2126
+ includeEntryCounts: true;
2127
+ }): PurgedLog[];
2128
+ purgeLogs(options?: PurgeLogsOptions & {
2129
+ includeEntryCounts?: false;
2130
+ }): string[];
2131
+ purgeLogs(options?: PurgeLogsOptions): string[] | PurgedLog[];
1791
2132
  /**
1792
2133
  * The status of the database.
1793
2134
  */
@@ -1910,5 +2251,5 @@ declare const versions: {
1910
2251
  "rocksdb-js": string;
1911
2252
  };
1912
2253
  //#endregion
1913
- 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 };
2254
+ 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 };
1914
2255
  //# sourceMappingURL=index.d.mts.map