JSDoc 类型定义 #

/**
 * @type {string} 字符串类型
 */
let name = 'John';

/**
 * @type {number} 数字类型
 */
let age = 25;

/**
 * @type {boolean} 布尔类型
 */
let isActive = true;

/**
 * @type {null} null 类型
 */
let empty = null;

/**
 * @type {undefined} undefined 类型
 */
let notDefined = undefined;

/**
 * @type {symbol} Symbol 类型
 */
let uniqueId = Symbol('id');

/**
 * @type {bigint} BigInt 类型
 */
let bigNumber = 9007199254740991n;

/**
 * @type {*} 任意类型
 */
let anything = 'any value';

/**
 * @type {void} 无返回值
 */
function log(message) {
  console.log(message);
}

/**
 * @type {never} 永不返回
 */
function throwError(message) {
  throw new Error(message);
}

/**
 * @type {object} 对象类型
 */
let config = { timeout: 5000 };

/**
 * @type {function} 函数类型
 */
let callback = () => {};

/**
 * 字符串数组
 * @type {string[]}
 */
let names = ['John', 'Jane', 'Bob'];

/**
 * 数字数组
 * @type {number[]}
 */
let scores = [90, 85, 95];

/**
 * 使用 Array 泛型
 * @type {Array<string>}
 */
let tags = ['js', 'node', 'react'];

/**
 * 二维数组
 * @type {number[][]}
 */
let matrix = [
  [1, 2, 3],
  [4, 5, 6]
];

/**
 * 三维数组
 * @type {string[][][]}
 */
let cube = [[['a', 'b'], ['c']], [['d']]];

/**
 * 混合类型数组
 * @type {Array<string|number>}
 */
let mixed = ['hello', 42, 'world', 100];

/**
 * 元组风格（固定长度和类型）
 * @type {[string, number, boolean]}
 */
let tuple = ['John', 25, true];

/**
 * 简单对象
 * @type {Object}
 */
let user = { name: 'John', age: 25 };

/**
 * 带属性类型的对象
 * @type {Object<string, number>}
 */
let scores = { math: 90, english: 85 };

/**
 * @typedef {Object} User
 * @property {string} name - 用户名
 * @property {number} age - 年龄
 * @property {string} [email] - 邮箱（可选）
 * @property {string[]} [tags=[]] - 标签数组
 */

/**
 * @type {User}
 */
const user = {
  name: 'John',
  age: 25,
  email: 'john@example.com',
  tags: ['developer', 'admin']
};

/**
 * @typedef {Object} Address
 * @property {string} city - 城市
 * @property {string} street - 街道
 * @property {number} zipCode - 邮编
 */

/**
 * @typedef {Object} User
 * @property {string} name - 用户名
 * @property {Address} address - 地址对象
 */

/**
 * @type {User}
 */
const user = {
  name: 'John',
  address: {
    city: 'Beijing',
    street: 'Main Street',
    zipCode: 100000
  }
};

/**
 * 字符串键，数字值
 * @type {Object<string, number>}
 */
const scores = { math: 90, english: 85 };

/**
 * 数字键，字符串值
 * @type {Object<number, string>}
 */
const indexMap = { 0: 'first', 1: 'second' };

/**
 * 任意键，任意值
 * @type {Object<string, *>}
 */
const cache = {};

/**
 * @type {Function}
 */
let callback = () => {};

/**
 * @type {function}
 */
let handler = function() {};

/**
 * 简单函数签名
 * @type {function(string): boolean}
 */
const isValid = (str) => str.length > 0;

/**
 * 多参数函数
 * @type {function(number, number): number}
 */
const add = (a, b) => a + b;

/**
 * 无参数函数
 * @type {function(): void}
 */
const logTime = () => console.log(Date.now());

/**
 * @callback RequestCallback
 * @param {Error|null} error - 错误对象
 * @param {Object} [data] - 响应数据
 * @returns {void}
 */

/**
 * 发送请求
 * @param {string} url - 请求地址
 * @param {RequestCallback} callback - 回调函数
 */
function request(url, callback) {
  // ...
}

/**
 * 处理输入
 * @param {string} input - 字符串输入
 * @returns {string}
 * @overload
 */

/**
 * 处理输入
 * @param {number} input - 数字输入
 * @returns {number}
 * @overload
 */

/**
 * 处理输入
 * @param {string|number} input - 输入值
 * @returns {string|number}
 */
function process(input) {
  return input;
}

/**
 * 字符串或数字
 * @type {string|number}
 */
let id = '123';
id = 123;

/**
 * 多种类型联合
 * @type {string|number|boolean}
 */
let value = 'hello';
value = 42;
value = true;

/**
 * 可能为 null
 * @type {?string}
 */
let name = 'John';
name = null;

// 等价于
/**
 * @type {string|null}
 */
let name2 = 'John';

/**
 * 可能为 undefined
 * @type {string|undefined}
 */
let email = undefined;

/**
 * 状态类型
 * @typedef {'pending' | 'active' | 'inactive'} Status
 */

/**
 * @type {Status}
 */
let status = 'active';

/**
 * 方向类型
 * @typedef {'up' | 'down' | 'left' | 'right'} Direction
 */

/**
 * @type {Direction}
 */
let direction = 'up';

/**
 * @typedef {Object} Name
 * @property {string} name
 */

/**
 * @typedef {Object} Age
 * @property {number} age
 */

/**
 * 交叉类型
 * @typedef {Name & Age} Person
 */

/**
 * @type {Person}
 */
const person = {
  name: 'John',
  age: 25
};

/**
 * @typedef {Object} BaseConfig
 * @property {string} baseURL - 基础地址
 */

/**
 * @typedef {Object} RequestOptions
 * @property {number} [timeout] - 超时时间
 */

/**
 * 合并配置类型
 * @typedef {BaseConfig & RequestOptions} Config
 */

/**
 * @type {Config}
 */
const config = {
  baseURL: '/api',
  timeout: 5000
};

/**
 * 泛型函数
 * @template T
 * @param {T} value - 输入值
 * @returns {T} 返回相同类型
 */
function identity(value) {
  return value;
}

/**
 * 多个泛型参数
 * @template T, U
 * @param {T} first - 第一个值
 * @param {U} second - 第二个值
 * @returns {Object} 包含两个值的对象
 */
function pair(first, second) {
  return { first, second };
}

/**
 * 带约束的泛型
 * @template {Object} T
 * @param {T} obj - 对象参数
 * @param {string} key - 键名
 * @returns {*} 属性值
 */
function getProperty(obj, key) {
  return obj[key];
}

/**
 * 数组工具
 * @template T
 * @param {T[]} items - 数组
 * @param {function(T): boolean} predicate - 条件函数
 * @returns {T[]} 过滤后的数组
 */
function filter(items, predicate) {
  return items.filter(predicate);
}

/**
 * 泛型容器类
 * @template T
 */
class Container {
  /**
   * @param {T} value - 初始值
   */
  constructor(value) {
    /**
     * @type {T}
     */
    this.value = value;
  }

  /**
   * @returns {T}
   */
  getValue() {
    return this.value;
  }

  /**
   * @param {T} value - 新值
   */
  setValue(value) {
    this.value = value;
  }
}

/**
 * @template [T=string]
 * @param {T} value - 输入值
 * @returns {T}
 */
function process(value) {
  return value;
}

/**
 * 用户类型
 * @typedef {Object} User
 * @property {number} id - 用户 ID
 * @property {string} name - 用户名
 * @property {string} email - 邮箱
 * @property {string[]} [roles] - 角色列表
 */

/**
 * @param {User} user - 用户对象
 */
function saveUser(user) {
  // ...
}

/**
 * API 响应类型
 * @template T
 * @typedef {Object} ApiResponse
 * @property {number} code - 状态码
 * @property {string} message - 消息
 * @property {T} [data] - 数据
 */

/**
 * @returns {Promise<ApiResponse<User>>}
 */
async function fetchUser() {
  // ...
}

/**
 * @typedef {import('./types').User} User
 * @typedef {import('./types').Config} Config
 */

/**
 * @param {User} user
 * @param {Config} config
 */
function init(user, config) {
  // ...
}

/**
 * 强制类型断言
 * @type {string}
 */
// @ts-ignore
const value = someValue;

/**
 * 检查是否为字符串
 * @param {*} value - 任意值
 * @returns {value is string}
 */
function isString(value) {
  return typeof value === 'string';
}

/**
 * 检查是否为用户对象
 * @param {*} obj - 任意对象
 * @returns {obj is User}
 */
function isUser(obj) {
  return obj && typeof obj.name === 'string';
}

/**
 * 从模块导入类型
 * @typedef {import('./user').User} User
 * @typedef {import('./config').Config} Config
 */

/**
 * 导入并重命名
 * @typedef {import('./api').Response as ApiResponse} ApiResponse
 */

/**
 * 用户模块
 * @module user
 */

/**
 * @typedef {Object} User
 * @property {string} name - 用户名
 * @property {number} age - 年龄
 */

export { User };

/**
 * 基础用户类型
 * @typedef {Object} BaseUser
 * @property {string} name - 用户名
 * @property {string} email - 邮箱
 */

/**
 * 扩展用户类型
 * @typedef {BaseUser & {
 *   id: number,
 *   createdAt: Date
 * }} FullUser
 */

/**
 * 部分属性
 * @typedef {Partial<User>} PartialUser
 */

/**
 * @param {PartialUser} updates - 更新数据
 */
function updateUser(updates) {
  // ...
}

/**
 * 所有属性必需
 * @typedef {Required<User>} RequiredUser
 */

/**
 * 选择部分属性
 * @typedef {Pick<User, 'name' | 'email'>} UserContact
 */

/**
 * 排除部分属性
 * @typedef {Omit<User, 'id'>} NewUser
 */

/**
 * 记录类型
 * @typedef {Record<string, number>} ScoreMap
 */

/**
 * @type {ScoreMap}
 */
const scores = { math: 90, english: 85 };

/**
 * @typedef {Object} User
 * @property {string} name
 * @property {number} age
 */

// 在 .ts 文件中可以直接使用
// import { User } from './user.js';

/**
 * JSDoc 会自动推断一些类型
 */
class User {
  constructor(name) {
    // 自动推断为 string
    this.name = name;
  }

  getName() {
    // 自动推断返回 string
    return this.name;
  }
}

// ✅ 好的做法
/**
 * @type {string[]}
 */

// ❌ 避免
/**
 * @type {Array}
 */

// ✅ 好的做法
/**
 * @param {string|number} value
 */

// ❌ 避免
/**
 * @param {*} value
 */

// ✅ 好的做法
/**
 * @typedef {Object} User
 * @property {string} name
 * @property {number} age
 */

/**
 * @param {User} user
 */

// ❌ 重复定义
/**
 * @param {Object} user
 * @param {string} user.name
 * @param {number} user.age
 */