Jolt JavaScript API

This repository is a JavaScript and Node.js client. This package provides direct access to the Jolt protocol, offering a lightweight, dependency-free interface for building real-time distributed applications, internal services, and event-driven systems.

Overview

The Jolt JavaScript API communicates with our Jolt broker using its native TCP protocol and newline-delimited JSON messaging format. The client exposes a Node.js EventEmitter interface and supports both callback-based and Promise-based usage.

This module intentionally relies only on Node.js core libraries to ensure low overhead, portability, and minimal setup requirements. TypeScript definitions are included for typed development environments.

Installation

npm install jolt-js-api

Installation from source:

git clone https://github.com/Jolt-Database/jolt-js-api.git
cd jolt-js-api
npm install

Usage Example

const JoltClient = require('jolt-js-api');

const client = new JoltClient({
  host: '127.0.0.1',
  port: 8080
});

client.on('connected', () => console.log('Connected to broker'));
client.on('message', (topic, data) => console.log(`[${topic}] ${data}`));
client.on('error', (error) => console.error('Error:', error));

async function main() {
  await client.connect();

  client.subscribe('chat.general');
  client.publish('chat.general', 'Hello, Jolt!');
  client.ping();

  await new Promise(resolve => setTimeout(resolve, 2000));
  client.close();
}

main();

API Summary

Constructor

const client = new JoltClient(config);

Configuration options:

• host: Broker hostname (default: 127.0.0.1)
• port: Broker port (default: 8080)

Connection Methods

• connect() – Establishes a connection to the broker.
• close() – Closes the client connection.
• isConnected() – Returns connection state.

Messaging Methods

• auth(username, password) – Performs broker authentication.
• subscribe(topic) – Subscribes to a topic.
• unsubscribe(topic) – Removes an existing subscription.
• publish(topic, data) – Publishes a message to a topic.
• ping() – Issues a protocol-level health check.

Event Interface

• connected
• ok
• error
• message
• disconnected
• socketError
• parseError
• unknown

These events provide full visibility into the broker communication, parsing results, socket behavior, and message routing.

Additional Examples

Simple Pub/Sub

await client.connect();
client.subscribe('chat.room1');
client.publish('chat.room1', 'Hello');

Multiple Topics

['news', 'sports', 'weather']
  .forEach(t => client.subscribe(t));

client.publish('news', 'Latest headline');

Promise-Based Wrapper Usage

await client.connect();
await client.subscribeAsync('chat.general');
await client.publishAsync('chat.general', 'Hello');

Error Handling Pattern

client.on('error', (err) => {
  console.error(err);
});

Testing

npm test
npm run test:watch
npm run example
npm run example:advanced

A running Jolt broker instance is required for full test execution.

Protocol Notes

Communication uses newline-delimited JSON over TCP.

Example request frames:

{"op": "auth", "user": "username", "pass": "password"}
{"op": "pub", "topic": "channel", "data": "message"}
{"op": "sub", "topic": "channel"}

Example response frames:

{"ok": true}
{"topic": "channel", "data": "message"}