@mlagie/sql-connector 1.4.9 → 2.0.0

package/docs/fr/README.md

@@ -1,5 +1,8 @@
 # Documentation du module sql-connector
 
+![GitHub package.json version](https://img.shields.io/github/package-json/v/lagie-marin/sql-connector?color=#008000) ![NPM Downloads](https://img.shields.io/npm/d18m/%40mlagie%2Fsql-connector?color=#008000) ![NPM Downloads](https://img.shields.io/npm/dw/%40mlagie%2Fsql-connector?color=#008000) ![GitHub followers](https://img.shields.io/github/followers/lagie-marin?style=plastic&color=color%3D%23008000) ![GitHub repo size](https://img.shields.io/github/repo-size/lagie-marin/sql-connector?color=%green)
+ ![GitHub last commit](https://img.shields.io/github/last-commit/lagie-marin/sql-connector)
+
 [English](../../README.md) | Français
 
 Le module sql-connector permet de gérer des connexions MySQL, de définir des schémas, de synchroniser automatiquement des tables et d'exposer des modèles pour manipuler les données simplement.
@@ -36,18 +39,18 @@ await logout();
 
 `Schema` décrit la structure d'une table. Chaque champ peut utiliser les propriétés suivantes.
 
-| Propriété | Type | Description |
-|---|---|---|
-| type | `SqlType` ou `{ name: SqlType }` | Type SQL du champ |
-| length | `number` | Longueur maximale |
-| required | `boolean` | Champ obligatoire |
-| default | `any` | Valeur par défaut |
-| unique | `boolean` | Valeur unique |
-| auto_increment | `boolean` | Auto-incrément |
-| foreignKey | `string` | Référence de clé étrangère |
-| enum | `string[]` | Liste de valeurs autorisées |
-| primary_key | `boolean` | Clé primaire |
-| customize | `string` | Options SQL additionnelles |
+| Propriété      | Type                             | Description                 |
+|----------------|----------------------------------|-----------------------------|
+| type           | `SqlType` ou `{ name: SqlType }` | Type SQL du champ           |
+| length         | `number`                         | Longueur maximale           |
+| required       | `boolean`                        | Champ obligatoire           |
+| default        | `any`                            | Valeur par défaut           |
+| unique         | `boolean`                        | Valeur unique               |
+| auto_increment | `boolean`                        | Auto-incrément              |
+| foreignKey     | `string`                         | Référence de clé étrangère  |
+| enum           | `string[]`                       | Liste de valeurs autorisées |
+| primary_key    | `boolean`                        | Clé primaire                |
+| customize      | `string`                         | Options SQL additionnelles  |
 
 ```javascript
 const userSchema = new Schema({
@@ -66,7 +69,22 @@ const userSchema = new Schema({
     type: String,
     enum: ['active', 'inactive', 'pending'],
     default: 'pending'
-  }
+  },
+    uuid: {
+        type: String,
+        required: true,
+        primary_key: true,
+        length: 36
+    },
+    my_uuid: {
+        type: String,
+        required: true,
+        length: 36
+    },
+    created_at: {
+        type: Date,
+        default: sqlTypeMap.CurrentTimestamp
+    }
 });
 ```
 
@@ -75,13 +93,9 @@ const userSchema = new Schema({
 `Model.syncAllTables()` compare les schémas JS avec la base et applique uniquement les différences utiles.
 
 - Ajout de colonne: automatique.
-- Suppression de colonne: uniquement avec `dangerousSync: true`.
-- Renommage de colonne: possible avec `oldName`.
-- Tables orphelines: sauvegarde avant suppression dans un fichier `backup_*.sql`.
 
 ```javascript
 await Model.syncAllTables();
-await Model.syncAllTables({ dangerousSync: true });
 ```
 
 Point important: ne combinez pas `primary_key: true` et `unique: true` sur le même champ. Une clé primaire est déjà unique et non nulle.
@@ -93,24 +107,190 @@ Point important: ne combinez pas `primary_key: true` et `unique: true` sur le m
 Méthodes principales:
 
 - `save(data)` pour insérer une ligne
-- `findOne(filter, fields)` pour récupérer une seule entrée
 - `find(filter, fields)` pour récupérer plusieurs entrées
-- `findAll(options)` pour les recherches avancées
 - `count(filter)` pour compter les lignes
 - `customRequest(custom)` pour exécuter une requête SQL personnalisée
 - `delete(filter)` pour supprimer une entrée
 - `dropTable()` pour supprimer la table
 - `generate_uuid()` pour générer un UUID unique
-- `Model.createAllTables()` pour créer toutes les tables dans le bon ordre
 
 ```javascript
 const userModel = new Model('users', userSchema);
 
-await Model.createAllTables();
+await Model.syncAllTables();
 await userModel.save({ email: 'user@example.com', status: 'active' });
 
-const user = await userModel.findOne({ email: 'user@example.com' });
-await userModel.delete({ email: 'user@example.com' });
+const user = await userModel.find({ where: { email: 'user@example.com' }});
+await user[0].deleteOne();
+```
+
+## Fonction save
+
+Enregistre les données dans la table de la base de données.
+
+- **Parameters** `data` *(Object)* - Les données à insérer dans la table.
+- **Returns** `Promise<Object>` - Une promesse avec le résultat de l'insertion.
+- **Throws** `Error` - Lève une erreur si l'insertion échoue.
+
+```js
+const User = require("user");
+
+async function createUser(email, stat) {
+    if (!email || !stat) {
+        console.error("Email & stat is required");
+        return;
+    }
+    await User.save({ email: email, status: stat });
+
+}
+```
+
+## Fonction find
+
+Récupère des entrées de la table.
+
+- **Parameters** `options` *(Object)* - Options de requête
+- **Parameters** `options.select` *(string[])* - Champs à renvoyer.
+- **Parameters** `options.where` *(Object)* - Filtre (key/value).
+- **Parameters** `options.order` *(Array)* - Ex: [['points', 'DESC']]
+- **Parameters** `options.limit` *(number)* - Limite de résultats.
+- **Returns** `Promise<Array<ModelInstance>>`
+
+### Options de find
+
+| Option     | Type            | Description                                              | Example                                      |
+|------------|-----------------|----------------------------------------------------------|----------------------------------------------|
+| `select`   | Array           | Champs ou transformations à récupérer                    | `['date_day']`                               |
+| `where`    | Object / String | Conditions de filtrage                                   | `{ project_id: 1 }`                          |
+| `groupBy`  | Array           | Champs utilisés pour regrouper les résultats             | `['period']`                                 |
+| `orderBy`  | Array           | Règles de tri                                            | `[{ field: 'date_day', direction: 'DESC' }]` |
+| `having`   | String          | Clause HAVING pour les requêtes agrégées                 | `'SUM(total_runs) > 100'`                    |
+| `limit`    | Number          | Limite le nombre de résultats                            | `100`                                        |
+
+## Exemple find
+
+```js
+const User = require("user");
+
+await User.find({
+  select: [
+    { dateFormat: ['date_day', '%Y-%m'], as: 'period' },
+    { sum: 'error' },
+    { sum: 'reload' },
+  ],
+  groupBy: ['period'],
+  orderBy: [{ field: 'period', direction: 'ASC' }],
+  limit: 10
+});
+```
+
+```js
+const User = require("user");
+
+await User.find({
+  select: [
+    "email"
+  ],
+  where: {
+    id: 1
+  }
+})
+```
+
+## Fonction count
+
+Compte le nombre d'enregistrements correspondant au filtre donné.
+
+- **Parameters** `filter` *(Object)* Les critères de filtrage de la requête. Il doit s'agir d'un objet dont les clés sont les noms des colonnes et les valeurs sont les valeurs de filtrage.
+- **Returns** `Promise<ModelInstance|number>` - Une promesse qui se résout en une instance `ModelInstance` si un enregistrement est trouvé, ou en `0` si aucun enregistrement ne correspond au filtre.
+
+## Exemple count
+
+```js
+const User = require("user");
+
+await User.count({
+  id: id
+})
+```
+
+## Fonction customRequest
+
+La fonction customRequest vous permet d'exécuter des requêtes SQL non prises en charge par sql-connector ; cela peut concerner des requêtes utilisant des mots-clés qui ne sont pas encore implémentés.
+
+- **Parameters** `custom` *(string)*  La requête SQL personnalisée à exécuter.
+- **Returns** `Promise<void>` Valeur retournée
+- **Throws** `Error` Lève une erreur si l'exécution de la requête échoue.
+
+## Exemple customRequest
+
+```js
+const User = require("user");
+
+await User.customRequest("SELECT id, email, status
+  FROM users
+  WHERE status IN ('active', 'pending')
+  AND email LIKE '%gmail.com';")
+```
+
+## Fonction delete
+
+Supprime de la table SQL une entrée correspondant au filtre fourni.
+
+- **Parameters** `filter` *(Object)* Un objet représentant les conditions de filtrage pour la suppression.
+- **Returns** `Promise<number>` Une promesse qui se résout à 0 si aucune ligne n'a été supprimée, ou à une instance de modèle représentant la ligne supprimée.
+- **Throws** `Error` Une promesse qui se résout à 0 si aucune ligne n'a été supprimée, ou à une instance de modèle représentant la ligne supprimée.
+
+## Exemple delete
+
+```js
+const User = require("user");
+
+await User.delete({
+  email: my@gmail.com
+})
+```
+
+## Fonction dropTable
+
+Supprime de manière asynchrone une table si elle existe dans la base de données.
+
+Cette fonction construit une requête SQL pour supprimer la table dont le nom est spécifié par la propriété `this.name`. Elle exécute ensuite la requête en utilisant une approche basée sur les promesses.
+Si la requête aboutit, le résultat est consigné dans la console.
+
+En cas d'erreur lors de l'exécution de la requête, un message d'erreur est consigné.
+
+- **Returns** `Promise<void>` Une promesse qui se résout une fois l'exécution de la requête terminée.
+
+## Example dropTable
+
+```js
+const User = require("user");
+
+await User.dropTable();
+```
+
+## generate_uuid function
+
+Génère un UUID unique pour le modèle actuel.
+
+Cette fonction génère un UUID à l'aide de la fonction `UUID()` de SQL_request et vérifie si cet UUID existe déjà dans la base de données pour le modèle actuel. Si l'UUID est unique, il est renvoyé.
+
+Sinon, la fonction renvoie `null`.
+
+- **Parameters** `string` var_uuid Par defaut il vaut uuid
+- **Returns** `Promise<string|null>` Une promesse qui se résout en une chaîne UUID unique en cas de succès, ou en `null` si une erreur survient ou si l'UUID n'est pas unique.
+- **Throws** `Error` S'il y a une erreur lors de l'exécution de la requête SQL_request.
+
+## Example generate_uuid
+
+```js
+const User = require("user");
+
+const uuid = await User.generate_uuid();
+const my_uuid = await User.generate_uuid("my_uuid");
+
+await User.save{ email: "user@example.com", status: "active", uuid: uuid, my_uuid: my_uuid }
 ```
 
 ## Instances de modèle
@@ -155,4 +335,4 @@ module.exports = client => {
 
 ## Résumé
 
-sql-connector fournit une couche simple pour connecter une base MySQL, décrire des schémas, synchroniser les tables et manipuler les données avec des modèles typés.
+sql-connector fournit une couche simple pour connecter une base MySQL, décrire des schémas, synchroniser les tables et manipuler les données avec des modèles typés.

package/eslint.config.mjs

@@ -0,0 +1,12 @@
+import security from "eslint-plugin-security";
+
+export default [
+  {
+    plugins: {
+      security
+    },
+    rules: {
+      ...security.configs.recommended.rules
+    }
+  }
+];

package/index.d.ts

@@ -95,10 +95,10 @@ export class Model {
     schema: Schema;
     constructor(name: string, schema: Schema);
     /**
-     * Crée toutes les tables dans l'ordre correct en fonction des foreign keys.
+     * Creates all tables in the correct order based on foreign keys.
      * @returns {Promise<void>}
      */
-    static syncAllTables({ dangerousSync = false } = {}): Promise<void>;
+    static syncAllTables(): Promise<void>;
     /**
      * Saves data to the database table.
      * @param {Object} data The data to insert into the table.
@@ -107,50 +107,20 @@ export class Model {
      */
     save(data: Record<string, any>): Promise<any>;
     /**
-     * Récupère plusieurs entrées de la table.
-     * @param {Object} [options] - Options de requête (attributs, where, order, limit).
-     * @param {string[]} [options.attributes] - Champs à retourner.
-     * @param {Object} [options.where] - Filtres (clé/valeur).
-     * @param {Array} [options.order] - Ex: [['points', 'DESC']]
-     * @param {number} [options.limit] - Limite de résultats.
+     * Retrieves multiple rows from the table.
+     * @param {Object} [options] - Query options (attributes, where, order, limit).
+     * @param {string[]} [options.select] - Fields to return.
+     * @param {Object} [options.where] - Filters (key/value).
+     * @param {Array} [options.order] - Example: [['points', 'DESC']]
+     * @param {number} [options.limit] - Result limit.
      * @returns {Promise<Array<Object>>}
      */
-    findAll(options?: {
-        attributes?: string[];
+    static find(options?: {
+        select?: string[];
         where?: Record<string, any>;
         order?: [string, string][];
         limit?: number;
     }): Promise<any[]>;
-    /**
-     * Finds a unique entry in the database table based on the filter provided.
-     * @param {Object} filter An object containing the key-value pairs to use to generate the search condition.
-     * @param {string[]} [fields=["*"]] An array of field names to return in the result.
-     * @returns {Promise<ModelInstance|number>} A promise that resolves to a ModelInstance if an entry is found, otherwise 0.
-     */
-    findOne(filter: Record<string, any>, fields?: string[]): Promise<ModelInstance | number>;
-    /**
-     * Finds a record in the database based on the provided filter.
-     *
-     * @async
-     * @param {Object} filter - The filter criteria for the query. Should be an object where keys are column names and values are the values to filter by.
-     * @param {Array<string>} [fields=["*"]] - The fields to select in the query. Defaults to selecting all fields.
-     * @returns {Promise<ModelInstance|number>} - A promise that resolves to a `ModelInstance` if a record is found, or `0` if no records match the filter.
-     *
-     * @example
-     * // Example usage:
-     * const filter = { id: 1 };
-     * const fields = ["id", "name"];
-     * MyTable.find(filter, fields).then((result) => {
-     *     if (result === 0) {
-     *         console.log("No records found.");
-     *     } else {
-     *         console.log("Record found:", result);
-     *     }
-     * }).catch((err) => {
-     *     console.error("Error:", err);
-     * });
-     */
-    find(filter: Record<string, any>, fields?: string[]): Promise<ModelInstance | number>;
     /**
      * 
      * @param {Object} filter The filter criteria for the query. Should be an object where keys are column names and values are the values to filter by.
@@ -165,14 +135,14 @@ export class Model {
      */
     customRequest(custom: string): Promise<any>;
     /**
-     * Supprime une entrée de la table SQL correspondant au filtre fourni.
+     * Deletes a record from the SQL table corresponding to the provided filter.
      *
      * @async
      * @function delete
-     * @param {Object} filter - Un objet représentant les conditions de filtre pour la suppression.
-     * @returns {Promise<number>} Une promesse qui se résout à 0 si aucune ligne n'a été supprimée,
-     * ou à une instance de ModelInstance représentant la ligne supprimée.
-     * @throws {Error} Lance une erreur si la requête SQL échoue.
+     * @param {Object} filter - An object representing the filter conditions for the deletion.
+     * @returns {Promise<number>} A promise that resolves to 0 if no rows were deleted,
+     * or an instance of ModelInstance representing the deleted row.
+     * @throws {Error} Throws an error if the SQL query fails.
      */
     delete(filter: Record<string, any>): Promise<number | ModelInstance>;
     /**

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@mlagie/sql-connector",
-  "version": "1.4.9",
+  "version": "2.0.0",
   "description": "Le module sql-connector permet de gérer les connexions à une base de données MySQL, de définir des schémas de tables, et d'interagir avec les données de manière simple et efficace.",
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "security": "npx eslint . --max-warnings 0"
   },
   "repository": {
     "type": "git",
@@ -37,6 +37,10 @@
   "dependencies": {
     "@mlagie/logger": "1.0.2",
     "glob": "^13.0.6",
-    "mysql2": "3.22.4"
+    "mysql2": "3.22.5"
+  },
+  "devDependencies": {
+    "eslint": "^10.6.0",
+    "eslint-plugin-security": "^4.0.1"
   }
 }

package/releases/1.5.0.md

@@ -0,0 +1,127 @@
+# **Release v1.5 — sql-connector**
+
+## Overview
+
+This release introduces a major improvement to the query system in sql-connector, focusing on flexibility, performance, and developer experience.
+
+The new version simplifies query building, adds support for advanced SQL features (such as aggregation and date formatting), and improves consistency across model operations.
+
+---
+
+## New Features
+
+### Enhanced Query Builder (findAll)
+
+- findAll() now supports advanced SQL features through a clean and extensible configuration object.
+- Developers can build complex queries without writing raw SQL.
+
+Supported features:
+
+- SUM, DATE_FORMAT, and custom field transformations
+- GROUP BY, ORDER BY, HAVING, and LIMIT
+- Multiple aggregations in a single query
+
+Example:
+
+```js
+Model.findAll({
+  select: [
+    { dateFormat: ['date_day', '%Y-%m'], as: 'period' },
+    { sum: 'error' },
+    { sum: 'reload' },
+  ],
+  groupBy: ['period'],
+  orderBy: [{ field: 'period', direction: 'ASC' }]
+});
+```
+
+---
+
+### Dynamic Field Builder
+
+- Query fields are now processed individually through a modular builder.
+- Enables combining multiple transformations (e.g., multiple SUM, DATE_FORMAT) without hardcoding specific cases.
+- Improves extensibility for future SQL functions (AVG, COUNT, etc.).
+
+---
+
+### Simplified Query Construction
+
+- Query generation now follows a fixed SQL order (WHERE → GROUP BY → HAVING → ORDER BY → LIMIT) without unnecessary sorting.
+- Improves performance and avoids overhead from dynamic reordering.
+- Keeps the implementation simple and predictable.
+
+---
+
+### Improved Aggregation Support
+
+- Designed for analytics use cases:
+  - Time-based grouping (day, month, year)
+  - Multi-metric aggregation
+  - Clean integration with frontend dashboards
+
+---
+
+### Better Developer Experience
+
+- No need to write raw SQL for common queries
+- Clear and readable query configuration
+- Consistent API across simple and advanced queries
+
+---
+
+## Improvements
+
+### customRequest function
+
+- customRequest provides all the information instead of taking the first element of the request.
+
+### Model Usage
+
+- findAll() is now instance-based instead of static for better flexibility and dependency injection.
+- Enables multiple database connections and improved testability.
+
+---
+
+### Performance Optimization
+
+- Removed unnecessary iteration and sorting logic in query building.
+- Query generation now runs in constant time structure (no scaling overhead with new features).
+
+---
+
+### Code Maintainability
+
+- Cleaner separation between:
+  - field building
+  - query parts
+  - execution
+
+- Easier to extend without modifying core logic.
+
+## Migration from v1.4.x
+
+### Main changes
+
+1. Switch to instance-based model usage
+2. Update findAll calls to use the new select format
+3. Adapt queries using aggregation to the new field builder system
+
+### Recommendation
+
+- Replace raw SQL queries with the new findAll configuration when possible
+- Review existing analytics queries to leverage built-in aggregation support
+
+## Documentation
+
+See the updated documentation in:
+
+- [README.md](../README.md)
+
+## Useful Links
+
+- GitHub Repository: <https://github.com/lagie-marin/sql-connector>
+
+- npm Package: <https://www.npmjs.com/package/@mlagie/sql-connector>
+
+- Issues: <https://github.com/lagie-marin/sql-connector/issues>

package/releases/2.0.0.md

@@ -0,0 +1,32 @@
+# **Release v2.0.0 — Security Hardening & Prototype Pollution Prevention**
+
+This release focuses heavily on `security improvements` across the ORM's core model management and data access layers. We have successfully mitigated potential security vulnerabilities regarding dynamic property access and file path operations, satisfying `eslint-plugin-security` analysis.
+
+## **Key Changes & Security Fixes**
+
+### **1. Prototype Pollution & Object Injection Prevention**
+
+- **Problem**: Using dynamic bracket notations like obj[key] where key originates from user inputs or database schemas exposed the application to **Object Injection** and **Prototype Pollution** (allowing attackers to alter critical global properties via keys like `__proto__` or `constructor`).
+
+- **Fix**: Introduced a centralized `safe.js` security utility leveraging `Reflect.get()` and `Reflect.set()` coupled with a strict property blacklist (`__proto__`, `constructor`, `prototype`).
+  - Migrated all dynamic model lookups and topological sorting dictionaries in `Model.js` to safe wrappers.
+  - Secured dynamic getters and setters mapped to data columns in `ModelInstance.js`.
+
+### **2. Path Traversal & Safe Database Backups**
+
+- **Problem**: Dynamically naming automated backup files (**.sql**) based on database table names without validation triggered `detect-non-literal-fs-filename` warnings, opening up potential `Path Traversal` vector concerns.
+
+- **Fix**: Implemented string sanitization via regex (`/[^a-zA-Z0-9_]/g`) on table-driven variables prior to passing arguments to standard `fs` sync methods (`writeFileSync`, `readFileSync`, `unlinkSync`, `renameSync`).
+  - Fully resolved all local `fs` filename security alerts.
+
+### **3. General Code Refactoring**
+
+- Replaced native object literals `{}` with prototype-less structures `(Object.create(null))` for configuration mappings and dependency graph resolution arrays to prevent unexpected inheritance bugs.
+
+## **Component Impact**
+
+|             File              |                             Changes Made                          |                         Warning Cleared                     |
+|-------------------------------|-------------------------------------------------------------------|-------------------------------------------------------------|
+| `src/utils/security/safe.js`  | Created utility with `Reflect` API + validation blacklist         | None (Fully clean)                                          |
+| `src/models/Model.js`         | Patched `syncAllTables`, topological sort, and `fs` operations    | `detect-object-injection`, `detect-non-literal-fs-filename` |
+| `src/models/ModelInstance.js` | Secured active schema columns maps inside constructor proxies     | `detect-object-injection`                                   |