type-fest 0.2.0 → 0.4.1

package/index.d.ts

@@ -1,130 +1,13 @@
+// Basic
+export * from './source/basic';
+
+// Utilities
+export {Omit} from './source/omit';
+export {Mutable} from './source/mutable';
+export {Merge} from './source/merge';
+export {MergeExclusive} from './source/merge-exclusive';
+export {RequireAtLeastOne} from './source/require-at-least-one';
+export {LiteralUnion} from './source/literal-union';
+
+// Miscellaneous
 export {PackageJson} from './source/package-json';
-
-// TODO: Add more examples
-
-// TODO: This can just be `export type Primitive = not object` when the `not` keyword is out.
-/**
-Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
-*/
-export type Primitive =
-	| null
-	| undefined
-	| string
-	| number
-	| boolean
-	| symbol;
-
-/**
-Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
-*/
-export type Class<T = unknown> = new(...arguments_: any[]) => T;
-
-/**
-Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
-*/
-export type TypedArray =
-	| Int8Array
-	| Uint8Array
-	| Uint8ClampedArray
-	| Int16Array
-	| Uint16Array
-	| Int32Array
-	| Uint32Array
-	| Float32Array
-	| Float64Array;
-
-/**
-Matches a JSON object.
-*/
-export type JsonObject = {[key: string]: JsonValue};
-
-/**
-Matches a JSON array.
-*/
-export interface JsonArray extends Array<JsonValue> {} // eslint-disable-line @typescript-eslint/no-empty-interface
-
-/**
-Matches any valid JSON value.
-*/
-export type JsonValue = string | number | boolean | null | JsonObject | JsonArray;
-
-/**
-Matches a value that is like an [Observable](https://github.com/tc39/proposal-observable).
-*/
-export interface ObservableLike {
-	subscribe(observer: (value: unknown) => void): void;
-	[Symbol.observable](): ObservableLike;
-}
-
-/**
-Create a type from an object type without certain keys.
-
-@example
-```
-import {Omit} from 'type-fest';
-
-type Foo = {
-	a: number;
-	b: string;
-};
-
-type FooWithoutA = Omit<Foo, 'a'>;
-//=> {b: string};
-```
-
-I'm surprised this one is not built-in. It seems [other people agree](https://github.com/Microsoft/TypeScript/issues/12215#issuecomment-420919470). Please open new issues on TypeScript about making it built-in.
-*/
-export type Omit<ObjectType, KeysType extends keyof ObjectType> = Pick<ObjectType, Exclude<keyof ObjectType, KeysType>>;
-
-/**
-Merge two types into a new type. Keys of the second type overrides keys of the first type.
-
-@example
-```
-import {Merge} from 'type-fest';
-
-type Foo = {
-	a: number;
-	b: string;
-};
-
-type Bar = {
-	b: number;
-};
-
-const ab: Merge<Foo, Bar> = {a: 1, b: 2};
-```
-*/
-export type Merge<FirstType, SecondType> = Omit<FirstType, Extract<keyof FirstType, keyof SecondType>> & SecondType;
-
-/**
-Allows creating a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union.
-
-Currently, when a union type of a primitive type is combined with literal types, TypeScript loses all information about the combined literals. Thus, when such type is used in an IDE with autocompletion, no suggestions are made for the declared literals.
-
-This type is a workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729). It will be removed as soon as it's not needed anymore.
-
-@example
-```
-import {LiteralUnion} from 'type-fest';
-
-// Before
-
-type Pet = 'dog' | 'cat' | string;
-
-const pet: Pet = '';
-// Start typing in your TypeScript-enabled IDE.
-// You **will not** get auto-completion for `dog` and `cat` literals.
-
-// After
-
-type Pet2 = LiteralUnion<'dog' | 'cat', string>;
-
-const pet: Pet2 = '';
-// You **will** get auto-completion for `dog` and `cat` literals.
-```
- */
-export type LiteralUnion<
-	LiteralType extends BaseType,
-	BaseType extends Primitive
-> = LiteralType | (BaseType & {_?: never});

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "0.2.0",
+	"version": "0.4.1",
 	"description": "A collection of essential TypeScript types",
 	"license": "(MIT OR CC0-1.0)",
 	"repository": "sindresorhus/type-fest",
@@ -13,7 +13,7 @@
 		"node": ">=6"
 	},
 	"scripts": {
-		"test": "xo && tsd-check"
+		"test": "xo && tsd"
 	},
 	"files": [
 		"index.d.ts",
@@ -31,9 +31,10 @@
 		"json"
 	],
 	"devDependencies": {
-		"@typescript-eslint/eslint-plugin": "^1.4.2",
-		"eslint-config-xo-typescript": "^0.8.0",
-		"tsd-check": "^0.3.0",
+		"@sindresorhus/tsconfig": "^0.3.0",
+		"@typescript-eslint/eslint-plugin": "^1.5.0",
+		"eslint-config-xo-typescript": "^0.10.0",
+		"tsd": "^0.7.2",
 		"xo": "^0.24.0"
 	},
 	"xo": {
@@ -42,7 +43,8 @@
 			"ts"
 		],
 		"rules": {
-			"import/no-unresolved": "off"
+			"import/no-unresolved": "off",
+			"@typescript-eslint/indent": "off"
 		}
 	}
 }

package/readme.md

@@ -48,27 +48,30 @@ type FooWithoutRainbow = Omit<Foo, 'rainbow'>;
 
 ## API
 
-See the [types file](index.d.ts) for complete docs.
+Click the type names for complete docs.
 
 ### Basic
 
-- `Primitive` - Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
-- `Class` - Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
-- `TypedArray` - Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
-- `JsonObject` - Matches a JSON object.
-- `JsonArray` - Matches a JSON array.
-- `JsonValue` - Matches any valid JSON value.
-- `ObservableLike` - Matches a value that is like an [Observable](https://github.com/tc39/proposal-observable).
+- [`Primitive`](source/basic.d.ts) - Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
+- [`Class`](source/basic.d.ts) - Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
+- [`TypedArray`](source/basic.d.ts) - Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
+- [`JsonObject`](source/basic.d.ts) - Matches a JSON object.
+- [`JsonArray`](source/basic.d.ts) - Matches a JSON array.
+- [`JsonValue`](source/basic.d.ts) - Matches any valid JSON value.
+- [`ObservableLike`](source/basic.d.ts) - Matches a value that is like an [Observable](https://github.com/tc39/proposal-observable).
 
 ### Utilities
 
-- `Omit` - Create a type from an object type without certain keys.
-- `Merge` - Merge two types into a new type. Keys of the second type overrides keys of the first type.
-- `LiteralUnion` - Allows creating 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).
+- [`Omit`](source/omit.d.ts) - Create a type from an object type without certain keys.
+- [`Mutable`](source/mutable.d.ts) - Convert an object with `readonly` properties into a mutable object. Inverse of `Readonly<T>`.
+- [`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 properties.
+- [`RequireAtLeastOne`](source/require-at-least-one.d.ts) - Create a type that requires at least one of the given properties.
+- [`LiteralUnion`](source/literal-union.d.ts) - Allows creating 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).
 
 ### Miscellaneous
 
-- `PackageJson` - Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file).
+- [`PackageJson`](source/package-json.d.ts) - Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file).
 
 
 ## Declined types
@@ -98,6 +101,13 @@ 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)

package/source/basic.d.ts

@@ -0,0 +1,59 @@
+// TODO: This can just be `export type Primitive = not object` when the `not` keyword is out.
+/**
+Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
+*/
+export type Primitive =
+	| null
+	| undefined
+	| string
+	| number
+	| boolean
+	| symbol;
+
+/**
+Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
+*/
+export type Class<T = unknown> = new(...arguments_: any[]) => T;
+
+/**
+Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
+*/
+export type TypedArray =
+	| Int8Array
+	| Uint8Array
+	| Uint8ClampedArray
+	| Int16Array
+	| Uint16Array
+	| Int32Array
+	| Uint32Array
+	| Float32Array
+	| Float64Array;
+
+/**
+Matches a JSON object.
+*/
+export type JsonObject = {[key: string]: JsonValue};
+
+/**
+Matches a JSON array.
+*/
+export interface JsonArray extends Array<JsonValue> {}
+
+/**
+Matches any valid JSON value.
+*/
+export type JsonValue = string | number | boolean | null | JsonObject | JsonArray;
+
+declare global {
+	interface SymbolConstructor {
+		readonly observable: symbol;
+	}
+}
+
+/**
+Matches a value that is like an [Observable](https://github.com/tc39/proposal-observable).
+*/
+export interface ObservableLike {
+	subscribe(observer: (value: unknown) => void): void;
+	[Symbol.observable](): ObservableLike;
+}

package/source/literal-union.d.ts

@@ -0,0 +1,33 @@
+import {Primitive} from './basic';
+
+/**
+Allows creating a union type by combining primitive types and literal types without sacrificing auto-completion in IDEs for the literal type part of the union.
+
+Currently, when a union type of a primitive type is combined with literal types, TypeScript loses all information about the combined literals. Thus, when such type is used in an IDE with autocompletion, no suggestions are made for the declared literals.
+
+This type is a workaround for [Microsoft/TypeScript#29729](https://github.com/Microsoft/TypeScript/issues/29729). It will be removed as soon as it's not needed anymore.
+
+@example
+```
+import {LiteralUnion} from 'type-fest';
+
+// Before
+
+type Pet = 'dog' | 'cat' | string;
+
+const pet: Pet = '';
+// Start typing in your TypeScript-enabled IDE.
+// You **will not** get auto-completion for `dog` and `cat` literals.
+
+// After
+
+type Pet2 = LiteralUnion<'dog' | 'cat', string>;
+
+const pet: Pet2 = '';
+// You **will** get auto-completion for `dog` and `cat` literals.
+```
+ */
+export type LiteralUnion<
+	LiteralType extends BaseType,
+	BaseType extends Primitive
+> = LiteralType | (BaseType & {_?: never});

package/source/merge-exclusive.d.ts

@@ -0,0 +1,39 @@
+// Helper type. Not useful on its own.
+type Without<FirstType, SecondType> = {[KeyType in Exclude<keyof FirstType, keyof SecondType>]?: never};
+
+/**
+Create a type that has mutually exclusive properties.
+
+This type was inspired by [this comment](https://github.com/Microsoft/TypeScript/issues/14094#issuecomment-373782604).
+
+This type works with a helper type, called `Without`. `Without<FirstType, SecondType>` produces a type that has only keys from `FirstType` which are not present on `SecondType` and sets the value type for these keys to `never`. This helper type is then used in `MergeExclusive` to remove keys from either `FirstType` or `SecondType`.
+
+@example
+```
+import {MergeExclusive} from 'type-fest';
+
+interface ExclusiveVariation1 {
+	exclusive1: boolean;
+}
+
+interface ExclusiveVariation2 {
+	exclusive2: string;
+}
+
+type ExclusiveOptions = MergeExclusive<ExclusiveVariation1, ExclusiveVariation2>;
+
+let exclusiveOptions: ExclusiveOptions;
+
+exclusiveOptions = {exclusive1: true};
+//=> Works
+exclusiveOptions = {exclusive2: 'hi'};
+//=> Works
+exclusiveOptions = {exclusive1: true, exclusive2: 'hi'};
+//=> Error
+```
+*/
+export type MergeExclusive<FirstType, SecondType> =
+	(FirstType | SecondType) extends object ?
+		(Without<FirstType, SecondType> & SecondType) | (Without<SecondType, FirstType> & FirstType) :
+		FirstType | SecondType;
+

package/source/merge.d.ts

@@ -0,0 +1,22 @@
+import {Omit} from './omit';
+
+/**
+Merge two types into a new type. Keys of the second type overrides keys of the first type.
+
+@example
+```
+import {Merge} from 'type-fest';
+
+type Foo = {
+	a: number;
+	b: string;
+};
+
+type Bar = {
+	b: number;
+};
+
+const ab: Merge<Foo, Bar> = {a: 1, b: 2};
+```
+*/
+export type Merge<FirstType, SecondType> = Omit<FirstType, Extract<keyof FirstType, keyof SecondType>> & SecondType;

package/source/mutable.d.ts

@@ -0,0 +1,22 @@
+/**
+Convert an object with `readonly` properties into a mutable object. Inverse of `Readonly<T>`.
+
+This can be used to [store and mutate options within a class](https://github.com/sindresorhus/pageres/blob/4a5d05fca19a5fbd2f53842cbf3eb7b1b63bddd2/source/index.ts#L72), [edit `readonly` objects within tests](https://stackoverflow.com/questions/50703834), and [construct a `readonly` object within a function](https://github.com/Microsoft/TypeScript/issues/24509).
+
+@example
+```
+import {Mutable} from 'type-fest';
+
+type Foo = {
+	readonly a: number;
+	readonly b: string;
+};
+
+const mutableFoo: Mutable<Foo> = {a: 1, b: '2'};
+mutableFoo.a = 3;
+```
+*/
+export type Mutable<ObjectType> = {
+	// For each `Key` in the keys of `ObjectType`, make a mapped type by removing the `readonly` modifier from the property.
+	-readonly [KeyType in keyof ObjectType]: ObjectType[KeyType];
+}

package/source/omit.d.ts

@@ -0,0 +1,17 @@
+/**
+Create a type from an object type without certain keys.
+
+@example
+```
+import {Omit} from 'type-fest';
+
+type Foo = {
+	a: number;
+	b: string;
+};
+
+type FooWithoutA = Omit<Foo, 'a'>;
+//=> {b: string};
+```
+*/
+export type Omit<ObjectType, KeysType extends keyof ObjectType> = Pick<ObjectType, Exclude<keyof ObjectType, KeysType>>;

package/source/package-json.d.ts

@@ -307,10 +307,10 @@ export type PackageJson = {
 	/**
 	The licenses for the package.
 	*/
-	licenses?: {
+	licenses?: Array<{
 		type?: string;
 		url?: string;
-	}[];
+	}>;
 
 	author?: PackageJson.Person;
 
@@ -420,7 +420,7 @@ export type PackageJson = {
 	/**
 	Operating systems the module runs on.
 	*/
-	os?: LiteralUnion<
+	os?: Array<LiteralUnion<
 		| 'aix'
 		| 'darwin'
 		| 'freebsd'
@@ -436,12 +436,12 @@ export type PackageJson = {
 		| '!sunos'
 		| '!win32',
 		string
-	>[];
+	>>;
 
 	/**
 	CPU architectures the module runs on.
 	*/
-	cpu?: LiteralUnion<
+	cpu?: Array<LiteralUnion<
 		| 'arm'
 		| 'arm64'
 		| 'ia32'
@@ -465,7 +465,7 @@ export type PackageJson = {
 		| '!x32'
 		| '!x64',
 		string
-	>[];
+	>>;
 
 	/**
 	If set to `true`, a warning will be shown if package is installed locally. Useful if the package is primarily a command-line application that should be installed globally.

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

@@ -0,0 +1,32 @@
+import {Omit} from './omit';
+
+/**
+Create a type that requires at least one of the given properties. The remaining properties are kept as is.
+
+@example
+```
+import {RequireAtLeastOne} from 'type-fest';
+
+type Responder = {
+	text?: () => string;
+	json?: () => string;
+
+	secure?: boolean;
+};
+
+const responder: RequireAtLeastOne<Responder, 'text' | 'json'> = {
+	json: () => '{"message": "ok"}',
+	secure: true
+};
+```
+*/
+export type RequireAtLeastOne<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>>
+		)
+	}[KeysType]
+	// …then, make intersection types by adding the remaining properties to each mapped type.
+	& Omit<ObjectType, KeysType>;