SimplyTyped社区贡献指南：如何扩展和自定义类型工具-尧图网络科技

SimplyTyped社区贡献指南：如何扩展和自定义类型工具

【免费下载链接】SimplyTypedyet another Typescript type library for advanced types项目地址: https://gitcode.com/gh_mirrors/si/SimplyTyped

SimplyTyped是一个强大的TypeScript类型工具库，专为处理复杂类型场景而设计。如果你正在寻找一个简单而强大的方式来扩展和自定义TypeScript类型工具，那么你来对地方了！🚀 本指南将带你深入了解如何为SimplyTyped做出贡献，无论你是TypeScript新手还是高级用户。

📦 项目概览与安装

SimplyTyped提供了丰富的类型工具，涵盖了对象操作、条件类型、字符串处理、数字运算等多个方面。要开始使用，只需运行：

npm install --save-dev simplytyped

或者如果你使用Deno：

import 'https://unpkg.com/simplytyped/edition-deno/index.ts'

🔧 开发环境设置

1. 克隆仓库并安装依赖

首先克隆项目仓库并安装必要的依赖：

git clone https://gitcode.com/gh_mirrors/si/SimplyTyped cd SimplyTyped npm install npm install typescript@3.0.3

2. 运行测试

SimplyTyped有完善的测试套件，确保你的贡献不会破坏现有功能：

# 运行所有测试 npm test # 在所有支持的TypeScript版本上运行测试 npm run test:all

所有贡献都需要附带测试用例。如果是修复bug，请提供一个在修复前会失败、修复后能通过的测试用例。

📝 编写新的类型工具

理解项目结构

SimplyTyped的源代码组织得非常清晰：

src/types/- 核心类型定义目录
- objects.ts- 对象相关类型工具
- conditionals.ts- 条件类型工具
- functions.ts- 函数相关类型
- numbers.ts- 数字运算类型
- strings.ts- 字符串处理类型
- tuples.ts- 元组类型工具
- utils.ts- 实用工具类型
test/- 测试文件目录
src/impl/- 运行时实现

添加新的类型工具

假设你想添加一个新的对象操作类型工具，可以按照以下步骤：

在相应的文件中添加类型定义

打开src/types/objects.ts，添加你的新类型：

/** * 创建一个新的对象类型，将所有属性值转换为特定类型 * @param T 源对象类型 * @param U 目标值类型 * @returns 所有属性值都转换为U类型的新对象 */ export type MapValues<T extends object, U> = { [K in keyof T]: U; };

编写JSDoc文档

所有公开的类型都需要完整的JSDoc文档。文档会用于自动生成README.md文件。如果你有内部辅助类型不想公开，可以在JSDoc的第一行添加no-doc：

/** * no-doc * 这是一个内部辅助类型，用于支持MapValues */ export type InternalHelper = any;

导出类型

确保在相应的导出文件中添加导出：

// 在src/types/objects.ts中 export type MapValues<T extends object, U> = { /* ... */ }; // 在src/types.ts中 export * from './types/objects';

🧪 编写测试用例

测试文件结构

测试文件按照功能模块组织在test/目录下：

test/objects/- 对象类型测试
test/conditionals/- 条件类型测试
test/functions/- 函数类型测试
test/numbers/- 数字类型测试
test/strings/- 字符串类型测试
test/tuples/- 元组类型测试
test/utils/- 工具类型测试

创建测试文件

为你的新类型工具创建测试文件：

// test/objects/MapValues.test.ts import test from 'ava'; import { MapValues } from '../../src'; test('Can map all values of an object to a specific type', t => { type Source = { a: number; b: string; c: boolean }; type Expected = { a: string; b: string; c: string }; type Result = MapValues<Source, string>; assert<Result, Expected>(t); assert<Expected, Result>(t); }); test('Can map values to union types', t => { type Source = { x: number; y: number }; type Expected = { x: string | number; y: string | number }; type Result = MapValues<Source, string | number>; assert<Result, Expected>(t); assert<Expected, Result>(t); });

使用assert辅助函数

测试中使用assert函数来验证类型相等性：

import { assert } from '../helpers/assert'; // 验证两个类型是否相等 assert<ActualType, ExpectedType>(t);

🔄 提交贡献

1. 遵循提交规范

SimplyTyped使用Conventional Commits规范。所有提交消息都会被自动检查：

feat: 添加MapValues类型工具 fix: 修复DeepPartial中数组处理的问题 docs: 更新README中的示例 test: 为Merge类型添加更多测试用例

2. 提交前的检查

在提交前，确保：

所有测试通过
代码符合TypeScript规范
添加了必要的文档
更新了相关的导出

3. 创建Pull Request

当你准备好贡献时：

Fork项目仓库
创建功能分支
提交你的更改
创建Pull Request

🎯 最佳实践指南

类型设计原则

保持简单：SimplyTyped的目标是提供简洁的类型构建块
类型安全：确保类型工具在边缘情况下也能正常工作
性能考虑：避免创建过于复杂的递归类型
向后兼容：新功能不应破坏现有API

代码组织建议

相关功能放在同一个文件中
使用清晰的命名约定
添加充分的注释说明复杂逻辑
遵循现有的代码风格

文档编写技巧

每个公开类型都需要JSDoc注释
包含使用示例
说明边界情况和注意事项
使用@param和@returns标签

🚀 高级贡献场景

添加运行时函数

除了类型工具，SimplyTyped还包含一些运行时函数。这些函数位于src/impl/目录中：

// src/impl/objects.ts export function mapValues<T extends object, U>( obj: T, mapper: (value: T[keyof T], key: keyof T) => U ): { [K in keyof T]: U } { const result: any = {}; for (const key in obj) { if (obj.hasOwnProperty(key)) { result[key] = mapper(obj[key], key); } } return result; }