@simplysm/orm-node 14.0.4 → 14.0.5

package/README.md

@@ -1,34 +1,74 @@
 # @simplysm/orm-node
 
-Node.js ORM runtime providing database connections for MySQL, MSSQL, and PostgreSQL with typed query execution.
+Node.js ORM module for the Simplysm framework. Provides database connections, query execution, and a high-level ORM factory for MySQL, MSSQL, and PostgreSQL.
 
 ## Installation
 
 ```bash
 npm install @simplysm/orm-node
+# or
+pnpm add @simplysm/orm-node
 ```
 
-Peer dependencies (install the driver for your database):
+Peer dependencies (install the driver for your DBMS):
 - MySQL: `mysql2`
 - MSSQL: `tedious`
 - PostgreSQL: `pg`, `pg-copy-streams`
 
-## Quick Start
+## API Overview
+
+### ORM Factory
+
+| Export | Type | Description |
+|--------|------|-------------|
+| [`createOrm`](./docs/orm-factory.md#createorm) | Function | Create an ORM instance with connection management |
+| [`Orm`](./docs/orm-factory.md#orm) | Interface | ORM instance type with `connect` and `connectWithoutTransaction` |
+| [`OrmOptions`](./docs/orm-factory.md#ormoptions) | Interface | ORM options (database/schema override) |
+
+### Query Execution
+
+| Export | Type | Description |
+|--------|------|-------------|
+| [`NodeDbContextExecutor`](./docs/orm-factory.md#nodedbcontextexecutor) | Class | Node.js `DbContextExecutor` implementation |
+
+### Connection
+
+| Export | Type | Description |
+|--------|------|-------------|
+| [`createDbConn`](./docs/connection.md#createdbconn) | Function | Create a low-level DB connection |
+| [`DbConn`](./docs/connection.md#dbconn) | Interface | Low-level DB connection interface |
+| [`MysqlDbConn`](./docs/connection.md#mysqldbconn) | Class | MySQL connection implementation |
+| [`MssqlDbConn`](./docs/connection.md#mssqldbconn) | Class | MSSQL connection implementation |
+| [`PostgresqlDbConn`](./docs/connection.md#postgresqldbconn) | Class | PostgreSQL connection implementation |
+
+### Config Types
+
+| Export | Type | Description |
+|--------|------|-------------|
+| [`DbConnConfig`](./docs/connection.md#dbconnconfig) | Type | Union of all dialect-specific configs |
+| [`MysqlDbConnConfig`](./docs/connection.md#mysqldbconnconfig) | Interface | MySQL connection config |
+| [`MssqlDbConnConfig`](./docs/connection.md#mssqldbconnconfig) | Interface | MSSQL connection config |
+| [`PostgresqlDbConnConfig`](./docs/connection.md#postgresqldbconnconfig) | Interface | PostgreSQL connection config |
+
+### Constants & Utilities
+
+| Export | Type | Description |
+|--------|------|-------------|
+| [`DB_CONN_CONNECT_TIMEOUT`](./docs/connection.md#db_conn_connect_timeout) | Constant | Connection timeout: 10,000ms (10s) |
+| [`DB_CONN_DEFAULT_TIMEOUT`](./docs/connection.md#db_conn_default_timeout) | Constant | Query timeout: 600,000ms (10min) |
+| [`DB_CONN_ERRORS`](./docs/connection.md#db_conn_errors) | Constant | Error message constants |
+| [`getDialectFromConfig`](./docs/connection.md#getdialectfromconfig) | Function | Extract `Dialect` from config (`mssql-azure` -> `mssql`) |
+
+## Usage Examples
+
+### Basic ORM Usage
 
 ```typescript
-import { defineDbContext, Table, expr } from "@simplysm/orm-common";
+import { defineDbContext } from "@simplysm/orm-common";
 import { createOrm } from "@simplysm/orm-node";
 
-const User = Table("User")
-  .columns((c) => ({
-    id: c.bigint().autoIncrement(),
-    name: c.varchar(100),
-    email: c.varchar(200).nullable(),
-  }))
-  .primaryKey("id");
-
 const MyDb = defineDbContext({
-  tables: { user: User },
+  tables: { user: User, post: Post },
 });
 
 const orm = createOrm(MyDb, {
@@ -40,215 +80,41 @@ const orm = createOrm(MyDb, {
   database: "mydb",
 });
 
-// With transaction
-await orm.connect(async (db) => {
-  await db.user().insert([{ name: "Gildong Hong" }]);
-  const users = await db.user().execute();
-  return users;
+// With transaction (auto commit/rollback)
+const users = await orm.connect(async (db) => {
+  return db.user().execute();
 });
 
 // Without transaction (for DDL or read-only)
 await orm.connectWithoutTransaction(async (db) => {
   await db.initialize();
-  const users = await db.user().execute();
-  return users;
 });
 ```
 
-## API Reference
-
-### Types
-
-#### DbConn (interface)
-
-Low-level database connection interface. Extends `EventEmitter<{ close: void }>`.
-
-| Field / Method | Type | Description |
-|---|---|---|
-| `config` | `DbConnConfig` | Connection configuration |
-| `isConnected` | `boolean` | Whether the connection is active |
-| `isInTransaction` | `boolean` | Whether a transaction is in progress |
-| `connect()` | `Promise<void>` | Establish connection |
-| `close()` | `Promise<void>` | Close connection |
-| `beginTransaction(isolationLevel?)` | `Promise<void>` | Start transaction |
-| `commitTransaction()` | `Promise<void>` | Commit transaction |
-| `rollbackTransaction()` | `Promise<void>` | Rollback transaction |
-| `execute(queries: string[])` | `Promise<Record<string, unknown>[][]>` | Execute SQL query array |
-| `executeParametrized(query, params?)` | `Promise<Record<string, unknown>[][]>` | Execute parameterized query |
-| `bulkInsert(tableName, columnMetas, records)` | `Promise<void>` | Native bulk insert (MSSQL: BulkLoad, MySQL: LOAD DATA, PostgreSQL: COPY) |
-
-#### DbConnConfig (type)
-
-```typescript
-type DbConnConfig = MysqlDbConnConfig | MssqlDbConnConfig | PostgresqlDbConnConfig;
-```
-
-#### MysqlDbConnConfig (interface)
-
-| Field | Type | Required | Description |
-|---|---|---|---|
-| `dialect` | `"mysql"` | Yes | Dialect identifier |
-| `host` | `string` | Yes | Server hostname |
-| `port` | `number` | No | Server port |
-| `username` | `string` | Yes | Login username |
-| `password` | `string` | Yes | Login password |
-| `database` | `string` | No | Default database |
-| `defaultIsolationLevel` | `IsolationLevel` | No | Default transaction isolation level |
-
-#### MssqlDbConnConfig (interface)
-
-| Field | Type | Required | Description |
-|---|---|---|---|
-| `dialect` | `"mssql" \| "mssql-azure"` | Yes | Dialect identifier |
-| `host` | `string` | Yes | Server hostname |
-| `port` | `number` | No | Server port |
-| `username` | `string` | Yes | Login username |
-| `password` | `string` | Yes | Login password |
-| `database` | `string` | No | Default database |
-| `schema` | `string` | No | Default schema (default: dbo) |
-| `defaultIsolationLevel` | `IsolationLevel` | No | Default transaction isolation level |
-
-#### PostgresqlDbConnConfig (interface)
-
-| Field | Type | Required | Description |
-|---|---|---|---|
-| `dialect` | `"postgresql"` | Yes | Dialect identifier |
-| `host` | `string` | Yes | Server hostname |
-| `port` | `number` | No | Server port |
-| `username` | `string` | Yes | Login username |
-| `password` | `string` | Yes | Login password |
-| `database` | `string` | No | Default database |
-| `schema` | `string` | No | Default schema (default: public) |
-| `defaultIsolationLevel` | `IsolationLevel` | No | Default transaction isolation level |
-
-#### getDialectFromConfig
-
-Extracts the `Dialect` from a `DbConnConfig`. Maps `"mssql-azure"` to `"mssql"`.
-
-```typescript
-function getDialectFromConfig(config: DbConnConfig): Dialect;
-```
-
-#### Constants
-
-| Constant | Value | Description |
-|---|---|---|
-| `DB_CONN_CONNECT_TIMEOUT` | `10000` | Connection establishment timeout (10 seconds) |
-| `DB_CONN_DEFAULT_TIMEOUT` | `600000` | Default query timeout (10 minutes) |
-| `DB_CONN_ERRORS` | `{ NOT_CONNECTED, ALREADY_CONNECTED }` | Standard error messages |
-
-### Connections
-
-#### MssqlDbConn (class)
-
-Implements `DbConn` using the `tedious` driver for Microsoft SQL Server.
-
-```typescript
-class MssqlDbConn implements DbConn {
-  constructor(tedious: typeof import("tedious"), config: MssqlDbConnConfig);
-}
-```
-
-#### MysqlDbConn (class)
-
-Implements `DbConn` using the `mysql2/promise` driver for MySQL.
-
-```typescript
-class MysqlDbConn implements DbConn {
-  constructor(mysql: typeof import("mysql2/promise"), config: MysqlDbConnConfig);
-}
-```
-
-#### PostgresqlDbConn (class)
-
-Implements `DbConn` using `pg` and `pg-copy-streams` drivers for PostgreSQL.
-
-```typescript
-class PostgresqlDbConn implements DbConn {
-  constructor(
-    pg: typeof import("pg"),
-    pgCopyStreams: typeof import("pg-copy-streams"),
-    config: PostgresqlDbConnConfig,
-  );
-}
-```
-
-### Core
-
-#### createDbConn
-
-Factory function that creates a `DbConn` instance with lazy-loaded drivers. The connection is NOT established -- call `connect()` separately.
-
-```typescript
-async function createDbConn(config: DbConnConfig): Promise<DbConn>;
-```
-
-#### NodeDbContextExecutor (class)
-
-Implements `DbContextExecutor` for Node.js. Bridges `DbConn` with the ORM's `QueryDef` system.
+### Low-Level Connection
 
 ```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[][]>;
-}
-```
+import { createDbConn } from "@simplysm/orm-node";
 
-#### createOrm
-
-Main factory function. Creates an `Orm` instance that manages `DbContext` creation and connection lifecycle.
+const conn = await createDbConn({
+  dialect: "postgresql",
+  host: "localhost",
+  port: 5432,
+  username: "postgres",
+  password: "password",
+  database: "mydb",
+});
 
-```typescript
-function createOrm<TDef extends DbContextDef<any, any, any>>(
-  dbContextDef: TDef,
-  config: DbConnConfig,
-  options?: OrmOptions,
-): Orm<TDef>;
+await conn.connect();
+const results = await conn.execute(["SELECT * FROM users"]);
+await conn.close();
 ```
 
-**Parameters:**
-
-| Parameter | Type | Description |
-|---|---|---|
-| `dbContextDef` | `DbContextDef` | Definition from `defineDbContext()` |
-| `config` | `DbConnConfig` | Database connection configuration |
-| `options` | `OrmOptions` | Optional overrides for database/schema |
-
-#### Orm (interface)
+### With OrmOptions Override
 
 ```typescript
-interface Orm<TDef extends DbContextDef<any, any, any>> {
-  readonly dbContextDef: TDef;
-  readonly config: DbConnConfig;
-  readonly options?: OrmOptions;
-
-  connect<R>(
-    callback: (conn: DbContextInstance<TDef>) => Promise<R>,
-    isolationLevel?: IsolationLevel,
-  ): Promise<R>;
-
-  connectWithoutTransaction<R>(
-    callback: (conn: DbContextInstance<TDef>) => Promise<R>,
-  ): Promise<R>;
-}
+const orm = createOrm(MyDb, config, {
+  database: "other_db",  // Override config.database
+  schema: "custom",      // Override config.schema
+});
 ```
-
-| Method | Description |
-|---|---|
-| `connect(callback, isolationLevel?)` | Create a new DbContext, connect with transaction, execute callback, auto-commit/rollback, close. |
-| `connectWithoutTransaction(callback)` | Create a new DbContext, connect without transaction, execute callback, close. |
-
-#### OrmOptions (interface)
-
-| Field | Type | Description |
-|---|---|---|
-| `database` | `string` | Override database name from config |
-| `schema` | `string` | Override schema name from config |

package/docs/connection.md

@@ -0,0 +1,252 @@
+# Connection
+
+Low-level database connection management for MySQL, MSSQL, and PostgreSQL.
+
+## createDbConn
+
+```typescript
+async function createDbConn(config: DbConnConfig): Promise<DbConn>
+```
+
+Factory function that creates a dialect-specific database connection. The connection is **not yet established** -- call `connect()` on the returned object.
+
+Driver modules are lazily loaded and cached:
+- `mysql`: `mysql2/promise`
+- `mssql`/`mssql-azure`: `tedious`
+- `postgresql`: `pg` + `pg-copy-streams`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `config` | `DbConnConfig` | Database connection configuration |
+
+Returns `MysqlDbConn`, `MssqlDbConn`, or `PostgresqlDbConn`.
+
+```typescript
+const conn = await createDbConn({
+  dialect: "mysql",
+  host: "localhost",
+  port: 3306,
+  username: "root",
+  password: "password",
+  database: "mydb",
+});
+
+await conn.connect();
+try {
+  const results = await conn.execute(["SELECT * FROM users"]);
+} finally {
+  await conn.close();
+}
+```
+
+## DbConn
+
+```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>;
+}
+```
+
+Low-level database connection interface. Extends `EventEmitter` from `@simplysm/core-common` and emits `close` events.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `config` | `DbConnConfig` | Connection configuration |
+| `isConnected` | `boolean` | Whether connection is established |
+| `isInTransaction` | `boolean` | Whether a transaction is active |
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `connect` | `() => Promise<void>` | Establish database connection |
+| `close` | `() => Promise<void>` | Close database connection |
+| `beginTransaction` | `(isolationLevel?) => Promise<void>` | Start transaction |
+| `commitTransaction` | `() => Promise<void>` | Commit transaction |
+| `rollbackTransaction` | `() => Promise<void>` | Rollback transaction |
+| `execute` | `(queries: string[]) => Promise<Record<string, unknown>[][]>` | Execute SQL query strings |
+| `executeParametrized` | `(query: string, params?: unknown[]) => Promise<Record<string, unknown>[][]>` | Execute parameterized query |
+| `bulkInsert` | `(tableName, columnMetas, records) => Promise<void>` | Native bulk insert |
+
+### Bulk Insert Implementation by Dialect
+
+| Dialect | Mechanism |
+|---------|-----------|
+| MySQL | `LOAD DATA LOCAL INFILE` (temporary CSV file) |
+| MSSQL | tedious `BulkLoad` API |
+| PostgreSQL | `COPY FROM STDIN` via pg-copy-streams |
+
+## MysqlDbConn
+
+```typescript
+class MysqlDbConn extends EventEmitter<{ close: void }> implements DbConn
+```
+
+MySQL connection implementation using the `mysql2/promise` library. Constructor:
+
+```typescript
+constructor(mysql: typeof import("mysql2/promise"), config: MysqlDbConnConfig)
+```
+
+## MssqlDbConn
+
+```typescript
+class MssqlDbConn extends EventEmitter<{ close: void }> implements DbConn
+```
+
+MSSQL/Azure SQL connection implementation using the `tedious` library. Constructor:
+
+```typescript
+constructor(tedious: typeof import("tedious"), config: MssqlDbConnConfig)
+```
+
+## PostgresqlDbConn
+
+```typescript
+class PostgresqlDbConn extends EventEmitter<{ close: void }> implements DbConn
+```
+
+PostgreSQL connection implementation using the `pg` and `pg-copy-streams` libraries. Constructor:
+
+```typescript
+constructor(pg: typeof import("pg"), pgCopyStreams: typeof import("pg-copy-streams"), config: PostgresqlDbConnConfig)
+```
+
+## DbConnConfig
+
+```typescript
+type DbConnConfig = MysqlDbConnConfig | MssqlDbConnConfig | PostgresqlDbConnConfig;
+```
+
+Union type of all dialect-specific connection configurations.
+
+## MysqlDbConnConfig
+
+```typescript
+interface MysqlDbConnConfig {
+  dialect: "mysql";
+  host: string;
+  port?: number;
+  username: string;
+  password: string;
+  database?: string;
+  defaultIsolationLevel?: IsolationLevel;
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `dialect` | `"mysql"` | Required | Must be `"mysql"` |
+| `host` | `string` | Required | Server hostname |
+| `port` | `number?` | `3306` | Server port |
+| `username` | `string` | Required | Login username |
+| `password` | `string` | Required | Login password |
+| `database` | `string?` | - | Default database name |
+| `defaultIsolationLevel` | `IsolationLevel?` | - | Default transaction isolation level |
+
+## MssqlDbConnConfig
+
+```typescript
+interface MssqlDbConnConfig {
+  dialect: "mssql" | "mssql-azure";
+  host: string;
+  port?: number;
+  username: string;
+  password: string;
+  database?: string;
+  schema?: string;
+  defaultIsolationLevel?: IsolationLevel;
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `dialect` | `"mssql" \| "mssql-azure"` | Required | `"mssql"` for on-premises, `"mssql-azure"` for Azure SQL |
+| `host` | `string` | Required | Server hostname |
+| `port` | `number?` | `1433` | Server port |
+| `username` | `string` | Required | Login username |
+| `password` | `string` | Required | Login password |
+| `database` | `string?` | - | Default database name |
+| `schema` | `string?` | `"dbo"` | Default schema |
+| `defaultIsolationLevel` | `IsolationLevel?` | - | Default transaction isolation level |
+
+## PostgresqlDbConnConfig
+
+```typescript
+interface PostgresqlDbConnConfig {
+  dialect: "postgresql";
+  host: string;
+  port?: number;
+  username: string;
+  password: string;
+  database?: string;
+  schema?: string;
+  defaultIsolationLevel?: IsolationLevel;
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `dialect` | `"postgresql"` | Required | Must be `"postgresql"` |
+| `host` | `string` | Required | Server hostname |
+| `port` | `number?` | `5432` | Server port |
+| `username` | `string` | Required | Login username |
+| `password` | `string` | Required | Login password |
+| `database` | `string?` | - | Default database name |
+| `schema` | `string?` | `"public"` | Default schema |
+| `defaultIsolationLevel` | `IsolationLevel?` | - | Default transaction isolation level |
+
+## DB_CONN_CONNECT_TIMEOUT
+
+```typescript
+const DB_CONN_CONNECT_TIMEOUT = 10 * 1000; // 10,000ms (10 seconds)
+```
+
+Timeout for establishing a database connection.
+
+## DB_CONN_DEFAULT_TIMEOUT
+
+```typescript
+const DB_CONN_DEFAULT_TIMEOUT = 10 * 60 * 1000; // 600,000ms (10 minutes)
+```
+
+Default timeout for query execution.
+
+## DB_CONN_ERRORS
+
+```typescript
+const DB_CONN_ERRORS = {
+  NOT_CONNECTED: "'Connection'이 연결되어 있지 않습니다.",
+  ALREADY_CONNECTED: "'Connection'이 이미 연결되어 있습니다.",
+} as const;
+```
+
+Error message constants for connection state validation.
+
+| Key | Value | Description |
+|-----|-------|-------------|
+| `NOT_CONNECTED` | Connection is not established | Thrown when operating on a closed connection |
+| `ALREADY_CONNECTED` | Connection is already established | Thrown when connecting an already-connected instance |
+
+## getDialectFromConfig
+
+```typescript
+function getDialectFromConfig(config: DbConnConfig): Dialect
+```
+
+Extracts the `Dialect` type from a connection config. Maps `"mssql-azure"` to `"mssql"`, passes through others unchanged.
+
+| Input `config.dialect` | Output `Dialect` |
+|------------------------|------------------|
+| `"mysql"` | `"mysql"` |
+| `"mssql"` | `"mssql"` |
+| `"mssql-azure"` | `"mssql"` |
+| `"postgresql"` | `"postgresql"` |

package/docs/orm-factory.md

@@ -0,0 +1,117 @@
+# ORM Factory & Query Execution
+
+High-level ORM instance creation and Node.js query execution.
+
+## createOrm
+
+```typescript
+function createOrm<TDef extends DbContextDef<any, any, any>>(
+  dbContextDef: TDef,
+  config: DbConnConfig,
+  options?: OrmOptions,
+): Orm<TDef>
+```
+
+Creates an ORM instance that manages DbContext creation and database connections. Each `connect()` or `connectWithoutTransaction()` call creates a fresh DbContext and connection.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `dbContextDef` | `DbContextDef` | DbContext definition from `defineDbContext()` |
+| `config` | `DbConnConfig` | Database connection configuration |
+| `options` | `OrmOptions?` | Optional overrides for database/schema |
+
+```typescript
+import { defineDbContext } from "@simplysm/orm-common";
+import { createOrm } from "@simplysm/orm-node";
+
+const MyDb = defineDbContext({
+  tables: { user: User, post: Post },
+});
+
+const orm = createOrm(MyDb, {
+  dialect: "mysql",
+  host: "localhost",
+  port: 3306,
+  username: "root",
+  password: "password",
+  database: "mydb",
+});
+
+// Transaction mode
+await orm.connect(async (db) => {
+  const users = await db.user().execute();
+  await db.post().insert([{ title: "Hello", authorId: users[0].id }]);
+  return users;
+});
+
+// No-transaction mode (for DDL, read-only)
+await orm.connectWithoutTransaction(async (db) => {
+  await db.initialize();
+});
+```
+
+## Orm
+
+```typescript
+interface Orm<TDef extends DbContextDef<any, any, any>> {
+  readonly dbContextDef: TDef;
+  readonly config: DbConnConfig;
+  readonly options?: OrmOptions;
+  connect<R>(callback: (conn: DbContextInstance<TDef>) => Promise<R>, isolationLevel?: IsolationLevel): Promise<R>;
+  connectWithoutTransaction<R>(callback: (conn: DbContextInstance<TDef>) => Promise<R>): Promise<R>;
+}
+```
+
+ORM instance returned by `createOrm()`.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `dbContextDef` | `TDef` | The DbContext definition |
+| `config` | `DbConnConfig` | The connection configuration |
+| `options` | `OrmOptions?` | The ORM options |
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `connect` | `<R>(callback: (conn) => Promise<R>, isolationLevel?) => Promise<R>` | Open connection, begin transaction, execute callback, commit (auto-rollback on error), close |
+| `connectWithoutTransaction` | `<R>(callback: (conn) => Promise<R>) => Promise<R>` | Open connection, execute callback, close (no transaction) |
+
+## OrmOptions
+
+```typescript
+interface OrmOptions {
+  database?: string;
+  schema?: string;
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `database` | `string?` | Override the database name from `DbConnConfig` |
+| `schema` | `string?` | Override the schema name (MSSQL: dbo, PostgreSQL: public) |
+
+## NodeDbContextExecutor
+
+```typescript
+class NodeDbContextExecutor implements DbContextExecutor {
+  constructor(config: DbConnConfig);
+}
+```
+
+Node.js implementation of `DbContextExecutor`. Manages a single database connection and provides query execution capabilities.
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `connect` | `() => Promise<void>` | Establish DB connection |
+| `close` | `() => Promise<void>` | Close DB connection |
+| `beginTransaction` | `(isolationLevel?: IsolationLevel) => Promise<void>` | Start transaction |
+| `commitTransaction` | `() => Promise<void>` | Commit transaction |
+| `rollbackTransaction` | `() => Promise<void>` | Rollback transaction |
+| `executeParametrized` | `(query: string, params?: unknown[]) => Promise<Record<string, unknown>[][]>` | Execute parameterized SQL query |
+| `bulkInsert` | `(tableName: string, columnMetas: Record<string, ColumnMeta>, records: DataRecord[]) => Promise<void>` | Bulk insert using native DB API |
+| `executeDefs` | `<T>(defs: QueryDef[], resultMetas?: (ResultMeta \| undefined)[]) => Promise<T[][]>` | Execute QueryDef array (builds SQL via `createQueryBuilder`, parses results via `parseQueryResult`) |
+
+The `executeDefs` method:
+1. Builds SQL from each QueryDef using the dialect-specific QueryBuilder
+2. If no resultMetas need data, combines all SQL into a single execution
+3. Otherwise executes each QueryDef individually
+4. Parses results using `parseQueryResult` when ResultMeta is provided

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/orm-node",
-  "version": "14.0.4",
+  "version": "14.0.5",
   "description": "심플리즘 패키지 - ORM (node)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -14,13 +14,14 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    "src"
+    "src",
+    "docs"
   ],
   "sideEffects": false,
   "dependencies": {
     "consola": "^3.4.2",
-    "@simplysm/core-common": "14.0.4",
-    "@simplysm/orm-common": "14.0.4"
+    "@simplysm/orm-common": "14.0.5",
+    "@simplysm/core-common": "14.0.5"
   },
   "devDependencies": {
     "@types/pg": "^8.20.0",