模块与声明文件

// ——— Named exports ———
export function add(a: number, b: number): number { return a + b }
export const VERSION = "1.0.0"
export interface MathOp { (a: number, b: number): number }

// ——— Named imports ———
import { add, VERSION } from "./math"
import type { MathOp } from "./math"

// ——— Default export ———
export default class Calculator {
  add(a: number, b: number): number { return a + b }
}

// ——— Default import ———
import Calculator from "./calculator"

// ——— Namespace import（导入全部）———
import * as Math from "./math"
Math.add(1, 2)
Math.VERSION

// ——— Re-export ———
export { add } from "./math"
export { add as sum } from "./math"       // 重命名再导出
export * from "./math"                    // 全部重新导出
export { default as Calc } from "./calc"  // 重新导出 default

// 整行导入仅作为类型使用，编译后完全擦除
import type { User } from "./types"

// 混合 value + inline type import（TS 4.5+）
import { type User, getUser } from "./user"

// type-only re-export
export type { User, Admin } from "./types"

// ✅ 仅类型层面引用，不产生运行时依赖
import type { Config } from "./config"
const c: Config = { ... }

// ❌ 普通 import 即使只用于类型标注，也会引入运行时依赖
import { Config } from "./config"

// 运行时动态导入
const module = await import("./heavy-module")
module.doWork()

// 类型层面：获取模块的完整类型（TS 2.9+）
type MyModule = typeof import("./my-module")
const mod: MyModule = await import("./my-module")

// declare 全局变量
declare const API_URL: string

// declare 全局函数
declare function initialize(config: Config): void

// declare 类
declare class EventEmitter {
  on(event: string, handler: (...args: any[]) => void): this
  emit(event: string, ...args: any[]): boolean
}

// declare 模块
declare module "*.css" {
  const content: Record<string, string>
  export default content
}

// global.d.ts — 注意：文件中不能有 import/export，否则变成模块模式
interface Window {
  myCustomProperty: string
}

declare const __DEV__: boolean

// 文件中有 export，说明是模块模式
export {}

declare global {
  interface Window {
    __INITIAL_STATE__: string
  }
  namespace NodeJS {
    interface ProcessEnv {
      API_KEY: string
      DATABASE_URL: string
    }
  }
  // 扩展内置类型
  interface String {
    toCamelCase(): string
  }
}

// 扩展已有模块的类型（Module Augmentation）
declare module "express" {
  interface Request {
    user?: { id: string; role: string }
  }
}

// 声明通配模块（如非 JS/TS 资源文件）
declare module "*.svg" {
  import type { FunctionComponent, SVGProps } from "react"
  const content: FunctionComponent<SVGProps<SVGSVGElement>>
  export default content
}

declare module "*.png" {
  const src: string
  export default src
}

declare module "*.module.css" {
  const classes: { readonly [key: string]: string }
  export default classes
}

// types/my-lib/index.d.ts
export function doSomething(input: string): Result

export interface Result {
  code: number
  data: unknown
}

export { default as Config } from "./config"

// 如果库导出了多个子路径
export * from "./sub-module"

// package.json
{
  "name": "my-lib",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.mjs",
      "require": "./dist/index.cjs"
    }
  }
}

npm i -D @types/package-name

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@utils/*": ["src/utils/*"],
      "@types/*": ["src/types/*"]
    }
  }
}

import { Button } from "@components/Button"
import { formatDate } from "@utils/date"
import type { User } from "@types/user"

// tsconfig.json 中 path 与 runtime 不一致时会报错
// ✅ 确保 bundler 也配置了相同 alias
// vite.config.ts
export default defineConfig({
  resolve: {
    alias: { "@": "/src" }
  }
})

namespace Validation {
  export interface StringValidator {
    isAcceptable(s: string): boolean
  }

  const lettersRegexp = /^[A-Za-z]+$/

  export class LettersOnlyValidator implements StringValidator {
    isAcceptable(s: string): boolean {
      return lettersRegexp.test(s)
    }
  }
}

// 使用
const validator: Validation.StringValidator =
  new Validation.LettersOnlyValidator()

// ✅ 现代写法：使用 ES module
// validation.ts
const lettersRegexp = /^[A-Za-z]+$/
export class LettersOnlyValidator implements StringValidator {
  isAcceptable(s: string): boolean { return lettersRegexp.test(s) }
}

// ❌ 遗留写法：namespace 增加不必要的嵌套
namespace Validation {
  export class LettersOnlyValidator { ... }
}

/// <reference path="./other.d.ts" />      // 引用其他声明文件
/// <reference types="node" />              // 声明对 @types/node 的依赖
/// <reference lib="es2022" />              // 声明使用的 lib