@depup/type-fest 5.4.4-depup.0

package/source/pick-deep.d.ts

@@ -0,0 +1,152 @@
+import type {TupleOf} from './tuple-of.d.ts';
+import type {BuildObject, NonRecursiveType, ObjectValue} from './internal/index.d.ts';
+import type {IsNever} from './is-never.d.ts';
+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';
+
+/**
+Pick properties from a deeply-nested object.
+
+It supports recursing into arrays.
+
+Use-case: Distill complex objects down to the components you need to target.
+
+@example
+```
+import type {PickDeep, PartialDeep} from 'type-fest';
+
+type Configuration = {
+	userConfig: {
+		name: string;
+		age: number;
+		address: [
+			{
+				city1: string;
+				street1: string;
+			},
+			{
+				city2: string;
+				street2: string;
+			},
+		];
+	};
+	otherConfig: any;
+};
+
+type NameConfig = PickDeep<Configuration, 'userConfig.name'>;
+// type NameConfig = {
+// 	userConfig: {
+// 		name: string;
+// 	}
+// };
+
+// Supports optional properties
+type User = PickDeep<PartialDeep<Configuration>, 'userConfig.name' | 'userConfig.age'>;
+// type User = {
+// 	userConfig?: {
+// 		name?: string;
+// 		age?: number;
+// 	};
+// };
+
+// Supports array
+type AddressConfig = PickDeep<Configuration, 'userConfig.address.0'>;
+// type AddressConfig = {
+// 	userConfig: {
+// 		address: [{
+// 			city1: string;
+// 			street1: string;
+// 		}];
+// 	};
+// }
+
+// Supports recurse into array
+type Street = PickDeep<Configuration, 'userConfig.address.1.street2'>;
+// type Street = {
+// 	userConfig: {
+// 		address: [
+// 			unknown,
+// 			{street2: string}
+// 		];
+// 	};
+// }
+```
+
+@category Object
+@category Array
+*/
+export type PickDeep<T, PathUnion extends Paths<T>> =
+	T extends NonRecursiveType
+		? never
+		: T extends UnknownArray
+			? UnionToIntersection<{
+				[P in PathUnion]: InternalPickDeep<T, P>;
+			}[PathUnion]
+			>
+			: T extends object
+				? Simplify<UnionToIntersection<{
+					[P in PathUnion]: InternalPickDeep<T, P>;
+				}[PathUnion]>>
+				: never;
+
+/**
+Pick an object/array from the given object/array by one path.
+*/
+type InternalPickDeep<T, Path extends string | number> =
+	T extends NonRecursiveType
+		? never
+		: T extends UnknownArray ? PickDeepArray<T, Path>
+			: T extends object ? Simplify<PickDeepObject<T, Path>>
+				: never;
+
+/**
+Pick an object from the given object by one path.
+*/
+type PickDeepObject<RecordType extends object, P extends string | number> =
+	P extends `${infer RecordKeyInPath}.${infer SubPath}`
+		? ObjectValue<RecordType, RecordKeyInPath> extends infer ObjectV
+			? IsNever<ObjectV> extends false
+				? BuildObject<RecordKeyInPath, InternalPickDeep<NonNullable<ObjectV>, SubPath>, RecordType>
+				: never
+			: never
+		: ObjectValue<RecordType, P> extends infer ObjectV
+			? IsNever<ObjectV> extends false
+				? BuildObject<P, ObjectV, RecordType>
+				: never
+			: never;
+
+/**
+Pick an array from the given array by one path.
+*/
+type PickDeepArray<ArrayType extends UnknownArray, P extends string | number> =
+	// Handle paths that are `${number}.${string}`
+	P extends `${infer ArrayIndex extends number}.${infer SubPath}`
+		// When `ArrayIndex` is equal to `number`
+		? number extends ArrayIndex
+			? ArrayType extends unknown[]
+				? Array<InternalPickDeep<NonNullable<ArrayType[number]>, SubPath>>
+				: ArrayType extends readonly unknown[]
+					? ReadonlyArray<InternalPickDeep<NonNullable<ArrayType[number]>, SubPath>>
+					: never
+			// When `ArrayIndex` is a number literal
+			: ArrayType extends unknown[]
+				? [...TupleOf<ArrayIndex>, InternalPickDeep<NonNullable<ArrayType[ArrayIndex]>, SubPath>]
+				: ArrayType extends readonly unknown[]
+					? readonly [...TupleOf<ArrayIndex>, InternalPickDeep<NonNullable<ArrayType[ArrayIndex]>, SubPath>]
+					: never
+		// When the path is equal to `number`
+		: P extends `${infer ArrayIndex extends number}`
+			// When `ArrayIndex` is `number`
+			? number extends ArrayIndex
+				? ArrayType
+				// When `ArrayIndex` is a number literal
+				: ArrayType extends unknown[]
+					? [...TupleOf<ArrayIndex>, ArrayType[ArrayIndex]]
+					: ArrayType extends readonly unknown[]
+						? readonly [...TupleOf<ArrayIndex>, ArrayType[ArrayIndex]]
+						: never
+			: never;
+
+export {};

package/source/pick-index-signature.d.ts

@@ -0,0 +1,52 @@
+/**
+Pick only index signatures from the given object type, leaving out all explicitly defined properties.
+
+This is the counterpart of `OmitIndexSignature`.
+
+@example
+```
+import type {PickIndexSignature} from 'type-fest';
+
+declare const symbolKey: unique symbol;
+
+type Example = {
+	// These index signatures will remain.
+	[x: string]: unknown;
+	[x: number]: unknown;
+	[x: symbol]: unknown;
+	[x: `head-${string}`]: string;
+	[x: `${string}-tail`]: string;
+	[x: `head-${string}-tail`]: string;
+	[x: `${bigint}`]: string;
+	[x: `embedded-${number}`]: string;
+
+	// These explicitly defined keys will be removed.
+	['kebab-case-key']: string;
+	[symbolKey]: string;
+	foo: 'bar';
+	qux?: 'baz';
+};
+
+type ExampleIndexSignature = PickIndexSignature<Example>;
+// {
+// 	[x: string]: unknown;
+// 	[x: number]: unknown;
+// 	[x: symbol]: unknown;
+// 	[x: `head-${string}`]: string;
+// 	[x: `${string}-tail`]: string;
+// 	[x: `head-${string}-tail`]: string;
+// 	[x: `${bigint}`]: string;
+// 	[x: `embedded-${number}`]: string;
+// }
+```
+
+@see {@link OmitIndexSignature}
+@category Object
+*/
+export type PickIndexSignature<ObjectType> = {
+	[KeyType in keyof ObjectType as {} extends Record<KeyType, unknown>
+		? KeyType
+		: never]: ObjectType[KeyType];
+};
+
+export {};

package/source/primitive.d.ts

@@ -0,0 +1,15 @@
+/**
+Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
+
+@category Type
+*/
+export type Primitive =
+	| null
+	| undefined
+	| string
+	| number
+	| boolean
+	| symbol
+	| bigint;
+
+export {};

package/source/promisable.d.ts

@@ -0,0 +1,27 @@
+/**
+Create a type that represents either the value or the value wrapped in `PromiseLike`.
+
+Use-cases:
+- A function accepts a callback that may either return a value synchronously or may return a promised value.
+- This type could be the return type of `Promise#then()`, `Promise#catch()`, and `Promise#finally()` callbacks.
+
+Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/31394) if you want to have this type as a built-in in TypeScript.
+
+@example
+```
+import type {Promisable} from 'type-fest';
+
+async function logger(getLogEntry: () => Promisable<string>): Promise<void> {
+	const entry = await getLogEntry();
+	console.log(entry);
+}
+
+await logger(() => 'foo');
+await logger(() => Promise.resolve('bar'));
+```
+
+@category Async
+*/
+export type Promisable<T> = T | PromiseLike<T>;
+
+export {};

package/source/readonly-deep.d.ts

@@ -0,0 +1,116 @@
+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.
+
+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.
+
+@example
+```
+import type {ReadonlyDeep} from 'type-fest';
+
+declare const foo: {
+	a: string;
+	b: {c: number};
+	d: Array<{e: number}>;
+};
+
+foo.a = 'bar'; // Allowed
+
+foo.b = {c: 3}; // Allowed
+
+foo.b.c = 4; // Allowed
+
+foo.d = [{e: 5}]; // Allowed
+
+foo.d.push({e: 6}); // Allowed
+
+const last = foo.d.at(-1);
+if (last) {
+	last.e = 7; // Allowed
+}
+
+declare const readonlyFoo: ReadonlyDeep<typeof foo>;
+
+// @ts-expect-error
+readonlyFoo.a = 'bar';
+// Error: Cannot assign to 'a' because it is a read-only property.
+
+// @ts-expect-error
+readonlyFoo.b = {c: 3};
+// Error: Cannot assign to 'b' because it is a read-only property.
+
+// @ts-expect-error
+readonlyFoo.b.c = 4;
+// Error: Cannot assign to 'c' because it is a read-only property.
+
+// @ts-expect-error
+readonlyFoo.d = [{e: 5}];
+// Error: Cannot assign to 'd' because it is a read-only property.
+
+// @ts-expect-error
+readonlyFoo.d.push({e: 6});
+// Error: Property 'push' does not exist on type 'ReadonlyArray<{readonly e: number}>'.
+
+const readonlyLast = readonlyFoo.d.at(-1);
+if (readonlyLast) {
+	// @ts-expect-error
+	readonlyLast.e = 8;
+	// Error: Cannot assign to 'e' because it is a read-only property.
+}
+```
+
+Note that types containing overloaded functions are not made deeply readonly due to a [TypeScript limitation](https://github.com/microsoft/TypeScript/issues/29732).
+
+@category Object
+@category Array
+@category Set
+@category Map
+*/
+export type ReadonlyDeep<T> = T extends BuiltIns
+	? T
+	: T extends new (...arguments_: any[]) => unknown
+		? T // Skip class constructors
+		: T extends (...arguments_: any[]) => unknown
+			? {} extends _ReadonlyObjectDeep<T>
+				? T
+				: HasMultipleCallSignatures<T> extends true
+					? T
+					: ((...arguments_: Parameters<T>) => ReturnType<T>) & _ReadonlyObjectDeep<T>
+			: T extends Readonly<ReadonlyMap<infer KeyType, infer ValueType>>
+				? 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[]]
+						? readonly []
+						: T extends readonly [infer U, ...infer V]
+							? readonly [ReadonlyDeep<U>, ...ReadonlyDeep<V>]
+							: T extends readonly [...infer U, infer V]
+								? readonly [...ReadonlyDeep<U>, ReadonlyDeep<V>]
+								: T extends ReadonlyArray<infer ItemType>
+									? ReadonlyArray<ReadonlyDeep<ItemType>>
+									: T extends object
+										? _ReadonlyObjectDeep<T>
+										: unknown;
+
+/**
+Same as `ReadonlyDeep`, but accepts only `ReadonlyMap`s as inputs. Internal helper for `ReadonlyDeep`.
+*/
+type ReadonlyMapDeep<KeyType, ValueType> = {} & Readonly<ReadonlyMap<ReadonlyDeep<KeyType>, ReadonlyDeep<ValueType>>>;
+
+/**
+Same as `ReadonlyDeep`, but accepts only `ReadonlySet`s as inputs. Internal helper for `ReadonlyDeep`.
+*/
+type ReadonlySetDeep<ItemType> = {} & Readonly<ReadonlySet<ReadonlyDeep<ItemType>>>;
+
+/**
+Same as `ReadonlyDeep`, but accepts only `object`s as inputs. Internal helper for `ReadonlyDeep`.
+*/
+export type _ReadonlyObjectDeep<ObjectType extends object> = {
+	readonly [KeyType in keyof ObjectType]: ReadonlyDeep<ObjectType[KeyType]>
+};
+
+export {};

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

@@ -0,0 +1,38 @@
+import type {IsReadonlyKeyOf} from './is-readonly-key-of.d.ts';
+
+/**
+Extract all readonly keys from the given type.
+
+This is useful when you want to create a new type that contains readonly keys only.
+
+@example
+```
+import type {ReadonlyKeysOf} from 'type-fest';
+
+type User = {
+	name: string;
+	surname: string;
+
+	readonly id: number;
+};
+
+type UpdateResponse<Entity extends object> = Pick<Entity, ReadonlyKeysOf<Entity>>;
+
+const update1: UpdateResponse<User> = {
+	id: 123,
+};
+```
+
+@category Utilities
+*/
+export type ReadonlyKeysOf<Type extends object> =
+	Type extends unknown // For distributing `Type`
+		? (keyof {[Key in keyof Type as
+			IsReadonlyKeyOf<Type, Key> extends false
+				? never
+				: Key
+			]: never
+		}) & keyof Type // Intersect with `keyof Type` to ensure result of `ReadonlyKeysOf<Type>` is always assignable to `keyof Type`
+		: never; // Should never happen
+
+export {};

package/source/readonly-tuple.d.ts

@@ -0,0 +1,34 @@
+import type {TupleOf} from './tuple-of.d.ts';
+
+/**
+Create a type that represents a read-only tuple of the given type and length.
+
+Use-cases:
+- Declaring fixed-length tuples with a large number of items.
+- Creating a range union (for example, `0 | 1 | 2 | 3 | 4` from the keys of such a type) without having to resort to recursive types.
+- Creating a tuple of coordinates with a static length, for example, length of 3 for a 3D vector.
+
+@example
+```
+import type {ReadonlyTuple} from 'type-fest';
+
+type FencingTeam = ReadonlyTuple<string, 3>;
+
+const guestFencingTeam: FencingTeam = ['Josh', 'Michael', 'Robert'];
+
+// @ts-expect-error
+const homeFencingTeam: FencingTeam = ['George', 'John'];
+// Error: Type '[string, string]' is not assignable to type 'readonly [string, string, string]'.
+
+// @ts-expect-error
+guestFencingTeam.push('Sam');
+// Error: Property 'push' does not exist on type 'readonly [string, string, string]'.
+```
+
+@deprecated This type will be removed in the next major version. Use the built-in `Readonly` type in combination with the {@link TupleOf} type instead, like `Readonly<TupleOf<Length, Element>>`.
+
+@category Utilities
+*/
+export type ReadonlyTuple<Element, Length extends number> = Readonly<TupleOf<Length, Element>>;
+
+export {};

package/source/remove-prefix.d.ts

@@ -0,0 +1,132 @@
+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 {Or} from './or.d.ts';
+
+/**
+@see {@link RemovePrefix}
+*/
+export type RemovePrefixOptions = {
+	/**
+	When enabled, instantiations with non-literal prefixes (e.g., `string`, `Uppercase<string>`, `` `on${string}` ``) simply return `string`, since their precise structure cannot be statically determined.
+
+	Note: Disabling this option can produce misleading results that might not reflect the actual runtime behavior.
+	For example, ``RemovePrefix<'on-change', `${string}-`, {strict: false}>`` returns `'change'`, but at runtime, prefix could be `'handle-'` (which satisfies `` `${string}-` ``) and removing `'handle-'` from `'on-change'` would not result in `'change'`.
+
+	So, it is recommended to not disable this option unless you are aware of the implications.
+
+	@default true
+
+	@example
+	```
+	import type {RemovePrefix} from 'type-fest';
+
+	type A = RemovePrefix<'on-change', `${string}-`, {strict: true}>;
+	//=> string
+
+	type B = RemovePrefix<'on-change', `${string}-`, {strict: false}>;
+	//=> 'change'
+
+	type C = RemovePrefix<'on-change', string, {strict: true}>;
+	//=> string
+
+	type D = RemovePrefix<'on-change', string, {strict: false}>;
+	//=> 'n-change'
+
+	type E = RemovePrefix<`${string}/${number}`, `${string}/`, {strict: true}>;
+	//=> string
+
+	type F = RemovePrefix<`${string}/${number}`, `${string}/`, {strict: false}>;
+	//=> `${number}`
+	```
+
+	Note: This option has no effect when only the input string type is non-literal. For example, ``RemovePrefix<`on-${string}`, 'on-'>`` will always return `string`.
+
+	@example
+	```
+	import type {RemovePrefix} from 'type-fest';
+
+	type A = RemovePrefix<`on-${string}`, 'on-', {strict: true}>;
+	//=> string
+
+	type B = RemovePrefix<`on-${string}`, 'on-', {strict: false}>;
+	//=> string
+
+	type C = RemovePrefix<`id-${number}`, 'id-', {strict: true}>;
+	//=> `${number}`
+
+	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;
+};
+
+type DefaultRemovePrefixOptions = {
+	strict: true;
+};
+
+/**
+Remove the specified prefix from the start of a string.
+
+@example
+```
+import type {RemovePrefix} from 'type-fest';
+
+type A = RemovePrefix<'on-change', 'on-'>;
+//=> 'change'
+
+type B = RemovePrefix<'sm:flex' | 'sm:p-4' | 'sm:gap-2', 'sm:'>;
+//=> 'flex' | 'p-4' | 'gap-2'
+
+type C = RemovePrefix<'on-change', 'off-'>;
+//=> 'on-change'
+
+type D = RemovePrefix<`handle${Capitalize<string>}`, 'handle'>;
+//=> Capitalize<string>
+```
+
+@see {@link RemovePrefixOptions}
+
+@category String
+@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
+	>
+>;
+
+type _RemovePrefix<S extends string, Prefix extends string, Options extends Required<RemovePrefixOptions>> =
+Prefix extends string // For distributing `Prefix`
+	? S extends `${Prefix}${infer Rest}`
+		? 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;
+
+export {};

package/source/replace.d.ts

@@ -0,0 +1,87 @@
+import type {ApplyDefaultOptions} from './internal/index.d.ts';
+
+export type ReplaceOptions = {
+	all?: boolean;
+};
+
+type DefaultReplaceOptions = {
+	all: false;
+};
+
+/**
+Represents a string with some or all matches replaced by a replacement.
+
+Use-case:
+- `kebab-case-path` to `dotted.path.notation`
+- Changing date/time format: `01-08-2042` → `01/08/2042`
+- Manipulation of type properties, for example, removal of prefixes
+
+@example
+```
+import type {Replace} from 'type-fest';
+
+declare function replace<
+	Input extends string,
+	Search extends string,
+	Replacement extends string,
+>(
+	input: Input,
+	search: Search,
+	replacement: Replacement
+): Replace<Input, Search, Replacement>;
+
+declare function replaceAll<
+	Input extends string,
+	Search extends string,
+	Replacement extends string,
+>(
+	input: Input,
+	search: Search,
+	replacement: Replacement
+): Replace<Input, Search, Replacement, {all: true}>;
+
+// The return type is the exact string literal, not just `string`.
+
+replace('hello ?', '?', '🦄');
+//=> 'hello 🦄'
+
+replace('hello ??', '?', '❓');
+//=> 'hello ❓?'
+
+replaceAll('10:42:00', ':', '-');
+//=> '10-42-00'
+
+replaceAll('__userName__', '__', '');
+//=> 'userName'
+
+replaceAll('My Cool Title', ' ', '');
+//=> 'MyCoolTitle'
+```
+
+@category String
+@category Template literal
+*/
+export type Replace<
+	Input extends string,
+	Search extends string,
+	Replacement extends string,
+	Options extends ReplaceOptions = {},
+> = _Replace<Input, Search, Replacement, ApplyDefaultOptions<ReplaceOptions, DefaultReplaceOptions, Options>>;
+
+type _Replace<
+	Input extends string,
+	Search extends string,
+	Replacement extends string,
+	Options extends Required<ReplaceOptions>,
+	Accumulator extends string = '',
+> = Search extends string // For distributing `Search`
+	? Replacement extends string // For distributing `Replacement`
+		? Input extends `${infer Head}${Search}${infer Tail}`
+			? Options['all'] extends true
+				? _Replace<Tail, Search, Replacement, Options, `${Accumulator}${Head}${Replacement}`>
+				: `${Head}${Replacement}${Tail}`
+			: `${Accumulator}${Input}`
+		: never
+	: never;
+
+export {};