type-fest 4.2.0 → 4.3.0

package/index.d.ts

@@ -6,6 +6,7 @@ export * from './source/observable-like';
 
 // Utilities
 export type {EmptyObject, IsEmptyObject} from './source/empty-object';
+export type {NonEmptyObject} from './source/non-empty-object';
 export type {UnknownRecord} from './source/unknown-record';
 export type {Except} from './source/except';
 export type {TaggedUnion} from './source/tagged-union';
@@ -26,7 +27,7 @@ export type {PartialOnUndefinedDeep, PartialOnUndefinedDeepOptions} from './sour
 export type {ReadonlyDeep} from './source/readonly-deep';
 export type {LiteralUnion} from './source/literal-union';
 export type {Promisable} from './source/promisable';
-export type {Opaque, UnwrapOpaque} from './source/opaque';
+export type {Opaque, UnwrapOpaque, Tagged, UnwrapTagged} from './source/opaque';
 export type {InvariantOf} from './source/invariant-of';
 export type {SetOptional} from './source/set-optional';
 export type {SetReadonly} from './source/set-readonly';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "4.2.0",
+	"version": "4.3.0",
 	"description": "A collection of essential TypeScript types",
 	"license": "(MIT OR CC0-1.0)",
 	"repository": "sindresorhus/type-fest",
@@ -37,8 +37,8 @@
 		"@sindresorhus/tsconfig": "~0.7.0",
 		"expect-type": "^0.15.0",
 		"tsd": "^0.28.1",
-		"typescript": "^5.0.4",
-		"xo": "^0.55.0"
+		"typescript": "^5.2.2",
+		"xo": "^0.56.0"
 	},
 	"xo": {
 		"rules": {

package/readme.md

@@ -60,7 +60,6 @@
 [![](https://img.shields.io/badge/unicorn-approved-ff69b4.svg)](https://giphy.com/gifs/illustration-rainbow-unicorn-26AHG5KGFxSkUWw1i)
 [![npm dependents](https://badgen.net/npm/dependents/type-fest)](https://www.npmjs.com/package/type-fest?activeTab=dependents)
 [![npm downloads](https://badgen.net/npm/dt/type-fest)](https://www.npmjs.com/package/type-fest)
-[![Docs](https://paka.dev/badges/v0/cute.svg)](https://paka.dev/npm/type-fest)
 
 Many of the types here should have been built-in. You can help by suggesting some of them to the [TypeScript project](https://github.com/Microsoft/TypeScript/blob/main/CONTRIBUTING.md).
 
@@ -110,6 +109,7 @@ Click the type names for complete docs.
 
 - [`EmptyObject`](source/empty-object.d.ts) - Represents a strictly empty plain object, the `{}` value.
 - [`IsEmptyObject`](source/empty-object.d.ts) - Returns a `boolean` for whether the type is strictly equal to an empty plain object, the `{}` value.
+- [`NonEmptyObject`](source/non-empty-object.d.ts) - Represents an object with at least 1 non-optional key.
 - [`UnknownRecord`](source/unknown-record.d.ts) - Represents an object with `unknown` value. You probably want this instead of `{}`.
 - [`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/utility-types.html#omittype-keys).
 - [`Writable`](source/writable.d.ts) - Create a type that strips `readonly` from all or some of an object's keys. The inverse of `Readonly<T>`.
@@ -129,8 +129,10 @@ Click the type names for complete docs.
 - [`PartialOnUndefinedDeep`](source/partial-on-undefined-deep.d.ts) - Create a deep version of another type where all keys accepting `undefined` type are set to optional.
 - [`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).
-- [`Opaque`](source/opaque.d.ts) - Create an [opaque type](https://codemix.com/opaque-types-in-javascript/).
-- [`UnwrapOpaque`](source/opaque.d.ts) - Revert an [opaque type](https://codemix.com/opaque-types-in-javascript/) back to its original type.
+- [`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) if needed.
+- [`UnwrapTagged`](source/opaque.d.ts) - Get the untagged portion of a tagged type created with `Tagged`.
+- [`Opaque`](source/opaque.d.ts) - Create a [tagged type](https://medium.com/@KevinBGreene/surviving-the-typescript-ecosystem-branding-and-type-tagging-6cf6e516523d). This implementation only supports a single tag.
+- [`UnwrapOpaque`](source/opaque.d.ts) - Get the untagged portion of a tagged type created with `Opaque` or `Tagged`.
 - [`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.
@@ -293,6 +295,8 @@ type ShouldBeNever = IfAny<'not any', 'not never', 'never'>;
 - `RecordDeep`- See [`Schema`](https://github.com/sindresorhus/type-fest/blob/main/source/schema.d.ts)
 - `Mutable`- See [`Writable`](https://github.com/sindresorhus/type-fest/blob/main/source/writable.d.ts)
 - `Prettify`- See [`Simplify`](https://github.com/sindresorhus/type-fest/blob/main/source/simplify.d.ts)
+- `RequireOnlyOne` - See [`RequireExactlyOne`](https://github.com/sindresorhus/type-fest/blob/main/source/require-exactly-one.d.ts)
+- `AtMostOne` - See [`RequireOneOrNone`](https://github.com/sindresorhus/type-fest/blob/main/source/require-one-or-none.d.ts)
 
 ## Tips
 
@@ -600,7 +604,7 @@ There are many advanced types most users don't know about.
 	// Cool, we're fine with that.
 	changePersonData(andrew, 'name', 'Pony');
 
-	// Goverment didn't like the fact that you wanted to change your identity.
+	// Government didn't like the fact that you wanted to change your identity.
 	changePersonData(andrew, ID, uniqueId());
 	```
 	</details>
@@ -716,7 +720,7 @@ There are many advanced types most users don't know about.
 	}
 
 	const articleCache = new InstanceCache(ArticleModel);
-	const amazonArticle = articleCache.getInstance('Amazon forests burining!');
+	const amazonArticle = articleCache.getInstance('Amazon forests burning!');
 	```
 	</details>
 

package/source/conditional-pick-deep.d.ts

@@ -1,4 +1,3 @@
-import type {Opaque} from './opaque';
 import type {IsEqual} from './is-equal';
 import type {ConditionalExcept} from './conditional-except';
 import type {ConditionalSimplifyDeep} from './conditional-simplify';
@@ -6,7 +5,7 @@ import type {ConditionalSimplifyDeep} from './conditional-simplify';
 /**
 Used to mark properties that should be excluded.
 */
-type ConditionalPickDeepSymbol = Opaque<symbol, 'conditional-pick-deep-symbol'>;
+declare const conditionalPickDeepSymbol: unique symbol;
 
 /**
 Assert the condition according to the {@link ConditionalPickDeepOptions.condition|condition} option.
@@ -98,5 +97,5 @@ export type ConditionalPickDeep<
 		? Type[Key]
 		: Type[Key] extends object
 			? ConditionalPickDeep<Type[Key], Condition, Options>
-			: ConditionalPickDeepSymbol;
-}, (ConditionalPickDeepSymbol | undefined) | Record<PropertyKey, never>>>;
+			: typeof conditionalPickDeepSymbol;
+}, (typeof conditionalPickDeepSymbol | undefined) | Record<PropertyKey, never>>>;

package/source/exact.d.ts

@@ -1,5 +1,5 @@
 import type {KeysOfUnion, ArrayElement, ObjectValue} from './internal';
-import type {Opaque} from './opaque';
+import type {Opaque, TagContainer} from './opaque';
 import type {IsEqual} from './is-equal';
 
 /**
@@ -56,7 +56,7 @@ export type Exact<ParameterType, InputType> =
 		: ParameterType extends unknown[] ? Array<Exact<ArrayElement<ParameterType>, ArrayElement<InputType>>>
 			// In TypeScript, Array is a subtype of ReadonlyArray, so always test Array before ReadonlyArray.
 			: ParameterType extends readonly unknown[] ? ReadonlyArray<Exact<ArrayElement<ParameterType>, ArrayElement<InputType>>>
-				// For Opaque types, internal details are hidden from public, so let's leave it as is.
-				: ParameterType extends Opaque<infer OpaqueType, infer OpaqueToken> ? ParameterType
+				// Leave tagged types as-is. We could try to make the untagged part Exact, and just leave the tag as-is, but that seems to create instanitation excessively deep errors.
+				: ParameterType extends TagContainer<unknown> ? ParameterType
 					: ParameterType extends object ? ExactObject<ParameterType, InputType>
 						: ParameterType;

package/source/invariant-of.d.ts

@@ -1,5 +1,7 @@
 import type {Opaque} from './opaque';
 
+declare const invariantBrand: unique symbol;
+
 /**
 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.
 
@@ -73,4 +75,4 @@ keyOfInvariantFooBar(invariantOf(fooBarBaz)); // Error: Argument of type 'Invari
 
 @category Type
 */
-export type InvariantOf<Type> = Opaque<Type, (argument: Type) => Type>;
+export type InvariantOf<Type> = Type & {[invariantBrand]: (_: Type) => Type};

package/source/non-empty-object.d.ts

@@ -0,0 +1,35 @@
+import type {HasRequiredKeys} from './has-required-keys';
+import type {RequireAtLeastOne} from './require-at-least-one';
+
+/**
+Represents an object with at least 1 non-optional key.
+
+This is useful when you need an object where all keys are optional, but there must be at least 1 key.
+
+@example
+```
+import type {NonEmptyObject} from 'type-fest';
+
+type User = {
+	name: string;
+	surname: string;
+	id: number;
+};
+
+type UpdateRequest<Entity extends object> = NonEmptyObject<Partial<Entity>>;
+
+const update1: UpdateRequest<User> = {
+	name: 'Alice',
+	surname: 'Acme',
+};
+
+// At least 1 key is required, therefore this will report a 2322 error:
+// Type '{}' is not assignable to type 'UpdateRequest<User>'
+const update2: UpdateRequest<User> = {};
+```
+
+@see Use `IsEmptyObject` to check whether an object is empty.
+
+@category Object
+*/
+export type NonEmptyObject<T extends object> = HasRequiredKeys<T> extends true ? T : RequireAtLeastOne<T, keyof T>;

package/source/opaque.d.ts

@@ -1,17 +1,25 @@
 declare const tag: unique symbol;
 
-declare type Tagged<Token> = {
+declare type TagContainer<Token> = {
 	readonly [tag]: Token;
 };
 
+type MultiTagContainer<Token extends PropertyKey> = {
+	readonly [tag]: {[K in Token]: void};
+};
+
 /**
-Create an opaque type, which hides its internal details from the public, and can only be created by being used explicitly.
+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.)
 
-The generic type parameter can be anything. It doesn't have to be an object.
+Also note that this implementation is limited to a single tag. If you want to allow multiple tags, use `Tagged` instead.
 
-[Read more about opaque types.](https://codemix.com/opaque-types-in-javascript/)
+[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 this feature to TypeScript via the `opaque type` operator, similar to how Flow does it. Unfortunately, nothing has (yet) moved forward:
+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)
@@ -59,7 +67,7 @@ getMoneyForAccount(2);
 // You can use opaque values like they aren't opaque too.
 const accountNumber = createAccountNumber();
 
-// This will not compile successfully.
+// 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.
@@ -71,10 +79,10 @@ type Person = {
 
 @category Type
 */
-export type Opaque<Type, Token = unknown> = Type & Tagged<Token>;
+export type Opaque<Type, Token = unknown> = Type & TagContainer<Token>;
 
 /**
-Revert an opaque type back to its original type by removing the readonly `[tag]`.
+Revert an opaque or tagged type back to its original type by removing the readonly `[tag]`.
 
 Why is this necessary?
 
@@ -97,11 +105,101 @@ const money = moneyByAccountType.SAVINGS; // TS error: Property 'SAVINGS' does n
 
 // 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
+*/
+export type UnwrapOpaque<OpaqueType extends TagContainer<unknown>> =
+	OpaqueType extends MultiTagContainer<string | number | symbol>
+		? 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 runtime values that would otherwise 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)
+
+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!
+getMoneyForAccount(2);
+
+// You can use opaque values like they aren't opaque too.
+const accountNumber = createAccountNumber();
+
+// This will compile successfully.
+const newAccountNumber = accountNumber + 2;
+```
+
+@category Type
+*/
+export type Tagged<Type, Tag extends PropertyKey> = Type & MultiTagContainer<Tag>;
+
+/**
+Revert a tagged type back to its original type by removing the readonly `[tag]`.
+
+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 UnwrapOpaque<OpaqueType extends Tagged<unknown>> =
-	OpaqueType extends Opaque<infer Type, OpaqueType[typeof tag]>
-		? Type
-		: OpaqueType;
+export type UnwrapTagged<TaggedType extends MultiTagContainer<PropertyKey>> =
+RemoveAllTags<TaggedType>;
+
+type RemoveAllTags<T> = T extends MultiTagContainer<infer ExistingTags>
+	? {
+		[ThisTag in ExistingTags]:
+		T extends Tagged<infer Type, ThisTag>
+			? RemoveAllTags<Type>
+			: never
+	}[ExistingTags]
+	: T;