Type Predicate를 활용해 사내 내장 유틸함수 타입 가드 적용

사내 Core에서 제공되는 내장 유틸 함수 _.vIsEmpty()와 _.vIsNull()은 런타임에서 null-safe 처리를 위해 매우 빈번히 사용되는 함수입니다. 

하지만 이렇게 빈번히 사용되는 함수가 컴파일 시점에선 TypeScript 환경에서 타입 가드 기능을 하지 못한다는 문제점이 있었습니다.

 

이런 문제점에 의구심과 불편함을 느끼며 개선을 해보고자 생각을 했고, 이번 글은 "기존 함수를 뜯어고치지 않고도 Type Guard를 가능하게 만든 경험"을 정리한 개발 기록입니다.

 

이번 경험을 통해 Type Predicate 에 대해 공부할 수 있었고,

타입 가드 문제 해결과 기존 시스템의 개선 의지에 대해 본부장님께도 칭찬 받는 좋은 경험이 됐습니다.😎😚

 

 

 

🪧선수 지식 - Type Guard

 

TypeScript에서 타입 가드(Type Guard)는 런타임 시점에 특정 값의 타입을 좁혀서(Type Narrowing) 컴파일러가 “이 시점에는 이 타입이 확실하다”라고 판단할 수 있게 해주는 문법입니다.

TypeScript는 정적 타입 언어이지만, 런타임에는 타입 정보가 사라집니다.
그래서 if 문이나 typeof, instanceof 등을 이용해 값의 타입을 검사하면, 컴파일러가 그 조건 안에서는 타입을 좁혀줍니다.

 

// 1️⃣ typeof 를 이용한 타입 가드 예시
function printLength(x: string | number) {
  if (typeof x === "string") {
    console.log(x.length);   // ✅ string 으로 좁혀짐
  } else {
    console.log(x.toFixed()); // ✅ number 로 좁혀짐
  }
}

// 2️⃣ instanceof 를 이용한 타입 가드 예시
class Dog { bark() {} }
class Cat { meow() {} }

function makeSound(animal: Dog | Cat) {
  if (animal instanceof Dog) {
    animal.bark();  // ✅ Dog 타입으로 좁혀짐
  } else {
    animal.meow();  // ✅ Cat 타입으로 좁혀짐
  }
}

//3️⃣ in 연산자를 이용한 타입 가드  예시
type User = { name: string };
type Admin = { name: string; role: string };

function printInfo(person: User | Admin) {
  if ("role" in person) {
    console.log(person.role); // ✅ Admin 타입으로 좁혀짐
  } else {
    console.log(person.name); // ✅ User 타입으로 좁혀짐
  }
}

//4️⃣ 간단한 자바스크립트의 “truthy/falsy” 평가를 이용한 간단한 타입 가드 예시
type User = { name: string } | undefined;

function greet(user: User) {
  if (user) {
    // 여기서는 user가 User로 좁혀짐 (undefined 아님)
    console.log("Hello, " + user.name);
  } else {
    console.log("No user");
  }
}

 

타입 가드(Type Guard)는 조건문을 통해 변수의 타입을 좁혀(Type Narrowing) TypeScript 컴파일러가 안전하게 타입 추론을 할 수 있도록 돕는 기능입니다.

 

 

 

 

📍배경 상황

사내 Core에서 제공되는 vIsEmpty()는 값이 비어있는지를 판별하는 내장 유틸 함수입니다.
함수의 타입 시그니처는 다음과 같습니다.

/**
 * @example
 *     true
 *     _.vIsEmpty('undefined'); //=> true
 *     _.vIsEmpty(undefined); //=> true
 *     _.vIsEmpty(null); //=> true
 *     _.vIsEmpty(""); //=> true
 *     _.vIsEmpty([]); //=> true
 *     _.vIsEmpty({}); //=> true
 *
 *     false
 *     _.vIsEmpty("mscorlib"); //=> false
 *     _.vIsEmpty([1,2]); //=> false
 *     _.vIsEmpty(0); //=> false
 *     _.vIsEmpty(1.1235); //=> false
 *     _.vIsEmpty(true); //=> false
 *     _.vIsEmpty(false); //=> false
 */
function vIsEmpty(value: any): boolean;

 

vIsEmpty 함수는 런타임에서는 아주 훌륭합니다.

• undefined, null, 빈 배열, 빈 객체까지 체크
• 서버 사이드 런타임에서 NPE 방지 가드 역할

하지만 TypeScript 환경에서는 전혀 타입을 좁혀주지 못하는 한계점이 있습니다.

 

 

따라서 아래와 같이 사용하여 타입 검사를 피해야만 했습니다.

// 1️⃣ JS의 “truthy/falsy” 평가를 한번 더 이용하여 타입가드하기 
if (!_.vIsEmpty(request.additional_info)) {
	if (request.additional_info) {
		const a = request.additional_info.a;
	}
}

// 2️⃣ Non-null 단언 연산자 사용하기(!)
if (!_.vIsEmpty(request.additional_info)) {
	const a = request.additional_info!.a;
}

 

 

1번 방식은 조건문을 한번 더 사용하게 되면서 코드 가독성도 떨어지고, 비효율적으로 보입니다.

 

2번 방식은 런타임상에선  null-safe 하지만, 컴파일 시점에서 보기에는 null-safe 하지 않다고 느꼈습니다.(개발자만 앎, 컴퓨터는 모름.) 실무에서 절대적이고 강력한 무기인 " ! "는,컴파일러의 타입검증을 우회하는 것일 뿐, 해결책이 아닙니다.

 

 

"아 그럼 _.vIsEmpty 쓰지말고 모두 if(객체) 로 써야 겠다" 라고 생각했습니다. 그러나 이것 또한 좋은 해답은 아니었습니다.

vIsEmpty 를 못사용하게 되면서, vIsEmpty 함수가 제공해주는 여러 검사를 활용하지 못하기 때문입니다.

 

 

결국 찜찜하지만, 2번방식을 택해서 사용을 했습니다. (그래도 런타임시점엔 null-safe 한 건 맞으니깐)

이런 불편함을 계속 겪으며, vIsEmpty 함수가 원래 제공하던 기능은 유지한 채 타입 가드가 되게 리팩토링을 시도하였습니다.

 

 

 

✨문제 해결

설정파일 수정?

첫번째로 Core 에서 제공하는 내장 함수를 수정하지 않고, 설정파일 등 외부 요소를 변경하여 타입 가드가 될 수 있게 할 수 있나 고민해 봤습니다.

 

tsconfig.json 파일을 수정해 가능할까 살펴봤지만, 컴파일러가 특정 함수 반환값을 타입가드로 인식하도록 만드는 설정은 존재하지 않았습니다.

 

TypeScript compiler(이하: tsc) 오픈 소스를 수정하면 가능할 것도 같았지만, 배보다 배꼽이 더 큰 격이라 비효율적이라 생각했습니다.

 

함수 리팩토링?

외부 요소를 수정하여 가능한 점은 못찾았기에 내장 유틸 함수를 리팩토링하여 가능하게 해보자 생각했습니다.

 

vIsEmpty 함수는 반환값이 boolean 입니다. 반환타입이 boolean 이기 때문에 타입가드가 되지 않습니다.

왜냐하면 TS는 “boolean을 반환하는 함수”( 타입 정보를 제공하지 않음) 를 타입가드로 인정하지 않기 때문입니다.
즉, boolean만을 반환하는 함수는 타입 추론에 아무 힌트도 주지 않는다는 뜻입니다. 

 

 

그래서 vIsEmpty 함수 기능을 런타임시점에서 보장하면서도 컴파일 시점에 boolean 만이 아닌 타입 정보도 제공할 수 있는 방안이 있는지 살펴 보았습니다.

 

 

Type predicate

문제 해결 방법은 바로 Type predicate 입니다.

Type predicate는 함수의 반환값에 매개변수 is 특정 타입 형태의 타입 단언(type assertion)을 사용하여,
해당 함수가 특정 타입을 반환할 때 타입스크립트가 변수의 타입을 더 구체적인 타입으로 추론(type narrowing)하도록 돕는 사용자 정의 타입 가드입니다. (사용법 : parameterName is Type)

아래 예시가 있습니다.

function isNumber(v: any): v is number {
  return typeof v === "number";
}

 

isNumber 함수 결과가 true일 때,
→ TS는 “이 시점 이후 v는 number 타입”으로 좁혀서 추론합니다.

isNumber 함수 결과가 false일 때,
→ v는 “number가 아닌 타입”으로 좁혀집니다.

 

TypeScript의 Type predicate (v is Something)는 런타임에서는 boolean, 컴파일 타임에서는 타입 정보를 전달합니다.

Type predicate 는 JS 런타임에서 boolean을 반환하는 함수여야 하고,

TypeScript 타입 시스템에서 Type predicate 는 parameter is Type 형태의 타입 정보를 함께 제공하는 것입니다.

TypeScript의 타입 가드는 “분기 조건”을 근거로 타입을 좁히는(narrowing) 시스템입니다.

 

 

 

Type predicate 개념을 vIsEmpty 함수에도 적용했습니다.

// vIsEmpty가 true면 null | undefined 라고 좁힘
function vIsEmpty<T>(v: T | null | undefined): v is null | undefined;

 

vIsEmpty 함수가 true를 반환하면 v는 null 또는 undefined 타입이 됩니다.

즉, vIsEmpty 결과값이 true면 v가 null 또는 undefined, false면 NonNullable이라는 뜻입니다.


타입가드 함수의 반환값 true/false는 컴파일러에게 타입 정보를 전달하는 용도로 사용될 수 있습니다.

겉으로 보면 vIsEmpty의 반환 타입이 v is null | undefined라서 boolean이 아닌 것처럼 보이지만,

실제로는 “boolean 값 + 타입정보 힌트” 두 역할을 동시에 합니다.

 

다시 말해 위 함수는 런타임 시점엔 true/false,
컴파일 시점엔 "true → v"는 null | undefined,
"false → v"는 NonNullable 로 해석됩니다.

정리하자면 boolean을 반환하는 함수이지만, TS 컴파일러 입장에서는 “boolean + 타입 힌트”가 섞여 있는 셈입니다.

결국 vIsEmpty는 boolean을 반환하고, TS는 그 결과를 이용해 변수의 타입을 좁혀주는 함수가 되게 됩니다.

 

이런 리팩토링을 통해 Core 내장 함수의 구현부를 수정하지 않고도 시그니처 변경을 통해 타입 가드까지 가능하게 해줄 수 있었습니다.

 

 

 

🧪검증

함수명을 구분하기 위해 오버로딩 하지않고 vIsEmpty2로 만들어 테스트 파일을 만들어 검증을 해보았습니다.

// vIsEmpty2가 true면 null | undefined 라고 좁힘
function vIsEmpty2<T>(v: T | null | undefined): v is null | undefined;

 

//isEmpty.spec.ts
(function test_vIsEmpty2() {

    // true cases
    Assert.equal(_.vIsEmpty2("undefined"), true, "_.vIsEmpty2('undefined')");
    Assert.equal(_.vIsEmpty2(undefined), true, "_.vIsEmpty2(undefined)");
    Assert.equal(_.vIsEmpty2(null), true, "_.vIsEmpty2(null)");
    Assert.equal(_.vIsEmpty2(""), true, "_.vIsEmpty2('')");
    Assert.equal(_.vIsEmpty2([]), true, "_.vIsEmpty2([])");
    Assert.equal(_.vIsEmpty2({}), true, "_.vIsEmpty2({})");

    // false cases
    Assert.equal(_.vIsEmpty2("내가 제일 잘나가"), false, "_.vIsEmpty2('내가 제일 잘나가')");
    Assert.equal(_.vIsEmpty2([1, 2]), false, "_.vIsEmpty2([1, 2])");
    Assert.equal(_.vIsEmpty2(0), false, "_.vIsEmpty2(0)");
    Assert.equal(_.vIsEmpty2(1.1235), false, "_.vIsEmpty2(1.1235)");
    Assert.equal(_.vIsEmpty2(true), false, "_.vIsEmpty2(true)");
    Assert.equal(_.vIsEmpty2(false), false, "_.vIsEmpty2(false)");

    const test_data = { a: 'abc', b: 1 };
    Assert.equal(_.vIsEmpty2(test_data), false, "_.vIsEmpty2(test_data)");
    Assert.equal(_.vIsEmpty2(test_data.a), false, "_.vIsEmpty2(test_data.a)");
    test_vIsEmpty3(test_data);

    const test_data2 = { a: undefined, b: 1 };
    test_vIsEmpty3(test_data2);

    // 타입가드 테스트 (컴파일 타임 확인용)
    const maybeValue: string | null = Math.random() > 0.5 ? "HELLO" : null;

    if (!_.vIsEmpty2(maybeValue)) {
        // 여기서 maybeValue는 NonNullable<string | null> → string 으로 좁혀짐
        const upper = maybeValue.toLowerCase(); // 컴파일 오류 없어야 함
        Assert.equal(typeof upper, "string", "type guard narrowing check");
    } else {
        Assert.equal(maybeValue == null, true, "vIsEmpty2(true) -> null or undefined");
    }
    console.log('type guard test end')
})();

//기존 vIsEmpty와 비교
function test_vIsEmpty3(abc: { a?: string; b: number }) {
    // a는 string 또는 undefined
    if (!_.vIsEmpty2(abc.a)) { // vIsEmpty 는 컴파일 오류 생기는 걸 확인함. vIsEmpty2 를 붙이니 컴파일 오류 사라짐. 타입 가드 잘되는 걸 확인.
        // 여기서 abc.a는 string으로 좁혀짐
        const upper = abc.a.toUpperCase();
        Assert.equal(typeof upper, "string", "type guard narrowing check");
        Assert.equal(upper, "ABC", "result check");
    } else {
        // 여기서 abc.a는 undefined로 좁혀짐
        Assert.equal(abc.a === undefined, true, "vIsEmpty2(true) -> undefined");
    }
};

 

 

 

🤔마무리하며

test case 도 모두 통과하면서 vIsEmpty2() 함수가 실질적으로 런타임시에 boolean 값을 반환하면서도 타입 가드가 잘 작동하는 걸 확인하였습니다.
추가적으로 vIsEmpty() 와 비슷한 함수 vIsNull() 도 적용할 수 있다고 판단해 Type predicate 을 적용해 봤습니다.

 

이번 경험은 단순히 “깔끔한 코드”를 만드는 것이 아니라, 런타임 안정성과 타입 시스템을 통합적으로 바라보는 관점을 심어줬습니다.

또한 Core 내장 유틸리티 함수들은 만인이 사용하지만 개선할 생각을 하지 못하는 함수들인데, 문제점을 인식하고 이를 개선하려고 했다는 스스로에게 “조금 더 나은 코드를 만들어갈 수 있는 개발자”라는 확신을 줄 수 있었던 경험이었습니다.

 

리팩토링을 통해 내장 함수의 타입 시스템과 런타임 사이의 간극을 줄이고, 사내 동료 개발자 분들이 더 안전하고 명확한 코드를 작성할 수 있는 방안을 제공했다는 점에서 큰 의미가 있었습니다.

앞으로도 기존의 레거시를 당연하게 받아들이지 않고, 작은 불편도 개선하는 시도를 계속해 나가야겠다고 다짐하게 됐습니다.