From 84d7c652f980eb73c35c7bcc99b11f25bfa3d709 Mon Sep 17 00:00:00 2001
From: Hernan Alvarado <hernanvid123@gmail.com>
Date: Mon, 10 Feb 2025 15:17:20 -0500
Subject: [PATCH] chore(docs): add missing documentation for utility types

---
 src/array-types.ts  | 10 +++++++-
 src/object-types.ts | 58 +++++++++++++++++++++++++++++++++++++--------
 2 files changed, 57 insertions(+), 11 deletions(-)

diff --git a/src/array-types.ts b/src/array-types.ts
index 53ed778..1b8b0fb 100644
--- a/src/array-types.ts
+++ b/src/array-types.ts
@@ -241,7 +241,15 @@ type ChunkImplementation<
       : [...Build, Partition]
 
 /**
- * TODO: add examples
+ * Split an array into chunks of a specific length if the last chunk is smaller than the specified length
+ * it will returns the last chunk with the remaining elements
+ *
+ * @example
+ * // Expected: [[1, 2], [3, 4], [5]]
+ * type Chunk1 = Chunk<[1, 2, 3, 4, 5], 2>;
+ *
+ * // Expected: [[1, 2, 3], [4, 5]]
+ * type Chunk2 = Chunk<[1, 2, 3, 4, 5], 3>;
  */
 export type Chunk<Array extends unknown[], Length extends number> = ChunkImplementation<Array, Length, [], []>
 
diff --git a/src/object-types.ts b/src/object-types.ts
index 0c318de..604cfd4 100644
--- a/src/object-types.ts
+++ b/src/object-types.ts
@@ -57,9 +57,14 @@ export type Discard<Compare, Match, Value = never, Reverse extends boolean = fal
         : Value
 
 /**
- * TODO: add examples
- *
  * Get the type of the resolved value of a PromiseLike object.
+ *
+ * @example
+ * // Expected: string
+ * type A = Awaited<Promise<string>>;
+ *
+ * // Expected: boolean
+ * type B = Awaited<Promise<Promise<boolean>>>;
  */
 export type Awaited<T extends PromiseLike<unknown>> =
     T extends PromiseLike<infer ResolveType>
@@ -154,8 +159,6 @@ export type PickByType<Obj extends object, Type> = {
 }
 
 /**
- * TODO: add examples
- *
  * Converts the specified keys of an object into optional ones
  *
  * @example
@@ -190,10 +193,23 @@ export type OmitByType<Obj extends object, Type> = {
 }
 
 /**
- * TODO: add examples
- *
  * Extracts the value of a key from an object and returns a new object with that value,
  * while keeping the other values unchanged.
+ *
+ * @example
+ * interface User {
+ *   name: string,
+ *   lastname: string,
+ *   address: {
+ *     street: string,
+ *     avenue: string
+ *   }
+ * }
+ *
+ * // Expected: { name: string, lastname: string, street: string, avenue: string }
+ * type UserAddress = ExtractValue<User, "address">;
+ *
+ * TODO: Implement a version that allows extracting nested values
  */
 export type FlattenProperties<Obj extends object, Keys extends keyof Obj> = Prettify<
     {
@@ -202,19 +218,41 @@ export type FlattenProperties<Obj extends object, Keys extends keyof Obj> = Pret
 >
 
 /**
- * TODO: add examples
- *
  * Removes the properties whose keys start with an underscore (_).
+ *
+ * @example
+ * interface User {
+ *   name: string,
+ *   _lastname: string,
+ *   _age: number
+ * }
+ *
+ * // Expected: { name: string }
+ * type PublicUser = PublicOnly<User>;
  */
 export type PublicOnly<Obj extends object> = {
     [Property in keyof Obj as Discard<Property, `_${string}`>]: Obj[Property]
 }
 
 /**
- * TODO: add examples
- *
  * Checks if a key exists in either of the two objects and returns its value.
  * If the key does not exist in either object, it returns `never`.
+ *
+ * @example
+ *
+ * interface Foo {
+ *   foo: string
+ * }
+ *
+ * interface Bar {
+ *   bar: number
+ * }
+ *
+ * // Expected: string
+ * type FooValue = RetrieveKeyValue<Foo, Bar, "foo">;
+ *
+ * // Expected: number
+ * type BarValue = RetrieveKeyValue<Foo, Bar, "bar">;
  */
 export type RetrieveKeyValue<Obj1 extends object, Obj2 extends object, Key> = Key extends keyof Obj1
     ? Obj1[Key]