@atlantjs/arch 13.3.0 → 14.0.0

package/@tool-box/utils/random/random.d.ts

@@ -1,5 +1,173 @@
 export declare class Random {
+    /**
+     * Gera um número inteiro aleatório dentro de um intervalo (inclusivo).
+     * @param min - Valor mínimo do intervalo
+     * @param max - Valor máximo do intervalo
+     * @returns Número inteiro aleatório entre min e max
+     * @example
+     * Random.number(1, 10) // pode retornar qualquer inteiro entre 1 e 10
+     */
     static number(min: number, max: number): number;
+    /**
+     * Gera um número decimal (float) aleatório dentro de um intervalo.
+     * @param min - Valor mínimo do intervalo
+     * @param max - Valor máximo do intervalo
+     * @param precision - Número de casas decimais (padrão: 2)
+     * @returns Número decimal aleatório entre min e max
+     * @example
+     * Random.float(1, 10) // pode retornar algo como 4.73
+     * Random.float(1, 10, 4) // pode retornar algo como 4.7312
+     */
+    static float(min: number, max: number, precision?: number): number;
+    /**
+     * Gera um número inteiro positivo aleatório até um valor máximo.
+     * @param max - Valor máximo do intervalo (padrão: 100)
+     * @returns Número inteiro positivo aleatório entre 1 e max
+     * @example
+     * Random.positiveNumber() // pode retornar qualquer inteiro entre 1 e 100
+     * Random.positiveNumber(50) // pode retornar qualquer inteiro entre 1 e 50
+     */
+    static positiveNumber(max?: number): number;
+    /**
+     * Gera um número inteiro negativo aleatório até um valor mínimo.
+     * @param min - Valor mínimo do intervalo (padrão: -100)
+     * @returns Número inteiro negativo aleatório entre min e -1
+     * @example
+     * Random.negativeNumber() // pode retornar qualquer inteiro entre -100 e -1
+     * Random.negativeNumber(-50) // pode retornar qualquer inteiro entre -50 e -1
+     */
+    static negativeNumber(min?: number): number;
+    /**
+     * Retorna um valor aleatório de um enum.
+     * @template T - Tipo do enum
+     * @param anEnum - Enum do qual será selecionado o valor aleatório
+     * @returns Um valor aleatório do enum
+     * @example
+     * enum Color { Red, Green, Blue }
+     * Random.enum(Color) // pode retornar Color.Red, Color.Green ou Color.Blue
+     */
     static enum<T extends Record<string, unknown>>(anEnum: T): T[keyof T];
+    /**
+     * Retorna um valor aleatório de um enum, excluindo valores específicos.
+     * @template T - Tipo do enum
+     * @param anEnum - Enum do qual será selecionado o valor aleatório
+     * @param excepts - Array de valores do enum que devem ser excluídos da seleção
+     * @returns Um valor aleatório do enum que não está nos excepts
+     * @throws {Error} Se não houver valores válidos após aplicar as exclusões
+     * @example
+     * enum Color { Red, Green, Blue }
+     * Random.enumExcluding(Color, [Color.Red]) // retorna Green ou Blue
+     */
     static enumExcluding<T extends Record<string, unknown>>(anEnum: T, excepts: Array<T[keyof T]>): T[keyof T];
+    /**
+     * Gera uma string aleatória de caracteres alfanuméricos.
+     * @param length - Comprimento da string a ser gerada (padrão: 8)
+     * @returns String aleatória com o comprimento especificado
+     * @example
+     * Random.string() // pode retornar "aB3xKp9z"
+     * Random.string(4) // pode retornar "kR2m"
+     */
+    static string(length?: number): string;
+    /**
+     * Gera uma string aleatória contendo apenas letras (sem números).
+     * @param length - Comprimento da string a ser gerada (padrão: 8)
+     * @returns String aleatória com apenas letras
+     * @example
+     * Random.letters() // pode retornar "AbCdEfGh"
+     * Random.letters(4) // pode retornar "kRmZ"
+     */
+    static letters(length?: number): string;
+    /**
+     * Gera um UUID v4 aleatório no formato padrão.
+     * @returns UUID no formato xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+     * @example
+     * Random.uuid() // pode retornar "550e8400-e29b-41d4-a716-446655440000"
+     */
+    static uuid(): string;
+    /**
+     * Gera um valor booleano aleatório (true ou false).
+     * @returns true ou false aleatoriamente
+     * @example
+     * Random.boolean() // pode retornar true ou false
+     */
+    static boolean(): boolean;
+    /**
+     * Gera um valor booleano aleatório com uma probabilidade específica de ser true.
+     * @param probability - Probabilidade de retornar true (0 a 1, padrão: 0.5)
+     * @returns true com a probabilidade fornecida, false caso contrário
+     * @example
+     * Random.booleanWithProbability(0.8) // 80% de chance de retornar true
+     * Random.booleanWithProbability(0.2) // 20% de chance de retornar true
+     */
+    static booleanWithProbability(probability?: number): boolean;
+    /**
+     * Retorna um elemento aleatório de um array.
+     * @template T - Tipo dos elementos do array
+     * @param array - Array do qual será selecionado um elemento
+     * @returns Um elemento aleatório do array
+     * @throws {Error} Se o array estiver vazio
+     * @example
+     * Random.arrayElement([1, 2, 3, 4]) // pode retornar 1, 2, 3 ou 4
+     * Random.arrayElement(["a", "b", "c"]) // pode retornar "a", "b" ou "c"
+     */
+    static arrayElement<T>(array: T[]): T;
+    /**
+     * Retorna um elemento aleatório de um array, excluindo valores específicos.
+     * @template T - Tipo dos elementos do array
+     * @param array - Array do qual será selecionado um elemento
+     * @param excepts - Array de valores que devem ser excluídos da seleção
+     * @returns Um elemento aleatório do array que não está nos excepts
+     * @throws {Error} Se não houver elementos válidos após aplicar as exclusões
+     * @example
+     * Random.arrayElementExcluding([1, 2, 3, 4], [2, 4]) // pode retornar 1 ou 3
+     */
+    static arrayElementExcluding<T>(array: T[], excepts: T[]): T;
+    /**
+     * Retorna múltiplos elementos aleatórios únicos de um array.
+     * @template T - Tipo dos elementos do array
+     * @param array - Array do qual serão selecionados os elementos
+     * @param count - Quantidade de elementos a retornar
+     * @returns Array com elementos aleatórios únicos
+     * @throws {Error} Se count for maior que o tamanho do array
+     * @example
+     * Random.arrayElements([1, 2, 3, 4, 5], 3) // pode retornar [3, 1, 5]
+     */
+    static arrayElements<T>(array: T[], count: number): T[];
+    /**
+     * Retorna uma cópia do array com a ordem dos elementos embaralhada.
+     * @template T - Tipo dos elementos do array
+     * @param array - Array a ser embaralhado
+     * @returns Novo array com os mesmos elementos em ordem aleatória
+     * @example
+     * Random.shuffle([1, 2, 3, 4]) // pode retornar [3, 1, 4, 2]
+     */
+    static shuffle<T>(array: T[]): T[];
+    /**
+     * Gera uma data aleatória dentro de um intervalo.
+     * @param start - Data inicial do intervalo
+     * @param end - Data final do intervalo
+     * @returns Data aleatória entre start e end
+     * @example
+     * Random.date(new Date("2020-01-01"), new Date("2024-12-31"))
+     * // pode retornar qualquer data entre 2020 e 2024
+     */
+    static date(start: Date, end: Date): Date;
+    /**
+     * Gera uma data aleatória no passado a partir da data atual.
+     * @param daysAgo - Quantidade máxima de dias no passado (padrão: 365)
+     * @returns Data aleatória entre daysAgo dias atrás e hoje
+     * @example
+     * Random.pastDate() // data aleatória no último ano
+     * Random.pastDate(30) // data aleatória nos últimos 30 dias
+     */
+    static pastDate(daysAgo?: number): Date;
+    /**
+     * Gera uma data aleatória no futuro a partir da data atual.
+     * @param daysAhead - Quantidade máxima de dias no futuro (padrão: 365)
+     * @returns Data aleatória entre hoje e daysAhead dias à frente
+     * @example
+     * Random.futureDate() // data aleatória no próximo ano
+     * Random.futureDate(30) // data aleatória nos próximos 30 dias
+     */
+    static futureDate(daysAhead?: number): Date;
 }

package/@tool-box/utils/random/random.js

@@ -2,15 +2,81 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Random = void 0;
 class Random {
+    // ==================== Números ====================
+    /**
+     * Gera um número inteiro aleatório dentro de um intervalo (inclusivo).
+     * @param min - Valor mínimo do intervalo
+     * @param max - Valor máximo do intervalo
+     * @returns Número inteiro aleatório entre min e max
+     * @example
+     * Random.number(1, 10) // pode retornar qualquer inteiro entre 1 e 10
+     */
     static number(min, max) {
         return Math.floor(Math.random() * (max - min + 1)) + min;
     }
+    /**
+     * Gera um número decimal (float) aleatório dentro de um intervalo.
+     * @param min - Valor mínimo do intervalo
+     * @param max - Valor máximo do intervalo
+     * @param precision - Número de casas decimais (padrão: 2)
+     * @returns Número decimal aleatório entre min e max
+     * @example
+     * Random.float(1, 10) // pode retornar algo como 4.73
+     * Random.float(1, 10, 4) // pode retornar algo como 4.7312
+     */
+    static float(min, max, precision = 2) {
+        const value = Math.random() * (max - min) + min;
+        return Number(value.toFixed(precision));
+    }
+    /**
+     * Gera um número inteiro positivo aleatório até um valor máximo.
+     * @param max - Valor máximo do intervalo (padrão: 100)
+     * @returns Número inteiro positivo aleatório entre 1 e max
+     * @example
+     * Random.positiveNumber() // pode retornar qualquer inteiro entre 1 e 100
+     * Random.positiveNumber(50) // pode retornar qualquer inteiro entre 1 e 50
+     */
+    static positiveNumber(max = 100) {
+        return Random.number(1, max);
+    }
+    /**
+     * Gera um número inteiro negativo aleatório até um valor mínimo.
+     * @param min - Valor mínimo do intervalo (padrão: -100)
+     * @returns Número inteiro negativo aleatório entre min e -1
+     * @example
+     * Random.negativeNumber() // pode retornar qualquer inteiro entre -100 e -1
+     * Random.negativeNumber(-50) // pode retornar qualquer inteiro entre -50 e -1
+     */
+    static negativeNumber(min = -100) {
+        return Random.number(min, -1);
+    }
+    // ==================== Enums ====================
+    /**
+     * Retorna um valor aleatório de um enum.
+     * @template T - Tipo do enum
+     * @param anEnum - Enum do qual será selecionado o valor aleatório
+     * @returns Um valor aleatório do enum
+     * @example
+     * enum Color { Red, Green, Blue }
+     * Random.enum(Color) // pode retornar Color.Red, Color.Green ou Color.Blue
+     */
     static enum(anEnum) {
         const keys = Object.keys(anEnum).filter((x) => Number.isNaN(Number(x)));
         const randomKeyIndex = Math.floor(Math.random() * keys.length);
         const randomKey = keys[randomKeyIndex];
         return anEnum[randomKey];
     }
+    /**
+     * Retorna um valor aleatório de um enum, excluindo valores específicos.
+     * @template T - Tipo do enum
+     * @param anEnum - Enum do qual será selecionado o valor aleatório
+     * @param excepts - Array de valores do enum que devem ser excluídos da seleção
+     * @returns Um valor aleatório do enum que não está nos excepts
+     * @throws {Error} Se não houver valores válidos após aplicar as exclusões
+     * @example
+     * enum Color { Red, Green, Blue }
+     * Random.enumExcluding(Color, [Color.Red]) // retorna Green ou Blue
+     */
     static enumExcluding(anEnum, excepts) {
         const exceptKeys = excepts.map((value) => Object.keys(anEnum).find((key) => anEnum[key] === value));
         const validKeys = Object.keys(anEnum).filter((key) => Number.isNaN(Number(key)) && !exceptKeys.includes(key));
@@ -21,5 +87,174 @@ class Random {
         const randomKey = validKeys[randomKeyIndex];
         return anEnum[randomKey];
     }
+    // ==================== Strings ====================
+    /**
+     * Gera uma string aleatória de caracteres alfanuméricos.
+     * @param length - Comprimento da string a ser gerada (padrão: 8)
+     * @returns String aleatória com o comprimento especificado
+     * @example
+     * Random.string() // pode retornar "aB3xKp9z"
+     * Random.string(4) // pode retornar "kR2m"
+     */
+    static string(length = 8) {
+        const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+        return Array.from({ length }, () => chars.charAt(Math.floor(Math.random() * chars.length))).join("");
+    }
+    /**
+     * Gera uma string aleatória contendo apenas letras (sem números).
+     * @param length - Comprimento da string a ser gerada (padrão: 8)
+     * @returns String aleatória com apenas letras
+     * @example
+     * Random.letters() // pode retornar "AbCdEfGh"
+     * Random.letters(4) // pode retornar "kRmZ"
+     */
+    static letters(length = 8) {
+        const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
+        return Array.from({ length }, () => chars.charAt(Math.floor(Math.random() * chars.length))).join("");
+    }
+    /**
+     * Gera um UUID v4 aleatório no formato padrão.
+     * @returns UUID no formato xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
+     * @example
+     * Random.uuid() // pode retornar "550e8400-e29b-41d4-a716-446655440000"
+     */
+    static uuid() {
+        return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (char) => {
+            const random = (Math.random() * 16) | 0;
+            const value = char === "x" ? random : (random & 0x3) | 0x8;
+            return value.toString(16);
+        });
+    }
+    // ==================== Booleanos ====================
+    /**
+     * Gera um valor booleano aleatório (true ou false).
+     * @returns true ou false aleatoriamente
+     * @example
+     * Random.boolean() // pode retornar true ou false
+     */
+    static boolean() {
+        return Math.random() < 0.5;
+    }
+    /**
+     * Gera um valor booleano aleatório com uma probabilidade específica de ser true.
+     * @param probability - Probabilidade de retornar true (0 a 1, padrão: 0.5)
+     * @returns true com a probabilidade fornecida, false caso contrário
+     * @example
+     * Random.booleanWithProbability(0.8) // 80% de chance de retornar true
+     * Random.booleanWithProbability(0.2) // 20% de chance de retornar true
+     */
+    static booleanWithProbability(probability = 0.5) {
+        return Math.random() < probability;
+    }
+    // ==================== Arrays ====================
+    /**
+     * Retorna um elemento aleatório de um array.
+     * @template T - Tipo dos elementos do array
+     * @param array - Array do qual será selecionado um elemento
+     * @returns Um elemento aleatório do array
+     * @throws {Error} Se o array estiver vazio
+     * @example
+     * Random.arrayElement([1, 2, 3, 4]) // pode retornar 1, 2, 3 ou 4
+     * Random.arrayElement(["a", "b", "c"]) // pode retornar "a", "b" ou "c"
+     */
+    static arrayElement(array) {
+        if (array.length === 0) {
+            throw new Error("Cannot get a random element from an empty array.");
+        }
+        return array[Math.floor(Math.random() * array.length)];
+    }
+    /**
+     * Retorna um elemento aleatório de um array, excluindo valores específicos.
+     * @template T - Tipo dos elementos do array
+     * @param array - Array do qual será selecionado um elemento
+     * @param excepts - Array de valores que devem ser excluídos da seleção
+     * @returns Um elemento aleatório do array que não está nos excepts
+     * @throws {Error} Se não houver elementos válidos após aplicar as exclusões
+     * @example
+     * Random.arrayElementExcluding([1, 2, 3, 4], [2, 4]) // pode retornar 1 ou 3
+     */
+    static arrayElementExcluding(array, excepts) {
+        const validElements = array.filter((item) => !excepts.includes(item));
+        if (validElements.length === 0) {
+            throw new Error("No valid elements available after excluding 'excepts'.");
+        }
+        return Random.arrayElement(validElements);
+    }
+    /**
+     * Retorna múltiplos elementos aleatórios únicos de um array.
+     * @template T - Tipo dos elementos do array
+     * @param array - Array do qual serão selecionados os elementos
+     * @param count - Quantidade de elementos a retornar
+     * @returns Array com elementos aleatórios únicos
+     * @throws {Error} Se count for maior que o tamanho do array
+     * @example
+     * Random.arrayElements([1, 2, 3, 4, 5], 3) // pode retornar [3, 1, 5]
+     */
+    static arrayElements(array, count) {
+        if (count > array.length) {
+            throw new Error(`Cannot pick ${count} elements from an array of ${array.length}.`);
+        }
+        const shuffled = [...array].sort(() => Math.random() - 0.5);
+        return shuffled.slice(0, count);
+    }
+    /**
+     * Retorna uma cópia do array com a ordem dos elementos embaralhada.
+     * @template T - Tipo dos elementos do array
+     * @param array - Array a ser embaralhado
+     * @returns Novo array com os mesmos elementos em ordem aleatória
+     * @example
+     * Random.shuffle([1, 2, 3, 4]) // pode retornar [3, 1, 4, 2]
+     */
+    static shuffle(array) {
+        const shuffled = [...array];
+        for (let i = shuffled.length - 1; i > 0; i--) {
+            const j = Math.floor(Math.random() * (i + 1));
+            [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]];
+        }
+        return shuffled;
+    }
+    // ==================== Datas ====================
+    /**
+     * Gera uma data aleatória dentro de um intervalo.
+     * @param start - Data inicial do intervalo
+     * @param end - Data final do intervalo
+     * @returns Data aleatória entre start e end
+     * @example
+     * Random.date(new Date("2020-01-01"), new Date("2024-12-31"))
+     * // pode retornar qualquer data entre 2020 e 2024
+     */
+    static date(start, end) {
+        const startTime = start.getTime();
+        const endTime = end.getTime();
+        return new Date(startTime + Math.random() * (endTime - startTime));
+    }
+    /**
+     * Gera uma data aleatória no passado a partir da data atual.
+     * @param daysAgo - Quantidade máxima de dias no passado (padrão: 365)
+     * @returns Data aleatória entre daysAgo dias atrás e hoje
+     * @example
+     * Random.pastDate() // data aleatória no último ano
+     * Random.pastDate(30) // data aleatória nos últimos 30 dias
+     */
+    static pastDate(daysAgo = 365) {
+        const now = new Date();
+        const past = new Date();
+        past.setDate(past.getDate() - daysAgo);
+        return Random.date(past, now);
+    }
+    /**
+     * Gera uma data aleatória no futuro a partir da data atual.
+     * @param daysAhead - Quantidade máxima de dias no futuro (padrão: 365)
+     * @returns Data aleatória entre hoje e daysAhead dias à frente
+     * @example
+     * Random.futureDate() // data aleatória no próximo ano
+     * Random.futureDate(30) // data aleatória nos próximos 30 dias
+     */
+    static futureDate(daysAhead = 365) {
+        const now = new Date();
+        const future = new Date();
+        future.setDate(future.getDate() + daysAhead);
+        return Random.date(now, future);
+    }
 }
 exports.Random = Random;