@nestia/e2e 7.0.0 → 7.0.2

package/src/ArrayUtil.ts

@@ -1,9 +1,54 @@
 /**
- * Utility functions for arrays.
+ * A namespace providing utility functions for array manipulation.
+ *
+ * This namespace contains utility functions for array operations including
+ * asynchronous processing, filtering, mapping, and repetition tasks implemented
+ * in functional programming style. All functions are implemented using currying
+ * to enhance reusability and composability.
  *
  * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   ```typescript
+ *   // Asynchronous filtering example
+ *   const numbers = [1, 2, 3, 4, 5];
+ *   const evenNumbers = await ArrayUtil.asyncFilter(numbers)(
+ *     async (num) => num % 2 === 0
+ *   );
+ *   console.log(evenNumbers); // [2, 4]
+ *   ```;
  */
 export namespace ArrayUtil {
+  /**
+   * Filters an array by applying an asynchronous predicate function to each
+   * element.
+   *
+   * This function is implemented in curried form, first taking an array and
+   * then a predicate function. Elements are processed sequentially, ensuring
+   * order is maintained.
+   *
+   * @example
+   *   ```typescript
+   *   const users = [
+   *     { id: 1, name: 'Alice', active: true },
+   *     { id: 2, name: 'Bob', active: false },
+   *     { id: 3, name: 'Charlie', active: true }
+   *   ];
+   *
+   *   const activeUsers = await ArrayUtil.asyncFilter(users)(
+   *     async (user) => {
+   *       // Async validation logic (e.g., API call)
+   *       await new Promise(resolve => setTimeout(resolve, 100));
+   *       return user.active;
+   *     }
+   *   );
+   *   console.log(activeUsers); // [{ id: 1, name: 'Alice', active: true }, { id: 3, name: 'Charlie', active: true }]
+   *   ```;
+   *
+   * @template Input - The type of elements in the input array
+   * @param elements - The readonly array to filter
+   * @returns A function that takes a predicate and returns a Promise resolving
+   *   to the filtered array
+   */
   export const asyncFilter =
     <Input>(elements: readonly Input[]) =>
     async (
@@ -21,6 +66,32 @@ export namespace ArrayUtil {
       return ret;
     };
 
+  /**
+   * Executes an asynchronous function for each element in an array
+   * sequentially.
+   *
+   * Unlike JavaScript's native forEach, this function processes asynchronous
+   * functions sequentially and waits for all operations to complete. It
+   * performs sequential processing rather than parallel processing, making it
+   * suitable for operations where order matters.
+   *
+   * @example
+   *   ```typescript
+   *   const urls = ['url1', 'url2', 'url3'];
+   *
+   *   await ArrayUtil.asyncForEach(urls)(async (url, index) => {
+   *   console.log(`Processing ${index}: ${url}`);
+   *   const data = await fetch(url);
+   *   await processData(data);
+   *   console.log(`Completed ${index}: ${url}`);
+   *   });
+   *   console.log('All URLs processed sequentially');
+   *   ```
+   *
+   * @template Input - The type of elements in the input array
+   * @param elements - The readonly array to process
+   * @returns A function that takes an async closure and returns a Promise<void>
+   */
   export const asyncForEach =
     <Input>(elements: readonly Input[]) =>
     async (
@@ -35,6 +106,34 @@ export namespace ArrayUtil {
       );
     };
 
+  /**
+   * Transforms each element of an array using an asynchronous function to
+   * create a new array.
+   *
+   * Similar to JavaScript's native map but processes asynchronous functions
+   * sequentially. Each element's transformation is completed before proceeding
+   * to the next element, ensuring order is maintained.
+   *
+   * @example
+   *   ```typescript
+   *   const userIds = [1, 2, 3, 4, 5];
+   *
+   *   const userDetails = await ArrayUtil.asyncMap(userIds)(
+   *   async (id, index) => {
+   *   console.log(`Fetching user ${id} (${index + 1}/${userIds.length})`);
+   *   const response = await fetch(`/api/users/${id}`);
+   *   return await response.json();
+   *   }
+   *   );
+   *   console.log('All users fetched:', userDetails);
+   *   ```
+   *
+   * @template Input - The type of elements in the input array
+   * @template Output - The type of elements in the output array
+   * @param elements - The readonly array to transform
+   * @returns A function that takes a transformation function and returns a
+   *   Promise resolving to the transformed array
+   */
   export const asyncMap =
     <Input>(elements: readonly Input[]) =>
     async <Output>(
@@ -52,6 +151,31 @@ export namespace ArrayUtil {
       return ret;
     };
 
+  /**
+   * Executes an asynchronous function a specified number of times sequentially.
+   *
+   * Executes the function with indices from 0 to count-1 incrementally. Each
+   * execution is performed sequentially, and all results are collected into an
+   * array.
+   *
+   * @example
+   *   ```typescript
+   *   // Generate random data 5 times
+   *   const randomData = await ArrayUtil.asyncRepeat(5)(async (index) => {
+   *     await new Promise(resolve => setTimeout(resolve, 100)); // Wait 0.1 seconds
+   *     return {
+   *       id: index,
+   *       value: Math.random(),
+   *       timestamp: new Date().toISOString()
+   *     };
+   *   });
+   *   console.log('Generated data:', randomData);
+   *   ```;
+   *
+   * @param count - The number of times to repeat (non-negative integer)
+   * @returns A function that takes an async closure and returns a Promise
+   *   resolving to an array of results
+   */
   export const asyncRepeat =
     (count: number) =>
     async <T>(closure: (index: number) => Promise<T>): Promise<T[]> => {
@@ -65,18 +189,118 @@ export namespace ArrayUtil {
       return output;
     };
 
+  /**
+   * Checks if at least one element in the array satisfies the given condition.
+   *
+   * Similar to JavaScript's native some() method but implemented in curried
+   * form for better compatibility with functional programming style. Returns
+   * true immediately when the first element satisfying the condition is found.
+   *
+   * @example
+   *   ```typescript
+   *   const numbers = [1, 3, 5, 7, 8, 9];
+   *   const products = [
+   *     { name: 'Apple', price: 100, inStock: true },
+   *     { name: 'Banana', price: 50, inStock: false },
+   *     { name: 'Orange', price: 80, inStock: true }
+   *   ];
+   *
+   *   const hasEvenNumber = ArrayUtil.has(numbers)(num => num % 2 === 0);
+   *   console.log(hasEvenNumber); // true (8 exists)
+   *
+   *   const hasExpensiveItem = ArrayUtil.has(products)(product => product.price > 90);
+   *   console.log(hasExpensiveItem); // true (Apple costs 100)
+   *
+   *   const hasOutOfStock = ArrayUtil.has(products)(product => !product.inStock);
+   *   console.log(hasOutOfStock); // true (Banana is out of stock)
+   *   ```;
+   *
+   * @template T - The type of elements in the array
+   * @param elements - The readonly array to check
+   * @returns A function that takes a predicate and returns a boolean
+   */
   export const has =
     <T>(elements: readonly T[]) =>
     (pred: (elem: T) => boolean): boolean =>
       elements.find(pred) !== undefined;
 
+  /**
+   * Executes a function a specified number of times and collects the results
+   * into an array.
+   *
+   * A synchronous repetition function that executes the given function for each
+   * index (from 0 to count-1) and collects the results into an array.
+   *
+   * @example
+   *   ```typescript
+   *   // Generate an array of squares from 1 to 5
+   *   const squares = ArrayUtil.repeat(5)(index => (index + 1) ** 2);
+   *   console.log(squares); // [1, 4, 9, 16, 25]
+   *
+   *   // Generate an array of default user objects
+   *   const users = ArrayUtil.repeat(3)(index => ({
+   *   id: index + 1,
+   *   name: `User${index + 1}`,
+   *   email: `user${index + 1}@example.com`
+   *   }));
+   *   console.log(users);
+   *   // [
+   *   //   { id: 1, name: 'User1', email: 'user1@example.com' },
+   *   //   { id: 2, name: 'User2', email: 'user2@example.com' },
+   *   //   { id: 3, name: 'User3', email: 'user3@example.com' }
+   *   // ]
+   *   ```
+   *
+   * @param count - The number of times to repeat (non-negative integer)
+   * @returns A function that takes a closure and returns an array of results
+   */
   export const repeat =
     (count: number) =>
     <T>(closure: (index: number) => T): T[] =>
       new Array(count).fill("").map((_, index) => closure(index));
 
-  export const flat = <T>(matrix: T[][]): T[] => ([] as T[]).concat(...matrix);
-
+  /**
+   * Generates all possible subsets of a given array.
+   *
+   * Implements the mathematical concept of power set, generating 2^n subsets
+   * from an array of n elements. Uses depth-first search (DFS) algorithm to
+   * calculate all possible combinations of including or excluding each
+   * element.
+   *
+   * @example
+   *   ```typescript
+   *   const numbers = [1, 2, 3];
+   *   const allSubsets = ArrayUtil.subsets(numbers);
+   *   console.log(allSubsets);
+   *   // [
+   *   //   [],           // empty set
+   *   //   [3],          // {3}
+   *   //   [2],          // {2}
+   *   //   [2, 3],       // {2, 3}
+   *   //   [1],          // {1}
+   *   //   [1, 3],       // {1, 3}
+   *   //   [1, 2],       // {1, 2}
+   *   //   [1, 2, 3]     // {1, 2, 3}
+   *   // ]
+   *
+   *   const colors = ['red', 'blue'];
+   *   const colorSubsets = ArrayUtil.subsets(colors);
+   *   console.log(colorSubsets);
+   *   // [
+   *   //   [],
+   *   //   ['blue'],
+   *   //   ['red'],
+   *   //   ['red', 'blue']
+   *   // ]
+   *
+   *   // Warning: Result size grows exponentially with array size
+   *   // Example: 10 elements → 1,024 subsets, 20 elements → 1,048,576 subsets
+   *   ```;
+   *
+   * @template T - The type of elements in the array
+   * @param array - The array to generate subsets from
+   * @returns An array containing all possible subsets
+   */
   export const subsets = <T>(array: T[]): T[][] => {
     const check: boolean[] = new Array(array.length).fill(false);
     const output: T[][] = [];

package/src/GaffComparator.ts

@@ -1,19 +1,103 @@
 /**
- * Gaff comparator.
+ * Type-safe comparator functions for Array.sort() operations with advanced
+ * field access.
  *
- * `GaffComparator` is a set of comparator functions for `Array.sort()` function,
- * which can be used with {@link TestValidator.sort} function. If you want to see
- * how to use them, see the below example link.
+ * GaffComparator provides a collection of specialized comparator functions
+ * designed to work seamlessly with Array.sort() and testing frameworks like
+ * TestValidator.sort(). Each comparator supports both single values and arrays
+ * of values, enabling complex multi-field sorting scenarios with lexicographic
+ * ordering.
+ *
+ * Key features:
+ *
+ * - Generic type safety for any object structure
+ * - Support for single values or arrays of values per field
+ * - Lexicographic comparison for multi-value scenarios
+ * - Locale-aware string comparison
+ * - Automatic type conversion for dates and numbers
+ *
+ * The comparators follow the standard JavaScript sort contract:
+ *
+ * - Return < 0 if first element should come before second
+ * - Return > 0 if first element should come after second
+ * - Return 0 if elements are equal
  *
- * @example https://github.com/samchon/nestia-template/blob/master/src/test/features/api/bbs/test_api_bbs_article_index_sort.ts
  * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   ```typescript
+ *   // Basic usage with single fields
+ *   users.sort(GaffComparator.strings(user => user.name));
+ *   posts.sort(GaffComparator.dates(post => post.createdAt));
+ *   products.sort(GaffComparator.numbers(product => product.price));
+ *
+ *   // Multi-field sorting with arrays
+ *   users.sort(GaffComparator.strings(user => [user.lastName, user.firstName]));
+ *   events.sort(GaffComparator.dates(event => [event.startDate, event.endDate]));
+ *
+ *   // Integration with TestValidator
+ *   await TestValidator.sort("user sorting")(
+ *     (sortable) => api.getUsers({ sort: sortable })
+ *   )("name", "email")(
+ *     GaffComparator.strings(user => [user.name, user.email])
+ *   )("+");
+ *   ```;
  */
 export namespace GaffComparator {
   /**
-   * String(s) comparator.
+   * Creates a comparator function for string-based sorting with locale-aware
+   * comparison.
+   *
+   * Generates a comparator that extracts string values from objects and
+   * performs lexicographic comparison using locale-sensitive string comparison.
+   * Supports both single strings and arrays of strings for multi-field sorting
+   * scenarios.
+   *
+   * When comparing arrays, performs lexicographic ordering: compares the first
+   * elements, then the second elements if the first are equal, and so on. This
+   * enables complex sorting like "sort by last name, then by first name".
+   *
+   * @example
+   *   ```typescript
+   *   interface User {
+   *     id: string;
+   *     firstName: string;
+   *     lastName: string;
+   *     email: string;
+   *     status: 'active' | 'inactive';
+   *   }
+   *
+   *   const users: User[] = [
+   *     { id: '1', firstName: 'John', lastName: 'Doe', email: 'john@example.com', status: 'active' },
+   *     { id: '2', firstName: 'Jane', lastName: 'Doe', email: 'jane@example.com', status: 'inactive' },
+   *     { id: '3', firstName: 'Bob', lastName: 'Smith', email: 'bob@example.com', status: 'active' }
+   *   ];
    *
-   * @param getter Getter of string(s) from input
-   * @returns Comparator function
+   *   // Single field sorting
+   *   users.sort(GaffComparator.strings(user => user.lastName));
+   *   // Result: Doe, Doe, Smith
+   *
+   *   // Multi-field sorting: last name, then first name
+   *   users.sort(GaffComparator.strings(user => [user.lastName, user.firstName]));
+   *   // Result: Doe Jane, Doe John, Smith Bob
+   *
+   *   // Status-based sorting
+   *   users.sort(GaffComparator.strings(user => user.status));
+   *   // Result: active users first, then inactive
+   *
+   *   // Complex multi-field: status, then last name, then first name
+   *   users.sort(GaffComparator.strings(user => [user.status, user.lastName, user.firstName]));
+   *
+   *   // Integration with API sorting validation
+   *   await TestValidator.sort("user name sorting")(
+   *     (sortFields) => userApi.getUsers({ sort: sortFields })
+   *   )("lastName", "firstName")(
+   *     GaffComparator.strings(user => [user.lastName, user.firstName])
+   *   )("+");
+   *   ```;
+   *
+   * @template T - The type of objects being compared
+   * @param getter - Function that extracts string value(s) from input objects
+   * @returns A comparator function suitable for Array.sort()
    */
   export const strings =
     <T>(getter: (input: T) => string | string[]) =>
@@ -26,10 +110,78 @@ export namespace GaffComparator {
     };
 
   /**
-   * Date(s) comparator.
+   * Creates a comparator function for date-based sorting with automatic string
+   * parsing.
+   *
+   * Generates a comparator that extracts date values from objects,
+   * automatically converting string representations to Date objects for
+   * numerical comparison. Supports both single dates and arrays of dates for
+   * complex temporal sorting.
+   *
+   * Date strings are parsed using the standard Date constructor, which supports
+   * ISO 8601 format, RFC 2822 format, and other common date representations.
+   * The comparison is performed on millisecond timestamps for precise
+   * ordering.
+   *
+   * @example
+   *   ```typescript
+   *   interface Event {
+   *     id: string;
+   *     title: string;
+   *     startDate: string;
+   *     endDate: string;
+   *     createdAt: string;
+   *     updatedAt: string;
+   *   }
+   *
+   *   const events: Event[] = [
+   *     {
+   *       id: '1',
+   *       title: 'Conference',
+   *       startDate: '2024-03-15T09:00:00Z',
+   *       endDate: '2024-03-15T17:00:00Z',
+   *       createdAt: '2024-01-10T10:00:00Z',
+   *       updatedAt: '2024-02-01T15:30:00Z'
+   *     },
+   *     {
+   *       id: '2',
+   *       title: 'Workshop',
+   *       startDate: '2024-03-10T14:00:00Z',
+   *       endDate: '2024-03-10T16:00:00Z',
+   *       createdAt: '2024-01-15T11:00:00Z',
+   *       updatedAt: '2024-01-20T09:15:00Z'
+   *     }
+   *   ];
    *
-   * @param getter Getter of date(s) from input
-   * @returns Comparator function
+   *   // Sort by start date (chronological order)
+   *   events.sort(GaffComparator.dates(event => event.startDate));
+   *
+   *   // Sort by creation date (oldest first)
+   *   events.sort(GaffComparator.dates(event => event.createdAt));
+   *
+   *   // Multi-field: start date, then end date
+   *   events.sort(GaffComparator.dates(event => [event.startDate, event.endDate]));
+   *
+   *   // Sort by modification history: created date, then updated date
+   *   events.sort(GaffComparator.dates(event => [event.createdAt, event.updatedAt]));
+   *
+   *   // Validate API date sorting
+   *   await TestValidator.sort("event chronological sorting")(
+   *     (sortFields) => eventApi.getEvents({ sort: sortFields })
+   *   )("startDate")(
+   *     GaffComparator.dates(event => event.startDate)
+   *   )("+");
+   *
+   *   // Test complex date-based sorting
+   *   const sortByEventSchedule = GaffComparator.dates(event => [
+   *     event.startDate,
+   *     event.endDate
+   *   ]);
+   *   ```;
+   *
+   * @template T - The type of objects being compared
+   * @param getter - Function that extracts date string(s) from input objects
+   * @returns A comparator function suitable for Array.sort()
    */
   export const dates =
     <T>(getter: (input: T) => string | string[]) =>
@@ -44,10 +196,73 @@ export namespace GaffComparator {
     };
 
   /**
-   * Number(s) comparator.
+   * Creates a comparator function for numerical sorting with multi-value
+   * support.
+   *
+   * Generates a comparator that extracts numerical values from objects and
+   * performs mathematical comparison. Supports both single numbers and arrays
+   * of numbers for complex numerical sorting scenarios like sorting by price
+   * then by rating.
+   *
+   * When comparing arrays, performs lexicographic numerical ordering: compares
+   * the first numbers, then the second numbers if the first are equal, and so
+   * on. This enables sophisticated sorting like "sort by price ascending, then
+   * by rating descending".
+   *
+   * @example
+   *   ```typescript
+   *   interface Product {
+   *     id: string;
+   *     name: string;
+   *     price: number;
+   *     rating: number;
+   *     stock: number;
+   *     categoryId: number;
+   *     salesCount: number;
+   *   }
    *
-   * @param closure Getter of number(s) from input
-   * @returns Comparator function
+   *   const products: Product[] = [
+   *     { id: '1', name: 'Laptop', price: 999.99, rating: 4.5, stock: 15, categoryId: 1, salesCount: 150 },
+   *     { id: '2', name: 'Mouse', price: 29.99, rating: 4.2, stock: 50, categoryId: 1, salesCount: 300 },
+   *     { id: '3', name: 'Keyboard', price: 79.99, rating: 4.8, stock: 25, categoryId: 1, salesCount: 200 }
+   *   ];
+   *
+   *   // Sort by price (ascending)
+   *   products.sort(GaffComparator.numbers(product => product.price));
+   *   // Result: Mouse ($29.99), Keyboard ($79.99), Laptop ($999.99)
+   *
+   *   // Sort by rating (descending requires negation)
+   *   products.sort(GaffComparator.numbers(product => -product.rating));
+   *   // Result: Keyboard (4.8), Laptop (4.5), Mouse (4.2)
+   *
+   *   // Multi-field: category, then price
+   *   products.sort(GaffComparator.numbers(product => [product.categoryId, product.price]));
+   *
+   *   // Complex business logic: popularity (sales) then rating
+   *   products.sort(GaffComparator.numbers(product => [-product.salesCount, -product.rating]));
+   *   // Negative values for descending order
+   *
+   *   // Sort by inventory priority: low stock first, then by sales
+   *   products.sort(GaffComparator.numbers(product => [product.stock, -product.salesCount]));
+   *
+   *   // Validate API numerical sorting
+   *   await TestValidator.sort("product price sorting")(
+   *     (sortFields) => productApi.getProducts({ sort: sortFields })
+   *   )("price")(
+   *     GaffComparator.numbers(product => product.price)
+   *   )("+");
+   *
+   *   // Test multi-criteria sorting
+   *   const sortByBusinessValue = GaffComparator.numbers(product => [
+   *     -product.salesCount,  // High sales first
+   *     -product.rating,      // High rating first
+   *     product.price         // Low price first (for tie-breaking)
+   *   ]);
+   *   ```;
+   *
+   * @template T - The type of objects being compared
+   * @param closure - Function that extracts number value(s) from input objects
+   * @returns A comparator function suitable for Array.sort()
    */
   export const numbers =
     <T>(closure: (input: T) => number | number[]) =>
@@ -60,5 +275,6 @@ export namespace GaffComparator {
     };
 
   const compare = (x: string, y: string) => x.localeCompare(y);
+
   const wrap = <T>(elem: T | T[]): T[] => (Array.isArray(elem) ? elem : [elem]);
 }