类型声明与命名空间

// interface 声明
interface User {
    name: string;
    age: number;
}
 
// type 声明
type ID = string | number;
 
// class 声明（class 既是值也是类型）
class Person {
    name: string;
    age: number;
}
 
// enum 声明（enum 既是值也是类型）
enum Direction {
    Up,
    Down,
    Left,
    Right
}

// 声明全局变量
declare var jQuery: (selector: string) => HTMLElement;
 
// 声明全局函数
declare function greet(name: string): void;
 
// 声明全局类
declare class Animal {
    name: string;
    constructor(name: string);
    speak(): void;
}
 
// 声明模块
declare module 'lodash' {
    export function debounce<T extends (...args: any[]) => any>(
        func: T,
        wait?: number
    ): T;
}
 
// 声明文件（.d.ts）
// 如 jquery.d.ts
declare module 'jquery' {
    export default function jQuery(selector: string): HTMLElement;
}

# 安装 jQuery 的类型声明
npm install @types/jquery --save-dev
 
# 安装 Node.js 的类型声明
npm install @types/node --save-dev
 
# 安装 Express 的类型声明
npm install @types/express --save-dev

// tsconfig.json 中可配置加载哪些内置声明
{
    "compilerOptions": {
        "lib": ["ES2020", "DOM"],  // 加载 ES2020 + DOM API 类型
        // 不设置 lib 时，target 为 ES5 则默认加载 ES5 + DOM
        // target 为 ES6+ 则默认加载对应版本 + DOM
    }
}

// @ts-ignore
const name: string = 599

// @ts-expect-error
const name: string = 599
 
// @ts-expect-error 错误使用此指令，报错
const age: number = 599

// 场景：实际存在类型错误
// @ts-ignore       ✅ 正常工作，错误被忽略
// @ts-expect-error ✅ 正常工作，错误被忽略
const wrong: string = 123
 
// 场景：不存在类型错误
// @ts-ignore       ✅ 正常工作（但这是危险的）
// @ts-expect-error ❌ 报错：无意义的 expect-error 指令
const correct: number = 123

// @ts-nocheck 以下代码均不会抛出错误
const name: string = 599
const age: number = "linbudu"

// JavaScript 文件
let myAge = 18
 
// 使用 JSDoc 标注变量类型
/** @type {string} */
let myName
 
class Foo {
  prop = 599
}

let myAge = 18
myAge = "90" // 与初始值类型不同
 
/** @type {string} */
let myName
myName = 599 // 与 JSDoc 标注类型不同

// @ts-check
/** @type {string} */
const myName = 599 // 报错！
 
let myAge = 18
myAge = "200" // 报错！

// @ts-check
/** @type {string} */
// @ts-expect-error
const myName = 599 // OK
 
let myAge = 18
// @ts-expect-error
myAge = "200" // OK

// ❌ 错误：使用 ts-ignore 掩盖问题
// @ts-ignore
someFunction(wrongArgument)
 
// ❌ 错误：长期保留 expect-error 而不修复
// @ts-expect-error TODO: 修复这个类型问题
legacyCode()
 
// ✅ 正确：明确标注原因和后续计划
// @ts-expect-error 第三方库类型定义缺失，已提 issue #123
externalLibrary.untypedMethod()

// 声明全局变量
declare var f1: () => void
 
// 声明接口
declare interface Foo {
  prop: string
}
 
// 声明函数
declare function foo(input: Foo): Foo
 
// 声明类
declare class Foo {}

// 直接使用声明的类型
declare let otherProp: Foo["prop"]

// × 不允许在环境上下文中使用初始值
declare let result = foo();
 
// √ 正确：只声明类型，不赋值
declare let result: ReturnType<typeof foo>;

{
  "compilerOptions": {
    "declaration": true,
    "declarationMap": true,
    "outDir": "./dist"
  }
}

// source.ts
const handler = (input: string): boolean => {
  return input.length > 5
}
 
interface Foo {
  name: string
  age: number
}
 
const foo: Foo = {
  name: "林不渡",
  age: 18
}
 
class FooCls {
  prop!: string
}

// source.d.ts
declare const handler: (input: string) => boolean
 
interface Foo {
  name: string
  age: number
}
 
declare const foo: Foo
 
declare class FooCls {
  prop: string
}

┌─────────────────────────────────────────────────────────────┐
│                    类型声明文件加载顺序                        │
├─────────────────────────────────────────────────────────────┤
│  1. node_modules/@types/     ← DefinitelyTyped 社区类型      │
│  2. 项目内的 .d.ts 文件       ← 自定义类型声明                │
│  3. tsconfig.json 指定文件   ← 通过 include/files 配置       │
│  4. 内置 lib.*.d.ts          ← TypeScript 内置类型           │
└─────────────────────────────────────────────────────────────┘

// custom-declarations.d.ts
declare module "some-old-package" {
  export function handler(): boolean
  export const version: string
}
 
// 使用
import { handler, version } from "some-old-package"
 
const result = handler() // 类型为 boolean
const ver = version // 类型为 string

declare module "another-package" {
  const handler: () => boolean
  export default handler
}
 
// 使用
import bar from "another-package"
bar() // 类型为 () => boolean

declare module "specific-package" {
  export interface Config {
    apiKey: string
    timeout?: number
  }
  export function init(config: Config): void
}

// 将模块声明为 any 类型，适用于快速原型开发
declare module "legacy-package"

// images.d.ts
declare module "*.png" {
  const src: string
  export default src
}
 
declare module "*.jpg" {
  const src: string
  export default src
}
 
declare module "*.svg" {
  const content: string
  export default content
}
 
// 使用
import logo from "./logo.png"
import icon from "./icon.svg"
 
const img: HTMLImageElement = document.createElement("img")
img.src = logo // 类型安全

// styles.d.ts
declare module '*.css' {
  const styles: { [className: string]: string };
  export default styles;
}
 
declare module '*.module.css' {
  const classes: { [className: string]: string };
  export default classes;
}
 
declare module '*.scss' {
  const styles: { [className: string]: string };
  export default styles;
}
 
// 使用
import styles from './Button.module.css';
import './global.css';
 
<button className={styles.primary}>Click me</button>

// assets.d.ts
declare module "*.md" {
  const content: string
  export default content
}
 
declare module "*.json" {
  const value: any
  export default value
}
 
declare module "*.txt" {
  const content: string
  export default content
}
 
declare module "*.pdf" {
  const url: string
  export default url
}
 
// 使用
import readme from "./README.md"
import config from "./config.json"

// global.d.ts
interface Window {
  errorReporter: (error: Error) => void
  userTracker: (event: string, data?: any) => Promise<void>
  customConfig: {
    apiUrl: string
    version: string
  }
}
 
// 使用
window.errorReporter(new Error("Something went wrong"))
window.userTracker("click", { button: "submit" })
console.log(window.customConfig.apiUrl)

// global.d.ts
declare namespace NodeJS {
  interface Global {
    myGlobalVar: string
  }
}
 
// 使用
global.myGlobalVar = "value"

// 扩展 Express 的 Request 接口
declare module "express" {
  interface Request {
    user?: {
      id: string
      name: string
    }
  }
}
 
// 使用
import { Request, Response } from "express"
 
app.get("/profile", (req: Request, res: Response) => {
  console.log(req.user?.name)
})

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./custom-types"],
    "types": ["node", "react", "jest"]
  }
}

// @types/node - 使用 declare module
declare module "fs" {
  export function readFileSync(path: string, encoding: string): string
}
 
// @types/react - 使用 declare namespace
declare namespace React {
  function useState<S>(initialState: S): [S, Dispatch<SetStateAction<S>>]
}

/// <reference path="..." />   // 引用其他声明文件
/// <reference types="..." />  // 引用 @types 包
/// <reference lib="..." />    // 引用内置库

// types/utils.d.ts
interface Utils {
  format(input: string): string
}
 
// types/main.d.ts
/// <reference path="./utils.d.ts" />
 
declare const utils: Utils

/// <reference types="node" />
 
declare function readConfig(): Buffer
 
/// <reference types="react" />
 
declare const Component: React.FC

/// <reference lib="es2020.promise" />
 
declare function asyncOperation(): Promise<void>
 
/// <reference lib="dom" />
 
declare function getElement(): HTMLElement

// ❌ 错误：指令前不能有其他代码
import { Foo } from "./foo"
/// <reference path="./types.d.ts" />
 
// ✅ 正确：指令必须在文件最顶部
/// <reference path="./types.d.ts" />
import { Foo } from "./foo"

┌─────────────────────────────────────────────────────────────┐
│                    三斜线指令使用建议                         │
├─────────────────────────────────────────────────────────────┤
│  ✅ 推荐使用场景：                                           │
│     • 编写库的类型声明文件                                    │
│     • 手动管理声明文件依赖                                    │
│     • 需要精确控制类型加载顺序                                 │
│                                                             │
│  ❌ 不推荐使用场景：                                          │
│     • 普通业务代码（使用 import/export 代替）                 │
│     • 现代 npm 包开发（package.json types 字段代替）          │
└─────────────────────────────────────────────────────────────┘

namespace Utils {
  export function format(input: string): string {
    return input.trim().toLowerCase()
  }
 
  export interface Config {
    delimiter: string
  }
 
  export const version = "1.0.0"
}
 
// 使用
const formatted = Utils.format("  HELLO  ")
const config: Utils.Config = { delimiter: "," }
console.log(Utils.version)

namespace App {
  export namespace Models {
    export interface User {
      id: string
      name: string
    }
 
    export interface Product {
      id: string
      price: number
    }
  }
 
  export namespace Services {
    export function fetchUser(id: string): Models.User {
      return { id, name: "Unknown" }
    }
  }
}
 
// 使用
const user: App.Models.User = App.Services.fetchUser("123")

// jquery.d.ts
declare namespace JQuery {
  interface Ajax {
    url: string
    method: string
    data?: any
  }
 
  interface Event {
    type: string
    target: HTMLElement
  }
}
 
declare const $: {
  ajax(options: JQuery.Ajax): Promise<any>
  (selector: string): {
    on(event: string, handler: (e: JQuery.Event) => void): void
  }
}

// 源码
namespace Guang {
    export interface Person {
        name: string;
        age?: number;
    }
 
    const name = 'guang';
    const age = 20;
 
    export const guang: Person = {
        name,
        age
    }
    export function add(a: number, b: number): number {
        return a + b;
    }
}
 
// 编译产物
var Guang;
(function (Guang) {
    Guang.name = 'guang';
    Guang.age = 20;
    Guang.guang = { name: 'guang', age: 20 };
    function add(a, b) { return a + b; }
    Guang.add = add;
})(Guang || (Guang = {}));

// @types/node 中的典型用法
declare module 'fs' {
    export function readFileSync(path: string, encoding: string): string;
    export function writeFileSync(path: string, data: string): void;
}
 
declare module 'path' {
    export function join(...paths: string[]): string;
    export function resolve(...pathSegments: string[]): string;
}

// global.d.ts —— 无 import/export，所有声明都是全局的
declare function greet(name: string): void;
declare const version: string;
// 在项目任何文件中都可以直接使用 greet 和 version
 
// module.d.ts —— 有 import/export，声明变成模块内的
import { Something } from './types';
declare function process(input: Something): void;
// process 不再是全局的，必须显式导出或 declare global

// global-with-import.d.ts
import { Request } from 'express';
 
declare global {
    // 这些类型在全局可用
    interface Window {
        customConfig: Record<string, unknown>;
    }
    function debug(message: string): void;
}
 
// 模块内部的类型
declare module 'express' {
    interface Request {
        userId?: string;
    }
}

// 推荐方式：引入类型声明但保持全局
/// <reference types="node" />
 
declare function readFile(path: string): Buffer;
// readFile 仍然是全局的
 
// 不推荐：import 会导致类型声明变为模块内的
// import { Buffer } from 'buffer';  // 这会让所有声明变为模块内的

// utils/string.ts
namespace Utils {
  export function trim(input: string): string {
    return input.trim()
  }
}
 
// utils/number.ts
namespace Utils {
  export function round(input: number): number {
    return Math.round(input)
  }
}
 
// main.ts
/// <reference path="utils/string.ts" />
/// <reference path="utils/number.ts" />
 
Utils.trim("  hello  ")
Utils.round(3.14)

// global.d.ts
declare namespace NodeJS {
  interface ProcessEnv {
    NODE_ENV: "development" | "production"
    API_URL: string
  }
}
 
// 使用
const env = process.env.NODE_ENV
const apiUrl = process.env.API_URL

// ✅ 推荐：在声明文件中使用命名空间
declare namespace MyLibrary {
  interface Options {
    debug: boolean
  }
}
 
// ✅ 推荐：为全局库声明命名空间
declare namespace $ {
  function ajax(options: any): void
}
 
// ❌ 不推荐：在应用代码中使用命名空间（使用 ES Modules 代替）
namespace App {
  export const config = {}
}
 
// ✅ 推荐：使用 ES Modules
export const config = {}

// 仅导入类型
import type { User, Config } from "./types"
 
// 混合导入：值和类型
import { format, type User } from "./utils"
 
// 仅导入类型（默认导出）
import type MyType from "./types"

// types.ts
export interface User {
  id: string
  name: string
}
 
export function createUser(name: string): User {
  return { id: crypto.randomUUID(), name }
}
 
// main.ts
import type { User } from "./types"
 
function greet(user: User): string {
  return `Hello, ${user.name}!`
}

// main.js - type 导入被完全移除
function greet(user) {
  return `Hello, ${user.name}!`
}

import { createUser, type User } from "./types"
 
const user: User = createUser("Alice")

import { createUser } from "./types"
 
const user = createUser("Alice")

// ❌ 错误：type 导入不能作为值使用
import type { User } from "./types"
const user = User // Error: 'User' is a type and cannot be used as a value
 
// ✅ 正确：type 导入仅用于类型标注
import type { User } from "./types"
function process(user: User): void {}
 
// ✅ 正确：普通导入可以同时用于类型和值
import { User } from "./types"
const u: User = { id: "1", name: "Test" }

// types.ts
export type UserID = string
 
export interface User {
  id: UserID
  name: string
}
 
export type { User as UserType }

// barrel.ts
export type { User, Config } from "./types"
export type { default as UserService } from "./service"

let config: import("./types").Config
 
function process(user: import("./types").User): void {}

┌─────────────────────────────────────────────────────────────┐
│                    编译产物对比                              │
├─────────────────────────────────────────────────────────────┤
│  源代码：                                                    │
│  import { User, createUser } from './types';               │
│                                                             │
│  编译后：                                                    │
│  import { User, createUser } from './types';               │
│  （User 可能被保留，因为无法确定是否仅用于类型）              │
├─────────────────────────────────────────────────────────────┤
│  源代码：                                                    │
│  import { type User, createUser } from './types';          │
│                                                             │
│  编译后：                                                    │
│  import { createUser } from './types';                     │
│  （User 被明确移除）                                         │
└─────────────────────────────────────────────────────────────┘

// ✅ 推荐：明确区分类型导入和值导入
import { render, type ComponentProps } from "react"
import { formatDate, type DateFormat } from "./utils"
 
// ✅ 推荐：纯类型文件使用 type 导入
import type { Config, Options, Result } from "./types"
 
// ❌ 不推荐：不区分类型和值
import { Config, Options, Result } from "./types" // 全是类型却被当作值导入

// @ts-expect-error - 如果这行代码被修复，会立即得到提醒
const wrong: string = 123

project/
├── src/
│   └── index.ts
├── types/                    # 自定义类型声明
│   ├── global.d.ts          # 全局类型扩展
│   ├── assets.d.ts          # 静态资源类型
│   └── modules/             # 第三方库类型补充
│       └── some-lib.d.ts
└── tsconfig.json

{
  "compilerOptions": {
    "typeRoots": ["./node_modules/@types", "./types"]
  }
}

// ✅ 使用 import type - 仅用于类型标注
import type { User } from "./types"
function process(user: User): void {}
 
// ❌ 不需要 type - 运行时需要使用
import { validateUser } from "./types"
validateUser(userData)

// 扩展 express
declare module "express" {
  interface Request {
    user?: { id: string; role: string }
  }
}
 
// 扩展 window
declare global {
  interface Window {
    myCustomProperty: string
  }
}

┌─────────────────────────────────────────────────────────────┐
│                    类型指令决策树                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  需要忽略类型错误？                                          │
│       │                                                     │
│       ├── 是 → 是否确定存在错误？                            │
│       │          │                                          │
│       │          ├── 是 → 使用 @ts-expect-error             │
│       │          │                                          │
│       │          └── 否 → 重新审视代码，修复类型问题          │
│       │                                                     │
│       └── 否 → 正常开发                                     │
│                                                             │
│  需要为 JS 文件启用检查？                                    │
│       │                                                     │
│       ├── 单个文件 → 使用 @ts-check                         │
│       │                                                     │
│       └── 所有文件 → tsconfig.json 中设置 "checkJs": true   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

project/
├── src/
├── types/
│   ├── global.d.ts        # 全局类型扩展（Window、NodeJS 等）
│   ├── assets.d.ts        # 静态资源类型（图片、CSS 等）
│   ├── modules/           # 第三方库类型补充
│   │   ├── lodash.d.ts
│   │   └── custom-lib.d.ts
│   └── env.d.ts           # 环境变量类型
└── tsconfig.json

// 1. 第三方库导入在前
import { useState, useEffect } from "react"
import type { ReactNode } from "react"
 
// 2. 项目内部导入在后
import { Button } from "@/components"
import type { ButtonProps } from "@/components"
 
// 3. 类型导入与值导入分离
import { formatDate, formatNumber } from "./utils"
import type { DateFormat, NumberFormat } from "./utils"

// ✅ 好的实践
declare module "my-library" {
  // 导出明确的类型
  export interface Config {
    apiUrl: string
    timeout?: number
  }
 
  // 导出函数签名
  export function init(config: Config): void
  export function destroy(): void
}
 
// ❌ 不好的实践
declare module "my-library" // 过于宽泛，丢失类型安全