mega-framework 0.1.11 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mega-framework",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Node.js 마이크로프레임웍 + CLI — Slim의 가벼움 + Rails의 관례",
   "type": "module",
   "engines": {

package/sample/crud/docs/guide/03-service-model-db.md

@@ -802,12 +802,68 @@ export class User extends MegaModel {
 
 - **옵트인**이다 — `static schema` 가 없는 모델(레거시 raw SQL 운용)은 그냥 무시된다.
 - 같은 `static schema` 선언은 **공통 CRUD([§2-1](#2-1-공통-crud-static-schema-opt-in-adr-212))도 함께 켠다**(SQL 어댑터) — "스키마 1선언 = 마이그레이션 + CRUD".
-- 타입: `serial/bigSerial/integer/bigInteger/smallInteger/real/doublePrecision/decimal(p,s)/varchar(n)/
-  text/char(n)/boolean/timestamp/timestamptz/date/time/uuid/json/jsonb/enum(values)/bytea`.
-- 체인: `.primary() .notNull() .unique({name?}) .default(v | {raw}) .defaultNow() .check(expr,{name?})
-  .references(model, col, {onDelete?, onUpdate?, name?}) .comment(text)`. 복합 PK 는 `t.primary(['a','b'])`.
-- FK 대상은 **모델 이름**(file-scan 범위 안에 있어야 함 — 없으면 fail-fast). 관계는 FK 까지만 —
-  조인 헬퍼/lazy load 같은 ORM 기능은 없다(ADR-009).
+
+#### 컬럼 타입 — `t.<type>()`
+
+각 타입 메서드는 `ColumnBuilder` 를 반환하므로 아래 **수식어를 체인**할 수 있다(`src/core/migration/schema-builder.js`).
+
+| 분류 | 메서드 | 비고 |
+| --- | --- | --- |
+| 정수 | `t.serial()` · `t.bigSerial()` | 자동증가(postgres SERIAL / BIGSERIAL) |
+| 정수 | `t.integer()` · `t.bigInteger()` · `t.smallInteger()` | |
+| 실수 | `t.real()` · `t.doublePrecision()` | |
+| 정밀수 | `t.decimal(precision, scale)` | NUMERIC(p,s) |
+| 문자열 | `t.varchar(maxLength)` · `t.char(length)` · `t.text()` | |
+| 논리 | `t.boolean()` | |
+| 시간 | `t.timestamp()` · `t.timestamptz()` · `t.date()` · `t.time()` | |
+| 기타 | `t.uuid()` · `t.json()` · `t.jsonb()` · `t.bytea()` | |
+| 열거 | `t.enum(values, { name? })` | postgres 는 `TEXT + CHECK (col IN (...))` 로 렌더(native enum 미사용 — 값 추가/삭제가 제약 교체로 단순) |
+| **mongo 전용** | `t.objectId()` · `t.object(shape?)` · `t.array(items?, { uniqueItems? })` | SQL dialect 는 렌더 시 거부. `object`/`array` 의 중첩 필드는 타입·길이·enum·notNull(→required)만 — unique/primary/references/check 는 **최상위 전용** |
+
+#### 컬럼 수식어 (체인) — `ColumnBuilder`
+
+| 메서드 | 뜻 |
+| --- | --- |
+| `.primary()` | 단일 컬럼 PRIMARY KEY. 복합 PK 는 `t.primary(['a','b'])`(아래) |
+| `.notNull()` | NOT NULL |
+| `.nullable()` | 명시 null 허용. SQL 은 기본 nullable 이라 선언적 표시(no-op), mongo 는 `['type','null']` 유니온. `.notNull()` 과 **동시 사용 불가** |
+| `.unique({ name? })` | UNIQUE 제약. 이름 미지정 시 `uniq_<table>_<col>` |
+| `.default(value)` | DEFAULT. literal(string/number/boolean/null) 또는 `{ raw: 'expr' }`(raw SQL 식) |
+| `.defaultNow()` | `DEFAULT CURRENT_TIMESTAMP` 단축 |
+| `.check(expr, { name? })` | CHECK 제약. 이름 미지정 시 `chk_<table>_<col>` |
+| `.references(model, col, { onDelete?, onUpdate?, name? })` | FK. 대상은 **모델 이름**(테이블명 아님 — 스냅샷 시 해석). `onDelete`/`onUpdate` ∈ `cascade · set null · set default · restrict · no action` |
+| `.comment(text)` | `COMMENT ON COLUMN` |
+
+- 테이블 레벨: `t.primary(['a','b'])` — **복합 PRIMARY KEY**(반환값 없음, 컬럼 맵엔 안 들어감). 단일 PK 는 컬럼 체인 `.primary()`.
+- FK 대상 모델은 **file-scan 범위 안에 있어야** 한다(없으면 fail-fast). 관계는 FK 까지만 — 조인 헬퍼/lazy load 같은 ORM 기능은 없다(ADR-009).
+
+#### 인덱스 — `static indexes = (t) => [ t.index(...) ]`
+
+```js
+static indexes = (t) => [
+  t.index(['role', 'createdAt']),                                  // 복합. 이름 자동: idx_<table>_<col…> (= idx_users_role_createdAt)
+  t.index(['email'], { unique: true }),                            // unique 인덱스
+  t.index({ expression: 'lower(email)' }, { name: 'idx_users_email_lower' }),  // 표현식 인덱스
+  t.index(['org_id'], { where: 'deleted_at IS NULL' }),            // 부분 인덱스(조건부)
+  t.index(['payload'], { using: 'gin' }),                          // 인덱스 방법(postgres USING)
+]
+```
+
+| `t.index(컬럼들|식, opts)` 인자 | 뜻 |
+| --- | --- |
+| 1번째: `'col'` / `['a','b']` / `{ expression: 'lower(x)' }` | 단일·복합 컬럼 또는 표현식 인덱스 |
+| `opts.name` | 인덱스 이름 override(기본 dialect 표준명) |
+| `opts.unique` | `true` 면 UNIQUE 인덱스 |
+| `opts.where` | **부분 인덱스** WHERE 조건(예: `'deleted_at IS NULL'`) |
+| `opts.using` | 인덱스 방법(postgres `USING` — 예: `gin`/`gist`/`hash`) |
+
+> 컬럼에 직접 `.unique()` 를 거는 것(=UNIQUE **제약**)과 `t.index([...], { unique: true })`(=UNIQUE **인덱스**)는
+> 비슷하나, 후자는 복합·표현식·부분 인덱스를 지원한다. 단일 컬럼 유일성은 `.unique()` 가 간단하다.
+
+**자동 이름 규칙**(postgres dialect, `{ name }` 미지정 시): 인덱스 `idx_<table>_<cols>` · UNIQUE 인덱스/제약
+`uniq_<table>_<cols>` · FK `fk_<table>_<col>_<reftable>` · CHECK `chk_<table>_<col>`. 63byte 초과 시 거부되니
+길면 `{ name }` 으로 짧게 지정한다.
+
 - 제외 규칙: `_` 로 시작하는 파일/폴더, `*.test.js`, `static skip = true`.
 - 식별자는 63byte(postgres 한도)를 넘으면 거부된다 — 합성 이름(`fk_…`)이 걸리면 `{name}` 으로
   짧은 이름을 명시하면 된다.

package/templates/model/code-mongo.tpl

@@ -17,19 +17,11 @@ export class {{Name}} extends MegaModel {
   static table = '{{table}}'
 
   // 자동 마이그레이션 스키마(ADR-209) — 빌더 API 는 docs/guide/03-service-model-db.md §5 참조.
-  static schema = (t) => ({
+  static schema = /** @param {any} t */ (t) => ({
     name: t.varchar(100).notNull(),
     createdAt: t.timestamptz().notNull(), // 생성 시 앱에서 new Date() 로 채운다(mongo 는 default 미지원)
   })
 
   // 인덱스(선택): static indexes = (t) => [t.index(['name'], { unique: true })]
 
-  /**
-   * _id 로 1건 조회 — `this.db` 는 native mongodb `Db`(ADR-009), 도큐먼트 API 직접 사용.
-   * @param {import('mongodb').ObjectId} id
-   * @returns {Promise<object|null>}
-   */
-  static async findById(id) {
-    return this.db.collection(this.table).findOne({ _id: id })
-  }
 }

package/templates/model/code.tpl

@@ -15,7 +15,7 @@ export class {{Name}} extends MegaModel {
   static table = '{{table}}'
 
   // 자동 마이그레이션 스키마(ADR-204) — 빌더 API 는 docs/guide/03-service-model-db.md §5 참조.
-  static schema = (t) => ({
+  static schema = /** @param {any} t */ (t) => ({
     id: t.serial().primary(),
     name: t.varchar(100).notNull(),
     createdAt: t.timestamptz().defaultNow(),
@@ -23,13 +23,4 @@ export class {{Name}} extends MegaModel {
 
   // 인덱스(선택): static indexes = (t) => [t.index(['name'], { unique: true })]
 
-  /**
-   * id 로 1건 조회. `this.query` 는 계측된 어댑터 query 위임(ADR-138).
-   * @param {string|number} id
-   * @returns {Promise<object|null>}
-   */
-  static async findById(id) {
-    const { rows } = await this.query('select * from {{table}} where id = $1', [id])
-    return rows[0] ?? null
-  }
 }

package/templates/model/test-mongo.tpl

@@ -12,27 +12,5 @@ describe('{{Name}} model (mongodb)', () => {
 
   test('schema 빌더 선언 — 자동 마이그레이션 트랙 옵트인(ADR-209)', () => {
     expect(typeof {{Name}}.schema).toBe('function')
-  })
-
-  test('findById — native Db 의 도큐먼트 API 에 위임', async () => {
-    /** @type {any[]} */
-    const calls = []
-    const fakeDb = {
-      collection: (/** @type {string} */ name) => ({
-        findOne: async (/** @type {any} */ filter) => {
-          calls.push({ name, filter })
-          return { _id: filter._id }
-        },
-      }),
-    }
-    // MegaModel.db 는 getter 라 서브클래스 own property 로 가린다(테스트 한정).
-    Object.defineProperty({{Name}}, 'db', { value: fakeDb, configurable: true })
-    try {
-      const doc = await {{Name}}.findById(/** @type {any} */ ('id-1'))
-      expect(doc).toEqual({ _id: 'id-1' })
-      expect(calls[0].name).toBe('{{table}}')
-    } finally {
-      delete /** @type {any} */ ({{Name}}).db
-    }
-  })
+  })  
 })

package/templates/model/test.tpl

@@ -13,21 +13,4 @@ describe('{{Name}} model', () => {
   test('schema 빌더 선언 — 자동 마이그레이션 트랙 옵트인(ADR-204)', () => {
     expect(typeof {{Name}}.schema).toBe('function')
   })
-
-  test('findById — 어댑터 query 에 위임', async () => {
-    const orig = {{Name}}.query
-    /** @type {any[]} */
-    const calls = []
-    {{Name}}.query = async (/** @type {string} */ sql, /** @type {any[]} */ params) => {
-      calls.push({ sql, params })
-      return { rows: [{ id: params[0] }] }
-    }
-    try {
-      const row = await {{Name}}.findById(7)
-      expect(row).toEqual({ id: 7 })
-      expect(calls[0].params).toEqual([7])
-    } finally {
-      {{Name}}.query = orig
-    }
-  })
 })