@depup/type-fest 5.4.4-depup.0

package/source/non-empty-object.d.ts

@@ -0,0 +1,38 @@
+import type {HasRequiredKeys} from './has-required-keys.d.ts';
+import type {RequireAtLeastOne} from './require-at-least-one.d.ts';
+
+/**
+Represents an object with at least 1 non-optional key.
+
+This is useful when you need an object where all keys are optional, but there must be at least 1 key.
+
+@example
+```
+import type {NonEmptyObject} from 'type-fest';
+
+type User = {
+	name: string;
+	surname: string;
+	id: number;
+};
+
+type UpdateRequest<Entity extends object> = NonEmptyObject<Partial<Entity>>;
+
+const update1: UpdateRequest<User> = {
+	name: 'Alice',
+	surname: 'Acme',
+};
+
+// At least 1 key is required, therefore this will report a 2322 error:
+// Type '{}' is not assignable to type 'UpdateRequest<User>'
+// @ts-expect-error
+const update2: UpdateRequest<User> = {};
+```
+
+@see Use `IsEmptyObject` to check whether an object is empty.
+
+@category Object
+*/
+export type NonEmptyObject<T extends object> = HasRequiredKeys<T> extends true ? T : RequireAtLeastOne<T, keyof T>;
+
+export {};

package/source/non-empty-string.d.ts

@@ -0,0 +1,32 @@
+/**
+Matches any non-empty string.
+
+This is useful when you need a string that is not empty, for example, as a function parameter.
+
+NOTE:
+- This returns `never` not just when instantiated with an empty string, but also when an empty string is a subtype of the instantiated type, like `string` or `Uppercase<string>`.
+
+@example
+```
+import type {NonEmptyString} from 'type-fest';
+
+declare function foo<T extends string>(string: NonEmptyString<T>): void;
+
+foo('a');
+// OK
+
+// @ts-expect-error
+foo('');
+// Error: Argument of type '""' is not assignable to parameter of type 'never'.
+
+declare const someString: string;
+// @ts-expect-error
+foo(someString);
+// Error: Argument of type 'string' is not assignable to parameter of type 'never'.
+```
+
+@category String
+*/
+export type NonEmptyString<T extends string> = '' extends T ? never : T;
+
+export {};

package/source/non-empty-tuple.d.ts

@@ -0,0 +1,24 @@
+/**
+Matches any non-empty tuple.
+
+@example
+```
+import type {NonEmptyTuple} from 'type-fest';
+
+const sum = (...numbers: NonEmptyTuple<number>) => numbers.reduce((total, value) => total + value, 0);
+
+sum(1, 2, 3);
+// Ok
+
+// @ts-expect-error
+sum();
+// Error: Expected at least 1 arguments, but got 0.
+```
+
+@see {@link RequireAtLeastOne} for objects
+
+@category Array
+*/
+export type NonEmptyTuple<T = unknown> = readonly [T, ...T[]];
+
+export {};

package/source/numeric.d.ts

@@ -0,0 +1,226 @@
+import type {IsFloat} from './is-float.d.ts';
+import type {IsInteger} from './is-integer.d.ts';
+
+export type _Numeric = number | bigint;
+
+type Zero = 0 | 0n;
+
+/**
+Matches the hidden `Infinity` type.
+
+Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/32277) if you want to have this type as a built-in in TypeScript.
+
+@see {@link NegativeInfinity}
+
+@category Numeric
+*/
+// See https://github.com/microsoft/TypeScript/issues/31752
+// eslint-disable-next-line no-loss-of-precision
+export type PositiveInfinity = 1e999;
+
+/**
+Matches the hidden `-Infinity` type.
+
+Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/32277) if you want to have this type as a built-in in TypeScript.
+
+@see {@link PositiveInfinity}
+
+@category Numeric
+*/
+// See https://github.com/microsoft/TypeScript/issues/31752
+// eslint-disable-next-line no-loss-of-precision
+export type NegativeInfinity = -1e999;
+
+/**
+A finite `number`.
+You can't pass a `bigint` as they are already guaranteed to be finite.
+
+Use-case: Validating and documenting parameters.
+
+Note: This can't detect `NaN`, please upvote [this issue](https://github.com/microsoft/TypeScript/issues/28682) if you want to have this type as a built-in in TypeScript.
+
+@example
+```
+import type {Finite} from 'type-fest';
+
+declare function setScore<T extends number>(length: Finite<T>): void;
+```
+
+@category Numeric
+*/
+export type Finite<T extends number> = T extends PositiveInfinity | NegativeInfinity ? never : T;
+
+/**
+A `number` that is an integer.
+
+Use-case: Validating and documenting parameters.
+
+@example
+```
+import type {Integer} from 'type-fest';
+
+type SomeInteger = Integer<1>;
+//=> 1
+
+type IntegerWithDecimal = Integer<1.0>;
+//=> 1
+
+type NegativeInteger = Integer<-1>;
+//=> -1
+
+type Float = Integer<1.5>;
+//=> never
+
+// Supports non-decimal numbers
+
+type OctalInteger = Integer<0o10>;
+//=> 8
+
+type BinaryInteger = Integer<0b10>;
+//=> 2
+
+type HexadecimalInteger = Integer<0x10>;
+//=> 16
+```
+
+@example
+```
+import type {Integer} from 'type-fest';
+
+declare function setYear<T extends number>(length: Integer<T>): void;
+```
+
+@see {@link NegativeInteger}
+@see {@link NonNegativeInteger}
+
+@category Numeric
+*/
+// `${bigint}` is a type that matches a valid bigint literal without the `n` (ex. 1, 0b1, 0o1, 0x1)
+// Because T is a number and not a string we can effectively use this to filter out any numbers containing decimal points
+export type Integer<T> =
+	T extends unknown // To distributive type
+		? IsInteger<T> extends true ? T : never
+		: never; // Never happens
+
+/**
+A `number` that is not an integer.
+
+Use-case: Validating and documenting parameters.
+
+It does not accept `Infinity`.
+
+@example
+```
+import type {Float} from 'type-fest';
+
+declare function setPercentage<T extends number>(length: Float<T>): void;
+```
+
+@see {@link Integer}
+
+@category Numeric
+*/
+export type Float<T> =
+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.
+Equivalent to `Negative<Float<T>>`.
+
+Use-case: Validating and documenting parameters.
+
+@see {@link Negative}
+@see {@link Float}
+
+@category Numeric
+*/
+export type NegativeFloat<T extends number> = Negative<Float<T>>;
+
+/**
+A negative `number`/`bigint` (`-∞ < x < 0`)
+
+Use-case: Validating and documenting parameters.
+
+@see {@link NegativeInteger}
+@see {@link NonNegative}
+
+@category Numeric
+*/
+export type Negative<T extends _Numeric> = T extends Zero ? never : `${T}` extends `-${string}` ? T : never;
+
+/**
+A negative (`-∞ < x < 0`) `number` that is an integer.
+Equivalent to `Negative<Integer<T>>`.
+
+You can't pass a `bigint` as they are already guaranteed to be integers, instead use `Negative<T>`.
+
+Use-case: Validating and documenting parameters.
+
+@see {@link Negative}
+@see {@link Integer}
+
+@category Numeric
+*/
+export type NegativeInteger<T extends number> = Negative<Integer<T>>;
+
+/**
+A non-negative `number`/`bigint` (`0 <= x < ∞`).
+
+Use-case: Validating and documenting parameters.
+
+@see {@link NonNegativeInteger}
+@see {@link Negative}
+
+@example
+```
+import type {NonNegative} from 'type-fest';
+
+declare function setLength<T extends number>(length: NonNegative<T>): void;
+```
+
+@category Numeric
+*/
+export type NonNegative<T extends _Numeric> = T extends Zero ? T : Negative<T> extends never ? T : never;
+
+/**
+A non-negative (`0 <= x < ∞`) `number` that is an integer.
+Equivalent to `NonNegative<Integer<T>>`.
+
+You can't pass a `bigint` as they are already guaranteed to be integers, instead use `NonNegative<T>`.
+
+Use-case: Validating and documenting parameters.
+
+@see {@link NonNegative}
+@see {@link Integer}
+
+@example
+```
+import type {NonNegativeInteger} from 'type-fest';
+
+declare function setLength<T extends number>(length: NonNegativeInteger<T>): void;
+```
+
+@category Numeric
+*/
+export type NonNegativeInteger<T extends number> = NonNegative<Integer<T>>;
+
+/**
+Returns a boolean for whether the given number is a negative number.
+
+@see {@link Negative}
+
+@example
+```
+import type {IsNegative} from 'type-fest';
+
+type ShouldBeFalse = IsNegative<1>;
+type ShouldBeTrue = IsNegative<-1>;
+```
+
+@category Numeric
+*/
+export type IsNegative<T extends _Numeric> = T extends Negative<T> ? true : false;
+
+export {};

package/source/object-merge.d.ts

@@ -0,0 +1,194 @@
+import type {If} from './if.d.ts';
+import type {NormalizedKeys} from './internal/object.d.ts';
+import type {IfNotAnyOrNever, IsExactOptionalPropertyTypesEnabled, MapsSetsOrArrays} from './internal/type.d.ts';
+import type {IsNever} from './is-never.d.ts';
+import type {IsOptionalKeyOf} from './is-optional-key-of.d.ts';
+import type {OmitIndexSignature} from './omit-index-signature.d.ts';
+import type {PickIndexSignature} from './pick-index-signature.d.ts';
+import type {RequiredKeysOf} from './required-keys-of.d.ts';
+import type {Simplify} from './simplify.d.ts';
+
+/**
+Merge two object types into a new object type, where keys from the second override keys from the first.
+
+@example
+```ts
+import type {ObjectMerge} from 'type-fest';
+
+type PartialOverride = ObjectMerge<{foo: string; bar: string}, {foo: number; baz: number}>;
+//=> {foo: number; baz: number; bar: string}
+
+type CompleteOverride = ObjectMerge<{foo: string; bar: number}, {foo: number; bar: string; baz: boolean}>;
+//=> {foo: number; bar: string; baz: boolean}
+
+type NoOverride = ObjectMerge<{foo: string; bar: number}, {baz: boolean; qux: bigint}>;
+//=> {baz: boolean; qux: bigint; foo: string; bar: number}
+```
+
+Use-cases:
+
+Can be used to accurately type object spread and `Object.assign`. The built-in inference for these operations can sometimes be unsound, especially when index signatures are involved.
+
+In the following example, both object spread and `Object.assign` produce a type that allows unsafe usage, whereas `ObjectMerge` produces a type that prevents this unsafe access.
+
+@example
+```ts
+import type {ObjectMerge} from 'type-fest';
+
+const left: {a: string} = {a: '1'};
+const right: {[x: string]: number} = {a: 1};
+
+const inferred = {...left, ...right};
+//=> {a: string}
+
+inferred.a.toUpperCase(); // No compile time error, but fails at runtime.
+
+const objectAssign = Object.assign(left, right);
+//=> {a: string} & {[x: string]: number}
+
+objectAssign.a.toUpperCase(); // No compile time error, but fails at runtime.
+
+declare const objectMerge: ObjectMerge<typeof left, typeof right>;
+//=> {[x: string]: string | number; a: string | number}
+
+// @ts-expect-error
+objectMerge.a.toUpperCase(); // Correctly errors at compile time.
+```
+
+Can be used to merge generic type arguments.
+
+In the following example, object spread without `ObjectMerge` produces an intersection type that is not particularly usable, whereas `ObjectMerge` produces a correctly merged and usable result.
+
+@example
+```ts
+import type {ObjectMerge} from 'type-fest';
+
+function withoutObjectMerge<T extends object, U extends object>(left: T, right: U) {
+	return {...left, ...right};
+}
+
+const result1 = withoutObjectMerge({a: 1}, {a: 'one'});
+//=> {a: number} & {a: string}
+
+const {a} = result1;
+//=> never
+
+function withObjectMerge<T extends object, U extends object>(left: T, right: U) {
+	return {...left, ...right} as unknown as ObjectMerge<T, U>;
+}
+
+const result2 = withObjectMerge({b: 1}, {b: 'one'});
+//=> {b: string}
+
+const {b} = result2;
+//=> string
+```
+
+Note: If you want a simple merge where properties from the second object always override properties from the first object without considering runtime implications, refer to the {@link Merge} type.
+
+@see {@link Merge}
+@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
+
+type _ObjectMerge<
+	First extends object,
+	Second extends object,
+	NormalizedFirstLiteralKeys extends PropertyKey,
+	NormalizedSecondLiteralKeys extends PropertyKey,
+	NormalizedFirst extends object,
+	NormalizedSecond extends object,
+> = Simplify<{
+	// Map over literal keys of `Second`, except those that are optional and also present in `First`.
+	-readonly [P in keyof Second as P extends NormalizedSecondLiteralKeys
+		? P extends NormalizedFirstLiteralKeys
+			? If<IsOptionalKeyOf<Second, P>, never, P>
+			: P
+		: never]:
+			| Second[P]
+			| (P extends NormalizedKeys<keyof PickIndexSignature<First>>
+				? If<IsOptionalKeyOf<Second, P>, First[NormalizedKeys<P> & keyof First], never>
+				: never)
+} & {
+	// Map over literal keys of `First`, except those that are not present in `Second`.
+	-readonly [P in keyof First as P extends NormalizedFirstLiteralKeys
+		? P extends NormalizedSecondLiteralKeys
+			? never
+			: P
+		: never]:
+			| First[P]
+				// If there's a matching index signature in `Second`, then add the type for it as well,
+				// for example, in `ObjectMerge<{a: string}, {[x: string]: number}>`, `a` is of type `string | number`.
+			| (P extends NormalizedKeys<keyof Second>
+				? Second[NormalizedKeys<P> & keyof Second]
+				: never);
+} & {
+	// Map over non-literal keys of `Second`.
+	-readonly [P in keyof Second as P extends NormalizedSecondLiteralKeys ? never : P]:
+		| Second[P]
+			// If there's a matching key in `First`, then add the type for it as well,
+			// for example, in `ObjectMerge<{a: number}, {[x: string]: string}>`,
+			// the resulting type is `{[x: string]: number | string; a: number | string}`.
+			// But, exclude keys from `First` that would surely get overwritten,
+			// for example, in `ObjectMerge<{a: number}, {[x: string]: string; a: string}>`,
+			// `a` from `First` would get overwritten by `a` from `Second`, so don't add type for it.
+		| (NormalizedKeys<P> & Exclude<keyof First, NormalizedKeys<RequiredKeysOf<OmitIndexSignature<Second>>>> extends infer NonOverwrittenKeysOfFirst
+			? If<IsNever<NonOverwrittenKeysOfFirst>, // This check is required because indexing with `never` doesn't always yield `never`, for example, `{[x: string]: number}[never]` results in `number`.
+				never,
+				NormalizedFirst[NonOverwrittenKeysOfFirst & keyof NormalizedFirst]>
+			: never); // Should never happen
+} & {
+	// Map over non-literal keys of `First`.
+	-readonly [P in keyof First as P extends NormalizedFirstLiteralKeys ? never : P]:
+		| First[P]
+		| If<IsNever<NormalizedKeys<P> & keyof Second>, // This check is required because indexing with `never` doesn't always yield `never`, for example, `{[x: string]: number}[never]` results in `number`.
+			never,
+			NormalizedSecond[NormalizedKeys<P> & keyof NormalizedSecond]>;
+} & {
+	// Handle optional keys of `Second` that are also present in `First`.
+	// Map over `First` instead of `Second` because the modifier is in accordance with `First`.
+	-readonly [P in keyof First as P extends NormalizedFirstLiteralKeys
+		? P extends NormalizedSecondLiteralKeys
+			? If<IsOptionalKeyOf<Second, NormalizedKeys<P> & keyof Second>, P, never>
+			: never
+		: never]:
+			| First[P]
+			| NormalizedSecond[NormalizedKeys<P> & keyof NormalizedSecond]
+}>;
+
+/**
+Get literal keys of a type, including both string and number representations wherever applicable.
+
+@example
+```ts
+type A = NormalizedLiteralKeys<{0: string; '1'?: number; foo: boolean}>;
+//=> 0 | '0' | 1 | '1' | 'foo'
+
+type B = NormalizedLiteralKeys<{[x: string]: string | number; 0: string; '1'?: number}>;
+//=> 0 | '0' | 1 | '1'
+
+type C = NormalizedLiteralKeys<{[x: string]: unknown}>;
+//=> never
+```
+*/
+type NormalizedLiteralKeys<Type> = Type extends unknown // For distributing `Type`
+	? NormalizedKeys<keyof OmitIndexSignature<Type>>
+	: never; // Should never happen
+
+export {};

package/source/omit-deep.d.ts

@@ -0,0 +1,154 @@
+import type {ArraySplice} from './array-splice.d.ts';
+import type {ExactKey, IsArrayReadonly, NonRecursiveType, SetArrayAccess, ToString} from './internal/index.d.ts';
+import type {IsEqual} from './is-equal.d.ts';
+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';
+
+/**
+Omit properties from a deeply-nested object.
+
+It supports recursing into arrays.
+
+It supports removing specific items from an array, replacing each removed item with unknown at the specified index.
+
+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.
+
+@example
+```
+import type {OmitDeep} from 'type-fest';
+
+type Info = {
+	userInfo: {
+		name: string;
+		uselessInfo: {
+			foo: string;
+		};
+	};
+};
+
+type UsefulInfo = OmitDeep<Info, 'userInfo.uselessInfo'>;
+//=> {userInfo: {name: string}}
+
+// Supports removing multiple paths
+type Info1 = {
+	userInfo: {
+		name: string;
+		uselessField: string;
+		uselessInfo: {
+			foo: string;
+		};
+	};
+};
+
+type UsefulInfo1 = OmitDeep<Info1, 'userInfo.uselessInfo' | 'userInfo.uselessField'>;
+//=> {userInfo: {name: string}}
+
+// Supports array
+type A = OmitDeep<[1, 'foo', 2], '1'>;
+//=> [1, unknown, 2]
+
+// Supports recursing into array
+
+type Info2 = {
+	address: [
+		{
+			street: string;
+		},
+		{
+			street2: string;
+			foo: string;
+		},
+	];
+};
+
+type AddressInfo = OmitDeep<Info2, 'address.1.foo'>;
+//=> {address: [{street: string}, {street2: string}]}
+```
+
+@category Object
+@category Array
+*/
+export type OmitDeep<T, PathUnion extends LiteralUnion<Paths<T>, string>> =
+	SimplifyDeep<
+		OmitDeepHelper<T, UnionToTuple<PathUnion>>,
+		UnknownArray>;
+
+/**
+Internal helper for {@link OmitDeep}.
+
+Recursively transforms `T` by applying {@link OmitDeepWithOnePath} for each path in `PathTuple`.
+*/
+type OmitDeepHelper<T, PathTuple extends UnknownArray> =
+	PathTuple extends [infer Path, ...infer RestPaths]
+		? OmitDeepHelper<OmitDeepWithOnePath<T, Path & (string | number)>, RestPaths>
+		: T;
+
+/**
+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;
+
+/**
+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>
+					: 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;
+
+/**
+Omit one path from from the given array.
+
+It replaces the item to `unknown` at the given index.
+
+@example
+```
+type A = OmitDeepArrayWithOnePath<[10, 20, 30, 40], 2>;
+//=> type A = [10, 20, unknown, 40];
+```
+*/
+type OmitDeepArrayWithOnePath<ArrayType extends UnknownArray, P extends string | number> =
+	// Handle paths that are `${number}.${string}`
+	P extends `${infer ArrayIndex extends number}.${infer SubPath}`
+		// If `ArrayIndex` is equal to `number`
+		? number extends ArrayIndex
+			? Array<OmitDeepWithOnePath<NonNullable<ArrayType[number]>, SubPath>>
+			// If `ArrayIndex` is a number literal
+			: ArraySplice<ArrayType, ArrayIndex, 1, [OmitDeepWithOnePath<NonNullable<ArrayType[ArrayIndex]>, SubPath>]>
+		// If the path is equal to `number`
+		: P extends `${infer ArrayIndex extends number}`
+			// If `ArrayIndex` is `number`
+			? number extends ArrayIndex
+				? []
+				// If `ArrayIndex` is a number literal
+				: ArraySplice<ArrayType, ArrayIndex, 1, [unknown]>
+			: ArrayType;
+
+export {};