@depup/type-fest 5.4.4-depup.0

package/source/distributed-pick.d.ts

@@ -0,0 +1,92 @@
+import type {KeysOfUnion} from './keys-of-union.d.ts';
+
+/**
+Pick keys from a type, distributing the operation over a union.
+
+TypeScript's `Pick` doesn't distribute over unions, leading to the erasure of unique properties from union members when picking keys. This creates a type that only retains properties common to all union members, making it impossible to access member-specific properties after the Pick. Essentially, using `Pick` 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: {
+		bar: string;
+	};
+};
+
+type B = {
+	discriminant: 'B';
+	foo: {
+		baz: string;
+	};
+};
+
+type Union = A | B;
+
+type PickedUnion = Pick<Union, 'discriminant' | 'foo'>;
+//=> {discriminant: 'A' | 'B'; foo: {bar: string} | {baz: string}}
+
+declare const pickedUnion: PickedUnion;
+
+if (pickedUnion.discriminant === 'A') {
+	// We would like to narrow `pickedUnion`'s type
+	// to `A` here, but we can't because `Pick`
+	// doesn't distribute over unions.
+
+	// @ts-expect-error
+	const barValue = pickedUnion.foo.bar;
+	// Error: Property 'bar' does not exist on type '{bar: string} | {baz: string}'.
+}
+```
+
+@example
+```
+import type {DistributedPick} from 'type-fest';
+
+type A = {
+	discriminant: 'A';
+	foo: {
+		bar: string;
+	};
+	extraneous: boolean;
+};
+
+type B = {
+	discriminant: 'B';
+	foo: {
+		baz: string;
+	};
+	extraneous: boolean;
+};
+
+// Notice that `foo.bar` exists in `A` but not in `B`.
+
+type Union = A | B;
+
+type PickedUnion = DistributedPick<Union, 'discriminant' | 'foo'>;
+
+declare const pickedUnion: PickedUnion;
+
+if (pickedUnion.discriminant === 'A') {
+	const barValue = pickedUnion.foo.bar;
+	// OK
+
+	// @ts-expect-error
+	const extraneousValue = pickedUnion.extraneous;
+	// Error: Property `extraneous` does not exist on type `Pick<A, 'discriminant' | 'foo'>`.
+
+	// @ts-expect-error
+	const bazValue = pickedUnion.foo.baz;
+	// Error: `bar` is not a property of `{discriminant: 'A'; a: string}`.
+}
+```
+
+@category Object
+*/
+export type DistributedPick<ObjectType, KeyType extends KeysOfUnion<ObjectType>> =
+	ObjectType extends unknown
+		? Pick<ObjectType, Extract<KeyType, keyof ObjectType>>
+		: never;
+
+export {};

package/source/empty-object.d.ts

@@ -0,0 +1,51 @@
+declare const emptyObjectSymbol: unique symbol;
+
+/**
+Represents a strictly empty plain object, the `{}` value.
+
+When you annotate something as the type `{}`, it can be anything except `null` and `undefined`. This means that you cannot use `{}` to represent an empty plain object ([read more](https://stackoverflow.com/questions/47339869/typescript-empty-object-and-any-difference/52193484#52193484)).
+
+@example
+```
+import type {EmptyObject} from 'type-fest';
+
+// The following illustrates the problem with `{}`.
+const foo1: {} = {}; // Pass
+const foo2: {} = []; // Pass
+const foo3: {} = 42; // Pass
+const foo4: {} = {a: 1}; // Pass
+
+// With `EmptyObject` only the first case is valid.
+const bar1: EmptyObject = {}; // Pass
+// @ts-expect-error
+const bar2: EmptyObject = []; // Fail
+// @ts-expect-error
+const bar3: EmptyObject = 42; // Fail
+// @ts-expect-error
+const bar4: EmptyObject = {a: 1}; // Fail
+```
+
+Unfortunately, `Record<string, never>`, `Record<keyof any, never>` and `Record<never, never>` do not work. See {@link https://github.com/sindresorhus/type-fest/issues/395 #395}.
+
+@category Object
+*/
+export type EmptyObject = {[emptyObjectSymbol]?: never};
+
+/**
+Returns a `boolean` for whether the type is strictly equal to an empty plain object, the `{}` value.
+
+@example
+```
+import type {IsEmptyObject} from 'type-fest';
+
+type Pass = IsEmptyObject<{}>; //=> true
+type Fail1 = IsEmptyObject<[]>; //=> false
+type Fail2 = IsEmptyObject<null>; //=> false
+```
+
+@see {@link EmptyObject}
+@category Object
+*/
+export type IsEmptyObject<T> = T extends EmptyObject ? true : false;
+
+export {};

package/source/entries.d.ts

@@ -0,0 +1,64 @@
+import type {_ArrayEntry, _MapEntry, _ObjectEntry, _SetEntry} from './entry.d.ts';
+
+type ArrayEntries<BaseType extends readonly unknown[]> = Array<_ArrayEntry<BaseType>>;
+type MapEntries<BaseType> = Array<_MapEntry<BaseType>>;
+type ObjectEntries<BaseType> = Array<_ObjectEntry<BaseType>>;
+type SetEntries<BaseType extends Set<unknown>> = Array<_SetEntry<BaseType>>;
+
+/**
+Many collections have an `entries` method which returns an array of a given object's own enumerable string-keyed property [key, value] pairs. The `Entries` type will return the type of that collection's entries.
+
+For example the {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries|`Object`}, {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/entries|`Map`}, {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/entries|`Array`}, and {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/entries|`Set`} collections all have this method. Note that `WeakMap` and `WeakSet` do not have this method since their entries are not enumerable.
+
+@see `Entry` if you want to just access the type of a single entry.
+
+@example
+```
+import type {Entries} from 'type-fest';
+
+type Example = {
+	someKey: number;
+};
+
+const manipulatesEntries = (examples: Entries<Example>) => examples.map(example => [
+	// Does some arbitrary processing on the key (with type information available)
+	example[0].toUpperCase(),
+
+	// Does some arbitrary processing on the value (with type information available)
+	example[1].toFixed(0),
+]);
+
+const example: Example = {someKey: 1};
+const entries = Object.entries(example) as Entries<Example>;
+const output = manipulatesEntries(entries);
+
+// Objects
+const objectExample = {a: 1};
+const objectEntries: Entries<typeof objectExample> = [['a', 1]];
+
+// Arrays
+const arrayExample = ['a', 1];
+const arrayEntries: Entries<typeof arrayExample> = [[0, 'a'], [1, 1]];
+
+// Maps
+const mapExample = new Map([['a', 1]]);
+const mapEntries: Entries<typeof mapExample> = [['a', 1]];
+
+// Sets
+const setExample = new Set(['a', 1]);
+const setEntries: Entries<typeof setExample> = [['a', 'a'], [1, 1]];
+```
+
+@category Object
+@category Map
+@category Set
+@category Array
+*/
+export type Entries<BaseType> =
+	BaseType extends Map<unknown, unknown> ? MapEntries<BaseType>
+		: BaseType extends Set<unknown> ? SetEntries<BaseType>
+			: BaseType extends readonly unknown[] ? ArrayEntries<BaseType>
+				: BaseType extends object ? ObjectEntries<BaseType>
+					: never;
+
+export {};

package/source/entry.d.ts

@@ -0,0 +1,67 @@
+type MapKey<BaseType> = BaseType extends Map<infer KeyType, unknown> ? KeyType : never;
+type MapValue<BaseType> = BaseType extends Map<unknown, infer ValueType> ? ValueType : never;
+
+export type _ArrayEntry<BaseType extends readonly unknown[]> = [number, BaseType[number]];
+export type _MapEntry<BaseType> = [MapKey<BaseType>, MapValue<BaseType>];
+export type _ObjectEntry<BaseType> = [keyof BaseType, BaseType[keyof BaseType]];
+export type _SetEntry<BaseType> = BaseType extends Set<infer ItemType> ? [ItemType, ItemType] : never;
+
+/**
+Many collections have an `entries` method which returns an array of a given object's own enumerable string-keyed property [key, value] pairs. The `Entry` type will return the type of that collection's entry.
+
+For example the {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries|`Object`}, {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/entries|`Map`}, {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/entries|`Array`}, and {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/entries|`Set`} collections all have this method. Note that `WeakMap` and `WeakSet` do not have this method since their entries are not enumerable.
+
+@see `Entries` if you want to just access the type of the array of entries (which is the return of the `.entries()` method).
+
+@example
+```
+import type {Entry} from 'type-fest';
+
+type Example = {
+	someKey: number;
+};
+
+const manipulatesEntry = (example: Entry<Example>) => [
+	// Does some arbitrary processing on the key (with type information available)
+	example[0].toUpperCase(),
+
+	// Does some arbitrary processing on the value (with type information available)
+	example[1].toFixed(0),
+];
+
+const example: Example = {someKey: 1};
+const entry = Object.entries(example)[0] as Entry<Example>;
+const output = manipulatesEntry(entry);
+
+// Objects
+const objectExample = {a: 1};
+const objectEntry: Entry<typeof objectExample> = ['a', 1];
+
+// Arrays
+const arrayExample = ['a', 1];
+const arrayEntryString: Entry<typeof arrayExample> = [0, 'a'];
+const arrayEntryNumber: Entry<typeof arrayExample> = [1, 1];
+
+// Maps
+const mapExample = new Map([['a', 1]]);
+const mapEntry: Entry<typeof mapExample> = ['a', 1];
+
+// Sets
+const setExample = new Set(['a', 1]);
+const setEntryString: Entry<typeof setExample> = ['a', 'a'];
+const setEntryNumber: Entry<typeof setExample> = [1, 1];
+```
+
+@category Object
+@category Map
+@category Array
+@category Set
+*/
+export type Entry<BaseType> =
+	BaseType extends Map<unknown, unknown> ? _MapEntry<BaseType>
+		: BaseType extends Set<unknown> ? _SetEntry<BaseType>
+			: BaseType extends readonly unknown[] ? _ArrayEntry<BaseType>
+				: BaseType extends object ? _ObjectEntry<BaseType>
+					: never;
+
+export {};

package/source/exact.d.ts

@@ -0,0 +1,73 @@
+import type {ObjectValue} from './internal/index.d.ts';
+import type {ArrayElement} from './array-element.d.ts';
+import type {IsEqual} from './is-equal.d.ts';
+import type {KeysOfUnion} from './keys-of-union.d.ts';
+import type {IsUnknown} from './is-unknown.d.ts';
+import type {Primitive} from './primitive.d.ts';
+
+/**
+Create a type from `ParameterType` and `InputType` and change keys exclusive to `InputType` to `never`.
+- Generate a list of keys that exists in `InputType` but not in `ParameterType`.
+- Mark these excess keys as `never`.
+*/
+type ExactObject<ParameterType, InputType> = {[Key in keyof ParameterType]: Exact<ParameterType[Key], ObjectValue<InputType, Key>>}
+	& Record<Exclude<keyof InputType, KeysOfUnion<ParameterType>>, never>;
+
+/**
+Create a type that does not allow extra properties, meaning it only allows properties that are explicitly declared.
+
+This is useful for function type-guarding to reject arguments with excess properties. Due to the nature of TypeScript, it does not complain if excess properties are provided unless the provided value is an object literal.
+
+*Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/12936) if you want to have this type as a built-in in TypeScript.*
+
+@example
+```
+type OnlyAcceptName = {name: string};
+
+declare function onlyAcceptName(arguments_: OnlyAcceptName): void;
+
+// TypeScript complains about excess properties when an object literal is provided.
+// @ts-expect-error
+onlyAcceptName({name: 'name', id: 1});
+// `id` is excess
+
+// TypeScript does not complain about excess properties when the provided value is a variable (not an object literal).
+const invalidInput = {name: 'name', id: 1};
+onlyAcceptName(invalidInput); // No errors
+```
+
+Having `Exact` allows TypeScript to reject excess properties.
+
+@example
+```
+import type {Exact} from 'type-fest';
+
+type OnlyAcceptName = {name: string};
+
+declare function onlyAcceptNameImproved<T extends Exact<OnlyAcceptName, T>>(arguments_: T): void;
+
+const invalidInput = {name: 'name', id: 1};
+// @ts-expect-error
+onlyAcceptNameImproved(invalidInput); // Compilation error
+```
+
+[Read more](https://stackoverflow.com/questions/49580725/is-it-possible-to-restrict-typescript-object-to-contain-only-properties-defined)
+
+@category Utilities
+*/
+export type Exact<ParameterType, InputType> =
+	// Before distributing, check if the two types are equal and if so, return the parameter type immediately
+	IsEqual<ParameterType, InputType> extends true ? ParameterType
+		// If the parameter is a primitive, return it as is immediately to avoid it being converted to a complex type
+		: ParameterType extends Primitive ? ParameterType
+			// If the parameter is an unknown, return it as is immediately to avoid it being converted to a complex type
+			: IsUnknown<ParameterType> extends true ? unknown
+				// If the parameter is a Function, return it as is because this type is not capable of handling function, leave it to TypeScript
+				: ParameterType extends Function ? ParameterType
+					// Convert union of array to array of union: A[] & B[] => (A & B)[]
+					: ParameterType extends unknown[] ? Array<Exact<ArrayElement<ParameterType>, ArrayElement<InputType>>>
+						// In TypeScript, Array is a subtype of ReadonlyArray, so always test Array before ReadonlyArray.
+						: ParameterType extends readonly unknown[] ? ReadonlyArray<Exact<ArrayElement<ParameterType>, ArrayElement<InputType>>>
+							: ExactObject<ParameterType, InputType>;
+
+export {};

package/source/except.d.ts

@@ -0,0 +1,112 @@
+import type {ApplyDefaultOptions} from './internal/index.d.ts';
+import type {IsEqual} from './is-equal.d.ts';
+
+/**
+Filter out keys from an object.
+
+Returns `never` if `Exclude` is strictly equal to `Key`.
+Returns `never` if `Key` extends `Exclude`.
+Returns `Key` otherwise.
+
+@example
+```
+type Filtered = Filter<'foo', 'foo'>;
+//=> never
+```
+
+@example
+```
+type Filtered = Filter<'bar', string>;
+//=> never
+```
+
+@example
+```
+type Filtered = Filter<'bar', 'foo'>;
+//=> 'bar'
+```
+
+@see {Except}
+*/
+type Filter<KeyType, ExcludeType> = IsEqual<KeyType, ExcludeType> extends true ? never : (KeyType extends ExcludeType ? never : KeyType);
+
+export type ExceptOptions = {
+	/**
+	Disallow assigning non-specified properties.
+
+	Note that any omitted properties in the resulting type will be present in autocomplete as `undefined`.
+
+	@default false
+	*/
+	requireExactProps?: boolean;
+};
+
+type DefaultExceptOptions = {
+	requireExactProps: false;
+};
+
+/**
+Create a type from an object type without certain keys.
+
+We recommend setting the `requireExactProps` option to `true`.
+
+This type is a stricter version of [`Omit`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-5.html#the-omit-helper-type). The `Omit` type does not restrict the omitted keys to be keys present on the given type, while `Except` does. The benefits of a stricter type are avoiding typos and allowing the compiler to pick up on rename refactors automatically.
+
+This type was proposed to the TypeScript team, which declined it, saying they prefer that libraries implement stricter versions of the built-in types ([microsoft/TypeScript#30825](https://github.com/microsoft/TypeScript/issues/30825#issuecomment-523668235)).
+
+@example
+```
+import type {Except} from 'type-fest';
+
+type Foo = {
+	a: number;
+	b: string;
+};
+
+type FooWithoutA = Except<Foo, 'a'>;
+//=> {b: string}
+
+// @ts-expect-error
+const fooWithoutA: FooWithoutA = {a: 1, b: '2'};
+// errors: 'a' does not exist in type '{ b: string; }'
+
+type FooWithoutB = Except<Foo, 'b', {requireExactProps: true}>;
+//=> {a: number} & Partial<Record<'b', never>>
+
+// @ts-expect-error
+const fooWithoutB: FooWithoutB = {a: 1, b: '2'};
+// errors at 'b': Type 'string' is not assignable to type 'undefined'.
+
+// The `Omit` utility type doesn't work when omitting specific keys from objects containing index signatures.
+
+// Consider the following example:
+
+type UserData = {
+	[metadata: string]: string;
+	email: string;
+	name: string;
+	role: 'admin' | 'user';
+};
+
+// `Omit` clearly doesn't behave as expected in this case:
+type PostPayload = Omit<UserData, 'email'>;
+//=> {[x: string]: string; [x: number]: string}
+
+// In situations like this, `Except` works better.
+// It simply removes the `email` key while preserving all the other keys.
+type PostPayloadFixed = Except<UserData, 'email'>;
+//=> {[x: string]: string; name: string; role: 'admin' | 'user'}
+```
+
+@category Object
+*/
+export type Except<ObjectType, KeysType extends keyof ObjectType, Options extends ExceptOptions = {}> =
+	_Except<ObjectType, KeysType, ApplyDefaultOptions<ExceptOptions, DefaultExceptOptions, Options>>;
+
+type _Except<ObjectType, KeysType extends keyof ObjectType, Options extends Required<ExceptOptions>> = {
+	[KeyType in keyof ObjectType as Filter<KeyType, KeysType>]: ObjectType[KeyType];
+} & (Options['requireExactProps'] extends true
+	? Partial<Record<KeysType, never>>
+	: {});
+
+export {};

package/source/exclude-rest-element.d.ts

@@ -0,0 +1,40 @@
+import type {SplitOnRestElement} from './split-on-rest-element.d.ts';
+import type {IsArrayReadonly} from './internal/array.d.ts';
+import type {UnknownArray} from './unknown-array.d.ts';
+import type {IfNotAnyOrNever} from './internal/type.d.ts';
+
+/**
+Create a tuple with the [`rest`](https://www.typescriptlang.org/docs/handbook/2/objects.html#tuple-types) element removed.
+
+@example
+```
+import type {ExcludeRestElement} from 'type-fest';
+
+type T1 = ExcludeRestElement<[number, ...string[], string, 'foo']>;
+//=> [number, string, 'foo']
+
+type T2 = ExcludeRestElement<[...boolean[], string]>;
+//=> [string]
+
+type T3 = ExcludeRestElement<[...Array<'foo'>, true]>;
+//=> [true]
+
+type T4 = ExcludeRestElement<[number, string]>;
+//=> [number, string]
+```
+
+@see {@link ExtractRestElement}
+@see {@link SplitOnRestElement}
+@category Array
+*/
+export type ExcludeRestElement<Array_ extends UnknownArray> = IfNotAnyOrNever<Array_,
+	SplitOnRestElement<Array_> extends infer Result
+		? Result extends readonly UnknownArray[]
+			? IsArrayReadonly<Array_> extends true
+				? Readonly<[...Result[0], ...Result[2]]>
+				: [...Result[0], ...Result[2]]
+			: never
+		: never
+>;
+
+export {};

package/source/exclude-strict.d.ts

@@ -0,0 +1,51 @@
+/**
+A stricter version of {@link Exclude<T, U>} that ensures every member of `U` can successfully exclude something from `T`.
+
+For example, `ExcludeStrict<string | number | boolean, number | bigint>` will error because `bigint` cannot exclude anything from `string | number | boolean`.
+
+@example
+```
+// Valid Examples
+import type {ExcludeStrict} from 'type-fest';
+
+type Example1 = ExcludeStrict<{status: 'success'; data: string[]} | {status: 'error'; error: string}, {status: 'success'}>;
+//=> {status: 'error'; error: string}
+
+type Example2 = ExcludeStrict<'xs' | 's' | 'm' | 'l' | 'xl', 'xs' | 's'>;
+//=> 'm' | 'l' | 'xl'
+
+type Example3 = ExcludeStrict<{x: number; y: number} | [number, number], unknown[]>;
+//=> {x: number; y: number}
+```
+
+@example
+```
+// Invalid Examples
+import type {ExcludeStrict} from 'type-fest';
+
+// `'xxl'` cannot exclude anything from `'xs' | 's' | 'm' | 'l' | 'xl'`
+// @ts-expect-error
+type Example1 = ExcludeStrict<'xs' | 's' | 'm' | 'l' | 'xl', 'xl' | 'xxl'>;
+//                                                           ~~~~~~~~~~~~
+// Error: Type "'xl' | 'xxl'" does not satisfy the constraint 'never'.
+
+// `unknown[]` cannot exclude anything from `{x: number; y: number} | {x: string; y: string}`
+// @ts-expect-error
+type Example2 = ExcludeStrict<{x: number; y: number} | {x: string; y: string}, unknown[]>;
+//                                                                             ~~~~~~~~~
+// Error: Type 'unknown[]' does not satisfy the constraint 'never'.
+```
+
+@category Improved Built-in
+*/
+export type ExcludeStrict<
+	T,
+	U extends [U] extends [
+		// Ensure every member of `U` excludes something from `T`
+		U extends unknown ? ([T] extends [Exclude<T, U>] ? never : U) : never,
+	]
+		? unknown
+		: never,
+> = Exclude<T, U>;
+
+export {};