Skip to Content
API 레퍼런스@asapjs/sequelize@Dto 데코레이터

@Dto 데코레이터

@Dto는 DTO 클래스의 메타데이터를 등록하는 클래스 데코레이터입니다. PaginationQueryDto, PaginationQueryType, DtoOrTypeIs 타입도 함께 다룹니다.

이 페이지에서 찾을 수 있는 것

심볼타입설명
DtoClassDecoratorDTO 메타데이터 등록 데코레이터
PaginationQueryDtoclass페이지네이션 쿼리 내장 DTO (canonical 위치)
PaginationQueryTypetypePick<PaginationQueryDto, 'page' | 'limit'>
DtoOrTypeIstypeDTO 클래스 또는 TypeIs 함수 유니온

임포트

import { Dto, PaginationQueryDto, type PaginationQueryType, type DtoOrTypeIs } from '@asapjs/sequelize';

@Dto

시그니처

function Dto(info: {
  defineTable: typeof Model;  // 필수 — 이 DTO가 쿼리할 엔티티 클래스
  timestamps?: boolean;        // 기본값: 생략 시 true
  name?: string;               // 선택적 레이블
}): ClassDecorator

파라미터

파라미터타입필수 여부설명
defineTabletypeof Model예이 DTO가 매핑되는 Sequelize 모델 클래스. middleware()가 반환값의 model을 채우고 TypeIs.QUERY가 연관 경로를 해석하는 데 사용됩니다.
timestampsboolean아니오생략하면 내부적으로 true. 비활성화하려면 false를 전달하세요. 메타데이터만 제어하며 컬럼을 추가하거나 제거하지 않습니다.
namestring아니오콘솔 레지스트리에 저장되는 선택적 레이블. 런타임 동작에 영향을 주지 않습니다.

동작

@Dto 데코레이터는 해석된 info 객체를 'sequelize::dtoInfo' reflect-metadata 키 아래 target.prototype에 기록합니다. 또한 addDto를 통해 DTO의 타입 데이터를 콘솔 레지스트리에 등록합니다.

@Dto({ defineTable: UsersTable, timestamps: false, name: 'user_info_dto' })
export default class UserInfoDto extends ExtendableDto {
  @TypeIs.INT({ comment: 'User ID' })
  id: number;
 
  @TypeIs.STRING({ comment: 'Email' })
  email: string;
 
  @TypeIs.STRING({ comment: 'Display name' })
  name: string;
}

@Dto vs. 생성자 방식

@Dto 데코레이터 (권장)생성자 Reflect.defineMetadata (레거시)
메타데이터 대상target.prototypethis (인스턴스)
init() 호출파일명이 *Dto.ts이면 initSequelizeModule()에서 자동 호출생성자에서 명시적 호출
콘솔 레지스트리addDto를 통해 자동 등록수동 등록 필요
사용 시점대부분의 경우 (권장)인스턴스별 제어가 필요할 때

PaginationQueryDto

PaginationQueryDto는 @asapjs/sequelize가 제공하는 내장 DTO로, 페이지네이션 쿼리 파라미터를 표준화합니다.

정의

class PaginationQueryDto extends ExtendableDto {
  @TypeIs.INT({ comment: '페이지' })
  page: number;
 
  @TypeIs.INT({ comment: '한 페이지당 표시 개수' })
  limit: number;
}

라우트에서의 사용법

라우트의 query 옵션으로 PaginationQueryDto(또는 이를 상속한 커스텀 DTO)를 전달하면 ?page=&limit= 쿼리 스트링 파라미터를 문서화합니다:

@Get('/', {
  title: '사용자 목록 조회',
  query: GetUserListQueryDto,  // PaginationQueryDto를 상속
  response: UserDto,
})
public getUserList = async ({ paging, user }: ExecuteArgs<{}, GetUserListQueryDto, {}>) => {
  const result = await this.userService.list(paging, user);
  return { result };
};

PaginationQueryType

type PaginationQueryType = Pick<PaginationQueryDto, 'page' | 'limit'>;

PaginationQueryDto에서 page와 limit 필드만 추출한 타입입니다. @asapjs/router의 Wrapper가 생성하는 paging 객체의 타입이며, ExecuteArgs.paging의 타입입니다. Wrapper는 DTO 인스턴스가 아닌 PaginationQueryType 타입의 plain object를 생성합니다.

DtoOrTypeIs 타입

type DtoOrTypeIs = typeof ExtendableDto | (() => TypeIsData);

DtoOrTypeIs는 IOptions(라우트 데코레이터 옵션)의 body, query, response 필드와 TypeIs.ARRAY가 받는 유니온 타입입니다.

분기사용 시점예시
typeof ExtendableDtoDTO 클래스 — 이름이 있는 필드를 가진 구조화된 객체body: CreateUserDto
() => TypeIsData순수 TypeIs.*() 호출 — 기본형 또는 복합 응답response: TypeIs.BOOLEAN()

TypeIs.ARRAY 함수는 런타임에 isClass 검사로 어느 분기인지 판별합니다:

// DTO 분기 — 네임드 스키마에 대한 $ref 생성
TypeIs.ARRAY(UserInfoDto)
 
// TypeIs 분기 — 인라인 배열 스키마 생성
TypeIs.ARRAY(TypeIs.INT())
TypeIs.ARRAY(TypeIs.STRING())

관련 항목

Last updated on
데이터베이스 라이프사이클ExtendableDto