{"id":22243177,"url":"https://github.com/x42en/ioserver","last_synced_at":"2026-02-15T18:33:39.918Z","repository":{"id":30328382,"uuid":"33880704","full_name":"x42en/IOServer","owner":"x42en","description":"Damn simple way to setup a Socket.io server","archived":false,"fork":false,"pushed_at":"2024-06-16T15:40:41.000Z","size":2209,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-09T07:35:44.819Z","etag":null,"topics":["coffeescript","nodejs","npm-module","socket-io"],"latest_commit_sha":null,"homepage":"","language":"CoffeeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/x42en.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-04-13T16:43:09.000Z","updated_at":"2023-02-19T09:31:16.000Z","dependencies_parsed_at":"2025-02-09T07:45:05.936Z","dependency_job_id":null,"html_url":"https://github.com/x42en/IOServer","commit_stats":{"total_commits":215,"total_committers":9,"mean_commits":23.88888888888889,"dds":"0.43255813953488376","last_synced_commit":"acb64f40e8f67a7a7f8a207683fbbe7a91d21056"},"previous_names":[],"tags_count":55,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x42en%2FIOServer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x42en%2FIOServer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x42en%2FIOServer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/x42en%2FIOServer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/x42en","download_url":"https://codeload.github.com/x42en/IOServer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247064183,"owners_count":20877565,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coffeescript","nodejs","npm-module","socket-io"],"created_at":"2024-12-03T04:21:25.156Z","updated_at":"2025-10-04T21:01:42.883Z","avatar_url":"https://github.com/x42en.png","language":"CoffeeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚀 IOServer\n\n[![npm version](https://badge.fury.io/js/ioserver.svg)](https://badge.fury.io/js/ioserver)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-yellow.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Node.js CI](https://github.com/x42en/IOServer/workflows/Node.js%20CI/badge.svg)](https://github.com/x42en/IOServer/actions)\n[![codecov](https://codecov.io/gh/x42en/IOServer/branch/main/graph/badge.svg)](https://codecov.io/gh/x42en/IOServer)\n[![TypeScript](https://img.shields.io/badge/TypeScript-4.9+-blue.svg)](https://www.typescriptlang.org/)\n\n**A powerful, production-ready framework for building real-time applications with HTTP and WebSocket support.**\n\nIOServer combines the speed of Fastify with the real-time capabilities of Socket.IO, providing a unified architecture for modern web applications. Built with TypeScript and designed for scalability, it offers a clean separation of concerns through services, controllers, managers, and watchers.\n\n## ✨ Features\n\n- 🚄 **High Performance** - Built on Fastify for maximum HTTP throughput\n- ⚡ **Real-time Communication** - Integrated Socket.IO for WebSocket connections\n- 🏗️ **Modular Architecture** - Clean separation with Services, Controllers, Managers, and Watchers\n- 🔒 **Security First** - Built-in CORS, error handling, and validation\n- 📝 **TypeScript Native** - Full type safety and IntelliSense support\n- 🧪 **Fully Tested** - Comprehensive test suite with 95%+ coverage\n- 🔧 **Configuration Driven** - JSON-based routing and flexible configuration\n- 📦 **Production Ready** - Memory leak detection, performance monitoring, and error handling\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\nnpm install ioserver\n# or\nyarn add ioserver\n```\n\n### Basic Usage\n\n```typescript\nimport { IOServer, BaseService, BaseController } from 'ioserver';\n\n// Create a service for real-time functionality\nclass ChatService extends BaseService {\n  async sendMessage(socket: any, data: any, callback?: Function) {\n    // Handle real-time messaging\n    socket.broadcast.emit('new_message', data);\n    if (callback) callback({ status: 'success' });\n  }\n}\n\n// Create a controller for HTTP endpoints\nclass ApiController extends BaseController {\n  async getStatus(request: any, reply: any) {\n    reply.send({ status: 'OK', timestamp: Date.now() });\n  }\n}\n\n// Initialize and configure server\nconst server = new IOServer({\n  host: 'localhost',\n  port: 3000,\n  cors: {\n    origin: ['http://localhost:3000'],\n    methods: ['GET', 'POST'],\n  },\n});\n\n// Register components\nserver.addService({ name: 'chat', service: ChatService });\nserver.addController({ name: 'api', controller: ApiController });\n\n// Start server\nawait server.start();\nconsole.log('🚀 Server running at http://localhost:3000');\n```\n\n## 🏗️ Architecture\n\nIOServer provides four core component types for building scalable applications:\n\n### 📡 **Services** - Real-time Logic\n\nHandle WebSocket connections and real-time events.\n\n```typescript\nclass NotificationService extends BaseService {\n  async notify(socket: any, data: any, callback?: Function) {\n    // Real-time notification logic\n    socket.emit('notification', { message: data.message });\n    if (callback) callback({ delivered: true });\n  }\n}\n```\n\n### 🌐 **Controllers** - HTTP Endpoints\n\nHandle HTTP requests with automatic route mapping from JSON configuration.\n\n```typescript\nclass UserController extends BaseController {\n  async getUser(request: any, reply: any) {\n    const userId = request.params.id;\n    reply.send({ id: userId, name: 'John Doe' });\n  }\n}\n```\n\n### 🔧 **Managers** - Shared Logic\n\nProvide shared functionality across services and controllers.\n\n```typescript\nclass DatabaseManager extends BaseManager {\n  async query(sql: string, params: any[]) {\n    // Database operations\n    return await this.db.query(sql, params);\n  }\n}\n```\n\n### 👀 **Watchers** - Background Tasks\n\nHandle background processes, monitoring, and scheduled tasks.\n\n```typescript\nclass HealthWatcher extends BaseWatcher {\n  async watch() {\n    setInterval(() =\u003e {\n      // Monitor system health\n      this.checkSystemHealth();\n    }, 30000);\n  }\n}\n```\n\n## 📋 Configuration\n\n### Server Options\n\n```typescript\nconst server = new IOServer({\n  host: 'localhost', // Server host\n  port: 3000, // Server port\n  verbose: 'INFO', // Log level\n  routes: './routes', // Route definitions directory\n  cors: {\n    // CORS configuration\n    origin: ['http://localhost:3000'],\n    methods: ['GET', 'POST', 'PUT', 'DELETE'],\n    credentials: true,\n  },\n  mode: ['websocket', 'polling'], // Socket.IO transport modes\n});\n```\n\n### Route Configuration\n\nDefine HTTP routes in JSON files (e.g., `routes/api.json`):\n\n```json\n[\n  {\n    \"method\": \"GET\",\n    \"url\": \"/users/:id\",\n    \"handler\": \"getUser\"\n  },\n  {\n    \"method\": \"POST\",\n    \"url\": \"/users\",\n    \"handler\": \"createUser\"\n  }\n]\n```\n\n## 🧪 Testing\n\nIOServer includes comprehensive testing utilities and examples:\n\n```bash\n# Run all tests\nnpm test\n\n# Test categories\nnpm run test:unit        # Unit tests\nnpm run test:integration # Integration tests\nnpm run test:e2e        # End-to-end tests\nnpm run test:performance # Performance tests\n\n# Coverage report\nnpm run test:coverage\n```\n\n## 📚 Examples\n\n### Real-time Chat Application\n\nA complete chat application example is included in the `examples/` directory, showcasing:\n\n- User authentication and management\n- Real-time messaging\n- Room-based conversations\n- Typing indicators\n- Connection management\n- API endpoints for statistics\n\n```bash\ncd examples/chat-app\nnpm install\nnpm start\n```\n\nVisit `http://localhost:8080` to see the chat application in action.\n\n## 🔧 API Reference\n\n### Core Classes\n\n- **`IOServer`** - Main server class\n- **`BaseService`** - Base class for WebSocket services\n- **`BaseController`** - Base class for HTTP controllers\n- **`BaseManager`** - Base class for shared logic managers\n- **`BaseWatcher`** - Base class for background watchers\n\n### Key Methods\n\n```typescript\n// Server management\nserver.addService(options: ServiceOptions)\nserver.addController(options: ControllerOptions)\nserver.addManager(options: ManagerOptions)\nserver.addWatcher(options: WatcherOptions)\nserver.start(): Promise\u003cvoid\u003e\nserver.stop(): Promise\u003cvoid\u003e\n\n// Real-time messaging\nserver.sendTo(options: SendToOptions): boolean\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Commit your changes: `git commit -m 'Add amazing feature'`\n4. Push to the branch: `git push origin feature/amazing-feature`\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the Apache-2.0 License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Built with [Fastify](https://www.fastify.io/) for high-performance HTTP\n- Powered by [Socket.IO](https://socket.io/) for real-time communication\n- Inspired by modern microservice architectures\n\n## 📞 Support\n\n- 📚 [Documentation](https://github.com/x42en/IOServer/wiki)\n- 🐛 [Issue Tracker](https://github.com/x42en/IOServer/issues)\n- 💬 [Discussions](https://github.com/x42en/IOServer/discussions)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \u003cstrong\u003eBuilt with ❤️ for the Node.js community\u003c/strong\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fx42en%2Fioserver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fx42en%2Fioserver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fx42en%2Fioserver/lists"}