rest-domain-state-manager

REST API 응답 데이터를 Proxy로 감싸 변경을 자동 추적하고, 저장 시점에 최적의 HTTP 메서드(POST / PUT / PATCH)로 자동 분기하는 순수 ES Module 기반 도메인 상태 관리 라이브러리.

번들러 없음  ·  npm 없음  ·  외부 의존성 없음

빠른 길잡이

목적에 해당하는 항목을 선택해 해당 섹션으로 이동한다.

1-1. 설치

번들러, npm, CDN 불필요. 폴더째 복사 후 import만 하면 된다.

your-project/
├── rest-domain-state-manager/   ← 복사한 라이브러리 폴더
└── index.html

<!-- index.html -->
<script type="module">
  import { ApiHandler, DomainState }
    from './rest-domain-state-manager/rest-domain-state-manager.js';
</script>

1-2. ApiHandler 생성

ApiHandler는 HTTP 전송을 담당하는 클래스다. 인스턴스 생성은 소비자가 직접 한다. 서버 주소를 여기서 결정한다.

const api = new ApiHandler({
  host:  'localhost:8080',  // 서버 주소
  debug: true,              // true → HTTP 자동 선택, 콘솔 로그 활성화
});

const userApi  = new ApiHandler({ host: 'user-service.com' });
const orderApi = new ApiHandler({ host: 'order-service.com' });

// 각자 맞는 api를 팩토리에 넘김
const user  = await userApi.get('/api/users/1');
const order = await orderApi.get('/api/orders/999');

// save()도 생성 시 주입된 api 그대로 사용
await user.save('/api/users/1');    // → user-service.com
await order.save('/api/orders/999'); // → order-service.com

1-3. GET → 변경 → 저장

api.get()은 서버에서 데이터를 가져와 DomainState 인스턴스를 반환한다. 이후 .data를 통해 값을 읽고 쓴다.

// 1. GET 요청 → DomainState 생성
const user = await api.get('/api/users/user_001');

// 2. 데이터 읽기
console.log(user.data.name);

// 3. 데이터 변경 (Proxy가 자동으로 변경을 추적)
user.data.name         = 'Davi';
user.data.address.city = 'Seoul';   // 중첩 객체도 추적

// 4. 저장
//   변경이 있으면 → PATCH (변경된 필드만 전송)
//   변경이 없으면 → PUT  (전체 객체 전송)
await user.save('/api/users/user_001');

// 5. 삭제
await user.remove('/api/users/user_001');

1-4. 신규 생성 → POST

신규 데이터 생성에는 fromVO() 또는 fromForm() 팩토리를 쓴다. 두 방법 모두 save() 호출 시 POST로 전송한다.

fromVO() — DomainVO 기반 생성

// 1. DomainVO 선언
class UserVO extends DomainVO {
  static baseURL = 'localhost:8080/api/users'; // save() 경로 자동 사용
  static fields  = {
    user_id: { default: '' },
    name:    { default: '' },
    role:    { default: 'USER' },
    address: { default: { city: '', zip: '' } },
  };
}

// 2. DomainState 생성 (isNew: true)
const newUser = DomainState.fromVO(new UserVO(), api);

// 3. 값 설정
newUser.data.user_id = 'user_' + Date.now();
newUser.data.name    = 'Davi';

// 4. POST 전송 (static baseURL 자동 사용)
await newUser.save();

fromForm() — HTML Form 기반 생성

<form id="user-form">
  <input name="name" />
  <input name="address.city" />  <!-- 점(.) 표기로 중첩 구조 표현 -->
  <select name="role">...</select>
</form>

// form 초기화 후 blur / change 이벤트를 자동으로 추적
const formState = DomainState.fromForm('user-form', api);

// 사용자가 입력을 마치면 변경이 자동으로 기록되어 있음
await formState.save('/api/users');

1-5. 여러 API 한 번에 (DomainPipeline)

DomainState.all()은 여러 API를 병렬로 호출하고, 완료 후 후처리를 순서대로 실행한다.

const result = await DomainState.all({
  roles: api.get('/api/roles'),
  user:  api.get('/api/users/user_001'),
})
.after('roles', async (roles) => {
  // roles → DomainState 인스턴스
  console.log(roles.data);
})
.after('user', async (user) => {
  console.log(user.data);
})
.run();

// result → { roles: DomainState, user: DomainState }

if (result._errors?.length) {
  console.warn('일부 실패:', result._errors);
}

1-6. 목록을 UI 요소로 렌더링 (DomainRenderer)

DomainRenderer 플러그인을 등록하면 DomainState에 renderTo() 메서드가 추가된다.

// 앱 초기화 시 1회 등록
DomainState.use(DomainRenderer);

const roles = await api.get('/api/roles');

// select
roles.renderTo('#role-select', {
  type:        'select',
  valueField:  'roleId',
  labelField:  'roleName',
  class:       'form-select',
  placeholder: '역할 선택',
  events: {
    change: (e) => console.log('선택:', e.target.value),
  },
});

// radio
roles.renderTo('#role-radio', {
  type:           'radio',
  valueField:     'roleId',
  labelField:     'roleName',
  containerClass: 'form-check',
  class:          'form-check-input',
  labelClass:     'form-check-label',
});

2-1. ApiHandler 전체 옵션

ApiHandler 생성자는 UrlConfig 객체를 받는다.

// 방식 1 — 구조 분해형
const api = new ApiHandler({
  host:     'api.example.com',
  basePath: '/app/api',
  env:      'production',       // HTTPS 자동 선택
});

// 방식 2 — 통합 문자열형
const api = new ApiHandler({
  baseURL: 'localhost:8080/app/api',
  debug:   true,    // HTTP 자동 선택
});

프로토콜 결정 우선순위

1. 명시적 protocol 옵션
2. env 값 → development: HTTP, production: HTTPS
3. env 없음 + debug: true  → HTTP
4. env 없음 + debug: false → HTTPS

요청별 URL 오버라이드

const user = await api.get('/api/users/1', {
  urlConfig: { host: 'other-server.com' },
});

2-2. DomainVO 필드 선언

DomainVO는 도메인 구조를 선언하는 베이스 클래스다. DomainState.fromVO()의 인자로 사용하며 세 가지를 제공한다.

class ProductVO extends DomainVO {
  static baseURL = 'localhost:8080/api/products';

  static fields = {
    productId: {
      default: '',
    },
    name: {
      default:  '',
      validate: (v) => v.trim().length > 0,   // 빈 문자열 거부
    },
    price: {
      default:   0,
      validate:  (v) => v >= 0,               // 음수 거부
      transform: Number,                       // 문자열 입력 → 숫자 변환
    },
    tags: {
      default: [],                             // 배열도 선언 가능
    },
    meta: {
      default: { createdAt: '', updatedAt: '' },  // 중첩 객체
    },
  };
}

static baseURL 폴백

const product = DomainState.fromVO(new ProductVO(), api);
await product.save();                           // static baseURL로 POST
await product.save('/api/products/override');   // 명시하면 오버라이드

checkSchema(data)

fromJSON()에 vo 옵션을 함께 넘기면 서버 응답이 VO 스키마와 일치하는지 검증한다.

const product = DomainState.fromJSON(jsonText, api, { vo: new ProductVO() });
// 스키마 불일치 시 콘솔에 경고 출력 (실행은 계속)

2-3. DomainState 내부 구조

Proxy와 data

.data는 원본 객체를 Proxy로 감싼 것이다. Proxy는 set / deleteProperty 트랩을 통해 모든 변경을 changeLog에 기록한다.

const user = await api.get('/api/users/1');

user.data.name = 'Davi';
// changeLog = [{ op: 'replace', path: '/name', value: 'Davi', oldValue: '기존값' }]

user.data.address.city = 'Seoul';   // 중첩도 자동 추적
// changeLog = [..., { op: 'replace', path: '/address/city', value: 'Seoul' }]

delete user.data.phone;
// changeLog = [..., { op: 'remove', path: '/phone', oldValue: '010-...' }]

isNew 플래그

POST 성공 후 isNew는 자동으로 false로 전환된다.

changeLog 직접 접근

console.log(user._getChangeLog());
// [ { op, path, value, oldValue }, ... ]

2-4. 팩토리 메서드 상세

fromJSON(jsonText, handler, options?)

// GET 응답을 VO로 검증하면서 동시에 form에 값을 채움
const user = DomainState.fromJSON(jsonText, api, {
  vo:   new UserVO(),
  form: 'user-form',
});

fromForm(form, handler, options?)

fromVO(vo, handler, options?)

2-5. save() 분기 전략

save(path?)는 isNew와 changeLog 길이를 보고 HTTP 메서드를 결정한다.

isNew === true
    → POST  (전체 객체 직렬화)

isNew === false
    changeLog.length > 0  → PATCH (RFC 6902 JSON Patch 배열)
    changeLog.length === 0 → PUT  (전체 객체 직렬화)

await user.save('/api/users/user_001');  // 경로 명시
await user.save();                       // urlConfig 또는 static baseURL 사용

2-6. DomainPipeline strict 모드 / _errors 처리

// strict: false — 부분 실패 허용 (기본)
const result = await DomainState.all({
  roles: api.get('/api/roles'),
  user:  api.get('/api/users/INVALID'),  // 실패
}, { strict: false })
.after('roles', async (roles) => { /* ... */ })
.run();

result._errors?.forEach(({ key, error }) => console.warn(key, error));

// strict: true — 첫 실패에서 중단
try {
  await DomainState.all({ ... }, { strict: true })
    .after('roles', async (roles) => { /* ... */ })
    .run();
} catch (err) {
  console.error('Pipeline 중단:', err);
}

2-7. renderTo() 전체 config

공통 옵션 (모든 type)

select 추가 옵션

radio / checkbox 추가 옵션

button

valueField 값이 button[data-value] 속성으로 주입된다. 클릭 핸들러에서 e.target.dataset.value로 읽는다.

roles.renderTo('#role-buttons', {
  type:       'button',
  valueField: 'roleId',
  labelField: 'roleName',
  class:      'btn btn-sm btn-outline-primary',
  events: {
    click: (e) => console.log(e.target.dataset.value),
  },
});

2-8. 플러그인 시스템 (use())

DomainState.use(plugin)은 { install(DomainState): void } 계약을 가진 플러그인을 등록한다.

const MyPlugin = {
  install(DomainState) {
    // prototype에 메서드 주입
    DomainState.prototype.toCSV = function () {
      const target = this._getTarget();
      return Object.values(target).join(',');
    };
  },
};

DomainState.use(MyPlugin);

const user = await api.get('/api/users/1');
console.log(user.toCSV());

2-9. Debug Popup

debug: true로 생성하면 디버그 채널이 활성화된다. openDebugger()로 팝업을 열면 같은 출처(Origin)의 모든 탭의 상태를 실시간으로 확인할 수 있다.

const user = DomainState.fromVO(new UserVO(), api, {
  debug: true,
  label: 'UserVO',  // 팝업에 표시될 이름
});

user.openDebugger();

팝업에서 확인할 수 있는 정보

• 탭 목록 (URL 기준)
• 각 탭의 DomainState 레이블
• 현재 data (실시간 갱신)
• changeLog 목록
• _errors 배열

통신 방식

BroadcastChannel — 브라우저 내장 Web API, 외부 의존성 없음. BroadcastChannel은 자기 자신이 보낸 메시지를 수신하지 않으므로, TAB_PING을 팝업이 직접 broadcast하고 각 탭이 응답하는 구조로 동작한다.

전체 레이어 구조

라이브러리는 세 개의 수직 레이어로 구성된다. 외부 개발자는 진입점 파일 하나만 알면 된다.

┌──────────────────────────────────────────────────────────────────────┐
│                         외부 개발자 진입점                               │
│                  rest-domain-state-manager.js                        │
│        { ApiHandler, DomainState, DomainVO,                         │
│          DomainPipeline, DomainRenderer }                            │
└───────────────┬──────────────────────────────┬───────────────────────┘
                │                              │
┌───────────────▼──────────────┐  ┌────────────▼─────────────────────┐
│           model/             │  │           plugin/                │
│                              │  │                                  │
│  DomainState                 │  │  domain-renderer/                │
│    ├─ fromJSON()             │  │    ├─ DomainRenderer.js          │
│    ├─ fromForm()             │  │    │    (prototype 주입)          │
│    ├─ fromVO()               │  │    └─ renderers/                 │
│    ├─ save() / remove()      │  │         ├─ select.renderer.js    │
│    └─ all() ────────────────────────────▶ ├─ radio-checkbox.js     │
│                              │  │         └─ button.renderer.js    │
│  DomainVO                    │  └──────────────────────────────────┘
│    ├─ toSkeleton()           │
│    ├─ getValidators()        │
│    ├─ getTransformers()      │
│    └─ checkSchema()          │
│                              │
│  DomainPipeline              │
│    ├─ after()                │
│    └─ run()                  │
└───────────────┬──────────────┘
                │ 내부 호출
┌───────────────▼──────────────────────────────────────────────────────┐
│                          src/ (내부 레이어)                             │
│                                                                      │
│  handler/          core/               constants/      debug/        │
│  api-handler.js    api-proxy.js        error.messages  debug-        │
│  (fetch 래퍼,      api-mapper.js       log.messages    channel.js    │
│   URL 조합)        url-resolver.js     op.const        (BroadcastChannel│
│                                         protocol.const  + 팝업 HTML) │
│                    common/              channel.const               │
│                    js-object-util.js                                │
└──────────────────────────────────────────────────────────────────────┘

도개교(Drawbridge) 패턴

createProxy()가 반환하는 네 가지 클로저(Closure) 세트를 DomainState가 보관한다. 이를 도개교 패턴이라 부른다 — 클로저 세계로의 출입문을 외부에서 제어하는 구조다.

// createProxy()의 반환값
{
  proxy:          object,     // 변경 추적이 활성화된 Proxy 객체
                              // 외부 개발자가 접근하는 유일한 진입점
  getChangeLog:   () => [],   // 현재까지의 변경 이력 얕은 복사본 반환
  getTarget:      () => {},   // 변경이 반영된 원본 객체 반환
  clearChangeLog: () => void, // 동기화 성공 후 이력 초기화
}

Proxy 트랩 설계

경로 누적 방식

루트 Proxy 생성 시 basePath = ''에서 시작하며, 중첩 객체 접근마다 makeHandler(basePath + '/' + prop)을 재귀 호출한다.

proxy.address.city = 'Seoul'
  // get 트랩: prop='address', basePath=''
  //   → path='/address' 로 새 Proxy 반환
  // set 트랩: prop='city', basePath='/address'
  //   → path='/address/city' 로 changeLog에 기록

트랩별 동작표

bypass 대상

다음 프로퍼티는 deep proxy를 씌우지 않고 Reflect.get 결과를 그대로 반환한다.

• Symbol 프로퍼티 — Symbol.toPrimitive, Symbol.iterator 등
• toJSON — JSON.stringify 호환성 보존
• then — Promise 체인 호환성 보존 (Proxy를 thenable로 오인 방지)
• valueOf — 원시값 변환 호환성 보존

데이터 흐름

GET → 화면 표시

서버 (JSON 응답)
    ↓ fetch()
api-handler._fetch()           — 공통 헤더, response.ok 검사
    ↓ text (JSON 문자열)
api-mapper.toDomain()          — JSON.parse → 도메인 객체
    ↓ plain object
api-proxy.createProxy()        — Proxy 래핑, 도개교 세트 생성
    ↓ { proxy, getChangeLog, getTarget, clearChangeLog }
DomainState 생성               — 메타데이터 보관, debug broadcast
    ↓ domainState
외부 개발자 코드               — domainState.data.xxx 읽기/쓰기

저장 (save)

domainState.save(path)
    ↓
isNew 확인
    ├─ true  → toPayload()  → POST
    └─ false → changeLog 확인
                  ├─ length > 0 → toPatch()    → PATCH (RFC 6902)
                  └─ length = 0 → toPayload()  → PUT
    ↓
api-handler._fetch()           — 전송
    ↓ 성공 시
clearChangeLog()               — 이력 초기화
isNew = false (POST일 때만)

파일 구조

rest-domain-state-manager/
│
├── rest-domain-state-manager.js     단일 진입점 — 외부 개발자는 이것만 import
├── proxy.test.html                  통합 테스트 (7개 케이스)
│
├── model/
│   ├── DomainState.js               핵심 외부 인터페이스
│   ├── DomainVO.js                  도메인 구조 선언 베이스 클래스
│   └── DomainPipeline.js            병렬 fetch + 순차 after() 체이닝
│
├── src/
│   ├── constants/
│   │   ├── protocol.const.js        PROTOCOL / ENV / DEFAULT_PROTOCOL
│   │   ├── op.const.js              RFC 6902 add / replace / remove
│   │   ├── channel.const.js         DEBUG_CHANNEL_NAME / MSG_TYPE
│   │   ├── error.messages.js        ERR / WARN 메시지 함수 상수
│   │   └── log.messages.js          LOG 템플릿 + formatMessage()
│   ├── common/
│   │   └── js-object-util.js        타입 판별 유틸
│   ├── core/
│   │   ├── api-proxy.js             Proxy 변경 추적 엔진 (createProxy)
│   │   ├── url-resolver.js          URL 조합 + 충돌 해소
│   │   └── api-mapper.js            toDomain / toPayload / toPatch
│   ├── handler/
│   │   └── api-handler.js           fetch 래퍼 클래스 (ApiHandler)
│   └── debug/
│       └── debug-channel.js         BroadcastChannel + 팝업 HTML 생성
│
└── plugin/
    └── domain-renderer/
        ├── DomainRenderer.js        renderTo() 주입 플러그인 본체
        ├── renderer.const.js        RENDERER_TYPE / TRACK_EVENT
        └── renderers/
            ├── select.renderer.js
            ├── radio-checkbox.renderer.js
            └── button.renderer.js

ApiHandler

HTTP 전송 레이어 클래스. URL 설정을 보관하고 fetch()를 래핑한다.

new ApiHandler(urlConfig: UrlConfig)

UrlConfig 타입

에러 구조

response.ok가 false이면 아래 구조의 객체를 throw한다. catch(err)에서 err.status로 분기할 수 있다.

{ status: number, statusText: string, body: string }

DomainState

REST 리소스 단위의 상태 관리자. 직접 new하지 않고 팩토리 메서드로 생성한다.

정적 메서드

인스턴스 프로퍼티 / 메서드

options 공통 필드

DomainVO

도메인 구조 선언 베이스 클래스. DomainState.fromVO()의 인자로 사용한다.

static 선언

fields 스키마 구조

인스턴스 메서드

DomainPipeline

DomainState.all()이 반환하는 파이프라인 객체. 직접 생성하지 않는다.

run() 반환값

{
  [key: string]: DomainState,  // resourceMap의 각 키
  _errors?: Array<{ key: string, error: any }>
                               // strict: false 시, 실패한 항목
}

DomainRenderer

DomainState.use(DomainRenderer) 등록 후 DomainState.prototype.renderTo()가 추가된다.

domainState.renderTo(selector, config)

라이브러리 정체성

이 라이브러리는 HTTP 클라이언트가 아니다. fetch()를 내부적으로 사용하지만, 핵심 가치는 "어떻게 보내는가"가 아니라 "무엇이 바뀌었는가를 추적하고, 저장 시점에 올바른 방식으로 동기화하는가"에 있다.

단일 상태 소스 (Single Source of Truth)

화면이 떠 있는 동안 하나의 DomainState 인스턴스가 해당 리소스의 유일한 진실을 담는다. DOM 요소, form 입력, 코드 내 직접 대입 — 모든 변경은 domainState.data(Proxy)를 통해서만 이루어진다.

// ❌ 안티패턴 — DOM에서 직접 읽어 별도 객체 구성
const payload = {
  name: document.getElementById('name').value,
  city: document.getElementById('city').value,
};

// ✅ 올바른 패턴 — Proxy 하나가 모든 변경을 수집
const user = DomainState.fromForm('userForm', api);
// form 이벤트 → user.data.name, user.data.address.city 자동 반영
await user.save('/api/users/1');

changeLog 구조

changeLog는 마지막 동기화 이후 발생한 모든 변경의 순서 있는 기록이다. 각 항목은 RFC 6902 JSON Patch 연산과 호환되는 내부 포맷을 따른다.

// 내부 changeLog 항목 구조
{
  op:       'add' | 'replace' | 'remove',
  path:     '/address/city',      // JSON Pointer 스타일 경로
  value:    'Seoul',              // 새 값 (remove 시 없음)
  oldValue: 'Busan',             // 이전 값
}

save()가 PATCH를 결정하면 api-mapper.toPatch()가 이 내부 포맷을 RFC 6902 표준 배열로 변환하여 서버에 전송한다.

// 서버로 전송되는 RFC 6902 JSON Patch 배열
[
  { "op": "replace", "path": "/address/city", "value": "Seoul" },
  { "op": "add",     "path": "/phone",         "value": "010-0000-0000" }
]

isNew 플래그

isNew는 이 인스턴스가 서버에 아직 존재하지 않는 신규 리소스인지를 나타낸다. 팩토리 메서드 호출 시점에 결정되며, POST 성공 후 자동으로 false로 전환된다.

// isNew 전환 흐름
const newUser = DomainState.fromVO(new UserVO(), api);
// newUser._isNew === true

await newUser.save();   // → POST 전송
// 성공 후: newUser._isNew === false

newUser.data.name = 'Davi';
await newUser.save();   // → PATCH 전송 (이제 기존 리소스)

Locality of Behavior

이 라이브러리는 Locality of Behavior를 중요한 설계 원칙으로 삼는다. 관련 동작이 한 곳에 모여 있어야 읽으면 이해되는 코드가 된다.

Clean Code의 "함수는 한 가지 일만"보다, 잘 읽히는 한 곳에서 흐름 전체를 파악할 수 있는 구조를 우선한다. 5줄짜리 함수 10개보다 주석이 달린 50줄짜리 함수 1개를 선호한다.

// 이 라이브러리의 설계 의도:
// "save() 한 줄 뒤에서 무슨 일이 일어나는지
//  코드를 보지 않아도 예측할 수 있어야 한다"

await user.save('/api/users/1');
// isNew가 false이고 changeLog가 있으면 → PATCH
// isNew가 false이고 changeLog가 없으면 → PUT
// isNew가 true이면 → POST
// 예측 가능한 한 가지 인터페이스, 세 가지 동작

각 결정은 대안을 검토하고 trade-off를 평가한 뒤 내려졌다. "왜 이렇게 설계됐는가"에 대한 기록이다.

DD-1. Proxy 적용 범위

검토한 대안

DD-2. save()의 HTTP 메서드 전략

검토한 대안

DD-3. deep proxy 적용 범위

검토한 대안

DD-4. 변경 기록 포맷

검토한 대안

DD-5. 폼 바인딩 방식

검토한 대안

DD-6. DomainPipeline strict 기본값

검토한 대안

DD-7. 디버그 팝업 통신 방식

검토한 대안

DD-8. radio / checkbox name 속성 기본값

검토한 대안