feat(spannerlib-node): add class-level documentation and TODOs for proto resolution

Author: surbhigarg92

spannerlib/wrappers/spannerlib-node/README.md

@@ -44,5 +44,9 @@ async function run() {
 
 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.
+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/package.json

@@ -36,14 +36,15 @@
     "build/Release/*.node"
   ],
   "dependencies": {
-    "node-addon-api": "^8.0.0"
+    "node-addon-api": "^8.0.0",
+    "bindings": "^1.5.0",
+    "@google-cloud/spanner": "^7.13.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",
     "@babel/core": "^7.24.0",
     "@babel/cli": "^7.23.9",
     "sinon": "^18.0.0",

spannerlib/wrappers/spannerlib-node/scripts/fix-extensions.cjs

@@ -1,3 +1,17 @@
+// Copyright 2026 Google LLC
+//
+// 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.
+
 const fs = require('fs');
 const path = require('path');
 

spannerlib/wrappers/spannerlib-node/src/cpp/addon.cc

@@ -16,6 +16,13 @@
 #include <iostream>
 #include "libspanner.h"
 
+// Documentation for Go function return fields (r0 - r4):
+// r0: Pinner ID (used for memory management to keep Go objects pinned)
+// r1: Error Code (0 for success, non-zero for error)
+// r2: Object ID (Handle to the created object, e.g., Pool or Connection)
+// r3: Message Length (Length of the protobuf message or error string in r4)
+// r4: Message Data (Pointer to protobuf bytes or JSON error message)
+
 //
 // Worker 1: CreatePool asynchronously
 //

spannerlib/wrappers/spannerlib-node/src/ffi/utils.ts

@@ -15,7 +15,7 @@
 import { createRequire } from 'module';
 // @ts-ignore
 const _require = typeof require !== 'undefined' ? require : createRequire(import.meta.url);
-const addon = _require('../../../Release/spanner_napi.node');
+const addon = _require('bindings')('spanner_napi');
 
 export const ENCODING_JSON = 0;
 export const ENCODING_PROTOBUF = 1;

spannerlib/wrappers/spannerlib-node/src/index.ts

@@ -18,6 +18,10 @@ import { Connection } from './lib/connection.js';
 import { Rows } from './lib/rows.js';
 import { SpannerLibError } from './ffi/utils.js';
 
+/**
+ * Releases all pinned resources and handles managed by the library.
+ * This method should be called when shutting down the application or when the wrapper is no longer needed to prevent native memory leaks.
+ */
 export function cleanup(): void {
     spannerLib.releaseAll();
 }

spannerlib/wrappers/spannerlib-node/src/lib/connection.ts

@@ -19,14 +19,30 @@ import { Rows } from './rows.js';
 import { createRequire } from 'module';
 // @ts-ignore
 const _require = typeof require !== 'undefined' ? require : createRequire(import.meta.url);
+// TODO: Avoid tight coupling to internal paths of full client libraries. 
+// Unlike other languages like Java, Python , Node client does not export its protos. 
+// We need to explore how to import protos in Node
 const { google } = _require('@google-cloud/spanner/build/protos/protos.js');
 
+/**
+ * Manages a connection to the Spanner database.
+ * 
+ * This class wraps the connection handle from the underlying Go library,
+ * providing methods to execute SQL statements and manage transactions.
+ */
 export class Connection {
     public pool: Pool | null;
     public oid: number | null;
     public pinnerId: number | null;
     public closed: boolean;
 
+    /**
+     * Creates a new connection within the specified pool.
+     * 
+     * @param pool The pool to create the connection in.
+     * @returns A Promise that resolves to a new Connection instance.
+     * @throws {SpannerLibError} If creation fails in the Go library.
+     */
     static async create(pool: Pool): Promise<Connection> {
         const c = new Connection();
         c.pool = pool;
@@ -50,6 +66,14 @@ export class Connection {
         this.closed = false;
     }
 
+    /**
+     * Executes a SQL statement on this connection.
+     * 
+     * @param sqlString The SQL query string to execute.
+     * @returns A Promise that resolves to a Rows instance containing results.
+     * @throws {Error} If the connection is closed or not bound to a pool.
+     * @throws {SpannerLibError} If execution fails in the Go library.
+     */
     async executeSql(sqlString: string): Promise<Rows> {
         if (this.closed) throw new Error("Connection is already closed");
         if (!this.pool) throw new Error("Connection is not bound to a Pool");
@@ -71,6 +95,11 @@ export class Connection {
         return new Rows(this, rowsId);
     }
 
+    /**
+     * Closes the connection and releases associated resources.
+     * 
+     * @returns A Promise that resolves when the connection is closed.
+     */
     async close(): Promise<void> {
         if (!this.closed) {
             this.closed = true;

spannerlib/wrappers/spannerlib-node/src/lib/pool.ts

@@ -16,13 +16,26 @@ import { ffi } from '../ffi/utils.js';
 import { spannerLib } from './spannerlib.js';
 import { Connection } from './connection.js';
 
+/**
+ * Manages a pool of database connections to Spanner.
+ * 
+ * This class wraps the connection pool handle from the underlying Go library,
+ * providing methods to create connections and manage the pool lifecycle.
+ */
 export class Pool {
     public oid: number | null;
     public pinnerId: number | null;
     public closed: boolean;
     public userAgent: string;
     public connStr: string;
 
+    /**
+     * Creates a new connection pool.
+     * 
+     * @param connectionString The connection string for the database.
+     * @returns A Promise that resolves to a new Pool instance.
+     * @throws {SpannerLibError} If creation fails in the Go library.
+     */
     static async create(connectionString: string): Promise<Pool> {
         // Detect if running in ESM context
         const isESM = typeof require === 'undefined';
@@ -50,11 +63,22 @@ export class Pool {
         this.connStr = connectionString;
     }
 
+    /**
+     * Creates a new connection from the pool.
+     * 
+     * @returns A Promise that resolves to a new Connection instance.
+     * @throws {Error} If the pool is closed.
+     */
     async createConnection(): Promise<Connection> {
         if (this.closed) throw new Error("Pool is already closed");
         return await Connection.create(this);
     }
 
+    /**
+     * Closes the pool and releases associated resources.
+     * 
+     * @returns A Promise that resolves when the pool is closed.
+     */
     async close(): Promise<void> {
         if (!this.closed) {
             this.closed = true;

spannerlib/wrappers/spannerlib-node/src/lib/rows.ts

@@ -18,11 +18,18 @@ import { Connection } from './connection.js';
 import { createRequire } from 'module';
 // @ts-ignore
 const _require = typeof require !== 'undefined' ? require : createRequire(import.meta.url);
+// TODO: Avoid tight coupling to internal paths of full client libraries. 
+// Unlike other languages like Java, Python , Node client does not export its protos. 
+// We need to explore how to import protos in Node
 const { google } = _require('@google-cloud/spanner/build/protos/protos.js');
 const ListValue = google.protobuf.ListValue;
 
-
-
+/**
+ * An iterator over results returned by a SQL query.
+ * 
+ * This class wraps the rows handle from the underlying Go library,
+ * providing methods to fetch rows one by one.
+ */
 export class Rows {
     public connection: Connection;
     public oid: number;
@@ -35,6 +42,13 @@ export class Rows {
         this.closed = false;
     }
 
+    /**
+     * Fetches the next row of data.
+     * 
+     * @returns A Promise that resolves to a ListValue containing the row data, or null if there are no more rows.
+     * @throws {Error} If the rows are already closed.
+     * @throws {SpannerLibError} If fetching fails in the Go library.
+     */
     async next(): Promise<any> {
         if (this.closed) throw new Error("Rows are already closed");
 
@@ -56,6 +70,11 @@ export class Rows {
         return ListValue.decode(handled.protobufBytes);
     }
 
+    /**
+     * Closes the rows iterator and releases associated resources.
+     * 
+     * @returns A Promise that resolves when the rows are closed.
+     */
     async close(): Promise<void> {
         if (!this.closed) {
             this.closed = true;