ts-essentials - TypeScript类型工具集简化类型安全编程

ts-essentials

所有必备的 TypeScript 类型集于一处 🤙

下载量

安装

npm install --save-dev ts-essentials

👉 我们需要 typescript>=4.5。如果你需要支持旧版本的 TS，请查看TypeScript 依赖表

👉 由于我们希望类型更加严格，我们要求在你的项目中启用 strictNullChecks

API

ts-essentials 是一组高质量、实用的 TypeScript 类型，可以让编写类型安全的代码变得更加容易。

基础类型

Builtin - 匹配原始类型、函数、日期、错误或正则表达式
KeyofBase - keyofStringsOnly 兼容的 PropertyKey 替代品
Prettify<Type> - 扁平化类型并使其在 IDE 悬停时更易读
Primitive - 匹配任何原始值
StrictExclude<UnionType, ExcludedMembers> - 通过从 UnionType 中排除所有可分配给 ExcludedMembers 的联合成员来构造类型。这是 Exclude 的更严格版本
StrictExtract<Type, Union> - 通过从 Type 中提取所有可分配给 Union 的联合成员来构造类型。这是 Extract 的更严格版本
StrictOmit<Type, Keys> - 通过从 Type 中选取所有属性然后移除 Keys 来构造类型。这是 Omit 的更严格版本
Writable<Type> - 构造一个类型，移除 Type 所有属性的 readonly，意味着构造类型的属性可以被重新赋值

实用类型

AsyncOrSync<Type> - 构造一个 Type 或 PromiseLike<Type> 的类型
AsyncOrSyncType<Type> - 解包 AsyncOrSync 类型
Dictionary<Type, Keys?> - 构造一个必需的对象类型，其属性键为 Keys（默认为 string），属性值为 Type
Merge<Object1, Object2> - 通过选取 Object1 和 Object2 的所有属性来构造类型。当属性键相同时，Object2 的属性值会覆盖 Object1 的属性值
MergeN<Tuple> - 通过递归地使用 Merge 类型合并元组 Tuple 中的对象来构造类型
Newable<ReturnType> - 构造一个类类型，其构造函数的返回类型为 ReturnType
NonNever<Type> - 通过选取 Type 中所有值不等于 never 的属性来构造类型
OmitProperties<Type, Value> - 通过选取 Type 中所有属性并移除值等于 Value 的那些属性来构造类型
Opaque<Type, Token> - 构造一个类型，它是 Type 的子集，带有指定的唯一标记 Token
PathValue<Type, Path> - 为类型 Type 和路径 Path 构造路径值
Paths<Type> - 通过选取类型 Type 的所有可能路径来构造联合类型
PickProperties<Type, Value> - 通过选取 Type 中所有值等于 Value 的属性来构造类型
SafeDictionary<Type, Keys?> - 构造一个可选的对象类型，其属性键为 Keys（默认为 string），属性值为 Type
UnionToIntersection<Union> - 从联合类型 Union 构造交叉类型
ValueOf<Type> - 为类型 Type 构造一个类型，对于原始类型等于原始值，对于数组等于数组元素，对于函数等于函数返回类型，对于对象等于对象属性值
XOR<Type1, Type2, Type3?, ..., Type50?> - 构造一个类型，它可以分配给 Type1 或 Type2，但不能同时分配给两者。从 ts-essentials@10 开始，它支持最多 50 个泛型类型。

标记包装类型

MarkOptional<Type, Keys> - 通过选取 Type 中的所有属性来构造类型，其中 Keys 属性被设置为可选，意味着它们不是必需的
MarkReadonly<Type, Keys> - 通过选取 Type 中的所有属性来构造类型，其中 Keys 属性被设置为 readonly，意味着它们不能被重新赋值
MarkRequired<Type, Keys> - 通过选取 Type 中的所有属性来构造类型，其中 Keys 属性被设置为必需
MarkWritable<Type, Keys> - 通过选取 Type 中的所有属性来构造类型，其中 Keys 属性移除 readonly 修饰符，意味着它们可以被重新赋值

深度包装类型

Buildable<Type> - 通过结合 DeepPartial 和 DeepWritable 构造一个类型，意味着来自 Type 类型的所有属性都被递归地设置为非 readonly 和可选的，即它们可以被重新赋值且不是必需的
DeepNonNullable<Type> - 通过递归地从 Type 类型中选择所有属性并从所有属性中排除 null 和 undefined 值来构造一个类型。要在一个层级上使属性非空，请使用 NonNullable<Type>
DeepNullable<Type> - 通过递归地从 Type 类型中选择所有属性并为所有属性包含 null 值来构造一个类型
DeepOmit<Type, Filter> - 通过从 Type 类型中选择所有属性并移除在 Filter 类型中值为 never 或 true 的属性来构造一个类型。如果您希望 Filter 类型根据 Type 的结构进行验证，请使用 StrictDeepOmit<Type, Filter>。
DeepPartial<Type> - 通过递归地从 Type 类型中选择所有属性并将它们设置为可选来构造一个类型，意味着它们不是必需的。要在一个层级上使属性可选，请使用 Partial<Type>
DeepPick<Type, Filter> - 通过从 Type 类型中选择一组在 Filter 类型中属性值为 never 或 true 的属性来构造一个类型。如果您希望 Filter 类型根据 Type 的结构进行验证，请使用 StrictDeepPick<Type, Filter>。
DeepReadonly<Type> - 通过递归地从 Type 类型中选择所有属性并设置 readonly 修饰符来构造一个类型，意味着它们不能被重新赋值。要在一个层级上使属性 readonly，请使用 Readonly<Type>
DeepRequired<Type> - 通过递归地从 Type 类型中选择所有属性并将其设置为必需来构造一个类型。要在一个层级上使属性必需，请使用 Required<Type>
DeepUndefinable<Type> - 通过递归地从 Type 类型中选择所有属性并为所有属性包含 undefined 值来构造一个类型
DeepWritable<Type> - 通过递归地从 Type 类型中选择所有属性并移除 readonly 修饰符来构造一个类型，意味着它们可以被重新赋值。要在一个层级上使属性可写，请使用 Writable<Type>
StrictDeepOmit<Type, Filter> - 通过从 Type 类型中选择所有属性并移除在 Filter 类型中值为 never 或 true 的属性来构造一个类型。Filter 类型根据 Type 的结构进行验证。
StrictDeepPick<Type, Filter> - 通过从 Type 类型中选择一组在 Filter 类型中属性值为 never 或 true 的属性来构造一个类型。Filter 类型根据 Type 的结构进行验证。

关键类型

OptionalKeys<Type> - 通过选择对象类型 Type 的所有可选属性构造一个联合类型
PickKeys<Type, Value> - 通过选择对象类型 Type 中所有可赋值给类型 Value 的属性构造一个联合类型
ReadonlyKeys<Type> - 通过选择对象类型 Type 的所有 readonly 属性构造一个联合类型，意味着它们的值不能被重新赋值
RequiredKeys<Type> - 通过选择对象类型 Type 的所有必需属性构造一个联合类型
WritableKeys<Type> - 通过选择对象类型 Type 的所有可写属性构造一个联合类型，意味着它们的值可以被重新赋值

类型检查器

Exact<Type, Shape> - 当类型 Type 和 Shape 完全相同时返回 Type。否则返回 never
IsAny<Type> - 当类型 Type 为 any 时返回 true。否则返回 false
IsNever<Type> - 当类型 Type 为 never 时返回 true。否则返回 false
IsUnknown<Type> - 当类型 Type 为 unknown 时返回 true。否则返回 false
IsTuple<Type> - 当类型 Type 为元组时返回 Type。否则返回 never
NonEmptyObject<Object> - 当 Object 至少有一个键时返回 Object。否则返回 never

数组和元组

AnyArray<Type?> - 匹配 Array 或 ReadonlyArray（默认 Type 为 any）
ArrayOrSingle<Type> - 匹配 Type 或 Type[]
ElementOf<Type> - 构造一个等于类型 Type 的数组元素类型的类型
Head<Type> - 构造一个等于类型 Type 中第一个元素的类型
NonEmptyArray<Type> - 匹配至少有一个 Type 类型元素的数组
ReadonlyArrayOrSingle - 匹配 Type 或 readonly Type[]
Tail<Type> - 构造一个等于类型 Type 中除第一个元素外的所有元素的类型
Tuple<Type?> - 匹配元组的类型约束，元素类型为 Type（默认为 any）

更改大小写

CamelCase<Type> - 将类型 Type 转换为驼峰式（例如 camelCase）
DeepCamelCaseProperties<Type> - 通过递归地从类型 Type 中选择所有属性并将它们全部转换为驼峰式来构造一个类型

函数类型

AnyFunction<Args?, ReturnType?> - 匹配参数类型为 Args（默认为 any[]）和返回类型为 ReturnType（默认为 any）的函数类型
PredicateFunction - 匹配类型守卫的类型约束，意味着第一个参数用于返回类型，且返回类型是类型谓词
PredicateType<Type> - 构造一个等于谓词函数 Type 中缩小类型的类型

实用函数

⚠️ 确保您将 ts-essentials 添加到 dependencies 中（npm install --save ts-essentials）以避免运行时错误

new UnreachableCaseError(value) - 匹配运行时类实例类型，帮助检查 value 的穷尽性。当 value 不是 never 时，它会显示 TypeScript 错误
assert(condition, message?) - 匹配运行时函数，帮助断言 condition。当 condition 为假时，它会抛出一个错误，错误信息为 Assertion Error: ${message}（默认消息为 "no additional info provided"）
createFactoryWithConstraint<Constraint>()(value) - 匹配运行时函数，验证 value 的类型是否匹配 Constraint，而不改变 value 的结果类型。satisfies 运算符的 polyfill
isExact<Expected>()(actual) - 匹配运行时函数，验证 actual 的类型是否等于 Expected。否则显示 TypeScript 错误
noop(..._args) - 匹配对参数 _args 不执行任何操作的运行时函数

搜索

当某个实用类型以不同名称被人所知时，请在此处添加以便更好地搜索。

ArrayValues - ValueOf<Type>
Branded - Opaque<Type, Token>
ConditionalKeys - PickKeys<Type, Value>
Except - StrictOmit<Type, Keys>
Get - PathValue<Type, Path>
Mutable - Writable<Type>
Nominal - Opaque<Type, Token>
Set*，例如 SetOptional - Mark*，例如 MarkReadonly<Type, Keys>
Unwrap - Prettify<Type>
ValueOf - DictionaryValues

内置类型

TypeScript 提供了几种实用类型来便于常见的类型转换。这些实用工具在全局范围内可用。

Awaited<Type> - 这种类型旨在模拟 async 函数中的 await 操作，或 Promise 上的 .then() 方法 - 特别是它们递归解包 Promise 的方式
Capitalize<StringType> - 将字符串中的第一个字符转换为大写形式
ConstructParameters<Type> - 从构造函数类型 Type 的类型构造一个元组或数组类型
Exclude<UnionType, ExcludedMembers> - 通过从 UnionType 中排除所有可赋值给 ExcludedMembers 的联合成员来构造一个类型
Extract<Type, Union> - 通过从 Type 中提取所有可赋值给 Union 的联合成员来构造一个类型
InstanceType<Type> - 构造一个由 Type 中构造函数的实例类型组成的类型
Lowercase<StringType> - 将字符串中的每个字符转换为小写形式
NonNullable<Type> - 通过从 Type 中排除 null 和 undefined 来构造一个类型
Omit<Type, Keys> - 通过从 Type 中选取所有属性然后移除 Keys 来构造一个类型
Parameters<Type> - 从函数类型 Type 的参数中使用的类型构造一个元组类型
Partial<Type> - 构造一个类型，将 Type 的所有属性设置为可选
Pick<Type, Keys> - 通过从 Type 中选取属性集 Keys 来构造一个类型
Readonly<Type> - 构造一个类型，将 Type 的所有属性设置为 readonly，意味着构造类型的属性不能被重新赋值
Record<Keys, Type> - 构造一个对象类型，其属性键为 Keys，属性值为 Type
Required<Type> - 构造一个类型，将 Type 的所有属性设置为必需
ReturnType<Type> - 构造一个由函数类型 Type 参数的返回类型组成的类型
Uncapitalize<StringType> - 将字符串中的第一个字符转换为小写形式
Uppercase<StringType> - 将字符串中的每个字符转换为大写版本

TypeScript 依赖表

`ts-essentials`	`typescript` / 依赖类型
`^10.0.0`	`^4.5.0` / 可选对等
`^9.4.0`	`^4.1.0` / 可选对等
`^8.0.0`	`^4.1.0` / 对等
`^5.0.0`	`^3.7.0` / 对等
`^3.0.1`	`^3.5.0` / 对等
`^1.0.1`	`^3.2.2` / 开发
`^1.0.0`	`^3.0.3` / 开发

贡献者

感谢这些优秀的人（表情符号键）：

本项目遵循all-contributors规范。欢迎任何形式的贡献！阅读更多

_{Chris Kaczor} 💻 💼 💡 📖	_{Xiao Liang} 💻 🤔 📖	_{Mateusz Burzyński} 💻 🤔 📖	_{Maciej Bembenista} 💻 🤔 📖	_{Michael Tontchev} 💻 🤔 📖	_{Thomas den Hollander} 💻 🤔 📖	_{Esa-Matti Suuronen} 💻 🤔 📖
_{Ilya Semenov} 💻 🤔 📖	_{Code Checks} 👀	_{Patricio Palladino} 🤔	_{Artur Kozak} 💻 🤔 📖 👀	_{Zihua Wu} 💻 🤔 📖	_{Kevin Peno} 💻	_{Dom Parfitt} 🤔
_EduardoRFS 💻 📖	_{Andrew C. Dvorak} 📖	_{Adam Russell} 💻 📖	_{Piotr Szlachciak} 💻 🤔 📖	_{Mikhail Swift} 💻	_{Ryan Zhang} 💻 🤔 📖	_{Francesco Borzì} 📖 💻
_{Marnick L'Eau} 💻 🤔 📖	_kubk 💻	_{Bill Barry} 💻 📖	_{Andrzej Wódkiewicz} 💻 📖 🤔	_Christian 🤔	_{Matthew Leffler} 📖	_studds 💻
_{Alex Berezin} 💻 📖	_vitonsky 📖	_{Itay Ronen} 💻	_{亚罗斯拉夫·拉林} 💻