@mlagie/sql-connector 1.4.9 → 1.5.0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,43 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: lagie-marin
+
+---
+
+## Bug Description
+
+## Steps to Reproduce
+
+1. Call the method `...`
+2. Pass the following options/parameters `...`
+3. Execute the code
+4. See the error
+
+## Code Snippet / Logs
+
+**JavaScript Code:**
+
+```javascript
+// Insert the JavaScript code that triggers the issue here
+const result = await MyModel.find({ ... });
+```
+
+## Error Logs / Output
+
+```txt
+TypeError: ... is not a function
+    at ...
+```
+
+## Expected Behavior
+
+Example: The `find()` method should return a native JavaScript Array of `ModelInstance` objects so that `.length` or indexation like `[0]` works out of the box when multiple rows are returned.
+
+## Environment
+
+- sql-connector version: vX.X.X
+- Node.js version: vXX.XX.X
+- Database (MySQL/MariaDB...): MySQL vX.X

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,29 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: lagie-marin
+
+---
+
+## Feature Type
+- [ ] New method / API addition
+- [ ] Performance improvement
+- [ ] Architecture Refactoring (ORM / Data Mapping)
+- [ ] Other: 
+
+## Problem Statement
+*Example: Currently, the ORM wraps the raw driver payload `[rows, fields]` inside a single global `ModelInstance`. This forces developers to leak internal database structure by accessing nested arrays like `data[0][0]` when handling records, destroying proper encapsulation.*
+
+## Proposed Solution
+*Example: Refactor the `find()` method to map and split the query results. It should return a native Array where each row is mapped into its own independent `ModelInstance`. Implement dynamic data-mapping (via continuous references, Getters/Setters, or a Proxy) to allow direct property access (`job.status`) without cloning the memory footprint.*
+
+## Desired Developer Experience (DX / Example)
+```javascript
+// Provide an example of how the ideal code should look after this feature:
+const jobs = await InjectionJobs.find({ where: { status: "running" } });
+
+console.log(jobs.length);    // Native array length works
+console.log(jobs[0].status); // Direct property access on the instance
+await jobs[0].updateOne({ status: "success" }); // Instance methods remain fully bound

package/README.md

@@ -1,5 +1,8 @@
 # sql-connector documentation
 
+![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)
+
 [Français](./docs/fr/README.md) | English
 
 sql-connector helps manage MySQL connections, define table schemas, sync tables automatically, and work with database models through a small API.
@@ -32,41 +35,91 @@ await connect(config);
 await logout();
 ```
 
+### Example
+
+```js
+const { connect: dbConnect, client, Model } =  require("@mlagie/sql-connector");
+
+
+await dbConnect({
+    host: 'localhost',
+    port: 3306,
+    user: 'root',
+    password: 'password',
+    database: 'mydatabase',
+    connectionLimit: 2,
+    multipleStatements: true,
+    idleTimeout: 10000,
+    typeCast: true,
+    }).then(() => { Logger.client("- connected to the database") }).catch(error => {
+        console.error(error);
+        process.exit();
+});
+```
+
 ## Schema
 
 `Schema` describes the structure of a table. Each field can use the following properties.
 
-| Property | Type | Description |
-|---|---|---|
-| type | `SqlType` or `{ name: SqlType }` | SQL type for the field |
-| length | `number` | Maximum length |
-| required | `boolean` | Not null constraint |
-| default | `any` | Default value |
-| unique | `boolean` | Unique constraint |
-| auto_increment | `boolean` | Auto increment |
-| foreignKey | `string` | Foreign key reference |
-| enum | `string[]` | Allowed values |
-| primary_key | `boolean` | Primary key flag |
-| customize | `string` | Extra SQL options |
+| Property       | Type                             | Description            |
+|----------------|----------------------------------|------------------------|
+| type           | `SqlType` or `{ name: SqlType }` | SQL type for the field |
+| length         | `number`                         | Maximum length         |
+| required       | `boolean`                        | Not null constraint    |
+| default        | `any`                            | Default value          |
+| unique         | `boolean`                        | Unique constraint      |
+| auto_increment | `boolean`                        | Auto increment         |
+| foreignKey     | `string`                         | Foreign key reference  |
+| enum           | `string[]`                       | Allowed values         |
+| primary_key    | `boolean`                        | Primary key flag       |
+| customize      | `string`                         | Extra SQL options      |
+
+### Example Schema creation & Model Creation
 
 ```javascript
+const { Schema, Model, sqlTypeMap } = require("@mlagie/sql-connector");
+
 const userSchema = new Schema({
-  id: {
-    type: Number,
-    auto_increment: true,
-    primary_key: true
-  },
-  email: {
-    type: String,
-    length: 255,
-    unique: true,
-    required: true
-  },
-  status: {
-    type: String,
-    enum: ['active', 'inactive', 'pending'],
-    default: 'pending'
-  }
+    id: {
+        type: Number,
+        auto_increment: true,
+        primary_key: true
+    },
+    group_uuid: {
+        type: String,
+        required: true,
+        primary_key: true,
+        length: 36
+    },
+    email: {
+        type: String,
+        length: 255,
+        unique: true,
+        required: true
+    },
+    status: {
+        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
+    }
+
+    module.exports = new Model("User", userSchema);
+
 });
 ```
 
@@ -92,25 +145,188 @@ Important: do not set both `primary_key: true` and `unique: true` on the same fi
 
 Main methods:
 
-- `save(data)` inserts a row
-- `findOne(filter, fields)` fetches a single row
-- `find(filter, fields)` fetches multiple rows
-- `findAll(options)` supports advanced queries
-- `count(filter)` counts rows
-- `customRequest(custom)` runs a custom SQL query
-- `delete(filter)` deletes a row
-- `dropTable()` drops the table
-- `generate_uuid()` generates a unique UUID
-- `Model.createAllTables()` creates tables in dependency order
+- `save(data)` Inserts a row
+- `find(options)` Retrieves entries from the table.
+- `count(filter)` Counts rows
+- `customRequest(custom)` Runs a custom SQL query
+- `delete(filter)` Deletes a row
+- `dropTable()` Drops the table
+- `generate_uuid()` Generates a unique UUID
 
 ```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();
+```
+
+## save function
+
+Saves data to the database table.
+
+- **Parameters** `data` *(Object)* - The data to insert into the table.
+- **Returns** `Promise<Object>` - A promise that resolves with the result of the insertion.
+- **Throws** `Error` - Throws an error if the insert fails.
+
+```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 });
+
+}
+```
+
+## find function
+
+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.
+- **Returns** `Promise<Array<ModelInstance>>`
+
+### find Options
+
+| 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`                                        |
+
+## Example find
+
+```js
+const User = require("user");
+
+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");
+
+User.find({
+  select: [
+    "email"
+  ],
+  where: {
+    id: 1
+  }
+})
+```
+
+## count function
+
+Counts the number of records matching the given filter.
+
+- **Parameters** `filter` *(Object)* The filter criteria for the query. Should be an object where keys are column names and values are the values to filter by.
+- **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 count
+
+```js
+const User = require("user");
+
+User.count({
+  id: id
+})
+```
+
+## customRequest function
+
+The customRequest function allows you to execute SQL queries that are not supported by sql-connector; this could be in queries where the keywords are not yet implemented.
+
+- **Parameters** `custom` *(string)*  The custom SQL_request query to execute.
+- **Returns** `Promise<void>` A promise that resolves when the query is executed.
+- **Throws** `Error` Throws an error if query execution fails.
+
+## Example customRequest
+
+```js
+const User = require("user");
+
+User.customRequest("SELECT id, email, status
+  FROM users
+  WHERE status IN ('active', 'pending')
+  AND email LIKE '%gmail.com';")
+```
+
+## delete function
+
+Deletes an entry from the SQL table that matches the provided filter.
+
+- **Parameters** `filter` *(Object)* An object representing the filter conditions for deletion.
+- **Returns** `Promise<number>` A promise that resolves to 0 if no rows were deleted, * or to a ModelInstance representing the deleted row.
+- **Throws** `Error` Throws an error if the SQL query fails.
+
+## Example delete
+
+```js
+const User = require("user");
+
+User.delete({
+  email: my@gmail.com
+})
+```
+
+## dropTable function
+
+Asynchronously drops a table if it exists in the database.
+
+This function constructs a SQL_request query to drop a table with the name specified by the `this.name` property. It then executes the query using a promise-based approach.
+If the query is successful, the result is logged to the console.
+If an error occurs during the execution of the query, an error message is logged.
+
+- **Returns** `Promise<void>` A promise that resolves when the query execution is complete.
+
+## Example dropTable
+
+```js
+const User = require("user");
+
+User.dropTable();
+```
+
+## generate_uuid function
+
+Generates a unique UUID for the current model.
+This function generates a UUID using the SQL_request `UUID()` function and checks if the generated UUID already exists in the database for the current model. If the UUID is unique, it is returned.
+Otherwise, the function resolves to `null`.
+
+- **Parameters** `string` var_uuid By default, it is set to uuid.
+- **Returns** `Promise<string|null>` A promise that resolves to a unique UUID string if successful, or `null` if an error occurs or the UUID is not unique.
+- **Throws** `Error` If there is an error executing the SQL_request query.
+
+## 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 }
 ```
 
 ## Model instances
@@ -122,8 +338,8 @@ await userModel.delete({ email: 'user@example.com' });
 - `deleteOne()` deletes the instance row
 - `customRequest(custom)` runs a custom query
 
-```javascript
-const userInstance = new ModelInstance('users', { email: 'user@example.com' });
+```js
+const userInstance = await find({ select: "users", where: { email: 'user@example.com' }})[0];
 
 await userInstance.updateOne({ status: 'inactive' });
 await userInstance.deleteOne();
@@ -155,4 +371,4 @@ module.exports = client => {
 
 ## Summary
 
-sql-connector provides a small layer to connect to MySQL, describe schemas, synchronize tables, and manipulate data with typed models.
+sql-connector provides a small layer to connect to MySQL, describe schemas, synchronize tables, and manipulate data with typed models.

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
+    }
 });
 ```
 
@@ -93,24 +111,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 +339,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.