@mlagie/sql-connector 2.0.5 → 2.0.7

package/.github/workflows/publish.yml

@@ -1,6 +1,7 @@
 name: Publish Package
 
 on:
+  workflow_dispatch:
   release:
     types: [published]
   push:
@@ -9,7 +10,6 @@ on:
   pull_request:
     branches:
       - main
-  workflow_dispatch:
 jobs:
   check_security:
     runs-on: ubuntu-latest
@@ -33,38 +33,48 @@ jobs:
   integrity:
     runs-on: ubuntu-latest
     steps:
-    - name: Checkout GH repository
-      uses: actions/checkout@v6
-    - name: setup node
-      uses: actions/setup-node@v6
-      with:
-        node-version: 22
-    - name: Install deps
-      run: npm ci
-    - name: Run integrity check
-      continue-on-error: false
-      run: |
-        npm run test
+      - name: Checkout GH repository
+        uses: actions/checkout@v6
+      - name: setup node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - name: Install deps
+        run: npm ci
+      - name: Run integrity check
+        continue-on-error: false
+        run: |
+          npm run test
   publish:
-    needs: 
+    needs:
       - check_security
       - integrity
-    if: github.event_name == 'release' || github.ref_name == 'main'
+    if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
     runs-on: ubuntu-latest
     environment: sqlc
     permissions:
       contents: read
-      id-token: write
+      id-token: write # Requis pour la provenance (--provenance)
 
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-node@v6
+      # 1. Récupérer le code source
+      - name: Checkout du code
+        uses: actions/checkout@v6
+
+      # 2. Configurer Node.js pour registry.npmjs.org
+      - name: Configurer Node.js
+        uses: actions/setup-node@v6
         with:
-          node-version: 22
-          registry-url: https://registry.npmjs.org
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org/" # <-- Cible npmjs
           scope: "@mlagie"
-      - name: Update npm and Publish
-        run: |
-          npm install -g npm@latest
-          npm ci
-          npm publish --provenance --access public
+
+      # 3. Installer les dépendances
+      - name: Installer les dépendances
+        run: npm ci
+
+      # 4. Publier sur le vrai registre npm
+      - name: Publier sur npmjs.com
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/README.md

@@ -184,23 +184,51 @@ async function createUser(email, stat) {
 
 Retrieves entries from the table.
 
-- **Parameters** `options` *(Object)* - Query options
-- **Parameters** `options.select` *(string[])* - Fields to be returned.
-- **Parameters** `options.where` *(Object)* - Filters (key/value).
-- **Parameters** `options.order` *(Array)* - Ex: [['points', 'DESC']]
-- **Parameters** `options.limit` *(number)* - Limit of results.
+- **Parameters** `options` *(Object)* - Query options.
+- **Parameters** `options.select` *(Array<string|SelectAggregation>)* - Fields, aggregations, or transformations to be returned.
+- **Parameters** `options.where` *(Object / string)* - Filtering conditions (key/value object or raw string condition).
+- **Parameters** `options.groupBy` *(string[])* - Fields used to group results.
+- **Parameters** `options.orderBy` *(Array<string|OrderByOption>)* - Sorting rules.
+- **Parameters** `options.join` *(JoinOption / JoinOption[])* - Table join configuration structures.
+- **Parameters** `options.limit` *(number)* - Maximum number of results to return.
 - **Returns** `Promise<Array<ModelInstance>>`
 
-### find Options
+### Advanced `select` Options (`SelectAggregation`)
 
-| Option     | Type            | Description                                              | Example                                      |
-|------------|-----------------|----------------------------------------------------------|----------------------------------------------|
-| `select`   | Array           | Fields or transformations to retrieve                    | `['date_day']`                               |
-| `where`    | Object / String | Filtering conditions                                     | `{ project_id: 1 }`                          |
-| `groupBy`  | Array           | Fields used to group results                             | `['period']`                                 |
-| `orderBy`  | Array           | Sorting rules                                            | `[{ field: 'date_day', direction: 'DESC' }]` |
-| `having`   | String          | HAVING clause for aggregated queries                     | `'SUM(total_runs) > 100'`                    |
-| `limit`    | Number          | Limits the number of results                             | `100`                                        |
+Each element in the `select` array can be either a standard string (raw column name) or an object providing advanced SQL capabilities and aggregations:
+
+| Property inside `select` object | Type              | Description                                                                                          |                                  Example / Generated SQL                                           |
+|---------------------------------|-------------------|------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
+| `col`                           | `string`          | Selects a plain, unaggregated table column.                                                          | `{ col: 'email' }` $\rightarrow$ \`email\`                                                         |
+| `sum`                           | `string`          | Computes the sum of all numerical values in a column.                                                | `{ sum: 'error' }` $\rightarrow$ `SUM(` \`error\``)`                                               |
+| `distinct`                      | `string`          | Applies a DISTINCT constraint on the specified column.                                               | `{ distinct: 'status' }` $\rightarrow$ `DISTINCT` \`status\`                                       |
+| `dateFormat`                    | `[string, string]`| Formats a Date column using standard MySQL formatting (Format: `[column, mysql_format_string]`).     | `{ dateFormat: ['created_at', '%Y-%m'] }` $\rightarrow$ `DATE_FORMAT(` \`created_at\``, '%Y-%m')`  |
+| `count`                         | `string`          | Standard row counting (ignores `NULL` values).                                                       | `{ count: 'id' }` $\rightarrow$ `COUNT(` \`id\``)`                                                 |
+| `count` (Array)                 | `string[]`        | Counts unique combinations across multiple columns (COUNT DISTINCT).                                 | `{ count: ['team', 'source'] }` $\rightarrow$ `COUNT( DISTINCT` \`team\``,` \`source\``)`          |
+| `count` (Object)                | `Object`          | Automated conditional aggregation (`CASE WHEN`). Perfect for KPIs and status metrics.                | `{ count: { deletedAt: null } }` $\rightarrow$ `COUNT(CASE WHEN` \`deletedAt\``= NULL THEN 1 END)` |
+| `as`                            | `string`          | Sets a custom output identifier or aggregation alias (SQL `AS`).                                     | `{ count: 'id', as: 'total' }` $\rightarrow$ `COUNT(` \`id\``) AS` \`total\`                       |
+
+---
+
+### Complex Structured Options (`orderBy` & `join`)
+
+#### OrderByOption
+
+Enables explicit sorting across one or multiple columns:
+
+- **field** `(string)`: The target column name to apply sorting on.
+- **direction** `('ASC'\|'DESC')`: The sorting direction (Defaults to `'ASC'`).
+
+#### JoinOption
+
+Specifies one or multiple relational database table joins:
+
+- **table** `(string)`: Target table name to join with.
+- **on** `(string)`: Relational equation statement string (e.g., `"ProjectPipelines.project_id = Projects.id"`).
+- **alias** `(string)` *(Optional)*: An alternative SQL alias name for the joined table.
+- **type** `('INNER'\|'LEFT'\|'RIGHT')` *(Optional)*: SQL join modality (Defaults to `'INNER'`).
+
+---
 
 ## Example find
 
@@ -232,6 +260,71 @@ User.find({
 })
 ```
 
+### Advanced Examples using `find`
+
+#### 1. Standard, Distinct, and Multi-Column Counting
+
+Count global rows alongside multi-column unique combinations, such as identifying unique team and source pipelines:
+
+```js
+const { MyTable } = require("./models");
+
+const stats = await MyTable.find({
+  select: [
+    { count: 'id', as: 'total_pipelines' },
+    { count: ['cteam', 'csource'], as: 'unique_groups' } // Multi-column COUNT DISTINCT
+  ],
+  where: { csource: 'web' }
+});
+```
+
+#### 2. Conditional Aggregations (Active / Decommissioned KPI Metrics)
+
+By passing an object to the `count` attribute, the ORM automatically structures a conditional `CASE WHEN` clause. This allows you to split different status counters into a single database trip:
+
+```js
+const { MyTable } = require("./models");
+
+const ppiStats = await MyTable.find({
+  select: [
+    { count: { deletedAt: null }, as: 'active' },          // Counts where deletedAt = NULL
+    { count: { status: 'SUCCESS' }, as: 'total_success' }   // Counts where status = 'SUCCESS'
+  ],
+  where: {
+    source: 'jenkins',
+    team: 'GROUP-1'
+  }
+});
+```
+
+#### 3. Table Joins, Time Series Grouping, and Multi-Column Sorting
+
+An advanced query orchestration combining left table joining, date formatting conversions, and sorting:
+
+```js
+const { MyTable } = require("./models");
+
+const history = await MyTable.find({
+  select: [
+    { col: 'Projects.name', as: 'project_name' },
+    { dateFormat: ['ProjectPipelines.created_at', '%Y-%m'], as: 'period' },
+    { count: 'ProjectPipelines.id', as: 'pipelines_count' }
+  ],
+  where: "ProjectPipelines.deletedAt IS NULL", // Raw condition strings are permitted
+  join: {
+    table: 'Projects',
+    on: 'ProjectPipelines.project_id = Projects.id',
+    type: 'LEFT'
+  },
+  groupBy: ['project_name', 'period'],
+  orderBy: [
+    { field: 'period', direction: 'DESC' },
+    { field: 'project_name', direction: 'ASC' }
+  ],
+  limit: 50
+});
+```
+
 ## count function
 
 Counts the number of records matching the given filter.

package/docs/fr/README.md

@@ -147,25 +147,53 @@ async function createUser(email, 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`                                        |
+Récupère des enregistrements de la table.
+
+- **Paramètres** `options` *(Object)* – Options de la requête.
+- **Paramètres** `options.select` *(Array<string|SelectAggregation>)* – Champs, agrégations ou transformations à retourner.
+- **Paramètres** `options.where` *(Object / string)* – Conditions de filtrage (objet clé/valeur ou clause brute sous forme de chaîne).
+- **Paramètres** `options.groupBy` *(string[])* – Champs utilisés pour grouper les résultats.
+- **Paramètres** `options.orderBy` *(Array<string|OrderByOption>)* – Règles de tri.
+- **Paramètres** `options.join` *(JoinOption / JoinOption[])* – Structures de configuration pour les jointures de tables.
+- **Paramètres** `options.limit` *(number)* – Nombre maximal de résultats à retourner.
+- **Retourne** `Promise<Array<ModelInstance>>`
+
+### Options avancées de `select` (`SelectAggregation`)
+
+Chaque élément du tableau `select` peut être soit une chaîne de caractères standard (nom brut de la colonne), soit un objet offrant des fonctionnalités SQL et des agrégations avancées :
+
+| Propriété dans l'objet `select` | Type              | Description                                                                                               |                                     Exemple / SQL Généré                                            |
+|---------------------------------|-------------------|-----------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
+| `col`                           | `string`          | Sélectionne une colonne de table simple, sans agrégation.                                                 | `{ col: 'email' }` $\rightarrow$ \`email\`                                                          |
+| `sum`                           | `string`          | Calcule la somme de toutes les valeurs numériques d'une colonne.                                          | `{ sum: 'error' }` $\rightarrow$ `SUM(`\`error\``)`                                                 |
+| `distinct`                      | `string`          | Applique une contrainte DISTINCT sur la colonne spécifiée.                                                | `{ distinct: 'status' }` $\rightarrow$ `DISTINCT `\`status\`                                        |
+| `dateFormat`                    | `[string, string]`| Formate une colonne de type Date en utilisant le formatage standard MySQL (`[colonne, chaine_de_format]`).| `{ dateFormat: ['created_at', '%Y-%m'] }` $\rightarrow$ `DATE_FORMAT(`\`created_at\``, '%Y-%m')`    |
+| `count`                         | `string`          | Comptage de lignes standard (ignore les valeurs `NULL`).                                                  | `{ count: 'id' }` $\rightarrow$ `COUNT(`\`id\``)`                                                   |
+| `count` (Array)                 | `string[]`        | Calcule le nombre de combinaisons uniques sur plusieurs colonnes (COUNT DISTINCT).                        | `{ count: ['team', 'source'] }` $\rightarrow$ `COUNT( DISTINCT `\`team\``, `\`source\`` )`          |
+| `count` (Object)                | `Object`          | Agrégation conditionnelle automatisée (`CASE WHEN`). Idéal pour les indicateurs clés (KPIs) et statuts.   | `{ count: { deletedAt: null } }` $\rightarrow$ `COUNT(CASE WHEN `\`deletedAt\`` = NULL THEN 1 END)` |
+| `as`                            | `string`          | Définit un identifiant de sortie personnalisé ou un alias d'agrégation (SQL `AS`).                        | `{ count: 'id', as: 'total' }` $\rightarrow$ `COUNT(`\`id\``) AS `\`total\`                         |
+
+---
+
+### Options complexes structurées (`orderBy` & `join`)
+
+#### OrderByOption
+
+Permet d'appliquer un tri explicite sur une ou plusieurs colonnes :
+
+- **field** `(string)` : Le nom de la colonne cible sur laquelle appliquer le tri.
+- **direction** `('ASC'\|'DESC')` : Le sens du tri (Par défaut : `'ASC'`).
+
+#### JoinOption
+
+Spécifie une ou plusieurs jointures de tables relationnelles :
+
+- **table** `(string)` : Nom de la table cible à joindre.
+- **on** `(string)` : Chaîne de caractères représentant la condition de jointure (ex: `"MyTable.project_id = Projects.id"`).
+- **alias** `(string)` *(Optionnel)* : Un alias SQL alternatif pour la table jointe.
+- **type** `('INNER'\|'LEFT'\|'RIGHT')` *(Optionnel)* : Type de jointure SQL (Par défaut : `'INNER'`).
+
+---
 
 ## Exemple find
 
@@ -197,6 +225,73 @@ await User.find({
 })
 ```
 
+### Exemples avancés avec `find`
+
+#### 1. Comptage standard, distinct et multi-colonnes
+
+Comptez les lignes globales parallèlement à des combinaisons uniques multi-colonnes, comme l'identification des couples uniques d'équipes et de sources de pipelines :
+
+```js
+const { MyTable } = require("./models");
+
+const stats = await MyTable.find({
+  select: [
+    { count: 'id', as: 'total_pipelines' },
+    { count: ['cteam', 'csource'], as: 'unique_groups' } // COUNT DISTINCT multi-colonnes
+  ],
+  where: { csource: 'web' }
+});
+```
+
+#### 2. Agrégations conditionnelles (Indicateurs KPIs Actifs / Inactifs)
+
+En passant un objet à l'attribut count, l'ORM structure automatiquement une clause conditionnelle CASE WHEN. Cela vous permet de ventiler différents compteurs de statuts en une seule et unique requête vers la base de données :
+
+```js
+const { ProjectPipeline } = require("./models");
+
+const ppiStats = await ProjectPipeline.find({
+  select: [
+    { count: { deletedAt: null }, as: 'active' },          // Compte les lignes où deletedAt = NULL
+    { count: { status: 'SUCCESS' }, as: 'total_success' }   // Compte les lignes où status = 'SUCCESS'
+  ],
+  where: {
+    source: 'jenkins',
+    team: 'GROUP-1'
+  }
+});
+
+// Format du tableau de sortie retourné : [{ active: 6, total_success: 42 }]
+```
+
+#### 3. Jointures de tables, groupement temporel et tri multi-colonnes
+
+Une orchestration de requête avancée combinant une jointure gauche (LEFT JOIN), des conversions de formats de date et des tris :
+
+```js
+const { ProjectPipeline } = require("./models");
+
+const history = await ProjectPipeline.find({
+  select: [
+    { col: 'Projects.name', as: 'project_name' },
+    { dateFormat: ['MyTable.created_at', '%Y-%m'], as: 'period' },
+    { count: 'MyTable.id', as: 'pipelines_count' }
+  ],
+  where: "MyTable.deletedAt IS NULL", // Les chaînes de conditions brutes sont autorisées
+  join: {
+    table: 'Projects',
+    on: 'MyTable.project_id = Projects.id',
+    type: 'LEFT'
+  },
+  groupBy: ['project_name', 'period'],
+  orderBy: [
+    { field: 'period', direction: 'DESC' },
+    { field: 'project_name', direction: 'ASC' }
+  ],
+  limit: 50
+});
+```
+
 ## Fonction count
 
 Compte le nombre d'enregistrements correspondant au filtre donné.

package/package.json

@@ -1,18 +1,23 @@
 {
   "name": "@mlagie/sql-connector",
-  "version": "2.0.5",
+  "version": "2.0.7",
   "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": "node --experimental-vm-modules node_modules/jest/bin/jest.js --runInBand",
+    "test": "rm -r coverage ; node --experimental-vm-modules node_modules/jest/bin/jest.js --runInBand",
+    "test:publish": "npm publish --dry-run",
     "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch",
-    "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
+    "test:coverage": "rm -r coverage ; node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
     "security": "npx eslint . --max-warnings 0 --ignore-pattern './tests/*'"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/lagie-marin/sql-connector.git"
   },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
   "keywords": [
     "sql",
     "schema",

package/releases/2.0.6.md

@@ -0,0 +1,80 @@
+# Release v2.0.6 — Architectural Property Isolation, Query Defusal & Test Coverage Expansion
+
+This emergency structural release addresses a critical data-shadowing bug within the `ModelInstance` hydration cycle where active database column values (e.g., fields named `name`, `schema`, or `data`) overrode the core internal engine structures, mangling runtime query generation. It also introduces a comprehensive overhaul of the test suite to secure maximum coverage.
+
+## 🛠️ The Bug Defusal (Why this was critical)
+
+When `ModelInstance` mapped rows dynamically into getters/setters, a column named `name` from the database would mask `this.name` (the structural reference to the SQL Table Name).
+
+As a result, an injection or ingestion update would mistakenly compile syntax failures like:
+
+```sql
+UPDATE my_value SET `deletedAt` = ... -- Mangled: Used row data instead of Table Name
+```
+
+By migrating all runtime configuration tokens to protected underscored properties (`_tableName`, `_data`, `_schema`), the instance context is now completely hermetic against database row schema payloads.
+
+## Massive Test Coverage Expansion
+
+To ensure the stability and robustness of this release, the unit test suites for both `Model` and `ModelInstance` have been significantly hardened:
+
+- **Edge-Case & Fallback Testing**: Added specialized tests to force controlled failures in deep `try/catch` blocks, guaranteeing that the global engine fallback workflows function flawlessly under corrupted data scenarios.
+
+- **SQL Mechanics Validation**: Built targeted unit tests covering schema dictionary mismatches, complex conditional mapping (e.g., table joins filtering mixed array types), and secondary logic paths inside `updateOne()`, `delete()`, and `deleteOne()`.
+
+- `Database Simulation Coverage`: Implemented strict simulation sequences verifying UUID collision rejections (ensuring `generate_uuid()` handles duplicates properly) and missing response payloads (such as undefined `affectedRows`).
+
+- `Zero-Crash Guarantees`: Hardened utility methods like `getFieldType()` against historical JavaScript edge cases (such as parsing `null` values safely).
+
+## What Was Improved
+
+- `Protected Context Isolation`: Migrated core metadata targets in `ModelInstance.js` to `_tableName`, `_data`, and `_schema`. Database columns can no longer shadow engine properties.
+
+- `Tiret/Hyphen Database Safety`: Wrapped table calls explicitly in SQL backticks (\`) inside `updateOne`, `delete`, and `deleteOne` routines. Tables named with hyphens (like my_value) no longer trigger syntax violations.
+
+- **Rehydration Mapping Consistency**: Standardized downstream sub-instantiations (like `customRequest`) to feed data strictly using the isolated `_tableName` descriptor.
+
+## File Blueprint Updates
+
+`ModelInstance.js`
+
+The updated architecture encapsulates the internal core parameters like this:
+
+```js
+class ModelInstance {
+    constructor(name, data, schema = null) {
+        Object.defineProperties(this, {
+            _tableName: { // 🔒 Fully protected from row data collisions
+                value: name,
+                writable: true,
+                configurable: true,
+                enumerable: false
+            },
+            _data: {
+                value: data,
+                writable: true,
+                configurable: true,
+                enumerable: true
+            },
+            _schema: {
+                value: schema,
+                writable: true,
+                configurable: true,
+                enumerable: false
+            }
+        });
+        
+        // Dynamic row mapping safely bound without property leakage...
+    }
+
+    async updateOne(model) {
+        const setClause = generateCondition(formatObject(model), true);
+        let whereClause = /* ... evaluation matrix using this._schema & this.getRecordData() ... */;
+
+        // Encapsulated Table execution with explicit backticks
+        const sql_request = `UPDATE \`${this._tableName}\` SET ${setClause} WHERE ${whereClause}`;
+        
+        // ... execute transaction safely
+    }
+}
+```

package/releases/2.0.7.md

@@ -0,0 +1,38 @@
+# Release v2.0.7 — COUNT Polymorphism, Aggregation Alias Security & Test Coverage Overhaul
+
+This major release upgrades the query engine by introducing full polymorphic support for the `COUNT` aggregation function (supporting standard, multi-column distinct, and conditional `CASE WHEN` operations). It also fixes a key-aliasing limitation during raw aggregations and strengthens query-building validation boundaries through an extensive unit testing overhaul.
+
+## COUNT Polymorphism (Why this evolution matters)
+
+Previously, the query engine only accepted a raw string parameter for `COUNT` instructions. The engine now dynamically evaluates three distinct structures (String, Array, Object) passed directly from your selection attributes:
+
+- **Multi-Column Distinct Counting**: Passing an array automatically compiles a unified multi-column unique combination statement, removing the need for manual raw SQL workarounds.
+
+- **Conditional Counting (`CASE WHEN`)**: Passing a key/value object cleanly compiles a conditional statement. This allows you to isolate state and status indicators (KPIs) in a single database round-trip without twisting your global query filters.
+
+As a result, complex nullity checks or status distributions are generated natively:
+
+```js
+-- Automated nullity indicator compilation example:
+COUNT(CASE WHEN `deletedAt` = NULL THEN 1 END)
+```
+
+## Test Coverage Expansion
+
+To guarantee the stability of these new mechanics and prevent structural regressions, the global unit testing footprint has been exhaustively expanded:
+
+- **Multi-Count Validation**: Added dedicated test pipelines ensuring the syntax of `COUNT(DISTINCT column1, column2)` is perfectly isolated from standard counters.
+
+- **Temporal Nullity Filtering**: Implemented test scenarios covering both `{ deletedAt: null }` and `{ deletedAt: "NOT NULL" }` parameters to verify string state evaluations.
+
+- **Unsupported Input Interception**: Added strict `throw new Error` type boundaries to guarantee that injecting non-compliant values (like booleans or numbers) results in a clean, controlled application crash.
+
+- **Zero-Leak Key Assurances**: Added strict payload assertions ensuring no raw unmapped backticked SQL expressions can escape into the final Node.js JSON output object.
+
+## What Was Improved
+
+- **Automatic Aggregation Fallback Alias**: Enhanced the `buildField` logic inside `buildQuery.js`. If an explicit `as` descriptor is omitted during a column sum (sum), the engine automatically fallbacks to using the targeted column name as the extraction property, blocking raw SQL formula leaks into the final row keys.
+
+- **Orchestrated Order Sorting**: Hardened the `options.orderBy` evaluator array loop to cleanly isolate and support both raw column identifier strings and structured sorting configuration objects `{ field, direction }`.
+
+Documentation Cleanup: Fully aligned the core developer usage guide and documentation files within `README.md` to reflect the updated parameter boundaries and capabilities.

package/socket.yml

@@ -0,0 +1,4 @@
+version: 2
+project:
+  # Masquer les alertes des outils de dev/test dans le rapport
+  ignoreDevDependencies: true

package/src/models/Model.js

@@ -4,8 +4,7 @@ const { getConnexion } = require("../db/connexion");
 const generateCondition = require("../utils/generateCondition");
 const formatObject = require("../utils/formatObject");
 const { ModelInstance } = require("./ModelInstance");
-const { buildSelect, buildQueryParts } = require("../utils/buildQuery");
-const util = require("util");
+const { buildSelect, buildQueryParts } = require("../utils/buildQuery/buildQuery");
 const { getSafe, setSafe } = require("../utils/security/safe");
 const { escapeIdentifier, escapeIdentifierList } = require("../utils/sql");
 
@@ -14,10 +13,8 @@ function getFieldType(field) {
         if (field.type && field.type.name !== undefined) return field.type.name;
         else if (field.type !== undefined) return field.type;
         return undefined;
-    } else {
-        if (field && field.name !== undefined) return field.name;
-        else return field;
     }
+    if (field && field.name !== undefined) return field.name;
 }
 
 function isDateLikeType(fieldType) {
@@ -99,7 +96,7 @@ function getColumnDefinition(fieldName, field) {
     if (defaultDefinition !== null) colDef += ` ${defaultDefinition}`;
     if (field.unique) colDef += ' UNIQUE';
     if (field.auto_increment) colDef += ' AUTO_INCREMENT';
-    if (field.primary_key) colDef += ' PRIMARY KEY';
+    if (field.primary_key) colDef += ' PRIMARY KEY'
     if (typeof field.customize === 'string' && field.customize.length != 0) colDef += ` ${field.customize}`;
     return `${escapeIdentifier(fieldName)} ${colDef}`;
 }
@@ -213,18 +210,6 @@ class Model {
         return `CREATE TABLE IF NOT EXISTS ${escapeIdentifier(this.name)} (${columns.join(', ')}${foreignKey.length > 0 ? ", " + foreignKey.join(', ') : ""}) ENGINE=InnoDB`;
     }
 
-    getRecordData() {
-        return Array.isArray(this.data) ? this.data[0] ?? this.data : this.data;
-    }
-
-    toJSON() {
-        return this.getRecordData()?.data;
-    }
-
-    [util.inspect.custom]() {
-        return this.getRecordData();
-    }
-
     /**
      * Saves data to the database table.
      * @param {Object} data The data to insert into the table.
@@ -246,23 +231,40 @@ class Model {
 
     /**
      * @typedef {Object} SelectAggregation
-     * @property {string} [sum] - The name of the column to sum (e.g., "total_runs").
-     * @property {string} [count] - The name of the column to count.
-     * @property {string[]} [dateFormat] - Array with [column, format] (e.g., ["date_day", "%Y-%m-%d"]).
-     * @property {string} as - The output alias for the SQL field (e.g., "total_runs" or "period").
+     * @property {string} [col] - Le nom brut de la colonne à récupérer sans agrégation.
+     * @property {string} [sum] - Le nom de la colonne à additionner (ex: "total_runs").
+     * @property {string} [distinct] - Applique le mot-clé DISTINCT sur la colonne spécifiée.
+     * @property {string | string[] | Object} [count] - Compte les lignes selon le format fourni :
+     * - `string`: Compte toutes les valeurs non-nulles de cette colonne (ex: "id").
+     * - `string[]`: Compte les combinaisons uniques de plusieurs colonnes (COUNT DISTINCT col1, col2).
+     * - `Object`: Comptage conditionnel (CASE WHEN clé = valeur THEN 1 END). Ex: { deletedAt: null }.
+     * @property {string[]} [dateFormat] - Tableau au format [colonne, format_mysql] (ex: ["date_day", "%Y-%m-%d"]).
+     * @property {string} [as] - Alias d'extraction SQL pour le champ (ex: "total_runs" ou "period").
+     */
+
+    /**
+     * @typedef {Object} OrderByOption
+     * @property {string} field - Le nom de la colonne sur laquelle appliquer le tri.
+     * @property {'ASC'|'DESC'} [direction] - La direction du tri (Par défaut : 'ASC').
+     */
+
+    /**
+     * @typedef {Object} JoinOption
+     * @property {string} table - Le nom de la table cible avec laquelle effectuer la jointure.
+     * @property {string} on - La condition de correspondance de la jointure (ex: "ProjectPipelines.project_id = Projects.id").
+     * @property {string} [alias] - Alias SQL optionnel à donner à la table jointe.
+     * @property {'INNER'|'LEFT'|'RIGHT'} [type] - Le type de jointure SQL à appliquer (Par défaut : 'INNER').
      */
 
     /**
-     * Retrieves multiple entries from the table.
-     * @param {Object} [options] - Query options (attributes, where, order, limit).
-     * @param {Array<string|SelectAggregation>} [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.
-     * @param {Object} [options.join] - Join options.
-     * @param {String} [options.join.table] - Table to join.
-     * @param {String} [options.join.on] - Join condition.
-     * @param {String} [options.join.alias] - Alias for the joined table.
+     * Récupère plusieurs entrées de la table correspondante.
+     * @param {Object} [options] - Options de configuration de la requête SQL.
+     * @param {Array<string|SelectAggregation>} [options.select] - Liste des champs, transformations ou agrégations à retourner.
+     * @param {Object|string} [options.where] - Filtres structurés (objet clé/valeur) ou clause WHERE brute sous forme de chaîne.
+     * @param {string[]} [options.groupBy] - Tableau de colonnes ou d'expressions pour grouper les résultats (ex: ["period"]).
+     * @param {Array<string|OrderByOption>} [options.orderBy] - Règles de tri des résultats.
+     * @param {number} [options.limit] - Limite maximale du nombre de lignes à retourner.
+     * @param {JoinOption | JoinOption[]} [options.join] - Option(s) de jointure avec d'autres tables de la base de données.
      * @returns {Promise<Array<ModelInstance>>}
      */
     async find(options = {}) {
@@ -346,7 +348,7 @@ class Model {
                 return resolve(1);
             }).catch((err) => {
                 error(`Error executing query delete: ${err}`);
-                return 0;
+                reject(err)
             });
         });
     }