refactor: commenting into to create and diff

Author: standy

src/create/create-ts-date.ts

@@ -1,10 +1,26 @@
 import {ValidDate} from '../valid-date';
 
+/**
+ * Type guard for ValidDate
+ */
+export function isValidDate(d: Date | null): d is ValidDate {
+	return d !== null && d instanceof Date && isFinite(d.getTime());
+}
+
+/**
+ * Converts to the `ValidDate`, creating new instance of Date
+ * @deprecated consider use of `isValidDate`
+ */
 export function fromDate(date: Date | number | undefined): ValidDate | null {
 	const d = new Date(+(date as Date));
 	return asValidDateOrNull(d);
 }
 
+/**
+ * Converts to the `ValidDate`, creating new instance of Date
+ * @throws Will throw TypeError if input not a valid Date or timestamp
+ * @deprecated Consider use of `isValidDate`
+ */
 export function fromDateOrThrow(date: Date | number | undefined): ValidDate {
 	const d = new Date(date instanceof Date ? date.getTime() : (date as number));
 	return asValidDateOrThrow(d, date);
@@ -14,58 +30,57 @@ export function asValidDateOrNull(date: Date): ValidDate | null {
 	if (isValidDate(date)) return date;
 	return null;
 }
-export function asValidDateOrThrow(date: Date, origin: any): ValidDate {
+function asValidDateOrThrow(date: Date, origin: any): ValidDate {
 	if (isValidDate(date)) return date;
 	throw new TypeError(`Cant parse date from "${origin}"`);
 }
 
-export interface NewValidDateFn {
-	(): ValidDate;
-	(value: number): ValidDate | null;
-	(value: string): ValidDate | null;
-	(
-		year: number,
-		month: number,
-		date?: number,
-		hours?: number,
-		minutes?: number,
-		seconds?: number,
-		ms?: number,
-	): ValidDate | null;
-}
-export const newValidDate = function(...args: Array<number | string>) {
+/**
+ * Create the `ValidDate`
+ * In case of failure returns `null`
+ */
+export function newValidDate(): ValidDate;
+export function newValidDate(value: number): ValidDate | null;
+export function newValidDate(value: string): ValidDate | null;
+export function newValidDate(
+	year: number,
+	month: number,
+	date?: number,
+	hours?: number,
+	minutes?: number,
+	seconds?: number,
+	ms?: number,
+): ValidDate | null;
+export function newValidDate(...args: Array<number | string | undefined>): ValidDate | null {
 	const dateArgs: [any, ...any[]] = [undefined];
 	for (let i = 0; i < arguments.length; i++) {
 		dateArgs[i + 1] = arguments[i];
 	}
 	const result = new (Date.bind.apply(Date, dateArgs) as any)();
 	return asValidDateOrNull(result);
-} as NewValidDateFn;
-
-export interface NewValidDateOrThrowFn {
-	(): ValidDate;
-	(value: number): ValidDate;
-	(value: string): ValidDate;
-	(
-		year: number,
-		month: number,
-		date?: number,
-		hours?: number,
-		minutes?: number,
-		seconds?: number,
-		ms?: number,
-	): ValidDate;
 }
 
-export const newValidDateOrThrow = function(...args: Array<number | string>) {
+/**
+ * Create the `ValidDate`
+ * In case of failure returns `null`
+ */
+export function newValidDateOrThrow(): ValidDate;
+export function newValidDateOrThrow(value: number): ValidDate;
+export function newValidDateOrThrow(value: string): ValidDate;
+export function newValidDateOrThrow(
+	year: number,
+	month: number,
+	date?: number,
+	hours?: number,
+	minutes?: number,
+	seconds?: number,
+	ms?: number,
+): ValidDate;
+export function newValidDateOrThrow(...args: Array<number | string | undefined>): ValidDate {
 	const dateArgs: [any, ...any[]] = [undefined];
 	for (let i = 0; i < arguments.length; i++) {
 		dateArgs[i + 1] = arguments[i];
 	}
 	const result = new (Date.bind.apply(Date, dateArgs) as any)();
 	return asValidDateOrThrow(result, dateArgs);
-} as NewValidDateOrThrowFn;
-
-export function isValidDate(d: Date | null): d is ValidDate {
-	return d !== null && d instanceof Date && isFinite(d.getTime());
 }

src/diff/diff-calendar-unit.ts

@@ -2,16 +2,34 @@ import {DiffUnitFn, MS} from '../utils/basic-types';
 import {isValidDate} from '../create/create-ts-date';
 import {absFloor} from '../utils/utils';
 
+/**
+ * Returns the number of years between two dates.
+ * Months, days and time are ignored
+ * @example
+ * diffCalendarYear(parseIso('2020-01-01'), parseIso('2019-12-31')) // 1 = 2020 - 2019
+ */
 export function diffCalendarYear<T extends Date | null>(d1: T, d2: T): DiffUnitFn<T> {
 	if (!isValidDate(d1) || !isValidDate(d2)) return null as any;
 	return d1.getFullYear() - d2.getFullYear();
 }
 
+/**
+ * Returns the number of months between two dates.
+ * Days and time are ignored
+ * @example
+ * diffCalendarMonth(parseIso('2020-05-01'), parseIso('2020-03-31')) // 2 = 5 - 3
+ */
 export function diffCalendarMonth<T extends Date | null>(d1: T, d2: T): DiffUnitFn<T> {
 	if (!isValidDate(d1) || !isValidDate(d2)) return null as any;
 	return (d1.getFullYear() - d2.getFullYear()) * 12 + d1.getMonth() - d2.getMonth();
 }
 
+/**
+ * Returns the number of days between two dates.
+ * Time is ignored
+ * @example
+ * diffCalendarDate(parseIso('2020-05-01'), parseIso('2020-04-20')) // 11 = 10 days in april and 1 in march
+ */
 export function diffCalendarDate<T extends Date | null>(d1: T, d2: T): DiffUnitFn<T> {
 	if (!isValidDate(d1) || !isValidDate(d2)) return null as any;
 	const u1 = Date.UTC(d1.getFullYear(), d1.getMonth(), d1.getDate());

src/diff/diff-unit.ts

@@ -2,16 +2,32 @@ import {MS, DiffUnitFn} from '../utils/basic-types';
 import {isValidDate} from '../create/create-ts-date';
 import {absFloor} from '../utils/utils';
 
+/**
+ * The number of milliseconds between two dates
+ * @example
+ * diffMilliseconds(parseIso('2020-01-02'), parseIso('2020-01-01')) // 86400000 = milliseconds in one day
+ */
 export function diffMilliseconds<T extends Date | null>(d1: T, d2: T): DiffUnitFn<T> {
 	if (!isValidDate(d1) || !isValidDate(d2)) return null as any;
 	return absFloor(d1.getTime() - d2.getTime());
 }
 
+/**
+ * The number of seconds between two dates
+ * @example
+ * diffSeconds(parseIso('2020-01-02'), parseIso('2020-01-01')) // 86400 = seconds in one day
+ */
 export function diffSeconds<T extends Date | null>(d1: T, d2: T): DiffUnitFn<T> {
 	if (!isValidDate(d1) || !isValidDate(d2)) return null as any;
 	return absFloor((d1.getTime() - d2.getTime()) / MS.Seconds);
 }
 
+/**
+ * The number of minutes between two dates
+ * @example
+ * diffMinutes(parseIso('2020-01-02'), parseIso('2020-01-01')) // 1440 = minutes in one day
+ * diffMinutes(parseIso('2020-01-01T12:30:01'), parseIso('2020-01-01T12:31:00')) // 0 = only 59 seconds left
+ */
 export function diffMinutes<T extends Date | null>(d1: T, d2: T): DiffUnitFn<T> {
 	if (!isValidDate(d1) || !isValidDate(d2)) return null as any;
 	return absFloor((d1.getTime() - d2.getTime()) / MS.Minutes);