Gathering detailed insights and metrics for ioserver
Gathering detailed insights and metrics for ioserver
Damn simple Fastify & Socket.io server framework with TypeScript support
Installations
npm install ioserverDeveloper Guide
BETA
Typescript
Yes
Module System
CommonJS
Min. Node Version
>=18.0.0
Node Version
20.19.2
NPM Version
10.8.2
Releases
34
Languages
2
TypeScript
JavaScript
TypeScript (93.14%)
JavaScript (6.86%)
Developer
Download Statistics
Total Downloads
0
Last Day
0
Last Week
0
Last Month
0
Last Year
0
GitHub Statistics
Apache-2.0 License
326 Commits
2 Watchers
5 Branches
3 Contributors
Updated on Jun 10, 2025
Maintainers
1
Package Meta Information
Latest Version
2.0.6
Package Id
ioserver@2.0.6
Unpacked Size
105.39 kB
Size
26.91 kB
File Count
19
NPM Version
10.8.2
Node Version
20.19.2
Published on
Jun 10, 2025
Total Downloads
Cumulative downloads
Total Downloads
NaN
Last Day
0%
NaN
Compared to previous day
Last Week
0%
NaN
Compared to previous week
Last Month
0%
NaN
Compared to previous month
Last Year
0%
NaN
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
🚀 IOServer
A powerful, production-ready framework for building real-time applications with HTTP and WebSocket support.
IOServer 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.
✨ Features
- 🚄 High Performance - Built on Fastify for maximum HTTP throughput
- ⚡ Real-time Communication - Integrated Socket.IO for WebSocket connections
- 🏗️ Modular Architecture - Clean separation with Services, Controllers, Managers, and Watchers
- 🔒 Security First - Built-in CORS, error handling, and validation
- 📝 TypeScript Native - Full type safety and IntelliSense support
- 🧪 Fully Tested - Comprehensive test suite with 95%+ coverage
- 🔧 Configuration Driven - JSON-based routing and flexible configuration
- 📦 Production Ready - Memory leak detection, performance monitoring, and error handling
🚀 Quick Start
Installation
1npm install ioserver 2# or 3yarn add ioserver
Basic Usage
1import { IOServer, BaseService, BaseController } from 'ioserver'; 2 3// Create a service for real-time functionality 4class ChatService extends BaseService { 5 async sendMessage(socket: any, data: any, callback?: Function) { 6 // Handle real-time messaging 7 socket.broadcast.emit('new_message', data); 8 if (callback) callback({ status: 'success' }); 9 } 10} 11 12// Create a controller for HTTP endpoints 13class ApiController extends BaseController { 14 async getStatus(request: any, reply: any) { 15 reply.send({ status: 'OK', timestamp: Date.now() }); 16 } 17} 18 19// Initialize and configure server 20const server = new IOServer({ 21 host: 'localhost', 22 port: 3000, 23 cors: { 24 origin: ['http://localhost:3000'], 25 methods: ['GET', 'POST'], 26 }, 27}); 28 29// Register components 30server.addService({ name: 'chat', service: ChatService }); 31server.addController({ name: 'api', controller: ApiController }); 32 33// Start server 34await server.start(); 35console.log('🚀 Server running at http://localhost:3000');
🏗️ Architecture
IOServer provides four core component types for building scalable applications:
📡 Services - Real-time Logic
Handle WebSocket connections and real-time events.
1class NotificationService extends BaseService { 2 async notify(socket: any, data: any, callback?: Function) { 3 // Real-time notification logic 4 socket.emit('notification', { message: data.message }); 5 if (callback) callback({ delivered: true }); 6 } 7}
🌐 Controllers - HTTP Endpoints
Handle HTTP requests with automatic route mapping from JSON configuration.
1class UserController extends BaseController { 2 async getUser(request: any, reply: any) { 3 const userId = request.params.id; 4 reply.send({ id: userId, name: 'John Doe' }); 5 } 6}
🔧 Managers - Shared Logic
Provide shared functionality across services and controllers.
1class DatabaseManager extends BaseManager { 2 async query(sql: string, params: any[]) { 3 // Database operations 4 return await this.db.query(sql, params); 5 } 6}
👀 Watchers - Background Tasks
Handle background processes, monitoring, and scheduled tasks.
1class HealthWatcher extends BaseWatcher { 2 async watch() { 3 setInterval(() => { 4 // Monitor system health 5 this.checkSystemHealth(); 6 }, 30000); 7 } 8}
📋 Configuration
Server Options
1const server = new IOServer({ 2 host: 'localhost', // Server host 3 port: 3000, // Server port 4 verbose: 'INFO', // Log level 5 routes: './routes', // Route definitions directory 6 cors: { 7 // CORS configuration 8 origin: ['http://localhost:3000'], 9 methods: ['GET', 'POST', 'PUT', 'DELETE'], 10 credentials: true, 11 }, 12 mode: ['websocket', 'polling'], // Socket.IO transport modes 13});
Route Configuration
Define HTTP routes in JSON files (e.g., routes/api.json):
1[ 2 { 3 "method": "GET", 4 "url": "/users/:id", 5 "handler": "getUser" 6 }, 7 { 8 "method": "POST", 9 "url": "/users", 10 "handler": "createUser" 11 } 12]
🧪 Testing
IOServer includes comprehensive testing utilities and examples:
1# Run all tests 2npm test 3 4# Test categories 5npm run test:unit # Unit tests 6npm run test:integration # Integration tests 7npm run test:e2e # End-to-end tests 8npm run test:performance # Performance tests 9 10# Coverage report 11npm run test:coverage
📚 Examples
Real-time Chat Application
A complete chat application example is included in the examples/ directory, showcasing:
- User authentication and management
- Real-time messaging
- Room-based conversations
- Typing indicators
- Connection management
- API endpoints for statistics
1cd examples/chat-app 2npm install 3npm start
Visit http://localhost:8080 to see the chat application in action.
🔧 API Reference
Core Classes
IOServer- Main server classBaseService- Base class for WebSocket servicesBaseController- Base class for HTTP controllersBaseManager- Base class for shared logic managersBaseWatcher- Base class for background watchers
Key Methods
1// Server management 2server.addService(options: ServiceOptions) 3server.addController(options: ControllerOptions) 4server.addManager(options: ManagerOptions) 5server.addWatcher(options: WatcherOptions) 6server.start(): Promise<void> 7server.stop(): Promise<void> 8 9// Real-time messaging 10server.sendTo(options: SendToOptions): boolean
🤝 Contributing
We welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
📄 License
This project is licensed under the Apache-2.0 License - see the LICENSE file for details.
🙏 Acknowledgments
- Built with Fastify for high-performance HTTP
- Powered by Socket.IO for real-time communication
- Inspired by modern microservice architectures
📞 Support
Built with ❤️ for the Node.js community
No vulnerabilities found.
Reason
no dangerous workflow patterns detected
Reason
no binaries found in the repo
Reason
29 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 10
Reason
license file detected
Details
- Info: project has a license file: LICENSE:0
- Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0
Reason
packaging workflow detected
Details
- Info: Project packages its releases by way of GitHub Actions.: .github/workflows/publish.yml:60
Reason
1 existing vulnerabilities detected
Details
- Warn: Project is vulnerable to: GHSA-v6h2-p8h4-qcjw
Reason
Found 0/7 approved changesets -- score normalized to 0
Reason
detected GitHub workflow tokens with excessive permissions
Details
- Warn: no topLevel permission defined: .github/workflows/build.yml:1
- Info: topLevel 'contents' permission set to 'read': .github/workflows/docs.yml:10
- Warn: no topLevel permission defined: .github/workflows/publish.yml:1
- Info: no jobLevel write permissions found
Reason
no effort to earn an OpenSSF best practices badge detected
Reason
dependency not pinned by hash detected -- score normalized to 0
Details
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:19: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/build.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/build.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/build.yml:28: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/build.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/build.yml:39: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/build.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/build.yml:62: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/build.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/docs.yml:24: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/docs.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/docs.yml:29: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/docs.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/docs.yml:39: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/docs.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/docs.yml:44: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/docs.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/docs.yml:65: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/docs.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/docs.yml:68: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/docs.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/docs.yml:82: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/docs.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish.yml:23: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/publish.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish.yml:26: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/publish.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/publish.yml:31: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/publish.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish.yml:42: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/publish.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish.yml:68: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/publish.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/publish.yml:73: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/publish.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish.yml:85: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/publish.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/publish.yml:92: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/publish.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/publish.yml:107: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/publish.yml/master?enable=pin
- Warn: third-party GitHubAction not pinned by hash: .github/workflows/publish.yml:115: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/publish.yml/master?enable=pin
- Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/publish.yml:133: update your workflow using https://app.stepsecurity.io/secureworkflow/x42en/IOServer/publish.yml/master?enable=pin
- Warn: pipCommand not pinned by hash: .github/workflows/docs.yml:35
- Warn: pipCommand not pinned by hash: .github/workflows/docs.yml:36
- Info: 0 out of 15 GitHub-owned GitHubAction dependencies pinned
- Info: 0 out of 8 third-party GitHubAction dependencies pinned
- Info: 0 out of 2 pipCommand dependencies pinned
Reason
security policy file not detected
Details
- Warn: no security policy file detected
- Warn: no security file to analyze
- Warn: no security file to analyze
- Warn: no security file to analyze
Reason
project is not fuzzed
Details
- Warn: no fuzzer integrations found
Reason
SAST tool is not run on all commits -- score normalized to 0
Details
- Warn: 0 commits out of 30 are checked with a SAST tool
Score
5.1
/10
Last Scanned on 2025-06-30
The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.
Learn More