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

package/source/non-nullable-deep.d.ts

@@ -0,0 +1,102 @@
+import type {BuiltIns, HasMultipleCallSignatures} from './internal/type.d.ts';
+import type {IsNever} from './is-never.d.ts';
+import type {Simplify} from './simplify.d.ts';
+
+/**
+Recursively removes `null` and `undefined` from the specified type.
+
+Use-cases:
+- Normalizing data received from external sources where `null`/`undefined` have been cleaned.
+- Creating non-nullable variants of deeply nested types.
+
+NOTE: Optional modifiers (`?`) are not removed from properties. For example, `NonNullableDeep<{foo?: string | null | undefined}>` will result in `{foo?: string}`. To remove both optional modifiers and nullables, use {@link RequiredDeep} in conjunction with this type.
+
+@example
+```
+import type {NonNullableDeep} from 'type-fest';
+
+type UserDraft = {
+	name: string | null;
+	address: {
+		city: string | undefined;
+		postalCode: string | null;
+		landmark?: string | undefined;
+	};
+	tags: Array<string | null>;
+	visits: Map<string | null, {
+		date: Date | null;
+		notes: Set<string | undefined>;
+	}>;
+};
+
+type User = NonNullableDeep<UserDraft>;
+//=> {
+// 	name: string;
+// 	address: {
+// 		city: string;
+// 		postalCode: string;
+// 		landmark?: string;
+// 	};
+// 	tags: string[];
+// 	visits: Map<string, {
+// 		date: Date;
+// 		notes: Set<string>;
+// 	}>;
+// }
+```
+
+@example
+```
+import type {NonNullableDeep} from 'type-fest';
+
+type ArrayExample = NonNullableDeep<[{a: number | undefined}, ...Array<{b: string | null}>]>;
+//=> [{a: number}, ...{b: string}[]]
+
+type MapExample = NonNullableDeep<{a: Map<{a: string | null}, {c: number | undefined}>}>;
+//=> {a: Map<{a: string}, {c: number}>}
+
+type SetExample = NonNullableDeep<Set<{a: string | null}> | null | undefined>;
+//=> Set<{a: string}>
+
+type PromiseExample = NonNullableDeep<{a: Promise<{b: string | null}>}>;
+//=> {a: Promise<{b: string}>}
+
+type FunctionExample = NonNullableDeep<(a: string | null) => number | undefined>;
+//=> (a: string) => number
+```
+
+@category Utilities
+@category Object
+@category Array
+@category Set
+@category Map
+*/
+export type NonNullableDeep<T> =
+	T extends BuiltIns | (new (...arguments_: any[]) => unknown)
+		? Exclude<T, null | undefined> // `Exclude` is used instead of `NonNullable` because `NonNullable<void>` results in `void & {}`.
+		: T extends Map<infer KeyType, infer ValueType>
+			? Map<NonNullableDeep<KeyType>, NonNullableDeep<ValueType>>
+			: T extends Set<infer ItemType>
+				? Set<NonNullableDeep<ItemType>>
+				: T extends ReadonlyMap<infer KeyType, infer ValueType>
+					? ReadonlyMap<NonNullableDeep<KeyType>, NonNullableDeep<ValueType>>
+					: T extends ReadonlySet<infer ItemType>
+						? ReadonlySet<NonNullableDeep<ItemType>>
+						: T extends WeakMap<infer KeyType, infer ValueType>
+							? WeakMap<NonNullableDeep<KeyType>, NonNullableDeep<ValueType>>
+							: T extends WeakSet<infer ItemType>
+								? WeakSet<NonNullableDeep<ItemType>>
+								: T extends Promise<infer ValueType>
+									? Promise<NonNullableDeep<ValueType>>
+									: T extends (...arguments_: any[]) => unknown
+										? HasMultipleCallSignatures<T> extends true
+											? T
+											: ((...arguments_: NonNullableDeep<Parameters<T>>) => NonNullableDeep<ReturnType<T>>)
+												& (IsNever<keyof T> extends true
+													? unknown
+													: NonNullableDeep<Simplify<T>>) // `Simplify` removes the call signature
+										: T extends object
+											? {[P in keyof T]: NonNullableDeep<T[P]>}
+											: unknown;
+
+export {};

package/source/numeric.d.ts

@@ -121,9 +121,9 @@ declare function setPercentage<T extends number>(length: Float<T>): void;
 @category Numeric
 */
 export type Float<T> =
-T extends unknown // To distributive type
-	? IsFloat<T> extends true ? T : never
-	: never; // Never happens
+	T extends unknown // To distributive type
+		? IsFloat<T> extends true ? T : never
+		: never; // Never happens
 
 /**
 A negative (`-∞ < x < 0`) `number` that is not an integer.

package/source/object-merge.d.ts

@@ -90,22 +90,27 @@ Note: If you want a simple merge where properties from the second object always
 @category Object
 */
 export type ObjectMerge<First extends object, Second extends object> =
-	IfNotAnyOrNever<First, IfNotAnyOrNever<Second, First extends unknown // For distributing `First`
-		? Second extends unknown // For distributing `Second`
-			? First extends MapsSetsOrArrays
-				? unknown
-				: Second extends MapsSetsOrArrays
-					? unknown
-					: _ObjectMerge<
-						First,
-						Second,
-						NormalizedLiteralKeys<First>,
-						NormalizedLiteralKeys<Second>,
-						IsExactOptionalPropertyTypesEnabled extends true ? Required<First> : First,
-						IsExactOptionalPropertyTypesEnabled extends true ? Required<Second> : Second
-					>
-			: never // Should never happen
-		: never>, First & Second>; // Should never happen
+	IfNotAnyOrNever<First, {
+		ifNot: IfNotAnyOrNever<Second, {
+			ifNot: First extends unknown // For distributing `First`
+				? Second extends unknown // For distributing `Second`
+					? First extends MapsSetsOrArrays
+						? unknown
+						: Second extends MapsSetsOrArrays
+							? unknown
+							: _ObjectMerge<
+								First,
+								Second,
+								NormalizedLiteralKeys<First>,
+								NormalizedLiteralKeys<Second>,
+								IsExactOptionalPropertyTypesEnabled extends true ? Required<First> : First,
+								IsExactOptionalPropertyTypesEnabled extends true ? Required<Second> : Second
+							>
+					: never // Should never happen
+				: never; // Should never happen
+		}>;
+		ifAny: First & Second;
+	}>;
 
 type _ObjectMerge<
 	First extends object,

package/source/omit-deep.d.ts

@@ -5,7 +5,6 @@ import type {IsNever} from './is-never.d.ts';
 import type {LiteralUnion} from './literal-union.d.ts';
 import type {Paths} from './paths.d.ts';
 import type {SimplifyDeep} from './simplify-deep.d.ts';
-import type {Simplify} from './simplify.d.ts';
 import type {UnionToTuple} from './union-to-tuple.d.ts';
 import type {UnknownArray} from './unknown-array.d.ts';
 
@@ -18,7 +17,7 @@ It supports removing specific items from an array, replacing each removed item w
 
 Use-case: Remove unneeded parts of complex objects.
 
-Use [`Omit`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys) if you only need one level deep.
+Use [`Omit<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#omittype-keys) if you only need one level deep.
 
 @example
 ```
@@ -94,34 +93,34 @@ type OmitDeepHelper<T, PathTuple extends UnknownArray> =
 Omit one path from the given object/array.
 */
 type OmitDeepWithOnePath<T, Path extends string | number> =
-T extends NonRecursiveType
-	? T
-	: T extends UnknownArray ? SetArrayAccess<OmitDeepArrayWithOnePath<T, Path>, IsArrayReadonly<T>>
-		: T extends object ? OmitDeepObjectWithOnePath<T, Path>
-			: T;
+	T extends NonRecursiveType
+		? T
+		: T extends UnknownArray ? SetArrayAccess<OmitDeepArrayWithOnePath<T, Path>, IsArrayReadonly<T>>
+			: T extends object ? OmitDeepObjectWithOnePath<T, Path>
+				: T;
 
 /**
 Omit one path from the given object.
 */
 type OmitDeepObjectWithOnePath<ObjectT extends object, P extends string | number> =
-P extends `${infer RecordKeyInPath}.${infer SubPath}`
-	? {
-		[Key in keyof ObjectT]:
-		IsEqual<RecordKeyInPath, ToString<Key>> extends true
-			? ExactKey<ObjectT, Key> extends infer RealKey
-				? RealKey extends keyof ObjectT
-					? OmitDeepWithOnePath<ObjectT[RealKey], SubPath>
+	P extends `${infer RecordKeyInPath}.${infer SubPath}`
+		? {
+			[Key in keyof ObjectT]:
+			IsEqual<RecordKeyInPath, ToString<Key>> extends true
+				? ExactKey<ObjectT, Key> extends infer RealKey
+					? RealKey extends keyof ObjectT
+						? OmitDeepWithOnePath<ObjectT[RealKey], SubPath>
+						: ObjectT[Key]
 					: ObjectT[Key]
 				: ObjectT[Key]
-			: ObjectT[Key]
-	}
-	: ExactKey<ObjectT, P> extends infer Key
-		? IsNever<Key> extends true
-			? ObjectT
-			: Key extends PropertyKey
-				? Simplify<Omit<ObjectT, Key>> // `Simplify` to prevent `Omit` from appearing in the resulting type
-				: ObjectT
-		: ObjectT;
+		}
+		: ExactKey<ObjectT, P> extends infer Key
+			? IsNever<Key> extends true
+				? ObjectT
+				: Key extends PropertyKey
+					? Omit<ObjectT, Key>
+					: ObjectT
+			: ObjectT;
 
 /**
 Omit one path from from the given array.

package/source/optional.d.ts

@@ -0,0 +1,31 @@
+/**
+Create a type that represents either the value or `undefined`, while stripping `null` from the type.
+
+Use-cases:
+- Enforcing the practice of using `undefined` instead of `null` as the "absence of value" marker.
+- Converting APIs that return `null` (DOM, JSON, legacy libraries) to use `undefined` consistently.
+
+@example
+```
+import type {Optional} from 'type-fest';
+
+// Adds `undefined` to the type
+type MaybeNumber = Optional<number>;
+//=> number | undefined
+
+// Strips `null` from the type
+type NullableString = Optional<string | null>;
+//=> string | undefined
+
+type Config = {
+	name: string;
+	description: Optional<string>;
+	//=> string | undefined
+};
+```
+
+@category Utilities
+*/
+export type Optional<Value> = Exclude<Value, null> | undefined;
+
+export {};

package/source/or-all.d.ts

@@ -0,0 +1,73 @@
+import type {SomeExtend} from './some-extend.d.ts';
+
+/**
+Returns a boolean for whether any of the given elements is `true`.
+
+Use-cases:
+- Check if at least one condition in a list of booleans is met.
+
+@example
+```
+import type {OrAll} from 'type-fest';
+
+type FFT = OrAll<[false, false, true]>;
+//=> true
+
+type FFF = OrAll<[false, false, false]>;
+//=> false
+```
+
+Note: When `boolean` is passed as an element, it is distributed into separate cases, and the final result is a union of those cases.
+For example, `OrAll<[false, boolean]>` expands to `OrAll<[false, true]> | OrAll<[false, false]>`, which simplifies to `true | false` (i.e., `boolean`).
+
+@example
+```
+import type {OrAll} from 'type-fest';
+
+type A = OrAll<[false, boolean]>;
+//=> boolean
+
+type B = OrAll<[true, boolean]>;
+//=> true
+```
+
+Note: If `never` is passed as an element, it is treated as `false` and the result is computed accordingly.
+
+@example
+```
+import type {OrAll} from 'type-fest';
+
+type A = OrAll<[never, never, true]>;
+//=> true
+
+type B = OrAll<[never, never, false]>;
+//=> false
+
+type C = OrAll<[never, never, never]>;
+//=> false
+
+type D = OrAll<[never, never, boolean]>;
+//=> boolean
+```
+
+Note: If `any` is passed as an element, it is treated as `boolean` and the result is computed accordingly.
+
+@example
+```
+import type {OrAll} from 'type-fest';
+
+type A = OrAll<[false, any]>;
+//=> boolean
+
+type B = OrAll<[true, any]>;
+//=> true
+```
+
+Note: `OrAll<[]>` evaluates to `false` because there are no `true` elements in an empty tuple. See [Wikipedia: Clause (logic) > Empty clauses](https://en.wikipedia.org/wiki/Clause_(logic)#Empty_clauses:~:text=The%20truth%20evaluation%20of%20an%20empty%20disjunctive%20clause%20is%20always%20false.).
+
+@see {@link Or}
+@see {@link AndAll}
+*/
+export type OrAll<T extends readonly boolean[]> = SomeExtend<T, true>;
+
+export {};

package/source/or.d.ts

@@ -1,8 +1,7 @@
-import type {If} from './if.d.ts';
-import type {IsNever} from './is-never.d.ts';
+import type {OrAll} from './or-all.d.ts';
 
 /**
-Returns a boolean for whether either of two given types is true.
+Returns a boolean for whether either of two given types is `true`.
 
 Use-case: Constructing complex conditional types where at least one condition must be satisfied.
 
@@ -74,16 +73,10 @@ type G = Or<never, never>;
 //=> false
 ```
 
+@see {@link OrAll}
 @see {@link And}
 @see {@link Xor}
 */
-export type Or<A extends boolean, B extends boolean> =
-	_Or<If<IsNever<A>, false, A>, If<IsNever<B>, false, B>>; // `never` is treated as `false`
-
-export type _Or<A extends boolean, B extends boolean> = A extends true
-	? true
-	: B extends true
-		? true
-		: false;
+export type Or<A extends boolean, B extends boolean> = OrAll<[A, B]>;
 
 export {};

package/source/package-json.d.ts

@@ -699,12 +699,12 @@ Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-j
 @category File
 */
 export type PackageJson =
-	JsonObject &
-	PackageJson.NodeJsStandard &
-	PackageJson.PackageJsonStandard &
-	PackageJson.NonStandardEntryPoints &
-	PackageJson.TypeScriptConfiguration &
-	PackageJson.YarnConfiguration &
-	PackageJson.JSPMConfiguration;
+	JsonObject
+	& PackageJson.NodeJsStandard
+	& PackageJson.PackageJsonStandard
+	& PackageJson.NonStandardEntryPoints
+	& PackageJson.TypeScriptConfiguration
+	& PackageJson.YarnConfiguration
+	& PackageJson.JSPMConfiguration;
 
 export {};

package/source/partial-deep.d.ts

@@ -44,12 +44,14 @@ type DefaultPartialDeepOptions = {
 };
 
 /**
-Create a type from another type with all keys and nested keys set to optional.
+Create a deeply optional version of another type.
 
 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.
 
+Use [`Partial<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype) if you only need one level deep.
+
 @example
 ```
 import type {PartialDeep} from 'type-fest';

package/source/pascal-case.d.ts

@@ -12,6 +12,7 @@ import type {PascalCase} from 'type-fest';
 
 const someVariable: PascalCase<'foo-bar'> = 'FooBar';
 const preserveConsecutiveUppercase: PascalCase<'foo-BAR-baz', {preserveConsecutiveUppercase: true}> = 'FooBARBaz';
+const splitOnPunctuation: PascalCase<'foo-bar>>baz', {splitOnPunctuation: true}> = 'FooBarBaz';
 
 // Advanced
 

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

@@ -48,6 +48,13 @@ const preserveConsecutiveUppercase: PascalCasedPropertiesDeep<{fooBAR: {fooBARBi
 		}],
 	},
 };
+
+const splitOnPunctuation: PascalCasedPropertiesDeep<{'user@info': {'user::id': number; 'user::name': string}}, {splitOnPunctuation: true}> = {
+	UserInfo: {
+		UserId: 1,
+		UserName: 'Tom',
+	},
+};
 ```
 
 @category Change case

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

@@ -3,7 +3,7 @@ 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.
+Convert top-level object properties to pascal case.
 
 This can be useful when, for example, converting some API types from a different style.
 
@@ -27,6 +27,10 @@ const result: PascalCasedProperties<User> = {
 const preserveConsecutiveUppercase: PascalCasedProperties<{fooBAR: string}, {preserveConsecutiveUppercase: true}> = {
 	FooBAR: 'string',
 };
+
+const splitOnPunctuation: PascalCasedProperties<{'foo::bar': string}, {splitOnPunctuation: true}> = {
+	FooBar: 'string',
+};
 ```
 
 @category Change case

package/source/pick-deep.d.ts

@@ -5,6 +5,7 @@ import type {Paths} from './paths.d.ts';
 import type {Simplify} from './simplify.d.ts';
 import type {UnionToIntersection} from './union-to-intersection.d.ts';
 import type {UnknownArray} from './unknown-array.d.ts';
+import type {SimplifyDeep} from './simplify-deep.d.ts';
 
 /**
 Pick properties from a deeply-nested object.
@@ -13,6 +14,8 @@ It supports recursing into arrays.
 
 Use-case: Distill complex objects down to the components you need to target.
 
+Use [`Pick<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#picktype-keys) if you only need one level deep.
+
 @example
 ```
 import type {PickDeep, PartialDeep} from 'type-fest';
@@ -36,24 +39,15 @@ type Configuration = {
 };
 
 type NameConfig = PickDeep<Configuration, 'userConfig.name'>;
-// type NameConfig = {
-// 	userConfig: {
-// 		name: string;
-// 	}
-// };
+//=> {userConfig: {name: string}}
 
 // Supports optional properties
 type User = PickDeep<PartialDeep<Configuration>, 'userConfig.name' | 'userConfig.age'>;
-// type User = {
-// 	userConfig?: {
-// 		name?: string;
-// 		age?: number;
-// 	};
-// };
+//=> {userConfig?: {name?: string; age?: number}}
 
 // Supports array
 type AddressConfig = PickDeep<Configuration, 'userConfig.address.0'>;
-// type AddressConfig = {
+//=> {
 // 	userConfig: {
 // 		address: [{
 // 			city1: string;
@@ -64,14 +58,7 @@ type AddressConfig = PickDeep<Configuration, 'userConfig.address.0'>;
 
 // Supports recurse into array
 type Street = PickDeep<Configuration, 'userConfig.address.1.street2'>;
-// type Street = {
-// 	userConfig: {
-// 		address: [
-// 			unknown,
-// 			{street2: string}
-// 		];
-// 	};
-// }
+//=> {userConfig: {address: [unknown, {street2: string}]}}
 ```
 
 @category Object
@@ -86,7 +73,7 @@ export type PickDeep<T, PathUnion extends Paths<T>> =
 			}[PathUnion]
 			>
 			: T extends object
-				? Simplify<UnionToIntersection<{
+				? SimplifyDeep<UnionToIntersection<{
 					[P in PathUnion]: InternalPickDeep<T, P>;
 				}[PathUnion]>>
 				: never;

package/source/readonly-deep.d.ts

@@ -1,12 +1,14 @@
 import type {BuiltIns, HasMultipleCallSignatures} from './internal/index.d.ts';
 
 /**
-Convert `object`s, `Map`s, `Set`s, and `Array`s and all of their keys/elements into immutable structures recursively.
+Create a deeply immutable version of another type.
 
 This is useful when a deeply nested structure needs to be exposed as completely immutable, for example, an imported JSON module or when receiving an API response that is passed around.
 
 Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/13923) if you want to have this type as a built-in in TypeScript.
 
+Use [`Readonly<T>`](https://www.typescriptlang.org/docs/handbook/utility-types.html#readonlytype) if you only need one level deep.
+
 @example
 ```
 import type {ReadonlyDeep} from 'type-fest';
@@ -83,8 +85,8 @@ export type ReadonlyDeep<T> = T extends BuiltIns
 				? ReadonlyMapDeep<KeyType, ValueType>
 				: T extends Readonly<ReadonlySet<infer ItemType>>
 					? ReadonlySetDeep<ItemType>
-					: // Identify tuples to avoid converting them to arrays inadvertently; special case `readonly [...never[]]`, as it emerges undesirably from recursive invocations of ReadonlyDeep below.
-					T extends readonly [] | readonly [...never[]]
+					// Identify tuples to avoid converting them to arrays inadvertently; special case `readonly [...never[]]`, as it emerges undesirably from recursive invocations of ReadonlyDeep below.
+					: T extends readonly [] | readonly [...never[]]
 						? readonly []
 						: T extends readonly [infer U, ...infer V]
 							? readonly [ReadonlyDeep<U>, ...ReadonlyDeep<V>]

package/source/remove-prefix.d.ts

@@ -1,7 +1,9 @@
 import type {ApplyDefaultOptions} from './internal/object.d.ts';
 import type {IfNotAnyOrNever, Not} from './internal/type.d.ts';
-import type {IsStringLiteral} from './is-literal.d.ts';
+import type {IsStringLiteral} from './is-string-literal.d.ts';
+import type {IsNever} from './is-never.d.ts';
 import type {Or} from './or.d.ts';
+import type {If} from './if.d.ts';
 
 /**
 @see {@link RemovePrefix}
@@ -58,24 +60,6 @@ export type RemovePrefixOptions = {
 	type D = RemovePrefix<`id-${number}`, 'id-', {strict: false}>;
 	//=> `${number}`
 	```
-
-	Note: If it can be statically determined that the input string can never start with the specified non-literal prefix, then the input string is returned as-is, regardless of the value of this option.
-	For example, ``RemovePrefix<`${string}/${number}`, `${string}:`>`` returns `` `${string}/${number}` ``, since a string of type `` `${string}/${number}` `` can never start with a prefix of type `` `${string}:` ``.
-	```
-	import type {RemovePrefix} from 'type-fest';
-
-	type A = RemovePrefix<`${string}/${number}`, `${string}:`, {strict: true}>;
-	//=> `${string}/${number}`
-
-	type B = RemovePrefix<`${string}/${number}`, `${string}:`, {strict: false}>;
-	//=> `${string}/${number}`
-
-	type C = RemovePrefix<'on-change', `${number}-`, {strict: true}>;
-	//=> 'on-change'
-
-	type D = RemovePrefix<'on-change', `${number}-`, {strict: false}>;
-	//=> 'on-change'
-	```
 	*/
 	strict?: boolean;
 };
@@ -110,23 +94,21 @@ type D = RemovePrefix<`handle${Capitalize<string>}`, 'handle'>;
 @category Template literal
 */
 export type RemovePrefix<S extends string, Prefix extends string, Options extends RemovePrefixOptions = {}> =
-IfNotAnyOrNever<
-	S,
-	IfNotAnyOrNever<
-		Prefix,
-		_RemovePrefix<S, Prefix, ApplyDefaultOptions<RemovePrefixOptions, DefaultRemovePrefixOptions, Options>>,
-		string,
-		S
-	>
->;
+	IfNotAnyOrNever<S, {
+		ifNot: If<
+			IsNever<Prefix>,
+			S,
+			_RemovePrefix<S, Prefix, ApplyDefaultOptions<RemovePrefixOptions, DefaultRemovePrefixOptions, Options>>
+		>;
+	}>;
 
 type _RemovePrefix<S extends string, Prefix extends string, Options extends Required<RemovePrefixOptions>> =
-Prefix extends string // For distributing `Prefix`
-	? S extends `${Prefix}${infer Rest}`
+	Prefix extends string // For distributing `Prefix`
 		? Or<IsStringLiteral<Prefix>, Not<Options['strict']>> extends true
-			? Rest
-			: string // Fallback to `string` when `Prefix` is non-literal and `strict` is disabled
-		: S // Return back `S` when `Prefix` is not present at the start of `S`
-	: never;
+			? S extends `${Prefix}${infer Rest}`
+				? Rest
+				: S // Return back `S` when `Prefix` is not present at the start of `S`
+			: string // Fallback to `string` when `Prefix` is non-literal and `strict` is enabled
+		: never;
 
 export {};