jolt-js-api 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 DevArqf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# Jolt JavaScript API
+
+A JavaScript & Node.js client for the [Jolt](https://github.com/Jolt-Database/Jolt) in-memory messaging broker.
+
+## Features
+
+✅ Native Jolt broker protocol support  
+✅ Event-driven architecture (EventEmitter)  
+✅ Promise-based API available  
+✅ Simple pub/sub messaging  
+✅ No external dependencies (Node.js core only)  
+✅ TypeScript definitions included  
+
+## Installation
+
+```bash
+npm install jolt-js-api
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/DevArqf/jolt-js-api.git
+cd jolt-js-api
+npm install
+```
+
+## Quick Start
+
+```javascript
+const JoltClient = require('jolt-js-api');
+
+// Create client
+const client = new JoltClient({
+  host: '127.0.0.1',
+  port: 8080
+});
+
+// Set up event handlers
+client.on('connected', () => console.log('Connected'));
+client.on('ok', () => console.log('✓ OK'));
+client.on('error', (error) => console.log('✗ Error:', error));
+client.on('message', (topic, data) => console.log(`[${topic}] ${data}`));
+client.on('disconnected', () => console.log('Disconnected'));
+
+// Connect and use
+async function main() {
+  await client.connect();
+  
+  client.subscribe('chat.general');
+  client.publish('chat.general', 'Hello, Jolt!');
+  client.ping();
+  
+  // Keep running...
+  await new Promise(resolve => setTimeout(resolve, 2000));
+  
+  client.close();
+}
+
+main();
+```
+
+## API Reference
+
+### Constructor
+
+```javascript
+const client = new JoltClient(config);
+```
+
+**Config Options:**
+- `host` (string): Broker host (default: '127.0.0.1')
+- `port` (number): Broker port (default: 8080)
+
+### Methods
+
+#### Connection
+- `connect()` → Promise<void> - Connect to broker
+- `close()` → void - Close connection
+- `isConnected()` → boolean - Check connection status
+
+#### Operations
+- `auth(username, password)` → void - Authenticate
+- `subscribe(topic)` → void - Subscribe to topic
+- `unsubscribe(topic)` → void - Unsubscribe from topic
+- `publish(topic, data)` → void - Publish message
+- `ping()` → void - Send ping
+
+### Events
+
+```javascript
+client.on('connected', () => {})
+client.on('ok', (rawLine) => {})
+client.on('error', (errorMsg, rawLine) => {})
+client.on('message', (topic, data, rawLine) => {})
+client.on('disconnected', () => {})
+client.on('socketError', (err) => {})
+client.on('parseError', (err, line) => {})
+client.on('unknown', (data, line) => {})
+```
+
+## Examples
+
+### Simple Chat
+
+```javascript
+const JoltClient = require('jolt-js-api');
+
+const client = new JoltClient();
+
+client.on('message', (topic, data) => {
+  console.log(`[${topic}] ${data}`);
+});
+
+await client.connect();
+client.subscribe('chat.room1');
+client.publish('chat.room1', 'Hello everyone!');
+```
+
+### Multiple Topics
+
+```javascript
+const topics = ['news', 'sports', 'weather'];
+
+// Subscribe to all
+topics.forEach(topic => client.subscribe(topic));
+
+// Publish to each
+client.publish('news', 'Breaking news!');
+client.publish('sports', 'Score: 3-2');
+client.publish('weather', 'Sunny, 25°C');
+```
+
+### Promise-Based Operations
+
+```javascript
+const JoltClientWrapper = require('./examples/advanced-usage');
+
+const client = new JoltClientWrapper({ host: '127.0.0.1', port: 8080 });
+
+await client.connect();
+await client.subscribeAsync('chat.general');
+await client.publishAsync('chat.general', 'Hello!');
+```
+
+### Error Handling
+
+```javascript
+client.on('error', (error) => {
+  if (error.includes('auth')) {
+    console.error('Authentication failed!');
+  } else if (error.includes('unknown_topic')) {
+    console.error('Topic does not exist!');
+  } else {
+    console.error('Error:', error);
+  }
+});
+
+client.on('socketError', (err) => {
+  console.error('Socket error:', err);
+  // Implement reconnection logic
+});
+```
+
+## Testing
+
+```bash
+# Run tests (broker must be running)
+npm test
+
+# Watch mode
+npm run test:watch
+
+# Run examples
+npm run example
+npm run example:advanced
+```
+
+## Protocol
+
+Jolt uses NDJSON (newline-delimited JSON) over TCP:
+
+### Commands
+```json
+{"op": "auth", "user": "username", "pass": "password"}
+{"op": "sub", "topic": "channel"}
+{"op": "unsub", "topic": "channel"}
+{"op": "pub", "topic": "channel", "data": "message"}
+{"op": "ping"}
+```
+
+### Responses
+```json
+{"ok": true}
+{"ok": false, "error": "error_message"}
+{"topic": "channel", "data": "message"}
+```
+
+## License
+
+MIT License - see LICENSE file for details

package/examples/advanced-usage.js

@@ -0,0 +1,113 @@
+const JoltClient = require('../src/JoltClient');
+
+class JoltClientWrapper {
+  constructor(config) {
+    this.client = new JoltClient(config);
+    this.responseHandlers = new Map();
+  }
+
+  async connect() {
+    return this.client.connect();
+  }
+
+  async subscribeAsync(topic) {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error('Subscription timeout'));
+      }, 5000);
+
+      const okHandler = () => {
+        clearTimeout(timeout);
+        this.client.off('ok', okHandler);
+        this.client.off('error', errorHandler);
+        resolve();
+      };
+
+      const errorHandler = (error) => {
+        clearTimeout(timeout);
+        this.client.off('ok', okHandler);
+        this.client.off('error', errorHandler);
+        reject(new Error(error));
+      };
+
+      this.client.once('ok', okHandler);
+      this.client.once('error', errorHandler);
+      this.client.subscribe(topic);
+    });
+  }
+
+  async publishAsync(topic, data) {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error('Publish timeout'));
+      }, 5000);
+
+      const okHandler = () => {
+        clearTimeout(timeout);
+        this.client.off('ok', okHandler);
+        this.client.off('error', errorHandler);
+        resolve();
+      };
+
+      const errorHandler = (error) => {
+        clearTimeout(timeout);
+        this.client.off('ok', okHandler);
+        this.client.off('error', errorHandler);
+        reject(new Error(error));
+      };
+
+      this.client.once('ok', okHandler);
+      this.client.once('error', errorHandler);
+      this.client.publish(topic, data);
+    });
+  }
+
+  on(event, handler) {
+    this.client.on(event, handler);
+  }
+
+  close() {
+    this.client.close();
+  }
+}
+
+async function advancedExample() {
+  const client = new JoltClientWrapper({
+    host: '127.0.0.1',
+    port: 8080
+  });
+
+  client.on('message', (topic, data) => {
+    console.log(`📩 [${topic}] ${data}`);
+  });
+
+  try {
+    console.log('Connecting...');
+    await client.connect();
+    console.log('✓ Connected');
+
+    console.log('Subscribing to topics...');
+    await client.subscribeAsync('news');
+    await client.subscribeAsync('sports');
+    console.log('✓ Subscribed');
+
+    console.log('Publishing messages...');
+    await client.publishAsync('news', 'Breaking: Node.js API released!');
+    await client.publishAsync('sports', 'Score: 3-2');
+    console.log('✓ Published');
+
+    await new Promise(resolve => setTimeout(resolve, 1000));
+
+    client.close();
+    console.log('✓ Closed');
+  } catch (err) {
+    console.error('Error:', err.message);
+    client.close();
+  }
+}
+
+if (require.main === module) {
+  advancedExample();
+}
+
+module.exports = JoltClientWrapper;

package/examples/multiple-clients.js

@@ -0,0 +1,55 @@
+const JoltClient = require('../src/JoltClient');
+
+async function multipleClientsExample() {
+  console.log('Creating two clients...\n');
+  
+  const client1 = new JoltClient({ host: '127.0.0.1', port: 8080 });
+  client1.on('message', (topic, data) => {
+    console.log(`[Client 1] 📩 [${topic}] ${data}`);
+  });
+  
+  const client2 = new JoltClient({ host: '127.0.0.1', port: 8080 });
+  client2.on('message', (topic, data) => {
+    console.log(`[Client 2] 📩 [${topic}] ${data}`);
+  });
+
+  try {
+    console.log('Connecting clients...');
+    await client1.connect();
+    await client2.connect();
+    console.log('✓ Both clients connected\n');
+
+    await new Promise(resolve => setTimeout(resolve, 100));
+
+    console.log('Subscribing to shared.channel...');
+    client1.subscribe('shared.channel');
+    client2.subscribe('shared.channel');
+    
+    await new Promise(resolve => setTimeout(resolve, 200));
+
+    console.log('\nClient 1 publishing...');
+    client1.publish('shared.channel', 'Hello from Client 1!');
+    
+    await new Promise(resolve => setTimeout(resolve, 500));
+
+    console.log('Client 2 publishing...');
+    client2.publish('shared.channel', 'Hello from Client 2!');
+
+    await new Promise(resolve => setTimeout(resolve, 1000));
+
+    console.log('\nClosing connections...');
+    client1.close();
+    client2.close();
+    console.log('✓ Done');
+  } catch (err) {
+    console.error('Error:', err);
+    client1.close();
+    client2.close();
+  }
+}
+
+if (require.main === module) {
+  multipleClientsExample();
+}
+
+module.exports = multipleClientsExample;

package/examples/simple-chat.js

@@ -0,0 +1,68 @@
+const JoltClient = require('../src/JoltClient');
+
+async function main() {
+  const client = new JoltClient({
+    host: '127.0.0.1',
+    port: 8080
+  });
+
+  client.on('connected', () => {
+    console.log('✓ Connected to Jolt broker');
+  });
+
+  client.on('ok', () => {
+    console.log('✓ OK');
+  });
+
+  client.on('error', (error) => {
+    console.log(`✗ Error: ${error}`);
+  });
+
+  client.on('message', (topic, data) => {
+    console.log(`📩 [${topic}] ${data}`);
+  });
+
+  client.on('disconnected', () => {
+    console.log('👋 Disconnected');
+  });
+
+  try {
+    console.log('Connecting...');
+    await client.connect();
+
+    await new Promise(resolve => setTimeout(resolve, 100));
+
+    // AUTHENTICATE FIRST (required when security is enabled)
+    console.log('Authenticating...');
+    client.auth('admin', 'joltadmin');
+    
+    await new Promise(resolve => setTimeout(resolve, 300));
+
+    console.log('Subscribing to chat.general...');
+    client.subscribe('chat.general');
+    
+    await new Promise(resolve => setTimeout(resolve, 300));
+
+    console.log('Publishing messages...');
+    client.publish('chat.general', 'Hello from Node.js!');
+    client.publish('chat.general', 'Authentication working!');
+
+    await new Promise(resolve => setTimeout(resolve, 300));
+
+    console.log('Sending ping...');
+    client.ping();
+
+    console.log('\nListening for messages...\n');
+    await new Promise(resolve => setTimeout(resolve, 2000));
+
+    console.log('\nClosing connection...');
+    client.close();
+    
+    console.log('✓ Done!');
+  } catch (err) {
+    console.error('Error:', err);
+    client.close();
+  }
+}
+
+main().catch(console.error);

package/package.json

@@ -0,0 +1,33 @@
+{
+    "name": "jolt-js-api",
+    "version": "1.0.0",
+    "description": "JavaScript & Node.js client for the Jolt in-memory messaging broker",
+    "main": "src/JoltClient.js",
+    "scripts": {
+      "test": "jest",
+      "test:watch": "jest --watch",
+      "example": "node examples/simple-chat.js",
+      "example:advanced": "node examples/advanced-usage.js"
+    },
+    "keywords": [
+      "jolt",
+      "messaging",
+      "broker",
+      "pubsub",
+      "real-time",
+      "tcp",
+      "ndjson"
+    ],
+    "author": "DevArqf",
+    "license": "MIT",
+    "repository": {
+      "type": "git",
+      "url": "https://github.com/DevArqf/jolt-js-api"
+    },
+    "devDependencies": {
+      "jest": "^29.0.0"
+    },
+    "engines": {
+      "node": ">=14.0.0"
+    }
+  }

package/src/JoltClient.js

@@ -0,0 +1,135 @@
+const net = require('net');
+const EventEmitter = require('events');
+
+class JoltClient extends EventEmitter {
+  constructor(config = {}) {
+    super();
+    this.host = config.host || '127.0.0.1';
+    this.port = config.port || 8080;
+    this.socket = null;
+    this.connected = false;
+    this.buffer = '';
+  }
+
+  connect() {
+    return new Promise((resolve, reject) => {
+      this.socket = net.createConnection({
+        host: this.host,
+        port: this.port
+      });
+
+      this.socket.on('connect', () => {
+        this.connected = true;
+        this.emit('connected');
+        resolve();
+      });
+
+      this.socket.on('data', (chunk) => {
+        this._handleData(chunk);
+      });
+
+      this.socket.on('error', (err) => {
+        this.connected = false;
+        this.emit('socketError', err);
+        reject(err);
+      });
+
+      this.socket.on('close', () => {
+        this.connected = false;
+        this.emit('disconnected');
+      });
+
+      this.socket.on('end', () => {
+        this.connected = false;
+        this.emit('disconnected');
+      });
+    });
+  }
+
+  /**
+   * Authenticate with the broker (REQUIRED if security is enabled)
+   * Protocol: {"op": "auth", "user": "...", "pass": "..."}
+   */
+  auth(username, password) {
+    this._send({ op: 'auth', user: username, pass: password });
+  }
+
+  subscribe(topic) {
+    this._send({ op: 'sub', topic });
+  }
+
+  unsubscribe(topic) {
+    this._send({ op: 'unsub', topic });
+  }
+
+  publish(topic, data) {
+    this._send({ op: 'pub', topic, data });
+  }
+
+  ping() {
+    this._send({ op: 'ping' });
+  }
+
+  close() {
+    if (this.socket) {
+      this.connected = false;
+      this.socket.end();
+      this.socket.destroy();
+      this.socket = null;
+    }
+  }
+
+  isConnected() {
+    return this.connected;
+  }
+
+  _send(obj) {
+    if (!this.connected || !this.socket) {
+      throw new Error('Not connected to broker');
+    }
+    
+    const message = JSON.stringify(obj) + '\n';
+    this.socket.write(message);
+  }
+
+  _handleData(chunk) {
+    this.buffer += chunk.toString();
+
+    while (this.buffer.includes('\n')) {
+      const newlineIndex = this.buffer.indexOf('\n');
+      const line = this.buffer.substring(0, newlineIndex).trim();
+      this.buffer = this.buffer.substring(newlineIndex + 1);
+
+      if (line) {
+        this._handleLine(line);
+      }
+    }
+  }
+
+  _handleLine(line) {
+    try {
+      const data = JSON.parse(line);
+
+      if (data.topic !== undefined && data.data !== undefined) {
+        this.emit('message', data.topic, data.data, line);
+        return;
+      }
+
+      if (data.ok === false && data.error) {
+        this.emit('error', data.error, line);
+        return;
+      }
+
+      if (data.ok === true) {
+        this.emit('ok', line);
+        return;
+      }
+
+      this.emit('unknown', data, line);
+    } catch (err) {
+      this.emit('parseError', err, line);
+    }
+  }
+}
+
+module.exports = JoltClient;

package/test/client.test.js

@@ -0,0 +1,128 @@
+const JoltClient = require('../src/JoltClient');
+
+describe('JoltClient', () => {
+  let client;
+
+  beforeEach(() => {
+    client = new JoltClient({ host: '127.0.0.1', port: 8080 });
+  });
+
+  afterEach(() => {
+    if (client.isConnected()) {
+      client.close();
+    }
+  });
+
+  describe('Configuration', () => {
+    test('should use default host and port', () => {
+      const defaultClient = new JoltClient();
+      expect(defaultClient.host).toBe('127.0.0.1');
+      expect(defaultClient.port).toBe(8080);
+    });
+
+    test('should use custom host and port', () => {
+      const customClient = new JoltClient({ host: '192.168.1.100', port: 9000 });
+      expect(customClient.host).toBe('192.168.1.100');
+      expect(customClient.port).toBe(9000);
+    });
+  });
+
+  describe('Connection', () => {
+    test('should connect to broker', async () => {
+      await client.connect();
+      expect(client.isConnected()).toBe(true);
+    }, 10000);
+
+    test('should emit connected event', async () => {
+      const connectedPromise = new Promise(resolve => {
+        client.on('connected', resolve);
+      });
+
+      await client.connect();
+      await connectedPromise;
+    }, 10000);
+
+    test('should handle disconnection', async () => {
+      await client.connect();
+      
+      const disconnectedPromise = new Promise(resolve => {
+        client.on('disconnected', resolve);
+      });
+
+      client.close();
+      await disconnectedPromise;
+      
+      expect(client.isConnected()).toBe(false);
+    }, 10000);
+  });
+
+  describe('Messaging', () => {
+    beforeEach(async () => {
+      await client.connect();
+    });
+
+    test('should send ping', (done) => {
+      client.on('ok', () => {
+        done();
+      });
+      
+      client.ping();
+    }, 10000);
+
+    test('should subscribe to topic', (done) => {
+      client.on('ok', () => {
+        done();
+      });
+
+      client.subscribe('test.topic');
+    }, 10000);
+
+    test('should publish and receive message', (done) => {
+      const testTopic = 'test.pubsub';
+      const testMessage = 'test message';
+
+      client.on('message', (topic, data) => {
+        if (topic === testTopic && data === testMessage) {
+          done();
+        }
+      });
+
+      client.subscribe(testTopic);
+      
+      setTimeout(() => {
+        client.publish(testTopic, testMessage);
+      }, 500);
+    }, 10000);
+
+    test('should handle multiple topics', (done) => {
+      const topics = ['topic1', 'topic2', 'topic3'];
+      const received = new Set();
+
+      client.on('message', (topic, data) => {
+        received.add(topic);
+        
+        if (received.size === topics.length) {
+          done();
+        }
+      });
+
+      topics.forEach(topic => client.subscribe(topic));
+
+      setTimeout(() => {
+        topics.forEach(topic => {
+          client.publish(topic, `message for ${topic}`);
+        });
+      }, 500);
+    }, 10000);
+
+    test('should handle errors', (done) => {
+      client.on('error', (error) => {
+        expect(error).toBeDefined();
+        done();
+      });
+
+      // Try to trigger an error (this depends on broker implementation)
+      client.subscribe('');
+    }, 10000);
+  });
+});