@nestia/e2e 7.0.0-dev.20250608 → 7.0.1

package/lib/ArrayUtil.js

@@ -46,41 +46,61 @@ var __values = (this && this.__values) || function(o) {
     };
     throw new TypeError(s ? "Object is not iterable." : "Symbol.iterator is not defined.");
 };
-var __read = (this && this.__read) || function (o, n) {
-    var m = typeof Symbol === "function" && o[Symbol.iterator];
-    if (!m) return o;
-    var i = m.call(o), r, ar = [], e;
-    try {
-        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
-    }
-    catch (error) { e = { error: error }; }
-    finally {
-        try {
-            if (r && !r.done && (m = i["return"])) m.call(i);
-        }
-        finally { if (e) throw e.error; }
-    }
-    return ar;
-};
-var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
-    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
-        if (ar || !(i in from)) {
-            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
-            ar[i] = from[i];
-        }
-    }
-    return to.concat(ar || Array.prototype.slice.call(from));
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ArrayUtil = void 0;
 /**
- * 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]
+ *   ```;
  */
 var ArrayUtil;
 (function (ArrayUtil) {
     var _this = this;
+    /**
+     * 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
+     */
     ArrayUtil.asyncFilter = function (elements) {
         return function (pred) { return __awaiter(_this, void 0, void 0, function () {
             var ret;
@@ -109,6 +129,32 @@ var ArrayUtil;
             });
         }); };
     };
+    /**
+     * 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>
+     */
     ArrayUtil.asyncForEach = function (elements) {
         return function (closure) { return __awaiter(_this, void 0, void 0, function () {
             return __generator(this, function (_a) {
@@ -123,6 +169,34 @@ var 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
+     */
     ArrayUtil.asyncMap = function (elements) {
         return function (closure) { return __awaiter(_this, void 0, void 0, function () {
             var ret;
@@ -150,6 +224,31 @@ var ArrayUtil;
             });
         }); };
     };
+    /**
+     * 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
+     */
     ArrayUtil.asyncRepeat = function (count) {
         return function (closure) { return __awaiter(_this, void 0, void 0, function () {
             var indexes, output, indexes_1, indexes_1_1, index, _a, _b, e_1_1;
@@ -193,20 +292,118 @@ var ArrayUtil;
             });
         }); };
     };
+    /**
+     * 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
+     */
     ArrayUtil.has = function (elements) {
         return function (pred) {
             return 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
+     */
     ArrayUtil.repeat = function (count) {
         return function (closure) {
             return new Array(count).fill("").map(function (_, index) { return closure(index); });
         };
     };
-    ArrayUtil.flat = function (matrix) {
-        var _a;
-        return (_a = []).concat.apply(_a, __spreadArray([], __read(matrix), false));
-    };
+    /**
+     * 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
+     */
     ArrayUtil.subsets = function (array) {
         var check = new Array(array.length).fill(false);
         var output = [];

package/lib/ArrayUtil.js.map

@@ -1 +1 @@
-{"version":3,"file":"ArrayUtil.js","sourceRoot":"","sources":["../src/ArrayUtil.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ArrayUtil.js","sourceRoot":"","sources":["../src/ArrayUtil.ts"],"names":[],"mappings":"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"}

package/lib/GaffComparator.d.ts

@@ -1,33 +1,248 @@
 /**
- * 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 declare 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';
+     *   }
      *
-     * @param getter Getter of string(s) from input
-     * @returns Comparator function
+     *   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' }
+     *   ];
+     *
+     *   // 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()
      */
     const strings: <T>(getter: (input: T) => string | string[]) => (x: T, y: T) => number;
     /**
-     * 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;
+     *   }
      *
-     * @param getter Getter of date(s) from input
-     * @returns Comparator function
+     *   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'
+     *     }
+     *   ];
+     *
+     *   // 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()
      */
     const dates: <T>(getter: (input: T) => string | string[]) => (x: T, y: T) => number;
     /**
-     * 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;
+     *   }
+     *
+     *   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)
+     *   ]);
+     *   ```;
      *
-     * @param closure Getter of number(s) from input
-     * @returns Comparator function
+     * @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()
      */
     const numbers: <T>(closure: (input: T) => number | number[]) => (x: T, y: T) => number;
 }