@nestia/e2e 14.0.0 → 14.0.2

package/src/GaffComparator.ts

@@ -22,27 +22,40 @@
  * - Return > 0 if first element should come after second
  * - Return 0 if elements are equal
  *
+ * Processing cost: Each comparison extracts both key lists and visits their
+ * common prefix until the first difference; date keys additionally parse all
+ * supplied strings once per comparison. No sort or repeated scan is performed
+ * inside a comparison.
+ *
  * @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));
+ *   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]));
+ *   users.sort(
+ *     GaffComparator.strings((user) => [user.lastName, user.firstName]),
+ *   );
+ *   events.sort(
+ *     GaffComparator.dates((event) => [event.startDate, event.endDate]),
+ *   );
  *
  *   // Integration with TestValidator's currying pattern
- *   const validator = TestValidator.sort("user sorting",
- *     (sortable) => api.getUsers({ sort: sortable })
- *   )("name", "email")(
- *     GaffComparator.strings(user => [user.name, user.email])
- *   );
+ *   const validator = TestValidator.sort("user sorting", (sortable) =>
+ *     api.getUsers({ sort: sortable }),
+ *   )(
+ *     "name",
+ *     "email",
+ *   )(GaffComparator.strings((user) => [user.name, user.email]));
  *   await validator("+"); // ascending
  *   await validator("-"); // descending
- *   ```;
+ *
+ * @evidence contracts/common.md#principled-implementation Each comparator maps both operands to arrays of comparable values and decides by the first position where they differ, then by array length, which is a lexicographic order that satisfies the sort contract for well-defined values; it is used to check server-side sorting from the client.
+ * @evidence contracts/common.md#clear-and-simple-design Three comparators share scalar-to-array wrapping. Strings compare each key by collation; dates and numbers use a shared strict mismatch search over their numeric keys.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts The ordering rule is generic in the getter, with no field, entity, or locale special case.
+ * @evidence contracts/common.md#meaningful-documentation The namespace prose lists the features and the sort contract with an example.
  */
 export namespace GaffComparator {
   /**
@@ -56,52 +69,89 @@ export namespace GaffComparator {
    *
    * 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".
+   * enables complex sorting like "sort by last name, then by first name". Keys
+   * that compare equal under the runtime's collation, including different
+   * canonically equivalent Unicode spellings, continue to the next key. If the
+   * whole common prefix compares equal, the shorter key list sorts first.
+   *
+   * Processing cost: Both getters run once and a bounded loop visits only
+   * common keys until the first collation difference. Work depends on examined
+   * keys and string comparison cost; scalar wrapping adds constant space.
    *
    * @example
-   *   ```typescript
    *   interface User {
    *     id: string;
    *     firstName: string;
    *     lastName: string;
    *     email: string;
-   *     status: 'active' | 'inactive';
+   *     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' }
+   *     {
+   *       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));
+   *   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]));
+   *   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));
+   *   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]));
+   *   users.sort(
+   *     GaffComparator.strings((user) => [
+   *       user.status,
+   *       user.lastName,
+   *       user.firstName,
+   *     ]),
+   *   );
    *
    *   // Integration with TestValidator sorting validation
-   *   const sortValidator = TestValidator.sort("user name sorting",
-   *     (sortFields) => userApi.getUsers({ sort: sortFields })
-   *   )("lastName", "firstName")(
-   *     GaffComparator.strings(user => [user.lastName, user.firstName])
-   *   );
+   *   const sortValidator = TestValidator.sort(
+   *     "user name sorting",
+   *     (sortFields) => userApi.getUsers({ sort: sortFields }),
+   *   )(
+   *     "lastName",
+   *     "firstName",
+   *   )(GaffComparator.strings((user) => [user.lastName, user.firstName]));
    *   await sortValidator("+"); // test ascending order
    *   await sortValidator("-"); // test descending order
-   *   ```;
    *
    * @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()
+   * @evidence contracts/common.md#principled-implementation Each common key position is compared once with localeCompare; a nonzero result decides the order, while collation-equal spellings continue to later keys. Only an entirely equal common prefix falls through to array length, establishing lexicographic order under the runtime's actual collation without assuming strict string equality.
+   * @evidence contracts/common.md#clear-and-simple-design Shared wrapping accepts scalar or array keys; one bounded loop returns the first nonzero collation result or the length difference.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The comparison is the platform's locale collation, not a hand-written ordering.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the locale sensitivity, the multi-value rule, and the arguments, with examples.
    */
   export const strings =
     <T>(getter: (input: T) => string | string[]) =>
@@ -109,8 +159,11 @@ export namespace GaffComparator {
       const a: string[] = wrap(getter(x));
       const b: string[] = wrap(getter(y));
 
-      const idx: number = a.findIndex((v, i) => v !== b[i]);
-      return idx !== -1 ? compare(a[idx]!, b[idx]!) : a.length - b.length;
+      for (let index = 0; index < Math.min(a.length, b.length); ++index) {
+        const result: number = compare(a[index]!, b[index]!);
+        if (result !== 0) return result;
+      }
+      return a.length - b.length;
     };
 
   /**
@@ -127,8 +180,11 @@ export namespace GaffComparator {
    * The comparison is performed on millisecond timestamps for precise
    * ordering.
    *
+   * Processing cost: Both getters run once, each returned string is parsed
+   * once, and the bounded mismatch search visits at most the common key count.
+   * Numeric key arrays require space proportional to the two lists.
+   *
    * @example
-   *   ```typescript
    *   interface Event {
    *     id: string;
    *     title: string;
@@ -140,53 +196,59 @@ export namespace GaffComparator {
    *
    *   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: "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'
-   *     }
+   *       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));
+   *   events.sort(GaffComparator.dates((event) => event.startDate));
    *
    *   // Sort by creation date (oldest first)
-   *   events.sort(GaffComparator.dates(event => event.createdAt));
+   *   events.sort(GaffComparator.dates((event) => event.createdAt));
    *
    *   // Multi-field: start date, then end date
-   *   events.sort(GaffComparator.dates(event => [event.startDate, event.endDate]));
+   *   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]));
+   *   events.sort(
+   *     GaffComparator.dates((event) => [event.createdAt, event.updatedAt]),
+   *   );
    *
    *   // Validate API date sorting with TestValidator
-   *   const dateValidator = TestValidator.sort("event chronological sorting",
-   *     (sortFields) => eventApi.getEvents({ sort: sortFields })
-   *   )("startDate")(
-   *     GaffComparator.dates(event => event.startDate)
-   *   );
+   *   const dateValidator = TestValidator.sort(
+   *     "event chronological sorting",
+   *     (sortFields) => eventApi.getEvents({ sort: sortFields }),
+   *   )("startDate")(GaffComparator.dates((event) => event.startDate));
    *   await dateValidator("+", true); // ascending with trace logging
    *
    *   // Test complex date-based sorting
-   *   const sortByEventSchedule = GaffComparator.dates(event => [
+   *   const sortByEventSchedule = GaffComparator.dates((event) => [
    *     event.startDate,
-   *     event.endDate
+   *     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()
+   * @evidence contracts/common.md#principled-implementation Each value is parsed by the `Date` constructor and compared by its millisecond timestamp, so ISO 8601 and the other formats the constructor accepts order correctly; a string the constructor cannot parse yields NaN, and the comparator then returns NaN, which a sort treats as equality, a limit the caller must respect by giving valid dates.
+   * @evidence contracts/common.md#clear-and-simple-design It uses the shared `wrap` and `mismatch`, and adds only the parsing.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts Parsing is the standard constructor with no format special cases.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the accepted formats and the millisecond comparison, with examples.
    */
   export const dates =
     <T>(getter: (input: T) => string | string[]) =>
@@ -196,7 +258,7 @@ export namespace GaffComparator {
       const a: number[] = take(x);
       const b: number[] = take(y);
 
-      const idx: number = a.findIndex((v, i) => v !== b[i]);
+      const idx: number = mismatch(a, b);
       return idx !== -1 ? a[idx]! - b[idx]! : a.length - b.length;
     };
 
@@ -214,8 +276,11 @@ export namespace GaffComparator {
    * on. This enables sophisticated sorting like "sort by price ascending, then
    * by rating descending".
    *
+   * Processing cost: Both getters run once and mismatch visits only the common
+   * prefix until the first unequal key. Existing key arrays are reused, and
+   * scalar wrapping takes constant auxiliary space.
+   *
    * @example
-   *   ```typescript
    *   interface Product {
    *     id: string;
    *     name: string;
@@ -227,49 +292,90 @@ export namespace GaffComparator {
    *   }
    *
    *   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 }
+   *     {
+   *       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));
+   *   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));
+   *   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]));
+   *   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]));
+   *   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]));
+   *   products.sort(
+   *     GaffComparator.numbers((product) => [
+   *       product.stock,
+   *       -product.salesCount,
+   *     ]),
+   *   );
    *
    *   // Validate API numerical sorting with TestValidator
-   *   const priceValidator = TestValidator.sort("product price sorting",
-   *     (sortFields) => productApi.getProducts({ sort: sortFields })
-   *   )("price")(
-   *     GaffComparator.numbers(product => product.price)
-   *   );
+   *   const priceValidator = TestValidator.sort(
+   *     "product price sorting",
+   *     (sortFields) => productApi.getProducts({ sort: sortFields }),
+   *   )("price")(GaffComparator.numbers((product) => product.price));
    *   await priceValidator("+"); // test ascending order
    *   await priceValidator("-"); // test descending order
    *
    *   // 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)
+   *   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()
+   * @evidence contracts/common.md#principled-implementation The sign of subtraction at the first differing position orders finite numeric values, and a shorter equal prefix sorts first. Subtraction can round or overflow, so the result's magnitude is not an exact-distance guarantee; callers must supply ordered numeric values rather than NaN.
+   * @evidence contracts/common.md#clear-and-simple-design It uses the shared `wrap` and `mismatch`, and adds only the subtraction.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The comparison is the arithmetic difference, with no rounding or thresholds.
+   * @evidence contracts/common.md#meaningful-documentation The comment states the multi-value rule and the arguments, with examples.
    */
   export const numbers =
     <T>(closure: (input: T) => number | number[]) =>
@@ -277,11 +383,23 @@ export namespace GaffComparator {
       const a: number[] = wrap(closure(x));
       const b: number[] = wrap(closure(y));
 
-      const idx: number = a.findIndex((v, i) => v !== b[i]);
+      const idx: number = mismatch(a, b);
       return idx !== -1 ? a[idx]! - b[idx]! : a.length - b.length;
     };
 
   const compare = (x: string, y: string) => x.localeCompare(y);
 
+  /**
+   * The first index where the two key lists differ within their common length,
+   * or -1; beyond it a proper prefix orders before its extension, in both
+   * argument orders.
+   */
+  const mismatch = <K>(a: K[], b: K[]): number => {
+    const length: number = Math.min(a.length, b.length);
+    for (let index: number = 0; index < length; ++index)
+      if (a[index] !== b[index]) return index;
+    return -1;
+  };
+
   const wrap = <T>(elem: T | T[]): T[] => (Array.isArray(elem) ? elem : [elem]);
 }

package/src/MapUtil.ts

@@ -5,9 +5,21 @@
  * objects, providing convenient methods for common Map operations like
  * retrieving values with lazy initialization.
  *
+ * Processing cost: The get-or-create operation uses native Map membership and
+ * lookup, and calls the factory only for an absent key; its dominant extra cost
+ * is the caller factory.
+ *
+ * Reuse: Stored values, including promises and undefined, are reused while the
+ * supplied Map retains the key. The caller must key every relevant dependency
+ * and remove stale or rejected entries; this helper cannot establish
+ * external-data freshness or prevent reentrant factory calls.
+ *
+ * Resource ownership: New values are transferred into the caller-owned Map,
+ * whose growth and eviction remain the caller responsibility; the helper
+ * acquires no external handle or background task.
+ *
  * @author Jeongho Nam - https://github.com/samchon
  * @example
- *   ```typescript
  *   // Create a cache with lazy initialization
  *   const cache = new Map<string, ExpensiveObject>();
  *
@@ -19,7 +31,11 @@
  *   // Subsequent calls return cached value without re-creating
  *   const sameObj = MapUtil.take(cache, "key1", () => new ExpensiveObject());
  *   console.log(obj === sameObj); // true
- *   ```;
+ *
+ * @evidence contracts/common.md#principled-implementation The namespace offers the get-or-create pattern over the native `Map`, whose `has` distinguishes an absent key from a stored `undefined`.
+ * @evidence contracts/common.md#clear-and-simple-design One function, without options or state.
+ * @evidence contracts/common.md#prohibited-implementation-shortcuts It uses only the public Map methods.
+ * @evidence contracts/common.md#meaningful-documentation The comment states the lazy initialization pattern with an example.
  */
 export namespace MapUtil {
   /**
@@ -32,8 +48,20 @@ export namespace MapUtil {
    * returns it. The factory function is only called when the key doesn't exist,
    * enabling lazy initialization and caching patterns.
    *
+   * Processing cost: One membership test and lookup, or one factory invocation
+   * and insertion, avoid a map scan; native Map access is sublinear on average
+   * and factory cost belongs to the supplied computation.
+   *
+   * Reuse: Stored values, including promises and undefined, are reused while
+   * the supplied Map retains the key. The caller must key every relevant
+   * dependency and remove stale or rejected entries; this helper cannot
+   * establish external-data freshness or prevent reentrant factory calls.
+   *
+   * Resource ownership: New values are transferred into the caller-owned Map,
+   * whose growth and eviction remain the caller responsibility; the helper
+   * acquires no external handle or background task.
+   *
    * @example
-   *   ```typescript
    *   // Simple caching example
    *   const userCache = new Map<number, User>();
    *
@@ -48,7 +76,7 @@ export namespace MapUtil {
    *   const dbConfig = MapUtil.take(configs, "database", () => ({
    *     host: "localhost",
    *     port: 5432,
-   *     database: "myapp"
+   *     database: "myapp",
    *   }));
    *
    *   // Lazy computation results
@@ -64,9 +92,8 @@ export namespace MapUtil {
    *   const key: [number, number] = [rows, cols];
    *
    *   const matrix = MapUtil.take(cache, key, () =>
-   *     generateIdentityMatrix(rows, cols)
+   *     generateIdentityMatrix(rows, cols),
    *   );
-   *   ```;
    *
    * @template K - The type of keys in the Map
    * @template V - The type of values in the Map
@@ -75,6 +102,10 @@ export namespace MapUtil {
    * @param value - A factory function that creates the value if key doesn't
    *   exist
    * @returns The existing value if found, or the newly created value
+   * @evidence contracts/common.md#principled-implementation The key is looked up with `has`, so an existing value, even `undefined`, is returned without calling the factory; otherwise the factory is called once, its value is stored, and the same value is returned.
+   * @evidence contracts/common.md#clear-and-simple-design A single check, one factory call, and one store.
+   * @evidence contracts/common.md#prohibited-implementation-shortcuts The factory result is stored as returned, with no copying or expiry.
+   * @evidence contracts/common.md#meaningful-documentation The comment states when the factory runs and documents the parameters with several examples.
    */
   export function take<K, V>(map: Map<K, V>, key: K, value: () => V): V {
     if (map.has(key)) {