@atlantjs/arch 13.2.0 → 14.0.0

package/objects/amount/amount.edge.d.ts

@@ -1,16 +1,394 @@
 import { AmountPolygon } from "./amount.polygon";
-export declare class AmountEdge<UnitsPoint> {
+export declare class AmountEdge<TUnitsPoint> {
     protected _value: number;
-    protected _unit: UnitsPoint;
-    constructor(_value: number, _unit: UnitsPoint);
+    protected _unit: TUnitsPoint;
+    constructor(_value: number, _unit: TUnitsPoint);
     get value(): number;
-    get unit(): UnitsPoint;
-    sum(amount: AmountEdge<UnitsPoint>): this;
-    subtract(amount: AmountEdge<UnitsPoint>): this;
-    divideBy(amount: AmountEdge<UnitsPoint> | number): this;
-    multiplyBy(amount: AmountEdge<UnitsPoint> | number): this;
-    changeUnit(unit: UnitsPoint): void;
-    changeValue(value: number): void;
+    get unit(): TUnitsPoint;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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: number): 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;
+    /**
+     * 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(): AmountEdge<TUnitsPoint>;
+    /**
+     * 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: AmountEdge<TUnitsPoint>): 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: AmountEdge<TUnitsPoint>): 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: AmountEdge<TUnitsPoint> | number): 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: AmountEdge<TUnitsPoint> | number): this;
+    /**
+     * 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: AmountEdge<TUnitsPoint> | number): 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: AmountEdge<TUnitsPoint>): AmountEdge<TUnitsPoint>;
+    /**
+     * 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: number): 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: AmountEdge<TUnitsPoint>): number;
+    /**
+     * 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: AmountEdge<TUnitsPoint>): boolean;
+    /**
+     * 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: AmountEdge<TUnitsPoint>): boolean;
+    /**
+     * 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: AmountEdge<TUnitsPoint>): boolean;
+    /**
+     * 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: AmountEdge<TUnitsPoint>): boolean;
+    /**
+     * 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: AmountEdge<TUnitsPoint>): boolean;
+    /**
+     * 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: AmountEdge<TUnitsPoint>): boolean;
+    /**
+     * 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: AmountEdge<TUnitsPoint>, max: AmountEdge<TUnitsPoint>): boolean;
+    /**
+     * 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(): boolean;
+    /**
+     * 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(): boolean;
+    /**
+     * 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(): boolean;
+    /**
+     * 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: TUnitsPoint): boolean;
+    /**
+     * 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(): AmountEdge<TUnitsPoint>;
+    /**
+     * 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: number): AmountEdge<TUnitsPoint>;
+    /**
+     * 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: TUnitsPoint): AmountEdge<TUnitsPoint>;
+    /**
+     * 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(): string;
-    toPolygon(precision?: number): AmountPolygon<UnitsPoint>;
+    /**
+     * 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?: string, precision?: number): string;
+    /**
+     * 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?: number): string;
+    /**
+     * 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?: number): AmountPolygon<TUnitsPoint>;
+    /**
+     * 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(): {
+        value: number;
+        unit: TUnitsPoint;
+    };
+    /**
+     * 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<T>(unit: T): AmountEdge<T>;
+    /**
+     * 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<T>(amounts: AmountEdge<T>[]): AmountEdge<T>;
+    /**
+     * 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<T>(amounts: AmountEdge<T>[]): AmountEdge<T>;
+    /**
+     * 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<T>(amounts: AmountEdge<T>[]): AmountEdge<T>;
+    /**
+     * 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<T>(amounts: AmountEdge<T>[]): AmountEdge<T>;
+    /**
+     * 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<T>(polygon: AmountPolygon<T>): AmountEdge<T>;
 }