type-fest 2.14.0 → 2.16.0

package/index.d.ts

@@ -38,7 +38,7 @@ export {Entry} from './source/entry';
 export {Entries} from './source/entries';
 export {SetReturnType} from './source/set-return-type';
 export {Asyncify} from './source/asyncify';
-export {Simplify} from './source/simplify';
+export {Simplify, SimplifyOptions} from './source/simplify';
 export {Jsonify} from './source/jsonify';
 export {Schema} from './source/schema';
 export {LiteralToPrimitive} from './source/literal-to-primitive';
@@ -57,6 +57,10 @@ export {
 export {StringKeyOf} from './source/string-key-of';
 export {Exact} from './source/exact';
 export {ReadonlyTuple} from './source/readonly-tuple';
+export {OptionalKeysOf} from './source/optional-keys-of';
+export {HasOptionalKeys} from './source/has-optional-keys';
+export {RequiredKeysOf} from './source/required-keys-of';
+export {HasRequiredKeys} from './source/has-required-keys';
 
 // Template literal types
 export {CamelCase} from './source/camel-case';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "type-fest",
-	"version": "2.14.0",
+	"version": "2.16.0",
 	"description": "A collection of essential TypeScript types",
 	"license": "(MIT OR CC0-1.0)",
 	"repository": "sindresorhus/type-fest",

package/readme.md

@@ -192,6 +192,10 @@ Click the type names for complete docs.
 - [`StringKeyOf`](source/string-key-of.d.ts) - Get keys of the given type as strings.
 - [`Schema`](source/schema.d.ts) - Create a deep version of another object type where property values are recursively replaced into a given value type.
 - [`Exact`](source/exact.d.ts) - Create a type that does not allow extra properties.
+- [`OptionalKeysOf`](source/optional-keys-of.d.ts) - Extract all optional keys from the given type.
+- [`HasOptionalKeys`](source/has-optional-keys.d.ts) - Create a `true`/`false` type depending on whether the given type has any optional fields.
+- [`RequiredKeysOf`](source/required-keys-of.d.ts) - Extract all required keys from the given type.
+- [`HasRequiredKeys`](source/has-required-keys.d.ts) - Create a `true`/`false` type depending on whether the given type has any required fields.
 
 ### JSON
 

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

@@ -0,0 +1,21 @@
+import {OptionalKeysOf} from './optional-keys-of';
+
+/**
+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;

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

@@ -0,0 +1,59 @@
+import {RequiredKeysOf} from './required-keys-of';
+
+/**
+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});
+
+interface Template1 {
+	optionalSubParam?: string;
+}
+
+interface 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;

package/source/includes.d.ts

@@ -15,8 +15,8 @@ type hasRed<array extends any[]> = Includes<array, 'red'>;
 @category Array
 */
 export type Includes<Value extends readonly any[], Item> =
-	IsEqual<Value[0], Item> extends true
-		? true
-		: Value extends [Value[0], ...infer rest]
-			? Includes<rest, Item>
-			: false;
+	Value extends readonly [Value[0], ...infer rest]
+		? IsEqual<Value[0], Item> extends true
+			? true
+			: Includes<rest, Item>
+		: false;

package/source/jsonify.d.ts

@@ -1,14 +1,9 @@
 import type {JsonPrimitive, JsonValue} from './basic';
+import {Finite, NegativeInfinity, PositiveInfinity} from './numeric';
+import {TypedArray} from './typed-array';
 
 // Note: The return value has to be `any` and not `unknown` so it can match `void`.
-type NotJsonable = ((...args: any[]) => any) | undefined;
-
-// Note: Handles special case where Arrays with `undefined` are transformed to `'null'` by `JSON.stringify()`
-// Only use with array members
-type JsonifyArrayMember<T> =
-	T extends undefined ?
-		null | Exclude<T, undefined> :
-		Jsonify<T>;
+type NotJsonable = ((...args: any[]) => any) | undefined | symbol;
 
 /**
 Transform a type to one that is assignable to the `JsonValue` type.
@@ -71,16 +66,26 @@ type Jsonify<T> =
 	// Check if there are any non-JSONable types represented in the union.
 	// Note: The use of tuples in this first condition side-steps distributive conditional types
 	// (see https://github.com/microsoft/TypeScript/issues/29368#issuecomment-453529532)
-	[Extract<T, NotJsonable>] extends [never]
-		? T extends JsonPrimitive
+	[Extract<T, NotJsonable | bigint>] extends [never]
+		? T extends PositiveInfinity | NegativeInfinity ? null
+		: T extends JsonPrimitive
 			? T // Primitive is acceptable
+			: T extends Number ? number
+			: T extends String ? string
+			: T extends Boolean ? boolean
+			: T extends Map<any, any> | Set<any> ? {}
+			: T extends TypedArray ? Record<string, number>
 			: T extends Array<infer U>
-				? Array<JsonifyArrayMember<U>> // It's an array: recursive call for its children
+				? Array<Jsonify<U extends NotJsonable ? null : U>> // It's an array: recursive call for its children
 				: T extends object
 					? T extends {toJSON(): infer J}
 						? (() => J) extends (() => JsonValue) // Is J assignable to JsonValue?
 							? J // Then T is Jsonable and its Jsonable value is J
 							: never // Not Jsonable because its toJSON() method does not return JsonValue
-						: {[P in keyof T]: Jsonify<Required<T>[P]>} // It's an object: recursive call for its children
+						: {[P in keyof T as P extends symbol
+							? never
+							: T[P] extends NotJsonable
+							? never
+							: P]: Jsonify<Required<T>[P]>} // It's an object: recursive call for its children
 					: never // Otherwise any other non-object is removed
 		: never; // Otherwise non-JSONable type union was found not empty

package/source/numeric.d.ts

@@ -34,6 +34,8 @@ You can't pass a `bigint` as they are already guaranteed to be finite.
 
 Use-case: Validating and documenting parameters.
 
+Note: This can't detect `NaN`, please upvote [this issue](https://github.com/microsoft/TypeScript/issues/28682) if you want to have this type as a built-in in TypeScript.
+
 @example
 ```
 import type {Finite} from 'type-fest';

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

@@ -0,0 +1,38 @@
+/**
+Extract all optional keys from the given type.
+
+This is useful when you want to create a new type that contains different type values for the optional keys only.
+
+@example
+```
+import type {OptionalKeysOf, Except} from 'type-fest';
+
+interface User {
+	name: string;
+	surname: string;
+
+	luckyNumber?: number;
+}
+
+const REMOVE_FIELD = Symbol('remove field symbol');
+type UpdateOperation<Entity extends object> = Except<Partial<Entity>, OptionalKeysOf<Entity>> & {
+	[Key in OptionalKeysOf<Entity>]?: Entity[Key] | typeof REMOVE_FIELD;
+};
+
+const update1: UpdateOperation<User> = {
+	name: 'Alice'
+};
+
+const update2: UpdateOperation<User> = {
+	name: 'Bob',
+	luckyNumber: REMOVE_FIELD
+};
+```
+
+@category Utilities
+*/
+export type OptionalKeysOf<BaseType extends object> = Exclude<{
+	[Key in keyof BaseType]: BaseType extends Record<Key, BaseType[Key]>
+		? never
+		: Key
+}[keyof BaseType], undefined>;

package/source/replace.d.ts

@@ -62,6 +62,6 @@ export type Replace<
 	Options extends ReplaceOptions = {},
 > = Input extends `${infer Head}${Search}${infer Tail}`
 	? Options['all'] extends true
-		? Replace<`${Head}${Replacement}${Tail}`, Search, Replacement, Options>
+		? `${Head}${Replacement}${Replace<Tail, Search, Replacement, Options>}`
 		: `${Head}${Replacement}${Tail}`
 	: Input;

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

@@ -0,0 +1,29 @@
+/**
+Extract all required keys from the given type.
+
+This is useful when you want to create a new type that contains different type values for the required keys only or use the list of keys for validation purposes, etc...
+
+@example
+```
+import type {RequiredKeysOf} from 'type-fest';
+
+declare function createValidation<Entity extends object, Key extends RequiredKeysOf<Entity> = RequiredKeysOf<Entity>>(field: Key, validator: (value: Entity[Key]) => boolean): ValidatorFn;
+
+interface User {
+	name: string;
+	surname: string;
+
+	luckyNumber?: number;
+}
+
+const validator1 = createValidation<User>('name', value => value.length < 25);
+const validator2 = createValidation<User>('surname', value => value.length < 25);
+```
+
+@category Utilities
+*/
+export type RequiredKeysOf<BaseType extends object> = Exclude<{
+	[Key in keyof BaseType]: BaseType extends Record<Key, BaseType[Key]>
+		? Key
+		: never
+}[keyof BaseType], undefined>;

package/source/simplify.d.ts

@@ -1,3 +1,23 @@
+/**
+@see Simplify
+*/
+export interface SimplifyOptions {
+	/**
+	Do the simplification recursively.
+
+	@default false
+	*/
+	deep?: boolean;
+}
+
+// Flatten a type without worrying about the result.
+type Flatten<
+	AnyType,
+	Options extends SimplifyOptions = {},
+> = Options['deep'] extends true
+	? {[KeyType in keyof AnyType]: Simplify<AnyType[KeyType], Options>}
+	: {[KeyType in keyof AnyType]: AnyType[KeyType]};
+
 /**
 Useful to flatten the type output to improve type hints shown in editors. And also to transform an interface into a type to aide with assignability.
 
@@ -55,4 +75,9 @@ fn(someInterface as Simplify<SomeInterface>); // Good: transform an `interface`
 
 @category Object
 */
-export type Simplify<T> = {[KeyType in keyof T]: T[KeyType]};
+export type Simplify<
+	AnyType,
+	Options extends SimplifyOptions = {},
+> = Flatten<AnyType> extends AnyType
+	? Flatten<AnyType, Options>
+	: AnyType;