vortez 4.1.3 → 5.0.0-dev.15

package/README.md

@@ -1,372 +1,318 @@
-# Importante
+# 🚀 Vortez
+
+This project began as a **personal journey** to deeply understand how web servers work in **Node.js**.
+Throughout its development, I’ve gained **tons of new skills and insights** that I’m excited to share.
+
+🛠️ **Continuous Improvement:**
+I constantly refactor the code whenever I spot areas that can be polished or optimized.
+
+🌟 **Real-World Usage:**
+I actively use this module in my own web projects, which means I’m always finding new ideas, enhancements, and opportunities to fix bugs based on feedback.
+
+💡 **Vision:**
+My goal is to make **Vortez** a tool that helps developers build **APIs**, **PWAs**, **websites**, and—thanks to the [Vizui module](https://github.com/NetFeez/Vizui)—**SPAs** with ease and confidence.
+
+Stay tuned for more updates and features! 🚀
+That’s all for now, [NetFeez](https://NetFeez.github.io) out.
+
+---
+
+# Installation
+
+You can use **npm** to install Vortez:
+
+* **Stable version**
+
+  ```console
+  mpm install vortez
+  ```
+* **Development version**
+
+  ```console
+  mpm install vortez@dev
+  ```
 
 > [!IMPORTANT]
-> La futura versión **3.7.0** será omitida hasta la versión **4.0.0**.
-> La razón de esta decisión fue que hubo cambios que afectan la compatibilidad
-> entre las versiones **3.6.5** y **3.7.0**:
->
-> Se está planteando que las funcionalidades **beta.mail** y **beta.jwt** se muevan a módulos separados.
-> Esta decisión dependerá de qué tan grandes se vuelvan dichas funcionalidades. Por el momento, y para la futura versión **4.0.0**,
-> seguirán estando en el lugar habitual, aunque con ciertos cambios que afectan la compatibilidad con las funciones beta
-> incorporadas en la versión **3.6.5**.
+> You need to set `"type": "module"` in your `package.json` to use **Vortez**.
+> This requirement will be removed in a future version, but for now please configure it like this:
 >
-> Recuerda que puedes acceder a la versión de desarrollo descargando la rama **dev** del repositorio o por medio de npm:
-> ```bash
-> npm i vortez@dev
+> ```json
+> {
+>   "name": "my-project",
+>   "main": "index.js",
+>   "type": "module"
+> }
 > ```
->
-> Como último punto, se planea cambiar el nombre del módulo en npm. Se darán detalles cuando se decida cuál será, y se agregará como dependencia a la última versión de **Vortez** que sea desplegada en npm.
 
+---
 
-# Vortez
+# Documentation
 
-Hola! soy [NetFeez](https://NetFeez.github.io).<br/>
-Como comente  anteriormente en mi perfil, Vortez permitirá:
+## Static Pages
 
-- [x] Crear servidores HTTP y HTTPS.
-- [ ] **En proceso** Sistema de plantillas.
-- [x] Gestionar conexiones WebSocket.
-- [ ] Gestionar negociaciones de WebRTC.
-- [ ] Gestionar notificaciones WebPush.
+You can use **Vortez** to serve static pages:
 
-Es posible que algunos de los puntos anteriores se subdividan en proyectos diferentes<br/>
-o que se cree un gestor de paquetes para implementar las funcionalidades dentro del mismo<br/>
+```js
+// Importing Vortez
+import Vortez from 'vortez';
 
-## Sobre el proyecto
+// Creating the server
+const server = new Vortez();
 
-Actualmente tengo en local una copia del proyecto con varias de las funcionalidades<br/>
-este comenzó como un proyecto personal y con fines de práctica de pensamiento lógico<br/>
-por lo tanto no tiene las mejores prácticas ni la mejor documentación, sin embargo<br/>
-publicaré el código de esta manera e iré modificando para corregir esto.
+// Adding rules
+server.router.addFolder('/source', 'source');
+server.router.addFile('/', 'source/index.html');
 
-```console
-mpm install vortez
+// Starting the server
+server.start();
 ```
 
-**Futuras correcciones**
+---
 
-- [x] Documentar clases y funciones para intellisense.
-- [x] Cambiar los nombres de variables, funciones, clases y descripciones a inglés.
-- [ ] **en proceso** Crear documentación para enseñar a usar el módulo.
-- [ ] **en proceso** Buscar y corregir malas practicas.
+## APIs and Websites
 
-Esto es todo por el momento, [NetFeez](https://NetFeez.github.io) se retira.
+You can use **actions** to execute code and send responses to the client:
 
-# Documentación 
+```js
+import Vortez from 'vortez';
 
-Primero debemos instalar el modulo usando
+const server = new Vortez();
 
-```console
-mpm install vortez
-```
+// Action with a static response
+server.router.addAction('GET', '/api/test', (request, response) => {
+  response.sendJson({
+    message: 'Hello World',
+    route: `[${request.method}] -> ${request.url}`
+  });
+});
 
-También es necesario que en tu package.json este el proyecto como type: module
-```json
-{
-  "name": "my-project",
-  "main": "index.js",
-  "type": "module"
-}
+// Route params and query params
+// Example route param: `/api/params/$id`
+// Example request: `http://localhost/api/params/123`
+server.router.addAction('GET', '/api/params/$id', (request, response) => {
+  response.sendJson({
+    message: 'Hello World',
+    route: `[${request.method}] -> ${request.url}`,
+    params: request.ruleParams,
+    query: request.searchParams
+  });
+});
+
+// Serving files
+server.router.addAction('GET', '/api/file', (request, response) => {
+  response.sendFile('source/index.html');
+});
+
+// Sending simple text
+server.router.addAction('GET', '/api/string', (request, response) => {
+  response.send('Hello World');
+});
+
+// Starting the server
+server.start();
 ```
 
-Una ves tengas Vortez en tu proyecto y lo hayas configurado como modulo debes importarlo<br/>
--->
-- Si en tu package.json tienes la propiedad `"type": "module"`:
-  ```js
-  import Vortez from 'vortez';
-  ```
-- Si no tienes esta propiedad usa:
-  ```js
-  //Actualmente no esta soportado, en futuras versiones se ampliara su compatibilidad
-  ```
+---
 
-## Servidor HTTP
+## SPAs
 
-Para crear un servidor HTTP puedes hacerlo de diferentes maneras:
+You can serve a single file for multiple URLs, including recursive routes:
 
-> [!NOTE]
-> Debes haber importado el modulo primero.
+```js
+import Vortez from 'vortez';
 
-- Solo pasando el puerto
+const server = new Vortez();
 
-  ```js
-  const Server = new Vortez(80);
-  ```
+server.router.addFile('/', 'main.html');
+server.router.addFile('/app/*', 'main.html');
+server.router.addFolder('/public', 'public');
 
-- Pasando Puerto y Host
+/*
+You can also add other features like actions, files, folders, etc.
+Use addWebSocket for real-time connections.
+*/
 
-  ```js
-  const Server = new Vortez(80, 'MiDominio.com');
-  ```
+server.start();
+```
 
-## Servidor HTTPS
+---
 
-> [!NOTE]
-> - Debes tener un certificado ssl (la clave publica y privada).
-> - Si no quieres especificar un host usa `null`.
-> - Actualmente se inicia el servidor HTTP y HTTPS a la vez en este caso
->   esto se corregirá y se pondrá como característica opcional en futuras versiones.
+## Server Configuration
+
+You can configure the server using the `server.config` object:
 
 ```js
-const server = new Vortez(80, null, {
-  pubKey: 'Cert/MiDominio.pem',    //El archivo con la clave publica       (Obligatorio)
-  privKey: 'Cert/MiDominio.key',   //El archivo con la  clave privada      (Obligatorio)
-  port: 443                        //El puerto donde se abrirá el servidor (Opcional)
-});
+import Vortez from 'vortez';
+const server = new Vortez();
+
+server.config.port = 3000;
+server.config.host = 'localhost';
+server.config.https = {
+  key: 'path/to/key.pem',
+  cert: 'path/to/cert.pem'
+};
+server.config.templates.error = 'error.html';
+server.config.templates.folder = 'folder.html';
 ```
 
-## Agregar enrutador
-
-En **`Vortez`** existen 4 clases de enrutador:
-
-|Tipo                   |Descripción                                          |
-|----------------------:|:----------------------------------------------------|
-|[Folder](#carpeta)     |Comparte una carpeta y sus sub-carpetas              |
-|[File](#archivo)       |Comparte un único archivo                            |
-|[Action](#acción)      |Te permite trabajar completamente con las solicitudes|
-|[WebSocket](#websocket)|Permite manejar conexiones WebSocket en esa ruta     |
-
-Los Métodos aceptados actualmente son:
-
-|Método|Descripción                                 |
-|-----:|:-------------------------------------------|
-|GET   |El método de petición `GET`.                |
-|POST  |El método de petición `POST`.               |
-|PUT   |El método de petición `PUT`.                |
-|DELETE|El método de petición `DELETE`.             |
-|ALL   |Todos los métodos anteriormente mencionados.|
-
-Como funciona la RuleUrl:<br/>
-
-Actualmente la RuleUrl acepta 2 características
- - Comodín * toma todas las sub rutas incluyendo hasta antes de *
-   - para /test/* tomaría /test y todo lo demás como /test/algo-mas/x
-   - para /test2/*/Algo tomaría /Test2/(cualquier-cosa)/Algo
-     es como el comodín $ solo que no guardara en una variable
- - Toma parámetros de la url usando $ seguido del nombre de la variable
-   y se puede acceder a ellas desde `Request.RuleParams`
-   **Ejemplo**:
-   ```js
-   server.addAction('ALL', '/User/$UserID/Post/$PostID', (request, response) => {
-    response.sendJson({
-      url: request.url,
-      ruleParams: request.ruleParams
-    });
-    /* Esto devolverá lo siguiente si la ruta fuera /User/111111/Post/222222
-      {
-         "Url": "/User/111111/Post/222222"
-         "RuleParams": {
-             "UserID": "111111",
-             "PostID": "222222"
-         }
-      }
-    */
-  });
-   ```
-**AuthExec**
-Es una función que recibe como parámetro la petición del http
-esta debe retornar un valor booleano, true para decir que la petición esta autenticada y false para decir que no lo esta.
-**Ejemplo**:
+You can also create the server with a configuration object passed to the constructor:
+
+* **Using options:**
+
 ```js
-// si la petición se hace con el QueryParam Auth y es igual a AuthYes se confirmara la autenticidad de la petición
-server.addFile('/FileWA', 'changes.md', (Request) => {
-    return Request.queryParams.has('Auth') && Request.queryParams.get('Auth') == 'AuthYes'
+const server = new Vortez({
+  port: 3000,
+  host: 'localhost',
+  ssl: null
 });
 ```
 
+* **Using the Config instance:**
 
-### Carpeta
+```js
+const config = new Vortez.Config();
+config.port = 3000;
+config.host = 'localhost';
+config.ssl = null;
 
-Comparte una carpeta y todo su contenido tanto archivos como sub-carpetas
+const server = new Vortez(config);
+```
 
-> [!WARNING]
-> - ⚠️No compartas la raíz de tu proyecto, ya que esto daría acceso a **TODO** su contenido.
->   - Datos privados como las llaves privadas de tus certificados.
->   - Contraseñas a bases de datos que estén en los archivos js del lado del servidor.
->   - Tokens de seguridad
->   y en general cualquier otro dato
-> - Esto tomara la ruta que le asignes de forma completa
->   **Ejemplo**: si le asignas la ruta `/src` tomaría todas las sub-rutas como `/src/estilos` 
+---
 
-Para añadir este tipo de regla usa:
+## URL Rules
 
-```js
-// Usando AddFile
-/*
-  Esta función acepta 3 parámetros:
-  UrlRule, Source, AuthExec.
-    AuthExec es opcional.
-*/
-server.addFolder('/MyFolder', 'Test');
+URL rules are strings used to define routes handled by the router.
+
+The main separator is `/` which indicates a new sub-route:
+
+* **`*`**: A wildcard that captures all sub-routes.
+* **`$<name>`**: A dynamic parameter you can access via `request.ruleParams`.
+* **`<string>`**: A literal segment that must match exactly.
+
+**Examples**:
+
+* `/api/*` — Matches `/api/users`, `/api/posts/comments`, etc.
+* `/user/$id` — Matches `/user/123`, capturing `123` as `id`.
+* `/blog/$category/$postId` — Matches `/blog/tech/42`, capturing `tech` as `category` and `42` as `postId`.
 
+---
 
-// Usando el constructor de la clase Rule:
-// De esta manera tienes mayor control sobre la creación de la regla.
-server.addRules(
-    /*
-      este constructor acepta 5 parámetros para crearse correctamente:
-      Tipo, Método, UrlRule, Content, AuthExec.
-      AuthExec es opcional.
-    */
-    new Vortez.Rule('Folder', 'GET', '/MyFolder/', 'Test/', () => true),
-  );
+## Rules
 
+In **Vortez**, there are four types of routers:
+
+| Type                    | Description                                            |
+| ----------------------- | ------------------------------------------------------ |
+| [Folder](#folder)       | Serves a folder and its sub-folders                    |
+| [File](#file)           | Serves a single file                                   |
+| [Action](#action)       | Lets you handle requests programmatically              |
+| [WebSocket](#websocket) | Allows managing WebSocket connections on a given route |
+
+### Folder
+
+Serves a folder and its sub-folders:
+
+> [!WARNING]
+> Do not share the root of your project, as this would expose **ALL** its contents:
+>
+> * Private certificate keys
+> * Database passwords in server-side `.js` files
+> * Security tokens
+> * And any other sensitive data
+>
+> Also:
+>
+> * The entire assigned path will be exposed.
+>
+>   * **Example:** assigning `/src` would include all sub-routes like `/src/styles`.
+
+```js
+server.router.addFolder('/my-folder', 'path/to/folder');
+server.router.addFolder('/my-folder-2', '/path/to/folder/absolute');
 ```
 
-### Archivo
+### File
 
-Comparte un archivo especifico
+Serves a single file:
 
 ```js
-// Usando AddFolder
-/*
-  Esta función acepta 3 parámetros:
-  UrlRule, Source, AuthExec.
-    AuthExec es opcional.
-*/
-server.addFile('/MyFile', 'changes.md');
-
-
-// Usando el constructor de la clase Rule:
-// De esta manera tienes mayor control sobre la creación de la regla.
-server.addRules(
-  /*
-    este constructor acepta 5 parámetros para crearse correctamente:
-    Tipo, Método, UrlRule, Content, AuthExec.
-    AuthExec es opcional.
-  */
-  new Vortez.Rule('File', 'GET', '/MyFile/*', 'changes.md', () => true),
-);
+server.router.addFile('/my-file', 'path/to/file');
+server.router.addFile('/my-file-2', '/path/to/file/absolute');
 ```
 
-### Acción
+### Action
 
-Te permite tener total control sobre esas peticiones:
+Lets you handle requests programmatically:
 
 ```js
-// Usando AddAction
-/*
-  Esta función acepta 4 parámetros:
-  Método, UrlRule, Action, AuthExec.
-    AuthExec es opcional.
-*/
-server.addAction('GET', '/', (request, response) => {
-    if (request.cookies.has('User_ID')) {
-      response.send("El User_ID que estas usando es:" + request.cookies.get('User_ID'));
-    } else {
-      response.sendFile('./ErrorUsuario.html');
-    }
-  }
-);
-
-
-// Usando el constructor de la clase Rule:
-// En este caso no hay diferencia a usar AddAction e incluso deberás especificar el tipo.
-Server.AddRules(
-  /*
-    este constructor acepta 5 parámetros para crearse correctamente:
-    Tipo, Método, UrlRule, Content, AuthExec.
-    AuthExec es opcional.
-  */
-  new Vortez.Rule('Action', 'GET', '/', (request, response) => {
-    if (request.cookies.has('User_ID')) {
-      response.send("El User_ID que estas usando es:" + request.cookies.get('User_ID'));
-    } else {
-      response.sendFile('./ErrorUsuario.html');
-    }
-  })
-);
+server.router.addAction('GET', '/my-action', (request, response) => {
+  response.sendJson({
+    message: 'Hello World',
+    route: `[${request.method}] -> ${request.url}`
+  });
+});
 ```
 
 ### WebSocket
 
-Esto te permite gestionar una conexión WebSocket completa:
-> [!NOTE]
-> Las url de los web sockets van por medio distinto al de las peticiones de File, Folder y Action por ende
-> no tendrán conflictos si son similares o iguales a ellas
+Allows managing WebSocket connections on a given route:
 
+> [!NOTE]
+> WebSocket URLs use a separate namespace from Files, Folders, and Actions,
+> so they won’t conflict even if they share the same route patterns.
 
 ```js
-// Usando AddWebSocket
-/*
-  Esta función acepta 3 parámetros:
-  UrlRule, Action, AuthExec.
-    AuthExec es opcional.
-*/
-const Conexiones = new Set();
+const connections = new Set();
+
 server.addWebSocket('/Test/WS-Chat', (request, socket) => {
-  console.log('[WS] CM: Conexión nueva')
-  Conexiones.forEach((Usuario) => Usuario.Send("Un usuario se conecto"));
-  Conexiones.add(socket);
-  socket.on('finish', () => Conexiones.delete(socket));
-  socket.on('error', (error) => console.log('[WS-Error]:', error));
+  console.log('[WS] New connection');
+  connections.forEach(user => user.Send('A user has connected.'));
+  connections.add(socket);
+
+  socket.on('finish', () => connections.delete(socket));
+  socket.on('error', error => console.log('[WS-Error]:', error));
+
   socket.on('message', (data, info) => {
-    //console.log(Info.OPCode);
-    if (info.opCode == 1) {
-      console.log('[WS] MSS:', data.toString());
-      Conexiones.forEach((Usuario) => {
-        if (Usuario !== socket) Usuario.Send(data.toString());
+    if (info.opCode === 1) {
+      console.log('[WS] Message:', data.toString());
+      connections.forEach(user => {
+        if (user !== socket) user.Send(data.toString());
       });
-    } else if (info.opCode == 8) {
-      Conexiones.forEach((Usuario) => Usuario.Send("Un usuario se desconecto"));
+    } else if (info.opCode === 8) {
+      connections.forEach(user => user.Send('A user has disconnected.'));
     }
   });
 });
+```
 
+---
 
-// Usando el constructor de la clase Rule:
-// En este caso no hay diferencia a usar AddWebSocket e incluso deberás especificar el tipo y el método.
-const Conexiones = new Set();
-Server.AddRules(
-  /*
-    este constructor acepta 5 parámetros para crearse correctamente:
-    Tipo, Método, UrlRule, Content, AuthExec.
-    AuthExec es opcional.
-    A pesar de recibir el método este no se tomara en cuenta para las conexiones web socket.
-  */
-  new Vortez.Rule('WebSocket', 'GET', '/Test/WS-Chat', (request, socket) => {
-    console.log('[WS] CM: Conexión nueva')
-    Conexiones.forEach((Usuario) => Usuario.Send("Un usuario se conecto"));
-    Conexiones.add(socket);
-    socket.on('finish', () => Conexiones.delete(socket));
-    socket.on('error', (error) => console.log('[WS-Error]:', error));
-    socket.on('message', (data, info) => {
-      //console.log(Info.OPCode);
-      if (info.opCode == 1) {
-        console.log('[WS] MSS:', data.toString());
-        Conexiones.forEach((Usuario) => {
-          if (Usuario !== socket) Usuario.Send(data.toString());
-        });
-      } else if (info.opCode == 8) {
-        Conexiones.forEach((Usuario) => Usuario.Send("Un usuario se desconecto"));
-      }
-    });
-  })
-);
-```
+# Development Version
+
+## Currently in Development
 
-# Version Dev
+The following features are under active development:
 
-## En desarrollo
+* **\[JsonWT]**: JSON Web Token (JWT) support.
+* **\[Mail]**: Email sending functionality.
+* **\[Server]**: Dynamic authentication system for routing.
 
-En el momento están en desarrollo:
-- [JsonWT]: El uso de Json Web Tokens.
-- [Mail]: El envió de E-Mails.
-- [Server]: El sistema de autenticación dinámico para las reglas de enrutamiento.
+## Installation
 
-## Instalación
+To install the development version:
 
-Para instalar la version en desarrollo:
 ```console
 mpm install vortez@dev
 ```
+
 > [!WARNING]
-> - Esta version podría contener errores.
-> - Contiene la version mas reciente del proyecto.
+> This version may contain bugs.
+> It includes the latest features that may not yet be fully tested.
+
+To access development features not yet listed in `changes.md`:
 
-Para acceder a las funciones en desarrollo sin añadir mencionadas en changes.md
 ```js
-import { Beta } from 'vortez'
-const Mail = Beta.Mail;
-const JsonWT = Beta.JsonWT;
-```
+import { Beta } from 'vortez';
+const { Mail, JwtManager } = Beta;
+```

package/build/Template.d.ts

@@ -4,10 +4,15 @@
  * @license Apache-2.0
  */
 export declare class Template {
-    /** Regular expressions used to compile the template */
+    /** Regular expressions used for parsing and processing the template. */
     private static expressions;
     /**
      * Load and compile a template.
+     * This method reads a template file from the specified path,
+     * checks if it's a valid file, and then compiles its content
+     * using the provided data object.
+     *
+     * @example `Template.load('./templates/myTemplate.html', { username: 'John Doe' });`
      * @param path - The path to the template file.
      * @param data - The data used to compile the template.
      * @returns The compiled template.
@@ -17,7 +22,12 @@ export declare class Template {
     static load(path: string, data: Template.dataObject): Promise<string>;
     /**
      * Compile a template.
-     * @param Content - The content of the template.
+     * This internal method takes the raw template content and the data object
+     * and performs the actual compilation, replacing variables and processing
+     * object/array blocks according to the defined syntax.
+     *
+     * @example `Template.compile('Hello, ${name}!', { name: 'Alice' });`
+     * @param content - The content of the template.
      * @param data - The data used to compile the template.
      * @returns The compiled template.
      * @throws Error if key and value names are equal in object blocks.
@@ -25,6 +35,10 @@ export declare class Template {
     private static compile;
 }
 export declare namespace Template {
+    /**
+     * Represents the structure of the data object used for template compilation.
+     * It is a key-value store where keys are strings and values can be of any type.
+     */
     interface dataObject {
         [key: string]: any;
     }