Skip to content

Home

Jump to bottom
Ben Mz edited this page Jun 8, 2025 · 2 revisions

Welcome to IOServer Wiki 🚀

IOServer is a powerful, production-ready framework for building real-time applications that combines the speed of Fastify with the real-time capabilities of Socket.IO. Built with TypeScript and designed for scalability, it provides a unified architecture for modern web applications.

📖 Table of Contents

🎯 What is IOServer?

IOServer is a TypeScript-first framework that solves the common challenge of building applications that need both HTTP APIs and real-time communication. Instead of managing separate servers or complex configurations, IOServer provides:

  • Unified Server: Single server handling both HTTP and WebSocket connections
  • Modular Architecture: Clean separation between Services, Controllers, Managers, and Watchers
  • Type Safety: Full TypeScript support with comprehensive type definitions
  • Production Ready: Built-in error handling, logging, and performance monitoring

⚡ Key Features

Feature Description
🚄 High Performance Built on Fastify for maximum HTTP throughput
⚡ Real-time Integrated Socket.IO for WebSocket connections
🏗️ Modular Clean separation with Services, Controllers, Managers, and Watchers
🔒 Secure Built-in CORS, error handling, and validation
📝 TypeScript Full type safety and IntelliSense support
🧪 Tested Comprehensive test suite with 95%+ coverage
🔧 Configurable JSON-based routing and flexible configuration

🏗️ Architecture Overview

graph TD
    A[IOServer] --> B[HTTP Server - Fastify]
    A --> C[WebSocket Server - Socket.IO]
    
    B --> D[Controllers]
    C --> E[Services]
    A --> F[Managers]
    A --> G[Watchers]
    
    D --> H[HTTP Routes]
    E --> I[Real-time Events]
    F --> J[Shared Logic]
    G --> K[Background Tasks]
Loading

Component Types

  • 🌐 Controllers: Handle HTTP requests with automatic route mapping
  • 📡 Services: Manage WebSocket connections and real-time events
  • 🔧 Managers: Provide shared business logic across components
  • 👁️ Watchers: Run background tasks and monitoring

🚀 Quick Start

# Install IOServer
npm install ioserver

# Create your first server
mkdir my-ioserver-app && cd my-ioserver-app
npm init -y
npm install ioserver typescript ts-node

import { IOServer, BaseService, BaseController } from 'ioserver';

// Real-time service
class ChatService extends BaseService {
  async sendMessage(socket: any, data: any, callback?: Function) {
    socket.broadcast.emit('new_message', data);
    if (callback) callback({ status: 'success' });
  }
}

// HTTP controller  
class ApiController extends BaseController {
  async getStatus(request: any, reply: any) {
    reply.send({ status: 'OK', timestamp: Date.now() });
  }
}

// Initialize server
const server = new IOServer({ port: 3000 });
server.addService({ name: 'chat', service: ChatService });
server.addController({ name: 'api', controller: ApiController });

await server.start();
console.log('🚀 Server running at http://localhost:3000');

📚 Documentation

Section Description
Getting Started Installation, setup, and your first IOServer app
Architecture Guide Deep dive into IOServer's modular architecture
API Reference Complete API documentation and examples
Chat App Tutorial Build a full-featured chat application
Deployment Guide Production deployment strategies
Contributing How to contribute to IOServer

❓ Frequently Asked Questions

🤔 Why should I use IOServer instead of Express + Socket.IO?

IOServer provides several advantages over a manual Express + Socket.IO setup:

  • 🚀 Performance: Fastify is 2-3x faster than Express
  • 🏗️ Structure: Modular architecture prevents spaghetti code
  • 📝 TypeScript: Full type safety out of the box
  • 🔧 Configuration: JSON-based routing reduces boilerplate
  • 🧪 Testing: Built-in testing utilities and patterns
  • 📦 Production: Error handling, logging, and monitoring included

You get enterprise-grade architecture without the complexity!

🔄 Can I migrate from an existing Express/Socket.IO app?

Yes! IOServer is designed for gradual migration:

  1. Start Small: Create new features as IOServer components
  2. Proxy Requests: Use IOServer alongside existing Express routes
  3. Migrate Gradually: Move existing routes to IOServer controllers
  4. WebSocket Upgrade: Replace Socket.IO setup with IOServer services

The modular architecture makes migration straightforward and low-risk.

📈 How does IOServer handle scaling?

IOServer is built for scale from day one:

  • 🚀 Performance: Fastify's architecture handles high throughput
  • 🔄 Horizontal Scaling: Load balancer friendly with sticky sessions
  • 💾 State Management: Managers provide centralized state handling
  • 🔌 Redis Integration: Built-in support for Redis adapter
  • 📊 Monitoring: Performance metrics and health checks included
  • 🐳 Container Ready: Docker-friendly with minimal footprint

Scale from prototype to production without architectural changes!

🛡️ Is IOServer secure for production use?

Absolutely! IOServer includes production-grade security features:

  • 🔒 CORS: Configurable cross-origin resource sharing
  • 🛡️ Input Validation: Built-in request/data validation
  • 🔐 Authentication: Flexible auth system integration
  • 📝 Logging: Comprehensive audit trails
  • ⚠️ Error Handling: Secure error responses (no info leakage)
  • 🚦 Rate Limiting: Built-in rate limiting capabilities
  • 🔍 Monitoring: Security event monitoring and alerting

Plus regular security updates and community auditing!

🧪 How do I test IOServer applications?

IOServer includes comprehensive testing utilities:

// Unit testing services
import { createTestServer } from 'ioserver/testing';

const server = createTestServer();
const client = await server.createTestClient();

// Test real-time events
await client.emit('chat:message', { text: 'Hello' });
expect(server.getLastEmission()).toMatchObject({
  event: 'chat:message',
  data: { text: 'Hello' }
});
  • 🔧 Test Utilities: Built-in testing helpers and mocks
  • 📡 WebSocket Testing: Easy Socket.IO event testing
  • 🌐 HTTP Testing: Supertest integration for API testing
  • 📊 Coverage: Jest integration with coverage reporting
  • 🚀 Performance: Memory leak and performance testing tools
🔌 Can I use IOServer with my existing database/ORM?

Yes! IOServer is database-agnostic and works with any persistence layer:

  • 🗄️ SQL: Prisma, TypeORM, Sequelize, Knex
  • 📄 NoSQL: Mongoose, MongoDB driver, DynamoDB
  • ⚡ Cache: Redis, Memcached integration
  • 🔍 Search: Elasticsearch, Algolia integration
  • 📊 Analytics: Integration with analytics services

Managers are perfect for encapsulating database logic and making it available across your application.

🚀 What's the performance like compared to other frameworks?

IOServer delivers excellent performance thanks to Fastify:

Framework Requests/sec Latency (avg)
IOServer ~65,000 0.8ms
Express ~25,000 2.1ms
Koa ~45,000 1.2ms
NestJS ~35,000 1.6ms

Benchmarks on Node.js 20, 4 CPU cores, real-time features disabled

Plus IOServer adds WebSocket performance with Socket.IO's optimized transport layer!

📦 What's included in the IOServer package?

IOServer comes with everything you need:

Core Framework:

  • HTTP server (Fastify)
  • WebSocket server (Socket.IO)
  • Modular architecture system
  • TypeScript definitions

Development Tools:

  • Hot reload support
  • Development logging
  • Error stack traces
  • Performance profiling

Production Features:

  • Error handling and reporting
  • Health checks and monitoring
  • Graceful shutdown handling
  • Process management utilities

Testing Suite:

  • Unit testing utilities
  • Integration test helpers
  • Performance testing tools
  • Mock and stub generators
🌍 Can I deploy IOServer to cloud platforms?

IOServer works seamlessly with all major cloud platforms:

  • ☁️ AWS: EC2, ECS, Lambda, Elastic Beanstalk
  • 🌐 Google Cloud: Compute Engine, Cloud Run, App Engine
  • 🔷 Azure: App Service, Container Instances, Functions
  • 🚀 Vercel: Serverless functions with WebSocket support
  • 📦 Heroku: Direct deployment with WebSocket support
  • 🐙 DigitalOcean: Droplets, App Platform, Kubernetes

Check our Deployment Guide for platform-specific instructions and optimizations!

🛠️ How do I debug IOServer applications?

IOServer includes powerful debugging capabilities:

// Enable debug logging
const server = new IOServer({
  verbose: 'DEBUG', // Show all debug information
  port: 3000
});

// Built-in logging
server.log('INFO', 'Custom log message');

// Error tracking
server.on('error', (error) => {
  console.error('Server error:', error);
});

Debug Features:

  • 📝 Structured Logging: Level-based logging system
  • 🔍 Request Tracing: HTTP and WebSocket request tracking
  • ⚠️ Error Reporting: Detailed error context and stack traces
  • 📊 Performance Metrics: Built-in performance monitoring
  • 🔧 Development Mode: Enhanced debugging in development
  • 🎯 VS Code Integration: Debug configuration included

🤝 Community & Support

📞 Get Help

  • 📖 Documentation: Complete guides and examples
  • 💬 GitHub Discussions: Community Q&A and feature requests
  • 🐛 Issue Tracker: Bug reports and feature requests
  • 📧 Email: ioserver@bitsdiver.com

🤝 Contributing

We welcome contributions! Check our Contributing Guide to get started:

  • 🐛 Bug Reports: Help us improve by reporting issues
  • ✨ Feature Requests: Suggest new features and improvements
  • 📝 Documentation: Help improve our documentation
  • 💻 Code: Submit pull requests with bug fixes and features
  • 🧪 Testing: Help expand our test coverage

📄 License

IOServer is open source software licensed under the Apache License 2.0.

Ready to build something amazing? 🚀

👉 Get Started Now | 📚 View Examples | 🌟 Star on GitHub

Clone this wiki locally