zyket 1.0.15 → 1.0.17

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/index.js

@@ -4,11 +4,14 @@ const EnvManager = require("./src/utils/EnvManager");
 
 const {Route, Middleware} = require("./src/services/express");
 const { Handler, Guard } = require("./src/services/socketio");
+const Schedule = require("./src/services/scheduler/Schedule");
+const Event = require("./src/services/events/Event");
 
 
 module.exports = {
   Kernel, Service,
   Route, Middleware,
   Handler, Guard,
+  Schedule, Event,
   EnvManager
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zyket",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
@@ -13,6 +13,7 @@
   "license": "ISC",
   "description": "",
   "dependencies": {
+    "bullmq": "^5.61.0",
     "colors": "^1.4.0",
     "cors": "^2.8.5",
     "dotenv": "^16.4.7",
@@ -20,6 +21,7 @@
     "fast-glob": "^3.3.3",
     "mariadb": "^3.4.0",
     "minio": "^8.0.5",
+    "node-cron": "^4.2.1",
     "node-dependency-injection": "^3.2.2",
     "prompts": "^2.4.2",
     "redis": "^4.7.0",

package/src/services/bullmq/Worker.js

@@ -0,0 +1,8 @@
+module.exports = class Worker {
+  name;
+  queueName = null;
+  
+  constructor(name) {
+    this.name = name;
+  }
+}

package/src/services/bullmq/index.js

@@ -0,0 +1,75 @@
+const Service = require("../Service");
+const { Queue, QueueEvents, Worker: BullWorker } = require("bullmq");
+const Worker = require("./Worker");
+const fs = require("fs");
+const path = require("path");
+const fg = require('fast-glob');
+
+module.exports = class BullMQ extends Service  {
+  #container
+  queues = {};
+  queuesEvents = {};
+
+  constructor(container) {
+    super("queues");
+    this.#container = container;
+  }
+
+  async boot() {
+    const queusConfig = this.#getActivatedQueues();
+
+    for (const queueName of queusConfig) {
+      this.queues[queueName] = new Queue(queueName, this.#connection());
+      this.queuesEvents[queueName] = new QueueEvents(queueName, this.#connection());
+      await this.#container.loggfer.info(`Queue ${queueName} initialized`);
+    }
+
+    const workers = await this.#loadWorkersFromFolder(path.join(process.cwd(), "src", "workers"));
+
+    for (const wkr of workers) {
+      if(!wkr.queueName) {
+        this.#container.get('logger').warn(`Worker ${wkr.name} has no queueName defined, skipping...`);
+        continue;
+      }
+      if (!this.queues[wkr.queueName]) {
+        this.#container.get('logger').warn(`Queue ${wkr.queueName} not found for worker ${wkr.name}, skipping...`);
+        continue;
+      }
+      new BullWorker(
+        wkr.queueName,
+        async (job) => wkr.handle({ container: this.#container, job }),
+        this.#connection()
+      );
+      this.#container.get('logger').info(`Worker ${wkr.name} for queue ${wkr.queueName} initialized`);
+    }
+  }
+
+  async #loadWorkersFromFolder(workersFolder) {
+    this.#createWorkersFolder(workersFolder);
+    const workers = (await fg('**/*.js', { cwd: workersFolder })).map((wkr) => {
+      const worker = require(path.join(workersFolder, wkr));
+      if(!(worker.prototype instanceof Worker)) throw new Error(`${wkr} is not a valid handler`);
+      return new worker(wkr.replace('.js', ''));
+    });
+    return workers;
+  }
+
+  #createWorkersFolder(workersFolder, overwrite = false) {
+    if (fs.existsSync(workersFolder) && !overwrite) return;
+    this.#container.get('logger').info(`Creating workers folder at ${workersFolder}`);
+    fs.mkdirSync(workersFolder);
+  }
+
+  #getActivatedQueues() {
+    const list = process.env.QUEUES || "";
+    return list.split(",").map(q => q.trim()).filter(q => q.length);
+  }
+
+  #connection() {
+    return {
+        connection: {
+          url: process.env.REDIS_URL || "redis://localhost:6379"
+        }
+    };
+  }
+}

package/src/services/events/Event.js

@@ -0,0 +1,7 @@
+module.exports = class Event {
+  name;
+  
+  constructor(name) {
+    this.name = name;
+  }
+}

package/src/services/events/index.js

@@ -0,0 +1,60 @@
+const Service = require("../Service");
+const fs = require("fs");
+const path = require("path");
+const fg = require('fast-glob');
+const Event = require("./Event");
+
+module.exports = class EventService extends Service  {
+  #container
+  events = {};
+
+  constructor(container) {
+    super("events");
+    this.#container = container;
+  }
+
+
+  emit(eventName, payload) {
+    const event = this.events[eventName];
+    if (!event) throw new Error(`Event ${eventName} not found`);
+    this.#container.get('logger').debug(`Emitting event ${eventName}`);
+    return event.handle({ container: this.#container, payload });
+  }
+
+  emitAsync(eventName, payload, timeout = 30000) {
+    const event = this.events[eventName];
+    if (!event) throw new Error(`Event ${eventName} not found`);
+    this.#container.get('logger').debug(`Emitting event ${eventName} asynchronously`);
+    return Promise.race([
+      event.handle({ container: this.#container, payload }),
+      new Promise((_, reject) => setTimeout(() => reject(new Error(`Event ${eventName} timed out after ${timeout}ms`)), timeout))
+    ]);
+  }
+
+  async boot() {
+    const events = await this.#loadEventsFromFolder(path.join(process.cwd(), "src", "events"));
+    this.#container.get('logger').info(`Loaded ${events.length} events`);
+    for (const evt of events) {
+      this.events[evt.name] = evt;
+      this.#container.get('logger').debug(`Event ${evt.name} initialized`);
+    }
+  }
+
+  async #loadEventsFromFolder(eventsFolder) {
+    this.#createEventsFolder(eventsFolder);
+    const events = (await fg('**/*.js', { cwd: eventsFolder })).map((evt) => {
+      const event = require(path.join(eventsFolder, evt));
+      if(!(event.prototype instanceof Event)) throw new Error(`${evt} is not a valid handler`);
+      return new event(evt.replace('.js', ''));
+    });
+    return events;
+  }
+
+  #createEventsFolder(eventsFolder, overwrite = false) {
+    if (fs.existsSync(eventsFolder) && !overwrite) return;
+    this.#container.get('logger').info(`Creating schedules folder at ${eventsFolder}`);
+    fs.mkdirSync(eventsFolder);
+  }
+
+
+}

package/src/services/index.js

@@ -3,13 +3,27 @@ const Cache = require("./cache");
 const S3 = require("./s3");
 const { SocketIO } = require("./socketio");
 const { Express } = require("./express");
+const Scheduler = require("./scheduler");
+const EventService = require("./events");
+
+const eventsActivated = process.env.DISABLE_EVENTS !== 'true';
+const databaseActivated = !!process.env.DATABASE_URL;
+const cacheActivated = !!process.env.CACHE_URL;
+const bullmqActivated = !!process.env.CACHE_URL && process.env.DISABLE_BULLMQ !== 'true';
+const s3Activated = process.env.S3_ENDPOINT && process.env.S3_ACCESS_KEY && process.env.S3_SECRET_KEY;
+const schedulerActivated = process.env.DISABLE_SCHEDULER !== 'true';
+const socketActivated = process.env.DISABLE_SOCKET !== 'true';
+const expressActivated = process.env.DISABLE_EXPRESS !== 'true';
 
 module.exports = [
   ["logger", require("./logger"), ["@service_container", process.env.LOG_DIRECTORY || `${process.cwd()}/logs`, process.env.DEBUG === "true"]],
   ["template-manager", require("./template-manager"), []],
-  process.env.DATABASE_URL ? ["database", Database, ["@service_container", process.env.DATABASE_URL]] : null,
-  process.env.CACHE_URL ? ["cache", Cache, ["@service_container", process.env.CACHE_URL]] : null,
-  (process.env.S3_ENDPOINT && process.env.S3_ACCESS_KEY && process.env.S3_SECRET_KEY) ? ["s3", S3, ["@service_container", process.env.S3_ENDPOINT, process.env.S3_PORT, process.env.S3_USE_SSL === "true", process.env.S3_ACCESS_KEY, process.env.S3_SECRET_KEY]] : null,
-  process.env.DISABLE_SOCKET !== 'true' ? ["socketio", SocketIO, ["@service_container"]] : null,
-  process.env.DISABLE_EXPRESS !== 'true' ? ["express", Express, ["@service_container"]] : null
+  eventsActivated ? ["events", EventService, ["@service_container"]] : null,
+  databaseActivated ? ["database", Database, ["@service_container", process.env.DATABASE_URL]] : null,
+  cacheActivated ? ["cache", Cache, ["@service_container", process.env.CACHE_URL]] : null,
+  s3Activated ? ["s3", S3, ["@service_container", process.env.S3_ENDPOINT, process.env.S3_PORT, process.env.S3_USE_SSL === "true", process.env.S3_ACCESS_KEY, process.env.S3_SECRET_KEY]] : null,
+  schedulerActivated ? ["scheduler", Scheduler, ["@service_container"]] : null,
+  bullmqActivated ? ["bullmq", require("./bullmq"), ["@service_container"]] : null,
+  socketActivated ? ["socketio", SocketIO, ["@service_container"]] : null,
+  expressActivated ? ["express", Express, ["@service_container"]] : null
 ].filter(Boolean);

package/src/services/scheduler/Schedule.js

@@ -0,0 +1,7 @@
+module.exports = class Schedule {
+  name;
+
+  constructor(name) {
+    this.name = name;
+  }
+}

package/src/services/scheduler/index.js

@@ -0,0 +1,42 @@
+const Service = require("../Service");
+const Schedule = require("./Schedule");
+const fs = require("fs");
+const path = require("path");
+const fg = require('fast-glob');
+const cron = require('node-cron');
+
+module.exports = class Scheduler extends Service  {
+  #container
+
+  constructor(container) {
+    super("scheduler");
+    this.#container = container;
+  }
+
+  async boot() {
+    const schedulers = await this.#loadSchedulersFromFolder(path.join(process.cwd(), "src", "schedulers"));
+    await this.#container.get('logger').info(`Loaded ${schedulers.length} schedulers`);
+    for (const schd of schedulers) {
+      cron.schedule(schd.time, () => schd.handle({ container: this.#container }));
+      this.#container.get('logger').info(`Scheduler ${schd.name}, ${schd.time} initialized`);
+    }
+  }
+
+  async #loadSchedulersFromFolder(schedulersFolder) {
+    this.#createSchedulersFolder(schedulersFolder);
+    const schedulers = (await fg('**/*.js', { cwd: schedulersFolder })).map((schd) => {
+      const schedule = require(path.join(schedulersFolder, schd));
+      if(!(schedule.prototype instanceof Schedule)) throw new Error(`${schd} is not a valid handler`);
+      return new schedule(schd.replace('.js', ''));
+    });
+    return schedulers;
+  }
+
+  #createSchedulersFolder(schedulersFolder, overwrite = false) {
+    if (fs.existsSync(schedulersFolder) && !overwrite) return;
+    this.#container.get('logger').info(`Creating schedules folder at ${schedulersFolder}`);
+    fs.mkdirSync(schedulersFolder);
+  }
+
+
+}

package/src/utils/EnvManager.js

@@ -24,7 +24,8 @@ module.exports = class EnvManager {
       S3_USE_SSL: true,
       S3_ACCESS_KEY: '',
       S3_SECRET_KEY: '',
-      LOG_DIRECTORY: "./logs"
+      LOG_DIRECTORY: "./logs",
+      QUEUES: '',
     }
 
     return Object.entries(envsToCreate).reduce((acc, [key, value]) => {