@simplysm/orm-node 14.0.1 → 14.0.4

package/README.md

@@ -0,0 +1,254 @@
+# @simplysm/orm-node
+
+Node.js ORM runtime providing database connections for MySQL, MSSQL, and PostgreSQL with typed query execution.
+
+## Installation
+
+```bash
+npm install @simplysm/orm-node
+```
+
+Peer dependencies (install the driver for your database):
+- MySQL: `mysql2`
+- MSSQL: `tedious`
+- PostgreSQL: `pg`, `pg-copy-streams`
+
+## Quick Start
+
+```typescript
+import { defineDbContext, Table, expr } 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 },
+});
+
+const orm = createOrm(MyDb, {
+  dialect: "mysql",
+  host: "localhost",
+  port: 3306,
+  username: "root",
+  password: "password",
+  database: "mydb",
+});
+
+// With transaction
+await orm.connect(async (db) => {
+  await db.user().insert([{ name: "Gildong Hong" }]);
+  const users = await db.user().execute();
+  return users;
+});
+
+// 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.
+
+```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[][]>;
+}
+```
+
+#### createOrm
+
+Main factory function. Creates an `Orm` instance that manages `DbContext` creation and connection lifecycle.
+
+```typescript
+function createOrm<TDef extends DbContextDef<any, any, any>>(
+  dbContextDef: TDef,
+  config: DbConnConfig,
+  options?: OrmOptions,
+): Orm<TDef>;
+```
+
+**Parameters:**
+
+| Parameter | Type | Description |
+|---|---|---|
+| `dbContextDef` | `DbContextDef` | Definition from `defineDbContext()` |
+| `config` | `DbConnConfig` | Database connection configuration |
+| `options` | `OrmOptions` | Optional overrides for database/schema |
+
+#### Orm (interface)
+
+```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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/orm-node",
-  "version": "14.0.1",
+  "version": "14.0.4",
   "description": "심플리즘 패키지 - ORM (node)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -19,8 +19,8 @@
   "sideEffects": false,
   "dependencies": {
     "consola": "^3.4.2",
-    "@simplysm/core-common": "14.0.1",
-    "@simplysm/orm-common": "14.0.1"
+    "@simplysm/core-common": "14.0.4",
+    "@simplysm/orm-common": "14.0.4"
   },
   "devDependencies": {
     "@types/pg": "^8.20.0",