type-fest 4.34.1 → 4.36.0

package/index.d.ts

@@ -104,6 +104,7 @@ export type {HasWritableKeys} from './source/has-writable-keys';
 export type {Spread} from './source/spread';
 export type {IsInteger} from './source/is-integer';
 export type {IsFloat} from './source/is-float';
+export type {TupleToObject} from './source/tuple-to-object';
 export type {TupleToUnion} from './source/tuple-to-union';
 export type {UnionToTuple} from './source/union-to-tuple';
 export type {IntRange} from './source/int-range';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "4.34.1",
+	"version": "4.36.0",
 	"description": "A collection of essential TypeScript types",
 	"license": "(MIT OR CC0-1.0)",
 	"repository": "sindresorhus/type-fest",
@@ -69,7 +69,19 @@
 				"error",
 				"prefer-top-level"
 			]
-		}
+		},
+		"overrides": [
+			{
+				"files": "**/*.d.ts",
+				"rules": {
+					"no-restricted-imports": [
+						"error",
+						"tsd",
+						"expect-type"
+					]
+				}
+			}
+		]
 	},
 	"tsd": {
 		"compilerOptions": {

package/readme.md

@@ -292,6 +292,7 @@ type ShouldBeNever = IfAny<'not any', 'not never', 'never'>;
 - [`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.
+- [`TupleToObject`](source/tuple-to-object.d.ts) - Transforms a tuple into an object, mapping each tuple index to its corresponding type as a key-value pair.
 
 ### Numeric
 

package/source/delimiter-case.d.ts

@@ -1,54 +1,23 @@
-import type {UpperCaseCharacters, WordSeparators} from './internal';
-
-// Transforms a string that is fully uppercase into a fully lowercase version. Needed to add support for SCREAMING_SNAKE_CASE, see https://github.com/sindresorhus/type-fest/issues/385
-type UpperCaseToLowerCase<T extends string> = T extends Uppercase<T> ? Lowercase<T> : T;
-
-// This implementation does not support SCREAMING_SNAKE_CASE, it is used internally by `SplitIncludingDelimiters`.
-type SplitIncludingDelimiters_<Source extends string, Delimiter extends string> =
-	Source extends '' ? [] :
-		Source extends `${infer FirstPart}${Delimiter}${infer SecondPart}` ?
-			(
-				Source extends `${FirstPart}${infer UsedDelimiter}${SecondPart}`
-					? UsedDelimiter extends Delimiter
-						? Source extends `${infer FirstPart}${UsedDelimiter}${infer SecondPart}`
-							? [...SplitIncludingDelimiters<FirstPart, Delimiter>, UsedDelimiter, ...SplitIncludingDelimiters<SecondPart, Delimiter>]
-							: never
-						: never
-					: never
-			) :
-			[Source];
-
-/**
-Unlike a simpler split, this one includes the delimiter splitted on in the resulting array literal. This is to enable splitting on, for example, upper-case characters.
-
-@category Template literal
-*/
-export type SplitIncludingDelimiters<Source extends string, Delimiter extends string> = SplitIncludingDelimiters_<UpperCaseToLowerCase<Source>, Delimiter>;
+import type {IsStringLiteral} from './is-literal';
+import type {Words, WordsOptions} from './words';
 
 /**
-Format a specific part of the splitted string literal that `StringArrayToDelimiterCase<>` fuses together, ensuring desired casing.
-
-@see StringArrayToDelimiterCase
+Convert an array of words to delimiter case starting with a delimiter with input capitalization.
 */
-type StringPartToDelimiterCase<StringPart extends string, Start extends boolean, UsedWordSeparators extends string, UsedUpperCaseCharacters extends string, Delimiter extends string> =
-	StringPart extends UsedWordSeparators ? Delimiter :
-		Start extends true ? Lowercase<StringPart> :
-			StringPart extends UsedUpperCaseCharacters ? `${Delimiter}${Lowercase<StringPart>}` :
-				StringPart;
-
-/**
-Takes the result of a splitted string literal and recursively concatenates it together into the desired casing.
-
-It receives `UsedWordSeparators` and `UsedUpperCaseCharacters` as input to ensure it's fully encapsulated.
-
-@see SplitIncludingDelimiters
-*/
-type StringArrayToDelimiterCase<Parts extends readonly any[], Start extends boolean, UsedWordSeparators extends string, UsedUpperCaseCharacters extends string, Delimiter extends string> =
-	Parts extends [`${infer FirstPart}`, ...infer RemainingParts]
-		? `${StringPartToDelimiterCase<FirstPart, Start, UsedWordSeparators, UsedUpperCaseCharacters, Delimiter>}${StringArrayToDelimiterCase<RemainingParts, false, UsedWordSeparators, UsedUpperCaseCharacters, Delimiter>}`
-		: Parts extends [string]
-			? string
-			: '';
+type DelimiterCaseFromArray<
+	Words extends string[],
+	Delimiter extends string,
+	OutputString extends string = '',
+> = Words extends [
+	infer FirstWord extends string,
+	...infer RemainingWords extends string[],
+]
+	? DelimiterCaseFromArray<RemainingWords, Delimiter, `${OutputString}${Delimiter}${FirstWord}`>
+	: OutputString;
+
+type RemoveFirstLetter<S extends string> = S extends `${infer _}${infer Rest}`
+	? Rest
+	: '';
 
 /**
 Convert a string literal to a custom string delimiter casing.
@@ -65,6 +34,7 @@ import type {DelimiterCase} from 'type-fest';
 // Simple
 
 const someVariable: DelimiterCase<'fooBar', '#'> = 'foo#bar';
+const someVariableNoSplitOnNumbers: DelimiterCase<'p2pNetwork', '#', {splitOnNumbers: false}> = 'p2p#network';
 
 // Advanced
 
@@ -87,13 +57,17 @@ const rawCliOptions: OddlyCasedProperties<SomeOptions> = {
 
 @category Change case
 @category Template literal
-*/
-export type DelimiterCase<Value, Delimiter extends string> = string extends Value ? Value : Value extends string
-	? StringArrayToDelimiterCase<
-	SplitIncludingDelimiters<Value, WordSeparators | UpperCaseCharacters>,
-	true,
-	WordSeparators,
-	UpperCaseCharacters,
-	Delimiter
-	>
+ */
+export type DelimiterCase<
+	Value,
+	Delimiter extends string,
+	Options extends WordsOptions = {},
+> = Value extends string
+	? IsStringLiteral<Value> extends false
+		? Value
+		: Lowercase<
+		RemoveFirstLetter<
+		DelimiterCaseFromArray<Words<Value, Options>, Delimiter>
+		>
+		>
 	: Value;

package/source/kebab-case.d.ts

@@ -1,4 +1,5 @@
 import type {DelimiterCase} from './delimiter-case';
+import type {WordsOptions} from './words';
 
 /**
 Convert a string literal to kebab-case.
@@ -12,6 +13,7 @@ import type {KebabCase} from 'type-fest';
 // Simple
 
 const someVariable: KebabCase<'fooBar'> = 'foo-bar';
+const someVariableNoSplitOnNumbers: KebabCase<'p2pNetwork', {splitOnNumbers: false}> = 'p2p-network';
 
 // Advanced
 
@@ -35,4 +37,7 @@ const rawCliOptions: KebabCasedProperties<CliOptions> = {
 @category Change case
 @category Template literal
 */
-export type KebabCase<Value> = DelimiterCase<Value, '-'>;
+export type KebabCase<
+	Value,
+	Options extends WordsOptions = {},
+> = DelimiterCase<Value, '-', Options>;

package/source/paths.d.ts

@@ -91,12 +91,48 @@ export type PathsOptions = {
 	```
 	*/
 	leavesOnly?: boolean;
+
+	/**
+	Only include paths at the specified depth. By default all paths up to {@link PathsOptions.maxRecursionDepth | `maxRecursionDepth`} are included.
+
+	Note: Depth starts at `0` for root properties.
+
+	@default number
+
+	@example
+	```
+	type Post = {
+		id: number;
+		author: {
+			id: number;
+			name: {
+				first: string;
+				last: string;
+			};
+		};
+	};
+
+	type DepthZero = Paths<Post, {depth: 0}>;
+	//=> 'id' | 'author'
+
+	type DepthOne = Paths<Post, {depth: 1}>;
+	//=> 'author.id' | 'author.name'
+
+	type DepthTwo = Paths<Post, {depth: 2}>;
+	//=> 'author.name.first' | 'author.name.last'
+
+	type LeavesAtDepthOne = Paths<Post, {leavesOnly: true; depth: 1}>;
+	//=> 'author.id'
+	```
+	*/
+	depth?: number;
 };
 
 type DefaultPathsOptions = {
 	maxRecursionDepth: 10;
 	bracketNotation: false;
 	leavesOnly: false;
+	depth: number;
 };
 
 /**
@@ -147,6 +183,8 @@ export type Paths<T, Options extends PathsOptions = {}> = _Paths<T, {
 	bracketNotation: Options['bracketNotation'] extends boolean ? Options['bracketNotation'] : DefaultPathsOptions['bracketNotation'];
 	// Set default leavesOnly to false
 	leavesOnly: Options['leavesOnly'] extends boolean ? Options['leavesOnly'] : DefaultPathsOptions['leavesOnly'];
+	// Set default depth to number
+	depth: Options['depth'] extends number ? Options['depth'] : DefaultPathsOptions['depth'];
 }>;
 
 type _Paths<T, Options extends Required<PathsOptions>> =
@@ -186,17 +224,36 @@ type InternalPaths<T, Options extends Required<PathsOptions>> =
 						) extends infer TranformedKey extends string | number ?
 						// 1. If style is 'a[0].b' and 'Key' is a numberlike value like 3 or '3', transform 'Key' to `[${Key}]`, else to `${Key}` | Key
 						// 2. If style is 'a.0.b', transform 'Key' to `${Key}` | Key
-							| (Options['leavesOnly'] extends true
+							| ((Options['leavesOnly'] extends true
 								? MaxDepth extends 0
 									? TranformedKey
 									: T[Key] extends EmptyObject | readonly [] | NonRecursiveType | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown>
 										? TranformedKey
 										: never
-								: TranformedKey)
+								: TranformedKey
+							) extends infer _TransformedKey
+								// If `depth` is provided, the condition becomes truthy only when it reaches `0`.
+								// Otherwise, since `depth` defaults to `number`, the condition is always truthy, returning paths at all depths.
+								? 0 extends Options['depth']
+									? _TransformedKey
+									: never
+								: never)
 							| (
 								// Recursively generate paths for the current key
 								GreaterThan<MaxDepth, 0> extends true // Limit the depth to prevent infinite recursion
-									? _Paths<T[Key], {bracketNotation: Options['bracketNotation']; maxRecursionDepth: Subtract<MaxDepth, 1>; leavesOnly: Options['leavesOnly']}> extends infer SubPath
+									? _Paths<T[Key],
+									{
+										bracketNotation: Options['bracketNotation'];
+										maxRecursionDepth: Subtract<MaxDepth, 1>;
+										leavesOnly: Options['leavesOnly'];
+										depth: Options['depth'] extends infer Depth extends number // For distributing `Options['depth']`
+											? Depth extends 0 // Don't subtract further if `Depth` has reached `0`
+												? never
+												: ToString<Depth> extends `-${number}` // Don't subtract if `Depth` is -ve
+													? never
+													: Subtract<Options['depth'], 1> // If `Subtract` supported -ve numbers, then `depth` could have simply been `Subtract<Options['depth'], 1>`
+											: never; // Should never happen
+									}> extends infer SubPath
 										? SubPath extends string | number
 											? (
 												Options['bracketNotation'] extends true

package/source/replace.d.ts

@@ -60,8 +60,16 @@ export type Replace<
 	Search extends string,
 	Replacement extends string,
 	Options extends ReplaceOptions = {},
+> = _Replace<Input, Search, Replacement, Options>;
+
+type _Replace<
+	Input extends string,
+	Search extends string,
+	Replacement extends string,
+	Options extends ReplaceOptions,
+	Accumulator extends string = '',
 > = Input extends `${infer Head}${Search}${infer Tail}`
 	? Options['all'] extends true
-		? `${Head}${Replacement}${Replace<Tail, Search, Replacement, Options>}`
+		? _Replace<Tail, Search, Replacement, Options, `${Accumulator}${Head}${Replacement}`>
 		: `${Head}${Replacement}${Tail}`
-	: Input;
+	: `${Accumulator}${Input}`;

package/source/screaming-snake-case.d.ts

@@ -1,15 +1,5 @@
-import type {SplitIncludingDelimiters} from './delimiter-case';
 import type {SnakeCase} from './snake-case';
-import type {Includes} from './includes';
-
-/**
-Returns a boolean for whether the string is screaming snake case.
-*/
-type IsScreamingSnakeCase<Value extends string> = Value extends Uppercase<Value>
-	? Includes<SplitIncludingDelimiters<Lowercase<Value>, '_'>, '_'> extends true
-		? true
-		: false
-	: false;
+import type {WordsOptions} from './words';
 
 /**
 Convert a string literal to screaming-snake-case.
@@ -21,13 +11,14 @@ This can be useful when, for example, converting a camel-cased object property t
 import type {ScreamingSnakeCase} from 'type-fest';
 
 const someVariable: ScreamingSnakeCase<'fooBar'> = 'FOO_BAR';
+const someVariableNoSplitOnNumbers: ScreamingSnakeCase<'p2pNetwork', {splitOnNumbers: false}> = 'P2P_NETWORK';
+
 ```
 
 @category Change case
 @category Template literal
-*/
-export type ScreamingSnakeCase<Value> = Value extends string
-	? IsScreamingSnakeCase<Value> extends true
-		? Value
-		: Uppercase<SnakeCase<Value>>
-	: Value;
+ */
+export type ScreamingSnakeCase<
+	Value,
+	Options extends WordsOptions = {},
+> = Value extends string ? Uppercase<SnakeCase<Value, Options>> : Value;

package/source/snake-case.d.ts

@@ -1,4 +1,5 @@
 import type {DelimiterCase} from './delimiter-case';
+import type {WordsOptions} from './words';
 
 /**
 Convert a string literal to snake-case.
@@ -12,6 +13,7 @@ import type {SnakeCase} from 'type-fest';
 // Simple
 
 const someVariable: SnakeCase<'fooBar'> = 'foo_bar';
+const someVariableNoSplitOnNumbers: SnakeCase<'p2pNetwork', {splitOnNumbers: false}> = 'p2p_network';
 
 // Advanced
 
@@ -35,4 +37,7 @@ const dbResult: SnakeCasedProperties<ModelProps> = {
 @category Change case
 @category Template literal
 */
-export type SnakeCase<Value> = DelimiterCase<Value, '_'>;
+export type SnakeCase<
+	Value,
+	Options extends WordsOptions = {},
+> = DelimiterCase<Value, '_', Options>;

package/source/tsconfig-json.d.ts

@@ -18,6 +18,7 @@ declare namespace TsConfigJson {
 			| 'ES2022'
 			| 'ESNext'
 			| 'Node16'
+			| 'Node18'
 			| 'NodeNext'
 			| 'Preserve'
 			| 'None'
@@ -32,6 +33,7 @@ declare namespace TsConfigJson {
 			| 'es2022'
 			| 'esnext'
 			| 'node16'
+			| 'node18'
 			| 'nodenext'
 			| 'preserve'
 			| 'none';
@@ -1109,6 +1111,20 @@ declare namespace TsConfigJson {
 		Suppress deprecation warnings
 		*/
 		ignoreDeprecations?: CompilerOptions.IgnoreDeprecations;
+
+		/**
+		Do not allow runtime constructs that are not part of ECMAScript.
+
+		@default false
+		*/
+		erasableSyntaxOnly?: boolean;
+
+		/**
+		Enable lib replacement.
+
+		@default true
+		*/
+		libReplacement?: boolean;
 	};
 
 	namespace WatchOptions {
@@ -1160,12 +1176,12 @@ declare namespace TsConfigJson {
 		synchronousWatchDirectory?: boolean;
 
 		/**
-		Specifies a list of directories to exclude from watch
+		Specifies a list of directories to exclude from watch.
 		*/
 		excludeDirectories?: string[];
 
 		/**
-		Specifies a list of files to exclude from watch
+		Specifies a list of files to exclude from watch.
 		*/
 		excludeFiles?: string[];
 	};

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

@@ -0,0 +1,42 @@
+import type {IsTuple} from './is-tuple';
+import type {UnknownArray} from './unknown-array';
+import type {IfAny} from './if-any';
+
+/**
+Transforms a tuple into an object, mapping each tuple index to its corresponding type as a key-value pair.
+
+Note: Tuple labels are [lost in the transformation process](https://stackoverflow.com/a/70398429/11719314). For example, `TupleToObject<[x: number, y: number]>` produces `{0: number; 1: number}`, and not `{x: number; y: number}`.
+
+@example
+```
+type Example1 = TupleToObject<[number, string, boolean]>;
+//=> { 0: number; 1: string; 2: boolean }
+
+// Tuples with optional indices
+type Example2 = TupleToObject<[number, string?, boolean?]>;
+//=> { 0: number; 1?: string; 2?: boolean }
+
+// Readonly tuples
+type Example3 = TupleToObject<readonly [number, string?]>;
+//=> { readonly 0: number; readonly 1?: string }
+
+// Non-tuple arrays get transformed into index signatures
+type Example4 = TupleToObject<string[]>;
+//=> { [x: number]: string }
+
+// Tuples with rest elements
+type Example5 = TupleToObject<[number, string, ...boolean[]]>;
+//=> { [x: number]: number | string | boolean; 0: number; 1: string }
+
+// Tuple labels are not preserved
+type Example6 = TupleToObject<[x: number, y: number]>;
+//=> { 0: number; 1: number }
+```
+
+@category Array
+*/
+export type TupleToObject<TArray extends UnknownArray> = IfAny<TArray, any, {
+	[
+	Key in keyof TArray as Key & (`${number}` | (IsTuple<TArray> extends true ? never : number))
+	]: TArray[Key];
+}>;

package/source/words.d.ts

@@ -1,11 +1,46 @@
-import type {IsLowerCase, IsNumeric, IsUpperCase, WordSeparators} from './internal';
+import type {
+	IsLowerCase,
+	IsNumeric,
+	IsUpperCase,
+	WordSeparators,
+} from './internal';
 
 type SkipEmptyWord<Word extends string> = Word extends '' ? [] : [Word];
 
-type RemoveLastCharacter<Sentence extends string, Character extends string> = Sentence extends `${infer LeftSide}${Character}`
+type RemoveLastCharacter<
+	Sentence extends string,
+	Character extends string,
+> = Sentence extends `${infer LeftSide}${Character}`
 	? SkipEmptyWord<LeftSide>
 	: never;
 
+/**
+Words options.
+
+@see {@link Words}
+*/
+export type WordsOptions = {
+	/**
+	Split on numeric sequence.
+
+	@default true
+
+	@example
+	```
+	type Example1 = Words<'p2pNetwork', {splitOnNumbers: true}>;
+	//=> ["p", "2", "p", "Network"]
+
+	type Example2 = Words<'p2pNetwork', {splitOnNumbers: false}>;
+	//=> ["p2p", "Network"]
+	```
+	*/
+	splitOnNumbers?: boolean;
+};
+
+type DefaultOptions = {
+	splitOnNumbers: true;
+};
+
 /**
 Split a string (almost) like Lodash's `_.words()` function.
 
@@ -31,37 +66,53 @@ type Words3 = Words<'--hello the_world'>;
 
 type Words4 = Words<'lifeIs42'>;
 //=> ['life', 'Is', '42']
+
+type Words5 = Words<'p2pNetwork', {splitOnNumbers: false}>;
+//=> ['p2p', 'Network']
 ```
 
 @category Change case
 @category Template literal
 */
-export type Words<
+export type Words<Sentence extends string, Options extends WordsOptions = {}> = WordsImplementation<Sentence, {
+	splitOnNumbers: Options['splitOnNumbers'] extends boolean ? Options['splitOnNumbers'] : DefaultOptions['splitOnNumbers'];
+}>;
+
+type WordsImplementation<
 	Sentence extends string,
+	Options extends Required<WordsOptions>,
 	LastCharacter extends string = '',
 	CurrentWord extends string = '',
 > = Sentence extends `${infer FirstCharacter}${infer RemainingCharacters}`
 	? FirstCharacter extends WordSeparators
 		// Skip word separator
-		? [...SkipEmptyWord<CurrentWord>, ...Words<RemainingCharacters>]
+		? [...SkipEmptyWord<CurrentWord>, ...WordsImplementation<RemainingCharacters, Options>]
 		: LastCharacter extends ''
 			// Fist char of word
-			? Words<RemainingCharacters, FirstCharacter, FirstCharacter>
-			// Case change: non-numeric to numeric, push word
+			? WordsImplementation<RemainingCharacters, Options, FirstCharacter, FirstCharacter>
+			// Case change: non-numeric to numeric
 			: [false, true] extends [IsNumeric<LastCharacter>, IsNumeric<FirstCharacter>]
-				? [...SkipEmptyWord<CurrentWord>, ...Words<RemainingCharacters, FirstCharacter, FirstCharacter>]
-				// Case change: numeric to non-numeric, push word
+				? Options['splitOnNumbers'] extends true
+					// Split on number: push word
+					? [...SkipEmptyWord<CurrentWord>, ...WordsImplementation<RemainingCharacters, Options, FirstCharacter, FirstCharacter>]
+					// No split on number: concat word
+					: WordsImplementation<RemainingCharacters, Options, FirstCharacter, `${CurrentWord}${FirstCharacter}`>
+				// Case change: numeric to non-numeric
 				: [true, false] extends [IsNumeric<LastCharacter>, IsNumeric<FirstCharacter>]
-					? [...SkipEmptyWord<CurrentWord>, ...Words<RemainingCharacters, FirstCharacter, FirstCharacter>]
+					? Options['splitOnNumbers'] extends true
+						// Split on number: push word
+						? [...SkipEmptyWord<CurrentWord>, ...WordsImplementation<RemainingCharacters, Options, FirstCharacter, FirstCharacter>]
+						// No split on number: concat word
+						: WordsImplementation<RemainingCharacters, Options, FirstCharacter, `${CurrentWord}${FirstCharacter}`>
 					// No case change: concat word
 					: [true, true] extends [IsNumeric<LastCharacter>, IsNumeric<FirstCharacter>]
-						? Words<RemainingCharacters, FirstCharacter, `${CurrentWord}${FirstCharacter}`>
+						? WordsImplementation<RemainingCharacters, Options, FirstCharacter, `${CurrentWord}${FirstCharacter}`>
 					// Case change: lower to upper, push word
 						: [true, true] extends [IsLowerCase<LastCharacter>, IsUpperCase<FirstCharacter>]
-							? [...SkipEmptyWord<CurrentWord>, ...Words<RemainingCharacters, FirstCharacter, FirstCharacter>]
+							? [...SkipEmptyWord<CurrentWord>, ...WordsImplementation<RemainingCharacters, Options, FirstCharacter, FirstCharacter>]
 						// Case change: upper to lower, brings back the last character, push word
 							: [true, true] extends [IsUpperCase<LastCharacter>, IsLowerCase<FirstCharacter>]
-								? [...RemoveLastCharacter<CurrentWord, LastCharacter>, ...Words<RemainingCharacters, FirstCharacter, `${LastCharacter}${FirstCharacter}`>]
+								? [...RemoveLastCharacter<CurrentWord, LastCharacter>, ...WordsImplementation<RemainingCharacters, Options, FirstCharacter, `${LastCharacter}${FirstCharacter}`>]
 							// No case change: concat word
-								: Words<RemainingCharacters, FirstCharacter, `${CurrentWord}${FirstCharacter}`>
+								: WordsImplementation<RemainingCharacters, Options, FirstCharacter, `${CurrentWord}${FirstCharacter}`>
 	: [...SkipEmptyWord<CurrentWord>];