@simplysm/orm-node 13.0.81 → 13.0.83

package/README.md

@@ -0,0 +1,60 @@
+# @simplysm/orm-node
+
+Node.js ORM module supporting MySQL, MSSQL (including Azure SQL), and PostgreSQL. Provides connection pooling, transaction management, bulk insert, and a high-level ORM factory that integrates with `@simplysm/orm-common` DbContext.
+
+## Installation
+
+```bash
+npm install @simplysm/orm-node
+```
+
+Install the peer dependency for your target database:
+
+| Database   | Peer dependency                  |
+|------------|----------------------------------|
+| MySQL      | `mysql2`                         |
+| MSSQL      | `tedious`                        |
+| PostgreSQL | `pg` + `pg-copy-streams`         |
+
+## Quick Start
+
+```typescript
+import { defineDbContext, queryable } from "@simplysm/orm-common";
+import { createOrm } from "@simplysm/orm-node";
+
+// 1. Define a DbContext
+const MyDb = defineDbContext({
+  user: (db) => queryable(db, User),
+});
+
+// 2. Create an ORM instance
+const orm = createOrm(MyDb, {
+  dialect: "mysql",
+  host: "localhost",
+  port: 3306,
+  username: "root",
+  password: "password",
+  database: "mydb",
+});
+
+// 3. Execute queries within a transaction
+const users = await orm.connect(async (db) => {
+  return await db.user().execute();
+});
+
+// 4. Execute queries without a transaction
+const users2 = await orm.connectWithoutTransaction(async (db) => {
+  return await db.user().execute();
+});
+```
+
+## Documentation
+
+| Category | File | Description |
+|----------|------|-------------|
+| ORM Factory | [docs/create-orm.md](docs/create-orm.md) | `createOrm` factory function, `Orm` and `OrmOptions` types |
+| Connections | [docs/connections.md](docs/connections.md) | `DbConn` interface, `MysqlDbConn`, `MssqlDbConn`, `PostgresqlDbConn` |
+| Connection Factory & Pooling | [docs/pooling.md](docs/pooling.md) | `createDbConn`, `PooledDbConn`, connection pool management |
+| Configuration | [docs/configuration.md](docs/configuration.md) | `DbConnConfig`, `DbPoolConfig`, dialect-specific config types |
+| Context Executor | [docs/context-executor.md](docs/context-executor.md) | `NodeDbContextExecutor` for DbContext integration |
+| Constants | [docs/constants.md](docs/constants.md) | Timeout values and error message constants |

package/docs/configuration.md

@@ -0,0 +1,100 @@
+# Configuration
+
+Connection configuration types used to establish database connections.
+
+## `DbConnConfig`
+
+Union type of all dialect-specific configurations:
+
+```typescript
+type DbConnConfig = MysqlDbConnConfig | MssqlDbConnConfig | PostgresqlDbConnConfig;
+```
+
+---
+
+## `MysqlDbConnConfig`
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `dialect` | `"mysql"` | Yes | Must be `"mysql"` |
+| `host` | `string` | Yes | Server hostname or IP |
+| `port` | `number` | No | Server port |
+| `username` | `string` | Yes | Login username |
+| `password` | `string` | Yes | Login password |
+| `database` | `string` | No | Default database name |
+| `defaultIsolationLevel` | `IsolationLevel` | No | Default transaction isolation level |
+| `pool` | `DbPoolConfig` | No | Connection pool settings |
+
+---
+
+## `MssqlDbConnConfig`
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `dialect` | `"mssql" \| "mssql-azure"` | Yes | Use `"mssql-azure"` for Azure SQL (enables encryption) |
+| `host` | `string` | Yes | Server hostname or IP |
+| `port` | `number` | No | Server port |
+| `username` | `string` | Yes | Login username |
+| `password` | `string` | Yes | Login password |
+| `database` | `string` | No | Default database name |
+| `schema` | `string` | No | Default schema (e.g., `dbo`) |
+| `defaultIsolationLevel` | `IsolationLevel` | No | Default transaction isolation level |
+| `pool` | `DbPoolConfig` | No | Connection pool settings |
+
+---
+
+## `PostgresqlDbConnConfig`
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `dialect` | `"postgresql"` | Yes | Must be `"postgresql"` |
+| `host` | `string` | Yes | Server hostname or IP |
+| `port` | `number` | No | Server port (default: 5432) |
+| `username` | `string` | Yes | Login username |
+| `password` | `string` | Yes | Login password |
+| `database` | `string` | No | Default database name |
+| `schema` | `string` | No | Default schema (e.g., `public`) |
+| `defaultIsolationLevel` | `IsolationLevel` | No | Default transaction isolation level |
+| `pool` | `DbPoolConfig` | No | Connection pool settings |
+
+---
+
+## `DbPoolConfig`
+
+Connection pool settings (applied via `generic-pool`).
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `min` | `number` | `1` | Minimum number of connections in the pool |
+| `max` | `number` | `10` | Maximum number of connections in the pool |
+| `acquireTimeoutMillis` | `number` | `30000` | Timeout for acquiring a connection (ms) |
+| `idleTimeoutMillis` | `number` | `30000` | Timeout before idle connections are destroyed (ms) |
+
+---
+
+## `IsolationLevel`
+
+Transaction isolation level (from `@simplysm/orm-common`):
+
+```typescript
+type IsolationLevel =
+  | "READ_UNCOMMITTED"
+  | "READ_COMMITTED"
+  | "REPEATABLE_READ"
+  | "SERIALIZABLE";
+```
+
+---
+
+## `getDialectFromConfig(config)`
+
+Utility that extracts the `Dialect` from a `DbConnConfig`. Maps `"mssql-azure"` to `"mssql"`.
+
+```typescript
+import { getDialectFromConfig } from "@simplysm/orm-node";
+
+getDialectFromConfig({ dialect: "mssql-azure", ... }); // => "mssql"
+getDialectFromConfig({ dialect: "mysql", ... });        // => "mysql"
+```
+
+**Returns:** `Dialect` (`"mysql" | "mssql" | "postgresql"`)

package/docs/connections.md

@@ -0,0 +1,158 @@
+# Connections
+
+Low-level database connection classes implementing the `DbConn` interface. Each class wraps a native driver for a specific DBMS.
+
+## `DbConn` Interface
+
+All connection classes implement this interface, which extends `EventEmitter<{ close: void }>`.
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `config` | `DbConnConfig` | Connection configuration |
+| `isConnected` | `boolean` | Whether the connection is active |
+| `isInTransaction` | `boolean` | Whether a transaction is in progress |
+
+### Methods
+
+#### `connect(): Promise<void>`
+
+Establishes the database connection.
+
+#### `close(): Promise<void>`
+
+Closes the database connection.
+
+#### `beginTransaction(isolationLevel?): Promise<void>`
+
+Begins a transaction with an optional isolation level. Defaults to `READ_UNCOMMITTED` if not specified in the method call or in the connection config's `defaultIsolationLevel`.
+
+#### `commitTransaction(): Promise<void>`
+
+Commits the current transaction.
+
+#### `rollbackTransaction(): Promise<void>`
+
+Rolls back the current transaction.
+
+#### `execute(queries): Promise<Record<string, unknown>[][]>`
+
+Executes an array of SQL query strings. Returns an array of result sets (one per query). Empty strings are skipped.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `queries` | `string[]` | SQL query strings |
+
+#### `executeParametrized(query, params?): Promise<Record<string, unknown>[][]>`
+
+Executes a single parameterized SQL query.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `query` | `string` | SQL query string |
+| `params` | `unknown[]` | Optional binding parameters |
+
+#### `bulkInsert(tableName, columnMetas, records): Promise<void>`
+
+Performs a high-performance bulk insert using native DBMS mechanisms.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `tableName` | `string` | Target table (e.g., `database.table` or `database.schema.table`) |
+| `columnMetas` | `Record<string, ColumnMeta>` | Column name to metadata mapping |
+| `records` | `Record<string, unknown>[]` | Records to insert |
+
+### Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `close` | `void` | Emitted when the connection is closed |
+
+---
+
+## `MysqlDbConn`
+
+MySQL connection using the `mysql2/promise` library.
+
+- **Bulk insert** uses `LOAD DATA LOCAL INFILE` with a temporary CSV file.
+- UUID and binary columns are stored via `UNHEX()` conversion.
+- Root user (`root`) connects without binding to a specific database.
+- Connection timeout: 10 minutes (auto-close after 20 minutes idle).
+
+```typescript
+import { MysqlDbConn } from "@simplysm/orm-node";
+
+const mysql = await import("mysql2/promise");
+const conn = new MysqlDbConn(mysql, {
+  dialect: "mysql",
+  host: "localhost",
+  port: 3306,
+  username: "root",
+  password: "password",
+  database: "mydb",
+});
+
+await conn.connect();
+const results = await conn.execute(["SELECT * FROM users"]);
+await conn.close();
+```
+
+---
+
+## `MssqlDbConn`
+
+MSSQL / Azure SQL connection using the `tedious` library.
+
+- **Bulk insert** uses tedious `BulkLoad` API.
+- Supports `mssql-azure` dialect for Azure SQL with encryption enabled.
+- Connection timeout: 10 seconds, query timeout: 10 minutes.
+- Auto-close after 20 minutes idle.
+
+```typescript
+import { MssqlDbConn } from "@simplysm/orm-node";
+
+const tedious = await import("tedious");
+const conn = new MssqlDbConn(tedious, {
+  dialect: "mssql",
+  host: "localhost",
+  port: 1433,
+  username: "sa",
+  password: "password",
+  database: "mydb",
+});
+
+await conn.connect();
+const results = await conn.execute(["SELECT * FROM users"]);
+await conn.close();
+```
+
+---
+
+## `PostgresqlDbConn`
+
+PostgreSQL connection using the `pg` library with `pg-copy-streams` for bulk operations.
+
+- **Bulk insert** uses `COPY FROM STDIN` with CSV format.
+- Binary columns use PostgreSQL `bytea` hex format (`\x...`).
+- Default port: 5432.
+- Connection timeout: 10 seconds, query timeout: 10 minutes.
+
+```typescript
+import { PostgresqlDbConn } from "@simplysm/orm-node";
+
+const pg = await import("pg");
+const pgCopyStreams = await import("pg-copy-streams");
+const conn = new PostgresqlDbConn(pg, pgCopyStreams, {
+  dialect: "postgresql",
+  host: "localhost",
+  port: 5432,
+  username: "postgres",
+  password: "password",
+  database: "mydb",
+});
+
+await conn.connect();
+const results = await conn.execute(["SELECT * FROM users"]);
+await conn.close();
+```

package/docs/constants.md

@@ -0,0 +1,26 @@
+# Constants
+
+Shared constants used across all connection implementations.
+
+## `DB_CONN_CONNECT_TIMEOUT`
+
+Connection establishment timeout.
+
+- **Value:** `10000` (10 seconds)
+- **Used by:** MSSQL (`connectTimeout`) and PostgreSQL (`connectionTimeoutMillis`)
+
+## `DB_CONN_DEFAULT_TIMEOUT`
+
+Default query execution timeout.
+
+- **Value:** `600000` (10 minutes)
+- **Used by:** All connection classes for query timeouts. Connections auto-close after `2x` this value (20 minutes) of inactivity.
+
+## `DB_CONN_ERRORS`
+
+Standard error messages for connection state violations.
+
+| Key | Value | Description |
+|-----|-------|-------------|
+| `NOT_CONNECTED` | `"'Connection' is not connected."` | Thrown when operating on a disconnected connection |
+| `ALREADY_CONNECTED` | `"'Connection' is already connected."` | Thrown when `connect()` is called on an active connection |

package/docs/context-executor.md

@@ -0,0 +1,93 @@
+# Context Executor
+
+## `NodeDbContextExecutor`
+
+A `DbContextExecutor` implementation for Node.js that bridges `@simplysm/orm-common` DbContext with actual database connections. Used internally by `createOrm`, but can also be used directly for lower-level control.
+
+### Constructor
+
+```typescript
+new NodeDbContextExecutor(config: DbConnConfig)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `config` | `DbConnConfig` | Database connection configuration |
+
+### Methods
+
+#### `connect(): Promise<void>`
+
+Acquires a connection from the pool and activates it.
+
+#### `close(): Promise<void>`
+
+Returns the connection to the pool.
+
+#### `beginTransaction(isolationLevel?): Promise<void>`
+
+Begins a transaction with an optional isolation level.
+
+#### `commitTransaction(): Promise<void>`
+
+Commits the current transaction.
+
+#### `rollbackTransaction(): Promise<void>`
+
+Rolls back the current transaction.
+
+#### `executeParametrized(query, params?): Promise<Record<string, unknown>[][]>`
+
+Executes a parameterized SQL query string.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `query` | `string` | SQL query string |
+| `params` | `unknown[]` | Optional query parameters |
+
+#### `bulkInsert(tableName, columnMetas, records): Promise<void>`
+
+Performs bulk insert using the native driver API.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `tableName` | `string` | Target table name |
+| `columnMetas` | `Record<string, ColumnMeta>` | Column metadata |
+| `records` | `DataRecord[]` | Records to insert |
+
+#### `executeDefs<T>(defs, resultMetas?): Promise<T[][]>`
+
+Executes an array of `QueryDef` objects. Converts each `QueryDef` to SQL using the appropriate dialect query builder, executes it, and parses results using optional `ResultMeta`.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `defs` | `QueryDef[]` | Query definitions to execute |
+| `resultMetas` | `(ResultMeta \| undefined)[]` | Optional result parsing metadata per query |
+
+**Optimization:** When all `resultMetas` are `undefined` (no result parsing needed), queries are combined into a single SQL batch for efficiency, returning empty arrays.
+
+### Usage
+
+```typescript
+import { NodeDbContextExecutor } from "@simplysm/orm-node";
+
+const executor = new NodeDbContextExecutor({
+  dialect: "postgresql",
+  host: "localhost",
+  username: "postgres",
+  password: "password",
+  database: "mydb",
+});
+
+await executor.connect();
+try {
+  await executor.beginTransaction();
+  const results = await executor.executeParametrized(
+    "SELECT * FROM users WHERE id = $1",
+    [1],
+  );
+  await executor.commitTransaction();
+} finally {
+  await executor.close();
+}
+```

package/docs/create-orm.md

@@ -0,0 +1,103 @@
+# ORM Factory
+
+High-level factory for creating ORM instances that manage DbContext lifecycle and transactions.
+
+## `createOrm(dbContextDef, config, options?)`
+
+Creates an `Orm` instance that binds a DbContext definition to a database connection configuration.
+
+```typescript
+import { defineDbContext, queryable } from "@simplysm/orm-common";
+import { createOrm } from "@simplysm/orm-node";
+
+const MyDb = defineDbContext({
+  user: (db) => queryable(db, User),
+  order: (db) => queryable(db, Order),
+});
+
+const orm = createOrm(MyDb, {
+  dialect: "mysql",
+  host: "localhost",
+  port: 3306,
+  username: "root",
+  password: "password",
+  database: "mydb",
+});
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `dbContextDef` | `DbContextDef` | DbContext definition created with `defineDbContext` |
+| `config` | `DbConnConfig` | Database connection configuration |
+| `options` | `OrmOptions` | Optional overrides for database/schema |
+
+**Returns:** `Orm<TDef>`
+
+## `Orm<TDef>`
+
+The object returned by `createOrm`.
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `dbContextDef` | `TDef` | The DbContext definition |
+| `config` | `DbConnConfig` | The connection configuration |
+| `options` | `OrmOptions \| undefined` | Optional overrides |
+
+### `orm.connect(callback, isolationLevel?)`
+
+Executes a callback within a transaction. The transaction is automatically committed on success and rolled back on error.
+
+```typescript
+const result = await orm.connect(async (db) => {
+  const users = await db.user().execute();
+  return users;
+}, "READ_COMMITTED");
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `callback` | `(conn: DbContextInstance<TDef>) => Promise<R>` | Callback receiving the DbContext instance |
+| `isolationLevel` | `IsolationLevel` | Optional transaction isolation level |
+
+**Returns:** `Promise<R>` -- the callback's return value.
+
+### `orm.connectWithoutTransaction(callback)`
+
+Executes a callback without wrapping in a transaction.
+
+```typescript
+const result = await orm.connectWithoutTransaction(async (db) => {
+  const users = await db.user().execute();
+  return users;
+});
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `callback` | `(conn: DbContextInstance<TDef>) => Promise<R>` | Callback receiving the DbContext instance |
+
+**Returns:** `Promise<R>` -- the callback's return value.
+
+## `OrmOptions`
+
+Options that override values from `DbConnConfig`.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `database` | `string \| undefined` | Database name (overrides config's `database`) |
+| `schema` | `string \| undefined` | Schema name (e.g., `dbo` for MSSQL, `public` for PostgreSQL) |
+
+```typescript
+const orm = createOrm(MyDb, config, {
+  database: "other_db",
+  schema: "custom_schema",
+});
+```

package/docs/pooling.md

@@ -0,0 +1,67 @@
+# Connection Factory & Pooling
+
+Connection pool management using the `generic-pool` library. Pools are keyed by configuration and reused automatically.
+
+## `createDbConn(config)`
+
+Factory function that acquires a pooled connection. Creates a new pool if none exists for the given configuration.
+
+```typescript
+import { createDbConn } from "@simplysm/orm-node";
+
+const conn = await createDbConn({
+  dialect: "mysql",
+  host: "localhost",
+  port: 3306,
+  username: "root",
+  password: "password",
+  database: "mydb",
+  pool: {
+    min: 2,
+    max: 20,
+  },
+});
+
+await conn.connect();
+// ... use connection ...
+await conn.close(); // returns connection to pool
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `config` | `DbConnConfig` | Database connection configuration |
+
+**Returns:** `Promise<DbConn>` -- a `PooledDbConn` wrapper.
+
+**Pool behavior:**
+
+- Pools are cached by a JSON-serialized configuration key.
+- Each pool validates connections on borrow (`testOnBorrow: true`).
+- Failed connection creation errors are tracked per pool.
+- Driver modules (`tedious`, `mysql2`, `pg`, `pg-copy-streams`) are lazy-loaded and cached.
+
+---
+
+## `PooledDbConn`
+
+A `DbConn` wrapper that manages borrowing from and returning connections to a pool. Implements the full `DbConn` interface via delegation.
+
+### Key Behaviors
+
+- **`connect()`** -- Acquires a physical connection from the pool. Throws if already connected.
+- **`close()`** -- Returns the connection to the pool (does **not** terminate the physical connection). If a transaction is in progress, it is rolled back first.
+- **Physical connection loss** -- If the underlying connection is lost (timeout, network error), the wrapper emits `close` and clears its reference. The pool's validation will discard the broken connection.
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `config` | `DbConnConfig` | Delegates to underlying connection's config |
+| `isConnected` | `boolean` | `true` if a physical connection is acquired and active |
+| `isInTransaction` | `boolean` | `true` if the underlying connection has an active transaction |
+
+### Methods
+
+All `DbConn` methods (`beginTransaction`, `commitTransaction`, `rollbackTransaction`, `execute`, `executeParametrized`, `bulkInsert`) are delegated to the underlying physical connection. Throws if no connection is acquired.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/orm-node",
-  "version": "13.0.81",
+  "version": "13.0.83",
   "description": "Simplysm package - ORM module (node)",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -21,8 +21,8 @@
   "dependencies": {
     "consola": "^3.4.2",
     "generic-pool": "^3.9.0",
-    "@simplysm/core-common": "13.0.81",
-    "@simplysm/orm-common": "13.0.81"
+    "@simplysm/orm-common": "13.0.83",
+    "@simplysm/core-common": "13.0.83"
   },
   "devDependencies": {
     "@types/pg": "^8.18.0",