@atlantjs/arch 13.3.0 → 14.0.1

package/@tool-box/utils/datatypes/boolean-utils.d.ts

@@ -6,4 +6,11 @@ interface Boolean {
     not(): boolean;
     and(value: boolean): boolean;
     or(value: boolean): boolean;
+    xor(value: boolean): boolean;
+    nand(value: boolean): boolean;
+    nor(value: boolean): boolean;
+    implies(value: boolean): boolean;
+    toNumber(): number;
+    toString(): string;
+    toggle(): boolean;
 }

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

@@ -1,22 +1,164 @@
 "use strict";
+/**
+ * Verifica se o valor booleano é verdadeiro (true).
+ * @returns true se o valor é true, false caso contrário
+ * @example
+ * (true).truthy() // true
+ * (false).truthy() // false
+ */
 Boolean.prototype.truthy = function () {
-    return this === true;
+    return this.valueOf() === true;
 };
+/**
+ * Verifica se o valor booleano é falso (false ou undefined).
+ * @returns true se o valor é false ou undefined, false caso contrário
+ * @example
+ * (false).falsy() // true
+ * (true).falsy() // false
+ */
 Boolean.prototype.falsy = function () {
-    return this === false || this === undefined;
+    return this.valueOf() === false || this.valueOf() === undefined;
 };
+/**
+ * Retorna o valor booleano negado (inversão lógica).
+ * @returns true se o valor é false, false se o valor é true
+ * @example
+ * (true).not() // false
+ * (false).not() // true
+ */
 Boolean.prototype.not = function () {
     return !this.valueOf();
 };
+/**
+ * Realiza a operação lógica AND (E) entre este valor e outro.
+ * Retorna true somente se ambos os valores forem true.
+ * @param value - Segundo operando booleano
+ * @returns true se ambos são true, false caso contrário
+ * @example
+ * (true).and(true) // true
+ * (true).and(false) // false
+ * (false).and(true) // false
+ */
 Boolean.prototype.and = function (value) {
     return this.valueOf() === true && value === true;
 };
+/**
+ * Realiza a operação lógica OR (OU) entre este valor e outro.
+ * Retorna true se pelo menos um dos valores for true.
+ * @param value - Segundo operando booleano
+ * @returns true se pelo menos um é true, false caso contrário
+ * @example
+ * (true).or(false) // true
+ * (false).or(false) // false
+ * (false).or(true) // true
+ */
 Boolean.prototype.or = function (value) {
     return this.valueOf() === true || value === true;
 };
+/**
+ * Verifica se este valor booleano é igual a outro.
+ * @param value - Valor booleano para comparação
+ * @returns true se os valores são iguais, false caso contrário
+ * @example
+ * (true).equal(true) // true
+ * (true).equal(false) // false
+ */
 Boolean.prototype.equal = function (value) {
-    return this === value;
+    return this.valueOf() === value;
 };
+/**
+ * Verifica se este valor booleano é diferente de outro.
+ * @param value - Valor booleano para comparação
+ * @returns true se os valores são diferentes, false caso contrário
+ * @example
+ * (true).different(false) // true
+ * (true).different(true) // false
+ */
 Boolean.prototype.different = function (value) {
-    return this !== value;
+    return this.valueOf() !== value;
+};
+/**
+ * Realiza a operação lógica XOR (OU exclusivo) entre este valor e outro.
+ * Retorna true somente se exatamente um dos valores for true.
+ * @param value - Segundo operando booleano
+ * @returns true se exatamente um é true, false caso contrário
+ * @example
+ * (true).xor(false) // true
+ * (true).xor(true) // false
+ * (false).xor(false) // false
+ */
+Boolean.prototype.xor = function (value) {
+    return this.valueOf() !== value;
+};
+/**
+ * Realiza a operação lógica NAND (NÃO-E) entre este valor e outro.
+ * Retorna false somente se ambos os valores forem true.
+ * @param value - Segundo operando booleano
+ * @returns false se ambos são true, true caso contrário
+ * @example
+ * (true).nand(true) // false
+ * (true).nand(false) // true
+ * (false).nand(false) // true
+ */
+Boolean.prototype.nand = function (value) {
+    return !(this.valueOf() === true && value === true);
+};
+/**
+ * Realiza a operação lógica NOR (NÃO-OU) entre este valor e outro.
+ * Retorna true somente se ambos os valores forem false.
+ * @param value - Segundo operando booleano
+ * @returns true se ambos são false, false caso contrário
+ * @example
+ * (false).nor(false) // true
+ * (true).nor(false) // false
+ * (true).nor(true) // false
+ */
+Boolean.prototype.nor = function (value) {
+    return !(this.valueOf() === true || value === true);
+};
+/**
+ * Realiza a operação lógica de implicação (→) entre este valor e outro.
+ * Retorna false somente se este valor é true e o outro é false.
+ * @param value - Consequente da implicação
+ * @returns false se this é true e value é false, true caso contrário
+ * @example
+ * (true).implies(true) // true
+ * (true).implies(false) // false
+ * (false).implies(true) // true
+ * (false).implies(false) // true
+ */
+Boolean.prototype.implies = function (value) {
+    return !this.valueOf() || value;
+};
+/**
+ * Converte o valor booleano para número.
+ * true é convertido para 1, false para 0.
+ * @returns 1 se o valor é true, 0 se o valor é false
+ * @example
+ * (true).toNumber() // 1
+ * (false).toNumber() // 0
+ */
+Boolean.prototype.toNumber = function () {
+    return this.valueOf() ? 1 : 0;
+};
+/**
+ * Converte o valor booleano para string.
+ * @returns "true" se o valor é true, "false" se o valor é false
+ * @example
+ * (true).toString() // "true"
+ * (false).toString() // "false"
+ */
+Boolean.prototype.toString = function () {
+    return this.valueOf() ? "true" : "false";
+};
+/**
+ * Retorna o valor booleano invertido sem alterar o original.
+ * Equivalente a `.not()`, porém semânticamente indica alternância de estado.
+ * @returns true se o valor é false, false se o valor é true
+ * @example
+ * (true).toggle() // false
+ * (false).toggle() // true
+ */
+Boolean.prototype.toggle = function () {
+    return !this.valueOf();
 };

package/@tool-box/utils/datatypes/string-utils.d.ts

@@ -1,14 +1,42 @@
+declare const _nativeStartsWith: {
+    (searchString: string, position?: number): boolean;
+    (substring: string): boolean;
+};
+declare const _nativeEndsWith: {
+    (searchString: string, endPosition?: number): boolean;
+    (substring: string): boolean;
+};
+declare const _nativeRepeat: {
+    (count: number): string;
+    (times: number): string;
+};
 interface String {
     toKebabCase(): string;
     toSnakeCase(): string;
+    toCamelCase(): string;
     toPascalCase(): string;
-    sanitize(): string;
-    capitalize(): string;
     toTitleCase(): string;
-    contains(substring: string): boolean;
-    truncate(length: number): String;
+    capitalize(): string;
+    sanitize(): string;
+    truncate(length: number): string;
     removeWhitespace(): string;
+    contains(substring: string): boolean;
+    startsWith(substring: string): boolean;
+    endsWith(substring: string): boolean;
     isEmpty(): boolean;
     isFilled(): boolean;
+    isPalindrome(): boolean;
+    isNumeric(): boolean;
+    isEmail(): boolean;
+    isURL(): boolean;
+    isUUID(): boolean;
+    countOccurrences(substring: string): number;
+    toBase64(): string;
     fromBase64(): string;
+    reverse(): string;
+    repeat(times: number): string;
+    padLeft(length: number, char?: string): string;
+    padRight(length: number, char?: string): string;
+    replaceAll(search: string | RegExp, replacement: string | ((substring: string, ...args: any[]) => string)): string;
 }
+declare function escapeRegExp(value: string): string;

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

@@ -1,38 +1,327 @@
 "use strict";
+const _nativeStartsWith = String.prototype.startsWith;
+const _nativeEndsWith = String.prototype.endsWith;
+const _nativeRepeat = String.prototype.repeat;
+// ==================== 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 _nativeRepeat.call(this, times);
+};
+/**
+ * Preenche o início (esquerda) 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".padLeft(3, "0") // "005"
+ * "hi".padLeft(5) // "   hi"
+ */
+String.prototype.padLeft = function (length, char = " ") {
+    return this.valueOf().padStart(length, char);
+};
+/**
+ * Preenche o final (direita) 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".padRight(3, "0") // "500"
+ * "hi".padRight(5) // "hi   "
+ */
+String.prototype.padRight = 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 _nativeStartsWith.call(this, 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 _nativeEndsWith.call(this, 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;
 }