type-fest 0.10.0 → 0.13.1

package/index.d.ts

@@ -15,6 +15,14 @@ export {Promisable} from './source/promisable';
 export {Opaque} from './source/opaque';
 export {SetOptional} from './source/set-optional';
 export {SetRequired} from './source/set-required';
+export {ValueOf} from './source/value-of';
+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';
+export {UnionToIntersection} from './source/union-to-intersection';
+export {Stringified} from './source/stringified';
 
 // Miscellaneous
 export {PackageJson} from './source/package-json';

package/license

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)
+Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https:/sindresorhus.com)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "0.10.0",
+	"version": "0.13.1",
 	"description": "A collection of essential TypeScript types",
 	"license": "(MIT OR CC0-1.0)",
 	"repository": "sindresorhus/type-fest",
@@ -8,10 +8,10 @@
 	"author": {
 		"name": "Sindre Sorhus",
 		"email": "sindresorhus@gmail.com",
-		"url": "sindresorhus.com"
+		"url": "https://sindresorhus.com"
 	},
 	"engines": {
-		"node": ">=8"
+		"node": ">=10"
 	},
 	"scripts": {
 		"test": "xo && tsd"
@@ -32,22 +32,14 @@
 		"json"
 	],
 	"devDependencies": {
-		"@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",
-		"typescript": "3.7.5",
-		"xo": "^0.25.3"
+		"tsd": "^0.11.0",
+		"xo": "^0.28.2"
 	},
+	"types": "index.d.ts",
 	"xo": {
-		"extends": "xo-typescript",
-		"extensions": [
-			"ts"
-		],
 		"rules": {
-			"import/no-unresolved": "off",
-			"@typescript-eslint/indent": "off"
+			"@typescript-eslint/indent": "off",
+			"func-call-spacing": "off"
 		}
 	}
 }

package/readme.md

@@ -74,6 +74,14 @@ 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.
+- [`ValueOf`](source/value-of.d.ts) - Create a union of the given object's values, and optionally specify which keys to get the values from.
+- [`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.
+- [`UnionToIntersection`](source/union-to-intersection.d.ts) - Convert a union type to an intersection type.
+- [`Stringified`](source/stringified.d.ts) - Create a type with the keys of the given type changed to `string` type.
 
 ### Miscellaneous
 
@@ -86,6 +94,8 @@ Click the type names for complete docs.
 
 - [`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.
+- [`SubType`](https://github.com/sindresorhus/type-fest/issues/22) - The type is powerful, but lacks good use-cases and is prone to misuse.
+- [`ExtractProperties` and `ExtractMethods`](https://github.com/sindresorhus/type-fest/pull/4) - The types violate the single responsibility principle. Instead, refine your types into more granular type hierarchies.
 
 ## Tips
 

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

@@ -0,0 +1,23 @@
+import {PromiseValue} from './promise-value';
+
+type AsyncFunction = (...args: any[]) => 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/package-json.d.ts

@@ -257,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/).
+
+		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 application), those other packages will also need `"flat": true` in their `package.json` or be installed with `yarn install --flat` on the command-line.
+		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;
 

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;

package/source/require-exactly-one.d.ts

@@ -1,5 +1,4 @@
 // TODO: Remove this when we target TypeScript >=3.5.
-// eslint-disable-next-line @typescript-eslint/generic-type-naming
 type _Omit<T, K extends keyof any> = Pick<T, Exclude<keyof T, K>>;
 
 /**

package/source/set-optional.d.ts

@@ -1,3 +1,5 @@
+import {Except} from './except';
+
 /**
 Create a type that makes the given keys optional. The remaining keys are kept as is. The sister of the `SetRequired` type.
 
@@ -23,7 +25,7 @@ type SomeOptional = SetOptional<Foo, 'b' | 'c'>;
 */
 export type SetOptional<BaseType, Keys extends keyof BaseType = keyof BaseType> =
 	// Pick just the keys that are not optional from the base type.
-	Pick<BaseType, Exclude<keyof BaseType, Keys>> &
+	Except<BaseType, Keys> &
 	// Pick the keys that should be optional from the base type and make them optional.
 	Partial<Pick<BaseType, Keys>> extends
 	// If `InferredType` extends the previous, then for each key, use the inferred type key.

package/source/set-required.d.ts

@@ -1,3 +1,5 @@
+import {Except} from './except';
+
 /**
 Create a type that makes the given keys required. The remaining keys are kept as is. The sister of the `SetOptional` type.
 
@@ -23,7 +25,7 @@ type SomeRequired = SetRequired<Foo, 'b' | 'c'>;
 */
 export type SetRequired<BaseType, Keys extends keyof BaseType = keyof BaseType> =
 	// Pick just the keys that are not required from the base type.
-	Pick<BaseType, Exclude<keyof BaseType, Keys>> &
+	Except<BaseType, Keys> &
 	// Pick the keys that should be required from the base type and make them required.
 	Required<Pick<BaseType, Keys>> extends
 	// If `InferredType` extends the previous, then for each key, use the inferred type key.

package/source/stringified.d.ts

@@ -0,0 +1,21 @@
+/**
+Create a type with the keys of the given type changed to `string` type.
+
+Use-case: Changing interface values to strings in order to use them in a form model.
+
+@example
+```
+import {Stringified} from 'type-fest';
+
+type Car {
+	model: string;
+	speed: number;
+}
+
+const carForm: Stringified<Car> = {
+	model: 'Foo',
+	speed: '101'
+};
+```
+*/
+export type Stringified<ObjectType> = {[KeyType in keyof ObjectType]: string};

package/source/union-to-intersection.d.ts

@@ -0,0 +1,58 @@
+/**
+Convert a union type to an intersection type using [distributive conditional types](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types).
+
+Inspired by [this Stack Overflow answer](https://stackoverflow.com/a/50375286/2172153).
+
+@example
+```
+import {UnionToIntersection} from 'type-fest';
+
+type Union = {the(): void} | {great(arg: string): void} | {escape: boolean};
+
+type Intersection = UnionToIntersection<Union>;
+//=> {the(): void; great(arg: string): void; escape: boolean};
+```
+
+A more applicable example which could make its way into your library code follows.
+
+@example
+```
+import {UnionToIntersection} from 'type-fest';
+
+class CommandOne {
+	commands: {
+		a1: () => undefined,
+		b1: () => undefined,
+	}
+}
+
+class CommandTwo {
+	commands: {
+		a2: (argA: string) => undefined,
+		b2: (argB: string) => undefined,
+	}
+}
+
+const union = [new CommandOne(), new CommandTwo()].map(instance => instance.commands);
+type Union = typeof union;
+//=> {a1(): void; b1(): void} | {a2(argA: string): void; b2(argB: string): void}
+
+type Intersection = UnionToIntersection<Union>;
+//=> {a1(): void; b1(): void; a2(argA: string): void; b2(argB: string): void}
+```
+*/
+export type UnionToIntersection<Union> = (
+	// `extends any` is always going to be the case and is used to convert the
+	// `Union` into a [distributive conditional
+	// type](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types).
+	Union extends unknown
+		// The union type is used as the only argument to a function since the union
+		// of function arguments is an intersection.
+		? (distributedUnion: Union) => void
+		// This won't happen.
+		: never
+		// Infer the `Intersection` type since TypeScript represents the positional
+		// arguments of unions of functions as an intersection of the union.
+	) extends ((mergedIntersection: infer Intersection) => void)
+		? Intersection
+		: never;

package/source/value-of.d.ts

@@ -0,0 +1,40 @@
+/**
+Create a union of the given object's values, and optionally specify which keys to get the values from.
+
+Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/31438) if you want to have this type as a built-in in TypeScript.
+
+@example
+```
+// data.json
+{
+	'foo': 1,
+	'bar': 2,
+	'biz': 3
+}
+
+// main.ts
+import {ValueOf} from 'type-fest';
+import data = require('./data.json');
+
+export function getData(name: string): ValueOf<typeof data> {
+	return data[name];
+}
+
+export function onlyBar(name: string): ValueOf<typeof data, 'bar'> {
+	return data[name];
+}
+
+// file.ts
+import {getData, onlyBar} from './main';
+
+getData('foo');
+//=> 1
+
+onlyBar('foo');
+//=> TypeError ...
+
+onlyBar('bar');
+//=> 2
+```
+*/
+export type ValueOf<ObjectType, ValueType extends keyof ObjectType = keyof ObjectType> = ObjectType[ValueType];