update

docs/implementation.md

@@ -316,6 +316,30 @@ julia test/scenario3_julia_to_julia.jl
 node test/scenario3_julia_to_julia.js
 ```
 
+## API Consistency Across Languages
+
+**High-Level API (Consistent Across All Languages):**
+- `smartsend(subject, data, ...)` - Main publishing function
+- `smartreceive(msg, ...)` - Main receiving function
+- Message envelope structure (`msg_envelope_v1` / `MessageEnvelope`)
+- Payload structure (`msg_payload_v1` / `MessagePayload`)
+- Transport strategy (direct vs link based on size threshold)
+- Supported payload types: text, dictionary, table, image, audio, video, binary
+
+**Low-Level Native Functions (Language-Specific Conventions):**
+- Julia: `NATS.connect()`, `publish_message()`, function overloading
+- JavaScript: `nats.js` client, native async/await patterns
+- Python: `nats-python` client, native async/await patterns
+
+**Connection Reuse Pattern - Key Differences:**
+- **Julia:** Uses `NATS_connection` keyword parameter with function overloading for automatic connection management
+- **JavaScript/Python:** Achieved by creating NATS client outside the function and reusing it in custom handlers or custom publish implementations
+
+**Why the Difference?**
+- Julia supports function overloading and keyword arguments, allowing `NATS_connection` to be passed as an optional parameter
+- JavaScript/Python use a simpler `is_publish` option to control automatic publishing
+- For connection reuse in JavaScript/Python, create a NATS client once and reuse it in your custom `fileserver_upload_handler` or custom publish logic
+
 ## Usage
 
 ### Scenario 1: Command & Control (Small Dictionary)
@@ -373,9 +397,39 @@ const config = {
     threshold: 0.5
 };
 
+// Use is_publish option to control automatic publishing
 await smartsend("control", [
     { dataname: "config", data: config, type: "dictionary" }
-]);
+], {
+    is_publish: true  // Automatically publish to NATS
+});
+```
+
+**Connection Reuse in JavaScript:**
+To achieve connection reuse in JavaScript, create a NATS client outside the function and use it in a custom `fileserver_upload_handler` or custom publish implementation:
+
+```javascript
+const { connect } = require('nats');
+const { smartsend } = require('./src/NATSBridge');
+
+// Create connection once
+const nc = await connect({ servers: ['nats://localhost:4222'] });
+
+// Send multiple messages using the same connection
+for (let i = 0; i < 100; i++) {
+    const config = { iteration: i, data: Math.random() };
+    
+    // Option 1: Use is_publish=false and publish manually with your connection
+    const { env, env_json_str } = await smartsend("control", [
+        { dataname: "config", data: config, type: "dictionary" }
+    ], { is_publish: false });
+    
+    // Publish with your existing connection
+    await nc.publish("control", env_json_str);
+}
+
+// Close connection when done
+await nc.close();
 ```
 
 **Python/Micropython (Sender/Receiver):**
@@ -390,7 +444,32 @@ config = {
     "threshold": 0.5
 }
 
-smartsend("control", [("config", config, "dictionary")])
+# Use is_publish parameter to control automatic publishing
+smartsend("control", [("config", config, "dictionary")], is_publish=True)
+```
+
+**Connection Reuse in Python:**
+To achieve connection reuse in Python, create a NATS client outside the function and use it in a custom `fileserver_upload_handler` or custom publish implementation:
+
+```python
+from nats_bridge import smartsend
+import nats
+
+# Create connection once
+nc = await nats.connect("nats://localhost:4222")
+
+# Send multiple messages using the same connection
+for i in range(100):
+    config = {"iteration": i, "data": random.random()}
+    
+    # Option 1: Use is_publish=False and publish manually with your connection
+    env, env_json_str = smartsend("control", [("config", config, "dictionary")], is_publish=False)
+    
+    # Publish with your existing connection
+    await nc.publish("control", env_json_str)
+
+# Close connection when done
+await nc.close()
 ```
 
 ### Basic Multi-Payload Example
@@ -607,6 +686,10 @@ env, env_json_str = smartsend(
 # Uses: publish_message(broker_url, subject, env_json_str, cid)
 ```
 
+**API Consistency Note:**
+- **Julia:** Uses `NATS_connection` keyword parameter with function overloading for automatic connection management
+- **JavaScript/Python:** Use `is_publish` option and achieve connection reuse by creating NATS client outside the function and reusing it in custom handlers or custom publish implementations
+
 #### JavaScript (Receiver)
 ```javascript
 const { smartreceive } = require('./src/NATSBridge');