mysql2-core 0.3.2 → 0.3.4

package/README.md

@@ -1 +1,608 @@
-# mysql2-core
+# mysql2-core
+
+A lightweight MySQL database adapter built on top of **mysql2** for the **SQL Repository** framework.
+
+This library provides connection management, transaction handling, query execution, object mapping, batch operations, streaming, exporting, and health checking while remaining completely independent from SQL generation.
+
+Unlike traditional ORMs, this library **does not build SQL**. Instead, it executes SQL generated by the SQL Repository library (or any SQL source) and provides a clean, type-safe runtime layer.
+
+---
+
+# Philosophy
+
+This library has one responsibility:
+
+> **Execute SQL efficiently.**
+
+It intentionally separates SQL execution from SQL generation.
+
+```
+                Application
+                     │
+                     ▼
+            SQL Repository Library
+              (SQL Generation)
+                     │
+                     ▼
+              Executor Interface
+                     │
+                     ▼
+                MySQL Adapter
+                     │
+                     ▼
+                   mysql2
+                     │
+                     ▼
+                   MySQL
+```
+
+This separation makes the entire stack easier to maintain, test, and extend.
+
+---
+
+# Features
+
+- Built on top of **mysql2**
+- Connection Pool Management
+- Transaction Management
+- Query Execution
+- Command Execution
+- Batch Execution
+- Streaming Query Results
+- Bulk Data Import
+- CSV/Data Export
+- Object Mapping
+- Boolean Conversion
+- Database Health Check
+- Promise-based API
+- Repository Friendly
+- Zero ORM Dependencies
+
+---
+
+# Why Another MySQL Library?
+
+Most MySQL libraries are either:
+
+- Low-level drivers (`mysql2`)
+- Full-featured ORMs (TypeORM, Prisma, Sequelize)
+
+This library focuses on infrastructure.
+
+It provides:
+
+- Connection management
+- Transactions
+- Streaming
+- Batch execution
+- Repository integration
+
+without hiding SQL from developers.
+
+---
+
+# Architecture
+
+```
+                  Application
+                       │
+                       ▼
+              SQL Repository Layer
+                       │
+                       ▼
+               Executor Interface
+                       │
+                       ▼
+               MySQL Adapter
+        ┌──────────────┼──────────────┐
+        ▼              ▼              ▼
+    Connection     Transaction     Stream
+        │              │              │
+        └──────────────┼──────────────┘
+                       ▼
+                    mysql2
+                       │
+                       ▼
+                     MySQL
+```
+
+---
+
+# Installation
+
+```bash
+npm install mysql2
+```
+
+```bash
+npm install mysql2-core
+```
+
+---
+
+# Creating a Database
+
+```ts
+import { MySQLDB } from "mysql2-core"
+
+const db = new MySQLDB({
+
+    host: "localhost",
+
+    port: 3306,
+
+    database: "demo",
+
+    user: "root",
+
+    password: "password"
+
+})
+```
+
+---
+
+# Query
+
+```ts
+const users = await db.query<User>(
+
+    `
+    SELECT *
+    FROM users
+    WHERE age > ?
+    `,
+
+    [18]
+
+)
+```
+
+---
+
+# Execute
+
+```ts
+await db.execute(
+
+    `
+    UPDATE users
+    SET active = ?
+    WHERE id = ?
+    `,
+
+    [true, 10]
+
+)
+```
+
+---
+
+# Transactions
+
+```ts
+const tx = await db.beginTransaction()
+
+try {
+
+    await tx.execute(
+
+        `
+        INSERT INTO users(name)
+        VALUES(?)
+        `,
+
+        ["John"]
+
+    )
+
+    await tx.commit()
+
+}
+catch (err) {
+
+    await tx.rollback()
+
+}
+```
+
+---
+
+# Batch Execution
+
+```ts
+await db.executeBatch([
+
+    {
+
+        query:
+            "INSERT INTO users(name) VALUES(?)",
+
+        params:
+            ["John"]
+
+    },
+
+    {
+
+        query:
+            "INSERT INTO users(name) VALUES(?)",
+
+        params:
+            ["Jane"]
+
+    }
+
+])
+```
+
+---
+
+# Streaming
+
+Stream large result sets without loading everything into memory.
+
+```ts
+await db.stream(
+
+    "SELECT * FROM users",
+
+    [],
+
+    async user => {
+
+        console.log(user)
+
+    }
+
+)
+```
+
+Ideal for:
+
+- ETL
+- Migration
+- Reporting
+- Exporting millions of rows
+
+---
+
+# Bulk Writer
+
+Insert data efficiently.
+
+```ts
+const writer = new MySQLWriter(db)
+
+await writer.write(users)
+```
+
+---
+
+# Batch Writer
+
+```ts
+const writer = new MySQLBatchWriter(db)
+
+await writer.write(users)
+```
+
+---
+
+# Stream Writer
+
+```ts
+const writer = new MySQLStreamWriter(db)
+
+await writer.write(stream)
+```
+
+Useful for importing very large datasets.
+
+---
+
+# Export
+
+Export query results without loading everything into memory.
+
+```ts
+await exporter.export(
+
+    `
+    SELECT *
+    FROM users
+    `,
+
+    "users.csv"
+
+)
+```
+
+---
+
+# Object Mapping
+
+Rows are automatically mapped into TypeScript objects.
+
+```ts
+interface User {
+
+    id: number
+
+    name: string
+
+    active: boolean
+
+}
+```
+
+```ts
+const users = await db.query<User>(
+    sql
+)
+```
+
+---
+
+# Boolean Conversion
+
+Automatically converts database values.
+
+```
+0  -> false
+
+1  -> true
+
+NULL -> null
+```
+
+---
+
+# Health Check
+
+```ts
+const ok = await checker.check()
+```
+
+Perfect for
+
+- Kubernetes
+- Docker
+- Load Balancers
+- Monitoring
+
+---
+
+# Repository Integration
+
+Designed to work seamlessly with **SQL Repository**.
+
+```
+Application
+
+        │
+
+        ▼
+
+SqlRepository
+
+        │
+
+        ▼
+
+Executor
+
+        │
+
+        ▼
+
+MySQL Adapter
+
+        │
+
+        ▼
+
+mysql2
+```
+
+The repository layer never depends directly on mysql2.
+
+---
+
+# Connection Pool
+
+Internally the adapter manages a connection pool.
+
+```
+Application
+
+        │
+
+        ▼
+
+Pool Manager
+
+        │
+
+        ▼
+
+mysql2 Pool
+```
+
+Connection reuse improves performance.
+
+---
+
+# Transaction Model
+
+```
+Application
+
+        │
+
+        ▼
+
+Transaction
+
+        │
+
+        ▼
+
+PoolConnection
+
+        │
+
+        ▼
+
+mysql2
+```
+
+Transactions are isolated from application code.
+
+---
+
+# Error Handling
+
+Database errors are propagated as Promise rejections.
+
+```ts
+try {
+
+    await db.execute(sql)
+
+}
+catch(err){
+
+    console.error(err)
+
+}
+```
+
+---
+
+# Performance
+
+The adapter is designed for high throughput.
+
+Features include:
+
+- Connection Pooling
+- Prepared Statement Parameters
+- Batch Execution
+- Streaming Queries
+- Minimal Object Allocation
+- Thin Wrapper over mysql2
+
+---
+
+# Design Goals
+
+- Lightweight
+- Predictable
+- SQL-first
+- Repository Friendly
+- Driver Independent
+- Easy to Debug
+- Easy to Extend
+- High Performance
+- Low Memory Usage
+
+---
+
+# Comparison
+
+| Feature | mysql2-core | mysql2 | TypeORM |
+|----------|---------------|---------|----------|
+| Connection Pool | ✅ | ✅ | ✅ |
+| Transactions | ✅ | ✅ | ✅ |
+| Streaming | ✅ | ✅ | Partial |
+| Repository Support | ✅ | ❌ | ✅ |
+| Batch Execution | ✅ | Manual | Partial |
+| SQL Generation | ❌ | ❌ | ORM |
+| ORM | ❌ | ❌ | ✅ |
+| Lightweight | ✅ | ✅ | ❌ |
+
+---
+
+# Project Structure
+
+```
+MySQLDB
+│
+├── Connection Pool
+├── Transactions
+├── Query Execution
+├── Execute
+├── Batch Execute
+├── Stream
+├── Exporter
+├── Object Mapper
+├── Health Checker
+└── Utilities
+```
+
+---
+
+# Future Roadmap
+
+Future versions will introduce:
+
+- SQL AST Compiler integration
+- PostgreSQL Adapter
+- SQL Server Adapter
+- Oracle Adapter
+- SQLite Adapter
+- Dialect Abstraction
+- Prepared Statement Cache
+- Retry Policies
+- Metrics & Tracing
+- Connection Observability
+
+---
+
+# Relationship with SQL Repository
+
+This library is intended to be used together with the SQL Repository library.
+
+```
+                 SQL Repository
+           (Metadata + SQL Builder)
+
+                      │
+
+                      ▼
+
+               Executor Interface
+
+                      │
+
+        ┌─────────────┴─────────────┐
+
+        ▼                           ▼
+
+   MySQL Adapter             PostgreSQL Adapter
+
+        ▼                           ▼
+
+      mysql2                         pg
+```
+
+The SQL Repository library generates SQL.
+
+This library executes SQL.
+
+Together they provide a lightweight, SQL-first data access framework.
+
+---
+
+# License
+
+MIT License
+
+---
+
+# Contributing
+
+Contributions are welcome!
+
+Feel free to submit issues, feature requests, or pull requests to improve the project.

package/lib/build.js

@@ -5,7 +5,7 @@ function param(i) {
 }
 exports.param = param;
 function params(length, from) {
-  if (from === undefined || from == null) {
+  if (from == null) {
     from = 0;
   }
   var ps = [];
@@ -77,7 +77,7 @@ function buildToSave(obj, table, attrs, ver, buildParam, i) {
       pks.push(attr);
     }
     var v = o[k];
-    if (v === undefined || v == null) {
+    if (v == null) {
       v = attr.default;
     }
     if (v !== undefined && v != null && !attr.ignored && !attr.noinsert) {
@@ -139,7 +139,7 @@ function buildToSave(obj, table, attrs, ver, buildParam, i) {
         if (attr && !attr.key && !attr.ignored && !attr.noupdate) {
           var field = attr.column ? attr.column : k;
           var x = void 0;
-          if (v == null) {
+          if (v === null) {
             x = "null";
           }
           else if (v === "") {
@@ -197,7 +197,7 @@ function buildToSaveBatch(objs, table, attrs, ver, buildParam) {
       var k = ks_4[_a];
       var attr = attrs[k];
       var v = o[k];
-      if (v === undefined || v == null) {
+      if (v == null) {
         v = attr.default;
       }
       if (v != null && v !== undefined && !attr.ignored && !attr.noinsert) {
@@ -249,7 +249,7 @@ function buildToSaveBatch(objs, table, attrs, ver, buildParam) {
         if (attr && !attr.key && !attr.ignored && k !== ver && !attr.noupdate) {
           var field = attr.column ? attr.column : k;
           var x = void 0;
-          if (v == null) {
+          if (v === null) {
             x = "null";
           }
           else if (v === "") {

package/lib/index.js

@@ -1071,7 +1071,7 @@ var MySQLStreamWriter = (function () {
     else {
       var total_1 = this.list.length;
       var stmt = build_1.buildToSaveBatch(this.list, this.table, this.attributes, this.version, this.param);
-      if (stmt) {
+      if (stmt.length > 0) {
         if (this.executeBatch) {
           return this.executeBatch(stmt).then(function (r) {
             _this.list = [];
@@ -1126,7 +1126,7 @@ var MySQLBatchWriter = (function () {
       }
     }
     var stmts = build_1.buildToSaveBatch(list, this.table, this.attributes, this.version, this.param);
-    if (stmts && stmts.length > 0) {
+    if (stmts.length > 0) {
       if (this.execute) {
         if (this.oneIfSuccess) {
           return this.execute(stmts).then(function (ct) { return stmts.length; });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mysql2-core",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "mysql2-core",
   "main": "./lib/index.js",
   "types": "./src/index.ts",

package/src/build.ts

@@ -4,7 +4,7 @@ export function param(i: number): string {
   return "?"
 }
 export function params(length: number, from?: number): string[] {
-  if (from === undefined || from == null) {
+  if (from == null) {
     from = 0
   }
   const ps: string[] = []
@@ -80,7 +80,7 @@ export function buildToSave<T>(obj: T, table: string, attrs: Attributes, ver?: s
       pks.push(attr)
     }
     let v = o[k]
-    if (v === undefined || v == null) {
+    if (v == null) {
       v = attr.default
     }
     if (v !== undefined && v != null && !attr.ignored && !attr.noinsert) {
@@ -134,7 +134,7 @@ export function buildToSave<T>(obj: T, table: string, attrs: Attributes, ver?: s
         if (attr && !attr.key && !attr.ignored && !attr.noupdate) {
           const field = attr.column ? attr.column : k
           let x: string
-          if (v == null) {
+          if (v === null) {
             x = "null"
           } else if (v === "") {
             x = `''`
@@ -183,7 +183,7 @@ export function buildToSaveBatch<T>(objs: T[], table: string, attrs: Attributes,
     for (const k of ks) {
       const attr = attrs[k]
       let v = o[k]
-      if (v === undefined || v == null) {
+      if (v == null) {
         v = attr.default
       }
       if (v != null && v !== undefined && !attr.ignored && !attr.noinsert) {
@@ -229,7 +229,7 @@ export function buildToSaveBatch<T>(objs: T[], table: string, attrs: Attributes,
         if (attr && !attr.key && !attr.ignored && k !== ver && !attr.noupdate) {
           const field = attr.column ? attr.column : k
           let x: string
-          if (v == null) {
+          if (v === null) {
             x = "null"
           } else if (v === "") {
             x = `''`

package/src/index.ts

@@ -902,7 +902,7 @@ export class MySQLStreamWriter<T> {
     } else {
       const total = this.list.length
       const stmt = buildToSaveBatch(this.list, this.table, this.attributes, this.version, this.param)
-      if (stmt) {
+      if (stmt.length > 0) {
         if (this.executeBatch) {
           return this.executeBatch(stmt).then((r) => {
             this.list = []
@@ -961,7 +961,7 @@ export class MySQLBatchWriter<T> {
       }
     }
     const stmts = buildToSaveBatch(list, this.table, this.attributes, this.version, this.param)
-    if (stmts && stmts.length > 0) {
+    if (stmts.length > 0) {
       if (this.execute) {
         if (this.oneIfSuccess) {
           return this.execute(stmts).then((ct) => stmts.length)