# lemon-fields 작성자: Claire `lemon-fields`는 `ts-transformer-keys`의 `keys()`를 generated registry 방식으로 옮기는 도구이다. 기존 방식: ```ts import { keys } from 'ts-transformer-keys'; export const USER_FIELDS = keys(); ``` 변경 후: ```ts import { fieldKeys } from './generated/field-registry'; export const USER_FIELDS = fieldKeys.userModel(); ``` - `migrate`: 기존 `keys()` 호출을 `fieldKeys.()`로 바꾼다. - `gen`: TypeScript checker로 ``의 field 목록을 읽고 `src/generated/field-registry.ts`를 만든다. - `--check`: generated registry가 최신인지 CI에서 확인한다. - `guard-common`: transformer spec의 `checkAllKeys` 안에 공통 모델 필드 검증을 삽입/갱신한다. - runtime에서는 transformer 없이 generated TypeScript 파일만 사용한다. ## 빠른 시작 ### 1. 설치 ```sh npm i --save-dev lemon-devkit ``` ### 2. 먼저 변경될 내용을 확인 ```sh npx lemon-fields migrate --dry-run --report --update-tsconfig ``` 이 명령은 source를 쓰지 않는다. 어떤 `keys()`가 어떤 `fieldKeys.()`로 바뀔지만 확인한다. ### 3. migration 적용 ```sh npx lemon-fields migrate --report --update-tsconfig ``` 이 단계에서 기존 코드가 아래처럼 바뀐다. ```ts // before export const USER_FIELDS = keys(); // after export const USER_FIELDS = fieldKeys.userModel(); ``` `--update-tsconfig`를 함께 쓰면 migration 완료 후 `ts-transformer-keys/transformer` plugin도 제거한다. ### 4. registry 생성 ```sh npx lemon-fields gen --report ``` 생성되는 파일은 기본적으로 아래 위치이다. ```txt src/generated/field-registry.ts ``` 생성 결과는 이런 형태이다. ```ts export const fieldKeys = { userModel: () => ["id", "name"] as Array>, } as const; ``` ### 5. 최신 상태 확인 ```sh npx lemon-fields --check ``` generated registry가 source와 다르면 exit code `1`로 실패한다. CI에서는 이 명령을 쓰면 된다. ### 6. test watch 전에 공통필드 guard 실행 ```sh npx lemon-fields guard-common --report ``` 이 명령은 `src/**/*.spec.ts`에서 `checkAllKeys`를 찾고, 공통필드 검증 블록이 없으면 자동으로 넣는다. `fieldKeys` base는 registry 기준으로 맞춘다. 개발자는 보통 `test:watch` 앞에 붙여두면 된다. ```json { "scripts": { "test:watch": "lemon-fields guard-common && LS=1 jest --config=jest.config.json --watchAll" } } ``` 처음 실행하면 필요한 spec 파일이 업데이트된다. ```txt [lemon-fields] guard-common — 3 guard(s), 3 file(s) updated. ``` 이미 guard가 있으면 아무 파일도 고치지 않고 바로 test watch로 넘어간다. ```txt [lemon-fields] guard-common — 0 guard(s), 0 file(s) updated. ``` `$` 포함 여부는 spec의 base field 변수에서 자동 판별한다. `CORE_FIELDS`를 쓰면 `$`를 포함하고, `['meta']`처럼 `$`가 없는 base를 쓰면 `$`를 제외한다. `_id` 필터도 감지한다. ## package.json 예시 ```json { "scripts": { "fields:migrate": "lemon-fields migrate --report --update-tsconfig", "fields:gen": "lemon-fields gen --report", "fields:check": "lemon-fields --check", "fields:guard-common": "lemon-fields guard-common --report", "test:watch": "lemon-fields guard-common && LS=1 jest --config=jest.config.json --watchAll", "build": "npm run fields:gen && tsc" } } ``` `src/generated/field-registry.ts`는 source와 함께 commit 하는 것을 권장한다. 이 파일은 build 산출물처럼 보이지만, 실제 source가 import해서 사용하는 코드이다. ## 이후 개발할 때 새로운 field list가 필요하면 개발자가 직접 `fieldKeys.()` 호출을 추가한다. ```ts import { fieldKeys } from '../generated/field-registry'; export const USER_FIELDS = fieldKeys.userModel(); ``` 여기서 `userModel`이 registry key이다. `gen`은 이 이름을 다시 계산하지 않고 그대로 보존한다. 이름을 바꾸고 싶으면 generated 파일을 고치지 않는다. 호출 위치의 key를 바꾸고 다시 `gen`을 실행한다. ```ts export const USER_FIELDS = fieldKeys.publicUser(); ``` ```sh npx lemon-fields gen ``` ## 이름 충돌 규칙 ### `export const` 이름과 registry key는 별개 아래 코드에는 이름이 두 개 있다. ```ts export const USER_FIELDS = fieldKeys.userModel(); // ^^^^^^^^^^^ ^^^^^^^^^ // TypeScript export 이름 lemon-fields registry key ``` `USER_FIELDS`는 TypeScript module export 이름이다. 파일이 다르면 같은 이름을 써도 바로 충돌하지 않는다. ```ts // src/a.ts export const USER_FIELDS = fieldKeys.userModel(); // src/b.ts export const USER_FIELDS = fieldKeys.userModel(); ``` 다만 한 파일에서 둘 다 import 하거나 barrel export로 묶으면 TypeScript 일반 규칙에 따라 alias가 필요할 수 있다. ```ts import { USER_FIELDS as A_USER_FIELDS } from './a'; import { USER_FIELDS as B_USER_FIELDS } from './b'; ``` ### registry key는 전역으로 본다 `fieldKeys.userModel`의 `userModel`은 generated registry의 key이다. 서로 다른 파일의 `UserModel`이 이름만 같아도 field 목록이 다르면 `gen`이 실패한다. ```ts // src/a.ts interface UserModel { id: string; name: string; } export const USER_FIELDS = fieldKeys.userModel(); // src/b.ts interface UserModel { id: string; email: string; } export const USER_FIELDS = fieldKeys.userModel(); ``` 이 경우 `userModel` key가 서로 다른 field 목록을 가리키므로 모호하다. ```txt duplicate registry name `userModel` with divergent field sets: - src/a.ts :: UserModel -> [id, name] - src/b.ts :: UserModel -> [id, email] Hand-edit one of the call sites to a distinct name. ``` 호출 위치의 key를 직접 분리한다. ```ts // src/a.ts export const USER_FIELDS = fieldKeys.adminUserModel(); // src/b.ts export const USER_FIELDS = fieldKeys.customerUserModel(); ``` 같은 key가 같은 field 목록을 가리키는 것은 허용한다. 같은 field list를 여러 파일에서 같은 이름으로 재사용하는 경우는 모호하지 않기 때문이다. ## 실제 실행 예시: lemon-templates-api 아래는 `lemon-templates-api`에 local tarball을 설치하고 실제로 실행한 결과를 줄인 예시이다. ### 설치 확인 ```sh $ npm ls lemon-devkit typescript --depth=0 lemon-templates-api@0.26.215 ├── lemon-devkit@0.0.9 └── typescript@4.7.4 ``` `lemon-devkit`만 교체되고 consumer project의 TypeScript `4.7.4`는 유지되었다. ### migration dry-run ```sh $ ./node_modules/.bin/lemon-fields migrate --dry-run --report --update-tsconfig [lemon-fields] [dry-run] migrate — rewrote 15 site(s), 9 file(s). src/cores/abstract-services.spec.ts keys() -> fieldKeys.testModel() src/cores/abstract-services.ts keys() -> fieldKeys.coreModel() src/view/transformer.spec.ts keys() -> fieldKeys.viewTransformerModel() src/modules/callback/model.ts keys() -> fieldKeys.callbackHead() src/modules/callback/model.ts keys() -> fieldKeys.callbackModel() src/modules/mock/model.ts keys() -> fieldKeys.mockModel() src/modules/mock/model.ts keys() -> fieldKeys.mockTestModel() src/modules/search/model.ts keys() -> fieldKeys.searchModel() src/modules/search/model.ts keys() -> fieldKeys.searchQueryModel() src/modules/search/model.ts keys() -> fieldKeys.searchBatchModel() [lemon-fields] would update tsconfig: removed ts-transformer-keys transformer plugin. ``` 전체 결과는 15개 호출, 9개 파일이었다. 위 예시는 핵심 위치만 발췌했다. `src/modules/mock/model.ts`의 `MockModel`은 `mockModel`로 생성된다. `Model`처럼 일반적인 이름도 path context가 이미 `model`로 끝나면 `mockModelModel`처럼 중복 suffix를 만들지 않는다. ### migration 적용 ```sh $ ./node_modules/.bin/lemon-fields migrate --report --update-tsconfig [lemon-fields] migrate — rewrote 15 site(s), 9 file(s); wrote bootstrap stub. [lemon-fields] updated tsconfig: removed ts-transformer-keys transformer plugin. ``` ### registry 생성과 report ```sh $ ./node_modules/.bin/lemon-fields gen --report [lemon-fields] gen — 15 entries, wrote src/generated/field-registry.ts [lemon-fields] report — 15 generated entries: callbackHead src/modules/callback/model.ts#CallbackHead fields(3): id, stereo, name callbackModel src/modules/callback/model.ts#CallbackModel fields(33): id, stereo, name, domain, clientIp, userAgent, state, parentId, parent$, no, target, qid, handler, result, requestedAt, responsedAt, $request, meta, hidden, optional, $, ns, type, sid, uid, gid, lock, next, createdAt, updatedAt, deletedAt, error, _id coreModel src/cores/abstract-services.ts#CoreModel fields(16): $, ns, type, stereo, sid, uid, gid, lock, next, meta, createdAt, updatedAt, deletedAt, error, id, _id mockModel src/modules/mock/model.ts#MockModel fields(18): name, aliasId, meta, id, $, ns, type, stereo, sid, uid, gid, lock, next, createdAt, updatedAt, deletedAt, error, _id mockTestModel src/modules/mock/model.ts#TestModel fields(23): name, count, extra, Model, $identity, $, ns, type, stereo, sid, uid, gid, lock, next, meta, createdAt, updatedAt, deletedAt, error, id, _id, _idx, _date searchModel src/modules/search/model.ts#SearchModel fields(17): id, name, $, ns, type, stereo, sid, uid, gid, lock, next, meta, createdAt, updatedAt, deletedAt, error, _id testModel src/cores/abstract-services.spec.ts#TestModel fields(21): name, test, extra, Model, $identity, $, ns, type, stereo, sid, uid, gid, lock, next, meta, createdAt, updatedAt, deletedAt, error, id, _id ``` `gen --report`는 generated registry를 열어보지 않아도 key, source 위치, type, field 목록을 바로 확인하기 위한 옵션이다. 출력이 길면 필요한 key만 확인하면 된다. ```sh $ ./node_modules/.bin/lemon-fields gen --report | grep mockModel mockModel src/modules/mock/model.ts#MockModel fields(18): name, aliasId, meta, id, $, ns, type, stereo, sid, uid, gid, lock, next, createdAt, updatedAt, deletedAt, error, _id ``` ### 최신 상태와 build 확인 ```sh $ ./node_modules/.bin/lemon-fields --check [lemon-fields] ok — 15 entries up-to-date. $ npm run build-ts > lemon-templates-api@0.26.215 build-ts > ttsc ``` 위 project에서는 migration 후 `build-ts`가 통과했다. 일부 service spec 실패가 있었지만, field migration과 직접 관련된 transformer/mock/callback/view spec은 통과했다. ### common field guard 적용 ```sh $ ./node_modules/.bin/lemon-fields guard-common --dry-run --diff --report [lemon-fields] [dry-run] guard-common — 3 guard(s), 3 file(s). src/view/transformer.spec.ts checkAllKeys $mock inserted: id,ns,gid,sid,uid,lock,meta,next,type,error,stereo,createdAt,deletedAt,updatedAt src/modules/callback/transformer.spec.ts checkAllKeys $temp inserted: id,ns,gid,sid,uid,lock,meta,next,type,error,stereo,createdAt,deletedAt,updatedAt src/modules/mock/transformer.spec.ts checkAllKeys $mock inserted: id,ns,gid,sid,uid,lock,meta,next,type,error,stereo,createdAt,deletedAt,updatedAt ``` 실제 적용: ```sh $ ./node_modules/.bin/lemon-fields guard-common --report [lemon-fields] guard-common — 3 guard(s), 3 file(s) updated. $ ./node_modules/.bin/lemon-fields guard-common --report [lemon-fields] guard-common — 0 guard(s), 0 file(s) updated. ``` 삽입되는 guard는 기존 `notInModel`, `keys`, `alls`, `return` 로직을 바꾸지 않고 `checkAllKeys` 맨 앞에 들어간다. ```ts const commons = fields.reduce((L, a) => { if ($mock.includes(a)) L.push(a); return L; }, []); expect2(() => $mock?.sort((a, b) => a.length - b.length || a.localeCompare(b)).join(',')).toEqual( 'id,ns,gid,sid,uid,lock,meta,next,type,error,stereo,createdAt,deletedAt,updatedAt', ); expect2(() => commons?.sort((a, b) => a.length - b.length || a.localeCompare(b)).join(',')).toEqual( 'id,ns,gid,sid,uid,lock,meta,next,type,error,stereo,createdAt,deletedAt,updatedAt', ); ``` ## CLI 옵션 공통 옵션: - `--tsconfig `: 기본값 `tsconfig.json` - `--out `: 기본값 `src/generated/field-registry.ts` - `--include-spec`: spec 파일 포함. 기본값 true - `--no-include-spec`: spec 파일 제외 - `--paths `: scan 대상 파일만 제한. 타입 해석 context는 전체 project를 유지 `gen` 옵션: - `--check`: 파일을 쓰지 않고 drift 여부만 검사 - `--report`: 생성된 registry key, source 위치, field 목록 출력 - `--allow-legacy`: migration 중 남은 `keys()`를 임시로 허용 - `--allow-empty`: 호출 위치가 없어도 실패하지 않고 bootstrap stub 생성 `migrate` 옵션: - `--dry-run`: source/stub을 쓰지 않고 결과만 계산 - `--diff`: 변경될 source diff 출력. 보통 `--dry-run`과 함께 사용 - `--allow-skips`: 자동 처리 불가 위치를 실패 대신 skipped로 보고 - `--update-tsconfig`: 전체 migration 완료 후 `ts-transformer-keys/transformer` plugin 제거 - `--report`: rewrite 결과 요약 출력 `guard-common` 옵션: - `--dry-run`: source를 쓰지 않고 삽입/갱신 결과만 계산 - `--diff`: 변경될 source diff 출력. 보통 `--dry-run`과 함께 사용 - `--paths `: 특정 spec 파일만 대상으로 제한 - `--target `: 기본값 `checkAllKeys` - `--report`: 삽입/갱신된 guard 위치와 expected 문자열 출력 - `--out `: registry 기준 field 확인 ## Common field guard `guard-common`은 개발자가 `test:watch`를 실행할 때 transformer spec의 공통필드 검증을 자동으로 맞춰주는 명령이다. 기본 사용법: ```sh npx lemon-fields guard-common --report ``` 보통은 `package.json`의 `test:watch` 앞에 붙인다. ```json { "scripts": { "test:watch": "lemon-fields guard-common && LS=1 jest --config=jest.config.json --watchAll" } } ``` 이렇게 해두면 동작은 단순하다. - guard가 없으면 최초 1회 spec 파일에 자동 삽입 - guard가 이미 맞으면 no-op - expected가 다르면 자동 갱신 - 그 다음 기존 `jest --watchAll` 실행 ### `$` 포함 여부 개발자가 `$` 포함 여부를 직접 맞출 필요는 없다. `guard-common`이 현재 spec의 base field 변수를 보고 expected 문자열을 고른다. `fieldKeys` base는 registry field를 사용한다. 예를 들어 `CORE_FIELDS`를 base로 쓰는 경우는 `$`를 포함한다. ```ts const $node = filterFields(keys(), CORE_FIELDS); ``` 삽입되는 expected: ```txt $,id,ns,gid,sid,uid,lock,meta,next,type,error,stereo,createdAt,deletedAt,updatedAt ``` 반대로 `['meta']`처럼 `$`가 없는 base를 쓰면 `$`를 제외한다. ```ts const $mock = filterFields(keys(), ['meta']); const $temp = filterFields(keys(), ['meta']); ``` 삽입되는 expected: ```txt id,ns,gid,sid,uid,lock,meta,next,type,error,stereo,createdAt,deletedAt,updatedAt ``` 즉 repo마다 `$` 포함 여부를 사람이 맞추지 않아도 된다. `filterFields(... _id 제외)`도 반영한다. ### test:watch에 연결 watch 시작 전에 한 번 실행하면 된다. ```json { "scripts": { "test:watch": "lemon-fields guard-common && LS=1 jest --config=jest.config.json --watchAll" } } ``` 처음 실행하면 필요한 spec 파일을 고친다. ```txt [lemon-fields] guard-common — 8 guard(s), 8 file(s) updated. ``` 이후 실행은 no-op이다. ```txt [lemon-fields] guard-common — 0 guard(s), 0 file(s) updated. ``` ## 주의사항 ### generated registry는 commit 필요 `src/generated/field-registry.ts`는 source와 함께 commit 한다. 이 파일이 없으면 아래 import가 깨진다. ```ts import { fieldKeys } from './generated/field-registry'; ``` CI에서는 아래 명령으로 최신 상태인지 확인한다. ```sh npm run fields:check ``` ### generic parameter는 자동 migration 대상이 아니다 아래 코드의 `T`는 실제 모델이 아니라 함수의 generic parameter이다. ```ts import { keys } from 'ts-transformer-keys'; export function fieldsOf() { return keys(); } ``` `lemon-fields`는 build 전에 concrete field 목록을 파일로 써야 한다. 그런데 위 코드의 `T`는 호출될 때마다 달라질 수 있어서 field 목록을 확정할 수 없다. 이런 코드는 모델별 concrete 호출로 바꾼다. ```ts export const USER_FIELDS = fieldKeys.userModel(); export const POST_FIELDS = fieldKeys.postModel(); ``` 자동 처리할 수 없는 위치를 보고만 받고 싶다면 아래 옵션을 쓴다. ```sh npx lemon-fields migrate --allow-skips --report ``` ### `--allow-legacy`는 임시 옵션이다 기본적으로 `gen`은 legacy `keys()`가 남아 있으면 실패한다. ```ts import { keys } from 'ts-transformer-keys'; export const USER_FIELDS = keys(); ``` 마이그레이션을 한 번에 끝내기 어려울 때만 임시로 허용할 수 있다. ```sh npx lemon-fields gen --allow-legacy ``` 다만 이 모드는 남아있는 `keys()`의 이름을 그때그때 derive 한다. 최종 상태에서는 source에 이름이 고정되는 아래 형태가 더 안전하다. ```ts import { fieldKeys } from './generated/field-registry'; export const USER_FIELDS = fieldKeys.userModel(); ``` ### property가 0개인 타입도 `[]`로 생성한다 `ts-transformer-keys`와 맞추기 위해 property가 0개인 타입은 skipped로 버리지 않고 빈 배열로 materialise 한다. ```ts export const EMPTY = fieldKeys.empty<{}>(); export const UNION = fieldKeys.union(); export const RECORD = fieldKeys.record>(); ``` 위와 같은 호출은 모두 generated registry에 `[]`로 기록된다. 실패로 보는 경우는 property가 0개인 상황이 아니라, TypeScript checker가 property 이름을 안정적으로 materialise 하지 못한 경우이다. ### 생성 실패/누락 케이스 | 케이스 이름 | 케이스 간단 설명 | error / throw 여부 | 예시 코드 | | --- | --- | --- | --- | | legacy leftover | 아직 `keys()`가 남아 있으면 `gen`이 실패한다. 먼저 `migrate`를 돌린다. | `기본값: throw`
`--allow-legacy: 허용` | `const FIELDS = keys();` | | divergent registry key | 같은 `fieldKeys.`이 서로 다른 field set을 가리키면 실패한다. 이름을 분리해야 한다. | `throw` | `fieldKeys.userModel();`
`fieldKeys.userModel();` | | materialise failure | checker가 타입 property를 확정하지 못하면 실패한다. 타입을 더 구체적으로 만든다. | `throw` | `fieldKeys.userModel();` | | empty scan | scan 범위에 callsite가 하나도 없으면 실패한다. `--paths`와 `tsconfig`를 확인한다. | `기본값: throw`
`--allow-empty: 허용` | `npx lemon-fields gen --paths 'src/user/**/*.ts'` | | partial generation by `--paths` | 실패는 아니지만 일부 key만 생성된다. 최종 생성/CI에는 쓰지 않는다. | `throw 없음` | `npx lemon-fields gen --paths 'src/user/**/*.ts'` | | scan blind spot | alias/wrapper 호출은 누락될 수 있다. 직접 호출만 안전하다. | `보통 throw 없음`
`전체 누락 시 empty scan throw 가능` | `const fk = fieldKeys;`
`fk.userModel();` | 직접 호출만 안정적으로 scan 된다. ```ts import { fieldKeys } from './generated/field-registry'; export const USER_FIELDS = fieldKeys.userModel(); ``` 다음 케이스들은 실패가 아니라 정상 동작이며 `[]`로 생성된다. | 케이스 이름 | 케이스 간단 설명 | error / throw 여부 | 예시 코드 | | --- | --- | --- | --- | | empty object | property가 0개인 타입은 실패가 아니라 `[]`로 생성된다. | `throw 없음` | `fieldKeys.empty<{}>()` | | union | 결과 property가 0개면 실패가 아니라 `[]`로 생성된다. | `throw 없음` | `fieldKeys.union()` | | record | key가 동적인 record도 실패가 아니라 `[]`로 생성된다. | `throw 없음` | `fieldKeys.record>()` | ### `--paths`는 scan 대상만 줄인다 `--paths`는 “어느 파일에서 `fieldKeys.()` 호출을 찾을지”만 제한한다. ```sh npx lemon-fields gen --paths 'src/modules/user/**/*.ts' ``` 타입 해석에는 imported model/source가 계속 필요하다. ```ts import { UserModel } from '../../models/user-model'; export const USER_FIELDS = fieldKeys.userModel(); ``` 위 코드를 스캔하려면 `src/modules/user/**/*.ts`만 지정해도 된다. 하지만 `UserModel`이 정의된 파일은 `tsconfig.json`의 `include` 안에 있어야 한다. ```json { "include": ["src/**/*"] } ``` 즉 `--paths`는 작업 범위를 줄이는 옵션이고, TypeScript project 자체를 줄이는 옵션은 아니다. ### `--update-tsconfig`는 전체 migration 때만 사용 `ts-transformer-keys` 호출이 모두 `fieldKeys.()`로 바뀌면 transformer plugin은 더 이상 필요하지 않다. ```json { "compilerOptions": { "plugins": [ { "transform": "ts-transformer-keys/transformer" } ] } } ``` 전체 migration을 끝낸 뒤 아래처럼 정리한다. ```sh npx lemon-fields migrate --update-tsconfig --report ``` `--update-tsconfig`는 `--paths`와 함께 쓰지 않는다. 일부 파일만 migration 한 상태에서 transformer plugin을 제거하면 아직 남아 있는 `keys()` 호출이 깨질 수 있기 때문이다. ### TypeScript version `lemon-fields`는 consumer project의 TypeScript checker를 사용한다. `lemon-devkit`은 TypeScript `>=4.7 <6` 범위를 허용하므로, 기존 project가 쓰던 TypeScript version을 가능하면 그대로 유지한다. ## 어디서 무엇을 검사하나 쉽게 말해, 검사는 4번 한다. | 단계 | 도구 | 무엇을 잡나 | |---|---|---| | Dev | `gen --report` | 생성 결과를 사람이 눈으로 확인 | | CI | `gen --check` | source는 바뀌었는데 `gen`을 안 돌린 상태 | | Runtime | `assertFieldRegistry` | 이미 생성된 registry 파일 손상/누락 | | Spec | `guard-common` | transformer spec의 common field guard 누락 | 짧게 정리하면: - `gen --report`: 사람이 눈으로 확인 - `gen --check`: CI가 `gen` 누락을 자동으로 차단 - `assertFieldRegistry`: 실행 중에 generated file 손상 여부 확인 - `guard-common`: spec의 `checkAllKeys`에 공통필드 검증이 없으면 자동 삽입 ## 앱 시작 시 registry 검사 쉽게 말해, generated registry 파일이 안 깨졌는지 실행 초기에 한 번 확인하는 기능이다. 여기서 "앱 시작"은 보통 아래를 뜻한다. - 일반 Node 서버: `app.listen()` 전 - Lambda: cold start 시점, 즉 `handler` 바깥 > **처음 켤 때**: `lemon-fields gen`을 한 번 다시 실행해야 한다. 예전 형식 registry에는 `fieldRegistryMeta`가 없어 `META_MISSING`이 날 수 있다. `assertFieldRegistry`는 위 초기화 구간에서 한 번만 호출한다. ```ts import { fieldKeys, fieldRegistryMeta } from './generated/field-registry'; import { assertFieldRegistry } from 'lemon-devkit'; // 서버 시작 전 / Lambda cold start 시점에 1번 assertFieldRegistry({ fieldKeys, fieldRegistryMeta }); ``` `fieldRegistryMeta` 안의 핵심 값은 아래 3개다. - `kind`: 이 파일이 임시 stub인지, 실제 생성 완료본인지 - `entryCount`: `fieldKeys` 안에 entry가 몇 개인지 - `checksum`: entry 이름과 field 목록 내용이 안 바뀌었는지 이 검사가 잡는 것: - bootstrap stub을 그대로 commit한 경우 - `fieldRegistryMeta`가 없거나 깨진 경우 - generated file을 손으로 수정한 경우 - entry 함수가 깨진 경우 이 검사가 못 잡는 것은 하나다: - source를 바꿨는데 `lemon-fields gen`을 다시 안 돌린 경우 이 경우는 CI의 `gen --check`가 잡는다. 예시 에러: ```txt field registry validation failed: [CHECKSUM_MISMATCH] registry checksum does not match meta.checksum ``` ### Runtime 오류 코드 자주 보게 될 코드는 아래 4개다. | Code | 의미 | |---|---| | `META_MISSING` | `fieldRegistryMeta`가 없거나 shape가 잘못됨 | | `BOOTSTRAP_STUB` | 아직 임시 stub 파일 상태라 `gen`이 더 필요함 | | `ENTRY_COUNT_MISMATCH` | entry 개수가 맞지 않음 | | `CHECKSUM_MISMATCH` | entry 내용이 손상되었거나 수동 수정됨 | 그 외 코드: - `UNSUPPORTED_SCHEMA`: registry 형식 버전이 맞지 않음 - `NON_FUNCTION_ENTRY`: entry가 함수가 아님 - `ENTRY_EVAL_FAILED`: entry 함수 실행 중 에러 - `INVALID_FIELD_LIST`: entry가 `string[]`를 반환하지 않음 - `EMPTY_CONCRETE_REGISTRY`: concrete registry인데 entry가 0개 참고: - field 하나만 손으로 지우면 보통 `CHECKSUM_MISMATCH` - entry 하나를 통째로 지우면 `ENTRY_COUNT_MISMATCH`와 `CHECKSUM_MISMATCH`가 같이 날 수 있다 문제 목록만 받고 싶으면 `validateFieldRegistry()`를 쓰고, 문제 있으면 바로 실패시키고 싶으면 `assertFieldRegistry()`를 쓴다. ```ts import { validateFieldRegistry } from 'lemon-devkit'; const result = validateFieldRegistry({ fieldKeys, fieldRegistryMeta }); if (!result.ok) { console.log(result.issues); } ``` ## 왜 예전에는 `ttsc`가 필요했나 예전 방식은 build할 때 특별한 변환기가 필요했다. ```ts const FIELDS = keys(); ``` 이 코드는 build 중에 transformer가 `keys()`를 실제 field 목록으로 바꿔줘야 한다. 그래서 plain `tsc`만으로는 부족했고 `ttsc` 같은 도구가 필요했다. 지금 방식은 `gen`이 결과를 미리 generated file로 만들어 둔다. ```ts const FIELDS = fieldKeys.user(); ``` 쉽게 말해: - 예전: build할 때 field 목록을 계산 - 지금: `gen` 할 때 한 번 계산해서 파일로 저장 그래서 migration이 끝나면 runtime과 build에서는 plain `tsc`로 충분하다. ### Migration 단계별 상태 | 단계 | 코드 모습 | 추가 도구 | 한 줄 설명 | |---|---|---|---| | Before migration | `keys()` | `ttsc` 필요 | 아직 예전 방식 | | During migration | `keys()` + `fieldKeys.user()` 혼용 | `ttsc` 유지 | 옮기는 중 | | After migration | `fieldKeys.user()` + generated registry | 불필요 | plain `tsc`만 쓰면 됨 | ### 언제 `ttsc`를 제거해도 되나 다음 4개가 모두 맞으면 `ttsc`·`ttypescript`·`ts-transformer-keys/transformer`를 제거해도 된다. - 모든 `keys()` 호출이 `fieldKeys.()`로 바뀌었다 - `lemon-fields gen`으로 concrete registry를 commit했다 - `lemon-fields migrate --update-tsconfig`로 transformer plugin을 tsconfig에서 제거했다 - 프로젝트에 다른 custom transformer가 남아 있지 않다 예를 들어, repo 전체에서 `keys<` 검색 결과가 더 이상 없고 `gen` 결과도 커밋했다면 제거할 준비가 된 것이다. ## 자주 묻는 질문 **`compilerOptions.plugins`만 넣으면 왜 안 되나?** `tsc`는 여기 있는 `plugins`를 IDE용으로만 보고, 실제 build 때 transformer를 실행하지 않는다. 그래서 `keys()`가 변환되지 않아 보통 빈 배열이 남는다. 예: ```ts const FIELDS = keys(); // 기대: ['id', 'name'], 실제: [] ``` **`--update-tsconfig` 후에도 `ttypescript`가 필요한 경우는?** 다른 custom transformer를 아직 쓰고 있으면 필요할 수 있다. 예: 같은 tsconfig에서 `ts-nameof`를 계속 쓰는 프로젝트 **`--allow-legacy`는 왜 임시 옵션인가?** `--allow-legacy`는 migration 중에만 잠깐 쓰는 옵션이다. 이 상태에서는 이름이 임시로 만들어져 registry가 흔들릴 수 있다. 예: 같은 field 목록인데 호출 위치에 따라 다른 key 이름이 생길 수 있다. ## 검증된 동작 아래 핵심 동작은 자동 테스트로 확인했다. - CLI 기본 동작: `--help`, 잘못된 옵션 처리 - migration 동작: `migrate --report`, `--dry-run`, `--diff`, `--update-tsconfig` - generation 동작: `gen --report`, `gen --check`, output directory 생성 - scan 규칙: generated registry 재스캔 방지, `--paths`는 scan 대상만 줄임 - 이름 규칙: 이름 충돌 감지, `ModelModel` 같은 중복 suffix 방지 - 빈 타입 처리: property가 0개인 타입은 실패 대신 `[]` 생성 - meta/validation: `fieldRegistryMeta`, checksum, bootstrap meta 생성 - runtime validator: `assertFieldRegistry`와 `validateFieldRegistry`의 오류 검출 - common field guard: registry base, `$`, `_id` 필터를 반영하고 `checkAllKeys` guard 삽입/갱신 ## 내부 파일 구조 어느 파일을 봐야 할지 빠르게 찾고 싶다면 아래만 보면 된다. - `types.ts`: 공통 타입 모음. 옵션/반환값 shape가 궁금할 때 - `validate.ts`: runtime validator. `META_MISSING` 같은 오류 흐름을 보고 싶을 때 - `field-derive-name.ts`: registry key 이름 규칙. 자동 이름이 왜 그렇게 붙었는지 볼 때 - `field-migrate.ts`: `keys()`를 `fieldKeys.()`로 바꾸는 로직 - `field-gen.ts`: scan 후 concrete registry를 만드는 로직 - `field-guard-common.ts`: `checkAllKeys`의 common field guard를 삽입/갱신하는 로직 - `../bin/lemon-fields.ts`: CLI 시작점. `gen`, `migrate`, `--check`, `--report` 처리를 볼 때