ts-deco 1.0.3 → 1.0.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +176 -203
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,25 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
TypeScript decorator utilities with **strict validation standards**
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
### 🔒 엄격한 검증 기준
|
|
8
|
-
|
|
9
|
-
기존의 널널한 커스텀 데코레이터 방식과 달리, `ts-deco`는 **엄격한 타입 검증과 검증 규칙**을 제공합니다.
|
|
10
|
-
|
|
11
|
-
- ✅ **타입 안전성**: 모든 데코레이터는 엄격한 타입 체크를 거칩니다
|
|
12
|
-
- ✅ **명시적 검증**: 옵션과 검증 규칙이 명확하게 정의되어 있습니다
|
|
13
|
-
- ✅ **일관된 동작**: 모든 데코레이터가 동일한 기준으로 동작합니다
|
|
14
|
-
- ✅ **런타임 안정성**: 잘못된 타입이나 값에 대해 명확한 에러를 제공합니다
|
|
15
|
-
|
|
16
|
-
### 기존 방식 vs ts-deco
|
|
17
|
-
|
|
18
|
-
| 기존 커스텀 방식 | ts-deco |
|
|
19
|
-
|----------------|---------|
|
|
20
|
-
| 느슨한 타입 체크 | 엄격한 타입 검증 |
|
|
21
|
-
| 불명확한 검증 규칙 | 명시적 검증 옵션 |
|
|
22
|
-
| 일관성 없는 동작 | 표준화된 동작 |
|
|
23
|
-
| 런타임 에러 가능성 | 타입 안전성 보장 |
|
|
5
|
+
엄격한 타입 검증과 검증 규칙을 제공하는 NestJS용 DTO 데코레이터 라이브러리입니다.
|
|
24
6
|
|
|
25
7
|
## 설치
|
|
26
8
|
|
|
@@ -28,267 +10,258 @@ TypeScript decorator utilities with **strict validation standards**
|
|
|
28
10
|
npm install ts-deco
|
|
29
11
|
```
|
|
30
12
|
|
|
31
|
-
##
|
|
32
|
-
|
|
33
|
-
### 사전 준비
|
|
34
|
-
|
|
35
|
-
#### 1. npm 로그인
|
|
36
|
-
|
|
37
|
-
배포하기 전에 npm에 로그인해야 합니다:
|
|
38
|
-
|
|
39
|
-
```bash
|
|
40
|
-
npm login
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
npm 계정이 없다면 [npmjs.com](https://www.npmjs.com)에서 계정을 생성하세요.
|
|
13
|
+
## 빠른 시작
|
|
44
14
|
|
|
45
|
-
|
|
15
|
+
`Property` 데코레이터 하나로 모든 타입을 처리할 수 있습니다:
|
|
46
16
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
**방법 1: 2FA 활성화 (권장)**
|
|
50
|
-
|
|
51
|
-
1. [npmjs.com](https://www.npmjs.com)에 로그인
|
|
52
|
-
2. 계정 설정 → "Two-Factor Authentication" 활성화
|
|
53
|
-
3. 인증 앱(Google Authenticator 등)으로 QR 코드 스캔
|
|
54
|
-
4. 배포 시 OTP 코드 입력
|
|
55
|
-
|
|
56
|
-
**방법 2: Granular Access Token 사용**
|
|
57
|
-
|
|
58
|
-
1. [npmjs.com](https://www.npmjs.com) → Account Settings → Access Tokens
|
|
59
|
-
2. "Generate New Token" → "Granular Access Token" 선택
|
|
60
|
-
3. 권한: "Publish" 선택
|
|
61
|
-
4. "Bypass 2FA" 옵션 활성화 (선택사항)
|
|
62
|
-
5. 생성된 토큰을 사용하여 로그인:
|
|
63
|
-
|
|
64
|
-
```bash
|
|
65
|
-
npm login --auth-type=legacy
|
|
66
|
-
# 또는 환경변수로 설정
|
|
67
|
-
export NPM_TOKEN=your_token_here
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
> **참고**: Granular Access Token을 사용하면 2FA를 우회할 수 있지만, 보안을 위해 2FA 활성화를 권장합니다.
|
|
71
|
-
|
|
72
|
-
### npm 스크립트 사용
|
|
73
|
-
|
|
74
|
-
```bash
|
|
75
|
-
# 패치 버전 (1.0.0 -> 1.0.1)
|
|
76
|
-
npm run publish:patch
|
|
77
|
-
|
|
78
|
-
# 마이너 버전 (1.0.0 -> 1.1.0)
|
|
79
|
-
npm run publish:minor
|
|
80
|
-
|
|
81
|
-
# 메이저 버전 (1.0.0 -> 2.0.0)
|
|
82
|
-
npm run publish:major
|
|
17
|
+
```typescript
|
|
18
|
+
import { Property } from 'ts-deco';
|
|
83
19
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
20
|
+
class CreateUserDto {
|
|
21
|
+
@Property({ type: String, optional: false })
|
|
22
|
+
name: string;
|
|
87
23
|
|
|
88
|
-
|
|
24
|
+
@Property({ type: Number, min: 0, max: 120 })
|
|
25
|
+
age: number;
|
|
89
26
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
./deploy.sh patch
|
|
27
|
+
@Property({ type: String, optional: true })
|
|
28
|
+
email?: string;
|
|
93
29
|
|
|
94
|
-
|
|
95
|
-
|
|
30
|
+
@Property({ type: Boolean, optional: false })
|
|
31
|
+
isActive: boolean;
|
|
96
32
|
|
|
97
|
-
|
|
98
|
-
|
|
33
|
+
@Property({ type: Date, optional: true })
|
|
34
|
+
createdAt?: Date;
|
|
35
|
+
}
|
|
99
36
|
```
|
|
100
37
|
|
|
101
|
-
> **참고**: 배포 전에 자동으로 빌드가 실행되며, `prepublishOnly` 훅을 통해 빌드가 확인됩니다.
|
|
102
|
-
|
|
103
38
|
## 주요 기능
|
|
104
39
|
|
|
105
|
-
|
|
106
|
-
- `DtoString`: 문자열 타입 엄격 검증
|
|
107
|
-
- `DtoNumber`: 숫자 타입 및 범위 검증 (min/max)
|
|
108
|
-
- `DtoDate`: 날짜 타입 검증 및 변환
|
|
109
|
-
- `DtoBoolean`: 불린 타입 검증 및 변환
|
|
110
|
-
- `DtoEnum`: 열거형 타입 엄격 검증
|
|
111
|
-
- `Property`: 통합 타입 기반 검증
|
|
112
|
-
- **타입 안전한** 유틸리티 함수 (`applyDecorators`)
|
|
40
|
+
### Property 데코레이터 (권장)
|
|
113
41
|
|
|
114
|
-
|
|
42
|
+
`Property` 데코레이터는 타입에 따라 자동으로 적절한 검증을 적용합니다.
|
|
115
43
|
|
|
116
|
-
|
|
44
|
+
#### 기본 타입
|
|
117
45
|
|
|
118
46
|
```typescript
|
|
119
|
-
import {
|
|
47
|
+
import { Property } from 'ts-deco';
|
|
120
48
|
|
|
121
|
-
class
|
|
122
|
-
//
|
|
123
|
-
@
|
|
49
|
+
class UserDto {
|
|
50
|
+
// 문자열
|
|
51
|
+
@Property({ type: String, optional: false })
|
|
124
52
|
name: string;
|
|
125
53
|
|
|
126
|
-
// 숫자 범위 검증
|
|
127
|
-
@
|
|
128
|
-
|
|
54
|
+
// 숫자 (범위 검증)
|
|
55
|
+
@Property({
|
|
56
|
+
type: Number,
|
|
57
|
+
min: 1,
|
|
58
|
+
max: 100,
|
|
59
|
+
optional: false
|
|
60
|
+
})
|
|
61
|
+
score: number;
|
|
129
62
|
|
|
130
|
-
//
|
|
131
|
-
@Property({ type:
|
|
132
|
-
|
|
63
|
+
// 날짜
|
|
64
|
+
@Property({ type: Date, optional: true })
|
|
65
|
+
birthDate?: Date;
|
|
66
|
+
|
|
67
|
+
// 불린
|
|
68
|
+
@Property({ type: Boolean, optional: false })
|
|
69
|
+
isActive: boolean;
|
|
133
70
|
}
|
|
134
71
|
```
|
|
135
72
|
|
|
136
|
-
|
|
73
|
+
#### 열거형 (Enum)
|
|
137
74
|
|
|
138
75
|
```typescript
|
|
139
|
-
import {
|
|
76
|
+
import { Property } from 'ts-deco';
|
|
140
77
|
|
|
141
78
|
enum UserRole {
|
|
142
79
|
ADMIN = 'admin',
|
|
143
80
|
USER = 'user',
|
|
81
|
+
GUEST = 'guest',
|
|
144
82
|
}
|
|
145
83
|
|
|
146
|
-
class
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
max: 100,
|
|
151
|
-
isInt: true, // 정수만 허용
|
|
152
|
-
minMessage: '최소값은 1 이상이어야 합니다',
|
|
153
|
-
maxMessage: '최대값은 100 이하여야 합니다'
|
|
84
|
+
class UserDto {
|
|
85
|
+
@Property({
|
|
86
|
+
enum: UserRole,
|
|
87
|
+
optional: false
|
|
154
88
|
})
|
|
155
|
-
|
|
89
|
+
role: UserRole;
|
|
156
90
|
|
|
157
|
-
//
|
|
158
|
-
@
|
|
159
|
-
|
|
160
|
-
exclude: []
|
|
91
|
+
// 특정 값 제외
|
|
92
|
+
@Property({
|
|
93
|
+
enum: UserRole,
|
|
94
|
+
exclude: [UserRole.GUEST],
|
|
95
|
+
optional: false
|
|
161
96
|
})
|
|
162
|
-
|
|
97
|
+
allowedRole: UserRole;
|
|
163
98
|
}
|
|
164
99
|
```
|
|
165
100
|
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
여러 데코레이터를 하나로 합치는 유틸리티 함수입니다.
|
|
101
|
+
#### 배열
|
|
169
102
|
|
|
170
103
|
```typescript
|
|
171
|
-
import {
|
|
172
|
-
import { ApiProperty } from '@nestjs/swagger';
|
|
173
|
-
import { IsString } from 'class-validator';
|
|
104
|
+
import { Property } from 'ts-deco';
|
|
174
105
|
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
106
|
+
class UserDto {
|
|
107
|
+
@Property({
|
|
108
|
+
type: String,
|
|
109
|
+
isArray: true,
|
|
110
|
+
optional: false
|
|
111
|
+
})
|
|
112
|
+
tags: string[];
|
|
113
|
+
|
|
114
|
+
@Property({
|
|
115
|
+
type: Number,
|
|
116
|
+
isArray: true,
|
|
117
|
+
min: 1,
|
|
118
|
+
max: 10,
|
|
119
|
+
optional: false
|
|
120
|
+
})
|
|
121
|
+
scores: number[];
|
|
122
|
+
}
|
|
179
123
|
```
|
|
180
124
|
|
|
181
|
-
|
|
125
|
+
#### 커스텀 에러 메시지
|
|
182
126
|
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
- `PropertyDecorator`끼리만 합칠 수 있습니다
|
|
186
|
-
- `MethodDecorator`끼리만 합칠 수 있습니다
|
|
187
|
-
- `ParameterDecorator`끼리만 합칠 수 있습니다
|
|
127
|
+
```typescript
|
|
128
|
+
import { Property } from 'ts-deco';
|
|
188
129
|
|
|
189
|
-
|
|
130
|
+
class UserDto {
|
|
131
|
+
@Property({
|
|
132
|
+
type: Number,
|
|
133
|
+
min: 1,
|
|
134
|
+
max: 100,
|
|
135
|
+
minMessage: '최소값은 1 이상이어야 합니다',
|
|
136
|
+
maxMessage: '최대값은 100 이하여야 합니다',
|
|
137
|
+
validatorMessage: '숫자 타입이어야 합니다',
|
|
138
|
+
optional: false
|
|
139
|
+
})
|
|
140
|
+
score: number;
|
|
141
|
+
}
|
|
142
|
+
```
|
|
190
143
|
|
|
191
|
-
|
|
192
|
-
- **MethodDecorator**: `PropertyDescriptor | void` 반환 가능
|
|
193
|
-
- **PropertyDecorator**: 반환값 없음 (void)
|
|
194
|
-
- **ParameterDecorator**: 반환값 없음 (void)
|
|
144
|
+
### 개별 데코레이터
|
|
195
145
|
|
|
196
|
-
|
|
146
|
+
더 세밀한 제어가 필요한 경우 개별 데코레이터를 사용할 수 있습니다:
|
|
197
147
|
|
|
198
|
-
|
|
148
|
+
```typescript
|
|
149
|
+
import { DtoString, DtoNumber, DtoDate, DtoBoolean, DtoEnum } from 'ts-deco';
|
|
199
150
|
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
- **배열 검증**: `isArray: true`인 경우 배열 타입만 허용
|
|
204
|
-
- **열거형 검증**: `DtoEnum`은 제공된 enum 값만 허용
|
|
151
|
+
class UserDto {
|
|
152
|
+
@DtoString({ optional: false })
|
|
153
|
+
name: string;
|
|
205
154
|
|
|
206
|
-
|
|
155
|
+
@DtoNumber({ min: 0, max: 120 })
|
|
156
|
+
age: number;
|
|
207
157
|
|
|
208
|
-
|
|
158
|
+
@DtoDate({ optional: true })
|
|
159
|
+
birthDate?: Date;
|
|
209
160
|
|
|
210
|
-
|
|
161
|
+
@DtoBoolean({ optional: false })
|
|
162
|
+
isActive: boolean;
|
|
211
163
|
|
|
212
|
-
|
|
164
|
+
@DtoEnum(UserRole, { optional: false })
|
|
165
|
+
role: UserRole;
|
|
166
|
+
}
|
|
167
|
+
```
|
|
213
168
|
|
|
214
|
-
|
|
169
|
+
## Property 데코레이터 옵션
|
|
215
170
|
|
|
216
|
-
|
|
171
|
+
### 공통 옵션
|
|
217
172
|
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
173
|
+
| 옵션 | 타입 | 기본값 | 설명 |
|
|
174
|
+
|------|------|--------|------|
|
|
175
|
+
| `type` | `String \| Number \| Date \| Boolean` | 필수 | 필드 타입 |
|
|
176
|
+
| `enum` | `object` | - | 열거형 타입 (type 대신 사용) |
|
|
177
|
+
| `optional` | `boolean` | `false` | 선택적 필드 여부 |
|
|
178
|
+
| `isArray` | `boolean` | `false` | 배열 타입 여부 |
|
|
179
|
+
| `validatorMessage` | `string` | - | 검증 실패 메시지 |
|
|
180
|
+
| `arrayMessage` | `string` | - | 배열 검증 실패 메시지 |
|
|
181
|
+
| `notEmptyMessage` | `string` | - | 빈 값 검증 실패 메시지 |
|
|
221
182
|
|
|
222
|
-
|
|
183
|
+
### 숫자 타입 전용 옵션
|
|
223
184
|
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
185
|
+
| 옵션 | 타입 | 기본값 | 설명 |
|
|
186
|
+
|------|------|--------|------|
|
|
187
|
+
| `min` | `number` | - | 최소값 |
|
|
188
|
+
| `max` | `number` | - | 최대값 |
|
|
189
|
+
| `isInt` | `boolean` | `false` | 정수만 허용 |
|
|
190
|
+
| `minMessage` | `string` | - | 최소값 검증 실패 메시지 |
|
|
191
|
+
| `maxMessage` | `string` | - | 최대값 검증 실패 메시지 |
|
|
227
192
|
|
|
228
|
-
|
|
193
|
+
### 열거형 전용 옵션
|
|
229
194
|
|
|
230
|
-
|
|
|
231
|
-
|
|
232
|
-
|
|
|
233
|
-
| 문법 | `@decorator` 형태 | `@decorator` 형태 (내부 동작 다름) |
|
|
234
|
-
| 타입 시그니처 | `(target, propertyKey, descriptor)` | `(value, context)` |
|
|
235
|
-
| 라이브러리 호환성 | NestJS, class-validator 등과 호환 | 아직 일부 라이브러리만 지원 |
|
|
236
|
-
| 안정성 | 검증됨 | 표준화 진행 중 |
|
|
195
|
+
| 옵션 | 타입 | 기본값 | 설명 |
|
|
196
|
+
|------|------|--------|------|
|
|
197
|
+
| `exclude` | `any[]` | `[]` | 제외할 enum 값들 |
|
|
237
198
|
|
|
238
|
-
|
|
199
|
+
### Swagger 옵션
|
|
239
200
|
|
|
240
|
-
|
|
201
|
+
`@nestjs/swagger`의 `ApiPropertyOptions`를 모두 사용할 수 있습니다:
|
|
241
202
|
|
|
242
|
-
|
|
203
|
+
```typescript
|
|
204
|
+
@Property({
|
|
205
|
+
type: String,
|
|
206
|
+
description: '사용자 이름',
|
|
207
|
+
example: '홍길동',
|
|
208
|
+
optional: false
|
|
209
|
+
})
|
|
210
|
+
name: string;
|
|
211
|
+
```
|
|
243
212
|
|
|
244
|
-
|
|
213
|
+
## 엄격한 검증 규칙
|
|
245
214
|
|
|
246
|
-
|
|
247
|
-
|--------|------|------|----------|
|
|
248
|
-
| `@nestjs/swagger` | ^7.0.0 | API 문서화 데코레이터 (`ApiProperty`, `ApiPropertyOptional`) | MIT |
|
|
249
|
-
| `class-transformer` | ^0.5.0 | 타입 변환 데코레이터 (`Type`, `Transform`) | MIT |
|
|
250
|
-
| `class-validator` | ^0.14.0 | 검증 데코레이터 (`IsString`, `IsNumber`, `IsDate`, `IsBoolean`, `IsEnum`, `IsArray`, `IsDefined`, `IsNotEmpty`, `IsOptional`, `Min`, `Max` 등) | MIT |
|
|
215
|
+
`ts-deco`는 다음과 같은 엄격한 검증 규칙을 적용합니다:
|
|
251
216
|
|
|
252
|
-
|
|
217
|
+
- ✅ **타입 안전성**: 모든 데코레이터는 엄격한 타입 체크를 거칩니다
|
|
218
|
+
- ✅ **명시적 검증**: 옵션과 검증 규칙이 명확하게 정의되어 있습니다
|
|
219
|
+
- ✅ **일관된 동작**: 모든 데코레이터가 동일한 기준으로 동작합니다
|
|
220
|
+
- ✅ **런타임 안정성**: 잘못된 타입이나 값에 대해 명확한 에러를 제공합니다
|
|
253
221
|
|
|
254
|
-
|
|
222
|
+
### 검증 규칙
|
|
255
223
|
|
|
256
|
-
|
|
224
|
+
- **타입 불일치 시 즉시 에러**: 잘못된 타입이 전달되면 명확한 에러 메시지 제공
|
|
225
|
+
- **범위 검증**: `min`/`max` 옵션이 제공되면 반드시 검증
|
|
226
|
+
- **필수 필드 검증**: `optional: false`인 경우 값이 없으면 에러
|
|
227
|
+
- **배열 검증**: `isArray: true`인 경우 배열 타입만 허용
|
|
228
|
+
- **열거형 검증**: `enum`이 제공되면 해당 값만 허용
|
|
257
229
|
|
|
258
|
-
##
|
|
230
|
+
## 유틸리티 함수
|
|
231
|
+
|
|
232
|
+
### applyDecorators
|
|
259
233
|
|
|
260
|
-
|
|
234
|
+
여러 데코레이터를 하나로 합치는 유틸리티 함수입니다:
|
|
261
235
|
|
|
262
|
-
|
|
236
|
+
```typescript
|
|
237
|
+
import { applyDecorators } from 'ts-deco';
|
|
238
|
+
import { ApiProperty } from '@nestjs/swagger';
|
|
239
|
+
import { IsString } from 'class-validator';
|
|
263
240
|
|
|
241
|
+
const MyDecorator = applyDecorators(
|
|
242
|
+
ApiProperty(),
|
|
243
|
+
IsString()
|
|
244
|
+
);
|
|
264
245
|
```
|
|
265
|
-
ISC License
|
|
266
246
|
|
|
267
|
-
|
|
247
|
+
⚠️ **주의**: 모든 데코레이터는 동일한 타입이어야 합니다.
|
|
268
248
|
|
|
269
|
-
|
|
270
|
-
purpose with or without fee is hereby granted, provided that the above
|
|
271
|
-
copyright notice and this permission notice appear in all copies.
|
|
249
|
+
## 데코레이터 지원
|
|
272
250
|
|
|
273
|
-
|
|
274
|
-
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
275
|
-
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
276
|
-
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
277
|
-
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
278
|
-
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
279
|
-
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
280
|
-
```
|
|
251
|
+
이 라이브러리는 **TypeScript legacy decorators**를 지원합니다. Stage 3 decorators는 아직 지원하지 않습니다.
|
|
281
252
|
|
|
282
|
-
|
|
253
|
+
## 의존성
|
|
283
254
|
|
|
284
|
-
이
|
|
255
|
+
이 라이브러리는 다음 패키지들을 **peer dependencies**로 사용합니다:
|
|
285
256
|
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
257
|
+
| 패키지 | 버전 | 용도 |
|
|
258
|
+
|--------|------|------|
|
|
259
|
+
| `@nestjs/swagger` | ^7.0.0 | API 문서화 데코레이터 |
|
|
260
|
+
| `class-transformer` | ^0.5.0 | 타입 변환 데코레이터 |
|
|
261
|
+
| `class-validator` | ^0.14.0 | 검증 데코레이터 |
|
|
289
262
|
|
|
290
|
-
|
|
263
|
+
> **참고**: 이 라이브러리는 런타임에 위 패키지들이 설치되어 있어야 합니다. `npm install` 시 자동으로 설치되지 않으므로, 프로젝트에 직접 설치해야 합니다.
|
|
291
264
|
|
|
292
|
-
|
|
265
|
+
## 라이선스
|
|
293
266
|
|
|
294
|
-
ISC License
|
|
267
|
+
ISC License
|