@depup/type-fest 5.4.4-depup.0

package/source/exclusify-union.d.ts

@@ -0,0 +1,147 @@
+import type {If} from './if.d.ts';
+import type {IfNotAnyOrNever, MapsSetsOrArrays, NonRecursiveType} from './internal/type.d.ts';
+import type {IsUnknown} from './is-unknown.d.ts';
+import type {KeysOfUnion} from './keys-of-union.d.ts';
+import type {Simplify} from './simplify.d.ts';
+
+/**
+Ensure mutual exclusivity in object unions by adding other members’ keys as `?: never`.
+
+Use-cases:
+- You want each union member to be exclusive, preventing overlapping object shapes.
+- You want to safely access any property defined across the union without additional type guards.
+
+@example
+```
+import type {ExclusifyUnion} from 'type-fest';
+
+type FileConfig = {
+	filePath: string;
+};
+
+type InlineConfig = {
+	content: string;
+};
+
+declare function loadConfig1(options: FileConfig | InlineConfig): void;
+
+// Someone could mistakenly provide both `filePath` and `content`.
+loadConfig1({filePath: './config.json', content: '{ "name": "app" }'}); // No errors
+
+// Use `ExclusifyUnion` to prevent that mistake.
+type Config = ExclusifyUnion<FileConfig | InlineConfig>;
+//=> {
+// 	filePath: string;
+// 	content?: never;
+// } | {
+// 	content: string;
+// 	filePath?: never;
+// }
+
+declare function loadConfig2(options: Config): void;
+
+// @ts-expect-error
+loadConfig2({filePath: './config.json', content: '{ "name": "app" }'});
+// Error: Argument of type '{ filePath: string; content: string; }' is not assignable to parameter of type '{ filePath: string; content?: never; } | { content: string; filePath?: never; }'.
+
+loadConfig2({filePath: './config.json'}); // Ok
+
+loadConfig2({content: '{ "name": "app" }'}); // Ok
+```
+
+@example
+```
+import type {ExclusifyUnion} from 'type-fest';
+
+type CardPayment = {
+	amount: number;
+	cardNumber: string;
+};
+
+type PaypalPayment = {
+	amount: number;
+	paypalId: string;
+};
+
+function processPayment1(payment: CardPayment | PaypalPayment) {
+	// @ts-expect-error
+	const details = payment.cardNumber ?? payment.paypalId; // Cannot access `cardNumber` or `paypalId` directly
+}
+
+type Payment = ExclusifyUnion<CardPayment | PaypalPayment>;
+//=> {
+// 	amount: number;
+// 	cardNumber: string;
+// 	paypalId?: never;
+// } | {
+// 	amount: number;
+// 	paypalId: string;
+// 	cardNumber?: never;
+// }
+
+function processPayment2(payment: Payment) {
+	const details = payment.cardNumber ?? payment.paypalId; // Ok
+	//=> string
+}
+```
+
+@example
+```
+import type {ExclusifyUnion} from 'type-fest';
+
+type A = ExclusifyUnion<{a: string} | {b: number}>;
+//=> {a: string; b?: never} | {b: number; a?: never}
+
+type B = ExclusifyUnion<{a: string} | {b: number} | {c: boolean}>;
+//=> {
+// 	a: string;
+// 	b?: never;
+// 	c?: never;
+// } | {
+// 	b: number;
+// 	a?: never;
+// 	c?: never;
+// } | {
+// 	c: boolean;
+// 	a?: never;
+// 	b?: never;
+// }
+
+type C = ExclusifyUnion<{a: string; b: number} | {b: string; c: number}>;
+//=> {
+// 	a: string;
+// 	b: number;
+// 	c?: never;
+// } | {
+// 	b: string;
+// 	c: number;
+// 	a?: never;
+// }
+
+type D = ExclusifyUnion<{a?: 1; readonly b: 2} | {d: 4}>;
+//=> {a?: 1; readonly b: 2; d?: never} | {d: 4; a?: never; b?: never}
+```
+
+@category Object
+@category Union
+*/
+export type ExclusifyUnion<Union> = IfNotAnyOrNever<Union,
+	If<IsUnknown<Union>, Union,
+		Extract<Union, NonRecursiveType | MapsSetsOrArrays> extends infer SkippedMembers
+			? SkippedMembers | _ExclusifyUnion<Exclude<Union, SkippedMembers>>
+			: never
+	>
+>;
+
+type _ExclusifyUnion<Union, UnionCopy = Union> = Union extends unknown // For distributing `Union`
+	? Simplify<
+		Union & Partial<
+			Record<
+				Exclude<KeysOfUnion<UnionCopy>, keyof Union>,
+				never
+			>
+		>
+	>
+	: never; // Should never happen
+
+export {};

package/source/extends-strict.d.ts

@@ -0,0 +1,44 @@
+import type {IsNever} from './is-never.d.ts';
+import type {IsAny} from './is-any.d.ts';
+
+/**
+A stricter, non-distributive version of `extends` for checking whether one type is assignable to another.
+
+Unlike the built-in `extends` keyword, `ExtendsStrict`:
+
+1. Prevents distribution over union types by wrapping both types in tuples. For example, `ExtendsStrict<string | number, number>` returns `false`, whereas `string | number extends number` would result in `boolean`.
+
+2. Treats `never` as a special case: `never` doesn't extend every other type, it only extends itself (or `any`). For example, `ExtendsStrict<never, number>` returns `false` whereas `never extends number` would result in `true`.
+
+@example
+```
+import type {ExtendsStrict} from 'type-fest';
+
+type T1 = ExtendsStrict<number | string, string>;
+//=> false
+
+type T2 = ExtendsStrict<never, number>;
+//=> false
+
+type T3 = ExtendsStrict<never, never>;
+//=> true
+
+type T4 = ExtendsStrict<string, number | string>;
+//=> true
+
+type T5 = ExtendsStrict<string, string>;
+//=> true
+```
+
+@category Improved Built-in
+*/
+export type ExtendsStrict<Left, Right> =
+	IsAny<Left | Right> extends true
+		? true
+		: IsNever<Left> extends true
+			? IsNever<Right>
+			: [Left] extends [Right]
+				? true
+				: false;
+
+export {};

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

@@ -0,0 +1,30 @@
+import type {SplitOnRestElement} from './split-on-rest-element.d.ts';
+import type {UnknownArray} from './unknown-array.d.ts';
+
+/**
+Extract the [`rest`](https://www.typescriptlang.org/docs/handbook/2/objects.html#tuple-types) element type from an array.
+
+@example
+```
+import type {ExtractRestElement} from 'type-fest';
+
+type T1 = ExtractRestElement<[number, ...string[], string, 'foo']>;
+//=> string
+
+type T2 = ExtractRestElement<[...boolean[], string]>;
+//=> boolean
+
+type T3 = ExtractRestElement<[...Array<'foo'>, true]>;
+//=> 'foo'
+
+type T4 = ExtractRestElement<[number, string]>;
+//=> never
+```
+
+@see {@link ExcludeRestElement}
+@see {@link SplitOnRestElement}
+@category Array
+*/
+export type ExtractRestElement<T extends UnknownArray> = SplitOnRestElement<T>[1][number];
+
+export {};

package/source/extract-strict.d.ts

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

package/source/find-global-type.d.ts

@@ -0,0 +1,68 @@
+/**
+Tries to find the type of a global with the given name.
+
+Limitations: Due to peculiarities with the behavior of `globalThis`, "globally defined" only includes `var` declarations in `declare global` blocks, not `let` or `const` declarations.
+
+@example
+```
+import type {FindGlobalType} from 'type-fest';
+
+declare global {
+	const foo: number; // let and const don't work
+	var bar: string; // var works
+}
+
+type FooType = FindGlobalType<'foo'>; //=> never (let/const don't work)
+type BarType = FindGlobalType<'bar'>; //=> string
+type OtherType = FindGlobalType<'other'>; //=> never (no global named 'other')
+```
+
+@category Utilities
+*/
+export type FindGlobalType<Name extends string> = typeof globalThis extends Record<Name, infer T> ? T : never;
+
+/**
+Tries to find one or more types from their globally-defined constructors.
+
+Use-case: Conditionally referencing DOM types only when the DOM library present.
+
+*Limitations:* Due to peculiarities with the behavior of `globalThis`, "globally defined" has a narrow definition in this case. Declaring a class in a `declare global` block won't work, instead you must declare its type using an interface and declare its constructor as a `var` (*not* `let`/`const`) inside the `declare global` block.
+
+@example
+```
+import type {FindGlobalInstanceType} from 'type-fest';
+
+class Point {
+	constructor(public x: number, public y: number) {}
+}
+
+type PointLike = Point | FindGlobalInstanceType<'DOMPoint'>;
+```
+
+@example
+```
+import type {FindGlobalInstanceType} from 'type-fest';
+
+declare global {
+	// Class syntax won't add the key to `globalThis`
+	class Foo {}
+
+	// interface + constructor style works
+	interface Bar {
+		bar: string;
+	}
+	var Bar: new () => Bar; // Not let or const
+}
+
+type FindFoo = FindGlobalInstanceType<'Foo'>; // Doesn't work
+type FindBar = FindGlobalInstanceType<'Bar'>; // Works
+```
+
+@category Utilities
+*/
+export type FindGlobalInstanceType<Name extends string> =
+	Name extends string
+		? typeof globalThis extends Record<Name, abstract new (...arguments_: any[]) => infer T> ? T : never
+		: never;
+
+export {};

package/source/fixed-length-array.d.ts

@@ -0,0 +1,97 @@
+import type {Except} from './except.d.ts';
+import type {TupleOf} from './tuple-of.d.ts';
+
+/**
+Methods to exclude.
+*/
+type ArrayLengthMutationKeys = 'splice' | 'push' | 'pop' | 'shift' | 'unshift';
+
+/**
+Create a type that represents an array of the given type and length. The `Array` prototype methods that manipulate its length are excluded from the resulting type.
+
+The problem with the built-in tuple type is that it allows mutating methods like `push`, `pop` etc, which can cause issues, like in the following example:
+
+@example
+```
+const color: [number, number, number] = [255, 128, 64];
+
+function toHex([r, g, b]: readonly [number, number, number]) {
+	return `#${r.toString(16)}${g.toString(16)}${b.toString(16)}`;
+}
+
+color.pop(); // Allowed
+
+console.log(toHex(color)); // Compiles fine, but fails at runtime since index `2` no longer contains a `number`.
+```
+
+`ArrayLengthMutationKeys` solves this problem by excluding methods like `push`, `pop` etc from the resulting type.
+
+@example
+```
+import type {FixedLengthArray} from 'type-fest';
+
+const color: FixedLengthArray<number, 3> = [255, 128, 64];
+
+// @ts-expect-error
+color.pop();
+// Error: Property 'pop' does not exist on type 'FixedLengthArray<number, 3>'.
+```
+
+Use-cases:
+- Declaring fixed-length tuples or arrays with a large number of items.
+- Creating an array of coordinates with a static length, for example, length of 3 for a 3D vector.
+
+@example
+```
+import type {FixedLengthArray} from 'type-fest';
+
+let color: FixedLengthArray<number, 3> = [255, 128, 64];
+
+const red = color[0];
+//=> number
+const green = color[1];
+//=> number
+const blue = color[2];
+//=> number
+
+// @ts-expect-error
+const alpha = color[3];
+// Error: Property '3' does not exist on type 'FixedLengthArray<number, 3>'.
+
+// You can write to valid indices.
+color[0] = 128;
+color[1] = 64;
+color[2] = 32;
+
+// But you cannot write to out-of-bounds indices.
+// @ts-expect-error
+color[3] = 0.5;
+// Error: Property '3' does not exist on type 'FixedLengthArray<number, 3>'.
+
+// @ts-expect-error
+color.push(0.5);
+// Error: Property 'push' does not exist on type 'FixedLengthArray<number, 3>'.
+
+// @ts-expect-error
+color = [0, 128, 255, 0.5];
+// Error: Type '[number, number, number, number]' is not assignable to type 'FixedLengthArray<number, 3>'. Types of property 'length' are incompatible.
+
+// @ts-expect-error
+color.length = 4;
+// Error: Cannot assign to 'length' because it is a read-only property.
+
+function toHex([r, g, b]: readonly [number, number, number]) {
+	return `#${r.toString(16)}${g.toString(16)}${b.toString(16)}`;
+}
+
+console.log(toHex(color)); // `FixedLengthArray<number, 3>` is assignable to `readonly [number, number, number]`.
+```
+
+@category Array
+*/
+export type FixedLengthArray<Element, Length extends number> =
+	Except<TupleOf<Length, Element>, ArrayLengthMutationKeys | number | 'length'>
+	& {readonly length: Length}
+	& (number extends Length ? {[n: number]: Element} : {}); // Add `number` index signature only for non-tuple arrays.
+
+export {};

package/source/get.d.ts

@@ -0,0 +1,227 @@
+import type {ApplyDefaultOptions, ToString} from './internal/index.d.ts';
+import type {_LiteralStringUnion} from './literal-union.d.ts';
+import type {Paths} from './paths.d.ts';
+import type {Split} from './split.d.ts';
+import type {KeyAsString} from './key-as-string.d.ts';
+import type {DigitCharacter} from './characters.d.ts';
+
+export type GetOptions = {
+	/**
+	Include `undefined` in the return type when accessing properties.
+
+	Setting this to `false` is not recommended.
+
+	@default true
+	*/
+	strict?: boolean;
+};
+
+type DefaultGetOptions = {
+	strict: true;
+};
+
+/**
+Like the `Get` type but receives an array of strings as a path parameter.
+*/
+type GetWithPath<BaseType, Keys, Options extends Required<GetOptions>> =
+	Keys extends readonly []
+		? BaseType
+		: Keys extends readonly [infer Head, ...infer Tail]
+			? GetWithPath<
+				PropertyOf<BaseType, Extract<Head, string>, Options>,
+				Extract<Tail, string[]>,
+				Options
+			>
+			: never;
+
+/**
+Adds `undefined` to `Type` if `strict` is enabled.
+*/
+type Strictify<Type, Options extends Required<GetOptions>> =
+	Options['strict'] extends false ? Type : (Type | undefined);
+
+/**
+If `Options['strict']` is `true`, includes `undefined` in the returned type when accessing properties on `Record<string, any>`.
+
+Known limitations:
+- Does not include `undefined` in the type on object types with an index signature (for example, `{a: string; [key: string]: string}`).
+*/
+type StrictPropertyOf<BaseType, Key extends keyof BaseType, Options extends Required<GetOptions>> =
+	Record<string, any> extends BaseType
+		? string extends keyof BaseType
+			? Strictify<BaseType[Key], Options> // Record<string, any>
+			: BaseType[Key] // Record<'a' | 'b', any> (Records with a string union as keys have required properties)
+		: BaseType[Key];
+
+/**
+Splits a dot-prop style path into a tuple comprised of the properties in the path. Handles square-bracket notation.
+
+@example
+```
+type A = ToPath<'foo.bar.baz'>;
+//=> ['foo', 'bar', 'baz']
+
+type B = ToPath<'foo[0].bar.baz'>;
+//=> ['foo', '0', 'bar', 'baz']
+```
+*/
+type ToPath<S extends string> = Split<FixPathSquareBrackets<S>, '.', {strictLiteralChecks: false}>;
+
+/**
+Replaces square-bracketed dot notation with dots, for example, `foo[0].bar` -> `foo.0.bar`.
+*/
+type FixPathSquareBrackets<Path extends string> =
+	Path extends `[${infer Head}]${infer Tail}`
+		? Tail extends `[${string}`
+			? `${Head}.${FixPathSquareBrackets<Tail>}`
+			: `${Head}${FixPathSquareBrackets<Tail>}`
+		: Path extends `${infer Head}[${infer Middle}]${infer Tail}`
+			? `${Head}.${FixPathSquareBrackets<`[${Middle}]${Tail}`>}`
+			: Path;
+
+/**
+Returns true if `LongString` is made up out of `Substring` repeated 0 or more times.
+
+@example
+```
+type A = ConsistsOnlyOf<'aaa', 'a'>; //=> true
+type B = ConsistsOnlyOf<'ababab', 'ab'>; //=> true
+type C = ConsistsOnlyOf<'aBa', 'a'>; //=> false
+type D = ConsistsOnlyOf<'', 'a'>; //=> true
+```
+*/
+type ConsistsOnlyOf<LongString extends string, Substring extends string> =
+	LongString extends ''
+		? true
+		: LongString extends `${Substring}${infer Tail}`
+			? ConsistsOnlyOf<Tail, Substring>
+			: false;
+
+/**
+Convert a type which may have number keys to one with string keys, making it possible to index using strings retrieved from template types.
+
+@example
+```
+type WithNumbers = {foo: string; 0: boolean};
+type WithStrings = WithStringKeys<WithNumbers>;
+
+type WithNumbersKeys = keyof WithNumbers;
+//=> 'foo' | 0
+type WithStringsKeys = keyof WithStrings;
+//=> 'foo' | '0'
+```
+*/
+type WithStringKeys<BaseType> = {
+	[Key in KeyAsString<BaseType>]: UncheckedIndex<BaseType, Key>
+};
+
+/**
+Perform a `T[U]` operation if `T` supports indexing.
+*/
+type UncheckedIndex<T, U extends string | number> = [T] extends [Record<string | number, any>] ? T[U] : never;
+
+/**
+Get a property of an object or array. Works when indexing arrays using number-literal-strings, for example, `PropertyOf<number[], '0'> = number`, and when indexing objects with number keys.
+
+Note:
+- Returns `unknown` if `Key` is not a property of `BaseType`, since TypeScript uses structural typing, and it cannot be guaranteed that extra properties unknown to the type system will exist at runtime.
+- Returns `undefined` from nullish values, to match the behaviour of most deep-key libraries like `lodash`, `dot-prop`, etc.
+*/
+type PropertyOf<BaseType, Key extends string, Options extends Required<GetOptions>> =
+	BaseType extends null | undefined
+		? undefined
+		: Key extends keyof BaseType
+			? StrictPropertyOf<BaseType, Key, Options>
+			// Handle arrays and tuples
+			: BaseType extends readonly unknown[]
+				? Key extends `${number}`
+					// For arrays with unknown length (regular arrays)
+					? number extends BaseType['length']
+						? Strictify<BaseType[number], Options>
+						// For tuples: check if the index is valid
+						: Key extends keyof BaseType
+							? Strictify<BaseType[Key & keyof BaseType], Options>
+							// Out-of-bounds access for tuples
+							: unknown
+					// Non-numeric string key for arrays/tuples
+					: unknown
+				// Handle array-like objects
+				: BaseType extends {
+					[n: number]: infer Item;
+					length: number; // Note: This is needed to avoid being too lax with records types using number keys like `{0: string; 1: boolean}`.
+				}
+					? (
+						ConsistsOnlyOf<Key, DigitCharacter> extends true
+							? Strictify<Item, Options>
+							: unknown
+					)
+					: Key extends keyof WithStringKeys<BaseType>
+						? StrictPropertyOf<WithStringKeys<BaseType>, Key, Options>
+						: unknown;
+
+// This works by first splitting the path based on `.` and `[...]` characters into a tuple of string keys. Then it recursively uses the head key to get the next property of the current object, until there are no keys left. Number keys extract the item type from arrays, or are converted to strings to extract types from tuples and dictionaries with number keys.
+/**
+Get a deeply-nested property from an object using a key path, like Lodash's `.get()` function.
+
+Use-case: Retrieve a property from deep inside an API response or some other complex object.
+
+@example
+```
+import type {Get} from 'type-fest';
+
+declare function get<BaseType, const Path extends string | readonly string[]>(object: BaseType, path: Path): Get<BaseType, Path>;
+
+type ApiResponse = {
+	hits: {
+		hits: Array<{
+			_id: string;
+			_source: {
+				name: Array<{
+					given: string[];
+					family: string;
+				}>;
+				birthDate: string;
+			};
+		}>;
+	};
+};
+
+const getName = (apiResponse: ApiResponse) => get(apiResponse, 'hits.hits[0]._source.name');
+//=> (apiResponse: ApiResponse) => {
+// 	given: string[];
+// 	family: string;
+// }[] | undefined
+
+// Path also supports a readonly array of strings
+const getNameWithPathArray = (apiResponse: ApiResponse) => get(apiResponse, ['hits', 'hits', '0', '_source', 'name']);
+//=> (apiResponse: ApiResponse) => {
+// 	given: string[];
+// 	family: string;
+// }[] | undefined
+
+// Non-strict mode:
+type A = Get<string[], '3', {strict: false}>;
+//=> string
+
+type B = Get<Record<string, string>, 'foo', {strict: true}>;
+//=> string | undefined
+```
+
+@category Object
+@category Array
+@category Template literal
+*/
+export type Get<
+	BaseType,
+	Path extends
+	| readonly string[]
+	| _LiteralStringUnion<ToString<Paths<BaseType, {bracketNotation: false; maxRecursionDepth: 2}> | Paths<BaseType, {bracketNotation: true; maxRecursionDepth: 2}>>>,
+	Options extends GetOptions = {},
+> =
+	GetWithPath<
+		BaseType,
+		Path extends string ? ToPath<Path> : Path,
+		ApplyDefaultOptions<GetOptions, DefaultGetOptions, Options>
+	>;
+
+export {};

package/source/global-this.d.ts

@@ -0,0 +1,24 @@
+/**
+Declare locally scoped properties on `globalThis`.
+
+When defining a global variable in a declaration file is inappropriate, it can be helpful to define a `type` or `interface` (say `ExtraGlobals`) with the global variable and then cast `globalThis` via code like `globalThis as unknown as ExtraGlobals`.
+
+Instead of casting through `unknown`, you can update your `type` or `interface` to extend `GlobalThis` and then directly cast `globalThis`.
+
+@example
+```
+import type {GlobalThis} from 'type-fest';
+
+type ExtraGlobals = GlobalThis & {
+	readonly GLOBAL_TOKEN: string;
+};
+
+const globalToken = (globalThis as ExtraGlobals).GLOBAL_TOKEN;
+//=> string
+```
+
+@category Type
+*/
+export type GlobalThis = typeof globalThis;
+
+export {};

package/source/globals/index.d.ts

@@ -0,0 +1,3 @@
+export type * from './observable-like.d.ts';
+
+export {};