@depup/type-fest 5.4.4-depup.0

package/source/simplify-deep.d.ts

@@ -0,0 +1,117 @@
+import type {ConditionalSimplifyDeep} from './conditional-simplify-deep.d.ts';
+import type {MapsSetsOrArrays, NonRecursiveType} from './internal/index.d.ts';
+import type {UnknownArray} from './unknown-array.d.ts';
+
+/**
+Deeply simplifies an object type.
+
+You can exclude certain types from being simplified by providing them in the second generic `ExcludeType`.
+
+Useful to flatten the type output to improve type hints shown in editors.
+
+@example
+```
+import type {SimplifyDeep} from 'type-fest';
+
+type PositionX = {
+	left: number;
+	right: number;
+};
+
+type PositionY = {
+	top: number;
+	bottom: number;
+};
+
+type Properties1 = {
+	height: number;
+	position: PositionY;
+};
+
+type Properties2 = {
+	width: number;
+	position: PositionX;
+};
+
+type Properties = Properties1 & Properties2;
+// In your editor, hovering over `Props` will show the following:
+//
+// type Properties = Properties1 & Properties2;
+
+type SimplifyDeepProperties = SimplifyDeep<Properties1 & Properties2>;
+// But if wrapped in SimplifyDeep, hovering over `SimplifyDeepProperties` will show a flattened object with all the properties:
+//
+// SimplifyDeepProperties = {
+// 	height: number;
+// 	width: number;
+// 	position: {
+// 		top: number;
+// 		bottom: number;
+// 		left: number;
+// 		right: number;
+// 	};
+// };
+```
+
+@example
+```
+import type {SimplifyDeep} from 'type-fest';
+
+// A complex type that you don't want or need to simplify
+type ComplexType = {
+	a: string;
+	b: 'b';
+	c: number;
+};
+
+type PositionX = {
+	left: number;
+	right: number;
+};
+
+type PositionY = {
+	top: number;
+	bottom: number;
+};
+
+// You want to simplify all other types
+type Properties1 = {
+	height: number;
+	position: PositionY;
+	foo: ComplexType;
+};
+
+type Properties2 = {
+	width: number;
+	position: PositionX;
+	foo: ComplexType;
+};
+
+type SimplifyDeepProperties = SimplifyDeep<Properties1 & Properties2, ComplexType>;
+// If wrapped in `SimplifyDeep` and set `ComplexType` to exclude, hovering over `SimplifyDeepProperties` will
+// show a flattened object with all the properties except `ComplexType`:
+//
+// SimplifyDeepProperties = {
+// 	height: number;
+// 	width: number;
+// 	position: {
+// 		top: number;
+// 		bottom: number;
+// 		left: number;
+// 		right: number;
+// 	};
+//	foo: ComplexType;
+// };
+```
+
+@see {@link Simplify}
+@category Object
+*/
+export type SimplifyDeep<Type, ExcludeType = never> =
+	ConditionalSimplifyDeep<
+		Type,
+	ExcludeType | NonRecursiveType | Exclude<MapsSetsOrArrays, UnknownArray>,
+	object
+	>;
+
+export {};

package/source/simplify.d.ts

@@ -0,0 +1,61 @@
+/**
+Useful to flatten the type output to improve type hints shown in editors. And also to transform an interface into a type to aide with assignability.
+
+@example
+```
+import type {Simplify} from 'type-fest';
+
+type PositionProps = {
+	top: number;
+	left: number;
+};
+
+type SizeProps = {
+	width: number;
+	height: number;
+};
+
+// In your editor, hovering over `Props` will show a flattened object with all the properties.
+type Props = Simplify<PositionProps & SizeProps>;
+```
+
+Sometimes it is desired to pass a value as a function argument that has a different type. At first inspection it may seem assignable, and then you discover it is not because the `value`'s type definition was defined as an interface. In the following example, `fn` requires an argument of type `Record<string, unknown>`. If the value is defined as a literal, then it is assignable. And if the `value` is defined as type using the `Simplify` utility the value is assignable.  But if the `value` is defined as an interface, it is not assignable because the interface is not sealed and elsewhere a non-string property could be added to the interface.
+
+If the type definition must be an interface (perhaps it was defined in a third-party npm package), then the `value` can be defined as `const value: Simplify<SomeInterface> = ...`. Then `value` will be assignable to the `fn` argument.  Or the `value` can be cast as `Simplify<SomeInterface>` if you can't re-declare the `value`.
+
+@example
+```
+import type {Simplify} from 'type-fest';
+
+interface SomeInterface {
+	foo: number;
+	bar?: string;
+	baz: number | undefined;
+}
+
+type SomeType = {
+	foo: number;
+	bar?: string;
+	baz: number | undefined;
+};
+
+const literal = {foo: 123, bar: 'hello', baz: 456};
+const someType: SomeType = literal;
+const someInterface: SomeInterface = literal;
+
+declare function fn(object: Record<string, unknown>): void;
+
+fn(literal); // Good: literal object type is sealed
+fn(someType); // Good: type is sealed
+// @ts-expect-error
+fn(someInterface); // Error: Index signature for type 'string' is missing in type 'someInterface'. Because `interface` can be re-opened
+fn(someInterface as Simplify<SomeInterface>); // Good: transform an `interface` into a `type`
+```
+
+@link https://github.com/microsoft/TypeScript/issues/15300
+@see {@link SimplifyDeep}
+@category Object
+*/
+export type Simplify<T> = {[KeyType in keyof T]: T[KeyType]} & {};
+
+export {};

package/source/single-key-object.d.ts

@@ -0,0 +1,28 @@
+import type {IsEmptyObject} from './empty-object.d.ts';
+import type {If} from './if.d.ts';
+import type {IsUnion} from './is-union.d.ts';
+
+/**
+Create a type that only accepts an object with a single key.
+
+@example
+```
+import type {SingleKeyObject} from 'type-fest';
+
+declare function someFunction<T>(parameter: SingleKeyObject<T>): void;
+
+someFunction({value: true});
+
+// @ts-expect-error
+someFunction({value: true, otherKey: true});
+// Error: Argument of type '{value: boolean; otherKey: boolean}' is not assignable to parameter of type 'never'.ts(2345)
+```
+
+@category Object
+*/
+export type SingleKeyObject<ObjectType> =
+	IsUnion<keyof ObjectType> extends true
+		? never
+		: If<IsEmptyObject<ObjectType>, never, ObjectType>;
+
+export {};

package/source/snake-case.d.ts

@@ -0,0 +1,47 @@
+import type {_DefaultDelimiterCaseOptions, DelimiterCase} from './delimiter-case.d.ts';
+import type {ApplyDefaultOptions} from './internal/index.d.ts';
+import type {WordsOptions} from './words.d.ts';
+
+/**
+Convert a string literal to snake-case.
+
+This can be useful when, for example, converting a camel-cased object property to a snake-cased SQL column name.
+
+@example
+```
+import type {SnakeCase} from 'type-fest';
+
+// Simple
+
+const someVariable: SnakeCase<'fooBar'> = 'foo_bar';
+const noSplitOnNumbers: SnakeCase<'p2pNetwork'> = 'p2p_network';
+const splitOnNumbers: SnakeCase<'p2pNetwork', {splitOnNumbers: true}> = 'p_2_p_network';
+
+// Advanced
+
+type SnakeCasedProperties<T> = {
+	[K in keyof T as SnakeCase<K>]: T[K]
+};
+
+type ModelProps = {
+	isHappy: boolean;
+	fullFamilyName: string;
+	foo: number;
+};
+
+const dbResult: SnakeCasedProperties<ModelProps> = {
+	'is_happy': true,
+	'full_family_name': 'Carla Smith',
+	foo: 123,
+};
+```
+
+@category Change case
+@category Template literal
+*/
+export type SnakeCase<
+	Value,
+	Options extends WordsOptions = {},
+> = DelimiterCase<Value, '_', ApplyDefaultOptions<WordsOptions, _DefaultDelimiterCaseOptions, Options>>;
+
+export {};

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

@@ -0,0 +1,65 @@
+import type {_DefaultDelimiterCaseOptions} from './delimiter-case.d.ts';
+import type {DelimiterCasedPropertiesDeep} from './delimiter-cased-properties-deep.d.ts';
+import type {ApplyDefaultOptions} from './internal/index.d.ts';
+import type {WordsOptions} from './words.d.ts';
+
+/**
+Convert object properties to snake case recursively.
+
+This can be useful when, for example, converting some API types from a different style.
+
+@see {@link SnakeCase}
+@see {@link SnakeCasedProperties}
+
+@example
+```
+import type {SnakeCasedPropertiesDeep} from 'type-fest';
+
+type User = {
+	userId: number;
+	userName: string;
+};
+
+type UserWithFriends = {
+	userInfo: User;
+	userFriends: User[];
+};
+
+const result: SnakeCasedPropertiesDeep<UserWithFriends> = {
+	user_info: {
+		user_id: 1,
+		user_name: 'Tom',
+	},
+	user_friends: [
+		{
+			user_id: 2,
+			user_name: 'Jerry',
+		},
+		{
+			user_id: 3,
+			user_name: 'Spike',
+		},
+	],
+};
+
+const splitOnNumbers: SnakeCasedPropertiesDeep<{line1: {line2: [{line3: string}]}}, {splitOnNumbers: true}> = {
+	line_1: {
+		line_2: [
+			{
+				line_3: 'string',
+			},
+		],
+	},
+};
+```
+
+@category Change case
+@category Template literal
+@category Object
+*/
+export type SnakeCasedPropertiesDeep<
+	Value,
+	Options extends WordsOptions = {},
+> = DelimiterCasedPropertiesDeep<Value, '_', ApplyDefaultOptions<WordsOptions, _DefaultDelimiterCaseOptions, Options>>;
+
+export {};

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

@@ -0,0 +1,42 @@
+import type {_DefaultDelimiterCaseOptions} from './delimiter-case.d.ts';
+import type {DelimiterCasedProperties} from './delimiter-cased-properties.d.ts';
+import type {ApplyDefaultOptions} from './internal/index.d.ts';
+import type {WordsOptions} from './words.d.ts';
+
+/**
+Convert object properties to snake case but not recursively.
+
+This can be useful when, for example, converting some API types from a different style.
+
+@see {@link SnakeCase}
+@see {@link SnakeCasedPropertiesDeep}
+
+@example
+```
+import type {SnakeCasedProperties} from 'type-fest';
+
+type User = {
+	userId: number;
+	userName: string;
+};
+
+const result: SnakeCasedProperties<User> = {
+	user_id: 1,
+	user_name: 'Tom',
+};
+
+const splitOnNumbers: SnakeCasedProperties<{line1: string}, {splitOnNumbers: true}> = {
+	'line_1': 'string',
+};
+```
+
+@category Change case
+@category Template literal
+@category Object
+*/
+export type SnakeCasedProperties<
+	Value,
+	Options extends WordsOptions = {},
+> = DelimiterCasedProperties<Value, '_', ApplyDefaultOptions<WordsOptions, _DefaultDelimiterCaseOptions, Options>>;
+
+export {};

package/source/split-on-rest-element.d.ts

@@ -0,0 +1,106 @@
+import type {IfNotAnyOrNever, IsExactOptionalPropertyTypesEnabled} from './internal/type.d.ts';
+import type {ApplyDefaultOptions} from './internal/object.d.ts';
+import type {IsOptionalKeyOf} from './is-optional-key-of.d.ts';
+import type {IsArrayReadonly} from './internal/array.d.ts';
+import type {UnknownArray} from './unknown-array.d.ts';
+import type {If} from './if.d.ts';
+
+/**
+{@link SplitOnRestElement} options.
+*/
+type SplitOnRestElementOptions = {
+	/**
+	Whether to preserve the optional modifier (`?`).
+
+	- When set to `true`, the optional modifiers are preserved as-is. For example:
+		`SplitOnRestElement<[number, string?, ...boolean[]], {preserveOptionalModifier: true}>` returns `[[number, string?], boolean[], []]`.
+
+	- When set to `false`, optional elements like `T?` are transformed to `T | undefined` or simply `T` depending on the `exactOptionalPropertyTypes` compiler option. For example:
+		- With `exactOptionalPropertyTypes` enabled: `SplitOnRestElement<[number, string?, ...boolean[]], {preserveOptionalModifier: false}>` returns `[[number, string], boolean[], []]`
+		- And, with it disabled, the result is: `[[number, string | undefined], boolean[], []]`
+
+	@default true
+	*/
+	preserveOptionalModifier?: boolean;
+};
+
+type DefaultSplitOnRestElementOptions = {
+	preserveOptionalModifier: true;
+};
+
+/**
+Splits an array into three parts, where the first contains all elements before the rest element, the second is the [`rest`](https://www.typescriptlang.org/docs/handbook/2/objects.html#tuple-types) element itself, and the third contains all elements after the rest element.
+
+Note: If any of the parts are missing, then they will be represented as empty arrays. For example, `SplitOnRestElement<[string, number]>` returns `[[string, number], [], []]`, where parts corresponding to the rest element and elements after it are empty.
+
+By default, the optional modifier (`?`) is preserved.
+See {@link SplitOnRestElementOptions `SplitOnRestElementOptions`}.
+
+@example
+```ts
+import type {SplitOnRestElement} from 'type-fest';
+
+type T1 = SplitOnRestElement<[number, ...string[], boolean]>;
+//=> [[number], string[], [boolean]]
+
+type T2 = SplitOnRestElement<readonly [...boolean[], string]>;
+//=> readonly [[], boolean[], [string]]
+
+type T3 = SplitOnRestElement<[number, string?]>;
+//=> [[number, string?], [], []]
+
+type T4 = SplitOnRestElement<[number, string?], {preserveOptionalModifier: false}>;
+//=> [[number, string], [], []]
+
+type T5 = SplitOnRestElement<readonly [string?, ...number[]], {preserveOptionalModifier: false}>;
+//=> readonly [[string], number[], []]
+```
+
+@see {@link ExtractRestElement}
+@see {@link ExcludeRestElement}
+@category Array
+*/
+export type SplitOnRestElement<
+	Array_ extends UnknownArray,
+	Options extends SplitOnRestElementOptions = {},
+> =
+	Array_ extends unknown // For distributing `Array_`
+		? IfNotAnyOrNever<Array_, _SplitOnRestElement<
+			Array_,
+			ApplyDefaultOptions<SplitOnRestElementOptions, DefaultSplitOnRestElementOptions, Options>
+		>> extends infer Result extends UnknownArray
+			? If<IsArrayReadonly<Array_>, Readonly<Result>, Result>
+			: never // Should never happen
+		: never; // Should never happen
+
+/**
+Deconstructs an array on its rest element and returns the split portions.
+*/
+export type _SplitOnRestElement<
+	Array_ extends UnknownArray,
+	Options extends Required<SplitOnRestElementOptions>,
+	HeadAcc extends UnknownArray = [],
+	TailAcc extends UnknownArray = [],
+> =
+	keyof Array_ & `${number}` extends never
+		// Enters this branch, if `Array_` is empty (e.g., []),
+		// or `Array_` contains no non-rest elements preceding the rest element (e.g., `[...string[]]` or `[...string[], string]`).
+		? Array_ extends readonly [...infer Rest, infer Last]
+			? _SplitOnRestElement<Rest, Options, HeadAcc, [Last, ...TailAcc]> // Accumulate elements that are present after the rest element.
+			: [HeadAcc, Array_ extends readonly [] ? [] : Array_, TailAcc] // Add the rest element between the accumulated elements.
+		: Array_ extends readonly [(infer First)?, ...infer Rest]
+			? _SplitOnRestElement<
+				Rest, Options,
+				[
+					...HeadAcc,
+					...IsOptionalKeyOf<Array_, '0'> extends true
+						? Options['preserveOptionalModifier'] extends false
+							? [If<IsExactOptionalPropertyTypesEnabled, First, First | undefined>] // Add `| undefined` for optional elements, if `exactOptionalPropertyTypes` is disabled.
+							: [First?]
+						: [First],
+				],
+				TailAcc
+			> // Accumulate elements that are present before the rest element.
+			: never; // Should never happen, since `[(infer First)?, ...infer Rest]` is a top-type for arrays.
+
+export {};

package/source/split.d.ts

@@ -0,0 +1,90 @@
+import type {And} from './and.d.ts';
+import type {ApplyDefaultOptions, Not} from './internal/index.d.ts';
+import type {IsStringLiteral} from './is-literal.d.ts';
+import type {Or} from './or.d.ts';
+
+/**
+Split options.
+
+@see {@link Split}
+*/
+export type SplitOptions = {
+	/**
+	When enabled, instantiations with non-literal string types (e.g., `string`, `Uppercase<string>`, `on${string}`) simply return back `string[]` without performing any splitting, as the exact structure cannot be statically determined.
+
+	@default true
+
+	@example
+	```ts
+	import type {Split} from 'type-fest';
+
+	type Example1 = Split<`foo.${string}.bar`, '.', {strictLiteralChecks: false}>;
+	//=> ['foo', string, 'bar']
+
+	type Example2 = Split<`foo.${string}`, '.', {strictLiteralChecks: true}>;
+	//=> string[]
+
+	type Example3 = Split<'foobarbaz', `b${string}`, {strictLiteralChecks: false}>;
+	//=> ['foo', 'r', 'z']
+
+	type Example4 = Split<'foobarbaz', `b${string}`, {strictLiteralChecks: true}>;
+	//=> string[]
+	```
+	*/
+	strictLiteralChecks?: boolean;
+};
+
+type DefaultSplitOptions = {
+	strictLiteralChecks: true;
+};
+
+/**
+Represents an array of strings split using a given character or character set.
+
+Use-case: Defining the return type of a method like `String.prototype.split`.
+
+@example
+```
+import type {Split} from 'type-fest';
+
+declare function split<S extends string, D extends string>(string: S, separator: D): Split<S, D>;
+
+type Item = 'foo' | 'bar' | 'baz' | 'waldo';
+const items = 'foo,bar,baz,waldo';
+const array: Item[] = split(items, ',');
+```
+
+@see {@link SplitOptions}
+
+@category String
+@category Template literal
+*/
+export type Split<
+	S extends string,
+	Delimiter extends string,
+	Options extends SplitOptions = {},
+> =
+	SplitHelper<S, Delimiter, ApplyDefaultOptions<SplitOptions, DefaultSplitOptions, Options>>;
+
+type SplitHelper<
+	S extends string,
+	Delimiter extends string,
+	Options extends Required<SplitOptions>,
+	Accumulator extends string[] = [],
+> = S extends string // For distributing `S`
+	? Delimiter extends string // For distributing `Delimiter`
+		// If `strictLiteralChecks` is `false` OR `S` and `Delimiter` both are string literals, then perform the split
+		? Or<Not<Options['strictLiteralChecks']>, And<IsStringLiteral<S>, IsStringLiteral<Delimiter>>> extends true
+			? S extends `${infer Head}${Delimiter}${infer Tail}`
+				? SplitHelper<Tail, Delimiter, Options, [...Accumulator, Head]>
+				: Delimiter extends ''
+					? S extends ''
+						? Accumulator
+						: [...Accumulator, S]
+					: [...Accumulator, S]
+			// Otherwise, return `string[]`
+			: string[]
+		: never // Should never happen
+	: never; // Should never happen
+
+export {};

package/source/spread.d.ts

@@ -0,0 +1,82 @@
+import type {RequiredKeysOf} from './required-keys-of.d.ts';
+import type {Simplify} from './simplify.d.ts';
+
+type SpreadObject<FirstType extends object, SecondType extends object> = {
+	[Key in keyof FirstType]: Key extends keyof SecondType
+		? FirstType[Key] | Required<SecondType>[Key]
+		: FirstType[Key];
+} & Pick<
+	SecondType,
+RequiredKeysOf<SecondType> | Exclude<keyof SecondType, keyof FirstType>
+>;
+
+type TupleOrArray = readonly [...unknown[]];
+
+type SpreadTupleOrArray<
+	FirstType extends TupleOrArray,
+	SecondType extends TupleOrArray,
+> = Array<FirstType[number] | SecondType[number]>;
+
+type Spreadable = object | TupleOrArray;
+
+/**
+Mimic the type inferred by TypeScript when merging two objects or two arrays/tuples using the spread syntax.
+
+@example
+```
+import type {Spread} from 'type-fest';
+
+type Foo = {
+	a: number;
+	b?: string;
+};
+
+type Bar = {
+	b?: number;
+	c: boolean;
+};
+
+const foo = {a: 1, b: '2'};
+const bar = {c: false};
+const fooBar = {...foo, ...bar};
+
+type FooBar = Spread<Foo, Bar>;
+// type FooBar = {
+// 	a: number;
+// 	b?: string | number | undefined;
+// 	c: boolean;
+// }
+
+declare function baz(argument: FooBar): void;
+
+baz(fooBar);
+```
+
+@example
+```
+import type {Spread} from 'type-fest';
+
+const foo = [1, 2, 3];
+const bar = ['4', '5', '6'];
+
+const fooBar = [...foo, ...bar];
+type FooBar = Spread<typeof foo, typeof bar>;
+// FooBar = (string | number)[]
+
+declare function baz(argument: FooBar): void;
+
+baz(fooBar);
+```
+
+@category Object
+*/
+export type Spread<
+	FirstType extends Spreadable,
+	SecondType extends Spreadable,
+> = FirstType extends TupleOrArray
+	? SecondType extends TupleOrArray
+		? SpreadTupleOrArray<FirstType, SecondType>
+		: Simplify<SpreadObject<FirstType, SecondType>>
+	: Simplify<SpreadObject<FirstType, SecondType>>;
+
+export {};

package/source/string-repeat.d.ts

@@ -0,0 +1,49 @@
+import type {IsNumericLiteral} from './is-literal.d.ts';
+import type {IsNegative} from './numeric.d.ts';
+
+/**
+Returns a new string which contains the specified number of copies of a given string, just like `String#repeat()`.
+
+@example
+```
+import type {StringRepeat} from 'type-fest';
+
+declare function stringRepeat<
+	Input extends string,
+	Count extends number,
+>(input: Input, count: Count): StringRepeat<Input, Count>;
+
+// The return type is the exact string literal, not just `string`.
+
+stringRepeat('foo', 2);
+//=> 'foofoo'
+
+stringRepeat('=', 3);
+//=> '==='
+```
+
+@category String
+@category Template literal
+*/
+export type StringRepeat<
+	Input extends string,
+	Count extends number,
+> = StringRepeatHelper<Input, Count>;
+
+type StringRepeatHelper<
+	Input extends string,
+	Count extends number,
+	Counter extends never[] = [],
+	Accumulator extends string = '',
+> =
+	IsNegative<Count> extends true
+		? never
+		: Input extends ''
+			? ''
+			: Count extends Counter['length']
+				? Accumulator
+				: IsNumericLiteral<Count> extends false
+					? string
+					: StringRepeatHelper<Input, Count, [...Counter, never], `${Accumulator}${Input}`>;
+
+export {};