@nestia/e2e 14.0.0 → 14.0.2

package/lib/GaffComparator.js

@@ -25,27 +25,40 @@ exports.GaffComparator = void 0;
  * - 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.
  */
 var GaffComparator;
 (function (GaffComparator) {
@@ -60,58 +73,99 @@ var 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.
      */
     GaffComparator.strings = (getter) => (x, y) => {
         const a = wrap(getter(x));
         const b = wrap(getter(y));
-        const idx = 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 = compare(a[index], b[index]);
+            if (result !== 0)
+                return result;
+        }
+        return a.length - b.length;
     };
     /**
      * Creates a comparator function for date-based sorting with automatic string
@@ -127,8 +181,11 @@ var 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,59 +197,65 @@ var 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.
      */
     GaffComparator.dates = (getter) => (x, y) => {
         const take = (v) => wrap(getter(v)).map((str) => new Date(str).getTime());
         const a = take(x);
         const b = take(y);
-        const idx = a.findIndex((v, i) => v !== b[i]);
+        const idx = mismatch(a, b);
         return idx !== -1 ? a[idx] - b[idx] : a.length - b.length;
     };
     /**
@@ -209,8 +272,11 @@ var 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;
@@ -222,57 +288,110 @@ var 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.
      */
     GaffComparator.numbers = (closure) => (x, y) => {
         const a = wrap(closure(x));
         const b = wrap(closure(y));
-        const idx = a.findIndex((v, i) => v !== b[i]);
+        const idx = mismatch(a, b);
         return idx !== -1 ? a[idx] - b[idx] : a.length - b.length;
     };
     const compare = (x, y) => 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 = (a, b) => {
+        const length = Math.min(a.length, b.length);
+        for (let index = 0; index < length; ++index)
+            if (a[index] !== b[index])
+                return index;
+        return -1;
+    };
     const wrap = (elem) => (Array.isArray(elem) ? elem : [elem]);
 })(GaffComparator || (exports.GaffComparator = GaffComparator = {}));
 //# sourceMappingURL=GaffComparator.js.map

package/lib/GaffComparator.js.map

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

package/lib/MapUtil.d.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 declare namespace MapUtil {
     /**
@@ -32,8 +48,20 @@ export declare 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 declare namespace MapUtil {
      *   const dbConfig = MapUtil.take(configs, "database", () => ({
      *     host: "localhost",
      *     port: 5432,
-     *     database: "myapp"
+     *     database: "myapp",
      *   }));
      *
      *   // Lazy computation results
@@ -64,9 +92,8 @@ export declare 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 declare 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.
      */
     function take<K, V>(map: Map<K, V>, key: K, value: () => V): V;
 }

package/lib/MapUtil.js

@@ -8,9 +8,21 @@ exports.MapUtil = void 0;
  * 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>();
  *
@@ -22,7 +34,11 @@ exports.MapUtil = void 0;
  *   // 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.
  */
 var MapUtil;
 (function (MapUtil) {
@@ -36,8 +52,20 @@ var 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>();
      *
@@ -52,7 +80,7 @@ var MapUtil;
      *   const dbConfig = MapUtil.take(configs, "database", () => ({
      *     host: "localhost",
      *     port: 5432,
-     *     database: "myapp"
+     *     database: "myapp",
      *   }));
      *
      *   // Lazy computation results
@@ -68,9 +96,8 @@ var 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
@@ -79,6 +106,10 @@ var 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.
      */
     function take(map, key, value) {
         if (map.has(key)) {

package/lib/MapUtil.js.map

@@ -1 +1 @@
-{"version":3,"file":"MapUtil.js","sourceRoot":"","sources":["../src/MapUtil.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,IAAiB,OAAO,CA+DvB;AA/DD,WAAiB,OAAO;IACtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqDG;IACH,SAAgB,IAAI,CAAO,GAAc,EAAE,GAAM,EAAE,KAAc;QAC/D,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACjB,OAAO,GAAG,CAAC,GAAG,CAAC,GAAG,CAAM,CAAC;QAC3B,CAAC;QACD,MAAM,QAAQ,GAAG,KAAK,EAAE,CAAC;QACzB,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QACvB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAPe,QAAA,IAAI,OAOnB,CAAA;AACH,CAAC,EA/DgB,OAAO,aAAP,OAAO,GAAP,OAAO,QA+DvB"}
+{"version":3,"file":"MapUtil.js","sourceRoot":"","sources":["../src/MapUtil.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,IAAiB,OAAO,CA8EvB;AA9ED,WAAiB,OAAO;IACtB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoEG;IACH,SAAgB,IAAI,CAAO,GAAc,EAAE,GAAM,EAAE,KAAc;QAC/D,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACjB,OAAO,GAAG,CAAC,GAAG,CAAC,GAAG,CAAM,CAAC;QAC3B,CAAC;QACD,MAAM,QAAQ,GAAG,KAAK,EAAE,CAAC;QACzB,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QACvB,OAAO,QAAQ,CAAC;IAClB,CAAC;IAPe,QAAA,IAAI,OAOnB,CAAA;AACH,CAAC,EA9EgB,OAAO,aAAP,OAAO,GAAP,OAAO,QA8EvB"}