@graphscope-neug/linux-x64 0.1.2

package/CMakeLists.txt

@@ -0,0 +1,111 @@
+# NeuG Node.js Bindings - CMake Build Configuration
+#
+# This file is built as a subdirectory of the main NeuG CMake project.
+# It requires neug_main and neug_proto targets to exist.
+#
+# Build from project root:
+#   mkdir -p build && cd build
+#   cmake .. -DBUILD_NODEJS=ON -DCMAKE_BUILD_TYPE=Release
+#   make -j$(nproc) neug_node_bind
+
+# Find Node.js headers by querying the node executable for its install prefix
+find_program(NODE_EXECUTABLE NAMES node nodejs)
+if (NOT NODE_EXECUTABLE)
+  message(FATAL_ERROR "Cannot find Node.js executable. Please install Node.js or set PATH.")
+endif()
+
+execute_process(
+  COMMAND ${NODE_EXECUTABLE} -p "require('path').resolve(process.execPath, '..', '..', 'include', 'node')"
+  OUTPUT_VARIABLE NODE_INCLUDE_HINT
+  OUTPUT_STRIP_TRAILING_WHITESPACE
+  ERROR_QUIET
+)
+
+find_path(NODE_INCLUDE_DIR node_api.h
+  HINTS ${NODE_INCLUDE_HINT} /usr/include/node /usr/local/include/node
+  PATH_SUFFIXES node
+)
+if (NOT NODE_INCLUDE_DIR)
+  message(FATAL_ERROR "Cannot find Node.js headers (node_api.h). Hint path: ${NODE_INCLUDE_HINT}")
+endif()
+
+# Find node-addon-api include path (if installed via npm)
+execute_process(
+  COMMAND ${NODE_EXECUTABLE} -p "require('node-addon-api').include"
+  WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+  OUTPUT_VARIABLE NODE_ADDON_API_DIR
+  OUTPUT_STRIP_TRAILING_WHITESPACE
+  ERROR_QUIET
+)
+string(REPLACE "\"" "" NODE_ADDON_API_DIR ${NODE_ADDON_API_DIR})
+
+file(GLOB_RECURSE SOURCE_CPP "${CMAKE_CURRENT_SOURCE_DIR}/src/*.cc")
+
+# Match Python binding: disable LTO to avoid GCC ICE with large static libs
+set(CMAKE_INTERPROCEDURAL_OPTIMIZATION FALSE)
+
+add_library(neug_node_bind MODULE ${SOURCE_CPP})
+set_target_properties(neug_node_bind PROPERTIES
+  PREFIX ""
+  SUFFIX ".node"
+)
+
+target_include_directories(neug_node_bind PRIVATE
+  ${NODE_INCLUDE_DIR}
+  ${NODE_ADDON_API_DIR}
+  ${CMAKE_CURRENT_SOURCE_DIR}/src
+  ${CMAKE_CURRENT_BINARY_DIR}/../../src/compiler
+)
+
+add_dependencies(neug_node_bind neug_proto)
+
+set(NEUG_LIBRARIES neug)
+if (BUILD_HTTP_SERVER)
+    set(NEUG_LIBRARIES ${NEUG_LIBRARIES})
+endif()
+
+find_package(OpenSSL REQUIRED)
+target_link_libraries(neug_node_bind PRIVATE
+  ${NEUG_LIBRARIES}
+  ${GLOG_LIBRARIES}
+  ${Protobuf_LIBRARIES}
+  OpenSSL::SSL
+  OpenSSL::Crypto
+)
+
+target_compile_definitions(neug_node_bind PRIVATE
+  NAPI_VERSION=8
+  NODE_ADDON_API_DISABLE_DEPRECATED
+  BUILDING_NODE_EXTENSION
+)
+
+if (CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+  target_compile_options(neug_node_bind PRIVATE -Wno-vla-extension)
+endif()
+
+# Hide protobuf/abseil/arrow symbols to avoid conflicts
+if (COMMAND neug_apply_symbol_visibility)
+  neug_apply_symbol_visibility(neug_node_bind)
+endif()
+
+# macOS: allow undefined symbols (Node.js resolves them at runtime)
+if (APPLE)
+  set_target_properties(neug_node_bind PROPERTIES
+    LINK_FLAGS "-undefined dynamic_lookup"
+  )
+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
+  )
+else()
+  set_target_properties(neug_node_bind PROPERTIES
+    INSTALL_RPATH "$ORIGIN"
+    BUILD_WITH_INSTALL_RPATH TRUE
+  )
+endif()

package/README.md

@@ -0,0 +1,116 @@
+# The Node.js binding API for NeuG
+
+## Prerequisites
+
+Same system dependencies as NeuG (CMake >= 3.16, C++20 compiler), plus:
+
+- Node.js >= 18.0.0
+
+### Installing Node.js
+
+NeuG Node.js bindings require **Node.js >= 18.0.0** (N-API v8). Install via nvm:
+
+```bash
+# Install nvm
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
+
+# Reload shell in Linux
+source ~/.bashrc
+# Or MacOS
+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
+
+# Verify
+node -v   # should be >= 18.0.0
+npm -v
+```
+
+## Building
+
+### Build
+
+```bash
+cd tools/nodejs_bind
+make build
+```
+
+This will:
+1. Install Node.js dependencies (`npm install`)
+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
+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>/`:
+   - `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`
+
+The resulting tarball can be installed without a C++ build environment:
+
+```bash
+npm install ./neug-0.1.2.tgz
+```
+
+ 
+### Clean
+
+```bash
+make clean
+```
+
+
+## API Example
+
+A complete runnable example is provided in [`example.js`](example.js):
+
+```bash
+node example.js
+```
+
+
+```js
+const { Database } = require('./lib');
+
+// Open an in-memory database
+const db = new Database({ databasePath: '', mode: 'w' });
+const conn = db.connect();
+
+// Create schema
+conn.execute('CREATE NODE TABLE person(id INT64, name STRING, age INT32, PRIMARY KEY(id));');
+conn.execute('CREATE REL TABLE knows(FROM person TO person, since INT64);');
+
+// Insert vertices
+conn.execute("CREATE (p:person {id: 1, name: 'Alice', age: 30});");
+conn.execute("CREATE (p:person {id: 2, name: 'Bob', age: 25});");
+
+// Insert edge
+conn.execute(
+  "MATCH (a:person), (b:person) WHERE a.name = 'Alice' AND b.name = 'Bob' " +
+  "CREATE (a)-[:knows {since: 2020}]->(b);"
+);
+
+// Query
+const result = conn.execute(
+  'MATCH (a:person)-[r:knows]->(b:person) RETURN a.name, r.since, b.name;'
+);
+for (const row of result) {
+  console.log(row);
+}
+
+conn.close();
+db.close();
+```

package/lib/async-connection.js

@@ -0,0 +1,90 @@
+/** Copyright 2020 Alibaba Group Holding Limited.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * 	http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+'use strict';
+
+const { QueryResult } = require('./query-result');
+
+/**
+ * AsyncConnection provides an asynchronous interface to interact with the NeuG database.
+ *
+ * The underlying implementation uses Node.js worker_threads (or the synchronous Connection
+ * wrapped in a Promise) to execute queries asynchronously.
+ *
+ * @example
+ * const db = new Database({ databasePath: '/tmp/test.db', mode: 'w' });
+ * const conn = db.asyncConnect();
+ * const result = await conn.execute('MATCH (n) RETURN n');
+ * for (const row of result) {
+ *   console.log(row);
+ * }
+ * conn.close();
+ */
+class AsyncConnection {
+  /**
+   * @param {object} nativeConnection - The native NodeConnection object.
+   */
+  constructor(nativeConnection) {
+    this._conn = nativeConnection;
+    this._isOpen = true;
+  }
+
+  /**
+   * Check if the connection is open.
+   * @returns {boolean} True if the connection is open.
+   */
+  get isOpen() {
+    return this._isOpen;
+  }
+
+  /**
+   * Close the async connection.
+   */
+  close() {
+    if (this._isOpen) {
+      this._conn.close();
+      this._isOpen = false;
+    }
+  }
+
+  /**
+   * Execute a cypher query asynchronously.
+   *
+   * @param {string} query - The cypher query to execute.
+   * @param {string} [accessMode=''] - The access mode of the query.
+   * @param {Object} [parameters=null] - Query parameters as key-value pairs.
+   * @returns {Promise<QueryResult>} A promise that resolves to the query result.
+   */
+  async execute(query, accessMode = '', parameters = null) {
+    if (!this._isOpen) {
+      throw new Error('Connection is closed.');
+    }
+    // Wrap synchronous native call in a Promise for async interface
+    return new Promise((resolve, reject) => {
+      try {
+        const nativeResult = this._conn.execute(
+          query,
+          accessMode,
+          parameters || {}
+        );
+        resolve(new QueryResult(nativeResult));
+      } catch (e) {
+        reject(e);
+      }
+    });
+  }
+}
+
+module.exports = { AsyncConnection };

package/lib/binding.js

@@ -0,0 +1,30 @@
+/** Copyright 2020 Alibaba Group Holding Limited.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+'use strict';
+
+// Native artifacts live in build/<Release|Debug>/<platform>/.
+// Platform tags use the format: <os>-<arch> (e.g. linux-x64, darwin-arm64).
+// Prefer Debug if present (dev intent); otherwise Release.
+
+const path = require('path');
+const fs = require('fs');
+
+const platform = `${process.platform}-${process.arch}`;
+
+const buildDir = path.join(__dirname, '..', 'build');
+const cfg = fs.existsSync(path.join(buildDir, 'Debug', platform)) ? 'Debug' : 'Release';
+
+module.exports = require(path.join(buildDir, cfg, platform, 'neug_node_bind.node'));

package/lib/connection.js

@@ -0,0 +1,127 @@
+/** Copyright 2020 Alibaba Group Holding Limited.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * 	http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+'use strict';
+
+const { QueryResult } = require('./query-result');
+const { validAccessModes, isAccessModeValid } = require('./utils');
+const { OK, ERR_CONNECTION_CLOSED, codeName } = require('./error-codes');
+
+/**
+ * Connection represents a logical connection to a NeuG database.
+ * Use this class to interact with the database, executing queries and managing transactions.
+ *
+ * @example
+ * const db = new Database({ databasePath: '/tmp/test.db', mode: 'w' });
+ * const conn = db.connect();
+ * const result = conn.execute('MATCH (n) RETURN n');
+ * for (const row of result) {
+ *   console.log(row);
+ * }
+ * conn.close();
+ */
+class Connection {
+  /**
+   * @param {object} nativeConnection - The native NodeConnection object from the C++ binding.
+   */
+  constructor(nativeConnection) {
+    this._conn = nativeConnection;
+    this._isOpen = true;
+  }
+
+  /**
+   * Check if the connection is open.
+   * @returns {boolean} True if the connection is open.
+   */
+  get isOpen() {
+    return this._isOpen;
+  }
+
+  /**
+   * Close the connection to the database.
+   */
+  close() {
+    if (this._isOpen) {
+      this._conn.close();
+      this._isOpen = false;
+    }
+  }
+
+  /**
+   * Execute a cypher query on the database.
+   *
+   * @param {string} query - The cypher query to execute.
+   * @param {string} [accessMode=''] - The access mode of the query.
+   *   Supported modes: 'read'/'r', 'insert'/'i', 'update'/'u', 'schema'/'s'.
+   * @param {Object} [parameters=null] - Query parameters as key-value pairs.
+   * @returns {QueryResult} The result of the query execution.
+   * @throws {Error} If the connection is closed or the query fails.
+   *
+   * @example
+   * // Simple query
+   * const result = conn.execute('MATCH (n) RETURN n.id');
+   *
+   * // Query with parameters
+   * const result = conn.execute(
+   *   'MATCH (n:person) WHERE n.id = $id RETURN n.name',
+   *   'read',
+   *   { id: 12345 }
+   * );
+   */
+  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}`
+      );
+    }
+
+    if (accessMode !== '' && !isAccessModeValid(accessMode.toLowerCase())) {
+      throw new Error(
+        `Invalid access_mode: ${accessMode}. Supported access modes are ` +
+        `[${validAccessModes.join(', ')}].`
+      );
+    }
+
+    const nativeResult = this._conn.execute(
+      query,
+      accessMode,
+      parameters || {}
+    );
+
+    const statusCode = nativeResult.statusCode();
+    const statusMessage = nativeResult.statusMessage();
+
+    if (statusCode === OK) {
+      return new QueryResult(nativeResult);
+    }
+
+    throw new Error(
+      `Failed to execute query: ${query}. ` +
+      `Error code: ${statusCode}, Error Message: ` +
+      `${codeName(statusCode)}: ${statusMessage}`
+    );
+  }
+
+  /**
+   * Get the schema of the NeuG database.
+   * @returns {string} The schema as a string.
+   */
+  getSchema() {
+    return this._conn.getSchema();
+  }
+}
+
+module.exports = { Connection };