chore: split, improve and clarify types in type-utils

Author: peter-sanderson

packages/type-utils/src/array.ts

@@ -0,0 +1,10 @@
+/**
+ * Gets the type of the elements in an array.
+ *
+ * Example:
+ *  ```
+ *  type A = (number | string)[];
+ *  type E = ArrayElement<A>; // number | string
+ *  ```
+ */
+export type ArrayElement<ArrayType extends readonly unknown[]> = ArrayType[number];

packages/type-utils/src/index.ts

@@ -1,3 +1,5 @@
-export * from './utils';
-export * from './timeout';
+export * from './array';
 export * from './overloads';
+export * from './timeout';
+export * from './utils';
+export * from './object';

packages/type-utils/src/object.ts

@@ -0,0 +1,13 @@
+export type GetObjectWithKey<U, K extends PropertyKey> = U extends object
+    ? K extends keyof U
+        ? U
+        : never
+    : never;
+
+export type GetObjectWithoutKey<U, K extends PropertyKey> = U extends object
+    ? K extends keyof U
+        ? never
+        : U
+    : never;
+
+export type ObjectsOnly<T> = T extends Record<string, unknown> ? T : never;

packages/type-utils/src/overloads.ts

@@ -1,5 +1,7 @@
 export type OverloadImplementations<T, U extends keyof T> = Overloads<T[U]>;
+
 export type Overloads<T> = Overloads24<T>;
+
 type Overloads24<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
@@ -53,6 +55,7 @@ type Overloads24<T> = T extends {
           (...args: A24) => R24,
       ]
     : Overloads23<T>;
+
 type Overloads23<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
@@ -104,6 +107,7 @@ type Overloads23<T> = T extends {
           (...args: A23) => R23,
       ]
     : Overloads22<T>;
+
 type Overloads22<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
@@ -153,6 +157,7 @@ type Overloads22<T> = T extends {
           (...args: A22) => R22,
       ]
     : Overloads21<T>;
+
 type Overloads21<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
@@ -200,6 +205,7 @@ type Overloads21<T> = T extends {
           (...args: A21) => R21,
       ]
     : Overloads20<T>;
+
 type Overloads20<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
@@ -245,6 +251,7 @@ type Overloads20<T> = T extends {
           (...args: A20) => R20,
       ]
     : Overloads19<T>;
+
 type Overloads19<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
@@ -288,6 +295,7 @@ type Overloads19<T> = T extends {
           (...args: A19) => R19,
       ]
     : Overloads18<T>;
+
 type Overloads18<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
@@ -329,6 +337,7 @@ type Overloads18<T> = T extends {
           (...args: A18) => R18,
       ]
     : Overloads17<T>;
+
 type Overloads17<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
@@ -368,6 +377,7 @@ type Overloads17<T> = T extends {
           (...args: A17) => R17,
       ]
     : Overloads16<T>;
+
 type Overloads16<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
@@ -405,6 +415,7 @@ type Overloads16<T> = T extends {
           (...args: A16) => R16,
       ]
     : Overloads15<T>;
+
 type Overloads15<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
@@ -440,6 +451,7 @@ type Overloads15<T> = T extends {
           (...args: A15) => R15,
       ]
     : Overloads14<T>;
+
 type Overloads14<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
@@ -473,6 +485,7 @@ type Overloads14<T> = T extends {
           (...args: A14) => R14,
       ]
     : Overloads13<T>;
+
 type Overloads13<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
@@ -504,6 +517,7 @@ type Overloads13<T> = T extends {
           (...args: A13) => R13,
       ]
     : Overloads12<T>;
+
 type Overloads12<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
@@ -533,6 +547,7 @@ type Overloads12<T> = T extends {
           (...args: A12) => R12,
       ]
     : Overloads11<T>;
+
 type Overloads11<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
@@ -560,6 +575,7 @@ type Overloads11<T> = T extends {
           (...args: A11) => R11,
       ]
     : Overloads10<T>;
+
 type Overloads10<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
@@ -585,6 +601,7 @@ type Overloads10<T> = T extends {
           (...args: A10) => R10,
       ]
     : Overloads9<T>;
+
 type Overloads9<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
@@ -608,6 +625,7 @@ type Overloads9<T> = T extends {
           (...args: A9) => R9,
       ]
     : Overloads8<T>;
+
 type Overloads8<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
@@ -629,6 +647,7 @@ type Overloads8<T> = T extends {
           (...args: A8) => R8,
       ]
     : Overloads7<T>;
+
 type Overloads7<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
@@ -648,6 +667,7 @@ type Overloads7<T> = T extends {
           (...args: A7) => R7,
       ]
     : Overloads6<T>;
+
 type Overloads6<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
@@ -665,6 +685,7 @@ type Overloads6<T> = T extends {
           (...args: A6) => R6,
       ]
     : Overloads5<T>;
+
 type Overloads5<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
@@ -680,6 +701,7 @@ type Overloads5<T> = T extends {
           (...args: A5) => R5,
       ]
     : Overloads4<T>;
+
 type Overloads4<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
@@ -688,19 +710,22 @@ type Overloads4<T> = T extends {
 }
     ? [(...args: A1) => R1, (...args: A2) => R2, (...args: A3) => R3, (...args: A4) => R4]
     : Overloads3<T>;
+
 type Overloads3<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
     (...args: infer A3): infer R3;
 }
     ? [(...args: A1) => R1, (...args: A2) => R2, (...args: A3) => R3]
     : Overloads2<T>;
+
 type Overloads2<T> = T extends {
     (...args: infer A1): infer R1;
     (...args: infer A2): infer R2;
 }
     ? [(...args: A1) => R1, (...args: A2) => R2]
     : Overloads1<T>;
+
 type Overloads1<T> = T extends {
     (...args: infer A1): infer R1;
 }

packages/type-utils/src/utils.ts

@@ -1,20 +1,55 @@
-// make key required
-
+/**
+ * Make property of the object required.
+ *
+ * Example:
+ *  ```
+ *  type T = { a?: number };
+ *  const t: RequiredKey<T, 'a'> = { a: 0 }; // 'a' is mandatory
+ *  ```
+ */
 export type RequiredKey<M, K extends keyof M> = Omit<M, K> & Required<Pick<M, K>>;
 
-// object values types
+/**
+ * Get type of the object values.
+ *
+ * Example:
+ *  ```
+ *  type T = { a: number; b: string };
+ *  type V: ObjectValues<T>; // number | string
+ *  ```
+ */
 export type ObjectValues<T extends { [key: string]: any }> = T[keyof T];
 
-// all keys of types in an union
+/**
+ * All keys of types in a union.
+ *
+ * Example:
+ *  ```
+ *  type T = { a: number; b: string };
+ *  type K: Keys<T>; // 'a' | 'b'
+ *  ```
+ */
 export type Keys<T> = T extends any ? keyof T : never;
 
-// remove the keys while keeping the union
+/**
+ * Distributes the Omit across a union. using distributive conditional types to achieve this:
+ * @see: https://www.typescriptlang.org/docs/handbook/2/conditional-types.html#distributive-conditional-types
+ * @source: https://stackoverflow.com/questions/57103834/typescript-omit-a-property-from-all-interfaces-in-a-union-but-keep-the-union-s#answer-57103940
+ *
+ * Example:
+ *  ```
+ *  type T = { remove: string; keep1: number } | { remove: string; keep2: boolean };
+ *  type W = Without<T, 'remove'>;
+ *  const w: W = { keep1: 1, keep2: true };
+ *  ```
+ */
 export type Without<T, K extends keyof any> = T extends any ? Omit<T, K> : never;
 
-// array element type
-export type ArrayElement<ArrayType extends readonly unknown[]> = ArrayType[number];
-
-// const with optional types
+/**
+ * Const with optional types.
+ * Todo: add example and better explanation.
+ *       It has exactly 1 usage so maybe this shall even be here in the utils package
+ */
 export type ConstWithOptionalFields<
     Const extends { [key: string]: any },
     Fields extends string | number | symbol,
@@ -30,49 +65,46 @@ export type ConstWithOptionalFields<
     };
 };
 
-// Extract item from union
-export type ItemExtractor<M> = Extract<M, { type: M }>;
-
-// Unwrap type from Promise
-export type Await<T> = T extends {
-    then(onfulfilled?: (value: infer U) => unknown): unknown;
-}
-    ? U
-    : T;
-
+/**
+ * Recursively makes all properties of the object optional. If the nested property is an object,
+ * it will make its properties optional as well.
+ *
+ * Example:
+ *  ```
+ *  type T = { a: number; b: { c: string; d: number } };
+ *  type P = DeepPartial<T>;
+ *  const p: P = { b: { d: 1 } }; // As everything is deeply optional
+ *  ```
+ */
 export type DeepPartial<T> = T extends () => any
     ? T
     : T extends { [key: string]: any }
       ? { [P in keyof T]?: DeepPartial<T[P]> }
       : T;
 
+/**
+ * Type containing all primitive types in TypeScript.
+ */
 export type PrimitiveType = string | number | boolean | Date | null | undefined;
 
-// Record<K, T> with optional key and required value.
-// example of using partial union as keys:
-// const p: PartialRecord<'a' | 'b' | 'c', string>; = { b: 'value' };
-export type PartialRecord<K extends keyof any, T> = {
-    [P in K]?: T;
-};
-
-// distributive conditional types to the rescue! This way we can infer union literal type from ReturnType but exclude undefined
+/**
+ * Record<K, T> with optional key and required value.
+ *
+ * Example:
+ *  ```
+ *  const p: PartialRecord<'a' | 'b' | 'c', string>; = { b: 'value' };
+ *  ```
+ */
+export type PartialRecord<K extends keyof any, T> = { [P in K]?: T };
+
+/**
+ * This infers the union literal type from ReturnType but exclude undefined
+ */
 export type DefinedUnionMember<T> = T extends string ? T : never;
 
-export type GetObjectWithKey<U, K extends PropertyKey> = U extends object
-    ? K extends keyof U
-        ? U
-        : never
-    : never;
-export type GetObjectWithoutKey<U, K extends PropertyKey> = U extends object
-    ? K extends keyof U
-        ? never
-        : U
-    : never;
-
-export type ObjectsOnly<T> = T extends Record<string, unknown> ? T : never;
-
-// map object `T` to a narrowed type with only those entries that match given `ValueFilter` type
+/**
+ * Map object `T` to a narrowed type with only those entries that match given `ValueFilter` type
+ */
 export type FilterPropertiesByType<T, ValueFilter> = {
     [Key in keyof T as T[Key] extends ValueFilter ? Key : never]: T[Key];
 };
-