npm - @usermetrics/queuebit - Versions diffs - 1.0.0 - Mend

@usermetrics/queuebit 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/LICENSE +21 -0
package/README.md +276 -0
package/docs/API.md +577 -0
package/docs/EXAMPLES.md +330 -0
package/docs/QUICKSTART.md +122 -0
package/examples/browser-example.html +573 -0
package/package.json +52 -0
package/src/client-browser.js +134 -0
package/src/client-node.js +112 -0
package/src/client.js +73 -0
package/src/index.js +7 -0
package/src/server-runner.js +30 -0
package/src/server.js +292 -0

package/examples/browser-example.html ADDED Viewed

@@ -0,0 +1,573 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>QueueBit Browser Example</title>
+    <style>
+        body {
+            font-family: Arial, sans-serif;
+            max-width: 1200px;
+            margin: 20px auto;
+            padding: 10px;
+            font-size: 14px;
+        }
+        h1 {
+            margin: 0 0 15px 0;
+            font-size: 24px;
+        }
+        h2 {
+            margin: 0 0 8px 0;
+            font-size: 16px;
+        }
+        .row {
+            display: flex;
+            gap: 10px;
+            margin-bottom: 10px;
+        }
+        .col {
+            flex: 1;
+        }
+        .container {
+            border: 1px solid #ccc;
+            padding: 10px;
+            border-radius: 3px;
+            background: #f9f9f9;
+        }
+        button {
+            padding: 6px 12px;
+            margin: 2px;
+            cursor: pointer;
+            font-size: 12px;
+        }
+        button:disabled {
+            opacity: 0.5;
+            cursor: not-allowed;
+        }
+        #messages {
+            border: 1px solid #ddd;
+            padding: 8px;
+            height: 300px;
+            overflow-y: auto;
+            background: white;
+            font-size: 12px;
+        }
+        .message {
+            padding: 3px;
+            margin: 2px 0;
+            background: #f0f0f0;
+            border-left: 3px solid #4CAF50;
+            padding-left: 8px;
+        }
+        .perf-message {
+            border-left-color: #2196F3;
+            font-weight: bold;
+        }
+        input, select {
+            padding: 5px;
+            font-size: 12px;
+            margin: 2px;
+        }
+        input.small {
+            width: 150px;
+        }
+        input.medium {
+            width: 200px;
+        }
+        select {
+            width: 120px;
+        }
+        #perfStats {
+            background: #e3f2fd;
+            padding: 8px;
+            margin: 5px 0;
+            border-radius: 3px;
+            display: none;
+            font-size: 12px;
+        }
+        #status {
+            margin: 5px 0;
+            font-weight: bold;
+        }
+        #serverVersion {
+            font-size: 11px;
+            color: #666;
+            margin-top: 3px;
+        }
+    </style>
+</head>
+<body>
+    <h1>QueueBit Browser Client</h1>
+    <div class="row">
+        <div class="col container">
+            <h2>Connection</h2>
+            <input type="text" id="serverUrl" value="http://localhost:3333" class="medium">
+            <button onclick="connect()">Connect</button>
+            <button onclick="disconnect()">Disconnect</button>
+            <div id="status">Not connected</div>
+            <div id="serverVersion"></div>
+        </div>
+        <div class="col container">
+            <h2>Publish</h2>
+            <input type="text" id="messageText" placeholder="Message text" class="medium">
+            <input type="text" id="subject" placeholder="Subject" class="small">
+            <br>
+            <button onclick="publishMessage()">Publish</button>
+            <button onclick="publishEphemeral()">Ephemeral</button>
+        </div>
+    </div>
+    <div class="row">
+        <div class="col container">
+            <h2>Subscribe</h2>
+            <input type="text" id="subscribeSubject" placeholder="Subject" class="small">
+            <button onclick="subscribe()">Subscribe</button>
+            <button onclick="subscribeQueue()">Queue Group</button>
+        </div>
+        <div class="col container">
+            <h2>Queue Operations</h2>
+            <input type="text" id="getMessagesSubject" placeholder="Subject" class="small">
+            <button onclick="getAllMessages()">Get All</button>
+            <button onclick="clearMessages()">Clear Display</button>
+            <br>
+            <select id="testMessageCount">
+                <option value="100">100 messages</option>
+                <option value="1000">1,000 messages</option>
+                <option value="10000">10,000 messages</option>
+                <option value="100000">100,000 messages</option>
+                <option value="1000000" selected>1,000,000 messages</option>
+            </select>
+            <button id="perfTestBtn" onclick="runPerformanceTest()">Run Test</button>
+        </div>
+    </div>
+    <div class="container">
+        <h2>Messages</h2>
+        <div id="perfStats"></div>
+        <div id="messages"></div>
+    </div>
+    <!-- Include Socket.IO client from CDN -->
+    <script src="https://cdn.socket.io/4.7.2/socket.io.min.js"></script>
+    <!-- Include QueueBit client -->
+    <script src="../src/client-browser.js"></script>
+    <script>
+        let client = null;
+        let perfTestRunning = false;
+        let receivedCount = 0;
+        let lastUpdateTime = 0;
+        let publishEndTime = 0;
+        let isConnected = false;
+        function connect() {
+            const url = document.getElementById('serverUrl').value;
+            client = new QueueBitClient(url);
+            // Listen for connection status
+            client.socket.on('connect', () => {
+                isConnected = true;
+                document.getElementById('status').textContent = 'Connected to ' + url;
+                document.getElementById('status').style.color = 'green';
+            });
+            client.socket.on('disconnect', () => {
+                isConnected = false;
+                document.getElementById('status').textContent = 'Disconnected';
+                document.getElementById('status').style.color = 'red';
+            });
+            // Listen for server info
+            client.socket.on('serverInfo', (info) => {
+                document.getElementById('serverVersion').textContent = `Server: v${info.version}`;
+            });
+            document.getElementById('status').textContent = 'Connecting...';
+            document.getElementById('status').style.color = 'orange';
+        }
+        function disconnect() {
+            if (client) {
+                client.disconnect();
+                client = null;
+                isConnected = false;
+                document.getElementById('status').textContent = 'Disconnected';
+                document.getElementById('status').style.color = 'black';
+                document.getElementById('serverVersion').textContent = '';
+            }
+        }
+        async function publishMessage() {
+            if (!client || !isConnected) {
+                alert('Please connect first and wait for connection to be established');
+                return;
+            }
+            const text = document.getElementById('messageText').value;
+            const subject = document.getElementById('subject').value;
+            const options = {};
+            if (subject) options.subject = subject;
+            try {
+                const result = await client.publish({ text, timestamp: new Date() }, options);
+                console.log('Published:', result);
+                document.getElementById('messageText').value = '';
+            } catch (error) {
+                console.error('Publish error:', error);
+                alert('Failed to publish: ' + error.message);
+            }
+        }
+        async function publishEphemeral() {
+            if (!client || !isConnected) {
+                alert('Please connect first and wait for connection to be established');
+                return;
+            }
+            const text = document.getElementById('messageText').value;
+            const subject = document.getElementById('subject').value;
+            const options = { removeAfterRead: true };
+            if (subject) options.subject = subject;
+            try {
+                const result = await client.publish({ text, timestamp: new Date() }, options);
+                console.log('Published ephemeral:', result);
+                document.getElementById('messageText').value = '';
+            } catch (error) {
+                console.error('Publish error:', error);
+                alert('Failed to publish: ' + error.message);
+            }
+        }
+        async function subscribe() {
+            if (!client || !isConnected) {
+                alert('Please connect first and wait for connection to be established');
+                return;
+            }
+            const subject = document.getElementById('subscribeSubject').value || 'default';
+            await client.subscribe((message) => {
+                if (!perfTestRunning) {
+                    addMessage(`[${subject}] ${JSON.stringify(message.data)}`);
+                }
+            }, { subject });
+            console.log('Subscribed to:', subject);
+        }
+        async function subscribeQueue() {
+            if (!client || !isConnected) {
+                alert('Please connect first and wait for connection to be established');
+                return;
+            }
+            const subject = document.getElementById('subscribeSubject').value || 'default';
+            await client.subscribe((message) => {
+                if (!perfTestRunning) {
+                    addMessage(`[Queue: ${subject}] ${JSON.stringify(message.data)}`);
+                }
+            }, { subject, queue: 'browser-workers' });
+            console.log('Subscribed to queue group:', subject);
+        }
+        function addMessage(text, isPerf = false) {
+            const messagesDiv = document.getElementById('messages');
+            const messageDiv = document.createElement('div');
+            messageDiv.className = isPerf ? 'message perf-message' : 'message';
+            messageDiv.textContent = new Date().toLocaleTimeString() + ' - ' + text;
+            messagesDiv.appendChild(messageDiv);
+            messagesDiv.scrollTop = messagesDiv.scrollHeight;
+        }
+        function clearMessages() {
+            document.getElementById('messages').innerHTML = '';
+        }
+        async function getAllMessages() {
+            if (!client || !isConnected) {
+                alert('Please connect first and wait for connection to be established');
+                return;
+            }
+            const subject = document.getElementById('getMessagesSubject').value || 'default';
+            try {
+                const result = await client.getMessages({ subject });
+                if (result.success) {
+                    clearMessages();
+                    addMessage(`=== Retrieved ${result.count} messages from queue "${subject}" ===`);
+                    result.messages.forEach((msg, index) => {
+                        const timestamp = new Date(msg.timestamp).toLocaleString();
+                        const expiry = msg.expiry ? ` | Expires: ${new Date(msg.expiry).toLocaleString()}` : '';
+                        const ephemeral = msg.removeAfterRead ? ' | [Ephemeral]' : '';
+                        addMessage(`${index + 1}. [${timestamp}${expiry}${ephemeral}] ${JSON.stringify(msg.data)}`);
+                    });
+                    if (result.count === 0) {
+                        addMessage('No messages in queue');
+                    }
+                } else {
+                    addMessage('Error retrieving messages');
+                }
+            } catch (error) {
+                console.error('Error:', error);
+                addMessage('Error: ' + error.message);
+            }
+        }
+        async function runPerformanceTest() {
+            console.log('runPerformanceTest called');
+            console.log('client:', client);
+            console.log('isConnected:', isConnected);
+            if (!client) {
+                alert('Please connect first');
+                return;
+            }
+            if (!isConnected) {
+                alert('Waiting for connection to be established. Please try again in a moment.');
+                return;
+            }
+            if (perfTestRunning) {
+                alert('Performance test already running');
+                return;
+            }
+            const totalMessages = parseInt(document.getElementById('testMessageCount').value);
+            console.log('totalMessages:', totalMessages);
+            const confirmed = confirm(`This will send ${totalMessages.toLocaleString()} messages to the queue. Continue?`);
+            if (!confirmed) {
+                console.log('Test cancelled by user');
+                return;
+            }
+            console.log('Starting performance test...');
+            perfTestRunning = true;
+            receivedCount = 0;
+            lastUpdateTime = 0;
+            publishEndTime = 0;
+            // Larger batch sizes for better throughput
+            const batchSize = totalMessages >= 100000 ? 500 : (totalMessages >= 10000 ? 250 : 100);
+            const subject = 'perftest';
+            const perfBtn = document.getElementById('perfTestBtn');
+            const perfStats = document.getElementById('perfStats');
+            perfBtn.disabled = true;
+            perfStats.style.display = 'block';
+            perfStats.innerHTML = 'Starting performance test...';
+            clearMessages();
+            addMessage('=== Performance Test Started ===', true);
+            addMessage(`Testing with ${totalMessages.toLocaleString()} messages in batches of ${batchSize}`, true);
+            // Subscribe to performance test messages BEFORE publishing
+            addMessage('Subscribing to performance test subject...', true);
+            await client.subscribe((message) => {
+                receivedCount++;
+                // Update frequency based on message count
+                const updateInterval = totalMessages >= 100000 ? 5000 : (totalMessages >= 10000 ? 1000 : 100);
+                // Update stats at intervals or every 500ms
+                const now = performance.now();
+                if (receivedCount % updateInterval === 0 || (now - lastUpdateTime > 500)) {
+                    lastUpdateTime = now;
+                    if (publishEndTime > 0) {
+                        const receiveElapsed = ((now - publishEndTime) / 1000);
+                        const receiveRate = Math.round(receivedCount / (receiveElapsed || 0.1));
+                        perfStats.innerHTML = `
+                            <strong>Status:</strong> Receiving messages <br>
+                            <strong>Received:</strong> ${receivedCount.toLocaleString()} / ${totalMessages.toLocaleString()} (${(receivedCount/totalMessages*100).toFixed(1)}%)<br>
+                            <strong>Pending:</strong> ${(totalMessages - receivedCount).toLocaleString()} <br>
+                            <strong>Receive Rate:</strong> ${receiveRate.toLocaleString()} msg/s
+                        `;
+                    }
+                }
+            }, { subject });
+            await new Promise(resolve => setTimeout(resolve, 1000)); // Give subscription time to register
+            const startTime = performance.now();
+            let publishStartTime = performance.now();
+            let publishedCount = 0;
+            let failedCount = 0;
+            try {
+                addMessage('Publishing messages...', true);
+                // Send messages in larger batches
+                for (let i = 0; i < totalMessages; i += batchSize) {
+                    const batchPromises = [];
+                    const currentBatchSize = Math.min(batchSize, totalMessages - i);
+                    for (let j = 0; j < currentBatchSize; j++) {
+                        const promise = client.publish({
+                            id: i + j,
+                            data: `Message ${i + j}`,
+                            timestamp: Date.now()
+                        }, { subject }).then(result => {
+                            if (result && result.success) {
+                                publishedCount++;
+                            } else {
+                                failedCount++;
+                                if (!result) {
+                                    console.error('No response from server for message', i + j);
+                                }
+                            }
+                            return result;
+                        }).catch(err => {
+                            failedCount++;
+                            console.error('Publish error:', err);
+                        });
+                        batchPromises.push(promise);
+                    }
+                    await Promise.all(batchPromises);
+                    // Reduce delay for better throughput
+                    if (totalMessages >= 100000 && i % 5000 === 0) {
+                        await new Promise(resolve => setTimeout(resolve, 1));
+                    }
+                    // Update progress every batch
+                    const progress = ((i + currentBatchSize) / totalMessages * 100).toFixed(1);
+                    const elapsed = ((performance.now() - startTime) / 1000).toFixed(2);
+                    const messagesPerSec = Math.round(publishedCount / (elapsed || 1));
+                    perfStats.innerHTML = `
+                        <strong>Progress:</strong> ${progress}% (${(i + currentBatchSize).toLocaleString()} / ${totalMessages.toLocaleString()}) <br>
+                        <strong>Elapsed:</strong> ${elapsed}s <br>
+                        <strong>Published:</strong> ${publishedCount.toLocaleString()} <br>
+                        ${failedCount > 0 ? `<strong style="color: red;">Failed:</strong> ${failedCount.toLocaleString()} <br>` : ''}
+                        <strong>Publish Throughput:</strong> ${messagesPerSec.toLocaleString()} msg/s <br>
+                        <strong>Received So Far:</strong> ${receivedCount.toLocaleString()}
+                    `;
+                }
+                publishEndTime = performance.now();
+                const publishDuration = (publishEndTime - publishStartTime) / 1000;
+                addMessage(`Published ${publishedCount.toLocaleString()} messages in ${publishDuration.toFixed(2)}s! Waiting for delivery...`, true);
+                if (failedCount > 0) {
+                    addMessage(`⚠ ${failedCount.toLocaleString()} messages failed to publish`, true);
+                }
+                // Wait for all messages to be received with timeout
+                const maxWaitTime = 300000; // 5 minutes timeout
+                const waitStartTime = performance.now();
+                let lastReceivedCount = 0;
+                let stuckCounter = 0;
+                while (receivedCount < publishedCount) {
+                    await new Promise(resolve => setTimeout(resolve, 500));
+                    // Check if we're stuck
+                    if (receivedCount === lastReceivedCount) {
+                        stuckCounter++;
+                        if (stuckCounter > 20) { // Stuck for 10 seconds
+                            addMessage(`⚠ Appears stuck at ${receivedCount.toLocaleString()} messages`, true);
+                            break;
+                        }
+                    } else {
+                        stuckCounter = 0;
+                    }
+                    lastReceivedCount = receivedCount;
+                    const elapsed = ((performance.now() - startTime) / 1000).toFixed(2);
+                    const waitTime = ((performance.now() - waitStartTime) / 1000).toFixed(2);
+                    const receiveElapsed = ((performance.now() - publishEndTime) / 1000);
+                    const receiveRate = Math.round(receivedCount / (receiveElapsed || 0.1));
+                    perfStats.innerHTML = `
+                        <strong>Status:</strong> Waiting for delivery completion <br>
+                        <strong>Total Elapsed:</strong> ${elapsed}s <br>
+                        <strong>Wait Time:</strong> ${waitTime}s <br>
+                        <strong>Received:</strong> ${receivedCount.toLocaleString()} / ${publishedCount.toLocaleString()} (${(receivedCount/publishedCount*100).toFixed(1)}%)<br>
+                        <strong>Pending:</strong> ${(publishedCount - receivedCount).toLocaleString()} <br>
+                        <strong>Receive Rate:</strong> ${receiveRate.toLocaleString()} msg/s
+                    `;
+                    // Timeout check
+                    if (performance.now() - waitStartTime > maxWaitTime) {
+                        addMessage(`⚠ Timeout after ${maxWaitTime/1000}s - only ${receivedCount.toLocaleString()} messages received`, true);
+                        break;
+                    }
+                }
+                const endTime = performance.now();
+                const totalDuration = (endTime - startTime) / 1000;
+                const receiveDuration = (endTime - publishEndTime) / 1000;
+                // Calculate statistics
+                const avgPublishRate = Math.round(publishedCount / publishDuration);
+                const avgReceiveRate = Math.round(receivedCount / receiveDuration);
+                const avgTotalRate = Math.round(receivedCount / totalDuration);
+                const successRate = ((receivedCount / publishedCount) * 100).toFixed(2);
+                addMessage('=== Performance Test Complete ===', true);
+                addMessage(`Total Messages Attempted: ${totalMessages.toLocaleString()}`, true);
+                addMessage(`Messages Published: ${publishedCount.toLocaleString()}`, true);
+                addMessage(`Messages Received: ${receivedCount.toLocaleString()}`, true);
+                addMessage(`Success Rate: ${successRate}%`, true);
+                if (failedCount > 0) {
+                    addMessage(`⚠ Failed to Publish: ${failedCount.toLocaleString()}`, true);
+                }
+                if (receivedCount < publishedCount) {
+                    addMessage(`⚠ Missing Messages: ${(publishedCount - receivedCount).toLocaleString()}`, true);
+                }
+                addMessage(`Total Time: ${totalDuration.toFixed(2)}s`, true);
+                addMessage(`Publish Time: ${publishDuration.toFixed(2)}s`, true);
+                addMessage(`Receive Time: ${receiveDuration.toFixed(2)}s`, true);
+                addMessage(`Average Publish Rate: ${avgPublishRate.toLocaleString()} msg/s`, true);
+                addMessage(`Average Receive Rate: ${avgReceiveRate.toLocaleString()} msg/s`, true);
+                addMessage(`Overall Throughput: ${avgTotalRate.toLocaleString()} msg/s`, true);
+                const statusIcon = receivedCount === publishedCount ? '✓' : '⚠';
+                perfStats.innerHTML = `
+                    <strong>${statusIcon} Test Complete!</strong><br>
+                    <strong>Messages Attempted:</strong> ${totalMessages.toLocaleString()}<br>
+                    <strong>Messages Published:</strong> ${publishedCount.toLocaleString()}<br>
+                    <strong>Messages Received:</strong> ${receivedCount.toLocaleString()}<br>
+                    <strong>Success Rate:</strong> ${successRate}%<br>
+                    ${failedCount > 0 ? `<strong style="color: red;">Failed to Publish:</strong> ${failedCount.toLocaleString()}<br>` : ''}
+                    ${receivedCount < publishedCount ? `<strong style="color: orange;">Missing:</strong> ${(publishedCount - receivedCount).toLocaleString()}<br>` : ''}
+                    <strong>Total Time:</strong> ${totalDuration.toFixed(2)}s<br>
+                    <strong>Publish Time:</strong> ${publishDuration.toFixed(2)}s<br>
+                    <strong>Receive Time:</strong> ${receiveDuration.toFixed(2)}s<br>
+                    <strong>Publish Rate:</strong> ${avgPublishRate.toLocaleString()} msg/s<br>
+                    <strong>Receive Rate:</strong> ${avgReceiveRate.toLocaleString()} msg/s<br>
+                    <strong>Overall Throughput:</strong> ${avgTotalRate.toLocaleString()} msg/s
+                `;
+            } catch (error) {
+                addMessage('Error during performance test: ' + error.message, true);
+                console.error('Performance test error:', error);
+            } finally {
+                perfTestRunning = false;
+                perfBtn.disabled = false;
+                // Unsubscribe from perftest subject
+                await client.unsubscribe({ subject });
+            }
+        }
+    </script>
+</body>
+</html>

package/package.json ADDED Viewed

@@ -0,0 +1,52 @@
+{
+  "name": "@usermetrics/queuebit",
+  "version": "1.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "A socket server API for using a queue with guaranteed delivery",
+  "main": "src/index.js",
+  "browser": "src/client-browser.js",
+  "scripts": {
+    "test": "node test/test-harness.js",
+    "start": "node src/index.js",
+    "server": "node src/server-runner.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "queue",
+    "socket",
+    "nats",
+    "message-queue",
+    "websocket",
+    "pubsub",
+    "realtime"
+  ],
+  "author": "Karl Lilje <karl@karllilje.com>",
+  "license": "MIT",
+  "dependencies": {
+    "socket.io": "^4.7.2",
+    "uuid": "^9.0.1"
+  },
+  "devDependencies": {
+    "socket.io-client": "^4.7.2"
+  },
+  "files": [
+    "src/",
+    "docs/",
+    "examples/",
+    "LICENSE",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bigfun123/queuebit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bigfun123/queuebit/issues"
+  },
+  "homepage": "https://github.com/bigfun123/queuebit#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  }
+}