@nestia/e2e 7.0.0 → 7.0.2

package/src/RandomGenerator.ts

@@ -1,20 +1,72 @@
 /**
- * Random data generator.
+ * Comprehensive random data generation utilities for testing and development.
+ *
+ * RandomGenerator provides a collection of functions for generating random data
+ * including strings, names, content, dates, and array sampling. All functions
+ * are designed to be deterministic within a single execution but produce varied
+ * output across different runs, making them ideal for testing scenarios.
+ *
+ * The namespace includes specialized generators for:
+ *
+ * - Text content (alphabets, alphanumeric, names, paragraphs)
+ * - Phone numbers and contact information
+ * - Date ranges and time-based data
+ * - Array sampling and element selection
  *
  * @author Jeongho Nam - https://github.com/samchon
+ * @example
+ *   ```typescript
+ *   // Generate test user data
+ *   const testUser = {
+ *     id: RandomGenerator.alphaNumeric(8),
+ *     name: RandomGenerator.name(),
+ *     bio: RandomGenerator.paragraph(3)(5, 10),
+ *     phone: RandomGenerator.mobile(),
+ *     createdAt: RandomGenerator.date(new Date())(1000 * 60 * 60 * 24 * 30) // 30 days
+ *   };
+ *
+ *   // Sample data for testing
+ *   const testSample = RandomGenerator.sample(allUsers)(5);
+ *   ```;
  */
 export namespace RandomGenerator {
   /* ----------------------------------------------------------------
         IDENTIFICATIONS
     ---------------------------------------------------------------- */
+
+  /** Character set containing lowercase alphabetical characters a-z */
   const CHARACTERS = "abcdefghijklmnopqrstuvwxyz";
+
+  /**
+   * Character set containing digits (0-9) and lowercase alphabetical characters
+   * (a-z)
+   */
   const LETTERS: string = "0123456789" + CHARACTERS;
 
   /**
-   * Generate random alphabets
+   * Generates a random string containing only lowercase alphabetical
+   * characters.
+   *
+   * Creates a string of specified length using only characters a-z. Each
+   * character is independently randomly selected, so the same character may
+   * appear multiple times. Useful for generating random identifiers, test
+   * names, or placeholder text.
    *
-   * @param length Length of alphabets
-   * @returns Generated alphabets
+   * @example
+   *   ```typescript
+   *   RandomGenerator.alphabets(5);  // "hello"
+   *   RandomGenerator.alphabets(3);  // "abc"
+   *   RandomGenerator.alphabets(10); // "randomtext"
+   *
+   *   // Generate random CSS class names
+   *   const className = `test-${RandomGenerator.alphabets(6)}`;
+   *
+   *   // Create random variable names for testing
+   *   const varName = RandomGenerator.alphabets(8);
+   *   ```
+   *
+   * @param length - The desired length of the generated alphabetic string
+   * @returns A string containing only lowercase letters of the specified length
    */
   export const alphabets = (length: number): string =>
     new Array(length)
@@ -23,12 +75,32 @@ export namespace RandomGenerator {
       .join("");
 
   /**
-   * Generate random alpha-numeric characters.
+   * Generates a random alphanumeric string containing digits and lowercase
+   * letters.
+   *
+   * Creates a string of specified length using characters from 0-9 and a-z.
+   * Each position is independently randomly selected from the combined
+   * character set. Ideal for generating random IDs, tokens, passwords, or
+   * unique identifiers that need both numeric and alphabetic characters.
    *
-   * Generate random string constructed with only alphabets and numbers.
+   * @example
+   *   ```typescript
+   *   RandomGenerator.alphaNumeric(8);  // "a1b2c3d4"
+   *   RandomGenerator.alphaNumeric(12); // "x9y8z7w6v5u4"
    *
-   * @param length Length of characters
-   * @returns Generated string
+   *   // Generate random API keys
+   *   const apiKey = RandomGenerator.alphaNumeric(32);
+   *
+   *   // Create session tokens
+   *   const sessionId = `sess_${RandomGenerator.alphaNumeric(16)}`;
+   *
+   *   // Generate test database IDs
+   *   const testId = RandomGenerator.alphaNumeric(10);
+   *   ```
+   *
+   * @param length - The desired length of the generated alphanumeric string
+   * @returns A string containing digits and lowercase letters of the specified
+   *   length
    */
   export const alphaNumeric = (length: number): string =>
     new Array(length)
@@ -37,27 +109,72 @@ export namespace RandomGenerator {
       .join("");
 
   /**
-   * Generate random name.
+   * Generates a random name-like string with realistic length variation.
+   *
+   * Creates a name by generating a paragraph with 2-3 words (randomly chosen).
+   * The resulting string resembles typical human names in structure and length.
+   * Each word is between 3-7 characters by default, creating realistic-looking
+   * names.
    *
-   * @param length Length of paragraph, default is 2 or 3
-   * @returns Generated name
+   * @example
+   *   ```typescript
+   *   RandomGenerator.name();    // "john doe"
+   *   RandomGenerator.name(1);   // "alice"
+   *   RandomGenerator.name(3);   // "jane mary smith"
+   *
+   *   // Generate test user names
+   *   const users = Array.from({ length: 10 }, () => ({
+   *   id: RandomGenerator.alphaNumeric(8),
+   *   name: RandomGenerator.name(),
+   *   email: `${RandomGenerator.name(1)}@test.com`
+   *   }));
+   *
+   *   // Create random author names for blog posts
+   *   const authorName = RandomGenerator.name();
+   *   ```
+   *
+   * @param length - Number of words in the name (default: random between 2-3)
+   * @returns A space-separated string resembling a human name
    */
   export const name = (length: number = randint(2, 3)): string =>
     paragraph(length)();
 
   /**
-   * Generate random paragraph.
+   * Generates a random paragraph with configurable sentence structure.
+   *
+   * Creates a paragraph consisting of a specified number of "sentences"
+   * (words). Each sentence is a random alphabetic string, and sentences are
+   * joined with spaces. Returns a currying function to allow configuration of
+   * word length ranges.
+   *
+   * @example
+   *   ```typescript
+   *   // Generate with default word lengths (3-7 characters)
+   *   RandomGenerator.paragraph(3)();           // "hello world test"
+   *   RandomGenerator.paragraph(5)();           // "lorem ipsum dolor sit amet"
+   *
+   *   // Custom word length ranges
+   *   RandomGenerator.paragraph(4)(2, 5);       // "ab cd ef gh"
+   *   RandomGenerator.paragraph(6)(8, 12);      // "verylongword anotherlongword..."
+   *
+   *   // Generate product descriptions
+   *   const description = RandomGenerator.paragraph(8)(4, 8);
+   *
+   *   // Create test content for forms
+   *   const placeholder = RandomGenerator.paragraph(3)(5, 10);
    *
-   * @param sentences Number of sentences
-   * @returns Paragraph generator
+   *   // Generate variable-length test data
+   *   const testTexts = Array.from({ length: 5 }, (_, i) =>
+   *     RandomGenerator.paragraph(i + 2)(3, 6)
+   *   );
+   *   ```;
+   *
+   * @param sentences - Number of sentences (words) in the paragraph (default:
+   *   random 2-5)
+   * @returns A currying function that accepts word length parameters
    */
   export const paragraph =
     (sentences: number = randint(2, 5)) =>
-    /**
-     * @param wordMin Minimum number of characters in a sentence
-     * @param wordMax Maximum number of characters in a sentence
-     * @returns Generated paragraph
-     */
     (wordMin: number = 3, wordMax: number = 7): string =>
       new Array(sentences)
         .fill("")
@@ -65,24 +182,48 @@ export namespace RandomGenerator {
         .join(" ");
 
   /**
-   * Generate random content.
+   * Generates random multi-paragraph content with customizable structure.
+   *
+   * Creates content consisting of multiple paragraphs separated by double
+   * newlines. Uses a triple-currying pattern to allow fine-grained control over
+   * content structure: paragraphs count → sentences per paragraph → word
+   * character lengths. Ideal for generating realistic-looking text content for
+   * testing.
+   *
+   * @example
+   *   ```typescript
+   *   // Generate with all defaults
+   *   const article = RandomGenerator.content()()();
+   *
+   *   // Specific structure: 5 paragraphs, 15-25 sentences each, 4-8 char words
+   *   const longContent = RandomGenerator.content(5)(15, 25)(4, 8);
+   *
+   *   // Short content with brief sentences
+   *   const shortContent = RandomGenerator.content(2)(5, 8)(2, 4);
+   *
+   *   // Generate blog post content
+   *   const blogPost = {
+   *     title: RandomGenerator.name(3),
+   *     content: RandomGenerator.content(4)(10, 20)(3, 7),
+   *     summary: RandomGenerator.paragraph(2)(5, 10)
+   *   };
+   *
+   *   // Create test data for CMS
+   *   const pages = Array.from({ length: 10 }, () => ({
+   *     id: RandomGenerator.alphaNumeric(8),
+   *     content: RandomGenerator.content(randint(2, 6))(8, 15)(4, 9)
+   *   }));
+   *
+   *   // Generate email content for testing
+   *   const emailBody = RandomGenerator.content(3)(5, 12)(3, 8);
+   *   ```;
    *
-   * @param paragraphs Number of paragraphs
-   * @returns Currying function
+   * @param paragraphs - Number of paragraphs to generate (default: random 3-8)
+   * @returns A currying function that accepts sentence count parameters
    */
   export const content =
     (paragraphs: number = randint(3, 8)) =>
-    /**
-     * @param sentenceMin Minimum number of sentences in a paragraph
-     * @param sentenceMax Maximum number of sentences in a paragraph
-     * @returns Currying function
-     */
     (sentenceMin: number = 10, sentenceMax: number = 40) =>
-    /**
-     * @param wordMin Minimum number of characters in a sentence
-     * @param wordMax Maximum number of characters in a sentence
-     * @returns Content generator
-     */
     (wordMin: number = 1, wordMax: number = 7): string =>
       new Array(paragraphs)
         .fill("")
@@ -92,10 +233,36 @@ export namespace RandomGenerator {
         .join("\n\n");
 
   /**
-   * Generate random substring.
+   * Extracts a random substring from the provided content string.
    *
-   * @param content Target content
-   * @returns Random substring
+   * Selects two random positions within the content and returns the substring
+   * between them. The starting position is always before the ending position.
+   * Automatically trims whitespace from the beginning and end of the result.
+   * Useful for creating excerpts, search terms, or partial content samples.
+   *
+   * @example
+   *   ```typescript
+   *   const text = "The quick brown fox jumps over the lazy dog";
+   *
+   *   RandomGenerator.substring(text);  // "quick brown fox"
+   *   RandomGenerator.substring(text);  // "jumps over"
+   *   RandomGenerator.substring(text);  // "fox jumps over the lazy"
+   *
+   *   // Generate search terms from content
+   *   const searchQuery = RandomGenerator.substring(articleContent);
+   *
+   *   // Create excerpts for previews
+   *   const excerpt = RandomGenerator.substring(fullBlogPost);
+   *
+   *   // Generate partial matches for testing search functionality
+   *   const partialMatch = RandomGenerator.substring(productDescription);
+   *
+   *   // Create random selections for highlight testing
+   *   const selectedText = RandomGenerator.substring(documentContent);
+   *   ```;
+   *
+   * @param content - The source string to extract a substring from
+   * @returns A trimmed substring of the original content
    */
   export const substring = (content: string): string => {
     const first: number = randint(0, content.length - 1);
@@ -105,11 +272,39 @@ export namespace RandomGenerator {
   };
 
   /**
-   * Generate random mobile number.
+   * Generates a random mobile phone number with customizable prefix.
+   *
+   * Creates a mobile phone number in the format: [prefix][3-4 digits][4
+   * digits]. The middle section is 3 digits if the random number is less than
+   * 1000, otherwise 4 digits. The last section is always 4 digits, zero-padded
+   * if necessary. Commonly used for generating Korean mobile phone numbers or
+   * similar formats.
    *
-   * @param prefix Prefix string, default is "010"
-   * @returns Random mobile number
-   * @example 0103340067
+   * @example
+   *   ```typescript
+   *   RandomGenerator.mobile();        // "0103341234"
+   *   RandomGenerator.mobile("011");   // "0119876543"
+   *   RandomGenerator.mobile("+82");   // "+8233412345"
+   *
+   *   // Generate test user phone numbers
+   *   const testUsers = Array.from({ length: 100 }, () => ({
+   *     name: RandomGenerator.name(),
+   *     phone: RandomGenerator.mobile(),
+   *     altPhone: RandomGenerator.mobile("011")
+   *   }));
+   *
+   *   // Create international phone numbers
+   *   const internationalPhone = RandomGenerator.mobile("+821");
+   *
+   *   // Generate contact list for testing
+   *   const contacts = ["010", "011", "016", "017", "018", "019"].map(prefix => ({
+   *     carrier: prefix,
+   *     number: RandomGenerator.mobile(prefix)
+   *   }));
+   *   ```;
+   *
+   * @param prefix - The prefix string for the phone number (default: "010")
+   * @returns A formatted mobile phone number string
    */
   export const mobile = (prefix: string = "010"): string =>
     [
@@ -122,11 +317,43 @@ export namespace RandomGenerator {
     ].join("");
 
   /**
-   * Generate random date.
+   * Generates a random date within a specified range from a starting point.
+   *
+   * Creates a currying function that accepts a range in milliseconds and
+   * returns a random date between the start date and start date + range. The
+   * range represents the maximum number of milliseconds to add to the starting
+   * date. Useful for generating timestamps, creation dates, or scheduling test
+   * data.
+   *
+   * @example
+   *   ```typescript
+   *   const now = new Date();
+   *   const oneDay = 24 * 60 * 60 * 1000;
+   *   const oneMonth = 30 * oneDay;
+   *
+   *   // Random date within the next 30 days
+   *   const futureDate = RandomGenerator.date(now)(oneMonth);
+   *
+   *   // Random date within the past week
+   *   const pastWeek = new Date(now.getTime() - 7 * oneDay);
+   *   const recentDate = RandomGenerator.date(pastWeek)(7 * oneDay);
    *
-   * @param from Start date
-   * @param range Range of random milliseconds
-   * @returns Random date
+   *   // Generate random creation dates for test data
+   *   const startOfYear = new Date(2024, 0, 1);
+   *   const endOfYear = new Date(2024, 11, 31).getTime() - startOfYear.getTime();
+   *   const randomCreationDate = RandomGenerator.date(startOfYear)(endOfYear);
+   *
+   *   // Create test events with random timestamps
+   *   const events = Array.from({ length: 50 }, () => ({
+   *     id: RandomGenerator.alphaNumeric(8),
+   *     title: RandomGenerator.name(2),
+   *     createdAt: RandomGenerator.date(new Date())(oneMonth),
+   *     scheduledFor: RandomGenerator.date(new Date())(oneMonth * 3)
+   *   }));
+   *   ```;
+   *
+   * @param from - The starting date for the random range
+   * @returns A currying function that accepts a range in milliseconds
    */
   export const date =
     (from: Date) =>
@@ -134,11 +361,40 @@ export namespace RandomGenerator {
       new Date(from.getTime() + randint(0, range));
 
   /**
-   * Pick random elements from an array.
+   * Randomly samples a specified number of unique elements from an array.
+   *
+   * Selects random elements from the input array without replacement, ensuring
+   * all returned elements are unique. The sample size is automatically capped
+   * at the array length to prevent errors. Uses a Set-based approach to
+   * guarantee uniqueness of selected indices. Ideal for creating test datasets
+   * or selecting random subsets for validation.
+   *
+   * @example
+   *   ```typescript
+   *   const numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+   *
+   *   RandomGenerator.sample(numbers)(3);  // [2, 7, 9]
+   *   RandomGenerator.sample(numbers)(5);  // [1, 4, 6, 8, 10]
+   *   RandomGenerator.sample(numbers)(15); // [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] (capped at array length)
+   *
+   *   // Sample users for testing
+   *   const allUsers = await getUsersFromDatabase();
+   *   const testUsers = RandomGenerator.sample(allUsers)(10);
+   *
+   *   // Create random product selections
+   *   const featuredProducts = RandomGenerator.sample(allProducts)(5);
+   *
+   *   // Generate test data subsets
+   *   const validationSet = RandomGenerator.sample(trainingData)(100);
    *
-   * @param array Target array
-   * @param count Number of count to pick
-   * @returns Sampled array
+   *   // Random A/B testing groups
+   *   const groupA = RandomGenerator.sample(allParticipants)(50);
+   *   const remaining = allParticipants.filter(p => !groupA.includes(p));
+   *   const groupB = RandomGenerator.sample(remaining)(50);
+   *   ```;
+   *
+   * @param array - The source array to sample from
+   * @returns A currying function that accepts the desired sample count
    */
   export const sample =
     <T>(array: T[]) =>
@@ -150,10 +406,43 @@ export namespace RandomGenerator {
     };
 
   /**
-   * Pick random element from an array.
+   * Randomly selects a single element from an array.
+   *
+   * Chooses one element at random from the provided array using uniform
+   * distribution. Each element has an equal probability of being selected. This
+   * is a convenience function equivalent to sampling with a count of 1, but
+   * returns the element directly rather than an array containing one element.
+   *
+   * @example
+   *   ```typescript
+   *   const colors = ['red', 'blue', 'green', 'yellow', 'purple'];
+   *   const fruits = ['apple', 'banana', 'orange', 'grape', 'kiwi'];
+   *
+   *   RandomGenerator.pick(colors);  // "blue"
+   *   RandomGenerator.pick(fruits);  // "apple"
+   *
+   *   // Select random configuration options
+   *   const randomTheme = RandomGenerator.pick(['light', 'dark', 'auto']);
+   *   const randomLocale = RandomGenerator.pick(['en', 'ko', 'ja', 'zh']);
+   *
+   *   // Choose random test scenarios
+   *   const testScenario = RandomGenerator.pick([
+   *     'happy_path',
+   *     'edge_case',
+   *     'error_condition',
+   *     'boundary_test'
+   *   ]);
+   *
+   *   // Random user role assignment
+   *   const userRole = RandomGenerator.pick(['admin', 'user', 'moderator']);
+   *
+   *   // Select random API endpoints for testing
+   *   const endpoints = ['/users', '/posts', '/comments', '/categories'];
+   *   const randomEndpoint = RandomGenerator.pick(endpoints);
+   *   ```;
    *
-   * @param array Target array
-   * @returns picked element
+   * @param array - The source array to pick an element from
+   * @returns A randomly selected element from the array
    */
   export const pick = <T>(array: T[]): T => array[randint(0, array.length - 1)];
 }