@crane-technologies/database 2.1.0

package/README.md

@@ -0,0 +1,475 @@
+# @crane-technologies/database
+
+Componente de base de datos PostgreSQL con connection pooling, transacciones, gestión de dependencias y **autocompletado de queries con TypeScript**.
+
+## ✨ Características
+
+- ✅ **Autocompletado completo** con `createQueries()`
+- ✅ Connection pooling automático
+- ✅ Transacciones ACID con dependencias entre queries
+- ✅ Soporte para queries planas, anidadas y mixtas
+- ✅ Raw SQL cuando lo necesites
+- ✅ Backward compatible con código existente
+- ✅ Logs configurables (4 niveles)
+- ✅ 100% TypeScript con tipos completos
+
+---
+
+## 📦 Instalación
+
+```bash
+npm install @crane-technologies/database
+```
+
+---
+
+## 🚀 Inicio Rápido
+
+### **Con `createQueries()` (Recomendado ⭐)**
+
+```typescript
+import Database, {
+  createQueries,
+  DatabaseConfig,
+} from "@crane-technologies/database";
+
+// 1. Crear queries con autocompletado
+const queries = createQueries({
+  users: {
+    getById: "SELECT * FROM users WHERE id = $1",
+    create: "INSERT INTO users (name, email) VALUES ($1, $2) RETURNING *",
+    update: "UPDATE users SET name = $1 WHERE id = $2 RETURNING *",
+    delete: "DELETE FROM users WHERE id = $1",
+  },
+  products: {
+    getAll: "SELECT * FROM products",
+    getById: "SELECT * FROM products WHERE id = $1",
+  },
+});
+
+// 2. Configurar base de datos
+const config: DatabaseConfig = {
+  connectionString: process.env.DATABASE_URL!,
+  ssl: { rejectUnauthorized: false },
+  max: 10,
+  logLevel: 2, // 0=NONE, 1=ERROR, 2=DEBUG, 3=ALL
+};
+
+// 3. Inicializar
+const db = Database.getInstance(config, queries);
+
+// 4. Usar con autocompletado! 🎉
+const user = await db.query(queries.users.getById, [123]);
+const newUser = await db.query(queries.users.create, [
+  "John",
+  "john@email.com",
+]);
+const products = await db.query(queries.products.getAll);
+```
+
+---
+
+## 📚 Casos de Uso
+
+### **1. Queries Planas (sin anidación)**
+
+```typescript
+const queries = createQueries({
+  getUser: "SELECT * FROM users WHERE id = $1",
+  createUser: "INSERT INTO users (name) VALUES ($1) RETURNING *",
+  deleteUser: "DELETE FROM users WHERE id = $1",
+});
+
+const db = Database.getInstance(config, queries);
+
+await db.query(queries.getUser, [123]);
+await db.query(queries.createUser, ["Alice"]);
+await db.query(queries.deleteUser, [456]);
+```
+
+---
+
+### **2. Queries Anidadas (organizadas por dominio)**
+
+```typescript
+const queries = createQueries({
+  users: {
+    getById: "SELECT * FROM users WHERE id = $1",
+    create: "INSERT INTO users (name, email) VALUES ($1, $2) RETURNING *",
+    update: "UPDATE users SET name = $1 WHERE id = $2 RETURNING *",
+  },
+  products: {
+    getAll: "SELECT * FROM products",
+    getById: "SELECT * FROM products WHERE id = $1",
+    create: "INSERT INTO products (name, price) VALUES ($1, $2) RETURNING *",
+  },
+});
+
+const db = Database.getInstance(config, queries);
+
+// Autocompletado funciona en todos los niveles!
+await db.query(queries.users.getById, [123]);
+await db.query(queries.products.create, ["Laptop", 999.99]);
+```
+
+---
+
+### **3. Queries Mixtas (planas + anidadas)**
+
+```typescript
+const queries = createQueries({
+  // Queries planas para cosas simples
+  testConnection: "SELECT NOW() as time",
+  checkHealth: "SELECT 1",
+
+  // Queries anidadas para dominios complejos
+  users: {
+    getById: "SELECT * FROM users WHERE id = $1",
+    create: "INSERT INTO users (name, email) VALUES ($1, $2) RETURNING *",
+  },
+  products: {
+    getAll: "SELECT * FROM products",
+  },
+});
+
+const db = Database.getInstance(config, queries);
+
+// Planas
+await db.query(queries.testConnection);
+await db.query(queries.checkHealth);
+
+// Anidadas
+await db.query(queries.users.getById, [123]);
+await db.query(queries.products.getAll);
+```
+
+---
+
+### **4. Raw SQL (cuando lo necesites)**
+
+```typescript
+// Raw SQL sigue funcionando
+const result = await db.query("SELECT COUNT(*) FROM users WHERE active = $1", [
+  true,
+]);
+const count = result.rows[0].count;
+```
+
+---
+
+### **5. Transacciones Simples**
+
+```typescript
+const results = await db.transaction(
+  [queries.users.create, queries.users.create],
+  [
+    ["Alice", "alice@email.com"],
+    ["Bob", "bob@email.com"],
+  ]
+);
+
+console.log("Usuarios creados:", results.length);
+```
+
+---
+
+### **6. Transacciones con Dependencias**
+
+```typescript
+import { Dependency } from "@crane-technologies/database";
+
+const queries = createQueries({
+  users: {
+    create: "INSERT INTO users (name, email) VALUES ($1, $2) RETURNING *",
+  },
+  profiles: {
+    create: "INSERT INTO profiles (user_id, bio) VALUES ($1, $2) RETURNING *",
+  },
+});
+
+const db = Database.getInstance(config, queries);
+
+// El ID del usuario se inyecta automáticamente en el perfil
+const dependencies: Dependency[] = [
+  { sourceIndex: 0, targetIndex: 1, targetParamIndex: 0 },
+];
+
+const results = await db.transaction(
+  [queries.users.create, queries.profiles.create],
+  [
+    ["John", "john@email.com"],
+    [null, "John's bio"], // null será reemplazado por user.id
+  ],
+  dependencies
+);
+
+console.log("Usuario creado:", results[0].rows[0]);
+console.log("Perfil creado:", results[1].rows[0]);
+```
+
+---
+
+## 📊 Niveles de Log
+
+```typescript
+export type LogLevel = 0 | 1 | 2 | 3;
+
+// 0 = NONE   - Sin logs
+// 1 = ERROR  - Solo errores
+// 2 = DEBUG  - Errores + debug
+// 3 = ALL    - Todos los logs (errores + debug + warnings + info)
+
+const config: DatabaseConfig = {
+  connectionString: process.env.DATABASE_URL!,
+  logLevel: 2, // DEBUG
+};
+
+// Cambiar dinámicamente
+db.setLogLevel(1); // Solo errores
+```
+
+---
+
+## 🔄 Backward Compatibility
+
+El paquete es 100% compatible con código existente:
+
+```typescript
+// ✅ Forma antigua (sigue funcionando)
+const db = Database.getInstance(config, {
+  getUser: "SELECT * FROM users WHERE id = $1",
+});
+await db.query("getUser", [123]);
+
+// ✅ Forma nueva (con autocompletado)
+const queries = createQueries({
+  users: {
+    getById: "SELECT * FROM users WHERE id = $1",
+  },
+});
+const db = Database.getInstance(config, queries);
+await db.query(queries.users.getById, [123]);
+```
+
+---
+
+## 🛡️ TypeScript
+
+El paquete incluye definiciones de tipos completas:
+
+```typescript
+import {
+  Database,
+  createQueries,
+  QueryReference,
+  DatabaseConfig,
+  Dependency,
+  Logger,
+  LogLevel,
+  QueryList,
+} from "@crane-technologies/database";
+```
+
+---
+
+## 📚 API Reference
+
+### `createQueries(queries)`
+
+Crea un objeto de queries con autocompletado.
+
+**Parámetros:**
+
+- `queries: Record<string, any>` - Objeto con queries (planas, anidadas o mixtas)
+
+**Retorna:** Objeto con queries y `__flatMap` interno
+
+**Ejemplo:**
+
+```typescript
+const queries = createQueries({
+  users: {
+    getById: "SELECT * FROM users WHERE id = $1",
+  },
+});
+```
+
+---
+
+### `Database.getInstance(config, queries)`
+
+Obtiene la instancia singleton de Database.
+
+**Parámetros:**
+
+- `config: DatabaseConfig` - Configuración de conexión
+- `queries?: any` - Resultado de `createQueries()` o objeto plano
+
+**Retorna:** `Database`
+
+**Ejemplo:**
+
+```typescript
+const db = Database.getInstance(config, queries);
+```
+
+---
+
+### `db.query(query, params?)`
+
+Ejecuta una query (con QueryReference, string key o raw SQL).
+
+**Parámetros:**
+
+- `query: string | QueryReference` - Query a ejecutar
+- `params?: any[]` - Parámetros de la query
+
+**Retorna:** `Promise<QueryResult>`
+
+**Ejemplos:**
+
+```typescript
+// Con QueryReference
+await db.query(queries.users.getById, [123]);
+
+// Con string key
+await db.query("users.getById", [123]);
+
+// Raw SQL
+await db.query("SELECT * FROM users WHERE id = $1", [123]);
+```
+
+---
+
+### `db.transaction(queryArray, paramsArray, dependencies?)`
+
+Ejecuta múltiples queries en una transacción atómica.
+
+**Parámetros:**
+
+- `queryArray: (string | QueryReference)[]` - Array de queries
+- `paramsArray: any[][]` - Parámetros para cada query
+- `dependencies?: Dependency[]` - Dependencias entre queries
+
+**Retorna:** `Promise<QueryResult[]>`
+
+**Ejemplo:**
+
+```typescript
+await db.transaction(
+  [queries.users.create, queries.profiles.create],
+  [
+    ["John", "john@email.com"],
+    [null, "Bio"],
+  ],
+  [{ sourceIndex: 0, targetIndex: 1, targetParamIndex: 0 }]
+);
+```
+
+---
+
+### `db.close()`
+
+Cierra todas las conexiones del pool.
+
+**Retorna:** `Promise<void>`
+
+**Ejemplo:**
+
+```typescript
+await db.close();
+```
+
+---
+
+### `db.setLogLevel(level)`
+
+Cambia el nivel de log dinámicamente.
+
+**Parámetros:**
+
+- `level: 0 | 1 | 2 | 3` - Nuevo nivel de log
+
+**Ejemplo:**
+
+```typescript
+db.setLogLevel(1); // Solo errores
+```
+
+---
+
+## 🔒 Cerrar Conexiones
+
+```typescript
+process.on("SIGTERM", async () => {
+  const db = Database.getInstance(config);
+  await db.close();
+  process.exit(0);
+});
+```
+
+---
+
+## 🧪 Testing
+
+```bash
+npm test
+```
+
+---
+
+## 📄 Licencia
+
+MIT
+
+---
+
+## 🤝 Contribuir
+
+Issues y Pull Requests son bienvenidos en: https://github.com/Crane/database
+
+---
+
+## 📝 Changelog
+
+### v2.0.0 (Actual)
+
+- ✨ **NEW:** `createQueries()` con autocompletado completo
+- ✨ **NEW:** Soporte para queries planas, anidadas y mixtas
+- ✨ **NEW:** `QueryReference` type para mejor DX
+- ✅ Backward compatible con v1.x.x
+- 📚 Documentación actualizada con ejemplos
+
+### v1.0.0
+
+- 🎉 Release inicial
+- Connection pooling
+- Transacciones con dependencias
+- Sistema de logs configurable
+
+---
+
+### `db.bulkInsert(table, columns, rows, options?)`
+
+Usa `COPY … FROM STDIN` para insertar muchos registros de forma nativa.
+
+**Parámetros:**
+
+- `table`: nombre de la tabla destino
+- `columns`: columnas que se van a poblar (ordenadas)
+- `rows`: matriz con los valores (cada fila puede tener `null`)
+- `options?`: [`BulkInsertOptions`](./interfaces/BulkInsertOptions.ts) para delimitar y agregar cabecera
+
+**Ejemplo:**
+
+```ts
+await db.bulkInsert(
+  "test_users",
+  ["name", "email"],
+  [
+    ["Bulk 1", "bulk1@example.com"],
+    ["Bulk 2", "bulk2@example.com"],
+  ],
+  { header: false }
+);
+```