@graphscope-neug/osx-arm64 0.1.3 → 0.2.0

package/CMakeLists.txt

@@ -93,16 +93,19 @@ if (APPLE)
 endif()
 
 # Set RPATH so neug_node_bind.node can find libneug.so / libneug.dylib
-# in the same directory (prebuilds/<platform>/). This is essential for
-# npm-distributed packages where the shared lib is bundled alongside the .node file.
-if (APPLE)
-  set_target_properties(neug_node_bind PROPERTIES
-    INSTALL_RPATH "@loader_path"
-    BUILD_WITH_INSTALL_RPATH TRUE
-  )
+# in the same directory (build/Release/<platform>/). Package builds retain
+# CMake's build-tree RPATHs until dependencies are bundled. Those paths identify
+# the exact libraries selected by the linker; the platform bundle step copies them
+# into the package and replaces non-portable RPATHs before npm pack runs.
+if(APPLE)
+  set(_neug_node_rpath "@loader_path")
 else()
-  set_target_properties(neug_node_bind PROPERTIES
-    INSTALL_RPATH "$ORIGIN"
-    BUILD_WITH_INSTALL_RPATH TRUE
-  )
+  set(_neug_node_rpath "$ORIGIN")
 endif()
+
+set_target_properties(neug_node_bind PROPERTIES
+  BUILD_RPATH "${_neug_node_rpath}"
+  INSTALL_RPATH "${_neug_node_rpath}"
+  BUILD_WITH_INSTALL_RPATH FALSE
+)
+set_property(TARGET neug APPEND PROPERTY BUILD_RPATH "${_neug_node_rpath}")

package/README.md

@@ -4,11 +4,26 @@
 
 Same system dependencies as NeuG (CMake >= 3.16, C++20 compiler), plus:
 
-- Node.js >= 18.0.0
+- Node.js >= 20.0.0
+- macOS package builds only: `delocate==0.13.0`
+- Linux package builds only: `ldd` and `patchelf==0.19.0`
+
+Install the macOS packaging dependency with:
+
+```bash
+python3 -m pip install delocate==0.13.0
+```
+
+On Linux, install `patchelf==0.19.0` from the system package manager or the
+[official releases](https://github.com/NixOS/patchelf/releases):
+
+```bash
+patchelf --version
+```
 
 ### Installing Node.js
 
-NeuG Node.js bindings require **Node.js >= 18.0.0** (N-API v8). Install via nvm:
+NeuG Node.js bindings require **Node.js >= 20.0.0** (N-API v8). Install via nvm:
 
 ```bash
 # Install nvm
@@ -21,11 +36,11 @@ source ~/.zshrc
 
 # Install Node.js LTS (v22)
 nvm install --lts && nvm use --lts
-# Or install a specific version (>= 18)
-nvm install 18 && nvm use 18
+# Or install a specific version (>= 20)
+nvm install 20 && nvm use 20
 
 # Verify
-node -v   # should be >= 18.0.0
+node -v   # should be >= 20.0.0
 npm -v
 ```
 
@@ -43,7 +58,6 @@ This will:
 2. Build the native addon via the main NeuG CMake project (`-DBUILD_NODEJS=ON`)
 3. Copy the resulting `neug_node_bind.node` to `build/Release/`
 
-
 ### Pack
 
 ```bash
@@ -53,16 +67,26 @@ make pack
 Create a self-contained, distributable npm package tarball (`.tgz`). This will:
 
 1. Build the native addon (same as `make build`)
-2. Copy prebuilt binaries into `prebuilds/<platform>/`:
+2. Copy NeuG's first-party binaries into `build/Release/<platform>/`:
    - `neug_node_bind.node` — the native addon
-   - `libneug.so` — core shared library
-   - `libmimalloc.so.2` — memory allocator
-3. Run `npm pack` to produce `neug-<version>.tgz`
+   - `libneug.so` / `libneug.dylib` — core shared library
+3. Collect the third-party libraries actually selected at link time:
+   - macOS uses `delocate-path` to copy them into `.dylibs/` and rewrite their
+     install names.
+   - Linux uses `ldd` to resolve the dependency closure, copies non-system
+     libraries into `.libs/`, and uses `patchelf` to set package-relative
+     `$ORIGIN` RPATHs.
+4. Print the bundled native dependencies for inspection.
+5. Run `npm pack` to produce `neug-<version>.tgz`
+
+Npm package builds always force `NEUG_PACKAGE_BUILD=ON` and
+`NEUG_NATIVE_ARCH=OFF`.
+For local source builds, use `NEUG_NATIVE_ARCH=ON make dev`.
 
 The resulting tarball can be installed without a C++ build environment:
 
 ```bash
-npm install ./neug-0.1.3.tgz
+npm install ./neug-0.2.0.tgz
 ```
 
  
@@ -83,7 +107,7 @@ node example.js
 
 
 ```js
-const { Database } = require('./lib');
+const { Database } = require('neug');
 
 // Open an in-memory database
 const db = new Database({ databasePath: '', mode: 'w' });
@@ -114,3 +138,30 @@ for (const row of result) {
 conn.close();
 db.close();
 ```
+
+## Explicit Transactions
+
+Since v0.2, the embedded Node.js `Connection` API supports explicit AP
+transactions. Auto-commit remains the default; begin a transaction only when
+multiple ordinary queries must share one private view and one final commit.
+
+```js
+const conn = db.connect();
+
+conn.beginTransaction();
+conn.execute("CREATE (p:person {id: 3, name: 'Carol'});");
+// Reads on this connection see the new vertex before publication.
+conn.execute('MATCH (p:person) RETURN p.name;');
+conn.commit();
+
+conn.beginTransaction({ readOnly: true });
+// This transaction pins one read view and rejects writes.
+conn.execute('MATCH (p:person) RETURN p.name;');
+conn.rollback();
+```
+
+`hasActiveTransaction` remains true after a failed statement because the
+connection is rollback-only. Call `rollback()` before issuing another query.
+Nested transactions, read-to-write upgrades, Cypher `BEGIN`/`COMMIT`/`ROLLBACK`,
+and explicit-transaction COPY, batch, index, checkpoint, procedure, and
+temporary-schema operations are not supported.

package/lib/connection.js

@@ -59,6 +59,64 @@ class Connection {
     }
   }
 
+  /**
+   * Whether this connection has an unfinished explicit transaction.
+   *
+   * The property remains true while a failed transaction is rollback-only.
+   * Call {@link rollback} before issuing another query.
+   *
+   * @returns {boolean}
+   */
+  get hasActiveTransaction() {
+    return this._isOpen && this._conn.hasActiveTransaction();
+  }
+
+  /**
+   * Begin an explicit embedded AP transaction.
+   *
+   * @param {{readOnly?: boolean}} [options={}] Transaction options.
+   * @param {boolean} [options.readOnly=false] Pin one read view and reject
+   *   writes. By default, the transaction uses a private COW write view.
+   * @throws {Error} If the connection is closed or already has an active
+   *   transaction.
+   */
+  beginTransaction(options = {}) {
+    this._ensureOpen('beginning a transaction');
+    if (
+      typeof options !== 'object' ||
+      options === null ||
+      Array.isArray(options)
+    ) {
+      throw new TypeError('Transaction options must be an object.');
+    }
+    const { readOnly = false } = options;
+    if (typeof readOnly !== 'boolean') {
+      throw new TypeError('options.readOnly must be a boolean.');
+    }
+    this._checkTransactionStatus(
+      'begin transaction',
+      this._conn.beginTransaction(readOnly)
+    );
+  }
+
+  /**
+   * Commit the active explicit transaction.
+   *
+   * A rollback-only transaction must be rolled back instead.
+   */
+  commit() {
+    this._ensureOpen('committing a transaction');
+    this._checkTransactionStatus('commit transaction', this._conn.commit());
+  }
+
+  /**
+   * Roll back the active explicit transaction and return to auto-commit mode.
+   */
+  rollback() {
+    this._ensureOpen('rolling back a transaction');
+    this._checkTransactionStatus('roll back transaction', this._conn.rollback());
+  }
+
   /**
    * Execute a cypher query on the database.
    *
@@ -81,12 +139,7 @@ class Connection {
    * );
    */
   execute(query, accessMode = '', parameters = null) {
-    if (!this._isOpen) {
-      throw new Error(
-        `Connection is closed. Please open the connection before executing queries. ` +
-        `Error code: ${ERR_CONNECTION_CLOSED}`
-      );
-    }
+    this._ensureOpen('executing queries');
 
     if (accessMode !== '' && !isAccessModeValid(accessMode.toLowerCase())) {
       throw new Error(
@@ -120,8 +173,27 @@ class Connection {
    * @returns {string} The schema as a string.
    */
   getSchema() {
+    this._ensureOpen('getting the schema');
     return this._conn.getSchema();
   }
+
+  _ensureOpen(action) {
+    if (!this._isOpen) {
+      throw new Error(
+        `Connection is closed. Please open the connection before ${action}. ` +
+        `Error code: ${ERR_CONNECTION_CLOSED}`
+      );
+    }
+  }
+
+  _checkTransactionStatus(action, status) {
+    if (status.code !== OK) {
+      throw new Error(
+        `Failed to ${action}. Error code: ${status.code}, Error Message: ` +
+        `${codeName(status.code)}: ${status.message}`
+      );
+    }
+  }
 }
 
 module.exports = { Connection };

package/lib/error-codes.js

@@ -29,7 +29,7 @@
 const { Code } = require('./proto/error_pb');
 
 // ---- Numeric error code constants (from error.proto Code enum) ----
-// General errors (1001-1017)
+// General errors (1001-1018)
 const OK                    = Code.OK;
 const ERR_PERMISSION        = Code.ERR_PERMISSION;
 const ERR_VERSION_MISMATCHED = Code.ERR_VERSION_MISMATCHED;
@@ -48,6 +48,7 @@ const ERR_IO_ERROR          = Code.ERR_IO_ERROR;
 const ERR_BAD_ENCODING      = Code.ERR_BAD_ENCODING;
 const ERR_INVALID_FILE      = Code.ERR_INVALID_FILE;
 const ERR_EXTENSION         = Code.ERR_EXTENSION;
+const ERR_NO_CHECKPOINT     = Code.ERR_NO_CHECKPOINT;
 
 // Network errors (2001-2007)
 const ERR_NETWORK           = Code.ERR_NETWORK;
@@ -122,6 +123,7 @@ module.exports = {
   ERR_BAD_ENCODING,
   ERR_INVALID_FILE,
   ERR_EXTENSION,
+  ERR_NO_CHECKPOINT,
   // Network errors
   ERR_NETWORK,
   ERR_SESSION_CLOSED,

package/lib/proto/error_pb.js

@@ -39,6 +39,7 @@ const Code = Object.create(
     [1015, 'ERR_BAD_ENCODING'],
     [1016, 'ERR_INVALID_FILE'],
     [1017, 'ERR_EXTENSION'],
+    [1018, 'ERR_NO_CHECKPOINT'],
     [2001, 'ERR_NETWORK'],
     [2002, 'ERR_SESSION_CLOSED'],
     [2003, 'ERR_CONNECTION_CLOSED'],
@@ -90,6 +91,7 @@ Code.ERR_IO_ERROR             = 1014;
 Code.ERR_BAD_ENCODING         = 1015;
 Code.ERR_INVALID_FILE         = 1016;
 Code.ERR_EXTENSION            = 1017;
+Code.ERR_NO_CHECKPOINT        = 1018;
 Code.ERR_NETWORK              = 2001;
 Code.ERR_SESSION_CLOSED       = 2002;
 Code.ERR_CONNECTION_CLOSED    = 2003;

package/lib/query-result.js

@@ -106,6 +106,18 @@ class QueryResult {
     this._result.close();
   }
 
+  /**
+   * Get the profile/explain result as a structured metrics object.
+   * @returns {{ total_elapsed_ms: number, total_output_rows: number, operators: Array }} Metrics object.
+   */
+  getProfileMetrics() {
+    const metrics = this._result.getProfileMetrics();
+    if (!metrics.operators) {
+      metrics.operators = [];
+    }
+    return metrics;
+  }
+
   /**
    * Make QueryResult iterable with for...of loops.
    * @returns {Iterator} An iterator over the result rows.

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@graphscope-neug/osx-arm64",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "NeuG Graph Database Node.js bindings - high performance embedded graph database with Cypher query support",
   "main": "lib/index.js",
+  "exports": "./lib/index.js",
   "scripts": {
-    "test": "for f in tests/test_*.js; do echo \"Running $f\"; node \"$f\" || exit 1; done"
+    "test": "node tests/test-shim.js"
   },
   "keywords": [
     "graph",
@@ -23,7 +24,7 @@
     "url": "git+https://github.com/alibaba/neug.git"
   },
   "engines": {
-    "node": ">=16.0.0"
+    "node": ">=20.0.0"
   },
   "dependencies": {
     "node-addon-api": "^7.0.0"

package/src/node_connection.cc

@@ -29,6 +29,21 @@
 
 namespace neug {
 
+namespace {
+
+Napi::Object StatusToJs(Napi::Env env, const Status& status) {
+  auto result = Napi::Object::New(env);
+  result.Set("code", Napi::Number::New(env, status.error_code()));
+  result.Set("message", Napi::String::New(env, status.error_message()));
+  return result;
+}
+
+Status ClosedConnectionStatus() {
+  return Status(StatusCode::ERR_CONNECTION_CLOSED, "Connection is closed.");
+}
+
+}  // namespace
+
 Napi::FunctionReference NodeConnection::constructor;
 
 Napi::Object NodeConnection::Init(Napi::Env env, Napi::Object exports) {
@@ -36,6 +51,11 @@ Napi::Object NodeConnection::Init(Napi::Env env, Napi::Object exports) {
       env, "NodeConnection",
       {
           InstanceMethod("execute", &NodeConnection::Execute),
+          InstanceMethod("beginTransaction", &NodeConnection::BeginTransaction),
+          InstanceMethod("commit", &NodeConnection::Commit),
+          InstanceMethod("rollback", &NodeConnection::Rollback),
+          InstanceMethod("hasActiveTransaction",
+                         &NodeConnection::HasActiveTransaction),
           InstanceMethod("getSchema", &NodeConnection::GetSchema),
           InstanceMethod("close", &NodeConnection::Close),
       });
@@ -81,7 +101,7 @@ Napi::Value NodeConnection::Execute(const Napi::CallbackInfo& info) {
   }
 
   // Parse parameters from JavaScript object
-  rapidjson::Document params_json;
+  rapidjson::Document params_json(rapidjson::kObjectType);
   if (info.Length() >= 3 && info[2].IsObject()) {
     Napi::Object params_obj = info[2].As<Napi::Object>();
     Napi::Array keys = params_obj.GetPropertyNames();
@@ -99,13 +119,53 @@ Napi::Value NodeConnection::Execute(const Napi::CallbackInfo& info) {
   return NodeQueryResult::NewInstance(env, std::move(query_result.value()));
 }
 
+Napi::Value NodeConnection::BeginTransaction(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() > 1 || (info.Length() == 1 && !info[0].IsBoolean())) {
+    Napi::TypeError::New(env, "readOnly must be a boolean")
+        .ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  const bool read_only =
+      info.Length() == 1 && info[0].As<Napi::Boolean>().Value();
+  const auto status =
+      conn_ ? conn_->BeginTransaction(read_only ? TransactionMode::kReadOnly
+                                                : TransactionMode::kReadWrite)
+            : ClosedConnectionStatus();
+  return StatusToJs(env, status);
+}
+
+Napi::Value NodeConnection::Commit(const Napi::CallbackInfo& info) {
+  const auto status = conn_ ? conn_->Commit() : ClosedConnectionStatus();
+  return StatusToJs(info.Env(), status);
+}
+
+Napi::Value NodeConnection::Rollback(const Napi::CallbackInfo& info) {
+  const auto status = conn_ ? conn_->Rollback() : ClosedConnectionStatus();
+  return StatusToJs(info.Env(), status);
+}
+
+Napi::Value NodeConnection::HasActiveTransaction(
+    const Napi::CallbackInfo& info) {
+  return Napi::Boolean::New(info.Env(), conn_ && conn_->HasActiveTransaction());
+}
+
 Napi::Value NodeConnection::GetSchema(const Napi::CallbackInfo& info) {
-  return Napi::String::New(info.Env(), conn_->GetSchema());
+  Napi::Env env = info.Env();
+  try {
+    return Napi::String::New(env, conn_->GetSchema());
+  } catch (const neug::exception::Exception& e) {
+    Napi::Error::New(env, e.what()).ThrowAsJavaScriptException();
+  } catch (const std::exception& e) {
+    Napi::Error::New(env, e.what()).ThrowAsJavaScriptException();
+  }
+  return env.Null();
 }
 
 Napi::Value NodeConnection::Close(const Napi::CallbackInfo& info) {
   if (conn_) {
-    db_->RemoveConnection(conn_);
+    conn_->Close();
     conn_.reset();
   }
   return info.Env().Undefined();

package/src/node_connection.h

@@ -21,7 +21,7 @@
 #include <memory>
 #include <string>
 
-#include "neug/execution/common/types/value.h"
+#include "neug/common/types/value.h"
 #include "neug/main/connection.h"
 #include "neug/main/neug_db.h"
 #include "node_query_result.h"
@@ -43,6 +43,10 @@ class NodeConnection : public Napi::ObjectWrap<NodeConnection> {
   static Napi::FunctionReference constructor;
 
   Napi::Value Execute(const Napi::CallbackInfo& info);
+  Napi::Value BeginTransaction(const Napi::CallbackInfo& info);
+  Napi::Value Commit(const Napi::CallbackInfo& info);
+  Napi::Value Rollback(const Napi::CallbackInfo& info);
+  Napi::Value HasActiveTransaction(const Napi::CallbackInfo& info);
   Napi::Value GetSchema(const Napi::CallbackInfo& info);
   Napi::Value Close(const Napi::CallbackInfo& info);
 

package/src/node_query_request.cc

@@ -18,7 +18,7 @@
 #include <sstream>
 #include <string>
 
-#include "neug/execution/common/types/value.h"
+#include "neug/common/types/value.h"
 #include "neug/main/query_request.h"
 #include "neug/utils/access_mode.h"
 #include "neug/utils/exception/exception.h"
@@ -64,8 +64,7 @@ rapidjson::Document napi_value_to_rapidjson_document(
   } else if (val.IsDate()) {
     // Convert Date to ISO string
     Napi::Object date_obj = val.As<Napi::Object>();
-    Napi::Function to_iso =
-        date_obj.Get("toISOString").As<Napi::Function>();
+    Napi::Function to_iso = date_obj.Get("toISOString").As<Napi::Function>();
     std::string iso_str =
         to_iso.Call(date_obj, {}).As<Napi::String>().Utf8Value();
     doc.SetString(iso_str.c_str(), iso_str.length(), allocator);
@@ -141,7 +140,7 @@ Napi::Value NodeQueryRequest::SerializeRequest(const Napi::CallbackInfo& info) {
                     rapidjson::Value(access_mode.c_str(), allocator),
                     allocator);
 
-  rapidjson::Document params_doc;
+  rapidjson::Document params_doc(rapidjson::kObjectType);
   if (info.Length() >= 3 && info[2].IsObject()) {
     Napi::Object params_obj = info[2].As<Napi::Object>();
     Napi::Array keys = params_obj.GetPropertyNames();

package/src/node_query_result.cc

@@ -41,6 +41,8 @@ Napi::Object NodeQueryResult::Init(Napi::Env env, Napi::Object exports) {
           InstanceMethod("statusMessage", &NodeQueryResult::StatusMessage),
           InstanceMethod("getBoltResponse", &NodeQueryResult::GetBoltResponse),
           InstanceMethod("close", &NodeQueryResult::Close),
+          InstanceMethod("getProfileMetrics",
+                         &NodeQueryResult::GetProfileMetrics),
           StaticMethod("fromString", &NodeQueryResult::FromString),
       });
   constructor = Napi::Persistent(func);
@@ -216,8 +218,7 @@ Napi::Value FetchValueFromColumn(Napi::Env env, const neug::Array& column,
       size_t offset = col.offsets(index);
       Napi::Array arr = Napi::Array::New(env, list_size);
       for (uint32_t i = 0; i < list_size; ++i) {
-        arr.Set(i,
-                FetchValueFromColumn(env, col.elements(), offset + i));
+        arr.Set(i, FetchValueFromColumn(env, col.elements(), offset + i));
       }
       return arr;
     } else {
@@ -332,9 +333,8 @@ Napi::Value NodeQueryResult::StatusMessage(const Napi::CallbackInfo& info) {
 
 Napi::Value NodeQueryResult::GetBoltResponse(const Napi::CallbackInfo& info) {
   auto names = column_names();
-  return Napi::String::New(info.Env(),
-                           results_to_bolt_response(query_result_.response(),
-                                                    names));
+  return Napi::String::New(
+      info.Env(), results_to_bolt_response(query_result_.response(), names));
 }
 
 Napi::Value NodeQueryResult::Close(const Napi::CallbackInfo& info) {
@@ -344,6 +344,51 @@ Napi::Value NodeQueryResult::Close(const Napi::CallbackInfo& info) {
   return info.Env().Undefined();
 }
 
+Napi::Value NodeQueryResult::GetProfileMetrics(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  Napi::Object result = Napi::Object::New(env);
+
+  if (!query_result_.response().has_profile_result()) {
+    return result;
+  }
+
+  const auto& profile_result = query_result_.response().profile_result();
+
+  // Add aggregate metrics
+  result.Set("total_elapsed_ms",
+             Napi::Number::New(env, profile_result.total_elapsed_ms()));
+  result.Set("total_output_rows",
+             Napi::Number::New(
+                 env, static_cast<double>(profile_result.total_output_rows())));
+
+  // Convert operators to array of objects
+  Napi::Array operators_array =
+      Napi::Array::New(env, profile_result.operators_size());
+  for (int i = 0; i < profile_result.operators_size(); ++i) {
+    const auto& op = profile_result.operators(i);
+    Napi::Object op_obj = Napi::Object::New(env);
+
+    op_obj.Set("operator_id", Napi::Number::New(env, op.operator_id()));
+    op_obj.Set("parent_id", Napi::Number::New(env, op.parent_id()));
+    op_obj.Set("operator_name", Napi::String::New(env, op.operator_name()));
+    op_obj.Set("elapsed_ms", Napi::Number::New(env, op.elapsed_ms()));
+    op_obj.Set("output_rows",
+               Napi::Number::New(env, static_cast<double>(op.output_rows())));
+
+    // Convert child_ids repeated field to array
+    Napi::Array child_ids_array = Napi::Array::New(env, op.child_ids_size());
+    for (int j = 0; j < op.child_ids_size(); ++j) {
+      child_ids_array.Set(j, Napi::Number::New(env, op.child_ids(j)));
+    }
+    op_obj.Set("child_ids", child_ids_array);
+
+    operators_array.Set(i, op_obj);
+  }
+  result.Set("operators", operators_array);
+
+  return result;
+}
+
 Napi::Value NodeQueryResult::FromString(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
   if (info.Length() < 1) {

package/src/node_query_result.h

@@ -60,6 +60,7 @@ class NodeQueryResult : public Napi::ObjectWrap<NodeQueryResult> {
   Napi::Value StatusMessage(const Napi::CallbackInfo& info);
   Napi::Value GetBoltResponse(const Napi::CallbackInfo& info);
   Napi::Value Close(const Napi::CallbackInfo& info);
+  Napi::Value GetProfileMetrics(const Napi::CallbackInfo& info);
   static Napi::Value FromString(const Napi::CallbackInfo& info);
 
   size_t index_{0};