type-fest 0.5.1 → 0.7.1

package/index.d.ts

@@ -2,13 +2,15 @@
 export * from './source/basic';
 
 // Utilities
-export {Omit} from './source/omit';
+export {Except} from './source/except';
 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 {ReadonlyDeep} from './source/readonly-deep';
 export {LiteralUnion} from './source/literal-union';
+export {Promisable} from './source/promisable';
+export {Opaque} from './source/opaque';
 
 // Miscellaneous
 export {PackageJson} from './source/package-json';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "0.5.1",
+	"version": "0.7.1",
 	"description": "A collection of essential TypeScript types",
 	"license": "(MIT OR CC0-1.0)",
 	"repository": "sindresorhus/type-fest",
@@ -10,7 +10,7 @@
 		"url": "sindresorhus.com"
 	},
 	"engines": {
-		"node": ">=6"
+		"node": ">=8"
 	},
 	"scripts": {
 		"test": "xo && tsd"
@@ -31,15 +31,13 @@
 		"json"
 	],
 	"devDependencies": {
-		"@sindresorhus/tsconfig": "^0.3.0",
-		"@typescript-eslint/eslint-plugin": "^1.8.0",
-		"eslint-config-xo-typescript": "^0.11.0",
+		"@sindresorhus/tsconfig": "^0.4.0",
+		"@typescript-eslint/eslint-plugin": "^1.9.0",
+		"@typescript-eslint/parser": "^1.10.2",
+		"eslint-config-xo-typescript": "^0.14.0",
 		"tsd": "^0.7.3",
 		"xo": "^0.24.0"
 	},
-	"peerDependencies": {
-		"typescript": ">=3.2"
-	},
 	"xo": {
 		"extends": "xo-typescript",
 		"extensions": [

package/readme.md

@@ -30,18 +30,20 @@ PR welcome for additional commonly needed types and docs improvements. Read the
 $ npm install type-fest
 ```
 
+*Requires TypeScript >=3.2*
+
 
 ## Usage
 
 ```ts
-import {Omit} from 'type-fest';
+import {Except} from 'type-fest';
 
 type Foo = {
 	unicorn: string;
 	rainbow: boolean;
 };
 
-type FooWithoutRainbow = Omit<Foo, 'rainbow'>;
+type FooWithoutRainbow = Except<Foo, 'rainbow'>;
 //=> {unicorn: string}
 ```
 
@@ -62,13 +64,15 @@ Click the type names for complete docs.
 
 ### Utilities
 
-- [`Omit`](source/omit.d.ts) - Create a type from an object type without certain keys.
+- [`Except`](source/except.d.ts) - Create a type from an object type without certain keys. This is a stricter version of [`Omit`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-5.html#the-omit-helper-type).
 - [`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.
 - [`ReadonlyDeep`](source/readonly-deep.d.ts) - Create a deeply immutable version of a `object`/`Map`/`Set`/`Array` type.
 - [`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).
+- [`Promisable`](source/promisable.d.ts) - Create a type that represents either the value or the value wrapped in `PromiseLike`.
+- [`Opaque`](source/opaque.d.ts) - Create an [opaque type](https://codemix.com/opaque-types-in-javascript/).
 
 ### Miscellaneous
 

package/source/basic.d.ts

@@ -13,10 +13,11 @@ export type Primitive =
 	| symbol
 	| bigint;
 
+// TODO: Remove the `= unknown` sometime  in the future when most users are on TS 3.5 as it's now the default
 /**
 Matches a [`class` constructor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes).
 */
-export type Class<T = unknown> = new(...arguments_: any[]) => T;
+export type Class<T = unknown, Arguments extends any[] = any[]> = new(...arguments_: Arguments) => T;
 
 /**
 Matches any [typed array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray), like `Uint8Array` or `Float64Array`.
@@ -36,6 +37,8 @@ export type TypedArray =
 
 /**
 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};
 

package/source/except.d.ts

@@ -0,0 +1,22 @@
+/**
+Create a type from an object type without certain keys.
+
+This type is a stricter version of [`Omit`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-5.html#the-omit-helper-type). The `Omit` type does not restrict the omitted keys to be keys present on the given type, while `Except` does. The benefits of a stricter type are avoiding typos and allowing the compiler to pick up on rename refactors automatically.
+
+Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/30825) if you want to have the stricter version as a built-in in TypeScript.
+
+@example
+```
+import {Except} from 'type-fest';
+
+type Foo = {
+	a: number;
+	b: string;
+	c: boolean;
+};
+
+type FooWithoutA = Except<Foo, 'a' | 'c'>;
+//=> {b: string};
+```
+*/
+export type Except<ObjectType, KeysType extends keyof ObjectType> = Pick<ObjectType, Exclude<keyof ObjectType, KeysType>>;

package/source/merge.d.ts

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

package/source/opaque.d.ts

@@ -0,0 +1,40 @@
+/**
+Create an opaque type, which hides its internal details from the public, and can only be created by being used explicitly.
+
+The generic type parameter can be anything. It doesn't have to be an object.
+
+[Read more about opaque types.](https://codemix.com/opaque-types-in-javascript/)
+
+There have been several discussions about adding this feature to TypeScript via the `opaque type` operator, similar to how Flow does it. Unfortunately, nothing has (yet) moved forward:
+	- [Microsoft/TypeScript#15408](https://github.com/Microsoft/TypeScript/issues/15408)
+	- [Microsoft/TypeScript#15807](https://github.com/Microsoft/TypeScript/issues/15807)
+
+@example
+```
+import {Opaque} from 'type-fest';
+
+type AccountNumber = Opaque<number>;
+type AccountBalance = Opaque<number>;
+
+function createAccountNumber(): AccountNumber {
+	return 2 as AccountNumber;
+}
+
+function getMoneyForAccount(accountNumber: AccountNumber): AccountBalance {
+	return 4 as AccountBalance;
+}
+
+// This will compile successfully.
+getMoneyForAccount(createAccountNumber());
+
+// But this won't, because it has to be explicitly passed as an `AccountNumber` type.
+getMoneyForAccount(2);
+
+// You can use opaque values like they aren't opaque too.
+const accountNumber = createAccountNumber();
+
+// This will compile successfully.
+accountNumber + 2;
+```
+*/
+export type Opaque<Type> = Type & {readonly __opaque__: unique symbol};

package/source/package-json.d.ts

@@ -251,6 +251,13 @@ declare namespace PackageJson {
 	}
 
 	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`.
+
+		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.
+		*/
+		flat?: boolean;
+
 		/**
 		Selective version resolutions. Allows the definition of custom package versions inside dependencies without manual edits in the `yarn.lock` file.
 		*/

package/source/promisable.d.ts

@@ -0,0 +1,23 @@
+/**
+Create a type that represents either the value or the value wrapped in `PromiseLike`.
+
+Use-cases:
+- A function accepts a callback that may either return a value synchronously or may return a promised value.
+- This type could be the return type of `Promise#then()`, `Promise#catch()`, and `Promise#finally()` callbacks.
+
+Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/31394) if you want to have this type as a built-in in TypeScript.
+
+@example
+```
+import {Promisable} from 'type-fest';
+
+async function logger(getLogEntry: () => Promisable<string>): Promise<void> {
+    const entry = await getLogEntry();
+    console.log(entry);
+}
+
+logger(() => 'foo');
+logger(() => Promise.resolve('bar'));
+```
+*/
+export type Promisable<T> = T | PromiseLike<T>;

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

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

package/source/omit.d.ts

@@ -1,17 +0,0 @@
-/**
-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>>;