difference

Calculates the difference between two dates in the specified unit.

Accepts any DateLike input (Date, timestamp, or date string).

Available since v2.0.0

Import

import { difference } from '@helpers4/date';

Signature

difference(dateA: DateLike, dateB: DateLike, options: DateDifferenceOptions): number

Parameters

Parameter	Type	Description
dateA	DateLike	First date
dateB	DateLike	Second date
options	DateDifferenceOptions	Difference options

Returns

number — The difference between the two dates, or NaN if either date is invalid

Examples

difference

difference('2025-01-01', '2025-01-10')
// => 9
difference('2025-01-01T00:00:00Z', '2025-01-01T02:30:00Z', { unit: 'hours' })
// => 2.5
difference('2025-01-10', '2025-01-01', { absolute: false })
// => -9

Related Types

DateDifferenceOptions

Options for date difference calculation

interface DateDifferenceOptions {
  absolute?: boolean;
  unit?: DifferenceUnit;
}

DateLike

A value that can be converted to a Date.

• Date — used as-is (validated for Invalid Date)
• number — treated as a timestamp (seconds or milliseconds, auto-detected); 0 is treated as invalid and produces null in ensureDate
• string — parsed via new Date(string)
• EpochMilliseconds — any object with a epochMilliseconds property (e.g. Temporal.Instant, Temporal.ZonedDateTime)

// TODO: When the Temporal API reaches Stage 4 and is available without // flags in all major runtimes, consider narrowing the union to the // concrete Temporal types for stricter type-checking.

type DateLike = Date | number | string | EpochMilliseconds

DifferenceUnit

Unit for date difference calculation

type DifferenceUnit = 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days'

EpochMilliseconds

An object that exposes an epoch timestamp in milliseconds.

This structural type is satisfied by Temporal.Instant and Temporal.ZonedDateTime (and any future object that carries the same property), so callers can pass Temporal values without importing them.

interface EpochMilliseconds {
  epochMilliseconds: number;
}

Name conflict

A helper named difference also exists in @helpers4/array. If you need both in the same file, rename at import with as:

import { difference as difference4date } from '@helpers4/date';
import { difference as difference4array } from '@helpers4/array';

See Name Conflicts for the full resolution guide.

Source

View source on GitHub