@crane-technologies/database 2.1.0 → 3.0.1

package/README.md

@@ -1,21 +1,21 @@
 # @crane-technologies/database
 
-Componente de base de datos PostgreSQL con connection pooling, transacciones, gestión de dependencias y **autocompletado de queries con TypeScript**.
+PostgreSQL database component with connection pooling, transactions, dependency management, and **TypeScript query autocomplete**.
 
-## ✨ Características
+## ✨ Features
 
-- ✅ **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
+- ✅ **Full autocomplete** with `createQueries()`
+- ✅ Automatic connection pooling
+- ✅ ACID transactions with query dependencies
+- ✅ Support for flat, nested, and mixed queries
+- ✅ Raw SQL when you need it
+- ✅ Backward compatible with existing code
+- ✅ Configurable logs (4 levels)
+- ✅ 100% TypeScript with complete types
 
 ---
 
-## 📦 Instalación
+## 📦 Installation
 
 ```bash
 npm install @crane-technologies/database
@@ -23,9 +23,9 @@ npm install @crane-technologies/database
 
 ---
 
-## 🚀 Inicio Rápido
+## 🚀 Quick Start
 
-### **Con `createQueries()` (Recomendado ⭐)**
+### **With `createQueries()` (Recommended ⭐)**
 
 ```typescript
 import Database, {
@@ -33,7 +33,7 @@ import Database, {
   DatabaseConfig,
 } from "@crane-technologies/database";
 
-// 1. Crear queries con autocompletado
+// 1. Create queries with autocomplete
 const queries = createQueries({
   users: {
     getById: "SELECT * FROM users WHERE id = $1",
@@ -47,7 +47,7 @@ const queries = createQueries({
   },
 });
 
-// 2. Configurar base de datos
+// 2. Configure database
 const config: DatabaseConfig = {
   connectionString: process.env.DATABASE_URL!,
   ssl: { rejectUnauthorized: false },
@@ -55,10 +55,10 @@ const config: DatabaseConfig = {
   logLevel: 2, // 0=NONE, 1=ERROR, 2=DEBUG, 3=ALL
 };
 
-// 3. Inicializar
+// 3. Initialize
 const db = Database.getInstance(config, queries);
 
-// 4. Usar con autocompletado! 🎉
+// 4. Use with autocomplete! 🎉
 const user = await db.query(queries.users.getById, [123]);
 const newUser = await db.query(queries.users.create, [
   "John",
@@ -69,9 +69,9 @@ const products = await db.query(queries.products.getAll);
 
 ---
 
-## 📚 Casos de Uso
+## 📚 Use Cases
 
-### **1. Queries Planas (sin anidación)**
+### **1. Flat Queries (no nesting)**
 
 ```typescript
 const queries = createQueries({
@@ -89,7 +89,7 @@ await db.query(queries.deleteUser, [456]);
 
 ---
 
-### **2. Queries Anidadas (organizadas por dominio)**
+### **2. Nested Queries (domain-organized)**
 
 ```typescript
 const queries = createQueries({
@@ -107,22 +107,22 @@ const queries = createQueries({
 
 const db = Database.getInstance(config, queries);
 
-// Autocompletado funciona en todos los niveles!
+// Autocomplete works at all levels!
 await db.query(queries.users.getById, [123]);
 await db.query(queries.products.create, ["Laptop", 999.99]);
 ```
 
 ---
 
-### **3. Queries Mixtas (planas + anidadas)**
+### **3. Mixed Queries (flat + nested)**
 
 ```typescript
 const queries = createQueries({
-  // Queries planas para cosas simples
+  // Flat queries for simple things
   testConnection: "SELECT NOW() as time",
   checkHealth: "SELECT 1",
 
-  // Queries anidadas para dominios complejos
+  // Nested queries for complex domains
   users: {
     getById: "SELECT * FROM users WHERE id = $1",
     create: "INSERT INTO users (name, email) VALUES ($1, $2) RETURNING *",
@@ -134,21 +134,21 @@ const queries = createQueries({
 
 const db = Database.getInstance(config, queries);
 
-// Planas
+// Flat
 await db.query(queries.testConnection);
 await db.query(queries.checkHealth);
 
-// Anidadas
+// Nested
 await db.query(queries.users.getById, [123]);
 await db.query(queries.products.getAll);
 ```
 
 ---
 
-### **4. Raw SQL (cuando lo necesites)**
+### **4. Raw SQL (when you need it)**
 
 ```typescript
-// Raw SQL sigue funcionando
+// Raw SQL still works
 const result = await db.query("SELECT COUNT(*) FROM users WHERE active = $1", [
   true,
 ]);
@@ -157,7 +157,7 @@ const count = result.rows[0].count;
 
 ---
 
-### **5. Transacciones Simples**
+### **5. Simple Transactions**
 
 ```typescript
 const results = await db.transaction(
@@ -168,12 +168,12 @@ const results = await db.transaction(
   ]
 );
 
-console.log("Usuarios creados:", results.length);
+console.log("Users created:", results.length);
 ```
 
 ---
 
-### **6. Transacciones con Dependencias**
+### **6. Transactions with Dependencies**
 
 ```typescript
 import { Dependency } from "@crane-technologies/database";
@@ -189,7 +189,7 @@ const queries = createQueries({
 
 const db = Database.getInstance(config, queries);
 
-// El ID del usuario se inyecta automáticamente en el perfil
+// The user ID is automatically injected into the profile
 const dependencies: Dependency[] = [
   { sourceIndex: 0, targetIndex: 1, targetParamIndex: 0 },
 ];
@@ -198,50 +198,50 @@ 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
+    [null, "John's bio"], // null will be replaced by user.id
   ],
   dependencies
 );
 
-console.log("Usuario creado:", results[0].rows[0]);
-console.log("Perfil creado:", results[1].rows[0]);
+console.log("User created:", results[0].rows[0]);
+console.log("Profile created:", results[1].rows[0]);
 ```
 
 ---
 
-## 📊 Niveles de Log
+## 📊 Log Levels
 
 ```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)
+// 0 = NONE   - No logs
+// 1 = ERROR  - Only errors
+// 2 = DEBUG  - Errors + debug
+// 3 = ALL    - All logs (errors + debug + warnings + info)
 
 const config: DatabaseConfig = {
   connectionString: process.env.DATABASE_URL!,
   logLevel: 2, // DEBUG
 };
 
-// Cambiar dinámicamente
-db.setLogLevel(1); // Solo errores
+// Change dynamically
+db.setLogLevel(1); // Only errors
 ```
 
 ---
 
 ## 🔄 Backward Compatibility
 
-El paquete es 100% compatible con código existente:
+The package is 100% compatible with existing code:
 
 ```typescript
-// ✅ Forma antigua (sigue funcionando)
+// ✅ Old style (still works)
 const db = Database.getInstance(config, {
   getUser: "SELECT * FROM users WHERE id = $1",
 });
 await db.query("getUser", [123]);
 
-// ✅ Forma nueva (con autocompletado)
+// ✅ New style (with autocomplete)
 const queries = createQueries({
   users: {
     getById: "SELECT * FROM users WHERE id = $1",
@@ -255,7 +255,7 @@ await db.query(queries.users.getById, [123]);
 
 ## 🛡️ TypeScript
 
-El paquete incluye definiciones de tipos completas:
+The package includes complete type definitions:
 
 ```typescript
 import {
@@ -276,15 +276,15 @@ import {
 
 ### `createQueries(queries)`
 
-Crea un objeto de queries con autocompletado.
+Creates a query object with autocomplete.
 
-**Parámetros:**
+**Parameters:**
 
-- `queries: Record<string, any>` - Objeto con queries (planas, anidadas o mixtas)
+- `queries: Record<string, any>` - Object with queries (flat, nested, or mixed)
 
-**Retorna:** Objeto con queries y `__flatMap` interno
+**Returns:** Object with queries and internal `__flatMap`
 
-**Ejemplo:**
+**Example:**
 
 ```typescript
 const queries = createQueries({
@@ -298,16 +298,16 @@ const queries = createQueries({
 
 ### `Database.getInstance(config, queries)`
 
-Obtiene la instancia singleton de Database.
+Gets the singleton Database instance.
 
-**Parámetros:**
+**Parameters:**
 
-- `config: DatabaseConfig` - Configuración de conexión
-- `queries?: any` - Resultado de `createQueries()` o objeto plano
+- `config: DatabaseConfig` - Connection configuration
+- `queries?: any` - Result of `createQueries()` or plain object
 
-**Retorna:** `Database`
+**Returns:** `Database`
 
-**Ejemplo:**
+**Example:**
 
 ```typescript
 const db = Database.getInstance(config, queries);
@@ -317,22 +317,22 @@ const db = Database.getInstance(config, queries);
 
 ### `db.query(query, params?)`
 
-Ejecuta una query (con QueryReference, string key o raw SQL).
+Executes a query (with QueryReference, string key, or raw SQL).
 
-**Parámetros:**
+**Parameters:**
 
-- `query: string | QueryReference` - Query a ejecutar
-- `params?: any[]` - Parámetros de la query
+- `query: string | QueryReference` - Query to execute
+- `params?: any[]` - Query parameters
 
-**Retorna:** `Promise<QueryResult>`
+**Returns:** `Promise<QueryResult>`
 
-**Ejemplos:**
+**Examples:**
 
 ```typescript
-// Con QueryReference
+// With QueryReference
 await db.query(queries.users.getById, [123]);
 
-// Con string key
+// With string key
 await db.query("users.getById", [123]);
 
 // Raw SQL
@@ -343,17 +343,17 @@ 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.
+Executes multiple queries in an atomic transaction.
 
-**Parámetros:**
+**Parameters:**
 
-- `queryArray: (string | QueryReference)[]` - Array de queries
-- `paramsArray: any[][]` - Parámetros para cada query
-- `dependencies?: Dependency[]` - Dependencias entre queries
+- `queryArray: (string | QueryReference)[]` - Array of queries
+- `paramsArray: any[][]` - Parameters for each query
+- `dependencies?: Dependency[]` - Dependencies between queries
 
-**Retorna:** `Promise<QueryResult[]>`
+**Returns:** `Promise<QueryResult[]>`
 
-**Ejemplo:**
+**Example:**
 
 ```typescript
 await db.transaction(
@@ -370,11 +370,11 @@ await db.transaction(
 
 ### `db.close()`
 
-Cierra todas las conexiones del pool.
+Closes all pool connections.
 
-**Retorna:** `Promise<void>`
+**Returns:** `Promise<void>`
 
-**Ejemplo:**
+**Example:**
 
 ```typescript
 await db.close();
@@ -384,21 +384,48 @@ await db.close();
 
 ### `db.setLogLevel(level)`
 
-Cambia el nivel de log dinámicamente.
+Dynamically changes the log level.
 
-**Parámetros:**
+**Parameters:**
 
-- `level: 0 | 1 | 2 | 3` - Nuevo nivel de log
+- `level: 0 | 1 | 2 | 3` - New log level
 
-**Ejemplo:**
+**Example:**
 
 ```typescript
-db.setLogLevel(1); // Solo errores
+db.setLogLevel(1); // Only errors
 ```
 
 ---
 
-## 🔒 Cerrar Conexiones
+### `db.bulkInsert(table, columns, rows, options?)`
+
+Uses `COPY … FROM STDIN` to insert many records natively.
+
+**Parameters:**
+
+- `table`: target table name
+- `columns`: columns to populate (ordered)
+- `rows`: matrix with values (each row can have `null`)
+- `options?`: [`BulkInsertOptions`](./interfaces/BulkInsertOptions.ts) to set delimiter and add header
+
+**Example:**
+
+```ts
+await db.bulkInsert(
+  "test_users",
+  ["name", "email"],
+  [
+    ["Bulk 1", "bulk1@example.com"],
+    ["Bulk 2", "bulk2@example.com"],
+  ],
+  { header: false }
+);
+```
+
+---
+
+## 🔒 Closing Connections
 
 ```typescript
 process.on("SIGTERM", async () => {
@@ -410,66 +437,42 @@ process.on("SIGTERM", async () => {
 
 ---
 
-## 🧪 Testing
-
-```bash
-npm test
-```
-
----
-
-## 📄 Licencia
+## 📄 License
 
 MIT
 
 ---
 
-## 🤝 Contribuir
+## 🤝 Contributing
 
-Issues y Pull Requests son bienvenidos en: https://github.com/Crane/database
+Issues and Pull Requests are welcome at: 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
-
----
+### v3.0.0 (Current)
 
-### `db.bulkInsert(table, columns, rows, options?)`
-
-Usa `COPY … FROM STDIN` para insertar muchos registros de forma nativa.
+- ✨ **NEW:** `bulkInsert()` method for high-performance bulk data loading using PostgreSQL's native `COPY ... FROM STDIN`.
+- 🚀 Bulk insert supports:
+  - Streaming large datasets as CSV directly to the database.
+  - Custom CSV delimiter and optional header row via `BulkInsertOptions`.
+  - Automatic quoting of table and column identifiers for safety.
+  - Full TypeScript typings for all parameters and options.
+  - Efficient handling of large inserts compared to multiple `INSERT` statements.
+- 📚 Documentation and usage examples for `bulkInsert()` added.
 
-**Parámetros:**
+### v2.0.0
 
-- `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
+- ✨ **NEW:** `createQueries()` with full autocomplete
+- ✨ **NEW:** Support for flat, nested, and mixed queries
+- ✨ **NEW:** `QueryReference` type for better DX
+- ✅ Backward compatible with v1.x.x
+- 📚 Updated documentation with examples
 
-**Ejemplo:**
+### v1.0.0
 
-```ts
-await db.bulkInsert(
-  "test_users",
-  ["name", "email"],
-  [
-    ["Bulk 1", "bulk1@example.com"],
-    ["Bulk 2", "bulk2@example.com"],
-  ],
-  { header: false }
-);
-```
+- 🎉 Initial release
+- Connection pooling
+- Transactions with dependencies
+- Configurable logging system

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crane-technologies/database",
-  "version": "2.1.0",
+  "version": "3.0.1",
   "description": "PostgreSQL database component with connection pooling, transactions, dependency management and TypeScript autocomplete",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",