스칼라 모듈 개요

스칼라 모듈은 애플리케이션 전반에 걸쳐 임베디드 문서, 공유 DTO 및 국제화된 데이터 구조를 위한 재사용 가능한 값 객체를 제공합니다. 스칼라를 재사용 가능한 레고 조각으로 생각해보세요 - 더 큰 모델로 조합할 수 있는 작고 집중된 데이터 구조입니다.

자체 데이터베이스 컬렉션을 가진 전체 Model과 달리, Scalar는 다른 모델 안에 내장됩니다. 다음과 같은 용도에 완벽합니다:

도메인 모델의 임베디드 문서 (예: 주소, 연락처 정보)
모듈 간 공유 DTO 및 구성 객체
런타임 유효성 검사가 있는 타입 안전 스키마
완전한 i18n 지원이 있는 국제화된 데이터 구조

핵심 원칙

🔄Reusability

모듈 간 사용을 위해 설계됨. 한 번 정의하고 어디서든 사용.

📦Stateless

비즈니스 로직 없는 순수 데이터 컨테이너. 동작이 아닌 구조에 집중.

🛡️Type-Safe

필드 옵션을 통한 런타임 유효성 검사와 완전한 TypeScript 통합.

🧩Composable

더 큰 도메인 모델 내에 임베딩 가능. 스칼라는 다른 스칼라를 포함할 수 있음.

파일 구조

스칼라 모듈은 라이브러리 내의 특수한 __scalar 디렉토리에 저장됩니다. 각 스칼라는 세 개의 핵심 파일이 있는 자체 디렉토리를 가집니다:

field	설명
*.constant.ts	via() 함수를 사용하여 스칼라 스키마를 정의하고 enumOf()를 사용하여 enum을 정의합니다. 여기서 필드, 타입, 기본값 및 유효성 검사 규칙을 선언합니다.
*.dictionary.ts	scalarDictionary() 빌더 패턴을 사용하여 국제화를 제공합니다. 모델 이름, 필드 레이블, 설명 및 enum 값에 대한 번역을 정의합니다.
*.document.ts	by() 함수를 사용하여 기능을 확장하는 선택적 파일입니다. 데이터 변환 및 계산된 값을 위한 커스텀 메서드를 추가합니다.

*.constant.ts

via() 함수를 사용하여 스칼라 스키마를 정의하고 enumOf()를 사용하여 enum을 정의합니다. 여기서 필드, 타입, 기본값 및 유효성 검사 규칙을 선언합니다.

*.dictionary.ts

scalarDictionary() 빌더 패턴을 사용하여 국제화를 제공합니다. 모델 이름, 필드 레이블, 설명 및 enum 값에 대한 번역을 정의합니다.

*.document.ts

by() 함수를 사용하여 기능을 확장하는 선택적 파일입니다. 데이터 변환 및 계산된 값을 위한 커스텀 메서드를 추가합니다.

스칼라 정의하기

Akan.js는 스칼라를 정의하는 데 함수형 접근 방식을 사용합니다. via() 함수는 타입 안전 스키마 정의를 생성하고, enumOf()는 타입이 지정된 enum 클래스를 생성합니다. 프레임워크의 실제 예시입니다:

price.constant.ts

핵심 패턴을 이해해봅시다:

field	설명
enumOf(name, values)	타입이 지정된 enum 클래스를 생성합니다. 첫 번째 인수는 enum 이름(dictionary에서 사용), 두 번째는 타입 안전을 위해 "as const"가 포함된 값 배열입니다.
via((field) => ({...}))	타입이 지정된 필드를 가진 스칼라 클래스를 생성합니다. field() 함수는 타입과 기본값, 유효성 검사 등을 위한 선택적 구성을 받습니다.
Field Options	옵션에는: default (정적 또는 함수), min/max (숫자용), minlength/maxlength (문자열용), validate (커스텀 검증 함수)가 포함됩니다.

enumOf(name, values)

타입이 지정된 enum 클래스를 생성합니다. 첫 번째 인수는 enum 이름(dictionary에서 사용), 두 번째는 타입 안전을 위해 "as const"가 포함된 값 배열입니다.

via((field) => ({...}))

타입이 지정된 필드를 가진 스칼라 클래스를 생성합니다. field() 함수는 타입과 기본값, 유효성 검사 등을 위한 선택적 구성을 받습니다.

Field Options

옵션에는: default (정적 또는 함수), min/max (숫자용), minlength/maxlength (문자열용), validate (커스텀 검증 함수)가 포함됩니다.

scalarDictionary()

scalarDictionary() 함수는 번역을 정의하기 위한 플루언트 빌더 패턴을 제공합니다. 타입 안전성과 모든 필드 및 enum 값의 완전한 커버리지를 보장합니다.

price.dictionary.ts

dictionary 빌더 패턴을 이해해봅시다:

field	설명
scalarDictionary([languages])	지원되는 언어 배열로 초기화합니다. 순서는 번역 배열에서 어떤 인덱스가 어떤 언어에 해당하는지를 결정합니다.
.of((t) => ...)	스칼라 자체의 이름과 설명을 정의합니다. 레이블에는 t([en, ko])를, 설명에는 .desc([en, ko])를 사용합니다.
.model<Type>((t) => ({...}))	각 필드에 대한 번역을 정의합니다. 제네릭 타입은 모든 필드가 커버되도록 보장합니다. 각 필드는 레이블과 설명을 가집니다.
.enum<Type>(name, (t) => ({...}))	enum 값에 대한 번역을 정의합니다. 첫 번째 인수는 enum 이름(enumOf()와 일치), 두 번째는 각 값에 대한 번역을 정의합니다.

scalarDictionary([languages])

지원되는 언어 배열로 초기화합니다. 순서는 번역 배열에서 어떤 인덱스가 어떤 언어에 해당하는지를 결정합니다.

.of((t) => ...)

스칼라 자체의 이름과 설명을 정의합니다. 레이블에는 t([en, ko])를, 설명에는 .desc([en, ko])를 사용합니다.

.model<Type>((t) => ({...}))

각 필드에 대한 번역을 정의합니다. 제네릭 타입은 모든 필드가 커버되도록 보장합니다. 각 필드는 레이블과 설명을 가집니다.

.enum<Type>(name, (t) => ({...}))

enum 값에 대한 번역을 정의합니다. 첫 번째 인수는 enum 이름(enumOf()와 일치), 두 번째는 각 값에 대한 번역을 정의합니다.

by()로 Document 확장하기

document 파일은 by() 함수를 사용하여 커스텀 메서드로 스칼라를 확장합니다. 이것은 선택 사항이지만 계산된 속성과 데이터 변환 메서드를 추가하는 데 유용합니다.

price.document.ts

document 확장에 대한 핵심 포인트:

field	설명
by(cnst.ClassName)	상수 클래스를 감싸고 메서드 추가를 활성화합니다. 이름 충돌을 피하기 위해 상수를 cnst로 임포트합니다.
Custom Methods	계산된 속성, 유효성 검사 헬퍼, 변환 메서드를 클래스 본문에 직접 추가합니다.
Access Fields	'this'를 사용하여 상수 파일에 정의된 모든 필드에 접근합니다. TypeScript가 완전한 자동 완성을 제공합니다.

by(cnst.ClassName)

상수 클래스를 감싸고 메서드 추가를 활성화합니다. 이름 충돌을 피하기 위해 상수를 cnst로 임포트합니다.

Custom Methods

계산된 속성, 유효성 검사 헬퍼, 변환 메서드를 클래스 본문에 직접 추가합니다.

Access Fields

'this'를 사용하여 상수 파일에 정의된 모든 필드에 접근합니다. TypeScript가 완전한 자동 완성을 제공합니다.

명명 규칙

일관된 명명은 유지보수성에 중요합니다. 다음 규칙을 따르세요:

field	설명
Scalar Directory	camelCase (e.g., encourageInfo)
Constant File	[name].constant.ts (e.g., encourageInfo.constant.ts)
Dictionary File	[name].dictionary.ts (e.g., encourageInfo.dictionary.ts)
Document File	[name].document.ts (e.g., encourageInfo.document.ts)
Scalar Class	PascalCase (e.g., EncourageInfo)
Enum Class	PascalCase (e.g., Journey, LinkType)
Enum Values	camelCase (e.g., firstJoin, waitPay)

Scalar Directory

camelCase (e.g., encourageInfo)

Constant File

[name].constant.ts (e.g., encourageInfo.constant.ts)

Dictionary File

[name].dictionary.ts (e.g., encourageInfo.dictionary.ts)

Document File

[name].document.ts (e.g., encourageInfo.document.ts)

Scalar Class

PascalCase (e.g., EncourageInfo)

Enum Class

PascalCase (e.g., Journey, LinkType)

Enum Values

camelCase (e.g., firstJoin, waitPay)

모범 사례

field	설명
Design for Reusability	여러 모듈에서 사용할 수 있는 스칼라를 만드세요. 주소, 연락처 정보, 상태 추적과 같은 공통 데이터 패턴을 생각해보세요.
Keep Scalars Focused	각 스칼라는 단일 개념을 나타내야 합니다. 스칼라가 너무 커지면 더 작고 조합 가능한 조각으로 분리하는 것을 고려하세요.
Use Proper Defaults	선택적 필드에 합리적인 기본값을 제공하세요. 생성 시 계산되어야 하는 동적 값에는 함수 기본값 (예: () => dayjs())을 사용하세요.
Complete Dictionary Coverage	항상 모든 필드와 enum 값에 대한 번역을 제공하세요. 타입 시스템을 사용하여 누락되는 것이 없도록 하세요.
Validate at Field Level	min/max, minlength/maxlength 및 커스텀 validate 함수와 같은 필드 옵션을 사용하여 스키마 수준에서 데이터 무결성을 보장하세요.

Design for Reusability

여러 모듈에서 사용할 수 있는 스칼라를 만드세요. 주소, 연락처 정보, 상태 추적과 같은 공통 데이터 패턴을 생각해보세요.

Keep Scalars Focused

각 스칼라는 단일 개념을 나타내야 합니다. 스칼라가 너무 커지면 더 작고 조합 가능한 조각으로 분리하는 것을 고려하세요.

Use Proper Defaults

선택적 필드에 합리적인 기본값을 제공하세요. 생성 시 계산되어야 하는 동적 값에는 함수 기본값 (예: () => dayjs())을 사용하세요.

Complete Dictionary Coverage

항상 모든 필드와 enum 값에 대한 번역을 제공하세요. 타입 시스템을 사용하여 누락되는 것이 없도록 하세요.

Validate at Field Level

min/max, minlength/maxlength 및 커스텀 validate 함수와 같은 필드 옵션을 사용하여 스키마 수준에서 데이터 무결성을 보장하세요.

통합 포인트

스칼라는 Akan.js 프레임워크의 다른 부분과 원활하게 통합됩니다:

field	설명
Domain Models	field([ScalarClass])를 사용하여 모델에 스칼라 임베드
GraphQL	API 계약을 위한 자동 생성된 타입 및 enum
Validation	필드 옵션을 통한 런타임 타입 검사
Internationalization	scalarDictionary()를 통한 일관된 용어
UI Components	Enum 값을 선택 필드에서 직접 사용 가능
Dictionary Sharing	dictionary 간 enum 번역 재사용

Domain Models

field([ScalarClass])를 사용하여 모델에 스칼라 임베드

GraphQL

API 계약을 위한 자동 생성된 타입 및 enum

Validation

필드 옵션을 통한 런타임 타입 검사

Internationalization

scalarDictionary()를 통한 일관된 용어

UI Components

Enum 값을 선택 필드에서 직접 사용 가능

Dictionary Sharing

dictionary 간 enum 번역 재사용

🎉 배운 내용:

✓ via()와 enumOf() 함수를 사용하여 스칼라를 만드는 방법
✓ scalarDictionary()로 국제화를 정의하는 방법
✓ by()를 사용하여 커스텀 메서드로 스칼라를 확장하는 방법
✓ 스칼라의 명명 규칙과 모범 사례
✓ 스칼라가 모델 및 기타 프레임워크 기능과 통합되는 방법

실제 애플리케이션에서 스칼라를 생성하고 사용하는 실습 예제를 보려면 Tutorials 섹션을 확인하세요.

스칼라 모듈 개요

자체 데이터베이스 컬렉션을 가진 전체 Model과 달리, Scalar는 다른 모델 안에 내장됩니다. 다음과 같은 용도에 완벽합니다:

도메인 모델의 임베디드 문서 (예: 주소, 연락처 정보)
모듈 간 공유 DTO 및 구성 객체
런타임 유효성 검사가 있는 타입 안전 스키마
완전한 i18n 지원이 있는 국제화된 데이터 구조

핵심 원칙

🔄Reusability

모듈 간 사용을 위해 설계됨. 한 번 정의하고 어디서든 사용.

📦Stateless

비즈니스 로직 없는 순수 데이터 컨테이너. 동작이 아닌 구조에 집중.

🛡️Type-Safe

필드 옵션을 통한 런타임 유효성 검사와 완전한 TypeScript 통합.

🧩Composable

더 큰 도메인 모델 내에 임베딩 가능. 스칼라는 다른 스칼라를 포함할 수 있음.

파일 구조

스칼라 모듈은 라이브러리 내의 특수한 __scalar 디렉토리에 저장됩니다. 각 스칼라는 세 개의 핵심 파일이 있는 자체 디렉토리를 가집니다:

field	설명
*.constant.ts	via() 함수를 사용하여 스칼라 스키마를 정의하고 enumOf()를 사용하여 enum을 정의합니다. 여기서 필드, 타입, 기본값 및 유효성 검사 규칙을 선언합니다.
*.dictionary.ts	scalarDictionary() 빌더 패턴을 사용하여 국제화를 제공합니다. 모델 이름, 필드 레이블, 설명 및 enum 값에 대한 번역을 정의합니다.
*.document.ts	by() 함수를 사용하여 기능을 확장하는 선택적 파일입니다. 데이터 변환 및 계산된 값을 위한 커스텀 메서드를 추가합니다.

*.constant.ts

via() 함수를 사용하여 스칼라 스키마를 정의하고 enumOf()를 사용하여 enum을 정의합니다. 여기서 필드, 타입, 기본값 및 유효성 검사 규칙을 선언합니다.

*.dictionary.ts

scalarDictionary() 빌더 패턴을 사용하여 국제화를 제공합니다. 모델 이름, 필드 레이블, 설명 및 enum 값에 대한 번역을 정의합니다.

*.document.ts

by() 함수를 사용하여 기능을 확장하는 선택적 파일입니다. 데이터 변환 및 계산된 값을 위한 커스텀 메서드를 추가합니다.

스칼라 정의하기

price.constant.ts

핵심 패턴을 이해해봅시다:

field	설명
enumOf(name, values)	타입이 지정된 enum 클래스를 생성합니다. 첫 번째 인수는 enum 이름(dictionary에서 사용), 두 번째는 타입 안전을 위해 "as const"가 포함된 값 배열입니다.
via((field) => ({...}))	타입이 지정된 필드를 가진 스칼라 클래스를 생성합니다. field() 함수는 타입과 기본값, 유효성 검사 등을 위한 선택적 구성을 받습니다.
Field Options	옵션에는: default (정적 또는 함수), min/max (숫자용), minlength/maxlength (문자열용), validate (커스텀 검증 함수)가 포함됩니다.

enumOf(name, values)

타입이 지정된 enum 클래스를 생성합니다. 첫 번째 인수는 enum 이름(dictionary에서 사용), 두 번째는 타입 안전을 위해 "as const"가 포함된 값 배열입니다.

via((field) => ({...}))

타입이 지정된 필드를 가진 스칼라 클래스를 생성합니다. field() 함수는 타입과 기본값, 유효성 검사 등을 위한 선택적 구성을 받습니다.

Field Options

옵션에는: default (정적 또는 함수), min/max (숫자용), minlength/maxlength (문자열용), validate (커스텀 검증 함수)가 포함됩니다.

scalarDictionary()

scalarDictionary() 함수는 번역을 정의하기 위한 플루언트 빌더 패턴을 제공합니다. 타입 안전성과 모든 필드 및 enum 값의 완전한 커버리지를 보장합니다.

price.dictionary.ts

dictionary 빌더 패턴을 이해해봅시다:

field	설명
scalarDictionary([languages])	지원되는 언어 배열로 초기화합니다. 순서는 번역 배열에서 어떤 인덱스가 어떤 언어에 해당하는지를 결정합니다.
.of((t) => ...)	스칼라 자체의 이름과 설명을 정의합니다. 레이블에는 t([en, ko])를, 설명에는 .desc([en, ko])를 사용합니다.
.model<Type>((t) => ({...}))	각 필드에 대한 번역을 정의합니다. 제네릭 타입은 모든 필드가 커버되도록 보장합니다. 각 필드는 레이블과 설명을 가집니다.
.enum<Type>(name, (t) => ({...}))	enum 값에 대한 번역을 정의합니다. 첫 번째 인수는 enum 이름(enumOf()와 일치), 두 번째는 각 값에 대한 번역을 정의합니다.

scalarDictionary([languages])

지원되는 언어 배열로 초기화합니다. 순서는 번역 배열에서 어떤 인덱스가 어떤 언어에 해당하는지를 결정합니다.

.of((t) => ...)

스칼라 자체의 이름과 설명을 정의합니다. 레이블에는 t([en, ko])를, 설명에는 .desc([en, ko])를 사용합니다.

.model<Type>((t) => ({...}))

각 필드에 대한 번역을 정의합니다. 제네릭 타입은 모든 필드가 커버되도록 보장합니다. 각 필드는 레이블과 설명을 가집니다.

.enum<Type>(name, (t) => ({...}))

enum 값에 대한 번역을 정의합니다. 첫 번째 인수는 enum 이름(enumOf()와 일치), 두 번째는 각 값에 대한 번역을 정의합니다.

by()로 Document 확장하기

price.document.ts

document 확장에 대한 핵심 포인트:

field	설명
by(cnst.ClassName)	상수 클래스를 감싸고 메서드 추가를 활성화합니다. 이름 충돌을 피하기 위해 상수를 cnst로 임포트합니다.
Custom Methods	계산된 속성, 유효성 검사 헬퍼, 변환 메서드를 클래스 본문에 직접 추가합니다.
Access Fields	'this'를 사용하여 상수 파일에 정의된 모든 필드에 접근합니다. TypeScript가 완전한 자동 완성을 제공합니다.

by(cnst.ClassName)

상수 클래스를 감싸고 메서드 추가를 활성화합니다. 이름 충돌을 피하기 위해 상수를 cnst로 임포트합니다.

Custom Methods

계산된 속성, 유효성 검사 헬퍼, 변환 메서드를 클래스 본문에 직접 추가합니다.

Access Fields

'this'를 사용하여 상수 파일에 정의된 모든 필드에 접근합니다. TypeScript가 완전한 자동 완성을 제공합니다.

명명 규칙

일관된 명명은 유지보수성에 중요합니다. 다음 규칙을 따르세요:

field	설명
Scalar Directory	camelCase (e.g., encourageInfo)
Constant File	[name].constant.ts (e.g., encourageInfo.constant.ts)
Dictionary File	[name].dictionary.ts (e.g., encourageInfo.dictionary.ts)
Document File	[name].document.ts (e.g., encourageInfo.document.ts)
Scalar Class	PascalCase (e.g., EncourageInfo)
Enum Class	PascalCase (e.g., Journey, LinkType)
Enum Values	camelCase (e.g., firstJoin, waitPay)

Scalar Directory

camelCase (e.g., encourageInfo)

Constant File

[name].constant.ts (e.g., encourageInfo.constant.ts)

Dictionary File

[name].dictionary.ts (e.g., encourageInfo.dictionary.ts)

Document File

[name].document.ts (e.g., encourageInfo.document.ts)

Scalar Class

PascalCase (e.g., EncourageInfo)

Enum Class

PascalCase (e.g., Journey, LinkType)

Enum Values

camelCase (e.g., firstJoin, waitPay)

모범 사례

field	설명
Design for Reusability	여러 모듈에서 사용할 수 있는 스칼라를 만드세요. 주소, 연락처 정보, 상태 추적과 같은 공통 데이터 패턴을 생각해보세요.
Keep Scalars Focused	각 스칼라는 단일 개념을 나타내야 합니다. 스칼라가 너무 커지면 더 작고 조합 가능한 조각으로 분리하는 것을 고려하세요.
Use Proper Defaults	선택적 필드에 합리적인 기본값을 제공하세요. 생성 시 계산되어야 하는 동적 값에는 함수 기본값 (예: () => dayjs())을 사용하세요.
Complete Dictionary Coverage	항상 모든 필드와 enum 값에 대한 번역을 제공하세요. 타입 시스템을 사용하여 누락되는 것이 없도록 하세요.
Validate at Field Level	min/max, minlength/maxlength 및 커스텀 validate 함수와 같은 필드 옵션을 사용하여 스키마 수준에서 데이터 무결성을 보장하세요.

Design for Reusability

여러 모듈에서 사용할 수 있는 스칼라를 만드세요. 주소, 연락처 정보, 상태 추적과 같은 공통 데이터 패턴을 생각해보세요.

Keep Scalars Focused

각 스칼라는 단일 개념을 나타내야 합니다. 스칼라가 너무 커지면 더 작고 조합 가능한 조각으로 분리하는 것을 고려하세요.

Use Proper Defaults

선택적 필드에 합리적인 기본값을 제공하세요. 생성 시 계산되어야 하는 동적 값에는 함수 기본값 (예: () => dayjs())을 사용하세요.

Complete Dictionary Coverage

항상 모든 필드와 enum 값에 대한 번역을 제공하세요. 타입 시스템을 사용하여 누락되는 것이 없도록 하세요.

Validate at Field Level

min/max, minlength/maxlength 및 커스텀 validate 함수와 같은 필드 옵션을 사용하여 스키마 수준에서 데이터 무결성을 보장하세요.

통합 포인트

스칼라는 Akan.js 프레임워크의 다른 부분과 원활하게 통합됩니다:

field	설명
Domain Models	field([ScalarClass])를 사용하여 모델에 스칼라 임베드
GraphQL	API 계약을 위한 자동 생성된 타입 및 enum
Validation	필드 옵션을 통한 런타임 타입 검사
Internationalization	scalarDictionary()를 통한 일관된 용어
UI Components	Enum 값을 선택 필드에서 직접 사용 가능
Dictionary Sharing	dictionary 간 enum 번역 재사용