@atlantjs/arch 13.3.0 → 14.0.1

package/objects/primitives/number.edge.sketch.d.ts

@@ -1,13 +1,249 @@
 export declare abstract class NumberEdgeSketch {
     private value;
     constructor(value: number);
+    /**
+     * Retorna o valor numérico interno.
+     * @returns Número interno do edge
+     * @example
+     * new MyNumberEdge(42).toNumber() // 42
+     */
     toNumber(): number;
+    /**
+     * Retorna o valor como string.
+     * @returns String representando o número
+     * @example
+     * new MyNumberEdge(42).toString() // "42"
+     */
+    toString(): string;
+    /**
+     * Retorna o valor absoluto do número.
+     * @returns Valor absoluto (sempre positivo)
+     * @example
+     * new MyNumberEdge(-5).toAbsolute() // 5
+     * new MyNumberEdge(5).toAbsolute() // 5
+     */
+    toAbsolute(): number;
+    /**
+     * Retorna o número fixado com casas decimais.
+     * @param decimalPlaces - Número de casas decimais (padrão: 2)
+     * @returns String com o número formatado
+     * @example
+     * new MyNumberEdge(3.14159).toFixed(2) // "3.14"
+     * new MyNumberEdge(3).toFixed(2) // "3.00"
+     */
+    toFixed(decimalPlaces?: number): string;
+    /**
+     * Verifica se este valor é igual a outro.
+     * @param value - Número ou NumberEdgeSketch para comparação
+     * @returns true se os valores são iguais, false caso contrário
+     * @example
+     * new MyNumberEdge(5).isEqual(5) // true
+     * new MyNumberEdge(5).isEqual(6) // false
+     */
     isEqual(value: number | NumberEdgeSketch): boolean;
+    /**
+     * Verifica se este valor é diferente de outro.
+     * @param value - Número ou NumberEdgeSketch para comparação
+     * @returns true se os valores são diferentes, false caso contrário
+     * @example
+     * new MyNumberEdge(5).isDifferent(6) // true
+     * new MyNumberEdge(5).isDifferent(5) // false
+     */
     isDifferent(value: number | NumberEdgeSketch): boolean;
+    /**
+     * Verifica se este valor é maior que outro.
+     * @param value - Número ou NumberEdgeSketch para comparação
+     * @returns true se this > value, false caso contrário
+     * @example
+     * new MyNumberEdge(10).isBiggerThan(5) // true
+     * new MyNumberEdge(3).isBiggerThan(5) // false
+     */
     isBiggerThan(value: number | NumberEdgeSketch): boolean;
+    /**
+     * Verifica se este valor é menor que outro.
+     * @param value - Número ou NumberEdgeSketch para comparação
+     * @returns true se this < value, false caso contrário
+     * @example
+     * new MyNumberEdge(3).isSmallerThan(5) // true
+     * new MyNumberEdge(10).isSmallerThan(5) // false
+     */
     isSmallerThan(value: number | NumberEdgeSketch): boolean;
+    /**
+     * Verifica se este valor é maior ou igual a outro.
+     * @param value - Número ou NumberEdgeSketch para comparação
+     * @returns true se this >= value, false caso contrário
+     * @example
+     * new MyNumberEdge(5).isEqualOrBiggerThan(5) // true
+     * new MyNumberEdge(6).isEqualOrBiggerThan(5) // true
+     * new MyNumberEdge(4).isEqualOrBiggerThan(5) // false
+     */
     isEqualOrBiggerThan(value: number | NumberEdgeSketch): boolean;
+    /**
+     * Verifica se este valor é menor ou igual a outro.
+     * @param value - Número ou NumberEdgeSketch para comparação
+     * @returns true se this <= value, false caso contrário
+     * @example
+     * new MyNumberEdge(5).isEqualOrSmallerThan(5) // true
+     * new MyNumberEdge(4).isEqualOrSmallerThan(5) // true
+     * new MyNumberEdge(6).isEqualOrSmallerThan(5) // false
+     */
     isEqualOrSmallerThan(value: number | NumberEdgeSketch): boolean;
+    /**
+     * Verifica se este valor está entre dois limites (inclusivo).
+     * @param min - Limite mínimo
+     * @param max - Limite máximo
+     * @returns true se min <= this <= max, false caso contrário
+     * @example
+     * new MyNumberEdge(5).isBetween(1, 10) // true
+     * new MyNumberEdge(15).isBetween(1, 10) // false
+     */
     isBetween(min: number | NumberEdgeSketch, max: number | NumberEdgeSketch): boolean;
+    /**
+     * Verifica se o número é positivo (maior que zero).
+     * @returns true se o número é positivo, false caso contrário
+     * @example
+     * new MyNumberEdge(5).isPositive() // true
+     * new MyNumberEdge(-5).isPositive() // false
+     * new MyNumberEdge(0).isPositive() // false
+     */
+    isPositive(): boolean;
+    /**
+     * Verifica se o número é negativo (menor que zero).
+     * @returns true se o número é negativo, false caso contrário
+     * @example
+     * new MyNumberEdge(-5).isNegative() // true
+     * new MyNumberEdge(5).isNegative() // false
+     * new MyNumberEdge(0).isNegative() // false
+     */
+    isNegative(): boolean;
+    /**
+     * Verifica se o número é zero.
+     * @returns true se o número é zero, false caso contrário
+     * @example
+     * new MyNumberEdge(0).isZero() // true
+     * new MyNumberEdge(1).isZero() // false
+     */
+    isZero(): boolean;
+    /**
+     * Verifica se o número é inteiro (sem casas decimais).
+     * @returns true se o número é inteiro, false caso contrário
+     * @example
+     * new MyNumberEdge(5).isInteger() // true
+     * new MyNumberEdge(5.5).isInteger() // false
+     */
+    isInteger(): boolean;
+    /**
+     * Verifica se o número é float (possui casas decimais).
+     * @returns true se o número é float, false caso contrário
+     * @example
+     * new MyNumberEdge(5.5).isFloat() // true
+     * new MyNumberEdge(5).isFloat() // false
+     */
+    isFloat(): boolean;
+    /**
+     * Verifica se o número é par.
+     * @returns true se o número é par, false caso contrário
+     * @example
+     * new MyNumberEdge(4).isEven() // true
+     * new MyNumberEdge(5).isEven() // false
+     */
+    isEven(): boolean;
+    /**
+     * Verifica se o número é ímpar.
+     * @returns true se o número é ímpar, false caso contrário
+     * @example
+     * new MyNumberEdge(5).isOdd() // true
+     * new MyNumberEdge(4).isOdd() // false
+     */
+    isOdd(): boolean;
+    /**
+     * Soma este valor com outro e retorna o resultado.
+     * @param value - Número ou NumberEdgeSketch a somar
+     * @returns Resultado da soma
+     * @example
+     * new MyNumberEdge(5).add(3) // 8
+     */
+    add(value: number | NumberEdgeSketch): number;
+    /**
+     * Subtrai outro valor deste e retorna o resultado.
+     * @param value - Número ou NumberEdgeSketch a subtrair
+     * @returns Resultado da subtração
+     * @example
+     * new MyNumberEdge(10).subtract(3) // 7
+     */
+    subtract(value: number | NumberEdgeSketch): number;
+    /**
+     * Multiplica este valor por outro e retorna o resultado.
+     * @param value - Número ou NumberEdgeSketch a multiplicar
+     * @returns Resultado da multiplicação
+     * @example
+     * new MyNumberEdge(5).multiply(3) // 15
+     */
+    multiply(value: number | NumberEdgeSketch): number;
+    /**
+     * Divide este valor por outro e retorna o resultado.
+     * @param value - Número ou NumberEdgeSketch divisor
+     * @returns Resultado da divisão
+     * @throws {Error} Se o divisor for zero
+     * @example
+     * new MyNumberEdge(10).divide(2) // 5
+     */
+    divide(value: number | NumberEdgeSketch): number;
+    /**
+     * Retorna o resto da divisão deste valor por outro.
+     * @param value - Número ou NumberEdgeSketch divisor
+     * @returns Resto da divisão
+     * @throws {Error} Se o divisor for zero
+     * @example
+     * new MyNumberEdge(10).modulo(3) // 1
+     */
+    modulo(value: number | NumberEdgeSketch): number;
+    /**
+     * Eleva este valor à potência de outro.
+     * @param exponent - Expoente da potenciação
+     * @returns Resultado da potenciação
+     * @throws {TypeError} Se o expoente não for finito
+     * @example
+     * new MyNumberEdge(2).power(8) // 256
+     * new MyNumberEdge(5).power(2) // 25
+     */
+    power(exponent: number): number;
+    /**
+     * Retorna a raiz quadrada do número.
+     * @returns Raiz quadrada do valor
+     * @throws {Error} Se o número for negativo
+     * @example
+     * new MyNumberEdge(9).sqrt() // 3
+     * new MyNumberEdge(16).sqrt() // 4
+     */
+    sqrt(): number;
+    /**
+     * Arredonda o número para o inteiro mais próximo.
+     * @returns Número arredondado
+     * @example
+     * new MyNumberEdge(4.5).round() // 5
+     * new MyNumberEdge(4.4).round() // 4
+     */
+    round(): number;
+    /**
+     * Arredonda o número para baixo (floor).
+     * @returns Maior inteiro menor ou igual ao número
+     * @example
+     * new MyNumberEdge(4.9).floor() // 4
+     * new MyNumberEdge(-4.1).floor() // -5
+     */
+    floor(): number;
+    /**
+     * Arredonda o número para cima (ceil).
+     * @returns Menor inteiro maior ou igual ao número
+     * @example
+     * new MyNumberEdge(4.1).ceil() // 5
+     * new MyNumberEdge(-4.9).ceil() // -4
+     */
+    ceil(): number;
+    /**
+     * Valida se o valor fornecido no construtor é um número válido.
+     * @throws {TypeError} Se o valor for NaN
+     */
     private validate;
 }

package/objects/primitives/number.edge.sketch.js

@@ -7,50 +7,336 @@ class NumberEdgeSketch {
         this.value = value;
         this.validate(value);
     }
+    // ==================== Getters ====================
+    /**
+     * Retorna o valor numérico interno.
+     * @returns Número interno do edge
+     * @example
+     * new MyNumberEdge(42).toNumber() // 42
+     */
     toNumber() {
         return this.value;
     }
+    /**
+     * Retorna o valor como string.
+     * @returns String representando o número
+     * @example
+     * new MyNumberEdge(42).toString() // "42"
+     */
+    toString() {
+        return String(this.value);
+    }
+    /**
+     * Retorna o valor absoluto do número.
+     * @returns Valor absoluto (sempre positivo)
+     * @example
+     * new MyNumberEdge(-5).toAbsolute() // 5
+     * new MyNumberEdge(5).toAbsolute() // 5
+     */
+    toAbsolute() {
+        return Math.abs(this.value);
+    }
+    /**
+     * Retorna o número fixado com casas decimais.
+     * @param decimalPlaces - Número de casas decimais (padrão: 2)
+     * @returns String com o número formatado
+     * @example
+     * new MyNumberEdge(3.14159).toFixed(2) // "3.14"
+     * new MyNumberEdge(3).toFixed(2) // "3.00"
+     */
+    toFixed(decimalPlaces = 2) {
+        return this.value.toFixed(decimalPlaces);
+    }
+    // ==================== Comparações ====================
+    /**
+     * Verifica se este valor é igual a outro.
+     * @param value - Número ou NumberEdgeSketch para comparação
+     * @returns true se os valores são iguais, false caso contrário
+     * @example
+     * new MyNumberEdge(5).isEqual(5) // true
+     * new MyNumberEdge(5).isEqual(6) // false
+     */
     isEqual(value) {
-        if (value instanceof NumberEdgeSketch) {
-            return value.toNumber() === this.value;
-        }
-        return this.value === value;
+        const comparand = value instanceof NumberEdgeSketch ? value.toNumber() : value;
+        return this.value === comparand;
     }
+    /**
+     * Verifica se este valor é diferente de outro.
+     * @param value - Número ou NumberEdgeSketch para comparação
+     * @returns true se os valores são diferentes, false caso contrário
+     * @example
+     * new MyNumberEdge(5).isDifferent(6) // true
+     * new MyNumberEdge(5).isDifferent(5) // false
+     */
     isDifferent(value) {
-        if (value instanceof NumberEdgeSketch) {
-            return value.toNumber() !== this.value;
-        }
-        return this.value !== value;
+        const comparand = value instanceof NumberEdgeSketch ? value.toNumber() : value;
+        return this.value !== comparand;
     }
+    /**
+     * Verifica se este valor é maior que outro.
+     * @param value - Número ou NumberEdgeSketch para comparação
+     * @returns true se this > value, false caso contrário
+     * @example
+     * new MyNumberEdge(10).isBiggerThan(5) // true
+     * new MyNumberEdge(3).isBiggerThan(5) // false
+     */
     isBiggerThan(value) {
-        if (value instanceof NumberEdgeSketch) {
-            return value.toNumber() > this.value;
-        }
-        return this.value > value;
+        const comparand = value instanceof NumberEdgeSketch ? value.toNumber() : value;
+        return this.value > comparand; // 🐛 fix: estava value.toNumber() > this.value (invertido)
     }
+    /**
+     * Verifica se este valor é menor que outro.
+     * @param value - Número ou NumberEdgeSketch para comparação
+     * @returns true se this < value, false caso contrário
+     * @example
+     * new MyNumberEdge(3).isSmallerThan(5) // true
+     * new MyNumberEdge(10).isSmallerThan(5) // false
+     */
     isSmallerThan(value) {
-        if (value instanceof NumberEdgeSketch) {
-            return value.toNumber() < this.value;
-        }
-        return this.value < value;
+        const comparand = value instanceof NumberEdgeSketch ? value.toNumber() : value;
+        return this.value < comparand; // 🐛 fix: estava value.toNumber() < this.value (invertido)
     }
+    /**
+     * Verifica se este valor é maior ou igual a outro.
+     * @param value - Número ou NumberEdgeSketch para comparação
+     * @returns true se this >= value, false caso contrário
+     * @example
+     * new MyNumberEdge(5).isEqualOrBiggerThan(5) // true
+     * new MyNumberEdge(6).isEqualOrBiggerThan(5) // true
+     * new MyNumberEdge(4).isEqualOrBiggerThan(5) // false
+     */
     isEqualOrBiggerThan(value) {
-        if (value instanceof NumberEdgeSketch) {
-            return value.toNumber() >= this.value;
-        }
-        return this.value >= value;
+        const comparand = value instanceof NumberEdgeSketch ? value.toNumber() : value;
+        return this.value >= comparand; // 🐛 fix: estava value.toNumber() >= this.value (invertido)
     }
+    /**
+     * Verifica se este valor é menor ou igual a outro.
+     * @param value - Número ou NumberEdgeSketch para comparação
+     * @returns true se this <= value, false caso contrário
+     * @example
+     * new MyNumberEdge(5).isEqualOrSmallerThan(5) // true
+     * new MyNumberEdge(4).isEqualOrSmallerThan(5) // true
+     * new MyNumberEdge(6).isEqualOrSmallerThan(5) // false
+     */
     isEqualOrSmallerThan(value) {
-        if (value instanceof NumberEdgeSketch) {
-            return value.toNumber() <= this.value;
-        }
-        return this.value <= value;
+        const comparand = value instanceof NumberEdgeSketch ? value.toNumber() : value;
+        return this.value <= comparand; // 🐛 fix: estava value.toNumber() <= this.value (invertido)
     }
+    /**
+     * Verifica se este valor está entre dois limites (inclusivo).
+     * @param min - Limite mínimo
+     * @param max - Limite máximo
+     * @returns true se min <= this <= max, false caso contrário
+     * @example
+     * new MyNumberEdge(5).isBetween(1, 10) // true
+     * new MyNumberEdge(15).isBetween(1, 10) // false
+     */
     isBetween(min, max) {
         const minimus = min instanceof NumberEdgeSketch ? min.toNumber() : min;
         const maximus = max instanceof NumberEdgeSketch ? max.toNumber() : max;
         return guardian_1._.isBetween(this.value, minimus, maximus);
     }
+    // ==================== Verificações ====================
+    /**
+     * Verifica se o número é positivo (maior que zero).
+     * @returns true se o número é positivo, false caso contrário
+     * @example
+     * new MyNumberEdge(5).isPositive() // true
+     * new MyNumberEdge(-5).isPositive() // false
+     * new MyNumberEdge(0).isPositive() // false
+     */
+    isPositive() {
+        return this.value > 0;
+    }
+    /**
+     * Verifica se o número é negativo (menor que zero).
+     * @returns true se o número é negativo, false caso contrário
+     * @example
+     * new MyNumberEdge(-5).isNegative() // true
+     * new MyNumberEdge(5).isNegative() // false
+     * new MyNumberEdge(0).isNegative() // false
+     */
+    isNegative() {
+        return this.value < 0;
+    }
+    /**
+     * Verifica se o número é zero.
+     * @returns true se o número é zero, false caso contrário
+     * @example
+     * new MyNumberEdge(0).isZero() // true
+     * new MyNumberEdge(1).isZero() // false
+     */
+    isZero() {
+        return this.value === 0;
+    }
+    /**
+     * Verifica se o número é inteiro (sem casas decimais).
+     * @returns true se o número é inteiro, false caso contrário
+     * @example
+     * new MyNumberEdge(5).isInteger() // true
+     * new MyNumberEdge(5.5).isInteger() // false
+     */
+    isInteger() {
+        return Number.isInteger(this.value);
+    }
+    /**
+     * Verifica se o número é float (possui casas decimais).
+     * @returns true se o número é float, false caso contrário
+     * @example
+     * new MyNumberEdge(5.5).isFloat() // true
+     * new MyNumberEdge(5).isFloat() // false
+     */
+    isFloat() {
+        return !Number.isInteger(this.value);
+    }
+    /**
+     * Verifica se o número é par.
+     * @returns true se o número é par, false caso contrário
+     * @example
+     * new MyNumberEdge(4).isEven() // true
+     * new MyNumberEdge(5).isEven() // false
+     */
+    isEven() {
+        return this.value % 2 === 0;
+    }
+    /**
+     * Verifica se o número é ímpar.
+     * @returns true se o número é ímpar, false caso contrário
+     * @example
+     * new MyNumberEdge(5).isOdd() // true
+     * new MyNumberEdge(4).isOdd() // false
+     */
+    isOdd() {
+        return this.value % 2 !== 0;
+    }
+    // ==================== Operações Aritméticas ====================
+    /**
+     * Soma este valor com outro e retorna o resultado.
+     * @param value - Número ou NumberEdgeSketch a somar
+     * @returns Resultado da soma
+     * @example
+     * new MyNumberEdge(5).add(3) // 8
+     */
+    add(value) {
+        const operand = value instanceof NumberEdgeSketch ? value.toNumber() : value;
+        return this.value + operand;
+    }
+    /**
+     * Subtrai outro valor deste e retorna o resultado.
+     * @param value - Número ou NumberEdgeSketch a subtrair
+     * @returns Resultado da subtração
+     * @example
+     * new MyNumberEdge(10).subtract(3) // 7
+     */
+    subtract(value) {
+        const operand = value instanceof NumberEdgeSketch ? value.toNumber() : value;
+        return this.value - operand;
+    }
+    /**
+     * Multiplica este valor por outro e retorna o resultado.
+     * @param value - Número ou NumberEdgeSketch a multiplicar
+     * @returns Resultado da multiplicação
+     * @example
+     * new MyNumberEdge(5).multiply(3) // 15
+     */
+    multiply(value) {
+        const operand = value instanceof NumberEdgeSketch ? value.toNumber() : value;
+        return this.value * operand;
+    }
+    /**
+     * Divide este valor por outro e retorna o resultado.
+     * @param value - Número ou NumberEdgeSketch divisor
+     * @returns Resultado da divisão
+     * @throws {Error} Se o divisor for zero
+     * @example
+     * new MyNumberEdge(10).divide(2) // 5
+     */
+    divide(value) {
+        const operand = value instanceof NumberEdgeSketch ? value.toNumber() : value;
+        if (operand === 0) {
+            throw new Error(`${this.constructor.name}: division by zero is not allowed.`);
+        }
+        return this.value / operand;
+    }
+    /**
+     * Retorna o resto da divisão deste valor por outro.
+     * @param value - Número ou NumberEdgeSketch divisor
+     * @returns Resto da divisão
+     * @throws {Error} Se o divisor for zero
+     * @example
+     * new MyNumberEdge(10).modulo(3) // 1
+     */
+    modulo(value) {
+        const operand = value instanceof NumberEdgeSketch ? value.toNumber() : value;
+        if (operand === 0) {
+            throw new Error(`${this.constructor.name}: modulo by zero is not allowed.`);
+        }
+        return this.value % operand;
+    }
+    /**
+     * Eleva este valor à potência de outro.
+     * @param exponent - Expoente da potenciação
+     * @returns Resultado da potenciação
+     * @throws {TypeError} Se o expoente não for finito
+     * @example
+     * new MyNumberEdge(2).power(8) // 256
+     * new MyNumberEdge(5).power(2) // 25
+     */
+    power(exponent) {
+        if (!Number.isFinite(exponent)) {
+            throw new TypeError(`${this.constructor.name}: exponent should be a finite number.`);
+        }
+        return this.value ** exponent;
+    }
+    /**
+     * Retorna a raiz quadrada do número.
+     * @returns Raiz quadrada do valor
+     * @throws {Error} Se o número for negativo
+     * @example
+     * new MyNumberEdge(9).sqrt() // 3
+     * new MyNumberEdge(16).sqrt() // 4
+     */
+    sqrt() {
+        if (this.value < 0) {
+            throw new Error(`${this.constructor.name}: cannot calculate sqrt of a negative number.`);
+        }
+        return Math.sqrt(this.value);
+    }
+    /**
+     * Arredonda o número para o inteiro mais próximo.
+     * @returns Número arredondado
+     * @example
+     * new MyNumberEdge(4.5).round() // 5
+     * new MyNumberEdge(4.4).round() // 4
+     */
+    round() {
+        return Math.round(this.value);
+    }
+    /**
+     * Arredonda o número para baixo (floor).
+     * @returns Maior inteiro menor ou igual ao número
+     * @example
+     * new MyNumberEdge(4.9).floor() // 4
+     * new MyNumberEdge(-4.1).floor() // -5
+     */
+    floor() {
+        return Math.floor(this.value);
+    }
+    /**
+     * Arredonda o número para cima (ceil).
+     * @returns Menor inteiro maior ou igual ao número
+     * @example
+     * new MyNumberEdge(4.1).ceil() // 5
+     * new MyNumberEdge(-4.9).ceil() // -4
+     */
+    ceil() {
+        return Math.ceil(this.value);
+    }
+    // ==================== Privados ====================
+    /**
+     * Valida se o valor fornecido no construtor é um número válido.
+     * @throws {TypeError} Se o valor for NaN
+     */
     validate(value) {
         if (Number.isNaN(value)) {
             throw new TypeError(`${this.constructor.name} should be valid.`);