Add IsOptionalKeyOf, IsReadonlyKeyOf, IsRequiredKeyOf, and IsWritableKeyOf types (#1189)

Author: benzaria

index.d.ts

@@ -97,14 +97,18 @@ export type {Subtract} from './source/subtract.d.ts';
 export type {KeyAsString} from './source/key-as-string.d.ts';
 export type {Exact} from './source/exact.d.ts';
 export type {ReadonlyTuple} from './source/readonly-tuple.d.ts';
-export type {OptionalKeysOf} from './source/optional-keys-of.d.ts';
 export type {OverrideProperties} from './source/override-properties.d.ts';
+export type {OptionalKeysOf} from './source/optional-keys-of.d.ts';
+export type {IsOptionalKeyOf} from './source/is-optional-key-of.d.ts';
 export type {HasOptionalKeys} from './source/has-optional-keys.d.ts';
 export type {RequiredKeysOf} from './source/required-keys-of.d.ts';
+export type {IsRequiredKeyOf} from './source/is-required-key-of.d.ts';
 export type {HasRequiredKeys} from './source/has-required-keys.d.ts';
 export type {ReadonlyKeysOf} from './source/readonly-keys-of.d.ts';
+export type {IsReadonlyKeyOf} from './source/is-readonly-key-of.d.ts';
 export type {HasReadonlyKeys} from './source/has-readonly-keys.d.ts';
 export type {WritableKeysOf} from './source/writable-keys-of.d.ts';
+export type {IsWritableKeyOf} from './source/is-writable-key-of.d.ts';
 export type {HasWritableKeys} from './source/has-writable-keys.d.ts';
 export type {Spread} from './source/spread.d.ts';
 export type {IsInteger} from './source/is-integer.d.ts';

readme.md

@@ -151,8 +151,8 @@ Click the type names for complete docs.
 - [`KeyAsString`](source/key-as-string.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.
 - [`KeysOfUnion`](source/keys-of-union.d.ts) - Create a union of all keys from a given type, even those exclusive to specific union members.
+- [`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.
@@ -205,6 +205,10 @@ Click the type names for complete docs.
 - [`IsUppercase`](source/is-uppercase.d.ts) - Returns a boolean for whether the given string literal is uppercase.
 - [`IsOptional`](source/is-optional.d.ts) - Returns a boolean for whether the given type includes `undefined`.
 - [`IsNullable`](source/is-nullable.d.ts) - Returns a boolean for whether the given type includes `null`.
+- [`IsOptionalKeyOf`](source/is-optional-key-of.d.ts) - Returns a boolean for whether the given key is an optional key of type.
+- [`IsRequiredKeyOf`](source/is-required-key-of.d.ts) - Returns a boolean for whether the given key is a required key of type.
+- [`IsReadonlyKeyOf`](source/is-readonly-key-of.d.ts) - Returns a boolean for whether the given key is a readonly key of type.
+- [`IsWritableKeyOf`](source/is-writable-key-of.d.ts) - Returns a boolean for whether the given key is a writable key of type.
 
 ### JSON
 

source/is-optional-key-of.d.ts

@@ -0,0 +1,49 @@
+import type {IsAny} from './is-any.d.ts';
+
+/**
+Returns a boolean for whether the given key is an optional key of type.
+
+This is useful when writing utility types or schema validators that need to differentiate `optional` keys.
+
+@example
+```
+import type {IsOptionalKeyOf} from 'type-fest';
+
+interface User {
+	name: string;
+	surname: string;
+
+	luckyNumber?: number;
+}
+
+interface Admin {
+	name: string;
+	surname?: string
+}
+
+type T1 = IsOptionalKeyOf<User, 'luckyNumber'>;
+//=> true
+
+type T2 = IsOptionalKeyOf<User, 'name'>;
+//=> false
+
+type T3 = IsOptionalKeyOf<User, 'name' | 'luckyNumber'>;
+//=> boolean
+
+type T4 = IsOptionalKeyOf<User | Admin, 'name'>;
+//=> false
+
+type T5 = IsOptionalKeyOf<User | Admin, 'surname'>;
+//=> boolean
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsOptionalKeyOf<Type extends object, Key extends keyof Type> =
+	IsAny<Type | Key> extends true ? never
+		: Key extends keyof Type
+			? Type extends Record<Key, Type[Key]>
+				? false
+				: true
+			: false;

source/is-readonly-key-of.d.ts

@@ -0,0 +1,53 @@
+import type {IsEqual} from './is-equal.d.ts';
+import type {IsAny} from './is-any.d.ts';
+
+/**
+Returns a boolean for whether the given key is a readonly key of type.
+
+This is useful when writing utility types or schema validators that need to differentiate `readonly` keys.
+
+@example
+```
+import type {IsReadonlyKeyOf} from 'type-fest';
+
+interface User {
+	name: string;
+	surname: string;
+
+	readonly id: number;
+}
+
+interface Admin {
+	name: string;
+	id: string
+}
+
+type T1 = IsReadonlyKeyOf<User, 'id'>;
+//=> true
+
+type T2 = IsReadonlyKeyOf<User, 'name'>;
+//=> false
+
+type T3 = IsReadonlyKeyOf<User, 'name' | 'id'>;
+//=> boolean
+
+type T4 = IsReadonlyKeyOf<User | Admin, 'name'>;
+//=> false
+
+type T5 = IsReadonlyKeyOf<User | Admin, 'id'>;
+//=> boolean
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsReadonlyKeyOf<Type extends object, Key extends keyof Type> =
+	IsAny<Type | Key> extends true ? never
+		: Key extends unknown // For distributing `Key`
+			? Type extends unknown // For distributing `Type`
+				? IsEqual<
+					{[K in Key]: Type[Key]},
+					{readonly [K in Key]: Type[Key]}
+				>
+				: never // Should never happen
+			: never; // Should never happen

source/is-required-key-of.d.ts

@@ -0,0 +1,49 @@
+import type {IsOptionalKeyOf} from './is-optional-key-of.d.ts';
+import type {Not} from './internal/type.d.ts';
+import type {IsAny} from './is-any.d.ts';
+
+/**
+Returns a boolean for whether the given key is a required key of type.
+
+This is useful when writing utility types or schema validators that need to differentiate `required` keys.
+
+@example
+```
+import type {IsRequiredKeyOf} from 'type-fest';
+
+interface User {
+	name: string;
+	surname: string;
+
+	luckyNumber?: number;
+}
+
+interface Admin {
+	name: string;
+	surname?: string
+}
+
+type T1 = IsRequiredKeyOf<User, 'name'>;
+//=> true
+
+type T2 = IsRequiredKeyOf<User, 'luckyNumber'>;
+//=> false
+
+type T3 = IsRequiredKeyOf<User, 'name' | 'luckyNumber'>;
+//=> boolean
+
+type T4 = IsRequiredKeyOf<User | Admin, 'name'>;
+//=> true
+
+type T5 = IsRequiredKeyOf<User | Admin, 'surname'>;
+//=> boolean
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsRequiredKeyOf<Type extends object, Key extends keyof Type> =
+	IsAny<Type | Key> extends true ? never
+		: Key extends keyof Type
+			? Not<IsOptionalKeyOf<Type, Key>>
+			: false;

source/is-writable-key-of.d.ts

@@ -0,0 +1,49 @@
+import type {IsReadonlyKeyOf} from './is-readonly-key-of.d.ts';
+import type {Not} from './internal/type.d.ts';
+import type {IsAny} from './is-any.d.ts';
+
+/**
+Returns a boolean for whether the given key is a writable key of type.
+
+This is useful when writing utility types or schema validators that need to differentiate `writable` keys.
+
+@example
+```
+import type {IsWritableKeyOf} from 'type-fest';
+
+interface User {
+	name: string;
+	surname: string;
+
+	readonly id: number;
+}
+
+interface Admin {
+	name: string;
+	id: string
+}
+
+type T1 = IsWritableKeyOf<User, 'name'>;
+//=> true
+
+type T2 = IsWritableKeyOf<User, 'id'>;
+//=> false
+
+type T3 = IsWritableKeyOf<User, 'name' | 'id'>;
+//=> boolean
+
+type T4 = IsWritableKeyOf<User | Admin, 'name'>;
+//=> true
+
+type T5 = IsWritableKeyOf<User | Admin, 'id'>;
+//=> boolean
+```
+
+@category Type Guard
+@category Utilities
+*/
+export type IsWritableKeyOf<Type extends object, Key extends keyof Type> =
+	IsAny<Type | Key> extends true ? never
+		: Key extends keyof Type
+			? Not<IsReadonlyKeyOf<Type, Key>>
+			: false;

source/optional-keys-of.d.ts

@@ -1,3 +1,5 @@
+import type {IsOptionalKeyOf} from './is-optional-key-of.d.ts';
+
 /**
 Extract all optional keys from the given type.
 
@@ -31,9 +33,12 @@ const update2: UpdateOperation<User> = {
 
 @category Utilities
 */
-export type OptionalKeysOf<BaseType extends object> =
-	BaseType extends unknown // For distributing `BaseType`
-		? (keyof {
-			[Key in keyof BaseType as BaseType extends Record<Key, BaseType[Key]> ? never : Key]: never
-		}) & (keyof BaseType) // Intersect with `keyof BaseType` to ensure result of `OptionalKeysOf<BaseType>` is always assignable to `keyof BaseType`
+export type OptionalKeysOf<Type extends object> =
+	Type extends unknown // For distributing `Type`
+		? (keyof {[Key in keyof Type as
+			IsOptionalKeyOf<Type, Key> extends false
+				? never
+				: Key
+			]: never
+		}) & keyof Type // Intersect with `keyof Type` to ensure result of `OptionalKeysOf<Type>` is always assignable to `keyof Type`
 		: never; // Should never happen

source/readonly-keys-of.d.ts

@@ -1,4 +1,4 @@
-import type {WritableKeysOf} from './writable-keys-of.d.ts';
+import type {IsReadonlyKeyOf} from './is-readonly-key-of.d.ts';
 
 /**
 Extract all readonly keys from the given type.
@@ -12,6 +12,7 @@ import type {ReadonlyKeysOf} from 'type-fest';
 interface User {
 	name: string;
 	surname: string;
+
 	readonly id: number;
 }
 
@@ -24,7 +25,12 @@ const update1: UpdateResponse<User> = {
 
 @category Utilities
 */
-export type ReadonlyKeysOf<T extends object> =
-	T extends unknown // For distributing `T`
-		? Exclude<keyof T, WritableKeysOf<T>>
+export type ReadonlyKeysOf<Type extends object> =
+	Type extends unknown // For distributing `Type`
+		? (keyof {[Key in keyof Type as
+			IsReadonlyKeyOf<Type, Key> extends false
+				? never
+				: Key
+			]: never
+		}) & keyof Type // Intersect with `keyof Type` to ensure result of `ReadonlyKeysOf<Type>` is always assignable to `keyof Type`
 		: never; // Should never happen

source/required-keys-of.d.ts

@@ -24,7 +24,7 @@ const validator2 = createValidation<User>('surname', value => value.length < 25)
 
 @category Utilities
 */
-export type RequiredKeysOf<BaseType extends object> =
-	BaseType extends unknown // For distributing `BaseType`
-		? Exclude<keyof BaseType, OptionalKeysOf<BaseType>>
+export type RequiredKeysOf<Type extends object> =
+	Type extends unknown // For distributing `Type`
+		? Exclude<keyof Type, OptionalKeysOf<Type>>
 		: never; // Should never happen

source/writable-keys-of.d.ts

@@ -1,4 +1,4 @@
-import type {IsEqual} from './is-equal.d.ts';
+import type {ReadonlyKeysOf} from './readonly-keys-of.d.ts';
 
 /**
 Extract all writable keys from the given type.
@@ -12,6 +12,7 @@ import type {WritableKeysOf} from 'type-fest';
 interface User {
 	name: string;
 	surname: string;
+
 	readonly id: number;
 }
 
@@ -25,9 +26,7 @@ const update1: UpdateRequest<User> = {
 
 @category Utilities
 */
-export type WritableKeysOf<T extends object> =
-	T extends unknown // For distributing `T`
-		? (keyof {
-			[P in keyof T as IsEqual<{[Q in P]: T[P]}, {readonly [Q in P]: T[P]}> extends false ? P : never]: never
-		}) & keyof T // Intersect with `keyof T` to ensure result of `WritableKeysOf<T>` is always assignable to `keyof T`
+export type WritableKeysOf<Type extends object> =
+	Type extends unknown // For distributing `Type`
+		? Exclude<keyof Type, ReadonlyKeysOf<Type>>
 		: never; // Should never happen