Date-IO Core

import { IUtils, DateIOFormats, Unit } from "@date-io/core";

const { IUtils, DateIOFormats, Unit } = require("@date-io/core");

import { IUtils, DateIOFormats } from "@date-io/core";

// Use the interface to type your date utility implementation
class MyDateUtils implements IUtils<Date, string> {
  lib = "native";
  formats: DateIOFormats = {
    fullDate: "MMMM Do, YYYY",
    // ... other format implementations
  };
  
  date(value?: any): Date {
    return value ? new Date(value) : new Date();
  }
  
  // ... implement other required methods
}

// Or use it to type function parameters
function processDate<TDate>(
  utils: IUtils<TDate, any>,
  date: TDate
): string {
  return utils.format(date, "fullDate");
}

/**
 * Interface defining format tokens for various date/time display patterns
 * @template TLibFormatToken - The format token type used by the underlying date library
 */
interface DateIOFormats<TLibFormatToken = string> {
  /** Localized full date @example "Jan 1, 2019" */
  fullDate: TLibFormatToken;
  /** Partially localized full date with weekday, useful for text-to-speech accessibility @example "Tuesday, January 1, 2019" */
  fullDateWithWeekday: TLibFormatToken;
  /** Date format string with month and day of month @example "1 January" */
  normalDate: TLibFormatToken;
  /** Date format string with weekday, month and day of month @example "Wed, Jan 1" */
  normalDateWithWeekday: TLibFormatToken;
  /** Shorter day format @example "Jan 1" */
  shortDate: TLibFormatToken;
  /** Year format string @example "2019" */
  year: TLibFormatToken;
  /** Month format string @example "January" */
  month: TLibFormatToken;
  /** Short month format string @example "Jan" */
  monthShort: TLibFormatToken;
  /** Month with year format string @example "January 2018" */
  monthAndYear: TLibFormatToken;
  /** Month with date format string @example "January 1" */
  monthAndDate: TLibFormatToken;
  /** Weekday format string @example "Wednesday" */
  weekday: TLibFormatToken;
  /** Short weekday format string @example "Wed" */
  weekdayShort: TLibFormatToken;
  /** Day format string @example "1" */
  dayOfMonth: TLibFormatToken;
  /** Hours format string @example "11" */
  hours12h: TLibFormatToken;
  /** Hours format string @example "23" */
  hours24h: TLibFormatToken;
  /** Minutes format string @example "44" */
  minutes: TLibFormatToken;
  /** Seconds format string @example "00" */
  seconds: TLibFormatToken;
  /** Full time localized format string @example "11:44 PM" for US, "23:44" for Europe */
  fullTime: TLibFormatToken;
  /** Not localized full time format string @example "11:44 PM" */
  fullTime12h: TLibFormatToken;
  /** Not localized full time format string @example "23:44" */
  fullTime24h: TLibFormatToken;
  /** Date & time format string with localized time @example "Jan 1, 2018 11:44 PM" */
  fullDateTime: TLibFormatToken;
  /** Not localized date & Time format 12h @example "Jan 1, 2018 11:44 PM" */
  fullDateTime12h: TLibFormatToken;
  /** Not localized date & Time format 24h @example "Jan 1, 2018 23:44" */
  fullDateTime24h: TLibFormatToken;
  /** Localized keyboard input friendly date format @example "02/13/2020 */
  keyboardDate: TLibFormatToken;
  /** Localized keyboard input friendly date/time format @example "02/13/2020 23:44" */
  keyboardDateTime: TLibFormatToken;
  /** Partially localized keyboard input friendly date/time 12h format @example "02/13/2020 11:44 PM" */
  keyboardDateTime12h: TLibFormatToken;
  /** Partially localized keyboard input friendly date/time 24h format @example "02/13/2020 23:44" */
  keyboardDateTime24h: TLibFormatToken;
}

/**
 * Main interface defining the contract for date utility implementations
 * @template TDate - The date object type used by the underlying date library
 * @template TLocale - The locale configuration type used by the underlying date library
 */
interface IUtils<TDate, TLocale> {
  /** Format configuration object */
  formats: DateIOFormats<any>;
  /** Optional locale configuration */
  locale?: TLocale;
  /** Optional moment.js instance reference */
  moment?: any;
  /** Optional dayjs instance reference */
  dayjs?: any;
  /** Name of the library that is used right now */
  lib: string;

  /**
   * Creates a date object. Use `utils.date()` to create a new date object of the underlying library.
   * Supports some of the standard input sources like ISO strings so you can pass the string directly
   * as `utils.date("2024-01-10T14:30:00Z"), and javascript `Date` objects `utils.date(new Date())`.
   * 
   * if `null` is passed `null` will be returned.
   */
  date<
    TArg extends unknown = undefined,
    TResultingDate extends unknown = TArg extends null
      ? null
      : TArg extends undefined
      ? TDate
      : TDate | null
  >(value?: TArg): TResultingDate;

  /** Convert date object to JavaScript Date */
  toJsDate(value: TDate): Date;
  /** Parse ISO string to date object */
  parseISO(isString: string): TDate;
  /** Convert date object to ISO string */
  toISO(value: TDate): string;
  /** Parse formatted string to date object */
  parse(value: string, format: string): TDate | null;

  /** Get current locale code */
  getCurrentLocaleCode(): string;
  /** Check if current locale uses 12-hour cycle */
  is12HourCycleInCurrentLocale(): boolean;
  /**
   * Returns user readable format (taking into account localized format tokens), useful to render helper text for input (e.g. placeholder).
   * If helper can not be created and **for luxon** always returns empty string.
   */
  getFormatHelperText(format: string): string;

  /** Check if value is null */
  isNull(value: TDate | null): boolean;
  /** Check if value is valid date */
  isValid(value: any): boolean;
  /** Get difference between dates */
  getDiff(value: TDate, comparing: TDate | string, unit?: Unit): number;
  /** Check if dates are equal */
  isEqual(value: any, comparing: any): boolean;

  /** Check if dates are on the same day */
  isSameDay(value: TDate, comparing: TDate): boolean;
  /** Check if dates are in the same month */
  isSameMonth(value: TDate, comparing: TDate): boolean;
  /** Check if dates are in the same year */
  isSameYear(value: TDate, comparing: TDate): boolean;
  /** Check if dates are in the same hour */
  isSameHour(value: TDate, comparing: TDate): boolean;

  /** Check if first date is after second */
  isAfter(value: TDate, comparing: TDate): boolean;
  /** Check if first date is after second by day */
  isAfterDay(value: TDate, comparing: TDate): boolean;
  /** Check if first date is after second by month */
  isAfterMonth(value: TDate, comparing: TDate): boolean;
  /** Check if first date is after second by year */
  isAfterYear(value: TDate, comparing: TDate): boolean;

  /** Check if first date is before second */
  isBefore(value: TDate, comparing: TDate): boolean;
  /** Check if first date is before second by day */
  isBeforeDay(value: TDate, comparing: TDate): boolean;
  /** Check if first date is before second by month */
  isBeforeMonth(value: TDate, comparing: TDate): boolean;
  /** Check if first date is before second by year */
  isBeforeYear(value: TDate, comparing: TDate): boolean;

  /** Check if date is within range */
  isWithinRange(value: TDate, range: [TDate, TDate]): boolean;

  /** Get start of year */
  startOfYear(value: TDate): TDate;
  /** Get end of year */
  endOfYear(value: TDate): TDate;
  /** Get start of month */
  startOfMonth(value: TDate): TDate;
  /** Get end of month */
  endOfMonth(value: TDate): TDate;
  /** Get start of week */
  startOfWeek(value: TDate): TDate;
  /** Get end of week */
  endOfWeek(value: TDate): TDate;
  /** Get start of day */
  startOfDay(value: TDate): TDate;
  /** Get end of day */
  endOfDay(value: TDate): TDate;

  /** Add seconds to date */
  addSeconds(value: TDate, count: number): TDate;
  /** Add minutes to date */
  addMinutes(value: TDate, count: number): TDate;
  /** Add hours to date */
  addHours(value: TDate, count: number): TDate;
  /** Add days to date */
  addDays(value: TDate, count: number): TDate;
  /** Add weeks to date */
  addWeeks(value: TDate, count: number): TDate;
  /** Add months to date */
  addMonths(value: TDate, count: number): TDate;
  /** Add years to date */
  addYears(value: TDate, count: number): TDate;

  /** Format date using predefined format key */
  format(value: TDate, formatKey: keyof DateIOFormats): string;
  /** Format date using custom format string */
  formatByString(value: TDate, formatString: string): string;
  /** Format number for display */
  formatNumber(numberToFormat: string): string;

  /** Get hours from date */
  getHours(value: TDate): number;
  /** Set hours on date */
  setHours(value: TDate, count: number): TDate;
  /** Get minutes from date */
  getMinutes(value: TDate): number;
  /** Set minutes on date */
  setMinutes(value: TDate, count: number): TDate;
  /** Get seconds from date */
  getSeconds(value: TDate): number;
  /** Set seconds on date */
  setSeconds(value: TDate, count: number): TDate;

  /** Get day of month from date */
  getDate(value: TDate): number;
  /** Set day of month on date */
  setDate(value: TDate, count: number): TDate;
  /** Get week number from date */
  getWeek(value: TDate): number;
  /** Get month from date */
  getMonth(value: TDate): number;
  /** Get number of days in month */
  getDaysInMonth(value: TDate): number;
  /** Set month on date */
  setMonth(value: TDate, count: number): TDate;
  /** Get next month from date */
  getNextMonth(value: TDate): TDate;
  /** Get previous month from date */
  getPreviousMonth(value: TDate): TDate;

  /** Get array of months */
  getMonthArray(value: TDate): TDate[];
  /** Get year from date */
  getYear(value: TDate): number;
  /** Set year on date */
  setYear(value: TDate, count: number): TDate;

  /** Merge date and time objects */
  mergeDateAndTime(date: TDate, time: TDate): TDate;
  /** Get array of weekday names */
  getWeekdays(): string[];
  /** Get calendar weeks array */
  getWeekArray(date: TDate): TDate[][];
  /** Get array of years in range */
  getYearRange(start: TDate, end: TDate): TDate[];
  /** Get AM/PM text for given period */
  getMeridiemText(ampm: "am" | "pm"): string;
}

/**
 * Time units for date arithmetic and differences
 */
type Unit =
  | "years"
  | "quarters" 
  | "months"
  | "weeks"
  | "days"
  | "hours"
  | "minutes"
  | "seconds"
  | "milliseconds";

/**
 * Constructor pattern for date utility implementations
 * @template TLocale - The locale configuration type used by the underlying date library
 */
class DateUtilsAdapter implements IUtils<TDate, TLocale> {
  constructor(options?: {
    /** Optional format overrides */
    formats?: Partial<DateIOFormats>;
    /** Optional locale configuration */
    locale?: TLocale;
    /** Optional library instance */
    instance?: any;
  }) {
    // Implementation details...
  }
  
  // ... implement all IUtils methods
}