sindresorhus / type-fest

A collection of essential TypeScript types

A collection of essential TypeScript types

---

^{Sindre Sorhus' open source work is supported by the community}

^{Special thanks to:}

Your app, enterprise-ready.

_{Start selling to enterprise customers with just a few lines of code.}
^{Add Single Sign-On (and more) in minutes instead of months.}

---

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.

Install

npm install type-fest

Requires TypeScript >=5.1

Works best with {strict: true} in your tsconfig.

Usage

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

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

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

API

Click the type names for complete docs.

Basic

• Primitive - Matches any primitive value.
• Class - Matches a class.
• Constructor - Matches a class constructor.
• AbstractClass - Matches an abstract class.
• AbstractConstructor - Matches an abstract class constructor.
• TypedArray - Matches any typed array, like Uint8Array or Float64Array.
• ObservableLike - Matches a value that is like an Observable.

Utilities

• EmptyObject - Represents a strictly empty plain object, the {} value.
• NonEmptyObject - Represents an object with at least 1 non-optional key.
• UnknownRecord - Represents an object with unknown value. You probably want this instead of {}.
• UnknownArray - Represents an array with unknown value.
• Except - Create a type from an object type without certain keys. This is a stricter version of Omit.
• Writable - Create a type that strips readonly from the given type. Inverse of Readonly<T>.
• WritableDeep - Create a deeply mutable version of an object/ReadonlyMap/ReadonlySet/ReadonlyArray type. The inverse of ReadonlyDeep<T>. Use Writable<T> if you only need one level deep.
• Merge - Merge two types into a new type. Keys of the second type overrides keys of the first type.
• MergeDeep - Merge two objects or two arrays/tuples recursively into a new type.
• MergeExclusive - Create a type that has mutually exclusive keys.
• OverrideProperties - Override only existing properties of the given type. Similar to Merge, but enforces that the original type has the properties you want to override.
• RequireAtLeastOne - Create a type that requires at least one of the given keys.
• RequireExactlyOne - Create a type that requires exactly a single key of the given keys and disallows more.
• RequireAllOrNone - Create a type that requires all of the given keys or none of the given keys.
• RequireOneOrNone - Create a type that requires exactly a single key of the given keys and disallows more, or none of the given keys.
• SingleKeyObject - Create a type that only accepts an object with a single key.
• RequiredDeep - Create a deeply required version of another type. Use Required<T> if you only need one level deep.
• PickDeep - Pick properties from a deeply-nested object. Use Pick<T> if you only need one level deep.
• OmitDeep - Omit properties from a deeply-nested object. Use Omit<T> if you only need one level deep.
• OmitIndexSignature - Omit any index signatures from the given object type, leaving only explicitly defined properties.
• PickIndexSignature - Pick only index signatures from the given object type, leaving out all explicitly defined properties.
• PartialDeep - Create a deeply optional version of another type. Use Partial<T> if you only need one level deep.
• PartialOnUndefinedDeep - Create a deep version of another type where all keys accepting undefined type are set to optional.
• UndefinedOnPartialDeep - Create a deep version of another type where all optional keys are set to also accept undefined.
• ReadonlyDeep - Create a deeply immutable version of an object/Map/Set/Array type. Use Readonly<T> if you only need one level deep.
• 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.
• SetParameterType - Create a function that replaces some parameters with the given parameters.
• 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.
• KeysOfUnion - Create a union of all keys from a given type, even those exclusive to specific union members.
• 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.
• IntRange - Generate a union of numbers.
• ArrayIndices - Provides valid indices for a constant array or tuple.
• ArrayValues - Provides all values for a constant array or tuple.
• ArraySplice - Creates a new array type by adding or removing elements at a specified index range in the original array.
• SetFieldType - Create a type that changes the type of the given keys.
• Paths - Generate a union of all possible paths to properties in the given object.
• SharedUnionFieldsDeep - Create a type with shared fields from a union of object types, deeply traversing nested structures.
• DistributedOmit - Omits keys from a type, distributing the operation over a union.
• DistributedPick - Picks keys from a type, distributing the operation over a union.

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'

• IsLiteral - Returns a boolean for whether the given type is a literal type.
• IsStringLiteral - Returns a boolean for whether the given type is a string literal type.
• IsNumericLiteral - Returns a boolean for whether the given type is a number or bigint literal type.
• IsBooleanLiteral - Returns a boolean for whether the given type is a true or false literal type.
• IsSymbolLiteral - Returns a boolean for whether the given type is a symbol literal type.
• IsAny - Returns a boolean for whether the given type is any. (Conditional version: IfAny.)
• IsNever - Returns a boolean for whether the given type is never. (Conditional version: IfNever.)
• IsUnknown - Returns a boolean for whether the given type is unknown. (Conditional version: IfUnknown.)
• IsEmptyObject - Returns a boolean for whether the type is strictly equal to an empty plain object, the {} value. (Conditional version: IfEmptyObject)

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.
• StringSlice - Returns a string slice of a given range, just like String#slice().

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.
• ArraySlice - Returns an array slice of a given range, just like Array#slice().
• 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

• PositiveInfinity - Matches the hidden Infinity type.
• NegativeInfinity - Matches the hidden -Infinity type.
• Finite - A finite number.
• Integer - A number that is an integer.
• Float - A number that is not an integer.
• NegativeFloat - A negative (-∞ < x < 0) number that is not an integer.
• Negative - A negative number/bigint (-∞ < x < 0)
• NonNegative - A non-negative number/bigint (0 <= x < ∞).
• NegativeInteger - A negative (-∞ < x < 0) number that is an integer.
• NonNegativeInteger - A non-negative (0 <= x < ∞) number that is an integer.
• IsNegative - Returns a boolean for whether the given number is a negative number.
• GreaterThan - Returns a boolean for whether a given number is greater than another number.
• GreaterThanOrEqual - Returns a boolean for whether a given number is greater than or equal to another number.
• LessThan - Returns a boolean for whether a given number is less than another number.
• LessThanOrEqual - Returns a boolean for whether a given number is less than or equal to another number.
• Sum - Returns the sum of two numbers.
• Subtract - Returns the difference between two numbers.

Change case

• CamelCase - Convert a string literal to camel-case (fooBar).
• CamelCasedProperties - Convert object properties to camel-case (fooBar).
• CamelCasedPropertiesDeep - Convert object properties to camel-case recursively (fooBar).
• KebabCase - Convert a string literal to kebab-case (foo-bar).
• KebabCasedProperties - Convert a object properties to kebab-case recursively (foo-bar).
• KebabCasedPropertiesDeep - Convert object properties to kebab-case (foo-bar).
• PascalCase - Converts a string literal to pascal-case (FooBar)
• PascalCasedProperties - Converts object properties to pascal-case (FooBar)
• PascalCasedPropertiesDeep - Converts object properties to pascal-case (FooBar)
• SnakeCase - Convert a string literal to snake-case (foo_bar).
• SnakeCasedProperties - Convert object properties to snake-case (foo_bar).
• SnakeCasedPropertiesDeep - Convert object properties to snake-case recursively (foo_bar).
• ScreamingSnakeCase - Convert a string literal to screaming-snake-case (FOO_BAR).
• DelimiterCase - Convert a string literal to a custom string delimiter casing.
• DelimiterCasedProperties - Convert object properties to a custom string delimiter casing.
• DelimiterCasedPropertiesDeep - Convert object properties to a custom string delimiter casing recursively.

Miscellaneous

• GlobalThis - Declare locally scoped properties on globalThis.
• PackageJson - Type for npm's package.json file. It also includes support for TypeScript Declaration Files.
• TsConfigJson - Type for TypeScript's tsconfig.json file.

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.

• Prettify- See Simplify
• Expand- See Simplify
• PartialBy - See SetOptional
• RecordDeep- See Schema
• Mutable- See Writable
• RequireOnlyOne - See RequireExactlyOne
• AtMostOne - See RequireOneOrNone
• AllKeys - See KeysOfUnion
• Branded - See Opaque

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

• typed-query-selector - Enhances document.querySelector and document.querySelectorAll with a template literal type that matches element types returned from an HTML element query selector.
• Linter.Config - Definitions for the ESLint configuration schema.

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

• Sindre Sorhus
• Haozheng Li
• Jarek Radosz
• Dimitri Benin
• Pelle Wessman
• Sébastien Mischler

License

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

type-fest's Issues

Proposal: ValueOf

It's a common question and not many know how to do it: https://stackoverflow.com/a/49286056/64949

type ValueOf<T> = T[keyof T];

type Foo = {a: string, b: number};

type ValueOfFoo = ValueOf<Foo>;
// string | number

The code is simple, but remembering the syntax is not. It would also be nice to have it as few know it's possible at all.

Real-world use-case: https://github.com/goodmind/FlowDefinitelyTyped/blob/333ce3a4273848326bfc43827eb4e7aa9a9d7441/types/react-native-vector-icons/FontAwesome5.d.ts

---

We could also consider instead adding a more powerful version that optionally supports picking the keys to get value from:

type ValueOf<T, K extends keyof T = keyof T> = T[K];

type Foo = {a: string, b: number: c: boolean};

type ValueOfFoo = ValueOf<Foo, 'a' | 'c'>;
// string | boolean

AsyncReturnType doesn't work

I'm not sure how AsyncReturnType is supposed to work. If I try it with a basic async function, that takes a string argument & returns it, I get a type error.

Type '(bar: string) => Promise' does not satisfy the constraint 'AsyncFunction'.
Types of parameters 'bar' and 'args' are incompatible.
Type 'unknown' is not assignable to type 'string'

I've set up a Codesandbox that demonstrates this. I'm not sure what Typescript version it's using, it's not listed in the dependencies, but I am getting it with TS v3.8.2 in my local project.

I'm not sure if there is a specific reason not to use any here, but replacing ...args: unknown[] with ...args: any[] in the AsyncFunction definition resolves the error.

Suggestion: NonEmptyArray

The following type looks really interesting:

type NonEmptyArray<A> = A[] & {0: A};

The original discussion was brought up in this thread: gcanti/fp-ts#735

If there's interest I could raise a PR.

How to use `JsonObject`?

const json: JsonObject = await fetchJson(...);
console.log(json.a.b.c);

// => error TS2339: Property 'b' does not exist on type 'string | number | boolean | JsonObject | JsonArray'.
  Property 'b' does not exist on type 'string'.

It seems to be useful for one-level JSON, but after that you'll have to use as JsonObject at every level, if you want to access a deep property (e.g. GraphQL response)

`PackageJson` is not a valid `JsonObject`

Description

The following fails type checking.

import {PackageJson, JsonObject} from 'type-fest';
import {expectType} from 'tsd';

const packageJson: PackageJson = {};

const createPackageJson = () => packageJson;
expectType<JsonObject>(createPackageJson()); // => Error

The error produced is the following.

Argument of type 'PackageJson' is not assignable to parameter of type 'JsonObject'.
  Index signatures are incompatible.
    Type 'unknown' is not assignable to type 'JsonValue'.
      Type 'unknown' is not assignable to type 'JsonArray'.ts(2345)

To fix this we would need to remove unknown from the PackageJson type and replace it with JsonValue since the package.json file only supports valid Json this shouldn't cause any issues.

I'll create a PR shortly.

`Opaque` forces lookup to `any` type because it cannot be used to index `Record` type

I use Opaque type extensively to reduce type errors for strings, but I found out that it has an unexpected behaviour that it cannot be used as a Record's index type.
Please see the example below for a typical setup.

import { Opaque } from 'type-fest';

type UUID = Opaque<string, 'UUID'>
type NormalizedDictionary<T> = Record<UUID, T>

type Foo = { bar: string }

const userEntities: NormalizedDictionary<Foo> = {
  '7dd4a16e-d5ee-454c-b1d0-71e23d9fa70b': { bar: 'John' },
  '6ce31270-31eb-4a72-a9bf-43192d4ab436': { bar: 'Doe' },
}

const johnsId = '7dd4a16e-d5ee-454c-b1d0-71e23d9fa70b' as UUID

const userJohn = userEntities[johnsId]
// the type of userJohn is `any`

Can anyone provide me a way to use an Opaque type to index a Record without sacrificing the type of the value becoming any?

Upvote & Fund

• We're using Polar.sh so you can upvote and help fund this issue.
• The funding will be given to active contributors.
• Thank you in advance for helping prioritize & fund our backlog.

Except not removing keys as Omit does

export interface Identifiable<T> {
  readonly id: T;
}

export interface Entity<ID> extends Identifiable<ID> {
  readonly createdAt: ZonedDateTime;
  modifiedAt: ZonedDateTime;
}

export type EntityOpts<T extends Entity<unknown>> = Omit<
  Partial<T>,
  'id' | 'createdAt' | 'modifiedAt'
>;

replace Omit with Except in this code and all of the "excluded" keys will still be available for use and compile.

> yarn list typescript type-fest && node --version
yarn list v1.22.4
warning Filtering by arguments is deprecated. Please use the pattern option instead.
├─ @google-cloud/[email protected]
│  └─ [email protected]
├─ [email protected]
│  ├─ [email protected]
│  │  └─ [email protected]
│  └─ [email protected]
├─ [email protected]
│  └─ [email protected]
├─ [email protected]
│  ├─ [email protected]
│  │  └─ [email protected]
│  ├─ [email protected]
│  │  └─ [email protected]
│  └─ [email protected]
├─ [email protected]
└─ [email protected]
✨  Done in 1.28s.
v12.16.3

Proposal: DeepPartial

interface Child {
  id: string;
  name: string;
  state: string;
  mother: {
    name: string;
    some: string;
  }
}

function fn(child: Partial<Child>) { }

fn({ name: '' }); // OK
fn({ mother: { name: '' }}); // NO, Property 'some' is missing

But.

type DeepPartial<T> = { [P in keyof T]?: DeepPartial<T[P]> };

function fn(child: DeepPartial<Child>) { }

fn({ name: '' }); // OK
fn({ mother: { name: '' }}); // OK

How about this?

---

IssueHunt Summary

kainiedziela has been rewarded.

Backers (Total: $60.00)

• issuehunt ($60.00)

Submitted pull Requests

• #47 Add PartialDeep type

---

Tips

• Checkout the Issuehunt explorer to discover more funded issues.
• Need some help from other developers? Add your repositories on IssueHunt to raise funds.

---

IssueHunt has been backed by the following sponsors. Become a sponsor

`RequireOnlyOne` type

See #24 and its feedback if you want to tackle this.

Add `WithReturnType` type?

type WithReturnType<
  TFn extends (...args: any) => any,
  TR
> = TFn extends (...args: infer TArgs) => any ? (...args: TArgs) => TR : any;

Creates a new function type that replaces the given function type's return type with the given type.

Use case: functions that return wrapped callbacks, i.e. any generic function in the general form of

(cb: (...args: A) => any) => (...args: A) => B

e.g. here's a React hook:

function useAsync<TFn extends (...args: any) => Promise<any>>(
  asyncFn: TFn
): [
  { loading: boolean; result?: AsyncReturnType<TFn> },
  WithReturnType<TFn, Promise<void>>
] {
  const [state, setState] = React.useState({
    loading: false,
    result: undefined as AsyncReturnType<TFn> | undefined
  });
  return [state, (async (...args: any) => {
    setState({ ...state, loading: true });
    try {
      const result = await asyncFn(...args);
      setState({ ...state, loading: false, result });
    } catch (e) {
      setState({ ...state, loading: false });
    }
  }) as WithReturnType<TFn, Promise<void>>];
}

I'm not sure if this use case is widespread enough but the solution is non-obvious if you're not familiar with conditional types (it's derived from how ReturnType is defined). I can create a PR if there's interest in adding this.

Proposal: Opaque

Please add support for opaque types, like so (here's a one liner):

type Opaque<V> = V & { readonly __opq__: unique symbol };

This would then be used like so:

type AccountNumber = Opaque<number>;
type AccountBalance = Opaque<number>;

function createAccountNumber (): AccountNumber {
    return 2 as AccountNumber;
}

function getMoneyForAccount (accountNumber: AccountNumber): AccountBalance {
    return 4 as AccountBalance;
}

// CompilerError:
getMoneyForAccount(2); 

// CompilerSuccess
getMoneyForAccount(createAccountNumber());

(copied from my gist)

This would be incredibly useful, and the TypeScript developers just don't seem like they're interested in implementing it.

Proposal: Promisable

Some times we are just awaiting a function, so we don't really care if the returned value is actually a promise or not. With Promisable:

type Promisable<T> = T | Promise<T>;

One could write this:

type Foo = () => Promisable<string | number | null>

Rather than:

type Foo = () => string | number | null | Promise<string> | Promise<number> | Promise<null>

It helps write a bit cleaner code. I'm not sure if it's useful enough to be included here, but I thought I'd mention it.

Proposal: OneOrMore

type OneOrMore<T> = T | T[];

lodash also has this type named as Many.

This is useful when you have a complex type:

OneOrMore<Validator<Value> | null>

Upvote & Fund

• We're using Polar.sh so you can upvote and help fund this issue.
• The funding will be given to active contributors.
• Thank you in advance for helping prioritize & fund our backlog.

Docs: Partial Example Error from v3.5.1

Partial Example: error from 3.5.1

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

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

 		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.configuration[key] = updateValue;
 				}

 				return this;
 		}
 }

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

Type 'string | number' is not assignable to type 'string & number'.
  Type 'string' is not assignable to type 'string & number'.
    Type 'string' is not assignable to type 'number'.

playground example

https://www.typescriptlang.org/play/?ts=3.3.3#code/JYOwLgpgTgZghgYwgAgHIHsAmEDC6QzADmyA3gLABQyycADnanALYQBcyAzmFKEQNxUaddFDAcQAV2YAjaIMoBfKlQQAbOJ05osEAIIMAQpOBrsUMkOR1eANziRkCfISKSoD4Pg4ZseAsTIALyW1DS0DEysHADkvvoMMQA0VsKi4sgAzAAMuVaKClbOAUQAFMWuHAAKcGLAcGoAPPH+rgB8AJSh4chgAJ50KC0uxADSEH3ByADWE+gwOn4jAiphNDCiyOX43DMTyPPIAPIyAFYQCGAAdLN9nNslXZqLuMvjfQDaALpdFGvhxV2kjomAcEAAag1JCgQhViB9bl9Cv8aMAFqVgaDIJC1NDgkEQpIQNhCCAIJhfqkek58GBQNCFNTkMpKFSaGAABbAThXOFuDx0-AIiZfKaYsE46FUllUqAQMDuEC9LmcRnMqgsoA

I would submit pull request but my typescript journey is just beginning; nut shell either typescript bug or from 3.5.1 strictness on this is tighter. But for me both types are string | number| so 🤷‍♂

Would you consider migrating isOfType and isObjectOfType ?

The sindresorhus/is library defines isOfType and isObjectOfType (as well as TypedArray, ArrayLike, Primitive, ObservableLike, ...)

Wouldn't be interesting to have all these types declared in type-fest (and make is to use them)?

Cannot find name 'unknown'.

platform: win10

ERROR in node_modules/type-fest/index.d.ts(20,23): error TS2304: Cannot find name 'unknown'.
node_modules/type-fest/index.d.ts(61,30): error TS2304: Cannot find name 'unknown'.
node_modules/type-fest/source/package-json.d.ts(60,28): error TS2304: Cannot find name 'unknown'.
node_modules/type-fest/source/package-json.d.ts(375,24): error TS2304: Cannot find name 'unknown'.
node_modules/type-fest/source/package-json.d.ts(486,21): error TS2304: Cannot find name 'unknown'.
node_modules/type-fest/source/package-json.d.ts(493,17): error TS2304: Cannot find name 'unknown'.

Property 'observable' does not exist on type 'SymbolConstructor'

Getting the following error right after adding type-fest package

Comparison to `ts-essentials`

Hello! Thanks for this great package. I have been using it for a while now. However, recently I stumbled on another similar package: https://github.com/krzkaczor/ts-essentials

Do you have any thoughts on the differences between it and type-fest?

Thank you very much.

Question: is there any way to get the advantages of opaque and other options at the same time?

given

export type OrderPart = SetRequired<Except<Partial<OrderEntity>, 'id'>, 'orderId'>;
export type OrderOnly = Opaque<OrderPart>;

export class OrderAggregateFactory {
  constructor(private readonly em: EntityManager) {}

  order(part: OrderOnly): Promise<OrderEntity> {

if I use it like this... I get the benefits of both

      const orderPart: OrderPart = {
        status: OrderStatus.Open,
        orderId,
      };
      return new OrderAggregateFactory(em).order(orderPart as OrderOnly);

but if I write like the latter, I lose the benefits of SetRequired, and probably other things (this compies)

      return new OrderAggregateFactory(em).order({
        status: OrderStatus.Open,
      } as OrderOnly);

is their a way to write it "like" the latter example? but still have Required and other things cause compile errors?

Upvote & Fund

• We're using Polar.sh so you can upvote and help fund this issue.
• The funding will be given to active contributors.
• Thank you in advance for helping prioritize & fund our backlog.

Proposal: FlipOptional

type OptionalKeys<T> = {
  [K in keyof T]-?: {} extends Pick<T, K> ? K : never
}[keyof T];

type FlipOptional<T> = (Required<Pick<T, OptionalKeys<T>>> &
  Partial<Omit<T, OptionalKeys<T>>>) extends infer O
  ? { [K in keyof O]: O[K] }
  : never;

Taken from https://stackoverflow.com/a/57593506/1154610.

A practical example is a TypeScript equivalent of ESLint rule react/require-default-props.

import React from 'react';

export interface InputProps {
  className?: string;
  name: string;
}

export default class Input extends React.Component<InputProps> {
  static defaultProps: FlipOptional<InputProps> = {
    // className is required for defaultProps.
    className: null
    // name is optional for defaultProps.
  }

  render() {
    const { className, name } = this.props;

    return <input className={className} name={name} />
  }
}

Upvote & Fund

• We're using Polar.sh so you can upvote and help fund this issue.
• The funding will be given to active contributors.
• Thank you in advance for helping prioritize & fund our backlog.

PackageJson - recommendation for extending the interface

The package.json definition is a great start, but going to be impossible to include everything.

We can make PR's for every field that is missing (yarn is missing workspaces, for example), but this could become never-ending, such as supporting package.json-based config for jest.

Instead, maybe it would be useful to document how we recommend developers extend the existing definition to add types they need for their code.

I'm still learning TypeScript, so I'm not sure if the best practice is for developers to provide extended properties in a global PackageJson namespace in a d.ts file, or use generics to pass in someting like PackageJson<extraFields>.

Thoughts?

Upgrade the `tsd` dependency

Add `Stringified` type

See the previous attempt and feedback: #43

Proposal for ModifyType ?

I find myself utilizing this useful type often for overriding a root type's fields with a different type.

https://stackoverflow.com/questions/41285211/overriding-interface-property-type-defined-in-typescript-d-ts-file#answer-55032655

Impl Type

type ModifiedType = Modify<OriginalType, {
  a: number;
  b: number;
}>

Example:

interface OriginalType {
  a: string;
  b: boolean;
  c: number;
}

type ModifiedType  = Modify<OriginalType , {
  a: number;
  b: number;
}>

// ModifiedType = { a: number; b: number; c: number; }

Would you all consider adding this or is there an existing suitable type in here already?

Upvote & Fund

• We're using Polar.sh so you can upvote and help fund this issue.
• The funding will be given to active contributors.
• Thank you in advance for helping prioritize & fund our backlog.

Add `Optional` type

An optional type is really missing in the context of return types,
When a function might a value or not you find yourself piping undefined

type Maybe<T> = T | undefined;

Can be really useful

Upvote & Fund

• We're using Polar.sh so you can upvote and help fund this issue.
• The funding will be given to active contributors.
• Thank you in advance for helping prioritize & fund our backlog.

Difference with other libs?

For example https://github.com/piotrwitek/utility-types
It is worth to develop one tool, I suppose

JsonObject doesn't allow optionals

I want to type something as JsonObject, because the interface defines a request from an API.

So then I use extends JsonObject, but my API has some optionals.

interface Unicorn extends JsonObject {
	unicorn: string;
	rainbow?: string;
}

The compiler will fail with

Property 'unicorn' of type 'string | undefined' is not assignable to string index type 'JsonValue'

The reasoning behind this is that undefined is not serializable and doesn't exist in JSON. But how would someone solve this issue? Or should we change something in the JSON definitions of type-fest?

A possible solution would be to allow undefined in JsonObject.

export type JsonObject = {[key: string]: JsonValue | undefined};

This allows me to add optionals to something which is a JsonObject.

interface Unicorn extends JsonObject {
	unicorn: string;
	rainbow?: string;
}

To me, this kinda makes sense because JSON.stringify({unicorn: '🦄', rainbow: undefined}) results in {"unicorn":"🦄"}, thus allowing undefined in JSON like objects.

Add links to try them in the TypeScript Playground

The Playground now supports automatic type acquisition - so you can showcase your API in a way that people can experiment in, for example here's the README example

Upvote & Fund

• We're using Polar.sh so you can upvote and help fund this issue.
• The funding will be given to active contributors.
• Thank you in advance for helping prioritize & fund our backlog.

Similar project

FYI https://github.com/piotrwitek/utility-types is very similar to this project.

Proposal: ThenArg

Hey there,

would be nice to include the helper type to unwrap a PromiseLike:

e.g.

type ThenArg<T> = T extends Promise<infer U> ? U : T

my main motivation is when using jsdoc in js I often declare a let without any initialisation and assign a value in a later closure (mostly when running mocha tests), e.g.:

describe('some block', () => {
  /** @type {ThenArg<ReturnType<loadData>>} */
  let data; // <-- data is untyped if not defining the @type above
  before('load data', async () => {
    // loadData is typed here and returns a valid type, but data keeps being set to any
    data = await loadData();
  })

  it('has loaded to correct data', () => {
    // ...
  });
})

Proposal: `PlainObject`

Motivation/Use-cases

If you want to model an object that can accept anything as value, you're tempted to use one of the following approach:

const myObject: { [props: string]: any } = { foo: 'bar' }  

or

const myObject: Record<string, any> = { foo: 'bar' }  

The problem being that both { [props: string]: any } and Record<string, any> accept functions and arrays, which I believe in 99% of cases is not what you were trying to model with your type. (Playground showcase here)

Proposal

We could construct a safer type based on the existing primitives of type-fest:

import { Primitive } from 'type-fest'

/**
 * Represents a POJO. Prevents from allowing arrays and functions
 */
export type PlainObject = {
  [x: string]: Primitive | object
}

Playground Example here

Notes

• The fact that it's very easy to construct with the existing type-fest primitives might be a case for not adding it, open for discussion

Upvote & Fund

• We're using Polar.sh so you can upvote and help fund this issue.
• The funding will be given to active contributors.
• Thank you in advance for helping prioritize & fund our backlog.

Proposal: Dictionary

Define

interface Dictionary<T> {
    [key: string]: T;
}

Usage

let v1: Dictionary<number>;
let v2: Dictionary<string>;
let v3: Dictionary<any>;

This is a very common and useful definition, also mentioned in the official documentation.

Rename `Omit`

We managed to convince the TS team to add Omit as a built-in type, unfortunately, they added a loose version, not what we suggested, and they insist on staying with it.

The great thing about user-land code is that we can fix their dumb decisions.

However, that does mean our Omit type will conflict with the native one... But I guess that gives us the opportunity to come up with a better name for it.

I never really found Omit that clear. How about ExcludeProperty or ExcludeKey? I prefer the former. Open to other suggestions.

Proposal: SubType

 type SubType<Base, Condition> = Pick<
     Base,
     {
         [Key in keyof Base]: Base[Key] extends Condition ? Key : never
     }[keyof Base]
 >;

Examples:

var object = {
    a: 1,
    b: true,
    c: () => null,
    d: () => null,
};

type JustMethods = SubType<typeof object, (...args: unknown[]) => unknown>;
// { c: () => null, d: () => null }

JustMethods from #4 can be realized via SubType. But, as I understand, JustProps can't. Maybe it will be possible after microsoft/TypeScript#29317

Documentation improvement request: Merge versus intersection

Recently someone pushed this commit to Got with the following message:

Use Merge as it's stricter than the intersection operator

I came here looking for an explanation on what exactly this means, and found none. I noticed that Merge uses the intersection operator under the hood, but I'd like to understand this better. Thanks.

Relates to #8

Also seems very related to this question I asked on SO recently (in which coincidentally I invented the terminology merged type before noticing the existence of Merge here in type-fest)

Upvote & Fund

• We're using Polar.sh so you can upvote and help fund this issue.
• The funding will be given to active contributors.
• Thank you in advance for helping prioritize & fund our backlog.

Proposal: DeepRecord

A while back while working on a project we needed a generic function to slice all strings of the provided object.

const stringSlicer = <T, U> (data: T, checker: U): T => {};

We wanted the U type the have the same type as the first argument but it had to flatten all the arrays.
So if T was of type

interface T {
	name: string;
	items: {
 		id: string
	}[]
}

U had to be of type

interface U {
	name: number;
	items: {
		id: number;
	}
}

With interface U defining the length of each string. But it shouldn't provide an array for items

proposal

export type DeepRecord<K, T> = {
	[P in keyof K]:
		Exclude<K[P], undefined> extends Array<infer E> ? DeepRecord<E, T> :
		Exclude<K[P], undefined> extends object ? DeepRecord<K[P], T> :
		T;
};

This way we can write the function as following

const stringSlicer = <T> (data: T, checker: DeepRecord<T, number>): T => {};

Proposal: Partial/Complete

This may be a limitation in the type system, but thought I'd drop this proposal here. The idea here is that there should be some way of expressing that P is an object with keys that are a subset of the keys of T, then those keys that are missing on P from T are required to be supplied as U.

interface IComplete {
    a: string;
    b: string
}

function partial<T, P extends Partial<T>>(defaults: P) {
    return function<U extends MissingFrom<T, P>>(remaining: U) {
        const complete: T = { ...defaults, ...remaining };
        return complete;
    }
}

const curried = partial({a:"foo"});
const bar: IComplete = curried({b:"bar"});
const baz: IComplete = curried({b:"baz"});

Upvote & Fund

• We're using Polar.sh so you can upvote and help fund this issue.
• The funding will be given to active contributors.
• Thank you in advance for helping prioritize & fund our backlog.

Proposal: AsyncReturnType

Reason

TypeScript provides ReturnType to infer what type a function returns, but it isn't as as useful when functions return a promise and you want to know what type the promise resolves to.

Proposal

ResolvedType which returns the type of a function that returns a promise, but also works if the function is not a promise.

Example

// Silly simple example
const asyncFunction = async (n: number) => n * 2;

// We have this today
type AsyncFunctionReturns = ReturnType<typeof asyncFunction>;
// => Promise<number>

// This is the proposal
type AsyncFunctionReturns = ResolvedType<typeof asyncFunction>;
// => number

Proof of concept

Not tested extensively, may have bugs!

// For any function, return the returnType or promiseResolved type.
export type ResolvedValue<FuncPromOrValue> = FuncPromOrValue extends (...args: any) => any
    ? ReturnType<FuncPromOrValue> extends Promise<infer Result> // Is a function.
        ? Result // Is a promise, return result from Promise.
        : ReturnType<FuncPromOrValue> // Non-promise function, return result.
    : FuncPromOrValue; // Not a promise or function, return type.

Existing work

I haven't seen anything like this before, but that doesn't mean it doesn't exist. I'm not fluent with other typed languages to know if there's a reason this doesn't exist or better way to implement it.

Proposal: PartialExcept

I've recently made the following type, and I though it might be useful enough to be included here:

type PartialExcept<Object, Keys extends keyof Object> = Partial<Object> & {
  [Key in Keys]: Required<Pick<Object, Key>>[Key]
};

It makes all properties in Object optional, except for the properties specified in Keys, which are required.

Upvote & Fund

• We're using Polar.sh so you can upvote and help fund this issue.
• The funding will be given to active contributors.
• Thank you in advance for helping prioritize & fund our backlog.

`AsyncReturnType` doesn't work with arguments

I'm not able to use this type:

type PromisedStringFunction = (query: string) => Promise<string>;
type ShouldBeAString = AsyncReturnType<PromisedStringFunction>;

I get this error:

Type '(query: string) => Promise<string>' does not satisfy the constraint 'AsyncFunction'.
  Types of parameters 'query' and 'args' are incompatible.
    Type 'unknown' is not assignable to type 'string'.ts(2344)

I had my own AsyncReturnType and it worked well with any, not unknown

Add `Mutable` type

The inverse of the built-in Readonly type.

It can be useful to temporarily use a readonly value or a copy of the value as mutable.

Use-case: https://github.com/sindresorhus/pageres/blob/4a5d05fca19a5fbd2f53842cbf3eb7b1b63bddd2/source/index.ts#L72

Thoughts?

notwoods earned $60.00 by resolving this issue!

• Checkout the Issuehunt explorer to discover more funded issues.
• Need some help from other developers? Add your repositories on Issuehunt to raise funds.

Add examples for the built-in types mentioned in the readme

I made a section in the readme for useful built-in types that many TS devs don't know about. Would be useful to also include some real-world examples of those types in use. It's hard to realize when they would be useful just from their description.

https://github.com/sindresorhus/type-fest#built-in-types

To resolve this issue you should at least add one realistic example for each type.

---

IssueHunt Summary

krnik has been rewarded.

Backers (Total: $60.00)

• issuehunt ($60.00)

Submitted pull Requests

• #35 Built-in types examples

---

Tips

• Checkout the Issuehunt explorer to discover more funded issues.
• Need some help from other developers? Add your repositories on IssueHunt to raise funds.

---

IssueHunt has been backed by the following sponsors. Become a sponsor

Upvote & Fund

• We're using Polar.sh so you can upvote and help fund this issue.
• The funding will be given to active contributors.
• Thank you in advance for helping prioritize & fund our backlog.

Proposal: Constructor

I propose the following "Constructor" interface:

interface Constructor<Class, Args extends any[] = []> {
  new ( ...args: Args ): Class
}

The problem it solves is the following.

Let's say we have the following Foo class:

class Foo {}

If we need to accept a Foo class as an argument we can write something like this:

function fn ( cls: typeof Foo ) {}

But what if Foo is a generic class? Then we can't write something like this:

function fn ( cls: typeof Foo<any> ) {}

And we also can't just write something like this:

function fn ( cls: Foo<any> ) {
  new cls ();
}

Because cls won't be recognized as a constructor and TS will throw the following error:

Cannot use 'new' with an expression whose type lacks a call or construct signature.ts(2351)

Here's where the proposed Constructor interface comes in, with it we can write the following:

class Foo<T1, T2> {}

function fn ( cls: Constructor<Foo<any, any>> ) {
  new cls ();
}

Apparently this has been discussed already in TypeScript's repo, here, and somebody mentioned how Angular also had to define a similar interface.

I've already stumbled on this twice, here and in another library I haven't released yet.

Optional Values of Type

Anyone know if its possible to get the Optional values of a type?

interface A {
  a: string;
  b?: string;
  c?:string;
  d: string;
}

type B = OptionalsOf<A>;

so B becomes something like

type B = {
  b?: string;
  c?: striing;
};

Though for my usecase I will do something like

type B = Required<OptionsOf<A>>;

But I presume that wouldn't make a difference?

Upvote & Fund

• We're using Polar.sh so you can upvote and help fund this issue.
• The funding will be given to active contributors.
• Thank you in advance for helping prioritize & fund our backlog.

`RequireAtLeaseOne` issues

import { RequireAtLeastOne } from 'type-fest';

interface BaseConditionProps {
  when: string;
  is?: any;
  isNot?: any;
  children: (value: any) => React.ReactNode;
}

type ConditionProps = RequireAtLeastOne<BaseConditionProps, 'isNot' | 'is'>;

const Condition: React.FC<ConditionProps> = ({ when, is, isNot, children }) => (  // ERROR HERE
  <Field name={when} subscription={{ value: true }}>
    {({ input: { value } }) => {
      const show = is ? value === is : value !== isNot;
      return show ? children(value) : null;
    }}
  </Field>
);

Typescript complain that

1. Property 'isNot' does not exist on type 'PropsWithChildren<RequireAtLeastOne<BaseConditionProps, "is" | "isNot">>'.ts(2339)
2. Property 'is' does not exist on type 'PropsWithChildren<RequireAtLeastOne<BaseConditionProps, "is" | "isNot">>'.ts(2339)

I had no problem if I use another version that I found in the issue.

import { Except } from 'type-fest';

export type RequireOne<ObjectType, KeysType extends keyof ObjectType = keyof ObjectType> = {
  // For each Key in KeysType make a mapped type
  [Key in KeysType]: (// …by picking that Key's type and making it required
  Required<Pick<ObjectType, Key>> &
    // …and adding the other keys in KeysType as optional and of type `never`
    Partial<Record<Exclude<KeysType, Key>, never>>);
}[KeysType] &
  // …then, make intersection types by adding the remaining properties to each mapped type.
  Except<ObjectType, KeysType>;

Proposal: ExcludeProps

@webstrand came up with this pretty cool type which I modified a bit, basically it's useful when you want to ensure that some properties are not set in an object.

In this real case scenario we want to extend a class instance with an object, but the properties set in said object mustn't override any already known properties, in order to avoid conflicts, so we use ExcludeProps for enforcing this:

// ExcludeProps definition

type ExcludeProps<T> = { [P in keyof T]?: 'Error: You cannot use this particular property name' & number } & { [prop: string]: any; };

// Usage 

class Foo {
  myProp: number = 123;
  protected myProtectedProp: number = 123;
  constructor ( extraProps: ExcludeProps<Foo> ) {
    Object.assign ( this, extraProps );
  }
}

new Foo ({ foo: 123 }); // It works, `foo` is not an excluded property

new Foo ({ myProp: 123 }); // We get an error, `myProp` is not allowed as it conflicts with the already known `myProp` property of Foo

new Foo ({ myProtectedProp: 123 }); // Unfortunately private e protected props aren't properly supported

I thought maybe it could be a decent addition to this repo, or maybe it's not general/useful enough, what do you think?

Upvote & Fund

• We're using Polar.sh so you can upvote and help fund this issue.
• The funding will be given to active contributors.
• Thank you in advance for helping prioritize & fund our backlog.

Proposal: FixedLengthArray

const myArray: FixedLengthArray<number, 3> = [1, 2, 3]

const [a, b, c] = myArray // Ok
const [a, b, c, d] = myArray // Invalid index error

See https://stackoverflow.com/a/59906630/8384910

cc @sindresorhus

Upvote & Fund

• We're using Polar.sh so you can upvote and help fund this issue.
• The funding will be given to active contributors.
• Thank you in advance for helping prioritize & fund our backlog.

Improve documentation and tests

My goal is to have the best documentation for each provided type.

If something is unclear in any of the types, please comment or open a PR to improve it.

Some things you could contribute:

• Fix typos.
• Improved description of the type.
• More examples.
• Provide more real-world use-cases. This helps the user understand where a type might come in handy.
• Add links to relevant discussions and docs/tutorials about a type from around the internet.
• Explain the types.
• More tests.

Upvote & Fund

• We're using Polar.sh so you can upvote and help fund this issue.
• The funding will be given to active contributors.
• Thank you in advance for helping prioritize & fund our backlog.

Possible improvement of Omit

type Omit<ObjectType, Keys> = Pick<
    ObjectType,
    Exclude<keyof ObjectType, Keys extends Primitive ? Keys : keyof Keys>
>

Example:

// Primitive example
type A = Omit<{ a: 1, b: 2, c: 3 }, 'a' | 'b'>
// => { c: 3 }

// Object example
type B = Omit<{ a: 1, b: 2, c: 3 }, {a: true, b: 'a'}>
// => { c: 3 }

What do you think?

Opaque types are interchangeable

Do you have any examples for Opaque? I thought Opaque types weren’t supposed to be interchangeable.

import { Opaque } from 'type-fest';

type AccountNumber = Opaque<number>;
type AccountBalance = Opaque<number>;

function getBalance(accountNumber: AccountNumber): AccountBalance {
  return 101 as AccountBalance;
}

// pass an AccountBalance instead of an AccountNumber
const ab = 42 as AccountBalance;
console.log(getBalance(ab)); 
// expected: should not compile
// actual: gets balance for account 42