add js class

src/natsbridge_ssr.js

@@ -1,6 +1,6 @@
 /**
  * NATSBridge - Cross-Platform Bi-Directional Data Bridge
- * JavaScript/Node.js Implementation (Client-Side Rendering)
+ * JavaScript/Node.js Implementation (Desktop/Server-Side)
  * 
  * This module provides functionality for sending and receiving data across network boundaries
  * using NATS as the message bus, with support for both direct payload transport and
@@ -8,6 +8,12 @@
  * 
  * Supported payload types: "text", "dictionary", "arrowtable", "jsontable", "image", "audio", "video", "binary"
  * 
+ * Node.js-specific features:
+ * - Apache Arrow IPC support via apache-arrow
+ * - TCP NATS connections (nats:// or tls:// URLs)
+ * - Buffer for binary data handling
+ * - Connection pooling for high-throughput scenarios
+ * 
  * @module NATSBridge
  */
 
@@ -342,15 +348,18 @@ async function fetchWithBackoff(url, maxRetries, baseDelay, maxDelay, correlatio
 
 /**
  * NATS client wrapper for connection management
+ * Supports both single-use and persistent connection modes
  */
 class NATSClient {
     /**
      * Create a new NATS client
-     * @param {string} url - NATS server URL
+     * @param {string} url - NATS server URL (nats:// or tls://)
+     * @param {boolean} [keepAlive=false] - Keep connection open for multiple publishes
      */
-    constructor(url) {
+    constructor(url, keepAlive = false) {
         this.url = url;
         this.connection = null;
+        this.keepAlive = keepAlive;
     }
 
     /**
@@ -358,6 +367,9 @@ class NATSClient {
      * @returns {Promise<NATS.Connection>}
      */
     async connect() {
+        if (this.connection) {
+            return this.connection;
+        }
         this.connection = await nats.connect({ servers: this.url });
         return this.connection;
     }
@@ -382,8 +394,94 @@ class NATSClient {
     async close() {
         if (this.connection) {
             this.connection.close();
+            this.connection = null;
         }
     }
+
+    /**
+     * Get the current connection (for external use)
+     * @returns {NATS.Connection|null}
+     */
+    getConnection() {
+        return this.connection;
+    }
+
+    /**
+     * Check if connected
+     * @returns {boolean}
+     */
+    isConnected() {
+        return this.connection !== null;
+    }
+}
+
+/**
+ * Connection pool for managing multiple NATS connections
+ * Useful for applications with multiple concurrent publishers
+ */
+class NATSConnectionPool {
+    /**
+     * Create a new connection pool
+     * @param {string} url - NATS server URL (nats:// or tls://)
+     * @param {number} [maxSize=10] - Maximum pool size
+     */
+    constructor(url, maxSize = 10) {
+        this.url = url;
+        this.maxSize = maxSize;
+        this.connections = new Map();
+        this.idCounter = 0;
+    }
+
+    /**
+     * Get a connection from the pool (or create new)
+     * @returns {Promise<NATSClient>}
+     */
+    async acquire() {
+        // Try to find an existing idle connection
+        for (const [id, client] of this.connections) {
+            if (client.isConnected()) {
+                return client;
+            }
+        }
+
+        // Create new connection if under limit
+        if (this.connections.size < this.maxSize) {
+            const id = `conn_${++this.idCounter}`;
+            const client = new NATSClient(this.url, true);
+            await client.connect();
+            this.connections.set(id, client);
+            return client;
+        }
+
+        // Pool exhausted - create new connection (caller should close when done)
+        const client = new NATSClient(this.url, false);
+        await client.connect();
+        return client;
+    }
+
+    /**
+     * Return a connection to the pool
+     * @param {NATSClient} client - Connection to return
+     */
+    release(client) {
+        // Only return persistent connections
+        if (client.keepAlive && client.isConnected()) {
+            // Connection already in pool, do nothing
+            return;
+        }
+        // Non-persistent connection - close it
+        client.close();
+    }
+
+    /**
+     * Close all connections in the pool
+     */
+    async closeAll() {
+        for (const [id, client] of this.connections) {
+            await client.close();
+        }
+        this.connections.clear();
+    }
 }
 
 // ---------------------------------------------- Core Functions ---------------------------------------------- //
@@ -394,9 +492,11 @@ class NATSClient {
  * @param {string} subject - NATS subject to publish to
  * @param {string} message - JSON message to publish
  * @param {string} correlationId - Correlation ID for tracing
+ * @param {boolean} [closeConnection=true] - Close connection after publish (set false for persistent connections)
  */
-async function publishMessage(brokerUrlOrClient, subject, message, correlationId) {
+async function publishMessage(brokerUrlOrClient, subject, message, correlationId, closeConnection = true) {
     let conn;
+    let shouldClose = false;
     
     if (brokerUrlOrClient instanceof NATSClient) {
         conn = brokerUrlOrClient;
@@ -410,15 +510,18 @@ async function publishMessage(brokerUrlOrClient, subject, message, correlationId
                 await brokerUrlOrClient.close();
             }
         };
+        shouldClose = true;
     } else {
         // String URL - create new client
         const client = new NATSClient(brokerUrlOrClient);
         conn = client;
+        shouldClose = true;
     }
     
     await conn.publish(subject, message, correlationId);
     
-    if (conn instanceof NATSClient) {
+    // Only close if explicitly requested and it's a short-lived client
+    if (shouldClose && closeConnection && conn instanceof NATSClient) {
         await conn.close();
     }
 }
@@ -764,9 +867,37 @@ async function smartreceive(msg, options = {}) {
 const NATSBridge = {
     /**
      * NATS client class for connection management
+     * Supports both single-use and persistent connection modes
+     * 
+     * @example
+     * // Single-use connection (closes after publish)
+     * const client = new NATSBridge.NATSClient("nats://localhost:4222");
+     * await NATSBridge.smartsend("/test", [["msg", "Hello", "text"]], { nats_connection: client });
+     * await client.close();
+     * 
+     * // Persistent connection (keeps connection open)
+     * const client = new NATSBridge.NATSClient("nats://localhost:4222", true);
+     * await client.connect();
+     * await NATSBridge.smartsend("/test1", [["msg", "Hello", "text"]], { nats_connection: client, is_publish: false });
+     * await NATSBridge.publishMessage(client, "/test2", JSON.stringify({msg: "World"}), "trace-id");
+     * // Connection remains open for more publishes
+     * await client.close();
      */
     NATSClient,
 
+    /**
+     * Connection pool for managing multiple NATS connections
+     * Useful for applications with multiple concurrent publishers
+     * 
+     * @example
+     * const pool = new NATSBridge.NATSConnectionPool("nats://localhost:4222", 10);
+     * const client = await pool.acquire();
+     * await NATSBridge.smartsend("/test", [["msg", "Hello", "text"]], { nats_connection: client });
+     * pool.release(client);
+     * await pool.closeAll();
+     */
+    NATSConnectionPool,
+
     /**
      * Send data via NATS with automatic transport selection
      */
@@ -777,6 +908,19 @@ const NATSBridge = {
      */
     smartreceive,
 
+    /**
+     * Publish message to NATS
+     * 
+     * @example
+     * // Using a persistent connection
+     * const client = new NATSBridge.NATSClient("nats://localhost:4222", true);
+     * await client.connect();
+     * await NATSBridge.publishMessage(client, "/subject", JSON.stringify({msg: "Hello"}), "trace-id", false);
+     * // Connection stays open for more publishes
+     * await client.close();
+     */
+    publishMessage,
+
     /**
      * Upload data to plik server in one-shot mode
      */