@atlantjs/arch 13.3.0 → 14.0.1

package/objects/time/time.edge.js

@@ -10,35 +10,414 @@ class TimeEdge {
         this.value = value;
         this.validate();
     }
+    // ==================== Getters ====================
+    /**
+     * Retorna as horas do tempo como número inteiro.
+     * @returns Número inteiro representando as horas (0-23)
+     * @example
+     * new TimeEdge("14:30").getHours() // 14
+     * new TimeEdge("08:00").getHours() // 8
+     */
+    getHours() {
+        return Number(this.value.split(":")[0]);
+    }
+    /**
+     * Retorna os minutos do tempo como número inteiro.
+     * @returns Número inteiro representando os minutos (0-59)
+     * @example
+     * new TimeEdge("14:30").getMinutes() // 30
+     * new TimeEdge("08:05").getMinutes() // 5
+     */
+    getMinutes() {
+        return Number(this.value.split(":")[1]);
+    }
+    /**
+     * Retorna o tempo total convertido em minutos.
+     * @returns Total de minutos representados pelo tempo
+     * @example
+     * new TimeEdge("01:30").toTotalMinutes() // 90
+     * new TimeEdge("02:00").toTotalMinutes() // 120
+     */
+    toTotalMinutes() {
+        return this.getHours() * 60 + this.getMinutes();
+    }
+    /**
+     * Retorna o tempo total convertido em segundos.
+     * @returns Total de segundos representados pelo tempo
+     * @example
+     * new TimeEdge("00:01").toTotalSeconds() // 60
+     * new TimeEdge("01:00").toTotalSeconds() // 3600
+     */
+    toTotalSeconds() {
+        return this.toTotalMinutes() * 60;
+    }
+    // ==================== Operações Aritméticas ====================
+    /**
+     * Subtrai um tempo de outro e retorna uma nova instância.
+     * @param time - Tempo a ser subtraído do valor atual
+     * @returns Nova instância de TimeEdge com o resultado da subtração
+     * @example
+     * new TimeEdge("10:30").subtract(new TimeEdge("01:00")) // TimeEdge("09:30")
+     * new TimeEdge("08:15").subtract(new TimeEdge("00:30")) // TimeEdge("07:45")
+     */
     subtract(time) {
         const momentTime = (0, moment_1.default)()
             .hours(this.getHours())
             .minutes(this.getMinutes());
         return new TimeEdge(momentTime.clone().subtract(time.toString()).format("HH:mm"));
     }
+    /**
+     * Soma um tempo ao valor atual e retorna uma nova instância.
+     * @param time - Tempo a ser somado ao valor atual
+     * @returns Nova instância de TimeEdge com o resultado da soma
+     * @example
+     * new TimeEdge("08:30").add(new TimeEdge("01:00")) // TimeEdge("09:30")
+     * new TimeEdge("23:30").add(new TimeEdge("01:00")) // TimeEdge("00:30")
+     */
     add(time) {
         const momentTime = (0, moment_1.default)()
             .hours(this.getHours())
             .minutes(this.getMinutes());
         return new TimeEdge(momentTime.clone().add(time.toString()).format("HH:mm"));
     }
+    /**
+     * Calcula a diferença absoluta entre dois tempos.
+     * @param time - Tempo para calcular a diferença
+     * @returns Nova instância de TimeEdge com a diferença absoluta
+     * @example
+     * new TimeEdge("10:00").difference(new TimeEdge("08:30")) // TimeEdge("01:30")
+     * new TimeEdge("08:30").difference(new TimeEdge("10:00")) // TimeEdge("01:30")
+     */
+    difference(time) {
+        const diffMinutes = Math.abs(this.toTotalMinutes() - time.toTotalMinutes());
+        const hours = Math.floor(diffMinutes / 60)
+            .toString()
+            .padStart(2, "0");
+        const minutes = (diffMinutes % 60).toString().padStart(2, "0");
+        return new TimeEdge(`${hours}:${minutes}`);
+    }
+    /**
+     * Multiplica o tempo por um fator numérico e retorna uma nova instância.
+     * @param factor - Fator de multiplicação
+     * @returns Nova instância de TimeEdge com o tempo multiplicado
+     * @example
+     * new TimeEdge("01:30").multiply(2) // TimeEdge("03:00")
+     * new TimeEdge("00:20").multiply(3) // TimeEdge("01:00")
+     */
+    multiply(factor) {
+        const totalMinutes = Math.round(this.toTotalMinutes() * factor);
+        const hours = Math.floor(totalMinutes / 60)
+            .toString()
+            .padStart(2, "0");
+        const minutes = (totalMinutes % 60).toString().padStart(2, "0");
+        return new TimeEdge(`${hours}:${minutes}`);
+    }
+    // ==================== Comparações ====================
+    /**
+     * Verifica se este tempo é igual a outro.
+     * @param time - Tempo para comparação
+     * @returns true se os tempos são iguais, false caso contrário
+     * @example
+     * new TimeEdge("10:30").isEqual(new TimeEdge("10:30")) // true
+     * new TimeEdge("10:30").isEqual(new TimeEdge("10:00")) // false
+     */
+    isEqual(time) {
+        return this.value === time.toString();
+    }
+    /**
+     * Verifica se este tempo é diferente de outro.
+     * @param time - Tempo para comparação
+     * @returns true se os tempos são diferentes, false caso contrário
+     * @example
+     * new TimeEdge("10:30").isDifferent(new TimeEdge("09:00")) // true
+     * new TimeEdge("10:30").isDifferent(new TimeEdge("10:30")) // false
+     */
+    isDifferent(time) {
+        return !this.isEqual(time);
+    }
+    /**
+     * Verifica se este tempo é maior que outro.
+     * @param time - Tempo para comparação
+     * @returns true se this > time, false caso contrário
+     * @example
+     * new TimeEdge("10:30").isGreaterThan(new TimeEdge("09:00")) // true
+     * new TimeEdge("08:00").isGreaterThan(new TimeEdge("10:00")) // false
+     */
+    isGreaterThan(time) {
+        return this.toTotalMinutes() > time.toTotalMinutes();
+    }
+    /**
+     * Verifica se este tempo é menor que outro.
+     * @param time - Tempo para comparação
+     * @returns true se this < time, false caso contrário
+     * @example
+     * new TimeEdge("08:00").isLessThan(new TimeEdge("10:00")) // true
+     * new TimeEdge("10:30").isLessThan(new TimeEdge("09:00")) // false
+     */
+    isLessThan(time) {
+        return this.toTotalMinutes() < time.toTotalMinutes();
+    }
+    /**
+     * Verifica se este tempo é maior ou igual a outro.
+     * @param time - Tempo para comparação
+     * @returns true se this >= time, false caso contrário
+     * @example
+     * new TimeEdge("10:30").isGreaterThanOrEqual(new TimeEdge("10:30")) // true
+     * new TimeEdge("10:30").isGreaterThanOrEqual(new TimeEdge("09:00")) // true
+     */
+    isGreaterThanOrEqual(time) {
+        return this.toTotalMinutes() >= time.toTotalMinutes();
+    }
+    /**
+     * Verifica se este tempo é menor ou igual a outro.
+     * @param time - Tempo para comparação
+     * @returns true se this <= time, false caso contrário
+     * @example
+     * new TimeEdge("08:00").isLessThanOrEqual(new TimeEdge("08:00")) // true
+     * new TimeEdge("08:00").isLessThanOrEqual(new TimeEdge("10:00")) // true
+     */
+    isLessThanOrEqual(time) {
+        return this.toTotalMinutes() <= time.toTotalMinutes();
+    }
+    /**
+     * Verifica se este tempo está entre dois limites (inclusive).
+     * @param start - Tempo mínimo do intervalo
+     * @param end - Tempo máximo do intervalo
+     * @returns true se o tempo está entre start e end, false caso contrário
+     * @example
+     * new TimeEdge("10:00").isBetween(new TimeEdge("08:00"), new TimeEdge("12:00")) // true
+     * new TimeEdge("14:00").isBetween(new TimeEdge("08:00"), new TimeEdge("12:00")) // false
+     */
+    isBetween(start, end) {
+        return this.isGreaterThanOrEqual(start) && this.isLessThanOrEqual(end);
+    }
+    // ==================== Validações ====================
+    /**
+     * Verifica se o tempo representa meia-noite (00:00).
+     * @returns true se o tempo é 00:00, false caso contrário
+     * @example
+     * new TimeEdge("00:00").isMidnight() // true
+     * new TimeEdge("12:00").isMidnight() // false
+     */
+    isMidnight() {
+        return this.value === "00:00";
+    }
+    /**
+     * Verifica se o tempo representa o meio-dia (12:00).
+     * @returns true se o tempo é 12:00, false caso contrário
+     * @example
+     * new TimeEdge("12:00").isNoon() // true
+     * new TimeEdge("00:00").isNoon() // false
+     */
+    isNoon() {
+        return this.value === "12:00";
+    }
+    /**
+     * Verifica se o tempo está no período da manhã (00:00 até 11:59).
+     * @returns true se o tempo é anterior às 12:00, false caso contrário
+     * @example
+     * new TimeEdge("09:00").isMorning() // true
+     * new TimeEdge("13:00").isMorning() // false
+     */
+    isMorning() {
+        return this.getHours() < 12;
+    }
+    /**
+     * Verifica se o tempo está no período da tarde (12:00 até 17:59).
+     * @returns true se o tempo está entre 12:00 e 17:59, false caso contrário
+     * @example
+     * new TimeEdge("14:00").isAfternoon() // true
+     * new TimeEdge("20:00").isAfternoon() // false
+     */
+    isAfternoon() {
+        return this.getHours() >= 12 && this.getHours() < 18;
+    }
+    /**
+     * Verifica se o tempo está no período da noite (18:00 até 23:59).
+     * @returns true se o tempo é a partir das 18:00, false caso contrário
+     * @example
+     * new TimeEdge("20:00").isEvening() // true
+     * new TimeEdge("14:00").isEvening() // false
+     */
+    isEvening() {
+        return this.getHours() >= 18;
+    }
+    // ==================== Clonagem e Imutabilidade ====================
+    /**
+     * Cria uma cópia independente desta instância de TimeEdge.
+     * @returns Nova instância com o mesmo valor de tempo
+     * @example
+     * const time1 = new TimeEdge("10:30");
+     * const time2 = time1.clone(); // instância independente com "10:30"
+     */
+    clone() {
+        return new TimeEdge(this.value);
+    }
+    /**
+     * Retorna uma nova instância com as horas alteradas.
+     * @param hours - Novo valor de horas (0-23)
+     * @returns Nova instância com as horas alteradas
+     * @example
+     * new TimeEdge("10:30").withHours(15) // TimeEdge("15:30")
+     */
+    withHours(hours) {
+        const paddedHours = hours.toString().padStart(2, "0");
+        const paddedMinutes = this.getMinutes().toString().padStart(2, "0");
+        return new TimeEdge(`${paddedHours}:${paddedMinutes}`);
+    }
+    /**
+     * Retorna uma nova instância com os minutos alterados.
+     * @param minutes - Novo valor de minutos (0-59)
+     * @returns Nova instância com os minutos alterados
+     * @example
+     * new TimeEdge("10:30").withMinutes(45) // TimeEdge("10:45")
+     */
+    withMinutes(minutes) {
+        const paddedHours = this.getHours().toString().padStart(2, "0");
+        const paddedMinutes = minutes.toString().padStart(2, "0");
+        return new TimeEdge(`${paddedHours}:${paddedMinutes}`);
+    }
+    // ==================== Formatação ====================
+    /**
+     * Retorna o tempo como string no formato HH:mm.
+     * @returns String no formato "HH:mm"
+     * @example
+     * new TimeEdge("14:30").toString() // "14:30"
+     */
     toString() {
         return this.value;
     }
+    /**
+     * Retorna o tempo no formato de 12 horas com AM/PM.
+     * @returns String no formato "hh:mm AM/PM"
+     * @example
+     * new TimeEdge("14:30").toFormat12h() // "02:30 PM"
+     * new TimeEdge("08:00").toFormat12h() // "08:00 AM"
+     */
+    toFormat12h() {
+        const hours = this.getHours();
+        const minutes = this.getMinutes().toString().padStart(2, "0");
+        const period = hours >= 12 ? "PM" : "AM";
+        const formattedHours = (hours % 12 || 12).toString().padStart(2, "0");
+        return `${formattedHours}:${minutes} ${period}`;
+    }
+    /**
+     * Retorna uma representação legível do tempo em horas e minutos por extenso.
+     * @returns String descritiva no formato "Xh Ym"
+     * @example
+     * new TimeEdge("14:30").toReadableString() // "14h 30m"
+     * new TimeEdge("08:05").toReadableString() // "8h 5m"
+     */
+    toReadableString() {
+        return `${this.getHours()}h ${this.getMinutes()}m`;
+    }
+    // ==================== Métodos Estáticos ====================
+    /**
+     * Cria um TimeEdge representando a hora atual do sistema.
+     * @returns Nova instância com o horário atual no formato HH:mm
+     * @example
+     * TimeEdge.now() // pode retornar TimeEdge("14:35") dependendo da hora atual
+     */
+    static now() {
+        return new TimeEdge((0, moment_1.default)().format("HH:mm"));
+    }
+    /**
+     * Cria um TimeEdge representando a meia-noite (00:00).
+     * @returns Nova instância com o valor "00:00"
+     * @example
+     * TimeEdge.midnight() // TimeEdge("00:00")
+     */
+    static midnight() {
+        return new TimeEdge("00:00");
+    }
+    /**
+     * Cria um TimeEdge representando o meio-dia (12:00).
+     * @returns Nova instância com o valor "12:00"
+     * @example
+     * TimeEdge.noon() // TimeEdge("12:00")
+     */
+    static noon() {
+        return new TimeEdge("12:00");
+    }
+    /**
+     * Cria um TimeEdge a partir de um total de minutos.
+     * @param totalMinutes - Total de minutos a converter para HH:mm
+     * @returns Nova instância com o tempo correspondente ao total de minutos
+     * @example
+     * TimeEdge.fromMinutes(90) // TimeEdge("01:30")
+     * TimeEdge.fromMinutes(125) // TimeEdge("02:05")
+     */
+    static fromMinutes(totalMinutes) {
+        const hours = Math.floor(totalMinutes / 60)
+            .toString()
+            .padStart(2, "0");
+        const minutes = (totalMinutes % 60).toString().padStart(2, "0");
+        return new TimeEdge(`${hours}:${minutes}`);
+    }
+    /**
+     * Retorna o maior tempo de uma lista.
+     * @param times - Array de instâncias de TimeEdge para comparação
+     * @returns A instância com o maior valor de tempo
+     * @throws {Error} Se o array estiver vazio
+     * @example
+     * TimeEdge.max([new TimeEdge("08:00"), new TimeEdge("14:30"), new TimeEdge("10:00")])
+     * // TimeEdge("14:30")
+     */
+    static max(times) {
+        if (times.length === 0) {
+            throw new Error("Cannot find max of an empty array of times.");
+        }
+        return times.reduce((max, time) => (time.isGreaterThan(max) ? time : max));
+    }
+    /**
+     * Retorna o menor tempo de uma lista.
+     * @param times - Array de instâncias de TimeEdge para comparação
+     * @returns A instância com o menor valor de tempo
+     * @throws {Error} Se o array estiver vazio
+     * @example
+     * TimeEdge.min([new TimeEdge("08:00"), new TimeEdge("14:30"), new TimeEdge("10:00")])
+     * // TimeEdge("08:00")
+     */
+    static min(times) {
+        if (times.length === 0) {
+            throw new Error("Cannot find min of an empty array of times.");
+        }
+        return times.reduce((min, time) => (time.isLessThan(min) ? time : min));
+    }
+    /**
+     * Soma uma lista de tempos e retorna o total.
+     * @param times - Array de instâncias de TimeEdge para somar
+     * @returns Nova instância com a soma total dos tempos
+     * @throws {Error} Se o array estiver vazio
+     * @example
+     * TimeEdge.sumAll([new TimeEdge("01:00"), new TimeEdge("02:30"), new TimeEdge("00:15")])
+     * // TimeEdge("03:45")
+     */
+    static sumAll(times) {
+        if (times.length === 0) {
+            throw new Error("Cannot sum an empty array of times.");
+        }
+        const totalMinutes = times.reduce((sum, time) => sum + time.toTotalMinutes(), 0);
+        return TimeEdge.fromMinutes(totalMinutes);
+    }
+    // ==================== Privados ====================
+    /**
+     * Valida o formato do tempo informado no construtor.
+     * @throws {Error} Se o formato não for HH:mm válido
+     */
     validate() {
         if (!this.isValidTimeFormat(this.value)) {
             throw new Error("Invalid time format. Please provide time in 'HH:mm' format.");
         }
     }
+    /**
+     * Verifica se uma string está no formato de tempo HH:mm válido.
+     * @param value - String a ser validada
+     * @returns true se o formato é válido, false caso contrário
+     */
     isValidTimeFormat(value) {
         const regex = /^(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9]$/;
         return regex.test(value);
     }
-    getHours() {
-        return Number(this.value.split(":")[0]);
-    }
-    getMinutes() {
-        return Number(this.value.split(":").reverse()[0]);
-    }
 }
 exports.TimeEdge = TimeEdge;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlantjs/arch",
-	"version": "13.3.0",
+	"version": "14.0.1",
 	"main": "index.js",
 	"license": "UNLICENSED",
 	"publishConfig": {