[TS] 타입스크립트 구조적 타이핑 활용하기

Object.keys 메서드의 타입 정의

---

타입스크립트를 사용하다 보면 아래 같은 상황을 자주 마주한다. Object.keys() 메서드를 사용해서 객체의 키를 배열로 추출한 후, 해당 키를 이용해 객체에 접근할 때 에러가 발생한다.

type Options = { host: string; port: number };

const validateOptions = (options: Options) => {
  const keys = Object.keys(options); // string[]
  keys.forEach((key) => {
    // Error! 'Options' 형식에서 'string' 형식의 매개 변수가 포함된 인덱스 시그니처를 찾을 수 없습니다.
    if (options[key] === null) {
      throw new Error(`Missing option ${key}`);
    }
  });
};

 

위 문제는 아래처럼 as 키워드를 사용해서 타입 단언하면 쉽게 해결할 수 있다. 이러한 문제는 왜 발생하는걸까?

const validateOptions = (options: Options) => {
  const keys = Object.keys(options) as (keyof Options)[];
  // ...
};

 

Object.keys 타입 정의를 살펴보면 객체를 인자로 받아 항상 string[]을 반환하도록 되어 있다.

// lib.es5.d.ts
interface ObjectConstructor {
  // ...
  keys(o: object): string[];
}

 

Object.keys() 메서드가 객체 제네릭 타입 T를 받아 (keyof T)[]를 반환한다면 이러한 문제는 발생하지 않는다. 타입스크립트가 이렇게 타입을 정의하지 않은 이유는 무엇일까? 이는 구조적 타입 시스템과 관련 있다.

export {}; // declare global을 사용하기 위해 외부 모듈로 인식하도록 만듦

declare global {
  interface ObjectConstructor {
    // ObjectConstructor 인터페이스를 확장하여 Object.keys 메서드 타입 덮어쓰기
    keys<T extends object>(o: T): (keyof T)[];
  }
}

const validateOptions = (options: Options) => {
  const keys = Object.keys(options); // (keyof Options)[]
  // ...
};

 

💡 타입스크립트 컴파일러는 export 혹은 import 구문이 없는 파일을 일반 스크립트로 취급한다. declare global을 이용해 전역 참조할 수 있는 선언 코드를 작성하려면 export {} 등을 사용해 외부 모듈로 인식하도록 해야 한다.

 

구조적 타이핑 Structural Typing

---

구조적 타이핑(Structural Typing)은 코드 구조의 관점에서 타입 호환성을 판단하는 방식을 의미한다. 일반적으로 객체 속성 수, 함수 파라미터 수 등이 비교 대상보다 많을 경우, 구조적으로 더 큰 타입이라고 볼 수 있다.

 

아래 예시에서 User 타입은 name, age 속성을 갖는다. 하지만 city 라는 추가 속성을 갖는 userThree 객체를 함수 파라미터로 넘겨도 에러가 발생하지 않는다.

type User = { name: string; age: number };

const saveUser = (user: User) => {};

const userOne = { name: 'One', age: 25 };
saveUser(userOne); // Ok

const userTwo = { name: 'Two' };
saveUser(userTwo); // ts(2345) Error! 'age' 속성이 '{ name: string; }' 형식에 없지만 'User' 형식에서 필수입니다

const userThree = { name: 'Three', age: 35, city: 'Seoul' };
saveUser(userThree); // OK

 

구조적 타입 시스템에선 기본적으로 타입 A가 B의 슈퍼셋인 경우(A는 B의 모든 속성을 포함하고 추가 속성도 가질 때) A를 B에 할당할 수 있다. (공변성, 반공변성과는 별도의 개념)

• 슈퍼셋 A는 서브셋 B에 할당할 수 있다
• 서브셋 B는 슈퍼셋 A에 할당할 수 없다

 

type Super = { name: string; age: number };
type Sub = { name: string };

const aSuper: Super = { name: 'super', age: 25 };
const aSub: Sub = { name: 'sub' };

const a: Sub = aSuper; // OK
const b: Super = aSub; // ts(2741) Error! 'age' 속성이 'Sub' 형식에 없지만 'Super' 형식에서 필수입니다

 

위 같은 특성 때문에 타입스크립트에서 특정 객체 타입 T를 다룰 때 구조적 타이핑 특성에 따라 해당 객체가 타입 T의 프로퍼티를 적어도 하나 이상 포함하고 있는지만 확인할 수 있다.

 

즉, 해당 객체가 정확히 타입 T의 프로퍼티만 갖는지, 아니면 추가적인 프로퍼티도 갖는지 알 수 없다는 말이다. 때문에 Object.keys 메서드는 각 프로퍼티의 정확한 타입 정보가 아닌, 객체 프로퍼티 키를 모두 string으로 처리해서 반환하는 것이다.

 

Object.keys 사용시 주의할 점

---

💡 a ||= b 문법은 ES2021에 도입된 신규 기능으로 a가 falsy이면 b를 a에 할당한다 — 참고 포스팅

 

아래 예시에서 validateUser 함수의 파라미터는 User 객체 타입을 받도록 작성했지만, 구조적 타이핑 특성으로 인해 email 추가 속성을 갖는 객체를 파라미터로 넘길 수 있다. 코드를 실행하면(런타임) validators 객체에 email 메서드가 없으므로 “validate is not a function” 에러가 발생한다.

 

다행히 코드를 실행하지 않더라도(컴파일 시점) Object.keys() 메서드는 항상 string[] 타입을 반환하므로 validators[key] 부분에서 타입 에러가 발생한다. 타입스크립트는 key가 string 타입인 것은 알고 있지만 각 문자열이 validators 객체의 키인지는 알 수 없기 때문에 타입 안정성을 보장할 수 없어서 그런 것.

 

만약 Object.keys() 메서드가 string[]이 아닌 validators 객체의 키 이름을 요소로 갖는 배열 타입을 반환했다면, 아래처럼 추가적인 속성을 가진 객체를 넘겼을 때 컴파일 시점에는 에러를 캐치하지 못하고 런타임 시점에 에러가 발생했을 것이다.

type User = { name: string; password: string };

const validators = {
  name: (name: string) => { ... },
  password: (password: string) => { ... },
};

const validateUser = (user: User) => {
  let error = '';
  const keys = Object.keys(user); // string[]

  for (const key of keys) {
    const validate = validators[key]; // 컴파일 Error! Expression of type 'string' can't be used to index type { ... }
    error ||= validate(user[key]); // 런타임 Error! validate is not a function
  }

  return error;
};

const user = { name: 'John', password: '1q2w3e4r', email: 'john@gmail.com' };
validateUser(user); // email 추가 프로퍼티로 인한 에러는 발생하지 않음

 

위 예시의 타입 에러를 해결하려면 타입가드를 사용해 key가 validators 객체의 키 중 하나임을 알려줘야 한다. 타입가드는 특정 스코프에 있는 타입을 런타임 때 체크하는 방법으로 is, typeof, instanceof 등의 키워드를 활용한다. 아래는 is 키워드를 이용해 타입을 검사하는 예시.

// ...

const isKeyOfValidators = (key: string): key is keyof typeof validators => {
  return key in validators;
};

const validateUser = (user: User) => {
  let error = '';

  const keys = Object.keys(user); // string[]
  for (const key of keys) {
    if (isKeyOfValidators(key)) {
      const validate = validators[key];
      error ||= validate(user[key]);
    }
  }
  return error;
};

 

구조적 타이핑 활용하기 ⭐

---

구조적 타이핑은 많은 유연함을 제공한다. 아래 getKeyboardShortcut 함수는 KeyboardEvent 객체를 파라미터로 받아 단축키 조합을 확인하고 대응하는 문자열을 반환한다.

function getKeyboardShortcut(e: KeyboardEvent) {
  // 참고로 메타 키는 윈도우에서 windows 키, macOS에선 command 키
  if (e.key === 's' && e.metaKey) return 'save';
  if (e.key === 'o' && e.metaKey) return 'open';

  return null;
}

 

위 함수가 예상대로 작동하는지 확인하기 위해 아래처럼 몇 가지 단위 테스트를 작성할 수 있다. 하지만 함수 인자로 넘긴 객체는 KeyboardEvent 타입에 있는 altKey, code 등 37개 속성이 없다는 타입 에러가 발생한다.

expect(getKeyboardShortcut({ key: 's', metaKey: true })).toEqual('save');
expect(getKeyboardShortcut({ key: 'o', metaKey: true })).toEqual('open');
expect(getKeyboardShortcut({ key: 's', metaKey: false })).toEqual(null);

 

 

임시 방편으로 as 키워드를 사용해 타입 단언할 수 있지만 잠재적으로 발생할 수 있는 다른 타입 에러를 놓칠 수 있는 단점이 있다.

getKeyboardShortcut({ key: 's', metaKey: true } as KeyboardEvent);

 

위에서 살펴본 구조적 타이핑 특성을 활용하면 이 문제를 더욱 깔끔하게 해결할 수 있다. 아래처럼 함수 파라미터에 필요한 키보드 이벤트 속성만 KeyboardShortcutEvent 타입으로 정의해두면 타입 에러를 피할 수 있다.

interface KeyboardShortcutEvent {
  key: string;
  metaKey: boolean;
}

function getKeyboardShortcut(e: KeyboardShortcutEvent) {
  // ...
}

 

위처럼 작성하면 getKeyboardShortcut 함수가 KeyboardEvent 타입에 덜 종속적이게 되어 더 다양한 컨텍스트에서 사용할 수 있는 장점도 있다. 아래 코드처럼 모든 KeyboardEvent 프로퍼티를 가지는 이벤트 객체를 넘길 수도 있다. KeyboardEvent 타입이 KeyboardShortcutEvent 타입의 슈퍼셋(더 큰 타입)이기 때문에 37개 프로퍼티를 모두 가지고 있지 않아도 함수 파라미터로 전달할 수 있게 된 것이다.

window.addEventListener('keydown', (e: KeyboardEvent) => {
  const shortcut = getKeyboardShortcut(e); // OK!
  if (shortcut) execShortcut(shortcut);
});

 

레퍼런스

---

Why doesn't TypeScript properly type Object.keys?

 

---

글 수정사항은 노션 페이지에 가장 빠르게 반영됩니다. 링크를 참고해 주세요