type-fest 0.8.0 → 0.11.0

package/index.d.ts

@@ -15,6 +15,12 @@ export {Promisable} from './source/promisable';
 export {Opaque} from './source/opaque';
 export {SetOptional} from './source/set-optional';
 export {SetRequired} from './source/set-required';
+export {PromiseValue} from './source/promise-value';
+export {AsyncReturnType} from './source/async-return-type';
+export {ConditionalExcept} from './source/conditional-except';
+export {ConditionalKeys} from './source/conditional-keys';
+export {ConditionalPick} from './source/conditional-pick';
 
 // Miscellaneous
 export {PackageJson} from './source/package-json';
+export {TsConfigJson} from './source/tsconfig-json';

package/package.json

@@ -1,9 +1,10 @@
 {
 	"name": "type-fest",
-	"version": "0.8.0",
+	"version": "0.11.0",
 	"description": "A collection of essential TypeScript types",
 	"license": "(MIT OR CC0-1.0)",
 	"repository": "sindresorhus/type-fest",
+	"funding": "https://github.com/sponsors/sindresorhus",
 	"author": {
 		"name": "Sindre Sorhus",
 		"email": "sindresorhus@gmail.com",
@@ -31,13 +32,15 @@
 		"json"
 	],
 	"devDependencies": {
-		"@sindresorhus/tsconfig": "^0.4.0",
-		"@typescript-eslint/eslint-plugin": "^2.2.0",
-		"@typescript-eslint/parser": "^2.2.0",
-		"eslint-config-xo-typescript": "^0.18.0",
+		"@sindresorhus/tsconfig": "^0.7.0",
+		"@typescript-eslint/eslint-plugin": "2.17.0",
+		"@typescript-eslint/parser": "2.17.0",
+		"eslint-config-xo-typescript": "^0.24.1",
 		"tsd": "^0.7.3",
-		"xo": "^0.24.0"
+		"typescript": "3.7.5",
+		"xo": "^0.25.3"
 	},
+	"types": "index.d.ts",
 	"xo": {
 		"extends": "xo-typescript",
 		"extensions": [

package/readme.md

@@ -23,7 +23,6 @@ Either add this package as a dependency or copy-paste the needed types. No credi
 
 PR welcome for additional commonly needed types and docs improvements. Read the [contributing guidelines](.github/contributing.md) first.
 
-
 ## Install
 
 ```
@@ -32,7 +31,6 @@ $ npm install type-fest
 
 *Requires TypeScript >=3.2*
 
-
 ## Usage
 
 ```ts
@@ -47,7 +45,6 @@ type FooWithoutRainbow = Except<Foo, 'rainbow'>;
 //=> {unicorn: string}
 ```
 
-
 ## API
 
 Click the type names for complete docs.
@@ -69,7 +66,7 @@ Click the type names for complete docs.
 - [`Merge`](source/merge.d.ts) - Merge two types into a new type. Keys of the second type overrides keys of the first type.
 - [`MergeExclusive`](source/merge-exclusive.d.ts) - Create a type that has mutually exclusive keys.
 - [`RequireAtLeastOne`](source/require-at-least-one.d.ts) - Create a type that requires at least one of the given keys.
-- [`RequireExactlyOne`](source/require-one.d.ts) - Create a type that requires exactly a single key of the given keys and disallows more.
+- [`RequireExactlyOne`](source/require-exactly-one.d.ts) - Create a type that requires exactly a single key of the given keys and disallows more.
 - [`PartialDeep`](source/partial-deep.d.ts) - Create a deeply optional version of another type. Use [`Partial<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1401-L1406) if you only need one level deep.
 - [`ReadonlyDeep`](source/readonly-deep.d.ts) - Create a deeply immutable version of an `object`/`Map`/`Set`/`Array` type. Use [`Readonly<T>`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1415-L1420) if you only need one level deep.
 - [`LiteralUnion`](source/literal-union.d.ts) - 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](https://github.com/Microsoft/TypeScript/issues/29729).
@@ -77,18 +74,23 @@ Click the type names for complete docs.
 - [`Opaque`](source/opaque.d.ts) - Create an [opaque type](https://codemix.com/opaque-types-in-javascript/).
 - [`SetOptional`](source/set-optional.d.ts) - Create a type that makes the given keys optional.
 - [`SetRequired`](source/set-required.d.ts) - Create a type that makes the given keys required.
+- [`PromiseValue`](source/promise-value.d.ts) - Returns the type that is wrapped inside a `Promise`.
+- [`AsyncReturnType`](source/async-return-type.d.ts) - Unwrap the return type of a function that returns a `Promise`.
+- [`ConditionalKeys`](source/conditional-keys.d.ts) - Extract keys from a shape where values extend the given `Condition` type.
+- [`ConditionalPick`](source/conditional-pick.d.ts) - Like `Pick` except it selects properties from a shape where the values extend the given `Condition` type.
+- [`ConditionalExcept`](source/conditional-except.d.ts) - Like `Omit` except it removes properties from a shape where the values extend the given `Condition` type.
 
 ### Miscellaneous
 
 - [`PackageJson`](source/package-json.d.ts) - Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file).
-
+- [`TsConfigJson`](source/tsconfig-json.d.ts) - Type for [TypeScript's `tsconfig.json` file](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) (TypeScript 3.7).
 
 ## Declined types
 
 *If we decline a type addition, we will make sure to document the better solution here.*
 
 - [`Diff` and `Spread`](https://github.com/sindresorhus/type-fest/pull/7) - The PR 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`](https://github.com/sindresorhus/type-fest/issues/33) - You only save a few characters (`Dictionary<number>` vs `Record<string, number>`) from [`Record`](https://github.com/Microsoft/TypeScript/blob/2961bc3fc0ea1117d4e53bc8e97fa76119bc33e3/src/lib/es5.d.ts#L1429-L1434), which is more flexible and well-known. Also, you shouldn't use an object as a dictionary. We have `Map` in JavaScript now.
 
 ## Tips
 
@@ -102,7 +104,7 @@ There are many advanced types most users don't know about.
 			Example
 	</summary>
 
-	[Playground](https://typescript-play.js.org/?target=6#code/KYOwrgtgBAMg9gcxsAbsANlA3gKClAeQDMiAaPKAEWACMwFz8BRAJxbhcagDEBDAF17ocAXxw4AliH7AWRXgGNgUAHJwAJsADCcEEQkJsFXgAcTK3hGAAuKAGd+LKQgDcFEx363wEGrLf46IjIaOi28EioGG5iOArovHZ2qhrAAIJmAEJgEuiaLEb4Jk4oAsoKuvoIYCwCErq2apo6egZQALyF+FCm5pY2UABETelmg1xFnrYAzAAM8xNQQZGh4cFR6AB0xEQUIm4UFa0IABRHVbYACrws-BJCADwjLVUAfACUXfhEHFBnug4oABrYAATygcCIhBoACtgAp+JsQaC7P9ju9Prhut0joCwCZ1GUAGpCMDKTrnAwAbWRPWSyMhKWalQMAF0Dtj8BIoSd8YSZCT0GSOu1OmAQJp9CBgOpPkc7uBgBzOfwABYSOybSnVWp3XQ0sF04FgxnPFkIVkdKB84mkpUUfCxbEsYD8GogKBqjUBKBiWIAen9UGut3u6CeqReBlePXQQQA7skwMl+HAoMU4CgJJoISB0ODeOmbvwIVC1cAcIGmdpzVApDI5IpgJscNL49WMiZsrl8id3lrzScsD0zBYrLZBgAVOCUOCdwa+95uIA)
+	[Playground](https://www.typescriptlang.org/play/#code/JYOwLgpgTgZghgYwgAgHIHsAmEDC6QzADmyA3gLABQyycADnanALYQBcyAzmFKEQNxUaddFDAcQAV2YAjaIMoBfKlQQAbOJ05osEAIIMAQpOBrsUMkOR1eANziRkCfISKSoD4Pg4ZseAsTIALyW1DS0DEysHADkvvoMMQA0VsKi4sgAzAAMuVaKClY2wPaOknSYDrguADwA0sgQAB6QIJjaANYQAJ7oMDp+LsQAfAAUXd0cdUnI9mo+uv6uANp1ALoAlKHhyGAAFsCcAHTOAW4eYF4gyxNrwbNwago0ypRWp66jH8QcAApwYmAjxq8SWIy2FDCNDA3ToKFBQyIdR69wmfQG1TOhShyBgomQX3w3GQE2Q6IA8jIAFYQBBgI4TTiEs5bTQYsFInrLTbbHZOIlgZDlSqQABqj0kKBC3yINx6a2xfOQwH6o2FVXFaklwSCIUkbQghBAEEwENSfNOlykEGefNe5uhB2O6sgS3GPRmLogmslG1tLxUOKgEDA7hAuydtteryAA)
 
 	```ts
 	interface NodeConfig {
@@ -116,6 +118,10 @@ There are many advanced types most users don't know about.
 					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;
 
@@ -126,7 +132,7 @@ There are many advanced types most users don't know about.
 									continue;
 							}
 
-							this.configuration[key] = updateValue;
+							this.updateConfig(key, updateValue);
 					}
 
 					return this;
@@ -608,19 +614,16 @@ There are many advanced types most users don't know about.
 
 You can find some examples in the [TypeScript docs](https://www.typescriptlang.org/docs/handbook/advanced-types.html#predefined-conditional-types).
 
-
 ## Maintainers
 
 - [Sindre Sorhus](https://github.com/sindresorhus)
 - [Jarek Radosz](https://github.com/CvX)
 - [Dimitri Benin](https://github.com/BendingBender)
 
-
 ## License
 
 (MIT OR CC0-1.0)
 
-
 ---
 
 <div align="center">

package/source/async-return-type.d.ts

@@ -0,0 +1,23 @@
+import {PromiseValue} from './promise-value';
+
+type AsyncFunction = (...args: unknown[]) => Promise<unknown>;
+
+/**
+Unwrap the return type of a function that returns a `Promise`.
+
+There has been [discussion](https://github.com/microsoft/TypeScript/pull/35998) about implementing this type in TypeScript.
+
+@example
+```ts
+import {AsyncReturnType} from 'type-fest';
+import {asyncFunction} from 'api';
+
+// This type resolves to the unwrapped return type of `asyncFunction`.
+type Value = AsyncReturnType<typeof asyncFunction>;
+
+async function doSomething(value: Value) {}
+
+asyncFunction().then(value => doSomething(value));
+```
+*/
+export type AsyncReturnType<Target extends AsyncFunction> = PromiseValue<ReturnType<Target>>;

package/source/basic.d.ts

@@ -40,7 +40,7 @@ Matches a JSON object.
 
 This type can be useful to enforce some input to be JSON-compatible or as a super-type to be extended from. Don't use this as a direct return type as the user would have to double-cast it: `jsonObject as unknown as CustomResponse`. Instead, you could extend your CustomResponse type from it to ensure your type only uses JSON-compatible types: `interface CustomResponse extends JsonObject { … }`.
 */
-export type JsonObject = {[key: string]: JsonValue};
+export type JsonObject = {[Key in string]?: JsonValue};
 
 /**
 Matches a JSON array.

package/source/conditional-except.d.ts

@@ -0,0 +1,43 @@
+import {Except} from './except';
+import {ConditionalKeys} from './conditional-keys';
+
+/**
+Exclude keys from a shape that matches the given `Condition`.
+
+This is useful when you want to create a new type with a specific set of keys from a shape. For example, you might want to exclude all the primitive properties from a class and form a new shape containing everything but the primitive properties.
+
+@example
+```
+import {Primitive, ConditionalExcept} from 'type-fest';
+
+class Awesome {
+	name: string;
+	successes: number;
+	failures: bigint;
+
+	run() {}
+}
+
+type ExceptPrimitivesFromAwesome = ConditionalExcept<Awesome, Primitive>;
+//=> {run: () => void}
+```
+
+@example
+```
+import {ConditionalExcept} from 'type-fest';
+
+interface Example {
+	a: string;
+	b: string | number;
+	c: () => void;
+	d: {};
+}
+
+type NonStringKeysOnly = ConditionalExcept<Example, string>;
+//=> {b: string | number; c: () => void; d: {}}
+```
+*/
+export type ConditionalExcept<Base, Condition> = Except<
+	Base,
+	ConditionalKeys<Base, Condition>
+>;

package/source/conditional-keys.d.ts

@@ -0,0 +1,43 @@
+/**
+Extract the keys from a type where the value type of the key extends the given `Condition`.
+
+Internally this is used for the `ConditionalPick` and `ConditionalExcept` types.
+
+@example
+```
+import {ConditionalKeys} from 'type-fest';
+
+interface Example {
+	a: string;
+	b: string | number;
+	c?: string;
+	d: {};
+}
+
+type StringKeysOnly = ConditionalKeys<Example, string>;
+//=> 'a'
+```
+
+To support partial types, make sure your `Condition` is a union of undefined (for example, `string | undefined`) as demonstrated below.
+
+@example
+```
+type StringKeysAndUndefined = ConditionalKeys<Example, string | undefined>;
+//=> 'a' | 'c'
+```
+*/
+export type ConditionalKeys<Base, Condition> = NonNullable<
+	// Wrap in `NonNullable` to strip away the `undefined` type from the produced union.
+	{
+		// Map through all the keys of the given base type.
+		[Key in keyof Base]:
+			// Pick only keys with types extending the given `Condition` type.
+			Base[Key] extends Condition
+				// Retain this key since the condition passes.
+				? Key
+				// Discard this key since the condition fails.
+				: never;
+
+	// Convert the produced object into a union type of the keys which passed the conditional test.
+	}[keyof Base]
+>;

package/source/conditional-pick.d.ts

@@ -0,0 +1,42 @@
+import {ConditionalKeys} from './conditional-keys';
+
+/**
+Pick keys from the shape that matches the given `Condition`.
+
+This is useful when you want to create a new type from a specific subset of an existing type. For example, you might want to pick all the primitive properties from a class and form a new automatically derived type.
+
+@example
+```
+import {Primitive, ConditionalPick} from 'type-fest';
+
+class Awesome {
+	name: string;
+	successes: number;
+	failures: bigint;
+
+	run() {}
+}
+
+type PickPrimitivesFromAwesome = ConditionalPick<Awesome, Primitive>;
+//=> {name: string; successes: number; failures: bigint}
+```
+
+@example
+```
+import {ConditionalPick} from 'type-fest';
+
+interface Example {
+	a: string;
+	b: string | number;
+	c: () => void;
+	d: {};
+}
+
+type StringKeysOnly = ConditionalPick<Example, string>;
+//=> {a: string}
+```
+*/
+export type ConditionalPick<Base, Condition> = Pick<
+	Base,
+	ConditionalKeys<Base, Condition>
+>;

package/source/opaque.d.ts

@@ -13,9 +13,28 @@ There have been several discussions about adding this feature to TypeScript via
 ```
 import {Opaque} from 'type-fest';
 
-type AccountNumber = Opaque<number>;
-type AccountBalance = Opaque<number>;
+type AccountNumber = Opaque<number, 'AccountNumber'>;
+type AccountBalance = Opaque<number, 'AccountBalance'>;
 
+// The Token parameter allows the compiler to differentiate between types, whereas "unknown" will not. For example, consider the following structures:
+type ThingOne = Opaque<string>;
+type ThingTwo = Opaque<string>;
+
+// To the compiler, these types are allowed to be cast to each other as they have the same underlying type. They are both `string & { __opaque__: unknown }`.
+// To avoid this behaviour, you would instead pass the "Token" parameter, like so.
+type NewThingOne = Opaque<string, 'ThingOne'>;
+type NewThingTwo = Opaque<string, 'ThingTwo'>;
+
+// Now they're completely separate types, so the following will fail to compile.
+function createNewThingOne (): NewThingOne {
+	// As you can see, casting from a string is still allowed. However, you may not cast NewThingOne to NewThingTwo, and vice versa.
+	return 'new thing one' as NewThingOne;
+}
+
+// This will fail to compile, as they are fundamentally different types.
+const thingTwo = createNewThingOne() as NewThingTwo;
+
+// Here's another example of opaque typing.
 function createAccountNumber(): AccountNumber {
 	return 2 as AccountNumber;
 }
@@ -33,8 +52,14 @@ getMoneyForAccount(2);
 // You can use opaque values like they aren't opaque too.
 const accountNumber = createAccountNumber();
 
-// This will compile successfully.
-accountNumber + 2;
+// This will not compile successfully.
+const newAccountNumber = accountNumber + 2;
+
+// As a side note, you can (and should) use recursive types for your opaque types to make them stronger and hopefully easier to type.
+type Person = {
+	id: Opaque<number, Person>;
+	name: string;
+};
 ```
 */
-export type Opaque<Type> = Type & {readonly __opaque__: unique symbol};
+export type Opaque<Type, Token = unknown> = Type & {readonly __opaque__: Token};

package/source/package-json.d.ts

@@ -27,6 +27,8 @@ declare namespace PackageJson {
 		};
 
 	export interface DirectoryLocations {
+		[directoryType: string]: unknown;
+
 		/**
 		Location for executable scripts. Sugar to generate entries in the `bin` property by walking the folder.
 		*/
@@ -56,8 +58,6 @@ declare namespace PackageJson {
 		Location for test files.
 		*/
 		test?: string;
-
-		[directoryType: string]: unknown;
 	}
 
 	export type Scripts = {
@@ -223,9 +223,9 @@ declare namespace PackageJson {
 		esnext?:
 		| string
 		| {
+			[moduleName: string]: string | undefined;
 			main?: string;
 			browser?: string;
-			[moduleName: string]: string | undefined;
 		};
 
 		/**
@@ -236,6 +236,13 @@ declare namespace PackageJson {
 		| {
 			[moduleName: string]: string | false;
 		};
+
+		/**
+		Denote which files in your project are "pure" and therefore safe for Webpack to prune if unused.
+
+		[Read more.](https://webpack.js.org/guides/tree-shaking/)
+		*/
+		sideEffects?: boolean | string[];
 	}
 
 	export interface TypeScriptConfiguration {
@@ -250,11 +257,48 @@ declare namespace PackageJson {
 		typings?: string;
 	}
 
+	/**
+	An alternative configuration for Yarn workspaces.
+	*/
+	export interface WorkspaceConfig {
+		/**
+		An array of workspace pattern strings which contain the workspace packages.
+		*/
+		packages?: WorkspacePattern[];
+
+		/**
+		Designed to solve the problem of packages which break when their `node_modules` are moved to the root workspace directory - a process known as hoisting. For these packages, both within your workspace, and also some that have been installed via `node_modules`, it is important to have a mechanism for preventing the default Yarn workspace behavior. By adding workspace pattern strings here, Yarn will resume non-workspace behavior for any package which matches the defined patterns.
+
+		[Read more](https://classic.yarnpkg.com/blog/2018/02/15/nohoist/)
+		*/
+		nohoist?: WorkspacePattern[];
+	}
+
+	/**
+	A workspace pattern points to a directory or group of directories which contain packages that should be included in the workspace installation process.
+
+	The patterns are handled with [minimatch](https://github.com/isaacs/minimatch).
+
+	@example
+	`docs` → Include the docs directory and install its dependencies.
+	`packages/*` → Include all nested directories within the packages directory, like `packages/cli` and `packages/core`.
+	*/
+	type WorkspacePattern = string;
+
 	export interface YarnConfiguration {
 		/**
-		If your package only allows one version of a given dependency, and you’d like to enforce the same behavior as `yarn install --flat` on the command line, set this to `true`.
+		Used to configure [Yarn workspaces](https://classic.yarnpkg.com/docs/workspaces/).
 
-		Note that if your `package.json` contains `"flat": true` and other packages depend on yours (e.g. you are building a library rather than an application), those other packages will also need `"flat": true` in their `package.json` or be installed with `yarn install --flat` on the command-line.
+		Workspaces allow you to manage multiple packages within the same repository in such a way that you only need to run `yarn install` once to install all of them in a single pass.
+
+		Please note that the top-level `private` property of `package.json` **must** be set to `true` in order to use workspaces.
+		*/
+		workspaces?: WorkspacePattern[] | WorkspaceConfig;
+
+		/**
+		If your package only allows one version of a given dependency, and you’d like to enforce the same behavior as `yarn install --flat` on the command-line, set this to `true`.
+
+		Note that if your `package.json` contains `"flat": true` and other packages depend on yours (e.g. you are building a library rather than an app), those other packages will also need `"flat": true` in their `package.json` or be installed with `yarn install --flat` on the command-line.
 		*/
 		flat?: boolean;
 
@@ -368,6 +412,13 @@ export type PackageJson = {
 	| {
 		type: string;
 		url: string;
+
+		/**
+		Relative path to package.json if it is placed in non-root directory (for example if it is part of a monorepo).
+
+		[Read more.](https://github.com/npm/rfcs/blob/latest/implemented/0010-monorepo-subdirectory-declaration.md)
+		*/
+		directory?: string;
 	};
 
 	/**
@@ -402,6 +453,15 @@ export type PackageJson = {
 	*/
 	peerDependencies?: PackageJson.Dependency;
 
+	/**
+	Indicate peer dependencies that are optional.
+	*/
+	peerDependenciesMeta?: {
+		[packageName: string]: {
+			optional: true;
+		};
+	};
+
 	/**
 	Package names that are bundled when the package is published.
 	*/
@@ -487,11 +547,35 @@ export type PackageJson = {
 	private?: boolean;
 
 	/**
-	 * A set of config values that will be used at publish-time. It's especially handy to set the tag, registry or access, to ensure that a given package is not tagged with 'latest', published to the global public registry or that a scoped module is private by default.
-	 */
+	A set of config values that will be used at publish-time. It's especially handy to set the tag, registry or access, to ensure that a given package is not tagged with 'latest', published to the global public registry or that a scoped module is private by default.
+	*/
 	publishConfig?: {
 		[config: string]: unknown;
 	};
+
+	/**
+	Describes and notifies consumers of a package's monetary support information.
+
+	[Read more.](https://github.com/npm/rfcs/blob/latest/accepted/0017-add-funding-support.md)
+	*/
+	funding?: string | {
+		/**
+		The type of funding.
+		*/
+		type?: LiteralUnion<
+			| 'github'
+			| 'opencollective'
+			| 'patreon'
+			| 'individual'
+			| 'foundation'
+			| 'corporation',
+			string
+		>;
+		/**
+		The URL to the funding page.
+		*/
+		url: string;
+	};
 } &
 PackageJson.NonStandardEntryPoints &
 PackageJson.TypeScriptConfiguration &

package/source/partial-deep.d.ts

@@ -68,5 +68,5 @@ interface PartialReadonlySetDeep<T> extends ReadonlySet<PartialDeep<T>> {}
 Same as `PartialDeep`, but accepts only `object`s as inputs. Internal helper for `PartialDeep`.
 */
 type PartialObjectDeep<ObjectType extends object> = {
-	[KeyType in keyof ObjectType]: PartialDeep<ObjectType[KeyType]> | undefined
+	[KeyType in keyof ObjectType]?: PartialDeep<ObjectType[KeyType]>
 };

package/source/promise-value.d.ts

@@ -0,0 +1,20 @@
+/**
+Returns the type that is wrapped inside a `Promise` type.
+If the type is not a `Promise`, the type itself is returned.
+
+@example
+```
+import {PromiseValue} from 'type-fest';
+
+type AsyncData = Promise<string>;
+let asyncData: PromiseValue<AsyncData> = Promise.resolve('ABC');
+
+type Data = PromiseValue<AsyncData>;
+let data: Data = await asyncData;
+
+// Here's an example that shows how this type reacts to non-Promise types.
+type SyncData = PromiseValue<string>;
+let syncData: SyncData = getSyncData();
+```
+*/
+export type PromiseValue<PromiseType, Otherwise = PromiseType> = PromiseType extends Promise<infer Value> ? Value : Otherwise;