@depup/type-fest 5.4.4-depup.0

package/source/conditional-pick-deep.d.ts

@@ -0,0 +1,120 @@
+import type {IsEqual} from './is-equal.d.ts';
+import type {ConditionalExcept} from './conditional-except.d.ts';
+import type {ConditionalSimplifyDeep} from './conditional-simplify-deep.d.ts';
+import type {UnknownRecord} from './unknown-record.d.ts';
+import type {EmptyObject} from './empty-object.d.ts';
+import type {ApplyDefaultOptions, IsPlainObject} from './internal/index.d.ts';
+
+/**
+Used to mark properties that should be excluded.
+*/
+declare const conditionalPickDeepSymbol: unique symbol;
+
+/**
+Assert the condition according to the {@link ConditionalPickDeepOptions.condition|condition} option.
+*/
+type AssertCondition<Type, Condition, Options extends ConditionalPickDeepOptions> = Options['condition'] extends 'equality'
+	? IsEqual<Type, Condition>
+	: Type extends Condition
+		? true
+		: false;
+
+/**
+ConditionalPickDeep options.
+
+@see {@link ConditionalPickDeep}
+*/
+export type ConditionalPickDeepOptions = {
+	/**
+	The condition assertion mode.
+
+	@default 'extends'
+	*/
+	condition?: 'extends' | 'equality';
+};
+
+type DefaultConditionalPickDeepOptions = {
+	condition: 'extends';
+};
+
+/**
+Pick keys recursively from the shape that matches the given condition.
+
+@see {@link ConditionalPick}
+
+@example
+```
+import type {ConditionalPickDeep} from 'type-fest';
+
+type Example = {
+	a: string;
+	b: string | boolean;
+	c: {
+		d: string;
+		e: {
+			f?: string;
+			g?: boolean;
+			h: string | boolean;
+			i: boolean | bigint;
+		};
+		j: boolean;
+	};
+};
+
+type StringPick = ConditionalPickDeep<Example, string>;
+//=> {a: string; c: {d: string}}
+
+type StringPickOptional = ConditionalPickDeep<Example, string | undefined>;
+//=> {a: string; c: {d: string; e: {f?: string}}}
+
+type StringPickOptionalOnly = ConditionalPickDeep<Example, string | undefined, {condition: 'equality'}>;
+//=> {c: {e: {f?: string}}}
+
+type BooleanPick = ConditionalPickDeep<Example, boolean | undefined>;
+//=> {c: {e: {g?: boolean}; j: boolean}}
+
+type NumberPick = ConditionalPickDeep<Example, number>;
+//=> {}
+
+type StringOrBooleanPick = ConditionalPickDeep<Example, string | boolean>;
+//=> {
+// 	a: string;
+// 	b: string | boolean;
+// 	c: {
+// 		d: string;
+// 		e: {
+// 			h: string | boolean;
+// 		};
+// 		j: boolean;
+// 	};
+// }
+
+type StringOrBooleanPickOnly = ConditionalPickDeep<Example, string | boolean, {condition: 'equality'}>;
+//=> {b: string | boolean; c: {e: {h: string | boolean}}}
+```
+
+@category Object
+*/
+export type ConditionalPickDeep<
+	Type,
+	Condition,
+	Options extends ConditionalPickDeepOptions = {},
+> = _ConditionalPickDeep<
+	Type,
+	Condition,
+	ApplyDefaultOptions<ConditionalPickDeepOptions, DefaultConditionalPickDeepOptions, Options>
+>;
+
+type _ConditionalPickDeep<
+	Type,
+	Condition,
+	Options extends Required<ConditionalPickDeepOptions>,
+> = ConditionalSimplifyDeep<ConditionalExcept<{
+	[Key in keyof Type]: AssertCondition<Type[Key], Condition, Options> extends true
+		? Type[Key]
+		: IsPlainObject<Type[Key]> extends true
+			? _ConditionalPickDeep<Type[Key], Condition, Options>
+			: typeof conditionalPickDeepSymbol;
+}, (typeof conditionalPickDeepSymbol | undefined) | EmptyObject>, never, UnknownRecord>;
+
+export {};

package/source/conditional-pick.d.ts

@@ -0,0 +1,46 @@
+import type {ConditionalKeys} from './conditional-keys.d.ts';
+
+/**
+Pick keys from the shape that matches the given `Condition`.
+
+This is useful when you want to create a new type from a specific subset of an existing type. For example, you might want to pick all the primitive properties from a class and form a new automatically derived type.
+
+@example
+```
+import type {Primitive, ConditionalPick} from 'type-fest';
+
+class Awesome {
+	constructor(public name: string, public successes: number, public failures: bigint) {}
+
+	run() {
+		// do something
+	}
+}
+
+type PickPrimitivesFromAwesome = ConditionalPick<Awesome, Primitive>;
+//=> {name: string; successes: number; failures: bigint}
+```
+
+@example
+```
+import type {ConditionalPick} from 'type-fest';
+
+type Example = {
+	a: string;
+	b: string | number;
+	c: () => void;
+	d: {};
+};
+
+type StringKeysOnly = ConditionalPick<Example, string>;
+//=> {a: string}
+```
+
+@category Object
+*/
+export type ConditionalPick<Base, Condition> = Pick<
+	Base,
+	ConditionalKeys<Base, Condition>
+>;
+
+export {};

package/source/conditional-simplify-deep.d.ts

@@ -0,0 +1,73 @@
+/**
+Recursively simplifies a type while including and/or excluding certain types from being simplified.
+
+@example
+```
+import type {ConditionalSimplifyDeep} from 'type-fest';
+
+type TypeA = {
+	foo: {
+		a: string;
+	};
+};
+
+type TypeB = {
+	foo: {
+		b: string;
+	};
+};
+
+type SimplifyDeepTypeAB = ConditionalSimplifyDeep<TypeA & TypeB, never, object>;
+//=> {foo: {a: string; b: string}}
+```
+
+@example
+```
+import type {ConditionalSimplifyDeep} from 'type-fest';
+
+type SomeComplexType1 = {
+	a1: string;
+	b1: number;
+	c1: boolean;
+};
+
+type SomeComplexType2 = {
+	a2: string;
+	b2: number;
+	c2: boolean;
+};
+
+type TypeA = {
+	foo: {
+		a: string;
+		complexType: SomeComplexType1;
+	};
+};
+
+type TypeB = {
+	foo: {
+		b: string;
+		complexType: SomeComplexType2;
+	};
+};
+
+type SimplifyDeepTypeAB = ConditionalSimplifyDeep<TypeA & TypeB, SomeComplexType1 | SomeComplexType2, object>;
+//=> {
+// 	foo: {
+// 		a: string;
+// 		complexType: SomeComplexType1 & SomeComplexType2;
+// 		b: string;
+// 	};
+// }
+```
+
+@see {@link SimplifyDeep}
+@category Object
+*/
+export type ConditionalSimplifyDeep<Type, ExcludeType = never, IncludeType = unknown> = Type extends ExcludeType
+	? Type
+	: Type extends IncludeType
+		? {[TypeKey in keyof Type]: ConditionalSimplifyDeep<Type[TypeKey], ExcludeType, IncludeType>}
+		: Type;
+
+export {};

package/source/conditional-simplify.d.ts

@@ -0,0 +1,50 @@
+/**
+Simplifies a type while including and/or excluding certain types from being simplified.
+
+Useful to improve type hints shown in editors. And also to transform an `interface` into a `type` to aid with assignability.
+
+@example
+```
+import type {ConditionalSimplify} from 'type-fest';
+
+type TypeA = {
+	a: string;
+};
+
+type TypeB = {
+	b: string;
+};
+
+type TypeAB = TypeA & TypeB;
+//=> TypeA & TypeB
+
+type SimplifyTypeAB = ConditionalSimplify<TypeAB, never, object>;
+//=> {a: string; b: string}
+```
+
+@example
+```
+import type {ConditionalSimplify} from 'type-fest';
+
+type Simplify<T> = ConditionalSimplify<T, Set<unknown> | Map<unknown, unknown> | unknown[], object>;
+
+type A = Simplify<Set<number> & Set<string>>;
+//=> Set<number> & Set<string>
+
+type B = Simplify<Map<number, number> & Map<string, string>>;
+//=> Map<number, number> & Map<string, string>
+
+type C = Simplify<{a: number} & {b: string}>;
+//=> {a: number; b: string}
+```
+
+@see {@link ConditionalSimplifyDeep}
+@category Object
+*/
+export type ConditionalSimplify<Type, ExcludeType = never, IncludeType = unknown> = Type extends ExcludeType
+	? Type
+	: Type extends IncludeType
+		? {[TypeKey in keyof Type]: Type[TypeKey]}
+		: Type;
+
+export {};

package/source/delimiter-case.d.ts

@@ -0,0 +1,77 @@
+import type {ApplyDefaultOptions, AsciiPunctuation, StartsWith} from './internal/index.d.ts';
+import type {IsStringLiteral} from './is-literal.d.ts';
+import type {Merge} from './merge.d.ts';
+import type {RemovePrefix} from './remove-prefix.d.ts';
+import type {_DefaultWordsOptions, Words, WordsOptions} from './words.d.ts';
+
+export type _DefaultDelimiterCaseOptions = Merge<_DefaultWordsOptions, {splitOnNumbers: false}>;
+
+/**
+Convert an array of words to delimiter case starting with a delimiter with input capitalization.
+*/
+type DelimiterCaseFromArray<
+	Words extends string[],
+	Delimiter extends string,
+	OutputString extends string = '',
+> = Words extends [
+	infer FirstWord extends string,
+	...infer RemainingWords extends string[],
+]
+	? DelimiterCaseFromArray<RemainingWords, Delimiter, `${OutputString}${
+		StartsWith<FirstWord, AsciiPunctuation> extends true ? '' : Delimiter
+	}${FirstWord}`>
+	: OutputString;
+
+/**
+Convert a string literal to a custom string delimiter casing.
+
+This can be useful when, for example, converting a camel-cased object property to an oddly cased one.
+
+@see {@link KebabCase}
+@see {@link SnakeCase}
+
+@example
+```
+import type {DelimiterCase} from 'type-fest';
+
+// Simple
+
+const someVariable: DelimiterCase<'fooBar', '#'> = 'foo#bar';
+const someVariableNoSplitOnNumbers: DelimiterCase<'p2pNetwork', '#', {splitOnNumbers: false}> = 'p2p#network';
+
+// Advanced
+
+type OddlyCasedProperties<T> = {
+	[K in keyof T as DelimiterCase<K, '#'>]: T[K]
+};
+
+type SomeOptions = {
+	dryRun: boolean;
+	includeFile: string;
+	foo: number;
+};
+
+const rawCliOptions: OddlyCasedProperties<SomeOptions> = {
+	'dry#run': true,
+	'include#file': 'bar.js',
+	foo: 123,
+};
+```
+
+@category Change case
+@category Template literal
+ */
+export type DelimiterCase<
+	Value,
+	Delimiter extends string,
+	Options extends WordsOptions = {},
+> = Value extends string
+	? IsStringLiteral<Value> extends false
+		? Value
+		: Lowercase<RemovePrefix<DelimiterCaseFromArray<
+			Words<Value, ApplyDefaultOptions<WordsOptions, _DefaultDelimiterCaseOptions, Options>>,
+			Delimiter
+		>, string, {strict: false}>>
+	: Value;
+
+export {};

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

@@ -0,0 +1,108 @@
+import type {_DefaultDelimiterCaseOptions, DelimiterCase} from './delimiter-case.d.ts';
+import type {ApplyDefaultOptions, NonRecursiveType} from './internal/index.d.ts';
+import type {UnknownArray} from './unknown-array.d.ts';
+import type {WordsOptions} from './words.d.ts';
+
+/**
+Convert object properties to delimiter case recursively.
+
+This can be useful when, for example, converting some API types from a different style.
+
+@see {@link DelimiterCase}
+@see {@link DelimiterCasedProperties}
+
+@example
+```
+import type {DelimiterCasedPropertiesDeep} from 'type-fest';
+
+type User = {
+	userId: number;
+	userName: string;
+};
+
+type UserWithFriends = {
+	userInfo: User;
+	userFriends: User[];
+};
+
+const result: DelimiterCasedPropertiesDeep<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: DelimiterCasedPropertiesDeep<{line1: {line2: [{line3: string}]}}, '-', {splitOnNumbers: true}> = {
+	'line-1': {
+		'line-2': [
+			{
+				'line-3': 'string',
+			},
+		],
+	},
+};
+```
+
+@category Change case
+@category Template literal
+@category Object
+*/
+export type DelimiterCasedPropertiesDeep<
+	Value,
+	Delimiter extends string,
+	Options extends WordsOptions = {},
+> = _DelimiterCasedPropertiesDeep<Value, Delimiter, ApplyDefaultOptions<WordsOptions, _DefaultDelimiterCaseOptions, Options>>;
+
+type _DelimiterCasedPropertiesDeep<
+	Value,
+	Delimiter extends string,
+	Options extends Required<WordsOptions>,
+> = Value extends NonRecursiveType
+	? Value
+	: Value extends UnknownArray
+		? DelimiterCasedPropertiesArrayDeep<Value, Delimiter, Options>
+		: Value extends Set<infer U>
+			? Set<_DelimiterCasedPropertiesDeep<U, Delimiter, Options>>
+			: Value extends object
+				? {
+					[K in keyof Value as DelimiterCase<K, Delimiter, Options>]:
+					_DelimiterCasedPropertiesDeep<Value[K], Delimiter, Options>
+				}
+				: Value;
+
+// This is a copy of CamelCasedPropertiesArrayDeep (see: camel-cased-properties-deep.d.ts).
+// These types should be kept in sync.
+type DelimiterCasedPropertiesArrayDeep<
+	Value extends UnknownArray,
+	Delimiter extends string,
+	Options extends Required<WordsOptions>,
+> = Value extends []
+	? []
+	// Trailing spread array
+	:	Value extends [infer U, ...infer V]
+		? [_DelimiterCasedPropertiesDeep<U, Delimiter, Options>, ..._DelimiterCasedPropertiesDeep<V, Delimiter, Options>]
+		: Value extends readonly [infer U, ...infer V]
+			? readonly [_DelimiterCasedPropertiesDeep<U, Delimiter, Options>, ..._DelimiterCasedPropertiesDeep<V, Delimiter, Options>]
+			// Leading spread array
+			: Value extends [...infer U, infer V]
+				? [..._DelimiterCasedPropertiesDeep<U, Delimiter, Options>, _DelimiterCasedPropertiesDeep<V, Delimiter, Options>]
+				: Value extends readonly [...infer U, infer V]
+					? readonly [..._DelimiterCasedPropertiesDeep<U, Delimiter, Options>, _DelimiterCasedPropertiesDeep<V, Delimiter, Options>]
+					// Array
+					: Value extends Array<infer U>
+						? Array<_DelimiterCasedPropertiesDeep<U, Delimiter, Options>>
+						: Value extends ReadonlyArray<infer U>
+							? ReadonlyArray<_DelimiterCasedPropertiesDeep<U, Delimiter, Options>>
+							: never;
+
+export {};

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

@@ -0,0 +1,48 @@
+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 object properties to delimiter case but not recursively.
+
+This can be useful when, for example, converting some API types from a different style.
+
+@see {@link DelimiterCase}
+@see {@link DelimiterCasedPropertiesDeep}
+
+@example
+```
+import type {DelimiterCasedProperties} from 'type-fest';
+
+type User = {
+	userId: number;
+	userName: string;
+};
+
+const result: DelimiterCasedProperties<User, '-'> = {
+	'user-id': 1,
+	'user-name': 'Tom',
+};
+
+const splitOnNumbers: DelimiterCasedProperties<{line1: string}, '-', {splitOnNumbers: true}> = {
+	'line-1': 'string',
+};
+```
+
+@category Change case
+@category Template literal
+@category Object
+*/
+export type DelimiterCasedProperties<
+	Value,
+	Delimiter extends string,
+	Options extends WordsOptions = {},
+> = Value extends Function
+	? Value
+	: Value extends Array<infer U>
+		? Value
+		: {[K in keyof Value as
+			DelimiterCase<K, Delimiter, ApplyDefaultOptions<WordsOptions, _DefaultDelimiterCaseOptions, Options>>
+			]: Value[K]};
+
+export {};

package/source/distributed-omit.d.ts

@@ -0,0 +1,96 @@
+import type {KeysOfUnion} from './keys-of-union.d.ts';
+
+/**
+Omits keys from a type, distributing the operation over a union.
+
+TypeScript's `Omit` doesn't distribute over unions, leading to the erasure of unique properties from union members when omitting keys. This creates a type that only retains properties common to all union members, making it impossible to access member-specific properties after the Omit. Essentially, using `Omit` on a union type merges the types into a less specific one, hindering type narrowing and property access based on discriminants. This type solves that.
+
+Example:
+
+```
+type A = {
+	discriminant: 'A';
+	foo: string;
+	a: number;
+};
+
+type B = {
+	discriminant: 'B';
+	foo: string;
+	b: string;
+};
+
+type Union = A | B;
+
+type OmittedUnion = Omit<Union, 'foo'>;
+//=> {discriminant: 'A' | 'B'}
+
+declare const omittedUnion: OmittedUnion;
+
+if (omittedUnion.discriminant === 'A') {
+	// We would like to narrow `omittedUnion`'s type
+	// to `A` here, but we can't because `Omit`
+	// doesn't distribute over unions.
+
+	// @ts-expect-error
+	const aValue = omittedUnion.a;
+	// Error: `a` is not a property of `{discriminant: 'A' | 'B'}`
+}
+```
+
+While `Except` solves this problem, it restricts the keys you can omit to the ones that are present in **ALL** union members, where `DistributedOmit` allows you to omit keys that are present in **ANY** union member.
+
+@example
+```
+import type {DistributedOmit} from 'type-fest';
+
+type A = {
+	discriminant: 'A';
+	foo: string;
+	a: number;
+};
+
+type B = {
+	discriminant: 'B';
+	foo: string;
+	bar: string;
+	b: string;
+};
+
+type C = {
+	discriminant: 'C';
+	bar: string;
+	c: boolean;
+};
+
+// Notice that `foo` exists in `A` and `B`, but not in `C`, and
+// `bar` exists in `B` and `C`, but not in `A`.
+
+type Union = A | B | C;
+
+type OmittedUnion = DistributedOmit<Union, 'foo' | 'bar'>;
+
+declare const omittedUnion: OmittedUnion;
+
+if (omittedUnion.discriminant === 'A') {
+	const aValue = omittedUnion.a;
+	// OK
+
+	// @ts-expect-error
+	const fooValue = omittedUnion.foo;
+	// Error: `foo` is not a property of `{discriminant: 'A'; a: string}`
+
+	// @ts-expect-error
+	const barValue = omittedUnion.bar;
+	// Error: `bar` is not a property of `{discriminant: 'A'; a: string}`
+}
+```
+
+@category Object
+*/
+export type DistributedOmit<ObjectType, KeyType extends KeysOfUnion<ObjectType>> =
+	ObjectType extends unknown
+		? Omit<ObjectType, KeyType>
+		: never;
+
+export {};