@atlantjs/arch 13.2.0 → 14.0.0

package/@tool-box/utils/datatypes/string-utils.js

@@ -1,38 +1,324 @@
 "use strict";
+// ==================== Transformação de Casing ====================
+/**
+ * Converte a string para o formato kebab-case.
+ * Separa palavras com hífen e converte tudo para minúsculas.
+ * @returns String no formato kebab-case
+ * @example
+ * "helloWorld".toKebabCase() // "hello-world"
+ * "FooBarBaz".toKebabCase() // "foo-bar-baz"
+ */
 String.prototype.toKebabCase = function () {
     return this.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
 };
+/**
+ * Converte a string para o formato snake_case.
+ * Separa palavras com underscore e converte tudo para minúsculas.
+ * @returns String no formato snake_case
+ * @example
+ * "helloWorld".toSnakeCase() // "hello_world"
+ * "FooBarBaz".toSnakeCase() // "foo_bar_baz"
+ */
 String.prototype.toSnakeCase = function () {
     return this.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase();
 };
+/**
+ * Converte a string para o formato camelCase.
+ * Remove espaços e capitaliza a primeira letra de cada palavra, exceto a primeira.
+ * @returns String no formato camelCase
+ * @example
+ * "hello world".toCamelCase() // "helloWorld"
+ * "foo bar baz".toCamelCase() // "fooBarBaz"
+ */
+String.prototype.toCamelCase = function () {
+    return this.valueOf()
+        .replace(/(?:^\w|[A-Z]|\b\w|\s+)/g, (match, index) => index === 0 ? match.toLowerCase() : match.toUpperCase())
+        .replace(/\s+/g, "");
+};
+/**
+ * Converte a string para o formato PascalCase.
+ * Remove espaços e capitaliza a primeira letra de cada palavra.
+ * @returns String no formato PascalCase
+ * @example
+ * "hello world".toPascalCase() // "HelloWorld"
+ * "foo bar baz".toPascalCase() // "FooBarBaz"
+ */
 String.prototype.toPascalCase = function () {
-    return this.replace(/(?:^\w|[A-Z]|\b\w|\s+)/g, (match) => match.toUpperCase()).replace(/\s+/g, "");
+    return this.valueOf()
+        .replace(/(?:^\w|[A-Z]|\b\w|\s+)/g, (match) => match.toUpperCase())
+        .replace(/\s+/g, "");
 };
-String.prototype.sanitize = function () {
-    return this.replace(/\s+/g, " ").trim();
+/**
+ * Converte a string para o formato Title Case.
+ * Capitaliza a primeira letra de cada palavra, mantendo as demais em minúsculo.
+ * @returns String no formato Title Case
+ * @example
+ * "hello world".toTitleCase() // "Hello World"
+ * "the quick brown fox".toTitleCase() // "The Quick Brown Fox"
+ */
+String.prototype.toTitleCase = function () {
+    return this.valueOf()
+        .toLowerCase()
+        .replace(/(?:^|\s)\w/g, (match) => match.toUpperCase());
 };
+/**
+ * Capitaliza a primeira letra de cada palavra da string.
+ * @returns String com a primeira letra de cada palavra em maiúsculo
+ * @example
+ * "hello world".capitalize() // "Hello World"
+ * "foo BAR".capitalize() // "Foo Bar"
+ */
 String.prototype.capitalize = function () {
-    return this.split(" ")
+    return this.valueOf()
+        .split(" ")
         .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
         .join(" ");
 };
-String.prototype.contains = function (substring) {
-    return this.indexOf(substring) !== -1;
+// ==================== Manipulação ====================
+/**
+ * Remove espaços extras e faz trim na string.
+ * Substitui múltiplos espaços consecutivos por um único espaço.
+ * @returns String sem espaços extras
+ * @example
+ * "  hello   world  ".sanitize() // "hello world"
+ * "foo  bar".sanitize() // "foo bar"
+ */
+String.prototype.sanitize = function () {
+    return this.valueOf().replace(/\s+/g, " ").trim();
 };
+/**
+ * Trunca a string para um comprimento máximo, adicionando "..." ao final.
+ * Se a string já for menor ou igual ao comprimento, retorna sem alteração.
+ * @param length - Comprimento máximo da string resultante (incluindo "...")
+ * @returns String truncada com "..." se necessário
+ * @example
+ * "Hello World".truncate(8) // "Hello..."
+ * "Hi".truncate(8) // "Hi"
+ */
 String.prototype.truncate = function (length) {
-    if (this.length <= length)
-        return this;
-    return `${this.substring(0, length - 3)}...`;
+    if (this.valueOf().length <= length)
+        return this.valueOf();
+    return `${this.valueOf().substring(0, length - 3)}...`;
 };
+/**
+ * Remove todos os espaços em branco da string.
+ * @returns String sem nenhum espaço em branco
+ * @example
+ * "hello world".removeWhitespace() // "helloworld"
+ * "  foo  bar  ".removeWhitespace() // "foobar"
+ */
 String.prototype.removeWhitespace = function () {
-    return this.replace(/\s+/g, "");
+    return this.valueOf().replace(/\s+/g, "");
 };
-String.prototype.isEmpty = function () {
-    return this.length === 0;
+/**
+ * Inverte os caracteres da string.
+ * @returns String com os caracteres em ordem inversa
+ * @example
+ * "hello".reverse() // "olleh"
+ * "abcd".reverse() // "dcba"
+ */
+String.prototype.reverse = function () {
+    return this.valueOf().split("").reverse().join("");
+};
+/**
+ * Repete a string um número específico de vezes.
+ * @param times - Número de vezes que a string será repetida
+ * @returns String repetida o número de vezes especificado
+ * @example
+ * "ab".repeat(3) // "ababab"
+ * "ha".repeat(2) // "haha"
+ */
+String.prototype.repeat = function (times) {
+    return this.valueOf().repeat(times);
+};
+/**
+ * Preenche o início da string com um caractere até atingir o comprimento especificado.
+ * @param length - Comprimento total desejado da string
+ * @param char - Caractere de preenchimento (padrão: " ")
+ * @returns String preenchida à esquerda
+ * @example
+ * "5".padStart(3, "0") // "005"
+ * "hi".padStart(5) // "   hi"
+ */
+String.prototype.padStart = function (length, char = " ") {
+    return this.valueOf().padStart(length, char);
+};
+/**
+ * Preenche o final da string com um caractere até atingir o comprimento especificado.
+ * @param length - Comprimento total desejado da string
+ * @param char - Caractere de preenchimento (padrão: " ")
+ * @returns String preenchida à direita
+ * @example
+ * "5".padEnd(3, "0") // "500"
+ * "hi".padEnd(5) // "hi   "
+ */
+String.prototype.padEnd = function (length, char = " ") {
+    return this.valueOf().padEnd(length, char);
+};
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Substitui todas as ocorrências de uma substring por outra.
+ * @param search - Substring/RegExp a ser substituída
+ * @param replacement - String de substituição ou função de substituição
+ * @returns Nova string com todas as ocorrências substituídas
+ * @example
+ * "foo bar foo".replaceAll("foo", "baz") // "baz bar baz"
+ */
+String.prototype.replaceAll = function (search, replacement) {
+    const source = this.valueOf();
+    if (search instanceof RegExp) {
+        const flags = search.flags.includes("g")
+            ? search.flags
+            : `${search.flags}g`;
+        return source.replace(new RegExp(search.source, flags), replacement);
+    }
+    const literalGlobalRegex = new RegExp(escapeRegExp(search), "g");
+    return source.replace(literalGlobalRegex, replacement);
+};
+// ==================== Verificação de Conteúdo ====================
+/**
+ * Verifica se a string contém uma substring específica.
+ * @param substring - Substring a ser procurada
+ * @returns true se a substring foi encontrada, false caso contrário
+ * @example
+ * "hello world".contains("world") // true
+ * "hello world".contains("foo") // false
+ */
+String.prototype.contains = function (substring) {
+    return this.valueOf().indexOf(substring) !== -1;
 };
+/**
+ * Verifica se a string começa com uma substring específica.
+ * @param substring - Substring a ser verificada no início
+ * @returns true se a string começa com a substring, false caso contrário
+ * @example
+ * "hello world".startsWith("hello") // true
+ * "hello world".startsWith("world") // false
+ */
+String.prototype.startsWith = function (substring) {
+    return this.valueOf().startsWith(substring);
+};
+/**
+ * Verifica se a string termina com uma substring específica.
+ * @param substring - Substring a ser verificada no final
+ * @returns true se a string termina com a substring, false caso contrário
+ * @example
+ * "hello world".endsWith("world") // true
+ * "hello world".endsWith("hello") // false
+ */
+String.prototype.endsWith = function (substring) {
+    return this.valueOf().endsWith(substring);
+};
+/**
+ * Conta o número de ocorrências de uma substring na string.
+ * @param substring - Substring a ser contada
+ * @returns Número de ocorrências encontradas
+ * @example
+ * "hello world hello".countOccurrences("hello") // 2
+ * "aaaa".countOccurrences("aa") // 2
+ */
+String.prototype.countOccurrences = function (substring) {
+    if (substring.length === 0)
+        return 0;
+    return this.valueOf().split(substring).length - 1;
+};
+// ==================== Validações ====================
+/**
+ * Verifica se a string está vazia (sem nenhum caractere).
+ * @returns true se a string não possui caracteres, false caso contrário
+ * @example
+ * "".isEmpty() // true
+ * "hello".isEmpty() // false
+ */
 String.prototype.isEmpty = function () {
-    return this.length > 0;
+    return this.valueOf().length === 0;
+};
+/**
+ * Verifica se a string possui conteúdo (não está vazia).
+ * @returns true se a string possui pelo menos um caractere, false caso contrário
+ * @example
+ * "hello".isFilled() // true
+ * "".isFilled() // false
+ */
+String.prototype.isFilled = function () {
+    return this.valueOf().length > 0;
+};
+/**
+ * Verifica se a string é um palíndromo (lida da mesma forma de frente para trás).
+ * @returns true se a string é um palíndromo, false caso contrário
+ * @example
+ * "racecar".isPalindrome() // true
+ * "hello".isPalindrome() // false
+ */
+String.prototype.isPalindrome = function () {
+    const clean = this.valueOf().toLowerCase().removeWhitespace();
+    return clean === clean.split("").reverse().join("");
+};
+/**
+ * Verifica se a string representa um valor numérico válido.
+ * @returns true se a string pode ser convertida para número, false caso contrário
+ * @example
+ * "42".isNumeric() // true
+ * "3.14".isNumeric() // true
+ * "hello".isNumeric() // false
+ */
+String.prototype.isNumeric = function () {
+    return !Number.isNaN(Number(this.valueOf())) && this.valueOf().isFilled();
+};
+/**
+ * Verifica se a string é um endereço de e-mail válido.
+ * @returns true se a string é um e-mail válido, false caso contrário
+ * @example
+ * "user@example.com".isEmail() // true
+ * "invalid-email".isEmail() // false
+ */
+String.prototype.isEmail = function () {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(this.valueOf());
+};
+/**
+ * Verifica se a string é uma URL válida.
+ * @returns true se a string é uma URL válida, false caso contrário
+ * @example
+ * "https://example.com".isURL() // true
+ * "not a url".isURL() // false
+ */
+String.prototype.isURL = function () {
+    try {
+        new URL(this.valueOf());
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Verifica se a string é um UUID (Universally Unique Identifier) válido.
+ * @returns true se a string é um UUID válido, false caso contrário
+ * @example
+ * "550e8400-e29b-41d4-a716-446655440000".isUUID() // true
+ * "invalid-uuid".isUUID() // false
+ */
+String.prototype.isUUID = function () {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(this.valueOf());
+};
+// ==================== Conversão ====================
+/**
+ * Converte a string para o formato Base64.
+ * @returns String codificada em Base64
+ * @example
+ * "hello".toBase64() // "aGVsbG8="
+ */
+String.prototype.toBase64 = function () {
+    return btoa(this.valueOf());
 };
+/**
+ * Decodifica a string do formato Base64.
+ * @returns String decodificada do Base64
+ * @example
+ * "aGVsbG8=".fromBase64() // "hello"
+ */
 String.prototype.fromBase64 = function () {
-    return atob(this.toString());
+    return atob(this.valueOf());
 };

package/@tool-box/utils/ducts/common.d.ts

@@ -1,9 +1,58 @@
+/**
+ * Symbol que representa o estado de sucesso em estruturas de dutos.
+ * @example
+ * const isSuccess = result[SuccessReturn];
+ */
 export declare const SuccessReturn: unique symbol;
+/**
+ * Symbol que representa o valor encapsulado em estruturas de dutos.
+ * @example
+ * const value = result[ValueReturn];
+ */
 export declare const ValueReturn: unique symbol;
+/**
+ * Symbol utilitário para armazenar referência de função/valor.
+ * @example
+ * const fnHolder = { [FnVal]: () => "ok" };
+ */
 export declare const FnVal: unique symbol;
+/**
+ * Array vazio imutável para reuso seguro.
+ * @example
+ * for (const item of EmptyArray) {
+ *   // não executa
+ * }
+ */
 export declare const EmptyArray: readonly any[];
+/**
+ * Conjunto de valores considerados falsey no domínio de dutos.
+ * @example
+ * const x: FalseyValues = "";
+ * const y: FalseyValues = 0;
+ */
 export type FalseyValues = false | null | undefined | 0 | 0n | "";
+/**
+ * Verifica se um valor deve ser tratado como "truthy".
+ * - Para Date, valida se o timestamp é válido (não-NaN).
+ * - Para demais tipos, usa coerção booleana.
+ *
+ * @param val Valor a ser verificado.
+ * @returns true quando o valor é considerado válido/truthy.
+ * @example
+ * isTruthy("abc"); // true
+ * isTruthy(""); // false
+ * isTruthy(new Date()); // true
+ * isTruthy(new Date("invalid")); // false
+ */
 export declare function isTruthy(val: unknown): boolean;
+/**
+ * Extrai o tipo do iterador de um tipo iterável.
+ * Retorna `unknown` quando o tipo não for iterável.
+ *
+ * @example
+ * type A = IterType<string[]>; // ArrayIterator<string>
+ * type B = IterType<number>; // unknown
+ */
 export type IterType<T> = T extends {
     [Symbol.iterator](): infer I;
 } ? I : unknown;

package/@tool-box/utils/ducts/common.js

@@ -3,12 +3,45 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.EmptyArray = exports.FnVal = exports.ValueReturn = exports.SuccessReturn = void 0;
 exports.isTruthy = isTruthy;
 const guardian_1 = require("../type-guard/guardian");
+/**
+ * Symbol que representa o estado de sucesso em estruturas de dutos.
+ * @example
+ * const isSuccess = result[SuccessReturn];
+ */
 exports.SuccessReturn = Symbol("SuccessReturn");
+/**
+ * Symbol que representa o valor encapsulado em estruturas de dutos.
+ * @example
+ * const value = result[ValueReturn];
+ */
 exports.ValueReturn = Symbol("ValueReturn");
+/**
+ * Symbol utilitário para armazenar referência de função/valor.
+ * @example
+ * const fnHolder = { [FnVal]: () => "ok" };
+ */
 exports.FnVal = Symbol("FnVal");
+/**
+ * Array vazio imutável para reuso seguro.
+ * @example
+ * for (const item of EmptyArray) {
+ *   // não executa
+ * }
+ */
 exports.EmptyArray = Object.freeze([]);
+/**
+ * Verifica se um valor deve ser tratado como "truthy".
+ * - Para Date, valida se o timestamp é válido (não-NaN).
+ * - Para demais tipos, usa coerção booleana.
+ *
+ * @param val Valor a ser verificado.
+ * @returns true quando o valor é considerado válido/truthy.
+ * @example
+ * isTruthy("abc"); // true
+ * isTruthy(""); // false
+ * isTruthy(new Date()); // true
+ * isTruthy(new Date("invalid")); // false
+ */
 function isTruthy(val) {
-    return val instanceof Date
-        ? guardian_1._.isEqual(val.getTime(), val.getTime())
-        : !!val;
+    return val instanceof Date ? guardian_1._.isEqual(val.getTime(), val.getTime()) : !!val;
 }

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)