feat: implementing new diffMethods

Implementing differenceInHours, differenceInSeconds
and differenceInMs

Author: Farenheith

package-lock.json

@@ -0,0 +1,8 @@
+import { scales } from './constants';
+
+export function differenceInHours<T extends Date, R extends Date>(
+	this: T,
+	start: R,
+) {
+	return Math.trunc((this.getTime() - start.getTime()) / scales.addHours);
+}

src/methods/difference-in-hours.ts

@@ -0,0 +1,6 @@
+export function differenceInMs<T extends Date, R extends Date>(
+	this: T,
+	start: R,
+) {
+	return this.getTime() - start.getTime();
+}

src/methods/difference-in-ms.ts

@@ -0,0 +1,8 @@
+import { scales } from './constants';
+
+export function differenceInSeconds<T extends Date, R extends Date>(
+	this: T,
+	start: R,
+) {
+	return Math.trunc((this.getTime() - start.getTime()) / scales.addSeconds);
+}

src/methods/difference-in-seconds.ts

@@ -3,6 +3,9 @@ export * from './base-methods';
 export * from './comparisons';
 export * from './difference-in-days';
 export * from './difference-in-minutes';
+export * from './difference-in-hours';
+export * from './difference-in-seconds';
+export * from './difference-in-ms';
 export * from './difference-in-days';
 export * from './difference-in-years';
 export * from './minutes-from-midnight';

src/methods/index.ts

@@ -8,22 +8,140 @@ export class SonicDate extends Date {
 	}
 }
 export interface SonicDate {
+	/**
+	 * Create a new `SonicDate` instance with the same time value.
+	 * @returns A cloned `SonicDate`.
+	 */
 	clone(): SonicDate;
+
+	/**
+	 * Returns true if this date is after the given date.
+	 * @param dateToCompare - Date, timestamp or ISO string to compare against.
+	 * @returns `true` when this date > `dateToCompare`.
+	 */
 	isAfter(dateToCompare: Dateable): boolean;
+
+	/**
+	 * Returns true if this date is before the given date.
+	 * @param dateToCompare - Date, timestamp or ISO string to compare against.
+	 * @returns `true` when this date < `dateToCompare`.
+	 */
 	isBefore(dateToCompare: Dateable): boolean;
+
+	/**
+	 * Add milliseconds to this date (mutates) and return `this`.
+	 * @param amount - Milliseconds to add (may be negative).
+	 * @returns The mutated `SonicDate` instance.
+	 */
 	addMilliseconds(amount: number): this;
+
+	/**
+	 * Add seconds to this date (mutates) and return `this`.
+	 * @param amount - Seconds to add (may be negative).
+	 * @returns The mutated `SonicDate` instance.
+	 */
 	addSeconds(amount: number): this;
+
+	/**
+	 * Add minutes to this date (mutates) and return `this`.
+	 * @param amount - Minutes to add (may be negative).
+	 * @returns The mutated `SonicDate` instance.
+	 */
 	addMinutes(amount: number): this;
+
+	/**
+	 * Add hours to this date (mutates) and return `this`.
+	 * @param amount - Hours to add (may be negative).
+	 * @returns The mutated `SonicDate` instance.
+	 */
 	addHours(amount: number): this;
+
+	/**
+	 * Add days to this date (mutates) and return `this`.
+	 * @param amount - Days to add (may be negative).
+	 * @returns The mutated `SonicDate` instance.
+	 */
 	addDays(amount: number): this;
+
+	/**
+	 * Add months to this date (mutates) and return `this`.
+	 * @param amount - Months to add (may be negative).
+	 * @returns The mutated `SonicDate` instance.
+	 */
 	addMonths(amount: number): this;
+
+	/**
+	 * Add years to this date (mutates) and return `this`.
+	 * @param amount - Years to add (may be negative).
+	 * @returns The mutated `SonicDate` instance.
+	 */
 	addYears(amount: number): this;
+
+	/**
+	 * Set time to the start of the day (00:00:00.000) and return `this`.
+	 * @returns The mutated `SonicDate` instance set to local start of day.
+	 */
 	startOfDay(): this;
+
+	/**
+	 * Get the minutes elapsed since local midnight (0-1439).
+	 * @returns Number of minutes from midnight.
+	 */
 	minutesFromMidnight(): number;
+
+	/**
+	 * Get the number of full minutes between this date and `dateRight`.
+	 * @param dateRight - Date, timestamp or ISO string to compare against.
+	 * @returns Floor of minutes difference (this - dateRight).
+	 */
 	differenceInMinutes(dateRight: Dateable): number;
+
+	/**
+	 * Get the number of full hours between this date and `dateRight`.
+	 * @param dateRight - Date, timestamp or ISO string to compare against.
+	 * @returns Floor of hours difference (this - dateRight).
+	 */
+	differenceInHours(dateRight: Dateable): number;
+
+	/**
+	 * Get the number of full seconds between this date and `dateRight`.
+	 * @param dateRight - Date, timestamp or ISO string to compare against.
+	 * @returns Floor of seconds difference (this - dateRight).
+	 */
+	differenceInSeconds(dateRight: Dateable): number;
+
+	/**
+	 * Get the difference in milliseconds between this date and `dateRight`.
+	 * @param dateRight - Date, timestamp or ISO string to compare against.
+	 * @returns Milliseconds difference (this - dateRight).
+	 */
+	differenceInMs(dateRight: Dateable): number;
+
+	/**
+	 * Get the number of full calendar days between this date and `dateRight`.
+	 * @param dateRight - Date, timestamp or ISO string to compare against.
+	 * @returns Number of full days difference.
+	 */
 	differenceInDays(dateRight: Dateable): number;
+
+	/**
+	 * Get the number of full years between this date and `dateRight`.
+	 * @param dateRight - Date, timestamp or ISO string to compare against.
+	 * @returns Number of full years difference.
+	 */
 	differenceInYears(dateRight: Dateable): number;
+
+	/**
+	 * Return an ISO date string in `YYYY-MM-DD` format.
+	 * @returns ISO date string (date portion only).
+	 */
 	toISODateString(): string;
+
+	/**
+	 * Return the epoch milliseconds adjusted to local UTC time.
+	 * This is equivalent to `getTime() - getTimezoneOffset() * 60000`.
+	 * @returns UTC-equivalent timestamp in milliseconds.
+	 */
 	utcTime(): number;
 }
 

src/sonic-date.ts

@@ -7,7 +7,7 @@ describe('incorrect calc', () => {
 		const result = date
 			.addYears(-25)
 			.addMonths(-1)
-			.differenceInYears(SonicDate.Now);
+			.differenceInYears(new SonicDate('2025-01-10T09:10:00Z'));
 
 		expect(result).toBe(25);
 	});

test/unit/bugfixes/bug-7.spec.ts

@@ -0,0 +1,35 @@
+import assert from 'assert';
+import { SonicDate } from 'src/index';
+import { differenceInHours } from 'src/methods';
+
+describe(differenceInHours.name, () => {
+	it('returns the number of full hours between the given dates', () => {
+		const result = new SonicDate(2014, 8 /* Sep */, 5, 2, 30).differenceInHours(
+			new SonicDate(2014, 8 /* Sep */, 4, 23, 0),
+		);
+		// 3.5 hours -> 3 full hours
+		assert(result === 3);
+	});
+
+	it('returns a negative number if the time value of the first date is smaller', () => {
+		const result = new SonicDate(2014, 8 /* Sep */, 4, 23, 0).differenceInHours(
+			new SonicDate(2014, 8 /* Sep */, 5, 2, 30),
+		);
+		assert(result === -3);
+	});
+
+	it('the difference is less than an hour but across calendar hours', () => {
+		const result = new SonicDate(2014, 8 /* Sep */, 5, 0, 30).differenceInHours(
+			new SonicDate(2014, 8 /* Sep */, 4, 23, 45),
+		);
+		// 0.75 hours -> 0 full hours
+		assert(result === 0);
+	});
+
+	it('returns NaN if either date is `Invalid Date`', () => {
+		const a = new SonicDate(NaN);
+		const b = new SonicDate(2014, 8 /* Sep */, 5);
+		assert(isNaN(a.differenceInHours(b)));
+		assert(isNaN(b.differenceInHours(new SonicDate(NaN))));
+	});
+});

test/unit/difference-in-hours.spec.ts

@@ -0,0 +1,40 @@
+/* eslint-env mocha */
+
+import assert from 'assert';
+import { SonicDate } from 'src/index';
+import { differenceInMs } from 'src/methods';
+
+describe(differenceInMs.name, () => {
+	it('returns the millisecond difference between the given dates (no flooring)', () => {
+		const result = new SonicDate(
+			2014,
+			8 /* Sep */,
+			5,
+			0,
+			0,
+			0,
+			500,
+		).differenceInMs(new SonicDate(2014, 8 /* Sep */, 5, 0, 0, 0, 0));
+		assert(result === 500);
+	});
+
+	it('returns a negative millisecond difference when appropriate', () => {
+		const result = new SonicDate(
+			2014,
+			8 /* Sep */,
+			5,
+			0,
+			0,
+			0,
+			0,
+		).differenceInMs(new SonicDate(2014, 8 /* Sep */, 5, 0, 0, 0, 500));
+		assert(result === -500);
+	});
+
+	it('returns NaN if either date is `Invalid Date`', () => {
+		const a = new SonicDate(NaN);
+		const b = new SonicDate(2014, 8 /* Sep */, 5);
+		assert(isNaN(a.differenceInMs(b)));
+		assert(isNaN(b.differenceInMs(new SonicDate(NaN))));
+	});
+});