feat(spannerlib-node): add support for Node wrapper with TypeScript and dual-publishing (ESM/CJS)

Author: surbhigarg92

.gitignore

@@ -1,3 +1,7 @@
 gorm/
 .idea
 .DS_Store
+node_modules
+build/
+package-lock.json
+googleapis/

spannerlib/.gitignore

@@ -10,3 +10,5 @@ vendor/bundle
 *.swp
 ext/
 Gemfile.lock
+/googleapis/
+package-lock.json

spannerlib/wrappers/spannerlib-node/.mocharc.json

@@ -0,0 +1,5 @@
+{
+  "timeout": 10000,
+  "reporter": "spec",
+  "spec": ["build/esm/test/**/*.js"]
+}

spannerlib/wrappers/spannerlib-node/.nycrc

@@ -0,0 +1,11 @@
+{
+  "all": true,
+  "check-coverage": true,
+  "include": ["src/**/*.js", "index.js"],
+  "exclude": ["test/**"],
+  "reporter": ["text", "lcov", "html"],
+  "branches": 80,
+  "lines": 80,
+  "functions": 80,
+  "statements": 80
+}

spannerlib/wrappers/spannerlib-node/.prettierrc

@@ -0,0 +1,10 @@
+{
+  "printWidth": 80,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "bracketSpacing": true,
+  "arrowParens": "always"
+}

spannerlib/wrappers/spannerlib-node/README.md

@@ -0,0 +1,48 @@
+# Node-API Wrapper for Spanner Shared Library
+
+This package provides a high-performance Node-API (N-API) bridge to the Go-based Spanner shared library. It offers superior stability and performance compared to traditional FFI approaches.
+
+## Prerequisites
+
+- Node.js >= 20.0.0
+- Go compiler (to build the underlying shared library, if not pre-built)
+- C++ toolchain (GCC/Clang or MSVC)
+
+## Installation & Building
+
+To build the native addon, run:
+
+```bash
+npm install
+```
+
+This will trigger `node-gyp` to compile the C++ bridge and link it with `libspanner.so`.
+
+## Usage
+
+```javascript
+const { Pool, Connection } = require('spannerlib-node');
+
+async function run() {
+    const pool = new Pool('my-user-agent', 'projects/.../instances/.../databases/...');
+    await pool.create();
+    
+    const conn = await pool.createConnection();
+    const rows = await conn.executeSql('SELECT 1');
+    
+    while (await rows.next()) {
+        // process rows
+    }
+    
+    await rows.close();
+    await conn.close();
+    await pool.close();
+}
+```
+
+## Architecture
+
+The wrapper consists of:
+1.  **`src/cpp/addon.cc`**: C++ Node-API bridge that handles thread boundaries and type conversions between V8 and C.
+2.  **`src/ffi/utils.js`**: Helper functions to invoke native methods asynchronously using Promises.
+3.  **`src/lib/`**: JavaScript classes (`Pool`, `Connection`, `Rows`) that provide a clean object-oriented interface.

spannerlib/wrappers/spannerlib-node/binding.gyp

@@ -0,0 +1,57 @@
+{
+  'targets': [
+    {
+      'target_name': 'spanner_napi',
+      'sources': [ 'src/cpp/addon.cc' ],
+      'include_dirs': [
+        '<!@(node -p "require(\'node-addon-api\').include")',
+        '../../shared',
+      ],
+      'dependencies': [
+        '<!(node -p "require(\'node-addon-api\').gyp")'
+      ],
+      'cflags!': [ '-fno-exceptions' ],
+      'cflags_cc!': [ '-fno-exceptions' ],
+      'xcode_settings': {
+        'MACOSX_DEPLOYMENT_TARGET': '10.15',
+        'GCC_ENABLE_CPP_EXCEPTIONS': 'YES',
+        'CLANG_CXX_LIBRARY': 'libc++',
+      },
+      'msvs_settings': {
+        'VCCLCompilerTool': { 'ExceptionHandling': 1 },
+      },
+      'conditions': [
+        ['OS=="mac"', {
+            'libraries': [
+                '<(module_root_dir)/../../shared/libspanner.so'
+            ],
+            'xcode_settings': {
+                'OTHER_LDFLAGS': [
+                    '-Wl,-rpath,@loader_path'
+                ]
+            },
+            'copies': [
+                {
+                    'destination': '<(PRODUCT_DIR)',
+                    'files': [ '<(module_root_dir)/../../shared/libspanner.so' ]
+                }
+            ]
+        }],
+        ['OS=="linux"', {
+          'ldflags': [
+            '-Wl,-rpath,$$ORIGIN'
+          ],
+          'libraries': [
+            '<(module_root_dir)/../../shared/libspanner.so'
+          ],
+          'copies': [
+            {
+                'destination': '<(PRODUCT_DIR)',
+                'files': [ '<(module_root_dir)/../../shared/libspanner.so' ]
+            }
+          ]
+        }]
+      ]
+    }
+  ]
+}

spannerlib/wrappers/spannerlib-node/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "spannerlib-node",
+  "version": "0.1.0",
+  "main": "./build/cjs/src/index.js",
+  "module": "./build/esm/src/index.js",
+  "types": "./build/esm/src/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./build/esm/src/index.d.ts",
+        "default": "./build/esm/src/index.js"
+      },
+      "require": {
+        "types": "./build/cjs/src/index.d.ts",
+        "default": "./build/cjs/src/index.js"
+      }
+    }
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "node-gyp rebuild",
+    "postbuild": "node -e \"if (process.platform === 'darwin') require('child_process').execSync('install_name_tool -change libspanner.so @loader_path/libspanner.so ./build/Release/spanner_napi.node')\"",
+    "compile:esm": "tsc -p .",
+    "compile:cjs": "tsc -p ./tsconfig.cjs.json",
+    "compile": "npm run compile:esm && npm run compile:cjs",
+    "test": "mocha build/esm/test/**/*.js"
+  },
+  "files": [
+    "build/esm",
+    "build/cjs",
+    "build/Release/*.node"
+  ],
+  "dependencies": {
+    "node-addon-api": "^8.0.0"
+  },
+  "devDependencies": {
+    "mocha": "^10.2.0",
+    "typescript": "^5.4.0",
+    "@types/node": "^20.11.0",
+    "@types/mocha": "^10.0.6",
+    "@google-cloud/spanner": "^7.13.0"
+  },
+  "gypfile": false
+}