@depup/type-fest 5.4.4-depup.0

package/source/globals/observable-like.d.ts

@@ -0,0 +1,78 @@
+declare global {
+	// eslint-disable-next-line @typescript-eslint/consistent-type-definitions -- It has to be an `interface` so that it can be merged.
+	interface SymbolConstructor {
+		readonly observable: symbol;
+	}
+}
+
+/**
+@remarks
+The TC39 observable proposal defines a `closed` property, but some implementations (such as xstream) do not as of 10/08/2021.
+As well, some guidance on making an `Observable` to not include `closed` property.
+
+@see https://github.com/tc39/proposal-observable/blob/master/src/Observable.js#L129-L130
+@see https://github.com/staltz/xstream/blob/6c22580c1d84d69773ee4b0905df44ad464955b3/src/index.ts#L79-L85
+@see https://github.com/benlesh/symbol-observable#making-an-object-observable
+
+@category Observable
+*/
+// eslint-disable-next-line type-fest/require-exported-types
+export type Unsubscribable = {
+	unsubscribe(): void;
+};
+
+/**
+@category Observable
+*/
+type OnNext<ValueType> = (value: ValueType) => void;
+
+/**
+@category Observable
+*/
+type OnError = (error: unknown) => void;
+
+/**
+@category Observable
+*/
+type OnComplete = () => void;
+
+/**
+@category Observable
+*/
+// eslint-disable-next-line type-fest/require-exported-types
+export type Observer<ValueType> = {
+	next: OnNext<ValueType>;
+	error: OnError;
+	complete: OnComplete;
+};
+
+/**
+Matches a value that is like an [Observable](https://github.com/tc39/proposal-observable).
+
+You must import it as a sub-import:
+
+@example
+```
+import type {ObservableLike} from 'type-fest/globals';
+```
+
+@remarks
+The TC39 Observable proposal defines 2 forms of `subscribe()`:
+1. Three callback arguments: `subscribe(observer: OnNext<ValueType>, onError?: OnError, onComplete?: OnComplete): Unsubscribable;`
+2. A single `observer` argument: (as defined below)
+
+But `Observable` implementations have evolved to preferring case 2 and some implementations choose not to implement case 1. Therefore, an `ObservableLike` cannot be trusted to implement the first case. (xstream and hand built observerables often do not implement case 1)
+
+@see https://github.com/tc39/proposal-observable#observable
+@see https://github.com/tc39/proposal-observable/blob/master/src/Observable.js#L246-L259
+@see https://benlesh.com/posts/learning-observable-by-building-observable/
+
+@category Observable
+*/
+// eslint-disable-next-line type-fest/require-exported-types
+export type ObservableLike<ValueType = unknown> = {
+	subscribe(observer?: Partial<Observer<ValueType>>): Unsubscribable;
+	[Symbol.observable](): ObservableLike<ValueType>;
+};
+
+export {};

package/source/greater-than-or-equal.d.ts

@@ -0,0 +1,30 @@
+import type {GreaterThan} from './greater-than.d.ts';
+
+/**
+Returns a boolean for whether a given number is greater than or equal to another number.
+
+@example
+```
+import type {GreaterThanOrEqual} from 'type-fest';
+
+type A = GreaterThanOrEqual<1, -5>;
+//=> true
+
+type B = GreaterThanOrEqual<1, 1>;
+//=> true
+
+type C = GreaterThanOrEqual<1, 5>;
+//=> false
+```
+*/
+export type GreaterThanOrEqual<A extends number, B extends number> = number extends A | B
+	? never
+	: A extends number // For distributing `A`
+		? B extends number // For distributing `B`
+			? A extends B
+				? true
+				: GreaterThan<A, B>
+			: never // Should never happen
+		: never; // Should never happen
+
+export {};

package/source/greater-than.d.ts

@@ -0,0 +1,58 @@
+import type {NumberAbsolute, PositiveNumericStringGt} from './internal/index.d.ts';
+import type {IsEqual} from './is-equal.d.ts';
+import type {PositiveInfinity, NegativeInfinity, IsNegative} from './numeric.d.ts';
+import type {And} from './and.d.ts';
+import type {Or} from './or.d.ts';
+
+/**
+Returns a boolean for whether a given number is greater than another number.
+
+@example
+```
+import type {GreaterThan} from 'type-fest';
+
+type A = GreaterThan<1, -5>;
+//=> true
+
+type B = GreaterThan<1, 1>;
+//=> false
+
+type C = GreaterThan<1, 5>;
+//=> false
+```
+*/
+export type GreaterThan<A extends number, B extends number> =
+	A extends number // For distributing `A`
+		? B extends number // For distributing `B`
+			? number extends A | B
+				? never
+				: [
+					IsEqual<A, PositiveInfinity>, IsEqual<A, NegativeInfinity>,
+					IsEqual<B, PositiveInfinity>, IsEqual<B, NegativeInfinity>,
+				] extends infer R extends [boolean, boolean, boolean, boolean]
+					? Or<
+						And<IsEqual<R[0], true>, IsEqual<R[2], false>>,
+						And<IsEqual<R[3], true>, IsEqual<R[1], false>>
+					> extends true
+						? true
+						: Or<
+							And<IsEqual<R[1], true>, IsEqual<R[3], false>>,
+							And<IsEqual<R[2], true>, IsEqual<R[0], false>>
+						> extends true
+							? false
+							: true extends R[number]
+								? false
+								: [IsNegative<A>, IsNegative<B>] extends infer R extends [boolean, boolean]
+									? [true, false] extends R
+										? false
+										: [false, true] extends R
+											? true
+											: [false, false] extends R
+												? PositiveNumericStringGt<`${A}`, `${B}`>
+												: PositiveNumericStringGt<`${NumberAbsolute<B>}`, `${NumberAbsolute<A>}`>
+									: never
+					: never
+			: never // Should never happen
+		: never; // Should never happen
+
+export {};

package/source/has-optional-keys.d.ts

@@ -0,0 +1,23 @@
+import type {OptionalKeysOf} from './optional-keys-of.d.ts';
+
+/**
+Creates a type that represents `true` or `false` depending on whether the given type has any optional fields.
+
+This is useful when you want to create an API whose behavior depends on the presence or absence of optional fields.
+
+@example
+```
+import type {HasOptionalKeys, OptionalKeysOf} from 'type-fest';
+
+type UpdateService<Entity extends object> = {
+	removeField: HasOptionalKeys<Entity> extends true
+		? (field: OptionalKeysOf<Entity>) => Promise<void>
+		: never;
+};
+```
+
+@category Utilities
+*/
+export type HasOptionalKeys<BaseType extends object> = OptionalKeysOf<BaseType> extends never ? false : true;
+
+export {};

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

@@ -0,0 +1,23 @@
+import type {ReadonlyKeysOf} from './readonly-keys-of.d.ts';
+
+/**
+Creates a type that represents `true` or `false` depending on whether the given type has any readonly fields.
+
+This is useful when you want to create an API whose behavior depends on the presence or absence of readonly fields.
+
+@example
+```
+import type {HasReadonlyKeys, ReadonlyKeysOf} from 'type-fest';
+
+type UpdateService<Entity extends object> = {
+	removeField: HasReadonlyKeys<Entity> extends true
+		? (field: ReadonlyKeysOf<Entity>) => Promise<void>
+		: never;
+};
+```
+
+@category Utilities
+*/
+export type HasReadonlyKeys<BaseType extends object> = ReadonlyKeysOf<BaseType> extends never ? false : true;
+
+export {};

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

@@ -0,0 +1,61 @@
+import type {RequiredKeysOf} from './required-keys-of.d.ts';
+
+/**
+Creates a type that represents `true` or `false` depending on whether the given type has any required fields.
+
+This is useful when you want to create an API whose behavior depends on the presence or absence of required fields.
+
+@example
+```
+import type {HasRequiredKeys} from 'type-fest';
+
+type GeneratorOptions<Template extends object> = {
+	prop1: number;
+	prop2: string;
+} & (HasRequiredKeys<Template> extends true
+	? {template: Template}
+	: {template?: Template});
+
+type Template1 = {
+	optionalSubParam?: string;
+};
+
+type Template2 = {
+	requiredSubParam: string;
+};
+
+type Options1 = GeneratorOptions<Template1>;
+type Options2 = GeneratorOptions<Template2>;
+
+const optA: Options1 = {
+	prop1: 0,
+	prop2: 'hi',
+};
+const optB: Options1 = {
+	prop1: 0,
+	prop2: 'hi',
+	template: {},
+};
+const optC: Options1 = {
+	prop1: 0,
+	prop2: 'hi',
+	template: {
+		optionalSubParam: 'optional value',
+	},
+};
+
+const optD: Options2 = {
+	prop1: 0,
+	prop2: 'hi',
+	template: {
+		requiredSubParam: 'required value',
+	},
+};
+
+```
+
+@category Utilities
+*/
+export type HasRequiredKeys<BaseType extends object> = RequiredKeysOf<BaseType> extends never ? false : true;
+
+export {};

package/source/has-writable-keys.d.ts

@@ -0,0 +1,23 @@
+import type {WritableKeysOf} from './writable-keys-of.d.ts';
+
+/**
+Creates a type that represents `true` or `false` depending on whether the given type has any writable fields.
+
+This is useful when you want to create an API whose behavior depends on the presence or absence of writable fields.
+
+@example
+```
+import type {HasWritableKeys, WritableKeysOf} from 'type-fest';
+
+type UpdateService<Entity extends object> = {
+	removeField: HasWritableKeys<Entity> extends true
+		? (field: WritableKeysOf<Entity>) => Promise<void>
+		: never;
+};
+```
+
+@category Utilities
+*/
+export type HasWritableKeys<BaseType extends object> = WritableKeysOf<BaseType> extends never ? false : true;
+
+export {};

package/source/if-any.d.ts

@@ -0,0 +1,28 @@
+import type {IsAny} from './is-any.d.ts';
+
+/**
+An if-else-like type that resolves depending on whether the given type is `any`.
+
+@deprecated This type will be removed in the next major version. Use the {@link If} type instead.
+
+@see {@link IsAny}
+
+@example
+```
+import type {IfAny} from 'type-fest';
+
+type ShouldBeTrue = IfAny<any>;
+//=> true
+
+type ShouldBeBar = IfAny<'not any', 'foo', 'bar'>;
+//=> 'bar'
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IfAny<T, TypeIfAny = true, TypeIfNotAny = false> = (
+	IsAny<T> extends true ? TypeIfAny : TypeIfNotAny
+);
+
+export {};

package/source/if-empty-object.d.ts

@@ -0,0 +1,30 @@
+import type {IsEmptyObject} from './empty-object.d.ts';
+
+/**
+An if-else-like type that resolves depending on whether the given type is `{}`.
+
+@deprecated This type will be removed in the next major version. Use the {@link If} type instead.
+
+@see {@link IsEmptyObject}
+
+@example
+```
+import type {IfEmptyObject} from 'type-fest';
+
+type ShouldBeTrue = IfEmptyObject<{}>;
+//=> true
+
+type ShouldBeBar = IfEmptyObject<{key: any}, 'foo', 'bar'>;
+//=> 'bar'
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IfEmptyObject<
+	T,
+	TypeIfEmptyObject = true,
+	TypeIfNotEmptyObject = false,
+> = IsEmptyObject<T> extends true ? TypeIfEmptyObject : TypeIfNotEmptyObject;
+
+export {};

package/source/if-never.d.ts

@@ -0,0 +1,28 @@
+import type {IsNever} from './is-never.d.ts';
+
+/**
+An if-else-like type that resolves depending on whether the given type is `never`.
+
+@deprecated This type will be removed in the next major version. Use the {@link If} type instead.
+
+@see {@link IsNever}
+
+@example
+```
+import type {IfNever} from 'type-fest';
+
+type ShouldBeTrue = IfNever<never>;
+//=> true
+
+type ShouldBeBar = IfNever<'not never', 'foo', 'bar'>;
+//=> 'bar'
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IfNever<T, TypeIfNever = true, TypeIfNotNever = false> = (
+	IsNever<T> extends true ? TypeIfNever : TypeIfNotNever
+);
+
+export {};

package/source/if-null.d.ts

@@ -0,0 +1,28 @@
+import type {IsNull} from './is-null.d.ts';
+
+/**
+An if-else-like type that resolves depending on whether the given type is `null`.
+
+@deprecated This type will be removed in the next major version. Use the {@link If} type instead.
+
+@see {@link IsNull}
+
+@example
+```
+import type {IfNull} from 'type-fest';
+
+type ShouldBeTrue = IfNull<null>;
+//=> true
+
+type ShouldBeBar = IfNull<'not null', 'foo', 'bar'>;
+//=> 'bar'
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IfNull<T, TypeIfNull = true, TypeIfNotNull = false> = (
+	IsNull<T> extends true ? TypeIfNull : TypeIfNotNull
+);
+
+export {};

package/source/if-unknown.d.ts

@@ -0,0 +1,28 @@
+import type {IsUnknown} from './is-unknown.d.ts';
+
+/**
+An if-else-like type that resolves depending on whether the given type is `unknown`.
+
+@deprecated This type will be removed in the next major version. Use the {@link If} type instead.
+
+@see {@link IsUnknown}
+
+@example
+```
+import type {IfUnknown} from 'type-fest';
+
+type ShouldBeTrue = IfUnknown<unknown>;
+//=> true
+
+type ShouldBeBar = IfUnknown<'not unknown', 'foo', 'bar'>;
+//=> 'bar'
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IfUnknown<T, TypeIfUnknown = true, TypeIfNotUnknown = false> = (
+	IsUnknown<T> extends true ? TypeIfUnknown : TypeIfNotUnknown
+);
+
+export {};

package/source/if.d.ts

@@ -0,0 +1,102 @@
+import type {IsNever} from './is-never.d.ts';
+
+/**
+An if-else-like type that resolves depending on whether the given `boolean` type is `true` or `false`.
+
+Use-cases:
+- You can use this in combination with `Is*` types to create an if-else-like experience. For example, `If<IsAny<any>, 'is any', 'not any'>`.
+
+Note:
+- Returns a union of if branch and else branch if the given type is `boolean` or `any`. For example, `If<boolean, 'Y', 'N'>` will return `'Y' | 'N'`.
+- Returns the else branch if the given type is `never`. For example, `If<never, 'Y', 'N'>` will return `'N'`.
+
+@example
+```
+import type {If} from 'type-fest';
+
+type A = If<true, 'yes', 'no'>;
+//=> 'yes'
+
+type B = If<false, 'yes', 'no'>;
+//=> 'no'
+
+type C = If<boolean, 'yes', 'no'>;
+//=> 'yes' | 'no'
+
+type D = If<any, 'yes', 'no'>;
+//=> 'yes' | 'no'
+
+type E = If<never, 'yes', 'no'>;
+//=> 'no'
+```
+
+@example
+```
+import type {If, IsAny, IsNever} from 'type-fest';
+
+type A = If<IsAny<unknown>, 'is any', 'not any'>;
+//=> 'not any'
+
+type B = If<IsNever<never>, 'is never', 'not never'>;
+//=> 'is never'
+```
+
+@example
+```
+import type {If, IsEqual} from 'type-fest';
+
+type IfEqual<T, U, IfBranch, ElseBranch> = If<IsEqual<T, U>, IfBranch, ElseBranch>;
+
+type A = IfEqual<string, string, 'equal', 'not equal'>;
+//=> 'equal'
+
+type B = IfEqual<string, number, 'equal', 'not equal'>;
+//=> 'not equal'
+```
+
+Note: Sometimes using the `If` type can make an implementation non–tail-recursive, which can impact performance. In such cases, it’s better to use a conditional directly. Refer to the following example:
+
+@example
+```
+import type {If, IsEqual, StringRepeat} from 'type-fest';
+
+type HundredZeroes = StringRepeat<'0', 100>;
+
+// The following implementation is not tail recursive
+type Includes<S extends string, Char extends string> =
+	S extends `${infer First}${infer Rest}`
+		? If<IsEqual<First, Char>,
+			'found',
+			Includes<Rest, Char>>
+		: 'not found';
+
+// Hence, instantiations with long strings will fail
+// @ts-expect-error
+type Fails = Includes<HundredZeroes, '1'>;
+//           ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// Error: Type instantiation is excessively deep and possibly infinite.
+
+// However, if we use a simple conditional instead of `If`, the implementation becomes tail-recursive
+type IncludesWithoutIf<S extends string, Char extends string> =
+	S extends `${infer First}${infer Rest}`
+		? IsEqual<First, Char> extends true
+			? 'found'
+			: IncludesWithoutIf<Rest, Char>
+		: 'not found';
+
+// Now, instantiations with long strings will work
+type Works = IncludesWithoutIf<HundredZeroes, '1'>;
+//=> 'not found'
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type If<Type extends boolean, IfBranch, ElseBranch> =
+	IsNever<Type> extends true
+		? ElseBranch
+		: Type extends true
+			? IfBranch
+			: ElseBranch;
+
+export {};

package/source/includes.d.ts

@@ -0,0 +1,24 @@
+import type {IsEqual} from './is-equal.d.ts';
+
+/**
+Returns a boolean for whether the given array includes the given item.
+
+This can be useful if another type wants to make a decision based on whether the array includes that item.
+
+@example
+```
+import type {Includes} from 'type-fest';
+
+type hasRed<array extends any[]> = Includes<array, 'red'>;
+```
+
+@category Array
+*/
+export type Includes<Value extends readonly any[], Item> =
+	Value extends readonly [Value[0], ...infer rest]
+		? IsEqual<Value[0], Item> extends true
+			? true
+			: Includes<rest, Item>
+		: false;
+
+export {};

package/source/int-closed-range.d.ts

@@ -0,0 +1,47 @@
+import type {IntRange} from './int-range.d.ts';
+import type {Sum} from './sum.d.ts';
+
+/**
+Generate a union of numbers.
+
+The numbers are created from the given `Start` (inclusive) parameter to the given `End` (inclusive) parameter.
+
+You skip over numbers using the `Step` parameter (defaults to `1`). For example, `IntClosedRange<0, 10, 2>` will create a union of `0 | 2 | 4 | 6 | 8 | 10`.
+
+Note: `Start` or `End` must be non-negative and smaller than `999`.
+
+Use-cases:
+1. This can be used to define a set of valid input/output values. for example:
+
+@example
+```
+import type {IntClosedRange} from 'type-fest';
+
+type Age = IntClosedRange<0, 20>;
+//=> 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20
+
+type FontSize = IntClosedRange<10, 20>;
+//=> 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20
+
+type EvenNumber = IntClosedRange<0, 10, 2>;
+//=> 0 | 2 | 4 | 6 | 8 | 10
+```
+
+2. This can be used to define random numbers in a range. For example, `type RandomNumber = IntClosedRange<0, 100>;`
+
+@example
+```
+import type {IntClosedRange} from 'type-fest';
+
+type ZeroToNine = IntClosedRange<0, 9>;
+//=> 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
+
+type Hundreds = IntClosedRange<100, 900, 100>;
+//=> 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900
+```
+
+@see {@link IntRange}
+*/
+export type IntClosedRange<Start extends number, End extends number, Skip extends number = 1> = IntRange<Start, Sum<End, 1>, Skip>;
+
+export {};