Date-IO Core provides the foundational TypeScript interface definitions for the date-io ecosystem, which abstracts common JavaScript date management libraries behind a unified API. The package contains the complete interface contract that all date-io adapters must implement, enabling developers to write date-handling code that works consistently across different underlying date libraries (moment.js, date-fns, luxon, dayjs, js-joda).
npm install @date-io/coreimport { IUtils, DateIOFormats, Unit } from "@date-io/core";For CommonJS:
const { IUtils, DateIOFormats, Unit } = require("@date-io/core");This package provides only TypeScript interface definitions - it does not contain implementations. It's designed to be used by date library adapter implementations and by applications that need type definitions for date utilities.
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");
}Date-IO Core is structured around three main components:
DateIOFormats interface defining all standard format tokensIUtils interface defining the complete API contract for date operationsStandardized format tokens for consistent date/time display across different date libraries.
/**
* 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;
}The complete interface contract that all date-io adapters must implement.
/**
* 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;
}Standardized time unit values for date arithmetic and differences.
/**
* Time units for date arithmetic and differences
*/
type Unit =
| "years"
| "quarters"
| "months"
| "weeks"
| "days"
| "hours"
| "minutes"
| "seconds"
| "milliseconds";Date-IO Core only provides interface definitions. Adapter implementations should follow this constructor pattern:
/**
* 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
}