@tactics/toddle-styleguide 5.3.1 → 5.3.3

package/src/utilities/datetime/dateonly.class.tsx

@@ -0,0 +1,287 @@
+import {Day, DayOutputFormat} from './day.class';
+import {DayOfWeek, ZeroBasedWeekdayNumbers} from './dayoftheweek.class';
+import {Month, MonthIndex, MonthLocalAwareOutputFormat, MonthOutputFormat} from './month.class';
+import {Year, YearOutputFormat} from './year.class';
+import dayjs, {Dayjs} from 'dayjs';
+import {YearAndMonth, YearAndMonthLocaleAwareOutputFormat, YearAndMonthOutputFormat} from './yearandmonth.class';
+import {Locale} from './locale';
+
+export class InvalidDate extends Error {
+  static invalidDate() {
+    return new InvalidDate("The provided date is invalid.");
+  }
+
+  static invalidDateFormat() {
+    return new InvalidDate("The provided date format is invalid.");
+  }
+}
+
+export enum DateOnlyOutputFormat {
+  /** ISO 8601 standard format (e.g., 2024-10-18) */
+  DATEONLY_ISO8601 = "yyyy-MM-dd",
+
+  /** Format in most european countries (e.g., 18-10-2024) */
+  DATEONLY_DAY_MONTH_YEAR_DASH = "dd-MM-yyyy",
+
+  /** Format in uk, france, ... (e.g., 18/10/2024) */
+  DATEONLY_DAY_MONTH_YEAR_SLASH = "dd/MM/yyyy",
+
+  /** Format in usa, with month first (e.g., 10/18/2024) */
+  DATEONLY_MONTH_DAY_YEAR_SLASH = "MM/dd/yyyy",
+
+  /** Format in germany (e.g., 18.10.2024) */
+  DATEONLY_DAY_MONTH_YEAR_PERIOD = "dd.MM.yyyy",
+
+  /** Custom format often used in logging (e.g., 20241018) */
+  DATEONLY_COMPACT = "yyyyMMdd",
+
+}
+
+export enum DateOnlyLocaleAwareOutputFormat {
+
+  /** Full month name with day and year (e.g., October 18, 2024) */
+  DATEONLY_FULL = "ddd, D MMM YYYY",
+}
+
+
+export interface DateOnlyCalculation {
+  years?: number;
+  months?: number;
+  days?: number;
+}
+
+export interface DateOnlyInterface {
+  year: Year;
+  month: Month;
+  day: Day;
+  dayOfWeek: DayOfWeek;
+
+  isSame(zone: DateOnlyInterface): boolean;
+  isBefore(dateOnly: DateOnlyInterface): boolean;
+  isAfter(dateOnly: DateOnlyInterface): boolean;
+
+  format(format: DateOnlyOutputFormat): string;
+  formatLocale(format: DateOnlyLocaleAwareOutputFormat, locale: Locale): string;
+
+  toIso8601(): string;
+  toYearAndMonth(): YearAndMonth
+}
+
+export class DateOnly implements DateOnlyInterface {
+  public readonly year: Year;
+  public readonly month: Month;
+  public readonly day: Day;
+  public readonly dayOfWeek: DayOfWeek;
+
+  private constructor(year: Year, month: Month, day: Day) {
+    // We just convert it to a datetime to check if the date is valid with dayjs.
+    // f.e 31 februari 2024 is a date you could form, but is not valid.
+    const asDate = dayjs(`${year.format(YearOutputFormat.YEAR_NUMERIC)}-${month.format(MonthOutputFormat.MONTH_TWO_DIGIT)}-${day.format(DayOutputFormat.DAY_TWO_DIGIT)}`, 'YYYY-MM-DD', true); // strict parsing
+    if (!asDate.isValid) {
+      throw InvalidDate.invalidDate();
+    }
+
+    this.year = year;
+    this.month = month;
+    this.day = day;
+
+    this.dayOfWeek = DayOfWeek.fromZeroBased(
+      asDate.day() as ZeroBasedWeekdayNumbers,
+    );
+  }
+
+  static from(year: Year, month: Month, day: Day) {
+    return new DateOnly(year, month, day);
+  }
+
+  // https://nl.wikipedia.org/wiki/ISO_8601
+  static fromIso8601(dateString: string): DateOnlyInterface {
+    const regex = /^\d{4}-\d{2}-\d{2}$/;
+
+    // Check needed to prevent Dayjs from parsing other formats we don't want.
+    if (!regex.test(dateString)) {
+      throw InvalidDate.invalidDateFormat();
+    }
+
+    const parsed = dayjs(dateString);
+    if (!parsed.isValid()) {
+      throw InvalidDate.invalidDateFormat();
+    }
+
+    return DateOnly.from(Year.from(parsed.year()), Month.from(parsed.month(), MonthIndex.ZERO_BASED), Day.from(parsed.date()));
+  }
+
+  static next(
+    now: DateOnlyInterface,
+    month: Month,
+    day: Day,
+  ): DateOnlyInterface {
+    if (now.month.asInt() > month.asInt()) {
+      return DateOnly.from(now.year.next(), month, day);
+    }
+
+    if (now.month.asInt() === month.asInt() && now.day.asInt() >= day.asInt()) {
+      return DateOnly.from(now.year.next(), month, day);
+    }
+
+    return DateOnly.from(now.year, month, day);
+  }
+
+  public toIso8601(): string {
+    return this.year.format(YearOutputFormat.YEAR_NUMERIC) + '-' + this.month.format(MonthOutputFormat.MONTH_TWO_DIGIT) + '-' + this.day.format(DayOutputFormat.DAY_TWO_DIGIT);
+  }
+
+  public isSame(dateOnly: DateOnlyInterface): boolean {
+    return (
+      this.year.isSame(dateOnly.year) &&
+      this.month.isSame(dateOnly.month) &&
+      this.day.isSame(dateOnly.day)
+    );
+  }
+
+  public isBefore(dateOnly: DateOnlyInterface): boolean {
+    if (this.year.asInt() < dateOnly.year.asInt()) {
+      return true;
+    }
+
+    if (
+      this.year.asInt() === dateOnly.year.asInt() &&
+      this.month.asInt() < dateOnly.month.asInt()
+    ) {
+      return true;
+    }
+
+    return (
+      this.year.asInt() === dateOnly.year.asInt() &&
+      this.month.asInt() === dateOnly.month.asInt() &&
+      this.day.asInt() < dateOnly.day.asInt()
+    );
+  }
+
+  public isAfter(dateOnly: DateOnlyInterface): boolean {
+    if (this.year.asInt() > dateOnly.year.asInt()) {
+      return true;
+    }
+
+    if (
+      this.year.asInt() === dateOnly.year.asInt() &&
+      this.month.asInt() > dateOnly.month.asInt()
+    ) {
+      return true;
+    }
+
+    return (
+      this.year.asInt() === dateOnly.year.asInt() &&
+      this.month.asInt() === dateOnly.month.asInt() &&
+      this.day.asInt() > dateOnly.day.asInt()
+    );
+  }
+
+  public toYearAndMonth(): YearAndMonth {
+    return YearAndMonth.from(this.year, this.month);
+  }
+
+  private toUtcDayJs(year: Year, month: Month, day: Day): Dayjs {
+    const parsed = dayjs.utc(
+      year.format(YearOutputFormat.YEAR_NUMERIC) + '-' + month.format(MonthOutputFormat.MONTH_TWO_DIGIT) + '-' + day.format(DayOutputFormat.DAY_TWO_DIGIT) + 'T' + '12:00:00'
+    );
+
+    if (!parsed.isValid()) {
+      throw InvalidDate.invalidDateFormat();
+    }
+
+    return parsed.utc(false);
+  }
+
+  public format(
+    format: DateOnlyOutputFormat | YearAndMonthOutputFormat | YearOutputFormat | MonthOutputFormat | DayOutputFormat,
+  ): string {
+
+    const isYearAndMonthFormat = Object.values(
+      YearAndMonthOutputFormat,
+    ).includes(format as YearAndMonthOutputFormat);
+
+    if (isYearAndMonthFormat) {
+      return this.toYearAndMonth().format(
+        format as YearAndMonthOutputFormat,
+      );
+    }
+
+    const isYearFormat = Object.values(
+      YearOutputFormat,
+    ).includes(format as YearOutputFormat);
+
+    if (isYearFormat) {
+      return this.year.format(
+        format as YearOutputFormat,
+      );
+    }
+
+    const isMonthFormat = Object.values(
+      MonthOutputFormat,
+    ).includes(format as MonthOutputFormat);
+
+    if (isMonthFormat) {
+      return this.month.format(
+        format as MonthOutputFormat,
+      );
+    }
+
+    switch (format) {
+      case DateOnlyOutputFormat.DATEONLY_ISO8601:
+        return `${this.year.asInt()}-${this.month.format(MonthOutputFormat.MONTH_TWO_DIGIT)}-${this.day.format(DayOutputFormat.DAY_TWO_DIGIT)}`;
+
+      case DateOnlyOutputFormat.DATEONLY_DAY_MONTH_YEAR_DASH:
+        return `${this.day.format(DayOutputFormat.DAY_TWO_DIGIT)}-${this.month.format(MonthOutputFormat.MONTH_TWO_DIGIT)}-${this.year.asInt()}`;
+
+      case DateOnlyOutputFormat.DATEONLY_DAY_MONTH_YEAR_SLASH:
+        return `${this.day.format(DayOutputFormat.DAY_TWO_DIGIT)}/${this.month.format(MonthOutputFormat.MONTH_TWO_DIGIT)}/${this.year.asInt()}`;
+
+      case DateOnlyOutputFormat.DATEONLY_DAY_MONTH_YEAR_PERIOD:
+        return `${this.day.format(DayOutputFormat.DAY_TWO_DIGIT)}.${this.month.format(MonthOutputFormat.MONTH_TWO_DIGIT)}.${this.year.asInt()}`;
+
+      case DateOnlyOutputFormat.DATEONLY_MONTH_DAY_YEAR_SLASH:
+        return `${this.month.format(MonthOutputFormat.MONTH_TWO_DIGIT)}/${this.day.format(DayOutputFormat.DAY_TWO_DIGIT)}/${this.year.asInt()}`;
+
+      case DateOnlyOutputFormat.DATEONLY_COMPACT:
+        return `${this.year.asInt()}${this.month.format(MonthOutputFormat.MONTH_TWO_DIGIT)}${this.day.format(DayOutputFormat.DAY_TWO_DIGIT)}`;
+
+      default:
+        throw new Error(`Unsupported format: ${format}`);
+    }
+  }
+
+  public formatLocale(format: DateOnlyLocaleAwareOutputFormat | YearAndMonthLocaleAwareOutputFormat | MonthLocalAwareOutputFormat, locale: Locale): string {
+
+    const isYearAndMonthFormat = Object.values(
+      YearAndMonthLocaleAwareOutputFormat,
+    ).includes(format as YearAndMonthLocaleAwareOutputFormat);
+
+    if (isYearAndMonthFormat) {
+      return this.toYearAndMonth().formatLocale(
+        format as YearAndMonthLocaleAwareOutputFormat,
+        locale
+      );
+    }
+
+    const isMonthFormat = Object.values(
+      MonthLocalAwareOutputFormat,
+    ).includes(format as MonthLocalAwareOutputFormat);
+
+    if (isMonthFormat) {
+      return this.month.formatLocale(
+        format as MonthLocalAwareOutputFormat,
+        locale
+      );
+    }
+
+    switch (format) {
+      case DateOnlyLocaleAwareOutputFormat.DATEONLY_FULL:
+        const day = this.toUtcDayJs(this.year, this.month, this.day);
+        return day.locale(locale).format(DateOnlyLocaleAwareOutputFormat.DATEONLY_FULL);
+      default:
+        throw new Error(`Unsupported format: ${format}`);
+    }
+
+  }
+}

package/src/utilities/datetime/datetime.class.tsx

@@ -0,0 +1,288 @@
+import dayjs, {Dayjs} from 'dayjs';
+import {Hour} from './hour.class';
+import {Minute} from './minute.class';
+import {Second} from './second.class';
+import {Millisecond} from './millisecond.class';
+import {Day, DayOutputFormat} from './day.class';
+import {Month, MonthIndex, MonthLocalAwareOutputFormat, MonthOutputFormat} from './month.class';
+import {Year, YearOutputFormat} from './year.class';
+import {DayOfWeek, IDayOfWeek, ZeroBasedWeekdayNumbers} from './dayoftheweek.class';
+import {YearAndMonth, YearAndMonthLocaleAwareOutputFormat} from './yearandmonth.class';
+import {TimeZone, TimeZoneInterface, UTCTimezone} from './timezone.class';
+import {Time, TimeInterface} from './time.class';
+import {Locale} from "./locale";
+import {DateOnlyLocaleAwareOutputFormat, InvalidDate} from "./dateonly.class";
+
+// Extends for dayjs.
+
+export class InvalidDateTime extends Error {
+  static invalidDateTimeFormat() {
+    return new InvalidDateTime("The provided datetime format is invalid.");
+  }
+}
+
+export enum DateTimeOutputFormat {
+  /** ISO 8601 standard format (e.g., 2024-10-18) */
+  DATETIME_ISO8601 = "yyyy-MM-dd'T'HH:mm:ss.SSS",
+
+  /** ISO 8601 date and time with offset but without milliseconds (e.g., 2024-10-19T15:30:45) */
+  DATETIME_ISO8601_NO_MILLIS = "yyyy-MM-dd'T'HH:mm:ss",
+
+  /** ISO 8601 date and time with timezone but without seconds (e.g., 2024-10-19T15:30) */
+  DATETIME_ISO8601_NO_SECONDS = "yyyy-MM-dd'T'HH:mm",
+}
+
+export interface DateTimeCalculation {
+  years?: number;
+  months?: number;
+  days?: number;
+  hours?: number;
+  minutes?: number;
+  seconds?: number;
+  milliseconds?: number;
+}
+
+export interface DateTimeInterface {
+  year: Year;
+  month : Month;
+  day: Day;
+  hour: Hour;
+  minute: Minute;
+  second: Second;
+  millisecond: Millisecond;
+  dayOfWeek: IDayOfWeek;
+  add(calculation : DateTimeCalculation): DateTimeInterface;
+  subtract(calculation : DateTimeCalculation): DateTimeInterface;
+
+  isSameDay($other : DateTimeInterface) : boolean;
+  startOfDay(): DateTimeInterface;
+  endOfDay(): DateTimeInterface;
+
+  toYearAndMonth(): YearAndMonth;
+  toTime(): TimeInterface;
+  toTimestamp(): number;
+  toNativeJsDate(): Date;
+  toDateOnlyIso8601(): string;
+
+  format(format: DateTimeOutputFormat): string;
+  formatLocale(format: DateOnlyLocaleAwareOutputFormat, locale: Locale): string;
+
+  inTimezone(timezone: TimeZoneInterface): DateTimeInterface;
+  inUtc(): DateTimeInterface;
+}
+
+export class DateTime implements DateTimeInterface {
+  private dateTime: Dayjs;
+  year: Year;
+  month: Month;
+  day: Day;
+  dayOfWeek: IDayOfWeek;
+  hour: Hour;
+  minute: Minute;
+  second: Second;
+  millisecond: Millisecond;
+  zone: TimeZoneInterface;
+
+  private constructor(dateTime: Dayjs, timezone: TimeZoneInterface) {
+    this.dateTime = dateTime;
+    this.zone = timezone;
+
+    this.year = Year.from(this.dateTime.year());
+    this.month = Month.from(this.dateTime.month(), MonthIndex.ZERO_BASED);
+    this.day = Day.from(this.dateTime.date());
+    this.hour = Hour.from(this.dateTime.hour());
+    this.minute = Minute.from(this.dateTime.minute());
+    this.second = Second.from(this.dateTime.second());
+    this.millisecond = Millisecond.from(this.dateTime.millisecond());
+    this.dayOfWeek = DayOfWeek.fromZeroBased(
+      this.dateTime.day() as ZeroBasedWeekdayNumbers,
+    );
+  }
+
+  static fromTimestamp(timestamp: number): DateTime {
+    const utcDate = dayjs.unix(timestamp);
+    return new DateTime(utcDate, TimeZone.UTC());
+  }
+
+  static fromIso8601(
+    dateString: string,
+    timezone: TimeZoneInterface,
+  ): DateTimeInterface {
+
+    const dateStringRegex =
+      /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3,6})?(Z)?$/;
+    const timezoneRegex = /Z$/;
+
+    const containsZ = timezoneRegex.test(dateString);
+    const isSupported = dateStringRegex.test(dateString);
+
+    if (containsZ && timezone.name() !== "UTC") {
+      throw new Error('Timezones are not matching!')
+    }
+
+    // Check needed to prevent dayjs from parsing other formats we don't want.
+    if (!isSupported) {
+      throw new Error('The provided datetime format is invalid!')
+    }
+
+    const asDate = dayjs.tz(dateString, timezone.name());
+    return new DateTime(asDate, timezone);
+  }
+
+  public add(calculation : DateTimeCalculation): DateTimeInterface {
+    const {
+      years = 0,
+      months = 0,
+      days = 0,
+      hours = 0,
+      minutes = 0,
+      seconds = 0,
+      milliseconds = 0,
+    } = calculation;
+
+    let _current = this.dateTime;
+
+      _current = _current.add(years, 'years');
+      _current = _current.add(months, 'months');
+      _current = _current.add(days, 'days');
+      _current = _current.add(hours, 'hours');
+      _current = _current.add(minutes, 'minutes');
+      _current = _current.add(seconds, 'seconds');
+      _current = _current.add(milliseconds, 'milliseconds');
+
+    return DateTime.fromTimestamp(_current.unix());
+  }
+
+  public subtract(calculation : DateTimeCalculation): DateTimeInterface {
+      const {
+        years = 0,
+        months = 0,
+        days = 0,
+        hours = 0,
+        minutes = 0,
+        seconds = 0,
+        milliseconds = 0,
+      } = calculation;
+
+      let _current = this.dateTime;
+
+      _current = _current.subtract(years, 'years');
+      _current = _current.subtract(months, 'months');
+      _current = _current.subtract(days, 'days');
+      _current = _current.subtract(hours, 'hours');
+      _current = _current.subtract(minutes, 'minutes');
+      _current =_current.subtract(seconds, 'seconds');
+      _current =_current.subtract(milliseconds, 'milliseconds');
+
+      return DateTime.fromTimestamp(_current.unix());
+  }
+
+  public startOfDay(): DateTimeInterface {
+    this.dateTime = this.dateTime.startOf('day');
+    return this;
+  }
+
+  public endOfDay(): DateTimeInterface {
+    this.dateTime = this.dateTime.endOf('day');
+    return this;
+  }
+
+  public toTime(): TimeInterface {
+    return Time.from(
+      this.hour.asInt(),
+      this.minute.asInt(),
+      this.second.asInt(),
+      this.millisecond.asInt(),
+    );
+  }
+
+  public toTimestamp(): number {
+    return this.dateTime.unix();
+  }
+
+  public inTimezone(timezone: TimeZoneInterface): DateTimeInterface {
+    const dayjs = this.dateTime.tz(timezone.name(), false);
+    return new DateTime(dayjs, timezone);
+  }
+
+  public inUtc(): DateTimeInterface {
+    const dayjs = this.dateTime.tz(UTCTimezone.name(), false);
+    return new DateTime(dayjs, UTCTimezone);
+  }
+
+  public toYearAndMonth(): YearAndMonth {
+    return YearAndMonth.from(this.year, this.month);
+  }
+
+  public toNativeJsDate(): Date {
+    return this.dateTime.toDate();
+  }
+
+  public format(format: DateTimeOutputFormat): string {
+    switch (format) {
+      case DateTimeOutputFormat.DATETIME_ISO8601:
+        return this.dateTime.format('YYYY-MM-DDTHH:mm:ss.SSS');
+      case DateTimeOutputFormat.DATETIME_ISO8601_NO_MILLIS:
+        return this.dateTime.format('YYYY-MM-DDTHH:mm:ss');
+      case DateTimeOutputFormat.DATETIME_ISO8601_NO_SECONDS:
+        return this.dateTime.format('YYYY-MM-DDTHH:mm');
+      default:
+        throw new Error(`Unsupported format: ${format}`);
+    }
+  }
+
+  public formatLocale(format: DateOnlyLocaleAwareOutputFormat | YearAndMonthLocaleAwareOutputFormat | MonthLocalAwareOutputFormat, locale: Locale): string {
+
+        const isYearAndMonthFormat = Object.values(
+            YearAndMonthLocaleAwareOutputFormat,
+        ).includes(format as YearAndMonthLocaleAwareOutputFormat);
+
+        if (isYearAndMonthFormat) {
+            return this.toYearAndMonth().formatLocale(
+                format as YearAndMonthLocaleAwareOutputFormat,
+                locale
+            );
+        }
+
+        const isMonthFormat = Object.values(
+            MonthLocalAwareOutputFormat,
+        ).includes(format as MonthLocalAwareOutputFormat);
+
+        if (isMonthFormat) {
+            return this.month.formatLocale(
+                format as MonthLocalAwareOutputFormat,
+                locale
+            );
+        }
+
+        switch (format) {
+            case DateOnlyLocaleAwareOutputFormat.DATEONLY_FULL:
+                const day = this.toUtcDayJs(this.year, this.month, this.day);
+                return day.locale(locale).format(DateOnlyLocaleAwareOutputFormat.DATEONLY_FULL);
+            default:
+                throw new Error(`Unsupported format: ${format}`);
+        }
+    }
+
+
+    public isSameDay($other : DateTimeInterface) : boolean {
+      return this.day.isSame($other.day) && this.month.isSame($other.month) && this.year.isSame($other.year);
+    }
+
+    private toUtcDayJs(year: Year, month: Month, day: Day): Dayjs {
+        const parsed = dayjs.utc(
+            year.format(YearOutputFormat.YEAR_NUMERIC) + '-' + month.format(MonthOutputFormat.MONTH_TWO_DIGIT) + '-' + day.format(DayOutputFormat.DAY_TWO_DIGIT) + 'T' + '12:00:00'
+        );
+
+        if (!parsed.isValid()) {
+            throw InvalidDate.invalidDateFormat();
+        }
+
+        return parsed.utc(false);
+    }
+
+    public toDateOnlyIso8601(): string {
+        return this.year.format(YearOutputFormat.YEAR_NUMERIC) + '-' + this.month.format(MonthOutputFormat.MONTH_TWO_DIGIT) + '-' + this.day.format(DayOutputFormat.DAY_TWO_DIGIT);
+    }
+
+}

package/src/utilities/datetime/day.class.tsx

@@ -0,0 +1,48 @@
+export class InvalidDay extends Error {
+  static notInScope() {
+    return new InvalidDay("A day must be between 1 and 31.");
+  }
+}
+
+export enum DayOutputFormat {
+  /** Month and day numeric (e.g., 1) */
+  DAY_NUMERIC = "day-numeric",
+  /** Month and day numeric (e.g., 01) */
+  DAY_TWO_DIGIT = "day-2-digit",
+}
+
+export interface DayInterface {
+  asInt(): number;
+  isSame(day: Day): boolean;
+  format(format: DayOutputFormat): string;
+  // formatLocale is not included since days don't get formatted local.
+}
+
+export class Day implements DayInterface {
+  private constructor(private readonly day: number) {
+    if (this.day < 1 || this.day > 31) {
+      throw InvalidDay.notInScope();
+    }
+  }
+
+  static from(day: number): Day {
+    return new Day(day);
+  }
+
+  asInt(): number {
+    return this.day;
+  }
+
+  format(format: DayOutputFormat): string {
+    switch (format) {
+      case DayOutputFormat.DAY_NUMERIC:
+        return String(this.asInt());
+      case DayOutputFormat.DAY_TWO_DIGIT:
+        return this.day.toString().padStart(2, "0");
+    }
+  }
+
+  isSame(day: Day): boolean {
+    return this.asInt() === day.asInt();
+  }
+}