feat: WebSocket enhancements with request queue and dynamic subscription management

[degenRobot]

Description:

Summary

• Adds comprehensive request queue management for WebSocket operations
• Implements dynamic subscription management for efficient event streaming
• Enhances connection resilience with exponential backoff and status tracking

Key Features

Request Queue Management

• Priority-based queuing: High, normal, and low priority levels for request processing
• Automatic retry logic: Configurable retry policies with exponential backoff
• Connection-aware processing: Queue automatically pauses during disconnections and resumes when connected
• Request batching: Efficient processing with configurable intervals
• Memory management: Configurable queue size limits and overflow handling

Dynamic Subscription Management

• Hot-swappable subscriptions: Update subscription parameters without reconnecting
• Event buffering: Manages event flow during subscription updates
• Type-safe interfaces: Full TypeScript support for shreds and logs subscriptions
• Resource efficient: Reuses existing connections for subscription updates

Connection Enhancements

• Exponential backoff: Implements progressive retry delays (1s → 2s → 4s → 8s → 16s → 30s)
• Connection status tracking: Real-time monitoring of connection state
• Graceful error handling: Improved resilience during network issues

Backwards Compatibility

✅ Fully backwards compatible - All existing APIs remain unchanged:

• Existing watchShreds, watchShredEvent, and watchContractShredEvent functions work as before
• No breaking changes to public APIs
• New features are opt-in through additional decorators and utilities
• Added comprehensive backward compatibility tests in tests/integration/backward-compatibility.test.ts

Testing

Extensive test coverage added:

• ✅ Request queue manager tests (290+ test cases)
• ✅ Subscription manager tests (206+ test cases)
• ✅ Connection decorator tests (116+ test cases)
• ✅ Exponential backoff tests (78+ test cases)
• ✅ Backward compatibility tests
• ✅ Integration tests for all watch functions

Examples

Added 13 new example files demonstrating:

• Basic queue usage (examples/request-queue.ts)
• Dynamic subscriptions (examples/dynamic-subscription.ts)
• Connection monitoring (examples/connection-monitoring.ts)
• Reconnection handling (examples/reconnection-test.ts)
• Various test scenarios for validation

Performance Improvements

• Reduced connection overhead through subscription reuse
• Efficient request batching reduces network calls
• Smart retry logic prevents connection storms
• Memory-efficient event buffering

Documentation

Updated README with:

• New queue management features
• Dynamic subscription examples
• Connection monitoring guidance
• API reference for new decorators

This PR significantly enhances the reliability and performance of WebSocket operations while maintaining full backward compatibility
with existing implementations.