@depup/type-fest 5.4.4-depup.0 → 5.9.0-depup.0

package/source/tagged.d.ts

@@ -8,12 +8,10 @@ export type TagContainer<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.)
+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).
 
 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:
@@ -100,7 +98,7 @@ const parsed = parse(x); // The type of `parsed` is { hello: string }
 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.
+Get the untagged portion of a tagged type created with `Tagged`.
 
 Why is this necessary?
 
@@ -121,7 +119,7 @@ const moneyByAccountType: Record<UnwrapTagged<AccountType>, number> = {
 // 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.
+// Attempting to pass a non-Tagged type to UnwrapTagged will raise a type error.
 // @ts-expect-error
 type WontWork = UnwrapTagged<string>;
 ```
@@ -129,7 +127,7 @@ type WontWork = UnwrapTagged<string>;
 @category Type
 */
 export type UnwrapTagged<TaggedType extends Tag<PropertyKey, any>> =
-RemoveAllTags<TaggedType>;
+	RemoveAllTags<TaggedType>;
 
 type RemoveAllTags<T> = T extends Tag<PropertyKey, any>
 	? {
@@ -239,7 +237,7 @@ const moneyByAccountType: Record<UnwrapOpaque<AccountType>, number> = {
 // 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.
+// Attempting to pass a non-Opaque type to UnwrapOpaque will raise a type error.
 // @ts-expect-error
 type WontWork = UnwrapOpaque<string>;
 

package/source/tsconfig-json.d.ts

@@ -61,6 +61,7 @@ export namespace TsConfigJson {
 			| 'ES2022'
 			| 'ES2023'
 			| 'ES2024'
+			| 'ES2025'
 			| 'ESNext'
 			// Lowercase alternatives
 			| 'es3'
@@ -76,6 +77,7 @@ export namespace TsConfigJson {
 			| 'es2022'
 			| 'es2023'
 			| 'es2024'
+			| 'es2025'
 			| 'esnext';
 
 		type Lib =
@@ -148,6 +150,13 @@ export namespace TsConfigJson {
 			| 'ES2024.Regexp'
 			| 'ES2024.SharedMemory'
 			| 'ES2024.String'
+			| 'ES2025'
+			| 'ES2025.Collection'
+			| 'ES2025.Float16'
+			| 'ES2025.Intl'
+			| 'ES2025.Iterator'
+			| 'ES2025.Promise'
+			| 'ES2025.RegExp'
 			| 'ESNext'
 			| 'ESNext.Array'
 			| 'ESNext.AsyncIterable'
@@ -156,6 +165,7 @@ export namespace TsConfigJson {
 			| 'ESNext.Decorators'
 			| 'ESNext.Disposable'
 			| 'ESNext.Error'
+			| 'ESNext.Float16'
 			| 'ESNext.Intl'
 			| 'ESNext.Iterator'
 			| 'ESNext.Object'
@@ -163,6 +173,7 @@ export namespace TsConfigJson {
 			| 'ESNext.Regexp'
 			| 'ESNext.String'
 			| 'ESNext.Symbol'
+			| 'ESNext.Temporal'
 			| 'ESNext.WeakRef'
 			| 'DOM'
 			| 'DOM.AsyncIterable'
@@ -244,6 +255,13 @@ export namespace TsConfigJson {
 			| 'es2024.regexp'
 			| 'es2024.sharedmemory'
 			| 'es2024.string'
+			| 'es2025'
+			| 'es2025.collection'
+			| 'es2025.float16'
+			| 'es2025.intl'
+			| 'es2025.iterator'
+			| 'es2025.promise'
+			| 'es2025.regexp'
 			| 'esnext'
 			| 'esnext.array'
 			| 'esnext.asynciterable'
@@ -252,6 +270,7 @@ export namespace TsConfigJson {
 			| 'esnext.decorators'
 			| 'esnext.disposable'
 			| 'esnext.error'
+			| 'esnext.float16'
 			| 'esnext.intl'
 			| 'esnext.iterator'
 			| 'esnext.object'
@@ -259,6 +278,7 @@ export namespace TsConfigJson {
 			| 'esnext.regexp'
 			| 'esnext.string'
 			| 'esnext.symbol'
+			| 'esnext.temporal'
 			| 'esnext.weakref'
 			| 'dom'
 			| 'dom.asynciterable'
@@ -326,7 +346,7 @@ export namespace TsConfigJson {
 			| 'legacy'
 			| 'force';
 
-		type IgnoreDeprecations = '5.0';
+		type IgnoreDeprecations = '5.0' | '6.0';
 	}
 
 	type CompilerOptions = {
@@ -479,7 +499,7 @@ export namespace TsConfigJson {
 		/**
 		Specify module code generation: 'None', 'CommonJS', 'AMD', 'System', 'UMD', 'ES6', 'ES2015' or 'ESNext'. Only 'AMD' and 'System' can be used in conjunction with `--outFile`. 'ES6' and 'ES2015' values may be used when targeting 'ES5' or lower.
 
-		@default ['ES3', 'ES5'].includes(target) ? 'CommonJS' : 'ES6'
+		Default: `'ESNext'` since TypeScript 6.0, `['ES3', 'ES5'].includes(target) ? 'CommonJS' : 'ES6'` before.
 		*/
 		module?: CompilerOptions.Module;
 
@@ -587,8 +607,17 @@ export namespace TsConfigJson {
 		*/
 		skipLibCheck?: boolean;
 
+		/**
+		Enforce stable type ordering.
+
+		@default false
+		*/
+		stableTypeOrdering?: boolean;
+
 		/**
 		Concatenate and emit output to single file.
+
+		@deprecated since TypeScript 6.0.
 		*/
 		outFile?: string;
 
@@ -696,7 +725,7 @@ export namespace TsConfigJson {
 		/**
 		Specify ECMAScript target version.
 
-		@default 'es3'
+		Default: Current-year ES version since TypeScript 6.0, `'es3'` before.
 		*/
 		target?: CompilerOptions.Target;
 
@@ -776,7 +805,7 @@ export namespace TsConfigJson {
 		/**
 		Report error if failed to find a source file for a side effect import.
 
-		@default false
+		Default: `true` since TypeScript 6.0, `false` before.
 		*/
 		noUncheckedSideEffectImports?: boolean;
 
@@ -822,6 +851,8 @@ export namespace TsConfigJson {
 
 		/**
 		Base directory to resolve non-relative module names.
+
+		@deprecated since TypeScript 6.0.
 		*/
 		baseUrl?: string;
 
@@ -944,7 +975,7 @@ export namespace TsConfigJson {
 		/**
 		Enable all strict type checking options.
 
-		@default false
+		Default: `true` since TypeScript 6.0, `false` before.
 		*/
 		strict?: boolean;
 
@@ -959,6 +990,7 @@ export namespace TsConfigJson {
 		Provide full support for iterables in `for-of`, spread, and destructuring when targeting `ES5` or `ES3`.
 
 		@default false
+		@deprecated since TypeScript 6.0.
 		*/
 		downlevelIteration?: boolean;
 
@@ -1150,7 +1182,7 @@ export namespace TsConfigJson {
 		/**
 		Enable lib replacement.
 
-		@default true
+		Default: `false` since TypeScript 6.0, `true` before.
 		*/
 		libReplacement?: boolean;
 	};
@@ -1234,7 +1266,7 @@ export namespace TsConfigJson {
 		exclude?: string[];
 
 		/**
-		Disable infering what types should be added based on filenames in a project.
+		Disable inferring what types should be added based on filenames in a project.
 		*/
 		disableFilenameBasedTypeAcquisition?: boolean;
 	};
@@ -1266,7 +1298,7 @@ export namespace TsConfigJson {
 }
 
 /**
-Type for [TypeScript's `tsconfig.json` file](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) (TypeScript 3.7).
+Type for [TypeScript's `tsconfig.json` file](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html).
 
 @category File
 */

package/source/tuple-of.d.ts

@@ -1,6 +1,7 @@
 import type {If} from './if.d.ts';
 import type {IfNotAnyOrNever} from './internal/type.d.ts';
 import type {IsNegative} from './numeric.d.ts';
+import type {DigitCharacter} from './characters.d.ts';
 import type {UnknownArray} from './unknown-array.d.ts';
 
 /**
@@ -30,7 +31,7 @@ type ZeroToFour = Range<0, 5>;
 //=> '0' | '1' | '2' | '3' | '4'
 
 type ThreeToEight = Range<3, 9>;
-//=> '5' | '3' | '4' | '6' | '7' | '8'
+//=> '3' | '4' | '5' | '6' | '7' | '8'
 ```
 
 Note: If the specified length is the non-literal `number` type, the result will not be a tuple but a regular array.
@@ -63,18 +64,51 @@ type EmptyTuple = TupleOf<-3, string>;
 //=> []
 ```
 
+Note: If the specified length has a decimal part, the decimal part will be ignored.
+
+@example
+```
+import type {TupleOf} from 'type-fest';
+
+type DecimalLength = TupleOf<3.5, string>;
+//=> [string, string, string]
+```
+
 Note: If you need a readonly tuple, simply wrap this type with `Readonly`, for example, to create `readonly [number, number, number]` use `Readonly<TupleOf<3, number>>`.
 
 @category Array
 */
-export type TupleOf<Length extends number, Fill = unknown> = IfNotAnyOrNever<Length,
-	_TupleOf<If<IsNegative<Length>, 0, Length>, Fill, []>,
-	Fill[], []>;
+export type TupleOf<Length extends number, Fill = unknown> = IfNotAnyOrNever<Length, {
+	ifNot: _TupleOf<If<IsNegative<Length>, 0, Length>, Fill>;
+	ifAny: Fill[];
+	ifNever: [];
+}>;
 
-type _TupleOf<L extends number, Fill, Accumulator extends UnknownArray> = number extends L
+type _TupleOf<Length extends number, Fill> = number extends Length
 	? Fill[]
-	: L extends Accumulator['length']
-		? Accumulator
-		: _TupleOf<L, Fill, [...Accumulator, Fill]>;
+	: BuildTupleDigitByDigit<`${Length}`, Fill>;
+
+type BuildTupleDigitByDigit<Length extends string, Fill, Accumulator extends UnknownArray = []> =
+	Length extends `${infer First extends DigitCharacter}${infer Rest}`
+		? BuildTupleDigitByDigit<Rest, Fill, [...RepeatTupleTenTimes<Accumulator>, ...DigitTupleOf<First, Fill>]>
+		: Accumulator;
+
+type RepeatTupleTenTimes<Tuple extends UnknownArray> = [
+	...Tuple, ...Tuple, ...Tuple, ...Tuple, ...Tuple,
+	...Tuple, ...Tuple, ...Tuple, ...Tuple, ...Tuple,
+];
+
+type DigitTupleOf<Digit extends DigitCharacter, Fill> = [
+	[],
+	[Fill],
+	[Fill, Fill],
+	[Fill, Fill, Fill],
+	[Fill, Fill, Fill, Fill],
+	[Fill, Fill, Fill, Fill, Fill],
+	[Fill, Fill, Fill, Fill, Fill, Fill],
+	[Fill, Fill, Fill, Fill, Fill, Fill, Fill],
+	[Fill, Fill, Fill, Fill, Fill, Fill, Fill, Fill],
+	[Fill, Fill, Fill, Fill, Fill, Fill, Fill, Fill, Fill],
+][Digit];
 
 export {};

package/source/typed-array.d.ts

@@ -11,6 +11,7 @@ export type TypedArray =
 	| Uint16Array
 	| Int32Array
 	| Uint32Array
+	| Float16Array
 	| Float32Array
 	| Float64Array
 	| BigInt64Array

package/source/union-length.d.ts

@@ -0,0 +1,27 @@
+import type {UnionToTuple} from './union-to-tuple.d.ts';
+
+/**
+Returns the length of a union type.
+
+@example
+```
+import type {UnionLength} from 'type-fest';
+
+type T1 = UnionLength<'foo' | 'bar' | 'baz'>;
+//=> 3
+
+type T2 = UnionLength<[string, string, string] | {x: string; y: string; z: string}>;
+//=> 2
+
+type T3 = UnionLength<any>;
+//=> 1
+
+type T4 = UnionLength<never>;
+//=> 0
+```
+
+@category Type
+*/
+export type UnionLength<Union> = UnionToTuple<Union>['length'];
+
+export {};

package/source/union-member.d.ts

@@ -0,0 +1,65 @@
+import type {UnionToIntersection} from './union-to-intersection.d.ts';
+import type {IsNever} from './is-never.d.ts';
+
+/**
+Returns an arbitrary member of a union type.
+
+Use-cases:
+- Implementing recursive type functions that accept a union type.
+
+@example
+```
+import type {UnionMember, IsNever} from 'type-fest';
+
+type UnionLength<T, Acc extends any[] = []> =
+	UnionMember<T> extends infer Member
+		? IsNever<Member> extends false
+			? UnionLength<Exclude<T, Member>, [...Acc, Member]>
+			: Acc['length']
+		: never;
+
+type T1 = UnionLength<'foo' | 'bar' | 'baz'>;
+//=> 3
+
+type T2 = UnionLength<{a: string}>;
+//=> 1
+```
+
+- Picking an arbitrary member from a union
+
+@example
+```
+import type {UnionMember, Primitive, LiteralToPrimitive} from 'type-fest';
+
+type IsHomogenous<T extends Primitive> = [T] extends [LiteralToPrimitive<UnionMember<T>>] ? true : false;
+
+type T1 = IsHomogenous<1 | 2 | 3 | 4>;
+//=> true
+
+type T2 = IsHomogenous<'foo' | 'bar'>;
+//=> true
+
+type T3 = IsHomogenous<'foo' | 'bar' | 1>;
+//=> false
+```
+
+Returns `never` when the input is `never`.
+
+@example
+```
+import type {UnionMember} from 'type-fest';
+
+type LastNever = UnionMember<never>;
+//=> never
+```
+
+@category Type
+*/
+export type UnionMember<T> =
+	IsNever<T> extends true
+		? never
+		: UnionToIntersection<T extends any ? () => T : never> extends () => (infer R)
+			? R
+			: never;
+
+export {};

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

@@ -1,5 +1,5 @@
 /**
-Convert a union type to an intersection type using [distributive conditional types](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-8.html#distributive-conditional-types).
+Convert a union type to an intersection type.
 
 Inspired by [this Stack Overflow answer](https://stackoverflow.com/a/50375286/2172153).
 

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

@@ -1,19 +1,7 @@
+import type {ExcludeExactly} from './exclude-exactly.d.ts';
 import type {IsNever} from './is-never.d.ts';
-import type {UnionToIntersection} from './union-to-intersection.d.ts';
-
-/**
-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;
+import type {UnionMember} from './union-member.d.ts';
+import type {UnknownArray} from './unknown-array.d.ts';
 
 /**
 Convert a union type into an unordered tuple type of its elements.
@@ -50,9 +38,12 @@ const petList = Object.keys(pets) as UnionToTuple<Pet>;
 
 @category Array
 */
-export type UnionToTuple<T, L = LastOfUnion<T>> =
-IsNever<T> extends false
-	? [...UnionToTuple<Exclude<T, L>>, L]
-	: [];
+export type UnionToTuple<Union> =
+	_UnionToTuple<Union> extends infer Result extends UnknownArray ? Result : never; // Nudges the compiler that `UnionToTuple` always yields an array.
+
+type _UnionToTuple<Union, Accumulator extends UnknownArray = [], Member = UnionMember<Union>> =
+	IsNever<Union> extends true
+		? Accumulator
+		: _UnionToTuple<ExcludeExactly<Union, Member>, [Member, ...Accumulator]>;
 
 export {};

package/source/unwrap-required.d.ts

@@ -0,0 +1,37 @@
+import type {MapsSetsOrArrays, NonRecursiveType} from './internal/type.d.ts';
+
+/**
+Revert the `Required` modifier on an object type.
+
+Use-case: Infer the underlying type `T` when only `Required<T>` is available or the original type may not be directly accessible.
+
+@example
+```
+import type {UnwrapRequired} from 'type-fest';
+
+type ContactFormData = Required<{
+	email: string;
+	message?: string;
+}>;
+
+type DraftContactFormData = UnwrapRequired<ContactFormData>;
+//=> {email: string; message?: string}
+```
+
+Note:
+	- If the provided type isn’t of the form `Required<T>`, `UnwrapRequired` simply returns the input type.
+	- `UnwrapRequired` doesn't work with arrays, if instantiated with arrays, it simply returns the input type.
+
+@category Object
+*/
+export type UnwrapRequired<RequiredObjectType> =
+	RequiredObjectType extends NonRecursiveType | MapsSetsOrArrays
+		? RequiredObjectType
+		: _UnwrapRequired<RequiredObjectType>;
+
+type _UnwrapRequired<RequiredObjectType> =
+	RequiredObjectType extends Required<infer ObjectType>
+		? ObjectType
+		: RequiredObjectType;
+
+export {};

package/source/words.d.ts

@@ -1,5 +1,6 @@
 import type {
 	ApplyDefaultOptions,
+	AsciiPunctuation,
 	IsNumeric,
 	WordSeparators,
 } from './internal/index.d.ts';
@@ -38,17 +39,34 @@ export type WordsOptions = {
 	```
 	*/
 	splitOnNumbers?: boolean;
+	/**
+	Split on {@link AsciiPunctuation | punctuation characters} (e.g., `#`, `&`, `*`, `:`, `?`, `@`, `~`).
+
+	@example
+	```
+	import type {Words} from 'type-fest';
+
+	type Example1 = Words<'hello:world', {splitOnPunctuation: true}>;
+	//=> ['hello', 'world']
+
+	type Example2 = Words<'hello:world', {splitOnPunctuation: false}>;
+	//=> ['hello', ':world']
+	```
+	*/
+	splitOnPunctuation?: boolean;
 };
 
 export type _DefaultWordsOptions = {
 	splitOnNumbers: true;
+	splitOnPunctuation: false;
 };
 
 /**
-Split a string (almost) like Lodash's `_.words()` function.
+Split a string similar to Lodash's `_.words()` function.
 
 - Split on each word that begins with a capital letter.
 - Split on each {@link WordSeparators}.
+- Split on each {@link AsciiPunctuation} (if {@link WordsOptions.splitOnPunctuation} is enabled).
 - Split on numeric sequence.
 
 @example
@@ -72,13 +90,21 @@ type Words4 = Words<'lifeIs42'>;
 
 type Words5 = Words<'p2pNetwork', {splitOnNumbers: false}>;
 //=> ['p2p', 'Network']
+
+type Words6 = Words<'hello:world', {splitOnPunctuation: true}>;
+//=> ['hello', 'world']
+
+type Words7 = Words<'hello:world', {splitOnPunctuation: false}>;
+//=> ['hello', ':world']
+
+type Words8 = Words<'hello::world', {splitOnPunctuation: true}>;
+//=> ['hello', 'world']
 ```
 
 @category Change case
 @category Template literal
 */
-export type Words<Sentence extends string, Options extends WordsOptions = {}> =
-	WordsImplementation<Sentence, ApplyDefaultOptions<WordsOptions, _DefaultWordsOptions, Options>>;
+export type Words<Sentence extends string, Options extends WordsOptions = {}> = WordsImplementation<Sentence, ApplyDefaultOptions<WordsOptions, _DefaultWordsOptions, Options>>;
 
 type WordsImplementation<
 	Sentence extends string,
@@ -86,7 +112,7 @@ type WordsImplementation<
 	LastCharacter extends string = '',
 	CurrentWord extends string = '',
 > = Sentence extends `${infer FirstCharacter}${infer RemainingCharacters}`
-	? FirstCharacter extends WordSeparators
+	? FirstCharacter extends WordSeparators | (Options['splitOnPunctuation'] extends true ? AsciiPunctuation : never)
 		// Skip word separator
 		? [...SkipEmptyWord<CurrentWord>, ...WordsImplementation<RemainingCharacters, Options>]
 		: LastCharacter extends ''

package/source/writable.d.ts

@@ -37,11 +37,7 @@ writableFoo.b[0] = 'new value'; // Will still fail as the value of property "b"
 writableFoo.b = ['something']; // Will work as the "b" property itself is no longer readonly.
 
 type SomeWritable = Writable<Foo, 'b' | 'c'>;
-// type SomeWritable = {
-// 	readonly a: number;
-// 	b: readonly string[]; // It's now writable. The type of the property remains unaffected.
-// 	c: boolean; // It's now writable.
-// }
+//=> {readonly a: number; b: readonly string[]; c: boolean}
 
 // Also supports array
 const readonlyArray: readonly number[] = [1, 2, 3];
@@ -54,19 +50,19 @@ writableArray.push(4); // Will work as the array itself is now writable.
 @category Object
 */
 export type Writable<BaseType, Keys extends keyof BaseType = keyof BaseType> =
-BaseType extends ReadonlyMap<infer KeyType, infer ValueType>
-	? Map<KeyType, ValueType>
-	: BaseType extends ReadonlySet<infer ItemType>
-		? Set<ItemType>
-		: BaseType extends readonly unknown[]
-			// Handle array
-			? WritableArray<BaseType>
-			// Handle object
-			: Simplify<
-			// Pick just the keys that are not writable from the base type.
-				Except<BaseType, Keys> &
-			// Pick the keys that should be writable from the base type and make them writable by removing the `readonly` modifier from the key.
-				{-readonly [KeyType in keyof Pick<BaseType, Keys>]: Pick<BaseType, Keys>[KeyType]}
-			>;
+	BaseType extends ReadonlyMap<infer KeyType, infer ValueType>
+		? Map<KeyType, ValueType>
+		: BaseType extends ReadonlySet<infer ItemType>
+			? Set<ItemType>
+			: BaseType extends readonly unknown[]
+				// Handle array
+				? WritableArray<BaseType>
+				// Handle object
+				: Simplify<
+					// Pick just the keys that are not writable from the base type.
+					Except<BaseType, Keys>
+					// Make the specified keys writable.
+					& {-readonly [KeyType in keyof BaseType as KeyType extends Keys ? KeyType : never]: BaseType[KeyType]}
+				>;
 
 export {};

package/source/xor.d.ts

@@ -3,7 +3,7 @@ import type {And} from './and.d.ts';
 import type {Or} from './or.d.ts';
 
 /**
-Returns a boolean for whether only one of two given types is true.
+Returns a boolean for whether only one of two given types is `true`.
 
 Use-case: Constructing complex conditional types where one single condition must be satisfied.