nostr-websocket-utils 0.2.1 → 0.2.3

package/README.md

@@ -1,187 +1,199 @@
-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
 
 - 🔄 Automatic reconnection with configurable attempts
-- 💓 Heartbeat monitoring
+- 💓 Heartbeat monitoring with configurable intervals
 - 📨 Message queueing during disconnections
-- 📢 Channel-based broadcasting
+- 📢 Channel-based broadcasting with filtered subscriptions
 - 🔒 Type-safe message handling with required handlers
-- 📝 Built-in logging
-- 🛡️ Comprehensive error handling
-- 🧪 Full test coverage
+- 📝 Built-in logging with Winston integration
+- 🛡️ Comprehensive error handling and validation
+- 🧪 100% test coverage with Jest
+- 📦 Zero DOM dependencies
 
 ## Installation
 
 ```bash
-npm install @humanjavaenterprises/nostr-websocket-utils
+npm install nostr-websocket-utils
 ```
 
-## Breaking Changes in v0.2.0
+## Breaking Changes in v0.2.2
 
-- Introduced required handlers pattern for better type safety
-- Removed individual event handler properties (onMessage, onError, onClose)
-- Message handler is now required in server options
-- Client updated to match server interface
+- 🔥 Removed all DOM-related code for better server-side compatibility
+- 🆔 Added UUID support for message tracking and correlation
+- 🔌 Introduced `WebSocketImpl` option for custom WebSocket implementations
+- 🛡️ Enhanced TypeScript type safety and validation
+- 🔄 Improved reconnection and error handling logic
+- 📝 Added comprehensive logging support
 
 ## Usage
 
 ### Server Example
 
 ```typescript
-import express from 'express';
-import { createServer } from 'http';
-import { NostrWSServer } from '@humanjavaenterprises/nostr-websocket-utils';
-import winston from 'winston';
-
-const app = express();
-const server = createServer(app);
-
-// Create a logger
-const logger = winston.createLogger({
-  level: 'info',
-  format: winston.format.json(),
-  transports: [new winston.transports.Console()]
-});
+import { NostrWSServer } from 'nostr-websocket-utils';
+import { WebSocketServer } from 'ws';
+import { getLogger } from './utils/logger';
 
-// Initialize WebSocket server with required handlers
-const wss = new NostrWSServer(server, {
-  heartbeatInterval: 30000,
-  logger,
+// Create WebSocket server
+const wss = new WebSocketServer({ port: 8080 });
+
+// Initialize NostrWSServer with handlers
+const server = new NostrWSServer(wss, {
+  logger: getLogger('nostr-server'),
+  heartbeatInterval: 30000, // Optional: 30 seconds
   handlers: {
-    // Required message handler
+    // Required: Handle incoming messages
     message: async (ws, message) => {
-      logger.info('Received message:', message);
-      
-      // Example: Handle different message types
       switch (message.type) {
         case 'subscribe':
           // Handle subscription
+          ws.subscriptions?.add(message.data.channel);
           break;
         case 'event':
-          // Broadcast to specific channel
-          wss.broadcastToChannel('my-channel', {
-            type: 'event',
-            data: { content: 'Hello channel!' }
-          });
+          // Broadcast to relevant subscribers
+          server.broadcastToChannel(message.data.channel, message);
           break;
       }
     },
-    // Optional error handler
+    // Optional: Handle errors
     error: (ws, error) => {
       logger.error('WebSocket error:', error);
     },
-    // Optional close handler
+    // Optional: Handle client disconnection
     close: (ws) => {
-      logger.info('Client disconnected');
+      logger.info(`Client ${ws.clientId} disconnected`);
     }
   }
 });
-
-server.listen(3000);
 ```
 
 ### Client Example
 
 ```typescript
-import { NostrWSClient } from '@humanjavaenterprises/nostr-websocket-utils';
-import winston from 'winston';
-
-// Create a logger
-const logger = winston.createLogger({
-  level: 'info',
-  format: winston.format.json(),
-  transports: [new winston.transports.Console()]
-});
+import { NostrWSClient } from 'nostr-websocket-utils';
+import { getLogger } from './utils/logger';
 
-const client = new NostrWSClient('wss://your-server.com', {
+const client = new NostrWSClient('ws://localhost:8080', {
+  logger: getLogger('nostr-client'),
   heartbeatInterval: 30000,
-  reconnectInterval: 5000,
-  maxReconnectAttempts: 5,
-  logger,
   handlers: {
+    // Required: Handle incoming messages
     message: async (ws, message) => {
-      logger.info('Received message:', message);
-      // Handle message
-    },
-    error: (ws, error) => {
-      logger.error('Connection error:', error);
-    },
-    close: (ws) => {
-      logger.info('Connection closed');
+      console.log('Received:', message);
     }
   }
 });
 
-// Listen to events
+// Listen for connection events
 client.on('connect', () => {
-  logger.info('Connected!');
+  console.log('Connected to server');
+  
+  // Subscribe to a channel
   client.subscribe('my-channel');
+  
+  // Send an event
+  client.send({
+    type: 'event',
+    data: {
+      channel: 'my-channel',
+      content: 'Hello, Nostr!'
+    }
+  });
 });
 
+// Connect to server
 client.connect();
 ```
 
-## Interface Reference
+## API Reference
 
-### NostrWSOptions
+### NostrWSServer
+
+The server-side WebSocket handler with support for channels and broadcasting.
 
 ```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;
-  };
+class NostrWSServer {
+  constructor(wss: WebSocketServer, options: NostrWSOptions);
+  
+  // Broadcast to all connected clients
+  broadcast(message: NostrWSMessage): void;
+  
+  // Broadcast to specific channel subscribers
+  broadcastToChannel(channel: string, message: NostrWSMessage): void;
+  
+  // Close the server and all connections
+  close(): void;
 }
 ```
 
-## Why This Library is Perfect for Nostr Development
+### NostrWSClient
+
+The client-side WebSocket handler with automatic reconnection and message queueing.
+
+```typescript
+class NostrWSClient {
+  constructor(url: string, options: NostrWSOptions);
+  
+  // Connect to the server
+  connect(): void;
+  
+  // Subscribe to a channel
+  subscribe(channel: string, filter?: unknown): void;
+  
+  // Unsubscribe from a channel
+  unsubscribe(channel: string): void;
+  
+  // Send a message to the server
+  send(message: NostrWSMessage): Promise<void>;
+  
+  // Close the connection
+  close(): void;
+}
+```
+
+### NostrWSMessage
+
+The standard message format for communication.
+
+```typescript
+interface NostrWSMessage {
+  id?: string;           // Auto-generated UUID if not provided
+  type: string;          // Message type (e.g., 'subscribe', 'event')
+  data: {
+    channel?: string;    // Target channel for subscription/broadcast
+    [key: string]: any;  // Additional message data
+  };
+}
+```
 
-This library is specifically designed to accelerate Nostr application development by providing a robust foundation for WebSocket communication. Here's what makes it particularly valuable:
+## Why Choose This Library
 
-### 1. Nostr-Specific Message Types
-- Built-in support for core Nostr protocol message types (`subscribe`, `unsubscribe`, `event`, `request/response`)
-- Perfectly aligned with Nostr's pub/sub model
+### 1. Nostr-Optimized
+- Built specifically for Nostr protocol requirements
+- Efficient pub/sub model with filtered subscriptions
 - Type-safe message handling for all Nostr events
 
-### 2. Advanced WebSocket Management
-- Zero-config connection maintenance with automatic reconnection
-- Built-in heartbeat mechanism prevents stale connections
-- Smart message queuing ensures no events are lost during disconnections
-- Comprehensive connection state tracking
-
-### 3. Efficient Event Distribution
-- Channel-based broadcasting for targeted event distribution
-- Support for filtered subscriptions (crucial for Nostr event filtering)
-- Memory-efficient subscription tracking
-- Optimized message routing to relevant subscribers
-
-### 4. Developer Experience
-- Full TypeScript support with comprehensive type definitions
-- Event-driven architecture matching Nostr's event-centric nature
-- Clear, consistent error handling and validation
-- Required handlers pattern ensures type safety
+### 2. Production-Ready
+- Comprehensive error handling and recovery
+- Memory-efficient subscription management
+- Built-in logging and monitoring
+- Extensive test coverage
+
+### 3. Developer-Friendly
+- Clear TypeScript definitions
+- Flexible configuration options
+- Detailed documentation
+- Active maintenance
 
 ## Contributing
 

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,9 +13,11 @@ 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,
+            WebSocketImpl: options.WebSocketImpl || WebSocket,
             handlers: {
                 message: options.handlers?.message || (async () => { }),
                 error: options.handlers?.error || (() => { }),
@@ -28,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) {
@@ -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,9 +1,11 @@
 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');
         }
@@ -13,47 +15,57 @@ export class NostrWSServer extends EventEmitter {
         this.options = {
             heartbeatInterval: options.heartbeatInterval || 30000,
             logger: options.logger,
+            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());
-                    await this.options.handlers.message(extWs, message);
-                }
-                catch (error) {
-                    if (this.options.handlers.error) {
-                        this.options.handlers.error(ws, error);
-                    }
-                }
-            });
-            ws.on('close', () => {
-                extWs.isAlive = false;
-                if (this.options.handlers.close) {
-                    this.options.handlers.close(ws);
-                }
-            });
-            ws.on('error', (error) => {
-                if (this.options.handlers.error) {
-                    this.options.handlers.error(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) => {

package/dist/types/index.d.ts

@@ -5,6 +5,7 @@ export interface NostrWSOptions {
     reconnectInterval?: number;
     maxReconnectAttempts?: number;
     logger: Logger;
+    WebSocketImpl: typeof WebSocket;
     handlers: {
         message: (ws: ExtendedWebSocket, message: NostrWSMessage) => Promise<void> | void;
         error?: (ws: WebSocket, error: Error) => void;
@@ -35,6 +36,7 @@ export interface NostrWSServerEvents {
 export interface ExtendedWebSocket extends WebSocket {
     isAlive?: boolean;
     subscriptions?: Set<string>;
+    clientId?: string;
     messageQueue?: NostrWSMessage[];
     lastPing?: number;
     reconnectAttempts?: number;
@@ -51,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,7 +1,7 @@
 {
   "name": "nostr-websocket-utils",
-  "version": "0.2.1",
-  "description": "WebSocket utilities for Nostr applications",
+  "version": "0.2.3",
+  "description": "Robust WebSocket utilities for Nostr applications with automatic reconnection, channel-based messaging, and type-safe handlers. Features heartbeat monitoring, message queueing, and comprehensive error handling.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -17,23 +17,41 @@
   "keywords": [
     "nostr",
     "websocket",
-    "utils",
+    "typescript",
+    "ws",
+    "realtime",
+    "pubsub",
+    "channel-based",
+    "reconnection",
+    "heartbeat",
+    "message-queue",
+    "type-safe",
     "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",