outlet-orm 4.2.1 → 5.5.1

package/README.md

@@ -30,71 +30,171 @@ Si aucun driver n'est installé, un message d'erreur explicite vous indiquera le
 
 ## 📁 Structure de Projet Recommandée
 
-Organisez votre projet utilisant Outlet ORM comme suit :
+Organisez votre projet utilisant Outlet ORM avec une **architecture en couches** (recommandée pour la production) :
 
 > 🔐 **Sécurité** : Voir le [Guide de Sécurité](./docs/SECURITY.md) pour les bonnes pratiques.
 
 ```
 mon-projet/
-├── .env                        # ⚠️ JAMAIS commité (dans .gitignore)
-├── .env.example                # Template sans secrets
-├── .gitignore                  # Exclure .env, node_modules, logs
+├── .env                          # ⚠️ JAMAIS commité (dans .gitignore)
+├── .env.example                  # Template sans secrets
+├── .gitignore
 ├── package.json
-├── config/                     # 🔒 Configuration centralisée
-│   ├── app.js                  # Config générale
-│   ├── database.js             # Config DB (lit .env)
-│   └── security.js             # Rate limit, helmet, CORS...
+│
+├── src/                          # 📦 Code source centralisé
+│   ├── index.js                  # Point d'entrée de l'application
+│   │
+│   ├── config/                   # ⚙️ Configuration
+│   │   ├── app.js                # Config générale (port, env)
+│   │   ├── database.js           # Config DB (lit .env)
+│   │   └── security.js           # CORS, helmet, rate limit
+│   │
+│   ├── models/                   # 📊 Couche Data (Entities)
+│   │   ├── index.js              # Export centralisé des models
+│   │   ├── User.js
+│   │   ├── Post.js
+│   │   └── Comment.js
+│   │
+│   ├── repositories/             # 🗄️ Couche Accès Données
+│   │   ├── BaseRepository.js     # Méthodes CRUD génériques
+│   │   ├── UserRepository.js     # Requêtes spécifiques User
+│   │   └── PostRepository.js
+│   │
+│   ├── services/                 # 💼 Couche Métier (Business Logic)
+│   │   ├── AuthService.js        # Logique d'authentification
+│   │   ├── UserService.js        # Logique métier utilisateur
+│   │   ├── PostService.js
+│   │   └── EmailService.js       # Service externe (emails)
+│   │
+│   ├── controllers/              # 🎮 Couche Présentation (HTTP)
+│   │   ├── AuthController.js
+│   │   ├── UserController.js
+│   │   └── PostController.js
+│   │
+│   ├── routes/                   # 🛤️ Définition des routes
+│   │   ├── index.js              # Agrégateur de routes
+│   │   ├── auth.routes.js
+│   │   ├── user.routes.js
+│   │   └── post.routes.js
+│   │
+│   ├── middlewares/              # 🔒 Middlewares
+│   │   ├── auth.js               # JWT verification
+│   │   ├── authorize.js          # RBAC / permissions
+│   │   ├── rateLimiter.js        # Protection DDoS
+│   │   ├── validator.js          # Validation request body
+│   │   └── errorHandler.js       # Gestion centralisée erreurs
+│   │
+│   ├── validators/               # ✅ Schémas de validation
+│   │   ├── authValidator.js
+│   │   └── userValidator.js
+│   │
+│   └── utils/                    # 🔧 Utilitaires
+│       ├── hash.js               # bcrypt wrapper
+│       ├── token.js              # JWT helpers
+│       ├── logger.js             # Winston/Pino config
+│       └── response.js           # Formatage réponses API
+│
 ├── database/
-│   ├── config.js               # Config migrations (généré par outlet-init)
-│   └── migrations/             # Vos fichiers de migration
-├── models/                     # Vos classes Model
-│   ├── User.js
-│   ├── Post.js
-│   └── Comment.js
-├── controllers/                # Vos contrôleurs (logique métier)
-│   ├── UserController.js
-│   └── PostController.js
-├── routes/                     # Vos fichiers de routes
-│   ├── index.js
-│   └── userRoutes.js
-├── middlewares/                # 🔒 Middlewares de sécurité
-│   ├── auth.js                 # Authentification JWT
-│   ├── authorization.js        # Contrôle des permissions (RBAC)
-│   ├── rateLimiter.js          # Protection anti-DDoS
-│   ├── validator.js            # Validation des entrées
-│   └── errorHandler.js         # Gestion centralisée des erreurs
-├── services/                   # Vos services (logique réutilisable)
-│   ├── AuthService.js
-│   └── EmailService.js
-├── utils/                      # 🔒 Utilitaires sécurité
-│   ├── hash.js                 # Hachage mots de passe (bcrypt)
-│   └── token.js                # Génération tokens sécurisés
-├── validators/                 # 🔒 Schémas de validation
-│   └── userValidator.js
-├── public/                     # ✅ Seul dossier accessible publiquement
+│   ├── config.js                 # Config migrations (outlet-init)
+│   ├── migrations/               # Fichiers de migration
+│   └── seeds/                    # Données de test/démo
+│       └── UserSeeder.js
+│
+├── public/                       # ✅ Fichiers statiques publics
 │   ├── images/
 │   ├── css/
 │   └── js/
-├── uploads/                    # ⚠️ Fichiers uploadés (validés)
-├── logs/                       # 📋 Journaux (non versionnés)
-├── src/                        # Votre code applicatif
-│   └── index.js
-└── tests/                      # Vos tests
-    └── models.test.js
+│
+├── uploads/                      # ⚠️ Fichiers uploadés
+│
+├── logs/                         # 📋 Journaux (non versionnés)
+│
+└── tests/                        # 🧪 Tests
+    ├── unit/                     # Tests unitaires
+    │   ├── services/
+    │   └── models/
+    ├── integration/              # Tests d'intégration
+    │   └── api/
+    └── fixtures/                 # Données de test
+        └── users.json
 ```
 
-| Dossier | Rôle | Sécurité |
-|---------|------|----------|
-| `config/` | Configuration centralisée | 🔒 Lit les secrets depuis .env |
-| `database/` | Migrations et config DB | `outlet-init` |
-| `models/` | Classes Model avec `hidden` et `fillable` | 🔒 Mass assignment protection |
-| `controllers/` | Logique métier | Valider les entrées |
-| `routes/` | Définition des routes API/Web | 🔒 Appliquer middlewares auth |
-| `middlewares/` | Auth, validation, rate limiting | 🔒 **Critique pour la sécurité** |
-| `services/` | Services réutilisables | Isoler la logique sensible |
-| `utils/` | Hash, tokens, encryption | 🔒 Ne jamais exposer |
-| `public/` | Seul dossier accessible | ✅ Fichiers statiques sûrs |
-| `logs/` | Journaux d'accès/erreurs | 📋 Dans .gitignore |
+### 🏗️ Architecture en Couches
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      HTTP Request                           │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  MIDDLEWARES: auth → validate → rateLimiter → errorHandler │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  ROUTES → CONTROLLERS (Couche Présentation)                 │
+│  Reçoit la requête, appelle le service, retourne réponse   │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  SERVICES (Couche Métier / Business Logic)                  │
+│  Logique métier, orchestration, règles business            │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  REPOSITORIES (Couche Accès Données)                        │
+│  Abstraction des requêtes DB, utilise les Models           │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  MODELS (Outlet ORM) → DATABASE                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 📋 Rôle de chaque couche
+
+| Couche | Dossier | Responsabilité | Dépend de |
+|--------|---------|----------------|-----------|
+| **Présentation** | `controllers/` | Traiter HTTP, valider entrées, formater réponses | Services |
+| **Métier** | `services/` | Logique business, orchestration, règles | Repositories |
+| **Données** | `repositories/` | Requêtes DB complexes, abstraction | Models |
+| **Entités** | `models/` | Définition des entités, relations, validations | Outlet ORM |
+
+### ✅ Avantages de cette architecture
+
+- **Testabilité** : Chaque couche peut être testée indépendamment
+- **Maintenabilité** : Séparation claire des responsabilités
+- **Scalabilité** : Facile d'ajouter de nouvelles fonctionnalités
+- **Réutilisabilité** : Services utilisables depuis CLI, workers, etc.
+
+### 📝 Exemple de flux
+
+```javascript
+// routes/user.routes.js
+router.get('/users/:id', auth, UserController.show);
+
+// controllers/UserController.js
+async show(req, res) {
+  const user = await userService.findById(req.params.id);
+  res.json({ data: user });
+}
+
+// services/UserService.js
+async findById(id) {
+  const user = await userRepository.findWithPosts(id);
+  if (!user) throw new NotFoundError('User not found');
+  return user;
+}
+
+// repositories/UserRepository.js
+async findWithPosts(id) {
+  return User.with('posts').find(id);
+}
+```
 
 ## ✨ Fonctionnalités clés
 
@@ -141,6 +241,19 @@ outlet-migrate make create_users_table
 outlet-migrate migrate
 ```
 
+### 🌱 Seeding rapide
+
+```bash
+# Créer un seeder
+outlet-migrate make:seed UserSeeder
+
+# Exécuter les seeds (DatabaseSeeder prioritaire)
+outlet-migrate seed
+
+# Exécuter un seeder spécifique
+outlet-migrate seed --class UserSeeder
+```
+
 ## 📖 Utilisation
 
 ### Configuration de la connexion

package/bin/init.js

@@ -98,6 +98,7 @@ module.exports = db;
       'config',
       'database',
       'database/migrations',
+      'database/seeds',
       'models',
       'controllers',
       'routes',
@@ -126,6 +127,23 @@ module.exports = db;
       }
     }
 
+    const databaseSeederPath = path.join(process.cwd(), 'database', 'seeds', 'DatabaseSeeder.js');
+    if (!fs.existsSync(databaseSeederPath)) {
+      const databaseSeederContent = `const { Seeder } = require('outlet-orm');
+
+class DatabaseSeeder extends Seeder {
+  async run() {
+    // Example:
+    // await this.call('UserSeeder');
+  }
+}
+
+module.exports = DatabaseSeeder;
+`;
+      fs.writeFileSync(databaseSeederPath, databaseSeederContent);
+      console.log('✅ database/seeds/DatabaseSeeder.js créé');
+    }
+
     // Generate .gitignore
     const gitignoreContent = `# Secrets
 .env

package/bin/migrate.js

@@ -31,8 +31,14 @@ async function main() {
     return;
   }
 
+  if (command === 'make:seed' || command === 'seed:make') {
+    await makeSeeder();
+    rl.close();
+    return;
+  }
+
   // Support non-interactive commands for automation and CI
-  const nonInteractive = new Set(['migrate', 'up', 'rollback', 'reset', 'refresh', 'fresh', 'status']);
+  const nonInteractive = new Set(['migrate', 'up', 'rollback', 'reset', 'refresh', 'fresh', 'status', 'seed', 'db:seed']);
   if (nonInteractive.has(command)) {
     const flags = parseFlags(process.argv.slice(3));
     await runNonInteractive(command, flags);
@@ -94,6 +100,40 @@ async function makeMigration() {
   console.log(`  Location: ${filePath}`);
 }
 
+/**
+ * Create a new seeder file
+ */
+async function makeSeeder() {
+  const seederName = process.argv[3];
+
+  if (!seederName) {
+    console.error('✗ Error: Seeder name is required');
+    console.log('Usage: outlet-migrate make:seed <seeder_name>');
+    console.log('Example: outlet-migrate make:seed UserSeeder');
+    return;
+  }
+
+  const seedsDir = path.join(process.cwd(), 'database', 'seeds');
+
+  try {
+    await fs.mkdir(seedsDir, { recursive: true });
+  } catch (error) {
+    if (error.code !== 'EEXIST') {
+      throw error;
+    }
+  }
+
+  const className = toSeederClassName(seederName);
+  const fileName = `${className}.js`;
+  const filePath = path.join(seedsDir, fileName);
+
+  const template = getSeederTemplate(className);
+  await fs.writeFile(filePath, template);
+
+  console.log(`✓ Seeder created: ${fileName}`);
+  console.log(`  Location: ${filePath}`);
+}
+
 /**
  * Extract table name from migration name
  */
@@ -128,7 +168,7 @@ function getCreateMigrationTemplate(tableName) {
  * Migration: Create ${tableName} table
  */
 
-const Migration = require('../../lib/Migrations/Migration');
+const { Migration } = require('outlet-orm');
 
 class Create${capitalize(tableName)}Table extends Migration {
   /**
@@ -165,7 +205,7 @@ function getAlterMigrationTemplate(tableName) {
  * Migration: Alter ${tableName} table
  */
 
-const Migration = require('../../lib/Migrations/Migration');
+const { Migration } = require('outlet-orm');
 
 class Alter${capitalize(tableName)}Table extends Migration {
   /**
@@ -204,6 +244,47 @@ function capitalize(str) {
   return str.charAt(0).toUpperCase() + str.slice(1);
 }
 
+function toSeederClassName(name) {
+  const cleaned = String(name)
+    .replace(/\.js$/i, '')
+    .replace(/[^a-zA-Z0-9]+/g, ' ')
+    .trim();
+
+  const pascal = cleaned
+    .split(/\s+/)
+    .filter(Boolean)
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1).toLowerCase())
+    .join('');
+
+  if (!pascal) {
+    throw new Error('Invalid seeder name');
+  }
+
+  return pascal.endsWith('Seeder') ? pascal : `${pascal}Seeder`;
+}
+
+function getSeederTemplate(className) {
+  return `/**
+ * Seeder: ${className}
+ */
+
+const { Seeder } = require('outlet-orm');
+
+class ${className} extends Seeder {
+  /**
+   * Run the seeder
+   */
+  async run() {
+    await this.insert('table_name', [
+      // { name: 'Example' }
+    ]);
+  }
+}
+
+module.exports = ${className};
+`;
+}
+
 /**
  * Simple flag parser for CLI args
  * Supports formats:
@@ -219,6 +300,10 @@ function parseFlags(argv) {
   const stepsRe = /(?:--steps(?:=|\s+)|-s\s+)(\S+)/;
   const stepsMatch = stepsRe.exec(text);
   if (stepsMatch) flags.steps = coerce(stepsMatch[1]);
+  // Seeder target: --class Name, --class=Name, -c Name
+  const classRe = /(?:--class(?:=|\s+)|-c\s+)(\S+)/;
+  const classMatch = classRe.exec(text);
+  if (classMatch) flags.class = classMatch[1];
   return flags;
 }
 
@@ -261,8 +346,7 @@ async function runNonInteractive(cmd, flags) {
     }
   }
 
-  const { DatabaseConnection } = require('../lib/Database/DatabaseConnection');
-  const MigrationManager = require('../lib/Migrations/MigrationManager');
+  const { DatabaseConnection, MigrationManager, SeederManager } = require('../src');
 
   const connection = new DatabaseConnection(dbConfig);
   await connection.connect();
@@ -313,6 +397,13 @@ async function runNonInteractive(cmd, flags) {
       await manager.status();
       break;
 
+    case 'seed':
+    case 'db:seed': {
+      const seederManager = new SeederManager(connection);
+      await seederManager.run(flags.class || null);
+      break;
+    }
+
     default:
       console.error(`✗ Unknown command: ${cmd}`);
     }
@@ -335,6 +426,8 @@ async function runMigrationCommands() {
   console.log('4. refresh         - Reset and re-run all migrations');
   console.log('5. fresh           - Drop all tables and re-run migrations');
   console.log('6. status          - Show migration status');
+  console.log('7. seed            - Run seeders from database/seeds');
+  console.log('8. make:seed       - Create a new seeder file');
   console.log('0. Exit\n');
 
   const choice = await question('Enter your choice: ');
@@ -370,8 +463,7 @@ async function runMigrationCommands() {
     }
   }
 
-  const { DatabaseConnection } = require('../lib/Database/DatabaseConnection');
-  const MigrationManager = require('../lib/Migrations/MigrationManager');
+  const { DatabaseConnection, MigrationManager, SeederManager } = require('../src');
 
   const connection = new DatabaseConnection(dbConfig);
   await connection.connect();
@@ -424,6 +516,16 @@ async function runMigrationCommands() {
       await manager.status();
       break;
 
+    case '7': {
+      const seederManager = new SeederManager(connection);
+      await seederManager.run();
+      break;
+    }
+
+    case '8':
+      await makeSeeder();
+      break;
+
     default:
       console.log('Invalid choice');
     }