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

.github/workflows/node-spanner-lib-wrapper-lint.yml

@@ -0,0 +1,38 @@
+name: Node Wrapper Lint
+
+on:
+  push:
+    branches: [ "main" ]
+    paths:
+      - 'spannerlib/wrappers/spannerlib-node/**'
+  pull_request:
+    branches: [ "main" ]
+    paths:
+      - 'spannerlib/wrappers/spannerlib-node/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: spannerlib/wrappers/spannerlib-node
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+        cache: 'npm'
+        cache-dependency-path: spannerlib/wrappers/spannerlib-node/package.json
+
+    - name: Install Dependencies
+      run: npm install
+
+    - name: Run Lint
+      run: npm run lint

.github/workflows/node-spanner-lib-wrapper-unit-tests.yml

@@ -0,0 +1,54 @@
+name: Node Wrapper Unit Tests
+
+on:
+  push:
+    branches: [ "main" ]
+    paths:
+      - 'spannerlib/wrappers/spannerlib-node/**'
+  pull_request:
+    branches: [ "main" ]
+    paths:
+      - 'spannerlib/wrappers/spannerlib-node/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  unit-tests:
+    name: Test ${{ matrix.os }} (Node ${{ matrix.node-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        node-version: ['20']
+
+    defaults:
+      run:
+        shell: bash
+        working-directory: ./spannerlib/wrappers/spannerlib-node
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Set up Go
+      uses: actions/setup-go@v6
+      with:
+        go-version: '1.26.x'
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+        cache-dependency-path: spannerlib/wrappers/spannerlib-node/package.json
+
+    - name: Install Dependencies
+      run: npm install
+
+    - name: Build Addon and TS
+      run: npm run build
+
+    - name: Run Unit Tests
+      run: npm test

.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/.editorconfig

@@ -0,0 +1,8 @@
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+insert_final_newline = true

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

@@ -0,0 +1,5 @@
+{
+  "timeout": 60000,
+  "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/.prettierrc.js

@@ -0,0 +1,3 @@
+module.exports = {
+  ...require('gts/.prettierrc.json'),
+};

spannerlib/wrappers/spannerlib-node/README.md

@@ -0,0 +1,52 @@
+# 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.ts`**: Helper functions to invoke native methods asynchronously using Promises.
+3.  **`src/lib/`**: JavaScript classes (`Pool`, `Connection`, `Rows`) that provide a clean object-oriented interface.
+
+### Component Interaction & Memory Management
+
+When a JavaScript object (like a `Pool` or `Connection`) is created, it holds an ID referencing a pinned Go object in memory. The `spannerLib` singleton maintains a **`FinalizationRegistry`**. This registry allows Node.js to listen for when the JavaScript object is garbage collected. When GC occurs, the registry automatically triggers a cleanup call to the native layer to release the corresponding Go object, preventing native memory leaks even if the developer forgets to call `.close()` explicitly.

spannerlib/wrappers/spannerlib-node/binding.gyp

@@ -0,0 +1,68 @@
+{
+  '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.dylib'
+            ],
+            'xcode_settings': {
+                'OTHER_LDFLAGS': [
+                    '-Wl,-rpath,@loader_path'
+                ]
+            },
+            'copies': [
+                {
+                    'destination': '<(PRODUCT_DIR)',
+                    'files': [ '<(module_root_dir)/../../shared/libspanner.dylib' ]
+                }
+            ]
+        }],
+        ['OS=="linux"', {
+          'ldflags': [
+            '-Wl,-rpath,$$ORIGIN'
+          ],
+          'libraries': [
+            '<(module_root_dir)/../../shared/libspanner.so'
+          ],
+          'copies': [
+            {
+                'destination': '<(PRODUCT_DIR)',
+                'files': [ '<(module_root_dir)/../../shared/libspanner.so' ]
+            }
+          ]
+        }],
+        ['OS=="win"', {
+          'libraries': [
+            '<(module_root_dir)/../../shared/libspanner.dll'
+          ],
+          'copies': [
+            {
+                'destination': '<(PRODUCT_DIR)',
+                'files': [ '<(module_root_dir)/../../shared/libspanner.dll' ]
+            }
+          ]
+        }]
+      ]
+    }
+  ]
+}

spannerlib/wrappers/spannerlib-node/eslint.config.cjs

@@ -0,0 +1,15 @@
+let customConfig = [];
+let hasIgnoresFile = false;
+try {
+  require.resolve('./eslint.ignores.cjs');
+  hasIgnoresFile = true;
+} catch {
+  // eslint.ignores.js doesn't exist
+}
+
+if (hasIgnoresFile) {
+  const ignores = require('./eslint.ignores.cjs');
+  customConfig = [{ignores}];
+}
+
+module.exports = [...customConfig, ...require('gts')];

spannerlib/wrappers/spannerlib-node/eslint.ignores.cjs

@@ -0,0 +1 @@
+module.exports = ['build/']

spannerlib/wrappers/spannerlib-node/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "spannerlib-node",
+  "version": "0.1.0",
+  "main": "./build/cjs/src/index.cjs",
+  "module": "./build/esm/src/index.js",
+  "types": "./build/cjs/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.cjs"
+      }
+    }
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build:go": "bash scripts/build-shared-lib.sh",
+    "build": "npm run build:go && node-gyp rebuild && npm run compile",
+    "postbuild": "node -e \"if (process.platform === 'darwin') require('child_process').execSync('install_name_tool -change libspanner.dylib @loader_path/libspanner.dylib ./build/Release/spanner_napi.node')\"",
+    "compile:esm": "tsc -p .",
+    "compile:cjs": "tsc -p ./tsconfig.cjs.json && babel build/cjs --out-dir build/cjs --out-file-extension .cjs && node scripts/fix-extensions.cjs",
+    "compile": "npm run compile:esm && npm run compile:cjs",
+    "test:esm": "mocha build/esm/test/**/*.js",
+    "test:cjs": "mocha build/cjs/test/**/*.cjs",
+    "test": "npm run test:esm && npm run test:cjs",
+    "lint": "gts lint",
+    "clean": "gts clean",
+    "fix": "gts fix",
+    "prepare": "npm run compile",
+    "pretest": "npm run compile"
+  },
+  "files": [
+    "build/esm/src",
+    "build/cjs/src",
+    "build/Release/*.node"
+  ],
+  "dependencies": {
+    "node-addon-api": "^8.0.0",
+    "bindings": "^1.5.0",
+    "@google-cloud/spanner": "^7.13.0"
+  },
+  "devDependencies": {
+    "mocha": "^10.2.0",
+    "typescript": "^5.6.3",
+    "@types/node": "^22.7.5",
+    "@types/bindings": "^1.5.0",
+    "@types/mocha": "^10.0.6",
+    "@babel/core": "^7.24.0",
+    "@babel/cli": "^7.23.9",
+    "sinon": "^18.0.0",
+    "@types/sinon": "^17.0.3",
+    "gts": "^7.0.0"
+  },
+  "gypfile": false
+}