타입 선언 파일 작성 및 사용

// 이 파일은 CommonJS 모듈로 작성되었다고 가정합니다.

/**
 * 주어진 문자열의 첫 글자를 대문자로 변환합니다.
 * @param {string} str - 원본 문자열
 * @returns {string} 첫 글자가 대문자로 변환된 문자열
 */
function capitalize(str) {
  if (typeof str !== 'string' || str.length === 0) {
    return '';
  }
  return str.charAt(0).toUpperCase() + str.slice(1);
}

/**
 * 주어진 문자열이 비어있는지 (null, undefined, 빈 문자열) 확인합니다.
 * @param {string | null | undefined} str - 확인할 문자열
 * @returns {boolean} 비어있으면 true, 아니면 false
 */
function isEmpty(str) {
  return str === null || str === undefined || str.length === 0;
}

module.exports = {
  capitalize,
  isEmpty
};

// 이 파일은 'StringUtils'라는 CommonJS 모듈에 대한 타입 선언 파일입니다.
// declare module '모듈 이름' { ... } 구문을 사용합니다.
declare module './StringUtils' {
  /**
   * 주어진 문자열의 첫 글자를 대문자로 변환합니다.
   * @param str 원본 문자열
   * @returns 첫 글자가 대문자로 변환된 문자열
   */
  export function capitalize(str: string): string;

  /**
   * 주어진 문자열이 비어있는지 (null, undefined, 빈 문자열) 확인합니다.
   * @param str 확인할 문자열
   * @returns 비어있으면 true, 아니면 false
   */
  export function isEmpty(str: string | null | undefined): boolean;

  // 만약 기본 내보내기가 있다면 아래와 같이 선언할 수 있습니다.
  // export default class StringUtil { ... }
}

// 참고: 만약 이 js 파일이 ES 모듈처럼 동작한다면, 다음과 같이 직접 export를 선언합니다.
// export function capitalize(str: string): string;
// export function isEmpty(str: string | null | undefined): boolean;

import { capitalize, isEmpty } from './js/StringUtils'; // .d.ts 파일에 의해 타입 정보가 제공됨

const myString = "hello world";
const capitalizedString = capitalize(myString);
console.log(capitalizedString); // "Hello world"

const emptyString = "";
const isStringEmpty = isEmpty(emptyString);
console.log(`"${emptyString}" is empty: ${isStringEmpty}`); // "is empty: true"

const nullString: string | null = null;
const isNullEmpty = isEmpty(nullString);
console.log(`null is empty: ${isNullEmpty}`); // "is empty: true"

// 잘못된 타입의 인자 전달 시 컴파일 오류 발생
// const num = 123;
// const capitalizedNum = capitalize(num); // Error: 'number' 형식의 인수는 'string' 형식의 매개 변수에 할당될 수 없습니다.

// 전역 변수 선언
declare var MY_APP_NAME: string;
declare const VERSION_NUMBER: number;

// 전역 함수 선언
declare function logActivity(message: string, level: 'info' | 'warn' | 'error'): void;

// 전역 인터페이스 확장 (예: Window 객체에 새로운 속성 추가)
interface Window {
  myGlobalData?: {
    userId: number;
    sessionId: string;
  };
}

// 또는 declare namespace를 사용한 전역 객체 선언
declare namespace Analytics {
  function trackEvent(eventName: string, data?: object): void;
  function setUserId(id: string): void;
}

// 타입스크립트 컴파일러는 global.d.ts를 자동으로 인식합니다.
console.log(`Application Name: ${MY_APP_NAME}`);
console.log(`Version: ${VERSION_NUMBER}`);

logActivity("User logged in", "info");

if (window.myGlobalData) {
  console.log(`User ID: ${window.myGlobalData.userId}`);
}

Analytics.trackEvent("page_view", { path: "/dashboard" });

// logActivity("Invalid level", "debug"); // Error: 'debug' 형식은 '"info" | "warn" | "error"' 형식에 할당될 수 없습니다.

{
  "compilerOptions": {
    "declaration": true,      // .d.ts 파일 자동 생성
    "outDir": "./dist",       // .js 및 .d.ts 파일 출력 디렉토리
    // ...
  }
}

{
  "name": "my-awesome-library",
  "version": "1.0.0",
  "main": "dist/index.js", // 실제 JS 구현 파일
  "types": "dist/index.d.ts", // 타입 정의 파일
  "files": [
    "dist" // npm publish 시 dist 폴더 포함
  ]
}