mysql2-core 0.3.10 → 0.5.1

package/README.md

@@ -45,7 +45,7 @@ npm install mysql2 mysql2-core
             Pool            PoolConnection
 ```
 
-### Executor
+### DB and Transaction
 
 `Executor` defines the common database operations:
 
@@ -54,7 +54,7 @@ interface Executor {
   driver: string
   param(i: number): string
   execute(sql: string, args?: any[], ctx?: any): Promise<number>
-  executeBatch(statements: Statement[], firstAffected?: boolean, ctx?: any): Promise<number>
+  executeBatch(statements: Statement[], requireFirstAffected?: boolean, ctx?: any): Promise<number>
   query<T>(sql: string, args?: any[], m?: StringMap, bools?: Attribute[], ctx?: any): Promise<T[]>
   queryOne<T>(sql: string, args?: any[], m?: StringMap, bools?: Attribute[], ctx?: any): Promise<T | null>
   executeScalar<T>(sql: string, args?: any[], ctx?: any): Promise<T | null>
@@ -62,9 +62,16 @@ interface Executor {
 }
 ```
 
-### DB
+A **transaction** extends the same interface:
 
-`DB` extends `Executor` with transaction creation:
+```ts
+interface Transaction extends Executor {
+  commit(): Promise<void>
+  rollback(): Promise<void>
+}
+```
+
+A database implementation can start a transaction through:
 
 ```ts
 interface DB extends Executor {
@@ -72,17 +79,83 @@ interface DB extends Executor {
 }
 ```
 
-### Transaction
+This makes application-level persistence code independent from the concrete MySQL connection implementation.
 
-`Transaction` extends `Executor` with:
+
+## SQL Parameters
+
+The default MySQL parameter builder returns:
 
 ```ts
-interface Transaction extends Executor {
-  commit(): Promise<void>
-  rollback(): Promise<void>
+export function param(i: number): string {
+  return "?"
+}
+```
+
+The index is provided to support custom parameter syntaxes.
+
+For example:
+
+```ts
+const buildParam = (i: number) => `$${i}`
+```
+
+This allows the SQL generation layer to be reused by implementations that require different placeholder conventions.
+
+## Metadata
+
+The persistence helpers use `Attributes` to describe database fields:
+
+```ts
+const attrs = {
+  id: {
+    key: true,
+    type: "integer",
+  },
+  name: {
+    type: "string",
+  },
+  active: {
+    type: "boolean",
+    true: 1,
+    false: 0,
+  },
 }
 ```
 
+An attribute can define:
+
+```ts
+export interface Attribute {
+  name?: string
+  column?: string
+  type?: DataType
+  default?: string | number | Date | boolean
+  key?: boolean
+  noinsert?: boolean
+  noupdate?: boolean
+  version?: boolean
+  ignored?: boolean
+  true?: string | number
+  false?: string | number
+}
+```
+
+### Attribute options
+
+| Option     | Description                                                                 |
+| ---------- | --------------------------------------------------------------------------- |
+| `key`      | Marks the field as a key used to determine whether an object can be updated |
+| `column`   | Database column name when it differs from the object property               |
+| `default`  | Default value used when the object property is `null` or `undefined`        |
+| `noinsert` | Excludes the field from generated `INSERT` statements                       |
+| `noupdate` | Excludes the field from generated update expressions                        |
+| `ignored`  | Excludes the field from persistence                                         |
+| `version`  | Initializes the field to `1` when inserting                                 |
+| `true`     | Database value used when a boolean is `true`                                |
+| `false`    | Database value used when a boolean is `false`                               |
+| `type`     | Describes the data type and supports metadata consumers                     |
+
 ## Creating a Connection Pool
 
 ```ts
@@ -102,12 +175,15 @@ const pool = createPool({
 
 The library also supports the `max` option as an alias for `connectionLimit` when `connectionLimit` is not explicitly provided.
 
+--- 
+
 ## Using `PoolManager`
 
 `PoolManager` provides the `DB` implementation for a MySQL connection pool.
 
 ```ts
-import { createPool, PoolManager} from "mysql2-core"
+import { createPool } from "mysql2"
+import { PoolManager} from "mysql2-core"
 
 const pool = createPool({
   host: "localhost",
@@ -118,9 +194,22 @@ const pool = createPool({
 
 const db = new PoolManager(pool)
 
-const users = await db.query(
-  "SELECT id, name FROM users WHERE active = ?",
-  [1]
+interface User {
+  id: number
+  name: string
+  status: string
+}
+
+const users = await db.query<User>(
+  "select id, name from users where status = ?",
+  ["ACTIVE"]
+)
+
+const affectedRows = await db.execute(
+  {
+    query: "update users set status = ? where id = ?",
+    params: ["ACTIVE", 100]
+  }
 )
 ```
 
@@ -198,7 +287,25 @@ if (!user) {
 
 ## Execute Scalar
 
-`executeScalar()` returns the first column of the first row.
+`executeScalar()` is intended for queries that return a single scalar value.
+
+It is particularly useful for queries such as:
+
+```sql
+SELECT COUNT(*)
+SELECT MAX(id)
+SELECT MIN(id)
+```
+
+Example:
+
+```ts
+const maxId = await db.executeScalar<number>(
+  "SELECT MAX(id) FROM users"
+)
+```
+
+Another example:
 
 ```ts
 const username = await db.executeScalar<string>(
@@ -207,6 +314,8 @@ const username = await db.executeScalar<string>(
 )
 ```
 
+`executeScalar()` returns the first column of the first row.
+
 If there is no row, it returns `null`.
 
 ## Count
@@ -220,7 +329,9 @@ const total = await db.count(
 )
 ```
 
-A missing scalar result is returned as `0`.
+The result is always a `number`.
+
+If the scalar result is `null`, `count()` returns `0`.
 
 ## Transactions
 
@@ -240,9 +351,9 @@ try {
     [100, 2]
   )
 
-  await tx.commit()
+  await tx.commit() // release connection inside commit
 } catch (err) {
-  await tx.rollback()
+  await tx.rollback() // release connection inside rollback
   throw err
 }
 ```
@@ -251,6 +362,8 @@ try {
 
 The connection is released when `commit()` or `rollback()` completes.
 
+The transaction manager also protects against releasing the same connection more than once.
+
 ## Batch Execution
 
 Statements are represented by:
@@ -283,15 +396,15 @@ For multiple statements, the pool-level `executeBatch()` obtains a connection an
 
 The connection is released after completion.
 
-## `firstAffected`
+## `requireFirstAffected`
 
-`executeBatch()` supports an optional `firstAffected` flag:
+`executeBatch()` supports an optional `requireFirstAffected` flag:
 
 ```ts
 await db.executeBatch(statements, true)
 ```
 
-When `firstAffected` is `true`, the first statement determines whether the remaining statements are executed.
+When `requireFirstAffected` is `true`, the first statement determines whether the remaining statements are executed.
 
 If the first statement affects at least one row:
 
@@ -357,6 +470,8 @@ resource.multipleStatements = true
 
 Each statement is terminated with a semicolon when necessary, and parameters are flattened into a single parameter array.
 
+---
+
 ## Direct Connection Operations
 
 The library also exposes functions that work directly with a `Pool` or `PoolConnection`.
@@ -389,47 +504,36 @@ const rows = await query<User>(
 )
 ```
 
-## Connection Helpers
-
-The library provides promise-based wrappers around MySQL connection operations.
+## Connection and Transaction helpers
 
-### Get a connection
+The library exposes transaction helpers:
 
 ```ts
-import { getConnection } from "mysql2-core"
-
-const connection = await getConnection(pool)
-
-try {
-  // use connection
-} finally {
-  connection.release()
-}
+import { beginTransaction, commit, rollback } from "mysql2-core"
 ```
 
-### Begin a transaction
+Example:
 
 ```ts
-import { beginTransaction } from "mysql2-core"
-
-await beginTransaction(connection)
-```
+const connection = await getConnection(pool)
 
-### Commit
+try {
+  await beginTransaction(connection)
 
-```ts
-import { commit } from "mysql2-core"
+  await execute(
+    connection,
+    "insert into users(name) values(?)",
+    ["John"]
+  )
 
-await commit(connection)
+  await commit(connection) // release connection inside commit
+} catch (err) {
+  await rollback(connection) // release connection inside rollback
+  throw err
+}
 ```
 
-### Rollback
-
-```ts
-import { rollback } from "mysql2-core"
-
-await rollback(connection)
-```
+---
 
 ## Result Mapping
 
@@ -524,6 +628,8 @@ await db.execute(
 
 With `resource.string = true`, the object is serialized using `JSON.stringify()`.
 
+---
+
 ## Dynamic SQL Field Helpers
 
 ### `getFields()`
@@ -532,18 +638,24 @@ With `resource.string = true`, the object is serialized using `JSON.stringify()`
 
 ```ts
 const fields = getFields(
-  ["id", "name"],
+  ["id", "name", "invalid"],
   ["id", "name", "email"]
 )
 ```
 
+The resulting fields are:
+```text
+id
+name
+```
+
 ### `buildFields()`
 
 `buildFields()` produces a comma-separated SQL field list.
 
 ```ts
 const sqlFields = buildFields(
-  ["id", "name"],
+  ["id", "name", "invalid"],
   ["id", "name", "email"]
 )
 ```
@@ -560,6 +672,25 @@ When no valid fields are available, `buildFields()` returns:
 *
 ```
 
+Dynamic field names should still come from trusted or validated input because SQL parameters cannot be used for identifiers.
+
+```ts
+SELECT ${buildFields(fields, allowedFields)}
+FROM users
+```
+For example:
+```ts
+SELECT ${buildFields(["id", "name", "password", "status"], ["id", "name", "status"])}
+FROM users
+```
+
+returns:
+
+```ts
+SELECT id, name, status
+FROM users
+```
+
 ### `getMapField()`
 
 `getMapField()` returns a mapped field name when a mapping exists:
@@ -579,6 +710,8 @@ Result:
 id
 ```
 
+---
+
 ## Error Handling
 
 Database errors are passed through `buildError()`.
@@ -1266,40 +1399,42 @@ await executeBatchConnection(
 
 This allows the statements to participate in an existing transaction.
 
-## Transactions
+## Multiple Statements
+enables batch optimization by combining multiple SQL statements into a single MySQL request. This reduces the number of application-to-database round trips for batch operations. When disabled, statements are executed individually within the same transaction.
 
-The library exposes transaction helpers:
+`multipleStatements` is specifically a round-trip optimization.
 
-```ts
-import { beginTransaction, commit, rollback } from "mysql2-core"
-```
+It enables batch optimization by combining multiple SQL statements into a single MySQL request. This reduces the number of application-to-database round trips for batch operations. When disabled, statements are executed individually within the same transaction.
+```text
+multipleStatements = false
 
-Example:
+Application
+   │
+   ├── SQL 1 ──► MySQL
+   ├── SQL 2 ──► MySQL
+   ├── SQL 3 ──► MySQL
+   │
+   └── SQL 100 ─► MySQL
 
-```ts
-const connection = await getConnection(pool)
+≈ 100 database round trips
+```
 
-try {
-  await beginTransaction(connection)
+versus:
 
-  await execute(
-    connection,
-    "insert into users(name) values(?)",
-    ["John"]
-  )
+```text
+multipleStatements = true
 
-  await commit(connection)
-} catch (err) {
-  await rollback(connection)
-  throw err
-} finally {
-  connection.release()
-}
+Application
+   │
+   └── SQL 1; SQL 2; ...; SQL 100 ──► MySQL
+
+≈ 1 database round trip
 ```
 
-## Multiple Statements
+For a batch containing many relatively small statements, that can be a meaningful performance improvement.
+
 
-The batch transaction executor can optionally combine multiple statements into a single MySQL request.
+Anyway, `multipleStatements` depends on the configuration in ConnectionString. So, I use `multipleStatements` as a global configuration.
 
 Enable:
 
@@ -1309,10 +1444,18 @@ import { resource } from "mysql2-core"
 resource.multipleStatements = true
 ```
 
-The statements are combined and executed through `connection.query()`.
-
-This can reduce the number of database round trips for large batches.
+It gives you a simple deployment-level decision:
 
+```text
+Connection configuration
+        │
+        ▼
+resource.multipleStatements
+        │
+        ├── false → individual execution
+        │
+        └── true  → combined batch execution
+```
 ## Serialization
 
 `toArray()` prepares parameter values before they are passed to `mysql2`.
@@ -1538,10 +1681,455 @@ This architecture keeps applications lightweight, modular, and easy to maintain.
 * MySQL
 * [`mysql2`](https://www.npmjs.com/package/mysql2)
 
+## Important Notes
+
+Table names and column names are inserted into generated SQL and should therefore be treated as trusted configuration.
+
+Values are generally represented as query parameters, while SQL identifiers are generated from metadata.
+
+`buildToSave()` uses MySQL `INSERT ... ON DUPLICATE KEY UPDATE` semantics when key fields are available. The actual duplicate condition is determined by MySQL's unique indexes.
+
+The `version` attribute currently initializes a version field to `1` during insertion; it does not by itself provide optimistic-locking checks.
+
+MySQL affected-row counts should be interpreted according to MySQL semantics. In particular, an upsert that does not change an existing row can report zero affected rows.
+
 ## License
 
 MIT
 
+# mysql2-core
+
+`mysql2-core` is a lightweight TypeScript database utility library for MySQL applications built on top of [`mysql2`](https://www.npmjs.com/package/mysql2).
+
+It provides reusable abstractions for SQL execution, transactions, metadata-driven persistence, batch operations, and streaming/batch writers while keeping the underlying MySQL driver accessible.
+
+## Features
+
+* Promise-based MySQL execution helpers
+* `Executor`, `DB`, and `Transaction` abstractions
+* Transaction and connection management
+* Single-statement and batch execution
+* Optional MySQL multiple-statement execution
+* Metadata-driven insert/upsert generation
+* Configurable column mappings
+* Boolean value mapping
+* Default values
+* Ignored, insert-only, and update-only attributes
+* Version-field initialization
+* Scalar and count execution interfaces
+* Generic `save()` and `saveBatch()` helpers
+* `MySQLWriter`
+* `MySQLBatchWriter`
+* `MySQLStreamWriter`
+* Custom SQL parameter builders for different SQL dialect conventions
+* JSON serialization support for object parameters
+* Duplicate-key error normalization
+
+## Installation
+
+```bash
+npm install mysql2-core mysql2
+```
+
+## Basic Usage
+
+The library works with a `mysql2` pool or connection.
+
+```ts
+import mysql from "mysql2"
+import { execute, getConnection } from "mysql2-core"
+
+const pool = mysql.createPool({
+  host: "localhost",
+  user: "root",
+  password: "password",
+  database: "app",
+}).promise()
+
+const affected = await execute(
+  pool as any,
+  "update users set name = ? where id = ?",
+  ["John", 1],
+)
+
+console.log(affected)
+```
+
+For applications using the callback-oriented `mysql2` pool/connection types directly, the execution helpers operate on `Pool` and `PoolConnection`.
+
+## Generating Save Statements
+
+`buildToSave()` converts an object and its metadata into a SQL statement.
+
+```ts
+const attrs = {
+  id: {
+    key: true,
+    type: "integer",
+  },
+  name: {
+    type: "string",
+  },
+  active: {
+    type: "boolean",
+  },
+}
+
+const statement = buildToSave(
+  {
+    id: 10,
+    name: "John",
+    active: true,
+  },
+  "users",
+  attrs,
+)
+```
+
+When a key is available, the generated statement uses MySQL's duplicate-key upsert syntax:
+
+```sql
+insert into users(...)
+values(...)
+on duplicate key update ...
+```
+
+When the key is missing, the operation becomes a normal insert.
+
+## Saving Objects
+
+The `save()` helper combines statement generation and execution:
+
+```ts
+const affected = await save(
+  pool,
+  {
+    id: 10,
+    name: "John",
+    active: true,
+  },
+  "users",
+  attrs,
+)
+```
+
+The same helper can also receive a custom execution function:
+
+```ts
+const affected = await save(
+  async (sql, args) => {
+    return executor.execute(sql, args)
+  },
+  user,
+  "users",
+  attrs,
+)
+```
+
+This makes the SQL-building component usable with a custom database abstraction.
+
+## Batch Saving
+
+Multiple objects can be converted into statements with:
+
+```ts
+const statements = buildToSaveBatch(
+  users,
+  "users",
+  attrs,
+)
+```
+
+Or directly executed:
+
+```ts
+const affected = await saveBatch(
+  pool,
+  users,
+  "users",
+  attrs,
+)
+```
+
+Multiple statements are executed inside a transaction.
+
+## Batch Execution
+
+Use `executeBatch()` for a collection of SQL statements:
+
+```ts
+const count = await executeBatch(pool, [
+  {
+    query: "update users set active = ? where id = ?",
+    params: [true, 1],
+  },
+  {
+    query: "update users set active = ? where id = ?",
+    params: [false, 2],
+  },
+])
+```
+
+For multiple statements, the helper obtains a connection, starts a transaction, executes the statements, and commits the transaction.
+
+If an execution fails, the transaction is rolled back and the original error is re-thrown.
+
+## Multiple Statements
+
+The library can optionally combine statements into one MySQL request.
+
+```ts
+resource.multipleStatements = true
+```
+
+When enabled, statements are concatenated with semicolons and executed together.
+
+When disabled, statements are executed individually inside the same transaction.
+
+For safety, table names and column names should always come from trusted application configuration and should never be derived directly from untrusted input.
+
+## Transactions
+
+Connection and transaction helpers are available directly:
+
+```ts
+const connection = await getConnection(pool)
+
+await beginTransaction(connection)
+
+try {
+  await execute(connection, "update ...", [...])
+  await execute(connection, "insert ...", [...])
+
+  await commit(connection)
+} catch (err) {
+  await rollback(connection)
+  throw err
+}
+```
+
+The batch execution APIs already provide this transaction handling automatically.
+
+## Boolean Mapping
+
+Boolean attributes can specify the values stored in MySQL:
+
+```ts
+const attrs = {
+  active: {
+    type: "boolean",
+    true: 1,
+    false: 0,
+  },
+}
+```
+
+The generated parameters become:
+
+```text
+true  -> 1
+false -> 0
+```
+
+Custom values are supported:
+
+```ts
+const attrs = {
+  active: {
+    type: "boolean",
+    true: "Y",
+    false: "N",
+  },
+}
+```
+
+## Object Parameters
+
+`toArray()` normalizes query parameters.
+
+By default, JavaScript objects are passed to the MySQL driver as objects.
+
+The library can optionally serialize object values to JSON:
+
+```ts
+resource.string = true
+```
+
+Dates are preserved as `Date` objects.
+
+## Duplicate Errors
+
+MySQL duplicate-key errors are normalized by `buildError()`.
+
+For:
+
+```text
+ER_DUP_ENTRY
+errno = 1062
+```
+
+the error receives:
+
+```ts
+error = "duplicate"
+```
+
+This allows application code to recognize duplicate persistence failures without depending entirely on MySQL's error-code representation.
+
+## Writers
+
+### MySQLWriter
+
+`MySQLWriter<T>` provides a reusable object writer.
+
+```ts
+const writer = new MySQLWriter(
+  pool,
+  "users",
+  attrs,
+)
+
+await writer.write({
+  id: 1,
+  name: "John",
+  active: true,
+})
+```
+
+An optional mapper can transform the object before persistence:
+
+```ts
+const writer = new MySQLWriter(
+  pool,
+  "users",
+  attrs,
+  false,
+  user => ({
+    ...user,
+    name: user.name.trim(),
+  }),
+)
+```
+
+The `oneIfSuccess` option converts a positive affected-row count into `1`:
+
+```ts
+const writer = new MySQLWriter(
+  pool,
+  "users",
+  attrs,
+  true,
+)
+```
+
+## MySQLBatchWriter
+
+`MySQLBatchWriter<T>` accepts a collection of objects and writes them as one transactional batch.
+
+```ts
+const writer = new MySQLBatchWriter(
+  pool,
+  "users",
+  attrs,
+)
+
+await writer.write(users)
+```
+
+A mapper can also be supplied:
+
+```ts
+const writer = new MySQLBatchWriter(
+  pool,
+  "users",
+  attrs,
+  user => ({
+    ...user,
+    name: user.name.trim(),
+  }),
+)
+```
+
+## MySQLStreamWriter
+
+`MySQLStreamWriter<T>` accumulates objects until a configurable batch size is reached.
+
+```ts
+const writer = new MySQLStreamWriter(
+  pool,
+  "users",
+  attrs,
+  1000,
+)
+
+for (const user of users) {
+  await writer.write(user)
+}
+
+await writer.flush()
+```
+
+This is useful when processing large collections without building one large SQL request.
+
+The final `flush()` should be called after the input stream has ended so that the remaining objects are persisted.
+
+## Number Conversion
+
+`toString()` converts valid JavaScript numbers into SQL-safe numeric literals:
+
+```ts
+toString(123)
+// "123"
+
+toString(NaN)
+// "null"
+
+toString(Infinity)
+// "null"
+```
+
+Non-finite numbers are represented as SQL `null`.
+
+## Design
+
+`mysql2-core` intentionally keeps the persistence model small.
+
+The library does not attempt to become a full ORM. Instead, it provides a thin layer around:
+
+```text
+mysql2
+   │
+   ├── connection / pool
+   ├── query execution
+   └── transactions
+          │
+          ▼
+     mysql2-core
+          │
+          ├── Executor
+          ├── Metadata
+          ├── SQL builders
+          ├── save helpers
+          └── writers
+```
+
+The application remains responsible for defining its entities, metadata, business rules, and queries.
+
+## Important Notes
+
+Table names and column names are inserted into generated SQL and should therefore be treated as trusted configuration.
+
+Values are generally represented as query parameters, while SQL identifiers are generated from metadata.
+
+`buildToSave()` uses MySQL `INSERT ... ON DUPLICATE KEY UPDATE` semantics when key fields are available. The actual duplicate condition is determined by MySQL's unique indexes.
+
+The `version` attribute currently initializes a version field to `1` during insertion; it does not by itself provide optimistic-locking checks.
+
+MySQL affected-row counts should be interpreted according to MySQL semantics. In particular, an upsert that does not change an existing row can report zero affected rows.
+
+## License
+
+MIT2
 
 
 # mysql2-core