@harperfast/rocksdb-js 2.2.0 → 2.3.0

package/README.md

@@ -1385,6 +1385,34 @@ import { versions } from '@harperfast/rocksdb-js';
 console.log(versions); // { "rocksdb": "10.10.1", "rocksdb-js": "0.1.2" }
 ```
 
+## Checkpoints
+
+### `db.createCheckpoint(targetPath: string): Promise<void>`
+
+Creates a [checkpoint](https://github.com/facebook/rocksdb/wiki/Checkpoints) — a point-in-time,
+fully independent copy of the entire database (all column families) at `targetPath` — and resolves
+once written. Unlike a backup, a checkpoint is a normal, writable database: open it as a new
+`RocksDatabase` and it diverges independently from the source.
+
+SST and blob files are **hard-linked** when `targetPath` is on the **same filesystem** as the
+database, and **copied** otherwise; other files (such as the `MANIFEST`) are always copied. As a
+result the operation is near-instant on the same filesystem and as costly as a full copy across
+filesystems. The memtable is flushed so the checkpoint includes the latest writes even when the
+WAL is disabled.
+
+Parent directories are created as needed. `targetPath` itself must not already exist — RocksDB
+creates the checkpoint directory — and the call rejects with `Create checkpoint failed: target
+path exists` if it does (other failures, such as a full disk, surface the RocksDB status message).
+The caller is responsible for opening the checkpoint and for eventually deleting the directory.
+
+```typescript
+const db = RocksDatabase.open('/path/to/database');
+await db.createCheckpoint('/path/to/checkpoint');
+
+// The checkpoint is a normal, writable database.
+const branch = RocksDatabase.open('/path/to/checkpoint');
+```
+
 ## Backups
 
 Backups use RocksDB's `BackupEngine` to capture consistent, incremental, checksum-verified

package/dist/index.cjs

@@ -1527,6 +1527,40 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		return this.store.backup(backupDir, options);
 	}
 	/**
+	* Creates a hardlinked, point-in-time, fully independent copy of the entire
+	* database (all column families) at `targetPath` and resolves once written.
+	*
+	* Unlike a backup, a checkpoint is a normal, writable sibling database: open
+	* it with {@link RocksDatabase.open} and it diverges independently from the
+	* source. SST and blob files are hardlinked when `targetPath` is on the same
+	* filesystem as the database and copied otherwise (other files such as the
+	* MANIFEST are always copied), so the operation is near-instant on the same
+	* filesystem. The memtable is flushed so the checkpoint includes the latest
+	* writes even when the WAL is disabled.
+	*
+	* Parent directories are created as needed. `targetPath` itself must not
+	* already exist (RocksDB creates the checkpoint directory) and rejects with
+	* `Create checkpoint failed: target path exists` if it does. The caller is
+	* responsible for eventual cleanup of the directory.
+	*
+	* @example
+	* ```typescript
+	* const db = RocksDatabase.open('/path/to/database');
+	* await db.createCheckpoint('/path/to/checkpoint');
+	* const branch = RocksDatabase.open('/path/to/checkpoint');
+	* ```
+	*/
+	createCheckpoint(targetPath) {
+		return new Promise((resolve, reject) => {
+			if ((0, node_fs.existsSync)(targetPath)) {
+				reject(/* @__PURE__ */ new Error("Create checkpoint failed: target path exists"));
+				return;
+			}
+			(0, node_fs.mkdirSync)((0, node_path.dirname)(targetPath), { recursive: true });
+			this.store.db.createCheckpoint(resolve, reject, targetPath);
+		});
+	}
+	/**
 	* Compacts the entire key range of the database synchronously.
 	* This triggers manual compaction which removes tombstones and reclaims space.
 	*
@@ -2375,7 +2409,7 @@ function loadLastPosition(transactionLog, readUncommitted) {
 //#region src/index.ts
 const versions = {
 	rocksdb: version,
-	"rocksdb-js": "2.2.0"
+	"rocksdb-js": "2.3.0"
 };
 
 //#endregion