타입 체크

TypeScript의 타입 체크 옵션은 코드의 안정성을 결정합니다. Sonamu는 strict 모드를 기본으로 활성화하여 최대한의 타입 안정성을 제공합니다.

Strict 모드

Sonamu는 모든 strict 옵션을 활성화합니다.

{
  "compilerOptions": {
    "strict": true,                          // 모든 strict 옵션 활성화
    "noImplicitAny": true,                   // any 타입 명시 필요
    "strictNullChecks": true,                // null/undefined 엄격 체크
    "strictFunctionTypes": true,             // 함수 타입 엄격 체크
    "strictBindCallApply": true,             // bind/call/apply 엄격 체크
    "strictPropertyInitialization": true,    // 클래스 프로퍼티 초기화 필요
    "noImplicitThis": true,                  // this 타입 명시 필요
    "alwaysStrict": true                     // 'use strict' 자동 추가
  }
}

strict: true는 위의 모든 옵션을 한 번에 활성화하는 단축 설정입니다.

Strict 옵션 상세

any 타입 명시 필요

기능:

타입을 추론할 수 없을 때 any를 암묵적으로 사용하지 못하도록 방지

예시:

// ❌ 에러 발생
function log(message) {
  //         ^^^^^^^ Parameter 'message' implicitly has an 'any' type
  console.log(message);
}

// ✅ 올바른 코드
function log(message: string) {
  console.log(message);
}

// ✅ 제네릭 사용
function log<T>(message: T) {
  console.log(message);
}

타입을 명시하기 어려운 경우 unknown을 사용하세요. any보다 안전합니다.

null/undefined 엄격 체크

기능:

null과 undefined를 다른 타입에 할당할 수 없도록 방지
모든 타입이 기본적으로 non-nullable

예시:

// ❌ 에러 발생
let name: string = null;
//                 ^^^^ Type 'null' is not assignable to type 'string'

// ✅ Union 타입 사용
let name: string | null = null;
name = "Alice";

// ✅ Optional 체이닝
interface User {
  email?: string;
}

function sendEmail(user: User) {
  // ❌ 에러 발생
  const length = user.email.length;
  //                  ^^^^^ Object is possibly 'undefined'

  // ✅ Optional 체이닝
  const length = user.email?.length;

  // ✅ null 체크
  if (user.email !== undefined) {
    const length = user.email.length;
  }
}

Sonamu에서:

// entity.json으로 정의된 Entity 사용
interface User {
  id: number;
  name: string;           // null이 될 수 없음
  bio: string | null;     // null 허용
  email?: string;         // undefined 허용
  created_at: Date;
}

// Model 클래스에서 타입 안정성 확보
class UserModelClass extends BaseModelClass {
  @api({ httpMethod: "GET" })
  async findById(
    subset: UserSubsetKey,
    id: number
  ): Promise<UserSubsetMapping[typeof subset] | null> {
    const rdb = this.getPuri("r");
    const user = await rdb.table("users").where("id", id).first();
    
    // strictNullChecks가 null 체크를 강제함
    if (!user) {
      return null;
    }
    
    return user;
  }
}

함수 타입 엄격 체크

기능:

함수 파라미터의 contravariance(반공변성) 체크
더 안전한 함수 타입 호환성

예시:

interface Animal {
  name: string;
}

interface Dog extends Animal {
  bark(): void;
}

// ❌ 에러 발생 (strictFunctionTypes: true)
let animalHandler: (animal: Animal) => void;
let dogHandler: (dog: Dog) => void;

animalHandler = dogHandler;
// ^^^^^^^^^ Type '(dog: Dog) => void' is not assignable to type '(animal: Animal) => void'

// ✅ 올바른 방향
dogHandler = animalHandler;  // OK

이 옵션은 함수의 타입 안정성을 크게 향상시키지만, 일부 라이브러리와 호환성 문제가 있을 수 있습니다.

bind/call/apply 엄격 체크

기능:

bind, call, apply 메서드의 파라미터 타입 체크

예시:

function greet(name: string, age: number) {
  console.log(`Hello, ${name}! You are ${age} years old.`);
}

// ❌ 에러 발생
greet.call(null, "Alice", "30");
//                        ^^^^ Argument of type 'string' is not assignable to parameter of type 'number'

// ✅ 올바른 타입
greet.call(null, "Alice", 30);

// ❌ 에러 발생
greet.apply(null, ["Alice"]);
//                ^^^^^^^^^ Argument of type '[string]' is not assignable to parameter of type '[string, number]'

// ✅ 올바른 인자 수
greet.apply(null, ["Alice", 30]);

클래스 프로퍼티 초기화 필수

기능:

클래스 프로퍼티가 생성자에서 초기화되었는지 확인

예시:

class User {
  // ❌ 에러 발생
  name: string;
  // ^^^^ Property 'name' has no initializer and is not definitely assigned in the constructor

  // ✅ 생성자에서 초기화
  email: string;

  constructor(email: string) {
    this.email = email;
  }

  // ✅ 기본값 제공
  age: number = 0;

  // ✅ Optional
  bio?: string;

  // ✅ null 허용
  avatar: string | null = null;

  // ✅ Definite assignment assertion (확실한 경우만)
  id!: number;
}

Sonamu에서:

// Generated 타입은 모두 초기화됨
interface UserRow {
  id: number;              // DB에서 자동 생성
  email: string;           // 필수 필드
  name: string;            // 기본값 "guest"
  created_at: Date;        // 기본값 CURRENT_TIMESTAMP
}

// Model 클래스에서 Definite Assignment Assertion 사용
class UserModelClass extends BaseModelClass {
  // 생성자에서 초기화되므로 !
  private readonly tableName!: string;
  
  constructor() {
    super();
    this.tableName = "users";
  }

  @api({ httpMethod: "POST" })
  async create(data: UserSaveParams) {
    // data는 반드시 필수 필드를 포함해야 함
    const wdb = this.getDB("w");
    return this.insert(wdb, data);
  }
}

this 타입 명시 필요

기능:

this의 타입이 명확하지 않을 때 에러 발생

예시:

// ❌ 에러 발생
function onClick() {
  console.log(this.textContent);
  //          ^^^^ 'this' implicitly has type 'any'
}

// ✅ this 타입 명시
function onClick(this: HTMLElement) {
  console.log(this.textContent);
}

// ✅ 화살표 함수 (this 바인딩 없음)
const onClick = () => {
  // 외부 this 사용
};

// ✅ 클래스 메서드
class Button {
  text: string = "Click me";

  onClick() {
    console.log(this.text);  // OK
  }
}

추가 타입 체크 옵션

Sonamu는 strict 모드 외에도 추가 체크 옵션을 활성화합니다.

{
  "compilerOptions": {
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "useUnknownInCatchVariables": true,
    "noUncheckedIndexedAccess": true
  }
}

Unused 체크
Return 체크
Switch 체크
Catch 변수
인덱스 접근

사용하지 않는 코드 경고

{
  "noUnusedLocals": true,
  "noUnusedParameters": true
}

예시:

// ❌ noUnusedLocals 에러
function greet(name: string) {
  const message = "Hello";  // 사용되지 않음
  //    ^^^^^^^ 'message' is declared but its value is never read
  return name;
}

// ❌ noUnusedParameters 에러
function add(a: number, b: number) {
  //                     ^ 'b' is declared but its value is never read
  return a;
}

// ✅ 의도적으로 무시할 때는 _ 사용
function onClick(_event: MouseEvent) {
  console.log("Clicked!");
}

사용하지 않는 파라미터는 _로 시작하면 경고가 발생하지 않습니다.

모든 경로에서 return 필요

{
  "noImplicitReturns": true
}

예시:

// ❌ 에러 발생
function getStatus(code: number): string {
  if (code === 200) {
    return "OK";
  } else if (code === 404) {
    return "Not Found";
  }
  // ^^^^ Not all code paths return a value
}

// ✅ 모든 경로에서 return
function getStatus(code: number): string {
  if (code === 200) {
    return "OK";
  } else if (code === 404) {
    return "Not Found";
  }
  return "Unknown";
}

// ✅ 또는 명시적 에러
function getStatus(code: number): string {
  if (code === 200) {
    return "OK";
  } else if (code === 404) {
    return "Not Found";
  }
  throw new Error(`Unknown status code: ${code}`);
}

Switch문 Fallthrough 방지

{
  "noFallthroughCasesInSwitch": true
}

예시:

// ❌ 에러 발생
function getDay(day: number): string {
  switch (day) {
    case 0:
      return "Sunday";
    case 1:
      console.log("Monday");
      // ^^^^ Fallthrough case in switch
    case 2:
      return "Tuesday";
    default:
      return "Unknown";
  }
}

// ✅ break 또는 return 추가
function getDay(day: number): string {
  switch (day) {
    case 0:
      return "Sunday";
    case 1:
      console.log("Monday");
      return "Monday";  // 또는 break;
    case 2:
      return "Tuesday";
    default:
      return "Unknown";
  }
}

catch 블록 변수는 unknown

{
  "useUnknownInCatchVariables": true
}

예시:

try {
  throw new Error("Something went wrong");
} catch (error) {
  // error는 unknown 타입

  // ❌ 에러 발생
  console.log(error.message);
  //          ^^^^^ Object is of type 'unknown'

  // ✅ 타입 가드 사용
  if (error instanceof Error) {
    console.log(error.message);
  }

  // ✅ 타입 단언 (확실한 경우만)
  const err = error as Error;
  console.log(err.message);
}

any 대신 unknown을 사용하면 타입 체크를 강제할 수 있습니다.

배열/객체 접근 시 undefined 체크

{
  "noUncheckedIndexedAccess": true
}

예시:

const users = ["Alice", "Bob"];

// ❌ 에러 발생 (noUncheckedIndexedAccess)
const firstUser = users[0];
//    ^^^^^^^^^ Type 'string | undefined'

const name = firstUser.toUpperCase();
//                     ^^^^^^^^^^^ Object is possibly 'undefined'

// ✅ undefined 체크
const firstUser = users[0];
if (firstUser !== undefined) {
  const name = firstUser.toUpperCase();
}

// ✅ Optional 체이닝
const name = users[0]?.toUpperCase();

// ✅ Non-null assertion (확실한 경우만)
const name = users[0]!.toUpperCase();

// 객체도 마찬가지
type UserMap = { [key: string]: string };
const userMap: UserMap = { alice: "Alice" };

const user = userMap["alice"];
//    ^^^^ Type 'string | undefined'

이 옵션은 모든 배열/객체 접근을 T | undefined로 만듭니다. 많은 코드 수정이 필요할 수 있습니다.

더 엄격한 옵션 (선택)

필요에 따라 추가할 수 있는 옵션들입니다.

{
  "compilerOptions": {
    "noPropertyAccessFromIndexSignature": true,
    "exactOptionalPropertyTypes": true,
    "noUncheckedSideEffectImports": true
  }
}

noPropertyAccessFromIndexSignature

인덱스 시그니처는 대괄호로만 접근

interface Options {
  [key: string]: string;
}

const options: Options = { color: "red" };

// ❌ 에러 발생
const color = options.color;

// ✅ 대괄호 사용
const color = options["color"];

언제 사용:

동적 프로퍼티 접근을 명시적으로 만들고 싶을 때

exactOptionalPropertyTypes

Optional 프로퍼티는 undefined만 허용

interface User {
  name?: string;
}

// ❌ 에러 발생
const user: User = { name: undefined };

// ✅ 프로퍼티 생략
const user: User = {};

// ✅ 명시적 undefined 허용하려면
interface User {
  name: string | undefined;
}

언제 사용:

Optional과 | undefined를 엄격히 구분하고 싶을 때

많은 라이브러리와 호환성 문제가 있을 수 있습니다.

타입 체크 비활성화

특정 상황에서 타입 체크를 우회해야 할 때가 있습니다.

파일 전체
한 줄
타입 단언

// @ts-nocheck
// 이 파일의 모든 타입 체크 무시

const value = "hello";
value = 123;  // 에러 발생 안 함

// @ts-ignore
const value = someUntypedLibrary();

// 또는 에러 설명 추가
// @ts-expect-error - 외부 라이브러리 타입 불일치
const value = someUntypedLibrary();

@ts-ignore 대신 @ts-expect-error를 사용하면 에러가 실제로 발생하지 않을 때 경고를 받을 수 있습니다.

// as를 사용한 타입 단언
const value = someValue as string;

// Non-null assertion
const element = document.getElementById("root")!;

// Double assertion (최후의 수단)
const value = someValue as unknown as TargetType;

타입 단언은 타입 안정성을 깨뜨립니다. 정말 확실한 경우에만 사용하세요.

권장 설정

신규 프로젝트
기존 프로젝트
라이브러리

{
  "compilerOptions": {
    // Sonamu 기본 설정 사용
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "useUnknownInCatchVariables": true,
    "noUncheckedIndexedAccess": true
  }
}

신규 프로젝트는 모든 옵션을 활성화하세요.

{
  "compilerOptions": {
    "strict": true,
    // 점진적으로 추가
    // "noUnusedLocals": true,
    // "noUncheckedIndexedAccess": true
  }
}

기존 프로젝트는 점진적으로 옵션을 추가하세요.추천 순서:

strict: true
noUnusedLocals, noUnusedParameters
noImplicitReturns
noUncheckedIndexedAccess (많은 수정 필요)

{
  "compilerOptions": {
    "strict": true,
    "declaration": true,
    "declarationMap": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true
  }
}

라이브러리는 타입 정의 생성도 필수입니다.

성능 고려사항

타입 체크 옵션이 많을수록 컴파일 시간이 증가할 수 있습니다.

타입 체크 속도 향상

{
  "compilerOptions": {
    "skipLibCheck": true,           // node_modules 타입 체크 생략
    "incremental": true,             // 증분 컴파일
    "tsBuildInfoFile": ".tsbuildinfo"
  }
}

skipLibCheck

node_modules의 .d.ts 파일을 체크하지 않음
컴파일 시간 크게 단축
Sonamu 기본 활성화

incremental

변경된 파일만 재컴파일
.tsbuildinfo 파일에 캐시 저장

다음 단계

tsconfig.json

전체 TypeScript 설정을 확인하세요

Path Mapping

절대 경로 import를 설정하세요

Entity 정의

타입 안전한 Entity를 작성하세요

테스트 작성

타입 안전한 테스트를 작성하세요

시작하기

핵심 개념

데이터베이스

API 개발

프론트엔드 통합

테스팅

고급 기능

도구 & CLI

설정

API 레퍼런스

문제 해결

자주 묻는 질문

Strict 모드

Strict 옵션 상세

any 타입 명시 필요

null/undefined 엄격 체크

함수 타입 엄격 체크

bind/call/apply 엄격 체크

클래스 프로퍼티 초기화 필수

this 타입 명시 필요

추가 타입 체크 옵션

사용하지 않는 코드 경고

모든 경로에서 return 필요

Switch문 Fallthrough 방지

catch 블록 변수는 unknown

배열/객체 접근 시 undefined 체크

더 엄격한 옵션 (선택)

타입 체크 비활성화

권장 설정

성능 고려사항

다음 단계

tsconfig.json

Path Mapping

Entity 정의

테스트 작성

​Strict 모드

​Strict 옵션 상세

​any 타입 명시 필요

​null/undefined 엄격 체크

​함수 타입 엄격 체크

​bind/call/apply 엄격 체크

​클래스 프로퍼티 초기화 필수

​this 타입 명시 필요

​추가 타입 체크 옵션

​사용하지 않는 코드 경고

​모든 경로에서 return 필요

​Switch문 Fallthrough 방지

​catch 블록 변수는 unknown

​배열/객체 접근 시 undefined 체크

​더 엄격한 옵션 (선택)

​타입 체크 비활성화

​권장 설정

​성능 고려사항

​다음 단계

tsconfig.json

Path Mapping

Entity 정의

테스트 작성

Strict 모드

Strict 옵션 상세

any 타입 명시 필요

null/undefined 엄격 체크

함수 타입 엄격 체크

bind/call/apply 엄격 체크

클래스 프로퍼티 초기화 필수

this 타입 명시 필요

추가 타입 체크 옵션

사용하지 않는 코드 경고

모든 경로에서 return 필요

Switch문 Fallthrough 방지

catch 블록 변수는 unknown

배열/객체 접근 시 undefined 체크

더 엄격한 옵션 (선택)

타입 체크 비활성화

권장 설정

성능 고려사항

다음 단계