type-fest 5.1.0 → 5.3.0

package/source/tagged.d.ts

@@ -38,15 +38,14 @@ function createAccountNumber(): AccountNumber {
 	return 2 as AccountNumber;
 }
 
-function getMoneyForAccount(accountNumber: AccountNumber): AccountBalance {
-	return 4 as AccountBalance;
-}
+declare function getMoneyForAccount(accountNumber: AccountNumber): AccountBalance;
 
 // This will compile successfully.
 getMoneyForAccount(createAccountNumber());
 
 // But this won't, because it has to be explicitly passed as an `AccountNumber` type!
 // Critically, you could not accidentally use an `AccountBalance` as an `AccountNumber`.
+// @ts-expect-error
 getMoneyForAccount(2);
 
 // You can also use tagged values like their underlying, untagged type.
@@ -80,19 +79,19 @@ This article explains more about [how tag metadata works and when it can be usef
 
 @example
 ```
-import type {Tagged} from 'type-fest';
+import type {Tagged, GetTagMetadata} from 'type-fest';
 
 type JsonOf<T> = Tagged<string, 'JSON', T>;
 
 function stringify<T>(it: T) {
-  return JSON.stringify(it) as JsonOf<T>;
+	return JSON.stringify(it) as JsonOf<T>;
 }
 
 function parse<T extends JsonOf<unknown>>(it: T) {
-  return JSON.parse(it) as GetTagMetadata<T, 'JSON'>;
+	return JSON.parse(it) as GetTagMetadata<T, 'JSON'>;
 }
 
-const x = stringify({ hello: 'world' });
+const x = stringify({hello: 'world'});
 const parsed = parse(x); // The type of `parsed` is { hello: string }
 ```
 
@@ -116,13 +115,14 @@ type AccountType = Tagged<'SAVINGS' | 'CHECKING', 'AccountType'>;
 
 const moneyByAccountType: Record<UnwrapTagged<AccountType>, number> = {
 	SAVINGS: 99,
-	CHECKING: 0.1
+	CHECKING: 0.1,
 };
 
 // Without UnwrapTagged, the following expression would throw a type error.
 const money = moneyByAccountType.SAVINGS; // TS error: Property 'SAVINGS' does not exist
 
 // Attempting to pass an non-Tagged type to UnwrapTagged will raise a type error.
+// @ts-expect-error
 type WontWork = UnwrapTagged<string>;
 ```
 
@@ -174,12 +174,13 @@ 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 {
+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.
+// @ts-expect-error
 const thingTwo = createNewThingOne() as NewThingTwo;
 
 // Here's another example of opaque typing.
@@ -187,14 +188,13 @@ function createAccountNumber(): AccountNumber {
 	return 2 as AccountNumber;
 }
 
-function getMoneyForAccount(accountNumber: AccountNumber): AccountBalance {
-	return 4 as AccountBalance;
-}
+declare function getMoneyForAccount(accountNumber: AccountNumber): AccountBalance;
 
 // This will compile successfully.
 getMoneyForAccount(createAccountNumber());
 
 // But this won't, because it has to be explicitly passed as an `AccountNumber` type.
+// @ts-expect-error
 getMoneyForAccount(2);
 
 // You can use opaque values like they aren't opaque too.
@@ -233,16 +233,18 @@ type AccountType = Opaque<'SAVINGS' | 'CHECKING', 'AccountType'>;
 
 const moneyByAccountType: Record<UnwrapOpaque<AccountType>, number> = {
 	SAVINGS: 99,
-	CHECKING: 0.1
+	CHECKING: 0.1,
 };
 
 // Without UnwrapOpaque, the following expression would throw a type error.
 const money = moneyByAccountType.SAVINGS; // TS error: Property 'SAVINGS' does not exist
 
 // Attempting to pass an non-Opaque type to UnwrapOpaque will raise a type error.
+// @ts-expect-error
 type WontWork = UnwrapOpaque<string>;
 
 // Using a Tagged type will work too.
+// @ts-expect-error
 type WillWork = UnwrapOpaque<Tagged<number, 'AccountNumber'>>; // number
 ```
 

package/source/trim.d.ts

@@ -17,7 +17,7 @@ Remove leading and trailing spaces from a string.
 ```
 import type {Trim} from 'type-fest';
 
-Trim<' foo '>
+type Example = Trim<' foo '>;
 //=> 'foo'
 ```
 

package/source/tuple-of.d.ts

@@ -22,6 +22,8 @@ type TicTacToeBoard = TupleOf<3, TupleOf<3, 'X' | 'O' | null>>;
 
 @example
 ```
+import type {TupleOf} from 'type-fest';
+
 type Range<Start extends number, End extends number> = Exclude<keyof TupleOf<End>, keyof TupleOf<Start>>;
 
 type ZeroToFour = Range<0, 5>;

package/source/tuple-to-object.d.ts

@@ -10,6 +10,8 @@ Note: Tuple labels are [lost in the transformation process](https://stackoverflo
 
 @example
 ```
+import type {TupleToObject} from 'type-fest';
+
 type Example1 = TupleToObject<[number, string, boolean]>;
 //=> { 0: number; 1: string; 2: boolean }
 

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

@@ -21,7 +21,7 @@ type RequestBody = {
 };
 
 function verifyRequestBody(body: unknown): body is RequestBody {
-	const deliverTo = (body as any).deliverTo;
+	const {deliverTo} = (body as any);
 	return typeof body === 'object' && body !== null && verifyDestination(deliverTo);
 }
 ```
@@ -37,10 +37,11 @@ type Destination = typeof destinations[number];
 
 const erroringType = new Set(['a', 'b', 'c']);
 
+// @ts-expect-error
 type ErroringType = typeof erroringType[number];
 //=> Type 'Set<string>' has no matching index signature for type 'number'. ts(2537)
 
-const numberBool: { [n: number]: boolean } = { 1: true };
+const numberBool: {[n: number]: boolean} = {1: true};
 
 type NumberBool = typeof numberBool[number];
 //=> boolean

package/source/undefined-on-partial-deep.d.ts

@@ -12,18 +12,19 @@ Use-cases:
 ```
 import type {UndefinedOnPartialDeep} from 'type-fest';
 
-interface Settings {
+type Settings = {
 	optionA: string;
 	optionB?: number;
 	subOption: {
 		subOptionA: boolean;
 		subOptionB?: boolean;
-	}
+	};
 };
 
 const testSettingsA: Settings = {
 	optionA: 'foo',
 	optionB: undefined, // TypeScript error if `exactOptionalPropertyTypes` is true.
+	// @ts-expect-error
 	subOption: {
 		subOptionA: true,
 		subOptionB: undefined, // TypeScript error if `exactOptionalPropertyTypes` is true
@@ -32,10 +33,10 @@ const testSettingsA: Settings = {
 
 const testSettingsB: UndefinedOnPartialDeep<Settings> = {
 	optionA: 'foo',
-	optionB: undefined, // 👉 `optionB` can be set to undefined now.
+	optionB: undefined, // `optionB` can be set to `undefined` now.
 	subOption: {
 		subOptionA: true,
-		subOptionB: undefined, // 👉 `subOptionB` can be set to undefined now.
+		subOptionB: undefined, // `subOptionB` can be set to `undefined` now.
 	},
 };
 ```

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

@@ -13,34 +13,6 @@ 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 type {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}
-```
-
 @category Type
 */
 export type UnionToIntersection<Union> = (

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

@@ -36,9 +36,9 @@ type NumbersTuple = UnionToTuple<Numbers>;
 import type {UnionToTuple} from 'type-fest';
 
 const pets = {
-  dog: '🐶',
-  cat: '🐱',
-  snake: '🐍',
+	dog: '🐶',
+	cat: '🐱',
+	snake: '🐍',
 };
 
 type Pet = keyof typeof pets;

package/source/value-of.d.ts

@@ -5,36 +5,16 @@ Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/31438)
 
 @example
 ```
-// data.json
-{
-	'foo': 1,
-	'bar': 2,
-	'biz': 3
-}
-
-// main.ts
 import type {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.d.ts';
 
-getData('foo');
-//=> 1
+type A = ValueOf<{id: number; name: string; active: boolean}>;
+//=> number | string | boolean
 
-onlyBar('foo');
-//=> TypeError ...
+type B = ValueOf<{id: number; name: string; active: boolean}, 'name'>;
+//=> string
 
-onlyBar('bar');
-//=> 2
+type C = ValueOf<{id: number; name: string; active: boolean}, 'id' | 'name'>;
+//=> number | string
 ```
 
 @category Object

package/source/words.d.ts

@@ -28,6 +28,8 @@ export type WordsOptions = {
 
 	@example
 	```
+	import type {Words} from 'type-fest';
+
 	type Example1 = Words<'p2pNetwork', {splitOnNumbers: true}>;
 	//=> ["p", "2", "p", "Network"]
 

package/source/writable-deep.d.ts

@@ -23,7 +23,7 @@ writableDeepFoo.b = ['something'];
 
 Note that types containing overloaded functions are not made deeply writable due to a [TypeScript limitation](https://github.com/microsoft/TypeScript/issues/29732).
 
-@see Writable
+@see {@link Writable}
 @category Object
 @category Array
 @category Set

package/source/writable-keys-of.d.ts

@@ -9,12 +9,12 @@ This is useful when you want to create a new type that contains writable keys on
 ```
 import type {WritableKeysOf} from 'type-fest';
 
-interface User {
+type User = {
 	name: string;
 	surname: string;
 
 	readonly id: number;
-}
+};
 
 type UpdateRequest<Entity extends object> = Pick<Entity, WritableKeysOf<Entity>>;
 

package/source/writable.d.ts

@@ -32,6 +32,7 @@ type Foo = {
 
 const writableFoo: Writable<Foo> = {a: 1, b: ['2'], c: true};
 writableFoo.a = 3;
+// @ts-expect-error
 writableFoo.b[0] = 'new value'; // Will still fail as the value of property "b" is still a readonly type.
 writableFoo.b = ['something']; // Will work as the "b" property itself is no longer readonly.
 
@@ -44,6 +45,7 @@ type SomeWritable = Writable<Foo, 'b' | 'c'>;
 
 // Also supports array
 const readonlyArray: readonly number[] = [1, 2, 3];
+// @ts-expect-error
 readonlyArray.push(4); // Will fail as the array itself is readonly.
 const writableArray: Writable<typeof readonlyArray> = readonlyArray as Writable<typeof readonlyArray>;
 writableArray.push(4); // Will work as the array itself is now writable.