@simplysm/orm-node 14.0.1 → 14.0.5

package/README.md

@@ -0,0 +1,120 @@
+# @simplysm/orm-node
+
+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 DBMS):
+- MySQL: `mysql2`
+- MSSQL: `tedious`
+- PostgreSQL: `pg`, `pg-copy-streams`
+
+## 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 } 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",
+});
+
+// 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();
+});
+```
+
+### Low-Level Connection
+
+```typescript
+import { createDbConn } from "@simplysm/orm-node";
+
+const conn = await createDbConn({
+  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();
+```
+
+### With OrmOptions Override
+
+```typescript
+const orm = createOrm(MyDb, config, {
+  database: "other_db",  // Override config.database
+  schema: "custom",      // Override config.schema
+});
+```

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.1",
+  "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.1",
-    "@simplysm/orm-common": "14.0.1"
+    "@simplysm/orm-common": "14.0.5",
+    "@simplysm/core-common": "14.0.5"
   },
   "devDependencies": {
     "@types/pg": "^8.20.0",