type-fest 0.4.1 → 0.6.0

package/index.d.ts

@@ -2,12 +2,14 @@
 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';
 
 // Miscellaneous
 export {PackageJson} from './source/package-json';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "0.4.1",
+	"version": "0.6.0",
 	"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,10 +31,11 @@
 		"json"
 	],
 	"devDependencies": {
-		"@sindresorhus/tsconfig": "^0.3.0",
-		"@typescript-eslint/eslint-plugin": "^1.5.0",
-		"eslint-config-xo-typescript": "^0.10.0",
-		"tsd": "^0.7.2",
+		"@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"
 	},
 	"xo": {

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,12 +64,14 @@ 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.
-- [`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).
+- [`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`.
 
 ### Miscellaneous
 
@@ -78,6 +82,8 @@ Click the type names for complete docs.
 
 *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.
+
 
 ## Tips
 

package/source/basic.d.ts

@@ -1,3 +1,5 @@
+/// <reference lib="esnext"/>
+
 // 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).
@@ -8,8 +10,10 @@ export type Primitive =
 	| string
 	| number
 	| boolean
-	| symbol;
+	| 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).
 */
@@ -27,10 +31,14 @@ export type TypedArray =
 	| Int32Array
 	| Uint32Array
 	| Float32Array
-	| Float64Array;
+	| Float64Array
+	| BigInt64Array
+	| BigUint64Array;
 
 /**
 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/mutable.d.ts

@@ -19,4 +19,4 @@ 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/package-json.d.ts

@@ -202,7 +202,7 @@ declare namespace PackageJson {
 		postrestart?: string;
 	} & {
 		[scriptName: string]: string;
-	}
+	};
 
 	/**
 	Dependencies of the package. The version range is a string which has one or more space-separated descriptors. Dependencies can also be identified with a tarball or Git URL.
@@ -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/readonly-deep.d.ts

@@ -0,0 +1,59 @@
+import {Primitive} from './basic';
+
+/**
+Convert `object`s, `Map`s, `Set`s, and `Array`s and all of their properties/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.
+
+Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/13923) if you want to have this type as a built-in in TypeScript.
+
+@example
+```
+// data.json
+{
+	"foo": ["bar"]
+}
+
+// main.ts
+import {ReadonlyDeep} from 'type-fest';
+import dataJson = require('./data.json');
+
+const data: ReadonlyDeep<typeof dataJson> = dataJson;
+
+export default data;
+
+// test.ts
+import data from './main';
+
+data.foo.push('bar');
+//=> error TS2339: Property 'push' does not exist on type 'readonly string[]'
+```
+*/
+export type ReadonlyDeep<T> = T extends Primitive | ((...arguments: any[]) => unknown)
+	? T
+	: T extends ReadonlyMap<infer KeyType, infer ValueType>
+	? ReadonlyMapDeep<KeyType, ValueType>
+	: T extends ReadonlySet<infer ItemType>
+	? ReadonlySetDeep<ItemType>
+	: T extends object
+	? ReadonlyObjectDeep<T>
+	: unknown;
+
+/**
+Same as `ReadonlyDeep`, but accepts only `ReadonlyMap`s as inputs. Internal helper for `ReadonlyDeep`.
+*/
+interface ReadonlyMapDeep<KeyType, ValueType>
+	extends ReadonlyMap<ReadonlyDeep<KeyType>, ReadonlyDeep<ValueType>> {}
+
+/**
+Same as `ReadonlyDeep`, but accepts only `ReadonlySet`s as inputs. Internal helper for `ReadonlyDeep`.
+*/
+interface ReadonlySetDeep<ItemType>
+	extends ReadonlySet<ReadonlyDeep<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]>
+};

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>>;