@atlantjs/arch 13.2.0 → 14.0.0

package/@tool-box/utils/ducts/return-type.d.ts

@@ -1,22 +1,22 @@
-import { FalseyValues, IterType, SuccessReturn, ValueReturn } from "./common";
+import { FalseyValues, IterType, SuccessReturn as SuccessReturnSymbol, ValueReturn as ValueReturnSymbol } from "./common";
 import { FailureAbstract } from "../../../objects/failure/edges/failure.abstract";
-export type Success<SuccessReturn> = ReturnType<SuccessReturn, never>;
-export type Failure<FailureReturn> = ReturnType<never, FailureReturn>;
-export type Return<T, E> = ReturnType<T, E>;
+export type Success<TSuccess> = ReturnType<TSuccess, never>;
+export type Failure<TFailure> = ReturnType<never, TFailure>;
+export type Return<TSuccess, TFailure> = ReturnType<TSuccess, TFailure>;
 type From<T> = Exclude<T, Error | FalseyValues>;
-export declare class ReturnType<SuccessReturn, FailureReturn> {
-    readonly [SuccessReturn]: boolean;
-    readonly [ValueReturn]: SuccessReturn | FailureReturn | undefined;
-    constructor(value: SuccessReturn | FailureReturn | undefined, hasSuccess: boolean);
-    [Symbol.iterator](this: Return<SuccessReturn, FailureReturn>): IterType<SuccessReturn>;
-    hasSuccess(this: Return<SuccessReturn, FailureReturn>): this is Success<SuccessReturn>;
-    hasFailure(this: Return<SuccessReturn, FailureReturn>): this is Failure<FailureReturn>;
-    unwrap(this: Return<SuccessReturn, FailureReturn>): SuccessReturn;
-    unwrapFail(this: Return<SuccessReturn, FailureReturn>): FailureReturn;
-    unwrapOr(this: Return<SuccessReturn, FailureReturn>, def: SuccessReturn): SuccessReturn;
-    unwrapAnyway(this: Return<SuccessReturn, FailureReturn>): SuccessReturn | FailureReturn | undefined;
+export declare class ReturnType<TSuccess, TFailure> {
+    readonly [SuccessReturnSymbol]: boolean;
+    readonly [ValueReturnSymbol]: TSuccess | TFailure | undefined;
+    constructor(value: TSuccess | TFailure | undefined, hasSuccess: boolean);
+    [Symbol.iterator](this: Return<TSuccess, TFailure>): IterType<TSuccess>;
+    hasSuccess(this: Return<TSuccess, TFailure>): this is Success<TSuccess>;
+    hasFailure(this: Return<TSuccess, TFailure>): this is Failure<TFailure>;
+    unwrap(this: Return<TSuccess, TFailure>): TSuccess;
+    unwrapFail(this: Return<TSuccess, TFailure>): TFailure;
+    unwrapOr(this: Return<TSuccess, TFailure>, def: TSuccess): TSuccess;
+    unwrapAnyway(this: Return<TSuccess, TFailure>): TSuccess | TFailure | undefined;
 }
 export declare function Return<T>(val: T): Return<From<T>, (T extends Error ? T : never) | (Extract<FalseyValues, T> extends never ? never : null)>;
-export declare function Success<SuccessReturn>(successValue?: SuccessReturn): Success<SuccessReturn>;
-export declare function Failure<FailureReturn extends FailureAbstract | null | undefined>(failureValue?: FailureReturn): Failure<FailureReturn>;
+export declare function Success<TSuccess>(successValue?: TSuccess): Success<TSuccess>;
+export declare function Failure<TFailure extends FailureAbstract | Error | null | undefined>(failureValue?: TFailure): Failure<TFailure>;
 export {};

package/@tool-box/utils/ducts/return-type.js

@@ -11,9 +11,17 @@ class ReturnType {
         this[common_1.SuccessReturn] = hasSuccess;
     }
     [Symbol.iterator]() {
-        return this[common_1.SuccessReturn]
-            ? this[common_1.ValueReturn][Symbol.iterator]()
-            : common_1.EmptyArray[Symbol.iterator]();
+        if (!this[common_1.SuccessReturn]) {
+            return common_1.EmptyArray[Symbol.iterator]();
+        }
+        const value = this[common_1.ValueReturn];
+        if (value !== null &&
+            value !== undefined &&
+            typeof value[Symbol.iterator] ===
+                "function") {
+            return value[Symbol.iterator]();
+        }
+        return common_1.EmptyArray[Symbol.iterator]();
     }
     hasSuccess() {
         return this[common_1.SuccessReturn];
@@ -34,7 +42,9 @@ class ReturnType {
         return this[common_1.ValueReturn];
     }
     unwrapOr(def) {
-        return this[common_1.SuccessReturn] ? this[common_1.ValueReturn] : def;
+        return this[common_1.SuccessReturn]
+            ? this[common_1.ValueReturn]
+            : def;
     }
     unwrapAnyway() {
         return this[common_1.ValueReturn];

package/@tool-box/utils/http-provider/http-provider.d.ts

@@ -7,5 +7,11 @@ export declare class HttpProvider {
     readonly baseUrl: string;
     protected readonly axios: AxiosInstance;
     constructor(baseUrl: string);
+    setDefaultHeader(key: string, value: string): void;
+    removeDefaultHeader(key: string): void;
+    setBearerToken(token: string): void;
     request(request: RequestAbstract): Promise<Return<HttpProviderSuccessResponse, HttpProviderFailureResponse>>;
+    private isSuccessStatus;
+    private buildFailureFromResponse;
+    private extractErrorMessage;
 }

package/@tool-box/utils/http-provider/http-provider.js

@@ -8,7 +8,6 @@ const axios_1 = __importDefault(require("axios"));
 const return_type_1 = require("../ducts/return-type");
 const http_provider_failure_response_1 = require("./http-provider-failure-response");
 const http_provider_success_response_1 = require("./http-provider-success-response");
-const guardian_1 = require("../type-guard/guardian");
 const http_status_codes_point_1 = require("../../../objects/@common/points/http-status-codes.point");
 function replaceUrlParams(url, params) {
     return url.replace(/:([a-zA-Z0-9_]+)/g, (_, key) => {
@@ -26,31 +25,61 @@ class HttpProvider {
             baseURL: baseUrl,
         });
     }
+    setDefaultHeader(key, value) {
+        this.axios.defaults.headers.common[key] = value;
+    }
+    removeDefaultHeader(key) {
+        delete this.axios.defaults.headers.common[key];
+    }
+    setBearerToken(token) {
+        this.setDefaultHeader("Authorization", `Bearer ${token}`);
+    }
     async request(request) {
+        let resolvedUrl = request.url;
         try {
-            let url = request.url;
-            if (guardian_1._.isNotUndefined(request.params)) {
-                url = replaceUrlParams(url, request.params);
+            if (request.params) {
+                resolvedUrl = replaceUrlParams(resolvedUrl, request.params);
             }
             const response = await this.axios.request({
-                url,
+                url: resolvedUrl,
                 method: request.method,
-                params: { ...request.queryParams },
+                params: request.queryParams,
                 data: request.payload,
-                headers: { ...request.headers },
+                headers: request.headers,
                 responseType: request.responseType,
-                validateStatus: (status) => {
-                    return true;
-                },
+                validateStatus: () => true,
             });
-            if (guardian_1._.or(guardian_1._.isEqual(response.status, http_status_codes_point_1.HttpStatusCodes.UNAUTHORIZED), guardian_1._.isEqual(response.status, http_status_codes_point_1.HttpStatusCodes.FORBIDDEN), guardian_1._.isEqual(response.status, http_status_codes_point_1.HttpStatusCodes.INTERNAL_SERVER_ERROR), guardian_1._.isEqual(response.status, http_status_codes_point_1.HttpStatusCodes.BAD_REQUEST), guardian_1._.isEqual(response.status, http_status_codes_point_1.HttpStatusCodes.NOT_FOUND))) {
-                return (0, return_type_1.Failure)(new http_provider_failure_response_1.HttpProviderFailureResponse(response.data.message, response.status, request.url));
+            if (!this.isSuccessStatus(response.status)) {
+                return (0, return_type_1.Failure)(this.buildFailureFromResponse(response, resolvedUrl));
             }
             return (0, return_type_1.Success)(new http_provider_success_response_1.HttpProviderSuccessResponse(response.status, response.data));
         }
-        catch {
-            return (0, return_type_1.Failure)(new http_provider_failure_response_1.HttpProviderFailureResponse("The request could not be completed. The server is currently unavailable.", http_status_codes_point_1.HttpStatusCodes.SERVICE_UNAVAILABLE, request.url));
+        catch (error) {
+            if (axios_1.default.isAxiosError(error) && error.response) {
+                return (0, return_type_1.Failure)(this.buildFailureFromResponse(error.response, resolvedUrl));
+            }
+            return (0, return_type_1.Failure)(new http_provider_failure_response_1.HttpProviderFailureResponse("The request could not be completed. The server is currently unavailable.", http_status_codes_point_1.HttpStatusCodes.SERVICE_UNAVAILABLE, resolvedUrl));
+        }
+    }
+    isSuccessStatus(status) {
+        return status >= 200 && status < 300;
+    }
+    buildFailureFromResponse(response, url) {
+        return new http_provider_failure_response_1.HttpProviderFailureResponse(this.extractErrorMessage(response.data, response.statusText), response.status, url);
+    }
+    extractErrorMessage(data, fallback) {
+        if (typeof data === "string" && data.trim().length > 0) {
+            return data;
+        }
+        if (data && typeof data === "object") {
+            const maybeMessage = data.message;
+            if (typeof maybeMessage === "string" && maybeMessage.trim().length > 0) {
+                return maybeMessage;
+            }
         }
+        return fallback?.trim()
+            ? fallback
+            : "The request failed. Please try again later.";
     }
 }
 exports.HttpProvider = HttpProvider;

package/@tool-box/utils/map/map.abstract.d.ts

@@ -1,6 +1,45 @@
 export declare abstract class MapAbstract<K, V> {
     protected abstract map: Map<K, V>;
+    /**
+     * Mantido por compatibilidade.
+     * Retorna o valor mapeado para a chave ou lança erro.
+     */
     toMap(key: K): V;
+    /**
+     * Retorna o valor mapeado para a chave ou lança erro.
+     */
+    get(key: K): V;
+    /**
+     * Retorna true se a chave existir no map.
+     */
+    has(key: K): boolean;
+    /**
+     * Retorna o valor ou undefined.
+     */
+    getOrUndefined(key: K): V | undefined;
+    /**
+     * Retorna a quantidade de itens.
+     */
+    size(): number;
+    /**
+     * Retorna true se o map estiver vazio.
+     */
+    isEmpty(): boolean;
+    /**
+     * Retorna todas as chaves.
+     */
+    keys(): K[];
+    /**
+     * Retorna todos os valores.
+     */
+    values(): V[];
+    /**
+     * Retorna todas as entradas.
+     */
+    entries(): Array<[K, V]>;
     protected getOrDefault(key: K, defaultValue: V): V;
     protected getOrThrow(key: K, errorMessage?: string): V;
+    protected set(key: K, value: V): void;
+    protected delete(key: K): boolean;
+    protected clear(): void;
 }

package/@tool-box/utils/map/map.abstract.js

@@ -1,20 +1,84 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MapAbstract = void 0;
-const guardian_1 = require("../type-guard/guardian");
 class MapAbstract {
+    /**
+     * Mantido por compatibilidade.
+     * Retorna o valor mapeado para a chave ou lança erro.
+     */
     toMap(key) {
         return this.getOrThrow(key);
     }
+    /**
+     * Retorna o valor mapeado para a chave ou lança erro.
+     */
+    get(key) {
+        return this.getOrThrow(key);
+    }
+    /**
+     * Retorna true se a chave existir no map.
+     */
+    has(key) {
+        return this.map.has(key);
+    }
+    /**
+     * Retorna o valor ou undefined.
+     */
+    getOrUndefined(key) {
+        return this.map.get(key);
+    }
+    /**
+     * Retorna a quantidade de itens.
+     */
+    size() {
+        return this.map.size;
+    }
+    /**
+     * Retorna true se o map estiver vazio.
+     */
+    isEmpty() {
+        return this.map.size === 0;
+    }
+    /**
+     * Retorna todas as chaves.
+     */
+    keys() {
+        return Array.from(this.map.keys());
+    }
+    /**
+     * Retorna todos os valores.
+     */
+    values() {
+        return Array.from(this.map.values());
+    }
+    /**
+     * Retorna todas as entradas.
+     */
+    entries() {
+        return Array.from(this.map.entries());
+    }
     getOrDefault(key, defaultValue) {
-        return this.map.get(key) ?? defaultValue;
+        // bug fix: usar has() evita confundir chave existente com valor undefined
+        if (!this.map.has(key)) {
+            return defaultValue;
+        }
+        return this.map.get(key);
     }
     getOrThrow(key, errorMessage = "Key not mapped") {
-        const value = this.map.get(key);
-        if (guardian_1._.isUndefined(value)) {
-            throw Error(errorMessage);
+        // bug fix: validar existência da chave com has(), não pelo valor retornado
+        if (!this.map.has(key)) {
+            throw new Error(errorMessage);
         }
-        return value;
+        return this.map.get(key);
+    }
+    set(key, value) {
+        this.map.set(key, value);
+    }
+    delete(key) {
+        return this.map.delete(key);
+    }
+    clear() {
+        this.map.clear();
     }
 }
 exports.MapAbstract = MapAbstract;

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;
 }