@simplysm/orm-node 14.0.23 → 14.0.25

package/package.json

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

package/README.md

@@ -1,116 +0,0 @@
-# @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 & Query Execution
-
-| Export | Type | Description |
-|--------|------|-------------|
-| [`createOrm`](./docs/orm-factory.md#createorm) | Function | Create an ORM instance from a DbContext subclass and connection config |
-| [`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) |
-| [`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 { DbContext } from "@simplysm/orm-common";
-import { createOrm } from "@simplysm/orm-node";
-
-class MyDb extends DbContext {
-  user = this.queryable(User);
-  post = this.queryable(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

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

@@ -1,122 +0,0 @@
-# ORM Factory & Query Execution
-
-High-level ORM instance creation and Node.js query execution.
-
-## createOrm
-
-```typescript
-function createOrm<T extends DbContext>(
-  DbClass: new (executor: DbContextExecutor, opt: { database: string; schema?: string }) => T,
-  config: DbConnConfig,
-  options?: OrmOptions,
-): Orm<T>
-```
-
-Creates an ORM instance that manages DbContext creation and database connections. Each `connect()` or `connectWithoutTransaction()` call creates a fresh DbContext and connection.
-
-The `database` parameter is required -- it is resolved from `options.database` first, then `config.database`. An error is thrown if neither is provided.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `DbClass` | `new (executor, opt) => T` | DbContext subclass constructor |
-| `config` | `DbConnConfig` | Database connection configuration |
-| `options` | `OrmOptions?` | Optional overrides for database/schema |
-
-```typescript
-import { DbContext } from "@simplysm/orm-common";
-import { createOrm } from "@simplysm/orm-node";
-
-class MyDb extends DbContext {
-  user = this.queryable(User);
-  post = this.queryable(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();
-  return users;
-});
-
-// No-transaction mode (for DDL, read-only)
-await orm.connectWithoutTransaction(async (db) => {
-  // ...
-});
-```
-
-## Orm
-
-```typescript
-interface Orm<T extends DbContext> {
-  readonly DbClass: new (
-    executor: DbContextExecutor,
-    opt: { database: string; schema?: string },
-  ) => T;
-  readonly config: DbConnConfig;
-  readonly options?: OrmOptions;
-  connect<R>(callback: (conn: T) => Promise<R>, isolationLevel?: IsolationLevel): Promise<R>;
-  connectWithoutTransaction<R>(callback: (conn: T) => Promise<R>): Promise<R>;
-}
-```
-
-ORM instance returned by `createOrm()`.
-
-| Field | Type | Description |
-|-------|------|-------------|
-| `DbClass` | `new (executor, opt) => T` | The DbContext subclass constructor |
-| `config` | `DbConnConfig` | The connection configuration |
-| `options` | `OrmOptions?` | The ORM options |
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `connect` | `<R>(callback: (conn: T) => Promise<R>, isolationLevel?) => Promise<R>` | Open connection, begin transaction, execute callback, commit (auto-rollback on error), close |
-| `connectWithoutTransaction` | `<R>(callback: (conn: T) => 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