@mlagie/sql-connector 1.0.0

package/documentation.md

@@ -0,0 +1,159 @@
+# Documentation du module `sql-connector`
+
+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.
+
+## Importation du module
+
+```javascript
+const { Schema, connect, logout, Model, client, sqlType } = require('sql-connector');
+```
+
+### Fonctions
+
+`connect(config)` Établit une connexion à la base de données.
+
+* Paramètres:
+    * `config` (Object) : La configuration de la connexion à la base de données.
+    * `host` (string) : L'hôte de la base de données.
+    * `port` (number) : Le port de la base de données.
+    * `user` (string) : Le nom d'utilisateur pour la connexion.
+    * `password` (string) : Le mot de passe pour la connexion.
+    * `database` (string) : Le nom de la base de données.
+    * `ect` pour en savoir plus vous pouvez vous rendre sur https://github.com/mysqljs/mysql dans la section `Connection options`
+
+* ### Exemple:
+
+```javascript
+const config = {
+  host: 'localhost',
+  port: 3306,
+  user: 'root',
+  password: 'password',
+  database: 'mydatabase'
+};
+await connect(config);
+```
+
+`logout()` Ferme la connexion à la base de données.
+
+* ### Exemple:
+
+```javascript
+await logout();
+```
+
+### Classes `Schema`
+
+Représente un schéma de base de données.
+* Constructeur:
+    * Schema(schemaDict) : Crée une instance de Schema.
+        * schemaDict (Object) : Un dictionnaire définissant le schéma.
+
+* Exemple
+
+```javascript
+const transferSchema = new Schema({
+  token: {
+    type: String,
+    length: 50
+  },
+  mdp: {
+    type: String,
+    length: 15
+  }
+});
+```
+## Class Model
+Représente un modèle de base de données.
+* ### Constructeur :
+    * `Model(name, schema)` : Crée une instance de `Model`.
+    * `name (string)` : Le nom de la table de base de données.
+    * `schema (Schema)` : Le schéma de la table de base de données.
+* ### Méthodes :
+    * `generateCreateTableStatement(schema)` : Génère une requête SQL pour créer une table.
+    * `save(data)` : Sauvegarde des données dans la table.
+    * `findOne(filter, fields)` : Trouve une entrée unique dans la table.
+    * `find(filter, fields)` : Trouve des entrées dans la table.
+    * `customRequest(custom)` : Exécute une requête SQL personnalisée.
+    * `delete(filter)` : Supprime une entrée de la table.
+    * `dropTable()` : Supprime la table si elle existe.
+    * `generate_uuid()` : Génère un UUID unique pour le modèle.
+    * `createAllTables()` : **Crée toutes les tables dans le bon ordre selon les dépendances de clés étrangères.** (statique)
+* ### Exemple
+```javascript
+const userModel = new Model('users', transferSchema);
+// Après avoir instancié tous les modèles :
+await Model.createAllTables(); // Crée toutes les tables dans le bon ordre
+
+// Sauvegarder des données
+await userModel.save({ token: 'abc123', mdp: 'password' });
+
+// Trouver une entrée
+const user = await userModel.findOne({ token: 'abc123' });
+
+// Supprimer une entrée
+await userModel.delete({ token: 'abc123' });
+```
+## Class ModelInstance
+Représente une instance d'un modèle de base de données.
+* ### Constructeur:
+    * `ModelInstance(name, data)` : Crée une instance de `ModelInstance`.
+    * `name (string)` : Le nom de la table de base de données.
+    * `data (Object)` : Les données de l'instance.
+* ### Méthodes :
+    * `updateOne(model)` : Met à jour une entrée unique dans la table.
+    * `delete(model)` : Supprime une entrée unique dans la table.
+    * `customRequest(custom)` : Exécute une requête SQL personnalisée.
+* ### Exemple
+```javascript
+const userInstance = new ModelInstance('users', { token: 'abc123', mdp: 'password' });
+
+// Mettre à jour des données
+await userInstance.updateOne({ mdp: 'newpassword' });
+
+// Supprimer des données
+await userInstance.delete({ token: 'abc123' });
+```
+# Types SQL
+Le module fournit également une map des types SQL courants via `sqlType`.
+## Type
+* String
+* Number
+* Boolean
+* Object
+* Array
+* Now
+* Float
+* Text
+* DateTime
+* Timestamp
+* ### Exemple
+```javascript
+console.log(sqlType.String); // "String"
+console.log(sqlTypeMap.String); // "VARCHAR"
+```
+## Conclusion
+Le module `sql-connector` fournit une interface simple et efficace pour interagir avec une base de données MySQL, permettant de définir des schémas, de gérer des connexions, et de manipuler des données de manière intuitive.
+
+# Client
+Le module client est un objet utilisé pour stocker des fonctions. Il sert de conteneur centralisé pour diverses fonctions qui peuvent être utilisées dans différentes parties de l'application.
+
+### Utilisation
+Pour ajouter une fonction à l'objet client, vous pouvez simplement définir une nouvelle propriété sur l'objet et lui assigner une fonction.
+* ### Exemple
+```javascript
+module.exports = client => {
+    client.checkServer() {
+        if (server.islaunch())
+            return 1;
+        return 0;
+    };
+};
+```
+### Avantages
+* `Centralisation` : Toutes les fonctions liées à des opérations spécifiques peuvent être centralisées dans un seul objet, ce qui facilite la gestion et l'organisation du code.
+* `Réutilisabilité` : Les fonctions stockées dans l'objet `client` peuvent être facilement réutilisées dans différentes parties de l'application.
+* `Modularité` : En utilisant un objet pour stocker des fonctions, il est plus facile de maintenir et de mettre à jour le code, car les fonctions peuvent être ajoutées, modifiées ou supprimées sans affecter d'autres parties de l'application.
+
+## Conclusion
+L'objet `client` est un outil puissant pour organiser et centraliser les fonctions dans votre application. En stockant des fonctions dans cet objet, vous pouvez améliorer la modularité, la réutilisabilité et la maintenabilité de votre code.

package/index.d.ts

@@ -0,0 +1,249 @@
+import { PoolOptions } from "mysql2";
+
+export type SqlType =
+    | "String"
+    | "Number"
+    | "Boolean"
+    | "Date"
+    | "Object"
+    | "Array"
+    | "Now"
+    | "Float"
+    | "Text"
+    | "DateTime"
+    | "Timestamp";
+
+export interface SchemaField {
+    type: SqlType | { name: SqlType };
+    length?: number;
+    required?: boolean;
+    default?: any;
+    unique?: boolean;
+    auto_increment?: boolean;
+    foreignKey?: string;
+    customize?: string;
+}
+
+export interface SchemaDict {
+    [key: string]: SchemaField;
+}
+
+/**
+ * Represents a database schema.
+ * 
+ * @example
+ * const transferSchema = new Schema({
+ *     token: {
+ *         type: String,
+ *         length: 50
+ *     },
+ *     mdp: {
+ *         type: String,
+ *         length: 15
+ *     }
+ * });
+ */
+export class Schema {
+    constructor(schemaDict: SchemaDict);
+    schemaDict: SchemaDict;
+}
+
+/**
+ * Establishes a connection to the database using a given configuration.
+ * @param {Object} config Database connection configuration.
+ * @param {string} config.host The database host.
+ * @param {number} config.port The database port.
+ * @param {string} config.user The username for the connection.
+ * @param {string} config.password The password for the connection.
+ * @param {string} config.database The name of the database.
+ * @returns {Promise<void>} A promise that resolves when the connection is established.
+ * 
+ * @example
+ * const config = {
+ *   host: 'localhost',
+ *   port: 6666,
+ *   user: 'root',
+ *   password: 'password',
+ *   database: 'mydatabase'
+ * };
+ * await connect(config);
+ */
+export function connect(config: PoolOptions): Promise<void>;
+
+/**
+ * Closes the database connection.
+ * This function terminates the active database connection and records a logging message
+ * indicating whether the shutdown succeeded or failed.
+ * 
+ * @returns {Promise<void>} A promise that resolves when the connection is closed.
+ *
+ * @example
+ * await logout();
+ */
+export function logout(): Promise<void>;
+
+/**
+ * Represents a database model.
+ * @class
+ */
+export class Model {
+    static sqlTypeMap: Record<SqlType, string>;
+    static pendingModels: Model[];
+    name: string;
+    schema: Schema;
+    constructor(name: string, schema: Schema);
+    /**
+     * Crée toutes les tables dans l'ordre correct en fonction des foreign keys.
+     * @returns {Promise<void>}
+     */
+    static createAllTables(): Promise<void>;
+    /**
+     * Saves data to the database table.
+     * @param {Object} data 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.
+     */
+    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.
+     * @returns {Promise<Array<Object>>}
+     */
+    findAll(options?: {
+        attributes?: 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.
+     * @returns {Promise<ModelInstance|number>} - A promise that resolves to a `ModelInstance` if a record is found, or `0` if no records match the filter.
+     */
+    count(filter?: Record<string, any>): Promise<any>;
+    /**
+     * Runs a custom SQL_request query.
+     * @param {string} custom 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.
+     */
+    customRequest(custom: string): Promise<any>;
+    /**
+     * Supprime une entrée de la table SQL correspondant au filtre fourni.
+     *
+     * @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.
+     */
+    delete(filter: Record<string, any>): Promise<number | ModelInstance>;
+    /**
+     * 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.
+     */
+    dropTable(): Promise<void>;
+    /**
+     * 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`.
+     *
+     * @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.
+     *
+     * @example
+     * const uuid = await model.generate_uuid();
+     * if (uuid) {
+     *     console.log(`Generated UUID: ${uuid}`);
+     * } else {
+     *     console.log('Failed to generate a unique UUID.');
+     * }
+     *
+     * @throws {Error} If there is an error executing the SQL_request query.
+     */
+    generate_uuid(var_uuid?: string): Promise<string | null>;
+}
+
+/**
+ * Represents an instance of a database model.
+ * @class
+ */
+export class ModelInstance {
+    name: string;
+    data: any;
+    schema?: Schema;
+    constructor(name: string, data: any, schema?: Schema);
+    /**
+     * Updates a single entry in the database table.
+     * 
+     * @param {Object} model An object containing the key-value pairs to use for updating.
+     * @returns {int} A promise that resolves with updated data.
+     * @throws {Error} Throws an error if the update fails.
+     */
+    updateOne(model: Record<string, any>): Promise<number>;
+    /**
+     * Deletes a single entry in the database table.
+     * @param {Object} model An object containing the key-value pairs to use for deletion.
+     * @returns {Promise<Object>} A promise that resolves with the data deleted.
+     * @throws {Error} Throws an error if the deletion fails.
+     */
+    delete(filter: Record<string, any>): Promise<number | ModelInstance>;
+    /**
+     * Deletes a single entry in the database table based on the instance data.
+     * @returns {Promise<number>} A promise that resolves to the number of rows deleted.
+     * @throws {Error} Throws an error if the deletion fails.
+     */
+    deleteOne(): Promise<number>;
+    /**
+     * Runs a custom SQL_request query.
+     * @param {string} custom 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.
+     */
+    customRequest(custom: string): Promise<any>;
+}
+
+export const client: Record<string, any>;
+export const sqlType: Record<string, SqlType>;