feat(nodejs): connection pool, database locked handling, resilience cleanup

.github/workflows/nodejs-workflow.yml

@@ -9,9 +9,15 @@ on:
         required: true
         default: false
 
+# Let heavy builds finish; new push queues instead of cancelling.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
 jobs:
   build-nodejs:
     runs-on: ${{ matrix.os }}
+    timeout-minutes: 90
     strategy:
       matrix:
         include:
@@ -144,3 +150,41 @@ jobs:
         if: ${{ matrix.platform == 'darwin' }}
         working-directory: tools/nodejs_api/
         run: rm -rf package
+
+  # Push prebuilt/*.node to repo so pnpm add github:user/ladybug#path:tools/nodejs_api uses them without building.
+  # Runs only on manual workflow_dispatch to avoid push loops.
+  update-prebuilt:
+    if: github.event_name == 'workflow_dispatch'
+    needs: build-nodejs
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Download Node.js artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+          pattern: "*nodejs*"
+          merge-multiple: false
+
+      - name: Copy artifacts to prebuilt
+        run: |
+          mkdir -p tools/nodejs_api/prebuilt
+          for d in artifacts/*/; do
+            find "$d" -name "lbugjs-*.node" -exec cp {} tools/nodejs_api/prebuilt/ \;
+          done
+          ls -la tools/nodejs_api/prebuilt/
+
+      - name: Commit and push prebuilt
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add -f tools/nodejs_api/prebuilt/
+          git diff --staged --quiet && echo "No prebuilt changes" && exit 0
+          git commit -m "chore(nodejs): update prebuilt addons from CI [skip ci]"
+          # Push to origin (repo where workflow runs: your fork when run from fork)
+          git push origin HEAD:"${GITHUB_REF#refs/heads/}"

.gitignore

@@ -1,5 +1,9 @@
+tree-sitter/
+tree-sitter-cypher/
+
 .idea/
 .vscode
+.cursor
 .vs
 bazel-*
 .clwb

Makefile

@@ -187,7 +187,7 @@ nodejs-deps:
 	cd tools/nodejs_api && npm install --include=dev
 
 nodejstest: nodejs
-	cd tools/nodejs_api && npm test
+	cd tools/nodejs_api && node copy_src_to_build.js && npm test
 
 nodejstest-deps: nodejs-deps nodejstest
 

docs/testing.md

@@ -35,6 +35,12 @@ TEST_F(MyTest, TestCaseName) {
 - `test/planner/` - Query planner tests
 - `test/optimizer/` - Query optimizer tests
 
+## Node.js API
+
+Tests live in `tools/nodejs_api/test/` and use the Node.js built-in test runner (`node --test`). Run with `npm test` from `tools/nodejs_api/`.
+
+For guidelines on writing and reviewing these tests, see [Node.js API — Testing Guide](../tools/nodejs_api/docs/nodejs_testing.md).
+
 ## Running Tests
 
 See `AGENTS.md` for build and test commands.

tools/nodejs_api/CHANGELOG.md

@@ -0,0 +1,9 @@
+## Changelog
+
+### Unreleased
+
+- **Breaking:** Drop support for Node.js versions lower than 20; the package now requires **Node.js 20 or later** (`engines.node: ">=20.0.0"`).
+- **Breaking:** Upgrade native build tooling to **`cmake-js` ^8.0.0** and **`node-addon-api` ^8.0.0**, aligning with the Node.js 20+ support window.
+- Clarify Node.js version requirement in the README.
+- Add **Node.js API testing guide** at `tools/nodejs_api/docs/nodejs_testing.md` for test authors and reviewers (assertions, isolation, data types, concurrency, errors, resource lifecycle, validation checklist). Remove `tools/nodejs_api/test/test_correctness_audit.md` in favor of this guide.
+

tools/nodejs_api/CMakeLists.txt

@@ -9,25 +9,42 @@ else()
   set(NPX_CMD npx)
 endif()
 
+# Use --log-level error so INFO lines are not captured in OUTPUT_VARIABLE
 execute_process(
-  COMMAND ${NPX_CMD} cmake-js print-cmakejs-include
+  COMMAND ${NPX_CMD} cmake-js print-cmakejs-include --log-level error
   WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
   OUTPUT_VARIABLE CMAKE_JS_INC
 )
 execute_process(
-  COMMAND ${NPX_CMD} cmake-js print-cmakejs-lib
+  COMMAND ${NPX_CMD} cmake-js print-cmakejs-lib --log-level error
   WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
   OUTPUT_VARIABLE CMAKE_JS_LIB
 )
 execute_process(
-  COMMAND ${NPX_CMD} cmake-js print-cmakejs-src
+  COMMAND ${NPX_CMD} cmake-js print-cmakejs-src --log-level error
   WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
   OUTPUT_VARIABLE CMAKE_JS_SRC
 )
 
-string(STRIP ${CMAKE_JS_INC} CMAKE_JS_INC)
-string(STRIP ${CMAKE_JS_LIB} CMAKE_JS_LIB)
-string(STRIP ${CMAKE_JS_SRC} CMAKE_JS_SRC)
+string(STRIP "${CMAKE_JS_INC}" CMAKE_JS_INC)
+string(STRIP "${CMAKE_JS_LIB}" CMAKE_JS_LIB)
+string(STRIP "${CMAKE_JS_SRC}" CMAKE_JS_SRC)
+# Filter out cmake-js INFO lines that may be mixed into stdout
+foreach(VAR CMAKE_JS_INC CMAKE_JS_LIB CMAKE_JS_SRC)
+  string(REPLACE "\n" ";" _LINES "${${VAR}}")
+  set(_FILTERED "")
+  foreach(_LINE ${_LINES})
+    string(STRIP "${_LINE}" _LINE)
+    if(_LINE AND NOT _LINE MATCHES "^INFO")
+      list(APPEND _FILTERED "${_LINE}")
+    endif()
+  endforeach()
+  list(JOIN _FILTERED " " _JOINED)
+  set(${VAR} "${_JOINED}")
+endforeach()
+string(STRIP "${CMAKE_JS_INC}" CMAKE_JS_INC)
+string(STRIP "${CMAKE_JS_LIB}" CMAKE_JS_LIB)
+string(STRIP "${CMAKE_JS_SRC}" CMAKE_JS_SRC)
 
 # Print CMAKE_JS variables
 message(STATUS "CMake.js configurations: LIB=${CMAKE_JS_LIB}, INC=${CMAKE_JS_INC}, SRC=${CMAKE_JS_SRC}")