@atlantjs/arch 13.2.0 → 14.0.0

package/objects/@common/edges/cron-expression.edge.js

@@ -7,17 +7,89 @@ exports.CronExpressionEdge = void 0;
 const cron_parser_1 = __importDefault(require("cron-parser"));
 const string_edge_sketch_1 = require("../../primitives/string.edge.sketch");
 class CronExpressionEdge extends string_edge_sketch_1.StringEdgeSketch {
-    constructor(_expression) {
-        super(_expression);
-        this._expression = _expression;
+    constructor(expression) {
+        // normaliza espaços múltiplos para evitar inconsistência de validação
+        super(expression.replace(/\s+/g, " "));
         this.validateCronExpression();
     }
     validateCronExpression() {
         try {
-            cron_parser_1.default.parse(this._expression);
+            // usa valor sanitizado do StringEdgeSketch
+            cron_parser_1.default.parse(this.toString());
         }
         catch {
-            throw new Error(`${this._expression} should be a valid Cron Expression (* * * * *).`);
+            throw new Error(`${this.toString()} should be a valid Cron Expression.`);
+        }
+    }
+    // ==================== Getters ====================
+    /**
+     * Retorna a expressão cron.
+     */
+    toString() {
+        return super.toString();
+    }
+    /**
+     * Retorna os campos da expressão cron.
+     */
+    getFields() {
+        return this.toString().split(/\s+/);
+    }
+    // ==================== Comparações ====================
+    /**
+     * Compara com outra expressão cron (string ou edge).
+     */
+    isEqual(other) {
+        const comparand = other instanceof CronExpressionEdge ? other.toString() : other;
+        return this.toString() === comparand.trim().replace(/\s+/g, " ");
+    }
+    isDifferent(other) {
+        return !this.isEqual(other);
+    }
+    // ==================== 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.default.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.default.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.default.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.default.parse(expression.trim().replace(/\s+/g, " "));
+            return true;
+        }
+        catch {
+            return false;
         }
     }
 }

package/objects/@common/edges/email.edge.d.ts

@@ -1,6 +1,44 @@
 import { StringEdgeSketch } from "../../primitives/string.edge.sketch";
 export declare class EmailEdge extends StringEdgeSketch {
-    private readonly email;
+    private static readonly pattern;
     constructor(email: string);
     protected validation(): void;
+    /**
+     * Retorna o e-mail como string.
+     */
+    toString(): string;
+    /**
+     * Retorna o e-mail normalizado (lowercase + trim já aplicado no super).
+     */
+    toNormalized(): string;
+    /**
+     * Retorna a parte local (antes do @).
+     */
+    getLocalPart(): string;
+    /**
+     * Retorna o domínio completo (após o @).
+     */
+    getDomain(): string;
+    /**
+     * Retorna o TLD (ex: "com", "com.br" -> "br").
+     */
+    getTld(): string;
+    /**
+     * Verifica se o e-mail pertence a um domínio.
+     */
+    isFromDomain(domain: string): boolean;
+    /**
+     * Compara este e-mail com outro (string ou EmailEdge).
+     * Por padrão, ignora case.
+     */
+    isEqual(other: string | EmailEdge, ignoreCase?: boolean): boolean;
+    /**
+     * Mascara a parte local do e-mail.
+     * Ex: "john.doe@mail.com" -> "j******e@mail.com"
+     */
+    mask(): string;
+    /**
+     * Verifica se uma string é um e-mail válido sem lançar exceção.
+     */
+    static isValid(value: string): boolean;
 }

package/objects/@common/edges/email.edge.js

@@ -5,13 +5,91 @@ const string_edge_sketch_1 = require("../../primitives/string.edge.sketch");
 class EmailEdge extends string_edge_sketch_1.StringEdgeSketch {
     constructor(email) {
         super(email);
-        this.email = email;
         this.validation();
     }
     validation() {
-        if (!/^[\w-\\.]+@([\w-]+\.)+[\w-]{2,4}$/.test(this.email)) {
+        // usa valor sanitizado do StringEdgeSketch (trim aplicado)
+        if (!EmailEdge.pattern.test(this.toString())) {
             throw new TypeError(`${this.constructor.name} should be valid.`);
         }
     }
+    // ==================== Getters ====================
+    /**
+     * Retorna o e-mail como string.
+     */
+    toString() {
+        return super.toString();
+    }
+    /**
+     * Retorna o e-mail normalizado (lowercase + trim já aplicado no super).
+     */
+    toNormalized() {
+        return this.toString().toLowerCase();
+    }
+    /**
+     * Retorna a parte local (antes do @).
+     */
+    getLocalPart() {
+        return this.toString().split("@")[0];
+    }
+    /**
+     * Retorna o domínio completo (após o @).
+     */
+    getDomain() {
+        return this.toString().split("@")[1];
+    }
+    /**
+     * Retorna o TLD (ex: "com", "com.br" -> "br").
+     */
+    getTld() {
+        const domain = this.getDomain();
+        const parts = domain.split(".");
+        return parts[parts.length - 1];
+    }
+    // ==================== Verificações ====================
+    /**
+     * Verifica se o e-mail pertence a um domínio.
+     */
+    isFromDomain(domain) {
+        return this.getDomain().toLowerCase() === domain.toLowerCase();
+    }
+    /**
+     * Compara este e-mail com outro (string ou EmailEdge).
+     * Por padrão, ignora case.
+     */
+    isEqual(other, ignoreCase = true) {
+        const comparand = other instanceof EmailEdge ? other.toString() : other;
+        if (ignoreCase) {
+            return this.toString().toLowerCase() === comparand.trim().toLowerCase();
+        }
+        return this.toString() === comparand.trim();
+    }
+    // ==================== Transformação ====================
+    /**
+     * Mascara a parte local do e-mail.
+     * Ex: "john.doe@mail.com" -> "j******e@mail.com"
+     */
+    mask() {
+        const local = this.getLocalPart();
+        const domain = this.getDomain();
+        if (local.length <= 2) {
+            return `${"*".repeat(local.length)}@${domain}`;
+        }
+        return `${local[0]}${"*".repeat(local.length - 2)}${local[local.length - 1]}@${domain}`;
+    }
+    // ==================== Métodos Estáticos ====================
+    /**
+     * Verifica se uma string é um e-mail válido sem lançar exceção.
+     */
+    static isValid(value) {
+        try {
+            const sanitized = value.trim();
+            return EmailEdge.pattern.test(sanitized);
+        }
+        catch {
+            return false;
+        }
+    }
 }
 exports.EmailEdge = EmailEdge;
+EmailEdge.pattern = /^[^\s@]+@[^\s@]+\.[^\s@]{2,}$/;

package/objects/@common/edges/ulid.sketch.edge.d.ts

@@ -1,6 +1,53 @@
 export declare abstract class UlidSketchEdge {
     private readonly value;
     constructor(value?: string);
-    equals(otherUlid: UlidSketchEdge): boolean;
+    /**
+     * Retorna o ULID como string.
+     */
     toString(): string;
+    /**
+     * Retorna o ULID em minúsculas.
+     */
+    toLowerCase(): string;
+    /**
+     * Retorna o ULID em maiúsculas.
+     */
+    toUpperCase(): string;
+    /**
+     * Retorna o timestamp embutido no ULID em ms.
+     */
+    getTimestamp(): number;
+    /**
+     * Retorna a data do timestamp embutido no ULID.
+     */
+    toDate(): Date;
+    /**
+     * Compara igualdade com outro ULID.
+     */
+    isEqual(otherUlid: UlidSketchEdge): boolean;
+    /**
+     * Compara diferença com outro ULID.
+     */
+    isDifferent(otherUlid: UlidSketchEdge): boolean;
+    /**
+     * @deprecated Use isEqual.
+     */
+    equals(otherUlid: UlidSketchEdge): boolean;
+    /**
+     * Verifica se este ULID foi gerado antes de outro.
+     * (ULID é ordenável lexicograficamente por tempo)
+     */
+    isBefore(otherUlid: UlidSketchEdge): boolean;
+    /**
+     * Verifica se este ULID foi gerado depois de outro.
+     */
+    isAfter(otherUlid: UlidSketchEdge): boolean;
+    /**
+     * Gera um novo ULID.
+     */
+    static generate(): string;
+    /**
+     * Verifica se uma string é ULID válido.
+     */
+    static isUlid(value: string): boolean;
 }

package/objects/@common/edges/ulid.sketch.edge.js

@@ -6,15 +6,86 @@ const index_1 = require("../../../index");
 class UlidSketchEdge {
     constructor(value = (0, ulid_1.ulid)()) {
         this.value = value;
-        if ((0, ulid_1.isValid)(value).falsy()) {
+        // 🐛 fix: isValid retorna boolean, não possui .falsy()
+        if (!(0, ulid_1.isValid)(this.value)) {
             throw new TypeError("The provided ULID is invalid. Please ensure it is in the correct format");
         }
     }
-    equals(otherUlid) {
-        return index_1._.isEqual(this.toString(), otherUlid.toString());
-    }
+    // ==================== Getters ====================
+    /**
+     * Retorna o ULID como string.
+     */
     toString() {
         return this.value;
     }
+    /**
+     * Retorna o ULID em minúsculas.
+     */
+    toLowerCase() {
+        return this.value.toLowerCase();
+    }
+    /**
+     * Retorna o ULID em maiúsculas.
+     */
+    toUpperCase() {
+        return this.value.toUpperCase();
+    }
+    /**
+     * Retorna o timestamp embutido no ULID em ms.
+     */
+    getTimestamp() {
+        return (0, ulid_1.decodeTime)(this.value);
+    }
+    /**
+     * Retorna a data do timestamp embutido no ULID.
+     */
+    toDate() {
+        return new Date(this.getTimestamp());
+    }
+    // ==================== Comparações ====================
+    /**
+     * Compara igualdade com outro ULID.
+     */
+    isEqual(otherUlid) {
+        return index_1._.isEqual(this.toString(), otherUlid.toString());
+    }
+    /**
+     * Compara diferença com outro ULID.
+     */
+    isDifferent(otherUlid) {
+        return !this.isEqual(otherUlid);
+    }
+    /**
+     * @deprecated Use isEqual.
+     */
+    equals(otherUlid) {
+        return this.isEqual(otherUlid);
+    }
+    /**
+     * Verifica se este ULID foi gerado antes de outro.
+     * (ULID é ordenável lexicograficamente por tempo)
+     */
+    isBefore(otherUlid) {
+        return this.toString() < otherUlid.toString();
+    }
+    /**
+     * Verifica se este ULID foi gerado depois de outro.
+     */
+    isAfter(otherUlid) {
+        return this.toString() > otherUlid.toString();
+    }
+    // ==================== Métodos Estáticos ====================
+    /**
+     * Gera um novo ULID.
+     */
+    static generate() {
+        return (0, ulid_1.ulid)();
+    }
+    /**
+     * Verifica se uma string é ULID válido.
+     */
+    static isUlid(value) {
+        return (0, ulid_1.isValid)(value);
+    }
 }
 exports.UlidSketchEdge = UlidSketchEdge;

package/objects/@common/edges/url.edge.d.ts

@@ -3,4 +3,186 @@ export declare class UrlEdge extends StringEdgeSketch {
     protected _url: string;
     constructor(_url: string);
     protected validateUrl(): void;
+    /**
+     * Retorna a URL completa como string.
+     * @returns String com a URL completa
+     * @example
+     * new UrlEdge("https://example.com/path?q=1").toString()
+     * // "https://example.com/path?q=1"
+     */
+    toString(): string;
+    /**
+     * Retorna o protocolo da URL (sem "://").
+     * @returns String com o protocolo
+     * @example
+     * new UrlEdge("https://example.com").getProtocol() // "https:"
+     * new UrlEdge("http://example.com").getProtocol() // "http:"
+     */
+    getProtocol(): string;
+    /**
+     * Retorna o hostname da URL (sem porta).
+     * @returns String com o hostname
+     * @example
+     * new UrlEdge("https://example.com:8080/path").getHostname() // "example.com"
+     */
+    getHostname(): string;
+    /**
+     * Retorna o host da URL (hostname + porta, se existir).
+     * @returns String com o host
+     * @example
+     * new UrlEdge("https://example.com:8080/path").getHost() // "example.com:8080"
+     * new UrlEdge("https://example.com/path").getHost() // "example.com"
+     */
+    getHost(): string;
+    /**
+     * Retorna a porta da URL, se definida.
+     * @returns String com a porta ou string vazia se não definida
+     * @example
+     * new UrlEdge("https://example.com:8080/path").getPort() // "8080"
+     * new UrlEdge("https://example.com/path").getPort() // ""
+     */
+    getPort(): string;
+    /**
+     * Retorna o pathname da URL.
+     * @returns String com o caminho da URL
+     * @example
+     * new UrlEdge("https://example.com/foo/bar").getPathname() // "/foo/bar"
+     * new UrlEdge("https://example.com").getPathname() // "/"
+     */
+    getPathname(): string;
+    /**
+     * Retorna a query string da URL (incluindo "?").
+     * @returns String com a query string ou string vazia se não existir
+     * @example
+     * new UrlEdge("https://example.com/path?q=1&page=2").getSearch() // "?q=1&page=2"
+     * new UrlEdge("https://example.com/path").getSearch() // ""
+     */
+    getSearch(): string;
+    /**
+     * Retorna o valor de um parâmetro específico da query string.
+     * @param key - Nome do parâmetro a buscar
+     * @returns Valor do parâmetro ou null se não existir
+     * @example
+     * new UrlEdge("https://example.com?q=hello&page=2").getSearchParam("q") // "hello"
+     * new UrlEdge("https://example.com?q=hello").getSearchParam("page") // null
+     */
+    getSearchParam(key: string): string | null;
+    /**
+     * Retorna todos os parâmetros da query string como objeto.
+     * @returns Objeto com chave/valor de todos os parâmetros
+     * @example
+     * new UrlEdge("https://example.com?q=hello&page=2").getSearchParams()
+     * // { q: "hello", page: "2" }
+     */
+    getSearchParams(): Record<string, string>;
+    /**
+     * Retorna o hash/fragmento da URL (incluindo "#").
+     * @returns String com o hash ou string vazia se não existir
+     * @example
+     * new UrlEdge("https://example.com/page#section-1").getHash() // "#section-1"
+     * new UrlEdge("https://example.com/page").getHash() // ""
+     */
+    getHash(): string;
+    /**
+     * Retorna a origem da URL (protocolo + host).
+     * @returns String com a origem
+     * @example
+     * new UrlEdge("https://example.com:8080/path?q=1").getOrigin() // "https://example.com:8080"
+     */
+    getOrigin(): string;
+    /**
+     * Verifica se a URL usa o protocolo HTTPS.
+     * @returns true se o protocolo é HTTPS, false caso contrário
+     * @example
+     * new UrlEdge("https://example.com").isHttps() // true
+     * new UrlEdge("http://example.com").isHttps() // false
+     */
+    isHttps(): boolean;
+    /**
+     * Verifica se a URL usa o protocolo HTTP.
+     * @returns true se o protocolo é HTTP, false caso contrário
+     * @example
+     * new UrlEdge("http://example.com").isHttp() // true
+     * new UrlEdge("https://example.com").isHttp() // false
+     */
+    isHttp(): boolean;
+    /**
+     * Verifica se a URL possui query string.
+     * @returns true se a URL tem parâmetros de query, false caso contrário
+     * @example
+     * new UrlEdge("https://example.com?q=1").hasSearchParams() // true
+     * new UrlEdge("https://example.com").hasSearchParams() // false
+     */
+    hasSearchParams(): boolean;
+    /**
+     * Verifica se a URL possui um parâmetro específico na query string.
+     * @param key - Nome do parâmetro a verificar
+     * @returns true se o parâmetro existe, false caso contrário
+     * @example
+     * new UrlEdge("https://example.com?q=1").hasSearchParam("q") // true
+     * new UrlEdge("https://example.com?q=1").hasSearchParam("page") // false
+     */
+    hasSearchParam(key: string): boolean;
+    /**
+     * Verifica se a URL possui hash/fragmento.
+     * @returns true se a URL tem hash, false caso contrário
+     * @example
+     * new UrlEdge("https://example.com#section").hasHash() // true
+     * new UrlEdge("https://example.com").hasHash() // false
+     */
+    hasHash(): boolean;
+    /**
+     * Verifica se esta URL é igual a outra.
+     * @param other - UrlEdge ou string para comparação
+     * @returns true se as URLs são iguais, false caso contrário
+     * @example
+     * const url = new UrlEdge("https://example.com");
+     * url.isEqual(new UrlEdge("https://example.com")) // true
+     * url.isEqual("https://other.com") // false
+     */
+    isEqual(other: UrlEdge | string): boolean;
+    /**
+     * Retorna uma nova URL com um parâmetro de query adicionado ou atualizado.
+     * @param key - Nome do parâmetro
+     * @param value - Valor do parâmetro
+     * @returns Nova instância de UrlEdge com o parâmetro adicionado
+     * @example
+     * new UrlEdge("https://example.com?q=1").withSearchParam("page", "2")
+     * // UrlEdge("https://example.com?q=1&page=2")
+     */
+    withSearchParam(key: string, value: string): UrlEdge;
+    /**
+     * Retorna uma nova URL sem um parâmetro de query específico.
+     * @param key - Nome do parâmetro a remover
+     * @returns Nova instância de UrlEdge sem o parâmetro
+     * @example
+     * new UrlEdge("https://example.com?q=1&page=2").withoutSearchParam("page")
+     * // UrlEdge("https://example.com?q=1")
+     */
+    withoutSearchParam(key: string): UrlEdge;
+    /**
+     * Retorna uma nova URL sem a query string.
+     * @returns Nova instância de UrlEdge sem query string
+     * @example
+     * new UrlEdge("https://example.com/path?q=1&page=2").withoutSearch()
+     * // UrlEdge("https://example.com/path")
+     */
+    withoutSearch(): UrlEdge;
+    /**
+     * Retorna uma nova URL sem o hash/fragmento.
+     * @returns Nova instância de UrlEdge sem hash
+     * @example
+     * new UrlEdge("https://example.com/page#section").withoutHash()
+     * // UrlEdge("https://example.com/page")
+     */
+    withoutHash(): UrlEdge;
+    /**
+     * Verifica se uma string é uma URL válida sem lançar exceção.
+     * @param value - String a ser verificada
+     * @returns true se a string é uma URL válida, false caso contrário
+     * @example
+     * UrlEdge.isValid("https://example.com") // true
+     * UrlEdge.isValid("not-a-url") // false
+     */
+    static isValid(value: string): boolean;
 }