feat: add Optional type with granular selection by key

README.md

@@ -82,6 +82,7 @@ Issues can be funded by anyone and the money will be transparently distributed t
 * [`ReadonlyKeys<T>`](#readonlykeyst)
 * [`WritableKeys<T>`](#writablekeyst)
 * [`RequiredKeys<T>`](#requiredkeyst)
+* [`Optional<T>`](#optionalst)
 * [`OptionalKeys<T>`](#optionalkeyst)
 * [`Partial<T>`](#partialt) _(built-in)_
 * [`DeepPartial<T>`](#deeppartialt)
@@ -313,6 +314,25 @@ type RequiredProps = ReadonlyKeys<Props>;
 
 [⇧ back to top](#table-of-contents)
 
+### `Optional<T, K>`
+
+From `T` make a set of properties by key `K` become optional
+
+**Usage:**
+
+```ts
+import { Optional } from 'utility-types';
+
+type Props = { name: string; age: number; visilbe: boolean; };
+
+// Expect: { name?: string; age?: number; visilbe?: boolean; }
+type Props = Optional<Props>
+// Expect: { name: string; age?: number; visilbe?: boolean; }
+type Props = Optional<Props, 'age' | 'visilbe'>;
+```
+
+[⇧ back to top](#table-of-contents)
+
 ### `OptionalKeys<T>`
 
 Get union type of keys that are optional in object type `T`

src/__snapshots__/mapped-types.spec.ts.snap

@@ -126,6 +126,10 @@ exports[`OmitByValueExact testType<OmitByValueExact<RequiredOptionalProps, undef
 
 exports[`OmitByValueExact testType<OmitByValueExact<T, number>>() 1`] = `"Pick<T, { [Key in keyof T]: [number] extends [T[Key]] ? [T[Key]] extends [T[Key] & number] ? never : Key : Key; }[keyof T]>"`;
 
+exports[`Optional testType<Optional<Props, 'age' | 'visible'>>() 1`] = `"(Pick<Props, \\"name\\" | \\"visible\\"> & { age?: number | undefined; }) | (Pick<Props, \\"name\\" | \\"age\\"> & { visible?: boolean | undefined; })"`;
+
+exports[`Optional testType<Optional<Props>>() 1`] = `"Partial<Props>"`;
+
 exports[`OptionalKeys testType<OptionalKeys<RequiredOptionalProps>>() 1`] = `"\\"opt\\" | \\"optUndef\\""`;
 
 exports[`Overwrite const result: Overwrite<Omit<T, 'age'>, T> = rest 1`] = `"any"`;

src/index.ts

@@ -35,6 +35,7 @@ export {
   OmitByValueExact,
   OptionalKeys,
   Overwrite,
+  Optional,
   PickByValue,
   PickByValueExact,
   Primitive,

src/mapped-types.spec.snap.ts

@@ -38,6 +38,7 @@ import {
   OptionalKeys,
   PickByValueExact,
   OmitByValueExact,
+  Optional,
 } from './mapped-types';
 
 /**
@@ -482,3 +483,12 @@ type RequiredOptionalProps = {
   // @dts-jest:pass:snap -> Brand<number, "USD">
   testType<Brand<number, 'USD'>>();
 }
+
+// @dts-jest:group Optional
+{
+  // @dts-jest:pass:snap -> Partial<Props>
+  testType<Optional<Props>>();
+
+  // @dts-jest:pass:snap -> (Pick<Props, "name" | "visible"> & { age?: number | undefined; }) | (Pick<Props, "name" | "age"> & { visible?: boolean | undefined; })
+  testType<Optional<Props, 'age' | 'visible'>>();
+}

src/mapped-types.spec.ts

@@ -38,6 +38,7 @@ import {
   OptionalKeys,
   PickByValueExact,
   OmitByValueExact,
+  Optional,
 } from './mapped-types';
 
 /**
@@ -482,3 +483,12 @@ type RequiredOptionalProps = {
   // @dts-jest:pass:snap
   testType<Brand<number, 'USD'>>();
 }
+
+// @dts-jest:group Optional
+{
+  // @dts-jest:pass:snap
+  testType<Optional<Props>>();
+
+  // @dts-jest:pass:snap
+  testType<Optional<Props, 'age' | 'visible'>>();
+}

src/mapped-types.ts

@@ -554,3 +554,23 @@ type IfEquals<X, Y, A = X, B = never> = (<T>() => T extends X
  *   gross(eur);
  */
 export type Brand<T, U> = T & { __brand: U };
+
+/**
+ * Optional
+ * @desc From `T` make a set of properties by key `K` become optional
+ * @example
+ *    type Props = {
+ *      name: string;
+ *      age: number;
+ *      visible: boolean;
+ *    };
+ *
+ *    // Expect: { name?: string; age?: number; visible?: boolean; }
+ *    type Props = Optional<Props>;
+ *
+ *    // Expect: { name: string; age?: number; visible?: boolean; }
+ *    type Props = Optional<Props, 'age' | 'visible'>;
+ */
+export type Optional<T extends object, K = keyof any> = K extends (keyof T)
+  ? (Omit<T, K> & { [key in K]?: T[key] })
+  : Partial<T>;