type-fest 2.6.0 → 2.10.0

package/source/kebab-cased-properties-deep.d.ts

@@ -38,6 +38,8 @@ const result: KebabCasedPropertiesDeep<UserWithFriends> = {
 };
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
+@category Object
 */
 export type KebabCasedPropertiesDeep<Value> = DelimiterCasedPropertiesDeep<Value, '-'>;

package/source/kebab-cased-properties.d.ts

@@ -21,6 +21,8 @@ const result: KebabCasedProperties<User> = {
 };
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
+@category Object
 */
 export type KebabCasedProperties<Value> = DelimiterCasedProperties<Value, '-'>;

package/source/last-array-element.d.ts

@@ -15,7 +15,8 @@ typeof lastOf(array);
 //=> number
 ```
 
-@category Template Literals
+@category Array
+@category Template literal
 */
 export type LastArrayElement<ValueType extends readonly unknown[]> =
 	ValueType extends readonly [infer ElementType]

package/source/literal-to-primitive.d.ts

@@ -0,0 +1,36 @@
+/**
+Given a [literal type](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#literal-types) return the {@link Primitive | primitive type} it belongs to, or `never` if it's not a primitive.
+
+Use-case: Working with generic types that may be literal types.
+
+@example
+```
+import {LiteralToPrimitive} from 'type-fest';
+
+// No overloads needed to get the correct return type
+function plus<T extends number | bigint | string>(x: T, y: T): LiteralToPrimitive<T> {
+	return x + (y as any);
+}
+
+plus('a', 'b'); // string
+plus(1, 2); // number
+plus(1n, 2n); // bigint
+```
+
+@category Type
+*/
+export type LiteralToPrimitive<T> = T extends number
+	? number
+	: T extends bigint
+	? bigint
+	: T extends string
+	? string
+	: T extends boolean
+	? boolean
+	: T extends symbol
+	? symbol
+	: T extends null
+	? null
+	: T extends undefined
+	? undefined
+	: never;

package/source/literal-union.d.ts

@@ -27,9 +27,9 @@ const pet: Pet2 = '';
 // You **will** get auto-completion for `dog` and `cat` literals.
 ```
 
-@category Utilities
- */
+@category Type
+*/
 export type LiteralUnion<
 	LiteralType,
 	BaseType extends Primitive,
-> = LiteralType | (BaseType & {_?: never});
+> = LiteralType | (BaseType & Record<never, never>);

package/source/merge-exclusive.d.ts

@@ -32,7 +32,7 @@ exclusiveOptions = {exclusive1: true, exclusive2: 'hi'};
 //=> Error
 ```
 
-@category Utilities
+@category Object
 */
 export type MergeExclusive<FirstType, SecondType> =
 	(FirstType | SecondType) extends object ?

package/source/merge.d.ts

@@ -22,6 +22,6 @@ type Bar = {
 const ab: Merge<Foo, Bar> = {a: 1, b: 2};
 ```
 
-@category Utilities
+@category Object
 */
 export type Merge<FirstType, SecondType> = Simplify<Merge_<FirstType, SecondType>>;

package/source/multidimensional-array.d.ts

@@ -34,7 +34,7 @@ const matrix = emptyMatrix(3);
 matrix[0][0][0] = 42;
 ```
 
-@category Utilities
+@category Array
 */
 export type MultidimensionalArray<Element, Dimensions extends number> = number extends Dimensions
 	? Recursive<Element>

package/source/multidimensional-readonly-array.d.ts

@@ -38,7 +38,7 @@ const matrix = emptyMatrix(3);
 const answer = matrix[0][0][0]; // 42
 ```
 
-@category Utilities
+@category Array
 */
 export type MultidimensionalReadonlyArray<Element, Dimensions extends number> = number extends Dimensions
 	? Recursive<Element>

package/source/mutable.d.ts

@@ -29,7 +29,7 @@ type SomeMutable = Mutable<Foo, 'b' | 'c'>;
 // }
 ```
 
-@category Utilities
+@category Object
 */
 export type Mutable<BaseType, Keys extends keyof BaseType = keyof BaseType> =
 	Simplify<

package/source/numeric.d.ts

@@ -0,0 +1,168 @@
+type Numeric = number | bigint;
+
+type Zero = 0 | 0n;
+
+/**
+Matches the hidden `Infinity` type.
+
+Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/32277) if you want to have this type as a built-in in TypeScript.
+
+@see NegativeInfinity
+
+@category Numeric
+*/
+// See https://github.com/microsoft/TypeScript/issues/31752
+// eslint-disable-next-line @typescript-eslint/no-loss-of-precision
+export type PositiveInfinity = 1e999;
+
+/**
+Matches the hidden `-Infinity` type.
+
+Please upvote [this issue](https://github.com/microsoft/TypeScript/issues/32277) if you want to have this type as a built-in in TypeScript.
+
+@see PositiveInfinity
+
+@category Numeric
+*/
+// See https://github.com/microsoft/TypeScript/issues/31752
+// eslint-disable-next-line @typescript-eslint/no-loss-of-precision
+export type NegativeInfinity = -1e999;
+
+/**
+A finite `number`.
+You can't pass a `bigint` as they are already guaranteed to be finite.
+
+Use-case: Validating and documenting parameters.
+
+@example
+```
+import {Finite} from 'type-fest';
+
+declare function setScore<T extends number>(length: Finite<T>): void;
+```
+
+@category Numeric
+*/
+export type Finite<T extends number> = T extends PositiveInfinity | NegativeInfinity ? never : T;
+
+/**
+A `number` that is an integer.
+You can't pass a `bigint` as they are already guaranteed to be integers.
+
+Use-case: Validating and documenting parameters.
+
+@example
+```
+import {Integer} from 'type-fest';
+
+declare function setYear<T extends number>(length: Integer<T>): void;
+```
+
+@see NegativeInteger
+@see NonNegativeInteger
+
+@category Numeric
+*/
+// `${bigint}` is a type that matches a valid bigint literal without the `n` (ex. 1, 0b1, 0o1, 0x1)
+// Because T is a number and not a string we can effectively use this to filter out any numbers containing decimal points
+export type Integer<T extends number> = `${T}` extends `${bigint}` ? T : never;
+
+/**
+A `number` that is not an integer.
+You can't pass a `bigint` as they are already guaranteed to be integers.
+
+Use-case: Validating and documenting parameters.
+
+@example
+```
+import {Float} from 'type-fest';
+
+declare function setPercentage<T extends number>(length: Float<T>): void;
+```
+
+@see Integer
+
+@category Numeric
+*/
+export type Float<T extends number> = T extends Integer<T> ? never : T;
+
+/**
+A negative (`-∞ < x < 0`) `number` that is not an integer.
+Equivalent to `Negative<Float<T>>`.
+
+Use-case: Validating and documenting parameters.
+
+@see Negative
+@see Float
+
+@category Numeric
+*/
+export type NegativeFloat<T extends number> = Negative<Float<T>>;
+
+/**
+A negative `number`/`bigint` (`-∞ < x < 0`)
+
+Use-case: Validating and documenting parameters.
+
+@see NegativeInteger
+@see NonNegative
+
+@category Numeric
+*/
+export type Negative<T extends Numeric> = T extends Zero ? never : `${T}` extends `-${string}` ? T : never;
+
+/**
+A negative (`-∞ < x < 0`) `number` that is an integer.
+Equivalent to `Negative<Integer<T>>`.
+
+You can't pass a `bigint` as they are already guaranteed to be integers, instead use `Negative<T>`.
+
+Use-case: Validating and documenting parameters.
+
+@see Negative
+@see Integer
+
+@category Numeric
+*/
+export type NegativeInteger<T extends number> = Negative<Integer<T>>;
+
+/**
+A non-negative `number`/`bigint` (`0 <= x < ∞`).
+
+Use-case: Validating and documenting parameters.
+
+@see NonNegativeInteger
+@see Negative
+
+@example
+```
+import {NonNegative} from 'type-fest';
+
+declare function setLength<T extends number>(length: NonNegative<T>): void;
+```
+
+@category Numeric
+*/
+export type NonNegative<T extends Numeric> = T extends Zero ? T : Negative<T> extends never ? T : never;
+
+/**
+A non-negative (`0 <= x < ∞`) `number` that is an integer.
+Equivalent to `NonNegative<Integer<T>>`.
+
+You can't pass a `bigint` as they are already guaranteed to be integers, instead use `NonNegative<T>`.
+
+Use-case: Validating and documenting parameters.
+
+@see NonNegative
+@see Integer
+
+@example
+```
+import {NonNegativeInteger} from 'type-fest';
+
+declare function setLength<T extends number>(length: NonNegativeInteger<T>): void;
+```
+
+@category Numeric
+*/
+export type NonNegativeInteger<T extends number> = NonNegative<Integer<T>>;

package/source/observable-like.d.ts

@@ -11,15 +11,29 @@ As well, some guideance on making an `Observable` do not include `closed` proper
 @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
 */
 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
+*/
 export type Observer<ValueType> = {
 	next: OnNext<ValueType>;
 	error: OnError;
@@ -40,7 +54,7 @@ But `Observable` implementations have evolved to preferring case 2 and some impl
 @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 Basic
+@category Observable
 */
 export interface ObservableLike<ValueType = unknown> {
 	subscribe(observer?: Partial<Observer<ValueType>>): Unsubscribable;

package/source/opaque.d.ts

@@ -69,6 +69,6 @@ type Person = {
 };
 ```
 
-@category Utilities
+@category Type
 */
 export type Opaque<Type, Token = unknown> = Type & Tagged<Token>;

package/source/package-json.d.ts

@@ -635,7 +635,7 @@ declare namespace PackageJson {
 /**
 Type for [npm's `package.json` file](https://docs.npmjs.com/creating-a-package-json-file). Also includes types for fields used by other popular projects, like TypeScript and Yarn.
 
-@category Miscellaneous
+@category File
 */
 export type PackageJson =
 PackageJson.PackageJsonStandard &

package/source/partial-deep.d.ts

@@ -1,4 +1,4 @@
-import {Primitive} from './primitive';
+import {BuiltIns} from './internal';
 
 /**
 Create a type from another type with all keys and nested keys set to optional.
@@ -28,10 +28,13 @@ const applySavedSettings = (savedSettings: PartialDeep<Settings>) => {
 settings = applySavedSettings({textEditor: {fontWeight: 500}});
 ```
 
-@category Utilities
+@category Object
+@category Array
+@category Set
+@category Map
 */
-export type PartialDeep<T> = T extends Primitive
-	? Partial<T>
+export type PartialDeep<T> = T extends BuiltIns
+	? T
 	: T extends Map<infer KeyType, infer ValueType>
 	? PartialMapDeep<KeyType, ValueType>
 	: T extends Set<infer ItemType>

package/source/pascal-case.d.ts

@@ -30,7 +30,8 @@ const dbResult: CamelCasedProperties<ModelProps> = {
 };
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
 */
 export type PascalCase<Value> = CamelCase<Value> extends string
 	? Capitalize<CamelCase<Value>>

package/source/pascal-cased-properties-deep.d.ts

@@ -38,9 +38,11 @@ const result: PascalCasedPropertiesDeep<UserWithFriends> = {
 };
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
+@category Object
 */
-export type PascalCasedPropertiesDeep<Value> = Value extends Function
+export type PascalCasedPropertiesDeep<Value> = Value extends Function | Date | RegExp
 	? Value
 	: Value extends Array<infer U>
 	? Array<PascalCasedPropertiesDeep<U>>

package/source/pascal-cased-properties.d.ts

@@ -21,7 +21,9 @@ const result: PascalCasedProperties<User> = {
 };
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
+@category Object
 */
 export type PascalCasedProperties<Value> = Value extends Function
 	? Value

package/source/primitive.d.ts

@@ -1,7 +1,7 @@
 /**
 Matches any [primitive value](https://developer.mozilla.org/en-US/docs/Glossary/Primitive).
 
-@category Basic
+@category Type
 */
 export type Primitive =
 	| null

package/source/promisable.d.ts

@@ -18,8 +18,8 @@ async function logger(getLogEntry: () => Promisable<string>): Promise<void> {
 
 logger(() => 'foo');
 logger(() => Promise.resolve('bar'));
-
-@category Utilities
 ```
+
+@category Async
 */
 export type Promisable<T> = T | PromiseLike<T>;

package/source/promise-value.d.ts

@@ -24,6 +24,6 @@ type RecursiveAsyncData = Promise<Promise<string> >;
 let recursiveAsyncData: PromiseValue<RecursiveAsyncData> = Promise.resolve(Promise.resolve('ABC'));
 ```
 
-@category Utilities
+@category Async
 */
 export type PromiseValue<PromiseType> = PromiseType extends PromiseLike<infer Value> ? PromiseValue<Value> : PromiseType;

package/source/readonly-deep.d.ts

@@ -1,4 +1,4 @@
-import {Primitive} from './primitive';
+import {BuiltIns} from './internal';
 
 /**
 Convert `object`s, `Map`s, `Set`s, and `Array`s and all of their keys/elements into immutable structures recursively.
@@ -29,9 +29,12 @@ data.foo.push('bar');
 //=> error TS2339: Property 'push' does not exist on type 'readonly string[]'
 ```
 
-@category Utilities
+@category Object
+@category Array
+@category Set
+@category Map
 */
-export type ReadonlyDeep<T> = T extends Primitive | ((...arguments: any[]) => unknown)
+export type ReadonlyDeep<T> = T extends BuiltIns | ((...arguments: any[]) => unknown)
 	? T
 	: T extends ReadonlyMap<infer KeyType, infer ValueType>
 	? ReadonlyMapDeep<KeyType, ValueType>

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

@@ -0,0 +1,98 @@
+/**
+Remove any index signatures from the given object type, so that only explicitly defined properties remain.
+
+Use-cases:
+- Remove overly permissive signatures from third-party types.
+
+This type was taken from this [StackOverflow answer](https://stackoverflow.com/a/68261113/420747).
+
+It relies on the fact that an empty object (`{}`) is assignable to an object with just an index signature, like `Record<string, unknown>`, but not to an object with explicitly defined keys, like `Record<'foo' | 'bar', unknown>`.
+
+(The actual value type, `unknown`, is irrelevant and could be any type. Only the key type matters.)
+
+```
+const indexed: Record<string, unknown> = {}; // Allowed
+
+const keyed: Record<'foo', unknown> = {}; // Error
+// => TS2739: Type '{}' is missing the following properties from type 'Record<"foo" | "bar", unknown>': foo, bar
+```
+
+Instead of causing a type error like the above, you can also use a [conditional type](https://www.typescriptlang.org/docs/handbook/2/conditional-types.html) to test whether a type is assignable to another:
+
+```
+type Indexed = {} extends Record<string, unknown>
+	? '✅ `{}` is assignable to `Record<string, unknown>`'
+	: '❌ `{}` is NOT assignable to `Record<string, unknown>`';
+// => '✅ `{}` is assignable to `Record<string, unknown>`'
+
+type Keyed = {} extends Record<'foo' | 'bar', unknown>
+	? "✅ `{}` is assignable to `Record<'foo' | 'bar', unknown>`"
+	: "❌ `{}` is NOT assignable to `Record<'foo' | 'bar', unknown>`";
+// => "❌ `{}` is NOT assignable to `Record<'foo' | 'bar', unknown>`"
+```
+
+Using a [mapped type](https://www.typescriptlang.org/docs/handbook/2/mapped-types.html#further-exploration), you can then check for each `KeyType` of `ObjectType`...
+
+```
+type RemoveIndexSignature<ObjectType> = {
+	[KeyType in keyof ObjectType // Map each key of `ObjectType`...
+  ]: ObjectType[KeyType]; // ...to its original value, i.e. `RemoveIndexSignature<Foo> == Foo`.
+};
+```
+
+...whether an empty object (`{}`) would be assignable to an object with that `KeyType` (`Record<KeyType, unknown>`)...
+
+```
+type RemoveIndexSignature<ObjectType> = {
+	[KeyType in keyof ObjectType
+		// Is `{}` assignable to `Record<KeyType, unknown>`?
+		as {} extends Record<KeyType, unknown>
+			? ... // ✅ `{}` is assignable to `Record<KeyType, unknown>`
+			: ... // ❌ `{}` is NOT assignable to `Record<KeyType, unknown>`
+	]: ObjectType[KeyType];
+};
+```
+
+If `{}` is assignable, it means that `KeyType` is an index signature and we want to remove it. If it is not assignable, `KeyType` is a "real" key and we want to keep it.
+
+```
+type RemoveIndexSignature<ObjectType> = {
+	[KeyType in keyof ObjectType
+		as {} extends Record<KeyType, unknown>
+			? never // => Remove this `KeyType`.
+			: KeyType // => Keep this `KeyType` as it is.
+	]: ObjectType[KeyType];
+};
+```
+
+@example
+```
+import {RemoveIndexSignature} from 'type-fest';
+
+interface Example {
+	// These index signatures will be removed.
+	[x: string]: any
+	[x: number]: any
+	[x: symbol]: any
+	[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 remain.
+	foo: 'bar';
+	qux?: 'baz';
+}
+
+type ExampleWithoutIndexSignatures = RemoveIndexSignature<Example>;
+// => { foo: 'bar'; qux?: 'baz' | undefined; }
+```
+
+@category Object
+*/
+export type RemoveIndexSignature<ObjectType> = {
+	[KeyType in keyof ObjectType as {} extends Record<KeyType, unknown>
+		? never
+		: KeyType]: ObjectType[KeyType];
+};

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

@@ -27,7 +27,7 @@ const responder2: RequireAllOrNone<Responder, 'text' | 'json'> = {
 };
 ```
 
-@category Utilities
+@category Object
 */
 export type RequireAllOrNone<ObjectType, KeysType extends keyof ObjectType = never> = (
 	| Required<Pick<ObjectType, KeysType>> // Require all of the given keys.

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

@@ -20,7 +20,7 @@ const responder: RequireAtLeastOne<Responder, 'text' | 'json'> = {
 };
 ```
 
-@category Utilities
+@category Object
 */
 export type RequireAtLeastOne<
 	ObjectType,

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

@@ -25,7 +25,7 @@ const responder: RequireExactlyOne<Responder, 'text' | 'json'> = {
 };
 ```
 
-@category Utilities
+@category Object
 */
 export type RequireExactlyOne<ObjectType, KeysType extends keyof ObjectType = keyof ObjectType> =
 	{[Key in KeysType]: (

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

@@ -23,7 +23,8 @@ import {ScreamingSnakeCase} from 'type-fest';
 const someVariable: ScreamingSnakeCase<'fooBar'> = 'FOO_BAR';
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
 */
 export type ScreamingSnakeCase<Value> = Value extends string
 	? IsScreamingSnakeCase<Value> extends true

package/source/set-optional.d.ts

@@ -24,7 +24,7 @@ type SomeOptional = SetOptional<Foo, 'b' | 'c'>;
 // }
 ```
 
-@category Utilities
+@category Object
 */
 export type SetOptional<BaseType, Keys extends keyof BaseType> =
 	Simplify<

package/source/set-required.d.ts

@@ -24,7 +24,7 @@ type SomeRequired = SetRequired<Foo, 'b' | 'c'>;
 // }
 ```
 
-@category Utilities
+@category Object
 */
 export type SetRequired<BaseType, Keys extends keyof BaseType> =
 	Simplify<

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

@@ -17,7 +17,7 @@ type MyWrappedFunction = SetReturnType<MyFunctionThatCanThrow, SomeOtherType | u
 //=> type MyWrappedFunction = (foo: SomeType, bar: unknown) => SomeOtherType | undefined;
 ```
 
-@category Utilities
+@category Function
 */
 export type SetReturnType<Fn extends (...args: any[]) => any, TypeToReturn> =
 	// Just using `Parameters<Fn>` isn't ideal because it doesn't handle the `this` fake parameter.

package/source/simplify.d.ts

@@ -53,6 +53,6 @@ fn(someInterface as Simplify<SomeInterface>); // Good: transform an `interface`
 
 @link https://github.com/microsoft/TypeScript/issues/15300
 
-@category Utilities
+@category Object
 */
 export type Simplify<T> = {[KeyType in keyof T]: T[KeyType]};

package/source/snake-case.d.ts

@@ -32,6 +32,7 @@ const dbResult: SnakeCasedProperties<ModelProps> = {
 };
 ```
 
-@category Template Literals
+@category Change case
+@category Template literal
 */
 export type SnakeCase<Value> = DelimiterCase<Value, '_'>;