nostr-websocket-utils 0.1.0 → 0.2.2

package/README.md

@@ -1,12 +1,12 @@
-Nostr Websocket Utils
+# Nostr Websocket Utils
 
-[![npm version](https://img.shields.io/npm/v/@humanjavaenterprises/nostr-websocket-utils.svg)](https://www.npmjs.com/package/@humanjavaenterprises/nostr-websocket-utils)
-[![License](https://img.shields.io/npm/l/@humanjavaenterprises/nostr-websocket-utils.svg)](https://github.com/HumanjavaEnterprises/nostr-websocket-utils/blob/main/LICENSE)
+[![npm version](https://img.shields.io/npm/v/nostr-websocket-utils.svg)](https://www.npmjs.com/package/nostr-websocket-utils)
+[![License](https://img.shields.io/npm/l/nostr-websocket-utils.svg)](https://github.com/HumanjavaEnterprises/nostr-websocket-utils/blob/main/LICENSE)
 [![Build Status](https://github.com/HumanjavaEnterprises/nostr-websocket-utils/workflows/CI/badge.svg)](https://github.com/HumanjavaEnterprises/nostr-websocket-utils/actions)
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org)
 [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
 
-A TypeScript library providing WebSocket utilities for Nostr applications, with robust connection handling, automatic reconnection, and channel-based messaging.
+A TypeScript library providing WebSocket utilities for Nostr applications, focusing on robust connection handling, automatic reconnection, and channel-based messaging. This library has been streamlined to remove any DOM-related code, enhancing performance and maintainability.
 
 ## Features
 
@@ -14,64 +14,115 @@ A TypeScript library providing WebSocket utilities for Nostr applications, with
 - 💓 Heartbeat monitoring
 - 📨 Message queueing during disconnections
 - 📢 Channel-based broadcasting
-- 🔒 Type-safe message handling
+- 🔒 Type-safe message handling with required handlers
 - 📝 Built-in logging
+- 🛡️ Comprehensive error handling
+- 🧪 Full test coverage
 
 ## Installation
 
 ```bash
-npm install @humanjavaenterprises/nostr-websocket-utils
+npm install nostr-websocket-utils
 ```
 
+## Breaking Changes in v0.2.2
+
+- Removed all DOM-related code to focus solely on WebSocket functionality.
+- Added UUID support for message tracking and correlation.
+- Introduced a new `WebSocketImpl` option for custom WebSocket implementations.
+- Improved TypeScript type safety across the codebase.
+- Enhanced error handling for WebSocket connections.
+
 ## Usage
 
-### Client Example
+### Server Example
 
 ```typescript
-import { NostrWSClient } from '@humanjavaenterprises/nostr-websocket-utils';
+import express from 'express';
+import { createServer } from 'http';
+import { NostrWSServer } from 'nostr-websocket-utils';
+import winston from 'winston';
 
-const client = new NostrWSClient('wss://your-server.com', {
-  heartbeatInterval: 30000,
-  reconnectInterval: 5000,
-  maxReconnectAttempts: 5
-});
+const app = express();
+const server = createServer(app);
 
-client.on('connect', () => {
-  console.log('Connected!');
-  client.subscribe('my-channel');
+// Create a logger
+const logger = winston.createLogger({
+  level: 'info',
+  format: winston.format.json(),
+  transports: [new winston.transports.Console()]
 });
 
-client.on('message', (message) => {
-  console.log('Received:', message);
+// Initialize the WebSocket server with custom WebSocket implementation
+const wsServer = new NostrWSServer(server, {
+  logger,
+  handlers: {
+    message: async (ws, message) => {
+      logger.info('Received message:', message);
+      // Handle message
+    },
+    error: (ws, error) => {
+      logger.error('WebSocket error:', error);
+    },
+    close: (ws) => {
+      logger.info('Connection closed');
+    }
+  }
 });
 
-client.connect();
+server.listen(3000);
 ```
 
-### Server Example
+### Client Example
 
 ```typescript
-import express from 'express';
-import { createServer } from 'http';
-import { NostrWSServer } from '@humanjavaenterprises/nostr-websocket-utils';
+import { NostrWSClient } from 'nostr-websocket-utils';
+import winston from 'winston';
 
-const app = express();
-const server = createServer(app);
-const wss = new NostrWSServer(server, {
-  heartbeatInterval: 30000
+const logger = winston.createLogger({
+  level: 'info',
+  format: winston.format.json(),
+  transports: [new winston.transports.Console()]
 });
 
-wss.on('message', (message, client) => {
+const client = new NostrWSClient('ws://localhost:3000', {
+  logger,
+  WebSocketImpl: CustomWebSocketImplementation // Optional custom WebSocket implementation
+});
+
+client.on('message', (message) => {
   console.log('Received message:', message);
-  
-  // Broadcast to specific channel
-  wss.broadcastToChannel('my-channel', {
-    type: 'event',
-    data: { content: 'Hello channel!' }
-  });
 });
 
-server.listen(3000);
+client.connect();
+```
+
+## Interface Reference
+
+### NostrWSOptions
+
+```typescript
+interface NostrWSOptions {
+  // Interval for sending heartbeat pings (ms)
+  heartbeatInterval?: number;
+  // Interval between reconnection attempts (ms)
+  reconnectInterval?: number;
+  // Maximum number of reconnection attempts
+  maxReconnectAttempts?: number;
+  // Required logger instance
+  logger: Logger;
+  // Required handlers object
+  handlers: {
+    // Required message handler
+    message: (ws: ExtendedWebSocket, message: NostrWSMessage) => Promise<void> | void;
+    // Optional error handler
+    error?: (ws: WebSocket, error: Error) => void;
+    // Optional close handler
+    close?: (ws: WebSocket) => void;
+  };
+  // Optional custom WebSocket implementation
+  WebSocketImpl?: WebSocketImpl;
+}
 ```
 
 ## Why This Library is Perfect for Nostr Development
@@ -99,54 +150,12 @@ This library is specifically designed to accelerate Nostr application developmen
 - Full TypeScript support with comprehensive type definitions
 - Event-driven architecture matching Nostr's event-centric nature
 - Clear, consistent error handling and validation
-- Minimal boilerplate needed to get started
-
-### 5. Production-Ready Features
-- Built-in logging system
-- Memory leak prevention through proper client cleanup
-- Scalable client management
-- Support for multiple simultaneous subscriptions
-
-By using this library, you can skip weeks of WebSocket infrastructure development and focus on building your Nostr application's unique features.
-
-## API Reference
-
-### NostrWSClient
-
-- `constructor(url: string, options?: NostrWSOptions)`
-- `connect(): void`
-- `send(message: NostrWSMessage): void`
-- `subscribe(channel: string): void`
-- `unsubscribe(channel: string): void`
-- `close(): void`
-
-Events:
-- `connect`
-- `disconnect`
-- `reconnect`
-- `message`
-- `error`
-
-### NostrWSServer
-
-- `constructor(server: any, options?: NostrWSOptions)`
-- `broadcast(message: NostrWSMessage): void`
-- `broadcastToChannel(channel: string, message: NostrWSMessage): void`
-- `sendTo(client: ExtendedWebSocket, message: NostrWSMessage): void`
-- `getClients(): Set<ExtendedWebSocket>`
-- `close(): void`
-
-Events:
-- `message`
+- Required handlers pattern ensures type safety
 
 ## Contributing
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
 
 ## License
 
-MIT
+MIT License - see the [LICENSE](LICENSE) file for details.

package/dist/client.d.ts

@@ -1,3 +1,4 @@
+/// <reference types="node" />
 import { EventEmitter } from 'events';
 import type { NostrWSOptions, NostrWSMessage } from './types/index.js';
 export declare class NostrWSClient extends EventEmitter {
@@ -8,6 +9,7 @@ export declare class NostrWSClient extends EventEmitter {
     private heartbeatInterval;
     private reconnectAttempts;
     private messageQueue;
+    private clientId;
     constructor(url: string, options?: Partial<NostrWSOptions>);
     connect(): void;
     private setupEventHandlers;

package/dist/client.js

@@ -1,3 +1,4 @@
+import { v4 as uuidv4 } from 'uuid';
 import WebSocket from 'ws';
 import { EventEmitter } from 'events';
 export class NostrWSClient extends EventEmitter {
@@ -12,12 +13,16 @@ export class NostrWSClient extends EventEmitter {
         if (!options.logger) {
             throw new Error('Logger is required');
         }
+        this.clientId = uuidv4();
         this.options = {
             heartbeatInterval: options.heartbeatInterval || 30000,
             logger: options.logger,
-            onMessage: options.onMessage,
-            onError: options.onError,
-            onClose: options.onClose
+            WebSocketImpl: options.WebSocketImpl || WebSocket,
+            handlers: {
+                message: options.handlers?.message || (async () => { }),
+                error: options.handlers?.error || (() => { }),
+                close: options.handlers?.close || (() => { })
+            }
         };
     }
     connect() {
@@ -26,7 +31,9 @@ export class NostrWSClient extends EventEmitter {
             return;
         }
         try {
-            this.ws = new WebSocket(this.url);
+            this.options.logger.debug('Creating new WebSocket connection');
+            this.ws = new this.options.WebSocketImpl(this.url);
+            this.options.logger.debug('WebSocket created successfully');
             this.setupEventHandlers();
         }
         catch (error) {
@@ -48,14 +55,12 @@ export class NostrWSClient extends EventEmitter {
             try {
                 const message = JSON.parse(data.toString());
                 this.emit('message', message);
-                if (this.options.onMessage) {
-                    await this.options.onMessage(this.ws, message);
-                }
+                await this.options.handlers.message(this.ws, message);
             }
             catch (error) {
                 this.emit('error', error);
-                if (this.options.onError) {
-                    this.options.onError(this.ws, error);
+                if (this.options.handlers.error) {
+                    this.options.handlers.error(this.ws, error);
                 }
             }
         });
@@ -64,15 +69,15 @@ export class NostrWSClient extends EventEmitter {
             this.stopHeartbeat();
             this.handleReconnect();
             this.emit('disconnect');
-            if (this.options.onClose) {
-                this.options.onClose(this.ws);
+            if (this.options.handlers.close) {
+                this.options.handlers.close(this.ws);
             }
         });
         this.ws.on('error', (error) => {
             this.options.logger.error('WebSocket error:', error);
             this.emit('error', error);
-            if (this.options.onError) {
-                this.options.onError(this.ws, error);
+            if (this.options.handlers.error) {
+                this.options.handlers.error(this.ws, error);
             }
         });
     }
@@ -122,6 +127,7 @@ export class NostrWSClient extends EventEmitter {
         }
     }
     async send(message) {
+        message.id = message.id || uuidv4();
         if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
             this.messageQueue.push(message);
             return;

package/dist/server.d.ts

@@ -1,12 +1,15 @@
+/// <reference types="node" />
 import { EventEmitter } from 'events';
-import { Server as HttpServer } from 'http';
-import type { NostrWSOptions, NostrWSMessage } from './types/index.js';
+import { WebSocketServer } from 'ws';
+import type { NostrWSOptions, NostrWSMessage, ExtendedWebSocket } from './types/index.js';
 export declare class NostrWSServer extends EventEmitter {
     private wss;
     private options;
     private heartbeatInterval;
-    constructor(server: HttpServer, options?: Partial<NostrWSOptions>);
+    clients: Map<string, ExtendedWebSocket>;
+    constructor(wss: WebSocketServer, options?: Partial<NostrWSOptions>);
     private setupServer;
+    private handleConnection;
     private startHeartbeat;
     broadcast(message: NostrWSMessage): void;
     broadcastToChannel(channel: string, message: NostrWSMessage): void;

package/dist/server.js

@@ -1,69 +1,85 @@
 import { EventEmitter } from 'events';
-import { WebSocketServer, WebSocket } from 'ws';
+import { WebSocket } from 'ws';
+import { v4 as uuidv4 } from 'uuid';
 export class NostrWSServer extends EventEmitter {
-    constructor(server, options = {}) {
+    constructor(wss, options = {}) {
         super();
         this.heartbeatInterval = null;
+        this.clients = new Map();
         if (!options.logger) {
             throw new Error('Logger is required');
         }
+        if (!options.handlers?.message) {
+            throw new Error('Message handler is required');
+        }
         this.options = {
             heartbeatInterval: options.heartbeatInterval || 30000,
             logger: options.logger,
-            onMessage: options.onMessage || (() => { }),
-            onError: options.onError || (() => { }),
-            onClose: options.onClose || (() => { })
+            WebSocketImpl: options.WebSocketImpl || WebSocket,
+            handlers: {
+                message: options.handlers.message,
+                error: options.handlers.error || (() => { }),
+                close: options.handlers.close || (() => { })
+            }
         };
-        this.wss = new WebSocketServer({ server });
+        this.wss = wss;
         this.setupServer();
     }
     setupServer() {
         this.wss.on('connection', (ws) => {
-            const extWs = ws;
-            extWs.subscriptions = new Set();
-            extWs.isAlive = true;
-            ws.on('message', async (data) => {
-                try {
-                    const message = JSON.parse(data.toString());
-                    if (this.options.onMessage) {
-                        await this.options.onMessage(extWs, message);
-                    }
-                }
-                catch (error) {
-                    if (this.options.onError) {
-                        this.options.onError(ws, error);
-                    }
-                }
-            });
-            ws.on('close', () => {
-                extWs.isAlive = false;
-                if (this.options.onClose) {
-                    this.options.onClose(ws);
-                }
-            });
-            ws.on('error', (error) => {
-                if (this.options.onError) {
-                    this.options.onError(ws, error);
-                }
-            });
+            this.handleConnection(ws);
         });
         if (this.options.heartbeatInterval && this.options.heartbeatInterval > 0) {
             this.startHeartbeat();
         }
     }
+    handleConnection(ws) {
+        ws.isAlive = true;
+        ws.subscriptions = new Set();
+        ws.clientId = ws.clientId || uuidv4();
+        this.clients.set(ws.clientId, ws);
+        ws.on('message', async (data) => {
+            try {
+                const message = JSON.parse(data.toString());
+                await this.options.handlers.message(ws, message);
+            }
+            catch (error) {
+                if (this.options.handlers.error) {
+                    this.options.handlers.error(ws, error);
+                }
+            }
+        });
+        ws.on('close', () => {
+            if (ws.clientId) {
+                this.clients.delete(ws.clientId);
+            }
+            if (this.options.handlers.close) {
+                this.options.handlers.close(ws);
+            }
+        });
+        ws.on('error', (error) => {
+            if (ws.clientId) {
+                this.clients.delete(ws.clientId);
+            }
+            if (this.options.handlers.error) {
+                this.options.handlers.error(ws, error);
+            }
+        });
+    }
     startHeartbeat() {
         this.heartbeatInterval = setInterval(() => {
             this.wss.clients.forEach((ws) => {
+                const extWs = ws;
+                if (!extWs.isAlive) {
+                    extWs.terminate();
+                    return;
+                }
+                extWs.isAlive = false;
                 if (ws.readyState === WebSocket.OPEN) {
-                    const extWs = ws;
-                    if (!extWs.isAlive) {
-                        return ws.terminate();
-                    }
                     ws.ping();
-                    extWs.isAlive = false;
                 }
             });
-        }, this.options.heartbeatInterval || 30000);
+        }, this.options.heartbeatInterval);
     }
     broadcast(message) {
         this.wss.clients.forEach((client) => {
@@ -73,10 +89,10 @@ export class NostrWSServer extends EventEmitter {
         });
     }
     broadcastToChannel(channel, message) {
-        this.wss.clients.forEach((client) => {
-            const extClient = client;
-            if (client.readyState === WebSocket.OPEN && extClient.subscriptions?.has(channel)) {
-                client.send(JSON.stringify(message));
+        this.wss.clients.forEach((ws) => {
+            const extWs = ws;
+            if (extWs.readyState === WebSocket.OPEN && extWs.subscriptions?.has(channel)) {
+                ws.send(JSON.stringify(message));
             }
         });
     }

package/dist/types/index.d.ts

@@ -5,9 +5,12 @@ export interface NostrWSOptions {
     reconnectInterval?: number;
     maxReconnectAttempts?: number;
     logger: Logger;
-    onMessage?: (ws: ExtendedWebSocket, message: NostrWSMessage) => Promise<void> | void;
-    onError?: (ws: WebSocket, error: Error) => void;
-    onClose?: (ws: WebSocket) => void;
+    WebSocketImpl: typeof WebSocket;
+    handlers: {
+        message: (ws: ExtendedWebSocket, message: NostrWSMessage) => Promise<void> | void;
+        error?: (ws: WebSocket, error: Error) => void;
+        close?: (ws: WebSocket) => void;
+    };
 }
 export interface NostrWSMessage {
     type: string;
@@ -33,6 +36,7 @@ export interface NostrWSServerEvents {
 export interface ExtendedWebSocket extends WebSocket {
     isAlive?: boolean;
     subscriptions?: Set<string>;
+    clientId?: string;
     messageQueue?: NostrWSMessage[];
     lastPing?: number;
     reconnectAttempts?: number;
@@ -49,5 +53,6 @@ export interface NostrWSConnectionState {
 export interface Logger {
     debug: (message: string, ...args: unknown[]) => void;
     info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
     error: (message: string, ...args: unknown[]) => void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nostr-websocket-utils",
-  "version": "0.1.0",
+  "version": "0.2.2",
   "description": "WebSocket utilities for Nostr applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,20 +20,30 @@
     "utils",
     "maiqr"
   ],
-  "author": "Human Java Enterprises",
+  "author": "vveerrgg",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HumanjavaEnterprises/nostr-websocket-utils.git"
+  },
+  "bugs": {
+    "url": "https://github.com/HumanjavaEnterprises/nostr-websocket-utils/issues"
+  },
+  "homepage": "https://github.com/HumanjavaEnterprises/nostr-websocket-utils#readme",
   "dependencies": {
-    "ws": "^8.16.0",
-    "winston": "^3.11.0",
     "@noble/curves": "^1.3.0",
     "@noble/hashes": "^1.3.3",
-    "nostr-tools": "^2.1.4"
+    "@types/uuid": "^10.0.0",
+    "nostr-tools": "^2.1.4",
+    "uuid": "^11.0.3",
+    "winston": "^3.11.0",
+    "ws": "^8.16.0"
   },
   "peerDependencies": {
     "nostr-tools": "^2.1.4"
   },
   "devDependencies": {
-    "@types/jest": "^29.5.11",
+    "@types/jest": "^29.5.14",
     "@types/node": "^20.11.0",
     "@types/ws": "^8.5.10",
     "@typescript-eslint/eslint-plugin": "^6.18.1",
@@ -48,14 +58,6 @@
     "README.md",
     "LICENSE"
   ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/humanjavaenterprises/nostr-websocket-utils.git"
-  },
-  "bugs": {
-    "url": "https://github.com/humanjavaenterprises/nostr-websocket-utils/issues"
-  },
-  "homepage": "https://github.com/humanjavaenterprises/nostr-websocket-utils#readme",
   "publishConfig": {
     "access": "public"
   }