From a052ca4d8298733765c1765076d76f9996fd2ba1 Mon Sep 17 00:00:00 2001 From: Justin Grant Date: Tue, 21 Jul 2020 11:14:02 -0700 Subject: [PATCH] Update types to 0.13 version (#46032) The date-and-time packages has evolved a bit since the 0.6 release. This commit: - adds types for new functions `compile`, `preparse`, `extend`, `plugin` - adds `PreparseResult` type - deprecates `getDelta` type that made intellisense worse - deprecates `Subtract` in favor of `SubtractResult` alias - Adapt to breaking changes in the library: - `parse` no longer returns NaN (it will return Invalid Date object) - `isLeapYear` accepts a `number`, not a `Date` - `getLocales` and `setLocales` functions are removed - Added various non-breaking updates, e.g. new optional parameters - Clarified some JSDoc comments & parameter names - Made minor grammar and capitalization updates --- types/date-and-time/date-and-time-tests.ts | 49 +++---- types/date-and-time/index.d.ts | 141 +++++++++++++-------- 2 files changed, 116 insertions(+), 74 deletions(-) diff --git a/types/date-and-time/date-and-time-tests.ts b/types/date-and-time/date-and-time-tests.ts index aae667f2bc..41294674a2 100644 --- a/types/date-and-time/date-and-time-tests.ts +++ b/types/date-and-time/date-and-time-tests.ts @@ -1,26 +1,27 @@ -import * as date from "date-and-time"; +import * as date from 'date-and-time'; +import 'date-and-time/plugin/meridiem'; const now = new Date(); // $ExpectType string -date.format(now, "YYYY/MM/DD HH:mm:ss"); // => '2015/01/02 23:14:05' +date.format(now, 'YYYY/MM/DD HH:mm:ss'); // => '2015/01/02 23:14:05' // $ExpectType string -date.format(now, "ddd MMM DD YYYY"); // => 'Fri Jan 02 2015' +date.format(now, 'ddd MMM DD YYYY'); // => 'Fri Jan 02 2015' // $ExpectType string -date.format(now, "hh:mm A [GMT]Z"); // => '11:14 p.m. GMT-0800' +date.format(now, 'hh:mm A [GMT]Z'); // => '11:14 p.m. GMT-0800' // $ExpectType string -date.format(now, "hh:mm A [GMT]Z", true); // => '07:14 a.m. GMT+0000' +date.format(now, 'hh:mm A [GMT]Z', true); // => '07:14 a.m. GMT+0000' -// $ExpectType number | Date -date.parse("2015/01/02 23:14:05", "YYYY/MM/DD HH:mm:ss"); // => date object -// $ExpectType number | Date -date.parse("02-01-2015", "DD-MM-YYYY"); // => date object -// $ExpectType number | Date -date.parse("Jam 1 2017", "MMM D YYYY"); // => NaN +// $ExpectType Date +date.parse('2015/01/02 23:14:05', 'YYYY/MM/DD HH:mm:ss'); // => date object +// $ExpectType Date +date.parse('02-01-2015', 'DD-MM-YYYY'); // => date object +// $ExpectType Date +date.parse('Jam 1 2017', 'MMM D YYYY'); // => NaN // $ExpectType boolean -date.isValid("2015/01/02 23:14:05", "YYYY/MM/DD HH:mm:ss"); // => true +date.isValid('2015/01/02 23:14:05', 'YYYY/MM/DD HH:mm:ss'); // => true // $ExpectType boolean -date.isValid("29-02-2015", "DD-MM-YYYY"); // => false +date.isValid('29-02-2015', 'DD-MM-YYYY'); // => false // $ExpectType Date date.addYears(now, 1); // => Date object @@ -46,7 +47,7 @@ date.addMilliseconds(now, 1); // => Date object const today = new Date(2015, 0, 2); const yesterday = new Date(2015, 0, 1); -// $ExpectType Subtract +// $ExpectType SubtractResult date.subtract(today, yesterday); // $ExpectType number date.subtract(today, yesterday).toDays(); // => 1 = today - yesterday @@ -59,12 +60,10 @@ date.subtract(today, yesterday).toSeconds(); // => 86400 // $ExpectType number date.subtract(today, yesterday).toMilliseconds(); // => 86400000 -const date1 = new Date(2015, 0, 2); -const date2 = new Date(2012, 0, 2); // $ExpectType boolean -date.isLeapYear(date1); // => false +date.isLeapYear(2015); // => false // $ExpectType boolean -date.isLeapYear(date2); // => true +date.isLeapYear(2012); // => true const date1_ = new Date(2017, 0, 2, 0); // Jan 2 2017 00:00:00 const date2_ = new Date(2017, 0, 2, 23, 59); // Jan 2 2017 23:59:00 @@ -77,10 +76,14 @@ date.isSameDay(date1_, date3); // => false // $ExpectType string date.locale(); -// $ExpectType any -date.getLocales(); +// $ExpectType PreparseResult +date.preparse('0000', 'YYYY'); + +// $ExpectType string[] +date.compile('YYYY'); // $ExpectType void -date.setLocales("en", { - A: ["AM", "PM"] -}); +date.plugin('meridiem'); + +// $ExpectType void +date.extend({ res: { A: ['am', 'pm'] } }); diff --git a/types/date-and-time/index.d.ts b/types/date-and-time/index.d.ts index 76f82809b3..1e3eedb7c6 100644 --- a/types/date-and-time/index.d.ts +++ b/types/date-and-time/index.d.ts @@ -1,57 +1,97 @@ -// Type definitions for date-and-time 0.6 +// Type definitions for date-and-time 0.13 // Project: https://github.com/knowledgecode/date-and-time // Definitions by: Daniel Plisetsky +// Justin Grant // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped +export interface 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; +} + +/** @deprecated */ export type getDelta = () => number; -export interface Subtract { - toMilliseconds: getDelta; - toSeconds: getDelta; - toMinutes: getDelta; - toHours: getDelta; - toDays: getDelta; +export interface SubtractResult { + toMilliseconds: () => number; + toSeconds: () => number; + toMinutes: () => number; + toHours: () => number; + toDays: () => number; } +/** @deprecated Use `SubtractResult` instead */ +export type Subtract = SubtractResult; + +/** + * Compiling a format string + * @param formatString - Format string + * @returns The compiled object + */ +export function compile(formatString: string): string[]; + +/** + * Pre-parsing a date string + * @param dateString - Date string + * @param formatter - Format string or a compiled object + * @returns The date structure + */ +export function preparse(dateString: string, formatString: string | string[]): PreparseResult; /** * Formatting a date * @param dateObj - Date object - * @param formatString - Format string - * @param [utc] - Output as UTC + * @param formatter - Format string or a compiled object + * @param utc - Output as UTC? * @returns The formatted string * */ -export function format( - dateObj: Date, - formatString: string, - utc?: boolean -): string; +export function format(dateObj: Date, formatString: string | string[], utc?: boolean): string; /** * Parsing a date string - * @param dateString - date string - * @param formatString - format string - * @param [utc] - input as UTC - * @returns the constructed date or NaN + * @param dateString - Date string + * @param formatter - Format string or a compiled object + * @param [utc] - Input as UTC + * @returns The constructed date */ -export function parse( - dateString: string, - formatString: string, - utc?: boolean -): Date | number; +export function parse(dateString: string, formatter: string | string[], utc?: boolean): Date; /** * Validation - * @param dateString - Date string - * @param formatString - Format string + * @param dateValue - Date string or preparsed date structure + * @param formatter - Format string or a compiled object * @returns Whether the date string is a valid date */ -export function isValid(dateString: string, formatString: string): boolean; +export function isValid(dateValue: string | PreparseResult, formatter?: string | string[]): boolean; /** * Adding years * @param dateObj - Date object - * @param years - Adding year + * @param years - Number of years to add * @returns The date after adding the value */ export function addYears(dateObj: Date, years: number): Date; @@ -59,7 +99,7 @@ export function addYears(dateObj: Date, years: number): Date; /** * Adding months * @param dateObj - Date object - * @param months - Adding month + * @param months - Number of months to add * @returns The date after adding the value */ export function addMonths(dateObj: Date, months: number): Date; @@ -67,7 +107,7 @@ export function addMonths(dateObj: Date, months: number): Date; /** * Adding days * @param dateObj - Date object - * @param days - Adding day + * @param days - Number of days to add * @returns The date after adding the value */ export function addDays(dateObj: Date, days: number): Date; @@ -75,7 +115,7 @@ export function addDays(dateObj: Date, days: number): Date; /** * Adding hours * @param dateObj - Date object - * @param hours - Adding hour + * @param hours - Number of hours to add * @returns The date after adding the value */ export function addHours(dateObj: Date, hours: number): Date; @@ -83,15 +123,15 @@ export function addHours(dateObj: Date, hours: number): Date; /** * Adding minutes * @param dateObj - Date object - * @param minutes - Adding minute + * @param minutes - Number of minutes to add * @returns The date after adding the value */ export function addMinutes(dateObj: Date, minutes: number): Date; /** * Adding seconds - * @param dateObj - date object - * @param seconds - adding second + * @param dateObj - Date object + * @param seconds - Number of seconds to add * @returns The date after adding the value */ export function addSeconds(dateObj: Date, seconds: number): Date; @@ -99,7 +139,7 @@ export function addSeconds(dateObj: Date, seconds: number): Date; /** * Adding milliseconds * @param dateObj - Date object - * @param milliseconds - Adding millisecond + * @param milliseconds - Number of milliseconds to add * @returns The date after adding the value */ export function addMilliseconds(dateObj: Date, milliseconds: number): Date; @@ -108,43 +148,42 @@ export function addMilliseconds(dateObj: Date, milliseconds: number): Date; * Subtracting * @param date1 - Date object * @param date2 - Date object - * @returns The result object after subtracting the date + * @returns The result object subtracting date2 from date1 */ -export function subtract(date1: Date, date2: Date): Subtract; +export function subtract(date1: Date, date2: Date): SubtractResult; /** * Leap year - * @param dateObj - Date object + * @param y - Year as a number * @returns Whether the year is a leap year */ -export function isLeapYear(dateObj: Date): boolean; +export function isLeapYear(y: number): boolean; /** * Comparison of dates - * @param date1 - Target for comparison - * @param date2 - Target for comparison + * @param date1 - Date object + * @param date2 - Date object * @returns Whether the dates are the same day (times are ignored) */ export function isSameDay(date1: Date, date2: Date): boolean; /** - * Setting a locale + * Change locale or setting a new locale definition * @param [code] - Language code + * @param [locale] - locale definition * @returns Current language code */ -export function locale(code?: string): string; +export function locale(code?: string, locale?: Record): string; /** - * Getting a definition of locale - * @param [code] - Language code - * @returns Definition of locale + * Locale extension + * @param extension - Locale extension */ -export function getLocales(code?: string): any; +export function extend(extension: Record): void; /** - * Adding a new definition of locale - * @param code - Language code - * @param options - Definition of locale - * @returns + * Plugin import or definition + * @param name - Plugin name + * @param extension - Locale extension */ -export function setLocales(code: string, options: any): void; +export function plugin(name: string, extension?: Record): void;