@simplysm/orm-node 13.0.100 → 14.0.4

package/README.md

@@ -1,6 +1,6 @@
 # @simplysm/orm-node
 
-Simplysm package - ORM module (node). Provides database connection implementations for MySQL, MSSQL, and PostgreSQL, plus a high-level ORM factory for managing DbContext instances with transaction support.
+Node.js ORM runtime providing database connections for MySQL, MSSQL, and PostgreSQL with typed query execution.
 
 ## Installation
 
@@ -8,220 +8,247 @@ Simplysm package - ORM module (node). Provides database connection implementatio
 npm install @simplysm/orm-node
 ```
 
-Database drivers are loaded lazily. Install only the driver(s) you need:
+Peer dependencies (install the driver for your database):
+- MySQL: `mysql2`
+- MSSQL: `tedious`
+- PostgreSQL: `pg`, `pg-copy-streams`
 
-```bash
-npm install mysql2          # for MySQL
-npm install tedious         # for MSSQL / Azure SQL
-npm install pg pg-copy-streams  # for PostgreSQL
-```
+## Quick Start
 
-## API Overview
+```typescript
+import { defineDbContext, Table, expr } from "@simplysm/orm-common";
+import { createOrm } from "@simplysm/orm-node";
 
-### Types
+const User = Table("User")
+  .columns((c) => ({
+    id: c.bigint().autoIncrement(),
+    name: c.varchar(100),
+    email: c.varchar(200).nullable(),
+  }))
+  .primaryKey("id");
 
-| API | Type | Description |
-|-----|------|-------------|
-| `DbConn` | interface | Low-level DB connection interface |
-| `DbConnConfig` | type | Union of all connection config types |
-| `MysqlDbConnConfig` | interface | MySQL connection configuration |
-| `MssqlDbConnConfig` | interface | MSSQL connection configuration |
-| `PostgresqlDbConnConfig` | interface | PostgreSQL connection configuration |
-| `DB_CONN_CONNECT_TIMEOUT` | const | Connection timeout (10 seconds) |
-| `DB_CONN_DEFAULT_TIMEOUT` | const | Query default timeout (10 minutes) |
-| `DB_CONN_ERRORS` | const | Error message constants |
-| `getDialectFromConfig` | function | Extract Dialect from DbConnConfig |
+const MyDb = defineDbContext({
+  tables: { user: User },
+});
 
-### Connections
+const orm = createOrm(MyDb, {
+  dialect: "mysql",
+  host: "localhost",
+  port: 3306,
+  username: "root",
+  password: "password",
+  database: "mydb",
+});
 
-| API | Type | Description |
-|-----|------|-------------|
-| `MysqlDbConn` | class | MySQL connection (uses mysql2/promise) |
-| `MssqlDbConn` | class | MSSQL/Azure SQL connection (uses tedious) |
-| `PostgresqlDbConn` | class | PostgreSQL connection (uses pg) |
-| `createDbConn` | function | DB connection factory function |
+// With transaction
+await orm.connect(async (db) => {
+  await db.user().insert([{ name: "Gildong Hong" }]);
+  const users = await db.user().execute();
+  return users;
+});
 
-### Core
+// 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
 
-| API | Type | Description |
-|-----|------|-------------|
-| `NodeDbContextExecutor` | class | DbContextExecutor for Node.js |
-| `createOrm` | function | ORM factory function |
-| `Orm` | interface | ORM instance type |
-| `OrmOptions` | interface | ORM options (database/schema override) |
+### Types
 
----
+#### DbConn (interface)
 
-### `DbConnConfig`
+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`
+#### 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"`.
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `dialect` | `"mysql"` | Dialect identifier |
-| `host` | `string` | Server hostname |
-| `port` | `number?` | Server port |
-| `username` | `string` | Username |
-| `password` | `string` | Password |
-| `database` | `string?` | Database name |
-| `defaultIsolationLevel` | `IsolationLevel?` | Default transaction isolation level |
+```typescript
+function getDialectFromConfig(config: DbConnConfig): Dialect;
+```
 
-### `MssqlDbConnConfig`
+#### Constants
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `dialect` | `"mssql" \| "mssql-azure"` | Dialect identifier |
-| `host` | `string` | Server hostname |
-| `port` | `number?` | Server port |
-| `username` | `string` | Username |
-| `password` | `string` | Password |
-| `database` | `string?` | Database name |
-| `schema` | `string?` | Schema name |
-| `defaultIsolationLevel` | `IsolationLevel?` | Default transaction isolation level |
-
-### `PostgresqlDbConnConfig`
+| 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 |
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `dialect` | `"postgresql"` | Dialect identifier |
-| `host` | `string` | Server hostname |
-| `port` | `number?` | Server port |
-| `username` | `string` | Username |
-| `password` | `string` | Password |
-| `database` | `string?` | Database name |
-| `schema` | `string?` | Schema name |
-| `defaultIsolationLevel` | `IsolationLevel?` | Default transaction isolation level |
-
-### `DbConn`
-
-Interface extending `EventEmitter<{ close: void }>`. Implemented by `MysqlDbConn`, `MssqlDbConn`, and `PostgresqlDbConn`.
-
-| Property/Method | Signature | Description |
-|-----------------|-----------|-------------|
-| `config` | `DbConnConfig` | Connection configuration |
-| `isConnected` | `boolean` | Whether connected |
-| `isInTransaction` | `boolean` | Whether transaction is in progress |
-| `connect` | `() => Promise<void>` | Establish DB connection |
-| `close` | `() => Promise<void>` | Close DB connection |
-| `beginTransaction` | `(isolationLevel?: IsolationLevel) => Promise<void>` | Begin transaction |
-| `commitTransaction` | `() => Promise<void>` | Commit transaction |
-| `rollbackTransaction` | `() => Promise<void>` | Rollback transaction |
-| `execute` | `(queries: string[]) => Promise<Record<string, unknown>[][]>` | Execute SQL query array |
-| `executeParametrized` | `(query: string, params?: unknown[]) => Promise<Record<string, unknown>[][]>` | Execute parameterized query |
-| `bulkInsert` | `(tableName: string, columnMetas: Record<string, ColumnMeta>, records: Record<string, unknown>[]) => Promise<void>` | Bulk INSERT using native API |
-
-### `createDbConn`
+### Connections
+
+#### MssqlDbConn (class)
+
+Implements `DbConn` using the `tedious` driver for Microsoft SQL Server.
 
 ```typescript
-function createDbConn(config: DbConnConfig): Promise<DbConn>
+class MssqlDbConn implements DbConn {
+  constructor(tedious: typeof import("tedious"), config: MssqlDbConnConfig);
+}
 ```
 
-Factory function that creates a DB connection instance. The returned connection is **not yet connected** -- call `connect()` separately. Database drivers are lazily loaded.
+#### MysqlDbConn (class)
 
-### `getDialectFromConfig`
+Implements `DbConn` using the `mysql2/promise` driver for MySQL.
 
 ```typescript
-function getDialectFromConfig(config: DbConnConfig): Dialect
+class MysqlDbConn implements DbConn {
+  constructor(mysql: typeof import("mysql2/promise"), config: MysqlDbConnConfig);
+}
 ```
 
-Extracts the `Dialect` from a config. Maps `"mssql-azure"` to `"mssql"`.
+#### PostgresqlDbConn (class)
 
-### `OrmOptions`
+Implements `DbConn` using `pg` and `pg-copy-streams` drivers for PostgreSQL.
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `database` | `string?` | Database name (overrides DbConnConfig's database) |
-| `schema` | `string?` | Schema name (MSSQL: dbo, PostgreSQL: public) |
+```typescript
+class PostgresqlDbConn implements DbConn {
+  constructor(
+    pg: typeof import("pg"),
+    pgCopyStreams: typeof import("pg-copy-streams"),
+    config: PostgresqlDbConnConfig,
+  );
+}
+```
 
-### `Orm<TDef>`
+### Core
 
-| Property/Method | Signature | Description |
-|-----------------|-----------|-------------|
-| `dbContextDef` | `TDef` | DbContext definition |
-| `config` | `DbConnConfig` | Connection configuration |
-| `options` | `OrmOptions?` | ORM options |
-| `connect` | `<R>(callback: (conn: DbContextInstance<TDef>) => Promise<R>, isolationLevel?: IsolationLevel) => Promise<R>` | Execute callback within a transaction |
-| `connectWithoutTransaction` | `<R>(callback: (conn: DbContextInstance<TDef>) => Promise<R>) => Promise<R>` | Execute callback without a transaction |
+#### createDbConn
 
-### `createOrm`
+Factory function that creates a `DbConn` instance with lazy-loaded drivers. The connection is NOT established -- call `connect()` separately.
 
 ```typescript
-function createOrm<TDef extends DbContextDef<any, any, any>>(
-  dbContextDef: TDef,
-  config: DbConnConfig,
-  options?: OrmOptions,
-): Orm<TDef>
+async function createDbConn(config: DbConnConfig): Promise<DbConn>;
 ```
 
-### `NodeDbContextExecutor`
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `constructor` | `(config: DbConnConfig)` | Create executor with connection config |
-| `connect` | `() => Promise<void>` | Establish DB connection |
-| `close` | `() => Promise<void>` | Close DB connection |
-| `beginTransaction` | `(isolationLevel?: IsolationLevel) => Promise<void>` | Begin transaction |
-| `commitTransaction` | `() => Promise<void>` | Commit transaction |
-| `rollbackTransaction` | `() => Promise<void>` | Rollback transaction |
-| `executeParametrized` | `(query: string, params?: unknown[]) => Promise<Record<string, unknown>[][]>` | Execute parameterized query |
-| `bulkInsert` | `(tableName: string, columnMetas: Record<string, ColumnMeta>, records: DataRecord[]) => Promise<void>` | Bulk insert |
-| `executeDefs` | `<T>(defs: QueryDef[], resultMetas?: (ResultMeta \| undefined)[]) => Promise<T[][]>` | Execute QueryDef array |
-
-## Usage Examples
+#### NodeDbContextExecutor (class)
 
-### Using createOrm (recommended)
+Implements `DbContextExecutor` for Node.js. Bridges `DbConn` with the ORM's `QueryDef` system.
 
 ```typescript
-import { createOrm } from "@simplysm/orm-node";
-import { defineDbContext, queryable } from "@simplysm/orm-common";
-
-const MyDb = defineDbContext({
-  user: (db) => queryable(db, User),
-});
+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[][]>;
+}
+```
 
-const orm = createOrm(MyDb, {
-  dialect: "mysql",
-  host: "localhost",
-  port: 3306,
-  username: "root",
-  password: "password",
-  database: "mydb",
-});
+#### createOrm
 
-// Execute within a transaction
-await orm.connect(async (db) => {
-  const users = await db.user().execute();
-  return users;
-});
+Main factory function. Creates an `Orm` instance that manages `DbContext` creation and connection lifecycle.
 
-// Execute without a transaction
-await orm.connectWithoutTransaction(async (db) => {
-  const users = await db.user().execute();
-  return users;
-});
+```typescript
+function createOrm<TDef extends DbContextDef<any, any, any>>(
+  dbContextDef: TDef,
+  config: DbConnConfig,
+  options?: OrmOptions,
+): Orm<TDef>;
 ```
 
-### Using low-level connection
+**Parameters:**
 
-```typescript
-import { createDbConn } from "@simplysm/orm-node";
+| Parameter | Type | Description |
+|---|---|---|
+| `dbContextDef` | `DbContextDef` | Definition from `defineDbContext()` |
+| `config` | `DbConnConfig` | Database connection configuration |
+| `options` | `OrmOptions` | Optional overrides for database/schema |
 
-const conn = await createDbConn({
-  dialect: "postgresql",
-  host: "localhost",
-  username: "admin",
-  password: "secret",
-  database: "testdb",
-});
+#### Orm (interface)
 
-await conn.connect();
-try {
-  const results = await conn.execute(["SELECT * FROM users"]);
-} finally {
-  await conn.close();
+```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>;
 }
 ```
+
+| 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/dist/connections/mssql-db-conn.d.ts

@@ -2,9 +2,9 @@ import { EventEmitter } from "@simplysm/core-common";
 import type { ColumnMeta, IsolationLevel } from "@simplysm/orm-common";
 import { type DbConn, type MssqlDbConnConfig } from "../types/db-conn";
 /**
- * MSSQL database connection class
+ * MSSQL 데이터베이스 연결 클래스
  *
- * Manages MSSQL/Azure SQL connections using the tedious library.
+ * tedious 라이브러리를 사용하여 MSSQL/Azure SQL 연결을 관리한다.
  */
 export declare class MssqlDbConn extends EventEmitter<{
     close: void;
@@ -34,10 +34,10 @@ export declare class MssqlDbConn extends EventEmitter<{
     private _convertColumnMetaToTediousBulkColumnDef;
     private _convertDataTypeToTediousBulkColumnType;
     /**
-     * Infer the type of a value and return Tedious data type
+     * 값의 타입을 추론하여 Tedious 데이터 타입을 반환한다
      *
-     * @param value - Value whose type is to be inferred (error if null/undefined is passed)
-     * @throws Error if null/undefined is passed
+     * @param value - 타입을 추론할 값 (null/undefined 전달 시 오류 발생)
+     * @throws null/undefined 전달 시 오류
      */
     private _guessTediousType;
 }