jQuery 타입 분석하기

Query는 점차 사용이 줄어들고 있지만 여전히 레거시 코드나 간단한 DOM 조작 등에서 자주 볼 수 있는 라이브러리다. 이번 글에서는 jQuery 라이브러리의 타입 선언 파일을 직접 분석하면서, 타입스크립트의 강력한 타입 시스템이 어떻게 외부 라이브러리를 설명하고 지원하는지를 배워보자. 

 

jQuery와 타입 선언 설치

$ npm i jquery@3.6.3 @types/jquery@3.5.16

 

• jquery: 실제 구현 코드
• @types/jquery: 타입 선언 파일 (.d.ts)

jQuery는 자체적으로 타입스크립트를 지원하지 않기 때문에 @types/jquery 패키지를 추가로 설치해야 한다.

타입 선언 파일 진입점 확인

node_modules/@types/jquery/package.json에 다음이 명시되어 있다:

 

"types": "index.d.ts"

 

따라서 index.d.ts 파일이 타입 선언의 진입점(entry point) 이다. 

/// <reference path="JQueryStatic.d.ts" />
/// <reference path="JQuery.d.ts" /> ...

 

• 각 파일은 jQuery의 주요 타입 인터페이스들 ($, jQuery, 인스턴스 메서드 등)을 정의한다.
• export = jQuery는 CommonJS 형식의 기본 내보내기를 의미하며 import $ = require("jquery") 식으로 사용할 수 있게 한다. 

$ 함수 분석

$("p").removeClass("myClass noClass").addClass("yourClass");

 

$의 정의 위치

declare const $: JQueryStatic;

 

JQueryStatic 인터페이스 내부 오버로딩 예시

<TElement extends HTMLElement = HTMLElement>(
  selector: JQuery.Selector, context?: Element | Document | JQuery
): JQuery<TElement>;

 

• $는 여러 오버로딩 중 적절한 것을 자동 선택한다. 
• "p"는 JQuery.Selector → type Selector = string → string 타입으로 매칭.

JQuery<TElement> 타입과 메서드 체이닝

.removeClass("myClass noClass")
.addClass("yourClass")

 

• JQuery<T>는 jQuery 인스턴스 타입이다.
• 메서드들의 반환 타입은 모두 this → 체이닝 가능.

예:

interface JQuery<TElement> {
  removeClass(name?: string | string[]): this;
  addClass(name: string | string[]): this;
}

 

• 타입 별칭 JQuery.TypeOrArray<T> = T | T[] 덕분에 "class1 class2"나 ["class1", "class2"] 모두 허용된다.

선택자 배열 처리

$(["p", "t"]).text("hello");

 

문자열 배열도 $의 오버로딩 중 하나에 대응된다.

<T>(element_elementArray: T | ArrayLike<T>): JQuery<T>;

 

• ["p", "t"]는 ArrayLike<string>으로 취급 가능.
• .text("hello")는 string | number | boolean | ((...) => string | number | boolean)을 받음.

콜백 함수 타입

const tag = $("ul li").addClass((index) => `item-${index}`);

 

addClass는 다음과 같은 오버로딩을 포함:

addClass(fn: (this: TElement, index: number, className: string) => string): this;

 

• 콜백에서 this는 TElement (여기서는 HTMLElement).

$(this)와 html 메서드

$(tag).html(function(i: number) {
  return $(this).data('name') + '입니다';
});

 

 

• this는 HTMLElement → $의 element_elementArray 오버로딩에 대응.
• html 메서드는 다음 형태를 가짐:

html(fn: (this: TElement, index: number, oldHtml: string) => string): this;

 

 

• data(key: string): any이므로 any + string은 string이 되어 html의 반환값 타입인 JQuery.htmlString에 적합.

타입 별칭과 네임스페이스의 역할

namespace JQuery {
  type htmlString = string;
}

 

• 단순한 string이지만 의미를 명확히 하려고 별칭과 네임스페이스를 사용.
• 같은 이름의 타입이 다른 라이브러리에 있을 경우 충돌을 방지.

정리: 타입 선언 분석 흐름

분석 순서	확인 위치
$ 정의	misc.d.ts → JQueryStatic
오버로딩 선택	JQueryStatic.d.ts
htmlString 정의	JQuery.htmlString = string
반환 타입 추적	JQuery<TElement>
메서드 확인	JQuery.d.ts 내 개별 메서드들
this 처리	각 콜백 함수 내의 this 타입
배열/Element 처리	element_elementArray 오버로딩 사용

 

• 외부 타입 선언(.d.ts) 파일 구조 이해
• 오버로딩 기반 타입 추론 흐름 따라가기
• this, T, 제네릭, 네임스페이스의 활용
• 타입스크립트가 어떻게 jQuery의 API 사용을 타입 수준에서 보장하는지 확인