@barakxyz/better-sqlite3 12.6.2 → 12.7.0

package/lib/database.js

@@ -77,6 +77,7 @@ Database.prototype.transaction = require('./methods/transaction');
 Database.prototype.pragma = require('./methods/pragma');
 Database.prototype.backup = require('./methods/backup');
 Database.prototype.serialize = require('./methods/serialize');
+Database.prototype.deserialize = require('./methods/deserialize');
 Database.prototype.function = require('./methods/function');
 Database.prototype.aggregate = require('./methods/aggregate');
 Database.prototype.table = require('./methods/table');

package/lib/methods/deserialize.js

@@ -0,0 +1,35 @@
+'use strict';
+const { cppdb } = require('../util');
+
+/**
+ * Deserialize a buffer into the database.
+ *
+ * Uses the safe pattern:
+ * 1. Create temp in-memory database
+ * 2. Deserialize buffer into temp
+ * 3. Backup from temp to current database
+ * 4. Close temp database
+ *
+ * This preserves file-based persistence and matches wa-sqlite's import pattern.
+ * REF: packages/@livestore/sqlite-wasm/src/make-sqlite-db.ts import implementation
+ *
+ * @param {Buffer} buffer - The serialized database buffer
+ * @param {Object} [options] - Options object
+ * @param {string} [options.attached='main'] - The attached database name
+ * @returns {this} The database instance for chaining
+ */
+module.exports = function deserialize(buffer, options) {
+	if (options == null) options = {};
+
+	// Validate arguments
+	if (!Buffer.isBuffer(buffer)) throw new TypeError('Expected first argument to be a buffer');
+	if (typeof options !== 'object') throw new TypeError('Expected second argument to be an options object');
+
+	// Interpret and validate options
+	const attachedName = 'attached' in options ? options.attached : 'main';
+	if (typeof attachedName !== 'string') throw new TypeError('Expected the "attached" option to be a string');
+	if (!attachedName) throw new TypeError('The "attached" option cannot be an empty string');
+
+	this[cppdb].deserialize(buffer, attachedName);
+	return this; // Return the JS Database instance for chaining
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barakxyz/better-sqlite3",
-  "version": "12.6.2",
+  "version": "12.7.0",
   "description": "The fastest and simplest library for SQLite in Node.js. Fork with session extension enabled.",
   "homepage": "https://github.com/BarakXYZ/better-sqlite3",
   "author": "Joshua Wise <joshuathomaswise@gmail.com>",

package/src/objects/database.cpp

@@ -132,6 +132,7 @@ INIT(Database::Init) {
 	SetPrototypeMethod(isolate, data, t, "exec", JS_exec);
 	SetPrototypeMethod(isolate, data, t, "backup", JS_backup);
 	SetPrototypeMethod(isolate, data, t, "serialize", JS_serialize);
+	SetPrototypeMethod(isolate, data, t, "deserialize", JS_deserialize);
 	SetPrototypeMethod(isolate, data, t, "function", JS_function);
 	SetPrototypeMethod(isolate, data, t, "aggregate", JS_aggregate);
 	SetPrototypeMethod(isolate, data, t, "table", JS_table);
@@ -295,6 +296,100 @@ NODE_METHOD(Database::JS_serialize) {
 	);
 }
 
+NODE_METHOD(Database::JS_deserialize) {
+	// Deserialize a buffer into the current database using the safe pattern:
+	// 1. Create temp in-memory database
+	// 2. Deserialize buffer into temp
+	// 3. Backup from temp to current database
+	// 4. Close temp database
+	//
+	// This preserves file-based persistence and matches wa-sqlite's import pattern.
+	// REF: packages/@livestore/sqlite-wasm/src/make-sqlite-db.ts import implementation
+	// REF: packages/@livestore/wa-sqlite/src/sqlite-api.js backup function
+
+	Database* db = Unwrap<Database>(info.This());
+	REQUIRE_DATABASE_OPEN(db);
+	REQUIRE_DATABASE_NOT_BUSY(db);
+	REQUIRE_DATABASE_NO_ITERATORS(db);
+
+	UseAddon;
+	UseIsolate;
+
+	// First argument: buffer containing serialized database
+	v8::Local<v8::Value> bufferArg = info[0];
+	if (!node::Buffer::HasInstance(bufferArg)) {
+		ThrowTypeError("Expected first argument to be a buffer");
+		return;
+	}
+	v8::Local<v8::Object> buffer = bufferArg.As<v8::Object>();
+
+	// Second argument: attached database name (default "main")
+	v8::Local<v8::String> attachedName;
+	if (info.Length() > 1 && !info[1]->IsUndefined()) {
+		if (!info[1]->IsString()) {
+			ThrowTypeError("Expected second argument to be a string");
+			return;
+		}
+		attachedName = info[1].As<v8::String>();
+	} else {
+		attachedName = StringFromUtf8(isolate, "main", -1);
+	}
+	v8::String::Utf8Value attached_name(isolate, attachedName);
+
+	// Step 1: Create a temporary in-memory database
+	sqlite3* temp_handle;
+	int status = sqlite3_open_v2(":memory:", &temp_handle, SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE, NULL);
+	if (status != SQLITE_OK) {
+		ThrowSqliteError(addon, "Failed to create temporary database", status);
+		return;
+	}
+
+	// Step 2: Deserialize the buffer into the temporary database
+	size_t length = node::Buffer::Length(buffer);
+	unsigned char* data = (unsigned char*)sqlite3_malloc64(length);
+	unsigned int flags = SQLITE_DESERIALIZE_FREEONCLOSE | SQLITE_DESERIALIZE_RESIZEABLE;
+
+	if (length) {
+		if (!data) {
+			sqlite3_close(temp_handle);
+			ThrowError("Out of memory");
+			return;
+		}
+		memcpy(data, node::Buffer::Data(buffer), length);
+	}
+
+	status = sqlite3_deserialize(temp_handle, "main", data, length, length, flags);
+	if (status != SQLITE_OK) {
+		sqlite3_close(temp_handle);
+		ThrowSqliteError(addon, status == SQLITE_ERROR ? "unable to deserialize database" : sqlite3_errstr(status), status);
+		return;
+	}
+
+	// Step 3: Backup from temp to current database
+	// sqlite3_backup_init(dest, destName, source, sourceName)
+	// REF: wa-sqlite sqlite-api.js - backup(dest, destName, source, sourceName)
+	sqlite3_backup* backup_handle = sqlite3_backup_init(db->db_handle, *attached_name, temp_handle, "main");
+	if (backup_handle == NULL) {
+		sqlite3_close(temp_handle);
+		db->ThrowDatabaseError();
+		return;
+	}
+
+	// Copy all pages in one step (-1 = all pages)
+	status = sqlite3_backup_step(backup_handle, -1);
+	sqlite3_backup_finish(backup_handle);
+
+	// Step 4: Close temporary database
+	sqlite3_close(temp_handle);
+
+	if (status != SQLITE_DONE) {
+		ThrowSqliteError(addon, "Failed to restore database from buffer", status);
+		return;
+	}
+
+	info.GetReturnValue().Set(info.This());
+}
+
 NODE_METHOD(Database::JS_function) {
 	Database* db = Unwrap<Database>(info.This());
 	REQUIRE_ARGUMENT_FUNCTION(first, v8::Local<v8::Function> fn);

package/src/objects/database.hpp

@@ -81,6 +81,7 @@ private:
 	static NODE_METHOD(JS_exec);
 	static NODE_METHOD(JS_backup);
 	static NODE_METHOD(JS_serialize);
+	static NODE_METHOD(JS_deserialize);
 	static NODE_METHOD(JS_function);
 	static NODE_METHOD(JS_aggregate);
 	static NODE_METHOD(JS_table);

package/src/objects/session.cpp

@@ -30,6 +30,7 @@ INIT(Session::Init) {
 	v8::Local<v8::FunctionTemplate> t = NewConstructorTemplate(isolate, data, JS_new, "Session");
 	SetPrototypeMethod(isolate, data, t, "attach", JS_attach);
 	SetPrototypeMethod(isolate, data, t, "changeset", JS_changeset);
+	SetPrototypeMethod(isolate, data, t, "enable", JS_enable);
 	SetPrototypeMethod(isolate, data, t, "close", JS_close);
 	return t->GetFunction(OnlyContext).ToLocalChecked();
 }
@@ -92,6 +93,24 @@ NODE_METHOD(Session::JS_attach) {
 	}
 }
 
+NODE_METHOD(Session::JS_enable) {
+	Session* session = Unwrap<Session>(info.This());
+	if (!session->alive) return ThrowTypeError("The session has been closed");
+	REQUIRE_DATABASE_OPEN(session->db->GetState());
+
+	UseIsolate;
+
+	// Require a boolean argument (matches wa-sqlite API pattern)
+	if (info.Length() < 1 || !info[0]->IsBoolean()) {
+		return ThrowTypeError("Expected first argument to be a boolean");
+	}
+
+	int enable_flag = info[0]->BooleanValue(isolate) ? 1 : 0;
+	sqlite3session_enable(session->session_handle, enable_flag);
+
+	// Return void (matches wa-sqlite API)
+}
+
 // Custom destructor for sqlite3_free
 static void FreeSqliteMemory(char* data, void* hint) {
 	sqlite3_free(data);

package/src/objects/session.hpp

@@ -24,6 +24,7 @@ private:
 	static NODE_METHOD(JS_new);
 	static NODE_METHOD(JS_attach);
 	static NODE_METHOD(JS_changeset);
+	static NODE_METHOD(JS_enable);
 	static NODE_METHOD(JS_close);
 
 	Database* const db;