@atlantjs/arch 13.2.0 → 14.0.0

package/@tool-box/utils/type-guard/guardian.d.ts

@@ -1,29 +1,472 @@
+import { Newable } from "../datatypes/generic-types";
 import { PrimitiveType } from "./guardian.type";
 declare class Guardian {
+    /**
+     * Verifica se todos os valores booleanos passados são verdadeiros.
+     * @param args - Valores booleanos a serem verificados
+     * @returns true se todos os valores são true, false caso contrário
+     * @example
+     * Guardian.and(true, true, true) // true
+     * Guardian.and(true, false, true) // false
+     */
     static and(...args: boolean[]): boolean;
+    /**
+     * Verifica se pelo menos um dos valores booleanos passados é verdadeiro.
+     * @param args - Valores booleanos a serem verificados
+     * @returns true se pelo menos um valor é true, false caso contrário
+     * @example
+     * Guardian.or(false, false, true) // true
+     * Guardian.or(false, false, false) // false
+     */
     static or(...args: boolean[]): boolean;
+    /**
+     * Retorna um valor baseado em uma condição booleana (ternário).
+     * @template TTrue - Tipo do valor a retornar se a condição for verdadeira
+     * @template TFalse - Tipo do valor a retornar se a condição for falsa
+     * @param condition - Condição a ser avaliada
+     * @param returnIfTrue - Valor retornado quando a condição é true
+     * @param returnIfFalse - Valor retornado quando a condição é false
+     * @returns O valor correspondente à condição
+     * @example
+     * Guardian.ternaryCondition(5 > 3, "maior", "menor") // "maior"
+     */
+    static ternaryCondition<TTrue, TFalse>(condition: boolean, returnIfTrue: TTrue, returnIfFalse: TFalse): TTrue | TFalse;
+    /**
+     * Verifica se um número é maior que uma referência.
+     * @param value - Valor a ser comparado
+     * @param reference - Valor de referência para comparação
+     * @returns true se value > reference, false caso contrário
+     * @example
+     * Guardian.greaterThan(10, 5) // true
+     */
     static greaterThan(value: number, reference: number): boolean;
+    /**
+     * Verifica se um número é menor que uma referência.
+     * @param value - Valor a ser comparado
+     * @param reference - Valor de referência para comparação
+     * @returns true se value < reference, false caso contrário
+     * @example
+     * Guardian.lessThan(3, 5) // true
+     */
     static lessThan(value: number, reference: number): boolean;
+    /**
+     * Verifica se um número é maior ou igual a uma referência.
+     * @param value - Valor a ser comparado
+     * @param reference - Valor de referência para comparação
+     * @returns true se value >= reference, false caso contrário
+     * @example
+     * Guardian.greaterThanOrEqual(5, 5) // true
+     */
+    static greaterThanOrEqual(value: number, reference: number): boolean;
+    /**
+     * Verifica se um número é menor ou igual a uma referência.
+     * @param value - Valor a ser comparado
+     * @param reference - Valor de referência para comparação
+     * @returns true se value <= reference, false caso contrário
+     * @example
+     * Guardian.lessThanOrEqual(5, 5) // true
+     */
+    static lessThanOrEqual(value: number, reference: number): boolean;
+    /**
+     * Verifica se um valor numérico está entre um mínimo e máximo (inclusive).
+     * @param value - Valor numérico ou string a ser verificado
+     * @param min - Valor mínimo da faixa
+     * @param max - Valor máximo da faixa
+     * @returns true se value está entre min e max, false caso contrário
+     * @throws {GuardianException} Se min > max ou se value está vazio
+     * @example
+     * Guardian.isBetween(5, 1, 10) // true
+     * Guardian.isBetween("5", 1, 10) // true
+     */
+    static isBetween(value: number | string, min: number, max: number): boolean;
+    /**
+     * Verifica se um número é positivo (maior que zero).
+     * @param value - Número a ser verificado
+     * @returns true se value > 0, false caso contrário
+     * @example
+     * Guardian.isPositive(5) // true
+     * Guardian.isPositive(-5) // false
+     */
+    static isPositive(value: number): boolean;
+    /**
+     * Verifica se um número é negativo (menor que zero).
+     * @param value - Número a ser verificado
+     * @returns true se value < 0, false caso contrário
+     * @example
+     * Guardian.isNegative(-5) // true
+     * Guardian.isNegative(5) // false
+     */
+    static isNegative(value: number): boolean;
+    /**
+     * Verifica se um número é zero.
+     * @param value - Número a ser verificado
+     * @returns true se value === 0, false caso contrário
+     * @example
+     * Guardian.isZero(0) // true
+     * Guardian.isZero(5) // false
+     */
+    static isZero(value: number): boolean;
+    /**
+     * Verifica se um valor é um número inteiro.
+     * @param value - Valor a ser verificado
+     * @returns true se value é um número inteiro, false caso contrário
+     * @example
+     * Guardian.isInteger(5) // true
+     * Guardian.isInteger(5.5) // false
+     */
+    static isInteger(value: unknown): value is number;
+    /**
+     * Verifica se um valor é um número decimal (ponto flutuante).
+     * @param value - Valor a ser verificado
+     * @returns true se value é um número decimal, false caso contrário
+     * @example
+     * Guardian.isFloat(5.5) // true
+     * Guardian.isFloat(5) // false
+     */
+    static isFloat(value: unknown): value is number;
+    /**
+     * Verifica se um valor está vazio (null, undefined, string vazia, array vazio, objeto vazio).
+     * @param value - Valor a ser verificado
+     * @returns true se value está vazio, false caso contrário
+     * @example
+     * Guardian.isEmpty(null) // true
+     * Guardian.isEmpty("") // true
+     * Guardian.isEmpty([]) // true
+     * Guardian.isEmpty({}) // true
+     * Guardian.isEmpty("texto") // false
+     */
+    static isEmpty(value: unknown): boolean;
+    /**
+     * Verifica se um valor não está vazio.
+     * @param value - Valor a ser verificado
+     * @returns true se value não está vazio, false caso contrário
+     * @example
+     * Guardian.isNotEmpty("texto") // true
+     * Guardian.isNotEmpty("") // false
+     */
+    static isNotEmpty(value: unknown): boolean;
+    /**
+     * Verifica se um array está vazio.
+     * @template T - Tipo dos elementos do array
+     * @param value - Array a ser verificado
+     * @returns true se o array está vazio, false caso contrário
+     * @throws {GuardianException} Se value não for um array
+     * @example
+     * Guardian.isEmptyArray([]) // true
+     * Guardian.isEmptyArray([1, 2]) // false
+     */
     static isEmptyArray<T>(value: T[] | null | undefined): value is T[];
+    /**
+     * Verifica se um array possui elementos (não está vazio).
+     * @template T - Tipo dos elementos do array
+     * @param value - Array a ser verificado
+     * @returns true se o array possui elementos, false caso contrário
+     * @throws {GuardianException} Se value não for um array
+     * @example
+     * Guardian.isFilledArray([1, 2]) // true
+     * Guardian.isFilledArray([]) // false
+     */
     static isFilledArray<T>(value: T[] | null | undefined): value is T[];
+    /**
+     * Verifica se um array possui exatamente um comprimento específico.
+     * @template T - Tipo dos elementos do array
+     * @param value - Array a ser verificado
+     * @param reference - Comprimento esperado do array
+     * @returns true se o array possui exatamente o comprimento especificado, false caso contrário
+     * @throws {GuardianException} Se value não for um array
+     * @example
+     * Guardian.isLengthArray([1, 2, 3], 3) // true
+     * Guardian.isLengthArray([1, 2], 3) // false
+     */
     static isLengthArray<T>(value: T[] | null | undefined, reference: number): value is T[];
-    private static isEmpty;
+    /**
+     * Verifica se um valor é undefined.
+     * @param value - Valor a ser verificado
+     * @returns true se value é undefined, false caso contrário
+     * @example
+     * Guardian.isUndefined(undefined) // true
+     * Guardian.isUndefined(null) // false
+     */
     static isUndefined(value: unknown): value is undefined;
+    /**
+     * Verifica se um valor não é undefined.
+     * @param value - Valor a ser verificado
+     * @returns true se value não é undefined, false caso contrário
+     * @example
+     * Guardian.isNotUndefined(null) // true
+     * Guardian.isNotUndefined(undefined) // false
+     */
     static isNotUndefined(value: unknown): value is boolean;
+    /**
+     * Verifica se um valor é null.
+     * @param value - Valor a ser verificado
+     * @returns true se value é null, false caso contrário
+     * @example
+     * Guardian.isNull(null) // true
+     * Guardian.isNull(undefined) // false
+     */
     static isNull(value: unknown): value is null;
+    /**
+     * Verifica se um valor não é null.
+     * @param value - Valor a ser verificado
+     * @returns true se value não é null, false caso contrário
+     * @example
+     * Guardian.isNotNull(undefined) // true
+     * Guardian.isNotNull(null) // false
+     */
     static isNotNull(value: unknown): value is boolean;
+    /**
+     * Verifica se um valor é null ou undefined.
+     * @param value - Valor a ser verificado
+     * @returns true se value é null ou undefined, false caso contrário
+     * @example
+     * Guardian.isNullOrUndefined(null) // true
+     * Guardian.isNullOrUndefined(undefined) // true
+     * Guardian.isNullOrUndefined("") // false
+     */
+    static isNullOrUndefined(value: unknown): value is null | undefined;
+    /**
+     * Verifica se um valor não é null e não é undefined.
+     * @param value - Valor a ser verificado
+     * @returns true se value não é null e não é undefined, false caso contrário
+     * @example
+     * Guardian.isNotNullOrUndefined("texto") // true
+     * Guardian.isNotNullOrUndefined(null) // false
+     */
+    static isNotNullOrUndefined(value: unknown): value is boolean;
+    /**
+     * Verifica se dois valores são iguais usando comparação estrita (===).
+     * @param valueA - Primeiro valor a ser comparado
+     * @param valueB - Segundo valor a ser comparado
+     * @returns true se valueA === valueB, false caso contrário
+     * @example
+     * Guardian.isEqual(5, 5) // true
+     * Guardian.isEqual(5, "5") // false
+     */
     static isEqual(valueA: unknown, valueB: unknown): boolean;
+    /**
+     * Verifica se dois valores são diferentes usando comparação estrita (!==).
+     * @param valueA - Primeiro valor a ser comparado
+     * @param valueB - Segundo valor a ser comparado
+     * @returns true se valueA !== valueB, false caso contrário
+     * @example
+     * Guardian.isDifferent(5, "5") // true
+     * Guardian.isDifferent(5, 5) // false
+     */
     static isDifferent(valueA: unknown, valueB: unknown): boolean;
+    /**
+     * Verifica se todos os valores de um array são iguais.
+     * @template T - Tipo dos valores no array
+     * @param values - Array de valores a ser verificado
+     * @returns true se todos os valores são iguais, false caso contrário
+     * @example
+     * Guardian.allEqual([5, 5, 5]) // true
+     * Guardian.allEqual([5, 5, 3]) // false
+     */
+    static allEqual<T>(values: T[]): boolean;
+    /**
+     * Verifica se um valor específico existe em uma coleção de valores.
+     * @param reference - Valor a ser procurado
+     * @param anyValues - Array de valores onde procurar
+     * @returns true se reference existe em anyValues, false caso contrário
+     * @example
+     * Guardian.isAnyOf(3, [1, 2, 3, 4]) // true
+     * Guardian.isAnyOf(5, [1, 2, 3, 4]) // false
+     */
     static isAnyOf(reference: unknown, anyValues: unknown[]): boolean;
-    static ternaryCondition<TTrue, TFalse>(condition: boolean, returnIfTrue: TTrue, returnIfFalse: TFalse): TTrue | TFalse;
-    static isBetween(value: number | string, min: number, max: number): boolean;
-    static isNullOrUndefined(value: unknown): value is null | undefined;
-    static isNotNullOrUndefined(value: unknown): value is boolean;
+    /**
+     * Verifica se uma string é um endereço de email válido.
+     * @param value - String a ser validada como email
+     * @returns true se value é um email válido, false caso contrário
+     * @example
+     * Guardian.isEmail("user@example.com") // true
+     * Guardian.isEmail("invalid-email") // false
+     */
+    static isEmail(value: string): boolean;
+    /**
+     * Verifica se uma string é uma URL válida.
+     * @param value - String a ser validada como URL
+     * @returns true se value é uma URL válida, false caso contrário
+     * @example
+     * Guardian.isURL("https://example.com") // true
+     * Guardian.isURL("not a url") // false
+     */
+    static isURL(value: string): boolean;
+    /**
+     * Verifica se uma string é um UUID (Universally Unique Identifier) válido.
+     * @param value - String a ser validada como UUID
+     * @returns true se value é um UUID válido, false caso contrário
+     * @example
+     * Guardian.isUUID("550e8400-e29b-41d4-a716-446655440000") // true
+     * Guardian.isUUID("invalid-uuid") // false
+     */
+    static isUUID(value: string): boolean;
+    /**
+     * Verifica se um valor é do tipo booleano.
+     * @param value - Valor a ser verificado
+     * @returns true se value é um booleano, false caso contrário
+     * @example
+     * Guardian.isBoolean(true) // true
+     * Guardian.isBoolean(1) // false
+     */
+    static isBoolean(value: unknown): value is boolean;
+    /**
+     * Verifica se um valor é uma função.
+     * @param value - Valor a ser verificado
+     * @returns true se value é uma função, false caso contrário
+     * @example
+     * Guardian.isFunction(() => {}) // true
+     * Guardian.isFunction("função") // false
+     */
+    static isFunction(value: unknown): value is Function;
+    /**
+     * Verifica se um valor é um objeto Date válido.
+     * @param value - Valor a ser verificado
+     * @returns true se value é uma data válida, false caso contrário
+     * @example
+     * Guardian.isDate(new Date()) // true
+     * Guardian.isDate(new Date("invalid")) // false
+     * Guardian.isDate("2024-01-01") // false
+     */
+    static isDate(value: unknown): value is Date;
+    /**
+     * Verifica se todos os elementos de um array satisfazem um predicado.
+     * @template T - Tipo dos elementos do array
+     * @param array - Array a ser verificado
+     * @param predicate - Função que retorna true/false para cada elemento
+     * @returns true se todos os elementos satisfazem o predicado, false caso contrário
+     * @example
+     * Guardian.isEveryOf([2, 4, 6], x => x % 2 === 0) // true
+     * Guardian.isEveryOf([2, 3, 6], x => x % 2 === 0) // false
+     */
+    static isEveryOf<T>(array: T[], predicate: (item: T) => boolean): boolean;
+    /**
+     * Verifica se pelo menos um elemento de um array satisfaz um predicado.
+     * @template T - Tipo dos elementos do array
+     * @param array - Array a ser verificado
+     * @param predicate - Função que retorna true/false para cada elemento
+     * @returns true se pelo menos um elemento satisfaz o predicado, false caso contrário
+     * @example
+     * Guardian.isSomeOf([1, 2, 4], x => x % 2 === 0) // true
+     * Guardian.isSomeOf([1, 3, 5], x => x % 2 === 0) // false
+     */
+    static isSomeOf<T>(array: T[], predicate: (item: T) => boolean): boolean;
+    /**
+     * Verifica se um valor que possui propriedade length tem exatamente o comprimento específico.
+     * @template T - Tipo do valor com propriedade length
+     * @param value - Valor a ser verificado
+     * @param length - Comprimento esperado
+     * @returns true se o comprimento é exatamente o especificado, false caso contrário
+     * @example
+     * Guardian.hasLength("hello", 5) // true
+     * Guardian.hasLength([1, 2, 3], 3) // true
+     * Guardian.hasLength([1, 2], 3) // false
+     */
+    static hasLength<T extends {
+        length: number;
+    }>(value: T, length: number): boolean;
+    /**
+     * Verifica se um valor existe dentro de uma coleção.
+     * @template T - Tipo dos valores
+     * @param value - Valor a ser procurado
+     * @param collection - Coleção onde procurar
+     * @returns true se value está na coleção, false caso contrário
+     * @example
+     * Guardian.isWithin(3, [1, 2, 3, 4]) // true
+     * Guardian.isWithin(5, [1, 2, 3, 4]) // false
+     */
+    static isWithin<T>(value: T, collection: T[]): boolean;
+    /**
+     * Verifica se um valor não existe dentro de uma coleção.
+     * @template T - Tipo dos valores
+     * @param value - Valor a ser procurado
+     * @param collection - Coleção onde procurar
+     * @returns true se value não está na coleção, false caso contrário
+     * @example
+     * Guardian.isNotWithin(5, [1, 2, 3, 4]) // true
+     * Guardian.isNotWithin(3, [1, 2, 3, 4]) // false
+     */
+    static isNotWithin<T>(value: T, collection: T[]): boolean;
+    /**
+     * Verifica se um objeto possui uma propriedade específica (própria ou herdada).
+     * @template T - Tipo do objeto
+     * @param value - Objeto a ser verificado
+     * @param property - Nome da propriedade a procurar
+     * @returns true se o objeto possui a propriedade, false caso contrário
+     * @example
+     * Guardian.hasProperty({ name: "João" }, "name") // true
+     * Guardian.hasProperty({ name: "João" }, "age") // false
+     */
+    static hasProperty<T extends object>(value: T, property: PropertyKey): property is keyof T;
+    /**
+     * Verifica se um objeto possui uma propriedade própria (não herdada).
+     * @template T - Tipo do objeto
+     * @param value - Objeto a ser verificado
+     * @param property - Nome da propriedade a procurar
+     * @returns true se o objeto possui a propriedade própria, false caso contrário
+     * @example
+     * Guardian.hasOwnProperty({ name: "João" }, "name") // true
+     * Guardian.hasOwnProperty({ name: "João" }, "toString") // false
+     */
+    static hasOwnProperty<T extends object>(value: T, property: PropertyKey): property is keyof T;
+    /**
+     * Verifica se um valor é do tipo primitivo especificado.
+     * @template T - Tipo esperado do valor
+     * @param value - Valor a ser verificado
+     * @param type - Tipo primitivo esperado (string, number, boolean, etc)
+     * @returns true se value é do tipo especificado, false caso contrário
+     * @example
+     * Guardian.isTypeOf("hello", "string") // true
+     * Guardian.isTypeOf(42, "number") // true
+     * Guardian.isTypeOf(42, "string") // false
+     */
+    static isTypeOf<T>(value: unknown, type: PrimitiveType): value is T;
+    /**
+     * Verifica se um valor não é do tipo primitivo especificado.
+     * @template T - Tipo esperado do valor
+     * @param value - Valor a ser verificado
+     * @param type - Tipo primitivo a ser descartado
+     * @returns true se value não é do tipo especificado, false caso contrário
+     * @example
+     * Guardian.isNotTypeOf(42, "string") // true
+     * Guardian.isNotTypeOf("hello", "string") // false
+     */
+    static isNotTypeOf<T>(value: unknown, type: PrimitiveType): value is T;
+    /**
+     * Verifica se um valor é uma instância de uma classe/construtor específico.
+     * @template T - Tipo esperado da instância
+     * @param value - Valor a ser verificado
+     * @param instance - Construtor/classe a ser verificado
+     * @returns true se value é uma instância de instance, false caso contrário
+     * @example
+     * Guardian.isInstanceOf(new Date(), Date) // true
+     * Guardian.isInstanceOf(new Date(), Array) // false
+     * Guardian.isInstanceOf(new User(), User) // true
+     */
+    static isInstanceOf<T>(value: unknown, instance: Newable<T>): value is T;
+    /**
+     * Verifica se um valor é do tipo numérico.
+     * @param value - Valor a ser verificado
+     * @returns true se value é um número, false caso contrário
+     */
     private static isNumber;
+    /**
+     * Verifica se um valor é do tipo string.
+     * @param value - Valor a ser verificado
+     * @returns true se value é uma string, false caso contrário
+     */
     private static isString;
+    /**
+     * Verifica se um valor é um array.
+     * @param value - Valor a ser verificado
+     * @returns true se value é um array, false caso contrário
+     */
     private static isArray;
+    /**
+     * Verifica se um valor é um objeto.
+     * @param value - Valor a ser verificado
+     * @returns true se value é um objeto, false caso contrário
+     */
     private static isObject;
-    static isTypeOf<T>(value: unknown, type: PrimitiveType): value is T;
-    static isNotTypeOf<T>(value: unknown, type: PrimitiveType): value is T;
 }
 export { Guardian as _ };