@elderbyte/ngx-starter 14.10.0 → 14.11.1

package/src/lib/common/time/date-util.ts

@@ -0,0 +1,120 @@
+/**
+ * Represents an ISO-8601 date string.
+ * https://en.wikipedia.org/wiki/ISO_8601#Dates
+ */
+import {Instant} from '@js-joda/core';
+
+export type IsoDateStr = string;
+
+export class DateUtil {
+
+  public static readonly IsoDateDelimiter = '-';
+  public static readonly IsoTimeDelimiter = ':';
+  public static readonly DateTimeSeparator = 'T';
+
+  /***************************************************************************
+   *                                                                         *
+   * Public API                                                              *
+   *                                                                         *
+   **************************************************************************/
+
+  public static instantToDate(instant: Instant): Date {
+    return new Date(instant.toEpochMilli());
+  }
+
+  /**
+   * Returns the given Date as ISO formatted local date string.
+   *
+   * YYYY-MM-DD
+   *
+   * @param date
+   */
+  public static toLocalDateIso(date: Date): string {
+    return DateUtil.dateString(date);
+  }
+
+  /**
+   * Returns the given Date as ISO formatted local date-time string.
+   *
+   * YYYY-MM-DDTHH:mm:ss.sss
+   *
+   * @param date
+   */
+  public static toLocalDateTimeIso(date: Date): string {
+    const dateString = DateUtil.toLocalDateIso(date);
+    const timeString = DateUtil.timeString(date);
+    return dateString + DateUtil.DateTimeSeparator + timeString;
+  }
+
+  /**
+   * Checks if the given DateTime is represents the start of the day.
+   *
+   * @param dateTime DateTime to check
+   */
+  public static isStartOfDay(date: Date): boolean {
+    date = new Date(date);
+    return date.getMilliseconds() === 0
+      && date.getSeconds() === 0
+      && date.getMinutes() === 0
+      && date.getHours() === 0;
+  }
+
+  /**
+   * Sets the given Date to the start of its day by setting its time to 0.
+   *
+   * @param localDate Date to set to start of day
+   */
+  public static startOfDay(localDate: Date): Date {
+    const startOfDay = new Date(localDate);
+    startOfDay.setHours(0, 0, 0, 0);
+    return startOfDay;
+  }
+
+  public static plusDays(date: Date, days: number): Date {
+    const plus = new Date(date);
+    plus.setDate(plus.getDate() + days);
+    return plus;
+  }
+
+  /***************************************************************************
+   *                                                                         *
+   * private Methods                                                         *
+   *                                                                         *
+   **************************************************************************/
+
+  private static dateString(date: Date): string {
+    const values = [
+      String(date.getFullYear()),
+      DateUtil.format(date.getMonth() + 1),
+      DateUtil.format(date.getDate())
+    ];
+
+    return values.join(DateUtil.IsoDateDelimiter);
+  }
+
+  private static timeString(date: Date): string {
+
+    const values = [
+      DateUtil.format(date.getHours()),
+      DateUtil.format(date.getMinutes()),
+      DateUtil.format(date.getSeconds())
+    ];
+
+    return values.join(DateUtil.IsoTimeDelimiter) +
+      '.' +
+      DateUtil.format(date.getMilliseconds(), 3);
+
+  }
+
+  private static format(value: number, digitCount = 2): string {
+    let zeros = '';
+
+    for (let i = 0; i < digitCount; i++) {
+      zeros += '0';
+    }
+
+    return (zeros + value).slice(-digitCount);
+  }
+
+
+}

package/src/lib/common/time/interval.spec.ts

@@ -0,0 +1,53 @@
+import {Interval} from './interval';
+import {LocalDate, ZoneId} from '@js-joda/core';
+import '@js-joda/timezone';
+
+describe('Interval Test', () => {
+
+  beforeEach(async () => {
+  });
+
+  beforeEach(() => {
+  });
+
+  it('Europe/Zurich Zone', () => {
+    const ch = ZoneId.of('Europe/Zurich');
+    expect(ch.id()).toEqual('Europe/Zurich');
+  });
+
+  it('Ensure Europe Timezones are loaded', () => {
+    const zoneIds = ZoneId.getAvailableZoneIds().filter(zid => zid.startsWith('Europe/'));
+    expect(zoneIds.length).toBeGreaterThan(20);
+  });
+
+  it('Interval.ofDay Swiss Winter', () => {
+    const swiss = ZoneId.of('Europe/Zurich');
+    const iv = Interval.ofDay(
+      LocalDate.of(2022, 2, 28),
+      swiss
+    );
+    expect(iv.start.toJSON()).toEqual('2022-02-27T23:00:00Z');
+    expect(iv.end.toJSON()).toEqual('2022-02-28T23:00:00Z');
+  });
+
+  it('Interval.ofDay Swiss shift_day', () => {
+    const swiss = ZoneId.of('Europe/Zurich');
+    const iv = Interval.ofDay(
+      LocalDate.of(2022, 3, 27),
+      swiss
+    );
+    expect(iv.start.toJSON()).toEqual('2022-03-26T23:00:00Z');
+    expect(iv.end.toJSON()).toEqual('2022-03-27T22:00:00Z');
+  });
+
+  it('Interval.ofDay Summer Time', () => {
+    const swiss = ZoneId.of('Europe/Zurich');
+    const iv = Interval.ofDay(
+      LocalDate.of(2022, 4, 28),
+      swiss
+    );
+    expect(iv.start.toJSON()).toEqual('2022-04-27T22:00:00Z');
+    expect(iv.end.toJSON()).toEqual('2022-04-28T22:00:00Z');
+  });
+
+});

package/src/lib/common/time/interval.ts

@@ -0,0 +1,539 @@
+import {DateUtil} from './date-util';
+import {Duration, Instant, LocalDate, nativeJs, Period, TemporalAmount, ZoneId} from '@js-joda/core';
+import {TimeUtil} from './time-util';
+import {PeriodDuration} from './period-duration';
+
+/**
+ * Represents an ISO-8601 interval string.
+ * https://en.wikipedia.org/wiki/ISO_8601#Time_intervals
+ */
+export type IsoIntervalStr = string;
+
+export class Interval {
+
+
+  /***************************************************************************
+   *                                                                         *
+   * Constructor                                                             *
+   *                                                                         *
+   **************************************************************************/
+
+  constructor(
+    public readonly start: Instant,
+    public readonly end: Instant
+  ) { }
+
+  /***************************************************************************
+   *                                                                         *
+   * Static Builders                                                         *
+   *                                                                         *
+   **************************************************************************/
+
+  /**
+   * Parses an ISO-8601 interval string.
+   * https://en.wikipedia.org/wiki/ISO_8601#Time_intervals
+   * @param iso
+   */
+  public static parse(
+    iso: IsoIntervalStr
+  ): Interval {
+    const parts = iso.split('/');
+
+    if (parts.length !== 2) {
+      throw new Error('The given string is not a valid iso interval: ' + iso);
+    }
+
+    const start = Instant.parse(parts[0]);
+
+    const endStr = parts[1];
+
+    // The 'end' part can either be an instant or a duration in iso format
+
+    if (endStr.startsWith('P') || endStr.startsWith('-P')) {
+
+      const duration = Duration.parse(endStr);
+
+      return Interval.ofStartAndOffset(
+        start,
+        duration
+      );
+    } else {
+      return Interval.of(
+        start,
+        Instant.parse(endStr)
+      );
+    }
+  }
+
+  public static yesterday(zoneId: ZoneId): Interval {
+    return Interval.ofDay(
+      LocalDate.now().minusDays(1),
+      zoneId
+    );
+  }
+
+  public static  tomorrow(zoneId: ZoneId): Interval {
+    return Interval.ofDay(
+      LocalDate.now().plusDays(1),
+      zoneId
+    );
+  }
+
+  public static today(zoneId: ZoneId): Interval {
+    return Interval.ofDay(LocalDate.now(), zoneId);
+  }
+
+  /**
+   * Creates a Interval from a Date by spreading it to the begin and end of its day.
+   * @param date Date to spread
+   */
+  public static ofDayDate(date: Date): Interval {
+    const localDate = LocalDate.from(nativeJs(date));
+    return Interval.ofDay(localDate, ZoneId.systemDefault());
+  }
+
+  public static ofDay(day: LocalDate, zoneId: ZoneId): Interval {
+    return Interval.betweenDays(
+      day,
+      day.plusDays(1),
+      zoneId
+    );
+  }
+
+  public static betweenDays(
+    startDayInclusive: LocalDate,
+    endDayExclusive: LocalDate,
+    zoneId: ZoneId
+  ) {
+    return Interval.of(
+      startDayInclusive.atStartOfDay(zoneId).toInstant(),
+      endDayExclusive.atStartOfDay(zoneId).toInstant()
+    );
+  }
+
+
+
+  /**
+   * Creates a new interval with the given start time point
+   * and a offset from the start.
+   *
+   * Note that you should use Period for days to account for zone specific
+   * things like daylight saving.
+   *
+   * @param startInclusive
+   * @param offsetExclusive A Period or Duration offset.
+   */
+  public static ofStartAndOffset(startInclusive: Instant, offsetExclusive: TemporalAmount): Interval {
+    return Interval.of(
+      startInclusive,
+      startInclusive.plus(offsetExclusive)
+    );
+  }
+
+  public static of(
+    startInclusive: Instant,
+    endExclusive: Instant
+  ): Interval {
+    return new Interval(
+      startInclusive,
+      endExclusive
+    );
+  }
+
+  public static ofDate(
+    startInclusive: Date | string,
+    endExclusive: Date | string
+  ): Interval {
+    return new Interval(
+      TimeUtil.instant(startInclusive),
+      TimeUtil.instant(endExclusive)
+    );
+  }
+
+  /***************************************************************************
+   *                                                                         *
+   * Properties                                                              *
+   *                                                                         *
+   **************************************************************************/
+
+  /**
+   * Checks if the range is empty.
+   * <p>
+   * An empty range occurs when the start date equals the inclusive end date.
+   *
+   * @return true if the range is empty
+   */
+  public isEmpty(): boolean {
+    return this.start.equals(this.end);
+  }
+
+  /**
+   * Checks if the start of the interval is unbounded.
+   *
+   * @return true if start is unbounded
+   */
+  public isUnboundedStart(): boolean {
+    return this.start.equals(Instant.MIN);
+  }
+
+  /**
+   * Checks if the end of the interval is unbounded.
+   *
+   * @return true if end is unbounded
+   */
+  public isUnboundedEnd(): boolean {
+    return this.end.equals(Instant.MAX);
+  }
+
+  /***************************************************************************
+   *                                                                         *
+   * Public API                                                              *
+   *                                                                         *
+   **************************************************************************/
+
+  public toDuration(): Duration {
+    return Duration.between(this.start, this.end);
+  }
+
+  public toPeriodDuration(zone: ZoneId): PeriodDuration {
+    return PeriodDuration.between(
+      this.start.atZone(zone),
+      this.end.atZone(zone)
+    );
+  }
+
+  public toString(): IsoIntervalStr {
+    return this.toDurationString();
+  }
+
+  public toInstantString(): IsoIntervalStr {
+    return this.start.toString() + '/' + this.end.toString();
+  }
+
+  public toDurationString(): IsoIntervalStr {
+    return this.start.toString() + '/' + this.toDuration().toString();
+  }
+
+  /***************************************************************************
+   *                                                                         *
+   * Public Modification API                                                 *
+   *                                                                         *
+   **************************************************************************/
+
+  /**
+   * Returns a copy of this range with the specified start instant.
+   *
+   * @param start  the start instant for the new interval, not null
+   * @return an interval with the end from this interval and the specified start
+   * @throws DateTimeException if the resulting interval has end before start
+   */
+  public withStart(start: Instant): Interval {
+    return Interval.of(start, this.end);
+  }
+
+  /**
+   * Returns a copy of this range with the specified end instant.
+   *
+   * @param end  the end instant for the new interval, not null
+   * @return an interval with the start from this interval and the specified end
+   * @throws DateTimeException if the resulting interval has end before start
+   */
+  public withEnd(end: Instant): Interval {
+    return Interval.of(this.start, end);
+  }
+
+  /**
+   * Calculates the interval that is the intersection of this interval and the specified interval.
+   * <p>
+   * This finds the intersection of two intervals.
+   * This throws an exception if the two intervals are not {@linkplain #isConnected(Interval) connected}.
+   *
+   * @param other  the other interval to check for, not null
+   * @return the interval that is the intersection of the two intervals
+   * @throws DateTimeException if the intervals do not connect
+   */
+  public intersection(other: Interval): Interval {
+    if (this.isConnected(other) === false) {
+      throw new Error('Intervals do not connect: ' + this + ' and ' + other);
+    }
+    const cmpStart = this.start.compareTo(other.start);
+    const cmpEnd = this.end.compareTo(other.end);
+    if (cmpStart >= 0 && cmpEnd <= 0) {
+      return this;
+    } else if (cmpStart <= 0 && cmpEnd >= 0) {
+      return other;
+    } else {
+      const newStart = (cmpStart >= 0 ? this.start : other.start);
+      const newEnd = (cmpEnd <= 0 ? this.end : other.end);
+      return Interval.of(newStart, newEnd);
+    }
+  }
+
+  /**
+   * Calculates the interval that is the union of this interval and the specified interval.
+   * <p>
+   * This finds the union of two intervals.
+   * This throws an exception if the two intervals are not {@linkplain #isConnected(Interval) connected}.
+   *
+   * @param other  the other interval to check for, not null
+   * @return the interval that is the union of the two intervals
+   * @throws DateTimeException if the intervals do not connect
+   */
+  public union(other: Interval): Interval {
+    if (this.isConnected(other) === false) {
+      throw new Error('Intervals do not connect: ' + this + ' and ' + other);
+    }
+    const cmpStart = this.start.compareTo(other.start);
+    const cmpEnd = this.end.compareTo(other.end);
+    if (cmpStart >= 0 && cmpEnd <= 0) {
+      return other;
+    } else if (cmpStart <= 0 && cmpEnd >= 0) {
+      return this;
+    } else {
+      const newStart = (cmpStart >= 0 ? other.start : this.start);
+      const newEnd = (cmpEnd <= 0 ? other.end : this.end);
+      return Interval.of(newStart, newEnd);
+    }
+  }
+
+  /**
+   * Calculates the smallest interval that encloses this interval and the specified interval.
+   * <p>
+   * The result of this method will {@linkplain #encloses(Interval) enclose}
+   * this interval and the specified interval.
+   *
+   * @param other  the other interval to check for, not null
+   * @return the interval that spans the two intervals
+   */
+  public span(other: Interval): Interval {
+    const cmpStart = this.start.compareTo(other.start);
+    const cmpEnd = this.end.compareTo(other.end);
+    const newStart = (cmpStart >= 0 ? other.start : this.start);
+    const newEnd = (cmpEnd <= 0 ? other.end : this.end);
+    return Interval.of(newStart, newEnd);
+  }
+
+
+  /**
+   * Shift the whole interval by the given days period.
+   * @param days
+   */
+  public shiftDays(days: number): Interval {
+    return this.shift(Period.ofDays(days));
+  }
+
+  /**
+   * Shift the whole interval by the given temporal amount.
+   * Note that only Period will account for zone specific things such as daylight savings.
+   * Use Duration only if you are below days.
+   * @param offset
+   */
+  public shift(offset: TemporalAmount): Interval {
+    return Interval.of(
+      this.start.plus(offset),
+      this.end.plus(offset)
+    );
+  }
+
+  public moveStart(offset: TemporalAmount): Interval {
+    return Interval.of(
+      this.start.plus(offset),
+      this.end
+    );
+  }
+
+  public moveEnd(offset: TemporalAmount): Interval {
+    return Interval.of(
+      this.start,
+      this.end.plus(offset)
+    );
+  }
+
+  /***************************************************************************
+   *                                                                         *
+   * Interval Query API                                                      *
+   *                                                                         *
+   **************************************************************************/
+
+
+  /**
+   * Checks if the given TimeFrame overlaps with this one.
+   *
+   * @param other TimeFrame to check against
+   * @return Returns {@code true} if the two candidates overlap, false otherwise
+   */
+  public overlaps(other: Interval): boolean {
+    return other.equals(this) || (this.start.compareTo(other.end) < 0 && other.start.compareTo(this.end) < 0);
+  }
+
+  /**
+   * Checks it the given localDate overlaps with the given TimeFrame.
+   *
+   * @param timeFrame TimeFrame to check against
+   * @param localDate LocalDate to check
+   */
+  public overlapsWithLocalDate(
+    localDate: Date
+  ): boolean {
+    return this.overlaps(Interval.ofDayDate(localDate));
+  }
+
+  /**
+   * Checks if this interval contains the specified instant.
+   * <p>
+   * This checks if the specified instant is within the bounds of this interval.
+   * If this range has an unbounded start then {@code contains(Instant#MIN)} returns true.
+   * If this range has an unbounded end then {@code contains(Instant#MAX)} returns true.
+   * If this range is empty then this method always returns false.
+   *
+   * @param instant  the instant, not null
+   * @return true if this interval contains the instant
+   */
+  public  contains(instant: Instant): boolean {
+    return this.start.compareTo(instant) <= 0 && (instant.compareTo(this.end) < 0 || this.isUnboundedEnd());
+  }
+
+  /**
+   * Checks if this interval encloses the specified interval.
+   * <p>
+   * This checks if the bounds of the specified interval are within the bounds of this interval.
+   * An empty interval encloses itself.
+   *
+   * @param other  the other interval, not null
+   * @return true if this interval contains the other interval
+   */
+  public encloses(other: Interval): boolean {
+    return this.start.compareTo(other.start) <= 0 && other.end.compareTo(this.end) <= 0;
+  }
+
+  /**
+   * Checks if this interval abuts (is next to or has a common boundary with) the specified interval.
+   * <p>
+   * The result is true if the end of this interval is the start of the other, or vice versa.
+   * An empty interval does not abut itself.
+   *
+   * @param other  the other interval, not null
+   * @return true if this interval abuts the other interval
+   */
+  public abuts(other: Interval): boolean {
+    return this.end.equals(other.start) !== this.start.equals(other.end); // !== means XOR
+  }
+
+  /**
+   * Checks if this interval is connected to the specified interval.
+   * <p>
+   * The result is true if the two intervals have an enclosed interval in common, even if that interval is empty.
+   * An empty interval is connected to itself.
+   * <p>
+   * This is equivalent to {@code (overlaps(other) || abuts(other))}.
+   *
+   * @param other  the other interval, not null
+   * @return true if this interval is connected to the other interval
+   */
+  public isConnected(other: Interval): boolean {
+    return this.equals(other) || (this.start.compareTo(other.end) <= 0 && other.start.compareTo(this.end) <= 0);
+  }
+
+  // ---
+
+  /**
+   * Checks if this interval is after the specified instant.
+   * <p>
+   * The result is true if this instant starts after the specified instant.
+   * An empty interval behaves as though it is an instant for comparison purposes.
+   *
+   * @param instant  the other instant to compare to, not null
+   * @return true if the start of this interval is after the specified instant
+   */
+  public isAfterInstant(instant: Instant): boolean {
+    return this.start.compareTo(instant) > 0;
+  }
+
+  /**
+   * Checks if this interval is before the specified instant.
+   * <p>
+   * The result is true if this instant ends before the specified instant.
+   * Since intervals do not include their end points, this will return true if the
+   * instant equals the end of the interval.
+   * An empty interval behaves as though it is an instant for comparison purposes.
+   *
+   * @param instant  the other instant to compare to, not null
+   * @return true if the start of this interval is before the specified instant
+   */
+  public isBeforeInstant(instant: Instant): boolean {
+    return this.end.compareTo(instant) <= 0 && this.start.compareTo(instant) < 0;
+  }
+
+  /**
+   * Checks if this interval is after the specified interval.
+   * <p>
+   * The result is true if this instant starts after the end of the specified interval.
+   * Since intervals do not include their end points, this will return true if the
+   * instant equals the end of the interval.
+   * An empty interval behaves as though it is an instant for comparison purposes.
+   *
+   * @param interval  the other interval to compare to, not null
+   * @return true if this instant is after the specified instant
+   */
+  public isAfter(interval: Interval): boolean {
+    return this.start.compareTo(interval.end) >= 0 && !interval.equals(this);
+  }
+
+  /**
+   * Checks if this interval is before the specified interval.
+   * <p>
+   * The result is true if this instant ends before the start of the specified interval.
+   * Since intervals do not include their end points, this will return true if the
+   * two intervals abut.
+   * An empty interval behaves as though it is an instant for comparison purposes.
+   *
+   * @param interval  the other interval to compare to, not null
+   * @return true if this instant is before the specified instant
+   */
+  public isBefore(interval: Interval): boolean {
+    return this.end.compareTo(interval.start) <= 0 && !interval.equals(this);
+  }
+
+
+
+/***************************************************************************
+   *                                                                         *
+   * Equality & Hashcode                                                     *
+   *                                                                         *
+   **************************************************************************/
+
+  /**
+   * Checks if this interval is equal to another interval.
+   * <p>
+   * Compares this {@code Interval} with another ensuring that the two instants are the same.
+   * Only objects of type {@code Interval} are compared, other types return false.
+   *
+   * @param obj  the object to check, null returns false
+   * @return true if this is equal to the other interval
+   */
+  public equals(obj: any): boolean {
+    if (this === obj) {
+      return true;
+    }
+    if (obj instanceof Interval) {
+      const other = <Interval> obj;
+      return this.start.equals(other.start) && this.end.equals(other.end);
+    }
+    return false;
+  }
+
+  /**
+   * Compares this Interval to the given Interval.
+   * <p>
+   * The comparison is based on the time-line position of the lower bound instants (Interval start).
+   *
+   * @param other the other Interval to compare to, not null
+   * @return the comparator value, negative if less, positive if greater
+   * @throws NullPointerException if other is null
+   */
+  public compareTo(other: Interval): number {
+    return this.start.compareTo(other.start);
+  }
+
+
+}