사람함께에이전트▾
사람 — 직접 정하고 책임지는 비즈니스 규칙과 흐름. 직접 읽어보세요.
함께 — 개념은 알아두고, 세부 규칙은 에이전트가 따릅니다.
에이전트 — 에이전트가 따르는 규칙과 레퍼런스. 필요할 때 찾아보세요.
모듈 규칙▾
스칼라 Document 구현 가이드
document 파일 (*.document.ts)은 by() 함수를 사용하여 커스텀 메서드로 스칼라를 확장하는 선택적 파일입니다. constant.ts가 데이터 구조를 정의하고 dictionary.ts가 번역을 제공하는 반면, document.ts는 런타임 동작과 유틸리티 메서드를 추가합니다.
이 가이드는 by() 함수 문법, document.ts를 사용해야 할 때, 메서드 추가 패턴을 다룹니다.
📁파일 구조
🎯사용 시기
- 계산된 속성 추가
- 유틸리티 메서드 추가
- 데이터 변환 로직 추가
- 유효성 검사 헬퍼 추가
by()를 사용한 기본 문법
by() 함수는 constant 클래스를 감싸고 인스턴스 메서드를 추가할 수 있게 합니다. constant의 모든 필드와 타입을 유지하면서 기능을 확장할 수 있습니다.
기본 구조
각 부분을 이해해봅시다:
📦import { by } from '@akanjs/document'
@akanjs/document에서 by() 함수를 import합니다. 스칼라 document에 필요한 유일한 import입니다.
🔗import * as cnst
constant 모듈을 'cnst' 네임스페이스로 import합니다. 이 규칙은 constant 클래스와 document 클래스 간의 이름 충돌을 방지합니다.
⚡extends by(cnst.YourScalar)
by() 함수는 constant로부터 기본 클래스를 생성합니다. document 클래스는 이를 확장하여 모든 필드를 상속하고 메서드를 추가합니다.
최소 Document (메서드 없음)
대부분의 스칼라 document 파일은 최소한입니다 - 메서드를 추가하지 않고 constant 클래스를 단순히 감쌉니다. 이는 일관성과 향후 확장 가능성을 위해 유용합니다.
빈 document 파일도 유용합니다! 향후 메서드를 위한 명확한 확장 포인트를 제공하고 일관된 파일 구조를 유지합니다.
커스텀 메서드 추가하기
클래스 본문에 인스턴스 메서드를 직접 추가할 수 있습니다. 이 메서드들은 'this'를 통해 모든 필드에 접근할 수 있으며 계산, 유효성 검사 또는 변환을 수행할 수 있습니다.
price.document.ts
document 메서드의 일반적인 패턴:
🧮계산된 속성
기존 필드에서 값을 계산하는 메서드 (예: getPercentage(), getTotal()).
✅상태 확인
조건을 확인하고 불리언을 반환하는 메서드 (예: isActive(), isExpired(), hasStock()).
🔄데이터 변환
데이터를 변환하거나 포맷하는 메서드 (예: getFormattedDate(), getDisplayName()).
🔍파서/추출기
필드에서 특정 정보를 추출하는 메서드 (예: pod 이름을 파싱하는 getService()).
메서드 예시
스칼라 document에 추가할 수 있는 메서드의 실용적인 예시입니다:
Stock - 계산 & 상태
DateRange - 포맷팅
Constant vs Document
constant.ts 또는 document.ts에서 메서드를 정의할 수 있습니다. 각각을 사용할 때:
📋constant.ts
- 필드 값만 사용하는 간단한 메서드
- 클라이언트와 서버 모두에서 필요한 메서드
- 외부 의존성이 필요 없음
📄document.ts
- 복잡한 로직이 있는 메서드
- 서버 측 import가 필요할 수 있는 메서드
- 관심사 분리 (스키마 vs 동작)
constant.ts의 메서드
참고: constant.ts와 document.ts 모두에서 메서드를 정의하면 document.ts 메서드가 constant.ts 메서드를 오버라이드합니다.
모범 사례
✓'cnst' 네임스페이스 사용
이름 충돌을 피하기 위해 항상 constant를 'cnst'로 import: import * as cnst from './scalar.constant'
✓클래스 이름 일치
일관성을 위해 document 클래스 이름은 constant 클래스 이름과 일치해야 합니다.
✓메서드를 순수하게 유지
스칼라 document 메서드는 상태를 수정하거나 부작용이 없는 순수 함수여야 합니다.
✓설명적인 이름 사용
명확한 메서드 이름 사용: calc(), check(), has() 대신 getPercentage(), isActive(), hasStock().
✓비어있어도 생성
일관성과 향후 확장성을 위해 메서드가 없어도 document.ts를 생성하세요.
구현 체크리스트
- 파일 위치: __scalar/<name>/<name>.document.ts
- '@akanjs/document'에서 by import
- constant를 'cnst' 네임스페이스로 import
- 클래스 이름이 constant 클래스 이름과 일치
- by(cnst.ClassName)을 확장
- document 클래스 export
- 메서드가 'this'로 필드에 접근
- 메서드가 순수 (부작용 없음)
💡 프로 팁:
- • Document 메서드는 클라이언트와 서버 모두에서 사용 가능 - 서버 전용 import에 주의
- • 메서드가 없는 간단한 스칼라의 경우 빈 document 클래스도 괜찮습니다
- • 더 나은 트리쉐이킹을 위해 자주 사용되는 메서드는 constant.ts에 정의하는 것을 고려