@atlantjs/arch 13.3.0 → 14.0.1

package/objects/amount/amount.edge.js

@@ -19,10 +19,72 @@ class AmountEdge {
     get unit() {
         return this._unit;
     }
+    // ==================== Arredondamento e Precisão ====================
+    /**
+     * Arredonda o valor para o inteiro mais próximo.
+     * @returns this para permitir encadeamento de métodos
+     * @example
+     * const amount = new AmountEdge(5.7, MassUnitPoint.gram);
+     * amount.round(); // valor agora é 6
+     */
     round() {
         this._value = Math.round(this._value);
         return this;
     }
+    /**
+     * Arredonda o valor para cima (sempre para o próximo inteiro maior).
+     * @returns this para permitir encadeamento de métodos
+     * @example
+     * const amount = new AmountEdge(5.2, MassUnitPoint.gram);
+     * amount.ceil(); // valor agora é 6
+     */
+    ceil() {
+        this._value = Math.ceil(this._value);
+        return this;
+    }
+    /**
+     * Arredonda o valor para baixo (sempre para o próximo inteiro menor).
+     * @returns this para permitir encadeamento de métodos
+     * @example
+     * const amount = new AmountEdge(5.9, MassUnitPoint.gram);
+     * amount.floor(); // valor agora é 5
+     */
+    floor() {
+        this._value = Math.floor(this._value);
+        return this;
+    }
+    /**
+     * Arredonda o valor com uma precisão decimal específica.
+     * @param precision - Número de casas decimais desejadas
+     * @returns this para permitir encadeamento de métodos
+     * @example
+     * const amount = new AmountEdge(5.6789, MassUnitPoint.gram);
+     * amount.toFixed(2); // valor agora é 5.68
+     */
+    toFixed(precision) {
+        this._value = Number(this._value.toFixed(precision));
+        return this;
+    }
+    /**
+     * Retorna o valor absoluto (sem sinal).
+     * @returns this para permitir encadeamento de métodos
+     * @example
+     * const amount = new AmountEdge(-5.5, MassUnitPoint.gram);
+     * amount.abs(); // valor agora é 5.5
+     */
+    abs() {
+        this._value = Math.abs(this._value);
+        return this;
+    }
+    // ==================== Compactação de Unidades ====================
+    /**
+     * Compacta a quantidade para uma unidade mais apropriada baseado no valor.
+     * Por exemplo, 1000 gramas é convertido para 1 quilograma.
+     * @returns Nova instância com a unidade compactada
+     * @example
+     * const amount = new AmountEdge(1500, MassUnitPoint.gram);
+     * const compact = amount.compact(); // 1.5 kg
+     */
     compact() {
         const amountValue = new amount_value_edge_1.AmountValueEdge(this._value);
         // Mass
@@ -63,14 +125,42 @@ class AmountEdge {
         }
         return this;
     }
+    // ==================== Operações Aritméticas ====================
+    /**
+     * Soma outra quantidade ao valor atual.
+     * @param amount - Quantidade a ser somada
+     * @returns this para permitir encadeamento de métodos
+     * @example
+     * const amount1 = new AmountEdge(5, MassUnitPoint.gram);
+     * const amount2 = new AmountEdge(3, MassUnitPoint.gram);
+     * amount1.sum(amount2); // valor agora é 8
+     */
     sum(amount) {
         this._value += amount.value;
         return this;
     }
+    /**
+     * Subtrai outra quantidade do valor atual.
+     * @param amount - Quantidade a ser subtraída
+     * @returns this para permitir encadeamento de métodos
+     * @example
+     * const amount1 = new AmountEdge(8, MassUnitPoint.gram);
+     * const amount2 = new AmountEdge(3, MassUnitPoint.gram);
+     * amount1.subtract(amount2); // valor agora é 5
+     */
     subtract(amount) {
         this._value -= amount.value;
         return this;
     }
+    /**
+     * Divide o valor por um número ou outra quantidade.
+     * @param amount - Divisor (número ou AmountEdge)
+     * @returns this para permitir encadeamento de métodos
+     * @example
+     * const amount = new AmountEdge(10, MassUnitPoint.gram);
+     * amount.divideBy(2); // valor agora é 5
+     * amount.divideBy(new AmountEdge(2, MassUnitPoint.gram)); // valor agora é 2.5
+     */
     divideBy(amount) {
         if (typeof amount === "number") {
             this._value /= amount;
@@ -80,6 +170,15 @@ class AmountEdge {
         }
         return this;
     }
+    /**
+     * Multiplica o valor por um número ou outra quantidade.
+     * @param amount - Multiplicador (número ou AmountEdge)
+     * @returns this para permitir encadeamento de métodos
+     * @example
+     * const amount = new AmountEdge(5, MassUnitPoint.gram);
+     * amount.multiplyBy(2); // valor agora é 10
+     * amount.multiplyBy(new AmountEdge(3, MassUnitPoint.gram)); // valor agora é 30
+     */
     multiplyBy(amount) {
         if (typeof amount === "number") {
             this._value *= amount;
@@ -89,15 +188,277 @@ class AmountEdge {
         }
         return this;
     }
-    changeUnit(unit) {
-        this._unit = unit;
+    /**
+     * Calcula o resto da divisão (módulo) do valor atual.
+     * @param amount - Divisor (número ou AmountEdge)
+     * @returns this para permitir encadeamento de métodos
+     * @example
+     * const amount = new AmountEdge(10, MassUnitPoint.gram);
+     * amount.modBy(3); // valor agora é 1
+     */
+    modBy(amount) {
+        if (typeof amount === "number") {
+            this._value %= amount;
+        }
+        else {
+            this._value %= amount.value;
+        }
+        return this;
+    }
+    /**
+     * Calcula a diferença absoluta entre esta quantidade e outra.
+     * @param amount - Quantidade para comparação
+     * @returns Nova instância com a diferença absoluta
+     * @example
+     * const amount1 = new AmountEdge(10, MassUnitPoint.gram);
+     * const amount2 = new AmountEdge(3, MassUnitPoint.gram);
+     * const diff = amount1.difference(amount2); // 7
+     */
+    difference(amount) {
+        const diff = Math.abs(this._value - amount.value);
+        return new AmountEdge(diff, this._unit);
+    }
+    /**
+     * Aplica uma porcentagem sobre o valor atual.
+     * @param percentage - Porcentagem a aplicar (0-100)
+     * @returns this para permitir encadeamento de métodos
+     * @example
+     * const amount = new AmountEdge(100, MassUnitPoint.gram);
+     * amount.applyPercentage(20); // valor agora é 120 (100 + 20%)
+     */
+    applyPercentage(percentage) {
+        const percentageValue = (this._value * percentage) / 100;
+        this._value += percentageValue;
+        return this;
+    }
+    /**
+     * Calcula a porcentagem que esta quantidade representa de um total.
+     * @param total - Quantidade total
+     * @returns Porcentagem como número (0-100)
+     * @example
+     * const amount = new AmountEdge(25, MassUnitPoint.gram);
+     * const total = new AmountEdge(100, MassUnitPoint.gram);
+     * const percentage = amount.percentageOf(total); // 25
+     */
+    percentageOf(total) {
+        if (total.value === 0)
+            return 0;
+        return (this._value / total.value) * 100;
+    }
+    // ==================== Comparações ====================
+    /**
+     * Verifica se esta quantidade é igual a outra.
+     * @param amount - Quantidade para comparação
+     * @returns true se as quantidades são iguais (valor e unidade), false caso contrário
+     * @example
+     * const amount1 = new AmountEdge(5, MassUnitPoint.gram);
+     * const amount2 = new AmountEdge(5, MassUnitPoint.gram);
+     * amount1.isEqual(amount2); // true
+     */
+    isEqual(amount) {
+        return (guardian_1._.isEqual(this._value, amount.value) && guardian_1._.isEqual(this._unit, amount.unit));
+    }
+    /**
+     * Verifica se esta quantidade é diferente de outra.
+     * @param amount - Quantidade para comparação
+     * @returns true se as quantidades são diferentes, false caso contrário
+     * @example
+     * const amount1 = new AmountEdge(5, MassUnitPoint.gram);
+     * const amount2 = new AmountEdge(3, MassUnitPoint.gram);
+     * amount1.isDifferent(amount2); // true
+     */
+    isDifferent(amount) {
+        return !this.isEqual(amount);
+    }
+    /**
+     * Verifica se esta quantidade é maior que outra.
+     * @param amount - Quantidade para comparação
+     * @returns true se this.value > amount.value, false caso contrário
+     * @example
+     * const amount1 = new AmountEdge(10, MassUnitPoint.gram);
+     * const amount2 = new AmountEdge(5, MassUnitPoint.gram);
+     * amount1.isGreaterThan(amount2); // true
+     */
+    isGreaterThan(amount) {
+        return this._value > amount.value;
+    }
+    /**
+     * Verifica se esta quantidade é menor que outra.
+     * @param amount - Quantidade para comparação
+     * @returns true se this.value < amount.value, false caso contrário
+     * @example
+     * const amount1 = new AmountEdge(3, MassUnitPoint.gram);
+     * const amount2 = new AmountEdge(5, MassUnitPoint.gram);
+     * amount1.isLessThan(amount2); // true
+     */
+    isLessThan(amount) {
+        return this._value < amount.value;
+    }
+    /**
+     * Verifica se esta quantidade é maior ou igual a outra.
+     * @param amount - Quantidade para comparação
+     * @returns true se this.value >= amount.value, false caso contrário
+     * @example
+     * const amount1 = new AmountEdge(5, MassUnitPoint.gram);
+     * const amount2 = new AmountEdge(5, MassUnitPoint.gram);
+     * amount1.isGreaterThanOrEqual(amount2); // true
+     */
+    isGreaterThanOrEqual(amount) {
+        return this._value >= amount.value;
+    }
+    /**
+     * Verifica se esta quantidade é menor ou igual a outra.
+     * @param amount - Quantidade para comparação
+     * @returns true se this.value <= amount.value, false caso contrário
+     * @example
+     * const amount1 = new AmountEdge(5, MassUnitPoint.gram);
+     * const amount2 = new AmountEdge(5, MassUnitPoint.gram);
+     * amount1.isLessThanOrEqual(amount2); // true
+     */
+    isLessThanOrEqual(amount) {
+        return this._value <= amount.value;
+    }
+    /**
+     * Verifica se esta quantidade está entre dois limites (inclusive).
+     * @param min - Quantidade mínima
+     * @param max - Quantidade máxima
+     * @returns true se o valor está entre min e max, false caso contrário
+     * @example
+     * const amount = new AmountEdge(5, MassUnitPoint.gram);
+     * const min = new AmountEdge(1, MassUnitPoint.gram);
+     * const max = new AmountEdge(10, MassUnitPoint.gram);
+     * amount.isBetween(min, max); // true
+     */
+    isBetween(min, max) {
+        return this.isGreaterThanOrEqual(min) && this.isLessThanOrEqual(max);
     }
-    changeValue(value) {
-        this._value = value;
+    // ==================== Validações ====================
+    /**
+     * Verifica se o valor é zero.
+     * @returns true se this.value === 0, false caso contrário
+     * @example
+     * const amount = new AmountEdge(0, MassUnitPoint.gram);
+     * amount.isZero(); // true
+     */
+    isZero() {
+        return this._value === 0;
     }
+    /**
+     * Verifica se o valor é positivo (maior que zero).
+     * @returns true se this.value > 0, false caso contrário
+     * @example
+     * const amount = new AmountEdge(5, MassUnitPoint.gram);
+     * amount.isPositive(); // true
+     */
+    isPositive() {
+        return this._value > 0;
+    }
+    /**
+     * Verifica se o valor é negativo (menor que zero).
+     * @returns true se this.value < 0, false caso contrário
+     * @example
+     * const amount = new AmountEdge(-5, MassUnitPoint.gram);
+     * amount.isNegative(); // true
+     */
+    isNegative() {
+        return this._value < 0;
+    }
+    /**
+     * Verifica se a unidade é igual a uma unidade específica.
+     * @param unit - Unidade a comparar
+     * @returns true se a unidade é igual, false caso contrário
+     * @example
+     * const amount = new AmountEdge(5, MassUnitPoint.gram);
+     * amount.hasUnit(MassUnitPoint.gram); // true
+     * amount.hasUnit(MassUnitPoint.kilogram); // false
+     */
+    hasUnit(unit) {
+        return guardian_1._.isEqual(this._unit, unit);
+    }
+    // ==================== Clonagem e Imutabilidade ====================
+    /**
+     * Cria uma cópia independente desta quantidade.
+     * Útil para evitar mutações indesejadas.
+     * @returns Nova instância com os mesmos valores
+     * @example
+     * const amount1 = new AmountEdge(5, MassUnitPoint.gram);
+     * const amount2 = amount1.clone();
+     * amount2.multiplyBy(2); // amount1 continua 5, amount2 é 10
+     */
+    clone() {
+        return new AmountEdge(this._value, this._unit);
+    }
+    /**
+     * Retorna uma nova instância com o valor alterado.
+     * Mantém a imutabilidade da instância original.
+     * @param value - Novo valor
+     * @returns Nova instância com o valor alterado
+     * @example
+     * const amount = new AmountEdge(5, MassUnitPoint.gram);
+     * const newAmount = amount.withValue(10); // amount continua 5, newAmount é 10
+     */
+    withValue(value) {
+        return new AmountEdge(value, this._unit);
+    }
+    /**
+     * Retorna uma nova instância com a unidade alterada.
+     * Mantém a imutabilidade da instância original.
+     * @param unit - Nova unidade
+     * @returns Nova instância com a unidade alterada
+     * @example
+     * const amount = new AmountEdge(5, MassUnitPoint.gram);
+     * const newAmount = amount.withUnit(MassUnitPoint.kilogram);
+     */
+    withUnit(unit) {
+        return new AmountEdge(this._value, unit);
+    }
+    // ==================== Formatação ====================
+    /**
+     * Retorna uma representação em string da quantidade.
+     * @returns String no formato "valor unidade"
+     * @example
+     * const amount = new AmountEdge(5, MassUnitPoint.gram);
+     * amount.toString(); // "5 g"
+     */
     toString() {
         return `${this._value.toString()} ${this._unit}`;
     }
+    /**
+     * Formata a quantidade como string com separador de milhar e precisão decimal.
+     * @param locale - Localização para formatação (ex: 'en-US', 'pt-BR')
+     * @param precision - Número de casas decimais
+     * @returns String formatada
+     * @example
+     * const amount = new AmountEdge(1234.5678, MassUnitPoint.gram);
+     * amount.toFormattedString('pt-BR', 2); // "1.234,57 g"
+     */
+    toFormattedString(locale = "pt-BR", precision = 2) {
+        const formatted = this._value.toLocaleString(locale, {
+            minimumFractionDigits: precision,
+            maximumFractionDigits: precision,
+        });
+        return `${formatted} ${this._unit}`;
+    }
+    /**
+     * Retorna apenas o valor como string com precisão específica.
+     * @param precision - Número de casas decimais
+     * @returns String do valor formatado
+     * @example
+     * const amount = new AmountEdge(5.6789, MassUnitPoint.gram);
+     * amount.toValueString(2); // "5.68"
+     */
+    toValueString(precision = 2) {
+        return this._value.toFixed(precision);
+    }
+    // ==================== Conversão ====================
+    /**
+     * Converte a quantidade para um objeto Polygon.
+     * @param precision - Número de casas decimais
+     * @returns Objeto polygon com valor e unidade
+     * @example
+     * const amount = new AmountEdge(5.6789, MassUnitPoint.gram);
+     * amount.toPolygon(2); // { value: 5.68, unit: MassUnitPoint.gram }
+     */
     toPolygon(precision = 2) {
         return {
             value: this._unit === mass_unit_point_1.MassUnitPoint.gram
@@ -106,5 +467,133 @@ class AmountEdge {
             unit: this._unit,
         };
     }
+    /**
+     * Converte a quantidade para um objeto JSON.
+     * @returns Objeto JSON com value e unit
+     * @example
+     * const amount = new AmountEdge(5, MassUnitPoint.gram);
+     * amount.toJSON(); // { value: 5, unit: "g" }
+     */
+    toJSON() {
+        return {
+            value: this._value,
+            unit: this._unit,
+        };
+    }
+    // ==================== Métodos Estáticos ====================
+    /**
+     * Cria uma nova quantidade com valor zero.
+     * @template T - Tipo da unidade
+     * @param unit - Unidade da quantidade
+     * @returns Nova instância com valor zero
+     * @example
+     * const zero = AmountEdge.zero(MassUnitPoint.gram); // 0 g
+     */
+    static zero(unit) {
+        return new AmountEdge(0, unit);
+    }
+    /**
+     * Soma uma lista de quantidades.
+     * @template T - Tipo da unidade
+     * @param amounts - Array de quantidades a somar
+     * @returns Nova instância com a soma total
+     * @example
+     * const amounts = [
+     *   new AmountEdge(5, MassUnitPoint.gram),
+     *   new AmountEdge(3, MassUnitPoint.gram),
+     *   new AmountEdge(2, MassUnitPoint.gram),
+     * ];
+     * const total = AmountEdge.sumAll(amounts); // 10 g
+     */
+    static sumAll(amounts) {
+        if (amounts.length === 0) {
+            throw new Error("Cannot sum an empty array of amounts");
+        }
+        const total = amounts[0].clone();
+        for (let i = 1; i < amounts.length; i++) {
+            total.sum(amounts[i]);
+        }
+        return total;
+    }
+    /**
+     * Retorna a quantidade máxima de uma lista.
+     * @template T - Tipo da unidade
+     * @param amounts - Array de quantidades
+     * @returns Nova instância com o maior valor
+     * @example
+     * const amounts = [
+     *   new AmountEdge(5, MassUnitPoint.gram),
+     *   new AmountEdge(10, MassUnitPoint.gram),
+     *   new AmountEdge(3, MassUnitPoint.gram),
+     * ];
+     * const max = AmountEdge.max(amounts); // 10 g
+     */
+    static max(amounts) {
+        if (amounts.length === 0) {
+            throw new Error("Cannot find max of an empty array of amounts");
+        }
+        let maxAmount = amounts[0].clone();
+        for (let i = 1; i < amounts.length; i++) {
+            if (amounts[i].isGreaterThan(maxAmount)) {
+                maxAmount = amounts[i].clone();
+            }
+        }
+        return maxAmount;
+    }
+    /**
+     * Retorna a quantidade mínima de uma lista.
+     * @template T - Tipo da unidade
+     * @param amounts - Array de quantidades
+     * @returns Nova instância com o menor valor
+     * @example
+     * const amounts = [
+     *   new AmountEdge(5, MassUnitPoint.gram),
+     *   new AmountEdge(10, MassUnitPoint.gram),
+     *   new AmountEdge(3, MassUnitPoint.gram),
+     * ];
+     * const min = AmountEdge.min(amounts); // 3 g
+     */
+    static min(amounts) {
+        if (amounts.length === 0) {
+            throw new Error("Cannot find min of an empty array of amounts");
+        }
+        let minAmount = amounts[0].clone();
+        for (let i = 1; i < amounts.length; i++) {
+            if (amounts[i].isLessThan(minAmount)) {
+                minAmount = amounts[i].clone();
+            }
+        }
+        return minAmount;
+    }
+    /**
+     * Calcula a média de uma lista de quantidades.
+     * @template T - Tipo da unidade
+     * @param amounts - Array de quantidades
+     * @returns Nova instância com a média dos valores
+     * @example
+     * const amounts = [
+     *   new AmountEdge(10, MassUnitPoint.gram),
+     *   new AmountEdge(20, MassUnitPoint.gram),
+     *   new AmountEdge(30, MassUnitPoint.gram),
+     * ];
+     * const average = AmountEdge.average(amounts); // 20 g
+     */
+    static average(amounts) {
+        const total = AmountEdge.sumAll(amounts);
+        total.divideBy(amounts.length);
+        return total;
+    }
+    /**
+     * Cria uma quantidade a partir de um objeto Polygon.
+     * @template T - Tipo da unidade
+     * @param polygon - Objeto polygon com value e unit
+     * @returns Nova instância de AmountEdge
+     * @example
+     * const polygon = { value: 5, unit: MassUnitPoint.gram };
+     * const amount = AmountEdge.fromPolygon(polygon); // 5 g
+     */
+    static fromPolygon(polygon) {
+        return new AmountEdge(polygon.value, polygon.unit);
+    }
 }
 exports.AmountEdge = AmountEdge;