@simplysm/orm-common 13.0.82 → 13.0.84

package/docs/schema-builders.md

@@ -0,0 +1,216 @@
+# Schema Builders
+
+Define database tables, views, and stored procedures with a fluent, type-safe API.
+
+## API Reference
+
+### `Table(name)`
+
+Factory function that creates a `TableBuilder` for defining table schemas.
+
+```typescript
+function Table(name: string): TableBuilder<{}, {}>
+```
+
+#### TableBuilder Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `description(desc)` | `.description(desc: string)` | Set table description (DDL comment) |
+| `database(db)` | `.database(db: string)` | Set database name |
+| `schema(schema)` | `.schema(schema: string)` | Set schema name (MSSQL: `dbo`, PostgreSQL: `public`) |
+| `columns(fn)` | `.columns((c) => ({...}))` | Define columns using column factory |
+| `primaryKey(...cols)` | `.primaryKey("col1", "col2")` | Set primary key (single or composite) |
+| `indexes(fn)` | `.indexes((i) => [...])` | Define indexes |
+| `relations(fn)` | `.relations((r) => ({...}))` | Define relationships (FK, reverse FK, logical relations) |
+
+#### Type Inference Properties
+
+| Property | Description |
+|----------|-------------|
+| `$inferSelect` | Full type (columns + deep relations) |
+| `$inferColumns` | Columns only |
+| `$inferInsert` | Insert type (autoIncrement/nullable/default fields are optional) |
+| `$inferUpdate` | Update type (all fields optional) |
+
+---
+
+### `View(name)`
+
+Factory function that creates a `ViewBuilder` for defining database views.
+
+```typescript
+function View(name: string): ViewBuilder<any, {}, {}>
+```
+
+#### ViewBuilder Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `description(desc)` | `.description(desc: string)` | Set view description |
+| `database(db)` | `.database(db: string)` | Set database name |
+| `schema(schema)` | `.schema(schema: string)` | Set schema name |
+| `query(viewFn)` | `.query((db) => db.table().select(...))` | Define view SELECT query |
+| `relations(fn)` | `.relations((r) => ({...}))` | Define relationships (logical only, no FK) |
+
+---
+
+### `Procedure(name)`
+
+Factory function that creates a `ProcedureBuilder` for defining stored procedures.
+
+```typescript
+function Procedure(name: string): ProcedureBuilder<never, never>
+```
+
+#### ProcedureBuilder Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `description(desc)` | `.description(desc: string)` | Set procedure description |
+| `database(db)` | `.database(db: string)` | Set database name |
+| `schema(schema)` | `.schema(schema: string)` | Set schema name |
+| `params(fn)` | `.params((c) => ({...}))` | Define input parameters |
+| `returns(fn)` | `.returns((c) => ({...}))` | Define return columns |
+| `body(sql)` | `.body("SELECT ...")` | Set procedure body SQL |
+
+---
+
+### Column Factory
+
+The column factory (`c`) is provided inside `.columns()` and `.params()`/`.returns()` callbacks.
+
+#### Column Types
+
+| Method | SQL Type | TypeScript Type | Notes |
+|--------|----------|-----------------|-------|
+| `c.int()` | INT | `number` | 4 bytes |
+| `c.bigint()` | BIGINT | `number` | 8 bytes |
+| `c.float()` | FLOAT | `number` | Single precision |
+| `c.double()` | DOUBLE | `number` | Double precision |
+| `c.decimal(p, s)` | DECIMAL(p,s) | `number` | Fixed-point |
+| `c.varchar(len)` | VARCHAR(len) | `string` | Variable-length string |
+| `c.char(len)` | CHAR(len) | `string` | Fixed-length string |
+| `c.text()` | TEXT | `string` | Large text |
+| `c.binary()` | BLOB/VARBINARY/BYTEA | `Bytes` | Binary data |
+| `c.boolean()` | TINYINT(1)/BIT/BOOLEAN | `boolean` | |
+| `c.datetime()` | DATETIME | `DateTime` | Date + time |
+| `c.date()` | DATE | `DateOnly` | Date only |
+| `c.time()` | TIME | `Time` | Time only |
+| `c.uuid()` | BINARY(16)/UNIQUEIDENTIFIER/UUID | `Uuid` | |
+
+#### Column Modifiers
+
+| Method | Description |
+|--------|-------------|
+| `.autoIncrement()` | Auto-increment (optional in INSERT inference) |
+| `.nullable()` | Allow NULL (adds `undefined` to type) |
+| `.default(value)` | Set default value (optional in INSERT inference) |
+| `.description(desc)` | Set column comment |
+
+---
+
+### Index Factory
+
+The index factory (`i`) is provided inside `.indexes()` callbacks.
+
+```typescript
+i.index("col1", "col2")     // Create index on columns
+  .unique()                  // Make unique
+  .orderBy("ASC", "DESC")   // Set sort order per column
+  .name("IX_Custom_Name")   // Custom index name
+  .description("desc")      // Description
+```
+
+---
+
+### Relation Factory
+
+The relation factory (`r`) is provided inside `.relations()` callbacks.
+
+| Method | Type | Description |
+|--------|------|-------------|
+| `r.foreignKey(cols, targetFn)` | N:1 | FK constraint created in DB |
+| `r.foreignKeyTarget(targetFn, relName)` | 1:N | Reverse FK reference (array by default) |
+| `r.relationKey(cols, targetFn)` | N:1 | Logical relation (no DB FK) |
+| `r.relationKeyTarget(targetFn, relName)` | 1:N | Logical reverse reference |
+
+Both `foreignKeyTarget` and `relationKeyTarget` support `.single()` to indicate a 1:1 relationship (returns single object instead of array).
+
+---
+
+## Usage Examples
+
+### Complete Table Definition
+
+```typescript
+const User = Table("User")
+  .database("mydb")
+  .description("Application users")
+  .columns((c) => ({
+    id: c.bigint().autoIncrement(),
+    name: c.varchar(100),
+    email: c.varchar(200).nullable(),
+    status: c.varchar(20).default("active"),
+    createdAt: c.datetime().default("CURRENT_TIMESTAMP"),
+  }))
+  .primaryKey("id")
+  .indexes((i) => [
+    i.index("email").unique(),
+    i.index("status", "createdAt").orderBy("ASC", "DESC"),
+  ]);
+```
+
+### Table with Relations
+
+```typescript
+const Post = Table("Post")
+  .columns((c) => ({
+    id: c.bigint().autoIncrement(),
+    authorId: c.bigint(),
+    title: c.varchar(200),
+  }))
+  .primaryKey("id")
+  .relations((r) => ({
+    author: r.foreignKey(["authorId"], () => User),
+  }));
+
+const User = Table("User")
+  .columns((c) => ({
+    id: c.bigint().autoIncrement(),
+    name: c.varchar(100),
+  }))
+  .primaryKey("id")
+  .relations((r) => ({
+    posts: r.foreignKeyTarget(() => Post, "author"),
+    profile: r.foreignKeyTarget(() => Profile, "user").single(),
+  }));
+```
+
+### View Definition
+
+```typescript
+const ActiveUsers = View("ActiveUsers")
+  .database("mydb")
+  .query((db: MyDb) =>
+    db.user()
+      .where((u) => [expr.eq(u.status, "active")])
+      .select((u) => ({ id: u.id, name: u.name, email: u.email }))
+  );
+```
+
+### Procedure Definition
+
+```typescript
+const GetUserById = Procedure("GetUserById")
+  .database("mydb")
+  .params((c) => ({
+    userId: c.bigint(),
+  }))
+  .returns((c) => ({
+    id: c.bigint(),
+    name: c.varchar(100),
+    email: c.varchar(200),
+  }))
+  .body("SELECT id, name, email FROM User WHERE id = userId");
+```

package/docs/types-and-utilities.md

@@ -0,0 +1,353 @@
+# Types and Utilities
+
+Core type definitions, error handling, search parsing, and result parsing utilities.
+
+## API Reference
+
+### Column Types
+
+#### `DataType`
+
+SQL data type definition used in column metadata.
+
+```typescript
+type DataType =
+  | { type: "int" }
+  | { type: "bigint" }
+  | { type: "float" }
+  | { type: "double" }
+  | { type: "decimal"; precision: number; scale?: number }
+  | { type: "varchar"; length: number }
+  | { type: "char"; length: number }
+  | { type: "text" }
+  | { type: "binary" }
+  | { type: "boolean" }
+  | { type: "datetime" }
+  | { type: "date" }
+  | { type: "time" }
+  | { type: "uuid" };
+```
+
+#### `ColumnPrimitive`
+
+All primitive TypeScript types that can be stored in columns. `undefined` represents NULL.
+
+```typescript
+type ColumnPrimitive = string | number | boolean | DateTime | DateOnly | Time | Uuid | Bytes | undefined;
+```
+
+#### `ColumnPrimitiveStr`
+
+String keys for column primitive type mapping.
+
+```typescript
+type ColumnPrimitiveStr = "string" | "number" | "boolean" | "DateTime" | "DateOnly" | "Time" | "Uuid" | "Bytes";
+```
+
+#### `ColumnMeta`
+
+Column metadata generated by `ColumnBuilder`.
+
+```typescript
+interface ColumnMeta {
+  type: ColumnPrimitiveStr;
+  dataType: DataType;
+  autoIncrement?: boolean;
+  nullable?: boolean;
+  default?: ColumnPrimitive;
+  description?: string;
+}
+```
+
+#### `inferColumnPrimitiveStr(value)`
+
+Infer `ColumnPrimitiveStr` from a runtime value.
+
+```typescript
+function inferColumnPrimitiveStr(value: ColumnPrimitive): ColumnPrimitiveStr
+```
+
+```typescript
+inferColumnPrimitiveStr("hello")        // "string"
+inferColumnPrimitiveStr(123)            // "number"
+inferColumnPrimitiveStr(new DateTime()) // "DateTime"
+```
+
+#### `dataTypeStrToColumnPrimitiveStr`
+
+Mapping from SQL type strings to TypeScript type names.
+
+```typescript
+dataTypeStrToColumnPrimitiveStr["int"]      // "number"
+dataTypeStrToColumnPrimitiveStr["varchar"]  // "string"
+dataTypeStrToColumnPrimitiveStr["datetime"] // "DateTime"
+```
+
+---
+
+### Database Types
+
+#### `Dialect`
+
+Supported database dialects.
+
+```typescript
+type Dialect = "mysql" | "mssql" | "postgresql";
+```
+
+#### `dialects`
+
+Array of all supported dialects (useful for testing).
+
+```typescript
+const dialects: Dialect[] = ["mysql", "mssql", "postgresql"];
+```
+
+#### `IsolationLevel`
+
+Transaction isolation levels.
+
+```typescript
+type IsolationLevel =
+  | "READ_UNCOMMITTED"
+  | "READ_COMMITTED"
+  | "REPEATABLE_READ"
+  | "SERIALIZABLE";
+```
+
+#### `DataRecord`
+
+Recursive type for query result records (supports nested relations).
+
+```typescript
+type DataRecord = {
+  [key: string]: ColumnPrimitive | DataRecord | DataRecord[];
+};
+```
+
+#### `ResultMeta`
+
+Metadata for transforming raw query results into typed TypeScript objects.
+
+```typescript
+interface ResultMeta {
+  columns: Record<string, ColumnPrimitiveStr>;
+  joins: Record<string, { isSingle: boolean }>;
+}
+```
+
+#### `QueryBuildResult`
+
+Result of building a QueryDef into SQL.
+
+```typescript
+interface QueryBuildResult {
+  sql: string;
+  resultSetIndex?: number;
+  resultSetStride?: number;
+}
+```
+
+#### `Migration`
+
+Database migration definition.
+
+```typescript
+interface Migration {
+  name: string;
+  up: (db: DbContextBase & DbContextDdlMethods) => Promise<void>;
+}
+```
+
+---
+
+### Error Handling
+
+#### `DbTransactionError`
+
+Standardized database transaction error with DBMS-independent error codes.
+
+```typescript
+class DbTransactionError extends Error {
+  readonly name = "DbTransactionError";
+  readonly code: DbErrorCode;
+  readonly originalError?: unknown;
+
+  constructor(code: DbErrorCode, message: string, originalError?: unknown);
+}
+```
+
+#### `DbErrorCode`
+
+Transaction-related error codes.
+
+```typescript
+enum DbErrorCode {
+  NO_ACTIVE_TRANSACTION = "NO_ACTIVE_TRANSACTION",
+  TRANSACTION_ALREADY_STARTED = "TRANSACTION_ALREADY_STARTED",
+  DEADLOCK = "DEADLOCK",
+  LOCK_TIMEOUT = "LOCK_TIMEOUT",
+}
+```
+
+```typescript
+try {
+  await executor.rollbackTransaction();
+} catch (err) {
+  if (err instanceof DbTransactionError) {
+    if (err.code === DbErrorCode.NO_ACTIVE_TRANSACTION) {
+      return; // Already rolled back, safe to ignore
+    }
+  }
+  throw err;
+}
+```
+
+---
+
+### Search Parser
+
+#### `parseSearchQuery(searchText)`
+
+Parse a user search string into structured SQL LIKE patterns.
+
+```typescript
+function parseSearchQuery(searchText: string): ParsedSearchQuery
+```
+
+```typescript
+interface ParsedSearchQuery {
+  or: string[];    // General terms (OR condition)
+  must: string[];  // Required terms (AND condition, + prefix or quotes)
+  not: string[];   // Excluded terms (NOT condition, - prefix)
+}
+```
+
+**Search Syntax:**
+
+| Syntax | Meaning | Example |
+|--------|---------|---------|
+| `term1 term2` | OR (match any) | `apple banana` |
+| `+term` | Required (AND) | `+apple +banana` |
+| `-term` | Excluded (NOT) | `apple -banana` |
+| `"exact phrase"` | Exact match (required) | `"delicious fruit"` |
+| `*` | Wildcard | `app*` -> `app%` |
+
+**Escape sequences:** `\\` (literal `\`), `\*` (literal `*`), `\%` (literal `%`), `\"` (literal `"`), `\+` (literal `+`), `\-` (literal `-`)
+
+```typescript
+parseSearchQuery('apple "delicious fruit" -banana +strawberry')
+// {
+//   or: ["%apple%"],
+//   must: ["%delicious fruit%", "%strawberry%"],
+//   not: ["%banana%"]
+// }
+
+parseSearchQuery('app* test')
+// {
+//   or: ["app%", "%test%"],
+//   must: [],
+//   not: []
+// }
+```
+
+---
+
+### Result Parser
+
+#### `parseQueryResult(rawResults, meta)`
+
+Transform raw database query results into typed TypeScript objects. Handles type conversion, nested JOIN result grouping, and deduplication.
+
+```typescript
+async function parseQueryResult<TRecord>(
+  rawResults: Record<string, unknown>[],
+  meta: ResultMeta,
+): Promise<TRecord[] | undefined>
+```
+
+**Features:**
+- Type conversion (string to number, string to DateTime, etc.)
+- Flat-to-nested object transformation (`"posts.id"` -> `{ posts: { id } }`)
+- JOIN result grouping with deduplication
+- Single vs array relationship handling (`isSingle`)
+- Event loop yielding for large datasets (every 100 records)
+- Returns `undefined` for empty results
+
+```typescript
+// Simple type parsing
+const raw = [{ id: "1", createdAt: "2026-01-07T10:00:00.000Z" }];
+const meta = { columns: { id: "number", createdAt: "DateTime" }, joins: {} };
+const result = await parseQueryResult(raw, meta);
+// [{ id: 1, createdAt: DateTime(...) }]
+
+// JOIN result nesting
+const raw = [
+  { id: 1, name: "Alice", "posts.id": 10, "posts.title": "Post1" },
+  { id: 1, name: "Alice", "posts.id": 11, "posts.title": "Post2" },
+];
+const meta = {
+  columns: { id: "number", name: "string", "posts.id": "number", "posts.title": "string" },
+  joins: { posts: { isSingle: false } },
+};
+const result = await parseQueryResult(raw, meta);
+// [{ id: 1, name: "Alice", posts: [{ id: 10, title: "Post1" }, { id: 11, title: "Post2" }] }]
+```
+
+---
+
+### QueryDef Types
+
+#### `QueryDefObjectName`
+
+Database object name with optional namespace.
+
+```typescript
+interface QueryDefObjectName {
+  database?: string;
+  schema?: string;
+  name: string;
+}
+```
+
+#### `QueryDef`
+
+Union type of all query definitions (DML + DDL + utility).
+
+Key DML types:
+
+| Type | Interface | Description |
+|------|-----------|-------------|
+| `"select"` | `SelectQueryDef` | SELECT with FROM, WHERE, JOIN, ORDER BY, GROUP BY, HAVING, LIMIT, WITH |
+| `"insert"` | `InsertQueryDef` | INSERT with records, output, overrideIdentity |
+| `"insertIfNotExists"` | `InsertIfNotExistsQueryDef` | Conditional INSERT |
+| `"insertInto"` | `InsertIntoQueryDef` | INSERT INTO ... SELECT |
+| `"update"` | `UpdateQueryDef` | UPDATE with JOIN support |
+| `"delete"` | `DeleteQueryDef` | DELETE with JOIN support |
+| `"upsert"` | `UpsertQueryDef` | INSERT or UPDATE (MERGE) |
+
+#### `DDL_TYPES`
+
+Constant array of all DDL query type strings. Used to prevent DDL execution inside transactions.
+
+```typescript
+const DDL_TYPES: readonly string[]
+// ["clearSchema", "createTable", "dropTable", "renameTable", "truncate",
+//  "addColumn", "dropColumn", "modifyColumn", "renameColumn",
+//  "dropPrimaryKey", "addPrimaryKey", "addForeignKey", "dropForeignKey",
+//  "addIndex", "dropIndex", "createView", "dropView", "createProc", "dropProc"]
+```
+
+---
+
+### Type Inference Utilities
+
+| Type | Description |
+|------|-------------|
+| `InferColumns<T>` | Infer value types from ColumnBuilderRecord |
+| `InferInsertColumns<T>` | Infer INSERT type (required + optional fields) |
+| `InferUpdateColumns<T>` | Infer UPDATE type (all fields optional) |
+| `InferColumnExprs<T>` | Infer expression input types |
+| `InferDeepRelations<T>` | Infer nested relation types (all optional) |
+| `ExtractRelationTarget<T>` | Extract N:1 relation target type |
+| `ExtractRelationTargetResult<T>` | Extract 1:N relation target type (array or single) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/orm-common",
-  "version": "13.0.82",
+  "version": "13.0.84",
   "description": "Simplysm Package - ORM Module (common)",
   "author": "simplysm",
   "license": "Apache-2.0",
@@ -15,10 +15,11 @@
   "files": [
     "dist",
     "src",
-    "tests"
+    "tests",
+    "docs"
   ],
   "sideEffects": false,
   "dependencies": {
-    "@simplysm/core-common": "13.0.82"
+    "@simplysm/core-common": "13.0.84"
   }
 }

package/src/ddl/initialize.ts

@@ -46,7 +46,7 @@ export async function initialize(
 
   const force = options?.force ?? false;
 
-  // 1. DB 존재 확인
+  // 1. Check DB existence
   for (const dbName of dbNames) {
     const schemaExistsDef = getSchemaExistsQueryDef(dbName, db.schema);
     const result = await db.executeDefs([schemaExistsDef]);
@@ -57,7 +57,7 @@ export async function initialize(
   }
 
   if (force) {
-    // 2. force: dbs 전체 Initialize
+    // 2. force: initialize all dbs
     for (const dbName of dbNames) {
       const clearDef = getClearSchemaQueryDef({ database: dbName, schema: db.schema });
       await db.executeDefs([clearDef]);
@@ -69,7 +69,7 @@ export async function initialize(
       await db._migration().insert(def.meta.migrations.map((m) => ({ code: m.name })));
     }
   } else {
-    // 3. Migration 기반 Initialize
+    // 3. Migration-based initialize
     let appliedMigrations: { code: string }[] | undefined;
     try {
       appliedMigrations = await db._migration().execute();
@@ -102,13 +102,13 @@ export async function initialize(
 }
 
 /**
- * 전체 object Generate (table/View/Procedure/FK/Index)
+ * Generate all objects (table/view/procedure/FK/index)
  */
 async function createAllObjects(
   db: DbContextBase,
   def: DbContextDef<any, any, any>,
 ): Promise<void> {
-  // 1. Table/View/Procedure Generate
+  // 1. Generate Table/View/Procedure
   const builders = getBuilders(def);
   const createDefs: QueryDef[] = [];
   for (const builder of builders) {
@@ -118,7 +118,7 @@ async function createAllObjects(
     await db.executeDefs(createDefs);
   }
 
-  // 2. FK Generate (TableBuilder만)
+  // 2. Generate FK (TableBuilder only)
   const tables = builders.filter((b) => b instanceof TableBuilder);
   const addFkDefs: QueryDef[] = [];
   for (const table of tables) {
@@ -136,7 +136,7 @@ async function createAllObjects(
     await db.executeDefs(addFkDefs);
   }
 
-  // 3. Index Generate (TableBuilder만)
+  // 3. Generate Index (TableBuilder only)
   const createIndexDefs: QueryDef[] = [];
   for (const table of tables) {
     const indexes = table.meta.indexes;
@@ -153,7 +153,7 @@ async function createAllObjects(
 }
 
 /**
- * DbContext의 모든 Builder 수집 (Table/View/Procedure)
+ * Collect all builders from DbContext (Table/View/Procedure)
  */
 function getBuilders(
   def: DbContextDef<any, any, any>,
@@ -186,8 +186,8 @@ function getBuilders(
 }
 
 /**
- * ForeignKeyTarget/RelationKeyTarget 관계의 유효성 Validation
- * - targetTableFn()이 반환하는 Table에 relationName에 해당하는 FK/RelationKey가 있는지 확인
+ * Validate ForeignKeyTarget/RelationKeyTarget relations
+ * - Checks if the table returned by targetTableFn() has a FK/RelationKey matching the relationName
  */
 export function validateRelations(def: DbContextDef<any, any, any>): void {
   const builders = getBuilders(def);
@@ -211,8 +211,8 @@ export function validateRelations(def: DbContextDef<any, any, any>): void {
 
       if (!(fkRel instanceof ForeignKeyBuilder) && !(fkRel instanceof RelationKeyBuilder)) {
         throw new Error(
-          `Invalid relation target: ${table.meta.name}.${relName}이 참조하는 ` +
-            `'${fkRelName}'이(가) ${targetTable.meta.name}의 유효한 ForeignKey/RelationKey가 아닙니다.`,
+          `Invalid relation target: '${fkRelName}' referenced by ${table.meta.name}.${relName} ` +
+            `is not a valid ForeignKey/RelationKey in ${targetTable.meta.name}.`,
         );
       }
     }
@@ -220,9 +220,9 @@ export function validateRelations(def: DbContextDef<any, any, any>): void {
 }
 
 /**
- * Table N/A 에러인지 확인
+ * Check if the error indicates a table does not exist
  *
- * DBMS별 error code/메시지 pattern:
+ * DBMS-specific error code/message patterns:
  * - MySQL: errno 1146 (ER_NO_SUCH_TABLE), "Table 'xxx' doesn't exist"
  * - MSSQL: number 208, "Invalid object name 'xxx'"
  * - PostgreSQL: code "42P01", "relation \"xxx\" does not exist"
@@ -230,13 +230,13 @@ export function validateRelations(def: DbContextDef<any, any, any>): void {
 function isTableNotExistsError(err: unknown): boolean {
   if (err == null) return false;
 
-  // error code로 우선 확인 (multilingual 환경에서도 안정적)
+  // Check error code first (reliable even in multilingual environments)
   const errObj = err as Record<string, unknown>;
   if (errObj["errno"] === 1146) return true; // MySQL ER_NO_SUCH_TABLE
   if (errObj["number"] === 208) return true; // MSSQL
   if (errObj["code"] === "42P01") return true; // PostgreSQL
 
-  // 폴백: 메시지 매칭 (multilingual 환경에서 불안정할 수 있음)
+  // Fallback: message matching (may be unreliable in multilingual environments)
   const message = err instanceof Error ? err.message : String(err);
   const lowerMessage = message.toLowerCase();