type-fest 4.25.0 → 4.26.1

package/index.d.ts

@@ -37,7 +37,7 @@ export type {ReadonlyDeep} from './source/readonly-deep';
 export type {LiteralUnion} from './source/literal-union';
 export type {Promisable} from './source/promisable';
 export type {Arrayable} from './source/arrayable';
-export type {Opaque, UnwrapOpaque, Tagged, GetTagMetadata, UnwrapTagged} from './source/opaque';
+export type {Opaque, UnwrapOpaque, Tagged, GetTagMetadata, UnwrapTagged} from './source/tagged';
 export type {InvariantOf} from './source/invariant-of';
 export type {SetOptional} from './source/set-optional';
 export type {SetReadonly} from './source/set-readonly';
@@ -104,6 +104,7 @@ export type {Spread} from './source/spread';
 export type {IsInteger} from './source/is-integer';
 export type {IsFloat} from './source/is-float';
 export type {TupleToUnion} from './source/tuple-to-union';
+export type {UnionToTuple} from './source/union-to-tuple';
 export type {IntRange} from './source/int-range';
 export type {IsEqual} from './source/is-equal';
 export type {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "4.25.0",
+	"version": "4.26.1",
 	"description": "A collection of essential TypeScript types",
 	"license": "(MIT OR CC0-1.0)",
 	"repository": "sindresorhus/type-fest",

package/readme.md

@@ -151,8 +151,8 @@ Click the type names for complete docs.
 - [`UndefinedOnPartialDeep`](source/undefined-on-partial-deep.d.ts) - Create a deep version of another type where all optional keys are set to also accept `undefined`.
 - [`ReadonlyDeep`](source/readonly-deep.d.ts) - Create a deeply immutable version of an `object`/`Map`/`Set`/`Array` type. Use [`Readonly<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#readonlytype) if you only need one level deep.
 - [`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).
-- [`Tagged`](source/opaque.d.ts) - Create a [tagged type](https://medium.com/@KevinBGreene/surviving-the-typescript-ecosystem-branding-and-type-tagging-6cf6e516523d) that can support [multiple tags](https://github.com/sindresorhus/type-fest/issues/665) and [per-tag metadata](https://medium.com/@ethanresnick/advanced-typescript-tagged-types-improved-with-type-level-metadata-5072fc125fcf). (This replaces the previous [`Opaque`](source/opaque.d.ts) type, which is now deprecated.)
-- [`UnwrapTagged`](source/opaque.d.ts) - Get the untagged portion of a tagged type created with `Tagged`. (This replaces the previous [`UnwrapOpaque`](source/opaque.d.ts) type, which is now deprecated.)
+- [`Tagged`](source/tagged.d.ts) - Create a [tagged type](https://medium.com/@KevinBGreene/surviving-the-typescript-ecosystem-branding-and-type-tagging-6cf6e516523d) that can support [multiple tags](https://github.com/sindresorhus/type-fest/issues/665) and [per-tag metadata](https://medium.com/@ethanresnick/advanced-typescript-tagged-types-improved-with-type-level-metadata-5072fc125fcf). (This replaces the previous [`Opaque`](source/tagged.d.ts) type, which is now deprecated.)
+- [`UnwrapTagged`](source/tagged.d.ts) - Get the untagged portion of a tagged type created with `Tagged`. (This replaces the previous [`UnwrapOpaque`](source/tagged.d.ts) type, which is now deprecated.)
 - [`InvariantOf`](source/invariant-of.d.ts) - Create an [invariant type](https://basarat.gitbook.io/typescript/type-system/type-compatibility#footnote-invariance), which is a type that does not accept supertypes and subtypes.
 - [`SetOptional`](source/set-optional.d.ts) - Create a type that makes the given keys optional.
 - [`SetReadonly`](source/set-readonly.d.ts) - Create a type that makes the given keys readonly.
@@ -283,6 +283,7 @@ type ShouldBeNever = IfAny<'not any', 'not never', 'never'>;
 - [`MultidimensionalReadonlyArray`](source/multidimensional-readonly-array.d.ts) - Create a type that represents a multidimensional readonly array of the given type and dimensions.
 - [`ReadonlyTuple`](source/readonly-tuple.d.ts) - Create a type that represents a read-only tuple of the given type and length.
 - [`TupleToUnion`](source/tuple-to-union.d.ts) - Convert a tuple/array into a union type of its elements.
+- [`UnionToTuple`](source/union-to-tuple.d.ts) - Convert a union type into an unordered tuple type of its elements.
 
 ### Numeric
 
@@ -356,8 +357,8 @@ type ShouldBeNever = IfAny<'not any', 'not never', 'never'>;
 - `RequireOnlyOne`, `OneOf` - See [`RequireExactlyOne`](source/require-exactly-one.d.ts)
 - `AtMostOne` - See [`RequireOneOrNone`](source/require-one-or-none.d.ts)
 - `AllKeys` - See [`KeysOfUnion`](source/keys-of-union.d.ts)
-- `Branded` - See [`Tagged`](source/opaque.d.ts)
-- `Opaque` - See [`Tagged`](source/opaque.d.ts)
+- `Branded` - See [`Tagged`](source/tagged.d.ts)
+- `Opaque` - See [`Tagged`](source/tagged.d.ts)
 - `SetElement` - See [`IterableElement`](source/iterable-element.d.ts)
 - `SetEntry` - See [`IterableElement`](source/iterable-element.d.ts)
 - `SetValues` - See [`IterableElement`](source/iterable-element.d.ts)
@@ -391,6 +392,53 @@ type ShouldBeNever = IfAny<'not any', 'not never', 'never'>;
 
 There are many advanced types most users don't know about.
 
+
+- [`Awaited<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#awaitedtype) - Extract the type of a value that a `Promise` resolves to.
+  <details>
+  <summary>
+  	Example
+  </summary>
+
+  [Playground](https://www.typescriptlang.org/play/?#code/JYOwLgpgTgZghgYwgAgKoGdrIN4FgBQyyAkMACYBcyIArgLYBG0A3AUcSHHRFemFKADmrQiTiCe1ekygiiAXwJtkCADZx06NJigBBAA7AAytABuwJDmXENATxAJkMCGAQALDNAAUNHQElKKUZoAEoqAAUoAHs6YEwAHk8oAD4rUWJiAHpM5AAxF3dkMDcUXywyODA4J2i6IpLkCqqGDQgAOmssnIAVBsQwGjhVZGA6fVUIbnBK4CiQZFjBNzBkVSiogGtV4A2UYriKTuyVOb5kKAh0fVOUAF5kOAB3OGAV51c3LwAiTLhDTLKUEyABJsICAvIQnISF0TiAzk1qvcLlcbm0AFboOZeKFHHIXAZQeaI6EZAk0Ik4EaBACMABpqFxJF8AFJRNzzAAiUQgXwZ4kkAGYAAzIeSkxSiSXKMC2fQofIfCBkJLIe66Z6vZXxABKLgpIG6cogiR0BmMZgsEAA2l93u4kl8ALrJZIiZR2BxOGgOMCzeZuOAgMgTJKcypwLx-C1QcxIKhJc0mWNWhngwK0YJQEJpdj8Wy5mEIU4rQFURXuZWq+5PF4raPJuPte0eHQ+fxkXHpWG6GCQKBOApuITIQGNCMM2xRGgqIPIeWwKJQOqmOACadafr+rToGiFDSj-RNEfFUo6EbgaDwJB0vGz9wnhqImpRb2Es8QBlLhZwDYjuBkGQrz+kMyC6OEfjnBAACONCXGAm5aCAEDKsqHTpPIs4fMgXjQNE2aFhkxx4d+gbBqoQjWJKChKKIxbwqWZqGI2VpqtQECPNo0BJpaSA4tCZEhhAYYRu23HMbxn7IDSUJAA)
+
+  ```ts
+  interface User {
+  	id: number;
+  	name: string;
+  	age: number;
+  }
+
+  class UserApiService {
+  	async fetchUser(userId: number): Promise<User> {
+  		// Fetch the user data from the database.
+  		// The actual implementation might look like this:
+  		// const response = await fetch('/api/user/${userId}');
+  		// const data = response.json();
+  		// return data;
+  		return {
+  			id: 1,
+  			name: 'John Doe',
+  			age: 30
+  		};
+  	}
+  }
+
+  type FetchedUser = Awaited<ReturnType<UserApiService['fetchUser']>>;
+
+  async function handleUserData(apiService: UserApiService, userId: number) {
+  	try {
+  		const user: FetchedUser = await apiService.fetchUser(userId);
+  		// After fetching user data, you can perform various actions such as updating the user interface,
+  		// caching the data for future use, or making additional API requests as needed.
+  	} catch (error) {
+  		// Error handling
+  	}
+  }
+
+  const userApiService = new UserApiService();
+  handleUserData(userApiService, 1);
+  ```
+
 - [`Partial<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype) - Make all properties in `T` optional.
 	<details>
 	<summary>

package/source/exact.d.ts

@@ -53,13 +53,14 @@ onlyAcceptNameImproved(invalidInput); // Compilation error
 @category Utilities
 */
 export type Exact<ParameterType, InputType> =
-	// If the parameter is a primitive, return it as is immediately to avoid it being converted to a complex type
-	ParameterType extends Primitive ? ParameterType
-		// If the parameter is an unknown, return it as is immediately to avoid it being converted to a complex type
-		: IsUnknown<ParameterType> extends true ? unknown
-			// If the parameter is a Function, return it as is because this type is not capable of handling function, leave it to TypeScript
-			: ParameterType extends Function ? ParameterType
-				: IsEqual<ParameterType, InputType> extends true ? ParameterType
+	// Before distributing, check if the two types are equal and if so, return the parameter type immediately
+	IsEqual<ParameterType, InputType> extends true ? ParameterType
+		// If the parameter is a primitive, return it as is immediately to avoid it being converted to a complex type
+		: ParameterType extends Primitive ? ParameterType
+			// If the parameter is an unknown, return it as is immediately to avoid it being converted to a complex type
+			: IsUnknown<ParameterType> extends true ? unknown
+				// If the parameter is a Function, return it as is because this type is not capable of handling function, leave it to TypeScript
+				: ParameterType extends Function ? ParameterType
 					// Convert union of array to array of union: A[] & B[] => (A & B)[]
 					: ParameterType extends unknown[] ? Array<Exact<ArrayElement<ParameterType>, ArrayElement<InputType>>>
 						// In TypeScript, Array is a subtype of ReadonlyArray, so always test Array before ReadonlyArray.

package/source/get.d.ts

@@ -1,4 +1,6 @@
-import type {StringDigit} from './internal';
+import type {StringDigit, ToString} from './internal';
+import type {LiteralStringUnion} from './literal-union';
+import type {Paths} from './paths';
 import type {Split} from './split';
 import type {StringKeyOf} from './string-key-of';
 
@@ -16,7 +18,7 @@ type GetOptions = {
 /**
 Like the `Get` type but receives an array of strings as a path parameter.
 */
-type GetWithPath<BaseType, Keys extends readonly string[], Options extends GetOptions = {}> =
+type GetWithPath<BaseType, Keys, Options extends GetOptions = {}> =
 	Keys extends readonly []
 		? BaseType
 		: Keys extends readonly [infer Head, ...infer Tail]
@@ -187,5 +189,10 @@ Get<Record<string, string>, 'foo', {strict: true}> // => string
 @category Array
 @category Template literal
 */
-export type Get<BaseType, Path extends string | readonly string[], Options extends GetOptions = {}> =
-	GetWithPath<BaseType, Path extends string ? ToPath<Path> : Path, Options>;
+export type Get<
+	BaseType,
+	Path extends
+	| readonly string[]
+	| LiteralStringUnion<ToString<Paths<BaseType, {bracketNotation: false}> | Paths<BaseType, {bracketNotation: true}>>>,
+	Options extends GetOptions = {}> =
+		GetWithPath<BaseType, Path extends string ? ToPath<Path> : Path, Options>;

package/source/literal-union.d.ts

@@ -1,5 +1,7 @@
 import type {Primitive} from './primitive';
 
+export type LiteralStringUnion<T> = LiteralUnion<T, string>;
+
 /**
 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.
 

package/source/opaque.d.ts

@@ -1,252 +1 @@
-declare const tag: unique symbol;
-
-export type TagContainer<Token> = {
-	readonly [tag]: Token;
-};
-
-type Tag<Token extends PropertyKey, TagMetadata> = TagContainer<{[K in Token]: TagMetadata}>;
-
-/**
-Attach a "tag" to an arbitrary type. This allows you to create distinct types, that aren't assignable to one another, for runtime values that would otherwise have the same type. (See examples.)
-
-The generic type parameters can be anything.
-
-Note that `Opaque` is somewhat of a misnomer here, in that, unlike [some alternative implementations](https://github.com/microsoft/TypeScript/issues/4895#issuecomment-425132582), the original, untagged type is not actually hidden. (E.g., functions that accept the untagged type can still be called with the "opaque" version -- but not vice-versa.)
-
-Also note that this implementation is limited to a single tag. If you want to allow multiple tags, use `Tagged` instead.
-
-[Read more about tagged types.](https://medium.com/@KevinBGreene/surviving-the-typescript-ecosystem-branding-and-type-tagging-6cf6e516523d)
-
-There have been several discussions about adding similar features to TypeScript. Unfortunately, nothing has (yet) moved forward:
-	- [Microsoft/TypeScript#202](https://github.com/microsoft/TypeScript/issues/202)
-	- [Microsoft/TypeScript#15408](https://github.com/Microsoft/TypeScript/issues/15408)
-	- [Microsoft/TypeScript#15807](https://github.com/Microsoft/TypeScript/issues/15807)
-
-@example
-```
-import type {Opaque} from 'type-fest';
-
-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;
-}
-
-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.
-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;
-};
-```
-
-@category Type
-@deprecated Use {@link Tagged} instead
-*/
-export type Opaque<Type, Token = unknown> = Type & TagContainer<Token>;
-
-/**
-Revert an opaque or tagged type back to its original type by removing the readonly `[tag]`.
-
-Why is this necessary?
-
-1. Use an `Opaque` type as object keys
-2. Prevent TS4058 error: "Return type of exported function has or is using name X from external module Y but cannot be named"
-
-@example
-```
-import type {Opaque, UnwrapOpaque} from 'type-fest';
-
-type AccountType = Opaque<'SAVINGS' | 'CHECKING', 'AccountType'>;
-
-const moneyByAccountType: Record<UnwrapOpaque<AccountType>, number> = {
-	SAVINGS: 99,
-	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.
-type WontWork = UnwrapOpaque<string>;
-
-// Using a Tagged type will work too.
-type WillWork = UnwrapOpaque<Tagged<number, 'AccountNumber'>>; // number
-```
-
-@category Type
-@deprecated Use {@link UnwrapTagged} instead
-*/
-export type UnwrapOpaque<OpaqueType extends TagContainer<unknown>> =
-	OpaqueType extends Tag<PropertyKey, any>
-		? RemoveAllTags<OpaqueType>
-		: OpaqueType extends Opaque<infer Type, OpaqueType[typeof tag]>
-			? Type
-			: OpaqueType;
-
-/**
-Attach a "tag" to an arbitrary type. This allows you to create distinct types, that aren't assignable to one another, for distinct concepts in your program that should not be interchangeable, even if their runtime values have the same type. (See examples.)
-
-A type returned by `Tagged` can be passed to `Tagged` again, to create a type with multiple tags.
-
-[Read more about tagged types.](https://medium.com/@KevinBGreene/surviving-the-typescript-ecosystem-branding-and-type-tagging-6cf6e516523d)
-
-A tag's name is usually a string (and must be a string, number, or symbol), but each application of a tag can also contain an arbitrary type as its "metadata". See {@link GetTagMetadata} for examples and explanation.
-
-A type `A` returned by `Tagged` is assignable to another type `B` returned by `Tagged` if and only if:
-  - the underlying (untagged) type of `A` is assignable to the underlying type of `B`;
-	- `A` contains at least all the tags `B` has;
-	- and the metadata type for each of `A`'s tags is assignable to the metadata type of `B`'s corresponding tag.
-
-There have been several discussions about adding similar features to TypeScript. Unfortunately, nothing has (yet) moved forward:
-	- [Microsoft/TypeScript#202](https://github.com/microsoft/TypeScript/issues/202)
-	- [Microsoft/TypeScript#4895](https://github.com/microsoft/TypeScript/issues/4895)
-	- [Microsoft/TypeScript#33290](https://github.com/microsoft/TypeScript/pull/33290)
-
-@example
-```
-import type {Tagged} from 'type-fest';
-
-type AccountNumber = Tagged<number, 'AccountNumber'>;
-type AccountBalance = Tagged<number, 'AccountBalance'>;
-
-function createAccountNumber(): AccountNumber {
-	// As you can see, casting from a `number` (the underlying type being tagged) is allowed.
-	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!
-// Critically, you could not accidentally use an `AccountBalance` as an `AccountNumber`.
-getMoneyForAccount(2);
-
-// You can also use tagged values like their underlying, untagged type.
-// I.e., this will compile successfully because an `AccountNumber` can be used as a regular `number`.
-// In this sense, the underlying base type is not hidden, which differentiates tagged types from opaque types in other languages.
-const accountNumber = createAccountNumber() + 2;
-```
-
-@example
-```
-import type {Tagged} from 'type-fest';
-
-// You can apply multiple tags to a type by using `Tagged` repeatedly.
-type Url = Tagged<string, 'URL'>;
-type SpecialCacheKey = Tagged<Url, 'SpecialCacheKey'>;
-
-// You can also pass a union of tag names, so this is equivalent to the above, although it doesn't give you the ability to assign distinct metadata to each tag.
-type SpecialCacheKey2 = Tagged<string, 'URL' | 'SpecialCacheKey'>;
-```
-
-@category Type
-*/
-export type Tagged<Type, TagName extends PropertyKey, TagMetadata = never> = Type & Tag<TagName, TagMetadata>;
-
-/**
-Given a type and a tag name, returns the metadata associated with that tag on that type.
-
-In the example below, one could use `Tagged<string, 'JSON'>` to represent "a string that is valid JSON". That type might be useful -- for instance, it communicates that the value can be safely passed to `JSON.parse` without it throwing an exception. However, it doesn't indicate what type of value will be produced on parse (which is sometimes known). `JsonOf<T>` solves this; it represents "a string that is valid JSON and that, if parsed, would produce a value of type T". The type T is held in the metadata associated with the `'JSON'` tag.
-
-This article explains more about [how tag metadata works and when it can be useful](https://medium.com/@ethanresnick/advanced-typescript-tagged-types-improved-with-type-level-metadata-5072fc125fcf).
-
-@example
-```
-import type {Tagged} from 'type-fest';
-
-type JsonOf<T> = Tagged<string, 'JSON', T>;
-
-function stringify<T>(it: T) {
-  return JSON.stringify(it) as JsonOf<T>;
-}
-
-function parse<T extends JsonOf<unknown>>(it: T) {
-  return JSON.parse(it) as GetTagMetadata<T, 'JSON'>;
-}
-
-const x = stringify({ hello: 'world' });
-const parsed = parse(x); // The type of `parsed` is { hello: string }
-```
-
-@category Type
-*/
-export type GetTagMetadata<Type extends Tag<TagName, unknown>, TagName extends PropertyKey> = Type[typeof tag][TagName];
-
-/**
-Revert a tagged type back to its original type by removing all tags.
-
-Why is this necessary?
-
-1. Use a `Tagged` type as object keys
-2. Prevent TS4058 error: "Return type of exported function has or is using name X from external module Y but cannot be named"
-
-@example
-```
-import type {Tagged, UnwrapTagged} from 'type-fest';
-
-type AccountType = Tagged<'SAVINGS' | 'CHECKING', 'AccountType'>;
-
-const moneyByAccountType: Record<UnwrapTagged<AccountType>, number> = {
-	SAVINGS: 99,
-	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.
-type WontWork = UnwrapTagged<string>;
-```
-
-@category Type
-*/
-export type UnwrapTagged<TaggedType extends Tag<PropertyKey, any>> =
-RemoveAllTags<TaggedType>;
-
-type RemoveAllTags<T> = T extends Tag<PropertyKey, any>
-	? {
-		[ThisTag in keyof T[typeof tag]]: T extends Tagged<infer Type, ThisTag, T[typeof tag][ThisTag]>
-			? RemoveAllTags<Type>
-			: never
-	}[keyof T[typeof tag]]
-	: T;
+export * from './tagged';

package/source/tagged.d.ts

@@ -0,0 +1,256 @@
+declare const tag: unique symbol;
+
+export type TagContainer<Token> = {
+	readonly [tag]: Token;
+};
+
+type Tag<Token extends PropertyKey, TagMetadata> = TagContainer<{[K in Token]: TagMetadata}>;
+
+/**
+Attach a "tag" to an arbitrary type. This allows you to create distinct types, that aren't assignable to one another, for distinct concepts in your program that should not be interchangeable, even if their runtime values have the same type. (See examples.)
+
+A type returned by `Tagged` can be passed to `Tagged` again, to create a type with multiple tags.
+
+[Read more about tagged types.](https://medium.com/@KevinBGreene/surviving-the-typescript-ecosystem-branding-and-type-tagging-6cf6e516523d)
+
+A tag's name is usually a string (and must be a string, number, or symbol), but each application of a tag can also contain an arbitrary type as its "metadata". See {@link GetTagMetadata} for examples and explanation.
+
+A type `A` returned by `Tagged` is assignable to another type `B` returned by `Tagged` if and only if:
+  - the underlying (untagged) type of `A` is assignable to the underlying type of `B`;
+	- `A` contains at least all the tags `B` has;
+	- and the metadata type for each of `A`'s tags is assignable to the metadata type of `B`'s corresponding tag.
+
+There have been several discussions about adding similar features to TypeScript. Unfortunately, nothing has (yet) moved forward:
+	- [Microsoft/TypeScript#202](https://github.com/microsoft/TypeScript/issues/202)
+	- [Microsoft/TypeScript#4895](https://github.com/microsoft/TypeScript/issues/4895)
+	- [Microsoft/TypeScript#33290](https://github.com/microsoft/TypeScript/pull/33290)
+
+@example
+```
+import type {Tagged} from 'type-fest';
+
+type AccountNumber = Tagged<number, 'AccountNumber'>;
+type AccountBalance = Tagged<number, 'AccountBalance'>;
+
+function createAccountNumber(): AccountNumber {
+	// As you can see, casting from a `number` (the underlying type being tagged) is allowed.
+	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!
+// Critically, you could not accidentally use an `AccountBalance` as an `AccountNumber`.
+getMoneyForAccount(2);
+
+// You can also use tagged values like their underlying, untagged type.
+// I.e., this will compile successfully because an `AccountNumber` can be used as a regular `number`.
+// In this sense, the underlying base type is not hidden, which differentiates tagged types from opaque types in other languages.
+const accountNumber = createAccountNumber() + 2;
+```
+
+@example
+```
+import type {Tagged} from 'type-fest';
+
+// You can apply multiple tags to a type by using `Tagged` repeatedly.
+type Url = Tagged<string, 'URL'>;
+type SpecialCacheKey = Tagged<Url, 'SpecialCacheKey'>;
+
+// You can also pass a union of tag names, so this is equivalent to the above, although it doesn't give you the ability to assign distinct metadata to each tag.
+type SpecialCacheKey2 = Tagged<string, 'URL' | 'SpecialCacheKey'>;
+```
+
+@category Type
+*/
+export type Tagged<Type, TagName extends PropertyKey, TagMetadata = never> = Type & Tag<TagName, TagMetadata>;
+
+/**
+Given a type and a tag name, returns the metadata associated with that tag on that type.
+
+In the example below, one could use `Tagged<string, 'JSON'>` to represent "a string that is valid JSON". That type might be useful -- for instance, it communicates that the value can be safely passed to `JSON.parse` without it throwing an exception. However, it doesn't indicate what type of value will be produced on parse (which is sometimes known). `JsonOf<T>` solves this; it represents "a string that is valid JSON and that, if parsed, would produce a value of type T". The type T is held in the metadata associated with the `'JSON'` tag.
+
+This article explains more about [how tag metadata works and when it can be useful](https://medium.com/@ethanresnick/advanced-typescript-tagged-types-improved-with-type-level-metadata-5072fc125fcf).
+
+@example
+```
+import type {Tagged} from 'type-fest';
+
+type JsonOf<T> = Tagged<string, 'JSON', T>;
+
+function stringify<T>(it: T) {
+  return JSON.stringify(it) as JsonOf<T>;
+}
+
+function parse<T extends JsonOf<unknown>>(it: T) {
+  return JSON.parse(it) as GetTagMetadata<T, 'JSON'>;
+}
+
+const x = stringify({ hello: 'world' });
+const parsed = parse(x); // The type of `parsed` is { hello: string }
+```
+
+@category Type
+*/
+export type GetTagMetadata<Type extends Tag<TagName, unknown>, TagName extends PropertyKey> = Type[typeof tag][TagName];
+
+/**
+Revert a tagged type back to its original type by removing all tags.
+
+Why is this necessary?
+
+1. Use a `Tagged` type as object keys
+2. Prevent TS4058 error: "Return type of exported function has or is using name X from external module Y but cannot be named"
+
+@example
+```
+import type {Tagged, UnwrapTagged} from 'type-fest';
+
+type AccountType = Tagged<'SAVINGS' | 'CHECKING', 'AccountType'>;
+
+const moneyByAccountType: Record<UnwrapTagged<AccountType>, number> = {
+	SAVINGS: 99,
+	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.
+type WontWork = UnwrapTagged<string>;
+```
+
+@category Type
+*/
+export type UnwrapTagged<TaggedType extends Tag<PropertyKey, any>> =
+RemoveAllTags<TaggedType>;
+
+type RemoveAllTags<T> = T extends Tag<PropertyKey, any>
+	? {
+		[ThisTag in keyof T[typeof tag]]: T extends Tagged<infer Type, ThisTag, T[typeof tag][ThisTag]>
+			? RemoveAllTags<Type>
+			: never
+	}[keyof T[typeof tag]]
+	: T;
+
+/**
+Note: The `Opaque` type is deprecated in favor of `Tagged`.
+
+Attach a "tag" to an arbitrary type. This allows you to create distinct types, that aren't assignable to one another, for runtime values that would otherwise have the same type. (See examples.)
+
+The generic type parameters can be anything.
+
+Note that `Opaque` is somewhat of a misnomer here, in that, unlike [some alternative implementations](https://github.com/microsoft/TypeScript/issues/4895#issuecomment-425132582), the original, untagged type is not actually hidden. (E.g., functions that accept the untagged type can still be called with the "opaque" version -- but not vice-versa.)
+
+Also note that this implementation is limited to a single tag. If you want to allow multiple tags, use `Tagged` instead.
+
+[Read more about tagged types.](https://medium.com/@KevinBGreene/surviving-the-typescript-ecosystem-branding-and-type-tagging-6cf6e516523d)
+
+There have been several discussions about adding similar features to TypeScript. Unfortunately, nothing has (yet) moved forward:
+	- [Microsoft/TypeScript#202](https://github.com/microsoft/TypeScript/issues/202)
+	- [Microsoft/TypeScript#15408](https://github.com/Microsoft/TypeScript/issues/15408)
+	- [Microsoft/TypeScript#15807](https://github.com/Microsoft/TypeScript/issues/15807)
+
+@example
+```
+import type {Opaque} from 'type-fest';
+
+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;
+}
+
+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.
+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;
+};
+```
+
+@category Type
+@deprecated Use {@link Tagged} instead
+*/
+export type Opaque<Type, Token = unknown> = Type & TagContainer<Token>;
+
+/**
+Note: The `UnwrapOpaque` type is deprecated in favor of `UnwrapTagged`.
+
+Revert an opaque or tagged type back to its original type by removing the readonly `[tag]`.
+
+Why is this necessary?
+
+1. Use an `Opaque` type as object keys
+2. Prevent TS4058 error: "Return type of exported function has or is using name X from external module Y but cannot be named"
+
+@example
+```
+import type {Opaque, UnwrapOpaque} from 'type-fest';
+
+type AccountType = Opaque<'SAVINGS' | 'CHECKING', 'AccountType'>;
+
+const moneyByAccountType: Record<UnwrapOpaque<AccountType>, number> = {
+	SAVINGS: 99,
+	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.
+type WontWork = UnwrapOpaque<string>;
+
+// Using a Tagged type will work too.
+type WillWork = UnwrapOpaque<Tagged<number, 'AccountNumber'>>; // number
+```
+
+@category Type
+@deprecated Use {@link UnwrapTagged} instead
+*/
+export type UnwrapOpaque<OpaqueType extends TagContainer<unknown>> =
+	OpaqueType extends Tag<PropertyKey, any>
+		? RemoveAllTags<OpaqueType>
+		: OpaqueType extends Opaque<infer Type, OpaqueType[typeof tag]>
+			? Type
+			: OpaqueType;

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

@@ -0,0 +1,54 @@
+import type {IsNever} from './is-never';
+import type {UnionToIntersection} from './union-to-intersection';
+
+/**
+Returns the last element of a union type.
+
+@example
+```
+type Last = LastOfUnion<1 | 2 | 3>;
+//=> 3
+```
+*/
+type LastOfUnion<T> =
+UnionToIntersection<T extends any ? () => T : never> extends () => (infer R)
+	? R
+	: never;
+
+/**
+Convert a union type into an unordered tuple type of its elements.
+
+This can be useful when you have objects with a finite set of keys and want a type defining only the allowed keys, but do not want to repeat yourself.
+
+@example
+```
+import type {UnionToTuple} from 'type-fest';
+
+type Numbers = 1 | 2 | 3;
+type NumbersTuple = UnionToTuple<Numbers>;
+//=> [1, 2, 3]
+```
+
+@example
+```
+import type {UnionToTuple} from 'type-fest';
+
+const pets = {
+  dog: '🐶',
+  cat: '🐱',
+  snake: '🐍',
+};
+
+type Pet = keyof typeof pets;
+//=> 'dog' | 'cat' | 'snake'
+
+const petList = Object.keys(pets) as UnionToTuple<Pet>;
+//=> ['dog', 'cat', 'snake']
+```
+
+@category Array
+*/
+export type UnionToTuple<T, L = LastOfUnion<T>> =
+IsNever<T> extends false
+	? [...UnionToTuple<Exclude<T, L>>, L]
+	: [];