@emanuelepifani/nexo-client 0.1.1 → 0.3.8

package/README.md

@@ -1,6 +1,8 @@
 # Nexo Client SDK
 
-High-performance TypeScript client for [Nexo](https://github.com/emanuel-epifani/nexo).
+High-performance TypeScript client for [Nexo](https://nexo-docs-hub.vercel.app/).
+
+
 
 ## Quick Start
 
@@ -19,6 +21,7 @@ This exposes:
 npm install @emanuelepifani/nexo-client
 ```
 
+
 ### Connection
 ```typescript
 const client = await NexoClient.connect({ host: 'localhost', port: 7654 });
@@ -48,57 +51,6 @@ await mailQ.subscribe((msg) => console.log(msg));
 await mailQ.delete();
 ```
 
-<details>
-<summary><strong>Advanced Features (Persistence, Retry, Delay, Priority)</strong></summary>
-
-```typescript
-// -------------------------------------------------------------
-// 1. CREATION (Default behavior for all messages in this queue)
-// -------------------------------------------------------------
-interface CriticalTask { type: string; payload: any; }
-
-const criticalQueue = await client.queue<CriticalTask>('critical-tasks').create({
-    // RELIABILITY:
-    visibilityTimeoutMs: 10000, // Retry delivery if not ACKed within 10s   (default=30s)
-    maxRetries: 5,              // Move to DLQ after 5 failures             (default=5)
-    ttlMs: 60000,               // Message expires if not consumed in 60s   (default=7days)
-
-    // PERSISTENCE:
-    // - 'memory':     Volatile (Fastest, lost on restart)
-    // - 'file_sync':  Save every message (Safest, Slowest)
-    // - 'file_async': Flush periodically (Fast & Durable) - 
-    // DEFAULT: 'file_async': Flush every 50ms or 5000 msgs
-    persistence: 'file_sync',
-});
-
-
-// ---------------------------------------------------------
-// 2. PRODUCING (Override specific behaviors per message)
-// ---------------------------------------------------------
-
-// PRIORITY: Higher value (255) delivered before lower values (0)
-// This message jumps ahead of all priority < 255 messages sent previously and still not consumed.
-await criticalQueue.push({ type: 'urgent' }, { priority: 255 });
-
-// SCHEDULING: Delay visibility
-// This message is hidden for 1 hour (default delayMs: 0, instant)
-await criticalQueue.push({ type: 'scheduled' }, { delayMs: 3600000 });
-
-
-
-// ---------------------------------------------------------
-// 3. CONSUMING (Worker Tuning to optimize throughput and latency)
-// ---------------------------------------------------------
-await criticalQueue.subscribe(
-    async (task) => { await processTask(task); },
-    {
-        batchSize: 100,   // Network: Fetch 100 messages in one request
-        concurrency: 10,  // Local: Process 10 messages concurrently (useful for I/O tasks)
-        waitMs: 5000      // Polling: If empty, wait 5s for new messages before retrying
-    }
-);
-```
-</details>
 
 ### 3. PUB/SUB
 
@@ -111,35 +63,6 @@ await alerts.subscribe((msg) => console.log(msg));
 await alerts.publish({ level: "high" });
 ```
 
-<details>
-<summary><strong>Wildcards & Retained Messages</strong></summary>
-
-```typescript
-// WILDCARD SUBSCRIPTIONS
-// ----------------------
-
-// 1. Single-Level Wildcard (+)
-// Matches: 'home/kitchen/light', 'home/garage/light'
-const roomLights = client.pubsub<LightStatus>('home/+/light');
-await roomLights.subscribe((status) => console.log('Light is:', status.state));
-
-// 2. Multi-Level Wildcard (#)
-// Matches all topics under 'sensors/'
-const allSensors = client.pubsub<SensorData>('sensors/#');
-await allSensors.subscribe((data) => console.log('Sensor value:', data.value));
-
-// PUBLISHING (No wildcards allowed!)
-// ---------------------------------
-// You must publish to concrete topics with matching types
-await client.pubsub<LightStatus>('home/kitchen/light').publish({ state: 'ON' });
-await client.pubsub<SensorData>('sensors/kitchen/temp').publish({ value: 22.5, unit: 'C' });
-
-// RETAINED MESSAGES
-// -----------------
-// Last value is stored and immediately sent to new subscribers
-await client.pubsub<string>('config/theme').publish('dark', { retain: true });
-```
-</details>
 
 ### 4. STREAM
 
@@ -154,60 +77,14 @@ await stream.subscribe('analytics', (msg) => {console.log(`User ${msg.userId} pe
 await stream.delete();
 ```
 
-<details>
-<summary><strong>Advanced Features (Consumer Groups, Persistence, Retention)</strong></summary>
-
-```typescript
-// ---------------------------------------------------------
-// 1. STREAM CREATION & POLICY
-// ---------------------------------------------------------
-const orders = await client.stream<Order>('orders').create({
-    // SCALING
-    partitions: 4,              // Max concurrent consumers per group on same topic (default=8)
-
-    // PERSISTENCE:
-    // - 'memory':     Volatile (Fastest, lost on restart)
-    // - 'file_sync':  Save every message (Safest, Slowest)
-    // - 'file_async': Flush periodically (Fast & Durable) - 
-    // DEFAULT: 'file_async': Flush every 50ms or 5000 msgs
-    persistence: 'file_sync',
-
-    // RETENTION (Cleanup Policy)
-    // --------------------------
-    // Delete old data when EITHER limit is reached:
-    retention: {
-        maxAgeMs: 86400000,     // 1 Day (Default: 7 Days)
-        maxBytes: 536870912     // 512 MB (Default: 1 GB)
-    },
-});
-
-// ---------------------------------------------------------
-// 2. CONSUMING (Scaling & Broadcast patterns)
-// ---------------------------------------------------------
-
-// SCALING (Microservices Replicas / K8s Pods)
-// Same Group ('workers') -> Automatic Load Balancing & Rebalancing
-// Partitions are distributed among workers.
-await orders.subscribe('workers', (order) => process(order));
-await orders.subscribe('workers', (order) => process(order));
-
-
-// BROADCAST (Independent Domains)
-// Different Groups -> Each group gets a full copy of the stream.
-// Useful for independent services reacting to the same event.
-await orders.subscribe('analytics', (order) => trackMetrics(order));
-await orders.subscribe('audit-log', (order) => saveAudit(order));
-```
-</details>
-
 
 
 ---
 
-### Binary Payloads (Zero-Overhead)
+### Binary Payloads
 
 All Nexo brokers (**Store, Queue, Stream, PubSub**) natively support raw binary data (`Buffer`).    
-Bypassing JSON serialization drastically reduces Latency, increases Throughput, and saves Bandwidth (~30% smaller payloads) .
+Bypassing JSON serialization drastically reduces Latency, increases Throughput, and saves Bandwidth.
 
 **Perfect for:** Video chunks, Images, Protobuf/MsgPack, Encrypted blobs.
 
@@ -215,16 +92,13 @@ Bypassing JSON serialization drastically reduces Latency, increases Throughput,
 // Send 1MB raw buffer (30% smaller than JSON/Base64)
 const heavyPayload = Buffer.alloc(1024 * 1024);
 
-// 1. STREAM: Replayable Data (e.g. CCTV Recording, Event Sourcing)
+// 1. STREAM
 await client.stream('cctv-archive').publish(heavyPayload);
-
-// 2. PUBSUB: Ephemeral Live Data (e.g. VoIP, Real-time Sensor)
+// 2. PUBSUB 
 await client.pubsub('live-audio-call').publish(heavyPayload);
-
-// 3. STORE (Cache Images)
+// 3. STORE
 await client.store.map.set('user:avatar:1', heavyPayload);
-
-// 4. QUEUE (Process Files)
+// 4. QUEUE
 await client.queue('pdf-processing').push(heavyPayload);
 ```
 
@@ -237,10 +111,8 @@ MIT
 
 ## Links
 
-- **Nexo Broker (Server):** [GitHub Repository](https://github.com/emanuel-epifani/nexo)
-- **Server Docs:** [Nexo Internals & Architecture](https://github.com/emanuel-epifani/nexo/tree/main/docs)
-- **SDK Source:** [sdk/ts](https://github.com/emanuel-epifani/nexo/tree/main/sdk/ts)
-- **Docker Image:** [emanuelepifani/nexo](https://hub.docker.com/r/emanuelepifani/nexo)
+- **📚 Full Documentation:** [Nexo Docs](https://nexo-docs-hub.vercel.app/)
+- **🐳 Docker Image:** [emanuelepifani/nexo](https://hub.docker.com/r/emanuelepifani/nexo)
 
 ## Author
 

package/dist/brokers/queue.d.ts

@@ -1,6 +1,6 @@
 import { NexoConnection } from '../connection';
 import { Logger } from '../utils/logger';
-export type PersistenceStrategy = 'memory' | 'file_sync' | 'file_async';
+export type PersistenceStrategy = 'file_sync' | 'file_async';
 export interface QueueConfig {
     visibilityTimeoutMs?: number;
     maxRetries?: number;
@@ -16,12 +16,61 @@ export interface QueuePushOptions {
     priority?: number;
     delayMs?: number;
 }
+/**
+ * Dead Letter Queue (DLQ) management for a queue.
+ * Provides methods to inspect, replay, delete, and purge failed messages.
+ */
+export declare class NexoDLQ<T = any> {
+    private conn;
+    private queueName;
+    private logger;
+    constructor(conn: NexoConnection, queueName: string, logger: Logger);
+    /**
+     * Peek messages in the DLQ without consuming them.
+     * @param limit Maximum number of messages to return (default: 10)
+     * @param offset Pagination offset (default: 0)
+     * @returns Object containing total count and array of messages
+     */
+    peek(limit?: number, offset?: number): Promise<{
+        total: number;
+        items: {
+            id: string;
+            data: T;
+            attempts: number;
+            failureReason: string;
+        }[];
+    }>;
+    /**
+     * Move a message from DLQ back to the main queue (replay/retry).
+     * The message will be reset with attempts = 0 and become available for consumption.
+     * @param messageId ID of the message to move
+     * @returns true if the message was moved, false if not found
+     */
+    moveToQueue(messageId: string): Promise<boolean>;
+    /**
+     * Delete a specific message from the DLQ.
+     * @param messageId ID of the message to delete
+     * @returns true if the message was deleted, false if not found
+     */
+    delete(messageId: string): Promise<boolean>;
+    /**
+     * Purge all messages from the DLQ.
+     * @returns Number of messages purged
+     */
+    purge(): Promise<number>;
+}
 export declare class NexoQueue<T = any> {
     private conn;
     readonly name: string;
     private logger;
     private isSubscribed;
+    private _dlq;
     constructor(conn: NexoConnection, name: string, logger: Logger);
+    /**
+     * Access the Dead Letter Queue (DLQ) for this queue.
+     * Use this to inspect, replay, delete, or purge failed messages.
+     */
+    get dlq(): NexoDLQ<T>;
     create(config?: QueueConfig): Promise<this>;
     exists(): Promise<boolean>;
     delete(): Promise<void>;
@@ -30,4 +79,5 @@ export declare class NexoQueue<T = any> {
         stop: () => void;
     }>;
     private ack;
+    private nack;
 }

package/dist/brokers/queue.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NexoQueue = void 0;
+exports.NexoQueue = exports.NexoDLQ = void 0;
 const codec_1 = require("../codec");
 const errors_1 = require("../errors");
 var QueueOpcode;
@@ -11,6 +11,11 @@ var QueueOpcode;
     QueueOpcode[QueueOpcode["Q_ACK"] = 19] = "Q_ACK";
     QueueOpcode[QueueOpcode["Q_EXISTS"] = 20] = "Q_EXISTS";
     QueueOpcode[QueueOpcode["Q_DELETE"] = 21] = "Q_DELETE";
+    QueueOpcode[QueueOpcode["Q_PEEK_DLQ"] = 22] = "Q_PEEK_DLQ";
+    QueueOpcode[QueueOpcode["Q_MOVE_TO_QUEUE"] = 23] = "Q_MOVE_TO_QUEUE";
+    QueueOpcode[QueueOpcode["Q_DELETE_DLQ"] = 24] = "Q_DELETE_DLQ";
+    QueueOpcode[QueueOpcode["Q_PURGE_DLQ"] = 25] = "Q_PURGE_DLQ";
+    QueueOpcode[QueueOpcode["Q_NACK"] = 26] = "Q_NACK";
 })(QueueOpcode || (QueueOpcode = {}));
 const QueueCommands = {
     create: (conn, name, config) => conn.send(QueueOpcode.Q_CREATE, codec_1.FrameCodec.string(name), codec_1.FrameCodec.string(JSON.stringify(config || {}))),
@@ -41,6 +46,36 @@ const QueueCommands = {
         return messages;
     },
     ack: (conn, name, id) => conn.send(QueueOpcode.Q_ACK, codec_1.FrameCodec.uuid(id), codec_1.FrameCodec.string(name)),
+    nack: (conn, name, id, reason) => conn.send(QueueOpcode.Q_NACK, codec_1.FrameCodec.uuid(id), codec_1.FrameCodec.string(name), codec_1.FrameCodec.string(reason)),
+    // DLQ Commands
+    peekDLQ: async (conn, name, limit, offset) => {
+        const res = await conn.send(QueueOpcode.Q_PEEK_DLQ, codec_1.FrameCodec.string(name), codec_1.FrameCodec.u32(limit), codec_1.FrameCodec.u32(offset));
+        const total = res.cursor.readU32();
+        const count = res.cursor.readU32();
+        const items = [];
+        for (let i = 0; i < count; i++) {
+            const idHex = res.cursor.readUUID();
+            const payloadLen = res.cursor.readU32();
+            const payloadBuf = res.cursor.readBuffer(payloadLen);
+            const data = codec_1.FrameCodec.decodeAny(new codec_1.Cursor(payloadBuf));
+            const attempts = res.cursor.readU32();
+            const failureReason = res.cursor.readString();
+            items.push({ id: idHex, data, attempts, failureReason });
+        }
+        return { total, items };
+    },
+    moveToQueue: async (conn, name, messageId) => {
+        const res = await conn.send(QueueOpcode.Q_MOVE_TO_QUEUE, codec_1.FrameCodec.string(name), codec_1.FrameCodec.uuid(messageId));
+        return res.cursor.readU8() === 1;
+    },
+    deleteDLQ: async (conn, name, messageId) => {
+        const res = await conn.send(QueueOpcode.Q_DELETE_DLQ, codec_1.FrameCodec.string(name), codec_1.FrameCodec.uuid(messageId));
+        return res.cursor.readU8() === 1;
+    },
+    purgeDLQ: async (conn, name) => {
+        const res = await conn.send(QueueOpcode.Q_PURGE_DLQ, codec_1.FrameCodec.string(name));
+        return res.cursor.readU32();
+    },
 };
 async function runConcurrent(items, concurrency, fn) {
     if (concurrency === 1) {
@@ -55,12 +90,69 @@ async function runConcurrent(items, concurrency, fn) {
     });
     await Promise.all(workers);
 }
+/**
+ * Dead Letter Queue (DLQ) management for a queue.
+ * Provides methods to inspect, replay, delete, and purge failed messages.
+ */
+class NexoDLQ {
+    constructor(conn, queueName, logger) {
+        this.conn = conn;
+        this.queueName = queueName;
+        this.logger = logger;
+    }
+    /**
+     * Peek messages in the DLQ without consuming them.
+     * @param limit Maximum number of messages to return (default: 10)
+     * @param offset Pagination offset (default: 0)
+     * @returns Object containing total count and array of messages
+     */
+    async peek(limit = 10, offset = 0) {
+        this.logger.debug(`[DLQ:${this.queueName}] Peeking ${limit} messages at offset ${offset}`);
+        return QueueCommands.peekDLQ(this.conn, this.queueName, limit, offset);
+    }
+    /**
+     * Move a message from DLQ back to the main queue (replay/retry).
+     * The message will be reset with attempts = 0 and become available for consumption.
+     * @param messageId ID of the message to move
+     * @returns true if the message was moved, false if not found
+     */
+    async moveToQueue(messageId) {
+        this.logger.debug(`[DLQ:${this.queueName}] Moving message ${messageId} to main queue`);
+        return QueueCommands.moveToQueue(this.conn, this.queueName, messageId);
+    }
+    /**
+     * Delete a specific message from the DLQ.
+     * @param messageId ID of the message to delete
+     * @returns true if the message was deleted, false if not found
+     */
+    async delete(messageId) {
+        this.logger.debug(`[DLQ:${this.queueName}] Deleting message ${messageId}`);
+        return QueueCommands.deleteDLQ(this.conn, this.queueName, messageId);
+    }
+    /**
+     * Purge all messages from the DLQ.
+     * @returns Number of messages purged
+     */
+    async purge() {
+        this.logger.debug(`[DLQ:${this.queueName}] Purging all messages`);
+        return QueueCommands.purgeDLQ(this.conn, this.queueName);
+    }
+}
+exports.NexoDLQ = NexoDLQ;
 class NexoQueue {
     constructor(conn, name, logger) {
         this.conn = conn;
         this.name = name;
         this.logger = logger;
         this.isSubscribed = false;
+        this._dlq = new NexoDLQ(conn, name, logger);
+    }
+    /**
+     * Access the Dead Letter Queue (DLQ) for this queue.
+     * Use this to inspect, replay, delete, or purge failed messages.
+     */
+    get dlq() {
+        return this._dlq;
     }
     async create(config = {}) {
         await QueueCommands.create(this.conn, this.name, config);
@@ -93,8 +185,6 @@ class NexoQueue {
                     await new Promise(r => setTimeout(r, 500));
                     continue;
                 }
-                // Add small jitter to avoid thundering herd on reconnect
-                await new Promise(r => setTimeout(r, Math.random() * 500));
                 try {
                     // Double check before sending
                     if (!this.conn.isConnected)
@@ -103,8 +193,13 @@ class NexoQueue {
                     if (messages.length === 0)
                         continue;
                     await runConcurrent(messages, concurrency, async (msg) => {
-                        if (!active)
+                        if (!active) {
+                            if (this.conn.isConnected) {
+                                // If stopped while consuming, release message immediately so it's available for others
+                                await this.nack(msg.id, "Consumer stopped").catch(() => { });
+                            }
                             return;
+                        }
                         try {
                             await callback(msg.data);
                             await this.ack(msg.id);
@@ -112,7 +207,9 @@ class NexoQueue {
                         catch (e) {
                             if (!this.conn.isConnected)
                                 return;
-                            this.logger.error(`Callback error in queue ${this.name}:`, e);
+                            const reason = e instanceof Error ? e.message : String(e);
+                            this.logger.error(`[Queue:${this.name}] Consumer error, sending NACK. Reason: ${reason}`);
+                            await this.nack(msg.id, reason);
                         }
                     });
                 }
@@ -133,10 +230,18 @@ class NexoQueue {
         loop().catch(err => {
             this.logger.error(`[CRITICAL] Queue loop crashed for ${this.name}`, err);
         });
-        return { stop: () => { active = false; } };
+        return {
+            stop: () => {
+                active = false;
+                this.isSubscribed = false;
+            }
+        };
     }
     async ack(id) {
         await QueueCommands.ack(this.conn, this.name, id);
     }
+    async nack(id, reason) {
+        await QueueCommands.nack(this.conn, this.name, id, reason);
+    }
 }
 exports.NexoQueue = NexoQueue;

package/dist/brokers/stream.d.ts

@@ -1,6 +1,6 @@
 import { NexoConnection } from '../connection';
 import { Logger } from '../utils/logger';
-export type PersistenceStrategy = 'memory' | 'file_sync' | 'file_async';
+export type PersistenceStrategy = 'file_sync' | 'file_async';
 export interface RetentionOptions {
     maxAgeMs: number;
     maxBytes: number;

package/dist/brokers/stream.js

@@ -85,8 +85,6 @@ class StreamSubscription {
                 await this.backoff(500);
                 continue;
             }
-            // Jitter to avoid thundering herd
-            await this.backoff(Math.random() * 500);
             try {
                 if (!this.conn.isConnected)
                     continue;

package/dist/codec.js

@@ -51,7 +51,10 @@ class FrameCodec {
         return result;
     }
     static uuid(hex) {
-        return Buffer.from(hex, 'hex');
+        // Remove dashes from UUID format (e.g., "550e8400-e29b-41d4-a716-446655440000")
+        // This handles both formats: with dashes (from crypto.randomUUID()) and without (from server)
+        const cleanHex = hex.replace(/-/g, '');
+        return Buffer.from(cleanHex, 'hex');
     }
     static any(data) {
         let type = protocol_1.DataType.RAW;
@@ -74,25 +77,24 @@ class FrameCodec {
         return result;
     }
     static packRequest(id, opcode, ...parts) {
-        // 1. Calcolo dimensione PAYLOAD (Opcode [1 byte] + Argomenti)
-        let payloadSize = 1;
+        // 1. Calcolo dimensione PAYLOAD
+        let payloadSize = 0;
         for (const part of parts)
             payloadSize += part.length;
-        // 2. Allocazione buffer TOTALE (Header [9 bytes] + Payload)
-        // Header è sempre fisso a 9 bytes: [Type:1][ID:4][Len:4]
-        const result = Buffer.allocUnsafe(9 + payloadSize);
-        // --- SCRITTURA HEADER (Bytes 0-8) ---
+        // 2. Allocazione buffer TOTALE (Header [10 bytes] + Payload)
+        // Header: [Type:1][Opcode:1][ID:4][Len:4]
+        const result = Buffer.allocUnsafe(10 + payloadSize);
+        // --- SCRITTURA HEADER (Bytes 0-9) ---
         // Byte 0: Tipo di Frame (REQUEST = 0x01)
         result.writeUInt8(protocol_1.FrameType.REQUEST, 0);
-        // Bytes 1-4: ID della richiesta (UInt32 Big Endian)
-        result.writeUInt32BE(id, 1);
-        // Bytes 5-8: Lunghezza del Payload (UInt32 Big Endian)
-        // Questo dice al server quanti byte leggere dopo l'header
-        result.writeUInt32BE(payloadSize, 5);
-        // --- SCRITTURA PAYLOAD (Bytes 9+) ---
-        // Byte 9: Opcode (Il primo byte del payload è sempre l'operazione)
-        result.writeUInt8(opcode, 9);
-        // Bytes 10+: Copia degli argomenti (dati effettivi)
+        // Byte 1: Opcode
+        result.writeUInt8(opcode, 1);
+        // Bytes 2-5: ID della richiesta (UInt32 Big Endian)
+        result.writeUInt32BE(id, 2);
+        // Bytes 6-9: Lunghezza del Payload (UInt32 Big Endian)
+        result.writeUInt32BE(payloadSize, 6);
+        // --- SCRITTURA PAYLOAD (Bytes 10+) ---
+        // Copia degli argomenti (dati effettivi)
         let offset = 10;
         for (const part of parts) {
             part.copy(result, offset);

package/dist/connection.js

@@ -54,7 +54,7 @@ class NexoConnection extends events_1.EventEmitter {
         this.port = options.port;
         this.logger = logger;
         this.socket = new net.Socket();
-        this.requestTimeoutMs = options.requestTimeoutMs ?? 10000;
+        this.requestTimeoutMs = options.requestTimeoutMs ?? 15000;
     }
     async connect() {
         this.shouldReconnect = true;
@@ -126,11 +126,11 @@ class NexoConnection extends events_1.EventEmitter {
             this.chunks = [];
         }
         while (true) {
-            // Need at least header (9 bytes)
-            if (this.buffer.length < 9)
+            // Need at least header (10 bytes): [Type:1][Opcode:1][ID:4][Len:4]
+            if (this.buffer.length < 10)
                 break;
-            const payloadLen = this.buffer.readUInt32BE(5);
-            const totalFrameLen = 9 + payloadLen;
+            const payloadLen = this.buffer.readUInt32BE(6);
+            const totalFrameLen = 10 + payloadLen;
             if (this.buffer.length < totalFrameLen)
                 break;
             // 2. Slice Frame
@@ -142,6 +142,7 @@ class NexoConnection extends events_1.EventEmitter {
     handleFrame(frame) {
         const cursor = new codec_1.Cursor(frame);
         const type = cursor.readU8();
+        const opcodeOrStatus = cursor.readU8(); // Opcode for requests, Status for responses
         const id = cursor.readU32();
         cursor.readU32(); // Skip payloadLen
         const payload = cursor.buf.subarray(cursor.offset);
@@ -150,8 +151,8 @@ class NexoConnection extends events_1.EventEmitter {
                 const req = this.pending.get(id);
                 if (req) {
                     this.pending.delete(id);
-                    // Payload: [Status:1][Data...]
-                    req.resolve({ status: payload[0], data: payload.subarray(1) });
+                    // Status is in header (byte 1), payload is clean data
+                    req.resolve({ status: opcodeOrStatus, data: payload });
                 }
                 break;
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emanuelepifani/nexo-client",
-  "version": "0.1.1",
+  "version": "0.3.8",
   "description": "High-performance TypeScript Client for Nexo Broker",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,6 +13,8 @@
   ],
   "scripts": {
     "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build"
   },
   "repository": {
@@ -37,6 +39,9 @@
   ],
   "devDependencies": {
     "@types/node": "^20.10.0",
-    "typescript": "^5.3.0"
+    "typescript": "^5.3.0",
+    "vitest": "^1.2.0",
+    "tsx": "^4.7.0",
+    "zod": "^4.2.1"
   }
 }

package/dist/performance-test.d.ts

@@ -1,2 +0,0 @@
-declare function performanceTest(): void;
-export { performanceTest };

package/dist/performance-test.js

@@ -1,58 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.performanceTest = performanceTest;
-const ringbuffer_1 = require("./ringbuffer");
-// Simple performance test for RingBuffer vs Buffer.concat
-function performanceTest() {
-    const iterations = 10000;
-    const chunkSize = 1024;
-    const totalData = iterations * chunkSize;
-    console.log(`Testing performance with ${iterations} chunks of ${chunkSize} bytes each...`);
-    // Test 1: Buffer.concat (old method)
-    console.time('Buffer.concat');
-    const chunks = [];
-    let totalBuffer = Buffer.alloc(0);
-    for (let i = 0; i < iterations; i++) {
-        const chunk = Buffer.allocUnsafe(chunkSize);
-        chunk.fill(Math.floor(Math.random() * 256));
-        chunks.push(chunk);
-        // Simulate periodic concatenation (like the old code)
-        if (chunks.length > 10) {
-            totalBuffer = Buffer.concat([totalBuffer, ...chunks]);
-            chunks.length = 0;
-        }
-    }
-    // Final concat
-    if (chunks.length > 0) {
-        totalBuffer = Buffer.concat([totalBuffer, ...chunks]);
-    }
-    console.timeEnd('Buffer.concat');
-    // Test 2: RingBuffer (new method)
-    console.time('RingBuffer');
-    const ringBuffer = new ringbuffer_1.RingBuffer();
-    for (let i = 0; i < iterations; i++) {
-        const chunk = Buffer.allocUnsafe(chunkSize);
-        chunk.fill(Math.floor(Math.random() * 256));
-        ringBuffer.write(chunk);
-    }
-    // Read all data
-    const result = ringBuffer.consume(ringBuffer.available);
-    console.timeEnd('RingBuffer');
-    console.log(`Total data processed: ${(totalData / 1024 / 1024).toFixed(2)} MB`);
-    console.log(`Buffer.concat result length: ${totalBuffer.length}`);
-    console.log(`RingBuffer result length: ${result.length}`);
-    // Memory usage comparison
-    const memBefore = process.memoryUsage();
-    // Test memory efficiency
-    const largeRingBuffer = new ringbuffer_1.RingBuffer(1024 * 1024); // 1MB initial
-    for (let i = 0; i < 1000; i++) {
-        const chunk = Buffer.allocUnsafe(4096);
-        largeRingBuffer.write(chunk);
-    }
-    const memAfter = process.memoryUsage();
-    console.log(`Memory usage increase: ${((memAfter.heapUsed - memBefore.heapUsed) / 1024 / 1024).toFixed(2)} MB`);
-}
-// Run the test
-if (require.main === module) {
-    performanceTest();
-}

package/dist/ringbuffer.d.ts

@@ -1,27 +0,0 @@
-/** @internal */
-export declare class RingBuffer {
-    private buffer;
-    private head;
-    private tail;
-    private size;
-    private capacity;
-    constructor(initialCapacity?: number);
-    /** Write data to ring buffer */
-    write(data: Buffer): number;
-    /** Read data from ring buffer without consuming it */
-    peek(length: number): Buffer;
-    /** Consume data from ring buffer */
-    consume(length: number): Buffer;
-    /** Get current data size */
-    get available(): number;
-    /** Get available space for writing */
-    get freeSpace(): number;
-    /** Check if buffer is empty */
-    get isEmpty(): boolean;
-    /** Clear all data */
-    clear(): void;
-    /** Ensure capacity for new data */
-    private ensureCapacity;
-    /** Get next power of 2 */
-    private nextPowerOf2;
-}

package/dist/ringbuffer.js

@@ -1,109 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.RingBuffer = void 0;
-/** @internal */
-class RingBuffer {
-    constructor(initialCapacity = 8192) {
-        this.head = 0; // write position
-        this.tail = 0; // read position
-        this.size = 0; // current data size
-        this.capacity = this.nextPowerOf2(initialCapacity);
-        this.buffer = Buffer.allocUnsafe(this.capacity);
-    }
-    /** Write data to ring buffer */
-    write(data) {
-        const dataLen = data.length;
-        // Ensure we have enough space
-        this.ensureCapacity(this.size + dataLen);
-        // Write data in potentially two chunks (if wrapping around)
-        const availableToEnd = this.capacity - this.head;
-        if (dataLen <= availableToEnd) {
-            // Fits in one chunk
-            data.copy(this.buffer, this.head);
-            this.head = (this.head + dataLen) & (this.capacity - 1);
-        }
-        else {
-            // Needs to wrap around
-            const firstChunk = data.subarray(0, availableToEnd);
-            const secondChunk = data.subarray(availableToEnd);
-            firstChunk.copy(this.buffer, this.head);
-            secondChunk.copy(this.buffer, 0);
-            this.head = secondChunk.length;
-        }
-        this.size += dataLen;
-        return dataLen;
-    }
-    /** Read data from ring buffer without consuming it */
-    peek(length) {
-        if (length > this.size) {
-            length = this.size;
-        }
-        if (length === 0)
-            return Buffer.alloc(0);
-        const availableToEnd = this.capacity - this.tail;
-        if (length <= availableToEnd) {
-            // Data is contiguous
-            return this.buffer.subarray(this.tail, this.tail + length);
-        }
-        else {
-            // Data wraps around, need to concatenate
-            const firstChunk = this.buffer.subarray(this.tail, this.capacity);
-            const secondChunk = this.buffer.subarray(0, length - availableToEnd);
-            return Buffer.concat([firstChunk, secondChunk]);
-        }
-    }
-    /** Consume data from ring buffer */
-    consume(length) {
-        const data = this.peek(length);
-        this.tail = (this.tail + length) & (this.capacity - 1);
-        this.size -= length;
-        return data;
-    }
-    /** Get current data size */
-    get available() {
-        return this.size;
-    }
-    /** Get available space for writing */
-    get freeSpace() {
-        return this.capacity - this.size;
-    }
-    /** Check if buffer is empty */
-    get isEmpty() {
-        return this.size === 0;
-    }
-    /** Clear all data */
-    clear() {
-        this.head = 0;
-        this.tail = 0;
-        this.size = 0;
-    }
-    /** Ensure capacity for new data */
-    ensureCapacity(required) {
-        if (required <= this.capacity)
-            return;
-        const newCapacity = this.nextPowerOf2(required);
-        const newBuffer = Buffer.allocUnsafe(newCapacity);
-        // Copy existing data to new buffer
-        if (this.size > 0) {
-            const data = this.peek(this.size);
-            data.copy(newBuffer, 0);
-        }
-        this.buffer = newBuffer;
-        this.capacity = newCapacity;
-        this.head = this.size;
-        this.tail = 0;
-    }
-    /** Get next power of 2 */
-    nextPowerOf2(n) {
-        if (n <= 0)
-            return 1;
-        n--;
-        n |= n >> 1;
-        n |= n >> 2;
-        n |= n >> 4;
-        n |= n >> 8;
-        n |= n >> 16;
-        return n + 1;
-    }
-}
-exports.RingBuffer = RingBuffer;