@depup/type-fest 5.4.4-depup.0

package/source/require-all-or-none.d.ts

@@ -0,0 +1,54 @@
+import type {If} from './if.d.ts';
+import type {IfNotAnyOrNever, RequireNone} from './internal/index.d.ts';
+import type {IsAny} from './is-any.d.ts';
+import type {IsNever} from './is-never.d.ts';
+
+/**
+Requires all of the keys in the given object.
+*/
+type RequireAll<ObjectType, KeysType extends keyof ObjectType> = Required<Pick<ObjectType, KeysType>>;
+
+/**
+Create a type that requires all of the given keys or none of the given keys. The remaining keys are kept as is.
+
+Use-cases:
+- Creating interfaces for components with mutually-inclusive keys.
+
+The caveat with `RequireAllOrNone` is that TypeScript doesn't always know at compile time every key that will exist at runtime. Therefore `RequireAllOrNone` can't do anything to prevent extra keys it doesn't know about.
+
+@example
+```
+import type {RequireAllOrNone} from 'type-fest';
+
+type Responder = {
+	text?: () => string;
+	json?: () => string;
+	secure: boolean;
+};
+
+const responder1: RequireAllOrNone<Responder, 'text' | 'json'> = {
+	secure: true,
+};
+
+const responder2: RequireAllOrNone<Responder, 'text' | 'json'> = {
+	text: () => '{"message": "hi"}',
+	json: () => '{"message": "ok"}',
+	secure: true,
+};
+```
+
+@category Object
+*/
+export type RequireAllOrNone<ObjectType, KeysType extends keyof ObjectType = keyof ObjectType> =
+	IfNotAnyOrNever<ObjectType,
+		If<IsNever<KeysType>,
+			ObjectType,
+			_RequireAllOrNone<ObjectType, If<IsAny<KeysType>, keyof ObjectType, KeysType>>
+		>>;
+
+type _RequireAllOrNone<ObjectType, KeysType extends keyof ObjectType> = (
+	| RequireAll<ObjectType, KeysType>
+	| RequireNone<KeysType>
+) & Omit<ObjectType, KeysType>; // The rest of the keys.
+
+export {};

package/source/require-at-least-one.d.ts

@@ -0,0 +1,50 @@
+import type {Except} from './except.d.ts';
+import type {If} from './if.d.ts';
+import type {IfNotAnyOrNever} from './internal/index.d.ts';
+import type {IsAny} from './is-any.d.ts';
+import type {IsNever} from './is-never.d.ts';
+
+/**
+Create a type that requires at least one of the given keys. The remaining keys are kept as is.
+
+@example
+```
+import type {RequireAtLeastOne} from 'type-fest';
+
+type Responder = {
+	text?: () => string;
+	json?: () => string;
+	secure?: boolean;
+};
+
+const responder: RequireAtLeastOne<Responder, 'text' | 'json'> = {
+	json: () => '{"message": "ok"}',
+	secure: true,
+};
+```
+
+@category Object
+*/
+export type RequireAtLeastOne<
+	ObjectType,
+	KeysType extends keyof ObjectType = keyof ObjectType,
+> =
+	IfNotAnyOrNever<ObjectType,
+		If<IsNever<KeysType>,
+			never,
+			_RequireAtLeastOne<ObjectType, If<IsAny<KeysType>, keyof ObjectType, KeysType>>
+		>>;
+
+type _RequireAtLeastOne<
+	ObjectType,
+	KeysType extends keyof ObjectType,
+> = {
+	// For each `Key` in `KeysType` make a mapped type:
+	[Key in KeysType]-?: Required<Pick<ObjectType, Key>> & // 1. Make `Key`'s type required
+	// 2. Make all other keys in `KeysType` optional
+		Partial<Pick<ObjectType, Exclude<KeysType, Key>>>;
+}[KeysType] &
+// 3. Add the remaining keys not in `KeysType`
+Except<ObjectType, KeysType>;
+
+export {};

package/source/require-exactly-one.d.ts

@@ -0,0 +1,48 @@
+import type {If} from './if.d.ts';
+import type {IfNotAnyOrNever} from './internal/index.d.ts';
+import type {IsAny} from './is-any.d.ts';
+import type {IsNever} from './is-never.d.ts';
+
+/**
+Create a type that requires exactly one of the given keys and disallows more. The remaining keys are kept as is.
+
+Use-cases:
+- Creating interfaces for components that only need one of the keys to display properly.
+- Declaring generic keys in a single place for a single use-case that gets narrowed down via `RequireExactlyOne`.
+
+The caveat with `RequireExactlyOne` is that TypeScript doesn't always know at compile time every key that will exist at runtime. Therefore `RequireExactlyOne` can't do anything to prevent extra keys it doesn't know about.
+
+@example
+```
+import type {RequireExactlyOne} from 'type-fest';
+
+type Responder = {
+	text: () => string;
+	json: () => string;
+	secure: boolean;
+};
+
+const responder: RequireExactlyOne<Responder, 'text' | 'json'> = {
+	// Adding a `text` key here would cause a compile error.
+
+	json: () => '{"message": "ok"}',
+	secure: true,
+};
+```
+
+@category Object
+*/
+export type RequireExactlyOne<ObjectType, KeysType extends keyof ObjectType = keyof ObjectType> =
+	IfNotAnyOrNever<ObjectType,
+		If<IsNever<KeysType>,
+			never,
+			_RequireExactlyOne<ObjectType, If<IsAny<KeysType>, keyof ObjectType, KeysType>>
+		>>;
+
+type _RequireExactlyOne<ObjectType, KeysType extends keyof ObjectType> =
+	{[Key in KeysType]: (
+		Required<Pick<ObjectType, Key>> &
+		Partial<Record<Exclude<KeysType, Key>, never>>
+	)}[KeysType] & Omit<ObjectType, KeysType>;
+
+export {};

package/source/require-one-or-none.d.ts

@@ -0,0 +1,49 @@
+import type {RequireExactlyOne} from './require-exactly-one.d.ts';
+import type {IfNotAnyOrNever, RequireNone} from './internal/index.d.ts';
+import type {If} from './if.d.ts';
+import type {IsAny} from './is-any.d.ts';
+import type {IsNever} from './is-never.d.ts';
+
+/**
+Create a type that requires exactly one of the given keys and disallows more, or none of the given keys. The remaining keys are kept as is.
+
+@example
+```
+import type {RequireOneOrNone} from 'type-fest';
+
+type Responder = RequireOneOrNone<{
+	text: () => string;
+	json: () => string;
+	secure: boolean;
+}, 'text' | 'json'>;
+
+const responder1: Responder = {
+	secure: true,
+};
+
+const responder2: Responder = {
+	text: () => '{"message": "hi"}',
+	secure: true,
+};
+
+const responder3: Responder = {
+	json: () => '{"message": "ok"}',
+	secure: true,
+};
+```
+
+@category Object
+*/
+export type RequireOneOrNone<ObjectType, KeysType extends keyof ObjectType = keyof ObjectType> =
+	IfNotAnyOrNever<ObjectType,
+		If<IsNever<KeysType>,
+			ObjectType,
+			_RequireOneOrNone<ObjectType, If<IsAny<KeysType>, keyof ObjectType, KeysType>>
+		>>;
+
+type _RequireOneOrNone<ObjectType, KeysType extends keyof ObjectType> = (
+	| RequireExactlyOne<ObjectType, KeysType>
+	| RequireNone<KeysType>
+) & Omit<ObjectType, KeysType>; // Ignore unspecified keys.
+
+export {};

package/source/required-deep.d.ts

@@ -0,0 +1,76 @@
+import type {BuiltIns, HasMultipleCallSignatures} from './internal/index.d.ts';
+import type {IsNever} from './is-never.d.ts';
+import type {Simplify} from './simplify.d.ts';
+
+/**
+Create a type from another type with all keys and nested keys set to required.
+
+Use-cases:
+- Creating optional configuration interfaces where the underlying implementation still requires all options to be fully specified.
+- Modeling the resulting type after a deep merge with a set of defaults.
+
+@example
+```
+import type {RequiredDeep} from 'type-fest';
+
+type Settings = {
+	textEditor?: {
+		fontSize?: number;
+		fontColor?: string;
+		fontWeight?: number | undefined;
+	};
+	autocomplete?: boolean;
+	autosave?: boolean | undefined;
+};
+
+type RequiredSettings = RequiredDeep<Settings>;
+//=> {
+// 	textEditor: {
+// 		fontSize: number;
+// 		fontColor: string;
+// 		fontWeight: number | undefined;
+// 	};
+// 	autocomplete: boolean;
+// 	autosave: boolean | undefined;
+// }
+```
+
+Note that types containing overloaded functions are not made deeply required due to a [TypeScript limitation](https://github.com/microsoft/TypeScript/issues/29732).
+
+@category Utilities
+@category Object
+@category Array
+@category Set
+@category Map
+*/
+export type RequiredDeep<T> = T extends BuiltIns
+	? T
+	: T extends Map<infer KeyType, infer ValueType>
+		? Map<RequiredDeep<KeyType>, RequiredDeep<ValueType>>
+		: T extends Set<infer ItemType>
+			? Set<RequiredDeep<ItemType>>
+			: T extends ReadonlyMap<infer KeyType, infer ValueType>
+				? ReadonlyMap<RequiredDeep<KeyType>, RequiredDeep<ValueType>>
+				: T extends ReadonlySet<infer ItemType>
+					? ReadonlySet<RequiredDeep<ItemType>>
+					: T extends WeakMap<infer KeyType, infer ValueType>
+						? WeakMap<RequiredDeep<KeyType>, RequiredDeep<ValueType>>
+						: T extends WeakSet<infer ItemType>
+							? WeakSet<RequiredDeep<ItemType>>
+							: T extends Promise<infer ValueType>
+								? Promise<RequiredDeep<ValueType>>
+								: T extends (...arguments_: any[]) => unknown
+									? IsNever<keyof T> extends true
+										? T
+										: HasMultipleCallSignatures<T> extends true
+											? T
+											: ((...arguments_: Parameters<T>) => ReturnType<T>) & RequiredObjectDeep<T>
+									: T extends object
+										? Simplify<RequiredObjectDeep<T>> // `Simplify` to prevent `RequiredObjectDeep` from appearing in the resulting type
+										: unknown;
+
+type RequiredObjectDeep<ObjectType extends object> = {
+	[KeyType in keyof ObjectType]-?: RequiredDeep<ObjectType[KeyType]>
+};
+
+export {};

package/source/required-keys-of.d.ts

@@ -0,0 +1,38 @@
+import type {OptionalKeysOf} from './optional-keys-of.d.ts';
+
+/**
+Extract all required keys from the given type.
+
+This is useful when you want to create a new type that contains different type values for the required keys only or use the list of keys for validation purposes, etc...
+
+@example
+```
+import type {RequiredKeysOf} from 'type-fest';
+
+declare function createValidation<
+	Entity extends object,
+	Key extends RequiredKeysOf<Entity> = RequiredKeysOf<Entity>,
+>(field: Key, validator: (value: Entity[Key]) => boolean): (entity: Entity) => boolean;
+
+type User = {
+	name: string;
+	surname: string;
+	luckyNumber?: number;
+};
+
+const validator1 = createValidation<User>('name', value => value.length < 25);
+const validator2 = createValidation<User>('surname', value => value.length < 25);
+
+// @ts-expect-error
+const validator3 = createValidation<User>('luckyNumber', value => value > 0);
+// Error: Argument of type '"luckyNumber"' is not assignable to parameter of type '"name" | "surname"'.
+```
+
+@category Utilities
+*/
+export type RequiredKeysOf<Type extends object> =
+	Type extends unknown // For distributing `Type`
+		? Exclude<keyof Type, OptionalKeysOf<Type>>
+		: never; // Should never happen
+
+export {};

package/source/schema.d.ts

@@ -0,0 +1,119 @@
+import type {ApplyDefaultOptions} from './internal/object.d.ts';
+import type {IfNotAnyOrNever, NonRecursiveType} from './internal/type.d.ts';
+import type {OptionalKeysOf} from './optional-keys-of.d.ts';
+import type {Simplify} from './simplify.d.ts';
+import type {UnknownArray} from './unknown-array.d.ts';
+
+/**
+@see {@link Schema}
+*/
+export type SchemaOptions = {
+	/**
+	By default, this affects elements in array and tuple types. You can change this by passing `{recurseIntoArrays: false}` as the third type argument:
+	- If `recurseIntoArrays` is set to `true` (default), array elements will be recursively processed as well.
+	- If `recurseIntoArrays` is set to `false`, arrays will not be recursively processed, and the entire array will be replaced with the given value type.
+
+	@example
+	```
+	import type {Schema} from 'type-fest';
+
+	type Participants = {
+		attendees: string[];
+		speakers: string[];
+	};
+
+	type ParticipantsWithMetadata = Schema<Participants, {id: number; name: string}, {recurseIntoArrays: true}>;
+	//=> {
+	// 	attendees: {
+	// 		id: number;
+	// 		name: string;
+	// 	}[];
+	// 	speakers: {
+	// 		id: number;
+	// 		name: string;
+	// 	}[];
+	// }
+
+	type ParticipantsCount = Schema<Participants, number, {recurseIntoArrays: false}>;
+	//=> {attendees: number; speakers: number}
+	```
+
+	@default true
+	*/
+	recurseIntoArrays?: boolean;
+};
+
+type DefaultSchemaOptions = {
+	recurseIntoArrays: true;
+};
+
+/**
+Create a deep version of another object type where property values are recursively replaced into a given value type.
+
+Use-cases:
+- Form validation: Define how each field should be validated.
+- Form settings: Define configuration for input fields.
+- Parsing: Define types that specify special behavior for specific fields.
+
+@example
+```
+import type {Schema} from 'type-fest';
+
+type User = {
+	id: string;
+	name: {
+		firstname: string;
+		lastname: string;
+	};
+	created: Date;
+	active: boolean;
+	passwordHash: string;
+	location: [latitude: number, longitude: number];
+};
+
+type UserMask = Schema<User, 'mask' | 'hide' | 'show'>;
+
+const userMaskSettings: UserMask = {
+	id: 'show',
+	name: {
+		firstname: 'show',
+		lastname: 'mask',
+	},
+	created: 'show',
+	active: 'show',
+	passwordHash: 'hide',
+	location: ['hide', 'hide'],
+};
+```
+
+@see {@link SchemaOptions}
+
+@category Object
+*/
+export type Schema<Type, Value, Options extends SchemaOptions = {}> =
+	IfNotAnyOrNever<Type,
+		_Schema<Type, Value, ApplyDefaultOptions<SchemaOptions, DefaultSchemaOptions, Options>>,
+		Value, Value>;
+
+type _Schema<Type, Value, Options extends Required<SchemaOptions>> =
+	Type extends NonRecursiveType | Map<unknown, unknown> | Set<unknown> | ReadonlyMap<unknown, unknown> | ReadonlySet<unknown>
+		? Value
+		: Type extends UnknownArray
+			? Options['recurseIntoArrays'] extends false
+				? Value
+				: SchemaHelper<Type, Value, Options>
+			: SchemaHelper<Type, Value, Options>;
+
+/**
+Internal helper for {@link _Schema}.
+
+Recursively transforms the value of each property in objects and arrays.
+*/
+type SchemaHelper<Type, Value, Options extends Required<SchemaOptions>> = Simplify<{
+	[Key in keyof Type]: _Schema<
+		Key extends OptionalKeysOf<Type & object> ? Exclude<Type[Key], undefined> : Type[Key], // Remove `| undefined` when accessing optional properties
+		Value,
+		Options>
+}>;
+
+export {};

package/source/screaming-snake-case.d.ts

@@ -0,0 +1,30 @@
+import type {_DefaultDelimiterCaseOptions} from './delimiter-case.d.ts';
+import type {ApplyDefaultOptions} from './internal/index.d.ts';
+import type {SnakeCase} from './snake-case.d.ts';
+import type {WordsOptions} from './words.d.ts';
+
+/**
+Convert a string literal to screaming-snake-case.
+
+This can be useful when, for example, converting a camel-cased object property to a screaming-snake-cased SQL column name.
+
+@example
+```
+import type {ScreamingSnakeCase} from 'type-fest';
+
+const someVariable: ScreamingSnakeCase<'fooBar'> = 'FOO_BAR';
+const someVariableNoSplitOnNumbers: ScreamingSnakeCase<'p2pNetwork', {splitOnNumbers: false}> = 'P2P_NETWORK';
+
+```
+
+@category Change case
+@category Template literal
+ */
+export type ScreamingSnakeCase<
+	Value,
+	Options extends WordsOptions = {},
+> = Value extends string
+	? Uppercase<SnakeCase<Value, ApplyDefaultOptions<WordsOptions, _DefaultDelimiterCaseOptions, Options>>>
+	: Value;
+
+export {};

package/source/set-field-type.d.ts

@@ -0,0 +1,67 @@
+import type {ApplyDefaultOptions} from './internal/index.d.ts';
+import type {Simplify} from './simplify.d.ts';
+
+export type SetFieldTypeOptions = {
+	/**
+	Preserve optional and readonly modifiers for properties being updated.
+
+	NOTE: Property modifiers will always be preserved for properties that are not being updated.
+
+	@default true
+	*/
+	preservePropertyModifiers?: boolean;
+};
+
+type DefaultSetFieldTypeOptions = {
+	preservePropertyModifiers: true;
+};
+
+/**
+Create a type that changes the type of the given keys.
+
+Use-cases:
+- Creating variations of a base model.
+- Fixing incorrect external types.
+
+@see `Merge` if you need to change multiple properties to different types.
+
+@example
+```
+import type {SetFieldType} from 'type-fest';
+
+type MyModel = {
+	readonly id: number;
+	readonly createdAt: Date;
+	updatedAt?: Date;
+};
+
+type MyModelApi1 = SetFieldType<MyModel, 'createdAt' | 'updatedAt', string>;
+// {
+// 	readonly id: number;
+// 	readonly createdAt: string;
+// 	updatedAt?: string;
+// }
+
+// `preservePropertyModifiers` option can be set to `false` if you want to remove property modifiers for properties being updated
+type MyModelApi2 = SetFieldType<MyModel, 'createdAt' | 'updatedAt', string, {preservePropertyModifiers: false}>;
+// {
+// 	readonly id: number;
+// 	createdAt: string; // no longer readonly
+// 	updatedAt: string; // no longer optional
+// }
+```
+
+@category Object
+*/
+export type SetFieldType<BaseType, Keys extends keyof BaseType, NewType, Options extends SetFieldTypeOptions = {}> =
+	_SetFieldType<BaseType, Keys, NewType, ApplyDefaultOptions<SetFieldTypeOptions, DefaultSetFieldTypeOptions, Options>>;
+
+type _SetFieldType<BaseType, Keys extends keyof BaseType, NewType, Options extends Required<SetFieldTypeOptions>> =
+	Simplify<{
+		[P in keyof BaseType]: P extends Keys ? NewType : BaseType[P];
+	} & (
+		// `Record` is used to remove property modifiers
+		Options['preservePropertyModifiers'] extends false ? Record<Keys, NewType> : unknown
+	)>;
+
+export {};

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

@@ -0,0 +1,85 @@
+import type {NonRecursiveType, StringToNumber} from './internal/index.d.ts';
+import type {Paths} from './paths.d.ts';
+import type {SetNonNullable} from './set-non-nullable.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';
+
+/**
+Create a type that makes the specified keys non-nullable (removes `null` and `undefined`), supports deeply nested key paths, and leaves all other keys unchanged.
+
+NOTE: Optional modifiers (`?`) are not removed from properties. For example, `SetNonNullableDeep<{foo?: string | null | undefined}, 'foo'>` will result in `{foo?: string}`.
+
+@example
+```
+import type {SetNonNullableDeep} from 'type-fest';
+
+type User = {
+	name: string;
+	address: {
+		city: string | undefined;
+		street?: string | null;
+	};
+	contact: {
+		email?: string | null | undefined;
+		phone: string | undefined;
+	};
+};
+
+type UpdatedUser = SetNonNullableDeep<User, 'address.street' | 'contact.email' | 'contact.phone'>;
+//=> {
+// 	name: string;
+// 	address: {
+// 		city: string | undefined;
+// 		street?: string;
+// 	};
+// 	contact: {
+// 		email?: string;
+// 		phone: string;
+// 	};
+// }
+```
+
+@example
+```
+import type {SetNonNullableDeep} from 'type-fest';
+
+// Set specific indices in an array to be non-nullable.
+type ArrayExample1 = SetNonNullableDeep<{a: [number | null, number | null, number | undefined]}, 'a.1' | 'a.2'>;
+//=> {a: [number | null, number, number]}
+
+// Optional modifier (`?`) is not removed.
+type ArrayExample2 = SetNonNullableDeep<{a: [(number | null)?, (number | null)?]}, 'a.1'>;
+//=> {a: [(number | null)?, number?]}
+```
+
+@category Object
+*/
+export type SetNonNullableDeep<BaseType, KeyPaths extends Paths<BaseType>> =
+	SetNonNullableDeepHelper<BaseType, UnionToTuple<KeyPaths>>;
+
+/**
+Internal helper for {@link SetNonNullableDeep}.
+
+Recursively transforms the `BaseType` by applying {@link SetNonNullableDeepSinglePath} for each path in `KeyPathsTuple`.
+*/
+type SetNonNullableDeepHelper<BaseType, KeyPathsTuple extends UnknownArray> =
+	KeyPathsTuple extends [infer KeyPath, ...infer RestPaths]
+		? SetNonNullableDeepHelper<SetNonNullableDeepSinglePath<BaseType, KeyPath>, RestPaths>
+		: BaseType;
+
+/**
+Makes a single path non-nullable in `BaseType`.
+*/
+type SetNonNullableDeepSinglePath<BaseType, KeyPath> =
+	BaseType extends NonRecursiveType | ReadonlySet<unknown> | ReadonlyMap<unknown, unknown> // Also distributes `BaseType`
+		? BaseType
+		: KeyPath extends `${infer Property}.${infer RestPath}`
+			? {
+				[Key in keyof BaseType]: Property extends `${Key & (string | number)}`
+					? SetNonNullableDeepSinglePath<BaseType[Key], RestPath>
+					: BaseType[Key];
+			}
+			: Simplify<SetNonNullable<BaseType, (KeyPath | StringToNumber<KeyPath & string>) & keyof BaseType>>;
+
+export {};

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

@@ -0,0 +1,41 @@
+/**
+Create a type that makes the given keys non-nullable, where the remaining keys are kept as is.
+
+If no keys are given, all keys will be made non-nullable.
+
+Use-case: You want to define a single model where the only thing that changes is whether or not some or all of the keys are non-nullable.
+
+@example
+```
+import type {SetNonNullable} from 'type-fest';
+
+type Foo = {
+	a: number | null;
+	b: string | undefined;
+	c?: boolean | null;
+};
+
+type SomeNonNullable = SetNonNullable<Foo, 'b' | 'c'>;
+// type SomeNonNullable = {
+// 	a: number | null;
+// 	b: string; // Can no longer be undefined.
+// 	c?: boolean; // Can no longer be null, but is still optional.
+// }
+
+type AllNonNullable = SetNonNullable<Foo>;
+// type AllNonNullable = {
+// 	a: number; // Can no longer be null.
+// 	b: string; // Can no longer be undefined.
+// 	c?: boolean; // Can no longer be null, but is still optional.
+// }
+```
+
+@category Object
+*/
+export type SetNonNullable<BaseType, Keys extends keyof BaseType = keyof BaseType> = {
+	[Key in keyof BaseType]: Key extends Keys
+		? NonNullable<BaseType[Key]>
+		: BaseType[Key];
+};
+
+export {};