date-and-time 2.2.1 → 2.3.0

package/date-and-time.d.ts

@@ -0,0 +1,304 @@
+/**
+ * Formatting date and time objects (Date -> String)
+ * @param dateObj - A Date object
+ * @param formatString - A format string
+ * @param [utc] - Output as UTC
+ * @returns A formatted string
+ */
+export function format(dateObj: Date, formatString: string, utc?: boolean): string;
+
+/**
+ * Formatting date and time objects (Date -> String)
+ * @param dateObj - A Date object
+ * @param compiledObj - A compiled object of format string
+ * @param [utc] - Output as UTC
+ * @returns A formatted string
+ */
+export function format(dateObj: Date, compiledObj: string[], utc?: boolean): string;
+
+/**
+ * Parsing date and time strings (String -> Date)
+ * @param dateString - A date and time string
+ * @param formatString - A format string
+ * @param [utc] - Input as UTC
+ * @returns A Date object
+ */
+export function parse(dateString: string, formatString: string, utc?: boolean): Date;
+
+/**
+ * Parsing date and time strings (String -> Date)
+ * @param dateString - A date and time string
+ * @param compiledObj - A compiled object of format string
+ * @param [utc] - Input as UTC
+ * @returns A Date object
+ */
+export function parse(dateString: string, compiledObj: string[], utc?: boolean): Date;
+
+/**
+ * Compiling format strings
+ * @param formatString - A format string
+ * @returns A compiled object
+ */
+export function compile(formatString: string): string[];
+
+/** Preparse result object */
+export type PreparseResult = {
+    /** Year */
+    Y: number;
+    /** Month */
+    M: number;
+    /** Day */
+    D: number;
+    /** 24-hour */
+    H: number;
+    /** Meridiem */
+    A: number;
+    /** 12-hour */
+    h: number;
+    /** Minute */
+    m: number;
+    /** Second */
+    s: number;
+    /** Millisecond */
+    S: number;
+    /** Timezone offset */
+    Z: number;
+    /** Pointer offset */
+    _index: number;
+    /** Length of the date string */
+    _length: number;
+    /** Token matching count */
+    _match: number;
+};
+
+/**
+ * Pre-parsing date and time strings
+ * @param dateString - A date and time string
+ * @param formatString - A format string
+ * @returns A pre-parsed result object
+ */
+export function preparse(dateString: string, formatString: string): PreparseResult;
+
+/**
+ * Pre-parsing date and time strings
+ * @param dateString - A date and time string
+ * @param compiledObj - A compiled object of format string
+ * @returns A pre-parsed result object
+ */
+export function preparse(dateString: string, compiledObj: string[]): PreparseResult;
+
+/**
+ * Date and time string validation
+ * @param dateString - A date and time string
+ * @param formatString - A format string
+ * @returns Whether the date and time string is a valid date and time
+ */
+export function isValid(dateString: string, formatString: string): boolean;
+
+/**
+ * Date and time string validation
+ * @param dateString - A date and time string
+ * @param compiledObj - A compiled object of format string
+ * @returns Whether the date and time string is a valid date and time
+ */
+export function isValid(dateString: string, compiledObj: string[]): boolean;
+
+/**
+ * Date and time string validation
+ * @param preparseResult - A pre-parsed result object
+ * @returns Whether the date and time string is a valid date and time
+ */
+export function isValid(preparseResult: PreparseResult): boolean;
+
+/**
+ * Format transformation of date and time strings (String -> String)
+ * @param dateString - A date and time string
+ * @param formatString1 - A format string before transformation
+ * @param formatString2 - A format string after transformation
+ * @param [utc] - Output as UTC
+ * @returns A formatted string
+ */
+export function transform(dateString: string, formatString1: string, formatString2: string, utc?: boolean): string;
+
+/**
+ * Format transformation of date and time strings (String -> String)
+ * @param dateString - A date and time string
+ * @param formatString - A format string before transformation
+ * @param compiledObj - A compiled object of format string after transformation
+ * @param [utc] - Output as UTC
+ * @returns A formatted string
+ */
+export function transform(dateString: string, formatString: string, compiledObj: string[], utc?: boolean): string;
+
+/**
+ * Format transformation of date and time strings (String -> String)
+ * @param dateString - A date and time string
+ * @param compiledObj - A compiled object of format string before transformation
+ * @param formatString - A format string after transformation
+ * @param [utc] - Output as UTC
+ * @returns A formatted string
+ */
+export function transform(dateString: string, compiledObj: string[], formatString: string, utc?: boolean): string;
+
+/**
+ * Format transformation of date and time strings (String -> String)
+ * @param dateString - A date and time string
+ * @param compiledObj1 - A compiled object of format string before transformation
+ * @param compiledObj2 - A compiled object of format string after transformation
+ * @param [utc] - Output as UTC
+ * @returns A formatted string
+ */
+export function transform(dateString: string, compiledObj1: string[], compiledObj2: string[], utc?: boolean): string;
+
+/**
+ * Adding years
+ * @param dateObj - A Date object
+ * @param years - Number of years to add
+ * @returns The Date object after adding the value
+ */
+export function addYears(dateObj: Date, years: number): Date;
+
+/**
+ * Adding months
+ * @param dateObj - A Date object
+ * @param months - Number of months to add
+ * @returns The Date object after adding the value
+ */
+export function addMonths(dateObj: Date, months: number): Date;
+
+/**
+ * Adding days
+ * @param dateObj - A Date object
+ * @param days - Number of days to add
+ * @returns The Date object after adding the value
+ */
+export function addDays(dateObj: Date, days: number): Date;
+
+/**
+ * Adding hours
+ * @param dateObj - A Date object
+ * @param hours - Number of hours to add
+ * @returns The Date object after adding the value
+ */
+export function addHours(dateObj: Date, hours: number): Date;
+
+/**
+ * Adding minutes
+ * @param dateObj - A Date object
+ * @param minutes - Number of minutes to add
+ * @returns The Date object after adding the value
+ */
+export function addMinutes(dateObj: Date, minutes: number): Date;
+
+/**
+ * Adding seconds
+ * @param dateObj - A Date object
+ * @param seconds - Number of seconds to add
+ * @returns The Date object after adding the value
+ */
+export function addSeconds(dateObj: Date, seconds: number): Date;
+
+/**
+ * Adding milliseconds
+ * @param dateObj - A Date object
+ * @param milliseconds - Number of milliseconds to add
+ * @returns The Date object after adding the value
+ */
+export function addMilliseconds(dateObj: Date, milliseconds: number): Date;
+
+/** Subtraction result object */
+export type SubtractResult = {
+    /** Returns the result value in milliseconds. */
+    toMilliseconds: () => number;
+    /** Returns the result value in seconds. */
+    toSeconds: () => number;
+    /** Returns the result value in minutes. This value might be a real number. */
+    toMinutes: () => number;
+    /** Returns the result value in hours. This value might be a real number. */
+    toHours: () => number;
+    /** Returns the result value in days. This value might be a real number. */
+    toDays: () => number;
+};
+
+/**
+ * Subtracting two dates (date1 - date2)
+ * @param date1 - A Date object
+ * @param date2 - A Date object
+ * @returns The result object of subtracting date2 from date1
+ */
+export function subtract(date1: Date, date2: Date): SubtractResult;
+
+/**
+ * Whether a year is a leap year
+ * @param y - A year to check
+ * @returns Whether the year is a leap year
+ */
+export function isLeapYear(y: number): boolean;
+
+/**
+ * Comparison of two dates
+ * @param date1 - A Date object
+ * @param date2 - A Date object
+ * @returns Whether the two dates are the same day (time is ignored)
+ */
+export function isSameDay(date1: Date, date2: Date): boolean;
+
+/** Locale installer */
+export type Locale = (proto: unknown) => string;
+
+/**
+ * Changing locales
+ * @param [locale] - A locale installer
+ * @returns The current language code
+ */
+export function locale(locale?: Locale): string;
+
+/**
+ * Changing locales
+ * @param [locale] - A language code
+ * @returns The current language code
+ */
+export function locale(locale?: string): string;
+
+export type Resources = {
+    [key: string]: string[] | string[][]
+};
+
+export type Formatter = {
+};
+
+export type Parser = {
+};
+
+export type Extender = {
+    [key: string]: (...args: any) => any
+};
+
+/** Extension object */
+export type Extension = {
+    res?: Resources,
+    formatter?: Formatter,
+    parser?: Parser,
+    extender?: Extender
+};
+
+/**
+ * Functional extension
+ * @param extension - An extension object
+ */
+export function extend(extension: Extension): void;
+
+/**  Plugin installer */
+export type Plugin = (proto: unknown, localized_proto?: unknown) => string;
+
+/**
+ * Importing plugins
+ * @param plugin - A plugin installer
+ */
+export function plugin(plugin: Plugin): void;
+
+/**
+ * Importing plugins
+ * @param plugin - A plugin name
+ */
+export function plugin(plugin: string): void;

package/date-and-time.js

@@ -146,9 +146,9 @@
         date;
 
     /**
-     * Compiling a format string
-     * @param {string} formatString - a format string
-     * @returns {Array.<string>} a compiled object
+     * Compiling format strings
+     * @param {string} formatString - A format string
+     * @returns {Array.<string>} A compiled object
      */
     proto.compile = function (formatString) {
         var re = /\[([^\[\]]|\[[^\[\]]*])*]|([A-Za-z])\2+|\.{3}|./g, keys, pattern = [formatString];
@@ -160,11 +160,11 @@
     };
 
     /**
-     * Formatting a Date and Time
-     * @param {Date} dateObj - a Date object
-     * @param {string|Array.<string>} arg - a format string or its compiled object
-     * @param {boolean} [utc] - output as UTC
-     * @returns {string} a formatted string
+     * Formatting date and time objects (Date -> String)
+     * @param {Date} dateObj - A Date object
+     * @param {string|Array.<string>} arg - A format string or its compiled object
+     * @param {boolean} [utc] - Output as UTC
+     * @returns {string} A formatted string
      */
     proto.format = function (dateObj, arg, utc) {
         var ctx = this || date, pattern = typeof arg === 'string' ? ctx.compile(arg) : arg,
@@ -181,10 +181,11 @@
     };
 
     /**
-     * Pre-parsing a Date and Time string
-     * @param {string} dateString - a date string
-     * @param {string|Array.<string>} arg - a format string or its compiled object
-     * @returns {Object} a date structure
+     * Pre-parsing date and time strings
+     * @param {string} dateString - A date and time string
+     * @param {string|Array.<string>} arg - A format string or its compiled object
+     * @param {boolean} [utc] - Input as UTC
+     * @returns {Object} A pre-parsed result object
      */
     proto.preparse = function (dateString, arg) {
         var ctx = this || date, pattern = typeof arg === 'string' ? ctx.compile(arg) : arg,
@@ -220,11 +221,11 @@
     };
 
     /**
-     * Parsing a Date and Time string
-     * @param {string} dateString - a date string
-     * @param {string|Array.<string>} arg - a format string or its compiled object
-     * @param {boolean} [utc] - input as UTC
-     * @returns {Date} a constructed date
+     * Parsing of date and time string (String -> Date)
+     * @param {string} dateString - A date-time string
+     * @param {string|Array.<string>} arg - A format string or its compiled object
+     * @param {boolean} [utc] - Input as UTC
+     * @returns {Date} A Date object
      */
     proto.parse = function (dateString, arg, utc) {
         var ctx = this || date, pattern = typeof arg === 'string' ? ctx.compile(arg) : arg,
@@ -241,10 +242,10 @@
     };
 
     /**
-     * Validation
-     * @param {Object|string} arg1 - a date structure or a date string
-     * @param {string|Array.<string>} [arg2] - a format string or its compiled object
-     * @returns {boolean} whether the date string is a valid date
+     * Date and time string validation
+     * @param {Object|string} arg1 - A pre-parsed result object or a date and time string
+     * @param {string|Array.<string>} [arg2] - A format string or its compiled object
+     * @returns {boolean} Whether the date and time string is a valid date and time
      */
     proto.isValid = function (arg1, arg2) {
         var ctx = this || date, dt = typeof arg1 === 'string' ? ctx.preparse(arg1, arg2) : arg1,
@@ -259,12 +260,12 @@
     };
 
     /**
-     * Transforming a Date and Time string
-     * @param {string} dateString - a date string
-     * @param {string|Array.<string>} arg1 - a format string or its compiled object
-     * @param {string|Array.<string>} arg2 - a transformed format string or its compiled object
-     * @param {boolean} [utc] - output as UTC
-     * @returns {string} a formatted string
+     * Format transformation of date and time string (String -> String)
+     * @param {string} dateString - A date and time string
+     * @param {string|Array.<string>} arg1 - A format string or its compiled object before transformation
+     * @param {string|Array.<string>} arg2 - A format string or its compiled object after transformation
+     * @param {boolean} [utc] - Output as UTC
+     * @returns {string} A formatted string
      */
     proto.transform = function (dateString, arg1, arg2, utc) {
         const ctx = this || date;
@@ -273,9 +274,9 @@
 
     /**
      * Adding years
-     * @param {Date} dateObj - a date object
-     * @param {number} years - number of years to add
-     * @returns {Date} a date after adding the value
+     * @param {Date} dateObj - A Date object
+     * @param {number} years - Number of years to add
+     * @returns {Date} The Date object after adding the value
      */
     proto.addYears = function (dateObj, years) {
         return (this || date).addMonths(dateObj, years * 12);
@@ -283,9 +284,9 @@
 
     /**
      * Adding months
-     * @param {Date} dateObj - a date object
-     * @param {number} months - number of months to add
-     * @returns {Date} a date after adding the value
+     * @param {Date} dateObj - A Date object
+     * @param {number} months - Number of months to add
+     * @returns {Date} The Date object after adding the value
      */
     proto.addMonths = function (dateObj, months) {
         var d = new Date(dateObj.getTime());
@@ -296,9 +297,9 @@
 
     /**
      * Adding days
-     * @param {Date} dateObj - a date object
-     * @param {number} days - number of days to add
-     * @returns {Date} a date after adding the value
+     * @param {Date} dateObj - A Date object
+     * @param {number} days - Number of days to add
+     * @returns {Date} The Date object after adding the value
      */
     proto.addDays = function (dateObj, days) {
         var d = new Date(dateObj.getTime());
@@ -309,9 +310,9 @@
 
     /**
      * Adding hours
-     * @param {Date} dateObj - a date object
-     * @param {number} hours - number of hours to add
-     * @returns {Date} a date after adding the value
+     * @param {Date} dateObj - A Date object
+     * @param {number} hours - Number of hours to add
+     * @returns {Date} The Date object after adding the value
      */
     proto.addHours = function (dateObj, hours) {
         return (this || date).addMinutes(dateObj, hours * 60);
@@ -319,9 +320,9 @@
 
     /**
      * Adding minutes
-     * @param {Date} dateObj - a date object
-     * @param {number} minutes - number of minutes to add
-     * @returns {Date} a date after adding the value
+     * @param {Date} dateObj - A Date object
+     * @param {number} minutes - Number of minutes to add
+     * @returns {Date} The Date object after adding the value
      */
     proto.addMinutes = function (dateObj, minutes) {
         return (this || date).addSeconds(dateObj, minutes * 60);
@@ -329,9 +330,9 @@
 
     /**
      * Adding seconds
-     * @param {Date} dateObj - a date object
-     * @param {number} seconds - number of seconds to add
-     * @returns {Date} a date after adding the value
+     * @param {Date} dateObj - A Date object
+     * @param {number} seconds - Number of seconds to add
+     * @returns {Date} The Date object after adding the value
      */
     proto.addSeconds = function (dateObj, seconds) {
         return (this || date).addMilliseconds(dateObj, seconds * 1000);
@@ -339,19 +340,19 @@
 
     /**
      * Adding milliseconds
-     * @param {Date} dateObj - a date object
-     * @param {number} milliseconds - number of milliseconds to add
-     * @returns {Date} a date after adding the value
+     * @param {Date} dateObj - A Date object
+     * @param {number} milliseconds - Number of milliseconds to add
+     * @returns {Date} The Date object after adding the value
      */
     proto.addMilliseconds = function (dateObj, milliseconds) {
         return new Date(dateObj.getTime() + milliseconds);
     };
 
     /**
-     * Subtracting two dates
-     * @param {Date} date1 - a Date object
-     * @param {Date} date2 - a Date object
-     * @returns {Object} a result object subtracting date2 from date1
+     * Subtracting two dates (date1 - date2)
+     * @param {Date} date1 - A Date object
+     * @param {Date} date2 - A Date object
+     * @returns {Object} The result object of subtracting date2 from date1
      */
     proto.subtract = function (date1, date2) {
         var delta = date1.getTime() - date2.getTime();
@@ -376,9 +377,9 @@
     };
 
     /**
-     * Whether year is leap year
-     * @param {number} y - year
-     * @returns {boolean} whether year is leap year
+     * Whether a year is a leap year
+     * @param {number} y - A year to check
+     * @returns {boolean} Whether the year is a leap year
      */
     proto.isLeapYear = function (y) {
         return (!(y % 4) && !!(y % 100)) || !(y % 400);
@@ -386,19 +387,19 @@
 
     /**
      * Comparison of two dates
-     * @param {Date} date1 - a Date object
-     * @param {Date} date2 - a Date object
-     * @returns {boolean} whether the two dates are the same day (time is ignored)
+     * @param {Date} date1 - A Date object
+     * @param {Date} date2 - A Date object
+     * @returns {boolean} Whether the two dates are the same day (time is ignored)
      */
     proto.isSameDay = function (date1, date2) {
         return date1.toDateString() === date2.toDateString();
     };
 
     /**
-     * Defining new locale
-     * @param {string} code - language code
-     * @param {Function} locale - locale installer
-     * @returns {string} current language code
+     * Definition of new locale
+     * @param {string} code - A language code
+     * @param {Function} locale - A locale installer
+     * @returns {void}
      */
     proto.locale = function (code, locale) {
         if (!locales[code]) {
@@ -407,9 +408,9 @@
     };
 
     /**
-     * Defining new plugin
-     * @param {string} name - plugin name
-     * @param {Function} plugin - plugin installer
+     * Definition of new plugin
+     * @param {string} name - A plugin name
+     * @param {Function} plugin - A plugin installer
      * @returns {void}
      */
     proto.plugin = function (name, plugin) {
@@ -422,9 +423,9 @@
     date = extend(proto);
 
     /**
-     * Changing locale
-     * @param {Function|string} [locale] - locale object | language code
-     * @returns {string} current language code
+     * Changing locales
+     * @param {Function|string} [locale] - A locale installer or language code
+     * @returns {string} The current language code
      */
     date.locale = function (locale) {
         var install = typeof locale === 'function' ? locale : date.locale[locale];
@@ -450,8 +451,8 @@
     };
 
     /**
-     * Feature extension
-     * @param {Object} extension - extension object
+     * Functional extension
+     * @param {Object} extension - An extension object
      * @returns {void}
      */
     date.extend = function (extension) {
@@ -469,8 +470,8 @@
     };
 
     /**
-     * Importing plugin
-     * @param {Function|string} plugin - plugin object | plugin name
+     * Importing plugins
+     * @param {Function|string} plugin - A plugin installer or plugin name
      * @returns {void}
      */
     date.plugin = function (plugin) {