@depup/type-fest 5.4.4-depup.0

package/source/partial-deep.d.ts

@@ -0,0 +1,155 @@
+import type {ApplyDefaultOptions, BuiltIns, HasMultipleCallSignatures} from './internal/index.d.ts';
+import type {IsNever} from './is-never.d.ts';
+
+/**
+@see {@link PartialDeep}
+*/
+export type PartialDeepOptions = {
+	/**
+	Whether to affect the individual elements of arrays and tuples.
+
+	@default false
+	*/
+	readonly recurseIntoArrays?: boolean;
+
+	/**
+	Allows `undefined` values in non-tuple arrays.
+
+	- When set to `true`, elements of non-tuple arrays can be `undefined`.
+	- When set to `false`, only explicitly defined elements are allowed in non-tuple arrays, ensuring stricter type checking.
+
+	@default false
+
+	@example
+	You can allow `undefined` values in non-tuple arrays by passing `{recurseIntoArrays: true; allowUndefinedInNonTupleArrays: true}` as the second type argument:
+
+	```
+	import type {PartialDeep} from 'type-fest';
+
+	type Settings = {
+		languages: string[];
+	};
+
+	declare const partialSettings: PartialDeep<Settings, {recurseIntoArrays: true; allowUndefinedInNonTupleArrays: true}>;
+
+	partialSettings.languages = [undefined]; // OK
+	```
+	*/
+	readonly allowUndefinedInNonTupleArrays?: boolean;
+};
+
+type DefaultPartialDeepOptions = {
+	recurseIntoArrays: false;
+	allowUndefinedInNonTupleArrays: false;
+};
+
+/**
+Create a type from another type with all keys and nested keys set to optional.
+
+Use-cases:
+- Merging a default settings/config object with another object, the second object would be a deep partial of the default object.
+- Mocking and testing complex entities, where populating an entire object with its keys would be redundant in terms of the mock or test.
+
+@example
+```
+import type {PartialDeep} from 'type-fest';
+
+let settings = {
+	textEditor: {
+		fontSize: 14,
+		fontColor: '#000000',
+		fontWeight: 400,
+	},
+	autocomplete: false,
+	autosave: true,
+};
+
+const applySavedSettings = (savedSettings: PartialDeep<typeof settings>) => (
+	{...settings, ...savedSettings, textEditor: {...settings.textEditor, ...savedSettings.textEditor}}
+);
+
+settings = applySavedSettings({textEditor: {fontWeight: 500}});
+```
+
+By default, this does not affect elements in array and tuple types. You can change this by passing `{recurseIntoArrays: true}` as the second type argument:
+
+```
+import type {PartialDeep} from 'type-fest';
+
+type Shape = {
+	dimensions: [number, number];
+};
+
+const partialShape: PartialDeep<Shape, {recurseIntoArrays: true}> = {
+	dimensions: [], // OK
+};
+
+partialShape.dimensions = [15]; // OK
+```
+
+@see {@link PartialDeepOptions}
+
+@category Object
+@category Array
+@category Set
+@category Map
+*/
+export type PartialDeep<T, Options extends PartialDeepOptions = {}> =
+	_PartialDeep<T, ApplyDefaultOptions<PartialDeepOptions, DefaultPartialDeepOptions, Options>>;
+
+type _PartialDeep<T, Options extends Required<PartialDeepOptions>> = T extends BuiltIns | ((new (...arguments_: any[]) => unknown))
+	? T
+	: T extends Map<infer KeyType, infer ValueType>
+		? PartialMapDeep<KeyType, ValueType, Options>
+		: T extends Set<infer ItemType>
+			? PartialSetDeep<ItemType, Options>
+			: T extends ReadonlyMap<infer KeyType, infer ValueType>
+				? PartialReadonlyMapDeep<KeyType, ValueType, Options>
+				: T extends ReadonlySet<infer ItemType>
+					? PartialReadonlySetDeep<ItemType, Options>
+					: T extends (...arguments_: any[]) => unknown
+						? IsNever<keyof T> extends true
+							? T // For functions with no properties
+							: HasMultipleCallSignatures<T> extends true
+								? T
+								: ((...arguments_: Parameters<T>) => ReturnType<T>) & PartialObjectDeep<T, Options>
+						: T extends object
+							? T extends ReadonlyArray<infer ItemType> // Test for arrays/tuples, per https://github.com/microsoft/TypeScript/issues/35156
+								? Options['recurseIntoArrays'] extends true
+									? ItemType[] extends T // Test for arrays (non-tuples) specifically
+										? readonly ItemType[] extends T // Differentiate readonly and mutable arrays
+											? ReadonlyArray<_PartialDeep<Options['allowUndefinedInNonTupleArrays'] extends false ? ItemType : ItemType | undefined, Options>>
+											: Array<_PartialDeep<Options['allowUndefinedInNonTupleArrays'] extends false ? ItemType : ItemType | undefined, Options>>
+										: PartialObjectDeep<T, Options> // Tuples behave properly
+									: T // If they don't opt into array testing, just use the original type
+								: PartialObjectDeep<T, Options>
+							: unknown;
+
+/**
+Same as `PartialDeep`, but accepts only `Map`s and as inputs. Internal helper for `PartialDeep`.
+*/
+type PartialMapDeep<KeyType, ValueType, Options extends Required<PartialDeepOptions>> = {} & Map<_PartialDeep<KeyType, Options>, _PartialDeep<ValueType, Options>>;
+
+/**
+Same as `PartialDeep`, but accepts only `Set`s as inputs. Internal helper for `PartialDeep`.
+*/
+type PartialSetDeep<T, Options extends Required<PartialDeepOptions>> = {} & Set<_PartialDeep<T, Options>>;
+
+/**
+Same as `PartialDeep`, but accepts only `ReadonlyMap`s as inputs. Internal helper for `PartialDeep`.
+*/
+type PartialReadonlyMapDeep<KeyType, ValueType, Options extends Required<PartialDeepOptions>> = {} & ReadonlyMap<_PartialDeep<KeyType, Options>, _PartialDeep<ValueType, Options>>;
+
+/**
+Same as `PartialDeep`, but accepts only `ReadonlySet`s as inputs. Internal helper for `PartialDeep`.
+*/
+type PartialReadonlySetDeep<T, Options extends Required<PartialDeepOptions>> = {} & ReadonlySet<_PartialDeep<T, Options>>;
+
+/**
+Same as `PartialDeep`, but accepts only `object`s as inputs. Internal helper for `PartialDeep`.
+*/
+type PartialObjectDeep<ObjectType extends object, Options extends Required<PartialDeepOptions>> = {
+	[KeyType in keyof ObjectType]?: _PartialDeep<ObjectType[KeyType], Options>
+};
+
+export {};

package/source/partial-on-undefined-deep.d.ts

@@ -0,0 +1,81 @@
+import type {If} from './if.d.ts';
+import type {ApplyDefaultOptions, BuiltIns, LiteralKeyOf} from './internal/index.d.ts';
+import type {IsUnknown} from './is-unknown.d.ts';
+import type {Merge} from './merge.d.ts';
+
+/**
+@see {@link PartialOnUndefinedDeep}
+*/
+export type PartialOnUndefinedDeepOptions = {
+	/**
+	Whether to affect the individual elements of arrays and tuples.
+
+	@default false
+	*/
+	readonly recurseIntoArrays?: boolean;
+};
+
+type DefaultPartialOnUndefinedDeepOptions = {
+	recurseIntoArrays: false;
+};
+
+/**
+Create a deep version of another type where all keys accepting `undefined` type are set to optional.
+
+This utility type is recursive, transforming at any level deep. By default, it does not affect arrays and tuples items unless you explicitly pass `{recurseIntoArrays: true}` as the second type argument.
+
+Use-cases:
+- Make all properties of a type that can be undefined optional to not have to specify keys with undefined value.
+
+@example
+```
+import type {PartialOnUndefinedDeep} from 'type-fest';
+
+type Settings = {
+	optionA: string;
+	optionB: number | undefined;
+	subOption: {
+		subOptionA: boolean;
+		subOptionB: boolean | undefined;
+	};
+};
+
+const testSettings: PartialOnUndefinedDeep<Settings> = {
+	optionA: 'foo',
+	// 👉 optionB is now optional and can be omitted
+	subOption: {
+		subOptionA: true,
+		// 👉 subOptionB is now optional as well and can be omitted
+	},
+};
+```
+
+@category Object
+*/
+export type PartialOnUndefinedDeep<T, Options extends PartialOnUndefinedDeepOptions = {}> =
+	_PartialOnUndefinedDeep<T, ApplyDefaultOptions<PartialOnUndefinedDeepOptions, DefaultPartialOnUndefinedDeepOptions, Options>>;
+
+type _PartialOnUndefinedDeep<T, Options extends Required<PartialOnUndefinedDeepOptions>> = T extends Record<any, any> | undefined
+	? {[KeyType in keyof T as undefined extends T[KeyType] ? If<IsUnknown<T[KeyType]>, never, KeyType> : never]?: PartialOnUndefinedDeepValue<T[KeyType], Options>} extends infer U // Make a partial type with all value types accepting undefined (and set them optional)
+		? Merge<{[KeyType in keyof T as KeyType extends LiteralKeyOf<U> ? never : KeyType]: PartialOnUndefinedDeepValue<T[KeyType], Options>}, U> // Join all remaining keys not treated in U
+		: never // Should not happen
+	: T;
+
+/**
+Utility type to get the value type by key and recursively call `PartialOnUndefinedDeep` to transform sub-objects.
+*/
+type PartialOnUndefinedDeepValue<T, Options extends Required<PartialOnUndefinedDeepOptions>> = T extends BuiltIns | ((...arguments_: any[]) => unknown)
+	? T
+	: T extends ReadonlyArray<infer U> // Test if type is array or tuple
+		? Options['recurseIntoArrays'] extends true // Check if option is activated
+			? U[] extends T // Check if array not tuple
+				? readonly U[] extends T
+					? ReadonlyArray<_PartialOnUndefinedDeep<U, Options>> // Readonly array treatment
+					: Array<_PartialOnUndefinedDeep<U, Options>> // Mutable array treatment
+				: _PartialOnUndefinedDeep<{[Key in keyof T]: _PartialOnUndefinedDeep<T[Key], Options>}, Options> // Tuple treatment
+			: T
+		: T extends Record<any, any> | undefined
+			? _PartialOnUndefinedDeep<T, Options>
+			: unknown;
+
+export {};

package/source/pascal-case.d.ts

@@ -0,0 +1,51 @@
+import type {CamelCase, CamelCaseOptions, _DefaultCamelCaseOptions} from './camel-case.d.ts';
+import type {ApplyDefaultOptions} from './internal/index.d.ts';
+
+/**
+Convert a string literal to pascal-case.
+
+@example
+```
+import type {PascalCase} from 'type-fest';
+
+// Simple
+
+const someVariable: PascalCase<'foo-bar'> = 'FooBar';
+const preserveConsecutiveUppercase: PascalCase<'foo-BAR-baz', {preserveConsecutiveUppercase: true}> = 'FooBARBaz';
+
+// Advanced
+
+type PascalCasedProperties<T> = {
+	[K in keyof T as PascalCase<K>]: T[K]
+};
+
+type RawOptions = {
+	'dry-run': boolean;
+	'full_family_name': string;
+	foo: number;
+	BAR: string;
+	QUZ_QUX: number;
+	'OTHER-FIELD': boolean;
+};
+
+const dbResult: PascalCasedProperties<RawOptions> = {
+	DryRun: true,
+	FullFamilyName: 'bar.js',
+	Foo: 123,
+	Bar: 'foo',
+	QuzQux: 6,
+	OtherField: false,
+};
+```
+
+@category Change case
+@category Template literal
+*/
+export type PascalCase<Value, Options extends CamelCaseOptions = {}> =
+	_PascalCase<Value, ApplyDefaultOptions<CamelCaseOptions, _DefaultCamelCaseOptions, Options>>;
+
+type _PascalCase<Value, Options extends Required<CamelCaseOptions>> = CamelCase<Value, Options> extends string
+	? Capitalize<CamelCase<Value, Options>>
+	: CamelCase<Value, Options>;
+
+export {};

package/source/pascal-cased-properties-deep.d.ts

@@ -0,0 +1,72 @@
+import type {CamelCaseOptions, _DefaultCamelCaseOptions} from './camel-case.d.ts';
+import type {ApplyDefaultOptions} from './internal/index.d.ts';
+import type {PascalCase} from './pascal-case.d.ts';
+
+/**
+Convert object properties to pascal case recursively.
+
+This can be useful when, for example, converting some API types from a different style.
+
+@see {@link PascalCase}
+@see {@link PascalCasedProperties}
+
+@example
+```
+import type {PascalCasedPropertiesDeep} from 'type-fest';
+
+type User = {
+	userId: number;
+	userName: string;
+};
+
+type UserWithFriends = {
+	userInfo: User;
+	userFriends: User[];
+};
+
+const result: PascalCasedPropertiesDeep<UserWithFriends> = {
+	UserInfo: {
+		UserId: 1,
+		UserName: 'Tom',
+	},
+	UserFriends: [
+		{
+			UserId: 2,
+			UserName: 'Jerry',
+		},
+		{
+			UserId: 3,
+			UserName: 'Spike',
+		},
+	],
+};
+
+const preserveConsecutiveUppercase: PascalCasedPropertiesDeep<{fooBAR: {fooBARBiz: [{fooBARBaz: string}]}}, {preserveConsecutiveUppercase: true}> = {
+	FooBAR: {
+		FooBARBiz: [{
+			FooBARBaz: 'string',
+		}],
+	},
+};
+```
+
+@category Change case
+@category Template literal
+@category Object
+*/
+export type PascalCasedPropertiesDeep<Value, Options extends CamelCaseOptions = {}> =
+	_PascalCasedPropertiesDeep<Value, ApplyDefaultOptions<CamelCaseOptions, _DefaultCamelCaseOptions, Options>>;
+
+type _PascalCasedPropertiesDeep<Value, Options extends Required<CamelCaseOptions>> = Value extends Function | Date | RegExp
+	? Value
+	: Value extends Array<infer U>
+		? Array<_PascalCasedPropertiesDeep<U, Options>>
+		: Value extends Set<infer U>
+			? Set<_PascalCasedPropertiesDeep<U, Options>>
+			: Value extends object
+				? {
+					[K in keyof Value as PascalCase<K, Options>]: _PascalCasedPropertiesDeep<Value[K], Options>;
+				}
+				: Value;
+
+export {};

package/source/pascal-cased-properties.d.ts

@@ -0,0 +1,42 @@
+import type {CamelCaseOptions, _DefaultCamelCaseOptions} from './camel-case.d.ts';
+import type {ApplyDefaultOptions} from './internal/index.d.ts';
+import type {PascalCase} from './pascal-case.d.ts';
+
+/**
+Convert object properties to pascal case but not recursively.
+
+This can be useful when, for example, converting some API types from a different style.
+
+@see {@link PascalCase}
+@see {@link PascalCasedPropertiesDeep}
+
+@example
+```
+import type {PascalCasedProperties} from 'type-fest';
+
+type User = {
+	userId: number;
+	userName: string;
+};
+
+const result: PascalCasedProperties<User> = {
+	UserId: 1,
+	UserName: 'Tom',
+};
+
+const preserveConsecutiveUppercase: PascalCasedProperties<{fooBAR: string}, {preserveConsecutiveUppercase: true}> = {
+	FooBAR: 'string',
+};
+```
+
+@category Change case
+@category Template literal
+@category Object
+*/
+export type PascalCasedProperties<Value, Options extends CamelCaseOptions = {}> = Value extends Function
+	? Value
+	: Value extends Array<infer U>
+		? Value
+		: {[K in keyof Value as PascalCase<K, ApplyDefaultOptions<CamelCaseOptions, _DefaultCamelCaseOptions, Options>>]: Value[K]};
+
+export {};

package/source/paths.d.ts

@@ -0,0 +1,241 @@
+import type {NonRecursiveType, ToString, IsNumberLike, ApplyDefaultOptions, MapsSetsOrArrays} from './internal/index.d.ts';
+import type {IsAny} from './is-any.d.ts';
+import type {UnknownArray} from './unknown-array.d.ts';
+import type {GreaterThan} from './greater-than.d.ts';
+import type {IsNever} from './is-never.d.ts';
+import type {Sum} from './sum.d.ts';
+import type {And} from './and.d.ts';
+
+/**
+Paths options.
+
+@see {@link Paths}
+*/
+export type PathsOptions = {
+	/**
+	The maximum depth to recurse when searching for paths. Range: 0 ~ 10.
+
+	@default 5
+	*/
+	maxRecursionDepth?: number;
+
+	/**
+	Use bracket notation for array indices and numeric object keys.
+
+	@default false
+
+	@example
+	```
+	import type {Paths} from 'type-fest';
+
+	type ArrayExample = {
+		array: ['foo'];
+	};
+
+	type A = Paths<ArrayExample, {bracketNotation: false}>;
+	//=> 'array' | 'array.0'
+
+	type B = Paths<ArrayExample, {bracketNotation: true}>;
+	//=> 'array' | 'array[0]'
+	```
+
+	@example
+	```
+	import type {Paths} from 'type-fest';
+
+	type NumberKeyExample = {
+		1: ['foo'];
+	};
+
+	type A = Paths<NumberKeyExample, {bracketNotation: false}>;
+	//=> 1 | '1' | '1.0'
+
+	type B = Paths<NumberKeyExample, {bracketNotation: true}>;
+	//=> '[1]' | '[1][0]'
+	```
+	*/
+	bracketNotation?: boolean;
+
+	/**
+	Only include leaf paths in the output.
+
+	@default false
+
+	@example
+	```
+	import type {Paths} from 'type-fest';
+
+	type Post = {
+		id: number;
+		author: {
+			id: number;
+			name: {
+				first: string;
+				last: string;
+			};
+		};
+	};
+
+	type AllPaths = Paths<Post, {leavesOnly: false}>;
+	//=> 'id' | 'author' | 'author.id' | 'author.name' | 'author.name.first' | 'author.name.last'
+
+	type LeafPaths = Paths<Post, {leavesOnly: true}>;
+	//=> 'id' | 'author.id' | 'author.name.first' | 'author.name.last'
+	```
+
+	@example
+	```
+	import type {Paths} from 'type-fest';
+
+	type ArrayExample = {
+		array: Array<{foo: string}>;
+		tuple: [string, {bar: string}];
+	};
+
+	type AllPaths = Paths<ArrayExample, {leavesOnly: false}>;
+	//=> 'array' | 'tuple' | `array.${number}` | `array.${number}.foo` | 'tuple.0' | 'tuple.1' | 'tuple.1.bar'
+
+	type LeafPaths = Paths<ArrayExample, {leavesOnly: true}>;
+	//=> `array.${number}.foo` | 'tuple.0' | 'tuple.1.bar'
+	```
+	*/
+	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
+	```
+	import type {Paths} from 'type-fest';
+
+	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: 5;
+	bracketNotation: false;
+	leavesOnly: false;
+	depth: number;
+};
+
+/**
+Generate a union of all possible paths to properties in the given object.
+
+It also works with arrays.
+
+Use-case: You want a type-safe way to access deeply nested properties in an object.
+
+@example
+```
+import type {Paths} from 'type-fest';
+
+type Project = {
+	filename: string;
+	listA: string[];
+	listB: [{filename: string}];
+	folder: {
+		subfolder: {
+			filename: string;
+		};
+	};
+};
+
+type ProjectPaths = Paths<Project>;
+//=> 'filename' | 'listA' | 'listB' | 'folder' | `listA.${number}` | 'listB.0' | 'listB.0.filename' | 'folder.subfolder' | 'folder.subfolder.filename'
+
+declare function open<Path extends ProjectPaths>(path: Path): void;
+
+open('filename'); // Pass
+open('folder.subfolder'); // Pass
+open('folder.subfolder.filename'); // Pass
+// @ts-expect-error
+open('foo'); // TypeError
+
+// Also works with arrays
+open('listA.1'); // Pass
+open('listB.0'); // Pass
+// @ts-expect-error
+open('listB.1'); // TypeError. Because listB only has one element.
+```
+
+@category Object
+@category Array
+*/
+export type Paths<T, Options extends PathsOptions = {}> = _Paths<T, ApplyDefaultOptions<PathsOptions, DefaultPathsOptions, Options>>;
+
+type _Paths<T, Options extends Required<PathsOptions>, CurrentDepth extends number = 0> =
+	T extends NonRecursiveType | Exclude<MapsSetsOrArrays, UnknownArray>
+		? never
+		: IsAny<T> extends true
+			? never
+			: T extends object
+				? InternalPaths<Required<T>, Options, CurrentDepth>
+				: never;
+
+type InternalPaths<T, Options extends Required<PathsOptions>, CurrentDepth extends number> =
+	{[Key in keyof T]: Key extends string | number // Limit `Key` to `string | number`
+		? (
+			And<Options['bracketNotation'], IsNumberLike<Key>> extends true
+				? `[${Key}]`
+				: CurrentDepth extends 0
+					// Return both `Key` and `ToString<Key>` because for number keys, like `1`, both `1` and `'1'` are valid keys.
+					? Key | ToString<Key>
+					: `.${(Key | ToString<Key>)}`
+		) extends infer TransformedKey extends string | number
+			? ((Options['leavesOnly'] extends true
+				? Options['maxRecursionDepth'] extends CurrentDepth
+					? TransformedKey
+					: IsNever<T[Key]> extends true
+						? TransformedKey
+						: T[Key] extends infer Value // For distributing `T[Key]`
+							? (Value extends readonly [] | NonRecursiveType | Exclude<MapsSetsOrArrays, UnknownArray>
+								? TransformedKey
+								: IsNever<keyof Value> extends true // Check for empty object & `unknown`, because `keyof unknown` is `never`.
+									? TransformedKey
+									: never)
+							: never // Should never happen
+				: TransformedKey
+			) extends infer _TransformedKey
+				// If `depth` is provided, the condition becomes truthy only when it matches `CurrentDepth`.
+				// Otherwise, since `depth` defaults to `number`, the condition is always truthy, returning paths at all depths.
+				? CurrentDepth extends Options['depth']
+					? _TransformedKey
+					: never
+				: never)
+			// Recursively generate paths for the current key
+			| (GreaterThan<Options['maxRecursionDepth'], CurrentDepth> extends true // Limit the depth to prevent infinite recursion
+				? `${TransformedKey}${_Paths<T[Key], Options, Sum<CurrentDepth, 1>> & (string | number)}`
+				: never)
+			: never
+		: never
+	}[keyof T & (T extends UnknownArray ? number : unknown)];
+
+export {};