@simplysm/orm-common 14.0.16 → 14.0.18

package/docs/core.md

@@ -1,68 +1,62 @@
 # Core
 
-DbContext definition, creation, and lifecycle management.
+DbContext abstract class, connection/transaction lifecycle, DDL execution, and initialization.
 
-## defineDbContext
+## DbContext
 
 ```typescript
-function defineDbContext<
-  TTables extends Record<string, TableBuilder<any, any>> = {},
-  TViews extends Record<string, ViewBuilder<any, any, any>> = {},
-  TProcedures extends Record<string, ProcedureBuilder<any, any>> = {},
->(config: {
-  tables?: TTables;
-  views?: TViews;
-  procedures?: TProcedures;
-  migrations?: Migration[];
-}): DbContextDef<TTables & { _migration: typeof _Migration }, TViews, TProcedures>
-```
+abstract class DbContext implements DbContextBase {
+  status: DbContextStatus;
 
-Creates a DbContext definition (blueprint) containing schema metadata. Automatically adds the `_migration` system table. The definition itself has no runtime state.
+  constructor(
+    executor: DbContextExecutor,
+    opt: { database: string; schema?: string },
+  )
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `config.tables` | `Record<string, TableBuilder>` | Table definitions |
-| `config.views` | `Record<string, ViewBuilder>` | View definitions |
-| `config.procedures` | `Record<string, ProcedureBuilder>` | Procedure definitions |
-| `config.migrations` | `Migration[]` | Migration definitions |
+  // Registration
+  protected queryable<T extends TableBuilder | ViewBuilder>(builder: T): () => Queryable<...>
+  protected executable<T extends ProcedureBuilder>(builder: T): () => Executable<...>
 
-```typescript
-const MyDb = defineDbContext({
-  tables: { user: User, post: Post },
-  views: { activeUsers: ActiveUsersView },
-  procedures: { getUserById: GetUserById },
-  migrations: [
-    { name: "20260101_001_init", up: async (db) => { await db.createTable(User); } },
-  ],
-});
-```
+  // Connection
+  connect<R>(fn: () => Promise<R>, isolationLevel?: IsolationLevel): Promise<R>
+  connectWithoutTransaction<R>(fn: () => Promise<R>): Promise<R>
+  transaction<R>(fn: () => Promise<R>, isolationLevel?: IsolationLevel): Promise<R>
 
-## createDbContext
+  // DDL execution (see DDL Execution Methods below)
+  // DDL QueryDef generators (get*QueryDef methods)
 
-```typescript
-function createDbContext<TDef extends DbContextDef<any, any, any>>(
-  def: TDef,
-  executor: DbContextExecutor,
-  opt: { database: string; schema?: string },
-): DbContextInstance<TDef>
+  // Initialization
+  initialize(options?: { dbs?: string[]; force?: boolean }): Promise<void>
+
+  // Override in subclass
+  migrations: Migration[];
+}
 ```
 
-Creates a full DbContext instance from a definition and executor. The returned object provides:
+Base class for database contexts. Subclass to define tables, views, and procedures as class properties.
 
-- **Queryable accessors** for each table/view (e.g., `db.user()` returns a `Queryable`)
-- **Executable accessors** for each procedure (e.g., `db.getUserById()` returns an `Executable`)
-- **Connection management**: `connect()`, `connectWithoutTransaction()`, `transaction()`
-- **DDL methods**: `createTable()`, `dropTable()`, `addColumn()`, etc. (see `DbContextDdlMethods`)
-- **DDL QueryDef generators**: `getCreateTableQueryDef()`, etc.
-- **Initialize**: `initialize()` runs migrations
+Each property registered via `queryable()` or `executable()` is independently serialized, avoiding TS7056 even with 40+ tables.
 
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `def` | `DbContextDef` | Definition from `defineDbContext()` |
+| Constructor Parameter | Type | Description |
+|---|---|---|
 | `executor` | `DbContextExecutor` | Query execution engine (e.g., `NodeDbContextExecutor`) |
 | `opt.database` | `string` | Database name |
 | `opt.schema` | `string?` | Schema name (MSSQL: dbo, PostgreSQL: public) |
 
+```typescript
+class MainDb extends DbContext {
+  user = this.queryable(User);
+  post = this.queryable(Post);
+  getUserById = this.executable(GetUserById);
+
+  migrations = [
+    { name: "20260101_001_init", up: async (db) => { await db.createTable(User); } },
+  ];
+}
+
+const db = new MainDb(executor, { database: "mydb", schema: "dbo" });
+```
+
 ### Connection Methods
 
 | Method | Signature | Description |
@@ -99,7 +93,7 @@ Creates a full DbContext instance from a definition and executor. The returned o
 
 ### DDL QueryDef Generators
 
-Each DDL method has a corresponding `get*QueryDef` method that returns a `QueryDef` without executing it. For example: `getCreateTableQueryDef(table)`, `getDropTableQueryDef(table)`, etc.
+Each DDL method has a corresponding `get*QueryDef` method that returns a `QueryDef` without executing it. For example: `getCreateTableQueryDef(table)`, `getDropTableQueryDef(table)`, `getCreateObjectQueryDef(builder)`, etc.
 
 ### Initialize
 
@@ -107,7 +101,20 @@ Each DDL method has a corresponding `get*QueryDef` method that returns a `QueryD
 async initialize(options?: { dbs?: string[]; force?: boolean }): Promise<void>
 ```
 
-Runs pending migrations. If `force` is true, drops and recreates the schema.
+Code First database initialization. Creates all registered Table/View/Procedure objects and runs pending migrations.
+
+- **force=true**: Clear schema, recreate all objects, register all migrations as applied
+- **force=false** (default):
+  - No `_Migration` table: Full creation + register all migrations
+  - `_Migration` table exists: Run only pending migrations
+
+## SD_BUILDER
+
+```typescript
+const SD_BUILDER: unique symbol
+```
+
+Internal symbol used to tag queryable/executable factory functions with their underlying builder. Used by `initialize()` to discover registered builders from DbContext instances.
 
 ## DbTransactionError
 
@@ -148,10 +155,63 @@ enum DbErrorCode {
 | `DEADLOCK` | Deadlock detected |
 | `LOCK_TIMEOUT` | Lock timeout exceeded |
 
+## DbContextBase
+
+```typescript
+interface DbContextBase {
+  status: DbContextStatus;
+  readonly database: string | undefined;
+  readonly schema: string | undefined;
+  getNextAlias(): string;
+  resetAliasCounter(): void;
+  executeDefs<T = DataRecord>(defs: QueryDef[], resultMetas?: (ResultMeta | undefined)[]): Promise<T[][]>;
+  getQueryDefObjectName(tableOrView: TableBuilder | ViewBuilder): QueryDefObjectName;
+  switchFk(table: QueryDefObjectName, enabled: boolean): Promise<void>;
+}
+```
+
+Core interface implemented by DbContext. Used internally by Queryable, Executable, and ViewBuilder.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `status` | `DbContextStatus` | Current connection status |
+| `database` | `string \| undefined` | Database name |
+| `schema` | `string \| undefined` | Schema name |
+| `getNextAlias()` | `string` | Generate next table alias (T1, T2, ...) |
+| `resetAliasCounter()` | `void` | Reset alias counter |
+| `executeDefs()` | `Promise<T[][]>` | Execute QueryDef array, returns result per def |
+| `getQueryDefObjectName()` | `QueryDefObjectName` | Resolve table/view to qualified name |
+| `switchFk()` | `Promise<void>` | Enable/disable FK constraints |
+
+## DbContextDdlMethods
+
+```typescript
+interface DbContextDdlMethods {
+  createTable(table: TableBuilder): Promise<void>;
+  dropTable(table: QueryDefObjectName): Promise<void>;
+  // ... all DDL methods listed in DbContext DDL Execution Methods above
+  // ... plus all get*QueryDef generator methods
+}
+```
+
+Interface for DDL execution and QueryDef generation methods. DbContext implements this interface. Used by the `initialize()` function and `Migration.up()` callback parameter type.
+
+## DbContextStatus
+
+```typescript
+type DbContextStatus = "ready" | "connect" | "transact";
+```
+
+| Value | Description |
+|-------|-------------|
+| `"ready"` | Not connected |
+| `"connect"` | Connected, no active transaction |
+| `"transact"` | Connected with active transaction |
+
 ## _Migration
 
 ```typescript
 const _Migration: TableBuilder<{ code: ColumnBuilder<string, ...> }, {}>
 ```
 
-System migration tracking table. Automatically added to every DbContext via `defineDbContext()`. Has a single `code` column (VARCHAR(255)) as primary key, storing executed migration names.
+System migration tracking table. Automatically registered in every DbContext as `_migration`. Has a single `code` column (VARCHAR(255)) as primary key, storing executed migration names.

package/docs/schema-builders.md

@@ -215,9 +215,7 @@ class ForeignKeyBuilder<TOwner extends TableBuilder<any, any>, TTargetFn extends
 
 N:1 FK relation builder. Creates an actual DB foreign key constraint.
 
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `description` | `(desc: string) => ForeignKeyBuilder` | Set relation description |
+`description` is configured via the factory function's `opts` parameter (3rd argument to `foreignKey()`), not via method chaining. This class has no methods — it is a data holder for relation metadata.
 
 ## ForeignKeyTargetBuilder
 
@@ -232,12 +230,11 @@ class ForeignKeyTargetBuilder<TTargetTableFn extends () => TableBuilder<any, any
 }
 ```
 
-1:N FK reverse-reference builder. Loaded as array by default, single object with `.single()`.
+1:N FK reverse-reference builder. Loaded as array by default, single object with `{ single: true }` opts.
 
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `description` | `(desc: string) => ForeignKeyTargetBuilder` | Set relation description |
-| `single` | `() => ForeignKeyTargetBuilder<..., true>` | Change to 1:1 (single object) |
+`description` and `single` are configured via the factory function's `opts` parameter (3rd argument to `foreignKeyTarget()`), not via method chaining. Method chaining was removed to prevent TS7022 in complex circular references.
+
+This class has no methods — it is a data holder for relation metadata.
 
 ## RelationKeyBuilder
 
@@ -250,9 +247,7 @@ class RelationKeyBuilder<
 
 Logical N:1 relation builder (no DB FK constraint). Works with both Tables and Views.
 
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `description` | `(desc: string) => RelationKeyBuilder` | Set relation description |
+`description` is configured via the factory function's `opts` parameter (3rd argument to `relationKey()`), not via method chaining. This class has no methods — it is a data holder for relation metadata.
 
 ## RelationKeyTargetBuilder
 
@@ -265,10 +260,9 @@ class RelationKeyTargetBuilder<
 
 Logical 1:N reverse-reference builder (no DB FK constraint). Works with both Tables and Views.
 
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `description` | `(desc: string) => RelationKeyTargetBuilder` | Set relation description |
-| `single` | `() => RelationKeyTargetBuilder<..., true>` | Change to 1:1 (single object) |
+`description` and `single` are configured via the factory function's `opts` parameter (3rd argument to `relationKeyTarget()`), not via method chaining.
+
+This class has no methods — it is a data holder for relation metadata.
 
 ## createRelationFactory
 
@@ -284,10 +278,10 @@ Creates a relation factory. For `TableBuilder`: provides `foreignKey`, `foreignK
 
 | Method | Signature | Description |
 |--------|-----------|-------------|
-| `foreignKey` | `(columns: TColumnKey[], targetFn: () => TableBuilder) => ForeignKeyBuilder` | N:1 FK (creates DB constraint) |
-| `foreignKeyTarget` | `(targetTableFn: () => TableBuilder, relationName: string) => ForeignKeyTargetBuilder` | 1:N FK reverse-reference |
-| `relationKey` | `(columns: TColumnKey[], targetFn: () => TableBuilder \| ViewBuilder) => RelationKeyBuilder` | N:1 logical relation (no DB FK) |
-| `relationKeyTarget` | `(targetTableFn: () => TableBuilder \| ViewBuilder, relationName: string) => RelationKeyTargetBuilder` | 1:N logical reverse-reference |
+| `foreignKey` | `(columns, targetFn, opts?: { description?: string })` | N:1 FK (creates DB constraint) |
+| `foreignKeyTarget` | `(targetTableFn, relationName, opts?: { single?: boolean; description?: string })` | 1:N FK reverse-reference. `{ single: true }` → 1:1 |
+| `relationKey` | `(columns, targetFn, opts?: { description?: string })` | N:1 logical relation (no DB FK) |
+| `relationKeyTarget` | `(targetTableFn, relationName, opts?: { single?: boolean; description?: string })` | 1:N logical reverse-reference. `{ single: true }` → 1:1 |
 
 ### Factory Methods (View)
 

package/docs/types.md

@@ -100,20 +100,7 @@ interface QueryBuildResult {
 
 ## DbContext Types
 
-### DbContextDef
-
-```typescript
-interface DbContextDef<TTables, TViews, TProcedures> {
-  readonly meta: {
-    readonly tables: TTables;
-    readonly views: TViews;
-    readonly procedures: TProcedures;
-    readonly migrations: Migration[];
-  };
-}
-```
-
-DbContext blueprint created by `defineDbContext()`. Contains only schema metadata, no runtime state.
+See [Core documentation](./core.md) for detailed descriptions of these types.
 
 ### DbContextBase
 
@@ -130,7 +117,7 @@ interface DbContextBase {
 }
 ```
 
-Core interface used internally by Queryable, Executable, and ViewBuilder.
+Core interface implemented by DbContext. Used internally by Queryable, Executable, and ViewBuilder.
 
 ### DbContextStatus
 
@@ -138,32 +125,6 @@ Core interface used internally by Queryable, Executable, and ViewBuilder.
 type DbContextStatus = "ready" | "connect" | "transact";
 ```
 
-### DbContextInstance
-
-```typescript
-type DbContextInstance<TDef extends DbContextDef<any, any, any>> =
-  DbContextBase &
-  DbContextConnectionMethods &
-  DbContextDdlMethods &
-  { [K in keyof TDef["meta"]["tables"]]: () => Queryable<...> } &
-  { [K in keyof TDef["meta"]["views"]]: () => Queryable<...> } &
-  { [K in keyof TDef["meta"]["procedures"]]: () => Executable<...> } &
-  { _migration: () => Queryable<{ code: string }, any> } &
-  { initialize(options?: { dbs?: string[]; force?: boolean }): Promise<void> };
-```
-
-Full DbContext instance type returned by `createDbContext()`. Includes queryable accessors for all tables/views, executable accessors for all procedures, connection methods, DDL methods, and `initialize()`.
-
-### DbContextConnectionMethods
-
-```typescript
-interface DbContextConnectionMethods {
-  connect<TResult>(fn: () => Promise<TResult>, isolationLevel?: IsolationLevel): Promise<TResult>;
-  connectWithoutTransaction<TResult>(callback: () => Promise<TResult>): Promise<TResult>;
-  transaction<TResult>(fn: () => Promise<TResult>, isolationLevel?: IsolationLevel): Promise<TResult>;
-}
-```
-
 ### DbContextDdlMethods
 
 See [Core - DDL Execution Methods](./core.md#ddl-execution-methods) and [Core - DDL QueryDef Generators](./core.md#ddl-querydef-generators) for the full list of 18 DDL execution methods and 22 QueryDef generator methods.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplysm/orm-common",
-  "version": "14.0.16",
+  "version": "14.0.18",
   "description": "심플리즘 패키지 - ORM (common)",
   "author": "심플리즘",
   "license": "Apache-2.0",
@@ -19,9 +19,9 @@
   ],
   "sideEffects": false,
   "devDependencies": {
-    "@types/node": "^20.19.37"
+    "@types/node": "^20.19.39"
   },
   "dependencies": {
-    "@simplysm/core-common": "14.0.16"
+    "@simplysm/core-common": "14.0.18"
   }
 }