1. Qu'est-ce que ts-sql-query et pourquoi l'utiliser ?

ts-sql-query est une bibliothèque TypeScript puissante qui permet d'écrire des requêtes SQL avec une vérification de types complète (type-safe). Elle propose un DSL (Domain-Specific Language) pratique pour construire des requêtes SQL, chaque requête étant vérifiée par le compilateur TypeScript par rapport au schéma de la base de données. Cela signifie que les erreurs dans les noms de tables, de colonnes ou les types de données sont détectées à la compilation, et non à l'exécution.

Pourquoi en avez-vous besoin ? Dans les approches traditionnelles (chaînes SQL brutes ou ORM), les développeurs rencontrent souvent des problèmes : fautes de frappe dans les noms de colonnes, incohérences de types, difficultés de refactoring. ts-sql-query résout ces problèmes en offrant un typage strict pour toutes les opérations : SELECT, INSERT, UPDATE, DELETE, JOIN, sous-requêtes, fonctions d'agrégation et bien plus encore. La bibliothèque prend en charge de nombreux SGBD (PostgreSQL, MySQL, SQLite, MariaDB, MSSQL) et fonctionne aussi bien avec les pilotes directement qu'avec les pools de connexions.

Contrairement aux ORM (comme TypeORM ou Prisma), ts-sql-query ne cache pas le SQL derrière des abstractions, mais l'intègre directement dans le code TypeScript. Vous écrivez toujours du SQL, mais avec l'autocomplétion, la vérification des types et sans risque d'injection SQL. C'est le choix idéal pour les projets où la performance et le contrôle total des requêtes sont essentiels, tout en bénéficiant des avantages du typage statique.

2. Installation

L'installation se fait via npm. Vous devez installer la bibliothèque elle-même ainsi que le pilote pour votre base de données.

# Installation de la bibliothèque principale
npm install ts-sql-query

# Installation du pilote pour PostgreSQL (exemple)
npm install pg

# Installation du pilote pour MySQL
npm install mysql2

# Installation du pilote pour SQLite
npm install better-sqlite3

# Installation du pilote pour SQLite (asynchrone)
npm install sql.js

# Installation des types pour Node.js (si nécessaire)
npm install --save-dev @types/node

Après l'installation du pilote, vous devez créer une connexion à la base de données. ts-sql-query fournit des adaptateurs pour chaque pilote.

3. Démarrage rapide — exemple minimal fonctionnel

Prenons un exemple avec PostgreSQL. Créons une table simple users et exécutons une requête SELECT.

import { createPool } from 'pg';
import { PostgreSqlConnection } from 'ts-sql-query/connections/PostgreSqlConnection';

// 1. Créer un pool de connexions
const pool = createPool({
    host: 'localhost',
    port: 5432,
    database: 'testdb',
    user: 'user',
    password: 'password',
});

// 2. Créer une classe de connexion
class DBConnection extends PostgreSqlConnection {
    // Vous pouvez définir ici des méthodes pour interagir avec les tables
}

// 3. Créer une instance de connexion
const connection = new DBConnection(pool);

// 4. Définir le type pour la table users
interface User {
    id: number;
    name: string;
    email: string;
    age: number;
}

// 5. Créer un objet pour interagir avec la table
const users = connection.table('users').columns({
    id: 'id',
    name: 'name',
    email: 'email',
    age: 'age',
});

// 6. Exécuter la requête
async function getUsers() {
    const query = connection
        .selectFrom(users)
        .select(users.id, users.name, users.email)
        .where(users.age.greaterThan(18))
        .orderBy(users.name, 'asc');

    const result = await query.executeSelectMany();
    return result;
}

getUsers().then(users => {
    console.log('Utilisateurs :', users);
}).catch(err => {
    console.error('Erreur :', err);
});

Dans cet exemple, nous avons créé une connexion, défini une table et exécuté une requête SELECT. Tous les types sont vérifiés par le compilateur.