ioserver 1.5.3 → 2.0.3

package/README.md

@@ -1,309 +1,266 @@
-# IOServer
+# 🚀 IOServer
 
-[![NPM](https://nodei.co/npm/ioserver.png?compact=true)](https://nodei.co/npm/ioserver/)
+[![npm version](https://badge.fury.io/js/ioserver.svg)](https://badge.fury.io/js/ioserver)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-yellow.svg)](https://opensource.org/licenses/Apache-2.0)
+[![Node.js CI](https://github.com/x42en/IOServer/workflows/Node.js%20CI/badge.svg)](https://github.com/x42en/IOServer/actions)
+[![codecov](https://codecov.io/gh/x42en/IOServer/branch/main/graph/badge.svg)](https://codecov.io/gh/x42en/IOServer)
+[![TypeScript](https://img.shields.io/badge/TypeScript-4.9+-blue.svg)](https://www.typescriptlang.org/)
 
-[![Downloads per month](https://img.shields.io/npm/dm/ioserver.svg?maxAge=2592000)](https://www.npmjs.org/package/ioserver)
-[![npm version](https://img.shields.io/npm/v/ioserver.svg)](https://www.npmjs.org/package/ioserver)
-[![Build Status](https://travis-ci.org/x42en/IOServer.svg?branch=master)](https://travis-ci.org/x42en/IOServer)
-[![Known Vulnerabilities](https://snyk.io/test/github/x42en/ioserver/badge.svg)](https://snyk.io/test/github/x42en/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.
 
-Damn simple way to setup your [Socket.io](http://socket.io) server using coffeescript or vanilla JS.
+## ✨ Features
 
-This will launch a server on hots:port specified (default: localhost:8080) and will register all method of the class set as service, except ones starting by '_' (underscore). The web server is based on [Fastify](https://fastify.io/) so you can even add REST routes and interact with your socket.io rooms and namespaces.  
-  
-The socket.io's registrated methods will then be accessible as standard client-side socket.io event:
-```coffeescript
-  socket.emit 'method_name', data
-```
+- 🚄 **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
 
-## Install
-
-Install with npm:
-  ```bash
-    npm install ioserver
-  ```
-  
-## Basic Usage
-
-Require the module:
-  ```coffeescript
-    IOServer = require 'ioserver'
-
-    app = new IOServer
-          verbose: true
-  ```
-
-Add manager using:
-  ```coffeescript
-    app.addManager
-      name:      'manager_name'
-      manager:   ManagerClass
-  ```
-
-Add services using:
-  ```coffeescript
-    app.addService
-      name:      'service_name'
-      service:   ServiceClass
-  ```
-
-Add watchers using:
-  ```coffeescript
-    app.addWatcher
-      name:      'watcher_name'
-      watcher:   WatcherClass
-  ```
-
-Add controller using:
-  ```coffeescript
-    app.addController
-      name:      'controller_name'
-      controller:   ControllerClass
-  ```
-
-Start the server...
-  ```coffeescript
-    app.start()
-  ```
-
-
-## Extended usage
-
-You can add services with Middlewares:
-  ```coffeescript
-    app.addService
-      name:      'service_name'
-      service:   ServiceClass
-      middlewares: [
-        AccessMiddleware
-      ]
-  ```
-Middlewares are invoked at the socket connection to namespaces, they are usually used for restricting access, validate connection method and parameters.  
-
-You can send event from external process
-  ```coffeescript
-    app.sendTo
-      event:   'event name'
-      data:     data
-  ```
-
-to specific namespace ...
-  ```coffeescript
-    app.sendTo
-      namespace: '/namespace'
-      event:     'event name'
-      data:      data
-  ```
-
-... or specific room
-  ```coffeescript
-    app.sendTo
-      namespace: '/namespace'
-      room:      'room_name'
-      event:     'event name'
-      data:      data
-  ```
-and even specific socket.id
-  ```coffeescript
-    app.sendTo
-      namespace: '/namespace'
-      sid:       socket.id
-      event:     'event name'
-      data:      data
-  ```
-
-You can add controller with Middlewares and routes prefix:
-  ```coffeescript
-    app.addController
-      name:      'controller_name'
-      prefix: '/my_prefix/'
-      controller:   ControllerClass
-      middlewares: [
-        RESTMiddleware
-      ]
-  ```
-
-You cann add watchers class that will be launched at start using watch() method
-  ```coffeescript
-    app.addWatcher
-      name:      'watcher_name'
-      watcher:   WatcherClass
-  ```
-
-In order to meet the fastify requirements, some pre-requised are needed to setup REST endpoints.
-1. First your JS class will define your accessible controller's methods
-  ```coffeescript
-  module.exports = class HelloController
-    constructor: (@app) ->
-
-    _isAuthentified: (req, reply, next) ->
-      if not req.headers['x-authentication']?
-        return reply.forbidden()
-      
-      next()
-    
-    world: (req, reply) ->
-      return { message: "Hello world" }
-    
-    display: (req, reply) ->
-      return { message: "Hello #{req.params.message}" }
-    
-    restricted: (req, reply) ->
-      return { message: "Welcome on Private Area" }
-  ```
-
-2. Then setup a routes description file (by default it will be looked-up into a `routes/${controller_name}.json` directory at root level of your project). *You can use different location by specifying `routes` options on IOServer instanciation (see unit-tests for examples).*
-  ```json
-  [
-    {
-      "method": "GET",
-      "url": "/",
-      "handler": "world"
-    },
-    {
-      "method": "GET",
-      "url": "/:message",
-      "handler": "display"
-    },
-    {
-      "method": "GET",
-      "url": "/private/",
-      "handler": "restricted",
-      "preValidation": "_isAuthentified"
-    }
-  ]
-  ```
-**All routes options from [fastify](https://www.fastify.io/docs/latest/Routes/#full-declaration) are supported**
-
-
-Common options are:
-  ```coffeescript
-    app = require 'ioserver'
-      port:     8443                         # change listening port
-      host:     '192.168.1.10'               # change listening host
-      mode:     ['websocket']                # Set socket.io client
-                                             # transport modes
-                                             # default is:
-                                             #  ['websocket','polling']
-                                             # available methods are:
-                                             #  ['websocket','htmlfile','polling','jsonp-polling']
-      verbose:  'DEBUG'                      # set verbosity level
-      cookies: false                         # Enable cookie usage for
-                                             # Socket.io v3
-
-      cors: {                                # Set up CORS as requested
-        origin: 'http://mydomain.com'        # in Socket.io v3
-        methods: ['GET','POST']
-      }
-  ```
-
-## Example
-
-1. Write a simple class (singleChat.coffee)
-  ```coffeescript
-    module.exports = class SingleChat
-      
-      constructor: (@app) ->
-      
-      replay: (socket, text) ->
-        console.log "Someone say: #{text}."
-        socket.broadcast.emit 'message', text
-
-      # Synchronous event are supported
-      sync_replay: (socket, text, callback) ->
-        console.log "Someone say: #{text}."
-        callback text
-
-      # All methods starting with '_' are meant private
-      # and will not be published
-      _notAccessible: (socket) ->
-        console.error "You should not be here !!"
-  ```
-
-2. Start server-side ioserver process (server.coffee)
-  ```coffeescript
-    IOServer      = require 'ioserver'
-    ChatService = require './singleChat'
-
-    app = new IOServer()
-
-    app.addService
-      name:  'chat'
-      service:   ChatService
-
-    app.start()
-  ```
-
-3. Compile and run server
-  ```bash
-    coffee -c *.coffee
-    node server.js
-  ```
-
-4. Write simple client wich interact with server class method as socket.io events
-  ```coffeescript
-    $           = require 'jquery'
-    io          = require 'socket.io-client'
-    NODE_SERVER = 'Your-server-ip'
-    NODE_PORT   = 'Your-server-port' # Default 8080
-
-    socket = io.connect "http://#{NODE_SERVER}:#{NODE_PORT}/chat"
-    
-    # When server emit action
-    socket.on 'message', msg, ->
-      $('.message_list').append "<div class='message'>#{msg}</div>"
-
-    # Jquery client action
-    $('button.send').on 'click', ->
-      msg = $('input[name="message"]').val()
-      socket.emit 'replay', msg
-    
-    # You can also use callback for synchronous actions
-    $('button.send').on 'click', ->
-      msg = $('input[name="message"]').val()
-      socket.emit 'sync_replay', msg, (data) ->
-        $('.message_list').append "<div class='message'>#{data}</div>"
-
-  ```
-For further case study you can also check de demo Chat application...  
-(link provided in few ~~days~~ weeks ;) )
-
-## Developers
-
-If you want to contribute to this project you are more than welcome !  
-
-### Run tests
 ```bash
-npm test
+npm install ioserver
+# or
+yarn add ioserver
+```
+
+### Basic Usage
+
+```typescript
+import { IOServer, BaseService, BaseController } from 'ioserver';
+
+// Create a service for real-time functionality
+class ChatService extends BaseService {
+  async sendMessage(socket: any, data: any, callback?: Function) {
+    // Handle real-time messaging
+    socket.broadcast.emit('new_message', data);
+    if (callback) callback({ status: 'success' });
+  }
+}
+
+// Create a controller for HTTP endpoints
+class ApiController extends BaseController {
+  async getStatus(request: any, reply: any) {
+    reply.send({ status: 'OK', timestamp: Date.now() });
+  }
+}
+
+// Initialize and configure server
+const server = new IOServer({
+  host: 'localhost',
+  port: 3000,
+  cors: {
+    origin: ['http://localhost:3000'],
+    methods: ['GET', 'POST'],
+  },
+});
+
+// Register components
+server.addService({ name: 'chat', service: ChatService });
+server.addController({ name: 'api', controller: ApiController });
+
+// Start server
+await server.start();
+console.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.
+
+```typescript
+class NotificationService extends BaseService {
+  async notify(socket: any, data: any, callback?: Function) {
+    // Real-time notification logic
+    socket.emit('notification', { message: data.message });
+    if (callback) callback({ delivered: true });
+  }
+}
+```
+
+### 🌐 **Controllers** - HTTP Endpoints
+
+Handle HTTP requests with automatic route mapping from JSON configuration.
+
+```typescript
+class UserController extends BaseController {
+  async getUser(request: any, reply: any) {
+    const userId = request.params.id;
+    reply.send({ id: userId, name: 'John Doe' });
+  }
+}
+```
+
+### 🔧 **Managers** - Shared Logic
+
+Provide shared functionality across services and controllers.
+
+```typescript
+class DatabaseManager extends BaseManager {
+  async query(sql: string, params: any[]) {
+    // Database operations
+    return await this.db.query(sql, params);
+  }
+}
+```
+
+### 👀 **Watchers** - Background Tasks
+
+Handle background processes, monitoring, and scheduled tasks.
+
+```typescript
+class HealthWatcher extends BaseWatcher {
+  async watch() {
+    setInterval(() => {
+      // Monitor system health
+      this.checkSystemHealth();
+    }, 30000);
+  }
+}
 ```
 
-**Please use Coffeescript for development language**  
+## 📋 Configuration
+
+### Server Options
+
+```typescript
+const server = new IOServer({
+  host: 'localhost', // Server host
+  port: 3000, // Server port
+  verbose: 'INFO', // Log level
+  routes: './routes', // Route definitions directory
+  cors: {
+    // CORS configuration
+    origin: ['http://localhost:3000'],
+    methods: ['GET', 'POST', 'PUT', 'DELETE'],
+    credentials: true,
+  },
+  mode: ['websocket', 'polling'], // Socket.IO transport modes
+});
+```
+
+### Route Configuration
+
+Define HTTP routes in JSON files (e.g., `routes/api.json`):
+
+```json
+[
+  {
+    "method": "GET",
+    "url": "/users/:id",
+    "handler": "getUser"
+  },
+  {
+    "method": "POST",
+    "url": "/users",
+    "handler": "createUser"
+  }
+]
+```
 
-### Compilation
+## 🧪 Testing
+
+IOServer includes comprehensive testing utilities and examples:
 
-Use coffeescript to compile your tests
 ```bash
-coffee --no-header -wc ./test
+# Run all tests
+npm test
+
+# Test categories
+npm run test:unit        # Unit tests
+npm run test:integration # Integration tests
+npm run test:e2e        # End-to-end tests
+npm run test:performance # Performance tests
+
+# Coverage report
+npm run test:coverage
 ```
 
-Use coffeescript to compile your changes in IOServer
+## 📚 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
+
 ```bash
-npm run build
+cd examples/chat-app
+npm install
+npm start
 ```
 
-### Publish
+Visit `http://localhost:8080` to see the chat application in action.
+
+## 🔧 API Reference
 
-The NPM publishing is automated, just commit (or better merge) into master with comment 'Release v1.0.x' in order to publish corresponding package in NPM.
+### Core Classes
 
-### Bump version
+- **`IOServer`** - Main server class
+- **`BaseService`** - Base class for WebSocket services
+- **`BaseController`** - Base class for HTTP controllers
+- **`BaseManager`** - Base class for shared logic managers
+- **`BaseWatcher`** - Base class for background watchers
 
-```sh
-npm --no-git-tag-version version [<newversion> | major | minor | patch]
+### Key Methods
+
+```typescript
+// Server management
+server.addService(options: ServiceOptions)
+server.addController(options: ControllerOptions)
+server.addManager(options: ManagerOptions)
+server.addWatcher(options: WatcherOptions)
+server.start(): Promise<void>
+server.stop(): Promise<void>
+
+// Real-time messaging
+server.sendTo(options: SendToOptions): boolean
 ```
 
-## TODO
-* [ ] write better doc
-* [ ] publish chat demo example
-* [x] improve unit tests for complete coverage (restricted method)
-* [x] Add REST API support
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Commit your changes: `git commit -m 'Add amazing feature'`
+4. Push to the branch: `git push origin feature/amazing-feature`
+5. Open a Pull Request
+
+## 📄 License
+
+This project is licensed under the Apache-2.0 License - see the [LICENSE](LICENSE) file for details.
+
+## 🙏 Acknowledgments
+
+- Built with [Fastify](https://www.fastify.io/) for high-performance HTTP
+- Powered by [Socket.IO](https://socket.io/) for real-time communication
+- Inspired by modern microservice architectures
+
+## 📞 Support
+
+- 📚 [Documentation](https://github.com/x42en/IOServer/wiki)
+- 🐛 [Issue Tracker](https://github.com/x42en/IOServer/issues)
+- 💬 [Discussions](https://github.com/x42en/IOServer/discussions)
+
+---
+
+<div align="center">
+  <strong>Built with ❤️ for the Node.js community</strong>
+</div>