@atlantjs/arch 13.3.0 → 14.0.0

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

@@ -1,24 +1,109 @@
 import { FalseyValues, IterType, SuccessReturn, ValueReturn } from "./common";
+/**
+ * Representa um Optional com valor presente.
+ * @example
+ * const value = Optional("ok");
+ * if (value.hasSomething()) {
+ *   value.unpack(); // "ok"
+ * }
+ */
 export type Something<T> = OptionalType<T> & {
     [SuccessReturn]: true;
 };
+/**
+ * Representa um Optional sem valor.
+ * @example
+ * const value = Optional("");
+ * value.hasNothing(); // true
+ */
 export type Nothing = OptionalType<never> & {
     [SuccessReturn]: false;
 };
+/**
+ * Tipo principal de Optional.
+ * @example
+ * const maybeName: Optional<string> = Optional("John");
+ */
 export type Optional<T> = OptionalType<T>;
 type From<T> = Exclude<T, Error | FalseyValues>;
 declare class OptionalType<T> {
     readonly [SuccessReturn]: boolean;
     readonly [ValueReturn]: T;
+    /**
+     * Cria uma nova instância de OptionalType.
+     * @param val Valor interno.
+     * @param something Indica presença de valor.
+     * @example
+     * const some = new (class extends OptionalType<string> {})("x", true);
+     */
     constructor(val: T, something: boolean);
+    /**
+     * Permite iteração quando houver valor iterável.
+     * @example
+     * const maybeArr = Optional([1, 2, 3]);
+     * for (const n of maybeArr) {
+     *   // 1, 2, 3
+     * }
+     */
     [Symbol.iterator](this: Optional<T>): IterType<T>;
+    /**
+     * Verifica se existe valor.
+     * @returns true se houver valor.
+     * @example
+     * Optional("abc").hasSomething(); // true
+     * Optional("").hasSomething(); // false
+     */
     hasSomething(this: Optional<T>): this is Something<T>;
+    /**
+     * Verifica se não existe valor.
+     * @returns true se não houver valor.
+     * @example
+     * Optional(null).hasNothing(); // true
+     */
     hasNothing(this: Optional<T>): this is Nothing;
+    /**
+     * Retorna o valor interno.
+     * @throws {Error} Se não houver valor.
+     * @example
+     * Optional(10).unpack(); // 10
+     */
     unpack(this: Optional<T>): T;
+    /**
+     * Retorna o valor interno mesmo quando vazio.
+     * @returns Valor interno ou undefined.
+     * @example
+     * Optional("x").unpackAnyway(); // "x"
+     * Optional("").unpackAnyway(); // undefined
+     */
     unpackAnyway(this: Optional<T>): T | undefined;
+    /**
+     * Retorna o valor interno ou valor padrão.
+     * @param def Valor padrão.
+     * @example
+     * Optional("").unpackOr("default"); // "default"
+     */
     unpackOr(this: Optional<T>, def: T): T;
+    /**
+     * Retorna o valor interno ou calcula valor padrão sob demanda.
+     * @param f Função para gerar valor padrão.
+     * @example
+     * Optional("").unpackOrElse(() => "fallback"); // "fallback"
+     */
     unpackOrElse(this: Optional<T>, f: () => T): T;
 }
+/**
+ * Cria um Optional a partir de um valor.
+ * Valores falsey e Error resultam em Nothing.
+ * @param val Valor de entrada.
+ * @example
+ * Optional("abc").hasSomething(); // true
+ * Optional(0).hasNothing(); // true
+ */
 export declare function Optional<T>(val: T): Optional<From<T>>;
+/**
+ * Singleton representando ausência de valor.
+ * @example
+ * Nothing.hasNothing(); // true
+ */
 export declare const Nothing: Readonly<OptionalType<never>>;
 export {};

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

@@ -4,44 +4,123 @@ exports.Nothing = void 0;
 exports.Optional = Optional;
 const common_1 = require("./common");
 class OptionalType {
+    /**
+     * Cria uma nova instância de OptionalType.
+     * @param val Valor interno.
+     * @param something Indica presença de valor.
+     * @example
+     * const some = new (class extends OptionalType<string> {})("x", true);
+     */
     constructor(val, something) {
         this[common_1.SuccessReturn] = something;
         this[common_1.ValueReturn] = val;
     }
+    /**
+     * Permite iteração quando houver valor iterável.
+     * @example
+     * const maybeArr = Optional([1, 2, 3]);
+     * for (const n of maybeArr) {
+     *   // 1, 2, 3
+     * }
+     */
     [Symbol.iterator]() {
         return this[common_1.SuccessReturn]
             ? this[common_1.ValueReturn][Symbol.iterator]()
             : common_1.EmptyArray[Symbol.iterator]();
     }
+    /**
+     * Verifica se existe valor.
+     * @returns true se houver valor.
+     * @example
+     * Optional("abc").hasSomething(); // true
+     * Optional("").hasSomething(); // false
+     */
     hasSomething() {
         return this[common_1.SuccessReturn];
     }
+    /**
+     * Verifica se não existe valor.
+     * @returns true se não houver valor.
+     * @example
+     * Optional(null).hasNothing(); // true
+     */
     hasNothing() {
         return !this[common_1.SuccessReturn];
     }
+    /**
+     * Retorna o valor interno.
+     * @throws {Error} Se não houver valor.
+     * @example
+     * Optional(10).unpack(); // 10
+     */
     unpack() {
         if (this[common_1.SuccessReturn]) {
             return this[common_1.ValueReturn];
         }
         throw new Error("Failed to unpack optional value. There is nothing in here");
     }
+    /**
+     * Retorna o valor interno mesmo quando vazio.
+     * @returns Valor interno ou undefined.
+     * @example
+     * Optional("x").unpackAnyway(); // "x"
+     * Optional("").unpackAnyway(); // undefined
+     */
     unpackAnyway() {
         return this[common_1.ValueReturn];
     }
+    /**
+     * Retorna o valor interno ou valor padrão.
+     * @param def Valor padrão.
+     * @example
+     * Optional("").unpackOr("default"); // "default"
+     */
     unpackOr(def) {
         return this[common_1.SuccessReturn] ? this[common_1.ValueReturn] : def;
     }
+    /**
+     * Retorna o valor interno ou calcula valor padrão sob demanda.
+     * @param f Função para gerar valor padrão.
+     * @example
+     * Optional("").unpackOrElse(() => "fallback"); // "fallback"
+     */
     unpackOrElse(f) {
         return this[common_1.SuccessReturn] ? this[common_1.ValueReturn] : f();
     }
 }
+/**
+ * Cria um Optional a partir de um valor.
+ * Valores falsey e Error resultam em Nothing.
+ * @param val Valor de entrada.
+ * @example
+ * Optional("abc").hasSomething(); // true
+ * Optional(0).hasNothing(); // true
+ */
 function Optional(val) {
     return from(val);
 }
+/**
+ * Cria um Optional no estado Something.
+ * @param val Valor presente.
+ * @example
+ * const some = Something("ok");
+ */
 function Something(val) {
     return new OptionalType(val, true);
 }
+/**
+ * Singleton representando ausência de valor.
+ * @example
+ * Nothing.hasNothing(); // true
+ */
 exports.Nothing = Object.freeze(new OptionalType(undefined, false));
+/**
+ * Converte valor para Optional conforme regra de truthy.
+ * @param val Valor de entrada.
+ * @example
+ * from("x").hasSomething(); // true
+ * from(false).hasNothing(); // true
+ */
 function from(val) {
     return (0, common_1.isTruthy)(val) && !(val instanceof Error)
         ? Something(val)

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;