@vulkano/core 1.15.5 → 1.16.1

package/README.md

@@ -1,80 +1,347 @@
 <p align="center">
-  <img src="https://avatars.githubusercontent.com/u/42077334?s=200&v=4" alt="Nodemon Logo">
+  <img src="https://avatars.githubusercontent.com/u/42077334?s=200&v=4" alt="Vulkano Logo" width="100">
 </p>
 
-# Vulkano
+<h1 align="center">@vulkano/core</h1>
 
-Vulkano is a small, simple, and fast framework for creating web applications using NodeJS. Inspired by KumbiaPHP.
-
-[![Backers on Open Collective](https://opencollective.com/vulkanojs/backers/badge.svg)](#backers)
-[![Sponsors on Open Collective](https://opencollective.com/vulkanojs/sponsors/badge.svg)](#sponsors)
+<p align="center">
+  A fast, convention-based MVC framework for Node.js — built on top of Express.
+</p>
 
-## Backers
+<p align="center">
+  <a href="https://opencollective.com/vulkanojs#backer"><img src="https://opencollective.com/vulkanojs/backers/badge.svg" alt="Backers"></a>
+  <a href="https://opencollective.com/vulkanojs#sponsor"><img src="https://opencollective.com/vulkanojs/sponsors/badge.svg" alt="Sponsors"></a>
+</p>
 
-Thank you to all [our backers](https://opencollective.com/vulkanojs#backer)! 🙏
+---
 
-[![vulkano backers](https://opencollective.com/vulkanojs/tiers/backer.svg?avatarHeight=50)](https://opencollective.com/vulkanojs#backers)
+## What is Vulkano?
 
+Vulkano is a lightweight MVC framework for building web applications and APIs with Node.js. It wires together Express, MongoDB (Mongoose), Socket.io, i18n, JWT, file uploads, cron jobs, and more — so you spend time writing features, not boilerplate.
 
-## Buy me a coffe
+Inspired by [KumbiaPHP](https://www.kumbiaphp.com).
 
-[Buy me a coffe](https://buymeacoffee.com/argordmel) 🙏
+---
 
-## Install
+## Requirements
 
-### System
+- **Node.js** `^22`
+- **MongoDB** (optional — only needed if you use models)
+- **Redis** (optional — only needed for Socket.io Redis adapter or sessions)
 
-- Unix
-- Node.js v20+
+---
 
-### Packages
+## Installation
 
 ```bash
-$ npm install @vulkano/core
+npm install @vulkano/core
 ```
 
-## Your App Structure
-
-- `public/` - HTTP Public folder
-- `vulkano/` - Vulkano App (config, controllers, models, views)
-- `app.js` - Server entry point
+---
 
-## Your Server entry point
+## Quick Start
 
-```bash
-/**
- * app.js
- *
- * To start the server, run: ⁠ node app.js ⁠.
- *
- * For example:
- *   => ⁠ npm run start ⁠
- *   => ⁠ node app.js ⁠
- */
+### 1. Entry point — `app.js`
 
+```js
 const vulkano = require('@vulkano/core');
+vulkano();
+```
+
+### 2. Project structure
+
+```
+your-app/
+├── app.js                  # Entry point
+├── public/                 # Static files served over HTTP
+│   ├── css/
+│   ├── js/
+│   ├── img/
+│   └── files/              # Uploaded files
+└── vulkano/                # Your application
+    ├── config/
+    │   ├── settings.js     # App-wide settings (port, database, JWT…)
+    │   ├── routes.js       # Explicit route overrides (optional)
+    │   ├── env/            # Per-environment config overrides
+    │   ├── express/        # Express middleware customization
+    │   ├── settings.js     # App-wide settings (port, database, JWT…)
+    │   ├── routes.js       # Explicit route overrides (optional)
+    │   └── locales/        # i18n translation files (en.js, es.js, etc.)
+    ├── controllers/        # Request handlers
+    ├── models/             # Mongoose model definitions
+    └── services/           # Shared services & libs (auto-loaded as globals)
+```
+
+---
+
+## Routing
+
+Vulkano resolves routes **by convention** — no route file required for standard CRUD.
+
+### Convention-based (automatic)
+
+| HTTP method | URL              | Resolves to                         |
+|-------------|------------------|-------------------------------------|
+| `GET`       | `/user`          | `UserController.get`                |
+| `POST`      | `/user`          | `UserController.post`               |
+| `PUT`       | `/user/42`       | `UserController['put :id']`         |
+| `PATCH`     | `/user/42`       | `UserController['patch :id']`       |
+| `DELETE`    | `/user/42`       | `UserController['delete :id']`      |
+| `POST`      | `/user/save`     | `UserController['post save']`       |
+| `GET`       | `/user/42/info`  | `UserController['get :id/info']`    |
+
+### Controller example
+
+```js
+// vulkano/controllers/UserController.js
+module.exports = {
+
+  get(req, res) {
+    res.vsr(Promise.resolve({ users: [] }));
+  },
+
+  'get :id': function (req, res) {
+    res.vsr(Promise.resolve({ id: req.params.id }));
+  },
+
+  'post save': function (req, res) {
+    res.vsr(Promise.resolve({ saved: true }));
+  }
+
+};
+```
+
+### Explicit routes — `config/routes.js`
+
+```js
+module.exports = [
+  { method: 'GET',  path: '/health', controller: 'StatusController', action: 'ping' },
+  { method: 'POST', path: '/auth/login', controller: 'AuthController', action: 'login' },
+];
+```
+
+You can also register routes with inline handlers or using `app.vulkano.get/post/…`.
+
+---
+
+## Responses — `res.vsr()`
+
+Every controller action uses `res.vsr(promise)`. It wraps the resolved value in a standard envelope:
+
+```json
+{ "success": true, "statusCode": 200, "data": { … } }
+```
+
+Errors are handled automatically:
+
+```js
+// Custom error with status code
+res.vsr(VSError.reject('Not allowed', 403));
+
+// 404
+res.vsr(VSError.notFound('User'));
+
+// Plain rejection → 500
+res.vsr(Promise.reject(new Error('Something went wrong')));
+```
+
+---
+
+## Scaffold — zero-code REST API
+
+Point a controller at a model and get a full REST API for free:
+
+```js
+// vulkano/controllers/api/ProductController.js
+module.exports = {
+  scaffold: 'Product',           // Mongoose model name
+  allowedMethods: ['get', 'post', 'put', 'patch', 'delete']
+};
+```
+
+This automatically exposes:
+
+| Method   | Path               | Action           |
+|----------|--------------------|------------------|
+| `GET`    | `/api/product`     | List (paginated) |
+| `GET`    | `/api/product/:id` | Get by ID        |
+| `POST`   | `/api/product`     | Create           |
+| `PUT`    | `/api/product/:id` | Replace          |
+| `PATCH`  | `/api/product/:id` | Partial update   |
+| `DELETE` | `/api/product/:id` | Soft-delete      |
+
+Query string params supported on list: `page`, `per_page`, `sort`, `search`, `fields`.
+
+---
+
+## Models
 
-vulkano(); ⁠
+Models live in `vulkano/models/` and are auto-loaded as globals (e.g., `Product`).
+
+```js
+// vulkano/models/Product.js
+module.exports = {
+  attributes: {
+    name:  { type: String, required: true },
+    price: { type: Number, default: 0 },
+    tags:  { type: [String] }
+  },
+
+  // Lifecycle hooks
+  beforeSave(next) {
+    this.updatedAt = new Date();
+    next();
+  }
+};
+```
+
+Every model automatically gets `active`, `createdAt`, and `updatedAt` fields.
+Models use [`mongoose-paginate-v2`](https://github.com/aravindnc/mongoose-paginate-v2) for pagination.
+
+---
+
+## Built-in Global Libs
+
+All files in `vulkano/services/` are auto-loaded as globals. The framework also exposes:
+
+| Global      | Description                                                     |
+|-------------|-----------------------------------------------------------------|
+| `VSError`   | Structured error factory (`reject`, `notFound`, `badRequest`)   |
+| `Jwt`       | Sign / verify JWT tokens                                        |
+| `Paginate`  | Query serialization and pagination helpers                      |
+| `Merge`     | Deep-merge utility (deepmerge-compatible, full option support)  |
+| `Encrypter` | Hash and compare passwords (bcrypt-based)                       |
+| `Filter`    | Input sanitization helpers                                      |
+| `Crontab`   | Schedule recurring jobs with cron expressions                   |
+| `ApiClient` | HTTP client for calling external APIs (native fetch + undici)   |
+| `Download`  | File download helper                                            |
+| `i18n`      | Internationalization via i18next                                |
+| `mongoose`  | Mongoose instance                                               |
+
+---
+
+## File Uploads
+
+Vulkano uses [Multer](https://github.com/expressjs/multer) v2. Files are available on `req.files` after a `multipart/form-data` POST:
+
+```js
+'post upload': function (req, res) {
+  const files = (req.files || []).map((f) => ({
+    fieldname:    f.fieldname,
+    originalname: f.originalname,
+    mimetype:     f.mimetype,
+    size:         f.size
+  }));
+  res.vsr(Promise.resolve({ uploaded: files.length, files }));
+}
+```
+
+---
+
+## JWT Authentication
+
+Configure in `vulkano/config/express/jwt.js`:
+
+```js
+module.exports = {
+  secret: process.env.JWT_SECRET,
+  unless: ['/auth/login', '/health']   // Public paths (no token required)
+};
+```
+
+Sign a token anywhere in your app:
+
+```js
+const token = Jwt.encode({ userId: user._id });
+```
+
+---
+
+## Cron Jobs
+
+```js
+// vulkano/services/Jobs.js
+module.exports = {
+  init() {
+    Crontab.add('cleanup', '0 3 * * *', async () => {
+      await Report.deleteMany({ active: false });
+    });
+  }
+};
 ```
 
+---
+
+## i18n
+
+Translation files go in `vulkano/config/locales/`. Use `i18n.t('key')` anywhere in your app.
+
+---
+
+## Socket.io
+
+Enabled via `vulkano/config/settings.js`. Adapters for MongoDB and Redis are included out of the box.
+
+---
+
+## Configuration — `vulkano/config/settings.js`
+
+```js
+module.exports = {
+
+  // PORT to listen on
+  port: process.env.PORT || 3000,
+
+  // Salt for password
+  salt: process.env.SALT_KEY || '',
+
+  // Database configuration
+  database: {
+
+    // MONGO_URI connection
+    connection: process.env.MONGO_URI,
+
+    // Settings before to connect
+    settings: {
+      strictQuery: false,
+      debug: false
+    },
+
+    // Additional config to mongoose
+    config: {
+      useNewUrlParser: true,
+      useUnifiedTopology: true,
+      // family: 4 // 4 (IPv4), 6 (IPv6), or null (default: OS family)
+      // useFindAndModify: false,
+      // useCreateIndex: true
+    }
+
+  }
+};
+```
+
+---
+
+## Running Tests
+
+```bash
+npm test              # all suites
+npm run test:watch    # watch mode
+npm run test:coverage # with coverage report
+```
+
+> Tests require Node.js 22. Use `nvm use 22` if needed.
+
+---
+
+## Support
 
-## Your Vulkano App Folder
+- [Open an issue](https://github.com/vulkanojs/vulkano-core/issues)
+- [Open Collective — Backers](https://opencollective.com/vulkanojs#backers)
+- [Buy me a coffee](https://buymeacoffee.com/argordmel)
 
-- `vulkano/` - Vulkano App
-  - `config` - Your config files
-    - `env` - Folder for custom environment settings
-    - `express` - Folder to customize the server (cookies, jwt, helmet, cors and settings)
-    - `locales` - i18n folder
-    - `views` - Folder to customize filters and helpers to Nunjukcs
-  - `controllers` - Your controllers
-  - `models` - Your models
-  - `services` - Your services or libs
+---
 
-## Your Vulkano Public Folder
+## License
 
-- `public/` - Public Path
-  - `css` - Styles
-  - `fonts` - Fonts
-  - `img` - Images
-  - `js` - Javascript
-  - `files` - Files uploaded
+MIT © [Vulkano Team](https://github.com/vulkanojs)

package/app.js

@@ -6,18 +6,14 @@
  */
 
 // Start Time for logs
-global.START_TIME = new Date();
+global.START_TIME = Date.now();
 
 const dotenv = require('dotenv');
 const path = require('path');
-const moment = require('moment');
-const merge = require('deepmerge');
-const _ = require('underscore');
 const v8 = require('v8');
 const fs = require('fs');
 
 global.app = {};
-global._ = _;
 
 const rootProject = path.resolve(process.cwd());
 
@@ -62,7 +58,7 @@ if (!fs.existsSync(PUBLIC_PATH)) {
 }
 
 // Read Dontenv config
-dotenv.config({ path: `${ABS_PATH}/.env` });
+dotenv.config({ path: `${ABS_PATH}/.env`, quiet: !process.env.DOTENV_VERBOSE });
 
 // Include all api config
 const config = require('include-all')({
@@ -71,6 +67,8 @@ const config = require('include-all')({
   optional: true
 });
 
+const merge = require('./libs/Merge');
+
 //
 // Get package.json information
 //
@@ -236,7 +234,7 @@ async function startVulkano() {
       const startUpConfig = [];
       startUpConfig.push(' SOCKETS: ', `${colors.fg.green}${showColumn(socketText, 10)}${colors.reset}`);
       startUpConfig.push(' | ');
-      startUpConfig.push(` STARTUP: ${colors.fg.green}${moment(moment().diff(global.START_TIME)).format('s.SSS')}s${colors.reset}`);
+      startUpConfig.push(` STARTUP: ${colors.fg.green}${((Date.now() - global.START_TIME) / 1000).toFixed(3)}s${colors.reset}`);
       console.log(startUpConfig.join(''));
 
       const dbConfig = [];

package/bootstrap/express.js

@@ -1,4 +1,4 @@
-const merge = require('deepmerge');
+const merge = require('../libs/Merge');
 
 module.exports = function getExpressConfiguration() {
 

package/bootstrap/server.js

@@ -56,6 +56,10 @@ module.exports = function loadServer() {
 
       const vulkano = express();
 
+      // Expose the Express instance early so that custom() initializers in
+      // config/routes.js can register routes via app.vulkano.get(), app.vulkano.post(), etc.
+      app.vulkano = vulkano;
+
       // Settings
       vulkano.enable('trust proxy');
 
@@ -173,8 +177,8 @@ module.exports = function loadServer() {
           res.header('Access-Control-Allow-Origin', '*');
           res.header('Access-Control-Allow-Headers', 'X-Requested-With, X-HTTP-Method-Override, Content-Type, Accept');
         }
-        res.header('Allow', 'GET,PUT,POST,DELETE,OPTIONS');
-        res.header('Access-Control-Allow-Methods', 'GET,PUT,POST,DELETE,OPTIONS');
+        res.header('Allow', 'GET,PUT,PATCH,POST,DELETE,OPTIONS');
+        res.header('Access-Control-Allow-Methods', 'GET,PUT,PATCH,POST,DELETE,OPTIONS');
 
         res.status(200).end();
 
@@ -230,7 +234,7 @@ module.exports = function loadServer() {
           tmpCorsHeaders = tmpCorsHeaders.concat(expressConfig.cors.headers || []);
 
           res.header('Access-Control-Allow-Origin', expressConfig.cors.origin);
-          res.header('Access-Control-Allow-Methods', 'GET,PUT,POST,DELETE,OPTIONS');
+          res.header('Access-Control-Allow-Methods', 'GET,PUT,PATCH,POST,DELETE,OPTIONS');
           res.header('Access-Control-Allow-Headers', tmpCorsHeaders.join(', '));
 
           // Disable CACHE in API resources.
@@ -440,10 +444,15 @@ module.exports = function loadServer() {
         next();
       });
 
-      // Middleware Folder
+      // Middleware Folder — routes.js always loads first if present
       const middlewares = app.config.middlewares || {};
 
+      if (middlewares.routes && typeof middlewares.routes === 'function') {
+        vulkano.use(middlewares.routes);
+      }
+
       Object.keys(middlewares).forEach( (item) => {
+        if (item === 'routes') return;
         const middlewareFunction = middlewares[item];
         if (typeof middlewareFunction === 'function') {
           vulkano.use(middlewareFunction);
@@ -497,13 +506,26 @@ module.exports = function loadServer() {
       Object.keys(this.routes || {}).forEach((i) => {
 
         const current = this.routes[i];
+
+        // Initializer functions: keys that are not path-based ('/...') and not
+        // 'METHOD path' pairs are treated as startup hooks that register routes
+        // directly via app.vulkano.get(), app.vulkano.post(), etc.
+        const keyParts = i.split(' ');
+        const isPathRoute = i.includes('/');
+        const isMethodRoute = ['get', 'post', 'put', 'delete', 'patch'].includes(keyParts[0].toLowerCase()) && keyParts.length > 1;
+
+        if (!isPathRoute && !isMethodRoute && typeof current === 'function') {
+          current();
+          return;
+        }
+
         const parts = i.split(' ');
         let pathToRun = parts.pop();
 
         // Capture the HTTP Method
         let option = (parts[0] !== undefined) ? String(parts[0]).toLowerCase() : 'get';
 
-        if (option !== 'get' && option !== 'post' && option !== 'put' && option !== 'delete') {
+        if (option !== 'get' && option !== 'post' && option !== 'put' && option !== 'patch' && option !== 'delete') {
           option = 'get';
         }
 
@@ -600,7 +622,9 @@ module.exports = function loadServer() {
             path: routePath
           } = r || {};
 
-          const routerControllerToCheck = Filter.get(req.path, 'trim', '/').split('/')[0];
+          const routerControllerToCheck = (typeof Filter !== 'undefined')
+            ? Filter.get(req.path, 'trim', '/').split('/')[0]
+            : req.path.replace(/^\/+|\/+$/g, '').split('/')[0];
 
           return routePath.startsWith(`/${routerControllerToCheck}`);
 
@@ -668,21 +692,26 @@ module.exports = function loadServer() {
 
         }
 
-        let errorViewToShow = `${CORE_PATH}/views/errors/exception.html`;
+        const errStack = (err && err.stack) ? String(err.stack) : '';
+        const isMissingTemplate = errStack.includes('template not found');
 
-        if (err.stack.indexOf('template not found') >= 0) {
-          errorViewToShow = `${CORE_PATH}/views/errors/no_view.html`;
+        let missingView = '';
+        if (isMissingTemplate) {
+          const afterNotFound = errStack.split('not found:')[1] || '';
+          missingView = `${afterNotFound.split('.')[0].trim()}.html`;
         }
 
+        const errorViewToShow = isMissingTemplate
+          ? `${CORE_PATH}/views/errors/no_view.html`
+          : `${CORE_PATH}/views/errors/exception.html`;
+
         res.render(errorViewToShow, {
           statusCode: status,
           method: req.method,
           controller: req.path.split('/')[1],
           action: req.path.split('/')[2],
-          view: err.stack.indexOf('template not found') >= 0
-            ? String( `${(err.stack.split('not found:')[1]).split('.')[0]}.html` ).trim()
-            : '',
-          stack: err.stack
+          view: missingView,
+          stack: errStack
         });
 
       });
@@ -733,10 +762,14 @@ module.exports = function loadServer() {
 
       if ( String(adapter).toLocaleLowerCase() === 'redis') {
 
+        const {
+          socket: socketRedisConfig
+        } = redisAdapter || {};
+
         const {
           host,
           port
-        } = redisAdapter || {};
+        } = socketRedisConfig || redisAdapter || {};
 
         if (!host || !port) {
           throw new Error('Unable to connect to Redis. File: "app/config/sockets/adapters/redis.js" to connect the sockets');
@@ -762,16 +795,9 @@ module.exports = function loadServer() {
 
       if ( String(adapter).toLocaleLowerCase() === 'redis') {
 
-        const propsToRedis = {
-          host: redisAdapter.host,
-          port: redisAdapter.port
-        };
-
-        if (redisAdapter.password) {
-          propsToRedis.password = redisAdapter.password;
-        }
+        pubClient = socketRedis(redisAdapter);
+        pubClient.on('error', (err) => console.log('Socket Redis Client Error', err));
 
-        pubClient = socketRedis(propsToRedis);
         subClient = pubClient.duplicate();
 
         io.adapter(socketRedisAdapter(pubClient, subClient));
@@ -792,7 +818,7 @@ module.exports = function loadServer() {
 
           let mongoClientDB = null;
 
-          // if not has a mongo conection try to create it
+          // If no active Mongoose connection, create a dedicated one
           if (!mongoose.connection.readyState) {
 
             if (!socketsConnection) {
@@ -914,7 +940,7 @@ module.exports = function loadServer() {
 
           });
 
-          // next line is the money
+          // Expose io globally so controllers can emit events
           global.io = io;
           vulkano.set('socketio', io);
 

package/controllers/ScaffoldController.js

@@ -93,6 +93,20 @@ module.exports = (modelName, allowedMethods) => {
 
     },
 
+    'patch :id': function onPatchRecord(req, res) {
+
+      const {
+        id
+      } = req.params || {};
+
+      const {
+        body
+      } = req || {};
+
+      res.vsr(global[modelName].update(id, body), 202);
+
+    },
+
     'delete :id': function onDeleteRecord(req, res) {
 
       const {
@@ -124,6 +138,10 @@ module.exports = (modelName, allowedMethods) => {
       delete allMethods['put :id'];
     }
 
+    if (!tempAllowedMethods.includes('patch')) {
+      delete allMethods['patch :id'];
+    }
+
     if (!tempAllowedMethods.includes('delete')) {
       delete allMethods['delete :id'];
     }

package/controllers/controllers.js

@@ -17,7 +17,7 @@ module.exports = function loadControllersApplication() {
 
   Object.keys(AllControllers).forEach( (controller) => {
 
-    const methods = ['get', 'post', 'put', 'delete'];
+    const methods = ['get', 'post', 'put', 'patch', 'delete'];
     const current = AllControllers[controller];
 
     const {
@@ -101,7 +101,7 @@ module.exports = function loadControllersApplication() {
                 method = pathToRun.toLowerCase();
                 pathToRun = `/${moduleName}/${controllerName}/`;
               } else {
-                pathToRun = `/${moduleName}/${controllerName}/${pathToRun.replace(/GET|POST|DELETE|PUT/i, '')}`;
+                pathToRun = `/${moduleName}/${controllerName}/${pathToRun.replace(/GET|POST|DELETE|PUT|PATCH/i, '')}`;
               }
 
             }
@@ -132,7 +132,7 @@ module.exports = function loadControllersApplication() {
             method = pathToRun.toLowerCase();
             pathToRun = `/${controllerName}/`;
           } else {
-            pathToRun = `/${controllerName}/${pathToRun.replace(/GET|POST|DELETE|PUT/i, '')}`;
+            pathToRun = `/${controllerName}/${pathToRun.replace(/GET|POST|DELETE|PUT|PATCH/i, '')}`;
           }
         }