type-fest 0.7.1 → 0.10.0

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 {
@@ -368,6 +375,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 +416,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 +510,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

@@ -0,0 +1,72 @@
+import {Primitive} from './basic';
+
+/**
+Create a type from another type with all keys and nested keys set to optional.
+
+Use-cases:
+- Merging a default settings/config object with another object, the second object would be a deep partial of the default object.
+- Mocking and testing complex entities, where populating an entire object with its keys would be redundant in terms of the mock or test.
+
+@example
+```
+import {PartialDeep} from 'type-fest';
+
+const settings: Settings = {
+	textEditor: {
+		fontSize: 14;
+		fontColor: '#000000';
+		fontWeight: 400;
+	}
+	autocomplete: false;
+	autosave: true;
+};
+
+const applySavedSettings = (savedSettings: PartialDeep<Settings>) => {
+	return {...settings, ...savedSettings};
+}
+
+settings = applySavedSettings({textEditor: {fontWeight: 500}});
+```
+*/
+export type PartialDeep<T> = T extends Primitive
+	? Partial<T>
+	: T extends Map<infer KeyType, infer ValueType>
+	? PartialMapDeep<KeyType, ValueType>
+	: T extends Set<infer ItemType>
+	? PartialSetDeep<ItemType>
+	: T extends ReadonlyMap<infer KeyType, infer ValueType>
+	? PartialReadonlyMapDeep<KeyType, ValueType>
+	: T extends ReadonlySet<infer ItemType>
+	? PartialReadonlySetDeep<ItemType>
+	: T extends ((...arguments: any[]) => unknown)
+	? T | undefined
+	: T extends object
+	? PartialObjectDeep<T>
+	: unknown;
+
+/**
+Same as `PartialDeep`, but accepts only `Map`s and  as inputs. Internal helper for `PartialDeep`.
+*/
+interface PartialMapDeep<KeyType, ValueType> extends Map<PartialDeep<KeyType>, PartialDeep<ValueType>> {}
+
+/**
+Same as `PartialDeep`, but accepts only `Set`s as inputs. Internal helper for `PartialDeep`.
+*/
+interface PartialSetDeep<T> extends Set<PartialDeep<T>> {}
+
+/**
+Same as `PartialDeep`, but accepts only `ReadonlyMap`s as inputs. Internal helper for `PartialDeep`.
+*/
+interface PartialReadonlyMapDeep<KeyType, ValueType> extends ReadonlyMap<PartialDeep<KeyType>, PartialDeep<ValueType>> {}
+
+/**
+Same as `PartialDeep`, but accepts only `ReadonlySet`s as inputs. Internal helper for `PartialDeep`.
+*/
+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]>
+};

package/source/readonly-deep.d.ts

@@ -1,7 +1,7 @@
 import {Primitive} from './basic';
 
 /**
-Convert `object`s, `Map`s, `Set`s, and `Array`s and all of their properties/elements into immutable structures recursively.
+Convert `object`s, `Map`s, `Set`s, and `Array`s and all of their keys/elements into immutable structures recursively.
 
 This is useful when a deeply nested structure needs to be exposed as completely immutable, for example, an imported JSON module or when receiving an API response that is passed around.
 
@@ -55,5 +55,5 @@ interface ReadonlySetDeep<ItemType>
 Same as `ReadonlyDeep`, but accepts only `object`s as inputs. Internal helper for `ReadonlyDeep`.
 */
 type ReadonlyObjectDeep<ObjectType extends object> = {
-	readonly [PropertyType in keyof ObjectType]: ReadonlyDeep<ObjectType[PropertyType]>
+	readonly [KeyType in keyof ObjectType]: ReadonlyDeep<ObjectType[KeyType]>
 };

package/source/require-at-least-one.d.ts

@@ -1,7 +1,7 @@
 import {Except} from './except';
 
 /**
-Create a type that requires at least one of the given properties. The remaining properties are kept as is.
+Create a type that requires at least one of the given keys. The remaining keys are kept as is.
 
 @example
 ```
@@ -28,5 +28,5 @@ export type RequireAtLeastOne<ObjectType, KeysType extends keyof ObjectType = ke
 			Required<Pick<ObjectType, Key>>
 		)
 	}[KeysType]
-	// …then, make intersection types by adding the remaining properties to each mapped type.
+	// …then, make intersection types by adding the remaining keys to each mapped type.
 	& Except<ObjectType, KeysType>;

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

@@ -0,0 +1,36 @@
+// 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>>;
+
+/**
+Create a type that requires exactly one of the given keys and disallows more. The remaining keys are kept as is.
+
+Use-cases:
+- Creating interfaces for components that only need one of the keys to display properly.
+- Declaring generic keys in a single place for a single use-case that gets narrowed down via `RequireExactlyOne`.
+
+The caveat with `RequireExactlyOne` is that TypeScript doesn't always know at compile time every key that will exist at runtime. Therefore `RequireExactlyOne` can't do anything to prevent extra keys it doesn't know about.
+
+@example
+```
+import {RequireExactlyOne} from 'type-fest';
+
+type Responder = {
+	text: () => string;
+	json: () => string;
+	secure: boolean;
+};
+
+const responder: RequireExactlyOne<Responder, 'text' | 'json'> = {
+	// Adding a `text` key here would cause a compile error.
+
+	json: () => '{"message": "ok"}',
+	secure: true
+};
+```
+*/
+export type RequireExactlyOne<ObjectType, KeysType extends keyof ObjectType = keyof ObjectType> =
+	{[Key in KeysType]: (
+		Required<Pick<ObjectType, Key>> &
+		Partial<Record<Exclude<KeysType, Key>, never>>
+	)}[KeysType] & _Omit<ObjectType, KeysType>;

package/source/set-optional.d.ts

@@ -0,0 +1,32 @@
+/**
+Create a type that makes the given keys optional. The remaining keys are kept as is. The sister of the `SetRequired` type.
+
+Use-case: You want to define a single model where the only thing that changes is whether or not some of the keys are optional.
+
+@example
+```
+import {SetOptional} from 'type-fest';
+
+type Foo = {
+	a: number;
+	b?: string;
+	c: boolean;
+}
+
+type SomeOptional = SetOptional<Foo, 'b' | 'c'>;
+// type SomeOptional = {
+// 	a: number;
+// 	b?: string; // Was already optional and still is.
+// 	c?: boolean; // Is now optional.
+// }
+```
+*/
+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>> &
+	// 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.
+	infer InferredType
+		? {[KeyType in keyof InferredType]: InferredType[KeyType]}
+		: never;

package/source/set-required.d.ts

@@ -0,0 +1,32 @@
+/**
+Create a type that makes the given keys required. The remaining keys are kept as is. The sister of the `SetOptional` type.
+
+Use-case: You want to define a single model where the only thing that changes is whether or not some of the keys are required.
+
+@example
+```
+import {SetRequired} from 'type-fest';
+
+type Foo = {
+	a?: number;
+	b: string;
+	c?: boolean;
+}
+
+type SomeRequired = SetRequired<Foo, 'b' | 'c'>;
+// type SomeRequired = {
+// 	a?: number;
+// 	b: string; // Was already required and still is.
+// 	c: boolean; // Is now required.
+// }
+```
+*/
+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>> &
+	// 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.
+	infer InferredType
+		? {[KeyType in keyof InferredType]: InferredType[KeyType]}
+		: never;