Skip to content

kevinzhao2233/type-fest_cn

BranchesTags
 
 

Repository files navigation



npm dependents npm downloads

Many of the types here should have been built-in. You can help by suggesting some of them to the TypeScript project.

Either add this package as a dependency or copy-paste the needed types. No credit required. 👌

PR welcome for additional commonly needed types and docs improvements. Read the contributing guidelines first.

Help wanted with reviewing proposals and pull requests.

安装

npm install type-fest

需要 TypeScript >=5.1

最好在 tsconfig 中配置 {strict: true}。

使用

import type {Except} from 'type-fest';

type Foo = {
	unicorn: string;
	rainbow: boolean;
};

type FooWithoutRainbow = Except<Foo, 'rainbow'>;
//=> {unicorn: string}

API

点击类型名称前往完整文档.

基本

Utilities

  • EmptyObject - 表示一个严格为空的纯对象 {}.
  • IsEmptyObject - 返回一个 boolean 值，表示类型是否严格等于空的纯对象，值为 {}.
  • NonEmptyObject - Represents an object with at least 1 non-optional key.
  • UnknownRecord - 表示具有 unnown 值的对象。你可能想要这个，而不是{}。通常在一个对象的键和值对你来说都是未知的时候使用。
  • Except - 创建一个类型，它来自一个对象去除某些特定的 key，这个类型可看作更严格的 Omit.
  • Writable - 创建一个去除对象中 key 的 readonly 的类型。这相当于 Readonly<T> 的反向操作。
  • WritableDeep - 创建object/ReadonlyMap/ReadonlySet/ReadonlyArray类型的深度可写版本。ReadonlyDeep<T>的反向操作。如果只需要一层深度，请使用Writable<T>。
  • Merge - 将两个类型合并为一个新类型。第二类型的键覆盖第一类型的键。
  • MergeDeep - 将两个对象或两个数组/元组递归合并为一个新类型。
  • MergeExclusive - 创建一个具有互斥键的类型，它具有两个类型的所有建，但非此即彼。
  • OverrideProperties - 使用新类型复写源类型，类似 Merge 但只能复写源类型中已有的属性。
  • RequireAtLeastOne - 创建至少需要一个给定 key 的类型。
  • RequireExactlyOne - 创建一种只需要给定 Key 中的一个 Key 而不允许更多 Key 的类型。
  • RequireAllOrNone - 创建需要所有给定 Key 或不需要任何给定 Key 的类型。
  • RequireOneOrNone - 创建只需要给定 Key 中的一个 Key 而不允许更多 Key 或不允许更多 Key 的类型。
  • RequiredDeep - Create a deeply required version of another type. Use Required<T> if you only need one level deep.
  • OmitIndexSignature - 省略给定对象类型的任何索引签名（如 [x: string] ），只保留显式定义的属性。
  • PickIndexSignature - 与 OmitIndexSignature 操作相反，选择出给定对象类型的任何索引签名（如 [x: string] ），去除显式定义的属性。
  • PartialDeep - 具有递归的 Partial。
  • PartialOnUndefinedDeep - 将值为 undefined 的 Key 也设置为可选的。
  • ReadonlyDeep - 对 object/Map/Set/Array 创建具有深度只读的类型。
  • LiteralUnion - Create a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union. Workaround for Microsoft/TypeScript#29729.
  • Tagged - Create a tagged type that can support multiple tags if needed.
  • UnwrapTagged - Get the untagged portion of a tagged type created with Tagged.
  • Opaque - Create a tagged type. This implementation only supports a single tag.
  • UnwrapOpaque - Get the untagged portion of a tagged type created with Opaque or Tagged.
  • InvariantOf - Create an invariant type, which is a type that does not accept supertypes and subtypes.
  • SetOptional - Create a type that makes the given keys optional.
  • SetReadonly - Create a type that makes the given keys readonly.
  • SetRequired - Create a type that makes the given keys required.
  • SetNonNullable - Create a type that makes the given keys non-nullable.
  • ValueOf - Create a union of the given object's values, and optionally specify which keys to get the values from.
  • ConditionalKeys - Extract keys from a shape where values extend the given Condition type.
  • ConditionalPick - Like Pick except it selects properties from a shape where the values extend the given Condition type.
  • ConditionalPickDeep - Like ConditionalPick except that it selects the properties deeply.
  • ConditionalExcept - Like Omit except it removes properties from a shape where the values extend the given Condition type.
  • UnionToIntersection - Convert a union type to an intersection type.
  • LiteralToPrimitive - Convert a literal type to the primitive type it belongs to.
  • LiteralToPrimitiveDeep - Like LiteralToPrimitive except it converts literal types inside an object or array deeply.
  • Stringified - Create a type with the keys of the given type changed to string type.
  • IterableElement - Get the element type of an Iterable/AsyncIterable. For example, an array or a generator.
  • Entry - Create a type that represents the type of an entry of a collection.
  • Entries - Create a type that represents the type of the entries of a collection.
  • SetReturnType - Create a function type with a return type of your choice and the same parameters as the given function type.
  • Simplify - Useful to flatten the type output to improve type hints shown in editors. And also to transform an interface into a type to aide with assignability.
  • Get - Get a deeply-nested property from an object using a key path, like Lodash's .get() function.
  • StringKeyOf - Get keys of the given type as strings.
  • Schema - Create a deep version of another object type where property values are recursively replaced into a given value type.
  • Exact - Create a type that does not allow extra properties.
  • OptionalKeysOf - Extract all optional keys from the given type.
  • HasOptionalKeys - Create a true/false type depending on whether the given type has any optional fields.
  • RequiredKeysOf - Extract all required keys from the given type.
  • HasRequiredKeys - Create a true/false type depending on whether the given type has any required fields.
  • ReadonlyKeysOf - Extract all readonly keys from the given type.
  • HasReadonlyKeys - Create a true/false type depending on whether the given type has any readonly fields.
  • WritableKeysOf - Extract all writable (non-readonly) keys from the given type.
  • HasWritableKeys - Create a true/false type depending on whether the given type has any writable fields.
  • Spread - Mimic the type inferred by TypeScript when merging two objects or two arrays/tuples using the spread syntax.
  • IsEqual - Returns a boolean for whether the two given types are equal.
  • TaggedUnion - Create a union of types that share a common discriminant property.

Type Guard

IsType vs. IfType

For every IsT type (e.g. IsAny), there is an associated IfT type that can help simplify conditional types. While the IsT types return a boolean, the IfT types act like an If/Else - they resolve to the given TypeIfT or TypeIfNotT depending on whether IsX is true or not. By default, IfT returns a boolean:

type IfAny<T, TypeIfAny = true, TypeIfNotAny = false> = (
	IsAny<T> extends true ? TypeIfAny : TypeIfNotAny
);

Usage

import type {IsAny, IfAny} from 'type-fest';

type ShouldBeTrue = IsAny<any> extends true ? true : false;
//=> true

type ShouldBeFalse = IfAny<'not any'>;
//=> false

type ShouldBeNever = IfAny<'not any', 'not never', 'never'>;
//=> 'never'

JSON

  • Jsonify - Transform a type to one that is assignable to the JsonValue type.
  • Jsonifiable - Matches a value that can be losslessly converted to JSON.
  • JsonPrimitive - Matches a JSON primitive.
  • JsonObject - Matches a JSON object.
  • JsonArray - Matches a JSON array.
  • JsonValue - Matches any valid JSON value.

Async

  • Promisable - Create a type that represents either the value or the value wrapped in PromiseLike.
  • AsyncReturnType - Unwrap the return type of a function that returns a Promise.
  • Asyncify - Create an async version of the given function type.

String

  • Trim - Remove leading and trailing spaces from a string.
  • Split - Represents an array of strings split using a given character or character set.
  • Replace - Represents a string with some or all matches replaced by a replacement.

Array

  • Includes - Returns a boolean for whether the given array includes the given item.
  • Join - Join an array of strings and/or numbers using the given string as a delimiter.
  • LastArrayElement - Extracts the type of the last element of an array.
  • FixedLengthArray - Create a type that represents an array of the given type and length.
  • MultidimensionalArray - Create a type that represents a multidimensional array of the given type and dimensions.
  • MultidimensionalReadonlyArray - Create a type that represents a multidimensional readonly array of the given type and dimensions.
  • ReadonlyTuple - Create a type that represents a read-only tuple of the given type and length.
  • TupleToUnion - Convert a tuple/array into a union type of its elements.

Numeric

Change case

Miscellaneous

Declined types

If we decline a type addition, we will make sure to document the better solution here.

  • Diff and Spread - The pull request author didn't provide any real-world use-cases and the PR went stale. If you think this type is useful, provide some real-world use-cases and we might reconsider.
  • Dictionary - You only save a few characters (Dictionary<number> vs Record<string, number>) from Record, which is more flexible and well-known. Also, you shouldn't use an object as a dictionary. We have Map in JavaScript now.
  • ExtractProperties and ExtractMethods - The types violate the single responsibility principle. Instead, refine your types into more granular type hierarchies.
  • Url2Json - Inferring search parameters from a URL string is a cute idea, but not very useful in practice, since search parameters are usually dynamic and defined separately.
  • Nullish - The type only saves a couple of characters, not everyone knows what "nullish" means, and I'm also trying to get away from null.
  • TitleCase - It's not solving a common need and is a better fit for a separate package.
  • ExtendOr and ExtendAnd - The benefits don't outweigh having to learn what they mean.
  • PackageJsonExtras - There are too many possible configurations that can be put into package.json. If you would like to extend PackageJson to support an additional configuration in your project, please see the Extending existing types section below.

Alternative type names

If you know one of our types by a different name, add it here for discovery.

Tips

Extending existing types

  • PackageJson - There are a lot of tools that place extra configurations inside the package.json file. You can extend PackageJson to support these additional configurations.

    Example

    Playground

     import type {PackageJson as BasePackageJson} from 'type-fest';
 import type {Linter} from 'eslint';

 type PackageJson = BasePackageJson & {eslintConfig?: Linter.Config};

Related

Built-in types

There are many advanced types most users don't know about.

  • Partial<T> - Make all properties in T optional.

    Example

    Playground

     interface NodeConfig {
 		appName: string;
 		port: number;
 }

 class NodeAppBuilder {
 		private configuration: NodeConfig = {
 				appName: 'NodeApp',
 				port: 3000
 		};

 		private updateConfig<Key extends keyof NodeConfig>(key: Key, value: NodeConfig[Key]) {
 				this.configuration[key] = value;
 		}

 		config(config: Partial<NodeConfig>) {
 				type NodeConfigKey = keyof NodeConfig;

 				for (const key of Object.keys(config) as NodeConfigKey[]) {
 						const updateValue = config[key];

 						if (updateValue === undefined) {
 								continue;
 						}

 						this.updateConfig(key, updateValue);
 				}

 				return this;
 		}
 }

 // `Partial<NodeConfig>`` allows us to provide only a part of the
 // NodeConfig interface.
 new NodeAppBuilder().config({appName: 'ToDoApp'});

  • Required<T> - Make all properties in T required.

    Example

    Playground

     interface ContactForm {
 		email?: string;
 		message?: string;
 }

 function submitContactForm(formData: Required<ContactForm>) {
 		// Send the form data to the server.
 }

 submitContactForm({
 		email: '[email protected]',
 		message: 'Hi! Could you tell me more about…',
 });

 // TypeScript error: missing property 'message'
 submitContactForm({
 		email: '[email protected]',
 });

  • Readonly<T> - Make all properties in T readonly.

    Example

    Playground

     enum LogLevel {
 		Off,
 		Debug,
 		Error,
 		Fatal
 };

 interface LoggerConfig {
 		name: string;
 		level: LogLevel;
 }

 class Logger {
 		config: Readonly<LoggerConfig>;

 		constructor({name, level}: LoggerConfig) {
 				this.config = {name, level};
 				Object.freeze(this.config);
 		}
 }

 const config: LoggerConfig = {
 	name: 'MyApp',
 	level: LogLevel.Debug
 };

 const logger = new Logger(config);

 // TypeScript Error: cannot assign to read-only property.
 logger.config.level = LogLevel.Error;

 // We are able to edit config variable as we please.
 config.level = LogLevel.Error;

  • Pick<T, K> - From T, pick a set of properties whose keys are in the union K.

    Example

    Playground

     interface Article {
 		title: string;
 		thumbnail: string;
 		content: string;
 }

 // Creates new type out of the `Article` interface composed
 // from the Articles' two properties: `title` and `thumbnail`.
 // `ArticlePreview = {title: string; thumbnail: string}`
 type ArticlePreview = Pick<Article, 'title' | 'thumbnail'>;

 // Render a list of articles using only title and description.
 function renderArticlePreviews(previews: ArticlePreview[]): HTMLElement {
 		const articles = document.createElement('div');

 		for (const preview of previews) {
 				// Append preview to the articles.
 		}

 		return articles;
 }

 const articles = renderArticlePreviews([
 		{
 			title: 'TypeScript tutorial!',
 			thumbnail: '/assets/ts.jpg'
 		}
 ]);

  • Record<K, T> - Construct a type with a set of properties K of type T.

    Example

    Playground

     // Positions of employees in our company.
 type MemberPosition = 'intern' | 'developer' | 'tech-lead';

 // Interface describing properties of a single employee.
 interface Employee {
 		firstName: string;
 		lastName: string;
 		yearsOfExperience: number;
 }

 // Create an object that has all possible `MemberPosition` values set as keys.
 // Those keys will store a collection of Employees of the same position.
 const team: Record<MemberPosition, Employee[]> = {
 		intern: [],
 		developer: [],
 		'tech-lead': [],
 };

 // Our team has decided to help John with his dream of becoming Software Developer.
 team.intern.push({
 	firstName: 'John',
 	lastName: 'Doe',
 	yearsOfExperience: 0
 });

 // `Record` forces you to initialize all of the property keys.
 // TypeScript Error: "tech-lead" property is missing
 const teamEmpty: Record<MemberPosition, null> = {
 		intern: null,
 		developer: null,
 };

  • Exclude<T, U> - Exclude from T those types that are assignable to U.

    Example

    Playground

     interface ServerConfig {
 	port: null | string | number;
 }

 type RequestHandler = (request: Request, response: Response) => void;

 // Exclude `null` type from `null | string | number`.
 // In case the port is equal to `null`, we will use default value.
 function getPortValue(port: Exclude<ServerConfig['port'], null>): number {
 	if (typeof port === 'string') {
 		return parseInt(port, 10);
 	}

 	return port;
 }

 function startServer(handler: RequestHandler, config: ServerConfig): void {
 	const server = require('http').createServer(handler);

 	const port = config.port === null ? 3000 : getPortValue(config.port);
 	server.listen(port);
 }

  • Extract<T, U> - Extract from T those types that are assignable to U.

    Example

    Playground

     declare function uniqueId(): number;

 const ID = Symbol('ID');

 interface Person {
 	[ID]: number;
 	name: string;
 	age: number;
 }

 // Allows changing the person data as long as the property key is of string type.
 function changePersonData<
 	Obj extends Person,
 	Key extends Extract<keyof Person, string>,
 	Value extends Obj[Key]
 > (obj: Obj, key: Key, value: Value): void {
 	obj[key] = value;
 }

 // Tiny Andrew was born.
 const andrew = {
 	[ID]: uniqueId(),
 	name: 'Andrew',
 	age: 0,
 };

 // Cool, we're fine with that.
 changePersonData(andrew, 'name', 'Pony');

 // Government didn't like the fact that you wanted to change your identity.
 changePersonData(andrew, ID, uniqueId());

  • NonNullable<T> - Exclude null and undefined from T.

    Example Works with strictNullChecks set to true.

    Playground

     type PortNumber = string | number | null;

 /** Part of a class definition that is used to build a server */
 class ServerBuilder {
 		portNumber!: NonNullable<PortNumber>;

 		port(this: ServerBuilder, port: PortNumber): ServerBuilder {
 				if (port == null) {
 						this.portNumber = 8000;
 				} else {
 						this.portNumber = port;
 				}

 				return this;
 		}
 }

 const serverBuilder = new ServerBuilder();

 serverBuilder
 		.port('8000')   // portNumber = '8000'
 		.port(null)     // portNumber =  8000
 		.port(3000);    // portNumber =  3000

 // TypeScript error
 serverBuilder.portNumber = null;

  • Parameters<T> - Obtain the parameters of a function type in a tuple.

    Example

    Playground

     function shuffle(input: any[]): void {
 	// Mutate array randomly changing its' elements indexes.
 }

 function callNTimes<Fn extends (...arguments_: any[]) => any> (func: Fn, callCount: number) {
 	// Type that represents the type of the received function parameters.
 	type FunctionParameters = Parameters<Fn>;

 	return function (...arguments_: FunctionParameters) {
 		for (let i = 0; i < callCount; i++) {
 			func(...arguments_);
 		}
 	}
 }

 const shuffleTwice = callNTimes(shuffle, 2);

  • ConstructorParameters<T> - Obtain the parameters of a constructor function type in a tuple.

    Example

    Playground

     class ArticleModel {
 	title: string;
 	content?: string;

 	constructor(title: string) {
 		this.title = title;
 	}
 }

 class InstanceCache<T extends (new (...arguments_: any[]) => any)> {
 	private ClassConstructor: T;
 	private cache: Map<string, InstanceType<T>> = new Map();

 	constructor (ctr: T) {
 		this.ClassConstructor = ctr;
 	}

 	getInstance (...arguments_: ConstructorParameters<T>): InstanceType<T> {
 		const hash = this.calculateArgumentsHash(...arguments_);

 		const existingInstance = this.cache.get(hash);
 		if (existingInstance !== undefined) {
 			return existingInstance;
 		}

 		return new this.ClassConstructor(...arguments_);
 	}

 	private calculateArgumentsHash(...arguments_: any[]): string {
 		// Calculate hash.
 		return 'hash';
 	}
 }

 const articleCache = new InstanceCache(ArticleModel);
 const amazonArticle = articleCache.getInstance('Amazon forests burning!');

  • ReturnType<T> - Obtain the return type of a function type.

    Example

    Playground

     /** Provides every element of the iterable `iter` into the `callback` function and stores the results in an array. */
 function mapIter<
 		Elem,
 		Func extends (elem: Elem) => any,
 		Ret extends ReturnType<Func>
 >(iter: Iterable<Elem>, callback: Func): Ret[] {
 		const mapped: Ret[] = [];

 		for (const elem of iter) {
 				mapped.push(callback(elem));
 		}

 		return mapped;
 }

 const setObject: Set<string> = new Set();
 const mapObject: Map<number, string> = new Map();

 mapIter(setObject, (value: string) => value.indexOf('Foo')); // number[]

 mapIter(mapObject, ([key, value]: [number, string]) => {
 		return key % 2 === 0 ? value : 'Odd';
 }); // string[]

  • InstanceType<T> - Obtain the instance type of a constructor function type.

    Example

    Playground

     class IdleService {
 		doNothing (): void {}
 }

 class News {
 		title: string;
 		content: string;

 		constructor(title: string, content: string) {
 				this.title = title;
 				this.content = content;
 		}
 }

 const instanceCounter: Map<Function, number> = new Map();

 interface Constructor {
 		new(...arguments_: any[]): any;
 }

 // Keep track how many instances of `Constr` constructor have been created.
 function getInstance<
 		Constr extends Constructor,
 		Arguments extends ConstructorParameters<Constr>
 >(constructor: Constr, ...arguments_: Arguments): InstanceType<Constr> {
 		let count = instanceCounter.get(constructor) || 0;

 		const instance = new constructor(...arguments_);

 		instanceCounter.set(constructor, count + 1);

 		console.log(`Created ${count + 1} instances of ${Constr.name} class`);

 		return instance;
 }


 const idleService = getInstance(IdleService);
 // Will log: `Created 1 instances of IdleService class`
 const newsEntry = getInstance(News, 'New ECMAScript proposals!', 'Last month...');
 // Will log: `Created 1 instances of News class`

  • Omit<T, K> - Constructs a type by picking all properties from T and then removing K.

    Example

    Playground

     interface Animal {
 		imageUrl: string;
 		species: string;
 		images: string[];
 		paragraphs: string[];
 }

 // Creates new type with all properties of the `Animal` interface
 // except 'images' and 'paragraphs' properties. We can use this
 // type to render small hover tooltip for a wiki entry list.
 type AnimalShortInfo = Omit<Animal, 'images' | 'paragraphs'>;

 function renderAnimalHoverInfo (animals: AnimalShortInfo[]): HTMLElement {
 		const container = document.createElement('div');
 		// Internal implementation.
 		return container;
 }

  • Uppercase<S extends string> - Transforms every character in a string into uppercase.

    Example 
     type T = Uppercase<'hello'>;  // 'HELLO'

 type T2 = Uppercase<'foo' | 'bar'>;  // 'FOO' | 'BAR'

 type T3<S extends string> = Uppercase<`aB${S}`>;
 type T4 = T3<'xYz'>;  // 'ABXYZ'

 type T5 = Uppercase<string>;  // string
 type T6 = Uppercase<any>;  // any
 type T7 = Uppercase<never>;  // never
 type T8 = Uppercase<42>;  // Error, type 'number' does not satisfy the constraint 'string'

  • Lowercase<S extends string> - Transforms every character in a string into lowercase.

    Example 
     type T = Lowercase<'HELLO'>;  // 'hello'

 type T2 = Lowercase<'FOO' | 'BAR'>;  // 'foo' | 'bar'

 type T3<S extends string> = Lowercase<`aB${S}`>;
 type T4 = T3<'xYz'>;  // 'abxyz'

 type T5 = Lowercase<string>;  // string
 type T6 = Lowercase<any>;  // any
 type T7 = Lowercase<never>;  // never
 type T8 = Lowercase<42>;  // Error, type 'number' does not satisfy the constraint 'string'

  • Capitalize<S extends string> - Transforms the first character in a string into uppercase.

    Example 
     type T = Capitalize<'hello'>;  // 'Hello'

 type T2 = Capitalize<'foo' | 'bar'>;  // 'Foo' | 'Bar'

 type T3<S extends string> = Capitalize<`aB${S}`>;
 type T4 = T3<'xYz'>;  // 'ABxYz'

 type T5 = Capitalize<string>;  // string
 type T6 = Capitalize<any>;  // any
 type T7 = Capitalize<never>;  // never
 type T8 = Capitalize<42>;  // Error, type 'number' does not satisfy the constraint 'string'

  • Uncapitalize<S extends string> - Transforms the first character in a string into lowercase.

    Example 
     type T = Uncapitalize<'Hello'>;  // 'hello'

 type T2 = Uncapitalize<'Foo' | 'Bar'>;  // 'foo' | 'bar'

 type T3<S extends string> = Uncapitalize<`AB${S}`>;
 type T4 = T3<'xYz'>;  // 'aBxYz'

 type T5 = Uncapitalize<string>;  // string
 type T6 = Uncapitalize<any>;  // any
 type T7 = Uncapitalize<never>;  // never
 type T8 = Uncapitalize<42>;  // Error, type 'number' does not satisfy the constraint 'string'

You can find some examples in the TypeScript docs.

Maintainers

License

SPDX-License-Identifier: (MIT OR CC0-1.0)

About

A collection of essential TypeScript types（TypeScript 类型集合）

Resources

Readme

License

CC0-1.0 license

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • TypeScript 99.6%
  • JavaScript 0.4%