zyket 1.0.15 → 1.0.16

package/README.md

@@ -1,63 +1,174 @@
-# ZYKET - Easy Socket.io Framework
+# Zyket
 
-Zyket is a framework inspired by Symfony that simplifies working with Socket.io by providing a structured approach.
+Zyket is a Node.js framework designed to simplify the development of real-time applications with Socket.IO and Express. Inspired by the structured approach of frameworks like Symfony, Zyket provides a robust, service-oriented architecture for building scalable and maintainable server-side applications.
 
-# Getting Started
+Upon initial boot, Zyket automatically scaffolds a default project structure, including handlers, routes, and configuration files, allowing you to get started immediately.
 
-To use zyket we need to install it into our project:
+## Getting Started
 
-```javascript
+To begin using Zyket, install it in your project:
+
+```bash
 npm i zyket
 ```
 
-Then we just need to import the Kernel and boot it:
+Then, create an `index.js` file and boot the Zyket Kernel:
 
 ```javascript
+// index.js
 const { Kernel } = require("zyket");
+
+// Instantiate the kernel
 const kernel = new Kernel();
 
-kernel.boot().then(() => console.log(`Kernel Booted`));
+// Boot the kernel to start all services
+kernel.boot().then(() => {
+    console.log("Kernel booted successfully!");
+});
 ```
 
-After boot is done for fist time, project folders/files will be created if doesnt exists.
+When you run this for the first time, Zyket will create a default `.env` file and a `src` directory containing boilerplate for routes, handlers, guards, and middlewares.
+
+## Core Concepts
 
-## Handlers
+Zyket is built around a few key architectural concepts:
+
+*   **Socket.IO Handlers & Guards**: For managing real-time WebSocket events and their authorization.
+*   **Express Routes & Middlewares**: For handling traditional RESTful API endpoints.
+*   **Services**: Reusable components that are managed by a dependency injection container.
+*   **CLI**: A command-line tool to scaffold features from templates.
+
+### Socket.IO Development
+
+#### Handlers
+
+Handlers are classes that process incoming Socket.IO events. The name of the handler file (e.g., `message.js`) determines the event it listens to (`message`).
 
-Handlers are the way to interact with user messages on the socket:
 ```javascript
+// src/handlers/message.js
 const { Handler } = require("zyket");
 
 module.exports = class MessageHandler extends Handler {
-    middlewares = ["default"];
+  // Array of guard names to execute before the handler
+  guards = ["default"];
+
+  async handle({ container, socket, data, io }) {
+    const logger = container.get("logger");
+    logger.info(`Received message: ${JSON.stringify(data)}`);
+    socket.emit("response", { received: data });
+  }
+};
+```
 
-    async handle({ container, socket, data, io }) {
-        container.get("logger").info("Message handler");
-    }
+#### Guards
+
+Guards are used to protect Socket.IO handlers or the initial connection. They run before the handler's `handle` method and are ideal for authorization logic.
+
+```javascript
+// src/guards/default.js
+const { Guard } = require("zyket");
+
+module.exports = class DefaultGuard extends Guard {
+  async handle({ container, socket, io }) {
+    container.get("logger").info(`Executing default guard for socket ${socket.id}`);
+    
+    // Example: Check for an auth token. If invalid, disconnect the user.
+    // if (!socket.token) {
+    //   socket.disconnect();
+    // }
+  }
 };
 ```
 
-- middlewares: An array of middleware names that should be executed before the handler.
+### Express API Development
 
-- handle(): The function that processes the event, receiving container, socket, and data.
+#### Routes
+
+Routes handle HTTP requests. The file path maps directly to the URL endpoint. For example, `src/routes/index.js` handles requests to `/`, and `src/routes/[test]/message.js` handles requests to `/:test/message`.
+
+```javascript
+// src/routes/index.js
+const { Route } = require("zyket");
+const DefaultMiddleware = require("../middlewares/default");
+
+module.exports = class DefaultRoute extends Route {
+  // Apply middlewares to specific HTTP methods
+  middlewares = {
+    get: [ new DefaultMiddleware() ],
+    post: [ new DefaultMiddleware() ]
+  }
+
+  async get({ container, request }) {
+    container.get("logger").info("Default route GET");
+    return { test: "Hello World GET!" };
+  }
+
+  async post({ container, request }) {
+    container.get("logger").info("Default route POST");
+    return { test: "Hello World POST!" };
+  }
+};
+```
 
-## Middlewares
+#### Middlewares
 
-Middlewares allow you to process data before it reaches the handler. They can be used for validation, authentication, logging, etc.
+Middlewares process the request before it reaches the route handler. They follow the standard Express middleware pattern.
 
 ```javascript
+// src/middlewares/default.js
 const { Middleware } = require("zyket");
 
 module.exports = class DefaultMiddleware extends Middleware {
-    async handle({ container, socket, io }) {
-        container.get("logger").info("Default middleware");
-    }
+  async handle({ container, request, response, next }) {
+    container.get("logger").info("Default Express middleware executing");
+    next(); // Pass control to the next middleware or route handler
+  }
 };
 ```
 
-- handle(): The function that processes the event, receiving container, socket, and data.
+## Services
 
+Services are the cornerstone of Zyket's architecture, providing reusable functionality across your application. Zyket includes several default services and allows you to register your own.
 
-## Services
+### Custom Services
+
+You can create your own services by extending the `Service` class and registering it with the Kernel.
+
+```javascript
+// src/services/MyCustomService.js
+const { Service } = require("zyket");
+
+module.exports = class MyCustomService extends Service {
+    constructor() {
+        super("my-custom-service");
+    }
+
+    async boot() {
+        console.log("MyCustomService has been booted!");
+    }
+
+    doSomething() {
+        return "Something was done.";
+    }
+}
+```
+
+Register the service in your main `index.js` file:
+
+```javascript
+// index.js
+const { Kernel } = require("zyket");
+const MyCustomService = require("./src/services/MyCustomService");
+
+const kernel = new Kernel({
+    services: [
+        // [name, class, [constructor_args]]
+        ["my-service", MyCustomService, []]
+    ]
+});
+
+kernel.boot();
+```
 Services are reusable components specified in the kernel configuration. Each service must include a boot() function that is executed when the kernel starts.
 
 ```javascript

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zyket",
-  "version": "1.0.15",
+  "version": "1.0.16",
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"