@usermetrics/queuebit 1.0.1 → 1.0.5

package/docs/API.md

@@ -7,6 +7,7 @@ QueueBit is a high-performance, socket-based message queue system with guarantee
 - [Server API](#server-api)
 - [Client API](#client-api)
 - [Message Format](#message-format)
+- [Load Balancer](#load-balancer)
 - [Examples](#examples)
 
 ---
@@ -15,15 +16,8 @@ QueueBit is a high-performance, socket-based message queue system with guarantee
 
 ### QueueBitServer
 
-The server class that handles message queuing and delivery.
-
-#### Constructor
-
-Creates a new QueueBit server instance.
-
 ```javascript
-const { QueueBitServer } = require('queuebit');
-
+const { QueueBitServer } = require('queuebit/src/server');
 const server = new QueueBitServer(options);
 ```
 
@@ -38,7 +32,7 @@ const server = new QueueBitServer(options);
 
 ```javascript
 const server = new QueueBitServer({ 
-  port: 3000,
+  port: 3333,
   maxQueueSize: 50000 
 });
 ```
@@ -51,51 +45,28 @@ Shuts down the server and closes all connections.
 server.close();
 ```
 
-**Example:**
-
-```javascript
-// Graceful shutdown
-process.on('SIGINT', () => {
-  console.log('Shutting down...');
-  server.close();
-  process.exit(0);
-});
-```
-
 ---
 
 ## Client API
 
 ### QueueBitClient
 
-The client class for connecting to a QueueBit server.
-
-#### Constructor
-
-Creates a new client connection to the server.
-
 ```javascript
-const { QueueBitClient } = require('queuebit');
+// Node.js
+const { QueueBitClient } = require('queuebit/src/client-node');
+const client = new QueueBitClient('http://localhost:3333');
 
-const client = new QueueBitClient(url);
+// Browser - include socket.io first
+// <script src="https://cdn.socket.io/4.7.2/socket.io.min.js"></script>
+// <script src="src/client-browser.js"></script>
+const client = new QueueBitClient('http://localhost:3333');
 ```
 
 **Parameters:**
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `url` | string | 'http://localhost:3000' | Server URL |
-
-**Example:**
-
-```javascript
-// Node.js
-const { QueueBitClient } = require('queuebit');
-const client = new QueueBitClient('http://localhost:3000');
-
-// Browser
-const client = new QueueBitClient('http://localhost:3000');
-```
+| `url` | string | 'http://localhost:3333' | Server URL |
 
 ---
 
@@ -103,13 +74,6 @@ const client = new QueueBitClient('http://localhost:3000');
 
 Publishes a message to the queue.
 
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `message` | object | Yes | The message data (must be a JSON object) |
-| `options` | object | No | Publishing options |
-
 **Options:**
 
 | Option | Type | Description |
@@ -118,37 +82,22 @@ Publishes a message to the queue.
 | `expiry` | Date | Expiration date for the message |
 | `removeAfterRead` | boolean | Remove message after first delivery (default: false) |
 
-**Returns:** Promise<{ success: boolean, messageId?: string, error?: string }>
-
-**Examples:**
+**Returns:** `Promise<{ success: boolean, messageId?: string, error?: string }>`
 
 ```javascript
 // Basic publish
-const result = await client.publish({ 
-  text: 'Hello, World!' 
-});
-console.log(result); // { success: true, messageId: 'uuid-here' }
+await client.publish({ text: 'Hello, World!' });
 
-// Publish to specific subject
-await client.publish(
-  { orderId: 12345, status: 'pending' },
-  { subject: 'orders' }
-);
+// Publish to subject
+await client.publish({ orderId: 123 }, { subject: 'orders' });
 
-// Ephemeral message (removed after first read)
-await client.publish(
-  { notification: 'System update' },
-  { removeAfterRead: true }
-);
+// Ephemeral (removed after first read)
+await client.publish({ code: 'ABC' }, { removeAfterRead: true });
 
-// Message with expiry (expires in 1 hour)
-const expiryDate = new Date(Date.now() + 3600000);
+// With expiry
 await client.publish(
-  { tempData: 'expires soon' },
-  { 
-    subject: 'temp',
-    expiry: expiryDate 
-  }
+  { data: 'temp' },
+  { expiry: new Date(Date.now() + 3600000) }
 );
 ```
 
@@ -156,157 +105,72 @@ await client.publish(
 
 ### subscribe(callback, options)
 
-Subscribes to messages from the queue.
-
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `callback` | function | Yes | Function called when message is received |
-| `options` | object | No | Subscription options |
+Subscribes to messages. All existing non-ephemeral messages are replayed to new regular subscribers.
 
 **Options:**
 
 | Option | Type | Description |
 |--------|------|-------------|
 | `subject` | string | Subscribe to specific subject (default: 'default') |
-| `queue` | string | Join a queue group for load-balanced delivery |
-
-**Callback Signature:**
+| `queue` | string | Join a load balancer group for round-robin delivery |
 
-```javascript
-(message: QueueMessage) => void
-```
-
-**Returns:** Promise<{ success: boolean, subject?: string, queue?: string }>
-
-**Examples:**
+**Returns:** `Promise<{ success: boolean, subject: string, loadBalancer?: string, loadBalancerId?: number }>`
 
 ```javascript
-// Basic subscription
+// Regular subscription (all subscribers receive every message)
 await client.subscribe((message) => {
   console.log('Received:', message.data);
-});
+}, { subject: 'events' });
 
-// Subscribe to specific subject
-await client.subscribe(
-  (message) => {
-    console.log('Order received:', message.data);
-  },
-  { subject: 'orders' }
-);
-
-// Queue group (load-balanced across multiple subscribers)
-await client.subscribe(
-  (message) => {
-    console.log('Processing task:', message.data);
-    // Only one subscriber in the group receives this message
-  },
-  { 
-    subject: 'tasks',
-    queue: 'workers' 
-  }
-);
-
-// Multiple subjects
-await client.subscribe(
-  (message) => console.log('High priority:', message.data),
-  { subject: 'priority.high' }
-);
-
-await client.subscribe(
-  (message) => console.log('Low priority:', message.data),
-  { subject: 'priority.low' }
-);
+// Load balancer (only one subscriber receives each message, round-robin)
+await client.subscribe((message) => {
+  console.log('Processing:', message.data);
+}, { subject: 'tasks', queue: 'my-workers' });
 ```
 
+> **Note:** Load balancer subscriptions do **not** receive existing messages on subscribe, only new ones.
+
 ---
 
 ### unsubscribe(options)
 
 Unsubscribes from messages.
 
-**Parameters:**
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `options` | object | No | Unsubscription options |
-
 **Options:**
 
 | Option | Type | Description |
 |--------|------|-------------|
 | `subject` | string | Subject to unsubscribe from (default: 'default') |
-| `queue` | string | Queue group to leave |
-
-**Returns:** Promise<{ success: boolean }>
+| `queue` | string | Load balancer group to leave |
 
-**Examples:**
+**Returns:** `Promise<{ success: boolean }>`
 
 ```javascript
-// Unsubscribe from default subject
-await client.unsubscribe();
-
-// Unsubscribe from specific subject
 await client.unsubscribe({ subject: 'orders' });
-
-// Leave queue group
-await client.unsubscribe({ 
-  subject: 'tasks',
-  queue: 'workers' 
-});
+await client.unsubscribe({ subject: 'tasks', queue: 'my-workers' });
 ```
 
 ---
 
 ### getMessages(options)
 
-Retrieves all messages currently in the queue for a subject.
-
-**Parameters:**
+Retrieves all messages currently stored for a subject.
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `options` | object | No | Query options |
-
-**Options:**
-
-| Option | Type | Description |
-|--------|------|-------------|
-| `subject` | string | Subject to query (default: 'default') |
-
-**Returns:** Promise<{ success: boolean, messages: QueueMessage[], count: number }>
-
-**Examples:**
+**Returns:** `Promise<{ success: boolean, messages: QueueMessage[], count: number }>`
 
 ```javascript
-// Get all messages from default subject
-const result = await client.getMessages();
-console.log(`Found ${result.count} messages`);
-result.messages.forEach(msg => {
-  console.log(msg.data);
-});
-
-// Get messages from specific subject
-const orders = await client.getMessages({ subject: 'orders' });
-console.log(`${orders.count} pending orders`);
+const result = await client.getMessages({ subject: 'orders' });
+console.log(`${result.count} messages`);
+result.messages.forEach(msg => console.log(msg.data));
 ```
 
 ---
 
 ### disconnect()
 
-Disconnects from the server.
-
-```javascript
-client.disconnect();
-```
-
-**Example:**
+Disconnects the client from the server.
 
 ```javascript
-// Clean disconnect
-await client.unsubscribe();
 client.disconnect();
 ```
 
@@ -314,32 +178,45 @@ client.disconnect();
 
 ## Message Format
 
-### QueueMessage
-
-Every message in QueueBit has the following structure:
-
 ```typescript
 {
-  id: string,              // Unique message identifier (UUID)
+  id: string,              // Unique UUID
   data: object,            // Your message payload
   subject: string,         // Message subject/topic
-  timestamp: Date,         // When message was published
-  expiry?: Date,           // Optional expiration date
-  removeAfterRead: boolean // Whether to remove after first read
+  timestamp: Date,         // When published
+  expiry?: Date,           // Optional expiration
+  removeAfterRead: boolean,// Ephemeral flag
+  loadBalancerId?: number, // Set when delivered via load balancer
+  queueName?: string       // Load balancer group name (internal routing)
 }
 ```
 
-**Example:**
+---
+
+## Load Balancer
+
+Load balancers provide round-robin delivery across multiple subscribers. Each message is delivered to exactly one subscriber.
+
+- Each call to `subscribe` with a unique `queue` name creates a new load balancer with a unique numeric ID
+- Messages are distributed round-robin across all registered load balancers for a subject
+- Load balancer messages are **consumed** (not stored) after delivery
+- The `loadBalancerId` is included in delivered messages for identification
 
 ```javascript
-{
-  id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
-  data: { orderId: 12345, amount: 99.99 },
-  subject: 'orders',
-  timestamp: '2024-01-15T10:30:00.000Z',
-  expiry: null,
-  removeAfterRead: false
-}
+// Worker 1 - gets its own load balancer (e.g. LB#1)
+await worker1.subscribe((msg) => {
+  console.log(`LB#${msg.loadBalancerId} got:`, msg.data);
+}, { subject: 'jobs', queue: 'worker-1' });
+
+// Worker 2 - gets its own load balancer (e.g. LB#2)
+await worker2.subscribe((msg) => {
+  console.log(`LB#${msg.loadBalancerId} got:`, msg.data);
+}, { subject: 'jobs', queue: 'worker-2' });
+
+// Messages alternate: LB#1, LB#2, LB#1, LB#2, ...
+await publisher.publish({ job: 1 }, { subject: 'jobs' }); // → LB#1
+await publisher.publish({ job: 2 }, { subject: 'jobs' }); // → LB#2
+await publisher.publish({ job: 3 }, { subject: 'jobs' }); // → LB#1
 ```
 
 ---
@@ -349,229 +226,92 @@ Every message in QueueBit has the following structure:
 ### Basic Pub/Sub
 
 ```javascript
-const { QueueBitServer, QueueBitClient } = require('queuebit');
-
-// Start server
-const server = new QueueBitServer({ port: 3000 });
+const { QueueBitServer } = require('./src/server');
+const { QueueBitClient } = require('./src/client-node');
 
-// Create clients
-const publisher = new QueueBitClient('http://localhost:3000');
-const subscriber = new QueueBitClient('http://localhost:3000');
+const server = new QueueBitServer({ port: 3333 });
+const publisher = new QueueBitClient('http://localhost:3333');
+const subscriber = new QueueBitClient('http://localhost:3333');
 
-// Subscribe
 await subscriber.subscribe((message) => {
   console.log('Received:', message.data);
 });
 
-// Publish
 await publisher.publish({ text: 'Hello, World!' });
 ```
 
-### Request-Response Pattern
+### In-Process Server
 
 ```javascript
-// Responder
-await responder.subscribe(async (message) => {
-  const { requestId, question } = message.data;
-  
-  // Process request
-  const answer = processQuestion(question);
-  
-  // Send response
-  await responder.publish(
-    { requestId, answer },
-    { subject: 'responses' }
-  );
-}, { subject: 'requests' });
-
-// Requester
-const requestId = generateId();
-
-// Listen for response
-await requester.subscribe((message) => {
-  if (message.data.requestId === requestId) {
-    console.log('Answer:', message.data.answer);
-  }
-}, { subject: 'responses' });
-
-// Send request
-await requester.publish(
-  { requestId, question: 'What is 2+2?' },
-  { subject: 'requests' }
-);
-```
-
-### Work Queue Pattern
-
-```javascript
-// Producer
-for (let i = 0; i < 100; i++) {
-  await producer.publish(
-    { taskId: i, work: `Task ${i}` },
-    { subject: 'tasks' }
-  );
-}
-
-// Worker 1
-await worker1.subscribe((message) => {
-  console.log('Worker 1 processing:', message.data.taskId);
-}, { subject: 'tasks', queue: 'workers' });
-
-// Worker 2
-await worker2.subscribe((message) => {
-  console.log('Worker 2 processing:', message.data.taskId);
-}, { subject: 'tasks', queue: 'workers' });
-
-// Tasks are distributed between Worker 1 and Worker 2
-```
-
-### Expiring Messages
-
-```javascript
-// Publish message that expires in 5 minutes
-const expiryDate = new Date(Date.now() + 300000);
-
-await client.publish(
-  { 
-    code: 'ABC123',
-    description: 'Temporary access code' 
-  },
-  { 
-    subject: 'temp-codes',
-    expiry: expiryDate 
-  }
-);
-
-// Message is automatically removed after expiry
-```
-
-### One-Time Notifications
-
-```javascript
-// Publisher sends ephemeral notification
-await publisher.publish(
-  { alert: 'Server restarting in 5 minutes' },
-  { 
-    subject: 'alerts',
-    removeAfterRead: true 
-  }
-);
-
-// First subscriber gets the message
-await subscriber1.subscribe((message) => {
-  console.log('Alert:', message.data.alert); // Receives message
-}, { subject: 'alerts' });
-
-// Second subscriber connects later
-await subscriber2.subscribe((message) => {
-  console.log('Alert:', message.data.alert); // Won't receive it
-}, { subject: 'alerts' });
-```
-
-### Multi-Topic Subscription
-
-```javascript
-const client = new QueueBitClient('http://localhost:3000');
-
-// Subscribe to multiple topics
-await client.subscribe((msg) => {
-  console.log('User event:', msg.data);
-}, { subject: 'users' });
+const { QueueBitServer } = require('./src/server');
+const { QueueBitClient } = require('./src/client-node');
 
-await client.subscribe((msg) => {
-  console.log('Order event:', msg.data);
-}, { subject: 'orders' });
+// Start server and client in the same process
+const server = new QueueBitServer({ port: 3333 });
+const client = new QueueBitClient('http://localhost:3333');
 
 await client.subscribe((msg) => {
-  console.log('Payment event:', msg.data);
-}, { subject: 'payments' });
+  console.log('Got:', msg.data);
+});
 
-// Publish to different topics
-await client.publish({ action: 'login' }, { subject: 'users' });
-await client.publish({ orderId: 123 }, { subject: 'orders' });
-await client.publish({ amount: 50 }, { subject: 'payments' });
+await client.publish({ hello: 'world' });
 ```
 
----
-
-## Performance Tips
-
-1. **Use subjects** for routing instead of filtering in callbacks
-2. **Queue groups** for load balancing across multiple consumers
-3. **Batch publishing** when sending many messages
-4. **Remove old messages** using expiry to prevent memory issues
-5. **WebSocket transport** is faster than long-polling (default)
-
----
-
-## Error Handling
+### Work Queue
 
 ```javascript
-try {
-  const result = await client.publish({ data: 'test' });
-  if (!result.success) {
-    console.error('Publish failed:', result.error);
-  }
-} catch (error) {
-  console.error('Connection error:', error);
+// Producer
+for (let i = 0; i < 10; i++) {
+  await producer.publish({ taskId: i }, { subject: 'tasks' });
 }
 
-// Handle disconnection
-client.socket.on('disconnect', () => {
-  console.log('Disconnected from server');
-  // Implement reconnection logic
-});
+// Worker 1
+await worker1.subscribe((msg) => {
+  console.log('Worker 1:', msg.data.taskId);
+}, { subject: 'tasks', queue: 'worker-1' });
 
-client.socket.on('connect_error', (error) => {
-  console.error('Connection error:', error);
-});
+// Worker 2
+await worker2.subscribe((msg) => {
+  console.log('Worker 2:', msg.data.taskId);
+}, { subject: 'tasks', queue: 'worker-2' });
+// Tasks alternate between workers
 ```
 
 ---
 
 ## Browser Usage
 
-Include Socket.IO and QueueBit client in your HTML:
-
 ```html
 <script src="https://cdn.socket.io/4.7.2/socket.io.min.js"></script>
-<script src="node_modules/queuebit/src/client-browser.js"></script>
-
+<script src="src/client-browser.js"></script>
 <script>
-  const client = new QueueBitClient('http://localhost:3000');
+  const client = new QueueBitClient('http://localhost:3333');
   
   client.subscribe((message) => {
     console.log('Received:', message.data);
-  });
+  }, { subject: 'events' });
   
-  client.publish({ text: 'Hello from browser!' });
+  client.publish({ text: 'Hello from browser!' }, { subject: 'events' });
 </script>
 ```
 
----
-
-## NATS Compatibility
-
-QueueBit implements NATS-like patterns:
-
-- **Subjects**: Topic-based routing
-- **Queue Groups**: Load-balanced delivery
-- **At-least-once delivery**: Messages persisted until delivered
-- **Wildcards**: Not currently supported (planned)
+See [`examples/qpanel.html`](../examples/qpanel.html) for a full browser dashboard with publish, subscribe, load balancer, and performance testing.
 
 ---
 
-## Best Practices
-
-1. **Use meaningful subject names**: `orders.created`, `users.login`, etc.
-2. **Set appropriate expiry times** for temporary data
-3. **Clean up subscriptions** when no longer needed
-4. **Monitor queue sizes** to prevent memory issues
-5. **Use queue groups** for scalable message processing
-6. **Handle reconnection** in production applications
-
----
+## Error Handling
 
-## License
+```javascript
+try {
+  const result = await client.publish({ data: 'test' });
+  if (!result.success) {
+    console.error('Publish failed:', result.error);
+  }
+} catch (error) {
+  // Thrown on timeout (5 second default)
+  console.error('Publish error:', error.message);
+}
 
-MIT License - See LICENSE file for details
+client.socket.on('disconnect', () => console.log('Disconnected'));
+client.socket.on('connect_error', (err) => console.error('Connection error:', err));
+```