@atlantjs/arch 15.7.6 → 15.7.8

package/src/objects/primitives/string.edge.sketch.js

@@ -0,0 +1,219 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StringEdgeSketch = void 0;
+class StringEdgeSketch {
+    value;
+    constructor(value) {
+        this.value = value;
+        this.sanitize();
+        this.validate();
+    }
+    // ==================== Getters ====================
+    /**
+     * Retorna o valor da string.
+     * @returns String interna do edge
+     * @example
+     * new MyStringEdge("hello").toString() // "hello"
+     */
+    toString() {
+        return this.value;
+    }
+    /**
+     * Retorna o comprimento da string.
+     * @returns Número de caracteres da string
+     * @example
+     * new MyStringEdge("hello").length() // 5
+     */
+    length() {
+        return this.value.length;
+    }
+    // ==================== Verificações ====================
+    /**
+     * Verifica se a string contém uma substring específica.
+     * @param value - Substring a ser procurada
+     * @returns true se a substring foi encontrada, false caso contrário
+     * @example
+     * new MyStringEdge("hello world").has("world") // true
+     * new MyStringEdge("hello world").has("foo") // false
+     */
+    has(value) {
+        return this.value.includes(value); // 🐛 fix: !indexOf() falha quando index é 0
+    }
+    /**
+     * Verifica se a string começa com uma substring específica.
+     * @param value - Substring a ser verificada no início
+     * @returns true se a string começa com a substring, false caso contrário
+     * @example
+     * new MyStringEdge("hello world").startsWith("hello") // true
+     * new MyStringEdge("hello world").startsWith("world") // false
+     */
+    startsWith(value) {
+        return this.value.startsWith(value);
+    }
+    /**
+     * Verifica se a string termina com uma substring específica.
+     * @param value - Substring a ser verificada no final
+     * @returns true se a string termina com a substring, false caso contrário
+     * @example
+     * new MyStringEdge("hello world").endsWith("world") // true
+     * new MyStringEdge("hello world").endsWith("hello") // false
+     */
+    endsWith(value) {
+        return this.value.endsWith(value);
+    }
+    /**
+     * Verifica se a string é igual a outra (case-sensitive).
+     * @param value - String para comparação
+     * @returns true se as strings são iguais, false caso contrário
+     * @example
+     * new MyStringEdge("hello").isEqual("hello") // true
+     * new MyStringEdge("hello").isEqual("Hello") // false
+     */
+    isEqual(value) {
+        return this.value === value;
+    }
+    /**
+     * Verifica se a string é igual a outra ignorando maiúsculas/minúsculas.
+     * @param value - String para comparação
+     * @returns true se as strings são iguais (case-insensitive), false caso contrário
+     * @example
+     * new MyStringEdge("hello").isEqualIgnoreCase("HELLO") // true
+     * new MyStringEdge("hello").isEqualIgnoreCase("world") // false
+     */
+    isEqualIgnoreCase(value) {
+        return this.value.toLowerCase() === value.toLowerCase();
+    }
+    // ==================== Extração ====================
+    /**
+     * Extrai uma substring entre dois delimitadores (exclusivo).
+     * @param start - Delimitador de início (não incluído no resultado)
+     * @param end - Delimitador de fim (não incluído no resultado)
+     * @returns Substring entre os delimitadores
+     * @example
+     * new MyStringEdge("[hello]").extract("[", "]") // "hello"
+     * new MyStringEdge("(foo bar)").extract("(", ")") // "foo bar"
+     */
+    extract(start, end) {
+        const indexStart = this.value.indexOf(start) + start.length; // 🐛 fix: incluir tamanho do delimitador
+        const indexEnd = this.value.lastIndexOf(end); // 🐛 fix: remover + 1 que incluía o char final
+        return this.value.substring(indexStart, indexEnd);
+    }
+    /**
+     * Retorna uma fatia da string entre dois índices.
+     * @param start - Índice inicial (inclusivo)
+     * @param end - Índice final (exclusivo, opcional)
+     * @returns Substring entre os índices fornecidos
+     * @example
+     * new MyStringEdge("hello world").slice(0, 5) // "hello"
+     * new MyStringEdge("hello world").slice(6) // "world"
+     */
+    slice(start, end) {
+        return this.value.slice(start, end);
+    }
+    // ==================== Transformação ====================
+    /**
+     * Remove todas as ocorrências das substrings fornecidas.
+     * @param substrings - Array de substrings a serem removidas
+     * @returns Nova string sem as substrings fornecidas
+     * @example
+     * new MyStringEdge("hello world").remove(["hello", " "]) // "world"
+     * new MyStringEdge("foo-bar_baz").remove(["-", "_"]) // "foobarbaz"
+     */
+    remove(substrings) {
+        return substrings.reduce(
+        // 🐛 fix: regex com [...] quebra para substrings com mais de 1 char
+        (acc, substring) => acc.split(substring).join(""), this.value);
+    }
+    /**
+     * Substitui a primeira ocorrência de uma substring por outra.
+     * @param search - Substring a ser substituída
+     * @param replacement - Substring substituta
+     * @returns Nova string com a primeira ocorrência substituída
+     * @example
+     * new MyStringEdge("foo bar foo").replace("foo", "baz") // "baz bar foo"
+     */
+    replace(search, replacement) {
+        return this.value.replace(search, replacement);
+    }
+    /**
+     * Substitui todas as ocorrências de uma substring por outra.
+     * @param search - Substring a ser substituída
+     * @param replacement - Substring substituta
+     * @returns Nova string com todas as ocorrências substituídas
+     * @example
+     * new MyStringEdge("foo bar foo").replaceAll("foo", "baz") // "baz bar baz"
+     */
+    replaceAll(search, replacement) {
+        return this.value.split(search).join(replacement);
+    }
+    /**
+     * Converte a string para letras maiúsculas.
+     * @returns String em maiúsculas
+     * @example
+     * new MyStringEdge("hello").toUpperCase() // "HELLO"
+     */
+    toUpperCase() {
+        return this.value.toUpperCase();
+    }
+    /**
+     * Converte a string para letras minúsculas.
+     * @returns String em minúsculas
+     * @example
+     * new MyStringEdge("HELLO").toLowerCase() // "hello"
+     */
+    toLowerCase() {
+        return this.value.toLowerCase();
+    }
+    /**
+     * Reverte os caracteres da string.
+     * @returns String com os caracteres em ordem inversa
+     * @example
+     * new MyStringEdge("hello").reverse() // "olleh"
+     */
+    reverse() {
+        return this.value.split("").reverse().join("");
+    }
+    /**
+     * 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
+     * new MyStringEdge("Hello World").truncate(8) // "Hello..."
+     * new MyStringEdge("Hi").truncate(8) // "Hi"
+     */
+    truncate(length) {
+        if (this.value.length <= length)
+            return this.value;
+        return `${this.value.substring(0, length - 3)}...`;
+    }
+    /**
+     * 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
+     * new MyStringEdge("hello world hello").countOccurrences("hello") // 2
+     */
+    countOccurrences(substring) {
+        if (substring.length === 0)
+            return 0;
+        return this.value.split(substring).length - 1;
+    }
+    // ==================== Privados ====================
+    /**
+     * Remove espaços extras no início e no fim da string.
+     */
+    sanitize() {
+        this.value = this.value.trim();
+    }
+    /**
+     * Valida se a string não está vazia após o sanitize.
+     * @throws {TypeError} Se a string estiver vazia
+     */
+    validate() {
+        if (this.value.length <= 0) {
+            throw new TypeError(`${this.constructor.name} should not be empty.`);
+        }
+    }
+}
+exports.StringEdgeSketch = StringEdgeSketch;

package/src/objects/scheduling/scheduling.edge.d.ts

@@ -1,9 +1,9 @@
-import { Optional } from "#/@tool-box/utils/ducts/optional-type.ts";
-import { Return } from "#/@tool-box/utils/ducts/return-type.ts";
-import { DatetimeEdge } from "#/objects/datetime/edges/datetime.edge.ts";
-import { FailureAbstract } from "#/objects/failure/edges/failure.abstract.ts";
-import { StringEdgeSketch } from "#/objects/primitives/string.edge.sketch.ts";
-import { TimeEdge } from "#/objects/time/time.edge.ts";
+import { Optional } from "../../@tool-box/utils/ducts/optional-type";
+import { Return } from "../../@tool-box/utils/ducts/return-type";
+import { DatetimeEdge } from "../../objects/datetime/edges/datetime.edge";
+import { FailureAbstract } from "../../objects/failure/edges/failure.abstract";
+import { StringEdgeSketch } from "../../objects/primitives/string.edge.sketch";
+import { TimeEdge } from "../../objects/time/time.edge";
 export declare class SchedulingEdge extends StringEdgeSketch {
     protected _cronExpression: string;
     expiresInPacked: Optional<DatetimeEdge>;
@@ -159,4 +159,3 @@ export declare class SchedulingEdge extends StringEdgeSketch {
      */
     static monthly(dayOfMonth: number, time: TimeEdge): SchedulingEdge;
 }
-//# sourceMappingURL=scheduling.edge.d.ts.map

package/src/objects/scheduling/scheduling.edge.failure.d.ts

@@ -1,5 +1,4 @@
-import { FailureAbstract } from "#/objects/failure/edges/failure.abstract.ts";
+import { FailureAbstract } from "../../objects/failure/edges/failure.abstract";
 export declare class RecurringSchedulingEdgeFailure extends FailureAbstract {
     constructor(schedule: string, error?: any);
 }
-//# sourceMappingURL=scheduling.edge.failure.d.ts.map

package/src/objects/scheduling/scheduling.edge.failure.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecurringSchedulingEdgeFailure = void 0;
+const failure_abstract_1 = require("../../objects/failure/edges/failure.abstract");
+class RecurringSchedulingEdgeFailure extends failure_abstract_1.FailureAbstract {
+    constructor(schedule, error) {
+        super({
+            failureClass: RecurringSchedulingEdgeFailure,
+            message: `${schedule} is not a recurring schedule`,
+            stackTrace: error,
+        });
+    }
+}
+exports.RecurringSchedulingEdgeFailure = RecurringSchedulingEdgeFailure;

package/src/objects/scheduling/scheduling.edge.js

@@ -0,0 +1,281 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchedulingEdge = void 0;
+const cron_parser_1 = require("cron-parser");
+const optional_type_1 = require("../../@tool-box/utils/ducts/optional-type");
+const return_type_1 = require("../../@tool-box/utils/ducts/return-type");
+const datetime_edge_1 = require("../../objects/datetime/edges/datetime.edge");
+const string_edge_sketch_1 = require("../../objects/primitives/string.edge.sketch");
+const time_edge_1 = require("../../objects/time/time.edge");
+class SchedulingEdge extends string_edge_sketch_1.StringEdgeSketch {
+    _cronExpression;
+    expiresInPacked = optional_type_1.Nothing;
+    constructor(_cronExpression) {
+        // normaliza espaços múltiplos para evitar inconsistência de validação
+        super(_cronExpression.replace(/\s+/g, " "));
+        this._cronExpression = _cronExpression;
+        this.validateCronExpression();
+    }
+    validateCronExpression() {
+        try {
+            cron_parser_1.CronExpressionParser.parse(this.toString());
+        }
+        catch {
+            throw new Error(`${this.toString()} should be a valid Cron Expression.`);
+        }
+    }
+    // ==================== Verificações ====================
+    /**
+     * Verifica se o agendamento é recorrente (baseado em expressão cron).
+     * @returns true se o agendamento é recorrente, false se é um datetime fixo
+     * @example
+     * new ScheduleEdge(new CronExpressionEdge("0 8 * * *")).isRecurrent() // true
+     * new ScheduleEdge(new DatetimeEdge(new Date())).isRecurrent() // false
+     */
+    isRecurrent() {
+        return this.expiresInPacked.hasSomething();
+    }
+    /**
+     * Verifica se o agendamento é um evento único (baseado no momento de expiracao).
+     * @returns true se o agendamento é um evento único, false se é recorrente
+     */
+    isOneTime() {
+        return this.expiresInPacked.hasNothing();
+    }
+    // ==================== Ocorrências ====================
+    /**
+     * Retorna a próxima ocorrência de um agendamento recorrente.
+     * @returns Success com a próxima ocorrência ou Failure se o agendamento não for recorrente
+     * @example
+     * const schedule = new ScheduleEdge(new CronExpressionEdge("0 8 * * *"));
+     * schedule.nextOccurrence() // Success(DatetimeEdge com a próxima ocorrência às 8h)
+     */
+    nextOccurrence() {
+        const cronDate = cron_parser_1.CronExpressionParser.parse(this._cronExpression.toString()).next();
+        return (0, return_type_1.Success)(new datetime_edge_1.DatetimeEdge(cronDate.toDate()));
+    }
+    /**
+     * Retorna as próximas N ocorrências de um agendamento recorrente.
+     * @param quantity - Número de ocorrências a retornar
+     * @returns Success com array das próximas ocorrências ou Failure se não for recorrente
+     * @example
+     * const schedule = new ScheduleEdge(new CronExpressionEdge("0 8 * * *"));
+     * schedule.nextOccurrences(3) // Success([DatetimeEdge, DatetimeEdge, DatetimeEdge])
+     */
+    nextOccurrences(quantity) {
+        const cronDates = cron_parser_1.CronExpressionParser.parse(this._cronExpression.toString()).take(quantity);
+        return (0, return_type_1.Success)(cronDates.map((cronDate) => new datetime_edge_1.DatetimeEdge(cronDate.toDate())));
+    }
+    /**
+     * Retorna a ocorrência anterior de um agendamento recorrente.
+     * @returns Success com a ocorrência anterior ou Failure se o agendamento não for recorrente
+     * @example
+     * const schedule = new ScheduleEdge(new CronExpressionEdge("0 8 * * *"));
+     * schedule.previousOccurrence() // Success(DatetimeEdge com a última ocorrência às 8h)
+     */
+    previousOccurrence() {
+        const cronDate = cron_parser_1.CronExpressionParser.parse(this._cronExpression.toString()).prev();
+        return (0, return_type_1.Success)(new datetime_edge_1.DatetimeEdge(cronDate.toDate()));
+    }
+    /**
+     * Retorna as N ocorrências anteriores de um agendamento recorrente.
+     * @param quantity - Número de ocorrências a retornar
+     * @returns Success com array das ocorrências anteriores ou Failure se não for recorrente
+     * @example
+     * const schedule = new ScheduleEdge(new CronExpressionEdge("0 8 * * *"));
+     * schedule.previousOccurrences(3) // Success([DatetimeEdge, DatetimeEdge, DatetimeEdge])
+     */
+    previousOccurrences(quantity) {
+        const cronDates = cron_parser_1.CronExpressionParser.parse(this._cronExpression.toString()).take(-quantity);
+        return (0, return_type_1.Success)(cronDates.map((cronDate) => new datetime_edge_1.DatetimeEdge(cronDate.toDate())));
+    }
+    /**
+     * Retorna todas as ocorrências dentro de um intervalo de datas.
+     * @param start - Data de início do intervalo
+     * @param end - Data de fim do intervalo
+     * @returns Success com array das ocorrências no intervalo ou Failure se não for recorrente
+     * @example
+     * const schedule = new ScheduleEdge(new CronExpressionEdge("0 8 * * *"));
+     * schedule.occurrencesBetween(startDate, endDate)
+     * // Success([DatetimeEdge, DatetimeEdge, ...])
+     */
+    occurrencesBetween(start, end) {
+        const interval = cron_parser_1.CronExpressionParser.parse(this._cronExpression.toString(), {
+            currentDate: start.toDate(),
+            endDate: end.toDate(),
+        });
+        const occurrences = [];
+        while (true) {
+            try {
+                const next = interval.next();
+                occurrences.push(new datetime_edge_1.DatetimeEdge(next.toDate()));
+            }
+            catch {
+                break;
+            }
+        }
+        return (0, return_type_1.Success)(occurrences);
+    }
+    /**
+     * Conta quantas ocorrências existem dentro de um intervalo de datas.
+     * @param start - Data de início do intervalo
+     * @param end - Data de fim do intervalo
+     * @returns Success com o número de ocorrências ou Failure se não for recorrente
+     * @example
+     * const schedule = new ScheduleEdge(new CronExpressionEdge("0 8 * * 1-5"));
+     * schedule.countOccurrencesBetween(startDate, endDate) // Success(5) em uma semana
+     */
+    countOccurrencesBetween(start, end) {
+        const resultWrapped = this.occurrencesBetween(start, end);
+        if (!resultWrapped.hasSuccess)
+            return resultWrapped;
+        return (0, return_type_1.Success)(resultWrapped.unwrap().values.length);
+    }
+    // ==================== Getters ====================
+    /**
+     * Retorna o horário do agendamento como um TimeEdge.
+     * @returns TimeEdge com hora e minuto do agendamento
+     * @example
+     * new ScheduleEdge(new CronExpressionEdge("0 8 * * *")).getTime()
+     * // TimeEdge("08:00")
+     */
+    getTime() {
+        const interval = cron_parser_1.CronExpressionParser.parse(this._cronExpression.toString()).fields;
+        const hour = String(interval.hour.values.toString()).padStart(2, "0");
+        const minute = String(interval.minute.values.toString()).padStart(2, "0");
+        return new time_edge_1.TimeEdge(`${hour}:${minute}`);
+    }
+    /**
+     * Retorna os campos da expressão cron.
+     */
+    getFields() {
+        return this.toString().split(/\s+/);
+    }
+    // ==================== Cálculo de Execução ====================
+    /**
+     * Retorna a próxima execução a partir de uma data base.
+     */
+    nextDate(fromDate = new Date()) {
+        const interval = cron_parser_1.CronExpressionParser.parse(this.toString(), {
+            currentDate: fromDate,
+        });
+        return interval.next().toDate();
+    }
+    /**
+     * Retorna a execução anterior a partir de uma data base.
+     */
+    previousDate(fromDate = new Date()) {
+        const interval = cron_parser_1.CronExpressionParser.parse(this.toString(), {
+            currentDate: fromDate,
+        });
+        return interval.prev().toDate();
+    }
+    /**
+     * Retorna as próximas N execuções.
+     */
+    nextDates(count, fromDate = new Date()) {
+        if (count <= 0)
+            return [];
+        const interval = cron_parser_1.CronExpressionParser.parse(this.toString(), {
+            currentDate: fromDate,
+        });
+        const dates = [];
+        for (let i = 0; i < count; i++) {
+            dates.push(interval.next().toDate());
+        }
+        return dates;
+    }
+    // ==================== Métodos Estáticos ====================
+    /**
+     * Valida expressão cron sem lançar exceção.
+     */
+    static isValid(expression) {
+        try {
+            cron_parser_1.CronExpressionParser.parse(expression.trim().replace(/\s+/g, " "));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Retorna a CronExpressionEdge do agendamento se for recorrente.
+     * @returns Success com a CronExpressionEdge ou Failure se for evento único
+     * @example
+     * const cron = new CronExpressionEdge("0 8 * * *");
+     * new ScheduleEdge(cron).getCronExpression() // CronExpressionEdge("0 8 * * *")
+     */
+    getCronExpression() {
+        return this._cronExpression;
+    }
+    // ==================== Clonagem e Imutabilidade ====================
+    /**
+     * Cria uma cópia independente desta instância de ScheduleEdge.
+     * @returns Nova instância com o mesmo momento interno
+     * @example
+     * const schedule = new ScheduleEdge(new CronExpressionEdge("0 8 * * *"));
+     * const clone = schedule.clone(); // instância independente
+     */
+    clone() {
+        return new SchedulingEdge(this._cronExpression);
+    }
+    // ==================== Métodos Estáticos ====================
+    /**
+     * Cria um ScheduleEdge de evento único a partir de um objeto Datetime.
+     * @param datetime - Data e hora do evento único
+     * @returns Nova instância de ScheduleEdge para evento único
+     * @example
+     * ScheduleEdge.fromDatetime(new Datetime("2026-12-25T08:00:00"))
+     * // agendamento para o Natal de 2026 às 8h
+     */
+    static fromDatetime(datetime) {
+        const date = datetime.toDate();
+        const minute = date.getMinutes();
+        const hour = date.getHours();
+        const day = date.getDate();
+        const month = date.getMonth() + 1;
+        const dayOfWeek = date.getDay();
+        const cron = `${minute} ${hour} ${day} ${month} ${dayOfWeek}`;
+        const scheduledFor = new SchedulingEdge(cron);
+        scheduledFor.expiresInPacked = (0, optional_type_1.Optional)(datetime);
+        return scheduledFor;
+    }
+    /**
+     * Cria um ScheduleEdge para agendamentos diários em um horário específico.
+     * @param time - Horário do agendamento no formato TimeEdge
+     * @returns Nova instância de ScheduleEdge com recorrência diária
+     * @example
+     * ScheduleEdge.daily(new TimeEdge("08:00")) // todos os dias às 8h -> "0 8 * * *"
+     */
+    static daily(time) {
+        const expression = `${time.getMinutes()} ${time.getHours()} * * *`;
+        return new SchedulingEdge(expression);
+    }
+    /**
+     * Cria um ScheduleEdge para agendamentos semanais em um dia e horário específico.
+     * @param dayOfWeek - Dia da semana (0=domingo, 1=segunda, ..., 6=sábado)
+     * @param time - Horário do agendamento no formato TimeEdge
+     * @returns Nova instância de ScheduleEdge com recorrência semanal
+     * @example
+     * ScheduleEdge.weekly(1, new TimeEdge("08:00"))
+     * // toda segunda-feira às 8h -> "0 8 * * 1"
+     */
+    static weekly(dayOfWeek, time) {
+        const expression = `${time.getMinutes()} ${time.getHours()} * * ${dayOfWeek}`;
+        return new SchedulingEdge(expression);
+    }
+    /**
+     * Cria um ScheduleEdge para agendamentos mensais em um dia e horário específico.
+     * @param dayOfMonth - Dia do mês (1-31)
+     * @param time - Horário do agendamento no formato TimeEdge
+     * @returns Nova instância de ScheduleEdge com recorrência mensal
+     * @example
+     * ScheduleEdge.monthly(15, new TimeEdge("08:00"))
+     * // todo dia 15 de cada mês às 8h -> "0 8 15 * *"
+     */
+    static monthly(dayOfMonth, time) {
+        const expression = `${time.getMinutes()} ${time.getHours()} ${dayOfMonth} * *`;
+        return new SchedulingEdge(expression);
+    }
+}
+exports.SchedulingEdge = SchedulingEdge;

package/src/objects/time/time.edge.d.ts

@@ -1,4 +1,4 @@
-import { SchedulingEdge } from "#/objects/scheduling/scheduling.edge.ts";
+import { SchedulingEdge } from "../../objects/scheduling/scheduling.edge";
 export declare class TimeEdge {
     private readonly value;
     constructor(value: string);
@@ -294,4 +294,3 @@ export declare class TimeEdge {
      */
     private isValidTimeFormat;
 }
-//# sourceMappingURL=time.edge.d.ts.map