type-fest 4.34.0 → 4.35.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.0",
+	"version": "4.35.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/omit-deep.d.ts

@@ -1,4 +1,3 @@
-import type {UnionToTuple} from 'expect-type';
 import type {ArraySplice} from './array-splice';
 import type {ExactKey, IsArrayReadonly, NonRecursiveType, SetArrayAccess, ToString} from './internal';
 import type {IsEqual} from './is-equal';
@@ -6,6 +5,7 @@ import type {IsNever} from './is-never';
 import type {LiteralUnion} from './literal-union';
 import type {Paths} from './paths';
 import type {SimplifyDeep} from './simplify-deep';
+import type {UnionToTuple} from './union-to-tuple';
 import type {UnknownArray} from './unknown-array';
 
 /**

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/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];
+}>;