mega-framework 0.1.6 → 0.1.7

package/src/models/mongo-crud.js

@@ -0,0 +1,285 @@
+// @ts-check
+/**
+ * MegaModel 공통 CRUD — **mongo(document) 경로** (ADR-212 P3). SQL 경로(model-crud.js)와 같은 표면·
+ * 의미를 mongo 도큐먼트 연산(`this.db.collection(table).find/insertOne/updateOne/...`)으로 구현한다.
+ *
+ * SQL 과 동일하게 **`static schema`(ADR-209 $jsonSchema) 게이트**로 식별자 화이트리스트를 강제하고,
+ * filter 는 등호 AND + 배열(`$in`) + null 까지만(체인 쿼리빌더 없음). PK 는 mongo 네이티브 `_id`
+ * (스키마의 `_id: t.objectId().primary()` 에서 도출) — `findById` 는 `_id` 로 조회한다.
+ *
+ * # SQL 과 다른 의미차(정직 명시)
+ *   - **트랜잭션 자동 참여 없음**: SQL 은 `Model.query` 가 ALS txContext 로 자동 라우팅되지만, mongo CRUD 는
+ *     글로벌 `Db` 핸들의 collection 을 쓴다 → `withTransaction((db, session) => …)` 의 session 에 자동으로
+ *     묶이지 않는다. 트랜잭션 안 도큐먼트 연산은 raw `collection.op(doc, { session })` 를 직접 써야 한다.
+ *   - **updateOne/deleteOne "정확히 하나"**: mongo updateOne 은 본래 첫 건만 바꾸고 에러가 없다 → SQL 의
+ *     >1 throw 를 맞추려 **사전 countDocuments** 로 매칭 수를 센다. count→연산 사이는 비원자(데모 수준 보장).
+ *
+ * @module models/mongo-crud
+ */
+import { MegaInternalError } from '../errors/http-errors.js'
+import { getModelMeta } from './model-crud.js'
+import { assertColumn, assertNonNegInt } from './crud-sql-builder.js'
+
+/** mongo 컬렉션 핸들 + schema 화이트리스트(+`_id`)·PK 메타. @param {any} Model @returns {{ col: any, cols: Set<string>, pk: string }} */
+function mongoCtx(Model) {
+  const meta = getModelMeta(Model) // schema 없으면 model.crud_requires_schema (SQL 과 동일 게이트)
+  const cols = new Set(meta.cols)
+  cols.add('_id') // mongo PK 는 항상 허용(스키마 미선언이어도 필터/조회 가능)
+  return { col: Model.db.collection(meta.table), cols, pk: meta.pk ?? '_id' }
+}
+
+/**
+ * filter → mongo 쿼리 도큐먼트. 등호 + 배열(`$in`) + null 만(ADR-212 경계). `undefined` 는 throw.
+ * @param {Record<string, any>} filter @param {Set<string>} cols @param {string} model @returns {Record<string, any>}
+ */
+function toQuery(filter, cols, model) {
+  /** @type {Record<string, any>} */
+  const q = {}
+  for (const [k, v] of Object.entries(filter)) {
+    assertColumn(k, cols, model, 'filter')
+    if (v === undefined) {
+      throw new MegaInternalError(
+        'model.invalid_filter',
+        `${model}: filter['${k}'] 가 undefined 입니다(null 과 구분 — 의도 모호).`,
+        { details: { model, column: k } },
+      )
+    }
+    q[k] = Array.isArray(v) ? { $in: v } : v // 빈 배열 → {$in: []} 는 매칭 0(안전). null → 그대로(null 매칭).
+  }
+  return q
+}
+
+/**
+ * select → mongo projection. 미지정이면 전체(undefined). 지정 시 inclusion + `_id` 제외(요청 안 했을 때).
+ * @param {string[]|undefined} select @param {Set<string>} cols @param {string} model @returns {Record<string, 0|1>|undefined}
+ */
+function toProjection(select, cols, model) {
+  if (!Array.isArray(select) || select.length === 0) return undefined
+  /** @type {Record<string, 0|1>} */
+  const p = {}
+  for (const c of select) {
+    assertColumn(c, cols, model, 'select')
+    p[c] = 1
+  }
+  if (!select.includes('_id')) p._id = 0 // 도메인 형태 — 명시 안 하면 _id 숨김(inclusion + _id 제외만 mongo 허용 조합).
+  return p
+}
+
+/** orderBy → mongo sort 도큐먼트. @param {any} orderBy @param {Set<string>} cols @param {string} model @returns {Record<string, 1|-1>|undefined} */
+function toSort(orderBy, cols, model) {
+  if (orderBy === undefined) return undefined
+  const list = typeof orderBy === 'string' ? [{ column: orderBy }] : orderBy
+  if (!Array.isArray(list) || list.length === 0) return undefined
+  /** @type {Record<string, 1|-1>} */
+  const s = {}
+  for (const o of list) {
+    const col = typeof o === 'string' ? o : o.column
+    assertColumn(col, cols, model, 'orderBy')
+    const dir = typeof o === 'string' ? 'asc' : (o.dir ?? 'asc')
+    if (dir !== 'asc' && dir !== 'desc') {
+      throw new MegaInternalError(
+        'model.invalid_pagination',
+        `${model}: orderBy dir 은 'asc'|'desc' 만 — got '${dir}'.`,
+        { details: { model, dir } },
+      )
+    }
+    s[col] = dir === 'desc' ? -1 : 1
+  }
+  return s
+}
+
+/** @param {any} Model @param {string} method @param {number} n */
+function multipleMatches(Model, method, n) {
+  return new MegaInternalError(
+    'model.multiple_matches',
+    `${Model.name}.${method}: filter 가 ${n} 건에 매칭됐습니다("정확히 하나" 위반). _id/unique filter 를 쓰거나 ${method.replace('One', 'Many')} 를 쓰세요.`,
+    {
+      details: { model: Model.name, method, matched: n },
+    },
+  )
+}
+
+// ── 읽기 ───────────────────────────────────────────────────────────────────
+
+/** @param {any} Model @param {Record<string, any>} filter @param {{ select?: string[] }} [opts] @returns {Promise<any|null>} */
+export async function findOne(Model, filter, opts = {}) {
+  const { col, cols } = mongoCtx(Model)
+  const projection = toProjection(opts.select, cols, Model.name)
+  return col.findOne(toQuery(filter ?? {}, cols, Model.name), projection ? { projection } : {})
+}
+
+/** @param {any} Model @param {Record<string, any>} filter @param {{ select?: string[], orderBy?: any, limit?: number, offset?: number }} [opts] @returns {Promise<any[]>} */
+export async function findMany(Model, filter, opts = {}) {
+  const { col, cols } = mongoCtx(Model)
+  const projection = toProjection(opts.select, cols, Model.name)
+  let cur = col.find(toQuery(filter ?? {}, cols, Model.name), projection ? { projection } : {})
+  const sort = toSort(opts.orderBy, cols, Model.name)
+  if (sort) cur = cur.sort(sort)
+  if (opts.offset !== undefined) cur = cur.skip(assertNonNegInt(opts.offset, 'offset', Model.name))
+  if (opts.limit !== undefined) cur = cur.limit(assertNonNegInt(opts.limit, 'limit', Model.name))
+  return cur.toArray()
+}
+
+/** @param {any} Model @param {any} id @param {{ select?: string[] }} [opts] @returns {Promise<any|null>} */
+export async function findById(Model, id, opts = {}) {
+  const { pk } = mongoCtx(Model)
+  return findOne(Model, { [pk]: id }, opts)
+}
+
+/** @param {any} Model @param {Record<string, any>} [filter] @returns {Promise<number>} */
+export async function count(Model, filter = {}) {
+  const { col, cols } = mongoCtx(Model)
+  return col.countDocuments(toQuery(filter, cols, Model.name))
+}
+
+/** @param {any} Model @param {Record<string, any>} filter @returns {Promise<boolean>} */
+export async function exists(Model, filter) {
+  const { col, cols } = mongoCtx(Model)
+  return (await col.countDocuments(toQuery(filter ?? {}, cols, Model.name), { limit: 1 })) > 0
+}
+
+/** @param {any} Model @param {Record<string, any>} filter @param {{ select?: string[], orderBy?: any, limit: number, offset?: number, withTotal?: boolean }} opts @returns {Promise<{ rows: any[], limit: number, offset: number, total?: number }>} */
+export async function paginate(Model, filter, opts) {
+  const limit = assertNonNegInt(opts?.limit, 'limit', Model.name)
+  const offset = opts?.offset !== undefined ? assertNonNegInt(opts.offset, 'offset', Model.name) : 0
+  const rows = await findMany(Model, filter, {
+    select: opts?.select,
+    orderBy: opts?.orderBy,
+    limit,
+    offset,
+  })
+  /** @type {{ rows: any[], limit: number, offset: number, total?: number }} */
+  const out = { rows, limit, offset }
+  if (opts?.withTotal === true) out.total = await count(Model, filter ?? {})
+  return out
+}
+
+// ── 쓰기 ───────────────────────────────────────────────────────────────────
+
+/** 삽입 도큐먼트 컬럼 검증. @param {any} Model @param {Record<string, any>} data @param {Set<string>} cols */
+function assertInsert(Model, data, cols) {
+  const keys = Object.keys(data ?? {})
+  if (keys.length === 0)
+    throw new MegaInternalError('model.empty_insert', `${Model.name}: 삽입할 필드가 없습니다.`, {
+      details: { model: Model.name },
+    })
+  keys.forEach((k) => assertColumn(k, cols, Model.name, 'data'))
+}
+
+/** @param {any} Model @param {Record<string, any>} data @param {{ returning?: boolean }} [opts] @returns {Promise<any>} */
+export async function insertOne(Model, data, opts = {}) {
+  const { col, cols } = mongoCtx(Model)
+  assertInsert(Model, data, cols)
+  const res = await col.insertOne({ ...data })
+  if (opts.returning === true) return col.findOne({ _id: res.insertedId })
+  return res.insertedId // 기본 — 새 _id
+}
+
+/** @param {any} Model @param {Record<string, any>[]} rows @param {{ returning?: boolean }} [opts] @returns {Promise<{ count: number } | any[]>} */
+export async function insertMany(Model, rows, opts = {}) {
+  if (!Array.isArray(rows) || rows.length === 0) return opts.returning === true ? [] : { count: 0 }
+  const { col, cols } = mongoCtx(Model)
+  rows.forEach((r) => assertInsert(Model, r, cols))
+  const res = await col.insertMany(rows.map((r) => ({ ...r })))
+  if (opts.returning === true) {
+    const ids = Object.values(res.insertedIds)
+    return col.find({ _id: { $in: ids } }).toArray()
+  }
+  return { count: res.insertedCount }
+}
+
+/** patch 검증(빈 patch throw). @param {any} Model @param {Record<string, any>} patch @param {Set<string>} cols @returns {string[]} */
+function assertPatch(Model, patch, cols) {
+  const keys = Object.keys(patch ?? {})
+  if (keys.length === 0)
+    throw new MegaInternalError(
+      'model.empty_patch',
+      `${Model.name}: 갱신할 필드(patch)가 없습니다.`,
+      { details: { model: Model.name } },
+    )
+  keys.forEach((k) => assertColumn(k, cols, Model.name, 'patch'))
+  return keys
+}
+
+/** @param {any} Model @param {Record<string, any>} filter @param {Record<string, any>} patch @returns {Promise<number>} */
+export async function updateOne(Model, filter, patch) {
+  const { col, cols } = mongoCtx(Model)
+  if (Object.keys(filter ?? {}).length === 0) {
+    throw new MegaInternalError(
+      'model.invalid_filter',
+      `${Model.name}: updateOne 은 대상을 특정하는 filter 가 필요합니다(빈 filter 금지).`,
+      { details: { model: Model.name } },
+    )
+  }
+  assertPatch(Model, patch, cols)
+  const q = toQuery(filter, cols, Model.name)
+  // "정확히 하나" — 사전 count(비원자, 데모 수준). >1 이면 변경 없이 throw.
+  const n = await col.countDocuments(q, { limit: 2 })
+  if (n > 1) throw multipleMatches(Model, 'updateOne', n)
+  return (await col.updateOne(q, { $set: patch })).matchedCount
+}
+
+/** @param {any} Model @param {Record<string, any>} filter @param {Record<string, any>} patch @param {{ all?: boolean }} [opts] @returns {Promise<number>} */
+export async function updateMany(Model, filter, patch, opts = {}) {
+  const { col, cols } = mongoCtx(Model)
+  assertPatch(Model, patch, cols)
+  if (Object.keys(filter ?? {}).length === 0 && opts.all !== true) {
+    throw new MegaInternalError(
+      'model.unbounded_write',
+      `${Model.name}: 빈 filter 의 전체 갱신은 막혀 있습니다. 의도면 { all: true } 를 쓰세요.`,
+      { details: { model: Model.name } },
+    )
+  }
+  return (await col.updateMany(toQuery(filter ?? {}, cols, Model.name), { $set: patch }))
+    .matchedCount
+}
+
+/** @param {any} Model @param {Record<string, any>} filter @returns {Promise<number>} */
+export async function deleteOne(Model, filter) {
+  const { col, cols } = mongoCtx(Model)
+  if (Object.keys(filter ?? {}).length === 0) {
+    throw new MegaInternalError(
+      'model.invalid_filter',
+      `${Model.name}: deleteOne 은 대상을 특정하는 filter 가 필요합니다(빈 filter 금지).`,
+      { details: { model: Model.name } },
+    )
+  }
+  const q = toQuery(filter, cols, Model.name)
+  const n = await col.countDocuments(q, { limit: 2 })
+  if (n > 1) throw multipleMatches(Model, 'deleteOne', n)
+  return (await col.deleteOne(q)).deletedCount
+}
+
+/** @param {any} Model @param {Record<string, any>} filter @param {{ all?: boolean }} [opts] @returns {Promise<number>} */
+export async function deleteMany(Model, filter, opts = {}) {
+  const { col, cols } = mongoCtx(Model)
+  if (Object.keys(filter ?? {}).length === 0 && opts.all !== true) {
+    throw new MegaInternalError(
+      'model.unbounded_write',
+      `${Model.name}: 빈 filter 의 전체 삭제는 막혀 있습니다. 의도면 { all: true } 를 쓰세요.`,
+      { details: { model: Model.name } },
+    )
+  }
+  return (await col.deleteMany(toQuery(filter ?? {}, cols, Model.name))).deletedCount
+}
+
+/** @param {any} Model @param {Record<string, any>} data @param {{ conflict: string[], returning?: boolean }} opts @returns {Promise<any>} */
+export async function upsert(Model, data, opts) {
+  const { col, cols } = mongoCtx(Model)
+  assertInsert(Model, data, cols)
+  const conflict = opts?.conflict
+  if (!Array.isArray(conflict) || conflict.length === 0) {
+    throw new MegaInternalError(
+      'model.invalid_conflict_target',
+      `${Model.name}: upsert 는 opts.conflict(충돌 필드 배열)가 필요합니다.`,
+      { details: { model: Model.name } },
+    )
+  }
+  conflict.forEach((c) => assertColumn(c, cols, Model.name, 'conflict'))
+  /** @type {Record<string, any>} */
+  const q = {}
+  conflict.forEach((c) => (q[c] = data[c]))
+  await col.updateOne(q, { $set: { ...data } }, { upsert: true })
+  if (opts.returning === true) return col.findOne(q)
+  return undefined
+}

package/templates/model/code-mongo.tpl

@@ -0,0 +1,35 @@
+// @ts-check
+import { MegaModel } from 'mega-framework'
+
+/**
+ * {{Name}} 모델(mongodb) — `static table` 이 collection 이름이다(SQL table 과 통일, ADR-081).
+ * `static adapter` 는 mega.config.js 의 services.databases 키를 가리킨다(ADR-061).
+ *
+ * `static schema`(빌더)를 선언하면 자동 마이그레이션 트랙에 합류한다(ADR-204/209 옵트인) —
+ * `mega migrate:generate` 가 collection validator($jsonSchema)·인덱스를 생성/갱신한다.
+ * mongo 차이(ADR-209/210): `_id` 는 자동 ObjectId(명시는 `_id: t.objectId().primary()` 만),
+ * `.default()` 미지원(기본값은 도큐먼트 생성 시 앱 레벨), FK/`.check()` 없음(cross-field 는
+ * 생성 파일 raw 편집의 `$expr`), 명시 null 을 저장하는 필드는 `.nullable()`, 중첩 도큐먼트는
+ * `t.object({...})`. 블록 삭제 시 raw 마이그레이션 트랙으로 돌아간다(호환).
+ */
+export class {{Name}} extends MegaModel {
+  static adapter = '{{adapter}}'
+  static table = '{{table}}'
+
+  // 자동 마이그레이션 스키마(ADR-209) — 빌더 API 는 docs/guide/03-service-model-db.md §5 참조.
+  static schema = (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

@@ -4,11 +4,25 @@ import { MegaModel } from 'mega-framework'
 /**
  * {{Name}} 모델 — 데이터 소스는 `static table` 로 통일(SQL table / Mongo collection, ADR-081).
  * `static adapter` 는 mega.config.js 의 services.databases 키를 가리킨다(ADR-061).
+ *
+ * `static schema`(빌더)를 선언하면 자동 마이그레이션 트랙에 합류한다(ADR-204 옵트인) —
+ * 모델 변경 후 `mega migrate:generate` 가 diff 로 마이그레이션 파일을 만들고 `mega migrate` 로
+ * 적용한다. 이 블록을 삭제하면 raw SQL 마이그레이션(`mega g migration <name>`)만 쓰는 트랙으로
+ * 돌아간다(기존 모델과 동일 — 호환).
  */
 export class {{Name}} extends MegaModel {
-  static adapter = 'primary'
+  static adapter = '{{adapter}}'
   static table = '{{table}}'
 
+  // 자동 마이그레이션 스키마(ADR-204) — 빌더 API 는 docs/guide/03-service-model-db.md §5 참조.
+  static schema = (t) => ({
+    id: t.serial().primary(),
+    name: t.varchar(100).notNull(),
+    createdAt: t.timestamptz().defaultNow(),
+  })
+
+  // 인덱스(선택): static indexes = (t) => [t.index(['name'], { unique: true })]
+
   /**
    * id 로 1건 조회. `this.query` 는 계측된 어댑터 query 위임(ADR-138).
    * @param {string|number} id

package/templates/model/test-mongo.tpl

@@ -0,0 +1,38 @@
+// @ts-check
+import { describe, test, expect } from 'vitest'
+import { MegaModel } from 'mega-framework'
+import { {{Name}} } from '{{importPath}}'
+
+describe('{{Name}} model (mongodb)', () => {
+  test('MegaModel 을 상속하고 static table(collection)/adapter 설정됨', () => {
+    expect(Object.getPrototypeOf({{Name}})).toBe(MegaModel)
+    expect({{Name}}.table).toBe('{{table}}')
+    expect(typeof {{Name}}.adapter).toBe('string')
+  })
+
+  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

@@ -10,6 +10,10 @@ describe('{{Name}} model', () => {
     expect(typeof {{Name}}.adapter).toBe('string')
   })
 
+  test('schema 빌더 선언 — 자동 마이그레이션 트랙 옵트인(ADR-204)', () => {
+    expect(typeof {{Name}}.schema).toBe('function')
+  })
+
   test('findById — 어댑터 query 에 위임', async () => {
     const orig = {{Name}}.query
     /** @type {any[]} */

package/types/adapters/adapter-manager.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 전역 config(`services.databases/caches/buses`)로부터 어댑터 인스턴스를 만든다 (lifecycle 1단계).
+ *
+ * 각 도메인의 `<globalKey>: { driver, ...opts }` 마다 `registry.resolve(driver)` → `new Cls(opts)`.
+ * driver 미등록(빌트인은 import 시 자기등록)·미지정·도메인 불일치는 즉시 throw (부팅 abort, fail-fast).
+ *
+ * # 종료 순서 (중요)
+ *   본 함수가 LIFO shutdown hook 을 등록하므로, **MegaApp 생성보다 먼저** 호출해야 한다. MegaShutdown
+ *   은 LIFO(나중 등록이 먼저 실행) — 어댑터 hook 을 앱 hook 보다 먼저 등록하면, 종료 시 앱(HTTP/WS)이
+ *   먼저 닫히고 그 다음 어댑터가 끊긴다(docs/10: ClosingHttp → … → DisconnectingAdapters).
+ *
+ * @param {{ services?: Record<string, any> }} [globalConfig] - mega.config.js (default export).
+ * @param {{ registerShutdownHook?: boolean }} [opts] - 테스트 격리용으로 hook 등록을 끌 수 있음(기본 on).
+ * @returns {void}
+ */
+export function buildFromGlobalConfig(globalConfig?: {
+    services?: Record<string, any>;
+}, { registerShutdownHook }?: {
+    registerShutdownHook?: boolean;
+}): void;
+/**
+ * 도메인+globalKey 로 공유 어댑터 인스턴스 조회. 없으면 `adapter.not_registered` throw (silent X).
+ *
+ * @param {'db'|'cache'|'bus'|'lock'} domain
+ * @param {string} key - globalKey.
+ * @returns {import('./mega-adapter.js').MegaAdapter}
+ */
+export function get(domain: "db" | "cache" | "bus" | "lock", key: string): import("./mega-adapter.js").MegaAdapter;
+/**
+ * 등록 여부 (Boolean — `has*`, ADR-036).
+ * @param {'db'|'cache'|'bus'|'lock'} domain @param {string} key @returns {boolean}
+ */
+export function has(domain: "db" | "cache" | "bus" | "lock", key: string): boolean;
+/**
+ * 전체 인스턴스 스냅샷 (디버그·테스트·헬스용). 등록 순서대로.
+ * @returns {Array<{ domain: 'db'|'cache'|'bus'|'lock', key: string, driver: string, state: string }>}
+ */
+export function list(): Array<{
+    domain: "db" | "cache" | "bus" | "lock";
+    key: string;
+    driver: string;
+    state: string;
+}>;
+/**
+ * 전체 어댑터 엔트리(인스턴스 포함)를 등록 순서대로 반환 — 외부 부착자(`MegaTracing`)가
+ * 모든 공유 어댑터에 hook 리스너를 일괄 구독할 때 쓴다. {@link list} 와 달리 raw 어댑터 인스턴스를
+ * 노출하므로 디버그·트레이싱 부착 외 용도로는 신중히 사용.
+ *
+ * @returns {AdapterEntry[]}
+ */
+export function entries(): AdapterEntry[];
+/**
+ * 모든 어댑터 connect (부팅 6단계). 병렬 시도하되 **fail-fast + 자동 cleanup** (ADR-102 QA M-A).
+ * 하나라도 실패하면 부팅을 abort 하기 위해 첫 실패 에러를 throw 하는데, 그 전에 이미 connect 된
+ * 어댑터를 **등록 역순(LIFO)으로 best-effort disconnect** 해서 연결 풀 leak 을 막는다 — 호출자가
+ * catch 안 해도 매니저 레벨에서 자원을 회수한다(call-site CLI 책임에만 의존하지 않음).
+ *
+ * `ping:true` 면 connect 직후 `healthCheck()` 를 1회 호출해 ok=false 면 `adapter.health_failed`
+ * throw (헬스까지 검증). ping 실패 어댑터도 connect 자체는 성공했으므로 cleanup 대상에 포함된다.
+ *
+ * cleanup 중 disconnect 가 실패해도 원래 connect 실패 에러를 우선 전파한다 — cleanup 실패는
+ * 비치명적이라 warn 로그만 남기고 삼킨다(부팅 abort 정리 중 한 어댑터 정리 실패가
+ * 진짜 원인(connect 실패)을 덮으면 안 됨).
+ *
+ * @param {{ logger?: any, ping?: boolean }} [opts]
+ * @returns {Promise<void>}
+ */
+export function connectAll({ logger, ping }?: {
+    logger?: any;
+    ping?: boolean;
+}): Promise<void>;
+/**
+ * 모든 어댑터 disconnect — 등록 **역순(LIFO)** (docs/10 §6, 07-sequence-diagrams §6). graceful
+ * shutdown 중이므로 개별 disconnect 실패는 비치명적: warn 후 다음 어댑터로 계속한다( * 한 어댑터 정리 실패가 나머지 정리를 막으면 안 됨).
+ *
+ * @param {{ logger?: any }} [opts]
+ * @returns {Promise<void>}
+ */
+export function disconnectAll({ logger }?: {
+    logger?: any;
+}): Promise<void>;
+/**
+ * 테스트용 reset — 인스턴스 비우고 shutdown hook 해제.
+ * @returns {void}
+ */
+export function _reset(): void;
+export type AdapterEntry = {
+    domain: "db" | "cache" | "bus" | "lock";
+    /**
+     * - globalKey (services.<configKey>.<key>).
+     */
+    key: string;
+    driver: string;
+    adapter: import("./mega-adapter.js").MegaAdapter;
+};

package/types/adapters/adapter-options.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 트랜잭션 격리수준 옵션 검증 + SQL 조각 변환 (ADR-190). `undefined` 는 driver 디폴트 위임(undefined 반환).
+ * @param {unknown} isolation - `withTransaction` 의 `opts.isolation`.
+ * @param {string} driver - 에러 메시지용 driver 이름.
+ * @returns {string | undefined} `SET TRANSACTION ISOLATION LEVEL <조각>` 에 쓸 SQL 조각.
+ * @throws {MegaValidationError} `adapter.invalid_option` - 화이트리스트 외 값.
+ */
+export function resolveTxIsolation(isolation: unknown, driver: string): string | undefined;
+/**
+ * 양의 정수(> 0) 검증 (undefined 통과). 위반 시 `adapter.invalid_option` throw.
+ * @param {string} name @param {unknown} value @param {Record<string, unknown>} [extra] @returns {void}
+ */
+export function assertPositiveInt(name: string, value: unknown, extra?: Record<string, unknown>): void;
+/**
+ * 음 아닌 정수(>= 0) 검증 (undefined 통과). 0 은 드라이버에서 "무제한/즉시/never" 의미로 허용.
+ * @param {string} name @param {unknown} value @param {Record<string, unknown>} [extra] @returns {void}
+ */
+export function assertNonNegativeInt(name: string, value: unknown, extra?: Record<string, unknown>): void;
+/**
+ * 플레인 객체 검증 (undefined 통과). 배열·null·non-object 거부.
+ * @param {string} name @param {unknown} value @param {Record<string, unknown>} [extra] @returns {void}
+ */
+export function assertPlainObject(name: string, value: unknown, extra?: Record<string, unknown>): void;
+/**
+ * 연결 모드 결정(url XOR discrete) + 충돌·필수 검증.
+ *
+ * @param {Record<string, any>} config - 어댑터 생성자 config.
+ * @param {object} opts
+ * @param {string} opts.driver - 에러 details 용 드라이버명('postgres'|'mariadb'|'mongodb').
+ * @param {string} [opts.dbKey] - discrete db 키 이름(SQL='database', 기본값). Mongo 는 'dbName' 을
+ *   url 과 충돌시키지 않으므로 별도 처리(아래 dbConflictsWithUrl 참조).
+ * @param {boolean} [opts.dbConflictsWithUrl] - db 키가 url 과 상호 배타인지(SQL=true). Mongo 의 dbName 은
+ *   url(=connection)과 별개(=db 선택)라 false.
+ * @returns {{ url?: string, host?: string, port?: number, user?: string, password?: string, database?: string }}
+ *   url 모드면 `{ url }`, discrete 모드면 존재하는 연결필드만. (database 는 dbConflictsWithUrl=true 일 때만 포함.)
+ * @throws {MegaValidationError} `adapter.connection_conflict` / `adapter.connection_required` / `adapter.invalid_option`
+ */
+export function resolveConnection(config: Record<string, any>, { driver, dbKey, dbConflictsWithUrl }: {
+    driver: string;
+    dbKey?: string;
+    dbConflictsWithUrl?: boolean;
+}): {
+    url?: string;
+    host?: string;
+    port?: number;
+    user?: string;
+    password?: string;
+    database?: string;
+};
+/**
+ * 공통 풀 인터페이스(`{ min, max, idleTimeoutMs, acquireTimeoutMs, maxLifetimeMs }`)를 드라이버
+ * 풀 옵션 객체로 변환·검증한다.
+ *
+ * - 알 수 없는 풀 키 → `adapter.invalid_option`(오타 fail-fast).
+ * - 드라이버 미지원 키(spec 값 null, 예: mariadb/mongo 의 maxLifetimeMs) → `adapter.invalid_option`(silent 무시 X).
+ * - `max` 는 양의 정수, 그 외(min·*Ms)는 음 아닌 정수.
+ * - `divideBy` 가 있으면 ms→초 변환(floor).
+ *
+ * @param {unknown} pool - config.pool.
+ * @param {Record<string, { key: string, divideBy?: number } | null>} spec - 드라이버 풀 매핑.
+ * @param {string} driver - 에러 details 용 드라이버명.
+ * @returns {Record<string, number>} 드라이버 풀 옵션 객체(빈 객체 가능).
+ */
+export function normalizePool(pool: unknown, spec: Record<string, {
+    key: string;
+    divideBy?: number;
+} | null>, driver: string): Record<string, number>;
+/**
+ * pg 풀 매핑 — 값이 null 이면 미지원(throw), `{ key, divideBy? }` 면 키 이름 변경(+단위 변환).
+ * @type {Record<string, { key: string, divideBy?: number } | null>}
+ */
+export const PG_POOL_SPEC: Record<string, {
+    key: string;
+    divideBy?: number;
+} | null>;
+/**
+ * mariadb 풀 매핑 — idleTimeout 은 초 단위(ms÷1000). maxLifetime 동등물 없음(미지원).
+ * @type {Record<string, { key: string, divideBy?: number } | null>}
+ */
+export const MARIA_POOL_SPEC: Record<string, {
+    key: string;
+    divideBy?: number;
+} | null>;
+/**
+ * mongodb 풀 매핑 — 전부 ms. maxLifetime 동등물 없음(미지원).
+ * @type {Record<string, { key: string, divideBy?: number } | null>}
+ */
+export const MONGO_POOL_SPEC: Record<string, {
+    key: string;
+    divideBy?: number;
+} | null>;