@seniorsistemas/hcm-clocking-event-rule-nodejs 0.35.0

package/src/utils/dateIntervalUtils.ts

@@ -0,0 +1,284 @@
+import { DateUtils } from "./dateUtils";
+
+/**
+ * Representa um intervalo de datas, com uma data inicial e uma data final.
+ * O intervalo é considerado válido se a data inicial for anterior ou igual à data final.
+ * 
+ * @example
+ * ```typescript
+ * 
+ * const interval = new DateInterval(new Date('2023-01-01'), new Date('2023-01-05'));
+ * console.log(interval.start); // 2023-01-01T00:00:00.000Z.
+ * console.log(interval.end);   // 2023-01-05T00:00:00.000Z.
+ * 
+ * // Intervalo inválido.
+ * const invalidInterval = new DateInterval(new Date('2023-01-05'), new Date('2023-01-01')); // Lança erro.
+ * 
+ * // Exemplo de uso em comparação de intervalos.
+ * const interval1 = new DateInterval(new Date('2023-01-01'), new Date('2023-01-05'));
+ * const interval2 = new DateInterval(new Date('2023-01-03'), new Date('2023-01-07'));
+ * 
+ * // Verifica se interval1 está antes ou é igual a interval2.
+ * const isBeforeOrEquals = DateIntervalUtils.isBeforeOrEquals(interval1, interval2);
+ * console.log(isBeforeOrEquals); // true
+ * ```
+ * 
+ */
+export class DateInterval {
+    private readonly _start: Date;
+    private readonly _end: Date;
+
+    /**
+     * Criação de um intervalo de datas.
+     * @param start Início do intervalo.
+     * @param end Fim do intervalo.
+     * @throws Error se a data inicial for posterior à data final.
+     */
+    constructor(start: Date, end: Date) {
+        if (start > end) {
+            throw new Error("Start date must be before or equal to end date.");
+        }
+        this._start = start;
+        this._end = end;
+    }
+
+    /**
+     * Retorna a data inicial do intervalo.
+     * 
+     * @example
+     * ```typescript
+     * const interval = new DateInterval(new Date('2023-01-01'), new Date('2023-01-05'));
+     * console.log(interval.start); // 2023-01-01T00:00:00.000Z.
+     * ```
+     * 
+     */
+    get start(): Date {
+        return this._start;
+    }
+    /**
+     * Retorna a data final do intervalo.
+     * 
+     * @example
+     * ```typescript
+     * const interval = new DateInterval(new Date('2023-01-01'), new Date('2023-01-05'));
+     * console.log(interval.end); // 2023-01-05T00:00:00.000Z.
+     * ```
+     */
+    get end(): Date {
+        return this._end;
+    }
+
+    /**
+     * Representa o intervalo de datas como uma string no formato ISO.
+     * @example
+     * ```typescript
+     * const interval = new DateInterval(new Date('2023-01-01'), new Date('2023-01-05'));
+     * console.log(interval.toString()); // DateInterval [start=2023-01-01T00:00:00.000Z, end=2023-01-05T00:00:00.000Z].
+     * ```
+     * @returns 
+     */
+    toString(): string {
+        return `DateInterval [start=${this._start.toISOString()}, end=${this._end.toISOString()}]`;
+    }
+}
+
+/**
+ * Classe utilitária para manipulação de intervalos de datas.
+ * Fornece métodos para verificar relações entre intervalos, como se um intervalo está antes,
+ * depois, se sobrepõe ou se está contido em outro intervalo.
+ * 
+ * @example
+ * ```typescript
+ * import { DateInterval, DateIntervalsUtils } from './DateIntervalUtils';
+ * const interval = new DateInterval(new Date('2023-01-01'), new Date('2023-01-05'));
+ * const intervalComp = new DateInterval(new Date('2023-01-03'), new Date('2023-01-07'));
+ * // Verifica se interval1 está antes ou é igual a interval2.
+ * const isBeforeOrEquals = DateIntervalsUtils.isBeforeOrEquals(interval, intervalComp);
+ * console.log(isBeforeOrEquals); // true
+ * ```
+ */
+export const DateIntervalUtils = {
+
+    /**
+     * Verifica se o fim do intervalo `interval` está antes ou é igual ao início do intervalo `comparedInterval`.
+     * ```
+     * Representações
+     * 
+     * interval........: |====|
+     * comparedInterval:          |----|
+     *
+     * interval........: |======|
+     * comparedInterval:        |------|
+     * ```
+     * 
+     * @example
+     * ```typescript
+     * const interval = new DateInterval(new Date('2023-01-01'), new Date('2023-01-05'));
+     * const comparedInterval = new DateInterval(new Date('2023-01-06'), new Date('2023-01-10'));
+     * // Verifica se o fim do intervalo `interval` está antes ou é igual ao início do intervalo `comparedInterval`.
+     * const isBeforeOrEquals = DateIntervalUtils.isBeforeOrEquals(interval, comparedInterval);
+     * console.log(isBeforeOrEquals); // true
+     * ```
+     * 
+     * @param interval intervalo.
+     * @param comparedInterval intervalo a ser comparado.
+     * @returns Se o fim do intervalo está antes ou é igual ao início do intervalo comparado.
+     */
+    isBeforeOrEquals(interval: DateInterval, comparedInterval: DateInterval): boolean {
+        return DateUtils.isBeforeOrEquals(interval.end, comparedInterval.start);
+    },
+
+    /**
+     * Verifica se o início do intervalo `interval` está depois ou é igual ao fim do intervalo `comparedInterval`.
+     * ```
+     * Representações
+     * 
+     * interval........:          |====|
+     * comparedInterval: |----|
+     *
+     * interval........:        |======|
+     * comparedInterval: |------|
+     * ```
+     * 
+     * @example
+     * ```typescript
+     * const interval = new DateInterval(new Date('2023-01-06'), new Date('2023-01-10'));
+     * const comparedInterval = new DateInterval(new Date('2023-01-01'), new Date('2023-01-05'));
+     * // Verifica se o início do intervalo `interval` está depois ou é igual ao fim do intervalo `comparedInterval`.
+     * const isAfterOrEquals = DateIntervalUtils.isAfterOrEquals(interval, comparedInterval);
+     * console.log(isAfterOrEquals); // true
+     * ```
+     * 
+     * @param interval Intervalo.
+     * @param compareInterval intervalo a ser comparado.
+     * @returns Se o início do intervalo está depois ou é igual ao fim do intervalo comparado.
+     */
+    isAfterOrEquals(interval: DateInterval, compareInterval: DateInterval): boolean {
+        return DateUtils.isAfterOrEquals(interval.start, compareInterval.end);
+    },
+
+    /**
+     * Verifica se o intervalo `interval` sobrepõe completamente o intervalo `comparedInterval`.
+     * Se o intervalo for igual também será considerado sobreposto.
+     * ```
+     * Representações
+     * 
+     * interval........: |========|
+     * comparedInterval:   |----|
+     *
+     * interval........: |========|
+     * comparedInterval: |--------|
+     * ```
+     * @example
+     * ```typescript
+     * const interval = new DateInterval(new Date('2023-01-01'), new Date('2023-01-05'));
+     * const comparedInterval = new DateInterval(new Date('2023-01-02'), new Date('2023-01-04'));
+     * // Verifica se o intervalo `interval` sobrepõe completamente o intervalo `comparedInterval`.
+     * const isOverlaps = DateIntervalUtils.overlaps(interval, comparedInterval);
+     * console.log(isOverlaps); // true
+     * ```
+     * 
+     * @param interval Intervalo a ser verificado.
+     * @param comparedInterval Intervalo comparado.
+     * @returns Se o intervalo sobrepõe ao intervalo comparado.
+     */
+    overlaps(interval: DateInterval, comparedInterval: DateInterval): boolean {
+        return DateUtils.isBeforeOrEquals(interval.start, comparedInterval.start) &&
+            DateUtils.isAfterOrEquals(interval.end, comparedInterval.end);
+    },
+
+    /**
+     * Verifica se o intervalo `interval` está completamente dentro do intervalo `compareInterval`.
+     * Se o intervalo for igual também será considerado dentro.
+     * ```
+     * Representações
+     * 
+     * interval........:   |====|
+     * comparedInterval: |--------|
+     *
+     * interval........: |========|
+     * comparedInterval: |--------|
+     * ```
+     * 
+     * @example
+     * ```typescript
+     * const interval = new DateInterval(new Date('2023-01-02'), new Date('2023-01-04'));
+     * const comparedInterval = new DateInterval(new Date('2023-01-01'), new Date('2023-01-05'));
+     * // Verifica se o intervalo `interval` está completamente dentro do intervalo `compareInterval`.
+     * const isInto = DateIntervalUtils.into(interval, comparedInterval);
+     * console.log(isInto); // true
+     * ```
+     * 
+     * @param interval Intervalo a ser verificado.
+     * @param comparedInterval Intervalo comparado.
+     * @returns Se o intervalo está completamente dentro do intervalo comparado.
+     * */
+    into(interval: DateInterval, comparedInterval: DateInterval): boolean {
+        return DateUtils.isBeforeOrEquals(comparedInterval.start, interval.start) &&
+            DateUtils.isAfterOrEquals(comparedInterval.end, interval.end);
+    },
+
+    /**
+     * Verifica se o intervalo `interval` sobrepõe o início do intervalo `compareInterval`.
+     * ```
+     * Representações
+     * 
+     * interval........: |=======|
+     * compareInterval:     |-------|
+     *
+     * interval........:    |====|
+     * compareInterval:     |-------|
+     * ```
+     * 
+     * @example
+     * ```typescript
+     * const interval = new DateInterval(new Date('2023-01-01'), new Date('2023-01-05'));
+     * const comparedInterval = new DateInterval(new Date('2023-01-03'), new Date('2023-01-07'));
+     * // Verifica se o intervalo `interval` sobrepõe o início do intervalo `compareInterval`.
+     * const isOverStart = DateIntervalUtils.isOverStart(interval, comparedInterval);
+     * console.log(isOverStart); // true
+     * ```
+     * 
+     * @param interval Intervalo a ser verificado.
+     * @param comparedInterval Intervalo comparado.
+     * @returns Se o intervalo sobrepõe o início do intervalo comparado.
+     * 
+     */
+    isOverStart(interval: DateInterval, comparedInterval: DateInterval): boolean {
+        return DateUtils.isBeforeOrEquals(interval.start, comparedInterval.start) &&
+            DateUtils.isAfter(interval.end, comparedInterval.start) &&
+            DateUtils.isBefore(interval.end, comparedInterval.end);
+    },
+
+    /**
+     * Verifica se o intervalo `interval` começa depois e está sobre o fim do intervalo `compareInterval`.
+     * ```
+     * Representações
+     * 
+     * interval........:     |=======|
+     * compareInterval: |-------|
+     *
+     * interval........:   |====|
+     * compareInterval: |-------|
+     * ````
+     * 
+     * @example
+     * ```typescript
+     * const interval = new DateInterval(new Date('2023-01-03'), new Date('2023-01-07'));
+     * const comparedInterval = new DateInterval(new Date('2023-01-01'), new Date('2023-01-05'));
+     * * // Verifica se o intervalo `interval` começa depois e está sobre o fim do intervalo `compareInterval`.
+     * const isOverEnd = DateIntervalUtils.isOverEnd(interval, comparedInterval);
+     * console.log(isOverEnd); // true
+     * ```
+     * @param interval Intervalo a ser verificado.
+     * @param comparedInterval Intervalo comparado.
+     * @returns Se o intervalo sobrepõe o fim do intervalo comparado.
+     * 
+     * 
+     */
+    isOverEnd(interval: DateInterval, comparedInterval: DateInterval): boolean {
+        return DateUtils.isAfter(interval.start, comparedInterval.start) &&
+            DateUtils.isBefore(interval.start, comparedInterval.end) &&
+            DateUtils.isAfterOrEquals(interval.end, comparedInterval.end);
+    }
+}