Merge pull request #17 from kakasoo/kakasoo/codebase-review

test, docs: comprehensive test coverage, JSDoc, and README rewrite

Author: kakasoo

README.md

@@ -1,6 +1,25 @@
 import { DeepStrictObjectKeys } from '../types/DeepStrictObjectKeys';
 import { DeepStrictPick } from '../types/DeepStrictPick';
 
+/**
+ * @title Runtime Function for Type-Safe Deep Property Extraction.
+ *
+ * A curried function that takes an object and returns a picker function.
+ * The picker function accepts a dot-notation key path and returns a new object
+ * containing only the specified nested property, preserving the original structure.
+ *
+ * This is the runtime counterpart of the {@link DeepStrictPick} type.
+ *
+ * @template T - The object type of the input
+ * @param input - The source object to extract properties from
+ * @returns A function that accepts a key path `K` and returns the deeply-picked result
+ *
+ * @example
+ * ```ts
+ * const result = deepStrictAssert({ a: { b: 1, c: 2 } })('a.b');
+ * // result: { a: { b: 1 } }
+ * ```
+ */
 export const deepStrictAssert =
   <T extends object>(input: T) =>
   <K extends DeepStrictObjectKeys<T>>(key: K): DeepStrictPick<T, K> => {

docs/README_KO.md

@@ -1,7 +1,9 @@
 import { DeepStrictObjectKeys } from '../types';
 
+/** @internal Removes a leading dot from a string type. e.g., `".foo"` becomes `"foo"`. */
 type RemoveStartWithDot<T extends string> = T extends `.${infer R extends string}` ? R : T;
 
+/** @internal Replaces all `[*]` array notation with `${number}` for runtime key path access. */
 type Replace<S extends string> = S extends '[*]'
   ? `${number}`
   : S extends `[*].${infer Rest}`
@@ -12,11 +14,36 @@ type Replace<S extends string> = S extends '[*]'
         ? `${Prefix}.${number}${Replace<Rest>}`
         : S; // 더 이상 `[ ]`가 없으면 문자열 반환
 
+/**
+ * @internal The return type for {@link deepStrictObjectKeys}.
+ * Converts type-level keys (with `[*]` notation) to runtime-friendly keys (with `${number}` notation),
+ * strips leading dots, and wraps the result in an array type.
+ */
 type ReturnType<
   Target extends object,
   Joiner extends { array: string; object: string } = { array: '[*]'; object: '.' },
 > = [Target] extends [never] ? [] : RemoveStartWithDot<Replace<DeepStrictObjectKeys<Target, Joiner, false>>>[];
 
+/**
+ * @title Runtime Function for Extracting All Nested Keys from an Object.
+ *
+ * Recursively traverses the input object and returns a flat array of all key paths
+ * using dot notation. Nested objects produce paths like `"a.b.c"`, and arrays produce
+ * indexed paths at runtime.
+ *
+ * This is the runtime counterpart of the {@link DeepStrictObjectKeys} type.
+ *
+ * @template Target - The object type to extract keys from
+ * @template Joiner - Separator symbols (defaults to `{ array: '[*]', object: '.' }`)
+ * @param target - The object instance to extract keys from
+ * @returns An array of all dot-notation key paths in the object
+ *
+ * @example
+ * ```ts
+ * const keys = deepStrictObjectKeys({ a: { b: 1, c: 2 } });
+ * // keys: ["a", "a.b", "a.c"]
+ * ```
+ */
 export function deepStrictObjectKeys<
   Target extends object,
   Joiner extends { array: string; object: string } = { array: '[*]'; object: '.' },

src/functions/DeepStrictAssert.ts

@@ -1,11 +1,29 @@
 import { DeepStrictUnbrand } from './DeepStrictUnbrand';
 
 /**
- * A utility type that recursively converts all `Date` types within a nested object or array to `string`.
+ * @title Type for Recursively Converting All Date Types to String.
  *
- * - If `T` is an array of objects, the type processes each element recursively.
- * - If `T` is a `Date`, it is converted to `string`.
- * - If `T` is an object, each key is checked recursively for `Date` types or nested objects.
+ * A utility type that recursively traverses a nested object or array type and converts
+ * every `Date` type to `string`. This is useful for representing serialized forms of objects
+ * where dates are transmitted as ISO strings (e.g., JSON responses from APIs).
+ *
+ * Conversion rules:
+ * - If `T` is an array of objects, each element is processed recursively.
+ * - If `T` is a `Date`, it becomes `string`.
+ * - If `T` is an object, each property is checked: `Date` properties become `string`,
+ *   nested objects are recursed into, and primitives are preserved as-is.
+ * - Union types containing `Date` (e.g., `Date | null`) have only the `Date` portion converted.
+ * - Branded types are unbranded via {@link DeepStrictUnbrand} before recursion.
+ *
+ * @template T - The object type to convert
+ * @returns A new type with all `Date` occurrences replaced by `string`
+ *
+ * @example
+ * ```typescript
+ * type Ex1 = DeepDateToString<{ created: Date; name: string }>; // { created: string; name: string }
+ * type Ex2 = DeepDateToString<{ items: { date: Date }[] }>; // { items: { date: string }[] }
+ * type Ex3 = DeepDateToString<{ prop: Date | null }>; // { prop: string | null }
+ * ```
  */
 export type DeepDateToString<T extends object> =
   DeepStrictUnbrand<T> extends Array<infer I extends object>

src/functions/DeepStrictObjectKeys.ts

@@ -51,6 +51,17 @@ namespace DeepStrictMerge {
  * 2. For array types, if both `Target` and `Source` are arrays and their elements are objects, those elements are merged.
  *    - If the elements of the arrays are not objects, merging is not possible.
  * 3. If only one of the types is an array, merging is not possible.
+ *
+ * @template Target - The primary object type. Its values take precedence on overlapping keys.
+ * @template Source - The secondary object type whose unique keys are added to the result.
+ * @returns A deeply merged object type combining `Target` and `Source`
+ *
+ * @example
+ * ```ts
+ * type Ex1 = DeepStrictMerge<{ a: 1 }, { b: 2 }>; // { a: 1; b: 2 }
+ * type Ex2 = DeepStrictMerge<{ a: { b: 1 } }, { a: { c: 2 } }>; // { a: { b: 1; c: 2 } }
+ * type Ex3 = DeepStrictMerge<{ a: 1 }, { a: 2 }>; // { a: 1 } (Target wins)
+ * ```
  */
 export type DeepStrictMerge<Target extends object, Source extends object> =
   Target extends Array<infer TE extends object>

src/types/DeepDateToString.ts

@@ -71,9 +71,10 @@ namespace DeepStrictObjectKeys {
  * type Example1 = DeepStrictObjectKeys<{ a: { b: 1; c: 2 } }>; // "a" | "a.b" | "a.c"
  * type Example2 = DeepStrictObjectKeys<{ a: { b: 1; c: { d: number }[] } }>; // "a" | "a.b" | "a.c" | "a.c[*].d"
  * ```
- * @template Target Destination type for which you want to pull a key
- * @template Joiner It means what symbol to connect when recursively spinning superimposed types.
- * @template IsSafe When a key is a combination type of a primitive type and an object, it means whether to perform a recursive search or not.
+ * @template Target - The object type to extract nested keys from
+ * @template Joiner - Defines the separator symbols for joining nested paths. `array` is used for array access (default `'[*]'`), `object` is used for object access (default `'.'`).
+ * @template IsSafe - When `true`, stops at union types that mix primitives and objects without recursing into them. When `false`, recursively explores all branches of such union types.
+ * @returns A union of all dot-notation key paths in `Target`
  */
 export type DeepStrictObjectKeys<
   Target extends object,

src/types/DeepStrictMerge.ts

@@ -4,6 +4,16 @@ import type { IsUnion } from './IsUnion';
 import type { ValueType } from './ValueType';
 
 namespace DeepStrictObjectLastKeys {
+  /**
+   * @internal Recursively extracts only the leaf-level (last) keys from a nested object type.
+   *
+   * Unlike {@link DeepStrictObjectKeys.Infer}, this type skips intermediate keys and only
+   * returns the deepest reachable paths. Union-typed properties are treated as leaf keys.
+   *
+   * @template T - The object type to extract leaf keys from
+   * @template Joiner - Separator symbols for array and object paths
+   * @template P - The current property keys being processed
+   */
   export type Infer<
     T extends object,
     Joiner extends {
@@ -42,10 +52,15 @@ namespace DeepStrictObjectLastKeys {
  * - For arrays, it appends array indices (`[*]`) followed by the key of the element.
  * - For objects, it recursively traverses the nested structure and appends the last level keys.
  *
- * Example Usage:
+ * @template T - The object type to extract leaf keys from
+ * @template Joiner - Defines the separator symbols for joining nested paths. `array` is used for array access (default `'[*]'`), `object` is used for object access (default `'.'`).
+ * @template P - The property keys of `T` to iterate over (defaults to `keyof T`)
+ * @returns A union of dot-notation strings representing only the deepest (leaf) keys in `T`
+ *
+ * @example
  * ```ts
- * type Example1 = DeepStrictObjectLastKeys<{ a: { b: { c: number[] } } }>; // "a.b.c"
- * type Example2 = DeepStrictObjectLastKeys<{ a: { b: number[]; c: { d: string }[] } }>; // "a.b" | "a.c" | "a.c[*].d"
+ * type Ex1 = DeepStrictObjectLastKeys<{ a: { b: { c: number[] } } }>; // "a.b.c"
+ * type Ex2 = DeepStrictObjectLastKeys<{ a: { b: number[]; c: { d: string }[] } }>; // "a.b" | "a.c[*].d"
  * ```
  */
 export type DeepStrictObjectLastKeys<

src/types/DeepStrictObjectKeys.ts

@@ -2,6 +2,19 @@ import type { DeepStrictObjectKeys } from './DeepStrictObjectKeys';
 import type { GetElementMember } from './GetMember';
 
 namespace DeepStrictOmit {
+  /**
+   * @internal Recursively omits keys from a non-array object type.
+   *
+   * Handles three cases for each property:
+   * - Array of objects: recurses into array elements using {@link GetElementMember} to extract sub-keys
+   * - Object (non-Date): recurses into the nested object
+   * - Primitive / Date / array of primitives: preserves as-is
+   *
+   * Top-level keys that exactly match `K` are removed via the `as` clause.
+   *
+   * @template T - The object type to omit keys from
+   * @template K - The dot-notation key paths to omit (must be valid keys of `T`)
+   */
   export type Infer<T extends object, K extends DeepStrictObjectKeys<T>> = [K] extends [never]
     ? T
     : {

src/types/DeepStrictObjectLastKeys.ts

@@ -1,5 +1,19 @@
 namespace DeepStrictUnbrand {
+  /**
+   * @internal Union of all JavaScript primitive types.
+   * Used to detect branded primitives (primitives intersected with `Record<any, any>`).
+   */
   export type Primitive = string | number | boolean | symbol | null | undefined;
+
+  /**
+   * @internal Strips branding from a single branded primitive type.
+   *
+   * A "branded primitive" is a type like `string & { __brand: 'email' }`.
+   * This type pattern-matches the base primitive and returns it without the brand.
+   *
+   * @template T - A branded primitive type (must extend both `Primitive` and `Record<any, any>`)
+   * @returns The underlying primitive type with branding removed
+   */
   export type Infer<T extends Primitive & Record<any, any>> = T extends string & Record<any, any>
     ? string
     : T extends number & Record<any, any>