Merge pull request #371 from HarperFast/destroy

Add `db.destroy()`

Author: cb1kenobi

README.md

@@ -91,6 +91,26 @@ RocksDatabase.config({
 });
 ```
 
+### `db.isOpen(): boolean`
+
+Returns `true` if the database is open, otherwise false.
+
+```typescript
+console.log(db.isOpen()); // true or false
+```
+
+### `db.name: string`
+
+Returns the database column family's name.
+
+```typescript
+const db = new RocksDatabase('path/to/db');
+console.log(db.name); // 'default'
+
+const db2 = new RocksDatabase('path/to/db', { name: 'users' });
+console.log(db.name); // 'users'
+```
+
 ### `db.open(): RocksDatabase`
 
 Opens the database at the given path. This must be called before performing any data operations.
@@ -108,16 +128,12 @@ There's also a static `open()` method for convenience that performs the same thi
 const db = RocksDatabase.open('path/to/db');
 ```
 
-### `db.name: string`
+### `db.status: 'opened' | 'closed'`
 
-Returns the database column family's name.
+Returns a string `'opened'` or `'closed'` indicating if the database is opened or closed.
 
 ```typescript
-const db = new RocksDatabase('path/to/db');
-console.log(db.name); // 'default'
-
-const db2 = new RocksDatabase('path/to/db', { name: 'users' });
-console.log(db.name); // 'users'
+console.log(db.status);
 ```
 
 ## Data Operations
@@ -156,6 +172,16 @@ const entriesRemoved = db.clearSync();
 console.log(entriesRemoved); // 10
 ```
 
+### `db.destroy(): void`
+
+Completely removes a database based on the `db` instance's path including all data, column families,
+and files on disk.
+
+```typescript
+db.destroy();
+console.log(fs.existsSync(db.path)); // false
+```
+
 ### `db.drop(): Promise<void>`
 
 Removes all entries in the database. If the database was opened with a `name`, the database will be
@@ -847,6 +873,24 @@ Returns an object containing all of the information in the log file.
   - `length: number` The size of the entry data.
   - `timestamp: number` The entry timestamp.
 
+### `registryStatus(): RegistryStatus`
+
+Returns an array containing that status of all active RocksDB instances.
+
+- `path: string` The database path.
+- `refCount: number` The number of JavaScript database instances plus the registry's reference.
+- `columnFamiles: string[]` A list of the database's column families.
+- `transactions: number` The count of active transactions.
+- `closables: number` The count of active database, transactions, and iterators.
+- `locks: number` The count of active locks.
+- `userSharedBuffers: number` The count of active user shared buffers.
+- `listenerCallbacks: number` The count of in-flight callbacks.
+
+```typescript
+import { registryStatus } from '@harperfast/rocksdb-js';
+console.log(registryStatus());
+```
+
 ### `shutdown(): void`
 
 The `shutdown()` will flush all in-memory data to disk and wait for any outstanding compactions to
@@ -858,6 +902,15 @@ import { shutdown } from '@harperfast/rocksdb-js';
 process.on('exit', shutdown);
 ```
 
+### `versions: { 'rocksdb': string; 'rocksdb-js': string }`
+
+Returns the `rocksdb-js` and RocksDB version.
+
+```typescript
+import { versions } from '@harperfast/rocksdb-js';
+console.log(versions); // { "rocksdb": "10.10.1", "rocksdb-js": "0.1.2" }
+```
+
 ## Custom Store
 
 The store is a class that sits between the `RocksDatabase` or `Transaction` instance and the native

package.json

@@ -25,17 +25,17 @@
     "build:bundle:minify": "cross-env MINIFY=1 pnpm build:bundle",
     "check": "pnpm type-check && pnpm lint",
     "clean": "node-gyp clean",
-    "coverage": "tsx scripts/coverage/main.ts",
+    "coverage": "tsx scripts/coverage/main.ts --no-file-parallelism",
     "format": "dprint check",
     "format:fix": "dprint fmt",
     "lint": "oxlint",
     "prepublishOnly": "pnpm build",
     "rebuild": "node-gyp rebuild",
     "rebuild:debug": "node-gyp rebuild --coverage --debug --verbose",
-    "test": "cross-env CI=1 node --expose-gc ./node_modules/vitest/vitest.mjs --reporter=verbose",
-    "test:bun": "cross-env CI=1 bun --bun --config=bunfig.toml ./node_modules/vitest/vitest.mjs --reporter=verbose",
-    "test:deno": "cross-env CI=1 deno run --allow-all --sloppy-imports ./node_modules/vitest/vitest.mjs",
-    "test:stress": "cross-env CI=1 node --expose-gc ./node_modules/vitest/vitest.mjs --reporter=verbose --config=vitest-stress.config.ts",
+    "test": "cross-env CI=1 node --expose-gc ./node_modules/vitest/vitest.mjs --reporter=verbose --no-file-parallelism",
+    "test:bun": "cross-env CI=1 bun --bun --config=bunfig.toml ./node_modules/vitest/vitest.mjs --reporter=verbose --no-file-parallelism",
+    "test:deno": "cross-env CI=1 deno run --allow-all --sloppy-imports ./node_modules/vitest/vitest.mjs --no-file-parallelism",
+    "test:stress": "cross-env CI=1 node --expose-gc ./node_modules/vitest/vitest.mjs --reporter=verbose --config=vitest-stress.config.ts --no-file-parallelism",
     "type-check": "tsc --noEmit"
   },
   "files": [

src/binding/binding.cpp

@@ -51,7 +51,7 @@ NAPI_MODULE_INIT() {
 	DEBUG_LOG("Binding::Init Module ref count: %d\n", refCount);
 
 	// initialize the registry
-	DBRegistry::Init();
+	rocksdb_js::DBRegistry::Init(env, exports);
 
 	// registry cleanup
 	NAPI_STATUS_THROWS(::napi_add_env_cleanup_hook(env, [](void* data) {

src/binding/database.cpp

@@ -169,16 +169,45 @@ napi_value Database::Close(napi_env env, napi_callback_info info) {
 	UNWRAP_DB_HANDLE();
 
 	if (*dbHandle && (*dbHandle)->descriptor) {
-		DEBUG_LOG("%p Database::Close closing database: %s\n", dbHandle->get(), (*dbHandle)->descriptor->path.c_str());
+		DEBUG_LOG("%p Database::Close Closing database: \"%s\"\n", dbHandle->get(), (*dbHandle)->path.c_str());
 		DBRegistry::CloseDB(*dbHandle);
-		DEBUG_LOG("%p Database::Close closed database\n", dbHandle->get());
+		DEBUG_LOG("%p Database::Close Closed database\n", dbHandle->get());
 	} else {
 		DEBUG_LOG("%p Database::Close Database not opened\n", dbHandle->get());
 	}
 
 	NAPI_RETURN_UNDEFINED();
 }
 
+/**
+ * Destroys the RocksDB database.
+ *
+ * @example
+ * ```typescript
+ * const db = new NativeDatabase();
+ * db.destroy();
+ * ```
+ */
+napi_value Database::Destroy(napi_env env, napi_callback_info info) {
+	NAPI_METHOD_ARGV(1);
+	UNWRAP_DB_HANDLE();
+
+	if (*dbHandle) {
+		try {
+			DBRegistry::DestroyDB((*dbHandle)->path);
+		} catch (const std::exception& e) {
+			DEBUG_LOG("%p Database::Destroy Error: %s\n", dbHandle->get(), e.what());
+			::napi_throw_error(env, nullptr, e.what());
+			return nullptr;
+		}
+	} else {
+		::napi_throw_error(env, nullptr, "Invalid database handle");
+		return nullptr;
+	}
+
+	NAPI_RETURN_UNDEFINED();
+}
+
 /**
  * Drops the RocksDB database column family asynchronously. If the column family
  * is the default, it will clear the database instead.
@@ -639,6 +668,7 @@ napi_value Database::GetDBIntProperty(napi_env env, napi_callback_info info) {
 napi_value Database::GetSync(napi_env env, napi_callback_info info) {
 	NAPI_METHOD_ARGV(3);
 	UNWRAP_DB_HANDLE_AND_OPEN();
+
 	// we store this in key slice (no copying) because we are synchronously using the key
 	rocksdb::Slice keySlice;
 	if (!rocksdb_js::getSliceFromArg(env, argv[0], keySlice, (*dbHandle)->defaultKeyBufferPtr, "Key must be a buffer")) {
@@ -906,6 +936,11 @@ napi_value Database::Open(napi_env env, napi_callback_info info) {
 
 	try {
 		(*dbHandle)->open(path, dbHandleOptions);
+
+		// now that the database is open and the dbHandle has a reference to
+		// the descriptor, we can attach the database instance's smart_ptr to
+		// the descriptor so it gets cleaned up when the descriptor is closed
+		(*dbHandle)->descriptor->attach(*dbHandle);
 	} catch (const std::exception& e) {
 		DEBUG_LOG("%p Database::Open Error: %s\n", dbHandle->get(), e.what());
 		::napi_throw_error(env, nullptr, e.what());
@@ -1156,6 +1191,7 @@ void Database::Init(napi_env env, napi_value exports) {
 		{ "clear", nullptr, Clear, nullptr, nullptr, nullptr, napi_default, nullptr },
 		{ "clearSync", nullptr, ClearSync, nullptr, nullptr, nullptr, napi_default, nullptr },
 		{ "close", nullptr, Close, nullptr, nullptr, nullptr, napi_default, nullptr },
+		{ "destroy", nullptr, Destroy, nullptr, nullptr, nullptr, napi_default, nullptr },
 		{ "drop", nullptr, Drop, nullptr, nullptr, nullptr, napi_default, nullptr },
 		{ "dropSync", nullptr, DropSync, nullptr, nullptr, nullptr, napi_default, nullptr },
 		{ "flush", nullptr, Flush, nullptr, nullptr, nullptr, napi_default, nullptr },

src/binding/database.h

@@ -43,6 +43,7 @@ struct Database final {
 	static napi_value Clear(napi_env env, napi_callback_info info);
 	static napi_value ClearSync(napi_env env, napi_callback_info info);
 	static napi_value Close(napi_env env, napi_callback_info info);
+	static napi_value Destroy(napi_env env, napi_callback_info info);
 	static napi_value Drop(napi_env env, napi_callback_info info);
 	static napi_value DropSync(napi_env env, napi_callback_info info);
 	static napi_value Flush(napi_env env, napi_callback_info info);

src/binding/db_descriptor.cpp

@@ -130,37 +130,14 @@ DBDescriptor::DBDescriptor(
  * (transactions, iterators, etc).
  */
 DBDescriptor::~DBDescriptor() {
-	DEBUG_LOG("%p DBDescriptor::~DBDescriptor Closing \"%s\" (closables=%zu columns=%zu transactions=%zu transactionLogStores=%zu)\n",
-		this, this->path.c_str(), this->closables.size(), this->columns.size(), this->transactions.size(), this->transactionLogStores.size());
-
-	std::unique_lock<std::mutex> txnsLock(this->txnsMutex);
-
-	while (!this->closables.empty()) {
-		Closable* handle = *this->closables.begin();
-		DEBUG_LOG("%p DBDescriptor::~DBDescriptor Closing closable %p\n", this, handle);
-		this->closables.erase(handle);
-
-		// release the mutex before calling close() to avoid a deadlock
-		txnsLock.unlock();
-		handle->close();
-		txnsLock.lock();
-	}
-
-	if (!this->transactionLogStores.empty()) {
-		std::lock_guard<std::mutex> logLock(this->transactionLogMutex);
-		DEBUG_LOG("%p DBDescriptor::~DBDescriptor Closing transaction log stores (size=%zu)\n", this, this->transactionLogStores.size());
-		for (auto& [name, transactionLogStore] : this->transactionLogStores) {
-			DEBUG_LOG("%p DBDescriptor::~DBDescriptor Closing transaction log store \"%s\"\n", this, name.c_str());
-			transactionLogStore->close();
-		}
-		this->transactionLogStores.clear();
-	}
-
-	this->transactions.clear();
-	this->columns.clear();
-	this->db.reset();
+	DEBUG_LOG("%p DBDescriptor::~DBDescriptor Closing \"%s\"\n", this, this->path.c_str());
+	this->close();
 }
 
+/**
+ * Close the database descriptor and any resources associated with it
+ * (transactions, iterators, etc).
+ */
 void DBDescriptor::close() {
 	// check if already closing
 	if (this->closing.exchange(true)) {
@@ -181,23 +158,58 @@ void DBDescriptor::close() {
 	// trigger a flush
 	rocksdb::WaitForCompactOptions options;
 	this->db->WaitForCompact(options);
+
+	std::unique_lock<std::mutex> txnsLock(this->txnsMutex);
+
+	// Close all handles that still exist and reset their descriptor references
+	for (auto it = this->closables.begin(); it != this->closables.end(); ) {
+		if (auto closable = it->second.lock()) {
+			// Remove from map before closing to avoid re-entrant detach() calls
+			it = this->closables.erase(it);
+
+			// Release mutex during close to avoid deadlocks
+			txnsLock.unlock();
+			closable->close();
+			txnsLock.lock();
+		} else {
+			// Handle was already GC'd, just remove the expired weak_ptr
+			it = this->closables.erase(it);
+		}
+	}
+
+	if (!this->transactionLogStores.empty()) {
+		std::lock_guard<std::mutex> logLock(this->transactionLogMutex);
+		DEBUG_LOG("%p DBDescriptor::~DBDescriptor Closing transaction log stores (size=%zu)\n", this, this->transactionLogStores.size());
+		for (auto& [name, transactionLogStore] : this->transactionLogStores) {
+			DEBUG_LOG("%p DBDescriptor::~DBDescriptor Closing transaction log store \"%s\"\n", this, name.c_str());
+			transactionLogStore->close();
+		}
+		this->transactionLogStores.clear();
+	}
+
+	this->transactions.clear();
+	this->columns.clear();
+	this->db.reset();
 }
 
 /**
  * Registers a database resource to be closed when the descriptor is closed.
+ *
+ * Important: The closable must be same smart_ptr that is napi-wrapped and
+ * bound to the JavaScript class counterpart.
  */
-void DBDescriptor::attach(Closable* closable) {
+void DBDescriptor::attach(std::shared_ptr<Closable> closable) {
 	std::lock_guard<std::mutex> lock(this->txnsMutex);
-	this->closables.insert(closable);
+	this->closables[closable.get()] = std::weak_ptr<Closable>(closable);
 }
 
 /**
  * Unregisters a database resource from being closed when the descriptor is
  * closed.
  */
-void DBDescriptor::detach(Closable* closable) {
+void DBDescriptor::detach(std::shared_ptr<Closable> closable) {
 	std::lock_guard<std::mutex> lock(this->txnsMutex);
-	this->closables.erase(closable);
+	this->closables.erase(closable.get());
 }
 
 /**
@@ -573,7 +585,7 @@ void DBDescriptor::transactionAdd(std::shared_ptr<TransactionHandle> txnHandle)
 	auto id = txnHandle->id;
 	std::lock_guard<std::mutex> lock(this->txnsMutex);
 	this->transactions.emplace(id, txnHandle);
-	this->closables.insert(txnHandle.get());
+	this->closables[txnHandle.get()] = std::weak_ptr<Closable>(txnHandle);
 }
 
 /**

src/binding/db_descriptor.h

@@ -93,7 +93,7 @@ struct DBDescriptor final : public std::enable_shared_from_this<DBDescriptor> {
 	/**
 	 * Set of closables to be closed when the descriptor is closed.
 	 */
-	std::set<Closable*> closables;
+	std::map<Closable*, std::weak_ptr<Closable>> closables;
 
 	/**
 	 * Mutex to protect the locks map.
@@ -166,24 +166,24 @@ struct DBDescriptor final : public std::enable_shared_from_this<DBDescriptor> {
 	std::mutex transactionLogMutex;
 
 private:
-    DBDescriptor(
-        const std::string& path,
-        const DBOptions& options,
-        std::shared_ptr<rocksdb::DB> db,
-        std::unordered_map<std::string, std::shared_ptr<rocksdb::ColumnFamilyHandle>>&& columns
-    );
+	DBDescriptor(
+		const std::string& path,
+		const DBOptions& options,
+		std::shared_ptr<rocksdb::DB> db,
+		std::unordered_map<std::string, std::shared_ptr<rocksdb::ColumnFamilyHandle>>&& columns
+	);
 
 	void discoverTransactionLogStores();
 
 public:
-    static std::shared_ptr<DBDescriptor> open(const std::string& path, const DBOptions& options);
-    ~DBDescriptor();
+	static std::shared_ptr<DBDescriptor> open(const std::string& path, const DBOptions& options);
+	~DBDescriptor();
 
 	void close();
 	bool isClosing() const { return this->closing.load(); }
 
-	void attach(Closable* closable);
-	void detach(Closable* closable);
+	void attach(std::shared_ptr<Closable> closable);
+	void detach(std::shared_ptr<Closable> closable);
 
 	void lockCall(
 		napi_env env,
@@ -388,8 +388,8 @@ struct ListenerCallback final {
 	 */
 	std::weak_ptr<DBHandle> owner;
 
-    ListenerCallback(napi_env env, napi_threadsafe_function tsfn, napi_ref callbackRef, std::weak_ptr<DBHandle> owner = {})
-        : env(env), threadsafeCallback(tsfn), callbackRef(callbackRef), owner(owner) {}
+	ListenerCallback(napi_env env, napi_threadsafe_function tsfn, napi_ref callbackRef, std::weak_ptr<DBHandle> owner = {})
+		: env(env), threadsafeCallback(tsfn), callbackRef(callbackRef), owner(owner) {}
 
 	// move constructor
 	ListenerCallback(ListenerCallback&& other) noexcept