@simplysm/orm-node 13.0.84 → 13.0.86

package/README.md

@@ -1,33 +1,61 @@
 # @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.
+Node.js용 ORM 모듈. MySQL, PostgreSQL, MSSQL(Azure 포함) 데이터베이스를 지원한다.
 
-## Installation
+## 설치
 
 ```bash
 npm install @simplysm/orm-node
 ```
 
-Install the peer dependency for your target database:
+사용하는 DB에 따라 드라이버를 추가로 설치한다 (모두 optional peerDependency):
 
-| Database   | Peer dependency                  |
-|------------|----------------------------------|
-| MySQL      | `mysql2`                         |
-| MSSQL      | `tedious`                        |
-| PostgreSQL | `pg` + `pg-copy-streams`         |
+```bash
+npm install mysql2                 # MySQL
+npm install pg pg-copy-streams     # PostgreSQL
+npm install tedious                # MSSQL / Azure SQL
+```
+
+**의존성:** `@simplysm/core-common`, `@simplysm/orm-common`, `generic-pool`, `consola`
+
+## 아키텍처 개요
+
+```
+createOrm()                  -- 최상위 팩토리 (ORM 인스턴스)
+  └─ NodeDbContextExecutor   -- DbContextExecutor 구현체
+       └─ createDbConn()     -- 커넥션 풀에서 PooledDbConn 획득
+            └─ PooledDbConn  -- 풀 래퍼
+                 └─ MysqlDbConn / PostgresqlDbConn / MssqlDbConn  -- 실제 연결
+```
+
+- `createOrm` -- `@simplysm/orm-common`의 `DbContext`와 DB 연결을 결합하는 고수준 API
+- `NodeDbContextExecutor` -- `QueryDef` → SQL 변환 및 실행을 담당하는 어댑터
+- `createDbConn` -- `generic-pool` 기반 커넥션 풀에서 연결을 획득
+- `PooledDbConn` -- 풀에서 빌린 물리 연결을 감싸는 래퍼 (반환 시 자동 롤백)
+- `MysqlDbConn` / `PostgresqlDbConn` / `MssqlDbConn` -- 각 DBMS별 실제 연결 구현
+
+## 주요 사용법
 
-## Quick Start
+### ORM 인스턴스 생성 및 트랜잭션
 
 ```typescript
-import { defineDbContext, queryable } from "@simplysm/orm-common";
 import { createOrm } from "@simplysm/orm-node";
+import { defineDbContext, Table } from "@simplysm/orm-common";
+
+// 1. 테이블 및 DbContext 정의 (orm-common)
+const User = Table("user")
+  .columns((c) => ({ id: c.int().autoIncrement(), name: c.varchar(100) }))
+  .primaryKey("id");
+
+const Order = Table("order")
+  .columns((c) => ({ id: c.int().autoIncrement(), userId: c.int(), amount: c.decimal(10, 2) }))
+  .primaryKey("id");
 
-// 1. Define a DbContext
 const MyDb = defineDbContext({
-  user: (db) => queryable(db, User),
+  tables: { user: User, order: Order },
 });
 
-// 2. Create an ORM instance
+// 2. ORM 인스턴스 생성
 const orm = createOrm(MyDb, {
   dialect: "mysql",
   host: "localhost",
@@ -37,24 +65,242 @@ const orm = createOrm(MyDb, {
   database: "mydb",
 });
 
-// 3. Execute queries within a transaction
-const users = await orm.connect(async (db) => {
-  return await db.user().execute();
+// 3-a. 자동 트랜잭션 (commit/rollback 자동 처리)
+const result = await orm.connect(async (db) => {
+  const users = await db.user().execute();
+  await db.user().insert([{ name: "Alice" }]);
+  return users;
 });
 
-// 4. Execute queries without a transaction
-const users2 = await orm.connectWithoutTransaction(async (db) => {
+// 3-b. 트랜잭션 없이 실행
+const users = await orm.connectWithoutTransaction(async (db) => {
   return await db.user().execute();
 });
+
+// 3-c. 격리 수준 지정
+await orm.connect(async (db) => {
+  /* ... */
+}, "SERIALIZABLE");
+```
+
+### OrmOptions로 database/schema 오버라이드
+
+```typescript
+const orm = createOrm(MyDb, config, {
+  database: "other_db",    // config.database 대신 사용
+  schema: "custom_schema", // config.schema 대신 사용
+});
+```
+
+### 저수준 DB 연결
+
+```typescript
+import { createDbConn } from "@simplysm/orm-node";
+
+const conn = await createDbConn(config);
+await conn.connect();
+
+await conn.beginTransaction();
+try {
+  const rows = await conn.execute(["SELECT * FROM users"]);
+  await conn.executeParametrized("INSERT INTO users (name) VALUES (?)", ["Alice"]);
+  await conn.commitTransaction();
+} catch {
+  await conn.rollbackTransaction();
+}
+
+await conn.close();
+```
+
+### 벌크 인서트
+
+각 DBMS의 네이티브 벌크 API를 사용하여 최적 성능을 제공한다.
+
+```typescript
+await conn.bulkInsert("users", columnMetas, records);
+```
+
+| DBMS | 방식 |
+|------|------|
+| MySQL | `LOAD DATA LOCAL INFILE` (임시 CSV 파일) |
+| PostgreSQL | `COPY FROM STDIN` (스트림 기반 CSV) |
+| MSSQL | tedious `BulkLoad` API (네이티브) |
+
+## API 레퍼런스
+
+### `createOrm(dbContextDef, config, options?): Orm`
+
+ORM 인스턴스 팩토리. `defineDbContext`로 정의한 DbContext 정의와 연결 설정을 결합한다.
+
+```typescript
+function createOrm<TDef extends DbContextDef<any, any, any>>(
+  dbContextDef: TDef,
+  config: DbConnConfig,
+  options?: OrmOptions,
+): Orm<TDef>;
+```
+
+**`Orm<TDef>` 인터페이스:**
+
+| 속성/메서드 | 타입 | 설명 |
+|---|---|---|
+| `dbContextDef` | `TDef` (readonly) | DbContext 정의 |
+| `config` | `DbConnConfig` (readonly) | 연결 설정 |
+| `options` | `OrmOptions` (readonly, optional) | 옵션 |
+| `connect(callback, isolationLevel?)` | `Promise<R>` | 트랜잭션 내에서 콜백 실행 |
+| `connectWithoutTransaction(callback)` | `Promise<R>` | 트랜잭션 없이 콜백 실행 |
+
+**`OrmOptions` 인터페이스:**
+
+| 필드 | 타입 | 설명 |
+|---|---|---|
+| `database?` | `string` | config.database 대신 사용할 DB 이름 |
+| `schema?` | `string` | config.schema 대신 사용할 스키마 이름 |
+
+### `createDbConn(config): Promise<DbConn>`
+
+커넥션 풀에서 DB 연결을 획득하여 반환한다. 동일 config에 대해 풀이 공유된다.
+
+```typescript
+function createDbConn(config: DbConnConfig): Promise<DbConn>;
 ```
 
-## Documentation
+### `DbConn` 인터페이스
 
-| 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 |
+모든 DB 연결 구현체의 공통 인터페이스. `EventEmitter<{ close: void }>`를 상속한다.
+
+```typescript
+interface DbConn extends EventEmitter<{ close: void }> {
+  config: DbConnConfig;
+  isConnected: boolean;
+  isInTransaction: boolean;
+
+  connect(): Promise<void>;
+  close(): Promise<void>;
+  beginTransaction(isolationLevel?: IsolationLevel): Promise<void>;
+  commitTransaction(): Promise<void>;
+  rollbackTransaction(): Promise<void>;
+  execute(queries: string[]): Promise<Record<string, unknown>[][]>;
+  executeParametrized(query: string, params?: unknown[]): Promise<Record<string, unknown>[][]>;
+  bulkInsert(
+    tableName: string,
+    columnMetas: Record<string, ColumnMeta>,
+    records: Record<string, unknown>[],
+  ): Promise<void>;
+}
+```
+
+### `DbConnConfig` 타입
+
+`dialect` 필드로 분기되는 유니온 타입이다.
+
+```typescript
+type DbConnConfig = MysqlDbConnConfig | MssqlDbConnConfig | PostgresqlDbConnConfig;
+```
+
+**공통 필드:**
+
+| 필드 | 타입 | 설명 |
+|---|---|---|
+| `dialect` | `"mysql"` \| `"mssql"` \| `"mssql-azure"` \| `"postgresql"` | DBMS 종류 |
+| `host` | `string` | 호스트 |
+| `port?` | `number` | 포트 |
+| `username` | `string` | 사용자명 |
+| `password` | `string` | 비밀번호 |
+| `database?` | `string` | 데이터베이스명 |
+| `defaultIsolationLevel?` | `IsolationLevel` | 기본 격리 수준 |
+| `pool?` | `DbPoolConfig` | 커넥션 풀 설정 |
+
+**MSSQL/PostgreSQL 전용:**
+
+| 필드 | 타입 | 설명 |
+|---|---|---|
+| `schema?` | `string` | 스키마 (MSSQL 기본: `dbo`, PostgreSQL 기본: `public`) |
+
+**MSSQL 특수 dialect:**
+- `"mssql-azure"`: Azure SQL용. `encrypt: true`가 자동 적용됨.
+
+### `DbPoolConfig` 인터페이스
+
+```typescript
+interface DbPoolConfig {
+  min?: number;                    // 최소 연결 수 (기본: 1)
+  max?: number;                    // 최대 연결 수 (기본: 10)
+  acquireTimeoutMillis?: number;   // 획득 타임아웃 (기본: 30초)
+  idleTimeoutMillis?: number;      // 유휴 타임아웃 (기본: 30초)
+}
+```
+
+### `NodeDbContextExecutor`
+
+`@simplysm/orm-common`의 `DbContextExecutor` 인터페이스 구현체. `DbContext`가 내부적으로 사용한다.
+
+```typescript
+class NodeDbContextExecutor implements DbContextExecutor {
+  constructor(config: DbConnConfig);
+
+  connect(): Promise<void>;
+  close(): Promise<void>;
+  beginTransaction(isolationLevel?: IsolationLevel): Promise<void>;
+  commitTransaction(): Promise<void>;
+  rollbackTransaction(): Promise<void>;
+  executeParametrized(query: string, params?: unknown[]): Promise<Record<string, unknown>[][]>;
+  bulkInsert(tableName: string, columnMetas: Record<string, ColumnMeta>, records: DataRecord[]): Promise<void>;
+  executeDefs<T = DataRecord>(defs: QueryDef[], resultMetas?: (ResultMeta | undefined)[]): Promise<T[][]>;
+}
+```
+
+**`executeDefs` 동작:**
+- `QueryDef`를 dialect에 맞는 SQL로 변환 (`createQueryBuilder`)
+- `resultMetas`가 모두 `undefined`이면 → 결과 없는 쿼리로 판단하여 단일 배치 실행
+- `ResultMeta`가 있으면 → `parseQueryResult`로 타입 변환 적용
+
+### `PooledDbConn`
+
+`generic-pool`의 풀에서 물리 연결을 빌려 사용하는 래퍼 클래스.
+
+```typescript
+class PooledDbConn extends EventEmitter<{ close: void }> implements DbConn {
+  constructor(pool: Pool<DbConn>, initialConfig: DbConnConfig, getLastCreateError?: () => Error | undefined);
+}
+```
+
+**특징:**
+- `connect()`: 풀에서 물리 연결 획득
+- `close()`: 트랜잭션 진행 중이면 자동 롤백 후 풀에 반환 (실제 연결은 닫지 않음)
+- 물리 연결이 끊기면 `close` 이벤트 자동 전파
+
+### DB 연결 구현 클래스
+
+| 클래스 | 드라이버 | dialect |
+|---|---|---|
+| `MysqlDbConn` | `mysql2/promise` | `"mysql"` |
+| `PostgresqlDbConn` | `pg` + `pg-copy-streams` | `"postgresql"` |
+| `MssqlDbConn` | `tedious` | `"mssql"`, `"mssql-azure"` |
+
+모두 `EventEmitter<{ close: void }>`를 상속하고 `DbConn`을 구현한다. 드라이버 모듈은 `createDbConn` 호출 시 lazy import된다.
+
+### `getDialectFromConfig(config): Dialect`
+
+config에서 `Dialect`를 추출한다. `"mssql-azure"` → `"mssql"`로 변환된다.
+
+```typescript
+function getDialectFromConfig(config: DbConnConfig): Dialect;
+```
+
+### 상수
+
+| 상수 | 값 | 설명 |
+|---|---|---|
+| `DB_CONN_CONNECT_TIMEOUT` | 10초 (10,000ms) | 연결 타임아웃 |
+| `DB_CONN_DEFAULT_TIMEOUT` | 10분 (600,000ms) | 쿼리 기본 타임아웃 |
+| `DB_CONN_ERRORS.NOT_CONNECTED` | `"'Connection' is not connected."` | 미연결 에러 메시지 |
+| `DB_CONN_ERRORS.ALREADY_CONNECTED` | `"'Connection' is already connected."` | 중복 연결 에러 메시지 |
+
+### IsolationLevel 타입
+
+`@simplysm/orm-common`에서 제공하는 트랜잭션 격리 수준이다.
+
+```typescript
+type IsolationLevel = "READ_UNCOMMITTED" | "READ_COMMITTED" | "REPEATABLE_READ" | "SERIALIZABLE";
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/orm-node",
-  "version": "13.0.84",
+  "version": "13.0.86",
   "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/orm-common": "13.0.84",
-    "@simplysm/core-common": "13.0.84"
+    "@simplysm/core-common": "13.0.86",
+    "@simplysm/orm-common": "13.0.86"
   },
   "devDependencies": {
     "@types/pg": "^8.18.0",

package/docs/configuration.md

@@ -1,100 +0,0 @@
-# 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

@@ -1,158 +0,0 @@
-# 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

@@ -1,26 +0,0 @@
-# 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

@@ -1,93 +0,0 @@
-# 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

@@ -1,103 +0,0 @@
-# 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

@@ -1,67 +0,0 @@
-# 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.