본문으로 건너뛰기
개발 머꼬
개발 노트JavaScript

TS18047 is possibly 'null' 해결 방법, 느낌표로 지웠더니 런타임에서 터진 이유

hohyeon.dev9

문제 발생

JavaScript로 돌아가던 관리자 페이지를 TypeScript로 옮기는 작업이었습니다. 파일 확장자만 .ts로 바꿨을 뿐인데 빌드가 에러 범벅이 됐습니다. 런타임에서는 몇 달째 멀쩡히 돌던 코드였습니다.

bad.ts(2,1): error TS18047: 'btn' is possibly 'null'.
bad.ts(6,26): error TS18048: 'u.email' is possibly 'undefined'.
bad.ts(13,10): error TS18048: 'found' is possibly 'undefined'.
bad.ts(17,7): error TS2322: Type 'string | undefined' is not assignable to type 'string'.
  Type 'undefined' is not assignable to type 'string'.

문제가 된 줄은 전부 평범했습니다.

const btn = document.getElementById("save");
btn.addEventListener("click", () => {});          // TS18047

interface User { name: string; email?: string }
function send(u: User) {
  return u.email.split("@")[1];                   // TS18048
}

function nameOf(id: string) {
  const found = users.find((u) => u.name === id);
  return found.name;                              // TS18048
}

const key: string = env.API_KEY;                  // TS2322

급한 마음에 tsconfig.json에서 strictNullChecks를 끄자 에러가 전부 사라졌습니다. 그 설정으로 한 달쯤 지나서, 운영 화면에서 Cannot read properties of undefined 에러가 올라왔습니다. 위 found.name 줄이었습니다. 이 글의 재현은 TypeScript 6.0에서 했습니다.

원인 분석

네 가지 에러 코드가 전부 같은 말을 합니다. TS18047은 null일 수 있다, TS18048은 undefined일 수 있다, TS2322는 string | undefined를 string 자리에 넣을 수 없다는 뜻입니다. 번호만 다를 뿐 "이 값이 없을 수도 있는데 있다고 치고 쓰고 있다"는 지적입니다.

각 줄이 왜 "없을 수도 있는" 값인지는 타입에 이미 적혀 있습니다.

  • document.getElementById는 HTMLElement | null을 돌려줍니다. 그런 id가 없으면 null입니다.
  • email?: string의 물음표는 "이 필드는 없을 수도 있다"는 선언입니다. 타입이 string | undefined가 됩니다.
  • Array.prototype.find는 조건에 맞는 항목이 없으면 undefined를 돌려줍니다.
  • 환경변수는 string | undefined입니다. 그 이름의 변수가 설정돼 있지 않을 수 있습니다.

strictNullChecks를 끄면 타입이 아니라 검사가 사라집니다. TypeScript 공식 설정 문서가 이걸 분명히 적습니다. strictNullChecks가 false면 null과 undefined가 언어에서 사실상 무시되고, 이는 런타임에 예상치 못한 에러로 이어질 수 있다고요. true면 null과 undefined가 각자의 타입을 가지며, 구체적인 값이 필요한 자리에 쓰려 하면 타입 에러가 난다고 설명합니다.

문서가 드는 예시가 하필 제가 겪은 그 상황입니다. users.find는 실제로 사용자를 찾는다는 보장이 없는데도 찾은 것처럼 코드를 쓸 수 있고, strictNullChecks를 켜면 "존재를 보장하지 않은 채 쓰려 한다"는 에러가 난다고요. 직접 확인해 보니 같은 파일이 strictNullChecks: false에서는 에러 0건으로 통과했습니다. 컴파일러가 조용해졌을 뿐, find가 undefined를 돌려주는 사실은 그대로였던 겁니다.

느낌표(!)도 검사만 지웁니다. 에러를 빨리 없애려고 found!.name처럼 쓰는 경우가 많습니다. TypeScript 핸드북은 이 연산자를 명시적인 검사 없이 타입에서 null과 undefined를 제거하는 문법이라고 설명하면서, 다른 타입 단언과 마찬가지로 런타임 동작을 바꾸지 않으므로 값이 null이나 undefined일 수 없다고 확신할 때만 쓰라고 못 박습니다. 재현에서 !를 붙인 코드는 컴파일을 통과했고, 같은 로직을 Node에서 실행하자 그대로 터졌습니다.

TypeError: Cannot read properties of undefined (reading 'name')

해결 방안

  1. 조건문으로 좁히고(narrowing) 나서 씁니다. TypeScript 핸드북이 narrowing이라 부르는 기본 해법입니다. if로 한 번 확인하면 그 블록 안에서 타입이 자동으로 좁혀집니다.
const btn = document.getElementById("save");
if (btn) btn.addEventListener("click", () => {});

값이 없을 때 더 진행할 이유가 없다면 이른 반환이 읽기 좋습니다.

function send(u: User) {
  if (!u.email) throw new Error("email 없음");
  return u.email.split("@")[1];   // 여기서는 string으로 좁혀져 있습니다
}
  1. 값이 없어도 되는 경우엔 ?.와 ??를 씁니다. 없으면 없는 대로 흘려보내도 되는 자리에는 옵셔널 체이닝과 널 병합 연산자가 더 짧습니다.
function nameOf(id: string) {
  const found = users.find((u) => u.name === id);
  return found?.name ?? "(없음)";
}

const key: string = env.API_KEY ?? "";

??는 ||와 다릅니다. ||는 빈 문자열과 0까지 기본값으로 바꿔 버리지만, ??는 null과 undefined일 때만 오른쪽 값을 씁니다. 포트 번호나 수량처럼 0이 유효한 값이면 이 차이가 버그가 됩니다.

  1. !는 "컴파일러보다 내가 더 안다"가 사실일 때만 씁니다. 핸드북의 경고 그대로입니다. 쓸 자리가 있다면 값이 반드시 존재한다는 근거가 코드 바깥에 있는 경우입니다. 예를 들어 바로 위에서 appendChild로 넣은 요소를 다시 조회하는 경우입니다. 반대로 find의 결과나 환경변수처럼 없을 수 있는 게 정상인 값에는 쓰면 안 됩니다. 꼭 필요하면 ! 대신 그 자리에서 에러를 던지는 쪽이 낫습니다. 어차피 터질 거라면 원인을 알 수 있는 메시지로 터지는 게 낫습니다.
function required(name: string): string {
  const v = env[name];
  if (v === undefined) throw new Error(`환경변수 ${name}가 없습니다`);
  return v;
}
const key = required("API_KEY");
  1. 배열을 거를 때는 filter(Boolean) 대신 타입 가드를 씁니다. 흔히 쓰는 filter(Boolean)은 런타임에는 undefined를 걸러 주지만 타입은 그대로입니다. 재현해 보니 이렇게 났습니다.
filt.ts(2,7): error TS2322: Type '(string | undefined)[]' is not assignable to type 'string[]'.

핸드북이 소개하는 사용자 정의 타입 가드를 쓰면 타입까지 좁혀집니다. 반환 타입을 매개변수 is 타입 형태로 적는 방식입니다.

const b: string[] = list.filter((x): x is string => Boolean(x));

객체 단위로도 같은 방법을 씁니다. 아래 hasEmail을 통과한 배열은 email이 string으로 확정됩니다.

function hasEmail(u: User): u is User & { email: string } {
  return typeof u.email === "string";
}
list.filter(hasEmail).map((u) => u.email.split("@")[1]);   // 에러 없음
  1. 좁히기가 풀리는 자리를 압니다. if로 확인했는데도 같은 에러가 나는 경우가 있습니다. 콜백 안입니다.
if (box.value) {
  setTimeout(() => { log(box.value.toUpperCase()); }, 0);   // TS18048
}

콜백은 나중에 실행되니, 그 사이에 box.value가 바뀌지 않는다고 TypeScript가 보장할 수 없습니다. 지역 변수로 한 번 받아 두면 해결됩니다. 그 변수는 아무도 바꿀 수 없기 때문입니다.

const v = box.value;
if (v) {
  setTimeout(() => { log(v.toUpperCase()); }, 0);   // 통과
}

참고로 await 뒤에서는 좁히기가 유지됐습니다. 콜백 함수 경계를 넘을 때만 풀립니다.

마지막으로, 한 단계 더 엄격하게 가고 싶다면 noUncheckedIndexedAccess가 있습니다. 설정 문서에 따르면 이 옵션을 켜면 인덱스 시그니처로 접근한 필드에 undefined가 추가됩니다. 기본 설정에서는 arr[10]이 string으로 통과하지만, 이 옵션을 켜면 string | undefined가 되어 검사를 강제합니다. 배열 인덱스 접근이 많은 코드라면 켜 두면 사고가 줄어듭니다.

공식 문서

마지막 수정

좋아요북마크

댓글0

아직 댓글이 없어요. 첫 댓글을 남겨 보세요.