Outlet ORM Best Practices

Comprehensive guide for using Outlet ORM - a Laravel Eloquent-inspired ORM for Node.js/TypeScript with support for MySQL, PostgreSQL, and SQLite.

🆕 v5.0.0 : Support TypeScript complet avec Generic Model, Schema Builder typé, MigrationInterface et intégration Copilot Skills. Architecture en couches recommandée (Controllers → Services → Repositories → Models).

Documentation Index

Document	Description
MODELS.md	Model definition, CRUD, casts, timestamps, connections
QUERIES.md	Query Builder, WHERE clauses, joins, pagination
RELATIONS.md	Relationships, Eager Loading, polymorphic, naming conventions
MIGRATIONS.md	Schema Builder, CLI tools, column types, foreign keys
ADVANCED.md	Transactions, Soft Deletes, Events, Validation, Best Practices
TYPESCRIPT.md	TypeScript types, generics, typed models, migrations
SECURITY.md	🔐 Security best practices, authentication, authorization
API.md	Complete API Reference

When to Apply

Reference these guidelines when:

•Defining models and table schemas MODELS.md
•Building database queries QUERIES.md
•Implementing relationships RELATIONS.md
•Using Eager Loading RELATIONS.md
•Setting up migrations MIGRATIONS.md
•Implementing transactions, soft deletes, events ADVANCED.md
•Using TypeScript with typed models TYPESCRIPT.md
•Securing your backend application SECURITY.md

Prerequisites

•Node.js: >= 18 (required)
•
Database Drivers (install only needed):
- •MySQL/MariaDB: npm install mysql2
- •PostgreSQL: npm install pg
- •SQLite: npm install sqlite3

bash

npm install outlet-orm

Recommended Project Structure (Layered Architecture)

When using Outlet ORM, organize your project following the Layered Architecture pattern:

🔐 Security: See the Security Guide for best practices.

code

my-project/
├── .env                           # ⚠️ NEVER commit (in .gitignore)
├── .env.example                   # Template without secrets
├── .gitignore
├── package.json
├── src/
│   ├── index.js                   # Entry point
│   ├── controllers/               # 🎮 Presentation Layer
│   │   └── UserController.js
│   ├── services/                  # ⚙️ Business Logic Layer
│   │   └── UserService.js
│   ├── repositories/              # 📦 Data Access Layer
│   │   └── UserRepository.js
│   ├── models/                    # 📊 Models Layer (outlet-orm)
│   │   └── User.js
│   ├── middlewares/               # 🔒 Auth, validation, rate limit
│   │   ├── auth.js
│   │   ├── validator.js
│   │   └── errorHandler.js
│   ├── routes/                    # 🛤️ Route definitions
│   │   └── index.js
│   ├── config/                    # 🔒 Configuration
│   │   ├── database.js
│   │   └── security.js
│   └── utils/                     # 🔒 Hash, tokens, helpers
│       └── helpers.js
├── database/
│   ├── config.js                  # Migration CLI config
│   └── migrations/
├── public/                        # ✅ Static files only
├── logs/                          # 📋 Not versioned
└── tests/
    ├── unit/
    └── integration/

Architecture Flow

code

┌─────────────────────────────────────────────────────────────┐
│                        HTTP REQUEST                         │
└─────────────────────────┬───────────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  🛤️ ROUTES          Route to correct controller             │
└─────────────────────────┬───────────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  🔒 MIDDLEWARES      Validation, Auth, Rate Limiting        │
└─────────────────────────┬───────────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  🎮 CONTROLLERS      HTTP handling (req/res) only           │
└─────────────────────────┬───────────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  ⚙️ SERVICES         Business logic, business rules         │
└─────────────────────────┬───────────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  📦 REPOSITORIES     Data access abstraction (CRUD)         │
└─────────────────────────┬───────────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  📊 MODELS           outlet-orm (User, Post, etc.)          │
└─────────────────────────┬───────────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                        DATABASE                             │
└─────────────────────────────────────────────────────────────┘

Layer Responsibilities

Layer	Files	Responsibility	Security
Controllers	`src/controllers/`	HTTP only (req/res)	Input validation
Services	`src/services/`	Business logic, rules	Authorization
Repositories	`src/repositories/`	DB abstraction, queries	Sanitization
Models	`src/models/`	Data structure, relations	Fillable/Hidden
Middlewares	`src/middlewares/`	Auth, validation, errors	🔒 Critical
Config	`src/config/`	Environment variables	🔒 Reads .env
Utils	`src/utils/`	Hash, tokens, helpers	🔒 Never expose

Quick Setup Commands