@nestia/e2e 11.0.0-dev.20260313 → 11.0.0-dev.20260313-2

package/lib/DynamicExecutor.js

@@ -0,0 +1,176 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DynamicExecutor = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Dynamic Executor running prefixed functions.
+ *
+ * `DynamicExecutor` runs every (or some filtered) prefixed functions in a
+ * specific directory.
+ *
+ * For reference, it's useful for test program development of a backend server.
+ * Just write test functions under a directory, and just specify it.
+ * Furthermore, if you compose e2e test programs to utilize the `@nestia/sdk`
+ * generated API functions, you can take advantage of {@link DynamicBenchmarker}
+ * at the same time.
+ *
+ * When you want to see some utilization cases, see the below example links.
+ *
+ * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   https://github.com/samchon/nestia-start/blob/master/test/index.ts
+ *
+ * @example
+ *   https://github.com/samchon/backend/blob/master/test/index.ts
+ */
+var DynamicExecutor;
+(function (DynamicExecutor) {
+    /**
+     * Prepare dynamic executor in strict mode.
+     *
+     * In strict mode, if any error occurs, the program will be terminated
+     * directly. Otherwise, {@link validate} mode does not terminate when error
+     * occurs, but just archive the error log.
+     *
+     * @param props Properties of dynamic execution
+     * @returns Report of dynamic test functions execution
+     */
+    DynamicExecutor.assert = (props) => main(true)(props);
+    /**
+     * Prepare dynamic executor in loose mode.
+     *
+     * In loose mode, the program would not be terminated even when error occurs.
+     * Instead, the error would be archived and returns as a list. Otherwise,
+     * {@link assert} mode terminates the program directly when error occurs.
+     *
+     * @param props Properties of dynamic executor
+     * @returns Report of dynamic test functions execution
+     */
+    DynamicExecutor.validate = (props) => main(false)(props);
+    const main = (assert) => (props) => __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const report = {
+            location: props.location,
+            time: Date.now(),
+            executions: [],
+        };
+        const executor = execute(props)(report)(assert);
+        const processes = yield iterate({
+            extension: (_a = props.extension) !== null && _a !== void 0 ? _a : "js",
+            location: props.location,
+            executor,
+        });
+        yield Promise.all(new Array((_b = props.simultaneous) !== null && _b !== void 0 ? _b : 1).fill(0).map(() => __awaiter(this, void 0, void 0, function* () {
+            while (processes.length !== 0) {
+                const task = processes.shift();
+                yield (task === null || task === void 0 ? void 0 : task());
+            }
+        })));
+        report.time = Date.now() - report.time;
+        return report;
+    });
+    const iterate = (props) => __awaiter(this, void 0, void 0, function* () {
+        const container = [];
+        const visitor = (path) => __awaiter(this, void 0, void 0, function* () {
+            const directory = yield fs_1.default.promises.readdir(path);
+            for (const file of directory) {
+                const location = path_1.default.resolve(`${path}/${file}`);
+                const stats = yield fs_1.default.promises.lstat(location);
+                if (stats.isDirectory() === true) {
+                    yield visitor(location);
+                    continue;
+                }
+                else if (file.substr(-3) !== `.${props.extension}`)
+                    continue;
+                const modulo = yield Promise.resolve(`${location}`).then(s => __importStar(require(s)));
+                container.push(() => props.executor(location, modulo));
+            }
+        });
+        yield visitor(props.location);
+        return container;
+    });
+    const execute = (props) => (report) => (assert) => (location, modulo) => __awaiter(this, void 0, void 0, function* () {
+        for (const [key, closure] of Object.entries(modulo)) {
+            if (key.substring(0, props.prefix.length) !== props.prefix ||
+                typeof closure !== "function" ||
+                (props.filter && props.filter(key) === false))
+                continue;
+            const func = () => {
+                if (props.wrapper !== undefined)
+                    return props.wrapper(key, closure, props.parameters(key));
+                else
+                    return closure(...props.parameters(key));
+            };
+            const result = {
+                name: key,
+                location,
+                value: undefined,
+                error: null,
+                started_at: new Date().toISOString(),
+                completed_at: new Date().toISOString(),
+            };
+            report.executions.push(result);
+            try {
+                result.value = yield func();
+                result.completed_at = new Date().toISOString();
+            }
+            catch (exp) {
+                result.error = exp;
+                if (assert === true)
+                    throw exp;
+            }
+            finally {
+                result.completed_at = new Date().toISOString();
+                if (props.onComplete)
+                    props.onComplete(result);
+            }
+        }
+    });
+})(DynamicExecutor || (exports.DynamicExecutor = DynamicExecutor = {}));
+//# sourceMappingURL=DynamicExecutor.js.map

package/lib/DynamicExecutor.js.map

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

package/lib/GaffComparator.d.ts

@@ -0,0 +1,255 @@
+/**
+ * Type-safe comparator functions for Array.sort() operations with advanced
+ * field access.
+ *
+ * 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
+ *
+ * @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's currying pattern
+ *   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
+ *   ```;
+ */
+export declare namespace GaffComparator {
+    /**
+     * 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' }
+     *   ];
+     *
+     *   // 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 TestValidator sorting validation
+     *   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()
+     */
+    const strings: <T>(getter: (input: T) => string | string[]) => (x: T, y: T) => number;
+    /**
+     * 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'
+     *     }
+     *   ];
+     *
+     *   // 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 with TestValidator
+     *   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 => [
+     *     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;
+    /**
+     * 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 with TestValidator
+     *   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)
+     *   ]);
+     *   ```;
+     *
+     * @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;
+}